Run

Run(
    project: str,
    name: str | None = None,
    config: dict[str, Any] | None = None,
    auto_expire_seconds: int | None = None,
    tags: dict[str, str] | None = None,
    notes: str | None = None,
    group: str | None = None,
    job_type: str | None = None,
    system_metrics: bool = True,
    system_metrics_interval: float = 15.0,
    capture_output: bool = False,
    resume: str | bool | None = None,
    dir: str | os.PathLike[str] | None = None,
    fork_from: str | None = None,
    fork_step: int | None = None
) -> None

Manages a single training run’s connection to the simpcat reporter.

Provides the core wandb.Run-like interface: log(), finish(), config, summary, context manager.

Run identity is the canonical run ID. With default resume="auto" semantics, SimpCat stores that ID in run.json under the run-data directory and reuses it for later runs that use the same directory. The default run-data directory is ./.simpcat; an explicit dir uses dir/simpcat.

Properties

• id — Run ID.
• name — Display name. Writable — setting it updates the server.
• tags — Tags dict. Writable — assign a dict to update.
• notes — Free-text notes. Writable.
• project — Project name.
• group — Group name.
• job_type — Job type label.
• step — Current global step counter.
• dir — Path to the run directory.
• url — URL to the run page on the web UI.
• resumed — Whether this run was resumed from a previous run.
• config
• summary

Methods

log['(', ' data: dict[str, Any],', ' step: int | None = None,', ' commit: bool | None = None', ') -> None']

Log metrics and/or media. Matches wandb.log() interface.

Never raises once training is underway: simpcat must not crash a long-running job over a data problem. Mid-run issues (non-Float32 values, bad steps, unsupported types, invalid histograms) degrade to a once-per-problem warning plus a run diagnostic, dropping or clamping only the offending data.

• data — Dict of metric names to values (scalars, Histogram, Audio, Image, or lists of media objects).
• step — Explicit step. If None, uses auto-incrementing counter.
• commit — Controls when metrics are flushed. None (default) means True when step is None, False when step is provided. True flushes all buffered and current metrics and advances the step counter. False buffers scalars until the next commit=True call (a new step auto-flushes the buffered one). Media is sent immediately regardless.

define_metric['(', ' name: str,', ' step_metric: str | None = None,', ' summary: str | None = None,', ' **kwargs: Any', ') -> None']

Define metric metadata (custom x-axis, summary aggregation).

• name — The metric name (e.g., “val_loss”).
• step_metric — Another metric to use as x-axis (e.g., “epoch”).
• summary — Aggregation type for run summary: “min”, “max”, “last”, “mean”, or “best” (resolves to min/max based on goal).

finish["(status: str = 'finished', user_payload: Any | None = None) -> None"]

Finish the run, flush remaining data, and shut down the reporter.

Safe to call multiple times. Also registered with atexit so it runs automatically on process exit.

• status — Final status label. Supported values: “finished”, “failed”, “crashed”, or “killed”.
• user_payload — Optional structured metadata attached to the stop event.