# GPT-Live Voice Partner Console

## PURPOSE
OpenAI's ad shows the new ChatGPT Voice "powered by GPT Live" as a *complete
conversational partner*: you can hesitate, interrupt it mid-sentence, and it keeps
listening "even while you're talking". This project builds the browser-side console
that reproduces that interaction in a classroom-safe way: a microphone loop, a live
turn log, and an explicit barge-in (interrupt) control. All speech-to-text, model
and text-to-speech calls are replaced by deterministic stubs so the app runs with no
API keys and no network.

## WHY THIS MATTERS
The transcript's whole point is turn-taking: "Hesitate, interrupt me. Even while
you're talking... you can interrupt me." Ordinary request/response chat UIs cannot
express that. A duplex voice console teaches the hard part of voice UX — capturing
partial audio, deciding when a turn is finished, and cancelling an in-flight reply
the moment the human speaks again.

## HOW TO BUILD
1. `pip install -r requirements.txt` (Gradio + NumPy).
2. Build a Gradio `Blocks` app with one `gr.Audio(sources=["microphone"], streaming=True)`
   input, a transcript `gr.Textbox`, and an "Interrupt" button.
3. Keep per-session state in a `Session` dataclass (turn history, interrupt flag).
4. Replace `stub_transcribe` / `stub_reply` with a real STT and the realtime model.

Key snippet (from `starter/main.py`):
```python
def respond(audio, session_id):
    if STREAM.interrupted(session_id):        # barge-in wins
        return "Interrupted — go ahead, I'm still listening.", log
    text = stub_transcribe(audio)             # TODO: real STT
    reply = stub_reply(text)                  # TODO: GPT Live realtime call
    return reply, f"{text} -> {reply}"
```

## WHEN TO USE IN PRODUCTION
Use it for voice-UX prototyping, prompt/behaviour QA, and classroom demos before you
commit to telephony. Do NOT ship it as-is for real calls: Gradio streaming is not a
SIP/WebRTC media path, has no jitter buffer, no echo cancellation and no PSTN billing.
For production telephony use WebRTC/SIP with a proper duplex audio pipeline.

## HOW IT HELPS STUDENTS
Students practice streaming UI state, session isolation, and dependency-inversion
(stub → real service) — the exact skills needed to swap a fake voice backend for a
production one without rewriting the app.

## STARTER CODE

`starter/main.py` is a runnable FastAPI skeleton for the full-duplex session gateway:

- `Session` (dataclass) — per-call turn state and interrupt bookkeeping.
- `_session(sid)` — session registry lookup.
- `stub_transcribe(audio)` / `stub_reply(user_text)` — deterministic stand-ins for the
  real speech-to-text and language-model calls (replace these first).
- `respond(audio, session_id)` — returns the `(transcript, reply)` turn pair.
- `interrupt(session_id)` — flushes the in-flight turn when the caller barges in.

Run it:

```bash
pip install -r requirements.txt
uvicorn starter.main:app --reload   # or: python starter/main.py
```

The `# TODO` markers show exactly where the stubbed ASR/LLM calls belong.
