bohrin 0.1.0__tar.gz

bohrin-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,71 @@
+name: Bug report
+description: Bohrin crashed, failed to read a dataset, or did something clearly wrong.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. The three version fields below are required because without
+        them almost every bug report is unactionable — we cannot tell a fixed bug from a
+        live one, or a format difference from a code difference.
+
+        **If bohrin flagged something that is actually fine**, that is a false positive, not
+        a bug — please use the *False positive* template instead. It goes into detector
+        calibration rather than the bug queue.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you run, what did you expect, and what did you get instead?
+      placeholder: |
+        I ran `bohrin scan ./my_data` and it exited with a traceback instead of a report.
+    validations:
+      required: true
+
+  - type: input
+    id: dataset
+    attributes:
+      label: Dataset
+      description: >
+        The Hugging Face repo id if it is public (e.g. `lerobot/pusht`) — that lets us
+        reproduce it exactly. If it is private, describe the format and layout instead.
+      placeholder: "lerobot/pusht — or: private LeRobot v2.1, 340 episodes, SO-101, 2 cameras"
+    validations:
+      required: true
+
+  - type: input
+    id: bohrin-version
+    attributes:
+      label: Bohrin version
+      description: "Output of `bohrin --version`"
+      placeholder: "bohrin 0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version and OS
+      description: "Output of `python --version`, plus your OS"
+      placeholder: "Python 3.11.9, Ubuntu 22.04"
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Full output
+      description: >
+        The complete terminal output, including any traceback. This is automatically
+        formatted as code, so no backticks needed.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked that no existing issue already reports this.
+          required: true

bohrin-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/prabhu-gopal/bohrin/security/advisories/new
+    about: Please report security issues privately, never as a public issue. See SECURITY.md.
+  - name: Unsupported dataset format
+    url: https://github.com/prabhu-gopal/bohrin/issues/new?labels=format-request&title=%5Bformat%5D+
+    about: Want bohrin to read a format it does not support yet? Tell us which, and how common it is.

bohrin-0.1.0/.github/ISSUE_TEMPLATE/false_positive.yml

@@ -0,0 +1,79 @@
+name: False positive
+description: Bohrin flagged something on your data that is actually fine.
+title: "[false positive] "
+labels: ["false-positive", "calibration"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **This is the most valuable report you can send us.**
+
+        Bohrin's only real asset is that its findings are trustworthy. A detector that
+        cries wolf is worse than no detector, and we cannot find those on synthetic data —
+        we need yours. Every report here goes directly into threshold calibration.
+
+        You do **not** need to share your dataset. The detector id, the numbers bohrin
+        reported, and your explanation of why it is wrong is enough to act on.
+
+  - type: input
+    id: detector-id
+    attributes:
+      label: Detector ID
+      description: >
+        The bracketed id printed with the finding, e.g. `[stats.dead_dimension]`. Run
+        `bohrin explain <id>` to see what it thinks it is measuring.
+      placeholder: "stats.jitter_outlier"
+    validations:
+      required: true
+
+  - type: textarea
+    id: the-finding
+    attributes:
+      label: The finding, as bohrin printed it
+      description: Copy the whole block, including the measured value and the episode count.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: why-wrong
+    attributes:
+      label: Why is this wrong?
+      description: >
+        What does bohrin not know about your setup? This is the part we cannot guess.
+      placeholder: |
+        Dimension 6 is a binary gripper open/close, so its variance is supposed to be near
+        zero between grasps. It is not a dead dimension — it is doing its job.
+    validations:
+      required: true
+
+  - type: textarea
+    id: dataset-context
+    attributes:
+      label: Dataset context
+      description: >
+        Robot/embodiment, control rate, action space (joint positions? EEF deltas?),
+        episode count, and the Hugging Face repo id if it is public.
+      placeholder: |
+        SO-101, 30 Hz, 6-DoF joint positions + binary gripper, 220 episodes, private.
+    validations:
+      required: true
+
+  - type: input
+    id: bohrin-version
+    attributes:
+      label: Bohrin version
+      description: "Output of `bohrin --version`"
+      placeholder: "bohrin 0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: json
+    attributes:
+      label: Report JSON (optional, but very helpful)
+      description: >
+        `bohrin scan <path> --json report.json` gives us the exact measured values and
+        thresholds. Attach it or paste the relevant finding. It contains no raw data from
+        your dataset — only statistics.
+      render: json

bohrin-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## What does this change?
+
+<!-- One or two sentences. The "why" matters more than the "what". -->
+
+## Why?
+
+<!-- What problem does this solve? Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] Commits are signed off (`git commit -s`) — see [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] `ruff check .`, `mypy`, and `pytest` pass locally
+- [ ] Added a test that fails before this change and passes after
+- [ ] Updated `CHANGELOG.md` under `## [Unreleased]` if this is user-visible
+
+### If this adds or changes a detector
+
+- [ ] The mechanism sentence says *why* the defect degrades a trained policy
+- [ ] Linked evidence that the defect is real (issue, paper, or training run)
+- [ ] Added a fault-injection scenario to the benchmark
+- [ ] Measured recall/precision are in the PR description

