# voice-livekit — LiveKit agent worker

Replaces `services/voice-bridge/` (Telnyx media bridge + Voxtral + Supertonic) per
`LIVEKIT_VOICE_MIGRATION.md` (working-dir root). A realtime speech-to-speech model is the
conversation brain; Convex stays the tool/compliance/persistence layer via the endpoints in
`LIVEKIT_VOICE_TOOL_CONTRACT.md` (already deployed on EU dev).

## Layout
- `agent.py` — worker entrypoint: `/voice/session` bootstrap (gates → refuse-and-hangup, persona
  prompt, tool manifest), the session (see Engines below), the 5 Convex function tools, transcript
  → `/voice/persist` (idempotent).
- `convex_tools.py` — async HTTP client for the Convex voice endpoints.

## Engines (env `VOICE_REALTIME_PROVIDER`)
- **`openai`** *(default for stakeholder demo — matches `/realtime-voice`)* — OpenAI Realtime
  speech-to-speech (`gpt-realtime` + `marin` voice, patient VAD). Persona/dialect from Convex
  Agent Builder. See **[OPENAI_REALTIME_DEMO.md](./OPENAI_REALTIME_DEMO.md)** for the full checklist.
  Note: US egress (not the EU-sovereignty path).
- **`deepgram`** — chained Deepgram STT + Groq LLM + Aura-2 TTS (EU audio; **no Arabic TTS**).
- **`azure`** — Azure OpenAI `gpt-realtime` (Sweden Central EU target when quota is available).
- **`gemini`** — realtime S2S fallback (US/global egress).

## Setup
```
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt   # Windows
cp .env.example .env                            # then fill the blanks
```

## Run
```
.venv/Scripts/python agent.py console   # talk from the terminal (needs model creds + VOICE_DEV_ORG_ID)
.venv/Scripts/python agent.py dev       # register with LiveKit Cloud and accept dispatches
```

## Status / TODO
- [x] Convex tool layer deployed + smoke-tested (EU dev, 2026-06-10)
- [x] LiveKit Cloud project keys verified (`coredeskai-c5hvxyvj`)
- [x] **Deepgram chained engine added (2026-06-17)** — `deepgram` provider builds an
      STT+LLM+TTS `AgentSession`; imports/constructs verified at livekit-agents 1.5.17. Unblocks
      calls without the Azure quota. Needs a real `DEEPGRAM_API_KEY` + `GROQ_API_KEY` to run.
- [ ] **BLOCKED: Azure OpenAI `gpt-realtime` Sweden Central creds** (needs an Azure subscription —
      company account; personal signup wants a credit card) — only blocks the `azure` S2S path now.
- [ ] First console-mode conversation on the `deepgram` path (needs Deepgram + Groq keys + a French
      Aura-2 voice id in `DEEPGRAM_TTS_MODEL`)
- [x] Inbound DID resolve (Story 7): worker reads SIP trunk number →
      `POST /voice/resolve-inbound` → org + agent; bind DIDs in Phone Numbers UI.
      Ops still need one shared Telnyx → LiveKit inbound trunk + dispatch rule
      targeting agent `coredesk-voice`.
- [ ] Telnyx SIP trunk ops checklist (inbound trunk + dispatch) for production DIDs
- [ ] Outbound campaign dispatch from `outboundCalls.initiateCall` (new `livekit` migration route)
- [ ] CEFR scoring pass + parallel ASR decision (recruitment)
- [ ] KPI-gated shadow → pilot ramp per `TELNYX_VOXTRAL_KPI_CONTRACT.md`