pipecat-roark 0.1.0__tar.gz

pipecat_roark-0.1.0/.env.example

@@ -0,0 +1,16 @@
+# ---------------------------------------------------------------------------
+# Roark — required by RoarkObserver itself
+# ---------------------------------------------------------------------------
+
+# Roark API key — create one on the API keys page in your Roark project.
+# This is the only Roark setting you need; the observer knows its own endpoints.
+ROARK_API_KEY=rk_live_replace_me
+
+# ---------------------------------------------------------------------------
+# Services — only needed to run examples/bot.py (not by the library itself).
+# Swap providers freely in your own pipeline; RoarkObserver is provider-agnostic.
+# ---------------------------------------------------------------------------
+
+DEEPGRAM_API_KEY=
+OPENAI_API_KEY=
+CARTESIA_API_KEY=

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

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          # Tests that import pipecat-ai are guarded with pytest.importorskip,
+          # so installing the dev extras alone is enough for CI.
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src/pipecat_roark
+      - name: Test
+        run: pytest -q

pipecat_roark-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# Auto-publish to PyPI on merge to main, but only when the version in
+# pyproject.toml has been bumped. Merging changes that don't touch the
+# version is a no-op (no duplicate-upload failures on PyPI).
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  # 1. Decide whether this push is a release: did the version change?
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.check.outputs.changed }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # need full history so we can see existing tags
+      - name: Check whether the version was bumped
+        id: check
+        run: |
+          version=$(grep -m1 -E '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if git rev-parse "v$version" >/dev/null 2>&1; then
+            echo "Tag v$version already exists — nothing to publish."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "New version v$version detected — will publish."
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  # 2. Gate the release on the full test/lint/type-check matrix passing.
+  test:
+    needs: check-version
+    if: needs.check-version.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src/pipecat_roark
+      - name: Test
+        run: pytest -q
+
+  # 3. Build, publish to PyPI via Trusted Publishing, then tag + release on GitHub.
+  publish:
+    needs: [check-version, test]
+    if: needs.check-version.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      # PyPI Trusted Publishing — no API token in repo secrets.
+      # See https://docs.pypi.org/trusted-publishers/
+      id-token: write
+      # Needed to push the version tag and create the GitHub release.
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Tag and create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${{ needs.check-version.outputs.version }}"
+          git tag "v$version"
+          git push origin "v$version"
+          gh release create "v$version" dist/* \
+            --title "v$version" \
+            --generate-notes

pipecat_roark-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Build / dist
+build/
+dist/
+*.egg-info/
+*.egg
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

pipecat_roark-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `pipecat-roark` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **BREAKING:** Roark service endpoints are now built into the client. The
+  `ROARK_WEBHOOK_URL` and `ROARK_CHUNK_UPLOAD_URL_ENDPOINT` env vars are no
+  longer read or required — `ROARK_API_KEY` (or `api_key=`) is the only Roark
+  configuration. Remove those two vars from your environment / deployment
+  secrets; they are now ignored.
+
+## [0.1.0] - 2026-05-22
+
+Initial public release. Drop-in `RoarkObserver` for Pipecat that ships call
+lifecycle, transcripts, tool calls, and audio recordings to Roark. Compatible
+with `pipecat-ai >= 0.0.40, < 1`; tested with `pipecat-ai` 0.0.108. Prepared
+for submission to the
+[Pipecat community-integrations](https://github.com/pipecat-ai/pipecat/blob/main/COMMUNITY_INTEGRATIONS.md)
+listing.
+
+### Added
+
+- `RoarkObserver` (`BaseObserver` subclass) capturing call lifecycle from
+  native Pipecat frames — `TranscriptionFrame`, `TTSTextFrame`,
+  `BotStoppedSpeakingFrame`, `InterruptionFrame`, `FunctionCallInProgressFrame`,
+  `FunctionCallResultFrame`, `EndFrame`, `CancelFrame`, `StopFrame`.
+- Default `AudioBufferProcessor` auto-created with stereo channels and
+  ~256 KB chunks. Sample rate is adopted from the pipeline's `StartFrame` so
+  it tracks whatever the transport negotiated (8 kHz Twilio/Telnyx,
+  16/24/48 kHz Daily/LiveKit). Exposed as `observer.audio_processor` for
+  power users; pass `audio_buffer_processor=` to override.
+- Chunked audio upload via presigned S3 URLs requested per chunk from the
+  Roark chunk-upload endpoint; in-flight uploads are drained before
+  `call-ended` is posted.
+- Frame deduplication by frame id (Pipecat invokes `on_push_frame` once per
+  processor-to-processor hop; without dedupe the same transcription would
+  repeat N times).
+- `aflush(reason=...)` idempotent escape hatch for WebRTC transports that
+  tear down without pushing `EndFrame` (notably `SmallWebRTC`).
+- OpenTelemetry correlation via shared `pipecat_call_id` ↔
+  `PipelineTask.conversation_id`.
+- `examples/basic_observer.py` — minimal transport-agnostic wiring sketch.
+- `examples/bot.py` — runnable foundational voice assistant
+  (Deepgram STT → OpenAI LLM → Cartesia TTS) using the canonical Pipecat
+  0.0.108 runner pattern (`LLMContext` + `LLMContextAggregatorPair`,
+  `create_transport`, `on_client_connected` / `on_client_disconnected`).
+  Same file runs self-hosted (`--transport webrtc` / `--transport daily`)
+  and deploys to Pipecat Cloud unchanged.
+
+### Configuration
+
+- `ROARK_WEBHOOK_URL` and `ROARK_CHUNK_UPLOAD_URL_ENDPOINT` env vars are
+  required at construction time — read directly from the environment, no
+  kwarg overrides.
+- `api_key`, `agent_id` are required; `agent_name`, `agent_prompt`,
+  `pipecat_call_id`, `audio_buffer_processor` are optional.
+
+[Unreleased]: https://github.com/roarkhq/pipecat-roark/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/roarkhq/pipecat-roark/releases/tag/v0.1.0

pipecat_roark-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roark, Inc.
+
+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.

pipecat_roark-0.1.0/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: pipecat-roark
+Version: 0.1.0
+Summary: Roark analytics observer for Pipecat — capture call lifecycle, transcripts, tool calls, and recordings from any Pipecat pipeline.
+Project-URL: Homepage, https://roark.ai
+Project-URL: Documentation, https://docs.roark.ai/integrations/pipecat
+Project-URL: Repository, https://github.com/roarkhq/pipecat-roark
+Project-URL: Issues, https://github.com/roarkhq/pipecat-roark/issues
+Author-email: Roark <support@roark.ai>
+License: MIT License
+        
+        Copyright (c) 2026 Roark, Inc.
+        
+        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: analytics,observability,pipecat,roark,voice-ai
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pipecat-ai<1,>=0.0.40
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# pipecat-roark
+
+A [Roark](https://roark.ai) analytics observer for
+[Pipecat](https://github.com/pipecat-ai/pipecat). Drop one observer into your
+pipeline — Roark captures call lifecycle, transcripts, tool calls, and a
+stereo audio recording. No other code changes required.
+
+- **Tested with** `pipecat-ai` 0.0.108 (compatible with `>= 0.0.40, < 1`)
+- **Python** 3.10+
+- **Runtime-agnostic** — same code runs self-hosted *and* on Pipecat Cloud
+
+> Maintained by [Roark](https://roark.ai). File issues at
+> <https://github.com/roarkhq/pipecat-roark/issues>.
+
+---
+
+## Contents
+
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Running modes](#running-modes)
+- [Examples](#examples)
+- [Advanced](#advanced)
+  - [Bring your own `AudioBufferProcessor`](#bring-your-own-audiobufferprocessor)
+  - [Handling WebRTC disconnects](#handling-webrtc-disconnects)
+  - [Correlating with OpenTelemetry tracing](#correlating-with-opentelemetry-tracing)
+- [Troubleshooting](#troubleshooting)
+- [Configuration reference](#configuration-reference)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Quick start
+
+### 1. Install
+
+```bash
+pip install pipecat-roark
+```
+
+### 2. Configure
+
+Set one env var:
+
+```bash
+ROARK_API_KEY=rk_live_...
+```
+
+> The Roark API key is all you configure — the observer knows its own service
+> endpoints. `ROARK_API_KEY` can also be passed as `api_key=` to `RoarkObserver`.
+
+### 3. Wire the observer
+
+Drop `RoarkObserver` into your pipeline's `observers=[...]` list. Splice the
+auto-created `roark.audio_processor` **after `transport.output()`** so it sees
+the bot's audio post-TTS:
+
+```python
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.task import PipelineParams, PipelineTask
+from pipecat_roark import RoarkObserver
+
+roark = RoarkObserver(
+    api_key="rk_live_...",
+    agent_id="support-bot-v3",
+    agent_name="Support Bot v3",
+    agent_prompt=SYSTEM_PROMPT,
+)
+
+pipeline = Pipeline([
+    transport.input(), stt, context_aggregator.user(), llm, tts,
+    transport.output(),
+    roark.audio_processor,          # after transport.output() — L=user, R=bot
+    context_aggregator.assistant(),
+])
+
+task = PipelineTask(pipeline, params=PipelineParams(observers=[roark]))
+```
+
+That's it — transcripts, tool calls, and the stereo recording flow to Roark
+automatically.
+
+---
+
+## How it works
+
+The observer subscribes to Pipecat frames and ships a compact event timeline
+to Roark:
+
+| Phase | What's captured |
+|---|---|
+| **Pipeline start** | `call-started` POST + recording begins. Agent is lazy-registered on Roark the first time it sees this `agent_id`. |
+| **User turns** | Final `TranscriptionFrame`s (interim transcriptions ignored). |
+| **Assistant turns** | `TTSTextFrame` chunks aggregated between `BotStoppedSpeakingFrame` / `InterruptionFrame` boundaries. |
+| **Tool calls** | `FunctionCallInProgressFrame` + `FunctionCallResultFrame`, paired by `toolCallId`. |
+| **Audio** | Stereo PCM chunks emitted by `AudioBufferProcessor`, streamed via presigned upload URLs (`POST /v1/integrations/pipecat/chunk-upload-url`). |
+| **Pipeline end** | `EndFrame` / `CancelFrame` / `StopFrame` (or `aflush()`) flushes in-flight turns, drains uploads, and POSTs `call-ended`. Roark finalizes the recording on its side. |
+
+Transcripts and tool calls are forwarded in Pipecat's native shape — Roark
+maps them to its internal schema on its side.
+
+### Audio capture defaults
+
+The observer always creates a sane-default
+[`AudioBufferProcessor`](https://docs.pipecat.ai/server/utilities/audio/audio-recording)
+(stereo, ~256 KB chunks) exposed as `roark.audio_processor`. The sample rate
+is **adopted from the pipeline's `StartFrame`**, so it tracks whatever the
+transport/provider negotiated — 8 kHz on Twilio/Telnyx, 16/24/48 kHz on
+Daily/LiveKit, etc. The rate is forwarded to Roark as the recording sample
+rate.
+
+### Failure mode
+
+Failures are logged and swallowed — **the observer never raises into the
+pipeline**. Your call keeps running even if Roark is unreachable.
+
+---
+
+## Running modes
+
+`RoarkObserver` is **runtime-agnostic** — the same observer wiring works
+whether your Pipecat agent runs as a self-hosted process or is deployed to
+[Pipecat Cloud](https://docs.pipecat.daily.co/). Write one `bot(runner_args)`
+entry point with Pipecat's
+[`create_transport`](https://docs.pipecat.ai/server/utilities/runner) helper,
+and the same file runs in both modes — see `examples/bot.py`.
+
+| | Self-hosted | Pipecat Cloud |
+|---|---|---|
+| Entry point | `python bot.py` → `pipecat.runner.run.main()` dispatches to `bot()` | Platform invokes `bot(runner_args)` per session |
+| Room/token | You provision (Daily REST, `pipecat.runner.daily.configure`, …) | Injected via `DailyRunnerArguments` |
+| Env vars | `.env` / your secrets manager | `pcc secrets set <name> KEY=value …` |
+| Teardown | `EndFrame` is reliable | Sessions can vanish — wire [`aflush()` on disconnect](#handling-webrtc-disconnects) |
+| Observer wiring | ← identical → | ← identical → |
+
+### Self-hosted
+
+```bash
+cp .env.example .env
+# fill in ROARK_API_KEY
+uv sync --all-extras
+uv run python examples/bot.py --transport daily   # or: --transport webrtc
+```
+
+### Pipecat Cloud
+
+Set the same vars as deployment secrets, then deploy:
+
+```bash
+pcc secrets set roark-secrets \
+    ROARK_API_KEY=rk_live_...
+
+pcc deploy
+pcc agent start <agent-name>
+```
+
+Reference the secrets from your `pcc-deploy.toml` so the container sees them
+as `os.environ["ROARK_API_KEY"]` (etc.) at runtime.
+
+---
+
+## Examples
+
+Two example files ship with the package:
+
+- **`examples/basic_observer.py`** — minimal transport-agnostic wiring sketch.
+  Shows where `RoarkObserver` and `roark.audio_processor` slot into a
+  `Pipeline` / `PipelineTask`. STT / LLM / TTS stages are omitted — copy them
+  into your own pipeline.
+- **`examples/bot.py`** — runnable foundational voice assistant
+  (Deepgram STT → OpenAI LLM → Cartesia TTS) with `RoarkObserver` wired in.
+  Same file runs self-hosted (`--transport webrtc` / `--transport daily`)
+  **and** deploys to Pipecat Cloud unchanged.
+
+```bash
+cp .env.example .env
+# fill in:
+#   ROARK_API_KEY
+#   DEEPGRAM_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY
+
+uv sync --all-extras
+uv pip install "pipecat-ai[silero,deepgram,openai,cartesia,webrtc,daily]"
+
+# Local browser via Pipecat's built-in WebRTC (no third-party transport account):
+uv run python examples/bot.py --transport webrtc
+# Or Daily (see Pipecat runner docs for transport-specific setup):
+uv run python examples/bot.py --transport daily
+```
+
+---
+
+## Advanced
+
+### Bring your own `AudioBufferProcessor`
+
+If you need to tune sample rate, channel count, or buffer size, instantiate
+`AudioBufferProcessor` yourself and pass it via `audio_buffer_processor=`:
+
+```python
+from pipecat.processors.audio.audio_buffer_processor import AudioBufferProcessor
+
+audio_buffer = AudioBufferProcessor(sample_rate=16000, num_channels=1, buffer_size=128 * 1024)
+
+pipeline = Pipeline([..., transport.output(), audio_buffer, ...])
+
+RoarkObserver(
+    api_key="rk_live_...",
+    agent_id="support-bot-v3",
+    audio_buffer_processor=audio_buffer,
+)
+```
+
+### Handling WebRTC disconnects
+
+Pipecat's WebRTC transports (notably `SmallWebRTC`) sometimes tear down
+without pushing `EndFrame` through observers. Call `aflush()` from the
+disconnect handler to guarantee the call is finalized on Roark:
+
+```python
+@transport.event_handler("on_client_disconnected")
+async def _on_disconnect(_, __):
+    await roark_observer.aflush(reason="client-disconnected")
+```
+
+`aflush()` is idempotent — the regular `EndFrame` path will no-op on the next call.
+
+### Correlating with OpenTelemetry tracing
+
+If you also enable Pipecat's OpenTelemetry tracing
+(`PipelineTask(enable_tracing=True)`), generate **one** call ID up front and
+pass it to both sides — the observer's `pipecat_call_id` and `PipelineTask`'s
+`conversation_id` — so each Roark call can be looked up by the same value in
+your tracing backend:
+
+```python
+import uuid
+from pipecat.pipeline.task import PipelineParams, PipelineTask
+from pipecat_roark import RoarkObserver
+
+call_id = str(uuid.uuid4())   # or your own external ID (Twilio CallSid, DB row id, …)
+
+roark = RoarkObserver(
+    api_key="rk_live_...",
+    agent_id="support-bot-v3",
+    pipecat_call_id=call_id,   # appears on the Roark record as `pipecatCallId`
+)
+
+task = PipelineTask(
+    pipeline,
+    params=PipelineParams(observers=[roark]),
+    enable_tracing=True,
+    conversation_id=call_id,   # set as the `conversation.id` span attribute by Pipecat
+)
+```
+
+Pipecat sets `conversation.id` as a **span attribute** on a root
+`"conversation"` span (and propagates it to every child span). The OTel
+`traceId` itself is auto-generated and unrelated to your call ID; correlation
+happens by attribute value. To find the trace for a Roark call, query your
+backend by `conversation.id = <pipecatCallId>` (e.g., Honeycomb:
+`where conversation.id = "..."`, Jaeger: tag filter, Datadog:
+`@conversation.id:...`).
+
+> If you omit `pipecat_call_id`, the observer generates one internally — fine
+> for standalone use, but you won't be able to link a Roark call to its trace.
+> With OTel enabled, **always pass the same value to both**.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><strong>Do I need <code>enable_tracing=True</code> on <code>PipelineTask</code>?</strong></summary>
+
+<br>
+
+No. `RoarkObserver` captures raw frames — it does not consume OpenTelemetry
+spans. The tracing flag is unrelated. If you *do* enable it and want Roark
+calls linked to their traces, see
+[Correlating with OpenTelemetry tracing](#correlating-with-opentelemetry-tracing).
+
+</details>
+
+<details>
+<summary><strong>Calls aren't finalizing on Roark</strong></summary>
+
+<br>
+
+Some transports (notably `SmallWebRTC`) tear down without pushing `EndFrame`
+through observers. Wire `aflush()` into your disconnect handler — see
+[Handling WebRTC disconnects](#handling-webrtc-disconnects).
+
+</details>
+
+<details>
+<summary><strong>Recording captures user audio only / bot audio only</strong></summary>
+
+<br>
+
+The `AudioBufferProcessor` must sit **after `transport.output()`** so it sees
+the bot's audio post-TTS. If it's placed earlier in the pipeline, the bot
+channel will be silent.
+
+</details>
+
+<details>
+<summary><strong>Transcripts arrive empty</strong></summary>
+
+<br>
+
+The observer warns `call-ended with empty transcript ... no TranscriptionFrame
+or TTSTextFrame was observed during the call` when nothing was captured.
+Usually this means the STT service isn't emitting finalized
+`TranscriptionFrame`s, or the pipeline ended before any speech was processed.
+
+</details>
+
+---
+
+## Configuration reference
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `api_key` | `str` | — | **Required.** Roark API key. |
+| `agent_id` | `str` | — | **Required.** Customer-stable agent identifier. |
+| `agent_name` | `str \| None` | `None` | Display name. |
+| `agent_prompt` | `str \| None` | `None` | System prompt. Persisted as the agent's prompt revision. |
+| `audio_buffer_processor` | `AudioBufferProcessor \| None` | `None` | Power-user override — pass your own `AudioBufferProcessor` to control sample rate / channels / buffer size. If omitted, the observer creates a default (stereo, ~256 KB chunks; sample rate adopted from the pipeline's `StartFrame`) accessible via `observer.audio_processor`. |
+| `pipecat_call_id` | `str \| None` | random UUID | Stable call identifier. Pass the same value to `PipelineTask(conversation_id=...)` when OTel tracing is enabled — see [Correlating with OpenTelemetry tracing](#correlating-with-opentelemetry-tracing). |
+
+---
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).