nnscope 0.1.0__tar.gz

nnscope-0.1.0/LICENSE

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

nnscope-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: nnscope
+Version: 0.1.0
+Summary: Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss.
+Keywords: neural-network,numpy,visualization,backpropagation,education,deep-learning,dashboard
+Author: michaelks
+Author-email: michaelks <michaelks540@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: numpy>=1.21
+Requires-Dist: matplotlib>=3.5 ; extra == 'png'
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/Ashurali/nnscope
+Project-URL: Repository, https://github.com/Ashurali/nnscope
+Project-URL: Issues, https://github.com/Ashurali/nnscope/issues
+Project-URL: Changelog, https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md
+Provides-Extra: png
+Description-Content-Type: text/markdown
+
+# nnscope
+
+**Watch your NumPy neural network learn.** Add one line to the training loop of a network you wrote yourself, and nnscope
+shows it live in your browser: every weight, every gradient, every activation, the loss, and plain-language hints about
+what is going on. Afterwards you get a standalone HTML replay you can scrub through, share, or export as images.
+
+It was built for students implementing neural networks **from scratch** (forward pass, backprop and SGD in NumPy)
+who want to *see* what their code does: gradients flowing backwards, ReLUs dying, sigmoids saturating, a hidden layer slowly
+learning to separate the classes.
+
+![nnscope dashboard](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/dashboard.png)
+
+- **Zero setup:** depends only on NumPy. The dashboard is one self-contained HTML file served by Python's standard library.
+- **Works with your code:** auto-detects common NumPy model layouts, or pass plain arrays.
+- **Live and replay:** a live view while training, then `save_html()` for an offline replay with a timeline slider.
+- **Explains itself:** every panel has a (?) with the math behind it, and an insights feed diagnoses common problems.
+- **Responsive:** works on a phone (the network turns vertical), light and dark themes.
+
+## Install
+
+```bash
+pip install nnscope            # NumPy is the only dependency
+pip install "nnscope[png]"     # optional: PNG snapshots from Python via matplotlib
+```
+
+## Quickstart
+
+```python
+import nnscope
+
+scope = nnscope.Scope("my-mlp")                    # opens http://127.0.0.1:8765 in your browser
+for epoch in range(epochs):
+    ...                                             # your own forward pass, backprop and SGD step
+    scope.log(epoch, model=model, loss=train_loss, metrics={"test_loss": test_loss})
+
+scope.save_html("run.html")                         # standalone replay, no server needed
+scope.snapshot("run.svg")                           # network structure + loss curve as an image
+scope.wait()                                        # keep the live page up until Ctrl+C
+```
+
+In a Jupyter notebook, `scope.show()` puts the live dashboard inline. Use `nnscope.Scope(..., live=False)` to only record
+(for `save_html` / `snapshot`).
+
+## Connecting your network
+
+nnscope never runs your network; it only **reads arrays you already have**.
+
+**1. A model object (auto-detected).** Any object with a `.layers` list whose dense layers expose weights and biases,
+optionally with their gradients:
+
+| what | attribute names tried |
+|---|---|
+| weights | `W`, `weight`, `weights`, `kernel` |
+| biases | `b`, `bias` |
+| gradients | `dW`, `grad_W`, `W_grad`, `dweight`, … and `db`, `grad_b`, … |
+| cached input (→ activation stats of the previous layer) | `x`, `input`, `inputs`, `a_prev` |
+
+Layers without weights are recognised as activations by class name (`ReLU`, `Tanh`, `Sigmoid`, `LeakyReLU`, …), so the graph
+shows `relu`, `tanh`, … on each layer. CS231n-style parameter dicts (`{"W1": …, "b1": …}` plus a matching `grads` dict)
+and lists of `(W, b)` pairs work too.
+
+**2. Plain arrays.** No model object needed:
+
+```python
+scope.log(step, weights=[W1, W2], biases=[b1, b2], grads=[dW1, dW2], loss=loss)
+```
+
+Both `x @ W` (`W` is `(in, out)`) and `W @ x` (`W` is `(out, in)`) conventions are detected from how the shapes chain. Force
+one with `Scope(layout="in_out")` or `layout="out_in"` if a network is ambiguous (e.g. every layer square).
+
+**Optional extras for richer views:**
+
+```python
+scope.log(step, model=model, loss=loss,
+          activations=[a1, a2],     # per-layer outputs on a batch → activation statistics
+          deltas=[d1, d2, d3],      # per-layer ∂L/∂z on a batch → shown in the gradient-flow panel
+          latent=z, labels=y)       # features of any layer → latent-space scatter
+```
+
+## How to read the dashboard
+
+| Panel | What it shows | What to look for |
+|---|---|---|
+| **Network** | Neurons (circles) and weights (lines): blue positive, orange negative, thickness ∝ \|w\|. Toggle the lines to **gradients** ∂L/∂w or **updates** Δw, and the node colour to mean activation or % active. | Click a neuron: the **inspector** shows z = Σ wᵢ aᵢ + b with the real numbers from your batch, its strongest inputs, their gradients and how they changed. Dead ReLUs are ringed in red. |
+| **Loss & metrics** | Every scalar you log over time (log or linear scale). | Spikes: learning rate too high. Test loss rising while training loss falls: overfitting. |
+| **Insights** | Plain-language diagnoses, each at the step where it appeared. Click to jump there. | Vanishing/exploding gradients, dead or saturated units, learning rate too high/low, overfitting. |
+| **Gradient flow** | Mean \|∂L/∂W\| per layer, input → output, log scale. | Bars shrinking towards the input = vanishing gradients (e.g. deep sigmoid nets). |
+| **Layer health** | ‖W‖, ‖∇W‖ and the update ratio ‖ΔW‖/‖W‖ per layer over time, plus W and ∇W histograms. | Update ratio ≈ 10⁻³ per SGD step is healthy; ≈ 10⁻¹ is too high. |
+| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | Neurons at 0 % active pass no gradient back and have stopped learning. |
+| **Latent space** | Any layer's features (PCA if wider than 2), coloured by label, along the timeline. | Classes starting mixed and ending linearly separable: the network is building a representation. |
+
+Use the **timeline** at the bottom (or ← → and space) to replay training. **Export** saves the network (SVG/PNG), the loss curve,
+the whole dashboard (PNG) or the raw run data (JSON).
+
+![deep sigmoid network: vanishing gradients](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/vanishing.png)
+
+## Examples
+
+The [`examples/`](https://github.com/Ashurali/nnscope/tree/master/examples) folder uses a tiny homework-style NumPy MLP ([`_mlp.py`](https://github.com/Ashurali/nnscope/blob/master/examples/_mlp.py)). Run them from that folder;
+add `--no-open` to skip opening a browser tab, or `--headless` to only write `runs/*.html` and `runs/*.svg`.
+
+| script | story |
+|---|---|
+| `01_quickstart_xor.py` | the basics: an MLP on XOR-like data, live |
+| `02_plain_arrays.py` | no model object: raw `W1, b1, W2, b2`, hand-written backprop, `deltas=` |
+| `03_latent_bottleneck.py --k 2` | watch a k-unit bottleneck layer separate two classes (try `--k 32`) |
+| `04_vanishing_gradients.py --act sigmoid` | deep sigmoid net: gradients vanish, the insight explains why (compare `--act relu`) |
+| `05_inr_spectral_bias.py [--fourier]` | fit an image f(x, y) → rgb: raw coordinates plateau, Fourier features keep improving |
+
+## API
+
+```python
+nnscope.Scope(name="run", *, live=True, port=8765, host="127.0.0.1", open_browser=True, max_neurons=32,
+              snapshot_every=None, max_snapshots=300, max_records=5000, layout="auto", latent_points=1000, quiet=False)
+```
+
+- `log(step=None, *, model=None, loss=None, metrics=None, weights=None, biases=None, grads=None, bias_grads=None, activations=None, deltas=None, latent=None, labels=None, snapshot=None)`
+- `save_html(path)`: standalone replay. `snapshot(path, step=None)`: `.svg` (no dependencies) or `.png` (matplotlib).
+- `show(height=820)`: Jupyter IFrame. `wait()`: serve until Ctrl+C. `close()`; also usable as a context manager.
+- `data()`: everything recorded so far as a JSON-serialisable dict.
+
+**Keeping it light.** Scalars are recorded at every `log`; full snapshots (edges, histograms, latent points) are thinned
+adaptively so a run keeps at most `max_snapshots` of them. Layers wider than `max_neurons` draw an evenly spaced subset
+(statistics always use all neurons). The live stream batches updates to about 10 per second.
+
+**Limitations.** Dense (fully-connected) layers only for now; convolutional layers are not drawn. The server binds to
+localhost by default.
+
+## Development
+
+```bash
+uv sync --dev
+uv run --dev pytest
+```
+
+## License
+
+MIT

nnscope-0.1.0/README.md

@@ -0,0 +1,138 @@
+# nnscope
+
+**Watch your NumPy neural network learn.** Add one line to the training loop of a network you wrote yourself, and nnscope
+shows it live in your browser: every weight, every gradient, every activation, the loss, and plain-language hints about
+what is going on. Afterwards you get a standalone HTML replay you can scrub through, share, or export as images.
+
+It was built for students implementing neural networks **from scratch** (forward pass, backprop and SGD in NumPy)
+who want to *see* what their code does: gradients flowing backwards, ReLUs dying, sigmoids saturating, a hidden layer slowly
+learning to separate the classes.
+
+![nnscope dashboard](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/dashboard.png)
+
+- **Zero setup:** depends only on NumPy. The dashboard is one self-contained HTML file served by Python's standard library.
+- **Works with your code:** auto-detects common NumPy model layouts, or pass plain arrays.
+- **Live and replay:** a live view while training, then `save_html()` for an offline replay with a timeline slider.
+- **Explains itself:** every panel has a (?) with the math behind it, and an insights feed diagnoses common problems.
+- **Responsive:** works on a phone (the network turns vertical), light and dark themes.
+
+## Install
+
+```bash
+pip install nnscope            # NumPy is the only dependency
+pip install "nnscope[png]"     # optional: PNG snapshots from Python via matplotlib
+```
+
+## Quickstart
+
+```python
+import nnscope
+
+scope = nnscope.Scope("my-mlp")                    # opens http://127.0.0.1:8765 in your browser
+for epoch in range(epochs):
+    ...                                             # your own forward pass, backprop and SGD step
+    scope.log(epoch, model=model, loss=train_loss, metrics={"test_loss": test_loss})
+
+scope.save_html("run.html")                         # standalone replay, no server needed
+scope.snapshot("run.svg")                           # network structure + loss curve as an image
+scope.wait()                                        # keep the live page up until Ctrl+C
+```
+
+In a Jupyter notebook, `scope.show()` puts the live dashboard inline. Use `nnscope.Scope(..., live=False)` to only record
+(for `save_html` / `snapshot`).
+
+## Connecting your network
+
+nnscope never runs your network; it only **reads arrays you already have**.
+
+**1. A model object (auto-detected).** Any object with a `.layers` list whose dense layers expose weights and biases,
+optionally with their gradients:
+
+| what | attribute names tried |
+|---|---|
+| weights | `W`, `weight`, `weights`, `kernel` |
+| biases | `b`, `bias` |
+| gradients | `dW`, `grad_W`, `W_grad`, `dweight`, … and `db`, `grad_b`, … |
+| cached input (→ activation stats of the previous layer) | `x`, `input`, `inputs`, `a_prev` |
+
+Layers without weights are recognised as activations by class name (`ReLU`, `Tanh`, `Sigmoid`, `LeakyReLU`, …), so the graph
+shows `relu`, `tanh`, … on each layer. CS231n-style parameter dicts (`{"W1": …, "b1": …}` plus a matching `grads` dict)
+and lists of `(W, b)` pairs work too.
+
+**2. Plain arrays.** No model object needed:
+
+```python
+scope.log(step, weights=[W1, W2], biases=[b1, b2], grads=[dW1, dW2], loss=loss)
+```
+
+Both `x @ W` (`W` is `(in, out)`) and `W @ x` (`W` is `(out, in)`) conventions are detected from how the shapes chain. Force
+one with `Scope(layout="in_out")` or `layout="out_in"` if a network is ambiguous (e.g. every layer square).
+
+**Optional extras for richer views:**
+
+```python
+scope.log(step, model=model, loss=loss,
+          activations=[a1, a2],     # per-layer outputs on a batch → activation statistics
+          deltas=[d1, d2, d3],      # per-layer ∂L/∂z on a batch → shown in the gradient-flow panel
+          latent=z, labels=y)       # features of any layer → latent-space scatter
+```
+
+## How to read the dashboard
+
+| Panel | What it shows | What to look for |
+|---|---|---|
+| **Network** | Neurons (circles) and weights (lines): blue positive, orange negative, thickness ∝ \|w\|. Toggle the lines to **gradients** ∂L/∂w or **updates** Δw, and the node colour to mean activation or % active. | Click a neuron: the **inspector** shows z = Σ wᵢ aᵢ + b with the real numbers from your batch, its strongest inputs, their gradients and how they changed. Dead ReLUs are ringed in red. |
+| **Loss & metrics** | Every scalar you log over time (log or linear scale). | Spikes: learning rate too high. Test loss rising while training loss falls: overfitting. |
+| **Insights** | Plain-language diagnoses, each at the step where it appeared. Click to jump there. | Vanishing/exploding gradients, dead or saturated units, learning rate too high/low, overfitting. |
+| **Gradient flow** | Mean \|∂L/∂W\| per layer, input → output, log scale. | Bars shrinking towards the input = vanishing gradients (e.g. deep sigmoid nets). |
+| **Layer health** | ‖W‖, ‖∇W‖ and the update ratio ‖ΔW‖/‖W‖ per layer over time, plus W and ∇W histograms. | Update ratio ≈ 10⁻³ per SGD step is healthy; ≈ 10⁻¹ is too high. |
+| **Activations** | Per neuron: mean activation and fraction of samples where it is active. | Neurons at 0 % active pass no gradient back and have stopped learning. |
+| **Latent space** | Any layer's features (PCA if wider than 2), coloured by label, along the timeline. | Classes starting mixed and ending linearly separable: the network is building a representation. |
+
+Use the **timeline** at the bottom (or ← → and space) to replay training. **Export** saves the network (SVG/PNG), the loss curve,
+the whole dashboard (PNG) or the raw run data (JSON).
+
+![deep sigmoid network: vanishing gradients](https://raw.githubusercontent.com/Ashurali/nnscope/master/docs/vanishing.png)
+
+## Examples
+
+The [`examples/`](https://github.com/Ashurali/nnscope/tree/master/examples) folder uses a tiny homework-style NumPy MLP ([`_mlp.py`](https://github.com/Ashurali/nnscope/blob/master/examples/_mlp.py)). Run them from that folder;
+add `--no-open` to skip opening a browser tab, or `--headless` to only write `runs/*.html` and `runs/*.svg`.
+
+| script | story |
+|---|---|
+| `01_quickstart_xor.py` | the basics: an MLP on XOR-like data, live |
+| `02_plain_arrays.py` | no model object: raw `W1, b1, W2, b2`, hand-written backprop, `deltas=` |
+| `03_latent_bottleneck.py --k 2` | watch a k-unit bottleneck layer separate two classes (try `--k 32`) |
+| `04_vanishing_gradients.py --act sigmoid` | deep sigmoid net: gradients vanish, the insight explains why (compare `--act relu`) |
+| `05_inr_spectral_bias.py [--fourier]` | fit an image f(x, y) → rgb: raw coordinates plateau, Fourier features keep improving |
+
+## API
+
+```python
+nnscope.Scope(name="run", *, live=True, port=8765, host="127.0.0.1", open_browser=True, max_neurons=32,
+              snapshot_every=None, max_snapshots=300, max_records=5000, layout="auto", latent_points=1000, quiet=False)
+```
+
+- `log(step=None, *, model=None, loss=None, metrics=None, weights=None, biases=None, grads=None, bias_grads=None, activations=None, deltas=None, latent=None, labels=None, snapshot=None)`
+- `save_html(path)`: standalone replay. `snapshot(path, step=None)`: `.svg` (no dependencies) or `.png` (matplotlib).
+- `show(height=820)`: Jupyter IFrame. `wait()`: serve until Ctrl+C. `close()`; also usable as a context manager.
+- `data()`: everything recorded so far as a JSON-serialisable dict.
+
+**Keeping it light.** Scalars are recorded at every `log`; full snapshots (edges, histograms, latent points) are thinned
+adaptively so a run keeps at most `max_snapshots` of them. Layers wider than `max_neurons` draw an evenly spaced subset
+(statistics always use all neurons). The live stream batches updates to about 10 per second.
+
+**Limitations.** Dense (fully-connected) layers only for now; convolutional layers are not drawn. The server binds to
+localhost by default.
+
+## Development
+
+```bash
+uv sync --dev
+uv run --dev pytest
+```
+
+## License
+
+MIT

nnscope-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "nnscope"
+version = "0.1.0"
+description = "Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.21"]
+keywords = [
+    "neural-network",
+    "numpy",
+    "visualization",
+    "backpropagation",
+    "education",
+    "deep-learning",
+    "dashboard",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[[project.authors]]
+name = "michaelks"
+email = "michaelks540@gmail.com"
+
+[project.optional-dependencies]
+png = ["matplotlib>=3.5"]
+
+[project.urls]
+Homepage = "https://github.com/Ashurali/nnscope"
+Repository = "https://github.com/Ashurali/nnscope"
+Issues = "https://github.com/Ashurali/nnscope/issues"
+Changelog = "https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

nnscope-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "nnscope"
+version = "0.1.0"
+description = "Watch your NumPy neural network learn: a live, replayable dashboard for weights, gradients, activations and loss."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "michaelks", email = "michaelks540@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.21",
+]
+keywords = ["neural-network", "numpy", "visualization", "backpropagation", "education", "deep-learning", "dashboard"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.optional-dependencies]
+png = ["matplotlib>=3.5"]
+
+[project.urls]
+Homepage = "https://github.com/Ashurali/nnscope"
+Repository = "https://github.com/Ashurali/nnscope"
+Issues = "https://github.com/Ashurali/nnscope/issues"
+Changelog = "https://github.com/Ashurali/nnscope/blob/master/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"

nnscope-0.1.0/src/nnscope/__init__.py

@@ -0,0 +1,12 @@
+"""nnscope: watch your NumPy neural network learn.
+
+    import nnscope
+    scope = nnscope.Scope("my-mlp")
+    scope.log(step, model=model, loss=loss)
+"""
+__version__ = "0.1.0"
+
+from .adapters import LayerView, extract_layers  # noqa: E402
+from .scope import Scope  # noqa: E402
+
+__all__ = ["Scope", "extract_layers", "LayerView", "__version__"]

nnscope-0.1.0/src/nnscope/adapters.py

@@ -0,0 +1,233 @@
+"""Turn "whatever the user has" into a uniform list of dense layers.
+
+nnscope never runs your network. It only *reads* arrays you already have: weights, biases, their gradients and
+(optionally) activations. This module finds them, either from explicit lists or by duck-typing common NumPy model
+layouts, and normalises every weight matrix to the ``(in_features, out_features)`` orientation used for ``x @ W``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, List, Optional, Sequence
+
+import numpy as np
+
+WEIGHT_ATTRS = ("W", "weight", "weights", "kernel", "w")
+BIAS_ATTRS = ("b", "bias", "biases")
+WEIGHT_GRAD_ATTRS = ("dW", "grad_W", "W_grad", "dweight", "grad_weight", "weight_grad", "dw")
+BIAS_GRAD_ATTRS = ("db", "grad_b", "b_grad", "dbias", "grad_bias", "bias_grad")
+INPUT_CACHE_ATTRS = ("x", "input", "inputs", "a_prev", "x_cache", "cache_x")
+ACTIVATION_NAMES = {
+    "relu": "relu", "leakyrelu": "leaky_relu", "tanh": "tanh", "sigmoid": "sigmoid", "logistic": "sigmoid",
+    "softmax": "softmax", "elu": "elu", "gelu": "gelu", "softplus": "softplus", "sine": "sine", "sin": "sine",
+    "linear": "linear", "identity": "linear", "swish": "swish", "silu": "swish",
+}
+
+HELP = """nnscope could not find dense-layer weights. Pass them explicitly, for example
+
+    scope.log(step, weights=[W1, W2], biases=[b1, b2], grads=[dW1, dW2], loss=loss)
+
+or give a model object with a `.layers` list whose layers expose `W`/`b` (and `dW`/`db`),
+a `.params` dict like {"W1": ..., "b1": ...}, or a list of (W, b) pairs."""
+
+
+@dataclass
+class LayerView:
+    """One dense layer, normalised so that ``W.shape == (in_features, out_features)``."""
+
+    W: np.ndarray
+    b: Optional[np.ndarray] = None
+    dW: Optional[np.ndarray] = None
+    db: Optional[np.ndarray] = None
+    act: Optional[str] = None          # activation applied to this layer's output ("relu", "tanh", ...)
+    name: str = ""
+    source: Any = None                 # the original layer object, if any (used to find cached inputs)
+
+    @property
+    def in_features(self) -> int:
+        return int(self.W.shape[0])
+
+    @property
+    def out_features(self) -> int:
+        return int(self.W.shape[1])
+
+
+def _arr(x: Any) -> Optional[np.ndarray]:
+    return np.asarray(x) if isinstance(x, np.ndarray) or (x is not None and hasattr(x, "__array__")) else None
+
+
+def _first_attr(obj: Any, names: Sequence[str], ndim: Optional[int] = None) -> Optional[np.ndarray]:
+    for n in names:
+        v = getattr(obj, n, None)
+        a = _arr(v) if v is not None else None
+        if a is not None and a.dtype.kind in "fiu" and (ndim is None or a.ndim == ndim):
+            return a
+    return None
+
+
+def activation_name(obj: Any) -> Optional[str]:
+    """Recognise an activation layer by its class name (ReLU, Tanh, Sigmoid, ...)."""
+    key = re.sub(r"[^a-z]", "", type(obj).__name__.lower())
+    return ACTIVATION_NAMES.get(key)
+
+
+# ------------------------------------------------------------------ collection from different model layouts
+def _from_layer_objects(layers: Sequence[Any]) -> List[LayerView]:
+    views: List[LayerView] = []
+    for obj in layers:
+        if hasattr(obj, "layers") and not isinstance(obj, (list, tuple)):       # nested Sequential
+            views.extend(_from_layer_objects(list(obj.layers)))
+            continue
+        W = _first_attr(obj, WEIGHT_ATTRS, ndim=2)
+        if W is not None:
+            views.append(LayerView(
+                W=W, b=_first_attr(obj, BIAS_ATTRS), dW=_first_attr(obj, WEIGHT_GRAD_ATTRS, ndim=2),
+                db=_first_attr(obj, BIAS_GRAD_ATTRS), name=type(obj).__name__, source=obj))
+            continue
+        act = activation_name(obj)
+        if act and views and views[-1].act is None:
+            views[-1].act = act
+    return views
+
+
+_KEY = re.compile(r"^(?P<kind>[A-Za-z]+)[_.]?(?P<idx>\d+)$")
+
+
+def _from_dict(params: dict, grads: Optional[dict] = None) -> List[LayerView]:
+    """CS231n-style dicts: {"W1": ..., "b1": ..., "W2": ...} (+ an optional grads dict with the same keys)."""
+    layers: dict = {}
+    for key, val in params.items():
+        m = _KEY.match(str(key))
+        if not m:
+            continue
+        kind, idx = m.group("kind"), int(m.group("idx"))
+        slot = layers.setdefault(idx, {})
+        if kind in WEIGHT_ATTRS:
+            slot["W"], slot["kW"] = np.asarray(val), key
+        elif kind in BIAS_ATTRS:
+            slot["b"], slot["kb"] = np.asarray(val), key
+    views = []
+    for idx in sorted(layers):
+        slot = layers[idx]
+        if "W" not in slot or slot["W"].ndim != 2:
+            continue
+        dW = _arr(grads.get(slot["kW"])) if grads else None
+        db = _arr(grads.get(slot.get("kb"))) if grads and slot.get("kb") else None
+        views.append(LayerView(W=slot["W"], b=slot.get("b"), dW=dW, db=db, name=f"layer {idx}"))
+    return views
+
+
+def _from_sequence(items: Sequence[Any]) -> List[LayerView]:
+    """A list of arrays ([W1, b1, W2, b2] or [W1, W2]), of (W, b) pairs, or of layer objects."""
+    if items and not any(isinstance(it, (np.ndarray, tuple, list)) for it in items):
+        return _from_layer_objects(items)
+    views: List[LayerView] = []
+    for it in items:
+        if isinstance(it, (tuple, list)):
+            W = np.asarray(it[0])
+            b = np.asarray(it[1]) if len(it) > 1 and it[1] is not None else None
+            views.append(LayerView(W=W, b=b))
+        else:
+            a = np.asarray(it)
+            if a.ndim == 2:
+                views.append(LayerView(W=a))
+            elif a.ndim == 1 and views and views[-1].b is None:
+                views[-1].b = a
+    return views
+
+
+# ------------------------------------------------------------------ orientation
+def _chains(mats: List[np.ndarray], in_out: bool) -> bool:
+    if in_out:
+        return all(mats[k].shape[1] == mats[k + 1].shape[0] for k in range(len(mats) - 1))
+    return all(mats[k].shape[0] == mats[k + 1].shape[1] for k in range(len(mats) - 1))
+
+
+def detect_layout(views: List[LayerView]) -> str:
+    """Return "in_out" (x @ W, W is (in, out)) or "out_in" (W @ x, W is (out, in))."""
+    mats = [v.W for v in views]
+    if len(mats) >= 2:
+        io, oi = _chains(mats, True), _chains(mats, False)
+        if io and not oi:
+            return "in_out"
+        if oi and not io:
+            return "out_in"
+    votes = 0                                            # ambiguous → let the biases decide
+    for v in views:
+        if v.b is not None and v.W.shape[0] != v.W.shape[1]:
+            n = v.b.size
+            votes += (n == v.W.shape[1]) - (n == v.W.shape[0])
+    return "out_in" if votes < 0 else "in_out"
+
+
+def normalise(views: List[LayerView], layout: str = "auto") -> List[LayerView]:
+    if layout not in ("auto", "in_out", "out_in"):
+        raise ValueError('layout must be "auto", "in_out" or "out_in"')
+    if layout == "auto":
+        layout = detect_layout(views)
+    if layout == "out_in":
+        for v in views:
+            v.W = v.W.T
+            if v.dW is not None:
+                v.dW = v.dW.T
+    for k, v in enumerate(views):
+        if not v.name:
+            v.name = f"layer {k + 1}"
+        for attr in ("b", "db"):
+            a = getattr(v, attr)
+            if a is not None:
+                setattr(v, attr, np.asarray(a).reshape(-1))
+        if v.dW is not None and v.dW.shape != v.W.shape:
+            v.dW = v.dW.T if v.dW.T.shape == v.W.shape else None
+    return views
+
+
+# ------------------------------------------------------------------ public entry point
+def extract_layers(model: Any = None, *, weights: Optional[Sequence] = None, biases: Optional[Sequence] = None,
+                   grads: Any = None, bias_grads: Optional[Sequence] = None, layout: str = "auto") -> List[LayerView]:
+    """Collect dense layers from ``model`` or from explicit arrays. Raises ``TypeError`` with usage help if none are found."""
+    if weights is not None:
+        views = [LayerView(W=np.asarray(W)) for W in weights]
+        for k, v in enumerate(views):
+            if biases is not None and k < len(biases) and biases[k] is not None:
+                v.b = np.asarray(biases[k])
+            if isinstance(grads, (list, tuple)) and k < len(grads) and grads[k] is not None:
+                v.dW = np.asarray(grads[k])
+            if bias_grads is not None and k < len(bias_grads) and bias_grads[k] is not None:
+                v.db = np.asarray(bias_grads[k])
+    elif model is None:
+        raise TypeError(HELP)
+    elif hasattr(model, "layers") and not isinstance(model, dict):
+        views = _from_layer_objects(list(model.layers))
+    elif isinstance(getattr(model, "params", None), dict):
+        g = grads if isinstance(grads, dict) else getattr(model, "grads", None)
+        views = _from_dict(model.params, g if isinstance(g, dict) else None)
+    elif isinstance(model, dict):
+        views = _from_dict(model, grads if isinstance(grads, dict) else None)
+    elif isinstance(model, (list, tuple)):
+        views = _from_sequence(model)
+        if isinstance(grads, (list, tuple)):
+            for v, g in zip(views, grads):
+                v.dW = np.asarray(g) if g is not None else None
+    else:
+        raise TypeError(HELP)
+    views = [v for v in views if v.W.ndim == 2]
+    if not views:
+        raise TypeError(HELP)
+    return normalise(views, layout)
+
+
+def cached_activations(views: List[LayerView]) -> List[Optional[np.ndarray]]:
+    """Best-effort: the output of hidden layer k is the cached *input* of layer k+1 (e.g. HW-style ``Linear.x``).
+
+    Returns one entry per layer (the last one, the network output, is usually unknown → None).
+    """
+    out: List[Optional[np.ndarray]] = [None] * len(views)
+    for k in range(len(views) - 1):
+        nxt = views[k + 1].source
+        if nxt is None:
+            continue
+        x = _first_attr(nxt, INPUT_CACHE_ATTRS)
+        if x is not None and x.ndim == 2 and x.shape[1] == views[k].out_features:
+            out[k] = x
+    return out