From b613e7d2d37125fa4e2b9c61cdd0af8db7f6c5cb Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Wed, 24 Jun 2026 15:35:59 -0400 Subject: [PATCH 1/4] Deprecate the standalone package; Flows is now part of Pipecat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pipecat Flows has moved into core pipecat-ai under `pipecat.flows`. Turn this repo's package into its final, frozen snapshot: - Importing `pipecat_flows` now emits a DeprecationWarning pointing at `pipecat.flows`. The code itself is unchanged and still works. - Pin `pipecat-ai` to the 1.5 line — where `pipecat.flows` first ships — so the frozen package stays known-good with that era and sunsets naturally; moving to a newer Pipecat means importing `pipecat.flows` instead. - Replace the README with a short redirect (before/after import, where things moved, pointer to the archived changelog). This is the last release before the repo is archived. It must be cut after pipecat-ai 1.5.0 is published — the pinned dependency won't resolve until then. --- README.md | 160 +++---------------- changelog/+now-part-of-pipecat.deprecated.md | 1 + pyproject.toml | 9 +- src/pipecat_flows/__init__.py | 11 ++ 4 files changed, 39 insertions(+), 142 deletions(-) create mode 100644 changelog/+now-part-of-pipecat.deprecated.md diff --git a/README.md b/README.md index 5bcd2459..78db10dd 100644 --- a/README.md +++ b/README.md @@ -2,162 +2,42 @@ pipecat -[![PyPI](https://img.shields.io/pypi/v/pipecat-ai-flows)](https://pypi.org/project/pipecat-ai-flows) [![Docs](https://img.shields.io/badge/Documentation-blue)](https://docs.pipecat.ai/guides/features/pipecat-flows) [![Discord](https://img.shields.io/discord/1239284677165056021)](https://discord.gg/pipecat) +# Pipecat Flows is now part of Pipecat -Pipecat Flows is an add-on framework for [Pipecat](https://github.com/pipecat-ai/pipecat/tree/main#readme) that allows you to build structured conversations in your AI applications. It enables you to create both predefined conversation paths and dynamically generated flows while handling the complexities of state management and LLM interactions. +As of **pipecat-ai 1.5.0**, Pipecat Flows ships inside the core [`pipecat-ai`](https://github.com/pipecat-ai/pipecat) package under the `pipecat.flows` namespace. There is no longer a separate package to install or keep version-matched. -The framework consists of: +This `pipecat-ai-flows` package is **deprecated** and frozen at its final release — it will not receive further updates. New features and fixes land in `pipecat.flows`. -- A Python module for building conversation flows with Pipecat -- A [visual editor](#Pipecat-Flows-Editor) for designing and exporting flow configurations +## Migrate -## Dependencies +Install Pipecat (Flows is included — nothing extra to add) and update your imports: -- Python 3.11 or higher -- [Pipecat](https://github.com/pipecat-ai/pipecat?tab=readme-ov-file#-getting-started) +```python +# Before +from pipecat_flows import ContextStrategyConfig, FlowManager, NodeConfig +from pipecat_flows.types import ActionConfig, ContextStrategy -## Installation - -1. Install uv - - ```bash - curl -LsSf https://astral.sh/uv/install.sh | sh - ``` - - > **Need help?** Refer to the [uv install documentation](https://docs.astral.sh/uv/getting-started/installation/). - -2. Install the module - - ```bash - # For new projects - uv init my-pipecat-flows-app - cd my-pipecat-flows-app - uv add pipecat-ai-flows - - # Or for existing projects - uv add pipecat-ai-flows - ``` - -> **Using pip?** You can still use `pip install pipecat-ai-flows` to get set up. - -## Quick Start - -See [Quick Start README](./examples/quickstart/README.md). - -For more detailed examples and guides, visit our [documentation](https://docs.pipecat.ai/guides/features/pipecat-flows). - -## Examples - -The repository includes several complete example implementations demonstrating various features of Pipecat Flows. - -### Available Examples - -The examples demonstrate various conversation flows including food ordering, restaurant reservations, patient intake, insurance quotes, and warm transfers. All examples support multiple LLM providers (OpenAI, Anthropic, Google Gemini, AWS Bedrock) to demonstrate cross-platform compatibility. - -### Getting Started with Examples - -For detailed setup instructions, configuration, and running examples, see the **[Examples README](examples/README.md)**. - -Quick start: - -```bash -# Install dependencies -uv sync -uv pip install "pipecat-ai[daily,openai,deepgram,cartesia,silero,examples]" - -# Configure environment -cp env.example .env # Add your API keys - -# Run an example -uv run examples/food_ordering.py +# After +from pipecat.flows import ContextStrategyConfig, FlowManager, NodeConfig +from pipecat.flows.types import ActionConfig, ContextStrategy ``` -## Contributing to the framework - -1. Clone the repository and navigate to it: - - ```bash - git clone https://github.com/pipecat-ai/pipecat-flows.git - cd pipecat-flows - ``` - -2. Install development dependencies: - - ```bash - uv sync --group dev - ``` - -3. Install the git pre-commit hooks (these help ensure your code follows project rules): - - ```bash - uv run pre-commit install - ``` - - > The package is automatically installed in editable mode when you run `uv sync`. - -## Tests - -The package includes a comprehensive test suite covering the core functionality. - -### Setup Test Environment - -Install venv and dependencies: - -```bash -uv sync --group dev -``` - -### Running Tests - -Run all tests: - -```bash -uv run pytest tests/ -``` - -Run specific test file: - -```bash -uv run pytest tests/test_state.py -``` - -Run specific test: - -```bash -uv run pytest tests/test_state.py -k test_initialization -``` - -Run with coverage report: - -```bash -uv run pytest tests/ --cov=pipecat_flows -``` - -## Pipecat Flows Editor - -A visual editor for creating and managing Pipecat conversation flows. - -![Food ordering flow example](https://raw.githubusercontent.com/pipecat-ai/pipecat-flows/main/images/flows-food-ordering.png) - -Visit the [Pipecat Flows Editor](https://github.com/pipecat-ai/pipecat-flows-editor) repo to learn more. - -## Contributing +That's the only change — the API is the same. -We welcome contributions from the community! Whether you're fixing bugs, improving documentation, or adding new features, here's how you can help: +## Where things moved -- **Found a bug?** Open an [issue](https://github.com/pipecat-ai/pipecat-flows/issues) -- **Have a feature idea?** Start a [discussion](https://discord.gg/pipecat) -- **Want to contribute code?** Check our [CONTRIBUTING.md](CONTRIBUTING.md) guide -- **Documentation improvements?** [Docs](https://github.com/pipecat-ai/docs) PRs are always welcome +- **Framework** → [`pipecat/flows`](https://github.com/pipecat-ai/pipecat/tree/main/src/pipecat/flows) +- **Examples** → [`examples/flows`](https://github.com/pipecat-ai/pipecat/tree/main/examples/flows) +- **Documentation** → [Pipecat Flows guide](https://docs.pipecat.ai/guides/features/pipecat-flows) -Before submitting a pull request, please check existing issues and PRs to avoid duplicates. +## History -We aim to review all contributions promptly and provide constructive feedback to help get your changes merged. +The release history of the standalone package remains here in [CHANGELOG.md](./CHANGELOG.md). Going forward, changes are tracked in Pipecat's [changelog](https://github.com/pipecat-ai/pipecat/blob/main/CHANGELOG.md). ## Getting help ➡️ [Join our Discord](https://discord.gg/pipecat) -➡️ [Pipecat Flows Guide](https://docs.pipecat.ai/guides/pipecat-flows) +➡️ [Pipecat Flows guide](https://docs.pipecat.ai/guides/features/pipecat-flows) ➡️ [Reach us on X](https://x.com/pipecat_ai) diff --git a/changelog/+now-part-of-pipecat.deprecated.md b/changelog/+now-part-of-pipecat.deprecated.md new file mode 100644 index 00000000..9c14f29a --- /dev/null +++ b/changelog/+now-part-of-pipecat.deprecated.md @@ -0,0 +1 @@ +- Pipecat Flows is now part of `pipecat-ai` under the `pipecat.flows` namespace, and this standalone `pipecat-ai-flows` package is deprecated and frozen at this final release. Importing `pipecat_flows` now emits a `DeprecationWarning`; migrate by importing from `pipecat.flows` instead (the API is unchanged). See the [README](./README.md) for details. diff --git a/pyproject.toml b/pyproject.toml index c1cef101..56318256 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,12 @@ classifiers = [ "Topic :: Multimedia :: Sound/Audio", ] dependencies = [ - "pipecat-ai>=1.4.0,<2", + # Final standalone release. Pipecat Flows now lives in pipecat-ai under + # `pipecat.flows`; this package is frozen at this snapshot. Pinned to the 1.5 + # line (where `pipecat.flows` first ships) so it stays known-good with that era + # and sunsets naturally — moving to a newer Pipecat means importing + # `pipecat.flows` instead. + "pipecat-ai>=1.5.0,<1.6", "loguru~=0.7.3", "docstring_parser>=0.16,<1", ] @@ -42,7 +47,7 @@ dev = [ "setuptools~=78.1.1", "setuptools_scm~=8.3.1", "python-dotenv>=1.0.1,<2.0.0", - "pipecat-ai[webrtc,websocket,daily,silero,deepgram,cartesia,openai,anthropic,google,aws,runner,evals]>=1.4.0,<2", + "pipecat-ai[webrtc,websocket,daily,silero,deepgram,cartesia,openai,anthropic,google,aws,runner,evals]>=1.5.0,<1.6", "towncrier~=25.8.0", ] diff --git a/src/pipecat_flows/__init__.py b/src/pipecat_flows/__init__.py index a4f49a41..f91f61b2 100644 --- a/src/pipecat_flows/__init__.py +++ b/src/pipecat_flows/__init__.py @@ -13,6 +13,8 @@ calling, action execution, and seamless transitions between conversation states. """ +import warnings + from .exceptions import ( ActionError, FlowError, @@ -38,6 +40,15 @@ flows_tool_options, ) +warnings.warn( + "`pipecat-ai-flows` is deprecated: Pipecat Flows is now part of `pipecat-ai`. " + "Import from `pipecat.flows` instead (e.g. `from pipecat.flows import FlowManager`). " + "This standalone package is frozen at its final release and will not receive further " + "updates.", + DeprecationWarning, + stacklevel=2, +) + __all__ = [ # Flow Manager "FlowManager", From 828c2cba59e588de2ba2ec437d94ee5c61f9bd69 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Wed, 24 Jun 2026 15:46:08 -0400 Subject: [PATCH 2/4] Pin the standalone package below the Flows-bearing Pipecat line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first cut pinned `pipecat-ai>=1.5.0`, which was backwards: it forced this standalone package to coexist with a pipecat-ai that already bundles `pipecat.flows` (two copies of Flows), and made the package unresolvable until 1.5.0 ships. Pin to `>=1.4.0,<1.5.0` instead — the last Pipecat line without built-in Flows. This package stays the Flows provider for that era and cannot be installed alongside a Pipecat that has `pipecat.flows`, so upgrading Pipecat past 1.4.x forces migrating to `pipecat.flows`. It also resolves and tests against the current Pipecat today. --- pyproject.toml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 56318256..f59a6254 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,11 +20,12 @@ classifiers = [ ] dependencies = [ # Final standalone release. Pipecat Flows now lives in pipecat-ai under - # `pipecat.flows`; this package is frozen at this snapshot. Pinned to the 1.5 - # line (where `pipecat.flows` first ships) so it stays known-good with that era - # and sunsets naturally — moving to a newer Pipecat means importing - # `pipecat.flows` instead. - "pipecat-ai>=1.5.0,<1.6", + # `pipecat.flows`; this package is frozen at this snapshot. Pin to the + # pre-Flows Pipecat line (< 1.5.0): this package stays the Flows provider for + # that era, and it deliberately cannot coexist with a pipecat-ai that already + # bundles `pipecat.flows`. Upgrading Pipecat past 1.4.x therefore forces + # dropping this package and importing `pipecat.flows` instead. + "pipecat-ai>=1.4.0,<1.5.0", "loguru~=0.7.3", "docstring_parser>=0.16,<1", ] @@ -47,7 +48,7 @@ dev = [ "setuptools~=78.1.1", "setuptools_scm~=8.3.1", "python-dotenv>=1.0.1,<2.0.0", - "pipecat-ai[webrtc,websocket,daily,silero,deepgram,cartesia,openai,anthropic,google,aws,runner,evals]>=1.5.0,<1.6", + "pipecat-ai[webrtc,websocket,daily,silero,deepgram,cartesia,openai,anthropic,google,aws,runner,evals]>=1.4.0,<1.5.0", "towncrier~=25.8.0", ] From cacb9e62f91476c223a38dfc56715cdfd2399e7f Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Wed, 24 Jun 2026 23:06:20 -0400 Subject: [PATCH 3/4] Name the changelog fragment with its PR number The fragment was placeholder-named while the PR didn't exist yet; now that it's #290, rename it so towncrier links the entry to the PR. --- .../{+now-part-of-pipecat.deprecated.md => 290.deprecated.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelog/{+now-part-of-pipecat.deprecated.md => 290.deprecated.md} (100%) diff --git a/changelog/+now-part-of-pipecat.deprecated.md b/changelog/290.deprecated.md similarity index 100% rename from changelog/+now-part-of-pipecat.deprecated.md rename to changelog/290.deprecated.md From 8b1292bb0b1d33dfa4c619023b3ffca9f19b45ef Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Wed, 24 Jun 2026 23:08:32 -0400 Subject: [PATCH 4/4] Update uv.lock for the capped pipecat-ai dependency Regenerate the lock so it matches the pipecat-ai pin tightened to >=1.4.0,<1.5.0 (the lock records the dependency specifiers). Resolved versions are unchanged. --- uv.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/uv.lock b/uv.lock index b1e2b2fb..66b2d51b 100644 --- a/uv.lock +++ b/uv.lock @@ -2416,14 +2416,14 @@ docs = [ requires-dist = [ { name = "docstring-parser", specifier = ">=0.16,<1" }, { name = "loguru", specifier = "~=0.7.3" }, - { name = "pipecat-ai", specifier = ">=1.4.0,<2" }, + { name = "pipecat-ai", specifier = ">=1.4.0,<1.5.0" }, ] [package.metadata.requires-dev] dev = [ { name = "build", specifier = "~=1.4.0" }, { name = "pip-tools", specifier = "~=7.5.3" }, - { name = "pipecat-ai", extras = ["webrtc", "websocket", "daily", "silero", "deepgram", "cartesia", "openai", "anthropic", "google", "aws", "runner", "evals"], specifier = ">=1.4.0,<2" }, + { name = "pipecat-ai", extras = ["webrtc", "websocket", "daily", "silero", "deepgram", "cartesia", "openai", "anthropic", "google", "aws", "runner", "evals"], specifier = ">=1.4.0,<1.5.0" }, { name = "pre-commit", specifier = "~=4.5.1" }, { name = "pyright", specifier = ">=1.1.404,<1.2" }, { name = "pytest", specifier = ">=9.0.0,<10" },