Skip to main content

Kalanos

Kalanos: understand your robot data before you train. Local by default, open source, HTML and JSON reports.

PyPI Python CI License

Understand your robot data before you train.

Kalanos is an open-source toolkit for robotics engineers and researchers inspecting recorded demonstrations. Find evidence of dropped samples, flatlined signals, timing irregularities and missing data; review results by episode, stream or channel; and bring repeatable checks into your training workflow.

Local by default · Apache-2.0 · HTML for investigation · JSON for automation

Run the quickstart · Explore a public report · GitHub Action · Training integrations · Browse datasets · Website

From recordings to evidence

Workflow: choose recordings, run an assessment, inspect findings and coverage, then use HTML or JSON reports in optional CI and tracking workflows.

  • Before training: inspect a collection batch and locate episodes or channels worth reviewing.
  • During dataset development: rerun the same checks as recordings change, and gate your pipeline on configured episode decisions.
  • Alongside experiments: retain the dataset assessment with the training run so collaborators can inspect the evidence behind the input data.

A score is one part of the assessment. Read the findings, episode decisions, measured coverage and evaluation scope together. A passing decision can still have report-only findings; readiness can be unavailable when evidence does not support a value.

pip install kalanos
kalanos grade my_recordings/ --report report.html

Grading runs in your environment. Nothing is uploaded unless you choose to publish. For a version-pinned, previously verified example, use the quickstart below.

Reads out of the box: CSV, JSON, JSONL, delimited text, LeRobot directories. With extras: HDF5, MCAP / ROS 2, Hugging Face datasets, sampled video checks. See Install extras.

Kalanos report summary for the sample fixture: readiness 61.4, one eligible recording and six findings

Recorded example from Kalanos 0.8.0: a synthetic fixture scores 61.4, with 1 of 1 episodes eligible under numeric-core-v1. Sufficiency is unknown. This illustrates the report, not training performance or the expected output of another version.

Choose your workflow

Your goal Start here
Inspect your own robot recordings Local quickstart, followed by your own data
Run dataset checks in CI Kalanos Robotics Dataset Audit Action. Runs the public grader on your runner, without MCP. Configure gates and review artifact retention for private data.
Keep assessments next to training curves Kalanos tracking adapters for W&B, MLflow, Trackio and TensorBoard. These attach existing assessments to runs; they do not replace the grader.
Explore existing public assessments Kalanos Hub. Start with a PushT report and inspect its recorded revision and scope.
Use public report evidence in agent and LeRobot workflows Kalanos MCP integrations. These consume stored Hub assessments and support pinned episode selections; they are not a local grading server.

Choose what fits your workflow; no integration is required to run the local grader. Sending reports to a hosted tracker or publishing them is a separate sharing decision. Review the report for private paths, instructions and diagnostic evidence first.

Try a notebook in Colab

Open in Colab

Run a dataset audit in Google Colab. No local installation is required. The notebook installs Kalanos 0.10.0 in the Colab kernel, downloads the public lerobot/aloha_sim_transfer_cube_human dataset, grades it, charts the signal it sends episodes to review for, and offers the JSON and HTML reports as a download. It is separate from the local quickstart below.

To audit a real recording, the Cube to Bowl notebook grades a pinned commit of the public triton7777/cube_to_bowl_so100 SO-100 dataset and shows the episode it sends to review. Open Cube to Bowl in Colab

Notebook instructions

Quickstart

Requires Python 3.10+. This walkthrough uses the released 0.8.0 package and a small official sample. No clone, account, API key or model service is needed.

python3 -m venv .venv
source .venv/bin/activate

python -m pip install "kalanos==0.8.0"
python -m pip show kalanos

python -c "from urllib.request import urlretrieve; urlretrieve('https://raw.githubusercontent.com/KalanosAI/kalanos/v0.8.0/tests/fixtures/arm_multi_device.csv', 'arm_multi_device.csv')"

kalanos grade arm_multi_device.csv --report report.html
kalanos grade arm_multi_device.csv --report report.json
kalanos inspect report.json

Open report.html in your browser. kalanos inspect prints a terminal summary of a saved JSON report.

Windows (PowerShell)
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, call .\.venv\Scripts\python.exe and .\.venv\Scripts\kalanos.exe directly instead of python and kalanos. The remaining commands are the same.

The sample is a synthetic test fixture: four interleaved arm streams with a flatlined channel, dropped samples and clock jitter, treated as one episode. It demonstrates parsing and findings, not detection accuracy or training performance. See the fixture description.

What you should see

Assessment  Ready
Readiness   61/100
Episodes    1 - eligible 1 - review 0 - blocked 0 - unknown 0
Scope       numeric-core-v1

Flagged channels
  low signal-to-noise  5 of 11 channels  1 episode  Integrity
  repeated values      1 of 12 channels  1 episode  Integrity

Both commands exit 0. The JSON records readiness 61.44832235703186, a complete inventory and one pass episode. The flatlined armB z channel and five low signal-to-noise channels are report-only findings under this scope — a passing episode can still have quality problems worth inspecting before selection.

Expanded recording view showing score 61.4 and the armA pose stream at 97.2 with recorded timing metrics

Detail view: the recording scores 61.4 while the expanded armA stream scores 97.2. Cadence is shown as recorded (100 Hz); clock provenance is unknown, so this is not a capture-timing certification. Dashes mean not applicable or no evidence, not a pass.

The full downloadable HTML report and JSON report from this run are included, generated with a clean install of 0.8.0 on macOS ARM64 / Python 3.14.7. Download the HTML file and open it in a browser; GitHub shows its source rather than a rendered report. The screenshots above provide an immediate preview.

Reading a decision

