Metadata-Version: 2.5
Name: livekit-plugins-oogam
Version: 0.1.0
Summary: Oogam for LiveKit Agents — streaming STT with fast turn finalize, TTS and Sutra — for 27 Indian languages and English.
Project-URL: Homepage, https://oogam.ai/integrations/livekit
Project-URL: Documentation, https://oogam.ai/docs/streaming-stt
Author-email: Dwet Labs <support@dwetlabs.com>
License: MIT
License-File: LICENSE
Keywords: indian-languages,livekit,livekit-agents,naad,oogam,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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: livekit-agents<2,>=1.8
Requires-Dist: livekit-plugins-openai<2,>=1.8
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# livekit-plugins-oogam

[Oogam](https://oogam.ai) for [LiveKit Agents](https://docs.livekit.io/agents/):
streaming speech-to-text, text-to-speech (Naad) and Sutra, for 27 Indian
languages and English.

| Service | Class | Oogam endpoint |
|---|---|---|
| Speech to text | `oogam.STT` | `wss://platform.oogam.ai/v1/realtime?intent=transcription` |
| Text to speech | `oogam.TTS` | `POST /v1/audio/speech` (streamed PCM) |
| Sutra | `oogam.LLM` | `POST /v1/chat/completions` |

## Install

```bash
pip install "livekit-agents[silero]~=1.8" livekit-plugins-oogam python-dotenv
```

Python 3.10 or later, LiveKit Agents 1.8. Create an API key with the NAAD
product (and SUTRA for the LLM) on the [Oogam Platform](https://platform.oogam.ai)
and set `OOGAM_API_KEY`.

## Quick start

```python
from dotenv import load_dotenv

from livekit import agents
from livekit.agents import Agent, AgentServer, AgentSession
from livekit.plugins import oogam, silero

load_dotenv()


class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful assistant. Reply in one or two short spoken sentences, in the caller's language.",
        )

    async def on_enter(self) -> None:
        self.session.generate_reply(instructions="Greet the caller in Hindi.")


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: agents.JobContext):
    session = AgentSession(
        stt=oogam.STT(language="hi"),
        llm=oogam.LLM(),
        tts=oogam.TTS(voice="aditi", language="hi"),
        vad=silero.VAD.load(),
    )
    await session.start(room=ctx.room, agent=Assistant())


if __name__ == "__main__":
    agents.cli.run_app(server)
```

```bash
python agent.py console   # talk to it in the terminal
python agent.py dev       # join a LiveKit room
```

## Turn-taking

Keep a VAD, as the quick start does. The STT declares `manual_flush`: when
LiveKit decides the caller has stopped — Silero's end of speech, or your turn
detector's verdict — it flushes the stream and the plugin sends Oogam
`finalize`, so the turn closes at that moment. The VAD also lets callers
interrupt the agent.

Measured on live calls (Hindi and Indian English, LiveKit Agents 1.8, Sutra
and Oogam TTS, 14 calls):

| Setup | Transcript after the caller stops | Agent starts speaking |
|---|---|---|
| `vad=silero.VAD.load()` | 0.6–0.75 s | 1.8–2.0 s |
| `silero.VAD.load(min_silence_duration=0.3)` | 0.6–0.75 s | 1.55–1.85 s |
| `turn_detection="stt"`, `min_delay` 0.07 | 0.65–0.8 s | 1.75–1.95 s |
| `turn_detection="stt"`, default `min_delay` | 0.65–0.75 s | 2.1–2.3 s |

Most of the time to the agent's first word is Sutra and the first sentence of
speech. A shorter `min_silence_duration` answers sooner, but may cut in on a
caller who pauses mid-sentence — test it with your callers.

To let Oogam end each turn by itself (each transcript then arrives as
START_OF_SPEECH, FINAL_TRANSCRIPT, END_OF_SPEECH), lower LiveKit's endpointing
delay too, or it waits another 0.5 s after every transcript:

```python
session = AgentSession(
    ...,
    turn_handling={"turn_detection": "stt", "endpointing": {"min_delay": 0.07}},
)
```

## Languages

`language` takes Oogam's short codes (`hi`, `gu`, `ta`, `en-IN`, `bho` …),
BCP-47 tags (`hi-IN`, `gu-IN`) or Oogam's 3-letter speech codes (`HIN`).
Oogam does not auto-detect: a session starts in the language you give it.
Plain `en` is American English; use `en-IN` for Indian English.

To follow a caller who switches language mid-call:

```python
stt = oogam.STT(language="hi", auto_switch=True, candidates=["hi", "en-IN", "gu"])
```

Each transcript carries the language it was heard in; move the TTS with it
using `tts.update_options(language=...)`.

## Sutra and tools

Sutra does not support function calling yet: an agent with tools gets a 400
(`tools_not_supported`). For agents that need tools, keep `oogam.STT` and
`oogam.TTS` and pair them with an LLM that supports tools.

## Billing

From your prepaid wallet: speech to text per second the session is open,
text to speech per character, Sutra per token. An empty wallet is refused
with a 402.

## Links

- [Integration guide](https://oogam.ai/integrations/livekit)
- [Streaming STT reference](https://oogam.ai/docs/streaming-stt)
- [Voices](https://oogam.ai/docs/voices)

MIT licensed. Maintained by DWET Labs.
