### Quick Start Example Setup

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Installs dependencies, configures environment variables, and runs the food ordering example. Ensure you add your API keys to the .env file.

```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
```

--------------------------------

### Run Quickstart Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/quickstart/README.md

Execute the 'hello_world.py' example from the quickstart directory using `uv`. This requires a configured `.env` file with API keys for Cartesia and Google Gemini.

```bash
uv run hello_world.py
```

--------------------------------

### Install Pipecat with Example Dependencies

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Installs the Pipecat package along with necessary dependencies for running the examples, including support for Daily, OpenAI, Deepgram, Cartesia, and Silero.

```bash
uv pip install "pipecat-ai[daily,openai,deepgram,cartesia,silero,examples]"
```

--------------------------------

### Install Pipecat for Google Gemini Examples

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Installs Pipecat with dependencies specifically for running Google Gemini examples, including Daily, Google, Deepgram, Cartesia, Silero, and general examples.

```bash
uv pip install "pipecat-ai[daily,google,deepgram,cartesia,silero,examples]"
```

--------------------------------

### Install Pipecat for AWS Bedrock Examples

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Installs Pipecat with dependencies for running AWS Bedrock examples, including Daily, AWS, Deepgram, Cartesia, Silero, and general examples.

```bash
uv pip install "pipecat-ai[daily,aws,deepgram,cartesia,silero,examples]"
```

--------------------------------

### Install Pipecat for Anthropic Examples

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Installs Pipecat with dependencies for running Anthropic examples, including Daily, Anthropic, Deepgram, Cartesia, Silero, and general examples.

```bash
uv pip install "pipecat-ai[daily,anthropic,deepgram,cartesia,silero,examples]"
```

--------------------------------

### Run Food Ordering Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Executes the food ordering example application. Ensure to fill in API keys in the .env file first.

```bash
cp env.example .env
uv run examples/food_ordering.py
```

--------------------------------

### Install uv

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Installs the uv package manager. Refer to the uv install documentation for assistance.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Installs all necessary dependencies for development, including testing and linting tools.

```bash
uv sync --group dev
```

--------------------------------

### Run Food Ordering Example with Daily Transport

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Executes the food ordering example flow specifically using the Daily transport. This allows for real-time communication through Daily's infrastructure.

```bash
uv run examples/food_ordering.py --transport daily
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Installs the pre-commit hooks to ensure code quality checks are run before commits.

```bash
uv run pre-commit install
```

--------------------------------

### Copy Environment Configuration

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Copies the example environment configuration file to `.env`, which should then be populated with specific API keys and settings.

```bash
cp env.example .env
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Installs development dependencies for the Pipecat Flows project using uv.

```bash
uv sync --group dev
```

--------------------------------

### Run Food Ordering Example with Twilio Transport via ngrok

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Runs the food ordering example using the Twilio transport, requiring an ngrok tunnel to expose the local server to the public internet. Replace 'your-ngrok' with your actual ngrok subdomain.

```bash
uv run examples/food_ordering.py --transport twilio --proxy your-ngrok.ngrok.io
```

--------------------------------

### Run Food Ordering Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/README.md

Executes the food ordering example flow using the Pipecat development runner. Access the bot via a web client at http://localhost:7860/client.

```bash
uv run examples/food_ordering.py
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/examples/quickstart/README.md

Synchronize project dependencies using the `uv` package manager. Ensure you have Python 3.11+ and `uv` installed.

```bash
uv sync
```

--------------------------------

### Install Git Pre-commit Hooks

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Installs git pre-commit hooks to ensure code adheres to project rules. The package is automatically installed in editable mode when running 'uv sync'.

```bash
uv run pre-commit install
```

--------------------------------

### Dataclass Docstring with Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Shows docstring conventions for Python dataclasses, including class purpose, example usage, and parameter documentation.

```python
@dataclass
class MessageFrame:
    """Frame containing messages in OpenAI format.

    Supports both simple and content list message formats.

    Example::

        [
            {"role": "user", "content": "Hello"},
            {"role": "assistant", "content": "Hi there!"}
        ]

    Parameters:
        messages: List of messages in OpenAI format.
    """

    messages: List[dict]
```

--------------------------------

### FlowActionHandler Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Example of a modern action handler that receives both the action dictionary and the flow manager instance.

```python
async def advanced_handler(action: dict, flow_manager: FlowManager):
    await flow_manager.transport.notify(action["text"])
```

--------------------------------

### initialize Method

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Initialize the flow manager, optionally starting at a specified initial node.

```APIDOC
## initialize(initial_node: NodeConfig | None = None) → None

