babylon.utils.recorder

Black box recorder for simulation forensics.

Provides persistent tick-by-tick recording of simulation state for debugging, replay, and troubleshooting long-horizon data.

The SessionRecorder implements the SimulationObserver protocol, automatically capturing TickMetrics, Events, and Narratives to JSONL files in distinct session directories.

See also

babylon.engine.observer for the SimulationObserver protocol. babylon.engine.observers.metrics for TickStateRecorder.

Classes

SessionRecorder(metrics_collector[, ...])

Black box recorder for simulation forensics.
class babylon.utils.recorder.SessionRecorder(metrics_collector, narrative_director=None, base_dir=None)[source]

Bases: object

Black box recorder for simulation forensics.

Implements SimulationObserver protocol to persist tick-by-tick simulation state to JSONL files for debugging and replay.

Each session creates a unique timestamped directory containing: - metrics.jsonl: TickMetrics snapshots (one per line) - events.jsonl: SimulationEvents (one per line) - narrative.jsonl: Narrative entries with tick numbers - summary.json: Session metadata on completion

Parameters:

  • metrics_collector (TickStateRecorder) – TickStateRecorder observer to extract TickMetrics.

  • narrative_director (NarrativeDirector | None) – Optional NarrativeDirector for narrative log.

  • base_dir (Path | None) – Base directory for sessions (default: logs/sessions).

Example

>>> from babylon.utils.recorder import SessionRecorder
>>> recorder = SessionRecorder(metrics_collector=collector)
>>> # Recorder is registered as observer with Simulation
>>> # Files written automatically during simulation
>>> zip_path = recorder.export_package()  # Create debug archive
__init__(metrics_collector, narrative_director=None, base_dir=None)[source]

Initialize SessionRecorder with observer references.

Parameters:
Return type:

None

property name: str

Observer identifier for logging and debugging.

on_simulation_start(_initial_state, _config)[source]

Create session directory and open file handles.

Parameters:

  • _initial_state (WorldState) – WorldState at tick 0 (unused, required by protocol).

  • _config (SimulationConfig) – SimulationConfig for this run (unused, required by protocol).

Return type:

None

on_tick(_previous_state, new_state)[source]

Record tick data to JSONL files.

Parameters:

  • _previous_state (WorldState) – WorldState before tick (unused, required by protocol).

  • new_state (WorldState) – WorldState after tick (contains events).

Return type:

None

on_simulation_end(final_state)[source]

Close file handles and write summary.

Parameters:

final_state (WorldState) – Final WorldState when simulation ends.

Return type:

None

export_package()[source]

Create ZIP archive of session files.

Flushes all buffers and creates a compressed archive containing all session JSONL files for sharing and debugging.

Return type:

Path

Returns:

Path to the created ZIP file.

Raises:

RuntimeError – If no session has been started.