Session Breakdown

Session Breakdown Skill

What it produces

A single JSON file: <session_dir>/session_breakdown.json.

• Schema: hyperloom.session_breakdown.v6.1 (hardcoded; see SCHEMA_VERSION in breakdown/schema.py).
• Producer: src/hyperloom/inference_optimizer/breakdown/exporter.py
• Filename: BREAKDOWN_FILENAME (= session_breakdown.json)

Beyond the envelope (schema_version / exported_at_utc / exporter_version), the JSON carries the sections below. This is the subset most consumers use, not the full set — breakdown/exporter.py (the breakdown = {...} literal) and breakdown/schema.py are authoritative.

Who reads it

• A downstream stats/reporting service — primary consumer. Replaces the MAE-synthesized raw_report / fact_sheet. Recommended read order: prefer session_breakdown.json if present, fall back to legacy MAE output otherwise.
• Offline / notebook analysis — single file, easy to load, no DB needed.

When to refresh (LLM Orchestrator decision tree)

The Coordinator's cli.py finally block writes session_breakdown.json unconditionally at end-of-session — that's the safety net. But you should ALSO refresh it eagerly when downstream dashboards may be watching this session live:

1. Always at end-of-session (handled by cli.py finally — you do not need to dispatch this).
2. After every KEEP'd explore, specialist, framework, or kernel result whose benchmark changed the final stack.
3. After a successful sweep or conc_sweep when a live dashboard is observing this session.
4. Never mid-action — collectors expect a coherent state snapshot.

Dispatch action session_breakdown — a single 1-minute action, no inputs required.

How to invoke

LLM-driven (Coordinator action)

yamlCopy code
# Issue an action intent like any other action
{ "action": "session_breakdown", "params": {} }

Code-driven (Python import)

pythonCopy code
from hyperloom.inference_optimizer.breakdown import build, write_breakdown_json

# Just compute the dict (no side effects)
breakdown = build("/workspace/hyperloom")

# Compute + atomically write to <sd>/session_breakdown.json
out_path = write_breakdown_json("/workspace/hyperloom")

CLI / offline (hyperloom session breakdown)

bashCopy code
# Live session in this sandbox
python -m hyperloom session breakdown

# Historical session on a shared filesystem
python -m hyperloom session breakdown \
    --session-dir /shared/hyperloom-sessions/<user>/<sid>

# Override output path (e.g. write to a staging area)
python -m hyperloom session breakdown \
    --session-dir <SD> --output /tmp/breakdown.json

Bulk historical (operator)

bashCopy code
for d in /shared/hyperloom-sessions/*/*; do
    [ -d "$d" ] || continue
    python -m hyperloom session breakdown \
        --session-dir "$d" > /dev/null
done

Field reference (what comes from where)

The collector for each section reads only from the listed sources. All collectors are pure functions; failure in one section never poisons another (each becomes a warnings[] entry instead). Like the table above, this reference is partial — breakdown/exporter.py is authoritative.

What is NOT in scope

• Real-time event streaming — use claw_session_events for that.
• LLM-based attribution — every collector is deterministic / rule-based. Attribution is delta_pct math, not natural language.
• Schema migration — consumers MUST check schema_version and gate features on it, comparing the major version (vN) rather than the exact string: the producer emits both …v2 and …v3.0 today (see Versioning policy) and they are wire-compatible.
• Cross-session aggregation — one file per session. Use a Jupyter notebook or downstream analytics job for fleet views.

Failure modes

Versioning policy

• schema_version (in schema.py) carries the major contract version; it is bumped ONLY on breaking changes (renamed/removed fields, changed semantics), apart from the declared 6.1 changes below.
• New exports carry hyperloom.session_breakdown.v6.1. 6.1 changes three things inside the 6 major, a declared exception to the major-bump rule: it renames one key, removes keys no producer populated (disposition: removed in 6.1, never populated) or that only carried a constant (roofline_measured, the baseline action's convergence; disposition: removed in 6.1, constant), and reports attributed_gain_pct, unattributed_gain_pct and run empty as null when unmeasured or not provided. throughput_tok_s_per_gpu in outcome.baseline, outcome.final and the baseline event measurement is now output_throughput, and the old key is no longer written. Archived 6.0 documents and 1.1.x exports keep the old key, so readers must accept both or migrate. Re-exporting a 6.0 session directory yields a null outcome.baseline.output_throughput, keeps the session's old contract_digest, and overwrites the archived file at the default output path.
• V6 was a breaking cutover for the timeline: the actions record their own events as they run, so an event's start_time is when the work began rather than when its artefacts were written, and the KERNEL and BASELINE projections are gone. Consumers that sorted around the old collapsed windows need to be rechecked.
• Inside v6, enablement gained the round ledger: rounds[] and its counters are added to the block, and the three state-sourced fields they replace (stall_streak, inflight_task_id, dispatch_tick) are no longer emitted. The block is runtime observability that is already {} on a session that ran no enablement, so it carries no field a consumer can gate a version on; the disposition of each replaced field is in docs/reference/session-breakdown.md.
• V5 was the preceding cutover, for optimization results: optimizations is reshaped, and the optimization_stack, attribution, geak_invocations, forge_invocations, and gemm_tuning projections are gone. Consumers MUST match on the vN major prefix, never on exact-string equality, and archived V2/V3/V4/V5 documents need a migration before a V6 reader sees them.
• optimizations carries its own schema_version (currently 5), independent of the envelope's.
• Adding optional fields is never a breaking change.
• exporter_version tracks the exporter implementation independently; consumers can ignore it.

Testing

Each collector has a unit test under src/hyperloom/inference_optimizer/tests/ that runs it against a fixture session_dir tree. An end-to-end test calls build(...) on a fully-populated fixture and JSON-schema-validates the result. Run:

bashCopy code
pytest src/hyperloom/inference_optimizer/tests/ -k breakdown -v