Proving the Tuning Instead of Guessing It

# labs/prototype_run.py
import time
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class PrototypeRun:
    name: str
    hypothesis: str
    config: dict
    results: list = field(default_factory=list)
    started_at: str = ""

    def __post_init__(self) -> None:
        if not self.started_at:
            self.started_at = datetime.now().isoformat()


if __name__ == "__main__":
    run = PrototypeRun(
        name="silence threshold",
        hypothesis="accuracy peaks near 0.01 and falls off on both sides",
        config={"values": [0.005, 0.01, 0.02, 0.04, 0.08], "clips": 20},
    )
    print(f"{run.name}: {len(run.results)} results so far")
    print(f"started_at: {run.started_at}")

$ uv run python labs/prototype_run.py
silence threshold: 0 results so far
started_at: 2026-08-18T09:41:22.318604

Two fields differ from chapter 25's Experiment, and both differences are the chapter. results is a list, because a sweep produces a series where a single change produced one outcome. And the list has to arrive through field(default_factory=list): the factory is called once per instance, so every run gets its own list, where a bare = [] would be one list shared by every run ever constructed. Dataclasses refuse that outright, with the ValueError you already met. hypothesis stays required and stays singular, since a sweep asks one question across many values, and writing it now is what stops you from discovering afterwards that you always expected whichever number happened to win.

    def record(self, step: str, value: float) -> None:
        self.results.append({"step": step, "value": value, "at": time.time()})


run.record("threshold_0.005", 0.80)
run.record("threshold_0.01", 0.95)
print(f"recorded {len(run.results)} steps")
print(run.results[-1])

$ uv run python labs/prototype_run.py
recorded 2 steps
{'step': 'threshold_0.01', 'value': 0.95, 'at': 1755509046.712933}

Three keys, and the third is the one people leave out. With at on every entry the list is a timeline: subtract the first stamp from the last and you know how long the sweep took, and the gaps between neighbours tell you which value was slow to measure. It is a float from time.time() rather than a readable string because arithmetic is the whole reason it exists; the human-readable stamp already lives once, on started_at. Recording the moment costs a function call now and cannot be reconstructed at all later.

from pathlib import Path

import numpy as np
import soundfile as sf

CLIP_DIR = Path("glados/data/calibration")


def clip_accuracy(threshold: float) -> float:
    clips = sorted(CLIP_DIR.glob("*.wav"))
    correct = 0
    for path in clips:
        audio, _ = sf.read(path, dtype="float32")
        rms = float(np.sqrt(np.mean(audio ** 2)))
        heard_speech = rms >= threshold
        is_speech = path.name.startswith("speech")
        correct += int(heard_speech == is_speech)
    return correct / len(clips)


def sweep(run: PrototypeRun) -> None:
    for value in run.config["values"]:
        accuracy = clip_accuracy(value)
        run.record(f"threshold_{value}", accuracy)
        print(f"threshold={value:<6} accuracy={accuracy:.2f}")

$ uv run python labs/prototype_run.py
threshold=0.005  accuracy=0.80
threshold=0.01   accuracy=0.95
threshold=0.02   accuracy=0.90
threshold=0.04   accuracy=0.80
threshold=0.08   accuracy=0.60

The clip set is twenty WAVs you record once with chapter 4's capture script: ten of you talking normally, saved as speech_01.wav through speech_10.wav, and ten of your empty room as silence_01.wav onward. The label lives in the filename, so the right answer for every clip is decided before any threshold is tried. Each clip's RMS is chapter 4's level check, unchanged; the threshold turns that number into a verdict, and accuracy is the fraction of verdicts that match the filename. Twenty clips means every result is a multiple of 0.05, a useful reminder of how coarse the instrument is.

These figures come off one bench run, one built-in laptop microphone, one quiet evening; yours will land elsewhere and your winning value may too. What repeats everywhere is the two-sided failure. Down at 0.005 the room's own hiss clears the bar and silence gets called speech. Up at 0.08 anything short of a raised voice is discarded. Between them sits a plateau where 0.01 and 0.02 both work, and its width matters as much as its peak: a knob with a wide safe band never needs revisiting, while a narrow one will betray you the week you move the microphone.

import json
from dataclasses import asdict

PROTOTYPE_DIR = Path("glados/data/prototypes")


    def best(self) -> dict | None:
        return max(self.results, key=lambda r: r["value"]) if self.results else None

    def summary(self) -> dict:
        top = self.best()
        span = self.results[-1]["at"] - self.results[0]["at"] if self.results else 0.0
        return {
            "started": self.started_at[:16],
            "steps": len(self.results),
            "seconds": round(span, 1),
            "best": top["step"] if top else None,
            "value": top["value"] if top else None,
        }


def save_run(run: PrototypeRun) -> Path:
    PROTOTYPE_DIR.mkdir(parents=True, exist_ok=True)
    slug = run.name.replace(" ", "-").lower()
    stamp = run.started_at[:19].replace("-", "").replace(":", "")
    path = PROTOTYPE_DIR / f"{slug}_{stamp}.json"
    path.write_text(json.dumps(asdict(run), indent=2))
    return path


def compare_runs(name: str) -> None:
    slug = name.replace(" ", "-").lower()
    for path in sorted(PROTOTYPE_DIR.glob(f"{slug}_*.json")):
        s = PrototypeRun(**json.loads(path.read_text())).summary()
        print(f"{s['started']}  {s['best']:<16} {s['value']:.2f}"
              f"  ({s['steps']} values, {s['seconds']}s)")


def main() -> None:
    run = PrototypeRun(
        name="silence threshold",
        hypothesis="accuracy peaks near 0.01 and falls off on both sides",
        config={"values": [0.005, 0.01, 0.02, 0.04, 0.08],
                "clips": 20, "mic": "laptop built-in"},
    )
    sweep(run)
    print(f"saved {save_run(run)}")
    compare_runs(run.name)


if __name__ == "__main__":
    main()

$ uv run python labs/prototype_run.py
threshold=0.005  accuracy=0.80
threshold=0.01   accuracy=0.95
threshold=0.02   accuracy=0.90
threshold=0.04   accuracy=0.80
threshold=0.08   accuracy=0.60
saved glados/data/prototypes/silence-threshold_20260818T094122.json
2026-08-18T09:41  threshold_0.01   0.95  (5 values, 41.6s)

$ uv run python labs/prototype_run.py   # three days later, on a USB microphone
threshold=0.005  accuracy=0.85
threshold=0.01   accuracy=0.95
threshold=0.02   accuracy=1.00
threshold=0.04   accuracy=0.90
threshold=0.08   accuracy=0.70
saved glados/data/prototypes/silence-threshold_20260821T201207.json
2026-08-18T09:41  threshold_0.01   0.95  (5 values, 41.6s)
2026-08-21T20:12  threshold_0.02   1.00  (5 values, 38.9s)

The second sweep is the payoff. A better microphone raised the whole curve and moved the peak one step to the right, and the comparison says so in two lines read off disk, with no appeal to what you think you remember about Tuesday. summary() deliberately drops the results list: an index that reprinted every step would be unreadable at twenty saved runs, while name, time, count and winner fit on a line. And PrototypeRun(**json.loads(...)) is the same round trip chapter 25 relied on, working for the same reason: every field is a JSON-native type, and __post_init__ leaves a loaded started_at alone because it is already filled.