bohrin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        # The suite is fully synthetic: no network, no GPU, no dataset downloads.
+        run: uv run pytest -q
+
+  # The CLI is what users actually touch, and a working test suite has never once caught a
+  # broken entry point or a missing runtime dependency. This installs the built wheel into a
+  # clean environment and runs the binary, which is the only way to catch that.
+  smoke:
+    name: installed-wheel smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build the wheel
+        run: uv build
+
+      - name: Verify the wheel contains the package
+        run: |
+          ls -R dist/
+          python -c "
+          import zipfile, glob, sys
+          wheel = glob.glob('dist/*.whl')[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert any(n.startswith('bohrin/') for n in names), 'no bohrin/ inside the wheel'
+          print(f'{wheel}: {len(names)} files, package present')
+          "
+
+      - name: Install into a clean environment and run it
+        run: |
+          python -m venv /tmp/fresh
+          /tmp/fresh/bin/pip install --quiet dist/*.whl
+          /tmp/fresh/bin/bohrin --version
+          /tmp/fresh/bin/bohrin --help
+          /tmp/fresh/bin/bohrin list-detectors | head -5
+          /tmp/fresh/bin/bohrin explain stats.dead_dimension
+
+      - name: Errors are messages, not tracebacks
+        run: |
+          set +e
+          out=$(/tmp/fresh/bin/bohrin scan ./definitely-not-a-dataset 2>&1)
+          code=$?
+          set -e
+          echo "$out"
+          [ "$code" -eq 2 ] || { echo "expected exit 2 for a usage error, got $code"; exit 1; }
+          case "$out" in *Traceback*) echo "a traceback reached the user"; exit 1 ;; esac

bohrin-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+# Tag-triggered publish. Never publish from a laptop: the tag is the only thing that can
+# ship a version, so what is on PyPI always corresponds to a commit anyone can check out.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: "Publish to TestPyPI instead of PyPI"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Show what is in the distributions
+        # If `bohrin/` is not inside the wheel, pyproject.toml is wrong and the upload
+        # would silently ship an empty package.
+        run: |
+          ls -R dist/
+          python -m zipfile -l dist/*.whl | head -20
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.test_pypi
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/bohrin
+    permissions:
+      # Required for Trusted Publishing: this is what lets uv mint a short-lived OIDC
+      # token instead of us storing a long-lived PyPI API token in GitHub Secrets.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Publish
+        run: uv publish --trusted-publishing always --publish-url https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bohrin
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Publish
+        run: uv publish --trusted-publishing always
+
+  github-release:
+    name: Attach distributions to the GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

bohrin-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Bohrin scan artifacts (never commit real reports)
+*_report.html
+*_report.json
+bohrin-report.*
+
+# Internal design docs: business strategy, roadmap, licensing/moat reasoning.
+# Kept locally for reference, deliberately never pushed to the public repo.
+/docs/

bohrin-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The **report schema** is versioned separately from the package — see `schema_version` in
+any `--json` output. It changes only when the serialized report shape changes.
+
+## [Unreleased]
+
+## [0.1.0] — unreleased
+
+First public release.
+
+### Added
+
+- `bohrin scan <path>` — analyze a robot-learning dataset and report the defects that hurt
+  training, with severity, affected episodes, the measured value, the mechanism, and a fix.
+- **Hugging Face Hub support**: `bohrin scan lerobot/pusht` fetches `meta/` and `data/`
+  (never video) and scans the local snapshot. This is the only network call in the tool.
+- **Formats**: LeRobot v2.1 and v3.0 (autodetected), RLDS/Open-X, robomimic and raw HDF5,
+  Zarr replay buffers, NumPy directories.
+- **Machine-readable output**: `--json` (versioned `schema_version`), `--sarif` (SARIF
+  2.1.0 for GitHub code scanning), and a self-contained `--html` report.
+- **CI gating**: `--ci --fail-on <severity>` exits non-zero only when you ask it to.
+- **Calibration**: `bohrin calibrate` builds a conformal FDR corpus from your own
+  known-good data, after which `--fpr` governs the covered detector gates.
+- `bohrin list-detectors`, `bohrin explain <detector-id>`, and `bohrin init`.
+- Adapters and detectors are plugins discovered through entry points — the same mechanism
+  the built-ins use.
+
+### Fixed
+
+- `dynamics.inverse_residual` reported HIGH unconditionally, whatever the measured extent.
+  Across 20 curated public LeRobot datasets it fired at HIGH on 19 of them, with flagged
+  fractions spanning 0.94% to 80.8% all reported identically. Severity now scales on extent
+  (≥20% of transitions) **or** magnitude (a residual as large as the signal itself, which is
+  physically unexplainable however rare). HIGH rate on real data: 95% → 50%,
+  measured with `scripts/hub_smoke.py`.
+- A clean scan printed "No findings" twice.
+
+### Known limitations
+
+- `smoothness.discontinuity_jump` and `integrity.declared_mismatch` report HIGH on 70% and
+  60% of curated public datasets respectively, which is far more likely to be a threshold
+  problem than a real epidemic. Documented in the README rather than silently shipped as
+  trustworthy; re-tuning them needs data we do not have yet.
+
+### Deliberately not included
+
+- **No 0-100 health score.** An aggregate number implies a calibration against real
+  training outcomes that does not exist yet — nothing here measures how much each defect
+  actually costs a trained policy. The report gives severity counts and ranked findings,
+  every one of which is individually defensible. The scoring function
+  (`bohrin.synth.pipeline.quality_score`) is still present and tested; the headline
+  returns when a corpus of training runs can back it.
+
+### Notes
+
+- Python 3.10 through 3.13 are supported and tested.
+- No telemetry. Your data never leaves your machine.
+- `schema_version` is `1.0` — the first published report contract. Nothing consumed an
+  earlier shape, since no version of bohrin was ever released.
+
+[Unreleased]: https://github.com/prabhu-gopal/bohrin/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/prabhu-gopal/bohrin/releases/tag/v0.1.0

bohrin-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+security@bohrin.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations