# Full-Duplex Voice Session Gateway

## PURPOSE
Build a WebSocket gateway that keeps a conversation open the way the new ChatGPT Voice model does: bidirectional and full duplex. In the video three women talk at once while a hair dryer runs, and the model still follows the thread. A plain request/response API cannot represent that. This project implements a session object that tracks the active speaker, accepts overlapping utterances, records barge-in events, and keeps listening while the assistant is still speaking.

## WHY THIS MATTERS
Full duplex means audio flows both ways at once, so the assistant can be interrupted mid-sentence instead of being blocked by push-to-talk turn-taking. The transcript shows the consequences: the user says "Wait, wait" and the model immediately folds in the Masurian region detour, and later "I still need to practice that" lands while the translation keeps going. Students learn that turn-taking state, not raw audio, is the hard part of a voice agent.

## HOW TO BUILD
1. Create the app with `FastAPI` and register a `/ws/voice/{session_id}` WebSocket route.
2. Model session state (active speaker, transcript buffer, barge-in counter) with a dataclass.
3. Map inbound JSON events (`utterance`, `barge_in`, `turn_end`) onto explicit state transitions.
4. Hide the model behind a `VoiceModelStub.respond()` method and swap in a streaming client later.
Key snippet:

```python
if event is EventType.BARGE_IN:
    self.barge_ins += 1
    self.speaking = Speaker.USER
    return {"state": "interrupted", "barge_ins": str(self.barge_ins)}
```

## WHEN TO USE IN PRODUCTION
Use it for call-centre copilots, in-car assistants, live translation booths and any hands-busy setting (cooking, cycling, driving) where users cannot press a button. Do NOT use it for batch transcription, offline summarisation, or flows where one clean turn per request is enough — the extra concurrency and partial-audio handling is pure cost there.

## HOW IT HELPS STUDENTS
Learners practise async WebSocket programming, event-driven state machines, enum-typed message contracts, and graceful degradation when a model stream is interrupted. They finish with a deployable service shape rather than a throwaway script.

## STARTER CODE
`starter/main.py` is a runnable FastAPI app with a deterministic `VoiceModelStub`, a `/health` endpoint and a WebSocket loop that answers `utterance`, `barge_in` and `turn_end` events. Replace the stub with a streaming voice client to go live.
