Getting Started¶

CEMI is designed around a local-first workflow:

Your training or benchmarking script writes run_record snapshots to disk with the Writer.
The local gateway reads those snapshots from the same directory and serves the embedded workspace UI.
cemi verify evaluates a run against a contract and exits with a pass or fail that CI can act on.

Nothing leaves the machine. No cloud sign-up is required for any of this.

Installation¶

From PyPI¶

pip install cemi-cli

From a private release wheel (closed beta)¶

Download the .whl asset from the private GitHub Release and install it directly:

pip install ./cemi-0.1.2-py3-none-any.whl

From source¶

From the cemi repository root:

pip install -e ./cli

With test tooling:

pip install -e "./cli[dev]"

Canonical local workflow¶

1. Instrument your script¶

Explicit lifecycleContext manager (recommended)Launched by cemi start

from cemi.writer import create_writer

writer = create_writer(project="default", log_dir=".cemi")
writer.start_run(name="my-run")

writer.log_parameter(key="batch_size", value=32)
writer.log_metric(name="loss", value=0.42, step=1)
writer.emit_run_record()

writer.end_run(status="succeeded")
writer.emit_run_record()

from cemi.writer import create_writer

writer = create_writer(project="default", log_dir=".cemi")

with writer.run(name="my-run"):
    writer.log_parameter(key="batch_size", value=32)
    writer.log_metric(name="loss", value=0.42, step=1)
    writer.emit_run_record()

The context manager calls start_run() on entry and end_run(status="succeeded") (or status="failed" on exception) on exit.

When your script is launched by cemi start, use create_writer_from_env() instead. It picks up CEMI_PROJECT_ID, CEMI_RUN_ID, CEMI_SAVE_DIR, and CEMI_LOCAL_SERVER_URL that the CLI injects:

from cemi.writer import create_writer_from_env

writer = create_writer_from_env()

with writer.run(name="my-run"):
    writer.log_metric(name="loss", value=0.42, step=1)
    writer.emit_run_record()

2. Start the gateway¶

Use the same log_dir you passed to the Writer:

cemi gateway --save-dir .cemi

3. Open the workspace¶

cemi view

The workspace is served at:

http://127.0.0.1:3141/workspace

4. Verify against a contract (optional)¶

Write a contract.json describing your deployment criteria, then:

cemi verify --contract contract.json --run <run_id>

Exit code 0 means all gates passed. Exit code 1 means at least one gate failed. See Gateway and Contract for the contract schema.

Save directory layout¶

The Writer and gateway must point at the same base directory.

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

The Writer appends run_record snapshots to runs/<run_id>.jsonl on each emit_run_record() call.
add_local_file_artifact() copies files into artifacts/<run_id>/.
The gateway reads runs/*.jsonl and serves artifacts at /api/runs/<run_id>/artifacts/<filename>.

The gateway uses the last valid line in a run file as the current view of that run.

Environment variables¶

Variable	Purpose
`CEMI_SAVE_DIR`	Base directory for `runs/` and `artifacts/`
`CEMI_LOCAL_DIR`	Override just the runs directory
`CEMI_ARTIFACTS_DIR`	Override just the artifacts directory
`CEMI_LOCAL_SERVER_URL`	Gateway base URL (useful when serving on a custom port)
`CEMI_SINK`	Sink mode: `local` or `local+local_server`
`CEMI_PROJECT_ID`	Project ID injected by `cemi start`
`CEMI_RUN_ID`	Run ID injected by `cemi start`

Local data¶

What gets written to disk¶

Run snapshots → save_dir/runs/<run_id>.jsonl
Copied artifacts → save_dir/artifacts/<run_id>/
CLI config → ~/.cemi/config.json
PID files (for cemi stop) → ~/.cemi/pids/

Default locations¶

Project-local data defaults to .cemi/ in the current working directory.
Per-user CLI state lives under ~/.cemi/.

Artifact sensitivity¶

add_local_file_artifact() copies a file into CEMI's artifact store for local serving. Do not attach secrets, credentials, private datasets, or files you would not want duplicated locally.

Gateway bind policy¶

The gateway binds to 127.0.0.1 only. It is a local developer tool, not a shared network service.

Stopping and resetting¶

Stop background processes:

cemi stop

Clear project-local state:

rm -rf .cemi

Clear per-user state:

rm -rf ~/.cemi

Uninstall:

pip uninstall cemi

Troubleshooting¶

No runs appear in the workspace¶

Make sure the Writer log_dir and gateway --save-dir point at the same path.

Artifact URLs return 404¶

If the gateway is not running on port 3141, set CEMI_LOCAL_SERVER_URL before creating artifacts so the generated URLs match the active gateway.

`cemi verify` shows metric not found¶

The gate's metric.name and metric.source must match what the Writer actually emitted. Check your summary_metrics keys or metrics.summary names against the contract gate definition.

Already have a job writing runs¶

Start the gateway separately with the same save directory:

cemi gateway --save-dir /path/to/log_dir
cemi view

Reset a broken local setup¶

cemi stop
rm -rf .cemi (if needed)
rm -rf ~/.cemi (if needed)
Reinstall with pip install cemi-cli