tuner-pipecat-sdk 0.1.0__tar.gz

tuner_pipecat_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest

tuner_pipecat_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+local-docs/
+.venv/
+.python-version
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.env
+settings.json
+settings.local.json

tuner_pipecat_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuner Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tuner_pipecat_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: tuner-pipecat-sdk
+Version: 0.1.0
+Summary: Pipecat FrameProcessor that observes pipecat-flows calls and sends structured data to the Tuner API.
+Project-URL: Homepage, https://github.com/usetuner/tuner-pipecat-sdk-python
+Project-URL: Documentation, https://github.com/usetuner/tuner-pipecat-sdk-python/tree/main/docs
+Project-URL: Repository, https://github.com/usetuner/tuner-pipecat-sdk-python
+Project-URL: Issues, https://github.com/usetuner/tuner-pipecat-sdk-python/issues
+Author: Tuner Team
+License: MIT License
+        
+        Copyright (c) 2026 Tuner Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,observability,pipecat,sdk,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: loguru~=0.7.2
+Requires-Dist: pipecat-ai>=0.0.105
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: hatch>=1.12; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == 'lint'
+Provides-Extra: publish
+Requires-Dist: hatch>=1.12; extra == 'publish'
+Requires-Dist: twine>=5.0; extra == 'publish'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Provides-Extra: type
+Requires-Dist: mypy>=1.10; extra == 'type'
+Description-Content-Type: text/markdown
+
+# tuner-pipecat-sdk
+
+`tuner-pipecat-sdk` is a lightweight observer SDK for [`pipecat-flows`](https://github.com/pipecat-ai/pipecat-flows).
+It captures flow transitions, latency signals, transcript segments, and usage metadata,
+then sends a structured `CallPayload` to the Tuner API when a call ends.
+
+
+
+## Requirements
+
+- Python **3.10–3.13**. 
+- **Do not use Python 3.14** for installs yet: Pipecat pulls **`onnxruntime~=1.23.2`** and **`numba`** without 3.14 wheels → errors like *No matching distribution found for onnxruntime*.
+- This SDK depends on **`pipecat-ai>=0.0.105`**.
+
+## Installation
+
+```bash
+pip install tuner-pipecat-sdk
+```
+
+
+## Quick Start Example
+
+```python
+import uuid
+from tuner_pipecat_sdk import FlowsObserver
+
+observer = FlowsObserver(
+    api_key="YOUR_TUNER_API_KEY",
+    workspace_id=42,
+    agent_id="my-agent",
+    call_id=str(uuid.uuid4()),
+    base_url="https://app.usetuner.ai",
+    asr_model="deepgram/nova-3",
+    llm_model="gpt-4o-mini",
+    tts_model="cartesia/sonic",
+)
+
+# Required: attach the flow manager before running the pipeline
+observer.attach_flow_manager(flow_manager)
+observer.attach_turn_tracking_observer(turn_tracker)
+```
+
+
+Place the observer after TTS in your pipeline:
+
+```python
+Pipeline([
+    transport.input(),
+    stt,
+    context_aggregator.user(),
+    llm,
+    tts,
+    observer,
+    transport.output(),
+    context_aggregator.assistant(),
+])
+```
+
+Enable metrics on the pipeline task so latency and usage fields are populated:
+
+```python
+from pipecat.pipeline.task import PipelineTask
+from pipecat.pipeline.pipeline_params import PipelineParams
+from pipecat.observers.turn_tracking_observer import TurnTrackingObserver
+
+turn_tracker = TurnTrackingObserver()
+
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(
+        observers=[observer.latency_observer, turn_tracker],
+        enable_metrics=True,
+        enable_usage_metrics=True,
+    ),
+)
+```
+
+Without these flags the observer will log warnings and LLM/TTS metric fields will be absent from the payload.
+For more example check https://github.com/usetuner/tuner-pipecat-sdk-python/tree/main/examples
+
+## FlowsObserver Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | — | Tuner API key |
+| `workspace_id` | `int` | — | Tuner workspace ID |
+| `agent_id` | `str` | — | Agent identifier |
+| `call_id` | `str` | — | Unique call ID (use `uuid4()`) |
+| `base_url` | `str` | `http://localhost:8000` | Tuner API base URL |
+| `call_type` | `str` | `"web_call"` | Call type label |
+| `recording_url` | `str` | `"pipecat://no-recording"` | Recording URL if available |
+| `asr_model` | `str` | `""` | ASR model name (e.g. `deepgram/nova-3`) |
+| `llm_model` | `str` | `""` | LLM model name (e.g. `gpt-4o-mini`) |
+| `tts_model` | `str` | `""` | TTS model name (e.g. `cartesia/sonic`) |
+| `debug` | `bool` | `False` | Log full transcript at flush |
+
+## Public API
+
+- `tuner_pipecat_sdk.FlowsObserver`
+- `tuner_pipecat_sdk.TunerConfig`
+
+Payload and transcript schemas are available under `tuner_pipecat_sdk.models`.
+
+
+## To build the project
+folow the steps in setup_guide.md

tuner_pipecat_sdk-0.1.0/README.md

@@ -0,0 +1,107 @@
+# tuner-pipecat-sdk
+
+`tuner-pipecat-sdk` is a lightweight observer SDK for [`pipecat-flows`](https://github.com/pipecat-ai/pipecat-flows).
+It captures flow transitions, latency signals, transcript segments, and usage metadata,
+then sends a structured `CallPayload` to the Tuner API when a call ends.
+
+
+
+## Requirements
+
+- Python **3.10–3.13**. 
+- **Do not use Python 3.14** for installs yet: Pipecat pulls **`onnxruntime~=1.23.2`** and **`numba`** without 3.14 wheels → errors like *No matching distribution found for onnxruntime*.
+- This SDK depends on **`pipecat-ai>=0.0.105`**.
+
+## Installation
+
+```bash
+pip install tuner-pipecat-sdk
+```
+
+
+## Quick Start Example
+
+```python
+import uuid
+from tuner_pipecat_sdk import FlowsObserver
+
+observer = FlowsObserver(
+    api_key="YOUR_TUNER_API_KEY",
+    workspace_id=42,
+    agent_id="my-agent",
+    call_id=str(uuid.uuid4()),
+    base_url="https://app.usetuner.ai",
+    asr_model="deepgram/nova-3",
+    llm_model="gpt-4o-mini",
+    tts_model="cartesia/sonic",
+)
+
+# Required: attach the flow manager before running the pipeline
+observer.attach_flow_manager(flow_manager)
+observer.attach_turn_tracking_observer(turn_tracker)
+```
+
+
+Place the observer after TTS in your pipeline:
+
+```python
+Pipeline([
+    transport.input(),
+    stt,
+    context_aggregator.user(),
+    llm,
+    tts,
+    observer,
+    transport.output(),
+    context_aggregator.assistant(),
+])
+```
+
+Enable metrics on the pipeline task so latency and usage fields are populated:
+
+```python
+from pipecat.pipeline.task import PipelineTask
+from pipecat.pipeline.pipeline_params import PipelineParams
+from pipecat.observers.turn_tracking_observer import TurnTrackingObserver
+
+turn_tracker = TurnTrackingObserver()
+
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(
+        observers=[observer.latency_observer, turn_tracker],
+        enable_metrics=True,
+        enable_usage_metrics=True,
+    ),
+)
+```
+
+Without these flags the observer will log warnings and LLM/TTS metric fields will be absent from the payload.
+For more example check https://github.com/usetuner/tuner-pipecat-sdk-python/tree/main/examples
+
+## FlowsObserver Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | — | Tuner API key |
+| `workspace_id` | `int` | — | Tuner workspace ID |
+| `agent_id` | `str` | — | Agent identifier |
+| `call_id` | `str` | — | Unique call ID (use `uuid4()`) |
+| `base_url` | `str` | `http://localhost:8000` | Tuner API base URL |
+| `call_type` | `str` | `"web_call"` | Call type label |
+| `recording_url` | `str` | `"pipecat://no-recording"` | Recording URL if available |
+| `asr_model` | `str` | `""` | ASR model name (e.g. `deepgram/nova-3`) |
+| `llm_model` | `str` | `""` | LLM model name (e.g. `gpt-4o-mini`) |
+| `tts_model` | `str` | `""` | TTS model name (e.g. `cartesia/sonic`) |
+| `debug` | `bool` | `False` | Log full transcript at flush |
+
+## Public API
+
+- `tuner_pipecat_sdk.FlowsObserver`
+- `tuner_pipecat_sdk.TunerConfig`
+
+Payload and transcript schemas are available under `tuner_pipecat_sdk.models`.
+
+
+## To build the project
+folow the steps in setup_guide.md

tuner_pipecat_sdk-0.1.0/docs/api.md

@@ -0,0 +1,47 @@
+# API Reference
+
+## `FlowsObserver`
+
+`FlowsObserver` is a `FrameProcessor` that captures runtime signals and emits one payload per call.
+
+Constructor:
+
+```python
+FlowsObserver(
+    api_key: str,
+    workspace_id: int,
+    agent_id: str,
+    call_id: str,
+    call_type: str = "web_call",
+    base_url: str = "http://localhost:8000",
+    recording_url: str = "pipecat://no-recording",
+    debug: bool = False,
+    asr_model: str = "",
+    llm_model: str = "",
+    tts_model: str = "",
+)
+```
+
+Methods:
+
+- `attach_flow_manager(flow_manager) -> None`
+- `attach_turn_tracking_observer(turn_tracker) -> None`
+- `latency_observer -> UserBotLatencyObserver`
+
+## `TunerConfig`
+
+Validated configuration model used by the observer and HTTP client.
+
+Validation rules:
+
+- `api_key`, `agent_id`, `call_id` must be non-empty.
+- `workspace_id` must be a positive integer.
+
+## Models
+
+Public payload and transcript models are available via:
+
+- `tuner_pipecat_sdk.models.CallPayload`
+- `tuner_pipecat_sdk.models.TranscriptSegment`
+- `tuner_pipecat_sdk.models.ToolInfo`
+- `tuner_pipecat_sdk.models.NodeInfo`

tuner_pipecat_sdk-0.1.0/docs/getting-started.md

@@ -0,0 +1,102 @@
+# Getting Started
+
+## Requirements
+
+- Python 3.10+
+- A `pipecat` bot that uses `pipecat-flows`
+- Tuner API credentials (`api_key`, `workspace_id`, `agent_id`)
+
+## Pipecat app working directory
+
+Run the pipeline from your **Pipecat application project root** (the app that creates the pipeline, adds `FlowsObserver`, and calls `PipelineTask`). That is the working directory (`pwd`) for the process that runs this SDK.
+
+Example: if your app is at `/path/to/pipecat-app`, start your server or script from there:
+
+```bash
+cd /path/to/pipecat-app
+python -m your_app.main
+# or
+uv run your_app
+```
+
+Relative imports, config paths, and pipeline setup all resolve from this directory. The observer runs inside the pipeline process; it does not need a separate working directory.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Minimal Setup
+
+```python
+import uuid
+from tuner_pipecat_sdk import FlowsObserver
+
+observer = FlowsObserver(
+    api_key="YOUR_TUNER_API_KEY",
+    workspace_id=42,
+    agent_id="support-agent",
+    call_id=str(uuid.uuid4()),
+    base_url="https://your-tuner-api.example.com",
+    asr_model="deepgram/nova-3",
+    llm_model="gpt-4o-mini",
+    tts_model="cartesia/sonic",
+)
+
+observer.attach_flow_manager(flow_manager)
+```
+
+Set `asr_model`, `llm_model`, and `tts_model` to populate
+`general_meta_data_raw.ai_models` in the payload.
+
+## Pipeline Placement
+
+Put `FlowsObserver` after TTS and before transport output:
+
+```python
+Pipeline([
+    transport.input(),
+    stt,
+    context_aggregator.user(),
+    llm,
+    tts,
+    observer,
+    transport.output(),
+    context_aggregator.assistant(),
+])
+```
+
+## Metrics from Pipecat (required for full payload)
+
+The SDK reads **usage and latency from Pipecat only** (no fallback). Ensure the task is created with metrics enabled:
+
+```python
+from pipecat.pipeline.task import PipelineTask
+from pipecat.pipeline.pipeline_params import PipelineParams
+from pipecat.observers.turn_tracking_observer import TurnTrackingObserver
+
+turn_tracker = TurnTrackingObserver()
+observer.attach_turn_tracking_observer(turn_tracker)
+
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(
+        observers=[observer.latency_observer, turn_tracker],
+        enable_metrics=True,
+        enable_usage_metrics=True,
+    ),
+)
+```
+
+Without these, `llm_token`, `tts_character_count`, and per-turn `ttfb_ms` / `llm_ms` / `tts_ms` will be absent (null/zero) in the payload.
+
+## What Happens at Call End
+
+When `EndFrame` or `CancelFrame` is observed:
+
+1. The observer reads transcript context from the attached flow manager.
+2. It builds a typed `CallPayload`.
+3. It sends the payload to `POST /api/v1/public/call`.
+
+Network failures are logged and swallowed so the media pipeline is not blocked.

tuner_pipecat_sdk-0.1.0/docs/integration.md

@@ -0,0 +1,37 @@
+# Integration Guide
+
+## Integration Contract
+
+`FlowsObserver` reads runtime events from your pipeline and emits one payload at call end.
+Turn timing is captured through `attach_turn_tracking_observer(...)`.
+
+## Recommended Flow
+
+1. Create your `FlowManager`.
+2. Create `FlowsObserver` with call metadata and model names.
+3. Call `observer.attach_flow_manager(flow_manager)` once before starting the task.
+4. Run your pipeline with observer after TTS.
+
+## Captured Signals
+
+- Call start/end timestamps and total duration
+- Per-turn latency: user stop to LLM, TTS, bot start, and bot stop
+- ASR confidence per turn
+- Flow node transitions:
+  - from/to node
+  - triggering function and arguments
+- Transcript segments:
+  - user turns
+  - agent turns
+  - tool call segments
+  - tool result segments
+  - node transition segments
+
+## Notes on Interruptions and TTS
+
+Interruption behavior in transcript context depends on the TTS provider behavior in `pipecat`:
+
+- Providers with word timestamps typically commit only spoken words.
+- Providers without word timestamps often commit full synthesized text before playback.
+
+For strongly structured flows, `pipecat-flows` context reset strategies can help keep context clean between nodes.

tuner_pipecat_sdk-0.1.0/examples/README.md

@@ -0,0 +1,56 @@
+# Examples
+
+Each example shows a different voice bot use case built with [Pipecat Flows](https://github.com/pipecat-ai/pipecat-flows) and observed with `pipecat-flows-tuner`.
+
+Every example is self-contained with its own `pyproject.toml`. Run `uv sync` inside the example directory and follow its README.
+
+---
+
+## Examples
+
+| Example | Use case | Key concepts |
+|---------|----------|-------------|
+| [`customer_support/`](customer_support/) | Acme Corp support agent | Multi-branch flow, state accumulation, resolve vs. escalate |
+| [`appointment_booking/`](appointment_booking/) | Medical clinic receptionist | Linear 7-node flow, enum inputs, confirmation + reschedule |
+| [`pizza_order/`](pizza_order/) | Pipecat Pizza ordering | Toppings selection, delivery/pickup branch, running price total |
+
+---
+
+## Prerequisites
+
+All examples share the same requirements:
+
+- Python 3.10+, [`uv`](https://docs.astral.sh/uv/)
+- For **installing the SDK with pip**, Python version issues, or local path deps, see the **repository root README** (not repeated here).
+- API keys: `CARTESIA_API_KEY`, `DEEPGRAM_API_KEY`, `OPENAI_API_KEY`
+- Optional: Tuner API credentials (`TUNER_API_KEY`, `TUNER_WORKSPACE_ID`, `TUNER_AGENT_ID`, `TUNER_BASE_URL`)
+
+---
+
+## Quick start
+
+```bash
+cd examples/<example_name>
+uv sync
+cp .env.example .env   # fill in your API keys
+uv run <example_name>.py
+```
+
+Then open http://localhost:7860 and click **Connect**.
+
+---
+
+## How the SDK fits in
+
+```
+transport.input()
+    └─► STT
+        └─► context_aggregator.user()
+            └─► LLM
+                └─► TTS
+                    └─► FlowsObserver   ← pipecat-flows-tuner
+                        └─► transport.output()
+                            └─► context_aggregator.assistant()
+```
+
+`FlowsObserver` sits after TTS in the pipeline. It intercepts metrics frames, tracks node transitions via `attach_flow_manager()`, and posts a structured `CallPayload` to the Tuner API when the call ends.

tuner_pipecat_sdk-0.1.0/examples/appointment_booking/.env.example

@@ -0,0 +1,12 @@
+# Audio Services
+DEEPGRAM_API_KEY=
+CARTESIA_API_KEY=
+
+# LLM
+OPENAI_API_KEY=
+
+# Tuner Observability
+TUNER_API_KEY=
+TUNER_WORKSPACE_ID=
+TUNER_AGENT_ID=appointment-booking-bot
+TUNER_BASE_URL=https://app.tuner.ai

tuner_pipecat_sdk-0.1.0/examples/appointment_booking/README.md

@@ -0,0 +1,67 @@
+# Appointment Booking Bot
+
+A medical clinic appointment booking bot built with Pipecat Flows and the `pipecat-flows-tuner` SDK.
+
+**What it demonstrates:**
+- Linear 7-node data-collection flow
+- Enum-constrained inputs (service type, day, time slot)
+- State accumulation across nodes (`patient_name`, `service`, `day`, `time_slot`, `phone`)
+- Confirmation node with reschedule branch
+- Full call observability via `FlowsObserver`
+
+## Flow diagram
+
+```
+greeting
+   └─► service_type
+           └─► preferred_day
+                   └─► preferred_time
+                               └─► contact_info
+                                       └─► confirm
+                                               ├─► farewell (confirmed)
+                                               └─► farewell (reschedule)
+```
+
+## Prerequisites
+
+- Python 3.10+
+- `uv` package manager
+
+## Setup
+
+1. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+2. Create a `.env` file:
+
+   ```env
+   CARTESIA_API_KEY=your_cartesia_key
+   DEEPGRAM_API_KEY=your_deepgram_key
+   OPENAI_API_KEY=your_openai_key
+
+   # Optional — Tuner observability (defaults to local dev server)
+   TUNER_API_KEY=dev
+   TUNER_WORKSPACE_ID=1
+   TUNER_AGENT_ID=appointment-booking-bot
+   TUNER_BASE_URL=http://localhost:8000
+   ```
+
+## Run
+
+```bash
+uv run appointment_booking.py
+```
+
+Open http://localhost:7860 in your browser and click **Connect**.
+
+## Services used
+
+| Role | Service |
+|------|---------|
+| STT  | Deepgram Nova-3 |
+| LLM  | OpenAI GPT-4o-mini |
+| TTS  | Cartesia Sonic |
+| Transport | SmallWebRTC (default) |