notedelta 0.1.0__tar.gz

notedelta-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+build/
+dist/
+
+# NoteDelta outputs
+notedelta-runs/
+notedelta-reports/
+*.notedelta.html
+/report*.html
+/report*.json
+
+# Node / VS Code extension
+node_modules/
+extensions/vscode/out/
+extensions/vscode/*.vsix
+.vscode-test/
+
+# Editors / OS
+.idea/
+.DS_Store
+Thumbs.db
+.ipynb_checkpoints/

notedelta-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes are listed here. Versions follow semantic versioning; the JSON
+report and the configuration carry their own schema versions.
+
+## 0.1.0 - 2026-11-15 (first beta)
+
+- Renamed from the working name LabTrace to NoteDelta before the first release (the
+  `labtrace` name was taken on PyPI). Package, command, configuration file
+  (`.notedelta.yml`) and VS Code identifiers all use `notedelta`.
+
+Core and CLI
+- `notedelta compare`: cell matching by stable ids, identical content and similarity,
+  with reorder detection and explicit ambiguity flags; source, output, error, execution
+  count and metadata diffs; image outputs compared by hash.
+- Numerical comparison with exact decimal arithmetic, absolute/relative tolerances,
+  careful handling of zero baselines, negative values, NaN, infinities and display
+  precision; arrays (shape check, elementwise, max/mean/RMS/relative L2) and pandas
+  tables.
+- Automatic discovery of numbers in logs, printed values, NumPy arrays, JSON outputs
+  and tables, via template-aligned text and a safe literal parser.
+- `.notedelta.yml` v1: configured metrics (regex, key/value, JSON path extraction),
+  directions, units, tolerances, cell selectors, discovery and policy settings; strict
+  validation and regex safety checks.
+- Explainable classification (regression, improvement, change, within tolerance,
+  missing, incomparable).
+- Environment diagnostics: kernel, Python version, interpreter, execution order, seeds,
+  requirements/pyproject/uv/poetry/Pipfile/conda files, graded as fact/warning/hypothesis.
+- Reports: terminal, JSON (schema 1.0, JSON Schema via `notedelta schema`), Markdown,
+  self-contained script-free HTML with light/dark themes. Best-effort redaction.
+- `notedelta compare-git`, `check-config`, `init`, `schema`.
+- Opt-in `notedelta execute` (nbclient; timeouts, repeats, provenance; not sandboxed) and
+  `notedelta stability`.
+
+Integrations
+- VS Code extension (preview): compare with git baseline or file, results view,
+  report panel, jump to cell, regression/reproducibility quick picks, starter config.
+- GitHub composite action with job summary, report artifact and least-privilege example
+  workflow.

notedelta-0.1.0/LICENSE

@@ -0,0 +1,43 @@
+NoteDelta End User License Agreement
+Version 1.0 (draft for the 0.1 beta)
+
+Copyright (c) 2026 Ouyang Matters. All rights reserved.
+
+This agreement covers the NoteDelta command-line tool and Python package, the NoteDelta
+extension for Visual Studio Code, the NoteDelta GitHub Actions integration and their
+documentation (together, the "Software").
+
+1. Licence grant. You may install and use the Software, free of charge, on any number
+   of computers, for personal, academic, research and commercial purposes, including
+   in continuous-integration systems that you or your organisation operate.
+
+2. Restrictions. You may not (a) sell, rent or sublicense the Software, (b) distribute
+   modified copies of the Software, or (c) remove or alter copyright or licence notices.
+   You may redistribute unmodified copies of the Software, including this agreement,
+   for example as part of an internal mirror or a container image.
+
+3. Your data. The Software processes your notebooks and project files locally. It
+   does not collect telemetry and does not transmit your notebooks, results or source
+   code anywhere. Reports it writes stay where you put them.
+
+4. Future editions. Some future features may be offered under a separate paid
+   licence. Features available free of charge in a released version will not be
+   removed from that version, and the Software contains no hidden time limits or
+   disabling mechanisms.
+
+5. Third-party components. The Software depends on open-source packages that are
+   licensed under their own terms (see THIRD_PARTY_NOTICES.md). Nothing in this
+   agreement limits your rights under those licences.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. NoteDelta
+   reports observable differences between notebooks according to documented rules;
+   it does not determine whether results are scientifically valid or reproducible.
+
+7. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL
+   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+8. Termination. This licence ends automatically if you breach it. Sections 6 and 7
+   survive termination.

notedelta-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: notedelta
+Version: 0.1.0
+Summary: Scientific notebook review: what changed in your numerical results, how much, and can you trust the comparison.
+Project-URL: Homepage, https://github.com/ouyang-matters/notedelta
+Project-URL: Documentation, https://github.com/ouyang-matters/notedelta/tree/main/docs
+Project-URL: Issues, https://github.com/ouyang-matters/notedelta/issues
+Project-URL: Changelog, https://github.com/ouyang-matters/notedelta/blob/main/CHANGELOG.md
+Author: Ouyang Matters
+License-Expression: LicenseRef-NoteDelta-EULA
+License-File: LICENSE
+Keywords: diff,jupyter,notebook,numerical,regression,reproducibility,scientific computing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: nbformat>=5.7
+Requires-Dist: packaging>=23.0
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: execute
+Requires-Dist: ipykernel>=6.0; extra == 'execute'
+Requires-Dist: nbclient>=0.9; extra == 'execute'
+Description-Content-Type: text/markdown
+
+# NoteDelta
+
+**Know what changed in your scientific results, not just your code.**
+
+NoteDelta compares two versions of a Jupyter notebook and answers the question a code diff
+cannot: *which numerical results changed, by how much, does that exceed what I consider
+acceptable, and is there something about the environment I should check?*
+
+- **Configured scientific metrics.** Declare a metric once: how to find it, whether
+  lower or higher is better, and a tolerance. NoteDelta reports the exact difference,
+  the relative change, and whether it is a regression, an improvement or within
+  tolerance, and explains the rule it applied.
+- **Automatic numerical discovery.** Numbers in changed outputs (logs, printed values,
+  NumPy arrays, pandas tables, JSON) are paired and compared without configuration.
+  Because their direction is unknown, they are reported as changes, never as regressions.
+- **Reproducibility diagnostics.** Differences in kernel, Python version, locked package
+  versions, dependency declarations, random seeds and execution order are each labelled
+  as a *fact*, a *warning* or a *hypothesis*. NoteDelta never claims a cause it cannot show.
+
+NoteDelta runs entirely offline, never executes notebook code during comparison, sends no
+telemetry and needs no account.
+
+![NoteDelta HTML report](https://raw.githubusercontent.com/ouyang-matters/notedelta/main/docs/images/report-light.png)
+
+> **Status: beta (0.1).** The VS Code extension and the GitHub Marketplace listing are in
+> preparation. This repository hosts the documentation, the issue tracker, the licence and
+> the GitHub Action. The source code is not public.
+
+## Install
+
+NoteDelta needs Python 3.11 or newer and runs on Windows, macOS and Linux.
+
+```bash
+pip install notedelta
+pip install "notedelta[execute]"   # optional: opt-in notebook re-execution (runs code; not sandboxed)
+```
+
+## Quick look
+
+```bash
+notedelta compare baseline.ipynb experiment.ipynb
+```
+
+```text
+NoteDelta  baseline.ipynb → candidate.ipynb
+  1 regression, 2 numerical changes
+
+Scientific metrics
+  Metric                         Baseline  Candidate  Difference            Tolerance        Status
+  Relative reconstruction error  0.0073    0.0091     +0.0018 (+24.66%)     ±0.0001 or ±2%   REGRESSION
+  Total energy                   12.48331  12.48329   -0.00002 (-0.00016%)  ±0.001%          WITHIN TOL
+    reconstruction_error: Relative reconstruction error increased by 0.0018 (+24.66%) (0.0073 → 0.0091),
+    exceeding the configured tolerance (absolute 0.0001 or relative 2% of |baseline|; allowed change 0.000146).
+    The metric is declared 'minimize' (lower is better), so this is a regression.
+```
+
+Declare the metrics you care about in `.notedelta.yml`:
+
+```yaml
+version: 1
+metrics:
+  - name: reconstruction_error
+    label: Relative reconstruction error
+    direction: minimize
+    extraction:
+      type: regex
+      pattern: 'Relative reconstruction error\s*=\s*([0-9.eE+-]+)'
+    tolerance: {absolute: 0.0001, relative: 0.02}
+  - name: validation_accuracy
+    direction: maximize
+    unit: fraction            # shown as %, differences in percentage points
+    extraction: {type: key_value, key: Validation accuracy}
+    tolerance: {absolute: 0.002}
+```
+
+Use it as a check, locally or in CI:
+
+```bash
+notedelta compare a.ipynb b.ipynb --html report.html --fail-on-regression
+notedelta compare-git notebooks/analysis.ipynb --ref main
+```
+
+Exit codes: `0` ok, `1` a fail-on condition was met, `2` invalid input or configuration,
+`3` internal error.
+
+## GitHub Action
+
+This repository is also a GitHub Action that checks notebooks in pull requests. It writes
+a job summary, uploads the HTML and JSON reports and needs only read permission. It
+installs NoteDelta from PyPI.
+
+```yaml
+permissions:
+  contents: read
+jobs:
+  notedelta:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ouyang-matters/notedelta@v0.1.0
+        with:
+          notebooks: |
+            notebooks/**/*.ipynb
+          fail-on: regression,new_error
+```
+
+See [docs/ci.md](https://github.com/ouyang-matters/notedelta/blob/main/docs/ci.md) for all inputs.
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](https://github.com/ouyang-matters/notedelta/blob/main/docs/getting-started.md) | a ten-minute tutorial with the bundled [examples](https://github.com/ouyang-matters/notedelta/tree/main/examples) |
+| [CLI reference](https://github.com/ouyang-matters/notedelta/blob/main/docs/cli.md) | every command, option and exit code |
+| [Configuration](https://github.com/ouyang-matters/notedelta/blob/main/docs/configuration.md) | the `.notedelta.yml` v1 specification |
+| [Numerical comparison](https://github.com/ouyang-matters/notedelta/blob/main/docs/numerics.md) | formulas, tolerances, NaN/zero/precision handling, arrays and tables |
+| [Classification rules](https://github.com/ouyang-matters/notedelta/blob/main/docs/classification.md) | every rule that can label a result |
+| [Environment diagnostics](https://github.com/ouyang-matters/notedelta/blob/main/docs/environment.md) | what is inspected and how findings are graded |
+| [Report format](https://github.com/ouyang-matters/notedelta/blob/main/docs/report-format.md) | the versioned JSON report ([schema](https://github.com/ouyang-matters/notedelta/blob/main/docs/report-schema.json)) |
+| [VS Code extension](https://github.com/ouyang-matters/notedelta/blob/main/docs/vscode.md) · [GitHub Actions](https://github.com/ouyang-matters/notedelta/blob/main/docs/ci.md) | integrations |
+| [Security and privacy](https://github.com/ouyang-matters/notedelta/blob/main/docs/security.md) · [Known limitations](https://github.com/ouyang-matters/notedelta/blob/main/docs/limitations.md) | |
+
+Example reports generated by NoteDelta: [ML experiment](https://github.com/ouyang-matters/notedelta/blob/main/examples/reports/ml-experiment.html),
+[numerical simulation](https://github.com/ouyang-matters/notedelta/blob/main/examples/reports/numerical-simulation.html),
+[reproducibility](https://github.com/ouyang-matters/notedelta/blob/main/examples/reports/reproducibility.html). Download them and open locally;
+they are self-contained HTML files.
+
+## Feedback
+
+Bug reports, questions and feature requests are welcome in
+[Issues](https://github.com/ouyang-matters/notedelta/issues). Please report security
+problems privately (see [SECURITY.md](https://github.com/ouyang-matters/notedelta/blob/main/SECURITY.md)).
+
+## What NoteDelta is not
+
+NoteDelta reports observable differences and applies the rules you configure. It does not
+decide whether an experiment is scientifically valid or reproducible, does not infer
+statistical significance from two values, and does not interpret images (plots are
+compared by content hash). Interpretation remains the researcher's responsibility.
+
+## License
+
+Proprietary freeware, see [LICENSE](https://github.com/ouyang-matters/notedelta/blob/main/LICENSE). It is free to use, including commercially.
+Third-party components keep their own licences ([THIRD_PARTY_NOTICES.md](https://github.com/ouyang-matters/notedelta/blob/main/THIRD_PARTY_NOTICES.md)).

notedelta-0.1.0/README.md

@@ -0,0 +1,143 @@
+# NoteDelta
+
+**Know what changed in your scientific results, not just your code.**
+
+NoteDelta compares two versions of a Jupyter notebook and answers the question a code
+diff cannot: *which numerical results changed, by how much, does that exceed what I
+consider acceptable, and is there something about the environment I should check?*
+
+- **Configured scientific metrics** - declare a metric once (how to find it, whether
+  lower or higher is better, a tolerance). NoteDelta reports the exact difference,
+  relative change and whether it is a regression, an improvement or within tolerance,
+  and explains the rule it applied.
+- **Automatic numerical discovery** - numbers in changed outputs (logs, printed values,
+  NumPy arrays, pandas tables, JSON) are paired and compared even without configuration.
+  They are reported as changes, never as regressions, because their direction is unknown.
+- **Reproducibility diagnostics** - kernel, Python version, locked package versions,
+  dependency declarations, random seeds and execution order, each labelled as a
+  *fact*, a *warning* or a *hypothesis*. NoteDelta never claims a cause it cannot show.
+
+It runs entirely offline, never executes notebook code during comparison, sends no
+telemetry and needs no account.
+
+![NoteDelta HTML report](docs/images/report-light.png)
+
+## Install
+
+NoteDelta needs Python 3.11 or newer.
+
+```bash
+pip install notedelta
+pip install "notedelta[execute]" # optional: opt-in notebook re-execution
+```
+
+## Quick start
+
+```bash
+notedelta compare baseline.ipynb experiment.ipynb
+```
+
+```text
+NoteDelta  baseline.ipynb → candidate.ipynb
+  1 regression, 2 numerical changes
+  cells: +0 −0 ~6 moved 0 | outputs changed 5 | numbers compared 14 | reproducibility warnings 1
+
+Scientific metrics
+  Metric                         Baseline  Candidate  Difference            Tolerance           Status
+  Relative reconstruction error  0.0073    0.0091     +0.0018 (+24.66%)     ±0.0001 or ±2%      REGRESSION
+  Total energy                   12.48331  12.48329   -0.00002 (-0.00016%)  ±0.001%             WITHIN TOL
+  Energy drift                   1.20e-06  1.21e-06   +1e-8 (+0.83%)        ±5%                 WITHIN TOL
+    reconstruction_error: Relative reconstruction error increased by 0.0018 (+24.66%) (0.0073 → 0.0091),
+    exceeding the configured tolerance (absolute 0.0001 or relative 2% of |baseline|; allowed change 0.000146).
+    The metric is declared 'minimize' (lower is better), so this is a regression.
+
+Discovered numerical changes (no declared direction)
+  Cell  Value                    Baseline    Candidate   Difference                      Status
+  #3    Max residual             3.2e-08     4.1e-08     +9e-9 (+28.12%)                 CHANGED
+  #6    Out[6]: u[N // 2, ::16]  array (8,)  array (8,)  max |Δ| 4.843e-05; 7/8 changed  CHANGED
+```
+
+(Output of `examples/numerical-simulation`, unedited.)
+
+Declare the metrics you care about in `.notedelta.yml` (run `notedelta init` for a
+starter file):
+
+```yaml
+version: 1
+metrics:
+  - name: reconstruction_error
+    label: Relative reconstruction error
+    direction: minimize
+    extraction:
+      type: regex
+      pattern: 'Relative reconstruction error\s*=\s*([0-9.eE+-]+)'
+    tolerance:
+      absolute: 0.0001
+      relative: 0.02
+  - name: validation_accuracy
+    direction: maximize
+    unit: fraction            # shown as %, differences in percentage points
+    extraction: {type: key_value, key: Validation accuracy}
+    tolerance: {absolute: 0.002}
+```
+
+Reports and CI:
+
+```bash
+notedelta compare a.ipynb b.ipynb --html report.html --json report.json
+notedelta compare a.ipynb b.ipynb --fail-on-regression       # exit 1 on a configured regression
+notedelta compare-git notebooks/analysis.ipynb --ref main    # baseline = the file at a git revision
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | comparison completed, no fail-on condition met |
+| 1 | a fail-on condition was met (for example `--fail-on-regression`) |
+| 2 | invalid input: unreadable/corrupt notebook, invalid configuration, bad arguments |
+| 3 | internal, git or execution error |
+
+## Integrations
+
+- **VS Code** (`extensions/vscode`): compare with a git baseline or another notebook,
+  results view, HTML report panel, jump to the affected cell. See [docs/vscode.md](docs/vscode.md).
+- **GitHub Actions** (`integrations/github-actions`): check notebooks in pull requests,
+  job summary, HTML reports as artifacts, read-only permissions. See [docs/ci.md](docs/ci.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | a ten-minute tutorial with the bundled examples |
+| [CLI reference](docs/cli.md) | every command, option and exit code |
+| [Configuration](docs/configuration.md) | the `.notedelta.yml` v1 specification |
+| [Numerical comparison](docs/numerics.md) | formulas, tolerances, NaN/zero/precision handling, arrays and tables |
+| [Classification rules](docs/classification.md) | every rule that can label a result, with its explanation |
+| [Environment diagnostics](docs/environment.md) | what is inspected and how findings are graded |
+| [Report format](docs/report-format.md) | the versioned JSON report |
+| [Architecture](docs/architecture.md) | how the pieces fit together |
+| [Security and privacy](docs/security.md) | threat model, execution, redaction |
+| [Known limitations](docs/limitations.md) | what NoteDelta does not do |
+| [Licensing and editions](docs/licensing.md) | licence, dependencies, provisional Free/Pro boundary |
+| [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Release process](docs/release.md) | |
+
+## What NoteDelta is not
+
+NoteDelta reports observable differences and applies the rules you configure. It does
+not decide whether an experiment is scientifically valid or reproducible, does not
+infer statistical significance from two values, and does not interpret images (plots
+are compared by content hash). Interpretation remains the researcher's responsibility.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/activate      # or: source .venv/bin/activate
+pip install -e ".[dev,execute]"
+pytest                      # unit, integration, regression tests
+ruff check src tests && ruff format --check src tests && mypy
+python scripts/benchmark.py # performance on a large generated notebook pair
+```
+
+## License
+
+Proprietary freeware, see [LICENSE](LICENSE). Free to use, including commercially.
+Third-party components keep their own licences ([THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)).

notedelta-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,24 @@
+# Third-party notices
+
+NoteDelta does not bundle third-party code. It depends on the following packages, which
+pip installs from PyPI under their own licences (versions measured for NoteDelta 0.1.0):
+
+| Package | Licence |
+|---|---|
+| nbformat | BSD-3-Clause |
+| pydantic, pydantic-core, annotated-types, typing-inspection | MIT |
+| PyYAML | MIT |
+| packaging | Apache-2.0 OR BSD-2-Clause |
+| jsonschema, jsonschema-specifications, referencing, rpds-py, attrs | MIT |
+| fastjsonschema | BSD-3-Clause |
+| traitlets, jupyter_core | BSD-3-Clause |
+| platformdirs | MIT |
+| typing_extensions | PSF-2.0 |
+
+Optional `notedelta[execute]`: nbclient, ipykernel, jupyter_client, pyzmq, IPython,
+psutil (BSD); tornado, asttokens (Apache-2.0); debugpy, jedi, parso (MIT); libzmq
+(bundled in pyzmq wheels, MPL-2.0).
+
+The VS Code extension contains only NoteDelta code. Its build tools (TypeScript,
+@vscode/vsce, @vscode/test-electron, @types/*) are development dependencies and are not
+included in the `.vsix`.

notedelta-0.1.0/extensions/vscode/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- First preview: compare with another notebook or a git baseline, results view, HTML
+  report panel, regression and reproducibility quick picks, jump to cell, starter
+  configuration.

notedelta-0.1.0/extensions/vscode/LICENSE

@@ -0,0 +1,43 @@
+NoteDelta End User License Agreement
+Version 1.0 (draft for the 0.1 beta)
+
+Copyright (c) 2026 Ouyang Matters. All rights reserved.
+
+This agreement covers the NoteDelta command-line tool and Python package, the NoteDelta
+extension for Visual Studio Code, the NoteDelta GitHub Actions integration and their
+documentation (together, the "Software").
+
+1. Licence grant. You may install and use the Software, free of charge, on any number
+   of computers, for personal, academic, research and commercial purposes, including
+   in continuous-integration systems that you or your organisation operate.
+
+2. Restrictions. You may not (a) sell, rent or sublicense the Software, (b) distribute
+   modified copies of the Software, or (c) remove or alter copyright or licence notices.
+   You may redistribute unmodified copies of the Software, including this agreement,
+   for example as part of an internal mirror or a container image.
+
+3. Your data. The Software processes your notebooks and project files locally. It
+   does not collect telemetry and does not transmit your notebooks, results or source
+   code anywhere. Reports it writes stay where you put them.
+
+4. Future editions. Some future features may be offered under a separate paid
+   licence. Features available free of charge in a released version will not be
+   removed from that version, and the Software contains no hidden time limits or
+   disabling mechanisms.
+
+5. Third-party components. The Software depends on open-source packages that are
+   licensed under their own terms (see THIRD_PARTY_NOTICES.md). Nothing in this
+   agreement limits your rights under those licences.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. NoteDelta
+   reports observable differences between notebooks according to documented rules;
+   it does not determine whether results are scientifically valid or reproducible.
+
+7. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL
+   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+8. Termination. This licence ends automatically if you breach it. Sections 6 and 7
+   survive termination.

notedelta-0.1.0/extensions/vscode/README.md

@@ -0,0 +1,51 @@
+# NoteDelta for VS Code
+
+**Know what changed in your scientific results, not just your code.**
+
+NoteDelta compares two versions of a Jupyter notebook and tells you which numerical
+results changed, by how much, whether a configured metric regressed beyond its
+tolerance, and which environment differences (kernel, Python, locked package
+versions, random seeds) deserve a look. It works offline and never runs notebook code.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| **NoteDelta: Compare Notebook with Git Baseline** | Compares the saved notebook with the same file at a git revision (default `HEAD`). Also in the notebook toolbar and the Explorer context menu. |
+| **NoteDelta: Compare Notebook with…** | Compares the current notebook with any other `.ipynb` file. |
+| **NoteDelta: Open NoteDelta Report** | Opens the self-contained HTML report beside the notebook (no scripts). |
+| **NoteDelta: Show Numerical Regressions** | Quick pick of regressions and changed numbers; choosing one jumps to the cell. |
+| **NoteDelta: Show Reproducibility Warnings** | Environment facts, warnings and (clearly labelled) hypotheses. |
+| **NoteDelta: Configure Metrics and Tolerances** | Opens `.notedelta.yml`, or creates a starter file after asking. |
+
+The **NoteDelta** view in the activity bar lists metrics, numerical changes, environment
+findings and changed cells; clicking an entry opens the corresponding cell.
+
+## Requirements
+
+The extension is a thin client for the NoteDelta command-line tool (Python 3.11+):
+
+```bash
+pip install notedelta
+```
+
+If `notedelta` is not on your `PATH`, set **`notedelta.pythonPath`** to the interpreter
+where it is installed. In untrusted workspaces, workspace-level values of
+`notedelta.pythonPath` and `notedelta.cliPath` are ignored so a repository cannot choose
+which program runs.
+
+## Settings
+
+- `notedelta.pythonPath`, `notedelta.cliPath` - where to find the CLI.
+- `notedelta.gitRef` - default baseline revision (`HEAD`).
+- `notedelta.configFile` - explicit `.notedelta.yml` (otherwise searched upwards from the notebook).
+- `notedelta.embedImages` - show changed plots side by side in the report.
+- `notedelta.openReportAfterCompare`, `notedelta.timeoutSeconds`.
+
+## Privacy
+
+No telemetry. Notebooks are read locally by the CLI; nothing is uploaded. Reports are
+written to the extension's storage folder and pruned after 7 days.
+
+NoteDelta reports observable differences and applies the rules you configure. Scientific
+interpretation remains yours.