hotatodocs
Home Docs GitHub
Home/Docs/Visual report

The visual report

One self-contained HTML file: a to-scale timeline for every event, drawn from the real frame data, with analytics on top and the evidence one click below. Zero external requests; it opens offline by double-click.

bash
# score a recording and render the report
uvx hotato report --stereo call.wav --out report.html

# the bundled self-test battery, same page
uvx hotato report --suite barge-in --out selftest.html

# the same content as Markdown tables
uvx hotato report --stereo call.wav --format md --out report.md

What the page shows

  • A per-event SVG timeline: caller and agent activity to scale, the overlap shaded, the caller-onset and yield markers, the measured talk-over seconds, expected vs actual, a PASS or FAIL chip, and the exact ScoreConfig thresholds used.
  • Analytics from the same measurements: a time-to-yield distribution strip (one dot per measured yield, with mean, median, and p90), a talk-over histogram on a fixed grid, and failure clustering by fix class.
  • A collapsible frame inspector per event: the full frame dump as a table (t_sec, per-channel dBFS, active flags, thresholds), so every pixel on the page is re-derivable by hand.
Every number is a measurement

The page renders the envelope; it computes nothing new. Rates appear as fractions (1.00 means 8 of 8), p90 is linear interpolation, and there is no accuracy percentage anywhere. Definitions: METHODOLOGY.md.

Regression deltas with --base

Save an envelope, then compare a later run against it. The report renders per-scenario talk-over and time-to-yield deltas with clear worse and better marks.

bash
hotato run --suite barge-in --format json > base.json
# ... change a prompt, a config knob, a model ...
hotato report --suite barge-in --base base.json --out report.html

PDF

The page ships print CSS. Print it from any browser and the interactive parts collapse into a clean paper layout, so print-to-PDF is the PDF export.

One command instead: hotato doctor

The 5-minute path. Pass a recording and it scores it, writes this report, and opens it in your browser; with no recording it runs the bundled self-test. On a headless box it prints the path.

bash
uvx hotato doctor --stereo call.wav   # score your call, open the report
uvx hotato doctor                     # self-test fallback, same flow
uvx hotato doctor --demo --no-open --out report.html
Same exit codes as run

0 all pass, 1 a regression (--no-fail forces 0), 2 usage or I/O error. The report is a CI artifact that doubles as the gate.