The Lab Notebook

# labs/experiments.py
import uuid
from dataclasses import dataclass
from datetime import datetime


@dataclass
class Experiment:
    name: str
    hypothesis: str
    parameters: dict
    results: dict | None = None
    status: str = "pending"
    id: str = ""
    created_at: str = ""

    def __post_init__(self) -> None:
        if not self.id:
            self.id = str(uuid.uuid4())[:8]
        if not self.created_at:
            self.created_at = datetime.now().isoformat()


if __name__ == "__main__":
    exp = Experiment(
        name="whisper model size",
        hypothesis="small beats base on word accuracy without pushing latency past 2s",
        parameters={"model": "small", "compute_type": "int8", "beam_size": 5},
    )
    print(f"id: {exp.id}  status: {exp.status}")
    print(f"created_at: {exp.created_at}")

$ uv run python labs/experiments.py
id: 7c1f22a9  status: pending
created_at: 2026-08-21T09:14:03.512847

Your id and timestamp will differ; that is the point of them. The interesting move is __post_init__. The dataclass machinery writes __init__ for you from the field annotations, assigns the plain defaults, and then hands control to __post_init__, where real code can run once per instance. A fresh UUID and the current time have to be computed there, at construction, because a field default is evaluated exactly once, when the class is defined. Also note results: dict | None = None: no result exists yet, and the record says so honestly instead of holding an empty dict that looks like a measurement of nothing.

import json
from dataclasses import asdict
from pathlib import Path

EXPERIMENTS_DIR = Path("glados/data/experiments")


def save_experiment(exp: Experiment) -> Path:
    EXPERIMENTS_DIR.mkdir(parents=True, exist_ok=True)
    path = EXPERIMENTS_DIR / f"{exp.id}.json"
    path.write_text(json.dumps(asdict(exp), indent=2))
    return path

$ cat glados/data/experiments/7c1f22a9.json
{
  "name": "whisper model size",
  "hypothesis": "small beats base on word accuracy without pushing latency past 2s",
  "parameters": {
    "model": "small",
    "compute_type": "int8",
    "beam_size": 5
  },
  "results": null,
  "status": "pending",
  "id": "7c1f22a9",
  "created_at": "2026-08-21T09:14:03.512847"
}

asdict() walks the dataclass recursively (nested dicts included) and returns plain Python that json.dumps understands, so keep the contents of parameters and results JSON-native: strings, numbers, booleans, lists, dicts. Naming the file by id gives every experiment a stable address; two experiments can never clobber each other, and the next function can find any record with nothing but its id. Python's None lands in the file as JSON null, exactly the "no result yet" marker a pending record wants.

def record_result(exp_id: str, results: dict) -> Experiment:
    path = EXPERIMENTS_DIR / f"{exp_id}.json"
    data = json.loads(path.read_text())
    exp = Experiment(**data)
    exp.results = results
    exp.status = "complete"
    save_experiment(exp)
    return exp


def main() -> None:
    exp = Experiment(
        name="whisper model size",
        hypothesis="small beats base on word accuracy without pushing latency past 2s",
        parameters={"model": "small", "compute_type": "int8", "beam_size": 5},
    )
    save_experiment(exp)
    print(f"created  {exp.id}  (status: {exp.status})")

    done = record_result(exp.id, {"word_accuracy": 0.94, "latency_ms": 1840})
    print(f"recorded {done.id}  (status: {done.status})")
    print(f"results: {done.results}")


if __name__ == "__main__":
    main()

$ uv run python labs/experiments.py
created  4a70f0cd  (status: pending)
recorded 4a70f0cd  (status: complete)
results: {'word_accuracy': 0.94, 'latency_ms': 1840}

The accuracy and latency here are one bench run on one machine; when you run the real comparison, your numbers will differ. What holds everywhere is the signature: record_result takes an id, not the live object, because in real use the run happens later, sometimes in a different process, with only the id written on a sticky note. Loading with Experiment(**data) proves the round-trip works: the JSON keys match the field names, so the dict unpacks straight into the constructor, and __post_init__ leaves the loaded id and timestamp alone because they are already truthy. The function can change results and status and nothing else. That asymmetry is deliberate: no code path exists for editing a hypothesis after the fact.