### Description
Initialize the flow manager. Optionally, you can provide an `initial_node` to start the flow immediately.

### Parameters
* **initial_node** – Optional initial node configuration. If provided, the flow will start at this node immediately.

### Raises
* **FlowInitializationError** – If initialization fails.

### Examples
#### Initialize with an initial node:
```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize(create_initial_node())
```

#### Initialize without an initial node (set later via set_node_from_config):
```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize()
```
```

--------------------------------

### Legacy Action Handler Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Example of a legacy action handler that only receives the action dictionary. Use `FlowActionHandler` for modern applications.

```python
async def simple_handler(action: dict):
    await notify(action["text"])
```

--------------------------------

### NodeConfig Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Example of a NodeConfig dictionary used to define a single node in a Pipecat flow. It includes settings for role messages, task objectives, functions, actions, context strategy, and immediate response behavior.

```default
{
    "role_message": "You are a helpful assistant...",
    "task_messages": [
        {
            "role": "developer",
            "content": "Ask the user for their name..."
        }
    ],
    "functions": [...],
    "pre_actions": [...],
    "post_actions": [...],
    "context_strategy": ContextStrategyConfig(strategy=ContextStrategy.APPEND),
    "respond_immediately": true,
}
```

--------------------------------

### Regular Class Docstring Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Illustrates docstring conventions for regular Python classes, including class purpose, __init__ method documentation with Args, and public method documentation with Args and Returns.

```python
class MyService(BaseService):
    """Description of what the service does.

    Provides detailed explanation of the service's functionality,
    key features, and usage patterns.

    Supported features:

    - Feature one with detailed explanation
    - Feature two with additional context
    - Feature three for advanced use cases
    """

    def __init__(self, param1: str, old_param: str = None, **kwargs):
        """Initialize the service.

        Args:
            param1: Description of param1.
            old_param: Controls legacy behavior.

                .. deprecated:: 1.2.0
                    This parameter no longer has any effect and will be removed in version 2.0.

            **kwargs: Additional arguments passed to parent.
        """
        if old_param is not None:
            import warnings
            warnings.warn(
                "Parameter 'old_param' is deprecated and will be removed in version 2.0.",
                DeprecationWarning,
            )
        super().__init__(**kwargs)

    @property
    def sample_rate(self) -> int:
        """Get the current sample rate.

        Returns:
            The sample rate in Hz.
        """
        return self._sample_rate

    async def process_data(self, data: str) -> bool:
        """Process the provided data.

        Args:
            data: The data to process.

        Returns:
            True if processing succeeded.
        """
        pass
```

--------------------------------

### Run Audio Eval Suite

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/changelog/284.added.md

Execute the audio evaluation suite using the `uv run` command. Ensure you are in the correct directory and have the necessary dependencies installed.

```bash
uv run pipecat eval suite evals/manifest.yaml
```

--------------------------------

### Initialize FlowManager with Initial Node

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Initialize the `FlowManager` and immediately start the conversation at a specified initial node. Ensure all necessary initialization parameters are provided.

```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize(create_initial_node())
```

--------------------------------

### FlowManager.initialize

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Initialize the flow manager. This method sets up the flow manager, optionally starting at a specified initial node.

```APIDOC
## async initialize(initial_node: NodeConfig | None = None) -> None

### Description
Initialize the flow manager.

### Parameters
* **initial_node** – Optional initial node configuration. If provided,
the flow will start at this node immediately.

### Raises
* **FlowInitializationError** – If initialization fails.

### Examples

Initialize with an initial node:

```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize(create_initial_node())
```

Initialize without an initial node (set later via set_node_from_config):

```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize()
```
```

--------------------------------

### Create Changelog Fragment (Changed Functionality)

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Create a changelog fragment file for changes in existing functionality. This example shows nested bullets for detailed changes.

```markdown
- Updated FlowManager initialization:
  - Changed default timeout to 30 seconds
  - Added retry logic for failed transitions
