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_checkpointcopies 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=Truehands 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()andcheckpoint(step)use a copy still on this machine, or download it, intocheckpoint-cache/<run id>/<step>underLOSSCAPE_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()andto_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=Trueadds them).min_stepandmax_steplimit the steps. api.run(run_id)gets one run; ids are the oneslsc.init()gives (run.id).run.checkpointslists its checkpoints by step (run.checkpoint(step)for one;api.checkpoint(link)by its link), withstep,size,files,url,importantandexpires_at;checkpoint.download(to, files=...)downloads all of its files or some (checked against their BLAKE3, resuming),set_important()protects it from retention, andcheckpoint.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 syncuploads it. At most ~100 ms of logging is lost onkill -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_tokenorpasswordin 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,
Bearertokens, and assignments likepassword=...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 byrandom.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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.