nervecode 0.1.0__tar.gz

nervecode-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+plan.md
+todo.md
+runs/
+scripts/rundev.py
+.claude
+.mypy_cache
+.pytest_cache
+.ruff_cache
+data

nervecode-0.1.0/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+
+## v0.1.0 — 2026-04-07
+
+- Initial preview release. Establishes PyTorch-native coding wrappers (Linear/Conv2d),
+  layerwise surprise aggregation (mean/max/weighted), calibration utilities,
+  a `WrappedModel` container, training utilities, benchmarks (CIFAR-10 OOD, MNIST OOD),
+  and a CPU-friendly experiment suite and scripts. Includes CI (lint/typecheck/tests),
+  docs scaffolding, and example scripts.
+
+- Wrappers and model container: Disabling coding now clears any cached
+  per-layer traces immediately (fail-open) so that model-level behavior (e.g.,
+  `WrappedModel.surprise()`) reflects the disabled state without requiring an
+  extra forward pass.
+
+- API stability: Locked the minimal public surface via explicit __all__ in
+  packages and added tests (including star-import check) to prevent accidental
+  API creep until the MVP is validated on real examples/benchmarks.
+
+- Tests: Separated fast correctness tests from heavy runs by introducing
+  `benchmark` and `slow` markers and deselecting them by default; CI runs only
+  the fast suite to keep pipelines reliable and quick. See CONTRIBUTING and
+  `docs/benchmarks.md` for how to include them locally.
+
+- Docs: Added `docs/benchmarks.md` template for experiment/benchmark reports to
+  standardize documentation and avoid one‑off notebooks.
+
+- Docs: Added `docs/scaling.md` covering selected-layer instrumentation, reduced
+  coding spaces, and practical tradeoffs between expressivity and overhead.
+
+- Layers: Added experimental convolutional reducers in `nervecode.layers.reducers`.
+  Includes a token-like spatial view (BHWC) for Conv2d outputs and a global
+  max-pooling reducer. These are opt-in via the existing `reducer=` parameter on
+  `CodingConv2d` and do not change defaults. Added a unit test exercising the
+  token-like path.
+
+- Training: Added experimental `EmaCodebookUpdater` (off by default) to update
+  codebook centers via EMA of batch-weighted means from a `CodingTrace`. Keeps
+  gradient-updated baseline unchanged; enables hybrid exploration when needed.
+
+- Docs: Added `docs/quickstart.md` explaining the end-to-end user flow and
+  mirroring the `examples/quickstart_mlp.py` script.
+
+- Benchmarks: Added `benchmarks/scaling/study.py` with `run_scaling_study` and a CLI
+  to measure compute (per-iteration time) and memory proxies (parameter and
+  activation overhead) as a function of layer width, coding dimension, and the
+  number of instrumented layers. Includes a unit test.
+
+- Scripts: Added `scripts/ablate_grid.py` to run ablations varying codebook size (K),
+  coding dimension (D), temperature (T), and layer selection strategy. Records
+  minimal quality (test accuracy) and approximate overhead proxies, and can write
+  results to CSV for quick analysis.
+
+- Tests: Added deterministic, explainability-focused unit tests for richer
+  aggregation modes (fixed weighted and max) on hand-constructed examples to
+  ensure stable outputs and clear aggregation metadata.
+
+- Tests: Added checkpoint-compatibility tests covering two common flows —
+  loading base-model weights before instrumentation and loading wrapped-model
+  checkpoints together with calibrator state after calibration.
+
+- Scoring: Implemented `weighted_surprise(...)` for fixed weighted aggregation
+  across layers with a simple configuration interface (layer-name or index-aligned
+  weights; optional normalization). Learnable aggregation is intentionally
+  deferred pending evidence of real-world benefit.
+
+- Scoring: Added `max_surprise(...)` as a supported alternative to
+  `mean_surprise(...)`, returning the same `AggregatedSurprise` result type and
+  plugging into existing calibrator flows.
+
+- Docs: Added rationale explaining why the first Conv2d wrapper uses pooled
+  coding and why richer spatial modes are deferred (see `docs/architecture.md`).
+
+- Wrap: `nervecode.layers.wrap.wrap` can now instrument convolutional layers explicitly
+  and via the shortcut `layers="all_conv"` (currently wraps `nn.Conv2d` with
+  `CodingConv2d`).
+
+- Examples: Added `examples/quickstart_cnn.py` demonstrating a small CNN where
+  pooled Conv2d traces contribute to the aggregated per-sample surprise.
+
+- Tests: Added unit tests verifying that `CodingConv2d` preserves the exact
+  forward output while producing valid pooled traces with correct metadata.
+
+- Integration: Added end-to-end tests exercising a small CNN with pooled
+  convolutional coding — covering training with a joint objective, surprise
+  retrieval via `WrappedModel.surprise()`, and empirical-percentile calibration
+  with basic ID/OOD separation.
+
+- Conv2d pooled coding metadata: pooled representations now record explicit
+  spatial-reduction metadata in ``reduction_meta`` (e.g., ``spatial_reduction``
+  and ``reduction_axes``) to make it clear that the coding view comes from a
+  spatial reduction rather than the raw activation tensor.
+
+- Layers: Added `CodingConv2d` with observe-only pooled coding (global average pooling over H×W by default) and set pooled coding as the default sample-level reducer for the first convolutional wrapper.
+
+- Layers: Convolutional wrappers now reuse the shared reduction and trace pipeline, so their pooled outputs feed the same assignment, loss, and calibration code paths as linear wrappers.
+
+- Docs: Added `CONTRIBUTING.md` and linked the changelog from README to prepare the repo for early external use.
+
+- Integration tests: added tests that execute README and API docs example code paths to ensure they remain valid.
+
+- Docs: corrected calibrator usage to `threshold_for(...)` in README and API reference examples.
+
+- Overhead (Conv2d pooled coding): added a deterministic estimator
+  (`nervecode.utils.overhead.estimate_pooled_conv_overhead`) and a timing
+  harness (`benchmarks/overhead/conv_overhead.py`). Documented expected
+  operating limits and typical compute/memory overhead in `docs/overhead.md`.
+
+- README: added installation instructions, an MVP quickstart example, and an explicit scope note (what Nervecode does/does not do).
+
+- Added a release smoke test that builds the package, installs the built wheel into a clean venv, and runs the quickstart example (opt-in via RUN_RELEASE_SMOKE=1).
+
+- Added `docs/api.md` documenting `wrap()`, `WrappedModel`, `CodingLinear`,
+  `CodingLoss`, the calibrator, and the aggregated surprise result.
+
+- Added `docs/diagnostics.md` explaining code utilization, entropy, code length,
+  commitment distance, empirical percentiles, and threshold-based OOD flags.
+
+- Repository structure scaffolded (`nervecode/`, `tests/`, `examples/`, `benchmarks/`, `docs/`, `scripts/`) and package importable from a clean checkout.
+ - CodingLoss: add commitment term that reads per-trace nearest-center distances (no recomputation); default weight 0.0 to preserve behavior and tests.
+- Added `pyproject.toml` with core metadata, Python 3.10 requirement, PyTorch dependency, and extras for `dev`, `docs`, `viz`, and `logging`.
+- Configured `ruff`, `mypy`, and `pytest` with a strict-enough baseline to catch shape, typing, and API regressions early.
+- Added `pre-commit` hooks for formatting, linting, type-checking, and a fast smoke test suite.
+- Added a minimal `README.md` explaining the product boundary, first public API shape, and MVP scope.
+- Added top-level API stubs in `nervecode/__init__.py` exposing `wrap` and `WrappedModel`.
+ - Created package layout mirroring conceptual architecture: `nervecode/core/`, `nervecode/layers/`, `nervecode/scoring/`, `nervecode/training/`, `nervecode/integration/`, and `nervecode/utils/`.
+ - Split tests into `tests/unit/`, `tests/integration/`, and `tests/smoke/`; added a minimal unit test and updated docs.
+- Added CI workflow to run install, ruff lint, mypy type-checks, and fast tests (unit + smoke) on push and pull requests.
+- Added `scripts/dev_smoke.py` to quickly verify imports and placeholder instantiation locally.
+- Added `scripts/train_minimal.py`: a dataset-agnostic training script for quick local validation and CI smoke runs.
+ - Added `benchmarks/overhead/overhead.py`: a simple timing benchmark that compares a base MLP against the instrumented model on a fixed workload.
+ - Added `docs/architecture.md` summarizing non-negotiable design rules (observe-only wrappers, fail-open, selected-layer instrumentation, explicit trace support, MVP-first scope).
+ - Added deterministic utilities: `nervecode.utils.seed` with `seed_everything`, `temp_seed`, and a per-test auto-seeding fixture honoring `NERVECODE_SEED` for reproducible runs.
+ - Implemented `nervecode/core/types.py` with a `SoftCode` dataclass whose `probs` tensor supports arbitrary leading dimensions with a final code dimension `(..., K)`.
+ - Extended `SoftCode` with optional fields `best_length`, `entropy`, `best_indices`, and `combined_surprise`, and added validation that all scalar-like fields match the leading shape of `probs`.
+ - Added `nervecode/core/trace.py` with a `CodingTrace` dataclass carrying reduced activations, reduction metadata, nearest-center distances, chosen center indices, commitment distances, and the associated `SoftCode`.
+ - Added `nervecode/core/shapes.py` with `flatten_leading`/`unflatten_leading` helpers to work uniformly across batch-only, token-like, and pooled-convolution layouts.
+ - Implemented `nervecode/core/codebook.py` providing a gradient-updated `Codebook` module with centers of shape `(K, code_dim)` and initialization scaled by the coding-space dimension.
+ - Codebook now follows PyTorch conventions: `reset_parameters()` without args using stored init strategy, improved `extra_repr()`, and a serialization contract via `get_extra_state`/`set_extra_state`.
+ - Packaging: added dynamic versioning via Hatch (single-source `nervecode/_version.py`) and build targets for wheel and sdist with appropriate includes.
+ - Marked Phase 1 TODO "Clamp all log and division operations" as NE locally pending the assignment engine implementation in `nervecode/core/`.
+ - Added `nervecode/core/temperature.py` with `FixedTemperature` and `CosineTemperature` schedules and a small `TemperatureSchedule` interface, and exported them via `nervecode.core`.
+ - Implemented `nervecode/core/assignment.py` with a `SoftAssignment` engine that returns a `SoftCode` and trace-ready intermediates (nearest distances, chosen indices, commitment distances) to avoid recomputing distances in loss.
+ - Added unit tests for `SoftCode`, `CodingTrace`, shape helpers, temperature schedules, and the CPU assignment engine; adjusted typing in `temperature.py` to satisfy mypy without a hard torch dependency.
+ - Added unit tests that verify gradient flow from the surprise signal back to reduced activations and codebook centers.
+- Added edge-case unit tests for the soft assignment engine covering exact center matches, ties between centers, uniform assignments, large input magnitudes, and autocast mixed precision where supported.
+- Added a synthetic convergence integration test that trains a codebook on a simple 2D Gaussian mixture and verifies it learns at least the expected number of active regions.
+ - Implemented `nervecode/layers/base.py` with a shared base class and protocol that standardize bypass behavior, trace caching, reduction setup, and diagnostics hooks.
+ - Added `nervecode/layers/linear.py` with `CodingLinear`, the first production wrapper around `nn.Linear` implementing observe-only semantics and trace caching (identity reduction in MVP).
+ - CodingLinear now accepts an optional `coding_dim` and uses identity reduction when `out_features == coding_dim`, or a learned linear projection reducer when `out_features > coding_dim`.
+- CodingLinear now exposes an explicit `forward_with_trace(x)` method returning `(y, trace)` while caching the latest `CodingTrace` for convenience via `last_trace`.
+- Verified `CodingLinear` across training/eval modes, mixed precision (autocast + GradScaler), and CPU/CUDA; added targeted unit tests.
+- CodingLinear preserves the original layer output bit-for-bit when coding is disabled or bypassed; added unit tests asserting `torch.equal` under disabled and bypass contexts.
+ - Added layer-level diagnostics helpers on wrappers (utilization, mean entropy, mean code length, mean commitment distance) derived from the latest cached trace; added a unit test for None-on-unavailable behavior.
+- Improved `CodingLinear` representation: `extra_repr()` now shows `code_dim`, codebook size `K`, reducer type, and coding enabled state; added unit tests for the printed summary.
+- Added unit test comparing an unwrapped `nn.Linear` and a wrapped twin with identical parameters to verify that the visible forward output is unchanged.
+ - Added unit tests verifying trace caching after plain forwards and that the explicit trace-return path is independent of hidden mutable state for `CodingLinear`.
+- Added multi-batch toggle tests for `CodingLinear`: verify disabling before forward yields no trace, re-enabling restores tracing, and cache updates across batches.
+- Added integration tests for a tiny model containing a `CodingLinear`, verifying device transfers, state_dict serialization round-trip, and optimizer integration.
+- Added a synthetic training integration test that uses `CodingLinear` inside a toy classifier and verifies that task loss and a coding-derived loss can be optimized together.
+- Added `nervecode/layers/wrap.py` with a `wrap()` helper to instrument models by explicit module names or via the `layers="all_linear"` shortcut; added unit tests for selection and output preservation.
+ - Refined layer selection in `wrap()`: introduced a tiny, extensible selector registry. MVP supports `layers="all_linear"` and explicit module-name lists; unrecognized shortcuts fail open.
+- Implemented a thin `WrappedModel` container that preserves the wrapped model's API (attribute access and `__call__`) while tracking inserted coding layers for later aggregation; added a unit test.
+- Implemented `WrappedModel.forward()` to delegate to the wrapped model's normal call and populate convenience caches with the latest per-layer traces when coding is enabled; added unit tests.
+ - Added model-level fail-open controls on `WrappedModel`: `enable_coding()`, `disable_coding()`, and a nestable `bypass()` context manager that delegate to all wrapped layers; added unit tests.
+ - Added `nervecode/scoring/aggregator.py` with a `mean_surprise(...)` function that computes per-sample mean aggregation across layer surprise signals; added unit tests.
+ - Structured the aggregator API to return an `AggregatedSurprise` result object, enabling future `max` and `weighted` strategies without changing the user-facing result type; updated unit tests accordingly.
+- Aggregator now supports mixing wrappers with different leading dimensions by reducing each per-layer surprise to a per-sample view before combining. Added `CodingTrace.sample_reduced_surprise()` to expose the sample-level reduction for layers.
+- Implemented `WrappedModel.surprise()` to return the latest mean-aggregated surprise across wrapped layers after a standard forward pass; added a unit test.
+ - Added integration test verifying that an explicit layer `forward_with_trace(...)` and model-level `WrappedModel.surprise()` agree on the same batch when called in a consistent order.
+- Added integration tests clarifying that explicit traces should be preferred in concurrent-looking usage and that the model-level convenience cache reflects last-forward state; updated docs to state this explicitly.
+ - Added `nervecode/training/loss.py` with a `CodingLoss` module that consumes `CodingTrace` objects (or `SoftCode`/tensors) and computes a scalar loss by aggregating per-layer surprise via `mean_surprise` and averaging over samples; avoids recomputing distances from raw outputs. 
+- Implemented `WrappedModel.coding_loss()` to compute loss from the latest per-layer traces and raise a helpful error when traces are unavailable; added unit tests.
+ - Added `nervecode/scoring/calibrator.py` with an empirical percentile calibrator that stores the sorted surprise distribution, chosen threshold quantiles, and minimal metadata to reproduce calibration; exported via `nervecode.scoring` and added a unit test for stored state.
+ - Implemented percentile lookup, threshold comparison, and boolean OOD decisions for scalar and batched surprise values in the calibrator; added unit tests.
+- Added synthetic calibration tests validating percentile ordering and threshold behavior on in-distribution vs shifted distributions.
+- Added end-to-end diagnostics tests ensuring finiteness and correct shapes across training, evaluation, and calibration passes.
+- Added bypass-consistency tests verifying that, under a temporary coding bypass, surprise aggregation returns None, `CodingLoss` raises on missing signals, and the calibrator rejects None inputs.
+ - Added `examples/quickstart_mlp.py` demonstrating a tiny MLP wrapped with coding layers, training with `CodingLoss`, calibrating empirical percentiles on held-out in-distribution data, and reading surprise + percentiles at inference.
+ - Added `examples/ood_smoke_test.py` demonstrating an obvious in-distribution vs out-of-distribution comparison and printing both raw scores and calibrated percentiles.

