# Live Call Background-Noise Suppression Simulator

## PURPOSE
A discrete-event simulation of a live voice-agent call running with background
speaker suppression enabled. The Dylos demo shows a real call where speech, TV, radio,
or an announcement plays underneath the conversation while the agent counts to 10 and
answers a trivia question. This project models that call turn by turn: background
sources start and stop, suppression is applied with a configurable latency, and the
simulator measures how much background audio actually reached the agent.

## WHY THIS MATTERS
Suppression is a race against the clock. A policy is only as good as its reaction time:
a TV advert that fires mid-turn must be gated before the transcription models it. The
video's "dynamic" mode — the agent deciding how much to suppress — is fundamentally a
scheduling and control problem, and discrete-event simulation is the right lens for it.

## HOW TO BUILD
Use SimPy for the event engine and NumPy for randomized background activity. Steps:
(1) model the caller as a process that emits turns; (2) spawn `background_noise` processes
for each source (TV, radio, announcement) with inter-arrival times from NumPy;
(3) keep a suppression controller that reacts to a noise-start event after `latency`
seconds; (4) record over the call timeline whether each frame was suppressed. Key snippet:

```python
def background_noise(env, name, controller, rng):
    while True:
        yield env.timeout(rng.exponential(8.0))     # quiet gap
        controller.trigger(name)
        dur = rng.uniform(2.0, 6.0)
        yield env.timeout(dur)                       # noise event window
        controller.release(name)
```

## WHEN TO USE IN PRODUCTION
Use it to size suppression latency budgets, compare static vs. dynamic policies, and
stress-test a gateway before deploying to real telephony. It gives capacity planners
leakage estimates under realistic noise arrival rates. Do **not** use it as a substitute
for real recorded-call evaluation — it is a model, not evidence. Skip it for one-off
single-call debugging.

## HOW IT HELPS STUDENTS
Teaches SimPy process modeling, exponential inter-arrival sampling with NumPy, control
loops with latency, and how to turn a product feature into a measurable simulation.

## STARTER CODE
See `starter/main.py` for the runnable SimPy call simulation with a suppression controller.