```

--------------------------------

### FlowArgs Type Alias Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Illustrates the structure of arguments passed to flow handlers. Handlers can freely mutate this dictionary.

```default
{
    "user_name": "John",
    "age": 25,
    "preferences": {"color": "blue"}
}
```

--------------------------------

### Iterate on Single Scenario

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/evals/README.md

Run a single bot and scenario for iterative development. This involves starting the bot in one terminal and driving a specific scenario in another. The bot remains active for re-runs.

```bash
# Terminal 1: the bot, headless on the eval transport
uv run examples/food_ordering.py -t eval
```

```bash
# Terminal 2: one scenario, verbose (per-turn / per-expectation lines)
uv run pipecat eval run evals/scenarios/food_ordering_pizza.yaml -v
```

--------------------------------

### Initialize FlowManager Without Initial Node

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Initialize the `FlowManager` without specifying an initial node. The starting node can be set later using `set_node_from_config`.

```python
flow_manager = FlowManager(
    ... # Initialization parameters
)
await flow_manager.initialize()
```

--------------------------------

### FlowsDirectFunction Signature Example

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Defines the expected signature for a direct function, which includes a FlowManager and accepts arbitrary keyword parameters described by its docstring.

```python
async def f(flow_manager: FlowManager, **params) -> ConsolidatedFunctionResult:
    ...
```

--------------------------------

### Getting Flow Manager State

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Retrieve values from the flow manager's state dictionary. Use .get() for safe access with a default value.

```python
name = flow_manager.state.get("user_name", "Unknown")
age = flow_manager.state["age"]
```

--------------------------------

### Format Code

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Formats the codebase according to the project's style guidelines using Ruff.

```bash
uv run ruff format .
```

--------------------------------

### FlowManager.get_current_context

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Get the current conversation context. This method retrieves a list of all messages within the current conversation.

```APIDOC
## get_current_context() -> list[dict]

### Description
Get the current conversation context.

### Returns
List of messages in the current context, including system messages,
user messages, and assistant responses.

### Raises
* **FlowError** – If context aggregator is not available.
```

--------------------------------

### FlowManager Initialization

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Initializes the FlowManager with necessary services and configurations.

```APIDOC
## FlowManager

Manages conversation flows.

The FlowManager orchestrates conversation flows by managing state transitions, function registration, and message handling across different LLM providers, with comprehensive action handling and error management.

### __init__

Initialize the flow manager.

#### Parameters:
* **llm** – LLM service or LLMSwitcher.
* **context_aggregator** – Context aggregator for updating user context.
* **worker** – PipelineWorker instance for queueing frames.
* **task** – PipelineWorker instance for queueing frames. Deprecated since version 1.2.0: Use `worker` instead. `task` will be removed in a future release.
* **context_strategy** – Context strategy configuration for managing conversation context during transitions.
* **transport** – Transport instance for communication.
* **global_functions** – Optional list of FlowsFunctionSchemas or FlowsDirectFunctions that will be available at every node. These functions are registered once during initialization and automatically included alongside node-specific functions.
```

--------------------------------

### Preview Changelog

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Generates a draft of the changelog for unreleased changes.

```bash
towncrier build --draft --version Unreleased
```

--------------------------------

### Create Changelog Fragment (Added Feature)

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Create a changelog fragment file for new features. The filename should include the PR number and the type 'added'.

```markdown
- Added support for custom context strategies in node transitions.
```

--------------------------------

### Include Audio Mode Configuration

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/evals/README.md

Use these includes to enable audio processing for user turns and judge bot speech in Pipecat Flows scenarios.

```yaml
user: !include _user_audio.yaml      # synthesize user turns (Kokoro)
judge: !include _judge_audio.yaml    # transcribe bot speech (Moonshine), then judge
```

--------------------------------

### Add pipecat-ai-flows to project

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Adds the pipecat-ai-flows module to your project using uv. Use 'uv add' for existing projects or 'uv init' followed by 'uv add' for new projects.

```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
```

--------------------------------

### Check Code Formatting

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Checks if the codebase is formatted correctly without making any changes.

```bash
uv run ruff format --check .
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Executes all tests and generates a code coverage report.

```bash
uv run pytest tests/ --cov=pipecat_flows
```

--------------------------------

### Multiple Changelog Fragments for One PR

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

When a single PR includes different types of changes, create separate fragment files for each type (e.g., added and fixed).

```bash
changelog/1234.added.md
changelog/1234.fixed.md
```

--------------------------------

### set_node_from_config Method

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Manually transition the conversation to a new node defined by its configuration.

```APIDOC
## set_node_from_config(node_config: NodeConfig) → None

### Description
Set up a new conversation node and transition to it. This method is used to manually transition between nodes in a flow, allowing for dynamic control over the conversation path.

### Parameters
* **node_config** – Configuration for the new node.

### Raises
* **FlowTransitionError** – If the manager is not initialized.
* **FlowError** – If node setup fails.
```

--------------------------------

### LLMAdapter.generate_summary

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.adapters.md

Generates a summary by performing a direct one-shot, out-of-band inference with the LLM.

