# Call Log Background-Interference Analyzer CLI

## PURPOSE
A Click + Pandas command-line tool that audits recorded voice-agent calls for background
speaker interference. In the Dylos demo the presenter plays speech in the background
while asking the agent to count to 10 and name the capital of France, proving that a
suppression feature is only trustworthy if you can measure how often background audio
leaked through. This CLI ingests a CSV of per-segment call logs and reports suppression
rates, residual interference, and the calls that need tuning.

## WHY THIS MATTERS
The video's whole point is an audible, verifiable separation between the speaker and the
background (TV, radio, announcements). Without measurement you can't tell a working
suppression policy from a lucky one. This tool makes the invisible — misrouted background
speech — visible as numbers you can trend release over release.

## HOW TO BUILD
Use Click for the command surface and Pandas for the aggregation. Define the expected
columns (`call_id`, `turn`, `energy_db`, `off_axis`, `voiced_ratio`, `suppressed`,
`ground_truth_background`). Steps: (1) load and validate with `pandas.read_csv`;
(2) compute per-call suppression rate; (3) compute false-suppress and missed-suppress
counts against `ground_truth_background`; (4) print a summary table and optionally write
a CSV. Key snippet:

```python
@click.command()
@click.argument("logfile", type=click.Path(exists=True))
@click.option("--by-call/--overall", default=True)
def report(logfile, by_call):
    df = pd.read_csv(logfile)          # TODO: support parquet/jsonl
    df["missed"] = (~df.suppressed) & df.ground_truth_background
    print(df.groupby("call_id").missed.sum())   # leakage per call
```

## WHEN TO USE IN PRODUCTION
Ideal for QA pipelines, nightly regression on call recordings, and pre-release audits
before enabling suppression for a new tenant. Run it in CI over a frozen call set to
catch regressions. Do **not** use it for real-time gating — it is a batch analyzer. Skip
it if you already have a full-blown telemetry warehouse; it is a lightweight first pass.

## HOW IT HELPS STUDENTS
Practices Click CLI design, Pandas groupby/aggregation, boolean masking for error
analysis, and the discipline of measuring an ML feature rather than eyeballing it.

## STARTER CODE
See `starter/main.py` for a runnable Click command with a built-in sample fallback.
