Skip to main content

losscape Python SDK

Install it with pip install losscape-sdk, and import it as lsc. The package named plain losscape is an unrelated project.

import lsc

with lsc.init(project="mnist", config={"lr": 1e-3, "batch_size": 64}) as run:
    for step in range(10_000):
        loss = train_step()
        run.log({"train/loss": loss, "lr": scheduler.get_last_lr()[0]})
        if step % 1000 == 0:
            run.log({"val": {"loss": val_loss, "acc": val_acc}}, step=step)  # -> val/loss, val/acc
    run.summary["best_acc"] = best_acc

The API follows Weights & Biases: init, log (with step / commit), config, summary, finish, context manager, lsc.log(...) on the current run.

The project must exist: create it in the web UI (New project) and be its owner or an editor. A run logged to an unknown project is refused by the server; its data stays in the local log, so losscape sync uploads it once the project is created.

Checkpoints

Save a checkpoint however you like, then log the folder (or a single file): it uploads in the background, beside the metrics, which never wait for it.

torch.save(model.state_dict(), "ckpt/model.pt")
torch.save(optimizer.state_dict(), "ckpt/optim.pt")
run.log_checkpoint("ckpt/")  # at the step last logged; or step=...

# Resuming, after a preempted job:
run = lsc.init(project="mnist", id=run_id, resume=True)
if (ckpt := run.latest_checkpoint()) is not None:  # a local folder, or None
    model.load_state_dict(torch.load(ckpt / "model.pt"))
  • log_checkpoint copies the folder into the run's local log before returning, so the next save can overwrite it at once (instant on btrfs and XFS). move=True hands it over instead.
  • Files upload in parts of 16 MiB, compressed with zstd when that saves at least 5% (configs, mostly-zero tensors), each part checked on arrival. An interrupted upload resumes where it stopped, with the run or with losscape sync; the local copy is deleted once uploaded.
  • finish() waits for checkpoints as long as they make progress, printing it.
  • One checkpoint per step: the server refuses another at the same step (it stays in the local log, with why). Delete checkpoints with checkpoint.delete().
  • latest_checkpoint() and checkpoint(step) use a copy still on this machine, or download it, into checkpoint-cache/<run id>/<step> under LOSSCAPE_DIR, kept until you delete it.
  • The server must have checkpoint storage (LOSSCAPE_STORAGE, see docs/DEPLOYMENT.md).