```APIDOC
## async generate_summary(llm: Any, summary_prompt: str, context: LLMContext) -> str | None

### Description
Generate a summary by running a direct one-shot, out-of-band inference with the LLM.

### Parameters
#### Path Parameters
- **llm** (Any) - Required - LLM service instance containing client/credentials.
- **summary_prompt** (str) - Required - Prompt text to guide summary generation.
- **context** (LLMContext) - Required - Context object containing conversation history for the summary.

### Returns
- str | None - Generated summary text, or None if generation fails.
```

--------------------------------

### Working with Daily Transport Features

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Shows how to use the `DailyTransport` specific features, like retrieving participant information.

```APIDOC
## Working with Daily Transport Features

### Description
Interact with specific features of the `DailyTransport`, such as retrieving a list of participants in a room.

### Example
```python
async def get_room_info(action: dict, flow_manager: FlowManager):
    transport = flow_manager.transport
    if isinstance(transport, DailyTransport):
        participants = transport.participants()
        return {"participant_count": len(participants)}
```
```

--------------------------------

### Cross-Provider Evaluation

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/evals/README.md

Confirm provider-agnostic function formatting by setting the LLM_PROVIDER environment variable. This allows testing with different LLM providers like Anthropic or Google.

```bash
LLM_PROVIDER=anthropic uv run pipecat eval suite evals/manifest.yaml
```

--------------------------------

### Create Changelog Fragment (Fixed Bug)

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Create a changelog fragment file for bug fixes. The filename should include the PR number and the type 'fixed'.

```markdown
- Fixed an issue where interrupted transitions left the flow permanently stuck.
```

--------------------------------

### Clone the Repository

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Clone the forked Pipecat Flows repository to your local machine to begin making changes.

```bash
git clone https://github.com/your-username/pipecat-flows
```

--------------------------------

### ActionConfig

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Configuration for an action, specifying its type, handler, and associated parameters.

```APIDOC
## ActionConfig

### Description
Configuration for an action.

### Parameters
* **type** (Required[str]) - Action type identifier (e.g. “tts_say”, “notify_slack”).
* **handler** (Callable[[dict[str, Any]], Awaitable[None]] | Callable[[dict[str, Any], FlowManager], Awaitable[None]]) - Callable to handle the action.
* **text** (str) - Text to speak for the “tts_say” action, or the optional goodbye message for the “end_conversation” action.
* **append_text_to_context** (bool) - For the built-in TTS actions (“tts_say” and “end_conversation”), whether the spoken `text` is appended to the LLM context. Defaults to True.

### Note
Additional fields are allowed and passed to the handler.
```

--------------------------------

### Run All Tests

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Executes all tests in the project using pytest.

```bash
uv run pytest tests/
```

--------------------------------

### ContextStrategyConfig

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Configuration object for managing context, including the strategy and an optional summary prompt.

```APIDOC
## ContextStrategyConfig

### Description
Configuration for context management.

### Parameters
* **strategy** (ContextStrategy) - Strategy to use for context management.
* **summary_prompt** (str | None) - Required prompt text when using RESET_WITH_SUMMARY. Deprecated since version 1.0.0: Deprecated along with RESET_WITH_SUMMARY. Use `LLMContextSummaryConfig.summarization_prompt` instead. Will be removed in 2.0.0. Defaults to None.
```

--------------------------------

### Multiple Changelog Fragments of Same Type

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

For multiple changes of the same type within one PR, use numbered fragment files (e.g., .changed.2.md).

```bash
changelog/1234.changed.md
changelog/1234.changed.2.md
```

--------------------------------

### Accessing Transport

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Demonstrates how to access the transport layer from the FlowManager to interact with participants.

```APIDOC
## Accessing Transport

### Description
Access the transport layer from the `FlowManager` to interact with participants, such as updating their status.

### Example
```python
async def mute_participant(action: dict, flow_manager: FlowManager):
    transport = flow_manager.transport
    if transport and hasattr(transport, 'update_participant'):
        await transport.update_participant(participant_id, {"canSnd": False})
```
```

--------------------------------

### Run Specific Test

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Executes a particular test case within a specified test file.

```bash
uv run pytest tests/test_state.py -k test_initialization
```

--------------------------------

### Create a New Branch

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Create a new branch for your contribution to keep your changes organized and separate from the main development line.

```bash
git checkout -b your-branch-name
```

--------------------------------

### Run Tests with Coverage Report

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Executes all tests and generates a coverage report for the pipecat_flows package.

```bash
uv run pytest tests/ --cov=pipecat_flows
```

--------------------------------

### Clone Pipecat Flows Repository

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Clones the Pipecat Flows repository and navigates into the project directory.

