{"slug": "physlint-deterministic-integrity-checks-for-physical-ai-data", "title": "Physlint – deterministic integrity checks for physical-AI data", "summary": "Physlint, an open-source tool for deterministic integrity checks of physical-AI datasets, released version 0.1.0a1 with a LeRobot Dataset v3.x adapter, offering 17 default rules that detect defects like malformed manifests, reordered clocks, and frozen cameras before robot data reaches training. The tool runs locally without network requests, outputs stable JSON reports, and returns CI-safe exit codes, with a public release gate pinning exact dataset revisions and checksums.", "body_md": "Local-first, deterministic validation for physical-AI recordings and robot-learning datasets.\n\n[Quickstart](#quickstart) · [Demo](#see-it-catch-a-real-defect) · [Rules](#what-physlint-checks) · [Evidence](#reproducible-public-data-evidence) · [Roadmap](#format-roadmap) · [Contributing](#contributing)\n\nPhyslint finds concrete integrity defects before robot data reaches training. It explains the impact, identifies the affected episode and stream, recommends remediation, writes a stable JSON report, and returns a CI-safe exit code.\n\nThe `0.1.0a1`\n\npublic alpha ships with a publicly validated **LeRobot Dataset v3.x** adapter. The engine is designed to grow into recording and dataset profiles for MCAP/ROS 2, Robomimic HDF5, RLDS/TFDS, and other physical-AI formats without pretending those adapters already exist.\n\nImportant\n\nPhyslint validates configured data-integrity contracts. A pass does not certify policy quality, task success, or robot safety.\n\n**Catch failures before GPU time:** malformed manifests, broken episode ranges, reordered clocks, missing values, corrupt video, frozen cameras, and black frames become actionable findings.**Keep robot data local:**`physlint check`\n\nperforms no network requests and never modifies its source dataset.**Get evidence, not a mystery score:** every finding includes a stable rule ID, severity, source location, observed condition, expected condition, impact, and remediation.**Use it in CI:** deterministic execution, versioned JSON, atomic report writes, strict configuration, and documented exit codes.**Trust scoped claims:** the public release gate pins exact dataset revisions and commits sanitized reports, corruption recipes, checksums, and publication metrics.\n\nPhyslint requires Python 3.11 or newer.\n\n```\npython -m pip install \"physlint[video]==0.1.0a1\"\n```\n\nTo test the exact tagged source instead of the PyPI distribution, install the GitHub release directly:\n\n```\npython -m pip install \"physlint[video] @ git+https://github.com/pranayjoshi/physlint.git@v0.1.0a1\"\nphyslint inspect /path/to/lerobot-dataset\nphyslint check /path/to/lerobot-dataset\n```\n\nWrite JSON to an exact destination:\n\n```\nphyslint check /path/to/lerobot-dataset \\\n  --output json \\\n  --json-output artifacts/physlint-report.json\n```\n\nThe source remains untouched. Exit code `0`\n\nmeans the configured contract passed; `1`\n\nmeans validation completed with a blocking finding.\n\nThese captures use the pinned Panda source from the release gate. The second dataset is a fully dereferenced copy with one deterministic NaN injected at episode 0, sample 5, state dimension 0.\n\n| Clean pinned snapshot | Controlled NaN corruption |\n|---|---|\n\nPhyslint owns NaN and infinity semantics in `numeric.finite_values`\n\n; the same sample is not duplicated as a missing-stream finding.\n\nSeventeen deterministic rules are enabled by default:\n\n| Area | Checks |\n|---|---|\nManifest |\nRequired files, declared/stored schema agreement, required streams, and feature shapes |\nEpisodes |\nUnique identifiers, positive lengths, non-overlapping boundaries, and stored-row agreement |\nTemporal |\nStrictly monotonic timestamps, FPS cadence, FPS-aware maximum gaps, complete stream overlap, and observation/action delay when independently timestamped |\nNumeric |\nNaN/Inf, configured physical bounds, and configured discontinuity limits |\nVideo |\nComplete decode, motion-aware frozen-frame runs, and grouped black/near-empty frames |\n\nList or explain the installed rule contract:\n\n```\nphyslint rules\nphyslint rules --json\nphyslint explain temporal.max_gap\nphyslint explain video.frozen_frames\n```\n\nRules whose required inputs are unavailable return `not_run`\n\nwith a reason; they are never misreported as passed. Robot-specific bounds and discontinuity checks stay `not_run`\n\nuntil the user supplies meaningful thresholds.\n\nRead the complete [MVP rule specifications](/pranayjoshi/physlint/blob/master/docs/rules/mvp-rules.md).\n\nRun `physlint init`\n\nto generate a documented quality contract, or create `physlint.yaml`\n\nyourself:\n\n```\nconfig_version: 1\nadapter: auto\nrequired_streams:\n  - observation.state\n  - action\nfail_on: error\n\nrules:\n  temporal.max_gap:\n    options:\n      # Default limit is 2× the interval implied by declared FPS.\n      max_gap_multiplier: 2.0\n\n  video.frozen_frames:\n    options:\n      max_consecutive_frames: 5\n      # Action is preferred over noisier observed state by default.\n      motion_streams: [action, observation.state]\n\n  numeric.configured_bounds:\n    options:\n      limits:\n        action:\n          min: [-1.0, -1.0]\n          max: [1.0, 1.0]\n\n  numeric.discontinuity:\n    options:\n      max_delta:\n        observation.state: [0.25, 0.25]\n\nreports:\n  json: true\n  output_dir: .physlint/reports\n```\n\nUse it explicitly when needed:\n\n```\nphyslint check /path/to/dataset --config physlint.yaml\n```\n\nUnknown top-level keys, rule IDs, rule options, duplicate required streams, and invalid values are rejected instead of silently ignored.\n\nThe CLI has stable exit codes and writes reports atomically, so a basic GitHub Actions gate is small:\n\n```\n- name: Install Physlint\n  run: python -m pip install \"physlint[video]==0.1.0a1\"\n\n- name: Validate robot dataset\n  run: |\n    physlint check \"$DATASET_PATH\" \\\n      --json-output artifacts/physlint-report.json\n\n- uses: actions/upload-artifact@v4\n  if: always()\n  with:\n    name: physlint-report\n    path: artifacts/physlint-report.json\n```\n\n| Exit code | Meaning |\n|---|---|\n`0` |\nValidation completed and the configured contract passed |\n`1` |\nValidation completed and the contract failed |\n`2` |\nInvalid command or configuration |\n`3` |\nDataset or adapter failure |\n`4` |\nInternal Physlint error |\n`130` |\nInterrupted by the user |\n\nThe alpha release gate evaluates four immutable public snapshots from four producers:\n\n| Dataset | Robot | Episodes | Frames | Applicable rules | Result |\n|---|---|---|---|---|---|\n`ViaCatalyst/robomimic-can-ph-lerobot-v3` |\n\n`cagataydev/scout-earth-rover-mini-20260616-053232`\n\n`lerobot/svla_so101_pickplace`\n\n`vikram-avea/sentinel-demo-09`\n\nClean-source result: **4/4 snapshots pass with zero findings and zero rule errors.** Controlled-defect recall: **3/3** for a non-finite value, reordered timestamps, and a deleted source row.\n\nEverything needed to audit or rerun those claims is versioned:\n\n[Pinned repository manifest](/pranayjoshi/physlint/blob/master/validation/manifest.yaml)[Deterministic corruption and execution harness](/pranayjoshi/physlint/blob/master/validation/harness.py)[Sanitized reports and SHA-256 values](/pranayjoshi/physlint/blob/master/validation/reports/real-data-2026-08-24/summary.json)[Publication-ready CSV](/pranayjoshi/physlint/blob/master/validation/reports/real-data-2026-08-24/summary.csv)[Manual classification and performance analysis](/pranayjoshi/physlint/blob/master/docs/validation/real-data-2026-08-23.md)[Reproduction instructions](/pranayjoshi/physlint/blob/master/validation/README.md)\n\nRuntime measurements are observations from the documented machine and run—not universal performance guarantees.\n\nThe storage format is an adapter boundary, not the product boundary.\n\n| Format | Status | Intended mode |\n|---|---|---|\n| LeRobot Dataset v3.x | Alpha—implemented and publicly validated |\nTraining datasets |\n| MCAP with ROS 2 profiles | Planned—seeking design partners | Recordings and derived datasets |\n| Robomimic HDF5 | Planned | Demonstration datasets |\n| RLDS/TFDS | Researching | Episode/step datasets |\n| ROS bag2 SQLite and ROS 1 bag | Researching | Recordings |\n\nMCAP needs two honest layers: container/channel health that works without training semantics, and an explicit profile mapping topics to actions, state, cameras, and episode boundaries. See the [cross-format roadmap](/pranayjoshi/physlint/blob/master/docs/roadmap.md) and [MCAP/ROS proposal](/pranayjoshi/physlint/blob/master/docs/design/mcap-ros.md).\n\nUse the adapter-request issue form to contribute an immutable public example and a real failure mode.\n\nSupported:\n\n- LeRobot v3.x\n`meta/info.json`\n\nschema and path templates - Chunked Parquet episode metadata and sample shards\n- Multiple episodes per shared Parquet/MP4 file\n- Fixed-size and regular vector features\n- Shared video segments using per-camera timestamp ranges\n- Metadata-first discovery and bounded batch iteration\n\nNot currently supported:\n\n- LeRobot v2.0/v2.1\n- Remote Hub identifiers passed directly to\n`physlint check`\n\n- Image-directory features in the video rule set\n- Arbitrary codecs unavailable to the installed OpenCV build\n- Inferred safety, calibration, task-success, or coordinate-frame conclusions\n\nRead the [LeRobot adapter boundary](/pranayjoshi/physlint/blob/master/docs/adapters/lerobot.md).\n\n```\nsource format → read-only adapter → canonical episodes/streams → capability planner\n                                                        ↓\n                                           deterministic rule engine\n                                                        ↓\n                                      terminal + versioned JSON evidence\n```\n\n**Read only:** source datasets are never repaired or rewritten.**Lazy by default:** metadata first, bounded Parquet batches, and one shared privacy-safe video analysis pass.**Explicit applicability:** adapters advertise capabilities; unavailable checks explain why they did not run.**Stable evidence:** rule versions, fingerprints, source revisions, and report schema are serialized.**Exception isolation:** one rule failure cannot masquerade as a clean dataset pass.\n\nValidation is offline. Reports contain source references, timestamps, aggregate statistics, and targeted evidence—not embedded images or complete source samples. Treat every dataset parser as an attack surface and report suspected vulnerabilities privately through [GitHub Security Advisories](https://github.com/pranayjoshi/physlint/security/advisories/new).\n\nSee [SECURITY.md](/pranayjoshi/physlint/blob/master/SECURITY.md) before submitting a vulnerability. Do not attach private datasets or sensitive reports to public issues.\n\nContributions are welcome, particularly:\n\n- Public healthy and defective datasets for adapter release gates\n- False-positive reproductions\n- MCAP/ROS recording schemas and failure modes\n- New deterministic rules with controlled corruptions\n- Documentation, performance characterization, and privacy reviews\n\nDevelopment setup:\n\n```\ngit clone https://github.com/pranayjoshi/physlint.git\ncd physlint\npython -m pip install -e \".[video,dev]\"\n\nruff check .\nruff format --check .\nmypy\npytest\n```\n\nRules require positive and negative fixtures, stable remediation, a bounded finding count, and controlled corruption evidence where applicable. Adapters must remain read-only, metadata-first, lazy over samples, and explicit about capabilities.\n\nRead [CONTRIBUTING.md](/pranayjoshi/physlint/blob/master/CONTRIBUTING.md), open a format request, or join [GitHub Discussions](https://github.com/pranayjoshi/physlint/discussions).\n\nPhyslint is an alpha. Its current claims are deliberately limited to the documented LeRobot v3 boundary and committed release evidence. The project does not train policies, repair data, host datasets, infer task success, produce an opaque quality score, or certify that a robot or policy is safe.\n\nSee [CHANGELOG.md](/pranayjoshi/physlint/blob/master/CHANGELOG.md) for release notes.\n\nPhyslint is available under the [MIT License](/pranayjoshi/physlint/blob/master/LICENSE).", "url": "https://wpnews.pro/news/physlint-deterministic-integrity-checks-for-physical-ai-data", "canonical_source": "https://github.com/pranayjoshi/physlint", "published_at": "2026-08-26 17:45:21+00:00", "updated_at": "2026-08-26 18:13:41.617813+00:00", "lang": "en", "topics": ["ai-tools", "mlops", "artificial-intelligence"], "entities": ["Physlint", "LeRobot Dataset v3.x", "pranayjoshi", "PyPI", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/physlint-deterministic-integrity-checks-for-physical-ai-data", "markdown": "https://wpnews.pro/news/physlint-deterministic-integrity-checks-for-physical-ai-data.md", "text": "https://wpnews.pro/news/physlint-deterministic-integrity-checks-for-physical-ai-data.txt", "jsonld": "https://wpnews.pro/news/physlint-deterministic-integrity-checks-for-physical-ai-data.jsonld"}}