# DuplexTurn Lab: A SimPy Barge-In Latency Simulator

## PURPOSE
A discrete-event simulation that compares three conversation policies —
push-to-talk (half duplex), voice-activity turn taking, and full-duplex with
barge-in — on the same synthetic user. It measures how long a user waits before
being heard, how much spoken output gets thrown away when they interrupt
("Hang on, what are you wittering about?"), and how often a cough falsely
cancels the assistant.

## WHY THIS MATTERS
OpenAI's UK clip sells one idea: ChatGPT voice, powered by GPT Live, is
"bidirectional, full-duplex" — you can listen and talk at the same time. Full
duplex is not free. Every barge-in discards tokens already generated, and every
false trigger makes the assistant look twitchy. SimPy lets students put numbers
on that trade-off before they build anything, which is exactly the reasoning a
production team needs when choosing VAD thresholds.

## HOW TO BUILD
1. Model the user as a `simpy.Process` emitting utterances on a schedule, and
   the assistant as a process producing speech at a fixed tokens-per-second rate.
2. Simulate network + model latency with `env.timeout(delay)`.
3. Implement the three policies behind one `ConversationPolicy` interface.
4. Track metrics with a `simpy.Resource`-free collector: first-response latency,
   wasted output seconds, false-cancel rate.
5. Sweep the VAD threshold (0.2 s to 1.0 s) and print a table.

```python
def user(env, policy, script):
    for utter in script:
        yield env.timeout(utter["gap"])
        policy.on_user_speech(env.now, utter["text"])

def assistant(env, policy):
    while True:
        yield env.timeout(policy.next_speak_delay())   # scheduling only
        policy.emit(env.now, policy.render_reply())
```

## WHEN TO USE IN PRODUCTION
Use it to size latency budgets before committing to a voice vendor, to pick a
barge-in sensitivity that survives noisy rooms, and to argue for streaming TTS
in a design review. Do NOT use it as a substitute for real end-to-end testing
with audio hardware, for evaluating model *quality*, or for one-shot translation
UX where there is no turn-taking to optimise.

## HOW IT HELPS STUDENTS
Discrete-event modelling, queue/latency intuition, interface-based design, and
the discipline of defining a metric before optimising it. Students also learn to
report a trade-off curve rather than a single number.

## STARTER CODE
See `starter/main.py` for the SimPy skeleton with all three policies and a
sweep loop that prints the comparison table.
