sherlorch 0.1.0__tar.gz

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

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v

sherlorch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sherlorch/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

sherlorch-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+*.whl
+.DS_Store
+.ipynb_checkpoints/

sherlorch-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-23
+
+### Added
+- Core `ProvenanceTracker` (`torch.overrides.TorchFunctionMode`-based) recording
+  an op-level provenance DAG for every tensor produced while tracing is active.
+- `diagnose(tensor)`: backward search from a non-finite tensor to the op(s) that
+  first introduced NaN/Inf, with the path from culprit to target.
+- `tracker.watch(model)` / `unwatch()`: tag recorded ops with the submodule that
+  produced them, via forward hooks. Hooks auto-removed on `with` block exit.
+- `fast_shape_ops` (default `True`): shape-preserving ops (`view`, `permute`,
+  `cat`, etc.) inherit finiteness from parent nodes instead of re-scanning,
+  exact rather than approximate.
+- `capture_stack`: optional `file:line` capture per recorded op.
+- `has_issue()`, `enable()`/`disable()`, `reset()` utility methods.
+- Benchmark suite (`benchmarks/bench_overhead.py`) and demo notebook
+  (`notebooks/sherlorch_demo.ipynb`).
+- Test suite covering division-by-zero, log-of-negative, multi-source culprit
+  merging, module tagging, fast-path correctness, and lifecycle edge cases.

