# Background Speaker Suppression Playground API

## PURPOSE
This project rebuilds the "playground toggle" experience shown in the Dylos demo as a
small, self-hosted HTTP service. In the video the presenter enables *background speaker
suppression* to ignore background talk, TV, radio, or announcement voices during a live
voice-agent call, and mentions that suppression can also be driven **dynamically** so the
agent decides how much to apply. This service exposes that same knob over a REST API:
a client registers a call, sets a fixed or dynamic suppression mode, and asks the API
whether a given inbound audio segment should be treated as background and dropped.

## WHY THIS MATTERS
The core lesson of the clip is that a voice agent must separate *the caller* from
*everyone else in the room*. Naively transcribing everything makes the agent answer the
TV. A suppression gate — static or model-driven — is what keeps the conversation clean.
Students see how a single policy decision (suppress vs. pass) becomes an API boundary.

## HOW TO BUILD
Use FastAPI for the HTTP layer, Pydantic for request/response models, and a deterministic
rule-scoring stub in place of the real suppression model. Steps: (1) define a
`CallConfig` model with `mode` (`off`/`fixed`/`dynamic`); (2) implement
`score_background(segment)` returning a 0-1 backgroundness score from segment features;
(3) apply a threshold that rises with the configured suppression level; (4) expose
`POST /calls/{call_id}/segments` to classify a segment. Key snippet:

```python
@app.post("/calls/{call_id}/segments")
def classify(call_id: str, seg: Segment):
    score = score_background(seg)          # TODO: real Dylos model / API
    cfg = CALLS[call_id]
    keep = score < threshold_for(cfg)      # dynamic mode adjusts threshold per turn
    return {"call_id": call_id, "background": not keep, "score": score}
```

## WHEN TO USE IN PRODUCTION
Good for telephony/contact-center platforms, meeting-bot backends, and voice-agent
gateways that need a uniform suppression policy per call. Use it when you must audit
*why* a segment was dropped. Do **not** use a mock scorer in production — swap the stub
for the vendor model. Avoid a heavy HTTP hop for ultra-low-latency on-device gating.

## HOW IT HELPS STUDENTS
Learns FastAPI routing, Pydantic validation, stateful per-call config, and how an ML
policy is wrapped behind a clean API contract — a real pattern in voice-infra teams.

## STARTER CODE
See `starter/main.py` for the runnable FastAPI skeleton with the deterministic scorer.
