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

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

Total release size: 14.0 MB

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

Download URL losscape_sdk-0.2.2-cp310-abi3-win_amd64.whl
Size 3.1 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
21ff0c924b634e1f7545e9caeaca04db2b726359d32a369bc6d93bba37ee274e
BLAKE2b-256 checksum
How to use checksums
34ffcb2e8c59de4c15a84701803245cbea4affd8216a3e5ca38c2a3784f30447
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.2-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL losscape_sdk-0.2.2-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
356dc0fbe4aeec5f97efba7399169b8cad025417c1e91bebf53df4b255dd9b43
BLAKE2b-256 checksum
How to use checksums
7786dfca4e3fe4a806a5d5aacb0ef374bb1d2d8fd27d8c7cadae70128fbf477c
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.2-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL losscape_sdk-0.2.2-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
18f0ed1c3edd9d30ce98634474165488e4bea0c8540abee7d65815d3a2cd78ab
BLAKE2b-256 checksum
How to use checksums
a23a51ff7c4fa46309c6d7694bb5e449992b67ba890be25397f7cefa8e9db7a0
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.2-cp310-abi3-macosx_11_0_arm64.whl

Download URL losscape_sdk-0.2.2-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
d452cb824c35097f549a787a1b19303aa1f9b792a305534b770d98c17afaae04
BLAKE2b-256 checksum
How to use checksums
a4818f43994b4c29caf3d6da3bc21a39d5c4db5e57f915682d9c903c1b0a5e7f
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.2

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