pipecat-ai · markbackman · Jul 4, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 25, 2026
diff --git a/README.md b/README.md
@@ -2,162 +2,42 @@
  <img alt="pipecat" width="500px" height="auto" src="https://raw.githubusercontent.com/pipecat-ai/pipecat-flows/main/pipecat-flows.png">
 </div></h1>
 
-[![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/290.deprecated.md b/changelog/290.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
@@ -19,7 +19,13 @@ 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. 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",
 ]
@@ -42,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.4.0,<2",
+    "pipecat-ai[webrtc,websocket,daily,silero,deepgram,cartesia,openai,anthropic,google,aws,runner,evals]>=1.4.0,<1.5.0",
     "towncrier~=25.8.0",
 ]
 

diff --git 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",

diff --git a/uv.lock b/uv.lock
Original file line number	Diff line number	Diff line change
		@@ -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.