The episode store

Every brain episode (scripts/brain_episode.py, pusht_sim.brain.episode.run_brain_episode) ends by recording itself: a fixed set of typed datapoints, one row per plan, and a narrative in the voice of the video report. The store is runs/episodes.sqlite (module pusht_sim.brain.store), and beside it:

• runs/<family>/<seed>/metadata.json - the record, plans and narratives, next to the episode.mp4 it describes, so the video never travels without its record;
• runs/episodes/<episode_id>/episode.mp4 + metadata.json - the store's own copy. episodes.video_path points here, so a row survives a re-run of the same seed overwriting runs/brain/<seed>/episode.mp4.

runs.py is the workbench's store for multi-scenario physics runs; this one is for brain episodes only and shares nothing with it but the runs/ root.

.venv/bin/python scripts/episodes.py list
.venv/bin/python scripts/episodes.py show 9a5daa8adf08                 # or a unique id prefix
.venv/bin/python scripts/episodes.py search --situation "near a wall" --solved no
.venv/bin/python scripts/episodes.py search --seed 438 --tag finish --min-coverage 0.9
.venv/bin/python scripts/episodes.py backfill runs/brain --tags brain_rule --git-commit 599bc8992d02
.venv/bin/python scripts/episodes.py narrate 9a5daa8adf08            # Claude narrative, needs ANTHROPIC_API_KEY
.venv/bin/python scripts/render_videos_page.py                       # docs/videos/index.html from the store

From Python: record_episode(log_path, video_path) -> episode_id, get(episode_id), search(seed=, backend=, planner=, model=, situation=, solved=, min_coverage=, max_coverage=, since=, until=, tag=, limit=), narrative(episode_id, kind), backfill(run_dirs), classify_situation(state), claude_narrative(episode_id). Every function takes root= (default runs/).

episodes - one row per episode

Every column exists because a later analysis will want to group or filter on it. The same one-line reasons are comments in the CREATE TABLE (sqlite3 runs/episodes.sqlite .schema).

Every number is derived from the per-step records and the final state, not read from the summary, so logs written before the summary carried solved_step or the plans carried an intent record the same columns.

plans - one row per planning call

episode_id, plan_index, intent, edge, lever_px (signed, torque sign), orbit, release_alignment_deg, fallback, latency_s, outcome (why the bout ended: alignment / drift / bout_length / placed / horizon), bout_frames, touched, position_before_px, position_after_px, angle_before_deg, angle_after_deg (signed), coverage_before, coverage_after (NULL in pre-intent logs), reasoning. The narrative's "plan 3 overshot: 11 -> 36 px" comes from here.

narratives - (episode_id, kind) -> text

The claude path uses the ClaudePlanner client pattern: client is anything with messages.create(**kwargs); without one it needs ANTHROPIC_API_KEY and raises the same BrainConfigError naming the key. record_episode never calls it.

The situation classifier

Deterministic, from the start state, with the thresholds the human analysis already uses (docs/human_pushing_analysis.md); the components are stored separately.

Labels compose as <angle>, <position>[, near a wall] or already nearly solved[, near a wall].

The auto narrative

<situation>. plans: a -> b -> c. <one or two sentences>, where the plan sequence is the intents (edges for pre-intent logs) and every sentence is chosen by a measured fact and quotes it:

• solved: the step, how many steps after coverage crossed 0.95 the pusher was 10 px clear, the error and coverage numbers; and whether the last plan was a finish;
• coverage crossed 0.95 but never solved: the step it crossed and the final/max coverage;
• position inside the human final-bout p90 (8 px) but angle above the 1.8 deg median and coverage below 0.95: "the angle is what is short; 0.95 needs ~2 deg";
• overshoot: a plan that began within 40 px and ended >= 5 px farther away, when the episode also ends farther from the goal than it started (otherwise it is the second sentence);
• no progress (both final errors within 5% of the start) or little progress per bout (below the human's 19.9 px and 5.5 deg per-bout medians with coverage < 0.5), each followed by the likely cause the numbers show: a wall within 115 px, an orbit direction that flips between at least half of the consecutive plans, or bouts under half the human's 17 frames;
• rotation-only or translation-only progress (one error halved, the other not by a quarter);
• otherwise the plain numbers and where the horizon ran out.

The second sentence, when there is room: the overshooting plan, a coverage peak >= 0.1 above the final value, fallbacks, or that no plan was ever made inside the finish box.

The comparison narrative is Before (<tags>, <date>): <bouts, errors, coverage, outcome>. After: <the same>. <verdict> with the verdict one of: identical to the pixel, now solved, solved both times, overshoot gone (ended farther than it started before, closer after), or the signed deltas. The engine comparison is the same sentence with On <other backend> (<tags>, <date>): ... On <this backend>: ... in place of before/after, the other engine being the baseline the verdict is read against.

The videos page

scripts/render_videos_page.py regenerates docs/videos/index.html from the store: one section per tag, the before/after table when every episode in the section has an earlier run on its seed, the situation table otherwise, and each caption is the stored narrative. It copies each episode's mp4 to docs/videos/<tag>_<seed>.mp4 and encodes the committed .webm beside it with ffmpeg when missing or stale.