rabbit-brain 0.1.0__tar.gz

rabbit_brain-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+rb-runs/
+.venv/

rabbit_brain-0.1.0/AGENTS.md

@@ -0,0 +1,139 @@
+# Rabbit Brain: AGENTS.md
+
+Rabbit Brain (`rb`) reviews a candidate checkpoint of an iterative perception model against the current one: it ranks the cases that regressed on error or never settled during refinement, explains each one, and keeps checks so the next checkpoint gets the same review. It runs locally; nothing leaves this machine.
+
+Read this whole file before running anything. **Compute per-case errors in your own evaluator; that is your metric. Do not compute regressions, rankings, stability or verdicts yourself.** `rb` defines them, applies the same definitions on every run, and records how, which is what makes a result comparable across checkpoints and people. If you find yourself writing a comparison script, stop and run `rb import`.
+
+## Install
+
+```sh
+pip install rabbit-brain        # or: uvx --from rabbit-brain rb
+rb version                      # rabbit-brain 0.1.x
+rb docs                         # prints this file
+```
+
+Python 3.10 or later. The only dependency is pydantic. Nothing here needs a GPU: version 0.1 reads results your evaluator already produced.
+
+## When to use it, and when not
+
+Use it when there are two checkpoints (or two models for the same task), one lower-is-better error per case for each, and a release decision to make. If the model refines its answer iteratively (RAFT-family optical flow, RAFT-Stereo-style depth), also export one number per refinement iteration per case and `rb` will flag the answers the candidate never settled on, which needs no labels.
+
+Do not use it for training, hyperparameter search, certifying a model, or metrics where higher is better (convert those to an error first).
+
+## What is in 0.1, and what is not
+
+In 0.1 you bring the numbers: `rb import` reads a results file (JSON, or a CSV of per-case metrics) and everything downstream works on it. `rb run`, the runner that executes both checkpoints and records trajectories itself, arrives in 0.2 together with `rb init`, `rb doctor`, `rb verify-hook`, `rb rerun` and `rb open`. Calling any of them in 0.1 returns `E_NOT_AVAILABLE` and explains this; do not try to work around it.
+
+## The workflow
+
+```sh
+rb example                                   # a run from built-in example data, to see what the output looks like
+rb import results.json                       # your results (version-1 JSON; format below) → a new run under rb-runs/
+rb import metrics.csv --project <p> --baseline-name <a> --candidate-name <b> --dataset <d> --metric <m> --unit <u>
+rb findings <run> --top 5                    # the ranked queue, the summary, the verdict
+rb case <run> <case_id>                      # one case: numbers, trajectory statistics, the reasoning
+rb check save <run> <case_id>                # keep this case for the next checkpoint (limit = current error + max regression)
+rb check run <run> --checks checks.json      # next time: exit 1 if a saved check fails or a case is flagged
+rb report <run> --print                      # the receipt a human reads (also written to the run directory)
+```
+
+Other commands: `rb runs` (list runs), `rb check list|rm`, `rb schema <name>`, `rb docs --errors`, `rb version`. `<run>` is a run id (`rb runs`), a run directory, a `bundle.json`, or a version-1 results file read in place.
+
+Limits, on any command that reads a run: `--max-regression 0.3 --max-late-share 0.25 --max-reversals 2` (these are the defaults; they are generic heuristics, and a scorer fitted to the model is a separate, paid step). `rb findings` also takes `--filter flagged|all|regressions|unstable|improved-unstable|settled-regressions|improved|stable` (default `flagged`), `--sort priority|error-change|late-share|name` and `--top N`.
+
+## The results file (version 1)
+
+```json
+{
+  "version": 1,
+  "project": "My perception project",
+  "baseline": "model-v1", "candidate": "model-v2",
+  "dataset": "Regression set", "metric": "mean_endpoint_error", "unit": "px",
+  "cases": [
+    { "id": "seq-001", "name": "First sequence", "baseline_error": 2.1, "candidate_error": 2.4,
+      "candidate_trajectory": [2.3, 1.4, 0.9, 0.6, 0.4, 0.3, 0.2, 0.15, 0.1, 0.08, 0.06, 0.05] }
+  ]
+}
+```
+
+Rules: 1–500 cases; case ids match `^[a-zA-Z0-9_.-]{1,80}$` and stay the same across checkpoints (saved checks follow them); `baseline_error` and `candidate_error` are the same lower-is-better metric per case for the current and the candidate model, computed against the same ground truth and valid mask; `baseline_trajectory` / `candidate_trajectory` are optional, 2–64 numbers each, the mean |update| per refinement iteration (record them with the hook below); `baseline_frames` / `candidate_frames` are optional paired per-frame error series of equal length; `tags` and `notes` are optional. `rb schema example` prints this file; `rb schema comparison-v1` prints the JSON Schema. A CSV works too: columns `case_id, baseline_error, candidate_error` and optionally `name, tags, baseline_trajectory, candidate_trajectory, baseline_frames, candidate_frames` (series as semicolon-separated numbers), with the project, model names, dataset, metric and unit given as flags.
+
+## Recording a trajectory (the one line you add to the model)
+
+```python
+from rabbit_brain import TrajectoryRecorder
+rec = TrajectoryRecorder()                 # optional: TrajectoryRecorder(mask=valid_pixels)
+for k in range(iters):
+    delta_flow = update_block(...)         # the existing update
+    flow = flow + delta_flow
+    rec.step(delta_flow)                   # one number per iteration: mean |update| over the valid region
+case["candidate_trajectory"] = rec.values  # one recorder per case per model
+```
+
+Works with torch tensors (shape `(B, 2, H, W)` is reduced to a per-pixel L1 magnitude), numpy arrays and nested lists. Record the current model the same way so both trajectories are compared under the same definition. If the update loop cannot be reached, import without trajectories: stability is then reported as "not assessed", never as "settled".
+
+## Output
+
+Every command accepts `--json` and prints exactly one JSON object on stdout; logs and warnings go to stderr.
+
+```json
+{"ok": true, "rb_version": "0.1.0", "command": "import", "run_id": "20260925-1412-model-v2",
+ "data": {"run_dir": "rb-runs/20260925-1412-model-v2",
+          "summary": {"cases": 12, "regressions": 3, "unstable": 4, "improved_unstable": 2, "settled_regressions": 1, "flagged": 5},
+          "verdict": {"status": "investigate", "ready": false, "line": "Not ready: 3 error regressions, 2 unstable cases that pass on error. Start with aisle-042.", "start": "aisle-042"}},
+ "errors": [],
+ "next": ["rb findings 20260925-1412-model-v2 --top 5", "rb case 20260925-1412-model-v2 aisle-042"]}
+```
+
+`next` lists the commands that usually follow. A run directory `rb-runs/<run_id>/` holds `bundle.json` (every case's numbers, trajectories, stability statistics and flags), `record.json` (the receipt: rb version, the exact command, input file and its sha256, environment, limits), `findings.json` (the ranked queue, the summary, the verdict under those limits) and `report.md` (the human receipt). `bundle.json`, `record.json`, `findings.json` and `report.md` are small and committable; `checks.json` belongs in the repo next to the model code. Schemas: `rb schema bundle|record|findings|checks|envelope`.
+
+Definitions `rb` applies, and restates in every report: a case is a **regression** when the candidate's error exceeds the current model's by more than `max_regression`; **late share** is the fraction of all refinement that happened in the last third of the iterations; a **reversal** is an iteration where the update grew by more than 5% over the previous one; a case is **unstable** when late share exceeds `max_late_share` or reversals exceed `max_reversals`. Cases are ranked regression+unstable, then regression, then **improved but unstable** (they pass on error and still need a look), then the rest, by error change. A **saved check** is an absolute limit for a case id in a project: candidate error ≤ `max_error`, optionally late share ≤ `max_late_share` and reversals ≤ `max_reversals`; a saved case missing from a later run fails the check.
+
+## Exit codes
+
+`0` ok · `1` a saved check failed or is missing, or a case is flagged (`rb check run`; choose with `--fail-on any|checks|flags`, default `any`) · `2` invalid input or config · `3` environment failure. Read `errors[].fix`.
+
+## Errors and what to do
+
+| code | meaning | do this |
+|---|---|---|
+| `E_IMPORT_INVALID` | the results file is not a valid comparison | fix every problem listed in `errors[0].problems`; start from `rb schema example` |
+| `E_IMPORT_NOT_JSON` | the file is not JSON | check for a missing comma or bracket |
+| `E_IMPORT_TOO_LARGE` | over 2 MB / 500 cases | split the case set or drop per-frame series |
+| `E_IMPORT_CONFIG` | a CSV import is missing names | pass `--project --baseline-name --candidate-name --dataset --metric --unit` |
+| `E_CSV_INVALID` | the CSV could not be converted | required columns `case_id, baseline_error, candidate_error`; series are semicolon-separated |
+| `E_FILE_NOT_FOUND` | a path does not exist | paths are relative to the current directory |
+| `E_RUN_NOT_FOUND` | no such run | `rb runs`; or pass a `bundle.json` / results file path |
+| `E_CASE_NOT_FOUND` | no such case id in this run | `rb findings <run> --filter all` lists every id |
+| `E_CHECKS_INVALID` | the checks file is not valid | `rb schema checks` |
+| `E_CHECKS_PROJECT_MISMATCH` | the named checks file is for another project | use the same project name, or another `--checks` file (an unnamed `checks.json` for another project is ignored with a warning) |
+| `E_LIMITS_INVALID` | a limit is out of range | `--max-regression ≥ 0`, `0 ≤ --max-late-share ≤ 1`, `0 ≤ --max-reversals ≤ 64` |
+| `E_NOT_AVAILABLE` | the command is not in this version | see "What is in 0.1"; import results instead |
+| `E_WRITE_FAILED` | a file could not be written | check permissions, or `--runs-dir` |
+| `E_INTERNAL` | unexpected failure | re-run with `--json` and report it |
+
+## Worked example
+
+Prompt from the human: *"Review candidate checkpoint v2 against v1 on the warehouse set with Rabbit Brain and tell me what to look at."*
+
+```sh
+python evaluate.py --checkpoint v1 --out v1.json      # your evaluator, unchanged: per-case errors (+ trajectories via the hook)
+python evaluate.py --checkpoint v2 --out v2.json
+python merge.py v1.json v2.json > results.json          # one results file in the version-1 format above (ids identical in both)
+rb import results.json --json
+rb findings <run_id> --top 5 --json
+rb case <run_id> <top case id> --json
+rb report <run_id>
+```
+
+Then report to the human, in this order: the verdict line; the top cases with their `why` text; the run id; the path to `report.md`; the command that reproduces the queue (`rb findings <run_id>` with the limits used). Quote numbers only from `findings.json`. If there were no trajectories, say that stability was not assessed.
+
+When a later checkpoint arrives, import it under the same project with the same case ids and run `rb check run <new run> --checks checks.json` first: it answers "are the cases we cared about still fine?" and exits 1 in CI if not. Then `rb findings` for the full review.
+
+## Boundaries
+
+`rb` does not run inference, does not modify model code (the one recorder line is the exception, and it only reads the update), and does not certify a model. Stability limits are generic heuristics and a starting point; a scorer fitted to the model is a separate, paid step. Nothing leaves the machine.
+
+## For humans: verify what your agent did
+
+Open `rb-runs/<run_id>/report.md`. The header lists the run id, the `rb` version, the exact command, the input file with its sha256, the environment and whether trajectories were present; the body restates the definitions with the limits in force and lists every case. Re-run the command from the header, or `rb findings <run_id>` with the same limits, and compare. If what the agent told you differs from the report, the report is right.

rabbit_brain-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 (2026-09-19)
+First release: the checker and importer from the Rabbit Brain v5 integration kit as a package.
+- `rb import` (version-1 JSON or metrics CSV) → a run directory with `bundle.json` (version 2), `record.json`, `findings.json`, `report.md`.
+- `rb findings`, `rb case`, `rb report`, `rb check save|run|list|rm`, `rb example`, `rb runs`, `rb docs`, `rb schema`, `rb version`.
+- `--json` envelope on every command; exit codes 0/1/2/3; error codes with fixes.
+- `TrajectoryRecorder` (the one-line hook) as a Python API.
+- Same arithmetic as the web workspace and the v5 `check.py`: late share, reversals, regression threshold, ranking, verdict, report.
+Not yet: `rb run` (the runner), adapters, evidence rendering, `rb open`. Those are 0.2.

rabbit_brain-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rabbit_brain-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: rabbit-brain
+Version: 0.1.0
+Summary: Release review for iterative perception models: rank the cases that regressed or never settled, keep checks for the next checkpoint.
+Project-URL: Homepage, https://rabbit-brain-evaluation.jhetchan.chatgpt.site
+Project-URL: Documentation, https://github.com/rabbit-brain/rb/blob/main/AGENTS.md
+Project-URL: Source, https://github.com/rabbit-brain/rb
+Project-URL: Paper, https://jhetchan.com
+Author: Jhet Chan
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: RAFT,agents,ci,depth,evaluation,model-release,optical-flow,perception,regression-testing,stereo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.5
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Rabbit Brain
+
+Release review for iterative perception models. Give it the per-case errors of your current and candidate checkpoints (and, if the model refines its answer iteratively, one number per refinement iteration) and it ranks the cases to look at: the ones that regressed on error, and the ones that pass on error but never settled. Then it keeps checks for the next checkpoint.
+
+```sh
+pip install rabbit-brain
+rb example                    # see it on built-in example data
+rb import results.json        # your evaluator's per-case results (format: rb schema example)
+rb findings <run> --top 5     # the ranked queue and a verdict
+rb check save <run> <case>    # keep a case for the next checkpoint
+rb check run <run>            # exit 1 in CI when something regressed
+```
+
+Everything runs locally and nothing leaves your machine. Every run leaves a receipt (`report.md`, `record.json`) with the exact command, the input's hash and the definitions in force, so a colleague, or you after your coding agent ran it, can verify the numbers.
+
+**What it does.** Compares two model versions case by case; flags regressions above a limit you choose; reads each model's own refinement trajectory (label-free) to flag answers that were still moving late or reversed direction; ranks what needs a decision first; explains each case in plain language; saves checks that follow case ids across checkpoints.
+
+**What it needs.** One lower-is-better error per case for both models (any metric with a unit: endpoint error in px, depth error in cm, …), computed by your evaluator against the same ground truth and valid mask. Optionally the trajectory, recorded with the one-line hook (`from rabbit_brain import TrajectoryRecorder`).
+
+**What it doesn't do.** Run inference (that arrives with the runner in 0.2), train anything, or certify a model. The stability limits are generic heuristics; a scorer fitted to your model is a separate, paid evaluation.
+
+**For coding agents.** `rb docs` prints [AGENTS.md](AGENTS.md): the workflow, the file format, the JSON output (`--json` on every command), exit codes and every error code with its fix. Tell your agent: *"Review candidate checkpoint B against A on this case set with Rabbit Brain."*
+
+The trajectory diagnostic comes from *Beyond Endpoint Sufficiency* (Jhet Chan, NeurIPS 2026 submission). The web workspace that reads the same files is at https://rabbit-brain-evaluation.jhetchan.chatgpt.site.
+
+Apache-2.0.

rabbit_brain-0.1.0/README.md

@@ -0,0 +1,26 @@
+# Rabbit Brain
+
+Release review for iterative perception models. Give it the per-case errors of your current and candidate checkpoints (and, if the model refines its answer iteratively, one number per refinement iteration) and it ranks the cases to look at: the ones that regressed on error, and the ones that pass on error but never settled. Then it keeps checks for the next checkpoint.
+
+```sh
+pip install rabbit-brain
+rb example                    # see it on built-in example data
+rb import results.json        # your evaluator's per-case results (format: rb schema example)
+rb findings <run> --top 5     # the ranked queue and a verdict
+rb check save <run> <case>    # keep a case for the next checkpoint
+rb check run <run>            # exit 1 in CI when something regressed
+```
+
+Everything runs locally and nothing leaves your machine. Every run leaves a receipt (`report.md`, `record.json`) with the exact command, the input's hash and the definitions in force, so a colleague, or you after your coding agent ran it, can verify the numbers.
+
+**What it does.** Compares two model versions case by case; flags regressions above a limit you choose; reads each model's own refinement trajectory (label-free) to flag answers that were still moving late or reversed direction; ranks what needs a decision first; explains each case in plain language; saves checks that follow case ids across checkpoints.
+
+**What it needs.** One lower-is-better error per case for both models (any metric with a unit: endpoint error in px, depth error in cm, …), computed by your evaluator against the same ground truth and valid mask. Optionally the trajectory, recorded with the one-line hook (`from rabbit_brain import TrajectoryRecorder`).
+
+**What it doesn't do.** Run inference (that arrives with the runner in 0.2), train anything, or certify a model. The stability limits are generic heuristics; a scorer fitted to your model is a separate, paid evaluation.
+
+**For coding agents.** `rb docs` prints [AGENTS.md](AGENTS.md): the workflow, the file format, the JSON output (`--json` on every command), exit codes and every error code with its fix. Tell your agent: *"Review candidate checkpoint B against A on this case set with Rabbit Brain."*
+
+The trajectory diagnostic comes from *Beyond Endpoint Sufficiency* (Jhet Chan, NeurIPS 2026 submission). The web workspace that reads the same files is at https://rabbit-brain-evaluation.jhetchan.chatgpt.site.
+
+Apache-2.0.

rabbit_brain-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rabbit-brain"
+version = "0.1.0"
+description = "Release review for iterative perception models: rank the cases that regressed or never settled, keep checks for the next checkpoint."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Jhet Chan" }]
+keywords = ["optical-flow", "stereo", "depth", "evaluation", "regression-testing", "model-release", "RAFT", "perception", "ci", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = ["pydantic>=2.5,<3"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2", "twine>=5"]
+
+[project.urls]
+Homepage = "https://rabbit-brain-evaluation.jhetchan.chatgpt.site"
+Documentation = "https://github.com/rabbit-brain/rb/blob/main/AGENTS.md"
+Source = "https://github.com/rabbit-brain/rb"
+Paper = "https://jhetchan.com"
+
+[project.scripts]
+rb = "rabbit_brain.cli:main"
+rabbit-brain = "rabbit_brain.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rabbit_brain"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"AGENTS.md" = "rabbit_brain/docs/AGENTS.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/rabbit_brain", "tests", "AGENTS.md", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

rabbit_brain-0.1.0/src/rabbit_brain/__init__.py

@@ -0,0 +1,12 @@
+"""Rabbit Brain: release review for iterative perception models.
+
+Rank the cases that regressed or never settled, keep checks for the next checkpoint.
+CLI: `rb`. Docs for agents and humans: `rb docs` (AGENTS.md).
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .recorder import TrajectoryRecorder  # noqa: E402
+
+__all__ = ["__version__", "TrajectoryRecorder"]

rabbit_brain-0.1.0/src/rabbit_brain/checks.py

@@ -0,0 +1,107 @@
+"""Saved checks: absolute limits per case id for one project, kept in the repo (`checks.json`) and run against the next candidate."""
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import Optional, Union
+
+from pydantic import ValidationError
+
+from .errors import RBError
+from .fmt import pct, to_fixed
+from .models import Bundle, CheckResult, ChecksV1, ChecksV2, CheckV1, CheckV2, ComparisonV1
+from .stability import EPS, trajectory_stats
+
+DEFAULT_CHECKS_PATH = Path("checks.json")
+
+
+def load_checks(path: Path, project: Optional[str] = None, strict: bool = True) -> ChecksV2:
+    """Read a version-1 (workspace / kit) or version-2 checks file. Returns version 2, filtered to `project` when given.
+
+    A file for another project raises E_CHECKS_PROJECT_MISMATCH when `strict`, otherwise returns no checks (the caller may warn)."""
+    if not path.exists():
+        return ChecksV2(version=2, project=project or "", checks=[])
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError:
+        raise RBError("E_CHECKS_INVALID", message=f"{path} is not valid JSON.")
+    if not isinstance(raw, dict):
+        raise RBError("E_CHECKS_INVALID")
+    try:
+        if raw.get("version") == 2:
+            v2 = ChecksV2.model_validate(raw)
+            if project and v2.checks and v2.project != project:
+                if strict:
+                    raise RBError("E_CHECKS_PROJECT_MISMATCH", message=f"{path} holds checks for '{v2.project}', not '{project}'.")
+                return ChecksV2(version=2, project=project, checks=[])
+            return v2
+        if raw.get("version") == 1:
+            v1 = ChecksV1.model_validate(raw)
+            checks = [c for c in v1.checks if project is None or c.project == project]
+            if project and v1.checks and not checks:
+                if strict:
+                    raise RBError("E_CHECKS_PROJECT_MISMATCH", message=f"No saved checks in {path} match project '{project}'.")
+                return ChecksV2(version=2, project=project, checks=[])
+            proj = project or (checks[0].project if checks else "")
+            return ChecksV2(version=2, project=proj, checks=[CheckV2(case_id=c.id, name=c.name, max_error=c.max_error, max_late_share=c.max_late_share) for c in checks])
+    except ValidationError as exc:
+        raise RBError("E_CHECKS_INVALID", message=f"{path}: {exc.errors()[0].get('msg', 'invalid')}")
+    raise RBError("E_CHECKS_INVALID", message=f"{path}: expected version 1 or 2.")
+
+
+def save_checks(path: Path, checks: ChecksV2) -> None:
+    try:
+        path.write_text(json.dumps(checks.model_dump(exclude_none=True), indent=2) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise RBError("E_WRITE_FAILED", message=f"Could not write {path}: {exc}")
+
+
+def evaluate_check(check: CheckV2, comparison: Union[ComparisonV1, Bundle], unit: str) -> CheckResult:
+    """Same semantics as the workspace's checkResult() and the kit's check.py."""
+    found = next((c for c in comparison.cases if c.id == check.case_id), None)
+    base = dict(case_id=check.case_id, max_error=check.max_error, max_late_share=check.max_late_share, max_reversals=check.max_reversals)
+    if found is None:
+        return CheckResult(status="missing", reason="Case not present in this comparison.", **base)
+    base["candidate_error"] = found.candidate_error
+    if found.candidate_error > check.max_error + EPS:
+        return CheckResult(status="failing", reason=f"Candidate error {to_fixed(found.candidate_error)} {unit} exceeds the {to_fixed(check.max_error)} {unit} limit.", **base)
+    if check.max_late_share is not None or check.max_reversals is not None:
+        if not found.candidate_trajectory:
+            return CheckResult(status="failing", reason="This check requires a settled trajectory, but none was exported for the candidate.", **base)
+        stats = trajectory_stats(found.candidate_trajectory)
+        if check.max_late_share is not None and stats.late_share > check.max_late_share + EPS:
+            return CheckResult(status="failing", reason=f"Late revision {pct(stats.late_share)} exceeds the {pct(check.max_late_share)} limit.", **base)
+        if check.max_reversals is not None and stats.reversals > check.max_reversals:
+            return CheckResult(status="failing", reason=f"Reversals {stats.reversals} exceed the {check.max_reversals} limit.", **base)
+    return CheckResult(status="passing", reason="Within limits.", **base)
+
+
+def evaluate_all(checks: ChecksV2, comparison: Union[ComparisonV1, Bundle], unit: str, case_id: Optional[str] = None) -> list[CheckResult]:
+    selected = [c for c in checks.checks if case_id is None or c.case_id == case_id]
+    return [evaluate_check(c, comparison, unit) for c in selected]
+
+
+def upsert_check(checks: ChecksV2, new: CheckV2) -> ChecksV2:
+    others = [c for c in checks.checks if c.case_id != new.case_id]
+    return ChecksV2(version=2, project=checks.project, checks=[*others, new])
+
+
+def default_check(bundle: Bundle, case_id: str, *, max_error: Optional[float], max_late_share: Optional[float], max_reversals: Optional[int], require_settled: bool, note: str) -> CheckV2:
+    case = next((c for c in bundle.cases if c.id == case_id), None)
+    if case is None:
+        raise RBError("E_CASE_NOT_FOUND", message=f"Case '{case_id}' is not in run {bundle.run_id}.")
+    if max_error is None:
+        max_error = float(to_fixed(case.baseline_error + bundle.limits.max_regression, 2))
+    if max_late_share is None and require_settled and case.candidate_trajectory:
+        max_late_share = bundle.limits.max_late_share
+    return CheckV2(case_id=case.id, name=case.name, max_error=max_error, max_late_share=max_late_share, max_reversals=max_reversals, from_run=bundle.run_id, created=date.today().isoformat(), note=note or "")
+
+
+def describe_check(check: CheckV2, unit: str) -> str:
+    parts = [f"candidate error ≤ {to_fixed(check.max_error)} {unit}"]
+    if check.max_late_share is not None:
+        parts.append(f"late revision ≤ {pct(check.max_late_share)}")
+    if check.max_reversals is not None:
+        parts.append(f"reversals ≤ {check.max_reversals}")
+    return ", ".join(parts)