# MR Title

feat(web): add OpenAI Realtime voice lab with WebRTC and sample tools

---

# MR Description (copy everything below this line into GitLab)

## Summary

Adds a standalone **OpenAI Realtime Voice Lab** at `/realtime-voice` — a separate interface from the existing LiveKit/Vapi voice stack. Uses OpenAI's speech-to-speech Realtime API over **WebRTC** per the [official voice agents](https://developers.openai.com/api/docs/guides/voice-agents) and [Realtime WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc) guides.

- **Session API** (`POST /api/realtime/session`) — forwards browser SDP to OpenAI `/v1/realtime/calls` with session config (model, instructions, tools, voice). API key stays server-side.
- **Tools API** (`POST /api/realtime/tools`) — executes sample function tools server-side when the model calls them over the data channel.
- **WebRTC hook** (`useOpenAIRealtime`) — manages mic, audio playback, data-channel events, and the tool-call loop.
- **Standalone UI** — minimal layout (no dashboard sidebar), live status, transcript/tool log, start/stop controls.
- **Public routes** — `/realtime-voice` and `/api/realtime/*` added to Clerk public routes in `proxy.ts`.

**Sample tools (mock handlers):** `get_weather`, `lookup_order`, `book_appointment`, `search_knowledge`

This is intentionally isolated for experimentation. It does not replace or modify the production LiveKit voice worker or Convex voice tool layer.

## Env vars

Add to `apps/web/.env.local`:

    OPENAI_API_KEY=sk-...
    OPENAI_REALTIME_MODEL=gpt-realtime  # optional
    OPENAI_REALTIME_VOICE=marin                               # optional

## Test plan

- [ ] Set `OPENAI_API_KEY` in `apps/web/.env.local`
- [ ] Run `pnpm --filter web dev` and open `http://localhost:3000/realtime-voice`
- [ ] Click **Start voice session** and allow microphone access
- [ ] Confirm status shows **Live** and assistant audio plays back
- [ ] Ask: "What's the weather in Paris?" → `get_weather` runs, response includes weather
- [ ] Ask: "Look up order ORD-12345" → `lookup_order` runs
- [ ] Ask: "Book an appointment tomorrow at 10am for Adem" → `book_appointment` runs
- [ ] Ask a knowledge question → `search_knowledge` runs
- [ ] Click **End session** — connection closes cleanly
- [ ] Verify `/realtime-voice` loads without Clerk login (public route)

---

**Branch:** `feat/openai-realtime-voice-lab`

**Create MR:** https://gitlab.com/Fakhreddine/coredeskai/-/merge_requests/new?merge_request%5Bsource_branch%5D=feat%2Fopenai-realtime-voice-lab