```bash
git clone https://github.com/pipecat-ai/pipecat-flows.git
cd pipecat-flows
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Push your newly created branch with your committed changes to your forked repository on GitHub.

```bash
git push origin your-branch-name
```

--------------------------------

### Enum Class Docstring

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Demonstrates docstring conventions for Python Enum classes, including purpose and documentation for each enum value.

```python
class Status(Enum):
    """Status codes for processing operations.

    Parameters:
        PENDING: Operation is queued but not started.
        RUNNING: Operation is currently in progress.
        COMPLETED: Operation finished successfully.
        FAILED: Operation encountered an error.
    """

    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
```

--------------------------------

### ActionManager.schedule_deferred_post_actions

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.actions.md

Schedules a list of actions to be executed after the next LLM completion. These are typically actions that should occur after a user's response is processed.

```APIDOC
## schedule_deferred_post_actions(post_actions: list[ActionConfig]) -> None

### Description
Schedules "deferred" post-actions to be executed after next LLM completion.

### Method
POST

### Endpoint
/schedule_deferred_post_actions

### Parameters
#### Request Body
- **post_actions** (list[ActionConfig]) - Required - List of actions to execute after LLM response.

```

--------------------------------

### ContextStrategy

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Enum defining strategies for managing context during node transitions.

```APIDOC
## ContextStrategy

### Description
Strategy for managing context during node transitions.

### Members
* **APPEND** - Append new messages to existing context (default).
* **RESET** - Reset context with new messages only.
* **RESET_WITH_SUMMARY** - Reset context but include an LLM-generated summary. Deprecated since version 1.0.0: Use Pipecat’s native context summarization instead. Will be removed in 2.0.0.
```

--------------------------------

### ActionManager.execute_actions

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.actions.md

Executes a list of configured actions during a conversation state transition. Each action must have a 'type' field that corresponds to a registered handler.

```APIDOC
## async execute_actions(actions: list[ActionConfig] | None) -> None

### Description
Executes a list of actions. Each action must have a 'type' field matching a registered handler.

### Method
ASYNC POST

### Endpoint
/execute_actions

### Parameters
#### Request Body
- **actions** (list[ActionConfig] | None) - Required - List of action configurations to execute.

### Raises
- **ActionError** – If action execution fails.
```

--------------------------------

### Commit Changes

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Commit your changes with a descriptive message that clearly explains the modifications made.

```bash
git commit -m "Description of your changes"
```

--------------------------------

### Lint Code

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Checks the codebase for style and potential errors using Ruff.

```bash
uv run ruff check .
```

--------------------------------

### Accessing Transport Instance

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Provides access to the transport instance used for communication with the client.

```APIDOC
## `FlowManager.transport` Property

### Description
Access the transport instance used for communication. This property provides access to the transport instance that handles communication with the client.

### Returns
The transport instance if provided during initialization, None otherwise.

### Return type
Optional[BaseTransport]

### Examples

Accessing transport in action handlers:
```python
async def mute_participant(action: dict, flow_manager: FlowManager):
    transport = flow_manager.transport
    if transport and hasattr(transport, 'update_participant'):
        await transport.update_participant(participant_id, {"canSnd": False})
```

Working with Daily transport features:
```python
async def get_room_info(action: dict, flow_manager: FlowManager):
    transport = flow_manager.transport
    if isinstance(transport, DailyTransport):
        participants = transport.participants()
        return {"participant_count": len(participants)}
```
```

--------------------------------

### Set New Conversation Node

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Manually transition the conversation to a new node by providing its configuration to `set_node_from_config`. This method is used for dynamic flow transitions.

```python
await flow_manager.set_node_from_config(node_config)
```

--------------------------------

### Run All Tests

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Executes all tests in the Pipecat Flows test suite using pytest.

```bash
uv run pytest tests/
```

--------------------------------

### Work with Daily Transport Features

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Check if the transport is an instance of DailyTransport to access its specific features, such as retrieving participant information.

```python
async def get_room_info(action: dict, flow_manager: FlowManager):
    transport = flow_manager.transport
    if isinstance(transport, DailyTransport):
        participants = transport.participants()
        return {"participant_count": len(participants)}
```

--------------------------------

### LLMAdapter.format_summary_message

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.adapters.md

Formats a generated summary into a developer message using the LLMContextMessage format.

```APIDOC
## format_summary_message(summary: str) -> dict

### Description
Format a summary as a developer message. Summary messages use the LLMContextMessage format (OpenAI-style), as summarization triggers an LLMMessagesUpdateFrame.