Read scores, episode decisions and coverage together. Missing evidence is not a pass and a pass can still have findings.

Episode decision Meaning under the selected scope Next action
pass (shown as eligible in terminal output) Required evidence is sufficient; no blocking or review decision remains Inspect report-only findings and confirm the scope fits your use
blocked A finding has an authorized blocking consequence Fix or exclude the episode, then rerun
review A finding needs a decision or supporting validation Review the evidence and resolve it before selection
unknown Required evidence is missing or unavailable Supply the needed data, mapping or dependency, then rerun

Readiness combines passing-episode quality with the passing share; blocked episodes contribute zero. It can be undefined when review or unknown decisions, or an incomplete inventory, prevent a supported whole-dataset value — read the reported reason rather than treating undefined as zero or as a pass. Full semantics: docs/DECISIONS.md.

Audit your own recordings

kalanos grade recording.csv --report recording.html
kalanos grade dataset/ --report dataset.json     # directories are walked recursively
kalanos grade dataset/ --report dataset.compact.json --compact   # short key aliases: a smaller file, for machines
kalanos profiles list                            # available evaluation scopes
kalanos adapters                                 # available readers

Start with a small local subset, check the inventory and skipped files, and pick a scope that matches your intended use. Typical uses: triaging a recording batch, investigating a sensor channel, or reviewing a vendor delivery. Compare runs only when scope and recorded identities are compatible.

Install extras

Need Install
HDF5 reader python -m pip install "kalanos[hdf5]==0.8.0"
MCAP / ROS 2 reader python -m pip install "kalanos[mcap]==0.8.0"
Hugging Face access python -m pip install "kalanos[hf]==0.8.0"
Optional numeric diagnostics python -m pip install "kalanos[numeric]==0.8.0"
Sampled video checks, including LeRobot video python -m pip install "kalanos[video]==0.8.0"
All extras python -m pip install "kalanos[all]==0.8.0"

A missing reader dependency prevents loading that format. A missing optional check is reported as unavailable; if the scope requires its capability, the missing evidence can make an episode unknown. Installing an extra does not change what a scope requires. See metrics, profiles, adapters and diagnostics.

Gate a CI pipeline

kalanos grade dataset/ --report audit.json --fail-on blocked,review,unknown
Exit code Meaning
0 The configured gate did not fail
1 The gate failed
2 Invalid configuration or operational failure

The default gate is blocked,unknown; add review when reviews must be resolved before merge. An incomplete inventory also fails when unknown is included. This gate is a status gate, not a minimum-score threshold — the sample fixture still exits 0 under blocked,review,unknown because its findings are report-only.

Local by default

Grading and report generation run entirely on your machine with no model API. The network is used only to install packages, fetch the public sample, or read remote sources you point Kalanos at; --max-remote-gb and --max-remote-files bound remote discovery. Start small rather than scanning a large remote dataset on a first run.

Publishing is opt-in. kalanos grade --publish or kalanos publish REPORT.json sends a report to your authenticated account on hub.kalanos.ai; it needs a Hub API key, and local datasets need a name. Report files can contain source paths, task instructions and diagnostic evidence — treat them as data and review them before sharing.

What Kalanos does and does not tell you

Kalanos reports technical recording quality within the evidence and scope available. It does not establish task success, dataset representativeness, robot safety, or any training-performance guarantee.

  • A pass means required evidence was sufficient under the scope, not that the recording is free of problems — read report-only findings.
  • Timing interpretation depends on clock provenance. Unknown provenance means recorded cadence is reported, not certified.
  • Sampled video checks do not inspect every frame by default.
  • Statistical findings may require review or accepted validation before they can block an episode.
  • The macOS commands above are tested; Linux and Windows variants follow the same CLI but were not separately verified for this release.

Help improve robotics data checks

Contributions are useful beyond code: share a minimal reproducible fixture, report a false positive or missed issue, improve an adapter, or document a workflow. Include the grader version, dataset format, evaluation scope and expected versus observed behavior. Do not attach private recordings or sensitive report contents to a public issue.

Contribution guide · Report an issue · Citation metadata

Documentation and support

Changelog · PyPI · Report schema · Decisions · Architecture · Contributing · Security · Issues

Reproducibility: the sample run's metadata and exit codes, resolved dependencies and verification notes are included.

Licensed under Apache-2.0.

Metadata

Release files for kalanos 0.10.1

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

Source distribution (sdist)

Source distribution for kalanos 0.10.1
File Size Uploaded Provenance Actions
kalanos-0.10.1.tar.gz 1.2 MB With provenance Details for kalanos-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kalanos 0.10.1
File Interpreter ABI Platform Actions
kalanos-0.10.1-py3-none-any.whl Python 3 none any Details for kalanos-0.10.1-py3-none-any.whl

Total release size: 1.8 MB

Release files / kalanos-0.10.1.tar.gz

Download URL kalanos-0.10.1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
6506b1676d76ab68e395d948cde0a85a4567c5195ec45b1607a9a1346ffbb845
BLAKE2b-256 checksum
How to use checksums
f06bc12efb85c0d742c8904ca40fe10f35ba6fc2a931ca6f1ad190d15cd565a2
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 19, 2026.

Transparency log

Release files / kalanos-0.10.1-py3-none-any.whl

Download URL kalanos-0.10.1-py3-none-any.whl
Size 532.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e2fa871eb00436694fb58950ac412d38e0b8d42b61ccdc760a0f649bf98964c
BLAKE2b-256 checksum
How to use checksums
18a3896c7aee70a04140f5997c0a5bdea1a5b801848147fe0cbe8ae0db5567f8
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 19, 2026.

Transparency log

Security for kalanos 0.10.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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kalanos-0.10.1.tar.gz

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 19, 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