hotato
GitHub
Home/Docs/Visual report

The visual report

One self-contained HTML file: a to-scale timeline for every event, analytics on top, the evidence one click below. Zero external requests; it opens offline by double-click. With --embed-audio the scored clip lands inside the file, so share it with the same care as the recording.

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

# the bundled self-test suite, 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

# opt-in: embed the exact scored audio in the file too (HTML only, ~8 MB cap)
uvx hotato report --stereo call.wav --embed-audio --out report.html
A Hotato HTML report. Header reads hotato, local call forensics and regression guards for AI agents, generated by Hotato. A summary shows 1 of 4 events pass with a REGRESSION badge. An Analytics block rolls the events up: a time-to-yield dot plot, a talk-over histogram, and failure clusters grouped by fix class.
The file itself. Summary, verdict badge, and the analytics rollup, all in the one self-contained HTML this command writes.

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, and a PASS or FAIL chip. An event whose input cannot be judged gets a NOT SCORABLE chip with its reason instead of a verdict.
  • 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. The rollup renders once a page carries three or more events.
  • 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.
  • Thresholds used, once: every scoring threshold and voice-activity (VAD) setting, collapsed into one closed panel at the page end, so the run stays reproducible without repeating that table on every event.
One scored moment from a Hotato report. A stored-evidence-check card marked FAIL: expected the agent to yield, it did not. A dual-channel timeline marks the caller onset at 2.00 seconds; the embedded audio player holds the exact clip the scorer measured; measured metrics read caller onset 2.00s, talk-over 2.65s, response gap 2.18s; a fix box names the config change that would register a floor-taking event.
One event card. The timeline, the exact audio clip, the measured numbers, and a named fix class, all in the file.
0s1s2s3sCallerAgentonsetyieldFAILtalk_over_sec 0.80
One event card, small: caller and agent bars to scale, the talk-over span shaded, the onset and yield markers, and the PASS or FAIL chip. One of these renders per event, with the frame table one click below; the exact scoring thresholds sit once, in a closed panel at the end of the page.
median 0.32mean 0.38p90 0.6800.250.50.751.0s
The same time-to-yield measurements from every event card, collapsed onto one strip: n=8 dots in this run, one per measured yield. Median, mean, and p90 are read straight off it, just position on a shared axis.
Every number is a measurement

The page renders the envelope, the run’s JSON; it computes nothing new. Counts are fractions like 8 of 8, never a percentage; p90 is linear interpolation; no accuracy score 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, embeds that recording's audio in the report by default, and opens it in your browser; with no recording it runs the bundled self-test, unembedded. 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.