nervecode-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nervecode Maintainers
+
+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.
+

nervecode-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: nervecode
+Version: 0.1.0
+Summary: Intrinsic surprise scoring for PyTorch via statistical coding.
+Project-URL: Homepage, https://gitlab.com/domezsolt/nervecode
+Project-URL: Repository, https://gitlab.com/domezsolt/nervecode
+Author: Zsolt Döme
+License: MIT License
+        
+        Copyright (c) 2026 Nervecode Maintainers
+        
+        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.
+        
+License-File: LICENSE
+Keywords: coding,ml,pytorch,research,surprise
+Requires-Python: >=3.10
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: logging
+Requires-Dist: loguru>=0.7; extra == 'logging'
+Requires-Dist: rich>=13; extra == 'logging'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: seaborn>=0.13; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# Nervecode Docs
+
+This directory will contain documentation for the Nervecode project.
+
+## Developer Setup
+
+- Install dev tools (in your virtualenv): `pip install -e .[dev]`
+- Install git hooks: `pre-commit install`
+- Run on all files once: `pre-commit run --all-files`
+
+Included hooks:
+- Formatting: `ruff-format`
+- Linting and import sorting: `ruff` (with `--fix`)
+- Type-checking: `mypy`
+
+## Tests
+
+- Unit tests: `pytest tests/unit` (fast correctness checks)
+- Integration tests: `pytest tests/integration` (heavier, cross-module)
+- Smoke tests: `pytest tests/smoke` (repo wiring and API surface)
+
+### Deterministic runs
+
+- Tests auto-seed RNGs per test using `NERVECODE_SEED` (default: `1234`).
+- You can control reproducibility in your own scripts via:
+  ```python
+  from nervecode.utils.seed import seed_everything, seed_from_env
+  seed_everything(seed_from_env())
+  ```
+
+## Performance Notes
+
+- Overhead estimates and guidance for pooled Conv2d coding: see `docs/overhead.md`.
+- Scaling and tradeoffs for layer selection and coding dimension: see `docs/scaling.md`.

