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.1

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.1
File Actions
losscape_sdk-0.2.1-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for losscape_sdk-0.2.1-cp310-abi3-win_amd64.whl
losscape_sdk-0.2.1-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for losscape_sdk-0.2.1-cp310-abi3-manylinux_2_28_x86_64.whl
losscape_sdk-0.2.1-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for losscape_sdk-0.2.1-cp310-abi3-manylinux_2_28_aarch64.whl
losscape_sdk-0.2.1-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for losscape_sdk-0.2.1-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 14.0 MB

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

Download URL losscape_sdk-0.2.1-cp310-abi3-win_amd64.whl
Size 3.1 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
1dbfebddd5f0d69c33ac90ab8d1bddb483f16ef0bd7c294f0185296c46dbf13c
BLAKE2b-256 checksum
How to use checksums
6814b9239be696eae70d380ab5b6cf179901cf5325b6c22f38051c8c51fb490f
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 16, 2026.

Transparency log

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

Download URL losscape_sdk-0.2.1-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
54c1d1975b16e6fea50283573a72f44e3b5dcea43195b5c1e3c5f5242e1ca4b7
BLAKE2b-256 checksum
How to use checksums
cf884e58402652944822099cbd34a2089617f885a3a27decfb3beda1af43c34a
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 16, 2026.

Transparency log

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

Download URL losscape_sdk-0.2.1-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
85c99e9ee114acfe3088fa5d2ebfd30a4088773dcacfb873f0fb2645b38d888f
BLAKE2b-256 checksum
How to use checksums
9236e518713b3f087ace678c24bd0b2535aaa15630cac489f41fe3af9c13ba6b
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 16, 2026.

Transparency log

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

Download URL losscape_sdk-0.2.1-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
43ee203574339dcb8263d6b8108f8a80f106c835bc9a1a6855fd0ed0e01c4f14
BLAKE2b-256 checksum
How to use checksums
05c74a7deae28ef82038b8f42c0b1b5e136fe52708b67f1e308929b74ffa99c9
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 16, 2026.

Transparency log

Security for losscape-sdk 0.2.1

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.1-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 16, 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