Gateway and Contract¶

The local gateway and the run contract are what make the local-first CEMI workflow work reliably across the CLI, Writer, workspace UI, and external training repositories.

Gateway responsibilities¶

The local gateway:

reads run snapshots from save_dir/runs/*.jsonl
serves the embedded workspace UI at /workspace
serves local artifacts from save_dir/artifacts/<run_id>/...
exposes read APIs for projects, runs, params, metrics, health, and contract evaluation
accepts live run_record events at POST /api/events

Start it with:

cemi gateway --save-dir .cemi

For the closed beta, the gateway should stay bound to 127.0.0.1 only. It is a local developer tool, not a shared network service.

Save directory layout¶

save_dir/
  runs/
    <run_id>.jsonl
  artifacts/
    <run_id>/
      <filename>

The Writer and gateway must point at the same save_dir.

What gets written to disk¶

The local workflow writes:

run snapshots to save_dir/runs/<run_id>.jsonl
copied artifacts to save_dir/artifacts/<run_id>/
local CLI config to ~/.cemi/config.json
PID files used by cemi stop to ~/.cemi/pids/

If you do not pass a custom save directory, the default project-local location is .cemi/ in the current working directory.

Key endpoints¶

Endpoint	Purpose
`GET /workspace`	Serve the embedded workspace SPA
`GET /api/health`	Report gateway health, mode, port, and active save directory
`GET /api/projects`	Discover projects from run files on disk
`GET /api/projects/<project>/runs`	List project runs
`GET /api/runs/<run_id>`	Return a normalized run snapshot
`GET /api/runs/<run_id>/metrics`	Return metric points, optionally filtered
`GET /api/runs/<run_id>/params`	Return run parameters
`GET /api/runs/<run_id>/artifacts/<name>`	Download a stored artifact
`POST /api/events`	Append a `run_record` event to a local JSONL file

Artifact sensitivity¶

Artifacts may include model binaries, checkpoints, evaluation reports, exported graphs, or copied local files. Treat artifact registration as local publication through the gateway-backed workspace UI. Do not attach secrets, credentials, private datasets, or files you do not want copied into the CEMI artifact store.

Event model¶

Each line in runs/<run_id>.jsonl is a run_record event. The current local contract uses schema version 2.0 and stores a complete run snapshot in payload.

Minimal shape:

{
  "type": "run_record",
  "schema_version": "2.0",
  "payload": {
    "run_id": "local-123",
    "project": "default",
    "name": "baseline",
    "stage": "default",
    "status": "running",
    "created_at_ms": 1730000000000,
    "context": {},
    "metrics": {
      "events": [],
      "summary": []
    },
    "artifacts": []
  }
}

Contract rules¶

The supported local contract is intentionally strict:

One run file per run id
One JSON object per line
Every emit_run_record() call appends a complete snapshot
The gateway uses the last valid run_record as the current view of a run
Project discovery is derived from run files, not from a separate registry

Compatibility behavior¶

The gateway includes compatibility logic so older UI expectations still work:

v2 payload.metrics.events is flattened into run.metrics
summary_metrics is reconstructed from summary metric entries when needed
tags are normalized to a list of key/value pairs for the UI
artifacts are normalized so relative URIs still resolve through the gateway

Health and workspace behavior¶

When the workspace points at the local gateway, GET /api/health responds with a payload like:

{
  "status": "ok",
  "mode": "local",
  "save_dir": "/path/to/.cemi",
  "port": 3141
}

This lets the workspace skip the hosted login flow and go directly to the local workspace experience.

Browser behavior¶

cemi view starts the gateway and opens a browser automatically.
cemi start opens a browser automatically before launching the tracked command.
cemi gateway serves the API and workspace but does not open a browser by itself.