nervecode-0.1.0/README.md

@@ -0,0 +1,135 @@
+# Nervecode
+
+Nervecode is a PyTorch library that adds an intrinsic uncertainty signal to neural networks by scoring how compressible internal activations are under learned codebooks. The goal is a practical, observe-only wrapper that preserves model outputs while exposing a calibrated surprise score for OOD detection, guardrails, and monitoring.
+
+## Installation
+- Prerequisites: Python 3.10+, PyTorch 2.0+ (install a build matching your platform from pytorch.org).
+- From a checkout for local use: `pip install -e .`
+- For development with tooling: `pip install -e .[dev]` then `pre-commit install`.
+- Optional extras: `.[viz]` for plotting, `.[logging]` for richer logs.
+
+Note: You can use the top-level convenience `nervecode.wrap(...)` which instruments your model in-place and returns a `WrappedModel` container.
+
+## Quickstart
+Minimal end-to-end flow using the current public surface:
+
+```python
+import torch
+from torch import nn
+from nervecode.layers.wrap import wrap as wrap_layers
+import nervecode as nvc
+from nervecode.scoring import EmpiricalPercentileCalibrator, mean_surprise
+
+# 1) Build and instrument a tiny model
+model = nn.Sequential(nn.Linear(2, 32), nn.ReLU(), nn.Linear(32, 2))
+wrap_layers(model, layers="all_linear")  # in-place Linear wrappers
+wrapped = nvc.WrappedModel(model)
+
+# 2) Train with task loss + coding loss
+x = torch.randn(64, 2)
+y = torch.randint(0, 2, (64,))
+logits = wrapped.forward(x)
+loss = nn.CrossEntropyLoss()(logits, y) + 0.1 * wrapped.coding_loss()
+loss.backward()
+
+# 3) Calibrate empirical percentiles on in-distribution scores
+with torch.no_grad():
+    _ = wrapped.forward(torch.randn(64, 2))
+    agg = wrapped.surprise() or mean_surprise(getattr(wrapped, "_last_layer_traces", {}))
+scores = agg.surprise if agg is not None else torch.empty(0)
+calib = EmpiricalPercentileCalibrator(threshold_quantiles=(0.95,))
+state = calib.fit(scores, aggregation="mean")
+thr = calib.threshold_for()  # threshold at 95th percentile
+```
+
+## Product Boundary
+- Is: a lightweight PyTorch library that wraps selected layers (start with Linear), learns codebooks over reduced activations, and emits layer-wise and aggregated surprise scores.
+- Is not: a hardware project, a full observability platform, or a framework-agnostic toolkit; MVP targets PyTorch only and focuses on observe-only wrappers with modest overhead.
+
+## First Public API Shape (MVP)
+The initial public surface is intentionally small and convenient:
+
+```python
+import nervecode
+
+model = MyModel()
+wrapped = nervecode.wrap(model, layers="all_linear")
+
+for x, y in train_loader:
+    logits = wrapped(x)
+    loss = task_loss_fn(logits, y) + wrapped.coding_loss()
+    loss.backward()
+    optimizer.step(); optimizer.zero_grad()
+
+wrapped.calibrate(calib_loader)
+
+logits = wrapped(x_test)
+surprise = wrapped.surprise()  # includes score and percentile
+
+# Optional explicit trace path for robust integrations
+logits, trace = wrapped.forward_with_trace(x_test)
+```
+
+Provisional API entries:
+- `wrap(...)`
+- `WrappedModel.coding_loss()`
+- `WrappedModel.calibrate(...)`
+- `WrappedModel.surprise()`
+- `WrappedModel.forward_with_trace(...)`
+
+## MVP Scope
+The MVP is a narrow, end-to-end vertical slice:
+- Gradient-updated codebooks and differentiable soft assignment.
+- `SoftCode` and `CodingTrace` data structures.
+- `CodingLinear` wrapper and `wrap(..., layers="all_linear")` convenience. The wrapper supports an optional `coding_dim` to project wide layer outputs down to a coding space via a learned linear reducer while preserving the layer's visible output.
+- Mean and max aggregation for a per-input surprise score.
+- Empirical percentile calibration on in-distribution data.
+- Lightweight coding loss and basic diagnostics (CSV/JSONL).
+- One small end-to-end example (MLP or simple CNN).
+
+Distance-augmented surprise:
+- The combined per-position surprise can include a distance component to lift
+  OOD scores above ID across the bulk, improving percentile thresholding. Set
+  `assignment.beta_distance > 0` (e.g., 0.2–1.0) to enable `S = βL·L + βH·H + βD·D`
+  where `D ≈ log1p(nearest-center squared distance)`.
+
+Quickstart: see `examples/quickstart_mlp.py` for a tiny end-to-end MLP training + calibration + inference script. For pooled Conv2d coding contributing to aggregated surprise, see `examples/quickstart_cnn.py`. For a plain‑language walkthrough of the expected user flow, read `docs/quickstart.md`.
+
+For a fast, dataset-agnostic smoke run suitable for CI or local validation, use `scripts/train_minimal.py` which trains a tiny model on a synthetic dataset and calibrates an empirical percentile threshold.
+
+For a minimal OOD benchmark harness, see `benchmarks/ood/simple.py` which trains an MLP, calibrates percentiles on in-distribution data, and reports AUROC versus a synthetic OOD split.
+
+For quick ablations over codebook/coding hyperparameters and layer selection, use `scripts/ablate_grid.py` which sweeps small grids of K (codebook size), D (coding dimension), T (temperature), and selection strategies, then logs a minimal quality metric and overhead proxies to CSV.
+
+For a minimal OOD comparison using synthetic scores and the empirical percentile calibrator, see `examples/ood_smoke_test.py`.
+
+Performance notes: see `docs/overhead.md` for pooled Conv2d coding overhead estimates, timing harness, and operating guidance.
+
+## Recommended OOD Settings (quick start)
+- Selection: `layers=first_linear`
+- Aggregation: `agg=max`
+- Coding: `coding_dim D=8`
+- Codebook: `K=16`
+- Weights: `βL=1.0`, `βE=1.0`, `βD=1.0` (distance-augmented surprise)
+- Calibration: `quantile q=0.90` (use `0.95` for stricter ID control)
+
+Run the bundled OOD benchmark with these settings:
+
+```
+python -m benchmarks.ood.simple --epochs 20 --device cpu \
+  --agg max --layers first_linear --K 16 --coding-dim 8 \
+  --beta-length 1.0 --beta-entropy 1.0 --beta-distance 1.0 \
+  --quantile 0.90 --json
+```
+
+Or sweep a narrow fast grid:
+
+```
+FAST=1 bash scripts/run_ood_matrix.sh
+```
+
+## Contributing
+Contributions are welcome. Please see `CONTRIBUTING.md` for a quick start, coding guidelines, and how to run tests locally.
+
+## Changelog
+User-facing changes are tracked in `CHANGELOG.md` under the Unreleased section and versioned entries.

