From 77e9daa58317523e23329b878e92eb66b44ce726 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Mon, 29 Jun 2026 14:39:22 -0400 Subject: [PATCH 1/2] docs: present Pipecat Flows as built into core Pipecat Pipecat Flows moved from its standalone package/repo into core Pipecat (pipecat-ai/pipecat#4882). Update the docs so Flows reads as built in rather than a separate add-on: - Drop the separate `uv add pipecat-ai-flows` install; Flows ships with pipecat-ai - Update imports from `pipecat_flows` to `pipecat.flows` - Repoint repo and example links to pipecat-ai/pipecat (examples/flows/) - Point the Flows API reference card at reference-server.pipecat.ai - Reword "add-on framework" and the Pipecat/Flows relationship section to describe Flows as a layer built on the pipeline - Add a namespace note to the 1.0 migration guide --- api-reference/pipecat-flows/exceptions.mdx | 2 +- api-reference/pipecat-flows/flow-manager.mdx | 4 ++-- api-reference/pipecat-flows/overview.mdx | 20 +++++--------------- api-reference/pipecat-flows/types.mdx | 8 ++++---- overview/flows.mdx | 8 ++++---- pipecat-flows/examples.mdx | 18 +++++++++--------- pipecat-flows/guides/context-strategies.mdx | 2 +- pipecat-flows/guides/functions.mdx | 4 ++-- pipecat-flows/guides/quickstart.mdx | 9 ++++----- pipecat-flows/introduction.mdx | 14 +++++--------- pipecat-flows/migration/migration-1.0.mdx | 11 ++++++++--- pipecat/examples/overview.mdx | 2 +- pipecat/get-started/introduction.mdx | 2 +- 13 files changed, 47 insertions(+), 57 deletions(-) diff --git a/api-reference/pipecat-flows/exceptions.mdx b/api-reference/pipecat-flows/exceptions.mdx index 11ca9e558..ac65aff18 100644 --- a/api-reference/pipecat-flows/exceptions.mdx +++ b/api-reference/pipecat-flows/exceptions.mdx @@ -8,7 +8,7 @@ description: "Error handling hierarchy for Pipecat Flows" Pipecat Flows defines a hierarchy of exceptions for handling errors during flow execution. All exceptions inherit from `FlowError`, making it possible to catch all flow-related errors with a single handler. ```python -from pipecat_flows import ( +from pipecat.flows import ( FlowError, FlowInitializationError, FlowTransitionError, diff --git a/api-reference/pipecat-flows/flow-manager.mdx b/api-reference/pipecat-flows/flow-manager.mdx index 76c7187dc..c1be90a98 100644 --- a/api-reference/pipecat-flows/flow-manager.mdx +++ b/api-reference/pipecat-flows/flow-manager.mdx @@ -238,7 +238,7 @@ node_config = NodeConfig( ### Basic Setup ```python -from pipecat_flows import FlowManager, FlowResult, NodeConfig +from pipecat.flows import FlowManager, FlowResult, NodeConfig async def create_initial_node() -> NodeConfig: return NodeConfig( @@ -260,7 +260,7 @@ await flow_manager.initialize(initial_node=await create_initial_node()) ### Using Global Functions ```python -from pipecat_flows import FlowManager, NodeConfig +from pipecat.flows import FlowManager, NodeConfig async def transfer_to_human(flow_manager: FlowManager) -> tuple[None, NodeConfig]: """Transfer the conversation to a human agent.""" diff --git a/api-reference/pipecat-flows/overview.mdx b/api-reference/pipecat-flows/overview.mdx index 0ae6bf835..8b9720302 100644 --- a/api-reference/pipecat-flows/overview.mdx +++ b/api-reference/pipecat-flows/overview.mdx @@ -10,27 +10,27 @@ description: "Reference docs for Pipecat's conversation flow system" [guides](/pipecat-flows/guides/quickstart) first. -Pipecat Flows is an add-on framework for Pipecat that allows you to build structured conversations in your AI applications. It enables you to define conversation paths while handling the complexities of state management and LLM interactions. +Pipecat Flows is Pipecat's framework for building structured conversations. It builds on the pipeline to let you define conversation paths while handling the complexities of state management and LLM interactions. Complete API documentation and method details Source code, examples, and issue tracking Working example with basic conversation flow @@ -38,17 +38,7 @@ Pipecat Flows is an add-on framework for Pipecat that allows you to build struct ## Installation -### Pipecat Flows - -To use Pipecat Flows, install the required dependency: - -```bash -uv add pipecat-ai-flows -``` - -### Pipecat Dependencies - -For fresh installations, you'll need to install Pipecat with dependencies for your Transport, STT, LLM, and TTS providers. +Pipecat Flows is included with Pipecat. For fresh installations, install Pipecat with dependencies for your Transport, STT, LLM, and TTS providers. For example, to use Daily, OpenAI, Deepgram, Cartesia, and Silero: diff --git a/api-reference/pipecat-flows/types.mdx b/api-reference/pipecat-flows/types.mdx index e14f372e8..ffb8761fe 100644 --- a/api-reference/pipecat-flows/types.mdx +++ b/api-reference/pipecat-flows/types.mdx @@ -150,7 +150,7 @@ Convert to a standard `FunctionSchema` for use with LLMs. Strips Flows-specific ### Example ```python -from pipecat_flows import FlowsFunctionSchema, FlowResult +from pipecat.flows import FlowsFunctionSchema, FlowResult async def handle_weather(args, flow_manager): city = args["city"] @@ -232,7 +232,7 @@ Enum defining strategies for managing conversation context during node transitio | `RESET_WITH_SUMMARY` | **Deprecated.** Reset context but include an LLM-generated summary. Use Pipecat's native [context summarization](/pipecat/fundamentals/context-summarization) instead. Requires `summary_prompt` in `ContextStrategyConfig`. | ```python -from pipecat_flows import ContextStrategy +from pipecat.flows import ContextStrategy strategy = ContextStrategy.APPEND strategy = ContextStrategy.RESET @@ -259,7 +259,7 @@ Dataclass for configuring context management behavior. ### Example ```python -from pipecat_flows import ContextStrategy, ContextStrategyConfig +from pipecat.flows import ContextStrategy, ContextStrategyConfig # Append (default) config = ContextStrategyConfig(strategy=ContextStrategy.APPEND) @@ -296,7 +296,7 @@ Decorator that overrides a function's default call options. It's optional — a ### Example ```python -from pipecat_flows import FlowManager, flows_tool_options, ConsolidatedFunctionResult +from pipecat.flows import FlowManager, flows_tool_options, ConsolidatedFunctionResult @flows_tool_options(cancel_on_interruption=True) async def lookup_order( diff --git a/overview/flows.mdx b/overview/flows.mdx index 38d9327c4..e24503da6 100644 --- a/overview/flows.mdx +++ b/overview/flows.mdx @@ -15,11 +15,11 @@ Pipecat Flows is best suited for use cases where: - **Your bot handles complex tasks** that can be broken down into smaller, manageable pieces - **You want to improve LLM accuracy** by focusing the model on one specific task at a time instead of managing multiple responsibilities simultaneously -## How Pipecat and Pipecat Flows Work Together +## How Pipecat Flows Builds on the Pipeline -**Pipecat** defines the core capabilities of your bot — the pipeline and processors that enable receiving audio, transcribing input, running LLM completions, converting responses to audio, and sending audio back to the user. +A Pipecat **pipeline** provides your bot's core mechanics — receiving audio, transcribing input, running LLM completions, converting responses to audio, and sending audio back to the user. -**Pipecat Flows** complements Pipecat by providing structure to a conversation, managing context and tools as the conversation progresses from one state to another. This is separate from the core pipeline, allowing you to separate conversation logic from pipeline mechanics. +**Pipecat Flows** builds on that pipeline to structure the conversation, managing context and tools as it moves from one state to the next. This keeps your conversation logic cleanly separated from the pipeline mechanics. ## Ready to Build? @@ -44,7 +44,7 @@ Pipecat Flows is best suited for use cases where: Source code, issues, and contributions diff --git a/pipecat-flows/examples.mdx b/pipecat-flows/examples.mdx index 54f33793e..de0445075 100644 --- a/pipecat-flows/examples.mdx +++ b/pipecat-flows/examples.mdx @@ -9,7 +9,7 @@ Explore these examples to see Pipecat Flows in action. Each example demonstrates A great first Flow to show you the ropes. Two-node flow that asks for a favorite color. @@ -17,48 +17,48 @@ Explore these examples to see Pipecat Flows in action. Each example demonstrates Multi-step ordering flow with menu selection, customization, and checkout. Collect party size, date, time, and contact details for a reservation. Healthcare intake flow collecting patient information and symptoms. Guided flow for collecting insurance quote details with state management. Switch between LLM providers mid-conversation based on task requirements. Transfer a conversation to a human agent with context handoff. - All examples are available in the [pipecat-flows GitHub - repository](https://github.com/pipecat-ai/pipecat-flows/tree/main/examples). + All examples are available in the [Pipecat repository on + GitHub](https://github.com/pipecat-ai/pipecat/tree/main/examples/flows). diff --git a/pipecat-flows/guides/context-strategies.mdx b/pipecat-flows/guides/context-strategies.mdx index ef6a1dfa3..687e0f854 100644 --- a/pipecat-flows/guides/context-strategies.mdx +++ b/pipecat-flows/guides/context-strategies.mdx @@ -32,7 +32,7 @@ Flows provides three built-in ways to manage conversation context as you move be Context strategies can be defined globally in the FlowManager constructor: ```python -from pipecat_flows import ContextStrategy, ContextStrategyConfig +from pipecat.flows import ContextStrategy, ContextStrategyConfig # Global strategy configuration flow_manager = FlowManager( diff --git a/pipecat-flows/guides/functions.mdx b/pipecat-flows/guides/functions.mdx index 379aa53fc..71a6ca0de 100644 --- a/pipecat-flows/guides/functions.mdx +++ b/pipecat-flows/guides/functions.mdx @@ -68,7 +68,7 @@ A function that doesn't need to change conversational state can return `None` fo By default, a function is not cancelled when the user interrupts, and it uses the LLM service's global timeout. To override either, decorate the function with `@flows_tool_options`: ```python -from pipecat_flows import flows_tool_options +from pipecat.flows import flows_tool_options # This lookup is only useful for the current turn, so cancel it if the user # interrupts and the conversation moves on. @@ -92,7 +92,7 @@ Direct functions cover most cases. Reach for `FlowsFunctionSchema` when you need A `FlowsFunctionSchema` spells out the function's name, description, and parameters by hand, and takes the `handler` that runs when the LLM calls the function: ```python -from pipecat_flows import FlowsFunctionSchema +from pipecat.flows import FlowsFunctionSchema async def record_favorite_color( args: FlowArgs, flow_manager: FlowManager diff --git a/pipecat-flows/guides/quickstart.mdx b/pipecat-flows/guides/quickstart.mdx index 64bd2c30d..15cfe378c 100644 --- a/pipecat-flows/guides/quickstart.mdx +++ b/pipecat-flows/guides/quickstart.mdx @@ -8,17 +8,16 @@ This guide walks through the Hello World example — a two-node conversation flo View the full source code on GitHub ## Prerequisites -Install Pipecat Flows and Pipecat with the services used in this example: +Pipecat Flows is included with Pipecat. Install Pipecat with the services used in this example: ```bash -uv add pipecat-ai-flows uv add "pipecat-ai[daily,google,cartesia,silero]" ``` @@ -38,7 +37,7 @@ A flow is a graph of nodes. Each node gives the LLM a task and the functions it The initial node sets the bot's personality via `role_message`, gives it a task via `task_messages`, and lists the function the LLM will call when the user answers: ```python -from pipecat_flows import FlowManager, NodeConfig +from pipecat.flows import FlowManager, NodeConfig def create_initial_node() -> NodeConfig: return NodeConfig( @@ -153,7 +152,7 @@ That's it! When a user connects, the bot greets them, asks for their favorite co See the [full source - code](https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/quickstart/hello_world.py) + code](https://github.com/pipecat-ai/pipecat/blob/main/examples/flows/hello_world.py) for the complete runnable example. diff --git a/pipecat-flows/introduction.mdx b/pipecat-flows/introduction.mdx index 784a08112..aa86f78ba 100644 --- a/pipecat-flows/introduction.mdx +++ b/pipecat-flows/introduction.mdx @@ -15,11 +15,11 @@ Pipecat Flows is best suited for use cases where: - **Your bot handles complex tasks** that can be broken down into smaller, manageable pieces - **You want to improve LLM accuracy** by focusing the model on one specific task at a time instead of managing multiple responsibilities simultaneously -## How Pipecat and Pipecat Flows Work Together +## How Pipecat Flows Builds on the Pipeline -**Pipecat** defines the core capabilities of your bot — the pipeline and processors that enable receiving audio, transcribing input, running LLM completions, converting responses to audio, and sending audio back to the user. +A Pipecat **pipeline** provides your bot's core mechanics — receiving audio, transcribing input, running LLM completions, converting responses to audio, and sending audio back to the user. -**Pipecat Flows** complements Pipecat by providing structure to a conversation, managing context and tools as the conversation progresses from one state to another. This is separate from the core pipeline, allowing you to separate conversation logic from pipeline mechanics. +**Pipecat Flows** builds on that pipeline to structure the conversation, managing context and tools as it moves from one state to the next. This keeps your conversation logic cleanly separated from the pipeline mechanics. **Pipecat Flows needs a text LLM that supports function calling** — use a @@ -37,11 +37,7 @@ Pipecat Flows is best suited for use cases where: ## Installation -```bash -uv add pipecat-ai-flows -``` - -You'll also need Pipecat with dependencies for your transport, STT, LLM, and TTS providers: +Pipecat Flows is included with Pipecat. Install Pipecat with the dependencies for your transport, STT, LLM, and TTS providers: ```bash uv add "pipecat-ai[daily,openai,deepgram,cartesia,silero]" @@ -74,7 +70,7 @@ The [Pipecat Flows Visual Editor](https://flows.pipecat.ai/) lets you design con Source code, issues, and contributions diff --git a/pipecat-flows/migration/migration-1.0.mdx b/pipecat-flows/migration/migration-1.0.mdx index cd020aafb..0aaa041b4 100644 --- a/pipecat-flows/migration/migration-1.0.mdx +++ b/pipecat-flows/migration/migration-1.0.mdx @@ -12,6 +12,11 @@ Before upgrading, search your codebase for the deprecated imports and patterns l If you're also upgrading Pipecat, see the [Pipecat 1.0 migration guide](/pipecat/migration/migration-1.0) first. + + Pipecat Flows is now part of core Pipecat. Import it from `pipecat.flows` + (previously `pipecat_flows`). The examples below use the new import path. + + ## 1. FlowManager Initialization The `tts` parameter was removed from `FlowManager.__init__()`. The built-in `tts_say` action now uses Pipecat's `TTSSpeakFrame` directly and no longer needs a reference to your TTS service. @@ -135,7 +140,7 @@ The `FlowConfig` type and `flow_config` parameter were removed. Static flows def ### Before (1.0) ```python -from pipecat_flows import FlowManager, FlowConfig +from pipecat.flows import FlowManager, FlowConfig flow_config: FlowConfig = { "initial_node": "greeting", @@ -164,7 +169,7 @@ await flow_manager.initialize() ### After (1.0) ```python -from pipecat_flows import FlowManager, NodeConfig +from pipecat.flows import FlowManager, NodeConfig def create_greeting_node() -> NodeConfig: return { @@ -224,7 +229,7 @@ node_config = { **Using `FlowsFunctionSchema`:** ```python -from pipecat_flows import FlowsFunctionSchema +from pipecat.flows import FlowsFunctionSchema node_config = { "task_messages": [...], diff --git a/pipecat/examples/overview.mdx b/pipecat/examples/overview.mdx index b546e709d..64553db34 100644 --- a/pipecat/examples/overview.mdx +++ b/pipecat/examples/overview.mdx @@ -145,7 +145,7 @@ Learn how to deploy the SmallWebRTCTransport in a Docker container. Learn how to use Pipecat Flows to create a structured navigation flow. This example shows a simple restaurant reservation flow. -[View Example →](https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/restaurant_reservation.py) +[View Example →](https://github.com/pipecat-ai/pipecat/blob/main/examples/flows/restaurant_reservation.py) diff --git a/pipecat/get-started/introduction.mdx b/pipecat/get-started/introduction.mdx index 25e2ddb59..cfd6aa234 100644 --- a/pipecat/get-started/introduction.mdx +++ b/pipecat/get-started/introduction.mdx @@ -56,7 +56,7 @@ Pipecat is an open source Python framework for building voice and multimodal AI + href="https://github.com/pipecat-ai/pipecat/tree/main/examples/flows"> Build structured conversations with Pipecat Flows to complete tasks and improve LLM accuracy From 35582af2778b72d538390b63b42fe9787b01de54 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Mon, 29 Jun 2026 14:52:26 -0400 Subject: [PATCH 2/2] docs: clarify Flows namespace moved in 1.5.0, not 1.0, in migration note --- pipecat-flows/migration/migration-1.0.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pipecat-flows/migration/migration-1.0.mdx b/pipecat-flows/migration/migration-1.0.mdx index 0aaa041b4..cd6c00979 100644 --- a/pipecat-flows/migration/migration-1.0.mdx +++ b/pipecat-flows/migration/migration-1.0.mdx @@ -13,8 +13,9 @@ Before upgrading, search your codebase for the deprecated imports and patterns l - Pipecat Flows is now part of core Pipecat. Import it from `pipecat.flows` - (previously `pipecat_flows`). The examples below use the new import path. + As of `pipecat-ai` 1.5.0, Pipecat Flows is part of core Pipecat, and its + import path is now `pipecat.flows` (previously `pipecat_flows`). The examples + below have been updated to use the new import path. ## 1. FlowManager Initialization