Skip to content

Run Records

graphids.exp.records owns saved configuration, manifests, lifecycle events and status summaries. New runs save final metrics and failures in schema-2 manifests; resolved-run.yml contains their validated input. Historical schema-1 manifests remain readable.

graphids.exp.tracking derives MLflow exports from current records and reads historical mlflow_ingest.json files. See observability and write paths.

records

Run manifests and event journals.

The goal is to make failure visible without needing Slurm, MLflow, or stderr as the only source of truth.

make_manifest

make_manifest(run: RunConfig) -> RunManifest

Keep historical manifest metadata while storing results in one place.

Source code in graphids/exp/records.py
def make_manifest(run: RunConfig) -> RunManifest:
    """Keep historical manifest metadata while storing results in one place."""
    return RunManifest(
        schema_version=2,
        run_id=run.name,
        name=run.name,
        stage=run.stage,
        git_sha=run.git_sha,
        run_dir=str(run.outputs.run_dir),
        config=dict(
            representation_cfg=asdict(run.representation_cfg),
            payload=run.payload.model_dump(mode="json"),
            resources=run.resources.model_dump(mode="json"),
        ),
        outputs=dict(
            journal_dir=str(run.outputs.journal_dir()),
            manifest=str(run.outputs.manifest_path()),
            events=str(run.outputs.events_path()),
            artifact_dir=str(run.outputs.artifact_path()),
            checkpoint_dir=str(run.outputs.checkpoint_path()),
        ),
    )

record_status

record_status(run: RunConfig, status: str, *, result: Mapping[str, Any] | None = None, failure: str | None = None, message: str | None = None, tracking_mode: str | None = None) -> RunManifest

Publish authoritative status/results atomically, then append a history event.

Source code in graphids/exp/records.py
def record_status(
    run: RunConfig,
    status: str,
    *,
    result: Mapping[str, Any] | None = None,
    failure: str | None = None,
    message: str | None = None,
    tracking_mode: str | None = None,
) -> RunManifest:
    """Publish authoritative status/results atomically, then append a history event."""
    manifest = load_manifest(run.outputs.run_dir, name=run.outputs.manifest_name)
    if manifest is None:
        manifest = make_manifest(run)
    changes = dict(schema_version=2, status=status, failure=failure)
    if tracking_mode is not None:
        changes["tracking_mode"] = tracking_mode
    if result is not None:
        changes.update(
            metrics=dict(result.get("metrics", {})),
            result={key: value for key, value in result.items() if key != "metrics"},
        )
    manifest = manifest.model_copy(update=changes)
    write_manifest(run.outputs.run_dir, manifest, name=run.outputs.manifest_name)
    append_event(
        run.outputs.run_dir,
        EventRecord(
            status=status,
            stage=run.stage,
            message=message or f"run_{status}",
            details={"failure": failure} if failure else {},
        ),
        name=run.outputs.events_name,
    )
    return manifest

write_config

write_config(run: RunConfig) -> Path

Save the resolved input once; mutable execution state lives in the manifest.

Source code in graphids/exp/records.py
def write_config(run: RunConfig) -> Path:
    """Save the resolved input once; mutable execution state lives in the manifest."""
    path = run.outputs.run_dir / "resolved-run.yml"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(yaml.safe_dump(run.model_dump(mode="json"), sort_keys=False))
    return path