pipecat-sprag 0.1.0__tar.gz → 0.2.0.dev1__tar.gz

pipecat_sprag-0.2.0.dev1/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.0.dev1
+
+### Added
+
+- `SpragSTTService(commit_on_turn_end=True)`: transcribes each turn when `SpragTurnDetector` ends it, so turn detection needs no VAD.
+- `examples/demo.py`: the voice agent behind a Sprag-branded browser client, with turns decided by Sprag's turn model.
+- `examples/turn_detection.py`: a voice agent whose turns are decided by Sprag's turn model.
+- `SpragTurnDetector`: Sprag's turn model as a processor that proposes the user's turn boundaries, for `ExternalUserTurnStrategies`, reporting `TurnMetricsData` for each turn.
+- `SpragTurnAnalyzer`: Sprag's turn model as a streaming turn analyzer.
+- `SpragAgentTextObserver`: gives either one the played words of the agent's last reply as context.
+
+### Changed
+
+- Requires `pipecat-ai` 1.12 or later.
+
+## 0.1.0
+
+### Added
+
+- `SpragSTTService`: streaming transcription with Rhythm.
+- `SpragLLMService`: Symphony, with function calling and token usage metrics.
+- `SpragTTSService`: streaming speech with Chorus.
+- `examples/voice_agent.py`: a voice agent running entirely on Sprag.