### Parameters
#### Path Parameters
- **summary** (str) - Required - The generated summary text.

### Returns
- dict - A developer message containing the summary.
```

--------------------------------

### FlowManager Initialization

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Initializes the FlowManager, which orchestrates conversation flows by managing state transitions, function registration, and message handling.

```APIDOC
## `FlowManager` Constructor

### Description
Initializes the flow manager with necessary services and configurations.

### Parameters
* **llm** (LLMService | LLMSwitcher) - LLM service or LLMSwitcher.
* **context_aggregator** (Any) - Context aggregator for updating user context.
* **worker** (PipelineWorker | None) - PipelineWorker instance for queueing frames.
* **task** (PipelineWorker | None) - Deprecated since version 1.2.0: Use `worker` instead. `task` will be removed in a future release.
* **context_strategy** (ContextStrategyConfig | None) - Context strategy configuration for managing conversation context during transitions.
* **transport** (BaseTransport | None) - Transport instance for communication.
* **global_functions** (list[FlowsFunctionSchema | Callable[[...], Awaitable[tuple[Any, NodeConfig | None]]]] | None) - Optional list of FlowsFunctionSchemas or FlowsDirectFunctions that will be available at every node.
```

--------------------------------

### NodeConfig

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Configuration for a single node in the flow, specifying task messages, node name, role, functions, actions, context strategy, and immediate response behavior.

```APIDOC
## class pipecat_flows.types.NodeConfig

Bases: `TypedDict`

Configuration for a single node in the flow.

* **Parameters:**
  * **task_messages** – List of message dicts defining the current node’s objectives.
  * **name** – Name of the node, useful for debug logging when returning a next node
    from a “consolidated” function.
  * **role_message** – The bot’s role/personality as a plain string, sent as the
    LLM’s system instruction via `LLMUpdateSettingsFrame`. When
    provided, the system instruction persists across node transitions
    until a new node explicitly sets `role_message` again.
  * **role_messages** – 

    Deprecated list-of-dicts format for the bot’s role/personality.

    #### Deprecated
    Deprecated since version 0.0.24: Use `role_message` (str) instead. Will be removed in 2.0.0.
  * **functions** – List of FlowsFunctionSchema definitions or direct functions
    whose definitions are automatically extracted from their signatures.
  * **pre_actions** – Actions to execute before LLM inference.
  * **post_actions** – Actions to execute after LLM inference.
  * **context_strategy** – Strategy for updating context during transitions.
  * **respond_immediately** – Whether to run LLM inference as soon as the node is
    set (default: True).

Example:

```default
{
    "role_message": "You are a helpful assistant...",
    "task_messages": [
        {
            "role": "developer",
            "content": "Ask the user for their name..."
        }
    ],
    "functions": [...],
    "pre_actions": [...],
    "post_actions": [...],
    "context_strategy": ContextStrategyConfig(strategy=ContextStrategy.APPEND),
    "respond_immediately": true,
}
```

#### task_messages *: Required[list[dict]]*

#### name *: str*

#### role_message *: str*

#### role_messages *: list[dict[str, Any]]*

#### functions *: list[FlowsFunctionSchema | Callable[[...], Awaitable[tuple[Any, NodeConfig | None]]]]*

#### pre_actions *: list[ActionConfig]*

#### post_actions *: list[ActionConfig]*

#### context_strategy *: ContextStrategyConfig*

#### respond_immediately *: bool*
```

--------------------------------

### register_action Method

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Register a handler for a specific action type to customize flow behavior.

```APIDOC
## register_action(action_type: str, handler: Callable) → None

### Description
Register a handler for a specific action type. This allows you to define custom logic that will be executed when a particular action is triggered within the flow.

### Parameters
* **action_type** – String identifier for the action (e.g., “tts_say”).
* **handler** – Async or sync function that handles the action.

### Example
```python
async def custom_notification(action: dict):
    text = action.get("text", "")
    await notify_user(text)

flow_manager.register_action("notify", custom_notification)
```
```

--------------------------------

### Lint and Fix Code

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CLAUDE.md

Checks the codebase for style and potential errors using Ruff and automatically fixes them.

```bash
uv run ruff check --fix .
```

--------------------------------

### flows_direct_function

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Deprecated decorator to configure a Flows direct function's call options. Use flows_tool_options instead.

```APIDOC
## pipecat_flows.flows_direct_function(, cancel_on_interruption: bool = False, timeout_secs: float | None = None) -> Callable[[Callable], Callable]

### Description
Configure a Flows direct function’s call options.