sherlorch-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Code of Conduct
+
+This project follows the spirit of the [Contributor Covenant](https://www.contributor-covenant.org/):
+be respectful, assume good faith, and keep disagreements focused on the technical merits.
+
+In short:
+
+- Be welcoming and patient, especially with people new to PyTorch internals or open source.
+- Give and receive feedback about code, not people.
+- Harassment, discriminatory language, and personal attacks are not tolerated, in issues,
+  PRs, or any other project space.
+- Maintainers may edit, remove, or reject contributions and comments that don't follow this,
+  and may block repeat offenders.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please open an issue (or, for sensitive
+reports, contact the maintainers directly via the contact info on their GitHub profile).
+Reports will be handled with discretion.

sherlorch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to sherlorch
+
+Thanks for considering a contribution — this project is intentionally small and
+sharply scoped, so even a modest PR can meaningfully move it forward.
+
+## Setup
+
+```bash
+git clone https://github.com/SankaVaas/sherlorch.git
+cd sherlorch
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+All new behavior needs a test. If you're fixing a bug, add a test that fails
+without your fix and passes with it.
+
+## Running the benchmark
+
+```bash
+python benchmarks/bench_overhead.py
+```
+
+This regenerates `benchmarks/results/overhead_results.csv` and the two plots in
+`assets/`. If your change affects performance (positively or negatively),
+please re-run this and include the updated numbers in your PR description —
+we'd rather see the real effect than guess at it.
+
+## Design principles
+
+- **Never crash the user's workload.** All instrumentation in `_record()` is
+  wrapped in `try/except Exception: pass`. If you add new instrumentation,
+  keep that guarantee.
+- **No strong references to traced tensors.** We track tensors by `id()` with
+  a weakref cleanup callback specifically so tracing doesn't extend a
+  tensor's lifetime or blow up memory on long runs. Don't reintroduce a
+  `WeakKeyDictionary` keyed by the tensor itself — `torch.Tensor.__eq__` is
+  elementwise, which breaks dict lookup machinery in ways that are easy to
+  miss in a quick test (see the history of `tracker.py` for the exact
+  failure mode).
+- **Exactness over approximation for `fast_shape_ops`.** Any op added to
+  `_SHAPE_PRESERVING_OPS` in `tracker.py` must be provably incapable of
+  turning a finite input into a non-finite output. When in doubt, leave it
+  out — a missed optimization is a performance cost, but a wrong one is a
+  correctness bug in a debugging tool, which defeats the point.
+
+## Good first contributions
+
+- More reliable backward-pass op-name capture
+- An optional Graphviz/HTML export of the provenance DAG
+- Expanding `_SHAPE_PRESERVING_OPS` to cover more of the dispatcher surface
+  (with a test proving each addition is safe)
+- A sampling mode for very large tensors, if you can characterize the
+  correctness/performance tradeoff clearly
+
+## Pull requests
+
+- Keep PRs focused — one behavior change per PR is easier to review and revert.
+- Update `CHANGELOG.md` under `[Unreleased]`.
+- Update the README if you're changing public API or documented behavior.
+
+## Reporting bugs
+
+Open an issue with a minimal repro. If it's a case where `sherlorch` gives a
+wrong diagnosis (rather than crashing), that's especially important — please
+include the model/ops involved, since it likely means `_SHAPE_PRESERVING_OPS`
+or the finiteness-checking logic needs a fix.

sherlorch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tensortrace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sherlorch-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: sherlorch
+Version: 0.1.0
+Summary: PyTorch-first tensor provenance debugger: find the exact op that introduced a NaN/Inf.
+Project-URL: Homepage, https://github.com/SankaVaas/sherlorch
+Project-URL: Issues, https://github.com/SankaVaas/sherlorch/issues
+Project-URL: Changelog, https://github.com/SankaVaas/sherlorch/blob/main/CHANGELOG.md
+Author: Sanka Vaas
+License: MIT
+License-File: LICENSE
+Keywords: autograd,debugging,deep-learning,nan,provenance,pytorch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: torch>=2.0
+Provides-Extra: benchmark
+Requires-Dist: matplotlib>=3.5; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![sherlorch name logo](<docs/images/sherlorch name logo.png>)
+
+# sherlorch
+
+[![CI](https://github.com/SankaVaas/sherlorch/actions/workflows/ci.yml/badge.svg)](https://github.com/SankaVaas/sherlorch/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/sherlorch.svg)](https://pypi.org/project/sherlorch/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sherlorch.svg)](https://pypi.org/project/sherlorch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Code style](https://img.shields.io/badge/types-checked-brightgreen.svg)](https://peps.python.org/pep-0561/)
+
+**Find the exact op that introduced a NaN or Inf into your PyTorch model — not just the line where you noticed it.**
+
+Every deep learning researcher knows this moment: `loss.backward()` returns `nan`, and now you're bisecting your forward pass by hand, printing `.isnan().any()` after every other line. `sherlorch` automates that entire process.
+
+It works by transparently intercepting every tensor operation while active (via `torch.overrides.TorchFunctionMode` — no hooks to register, no model changes needed), building a lightweight op-level provenance graph. When you point it at a bad tensor, it walks that graph backward and tells you precisely which operation, on which inputs, first produced the non-finite value — plus the path from there to the tensor you noticed the problem in.
+
+```
+sherlorch diagnosis for [14] layer_norm (shape=(4, 4, 16, 32)):
+  Found 1 culprit op(s) out of 15 traced ops.
+
+  Culprit #1: [10] log  shape=(4, 4, 16, 16) dtype=torch.float32  [model.layer1]  (train.py:27)  <-- Inf
+    Path to target:
+      -> [10] log  ...  [model.layer1]  <-- Inf
+      -> [11] mean  ...  [model]  <-- Inf
+      -> [12] unsqueeze  ...  [model]  <-- Inf
+      -> [13] add  ...  [model]  <-- Inf
+      -> [14] layer_norm  ...  [model.norm]  <-- NaN
+```
+
+That's real output from [`examples/find_nan_in_transformer.py`](examples/find_nan_in_transformer.py) — a `log(relu(x))` bug buried two submodules deep, found and localized to `model.layer1` in one traced run, no bisection required.
+
+## Contents
+
+- [sherlorch](#sherlorch)
+  - [Contents](#contents)
+  - [Install](#install)
+  - [Quickstart](#quickstart)
+    - [Options](#options)
+  - [Module tagging](#module-tagging)
+  - [Perf mode](#perf-mode)
+  - [Benchmarks](#benchmarks)
+  - [How it works](#how-it-works)
+  - [Costs and limitations](#costs-and-limitations)
+  - [Try it](#try-it)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+## Install
+
+```bash
+pip install sherlorch
+```
+
+Or from a clone, for local development:
+
+```bash
+git clone https://github.com/SankaVaas/sherlorch.git
+cd sherlorch
+pip install -e ".[dev]"
+```
+
+Requires `torch>=2.0`, Python `>=3.9`.
+
+## Quickstart
+
+```python
+import torch
+import sherlorch
+
+with sherlorch.trace() as tracker:
+    out = model(x)
+    loss = criterion(out, y)
+    loss.backward()
+
+if tracker.has_issue(loss):
+    print(tracker.diagnose(loss))
+```
+
+Example output:
+
+```
+sherlorch diagnosis for [812] sum (shape=()):
+  Found 1 culprit op(s) out of 811 traced ops.
+
+  Culprit #1: [340] div  shape=(32, 128) dtype=torch.float32  (train.py:57)  <-- Inf
+    Path to target:
+      -> [340] div  shape=(32, 128) dtype=torch.float32  (train.py:57)  <-- Inf
+      -> [341] mul  shape=(32, 128) dtype=torch.float32  <-- Inf
+      -> [812] sum  shape=()  <-- Inf
+```
+
+### Options
+
+| Option | Default | What it does |
+|---|---|---|
+| `sherlorch.trace(capture_stack=True)` | `False` | Attach a `file:line` to each recorded op. Useful while actively hunting a bug; adds real overhead (see [Benchmarks](#benchmarks)), especially inside Jupyter/IPython. |
+| `sherlorch.trace(fast_shape_ops=False)` | `True` | Force a full isnan/isinf scan on every op, including shape-only ops. See [Perf mode](#perf-mode). |
+| `tracker.watch(model, name="model")` | — | Tag every recorded op with the submodule that produced it. See [Module tagging](#module-tagging). |
+| `tracker.disable()` / `enable()` | — | Pause/resume recording inside the `with` block, e.g. to skip a warmup loop. |
+| `tracker.reset()` | — | Drop all recorded provenance, e.g. between training steps, to bound memory on long runs. |
+| `tracker.has_issue(tensor)` | — | Cheap NaN/Inf check on any live tensor, tracked or not. |
+
+## Module tagging
+
+Wrap `model(x)` with `tracker.watch(model)` and every op's diagnosis includes which submodule produced it:
+
+```python
+with sherlorch.trace() as tracker:
+    tracker.watch(model, name="model")
+    out = model(x)
+
+print(tracker.diagnose(out))
+```
+
+That `[model.layer1]` tag comes straight from `model.named_modules()`, so it matches whatever names you gave your submodules. Hooks are removed automatically when the `with` block exits, or manually via `tracker.unwatch()`. Best-effort: relies on forward hooks firing in normal LIFO order, which activation checkpointing or re-entrant forward calls can disrupt.
+
+## Perf mode
+
+By default (`fast_shape_ops=True`), ops that can only rearrange, copy, index, or combine existing values — `view`, `reshape`, `permute`, `transpose`, `cat`, `stack`, `narrow`, and similar — skip the isnan/isinf tensor scan entirely and instead **inherit** finiteness from their parent node(s). This is exact, not an approximation: those ops provably cannot introduce a NaN/Inf that wasn't already in one of their inputs (dtype-narrowing ops like `.to()`/`.half()` are deliberately excluded, since precision loss can itself overflow to Inf). Since transformer-style models are full of reshapes and permutes, this cuts meaningful overhead — and the savings grow with tensor size, since the skipped scan cost is proportional to tensor size while inheritance is O(1).
+
+## Benchmarks
+
+Measured on a small transformer attention block (`benchmarks/bench_overhead.py`, CPU, median of 15 runs after warmup — see [`benchmarks/results/overhead_results.csv`](benchmarks/results/overhead_results.csv) for raw numbers and reproduce with `python benchmarks/bench_overhead.py`):
+
+<p align="center">
+  <img src="assets/benchmark_overhead.png" width="600" alt="sherlorch tracing overhead vs model size">
+</p>
+
+<p align="center">
+  <img src="assets/benchmark_speedup.png" width="600" alt="sherlorch overhead multiplier, fast_shape_ops on vs off">
+</p>
+
+Takeaways from the actual measured numbers:
+
+- **`fast_shape_ops=True` (default) consistently cuts 35–47% off tracing overhead** compared to always doing a full scan, across model sizes from d_model=64 to d_model=1024.
+- **The overhead multiplier shrinks as models get bigger** — at d_model=64 the default mode is ~3.9x baseline forward-pass time, dropping to ~1.5x at d_model=1024, because per-op Python bookkeeping is a fixed cost while actual tensor compute grows with size and dominates more.
+- **`capture_stack=True` is the expensive option** — it's fine in a plain script, but calls `inspect.stack()`, which is dramatically more costly under Jupyter/IPython's deeper call stacks (see the walkthrough and real numbers in [`notebooks/sherlorch_demo.ipynb`](notebooks/sherlorch_demo.ipynb)). Turn it off, or use it sparingly, inside notebooks.
+
+This is a **debugging tool**, not something to leave on during real training — the numbers above are the honest cost of that convenience, not a claim that tracing is free.
+
+## How it works
+
+`ProvenanceTracker` is a `TorchFunctionMode`. While active, every `torch.*` call is intercepted: the op runs normally, and a small `OpNode` (op name, shape, dtype, finite/nan/inf flags, optional module tag and source location) is recorded and linked to the `OpNode`s of its input tensors. Tensors are tracked by `id()` in a plain dict, not by the tensor object itself — `torch.Tensor.__eq__` is elementwise, which breaks the equality checks a `WeakKeyDictionary` needs internally. A `weakref` callback removes each entry as soon as its tensor is garbage collected, so a later `id()` reuse can never collide with a stale entry, and traced tensors are never kept alive artificially.
+
+`diagnose(tensor)` then does a backward BFS from the target tensor's node, following only the non-finite ancestors, until it finds nodes whose inputs were *all* finite — those are the culprits: the operations that actually introduced the corruption, as opposed to ones that merely inherited it.
+
+## Costs and limitations
+
+- This is a **debugging tool**, not something to leave on during real training — see [Benchmarks](#benchmarks) for the actual measured overhead.
+- Backward-pass ops are captured on a best-effort basis; some fused/kernel-level backward computation may not surface individual sub-ops.
+- Only tensors actually produced *while tracing was active* have provenance; tensors created outside the `with` block, or moved off the tracked identity (e.g. via certain C++-side aliasing), will raise `KeyError` on `diagnose()`.
+- Module tagging via `watch()` assumes normally-nested forward calls; activation checkpointing or re-entrant forward passes can produce imprecise tags.
+
+## Try it
+
+- [`examples/find_nan_in_transformer.py`](examples/find_nan_in_transformer.py) — a runnable script reproducing the example at the top of this README.
+- [`notebooks/sherlorch_demo.ipynb`](notebooks/sherlorch_demo.ipynb) — an executed walkthrough covering the minimal repro, module tagging on a small transformer, the full benchmark suite with plots, and a comparison with how you'd normally debug this.
+
+## Contributing
+
+Issues and PRs welcome — this is intentionally a small, sharply-scoped tool. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, design principles, and good first contributions, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sherlorch-0.1.0/README.md

@@ -0,0 +1,165 @@
+![sherlorch name logo](<docs/images/sherlorch name logo.png>)
+
+# sherlorch
+
+[![CI](https://github.com/SankaVaas/sherlorch/actions/workflows/ci.yml/badge.svg)](https://github.com/SankaVaas/sherlorch/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/sherlorch.svg)](https://pypi.org/project/sherlorch/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sherlorch.svg)](https://pypi.org/project/sherlorch/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Code style](https://img.shields.io/badge/types-checked-brightgreen.svg)](https://peps.python.org/pep-0561/)
+
+**Find the exact op that introduced a NaN or Inf into your PyTorch model — not just the line where you noticed it.**
+
+Every deep learning researcher knows this moment: `loss.backward()` returns `nan`, and now you're bisecting your forward pass by hand, printing `.isnan().any()` after every other line. `sherlorch` automates that entire process.
+
+It works by transparently intercepting every tensor operation while active (via `torch.overrides.TorchFunctionMode` — no hooks to register, no model changes needed), building a lightweight op-level provenance graph. When you point it at a bad tensor, it walks that graph backward and tells you precisely which operation, on which inputs, first produced the non-finite value — plus the path from there to the tensor you noticed the problem in.
+
+```
+sherlorch diagnosis for [14] layer_norm (shape=(4, 4, 16, 32)):
+  Found 1 culprit op(s) out of 15 traced ops.
+
+  Culprit #1: [10] log  shape=(4, 4, 16, 16) dtype=torch.float32  [model.layer1]  (train.py:27)  <-- Inf
+    Path to target:
+      -> [10] log  ...  [model.layer1]  <-- Inf
+      -> [11] mean  ...  [model]  <-- Inf
+      -> [12] unsqueeze  ...  [model]  <-- Inf
+      -> [13] add  ...  [model]  <-- Inf
+      -> [14] layer_norm  ...  [model.norm]  <-- NaN
+```
+
+That's real output from [`examples/find_nan_in_transformer.py`](examples/find_nan_in_transformer.py) — a `log(relu(x))` bug buried two submodules deep, found and localized to `model.layer1` in one traced run, no bisection required.
+
+## Contents
+
+- [sherlorch](#sherlorch)
+  - [Contents](#contents)
+  - [Install](#install)
+  - [Quickstart](#quickstart)
+    - [Options](#options)
+  - [Module tagging](#module-tagging)
+  - [Perf mode](#perf-mode)
+  - [Benchmarks](#benchmarks)
+  - [How it works](#how-it-works)
+  - [Costs and limitations](#costs-and-limitations)
+  - [Try it](#try-it)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+## Install
+
+```bash
+pip install sherlorch
+```
+
+Or from a clone, for local development:
+
+```bash
+git clone https://github.com/SankaVaas/sherlorch.git
+cd sherlorch
+pip install -e ".[dev]"
+```
+
+Requires `torch>=2.0`, Python `>=3.9`.
+
+## Quickstart
+
+```python
+import torch
+import sherlorch
+
+with sherlorch.trace() as tracker:
+    out = model(x)
+    loss = criterion(out, y)
+    loss.backward()
+
+if tracker.has_issue(loss):
+    print(tracker.diagnose(loss))
+```
+
+Example output:
+
+```
+sherlorch diagnosis for [812] sum (shape=()):
+  Found 1 culprit op(s) out of 811 traced ops.
+
+  Culprit #1: [340] div  shape=(32, 128) dtype=torch.float32  (train.py:57)  <-- Inf
+    Path to target:
+      -> [340] div  shape=(32, 128) dtype=torch.float32  (train.py:57)  <-- Inf
+      -> [341] mul  shape=(32, 128) dtype=torch.float32  <-- Inf
+      -> [812] sum  shape=()  <-- Inf
+```
+
+### Options
+
+| Option | Default | What it does |
+|---|---|---|
+| `sherlorch.trace(capture_stack=True)` | `False` | Attach a `file:line` to each recorded op. Useful while actively hunting a bug; adds real overhead (see [Benchmarks](#benchmarks)), especially inside Jupyter/IPython. |
+| `sherlorch.trace(fast_shape_ops=False)` | `True` | Force a full isnan/isinf scan on every op, including shape-only ops. See [Perf mode](#perf-mode). |
+| `tracker.watch(model, name="model")` | — | Tag every recorded op with the submodule that produced it. See [Module tagging](#module-tagging). |
+| `tracker.disable()` / `enable()` | — | Pause/resume recording inside the `with` block, e.g. to skip a warmup loop. |
+| `tracker.reset()` | — | Drop all recorded provenance, e.g. between training steps, to bound memory on long runs. |
+| `tracker.has_issue(tensor)` | — | Cheap NaN/Inf check on any live tensor, tracked or not. |
+
+## Module tagging
+
+Wrap `model(x)` with `tracker.watch(model)` and every op's diagnosis includes which submodule produced it:
+
+```python
+with sherlorch.trace() as tracker:
+    tracker.watch(model, name="model")
+    out = model(x)
+
+print(tracker.diagnose(out))
+```
+
+That `[model.layer1]` tag comes straight from `model.named_modules()`, so it matches whatever names you gave your submodules. Hooks are removed automatically when the `with` block exits, or manually via `tracker.unwatch()`. Best-effort: relies on forward hooks firing in normal LIFO order, which activation checkpointing or re-entrant forward calls can disrupt.
+
+## Perf mode
+
+By default (`fast_shape_ops=True`), ops that can only rearrange, copy, index, or combine existing values — `view`, `reshape`, `permute`, `transpose`, `cat`, `stack`, `narrow`, and similar — skip the isnan/isinf tensor scan entirely and instead **inherit** finiteness from their parent node(s). This is exact, not an approximation: those ops provably cannot introduce a NaN/Inf that wasn't already in one of their inputs (dtype-narrowing ops like `.to()`/`.half()` are deliberately excluded, since precision loss can itself overflow to Inf). Since transformer-style models are full of reshapes and permutes, this cuts meaningful overhead — and the savings grow with tensor size, since the skipped scan cost is proportional to tensor size while inheritance is O(1).
+
+## Benchmarks
+
+Measured on a small transformer attention block (`benchmarks/bench_overhead.py`, CPU, median of 15 runs after warmup — see [`benchmarks/results/overhead_results.csv`](benchmarks/results/overhead_results.csv) for raw numbers and reproduce with `python benchmarks/bench_overhead.py`):
+
+<p align="center">
+  <img src="assets/benchmark_overhead.png" width="600" alt="sherlorch tracing overhead vs model size">
+</p>
+
+<p align="center">
+  <img src="assets/benchmark_speedup.png" width="600" alt="sherlorch overhead multiplier, fast_shape_ops on vs off">
+</p>
+
+Takeaways from the actual measured numbers:
+
+- **`fast_shape_ops=True` (default) consistently cuts 35–47% off tracing overhead** compared to always doing a full scan, across model sizes from d_model=64 to d_model=1024.
+- **The overhead multiplier shrinks as models get bigger** — at d_model=64 the default mode is ~3.9x baseline forward-pass time, dropping to ~1.5x at d_model=1024, because per-op Python bookkeeping is a fixed cost while actual tensor compute grows with size and dominates more.
+- **`capture_stack=True` is the expensive option** — it's fine in a plain script, but calls `inspect.stack()`, which is dramatically more costly under Jupyter/IPython's deeper call stacks (see the walkthrough and real numbers in [`notebooks/sherlorch_demo.ipynb`](notebooks/sherlorch_demo.ipynb)). Turn it off, or use it sparingly, inside notebooks.
+
+This is a **debugging tool**, not something to leave on during real training — the numbers above are the honest cost of that convenience, not a claim that tracing is free.
+
+## How it works
+
+`ProvenanceTracker` is a `TorchFunctionMode`. While active, every `torch.*` call is intercepted: the op runs normally, and a small `OpNode` (op name, shape, dtype, finite/nan/inf flags, optional module tag and source location) is recorded and linked to the `OpNode`s of its input tensors. Tensors are tracked by `id()` in a plain dict, not by the tensor object itself — `torch.Tensor.__eq__` is elementwise, which breaks the equality checks a `WeakKeyDictionary` needs internally. A `weakref` callback removes each entry as soon as its tensor is garbage collected, so a later `id()` reuse can never collide with a stale entry, and traced tensors are never kept alive artificially.
+
+`diagnose(tensor)` then does a backward BFS from the target tensor's node, following only the non-finite ancestors, until it finds nodes whose inputs were *all* finite — those are the culprits: the operations that actually introduced the corruption, as opposed to ones that merely inherited it.
+
+## Costs and limitations
+
+- This is a **debugging tool**, not something to leave on during real training — see [Benchmarks](#benchmarks) for the actual measured overhead.
+- Backward-pass ops are captured on a best-effort basis; some fused/kernel-level backward computation may not surface individual sub-ops.
+- Only tensors actually produced *while tracing was active* have provenance; tensors created outside the `with` block, or moved off the tracked identity (e.g. via certain C++-side aliasing), will raise `KeyError` on `diagnose()`.
+- Module tagging via `watch()` assumes normally-nested forward calls; activation checkpointing or re-entrant forward passes can produce imprecise tags.
+
+## Try it
+
+- [`examples/find_nan_in_transformer.py`](examples/find_nan_in_transformer.py) — a runnable script reproducing the example at the top of this README.
+- [`notebooks/sherlorch_demo.ipynb`](notebooks/sherlorch_demo.ipynb) — an executed walkthrough covering the minimal repro, module tagging on a small transformer, the full benchmark suite with plots, and a comparison with how you'd normally debug this.
+
+## Contributing
+
+Issues and PRs welcome — this is intentionally a small, sharply-scoped tool. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, design principles, and good first contributions, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).