nervecode-0.1.0/benchmarks/README.md

@@ -0,0 +1,17 @@
+# Benchmarks
+
+This directory contains performance benchmarks and profiling harnesses.
+
+- Overhead: `benchmarks/overhead/overhead.py` compares a base MLP against the
+  instrumented version on a fixed workload and reports per‑iteration timings.
+  Usage:
+  - `python -m benchmarks.overhead.overhead --iters 100 --device cpu`
+  - `python benchmarks/overhead/overhead.py --json`
+
+- Conv Overhead: `benchmarks/overhead/conv_overhead.py` runs a tiny CNN with
+  and without pooled Conv2d coding and reports per‑iteration timings. On CUDA
+  it also prints a rough GPU memory delta after instrumentation. Usage:
+  - `python -m benchmarks.overhead.conv_overhead --iters 100 --device cpu`
+  - `python benchmarks/overhead/conv_overhead.py --json`
+
+Benchmarks are not part of strict CI and are intended for manual runs.

nervecode-0.1.0/benchmarks/__init__.py

@@ -0,0 +1,4 @@
+"""Benchmarks and profiling harnesses for Nervecode.
+
+Not part of strict CI; intended for manual runs.
+"""

nervecode-0.1.0/benchmarks/ood/__init__.py

@@ -0,0 +1,8 @@
+"""Simple OOD benchmark harness.
+
+This package contains a minimal, dependency-light benchmark that trains a small
+model, calibrates aggregated surprise on in-distribution data, and measures
+separation between in-distribution and out-of-distribution samples via AUROC.
+"""
+
+__all__: list[str] = []