#### Deprecated
Deprecated since version 1.x.0: Renamed to `flows_tool_options()` to align with Pipecat’s `@tool_options` and make clearer that it configures call options. This alias still works but will be removed in a future version.

### Parameters
- **cancel_on_interruption** (bool) - Optional - Whether to cancel the function call when the user interrupts. Defaults to False.
- **timeout_secs** (float | None) - Optional - Optional per-tool timeout in seconds, overriding the global `function_call_timeout_secs`. Defaults to None (use global timeout).

### Returns
A decorator that attaches the metadata to the function.
```

--------------------------------

### NodeConfig

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.md

Configuration for a single node in the flow, defining its objectives, role, and actions.

```APIDOC
## class pipecat_flows.NodeConfig

### Description
Configuration for a single node in the flow.

### Parameters
- **task_messages** (List[dict]) - Required - List of message dicts defining the current node’s objectives.
- **name** (str) - Required - Name of the node, useful for debug logging when returning a next node from a “consolidated” function.
- **role_message** (str) - Required - The bot’s role/personality as a plain string, sent as the LLM’s system instruction via `LLMUpdateSettingsFrame`. When provided, the system instruction persists across node transitions until a new node explicitly sets `role_message` again.
- **role_messages** (List[dict[str, Any]]) - Deprecated - List-of-dicts format for the bot’s role/personality. Use `role_message` (str) instead. Will be removed in 2.0.0.
- **functions** (List[FlowsFunctionSchema | Callable[[...], Awaitable[tuple[Any, NodeConfig | None]]]]) - Required - List of FlowsFunctionSchema definitions or direct functions whose definitions are automatically extracted from their signatures.
- **pre_actions** (List[ActionConfig]) - Required - Actions to execute before LLM inference.
- **post_actions** (List[ActionConfig]) - Required - Actions to execute after LLM inference.
- **context_strategy** (ContextStrategyConfig) - Required - Strategy for updating context during transitions.
- **respond_immediately** (bool) - Required - Whether to run LLM inference as soon as the node is set (default: True).

### Example
```default
{
    "role_message": "You are a helpful assistant...",
    "task_messages": [
        {
            "role": "developer",
            "content": "Ask the user for their name..."
        }
    ],
    "functions": [...],
    "pre_actions": [...],
    "post_actions": [...],
    "context_strategy": ContextStrategyConfig(strategy=ContextStrategy.APPEND),
    "respond_immediately": true,
}
```
```

--------------------------------

### Run Specific Test File

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/README.md

Executes tests within a specific file in the Pipecat Flows test suite.

```bash
uv run pytest tests/test_state.py
```

--------------------------------

### Register Custom Action Handler

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Register a custom handler function for a specific action type using `register_action`. This allows the flow to respond to custom events or commands.

```python
async def custom_notification(action: dict):
    text = action.get("text", "")
    await notify_user(text)

flow_manager.register_action("notify", custom_notification)
```

--------------------------------

### Queue Custom Frames with PipelineWorker

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Utilize the `worker` property to access the `PipelineWorker` and queue custom frames, such as `TTSUpdateSettingsFrame`, for advanced flow control.

```python
async def send_custom_notification(action: dict, flow_manager: FlowManager):
    from pipecat.frames.frames import TTSUpdateSettingsFrame

    # Queue a TTS settings update frame
    await flow_manager.worker.queue_frame(
        TTSUpdateSettingsFrame(settings={"voice": "your-new-voice-id"})
    )
```

--------------------------------

### flows_tool_options

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Decorator to configure a Flows direct function's call options, such as cancellation on interruption and timeout.

```APIDOC
## flows_tool_options

pipecat_flows.types.flows_tool_options(, cancel_on_interruption: bool = False, timeout_secs: float | None = None) → Callable[[Callable], Callable]

Configure a Flows direct function’s call options.

This decorator is optional; use it to override the defaults for a Flows
direct function (an async function whose first parameter is `flow_manager`).

* **Parameters:**
  * **cancel_on_interruption** – Whether to cancel the function call when the user
    interrupts. Defaults to False.
  * **timeout_secs** – Optional per-tool timeout in seconds, overriding the global
    `function_call_timeout_secs`. Defaults to None (use global timeout).
* **Returns:**
  A decorator that attaches the metadata to the function.

Example:

