Metadata-Version: 2.5
Name: pipecat-oogam
Version: 0.1.0
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: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
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. **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.)

**The language must be given** — Oogam does not auto-detect. To follow a caller
who switches language mid-call, turn on auto-switch:

```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, Language.GU],
    ),
)

@stt.event_handler("on_language_changed")
async def on_language_changed(service, from_code, to_code, reason):
    # e.g. switch the TTS language to match
    await task.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 first sentence after a switch is transcribed in the old
language, and the switch applies from the next one. Changing `language` with
an `STTUpdateSettingsFrame` re-pins the live session without reconnecting.

| Setting | Default | |
|---|---|---|
| `language` | `Language.HI` | A Pipecat `Language` or an Oogam short code (`hi`, `en-IN`, `bho`). |
| `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.

## 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:

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

## Billing

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.

## 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)
