marla.metrics

Writes the run directory and renders marla summarize’s plots. See Metrics and plots for a narrative description of every artifact and plot.

Writes the run directory (spec section 21): metadata.json, episodes.csv, decisions.csv, updates.csv, summary.json, config.yaml, checkpoint.pt.

The RL Orchestrator is the only central metrics writer (spec section 21); this module is called once, after a run ends (whether it completed, stopped by user, or failed), from the CLI’s run command.

Some spec-listed decisions.csv columns are not populated in this release and are always written empty: schema_revision_count (the Gatekeeper’s per-request revision count is never reported back to the RL Orchestrator – doing so would need a wire-protocol change to the ADVISORY_RESPONSE artifact), action_success (NASimEmu’s reward doesn’t expose a distinct success/failure signal separate from the reward value itself), and artifact_path (spec’s artifacts/plan_maker/<request-id>.json full request/response dump isn’t implemented – marla run --debug writes comparable query/response text files to debug/<run_id>/ instead). updates.csv’s checkpoint_id is likewise always empty: this module saves exactly one checkpoint per run, at the very end (spec section 5’s normal-shutdown step 1), not one per PPO update – there is nothing to put in a per-update column. Load the final checkpoint with marla.learning.checkpoint.load_checkpoint.

marla.metrics.writer.write_decisions_csv(run_dir, config, records)

Parameters:

• run_dir (Path)

• config (Config)

• records (list[StepRecord])

Return type:

None

marla.metrics.writer.write_episodes_csv(run_dir, config, episode_summaries, eval_episode_summaries=())

Parameters:

• run_dir (Path)

• config (Config)

• episode_summaries (list[EpisodeSummary])

• eval_episode_summaries (list[EpisodeSummary])

Return type:

None

marla.metrics.writer.write_metadata_json(run_dir, config, resolved_device, start_time, end_time, status)

Parameters:

• run_dir (Path)

• config (Config)

• resolved_device (ResolvedDevice)

• start_time (datetime)

• end_time (datetime)

• status (str)

Return type:

None

marla.metrics.writer.write_run_artifacts(run_dir, config, result, resolved_device, start_time, end_time, status)

Write every spec section 21 artifact this release produces for one run.

Safe to call even when result is None (construction failed before any training happened) – episodes/decisions/updates are then written empty, and metadata.json still records the failure.

Parameters:

• run_dir (Path)

• config (Config)

• result (TrainingResult | None)

• resolved_device (ResolvedDevice)

• start_time (datetime)

• end_time (datetime)

• status (str)

Return type:

None

marla.metrics.writer.write_summary_json(run_dir, episode_summaries, update_metrics, all_records, environment_steps, eval_episode_summaries=())

Parameters:

• run_dir (Path)

• episode_summaries (list[EpisodeSummary])

• update_metrics (list[dict[str, Any]])

• all_records (list[StepRecord])

• environment_steps (int)

• eval_episode_summaries (list[EpisodeSummary])

Return type:

None

marla.metrics.writer.write_updates_csv(run_dir, config, update_metrics)

Parameters:

• run_dir (Path)

• config (Config)

• update_metrics (list[dict[str, Any]])

Return type:

None

Plot generation for marla summarize, from a written run directory’s CSVs.

marla.metrics.plots.generate_plots(run_dir, plots_dir)

Render whichever plots the available CSVs support; returns the files written.

Every plot is independently best-effort: a run with no episodes yet (or metrics.record_decisions: false) still gets whatever plots its data supports, rather than failing the whole command over one missing file.

Parameters:

• run_dir (Path)

• plots_dir (Path)

Return type:

list[Path]