pipecat_sprag-0.2.0.dev1/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: pipecat-sprag
+Version: 0.2.0.dev1
+Summary: Sprag speech and language models for Pipecat: Rhythm STT, Symphony LLM, Chorus TTS, and turn detection
+Project-URL: Homepage, https://sprag.ai
+Project-URL: Source, https://github.com/sprag-ai/pipecat-sprag
+Project-URL: Changelog, https://github.com/sprag-ai/pipecat-sprag/blob/main/CHANGELOG.md
+Author: Sprag AI Inc.
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: ai,llm,pipecat,sprag,stt,tts,turn-detection,voice
+Requires-Python: >=3.11
+Requires-Dist: pipecat-ai<2,>=1.12
+Description-Content-Type: text/markdown
+
+# pipecat-sprag
+
+[Sprag](https://sprag.ai/) speech and language models for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+This integration is maintained by Sprag.
+
+| Service | Import | Model |
+| --- | --- | --- |
+| `SpragSTTService` | `pipecat_sprag.stt` | Rhythm (speech to text) |
+| `SpragLLMService` | `pipecat_sprag.llm` | Symphony (LLM) |
+| `SpragTTSService` | `pipecat_sprag.tts` | Chorus (text to speech) |
+| `SpragTurnDetector`, `SpragTurnAnalyzer` | `pipecat_sprag.turns` | Sprag Turns (end of turn) |
+
+## Installation
+
+```bash
+uv add pipecat-sprag
+```
+
+Each service reads your API key from the `SPRAG_API_KEY` environment variable, or takes it as `api_key=`. You can generate a key from [API keys](https://sprag.ai/app/api-keys) in the Sprag app.
+
+## Usage
+
+Each service drops into a Pipecat pipeline in place of any other STT, LLM, or TTS service:
+
+```python
+from pipecat_sprag.llm import SpragLLMService
+from pipecat_sprag.stt import SpragSTTService
+from pipecat_sprag.tts import SpragTTSService
+
+stt = SpragSTTService()
+llm = SpragLLMService()
+tts = SpragTTSService(settings=SpragTTSService.Settings(voice="wade"))
+
+pipeline = Pipeline(
+    [transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]
+)
+```
+
+- **`SpragSTTService`** streams audio to Rhythm over Sprag's streaming transcription socket (`wss://api.sprag.ai/v1/audio/transcriptions`). By default your pipeline's VAD decides when a turn ends; pass `turn_detection={"type": "server_vad"}` to let Sprag detect turns instead, or `commit_on_turn_end=True` to transcribe each turn when `SpragTurnDetector` ends it.
+- **`SpragLLMService`** runs Symphony through Sprag's chat completions API, with function calling and token usage metrics.
+- **`SpragTTSService`** streams Chorus speech over Sprag's streaming speech socket (`wss://api.sprag.ai/v1/audio/speech`), one sentence at a time. It defaults to the `chorus` model and the `wade` voice; the available voices are listed in [voice presets](https://sprag.ai/docs/tts/voices/presets).
+
+Each service takes `settings=<Service>.Settings(...)` for its model and other options, and `api_key=` if you don't use the `SPRAG_API_KEY` environment variable.
+
+## Turn detection
+
+Sprag's turn model reads the caller's audio, plus what your agent last said, and decides when the caller has finished their turn. It streams over Sprag's turns socket (`wss://api.sprag.ai/v1/turns`). You can use it in either of two ways.
+
+**`SpragTurnDetector`: the model decides the turn.** Place the detector after the transport input, and let the user aggregator follow it with Pipecat's external turn strategies. The model's `turn.started` starts the user's turn and interrupts the bot. Its `turn.ended` commits the turn's audio to Rhythm, and the turn ends once that transcript arrives. No VAD is needed:
+
+```python
+from pipecat.processors.aggregators.llm_response_universal import LLMUserAggregatorParams
+from pipecat.turns.user_start import ExternalUserTurnStartStrategy
+from pipecat.turns.user_stop import ExternalUserTurnStopStrategy
+from pipecat.turns.user_turn_strategies import UserTurnStrategies
+from pipecat_sprag.stt import SpragSTTService
+from pipecat_sprag.turns import SpragAgentTextObserver, SpragTurnDetector
+
+turns = SpragTurnDetector()
+stt = SpragSTTService(commit_on_turn_end=True)
+user_params = LLMUserAggregatorParams(
+    user_turn_strategies=UserTurnStrategies(
+        start=[ExternalUserTurnStartStrategy()],
+        stop=[ExternalUserTurnStopStrategy(timeout=0.1)],
+    )
+)
+
+pipeline = Pipeline(
+    [
+        transport.input(),
+        turns,
+        stt,
+        user_aggregator,
+        llm,
+        tts,
+        transport.output(),
+        assistant_aggregator,
+    ]
+)
+worker = PipelineWorker(pipeline, observers=[SpragAgentTextObserver(turns)])
+```
+
+The stop strategy's `timeout` is how long it waits for further transcripts after one arrives; Pipecat's default is 0.5 s.
+
+**`SpragTurnAnalyzer`: a drop-in turn analyzer.** It takes the place of `LocalSmartTurnAnalyzerV3`, alongside your VAD. Like other streaming analyzers, it reports the turn complete as soon as the model ends it. Create one analyzer for each pipeline:
+
+```python
+from pipecat.turns.user_stop import TurnAnalyzerUserTurnStopStrategy
+from pipecat_sprag.turns import SpragAgentTextObserver, SpragTurnAnalyzer
+
+analyzer = SpragTurnAnalyzer()
+stop = [TurnAnalyzerUserTurnStopStrategy(turn_analyzer=analyzer)]
+worker = PipelineWorker(pipeline, observers=[SpragAgentTextObserver(analyzer)])
+```
+
+`SpragAgentTextObserver` gives the model the words of the agent's last reply that were played, as context. Without it, the model judges the caller's audio alone. Both classes connect in the background and reconnect if the socket drops. Audio that arrives while they are not connected is not sent. Each turn the model ends is reported as a `TurnMetricsData` with the model's end-of-turn probability and the time from the VAD's last speech stop. The detector reports it when the pipeline enables metrics. Both take `params=SpragTurnParams(...)`:
+
+- `eot_threshold`: the end-of-turn probability that ends the turn. Default `0.6`.
+- `min_silence_ms`: the silence a turn needs before the model can end it. Default `200`.
+- `eot_timeout_ms`: the silence that ends the turn whatever the model scores. Default `3000`.
+
+## Example
+
+[`examples/voice_agent.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/voice_agent.py) is a complete voice agent running on Rhythm, Symphony, and Chorus. It uses Pipecat's development runner:
+
+```bash
+uv sync --group examples
+SPRAG_API_KEY=... uv run examples/voice_agent.py
+```
+
+Then open the printed URL in your browser and talk to it.
+
+[`examples/demo.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/demo.py) runs the same pipeline behind a Sprag-branded browser client that shows the live transcript, which service is working, and each service's time to first byte:
+
+```bash
+uv sync --group examples
+SPRAG_API_KEY=... uv run examples/demo.py
+```
+
+Then open http://localhost:7860.
+
+## Compatibility
+
+Requires `pipecat-ai>=1.8,<2`. Tested with Pipecat v1.12.0.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check && uv run ruff format --check
+uv run mypy src
+uv run pytest
+```
+
+Live tests call api.sprag.ai and are skipped by default: `SPRAG_API_KEY=... uv run pytest -m live`.
+
+## License
+
+BSD 2-Clause. See [LICENSE](https://github.com/sprag-ai/pipecat-sprag/blob/main/LICENSE).

pipecat_sprag-0.2.0.dev1/README.md

@@ -0,0 +1,140 @@
+# pipecat-sprag
+
+[Sprag](https://sprag.ai/) speech and language models for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+This integration is maintained by Sprag.
+
+| Service | Import | Model |
+| --- | --- | --- |
+| `SpragSTTService` | `pipecat_sprag.stt` | Rhythm (speech to text) |
+| `SpragLLMService` | `pipecat_sprag.llm` | Symphony (LLM) |
+| `SpragTTSService` | `pipecat_sprag.tts` | Chorus (text to speech) |
+| `SpragTurnDetector`, `SpragTurnAnalyzer` | `pipecat_sprag.turns` | Sprag Turns (end of turn) |
+
+## Installation
+
+```bash
+uv add pipecat-sprag
+```
+
+Each service reads your API key from the `SPRAG_API_KEY` environment variable, or takes it as `api_key=`. You can generate a key from [API keys](https://sprag.ai/app/api-keys) in the Sprag app.
+
+## Usage
+
+Each service drops into a Pipecat pipeline in place of any other STT, LLM, or TTS service:
+
+```python
+from pipecat_sprag.llm import SpragLLMService
+from pipecat_sprag.stt import SpragSTTService
+from pipecat_sprag.tts import SpragTTSService
+
+stt = SpragSTTService()
+llm = SpragLLMService()
+tts = SpragTTSService(settings=SpragTTSService.Settings(voice="wade"))
+
+pipeline = Pipeline(
+    [transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]
+)
+```
+
+- **`SpragSTTService`** streams audio to Rhythm over Sprag's streaming transcription socket (`wss://api.sprag.ai/v1/audio/transcriptions`). By default your pipeline's VAD decides when a turn ends; pass `turn_detection={"type": "server_vad"}` to let Sprag detect turns instead, or `commit_on_turn_end=True` to transcribe each turn when `SpragTurnDetector` ends it.
+- **`SpragLLMService`** runs Symphony through Sprag's chat completions API, with function calling and token usage metrics.
+- **`SpragTTSService`** streams Chorus speech over Sprag's streaming speech socket (`wss://api.sprag.ai/v1/audio/speech`), one sentence at a time. It defaults to the `chorus` model and the `wade` voice; the available voices are listed in [voice presets](https://sprag.ai/docs/tts/voices/presets).
+
+Each service takes `settings=<Service>.Settings(...)` for its model and other options, and `api_key=` if you don't use the `SPRAG_API_KEY` environment variable.
+
+## Turn detection
+
+Sprag's turn model reads the caller's audio, plus what your agent last said, and decides when the caller has finished their turn. It streams over Sprag's turns socket (`wss://api.sprag.ai/v1/turns`). You can use it in either of two ways.
+
+**`SpragTurnDetector`: the model decides the turn.** Place the detector after the transport input, and let the user aggregator follow it with Pipecat's external turn strategies. The model's `turn.started` starts the user's turn and interrupts the bot. Its `turn.ended` commits the turn's audio to Rhythm, and the turn ends once that transcript arrives. No VAD is needed:
+
+```python
+from pipecat.processors.aggregators.llm_response_universal import LLMUserAggregatorParams
+from pipecat.turns.user_start import ExternalUserTurnStartStrategy
+from pipecat.turns.user_stop import ExternalUserTurnStopStrategy
+from pipecat.turns.user_turn_strategies import UserTurnStrategies
+from pipecat_sprag.stt import SpragSTTService
+from pipecat_sprag.turns import SpragAgentTextObserver, SpragTurnDetector
+
+turns = SpragTurnDetector()
+stt = SpragSTTService(commit_on_turn_end=True)
+user_params = LLMUserAggregatorParams(
+    user_turn_strategies=UserTurnStrategies(
+        start=[ExternalUserTurnStartStrategy()],
+        stop=[ExternalUserTurnStopStrategy(timeout=0.1)],
+    )
+)
+
+pipeline = Pipeline(
+    [
+        transport.input(),
+        turns,
+        stt,
+        user_aggregator,
+        llm,
+        tts,
+        transport.output(),
+        assistant_aggregator,
+    ]
+)
+worker = PipelineWorker(pipeline, observers=[SpragAgentTextObserver(turns)])
+```
+
+The stop strategy's `timeout` is how long it waits for further transcripts after one arrives; Pipecat's default is 0.5 s.
+
+**`SpragTurnAnalyzer`: a drop-in turn analyzer.** It takes the place of `LocalSmartTurnAnalyzerV3`, alongside your VAD. Like other streaming analyzers, it reports the turn complete as soon as the model ends it. Create one analyzer for each pipeline:
+
+```python
+from pipecat.turns.user_stop import TurnAnalyzerUserTurnStopStrategy
+from pipecat_sprag.turns import SpragAgentTextObserver, SpragTurnAnalyzer
+
+analyzer = SpragTurnAnalyzer()
+stop = [TurnAnalyzerUserTurnStopStrategy(turn_analyzer=analyzer)]
+worker = PipelineWorker(pipeline, observers=[SpragAgentTextObserver(analyzer)])
+```
+
+`SpragAgentTextObserver` gives the model the words of the agent's last reply that were played, as context. Without it, the model judges the caller's audio alone. Both classes connect in the background and reconnect if the socket drops. Audio that arrives while they are not connected is not sent. Each turn the model ends is reported as a `TurnMetricsData` with the model's end-of-turn probability and the time from the VAD's last speech stop. The detector reports it when the pipeline enables metrics. Both take `params=SpragTurnParams(...)`:
+
+- `eot_threshold`: the end-of-turn probability that ends the turn. Default `0.6`.
+- `min_silence_ms`: the silence a turn needs before the model can end it. Default `200`.
+- `eot_timeout_ms`: the silence that ends the turn whatever the model scores. Default `3000`.
+
+## Example
+
+[`examples/voice_agent.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/voice_agent.py) is a complete voice agent running on Rhythm, Symphony, and Chorus. It uses Pipecat's development runner:
+
+```bash
+uv sync --group examples
+SPRAG_API_KEY=... uv run examples/voice_agent.py
+```
+
+Then open the printed URL in your browser and talk to it.
+
+[`examples/demo.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/demo.py) runs the same pipeline behind a Sprag-branded browser client that shows the live transcript, which service is working, and each service's time to first byte:
+
+```bash
+uv sync --group examples
+SPRAG_API_KEY=... uv run examples/demo.py
+```
+
+Then open http://localhost:7860.
+
+## Compatibility
+
+Requires `pipecat-ai>=1.8,<2`. Tested with Pipecat v1.12.0.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check && uv run ruff format --check
+uv run mypy src
+uv run pytest
+```
+
+Live tests call api.sprag.ai and are skipped by default: `SPRAG_API_KEY=... uv run pytest -m live`.
+
+## License
+
+BSD 2-Clause. See [LICENSE](https://github.com/sprag-ai/pipecat-sprag/blob/main/LICENSE).

{pipecat_sprag-0.1.0 → pipecat_sprag-0.2.0.dev1}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pipecat-sprag"
-version = "0.1.0"
-description = "Sprag speech and language models for Pipecat: Rhythm STT, Symphony LLM, and Chorus TTS"
+version = "0.2.0.dev1"
+description = "Sprag speech and language models for Pipecat: Rhythm STT, Symphony LLM, Chorus TTS, and turn detection"
 readme = "README.md"
 license = "BSD-2-Clause"
 requires-python = ">=3.11"
 authors = [{ name = "Sprag AI Inc." }]
-keywords = ["pipecat", "sprag", "voice", "ai", "stt", "tts", "llm"]
-dependencies = ["pipecat-ai>=1.8,<2"]
+keywords = ["pipecat", "sprag", "voice", "ai", "stt", "tts", "llm", "turn-detection"]
+dependencies = ["pipecat-ai>=1.12,<2"]
 
 [project.urls]
 Homepage = "https://sprag.ai"
@@ -26,7 +26,7 @@ include = ["src/pipecat_sprag", "README.md", "CHANGELOG.md", "LICENSE"]
 
 [dependency-groups]
 examples = [
-    "pipecat-ai[daily,runner,webrtc]>=1.8,<2",
+    "pipecat-ai[daily,runner,webrtc]>=1.12,<2",
     "python-dotenv>=1.0",
 ]
 dev = [

{pipecat_sprag-0.1.0 → pipecat_sprag-0.2.0.dev1}/src/pipecat_sprag/common/__init__.py

@@ -8,6 +8,8 @@ __version__ = version("pipecat-sprag")
 SPRAG_BASE_URL = "https://api.sprag.ai/v1"
 SPRAG_TRANSCRIPTION_URL = "wss://api.sprag.ai/v1/audio/transcriptions"
 SPRAG_SPEECH_URL = "wss://api.sprag.ai/v1/audio/speech"
+SPRAG_TURNS_URL = "wss://api.sprag.ai/v1/turns"
+SPRAG_TURNS_MODEL = "sprag-turns"
 ATTRIBUTION_HEADERS = {"X-Sprag-Integration": f"pipecat/{__version__}"}
 
 

{pipecat_sprag-0.1.0 → pipecat_sprag-0.2.0.dev1}/src/pipecat_sprag/stt/service.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Literal
 
+from pipecat.frames.frames import Frame, ProposedUserStoppedSpeakingFrame
+from pipecat.processors.frame_processor import FrameDirection
 from pipecat.services.openai.stt import OpenAIRealtimeSTTService, OpenAIRealtimeSTTSettings
 
 from pipecat_sprag.common import SPRAG_TRANSCRIPTION_URL, resolve_api_key
@@ -19,7 +21,9 @@ class SpragSTTService(OpenAIRealtimeSTTService):
     """Streaming transcription with Rhythm over Sprag's streaming transcription socket.
 
     By default the pipeline's own VAD decides when a turn ends. Pass
-    ``turn_detection={"type": "server_vad"}`` to have Sprag detect turns instead.
+    ``turn_detection={"type": "server_vad"}`` to have Sprag detect turns instead, or
+    ``commit_on_turn_end=True`` to transcribe each turn when a turn model such as
+    ``SpragTurnDetector`` proposes its end.
 
     Unlike the LLM and TTS services, it sends no ``X-Sprag-Integration`` header: Pipecat's
     realtime STT connects with a fixed set of headers.
@@ -34,6 +38,7 @@ class SpragSTTService(OpenAIRealtimeSTTService):
         api_key: str | None = None,
         base_url: str = SPRAG_TRANSCRIPTION_URL,
         turn_detection: dict[str, Any] | Literal[False] | None = False,
+        commit_on_turn_end: bool = False,
         settings: SpragSTTSettings | None = None,
         **kwargs: Any,
     ) -> None:
@@ -46,6 +51,8 @@ class SpragSTTService(OpenAIRealtimeSTTService):
             turn_detection: ``False`` (the default) leaves turn detection to the
                 pipeline's VAD. A dict such as ``{"type": "server_vad"}`` enables
                 Sprag's server-side VAD.
+            commit_on_turn_end: Whether a ``ProposedUserStoppedSpeakingFrame`` commits the
+                audio for transcription. Applies only without server-side VAD.
             settings: Runtime-updatable settings. The model defaults to ``rhythm``.
             **kwargs: Additional arguments passed to OpenAIRealtimeSTTService.
         """
@@ -60,3 +67,19 @@ class SpragSTTService(OpenAIRealtimeSTTService):
             settings=default_settings,
             **kwargs,
         )
+        self._commit_on_turn_end = commit_on_turn_end
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
+        """Process a frame, committing the audio when a proposed turn end arrives.
+
+        Args:
+            frame: The frame to process.
+            direction: The frame's direction.
+        """
+        await super().process_frame(frame, direction)
+        if (
+            self._commit_on_turn_end
+            and not self._server_vad_enabled
+            and isinstance(frame, ProposedUserStoppedSpeakingFrame)
+        ):
+            await self._commit_audio_buffer()

pipecat_sprag-0.2.0.dev1/src/pipecat_sprag/turns/__init__.py

@@ -0,0 +1,8 @@
+"""Sprag's turn model for Pipecat: a turn detector, a turn analyzer, and an agent-text observer."""
+
+from pipecat_sprag.turns.analyzer import SpragTurnAnalyzer
+from pipecat_sprag.turns.context import SpragAgentTextObserver
+from pipecat_sprag.turns.detector import SpragTurnDetector
+from pipecat_sprag.turns.session import SpragTurnParams
+
+__all__ = ["SpragAgentTextObserver", "SpragTurnAnalyzer", "SpragTurnDetector", "SpragTurnParams"]

pipecat_sprag-0.2.0.dev1/src/pipecat_sprag/turns/analyzer.py

@@ -0,0 +1,159 @@
+"""Sprag's turn model as a Pipecat turn analyzer."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from loguru import logger
+from pipecat.audio.turn.base_turn_analyzer import BaseTurnAnalyzer, EndOfTurnState
+from pipecat.metrics.metrics import MetricsData, TurnMetricsData
+
+from pipecat_sprag.common import SPRAG_TURNS_MODEL, SPRAG_TURNS_URL, resolve_api_key
+from pipecat_sprag.turns.session import SpragTurnParams, TurnsSession, error_message
+
+
+class SpragTurnAnalyzer(BaseTurnAnalyzer):
+    """Streams the caller's audio to Sprag's turn model; the turn is complete on its ``turn.ended``.
+
+    Pass it as ``TurnAnalyzerUserTurnStopStrategy(turn_analyzer=...)``, one analyzer per
+    pipeline. It is a streaming analyzer: ``append_audio`` returns ``COMPLETE`` once the model
+    has ended the turn, and ``analyze_end_of_turn`` keeps reporting ``COMPLETE`` until the turn
+    is cleared or the model opens a new one. The analyzer sees no agent text of its own; call
+    ``set_agent_text`` with what the agent last said, for example from
+    ``SpragAgentTextObserver``.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        url: str = SPRAG_TURNS_URL,
+        model: str = SPRAG_TURNS_MODEL,
+        params: SpragTurnParams | None = None,
+        connect_timeout: float = 10.0,
+        sample_rate: int | None = None,
+    ) -> None:
+        """Initialize the analyzer.
+
+        Args:
+            api_key: Your Sprag API key. Defaults to the ``SPRAG_API_KEY`` environment variable.
+            url: The Sprag turns WebSocket URL.
+            model: The turn model.
+            params: The model's thresholds. Defaults to ``SpragTurnParams()``.
+            connect_timeout: Seconds the session may take to open, and again to be configured.
+            sample_rate: The input sample rate; defaults to the pipeline's.
+        """
+        super().__init__(sample_rate=sample_rate)
+        self._params = params or SpragTurnParams()
+        self._session = TurnsSession(
+            api_key=resolve_api_key(api_key),
+            url=url,
+            model=model,
+            params=self._params,
+            on_event=self._on_event,
+            connect_timeout=connect_timeout,
+        )
+        self._connection: asyncio.Task[None] | None = None
+        self._speech_triggered = False
+        self._turn_ended = False
+        self._turn_reported = False
+        self._last_metrics: TurnMetricsData | None = None
+        self._speech_stopped_at: float | None = None
+
+    @property
+    def speech_triggered(self) -> bool:
+        """Whether the model has opened a turn that has not ended yet."""
+        return self._speech_triggered
+
+    @property
+    def params(self) -> SpragTurnParams:
+        """The model's thresholds."""
+        return self._params
+
+    async def set_agent_text(self, text: str) -> None:
+        """Set what the agent last said, which the model reads as context for later readings.
+
+        Args:
+            text: The agent's last utterance; empty clears it.
+        """
+        await self._session.send_agent_text(text)
+
+    def append_audio(self, buffer: bytes, is_speech: bool) -> EndOfTurnState:
+        """Queue caller audio for the model and report whether it has ended the turn.
+
+        Args:
+            buffer: Mono PCM16 audio at the analyzer's sample rate.
+            is_speech: Whether the pipeline's VAD marks the audio as speech.
+
+        Returns:
+            ``COMPLETE`` once after the model ends a turn, otherwise ``INCOMPLETE``.
+        """
+        if self._connection is None:
+            self._connection = asyncio.get_running_loop().create_task(
+                self._session.maintain(self._report_error)
+            )
+        if is_speech:
+            self._speech_stopped_at = None
+        elif self._speech_stopped_at is None:
+            self._speech_stopped_at = time.perf_counter()
+        self._session.push_audio(buffer, self.sample_rate)
+        if self._turn_ended and not self._turn_reported:
+            self._turn_reported = True
+            return EndOfTurnState.COMPLETE
+        return EndOfTurnState.INCOMPLETE
+
+    async def analyze_end_of_turn(self) -> tuple[EndOfTurnState, MetricsData | None]:
+        """Report whether the model has ended the turn, with its ending reading's metrics.
+
+        Returns:
+            ``COMPLETE`` from the model's ``turn.ended`` until ``clear`` or its next
+            ``turn.started``, and the ending reading's metrics on the first call that reports it.
+        """
+        state = EndOfTurnState.COMPLETE if self._turn_ended else EndOfTurnState.INCOMPLETE
+        metrics, self._last_metrics = self._last_metrics, None
+        return state, metrics
+
+    def clear(self) -> None:
+        """Forget the current turn's state; the session stays open."""
+        self._speech_triggered = False
+        self._turn_ended = False
+        self._turn_reported = False
+        self._last_metrics = None
+        self._speech_stopped_at = None
+
+    async def cleanup(self) -> None:
+        """Close the session; the next ``append_audio`` opens a new one."""
+        connection, self._connection = self._connection, None
+        if connection is not None:
+            connection.cancel()
+            await asyncio.gather(connection, return_exceptions=True)
+        await self._session.close()
+        self.clear()
+
+    async def _report_error(self, error: Exception) -> None:
+        logger.error(f"Error connecting to Sprag turns: {error}")
+
+    async def _on_event(self, event: dict[str, Any]) -> None:
+        event_type = event.get("type")
+        if event_type == "turn.started":
+            stopped = self._speech_stopped_at
+            self.clear()
+            self._speech_stopped_at = stopped
+            self._speech_triggered = True
+        elif event_type == "turn.ended":
+            self._speech_triggered = False
+            self._turn_ended = True
+            self._turn_reported = False
+            stopped = self._speech_stopped_at
+            self._last_metrics = TurnMetricsData(
+                processor="SpragTurnAnalyzer",
+                is_complete=True,
+                probability=float(event.get("p_eot") or 0.0),
+                e2e_processing_time_ms=(time.perf_counter() - stopped) * 1000
+                if stopped is not None
+                else 0.0,
+            )
+        elif event_type == "error":
+            logger.error(f"Sprag turns error: {error_message(event)}")

pipecat_sprag-0.2.0.dev1/src/pipecat_sprag/turns/context.py

@@ -0,0 +1,50 @@
+"""An observer that hands the agent's last utterance to a Sprag turn detector or analyzer."""
+
+from __future__ import annotations
+
+from pipecat.frames.frames import BotStartedSpeakingFrame, BotStoppedSpeakingFrame, TTSTextFrame
+from pipecat.observers.base_observer import BaseObserver, FramePushed
+from pipecat.processors.frame_processor import FrameDirection
+from pipecat.transports.base_output import BaseOutputTransport
+
+from pipecat_sprag.turns.analyzer import SpragTurnAnalyzer
+from pipecat_sprag.turns.detector import SpragTurnDetector
+
+
+class SpragAgentTextObserver(BaseObserver):
+    """Sets the text the bot spoke as the turn model's context each time the bot stops speaking.
+
+    Pass it to the pipeline worker's ``observers``. Text is collected as the output transport
+    plays it, so an interrupted reply sets only the words that were played, and a reply with
+    no text clears the context.
+    """
+
+    def __init__(self, target: SpragTurnDetector | SpragTurnAnalyzer) -> None:
+        """Initialize the observer.
+
+        Args:
+            target: The detector or analyzer whose context this observer keeps current.
+        """
+        super().__init__()
+        self._target = target
+        self._spoken: list[str] = []
+
+    async def on_push_frame(self, data: FramePushed) -> None:
+        """Track the text the output transport plays across one reply.
+
+        Args:
+            data: The pushed frame and its route.
+        """
+        if data.direction is not FrameDirection.DOWNSTREAM:
+            return
+        if not isinstance(data.source, BaseOutputTransport):
+            return
+        frame = data.frame
+        if isinstance(frame, BotStartedSpeakingFrame):
+            self._spoken = []
+        elif isinstance(frame, TTSTextFrame):
+            self._spoken.append(frame.text)
+        elif isinstance(frame, BotStoppedSpeakingFrame):
+            text = " ".join(part.strip() for part in self._spoken if part.strip())
+            self._spoken = []
+            await self._target.set_agent_text(text)

pipecat_sprag-0.2.0.dev1/src/pipecat_sprag/turns/detector.py

@@ -0,0 +1,160 @@
+"""Sprag's turn model as a Pipecat processor that proposes the user's turn boundaries."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import numpy as np
+from pipecat.frames.frames import (
+    CancelFrame,
+    EndFrame,
+    Frame,
+    InputAudioRawFrame,
+    MetricsFrame,
+    ProposedUserStartedSpeakingFrame,
+    ProposedUserStoppedSpeakingFrame,
+    StartFrame,
+    VADUserStartedSpeakingFrame,
+    VADUserStoppedSpeakingFrame,
+)
+from pipecat.metrics.metrics import TurnMetricsData
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
+
+from pipecat_sprag.common import SPRAG_TURNS_MODEL, SPRAG_TURNS_URL, resolve_api_key
+from pipecat_sprag.turns.session import SpragTurnParams, TurnsSession, error_message
+
+
+class SpragTurnDetector(FrameProcessor):
+    """Streams caller audio to Sprag's turn model and proposes the user's turn boundaries.
+
+    Place it after the transport input and use Pipecat's ``ExternalUserTurnStrategies``: the
+    model's ``turn.started`` becomes a ``ProposedUserStartedSpeakingFrame`` and its
+    ``turn.ended`` a ``ProposedUserStoppedSpeakingFrame``, which the user aggregator closes on
+    once the STT's transcript arrives. Every frame passes through unchanged, and the
+    connection runs in the background so audio is never held back while it opens. Its
+    ``on_turn_update`` event receives each end-of-turn reading and its ``on_turn_ended`` event
+    each closed turn. With metrics enabled, it pushes a ``TurnMetricsData`` for each closed turn.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        url: str = SPRAG_TURNS_URL,
+        model: str = SPRAG_TURNS_MODEL,
+        params: SpragTurnParams | None = None,
+        connect_timeout: float = 10.0,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the detector.
+
+        Args:
+            api_key: Your Sprag API key. Defaults to the ``SPRAG_API_KEY`` environment variable.
+            url: The Sprag turns WebSocket URL.
+            model: The turn model.
+            params: The model's thresholds. Defaults to ``SpragTurnParams()``.
+            connect_timeout: Seconds the session may take to open, and again to be configured.
+            **kwargs: Additional arguments passed to FrameProcessor.
+        """
+        super().__init__(**kwargs)
+        self._session = TurnsSession(
+            api_key=resolve_api_key(api_key),
+            url=url,
+            model=model,
+            params=params or SpragTurnParams(),
+            on_event=self._on_event,
+            connect_timeout=connect_timeout,
+        )
+        self._connection: asyncio.Task[None] | None = None
+        self._model = model
+        self._speech_stopped_at: float | None = None
+        self._register_event_handler("on_turn_update")
+        self._register_event_handler("on_turn_ended")
+
+    async def set_agent_text(self, text: str) -> None:
+        """Set what the agent last said, which the model reads as context for later readings.
+
+        Args:
+            text: The agent's last utterance; empty clears it.
+        """
+        await self._session.send_agent_text(text)
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
+        """Stream input audio to the model and pass every frame on.
+
+        Args:
+            frame: The frame to process.
+            direction: The frame's direction.
+        """
+        await super().process_frame(frame, direction)
+        if isinstance(frame, StartFrame):
+            await self.push_frame(frame, direction)
+            if self._connection is None:
+                self._connection = self.create_task(self._session.maintain(self._report_error))
+            return
+        if isinstance(frame, (EndFrame, CancelFrame)):
+            await self._stop()
+        elif isinstance(frame, InputAudioRawFrame):
+            self._session.push_audio(_mono(frame), frame.sample_rate)
+        elif isinstance(frame, VADUserStartedSpeakingFrame):
+            self._speech_stopped_at = None
+        elif isinstance(frame, VADUserStoppedSpeakingFrame):
+            self._speech_stopped_at = time.perf_counter()
+        await self.push_frame(frame, direction)
+
+    async def cleanup(self) -> None:
+        """Close the session."""
+        await super().cleanup()
+        await self._stop()
+
+    async def _stop(self) -> None:
+        if self._connection is not None:
+            await self.cancel_task(self._connection)
+            self._connection = None
+        await self._session.close()
+
+    def can_generate_metrics(self) -> bool:
+        """Report that the detector produces turn metrics."""
+        return True
+
+    async def _push_turn_metrics(self, event: dict[str, Any]) -> None:
+        stopped, self._speech_stopped_at = self._speech_stopped_at, None
+        if not self.metrics_enabled:
+            return
+        metrics = TurnMetricsData(
+            processor=self.name,
+            model=self._model,
+            is_complete=True,
+            probability=float(event.get("p_eot") or 0.0),
+            e2e_processing_time_ms=(time.perf_counter() - stopped) * 1000
+            if stopped is not None
+            else 0.0,
+        )
+        await self.push_frame(MetricsFrame(data=[metrics]))
+
+    async def _report_error(self, error: Exception) -> None:
+        await self.push_error(
+            error_msg=f"Error connecting to Sprag turns: {error}", exception=error
+        )
+
+    async def _on_event(self, event: dict[str, Any]) -> None:
+        event_type = event.get("type")
+        if event_type == "turn.started":
+            await self.broadcast_frame(ProposedUserStartedSpeakingFrame)
+        elif event_type == "turn.update":
+            await self._call_event_handler("on_turn_update", event)
+        elif event_type == "turn.ended":
+            await self.broadcast_frame(ProposedUserStoppedSpeakingFrame)
+            await self._push_turn_metrics(event)
+            await self._call_event_handler("on_turn_ended", event)
+        elif event_type == "error":
+            await self.push_error(error_msg=f"Sprag turns error: {error_message(event)}")
+
+
+def _mono(frame: InputAudioRawFrame) -> bytes:
+    if frame.num_channels == 1:
+        return frame.audio
+    samples = np.frombuffer(frame.audio, dtype=np.int16).reshape(-1, frame.num_channels)
+    return bytes(samples.mean(axis=1).astype(np.int16).tobytes())

pipecat_sprag-0.2.0.dev1/src/pipecat_sprag/turns/session.py

@@ -0,0 +1,279 @@
+"""A client for Sprag's ``/v1/turns`` socket, shared by the turn detector and the turn analyzer."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlsplit, urlunsplit
+
+from loguru import logger
+from pipecat.audio.turn.base_turn_analyzer import BaseTurnParams
+from pipecat.audio.utils import create_stream_resampler
+from pydantic import Field
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed
+
+from pipecat_sprag.common import ATTRIBUTION_HEADERS
+
+SAMPLE_RATE = 16000
+RECONNECT_INTERVAL_SECS = 2.0
+MAX_RECONNECT_INTERVAL_SECS = 30.0
+AUDIO_QUEUE_FRAMES = 25
+MAX_MESSAGE_BYTES = 2**16
+CLOSE_TIMEOUT_SECS = 2.0
+
+EventHandler = Callable[[dict[str, Any]], Awaitable[None]]
+ErrorHandler = Callable[[Exception], Awaitable[None]]
+
+
+class SpragTurnParams(BaseTurnParams):
+    """Thresholds the Sprag turn model applies to its readings."""
+
+    eot_threshold: float = Field(
+        default=0.6, ge=0.0, le=1.0, description="end-of-turn probability that ends the turn"
+    )
+    min_silence_ms: int = Field(
+        default=200, ge=0, description="silence the turn needs before the model can end it"
+    )
+    eot_timeout_ms: int = Field(
+        default=3000,
+        ge=100,
+        le=60000,
+        description="silence that ends the turn whatever the model scores",
+    )
+
+
+class TurnsSession:
+    """One ``/v1/turns`` session: streams caller audio and agent context, and reports turn events.
+
+    Audio of any sample rate is resampled to the 16 kHz PCM16 the socket reads. Events reach
+    ``on_event`` in the order the server sends them. The agent text is kept across reconnects
+    and sent again on every new connection.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        url: str,
+        model: str,
+        params: SpragTurnParams,
+        on_event: EventHandler,
+        connect_timeout: float = 10.0,
+    ) -> None:
+        """Prepare a session; nothing is opened until ``connect`` or ``maintain``.
+
+        Args:
+            api_key: The Sprag API key.
+            url: The ``/v1/turns`` WebSocket URL.
+            model: The turn model to open the session on, unless ``url`` already names one.
+            params: The thresholds sent as the session's configuration.
+            on_event: Called with every server event after the session is configured.
+            connect_timeout: Seconds the socket may take to open, and again to be configured.
+        """
+        self._api_key = api_key
+        self._url = url
+        self._model = model
+        self._params = params
+        self._on_event = on_event
+        self._connect_timeout = connect_timeout
+        self._websocket: ClientConnection | None = None
+        self._tasks: list[asyncio.Task[None]] = []
+        self._closing: asyncio.Task[None] | None = None
+        self._audio: asyncio.Queue[tuple[bytes, int]] = asyncio.Queue(maxsize=AUDIO_QUEUE_FRAMES)
+        self._lost = asyncio.Event()
+        self._agent_text = ""
+        self._resampler = create_stream_resampler()
+
+    @property
+    def connected(self) -> bool:
+        """Whether the session is open and configured."""
+        return self._websocket is not None
+
+    async def maintain(self, on_error: ErrorHandler) -> None:
+        """Keep the session connected until the calling task is cancelled.
+
+        A failed attempt goes to ``on_error`` and is retried after a delay that starts at
+        ``RECONNECT_INTERVAL_SECS`` and doubles up to ``MAX_RECONNECT_INTERVAL_SECS``.
+
+        Args:
+            on_error: Called with the error of each failed connection attempt.
+        """
+        delay = RECONNECT_INTERVAL_SECS
+        while True:
+            try:
+                await self.connect()
+            except Exception as e:
+                await on_error(e)
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, MAX_RECONNECT_INTERVAL_SECS)
+                continue
+            delay = RECONNECT_INTERVAL_SECS
+            await self._lost.wait()
+
+    async def connect(self) -> None:
+        """Open the socket, apply the session's thresholds and send the agent text.
+
+        Raises:
+            RuntimeError: The server refused the configuration.
+            ConnectionError: The socket closed before the session was configured.
+            TimeoutError: The session took longer than ``connect_timeout`` to configure.
+        """
+        if self._websocket is not None:
+            return
+        websocket = await connect(
+            self._session_url(),
+            additional_headers={"Authorization": f"Bearer {self._api_key}", **ATTRIBUTION_HEADERS},
+            open_timeout=self._connect_timeout,
+            close_timeout=CLOSE_TIMEOUT_SECS,
+            max_size=MAX_MESSAGE_BYTES,
+        )
+        try:
+            await asyncio.wait_for(self._configure(websocket), timeout=self._connect_timeout)
+            if self._agent_text:
+                await websocket.send(_context_update(self._agent_text))
+        except BaseException:
+            await websocket.close()
+            raise
+        while not self._audio.empty():
+            self._audio.get_nowait()
+        self._resampler = create_stream_resampler()
+        self._websocket = websocket
+        self._lost.clear()
+        self._tasks = [
+            asyncio.create_task(self._receive(websocket)),
+            asyncio.create_task(self._send_audio(websocket)),
+        ]
+
+    def push_audio(self, audio: bytes, sample_rate: int) -> None:
+        """Queue caller audio for the socket without waiting on it.
+
+        Audio is dropped while the session is not connected, and the oldest queued audio is
+        dropped once ``AUDIO_QUEUE_FRAMES`` buffers are waiting.
+
+        Args:
+            audio: Mono PCM16 little-endian samples.
+            sample_rate: The audio's sample rate in hertz.
+        """
+        if self._websocket is None:
+            return
+        if self._audio.full():
+            self._audio.get_nowait()
+        self._audio.put_nowait((audio, sample_rate))
+
+    async def send_agent_text(self, text: str) -> None:
+        """Set what the agent last said, which every later reading takes as context.
+
+        Args:
+            text: The agent's last utterance; empty clears the context.
+        """
+        self._agent_text = text
+        websocket = self._websocket
+        if websocket is None:
+            return
+        try:
+            await websocket.send(_context_update(text))
+        except ConnectionClosed:
+            self._drop(websocket)
+
+    async def close(self) -> None:
+        """End the session and close the socket; a later ``connect`` opens a new one."""
+        websocket, self._websocket = self._websocket, None
+        tasks, self._tasks = self._tasks, []
+        current = asyncio.current_task()
+        others = [task for task in tasks if task is not current]
+        for task in others:
+            task.cancel()
+        await asyncio.gather(*others, return_exceptions=True)
+        if websocket is not None:
+            try:
+                await websocket.send(json.dumps({"type": "session.close"}))
+            except ConnectionClosed:
+                pass
+            await websocket.close()
+
+    def _session_url(self) -> str:
+        parts = urlsplit(self._url)
+        if parts.scheme == "ws" and parts.hostname not in ("localhost", "127.0.0.1", "::1"):
+            logger.warning("The Sprag turns URL is not encrypted; the API key is sent in plaintext")
+        if "model" in parse_qs(parts.query):
+            return self._url
+        query = "&".join(q for q in (parts.query, urlencode({"model": self._model})) if q)
+        return urlunsplit(parts._replace(query=query))
+
+    async def _configure(self, websocket: ClientConnection) -> None:
+        await websocket.send(
+            json.dumps({"type": "session.update", "session": self._params.model_dump()})
+        )
+        async for message in websocket:
+            if not isinstance(message, str):
+                continue
+            event = json.loads(message)
+            if event.get("type") == "session.updated":
+                return
+            if event.get("type") == "error":
+                raise RuntimeError(error_message(event))
+        raise ConnectionError("the turns session closed before it was configured")
+
+    async def _receive(self, websocket: ClientConnection) -> None:
+        try:
+            async for message in websocket:
+                if not isinstance(message, str):
+                    continue
+                try:
+                    event = json.loads(message)
+                    if isinstance(event, dict):
+                        await self._on_event(event)
+                except Exception:
+                    logger.exception("Error handling a Sprag turns event")
+        except ConnectionClosed:
+            pass
+        finally:
+            self._drop(websocket)
+
+    async def _send_audio(self, websocket: ClientConnection) -> None:
+        try:
+            while True:
+                audio, sample_rate = await self._audio.get()
+                if sample_rate != SAMPLE_RATE:
+                    audio = await self._resampler.resample(audio, sample_rate, SAMPLE_RATE)
+                if audio:
+                    await websocket.send(audio)
+        except ConnectionClosed:
+            pass
+        except Exception:
+            logger.exception("Error streaming audio to Sprag turns")
+        finally:
+            self._drop(websocket)
+
+    def _drop(self, websocket: ClientConnection) -> None:
+        if self._websocket is not websocket:
+            return
+        logger.warning("Sprag turns session lost")
+        self._websocket = None
+        current = asyncio.current_task()
+        for task in self._tasks:
+            if task is not current:
+                task.cancel()
+        self._tasks = []
+        self._closing = asyncio.create_task(websocket.close())
+        self._lost.set()
+
+
+def error_message(event: dict[str, Any]) -> str:
+    """Describe a server ``error`` event.
+
+    Args:
+        event: The server's ``error`` event.
+
+    Returns:
+        The error's message, else its code, else a generic description.
+    """
+    error = event.get("error") or {}
+    return str(error.get("message") or error.get("code") or "the turns session reported an error")
+
+
+def _context_update(text: str) -> str:
+    return json.dumps({"type": "context.update", "agent_text": text})

pipecat_sprag-0.1.0/CHANGELOG.md

@@ -1,10 +0,0 @@
-# Changelog
-
-## 0.1.0
-
-### Added
-
-- `SpragSTTService`: streaming transcription with Rhythm.
-- `SpragLLMService`: Symphony, with function calling and token usage metrics.
-- `SpragTTSService`: streaming speech with Chorus.
-- `examples/voice_agent.py`: a voice agent running entirely on Sprag.

pipecat_sprag-0.1.0/PKG-INFO

@@ -1,88 +0,0 @@
-Metadata-Version: 2.5
-Name: pipecat-sprag
-Version: 0.1.0
-Summary: Sprag speech and language models for Pipecat: Rhythm STT, Symphony LLM, and Chorus TTS
-Project-URL: Homepage, https://sprag.ai
-Project-URL: Source, https://github.com/sprag-ai/pipecat-sprag
-Project-URL: Changelog, https://github.com/sprag-ai/pipecat-sprag/blob/main/CHANGELOG.md
-Author: Sprag AI Inc.
-License-Expression: BSD-2-Clause
-License-File: LICENSE
-Keywords: ai,llm,pipecat,sprag,stt,tts,voice
-Requires-Python: >=3.11
-Requires-Dist: pipecat-ai<2,>=1.8
-Description-Content-Type: text/markdown
-
-# pipecat-sprag
-
-[Sprag](https://sprag.ai/) speech and language models for [Pipecat](https://github.com/pipecat-ai/pipecat).
-
-This integration is maintained by Sprag.
-
-| Service | Import | Model |
-| --- | --- | --- |
-| `SpragSTTService` | `pipecat_sprag.stt` | Rhythm (speech to text) |
-| `SpragLLMService` | `pipecat_sprag.llm` | Symphony (LLM) |
-| `SpragTTSService` | `pipecat_sprag.tts` | Chorus (text to speech) |
-
-## Installation
-
-```bash
-uv add pipecat-sprag
-```
-
-Each service reads your API key from the `SPRAG_API_KEY` environment variable, or takes it as `api_key=`. You can generate a key from [API keys](https://sprag.ai/app/api-keys) in the Sprag app.
-
-## Usage
-
-Each service drops into a Pipecat pipeline in place of any other STT, LLM, or TTS service:
-
-```python
-from pipecat_sprag.llm import SpragLLMService
-from pipecat_sprag.stt import SpragSTTService
-from pipecat_sprag.tts import SpragTTSService
-
-stt = SpragSTTService()
-llm = SpragLLMService()
-tts = SpragTTSService(settings=SpragTTSService.Settings(voice="wade"))
-
-pipeline = Pipeline(
-    [transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]
-)
-```
-
-- **`SpragSTTService`** streams audio to Rhythm over Sprag's streaming transcription socket (`wss://api.sprag.ai/v1/audio/transcriptions`). By default your pipeline's VAD decides when a turn ends; pass `turn_detection={"type": "server_vad"}` to let Sprag detect turns instead.
-- **`SpragLLMService`** runs Symphony through Sprag's chat completions API, with function calling and token usage metrics.
-- **`SpragTTSService`** streams Chorus speech over Sprag's streaming speech socket (`wss://api.sprag.ai/v1/audio/speech`), one sentence at a time. It defaults to the `chorus` model and the `wade` voice; the available voices are listed in [voice presets](https://sprag.ai/docs/tts/voices/presets).
-
-Each service takes `settings=<Service>.Settings(...)` for its model and other options, and `api_key=` if you don't use the `SPRAG_API_KEY` environment variable.
-
-## Example
-
-[`examples/voice_agent.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/voice_agent.py) is a complete voice agent running on Rhythm, Symphony, and Chorus. It uses Pipecat's development runner:
-
-```bash
-uv sync --group examples
-SPRAG_API_KEY=... uv run examples/voice_agent.py
-```
-
-Then open the printed URL in your browser and talk to it.
-
-## Compatibility
-
-Requires `pipecat-ai>=1.8,<2`. Tested with Pipecat v1.12.0.
-
-## Development
-
-```bash
-uv sync
-uv run ruff check && uv run ruff format --check
-uv run mypy src
-uv run pytest
-```
-
-Live tests call api.sprag.ai and are skipped by default: `SPRAG_API_KEY=... uv run pytest -m live`.
-
-## License
-
-BSD 2-Clause. See [LICENSE](https://github.com/sprag-ai/pipecat-sprag/blob/main/LICENSE).

pipecat_sprag-0.1.0/README.md

@@ -1,73 +0,0 @@
-# pipecat-sprag
-
-[Sprag](https://sprag.ai/) speech and language models for [Pipecat](https://github.com/pipecat-ai/pipecat).
-
-This integration is maintained by Sprag.
-
-| Service | Import | Model |
-| --- | --- | --- |
-| `SpragSTTService` | `pipecat_sprag.stt` | Rhythm (speech to text) |
-| `SpragLLMService` | `pipecat_sprag.llm` | Symphony (LLM) |
-| `SpragTTSService` | `pipecat_sprag.tts` | Chorus (text to speech) |
-
-## Installation
-
-```bash
-uv add pipecat-sprag
-```
-
-Each service reads your API key from the `SPRAG_API_KEY` environment variable, or takes it as `api_key=`. You can generate a key from [API keys](https://sprag.ai/app/api-keys) in the Sprag app.
-
-## Usage
-
-Each service drops into a Pipecat pipeline in place of any other STT, LLM, or TTS service:
-
-```python
-from pipecat_sprag.llm import SpragLLMService
-from pipecat_sprag.stt import SpragSTTService
-from pipecat_sprag.tts import SpragTTSService
-
-stt = SpragSTTService()
-llm = SpragLLMService()
-tts = SpragTTSService(settings=SpragTTSService.Settings(voice="wade"))
-
-pipeline = Pipeline(
-    [transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]
-)
-```
-
-- **`SpragSTTService`** streams audio to Rhythm over Sprag's streaming transcription socket (`wss://api.sprag.ai/v1/audio/transcriptions`). By default your pipeline's VAD decides when a turn ends; pass `turn_detection={"type": "server_vad"}` to let Sprag detect turns instead.
-- **`SpragLLMService`** runs Symphony through Sprag's chat completions API, with function calling and token usage metrics.
-- **`SpragTTSService`** streams Chorus speech over Sprag's streaming speech socket (`wss://api.sprag.ai/v1/audio/speech`), one sentence at a time. It defaults to the `chorus` model and the `wade` voice; the available voices are listed in [voice presets](https://sprag.ai/docs/tts/voices/presets).
-
-Each service takes `settings=<Service>.Settings(...)` for its model and other options, and `api_key=` if you don't use the `SPRAG_API_KEY` environment variable.
-
-## Example
-
-[`examples/voice_agent.py`](https://github.com/sprag-ai/pipecat-sprag/blob/main/examples/voice_agent.py) is a complete voice agent running on Rhythm, Symphony, and Chorus. It uses Pipecat's development runner:
-
-```bash
-uv sync --group examples
-SPRAG_API_KEY=... uv run examples/voice_agent.py
-```
-
-Then open the printed URL in your browser and talk to it.
-
-## Compatibility
-
-Requires `pipecat-ai>=1.8,<2`. Tested with Pipecat v1.12.0.
-
-## Development
-
-```bash
-uv sync
-uv run ruff check && uv run ruff format --check
-uv run mypy src
-uv run pytest
-```
-
-Live tests call api.sprag.ai and are skipped by default: `SPRAG_API_KEY=... uv run pytest -m live`.
-
-## License
-
-BSD 2-Clause. See [LICENSE](https://github.com/sprag-ai/pipecat-sprag/blob/main/LICENSE).