https://github.com/hinanohart/koopgauge
Koopman/DMD spectral audit for sequence foundation models (pre-alpha, experimental)
https://github.com/hinanohart/koopgauge
dmd dynamical-systems koopman mech-interp spectral-analysis
Last synced: 4 days ago
JSON representation
Koopman/DMD spectral audit for sequence foundation models (pre-alpha, experimental)
- Host: GitHub
- URL: https://github.com/hinanohart/koopgauge
- Owner: hinanohart
- License: mit
- Created: 2026-05-28T18:50:17.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-06-10T09:24:52.000Z (9 days ago)
- Last Synced: 2026-06-10T10:06:43.031Z (9 days ago)
- Topics: dmd, dynamical-systems, koopman, mech-interp, spectral-analysis
- Language: Python
- Size: 172 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# koopgauge
**Pre-alpha / Experimental — not production-ready**
Koopman/DMD spectral audit for sequence foundation models (Transformer / RWKV).
`koopgauge` applies Dynamic Mode Decomposition (DMD) to hidden state trajectories extracted
from language models to detect representation collapse, periodicity, and chaotic dynamics.
The result is a `KoopmanFingerprint` (JSON-LD), a compact spectral signature of a model's
internal dynamics. HF Hub fingerprint publishing is planned for v0.1.1.
> Calibration is synthetic-only in v0.1.0a3. This is a reference implementation,
> not a production calibrator.
## Install
```bash
pip install koopgauge
```
With optional backends:
```bash
pip install "koopgauge[transformers]" # HuggingFace transformers support
pip install "koopgauge[rwkv]" # RWKV support
```
## Quickstart
```python
import numpy as np
from koopgauge import SpectralAuditor
# Synthetic trajectory (T=200 time steps, D=64 hidden dims)
rng = np.random.default_rng(42)
X = rng.standard_normal((200, 64))
auditor = SpectralAuditor()
auditor.fit(X)
fingerprint = auditor.fingerprint()
print(f"Spectral radius: {fingerprint.spectral_radius:.4f}")
print(f"Stability: {fingerprint.stability_label}")
```
### CLI usage
```bash
# 1. Extract hidden states from a HuggingFace model
koopgauge extract gpt2 --prompts prompts.jsonl --out trajectory.zarr --revision
# 2. Run DMD audit and emit a KoopmanFingerprint
koopgauge audit trajectory.zarr --out fingerprint.json
# 3. Gate on spectral radius (exit 0=pass, 2=fail/abstain)
koopgauge gate --fingerprint fingerprint.json --threshold 1.0
# 4. Upload fingerprint to HF Hub (planned v0.1.1)
koopgauge upload fingerprint.json --hub-dataset my-org/my-model-fingerprints
```
## How it works
1. **Extract**: A backend adapter (`transformers` or `rwkv`) runs the model on a prompt set and
collects per-layer hidden state snapshots into a zarr trajectory array of shape `(T, D)`.
2. **Kernel selection**: `SpectralAuditor` auto-selects the best DMD variant based on trajectory
shape and noise:
- `exact_dmd` — default for well-conditioned trajectories
- `hankel_dmd` — preferred when T < 30 (short sequences)
- `tls_dmd` — preferred when noise variance is high
- `arnoldi_dmd` — preferred when D > 5000 (large hidden dimension)
- `edmd_rbf` — nonlinear fallback when residual > 0.3
3. **Eigenvalue decomposition**: Each kernel factors the trajectory into eigenvalues and DMD modes.
The spectral radius (largest |eigenvalue|) is the primary stability indicator.
4. **AbstainGate**: A three-way decision (`pass` / `abstain` / `fail`) with bootstrap CI is
applied on the spectral radius. Under the default `fail-closed` policy, `abstain` maps to
exit code 2 (same as `fail`).
5. **KoopmanFingerprint**: A JSON-LD record capturing eigenvalues, spectral radius, stability
label, and provenance (model ID, revision SHA, prompt hash, koopgauge version).
## Architecture
## Key features
- 5 DMD kernels: exact, Hankel, TLS (denoising), Arnoldi (large-D), EDMD-RBF (nonlinear)
- Auto-selects kernel based on trajectory size and noise level
- AbstainGate: pass / abstain / fail with bootstrap CI
- `KoopmanFingerprint` schema v1.0 (JSON-LD + HTML embed)
- sklearn-compatible `SpectralAuditor` (fit / transform / predict / score)
- CLI: `koopgauge audit`, `koopgauge extract`, `koopgauge calibrate`, `koopgauge gate`, `koopgauge upload`
- HF Hub fingerprint publishing (planned for v0.1.1)
## Paper credits
- RKSP: Kim et al. (2026), arXiv 2602.22988 — training-time Koopman profiling
- Transformer Dynamics: arXiv 2502.12131
- DMD: Brunton & Kutz, *Data-Driven Science and Engineering* (2022)
## License
MIT