Metadata-Version: 2.5
Name: pipecat-oogam
Version: 0.2.1
Summary: Oogam speech services for Pipecat — streaming STT with client-driven turn finalize, streaming TTS, and Sutra — for 27 Indian languages and English.
Project-URL: Homepage, https://oogam.ai/integrations/pipecat
Project-URL: Documentation, https://oogam.ai/docs/streaming-stt
Author-email: Dwet Labs <support@dwetlabs.com>
License: MIT
License-File: LICENSE
Keywords: indian-languages,naad,oogam,pipecat,stt,sutra,tts,voice-agent
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: numpy>=1.26
Requires-Dist: pipecat-ai<2,>=1.16
Requires-Dist: websockets>=13
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# pipecat-oogam

Oogam speech services for [Pipecat](https://github.com/pipecat-ai/pipecat):
streaming speech-to-text, streaming text-to-speech and the Sutra conversation
model, for 27 Indian languages and English.

| Service | Oogam endpoint | What it does |
|---|---|---|
| `OogamSTTService` | `wss://platform.oogam.ai/v1/realtime?intent=transcription` | Streaming STT. Final transcripts; finalizes the turn the moment Pipecat's VAD says the user stopped. |
| `OogamTTSService` | `POST /v1/audio/speech` (`stream: true`, `response_format: "pcm"`) | Streaming TTS — 24 kHz PCM played as it is generated. |
| `OogamLLMService` | `POST /v1/chat/completions` | Sutra (`sutra-conversation`) through Pipecat's OpenAI service. |

```bash
pip install pipecat-oogam
```

Requires Python 3.11+, Pipecat 1.16 or later (1.x) and an Oogam API key
with the NAAD product enabled (and SUTRA, to use `OogamLLMService`).
**Tested with Pipecat v1.16.0.**

Maintained by [DWET Labs](https://oogam.ai), the team behind Oogam. Integration
guide: [oogam.ai/integrations/pipecat](https://oogam.ai/integrations/pipecat).

## Speech-to-text

```python
from pipecat.transcriptions.language import Language
from pipecat_oogam import OogamSTTService

stt = OogamSTTService(
    api_key=os.environ["OOGAM_API_KEY"],
    settings=OogamSTTService.Settings(language=Language.HI),
)
```

**Turn-taking stays with your pipeline.** Oogam's own end-of-turn detection
waits for 700 ms of silence. With this service you do not wait for it: when
Pipecat's VAD reports that the user stopped speaking, the service sends Oogam
`finalize` and Oogam closes the turn straight away. Smart Turn — Pipecat's
default — or any other turn strategy then decides whether the user's turn is
really over, exactly as with any other streaming STT. Set
`finalize_on_vad_stop=False` only if you want Oogam to decide instead.

Each transcript is final. Measured on the live engine (12 Nov 2026): with
`finalize` the transcript arrives about 0.33 s after the caller stops, against
about 0.8 s when Oogam waits out its own silence window. If a caller pauses for
0.8 s or more mid-sentence, Oogam closes a turn there and the rest arrives as a
second transcript; Pipecat's user aggregator joins them, so Smart Turn still
decides when the agent replies. (If Oogam ever re-transcribes a turn with
`replace`, the service pushes only the new words.)

**Breaths don't split sentences.** Pipecat's VAD also stops at a 0.2 s breath
inside a sentence, and Oogam transcribes each finalized stretch on its own — so
finalizing there splits the sentence and the second half is heard without its
context (measured: "मेरा mobile number | छह पाँच चार है" lost "नौ आठ सात").
Since 0.2 the service holds the finalize for `finalize_hold_ms` (400) and drops
it if the caller carries on, watching the audio itself so a soft restart that
Pipecat's VAD is slow to report still counts. Measured on the live engine with
Hindi sentences that have a 350 ms breath: 6 of 6 kept whole (0 of 6 in 0.1),
for about 0.15–0.25 s on the reply.

For replies about as fast as 0.1, add `OogamSmartTurnStopStrategy` — Pipecat's
own Smart Turn v3 strategy, which also tells the STT to finalize at once when
Smart Turn judges a pause to be the end of the turn:

```python
from pipecat.turns.user_turn_strategies import UserTurnStrategies
from pipecat_oogam import OogamSmartTurnStopStrategy

user_params = LLMUserAggregatorParams(
    vad_analyzer=SileroVADAnalyzer(),
    user_turn_strategies=UserTurnStrategies(stop=[OogamSmartTurnStopStrategy(max_wait=1.5)]),
)
```

Breaths stay whole wherever Smart Turn calls them unfinished (6 of 9 in the same
test); when it wrongly calls a breath the end, that sentence splits as in 0.1.
`max_wait` is Smart Turn's `stop_secs`: how long it waits when it thinks the
caller is not finished (Pipecat's default 3 s; 1–1.5 s suits number-heavy calls).

**The language must be given** — Oogam does not detect it at the start of a
call, so start in the caller's language when you know it. To follow a caller
who switches language mid-call, turn on auto-switch and move the TTS with it:

```python
stt = OogamSTTService(
    api_key=os.environ["OOGAM_API_KEY"],
    settings=OogamSTTService.Settings(
        language=Language.HI,
        auto_switch=True,
        candidates=[Language.HI, Language.EN_IN],
    ),
)

@stt.event_handler("on_language_changed")
async def on_language_changed(service, from_code, to_code, reason):
    # speak the language the caller switched to
    await worker.queue_frame(TTSUpdateSettingsFrame(delta=OogamTTSService.Settings(language=to_code)))
```

Auto-switch acts on Oogam's language hint, which comes after the turn it was
detected in — so the switch applies from the caller's second sentence
(sometimes the third), and that first sentence is usually misheard. The engine
also takes a few seconds to change language, so a sentence spoken while it
switches can come back several seconds late. Measured on
live calls (15 Nov 2026): Hindi → English is the most reliable; Hindi → Tamil,
Bengali and Marathi, and Tamil → English or Hindi, also switched. Hindi ↔
Gujarati, English → Hindi and Gujarati → English were not noticed — for those
callers start in their language, or change `language` yourself with an
`STTUpdateSettingsFrame`, which re-pins the live session at once, without
reconnecting.

| Setting | Default | |
|---|---|---|
| `language` | `Language.HI` | A Pipecat `Language` or an Oogam short code (`hi`, `en-IN`, `bho`). |
| `finalize_hold_ms` (constructor) | `400` | Wait after a VAD stop before finalizing; 0 = finalize at every VAD stop (0.1). Keep it ≤ 500: Oogam closes a turn itself at ~0.8 s of silence. |
| `vad_end_silence_ms` | Oogam's (700) | 700–5000. Reserved: sent to Oogam, but the current engine does not act on it. |
| `auto_switch` | `False` | Follow a caller who changes language. |
| `candidates` | any | Languages a call may switch to. |
| `min_confidence` | 0.6 | Hint confidence needed to switch. |

Audio is sent at 16 kHz mono PCM16; Pipecat resamples whatever your
transport delivers.

## Text-to-speech

```python
async with aiohttp.ClientSession() as session:
    tts = OogamTTSService(
        api_key=os.environ["OOGAM_API_KEY"],
        aiohttp_session=session,
        settings=OogamTTSService.Settings(voice="aditi", language=Language.HI),
    )
```

`voice` is a preset id (`aditi`, `arjun`, …) or a cloned voice id from
`GET /v1/voices`. Set `language` deliberately: Oogam falls back to Hindi for a
code it does not know.

**The voice follows the text.** Oogam speaks a text only in a language that is
written in its script, and refuses it otherwise ("text is predominantly Tamil
script but language=HIN expects Devanagari"). Since 0.2.1 a sentence that is
not in the script of the TTS language — a Tamil reply while the TTS is set to
Hindi — is spoken in the language that script belongs to, with the same voice,
instead of ending in an `ErrorFrame` and silence. Text in Latin letters is
always spoken in the TTS language. `OogamTTSService(auto_language=False)`
turns this off.

## Sutra

```python
llm = OogamLLMService(api_key=os.environ["OOGAM_API_KEY"])
```

**No function calling yet.** `/v1/chat/completions` answers a request that
carries `tools` with `400 tools_not_supported`, so do not register tools on
this service. For tool use, keep Oogam for STT and TTS and pair them with an
LLM service that supports tools.

## A complete agent

`examples/voice_agent.py` (in the source distribution, and on
[oogam.ai/integrations/pipecat](https://oogam.ai/integrations/pipecat#quickstart))
runs Oogam STT → Sutra → Oogam TTS with Silero VAD and Smart Turn, in the
browser through Pipecat's development runner. It moves the TTS language with
the caller and cancels the pipeline when the caller disconnects — keep that
handler in your own agent: a pipeline left running holds its Oogam session,
billed per second, until Pipecat's idle timeout (5 minutes).

```bash
pip install "pipecat-ai[runner,webrtc,silero]" pipecat-oogam
OOGAM_API_KEY=sk-setu-… python examples/voice_agent.py
```

Smart Turn v3 ships with Pipecat itself, so it needs no extra.

## Billing and limits

Streaming STT is billed at the speech-to-text rate per second the socket is
open, TTS per character as on the REST API, and Sutra per token.

Each Sutra reply and each sentence the agent speaks is one request against
your API key's requests-per-minute limit (60 on the Free plan; set per key in
the dashboard). One live call makes roughly 15–25 a minute, so size the limit
to the number of calls you run at once: a refused sentence reaches the
pipeline as an `ErrorFrame` and is not spoken.

## Developing

```bash
pip install -e ".[dev]"
pytest
```

Tests that need a running Oogam gateway are skipped unless `OOGAM_DEV_STACK`
points at one.

## Support

[support@dwetlabs.com](mailto:support@dwetlabs.com) ·
[Streaming STT reference](https://oogam.ai/docs/streaming-stt)
