Quickstart

Simpcat ships as a single package that includes both the Python SDK and the simpcat CLI.

1. Install

Install simpcat into the same Python environment where your training code runs:

pip install simpcat

This gives you:

• The Python SDK (import simpcat) for logging metrics and media from training code
• The simpcat CLI for authentication, offline sync, and data queries

2. Create an API key and log in

Create an API key in the Simpcat web UI under Settings → API Keys, then run:

simpcat login

simpcat login prompts for the key, verifies it with the server, and stores it per host in ~/.simpcat/config.toml.

If you want to pass the key directly:

simpcat login --key sk-your-api-key

3. Log your first run

import simpcat

# Initialize a run
run = simpcat.init(project="my-project", name="first-run")

# Log some metrics
for step in range(100):
    loss = 1.0 / (step + 1)
    simpcat.log({"loss": loss, "step": step})

# Finish the run
simpcat.finish()

That’s it. Open the Simpcat web UI to see your run’s charts.

What happens under the hood

1. simpcat.init() creates a local runtime directory at .simpcat/run-{timestamp}-{local-id}/
2. A reporter process starts in the background for this run
3. simpcat.log() sends metrics over a Unix socket to the reporter (non-blocking)
4. The reporter batches metrics and flushes them to the server
5. simpcat.finish() signals the reporter to upload final data and shut down

You do not normally run the reporter directly. simpcat.init() starts it for each run, and it inherits the environment of the training process that launched it.

If you set runtime environment variables before starting training, they apply to the spawned reporter too. For example, SIMPCAT_MODE=offline makes the run write locally for later simpcat sync, and SIMPCAT_LOG_FILTER=debug increases reporter log verbosity. See Environment Variables.

With config

Pass hyperparameters via config= to track them alongside metrics:

run = simpcat.init(
    project="my-project",
    config={"lr": 3e-4, "batch_size": 32, "epochs": 10},
)

# Config is also accessible as run.config
print(run.config["lr"])  # 3e-4

# Update config later
run.config["early_stop"] = True

As a context manager

The run auto-finishes when the block exits. If an exception occurs, the run is marked as "failed".

with simpcat.init(project="my-project") as run:
    for epoch in range(10):
        simpcat.log({"epoch": epoch, "loss": compute_loss()})

Auto-expiring runs

Use auto_expire_seconds for test runs that should be automatically cleaned up:

simpcat.init(project="my-project", auto_expire_seconds=3600)

Auto-expiring runs are automatically deleted after the specified number of seconds.