```default
@flows_tool_options(cancel_on_interruption=False, timeout_secs=30)
async def long_running_task(flow_manager: FlowManager, query: str):
    '''Perform a long-running task that should not be cancelled on interruption.'''
    # ... implementation
    return {"status": "complete"}, None
```
```

--------------------------------

### Setting Flow Manager State

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Assign values to keys in the flow manager's state dictionary to store conversation data.

```python
flow_manager.state["user_name"] = "Alice"
flow_manager.state["age"] = 25
```

--------------------------------

### LegacyActionHandler

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Legacy action handler type that only receives the action dictionary. This type is deprecated and will be removed in a future version.

```APIDOC
## LegacyActionHandler

### Description
Legacy action handler type that only receives the action dictionary. Deprecated since version 1.x.0: Use `FlowActionHandler` (`(action, flow_manager)`) instead. Will be removed in 2.0.0.

### Parameters
* **action** (dict) - Dictionary containing action configuration and parameters.

### Example
```default
async def simple_handler(action: dict):
    await notify(action["text"])
```

### Type Alias
`Callable`[[`dict`[`str`, `Any`]], `Awaitable`[`None`]]
```

--------------------------------

### Configure Flows Direct Function Call Options with flows_tool_options

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Use this decorator to override default call options for a Flows direct function, such as cancellation behavior and timeouts. It attaches metadata to the function.

```python
@flows_tool_options(cancel_on_interruption=False, timeout_secs=30)
async def long_running_task(flow_manager: FlowManager, query: str):
    '''Perform a long-running task that should not be cancelled on interruption.'''
    # ... implementation
    return {"status": "complete"}, None
```

--------------------------------

### flows_direct_function (Deprecated)

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

Deprecated alias for flows_tool_options, used to configure call options for Flows direct functions.

```APIDOC
## flows_direct_function (Deprecated)

pipecat_flows.types.flows_direct_function(, cancel_on_interruption: bool = False, timeout_secs: float | None = None) → Callable[[Callable], Callable]

Configure a Flows direct function’s call options.

#### Deprecated
Deprecated since version 1.x.0: Renamed to `flows_tool_options()` to align with Pipecat’s
`@tool_options` and make clearer that it configures call options. This
alias still works but will be removed in a future version.

* **Parameters:**
  * **cancel_on_interruption** – Whether to cancel the function call when the user
    interrupts. Defaults to False.
  * **timeout_secs** – Optional per-tool timeout in seconds, overriding the global
    `function_call_timeout_secs`. Defaults to None (use global timeout).
* **Returns:**
  A decorator that attaches the metadata to the function.
```

--------------------------------

### ActionManager.clear_deferred_post_actions

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.actions.md

Clears any actions that were previously scheduled to be executed after the next LLM completion.

```APIDOC
## clear_deferred_post_actions() -> None

### Description
Clears any scheduled deferred post-actions.

### Method
DELETE

### Endpoint
/clear_deferred_post_actions

```

--------------------------------

### Related Changes in One Fragment

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/CONTRIBUTING.md

Group related changes within a single fragment file using nested bullets for clarity.

```markdown
- Updated node configuration:
  - Changed default context strategy to APPEND
  - Added validation for task messages
```

--------------------------------

### ZeroArgFunctionHandler

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.types.md

A deprecated function handler that takes no arguments. Use FlowFunctionHandler instead.

```APIDOC
### pipecat_flows.types.ZeroArgFunctionHandler

Function handler that takes no arguments.

#### Deprecated
Deprecated since version 1.x.0: Use `FlowFunctionHandler` (`(args, flow_manager)`) instead. Will be
removed in 2.0.0.

* **Returns:**
  Any JSON-serializable value, or a `ConsolidatedFunctionResult`
  tuple to also specify the next node.

alias of `Callable`[[], `Awaitable`[`Any`]]
```

--------------------------------

### Checking for State Existence

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Use the 'in' operator to check if a key exists in the flow manager's state dictionary before accessing it.

```python
if "user_preferences" in flow_manager.state:
    preferences = flow_manager.state["user_preferences"]
```

--------------------------------

### task Property (Deprecated)

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/docs/api/pipecat_flows.manager.md

Access the pipeline worker instance for frame queueing. This property is deprecated and `worker` should be used instead.

```APIDOC
## task Property

### Description
Access the pipeline worker instance for frame queueing.

#### Deprecated
Deprecated since version 1.2.0: Use `worker` instead. This property will be removed in a future release.

### Returns
The pipeline worker instance used for frame processing and queueing operations.

### Return Type
PipelineWorker
```

--------------------------------

### Pull Judge LLM Model

Source: https://github.com/pipecat-ai/pipecat-flows/blob/main/evals/README.md

Pulls the default judge model (gemma2:9b) for local Ollama to be used for 'eval:' criteria.

```bash
ollama pull gemma2:9b
```