Session Breakdown

Session Breakdown Skill

What it produces

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

• Schema: hyperloom.session_breakdown.v6.0 (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.
• hyperloom-results-service — downstream automation may POST this JSON when HYPERLOOM_RESULTS_SERVICE_URL is set.
• 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)

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

Code-driven (Python import)

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.inference_optimizer.tools.dump_session_breakdown)

# Live session in this sandbox
python -m hyperloom.inference_optimizer.tools.dump_session_breakdown

# Historical session on a shared filesystem
python -m hyperloom.inference_optimizer.tools.dump_session_breakdown \
    --session-dir /shared/hyperloom-sessions/<user>/<sid>

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

Bulk historical (operator)

for d in /shared/hyperloom-sessions/*/*; do
    [ -d "$d" ] || continue
    python -m hyperloom.inference_optimizer.tools.dump_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).
• New exports carry hyperloom.session_breakdown.v6.0. V6 is 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:

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