Each checkpoint has a link of its own through the server, whatever the storage behind it (copy it from the run's Checkpoints tab): the whole checkpoint as a tar archive, and <link>/<path> one file, with HTTP ranges so downloads resume.

ckpt = lsc.Api().checkpoint("https://losscape.example.com/ckpt/01a1e101-…")
ckpt.download(files="model.pt")  # resumes an interrupted download, checks the BLAKE3
ckpt.set_important()  # never deleted by the project's retention
curl -H "Authorization: Bearer $LOSSCAPE_API_KEY" https://losscape.example.com/ckpt/01a1e101-… | tar -x

Projects keep checkpoints until they're deleted, or for a number of days (project settings), except the ones marked important and, if chosen, each run's last one and its best one by a metric.

Reading runs back

lsc.Api() reads what the server stored, for analysis in scripts and notebooks. It connects like lsc.init() does: LOSSCAPE_SERVER and LOSSCAPE_API_KEY, or lsc.Api(server, api_key).

import lsc

api = lsc.Api()
runs = api.runs("mnist")  # newest first; api.runs(..., archived=True)
best = max(runs, key=lambda r: r.summary.get("val/acc", 0))
print(best.name, best.config["lr"], best.state)

table = runs.to_pandas()  # one row per run: config.* and summary.* columns
df = best.history(["train/loss", "val/acc"])  # step column, one column per metric
for point in best.scan_history("train/loss"):  # streamed: metric, step, time, value
    ...
  • history() and to_pandas() need pandas: pip install 'losscape-sdk[pandas]'. The rest needs nothing beyond Python.
  • History has every logged point, not the downsampled ones the charts draw. Steps where a metric wasn't logged are NaN; history(..., wide=False) gives one row per point instead.
  • Without keys, history has every metric of the run except system metrics (system=True adds them). min_step and max_step limit the steps.
  • api.run(run_id) gets one run; ids are the ones lsc.init() gives (run.id).
  • run.checkpoints lists its checkpoints by step (run.checkpoint(step) for one; api.checkpoint(link) by its link), with step, size, files, url, important and expires_at; checkpoint.download(to, files=...) downloads all of its files or some (checked against their BLAKE3, resuming), set_important() protects it from retention, and checkpoint.delete() deletes it.
  • Metrics as logged: renames and computed metrics of the web UI aren't applied.

How it works

  • log() appends to an in-memory buffer (~1 µs for 20 metrics) and never touches the network.
  • A Rust background thread writes the buffer every 100 ms as one batch to a local log (.losscape/runs/<run id>/) and uploads from there, retrying until the server confirms.
  • Killed process, server down, offline mode: the data stays in the local log. losscape sync uploads it. At most ~100 ms of logging is lost on kill -9.

Also recorded with every run: console output (what the process and its subprocesses print, progress bars kept as one line), system metrics, and the environment (git commit and uncommitted diff, command line, hostname, selected environment variables, untracked file names, packages, OS, CPU, GPUs and driver, Slurm job, container).

Secrets

Everyone with access to a project can read what its runs record, so before anything is written to the local log or uploaded, what looks like a secret is replaced by ***:

  • strings under names like api_key, hf_token or password in the config, summary and environment variables, and everything inside an object with such a name;
  • anywhere, including console output and the git diff: well-known kinds of credentials (GitHub, OpenAI, Hugging Face, AWS, Slack, GitLab, PyPI and losscape keys, JSON web tokens), passwords in URLs, Bearer tokens, and assignments like password=... or "api_key": "...".

This only catches what can be recognized: a password printed on its own looks like any other word, and a secret in a file you changed is uploaded unless it has one of these shapes. If that matters for a run, turn off what you don't want recorded: git_diff=False, console=False. Metric names aren't checked.

The local log (.losscape/) is readable only by you on Linux and macOS, for what's created from this version on. If a folder above it was already there, it keeps its permissions.

Settings

Argument Environment Default
project LOSSCAPE_PROJECT uncategorized
mode LOSSCAPE_MODE online (offline, disabled)
dir LOSSCAPE_DIR ./.losscape
server LOSSCAPE_SERVER http://localhost:8080
api_key LOSSCAPE_API_KEY required online: create one in the web UI, Settings > API keys
console LOSSCAPE_CONSOLE on: stdout and stderr are recorded (off on Windows and in Jupyter)
git_diff LOSSCAPE_GIT_DIFF on: uncommitted changes are recorded (whether there are any always is)
code_dir LOSSCAPE_CODE_DIR where the code's git repository is: the working directory, or the main script's folder if that isn't in one
system_metrics LOSSCAPE_SYSTEM_METRICS on: CPU, memory, disk, network, NVIDIA GPUs
LOSSCAPE_SYSTEM_INTERVAL 5 s
finish(timeout=) LOSSCAPE_FINISH_TIMEOUT 60 s
LOSSCAPE_SILENT=1 print nothing

Other things

  • lsc.utils.random_name() -> brave-falcon-42 (not affected by random.seed).
  • lsc.init(id=..., resume=True) continues a run where it stopped.
  • Forked children (e.g. DataLoader workers) can't log to the parent's run; their calls are ignored with a warning.

Development

uv sync                                    # builds the Rust core in place
uv run pytest                              # unit tests
uv run python benchmarks/bench_log.py      # log() latency

Metadata

Release files for losscape-sdk 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for losscape-sdk 0.2.0
File Actions
losscape_sdk-0.2.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for losscape_sdk-0.2.0-cp310-abi3-win_amd64.whl
losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_x86_64.whl
losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_aarch64.whl
losscape_sdk-0.2.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for losscape_sdk-0.2.0-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 14.0 MB

Release files / losscape_sdk-0.2.0-cp310-abi3-win_amd64.whl

Download URL losscape_sdk-0.2.0-cp310-abi3-win_amd64.whl
Size 3.1 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
90e1ab3d2737ed0d9ad288422727eec76ea0f18502d55bc6758c7c31b113f8fd
BLAKE2b-256 checksum
How to use checksums
09f1c792e55b82b0ae1a62c62a40ce32a545c1d523d6053dcf880833bf849c00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_x86_64.whl
Size 3.8 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
4a16af6a16e08005f4b5b0044002d6416c378e9525fc9a226063e65306c7d6ce
BLAKE2b-256 checksum
How to use checksums
271d82cdb8f367b95626d8e37574e8c95799e66fc2bda4098f4776f17c5a0ce8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL losscape_sdk-0.2.0-cp310-abi3-manylinux_2_28_aarch64.whl
Size 3.7 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
20de559cd275328cd772184897b946d4f7df4517def6aae561578f27e0c7ac5b
BLAKE2b-256 checksum
How to use checksums
8ff3583eb30d192525ef4073cde000a0e6951f791c9fbd269bcf09c2acb6313f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / losscape_sdk-0.2.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL losscape_sdk-0.2.0-cp310-abi3-macosx_11_0_arm64.whl
Size 3.3 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
7d186a5ee643015020ec980f9b2e9f28eba22acb4d8bf82a2b956aa8deb66ad1
BLAKE2b-256 checksum
How to use checksums
a0c12f4238f2c8195956d7e665ecaaa1f89e4ff99fa9645652c99da8dc104bec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for losscape-sdk 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for losscape_sdk-0.2.0-cp310-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page