{"id":50873697,"url":"https://github.com/hinanohart/koopgauge","last_synced_at":"2026-06-15T07:31:28.895Z","repository":{"id":361001781,"uuid":"1252668823","full_name":"hinanohart/koopgauge","owner":"hinanohart","description":"Koopman/DMD spectral audit for sequence foundation models (pre-alpha, experimental)","archived":false,"fork":false,"pushed_at":"2026-06-10T09:24:52.000Z","size":176,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T10:06:43.031Z","etag":null,"topics":["dmd","dynamical-systems","koopman","mech-interp","spectral-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hinanohart.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T18:50:17.000Z","updated_at":"2026-06-10T09:24:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hinanohart/koopgauge","commit_stats":null,"previous_names":["hinanohart/koopgauge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hinanohart/koopgauge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Fkoopgauge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Fkoopgauge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Fkoopgauge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Fkoopgauge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hinanohart","download_url":"https://codeload.github.com/hinanohart/koopgauge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hinanohart%2Fkoopgauge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34353189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dmd","dynamical-systems","koopman","mech-interp","spectral-analysis"],"created_at":"2026-06-15T07:31:28.033Z","updated_at":"2026-06-15T07:31:28.889Z","avatar_url":"https://github.com/hinanohart.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koopgauge\n\n**Pre-alpha / Experimental — not production-ready** \u003c!-- honest:ok --\u003e\n\nKoopman/DMD spectral audit for sequence foundation models (Transformer / RWKV).\n\n`koopgauge` applies Dynamic Mode Decomposition (DMD) to hidden state trajectories extracted\nfrom language models to detect representation collapse, periodicity, and chaotic dynamics.\nThe result is a `KoopmanFingerprint` (JSON-LD), a compact spectral signature of a model's\ninternal dynamics. HF Hub fingerprint publishing is planned for v0.1.1.\n\n\u003e Calibration is synthetic-only in v0.1.0a3. This is a reference implementation,\n\u003e not a production calibrator.\n\n## Install\n\n```bash\npip install koopgauge\n```\n\nWith optional backends:\n\n```bash\npip install \"koopgauge[transformers]\"   # HuggingFace transformers support\npip install \"koopgauge[rwkv]\"           # RWKV support\n```\n\n## Quickstart\n\n```python\nimport numpy as np\nfrom koopgauge import SpectralAuditor\n\n# Synthetic trajectory (T=200 time steps, D=64 hidden dims)\nrng = np.random.default_rng(42)\nX = rng.standard_normal((200, 64))\n\nauditor = SpectralAuditor()\nauditor.fit(X)\nfingerprint = auditor.fingerprint()\nprint(f\"Spectral radius: {fingerprint.spectral_radius:.4f}\")\nprint(f\"Stability: {fingerprint.stability_label}\")\n```\n\n### CLI usage\n\n```bash\n# 1. Extract hidden states from a HuggingFace model\nkoopgauge extract gpt2 --prompts prompts.jsonl --out trajectory.zarr --revision \u003ccommit-sha\u003e\n\n# 2. Run DMD audit and emit a KoopmanFingerprint\nkoopgauge audit trajectory.zarr --out fingerprint.json\n\n# 3. Gate on spectral radius (exit 0=pass, 2=fail/abstain)\nkoopgauge gate --fingerprint fingerprint.json --threshold 1.0\n\n# 4. Upload fingerprint to HF Hub (planned v0.1.1)\nkoopgauge upload fingerprint.json --hub-dataset my-org/my-model-fingerprints\n```\n\n## How it works\n\n1. **Extract**: A backend adapter (`transformers` or `rwkv`) runs the model on a prompt set and\n   collects per-layer hidden state snapshots into a zarr trajectory array of shape `(T, D)`.\n\n2. **Kernel selection**: `SpectralAuditor` auto-selects the best DMD variant based on trajectory\n   shape and noise:\n   - `exact_dmd` — default for well-conditioned trajectories\n   - `hankel_dmd` — preferred when T \u003c 30 (short sequences)\n   - `tls_dmd` — preferred when noise variance is high\n   - `arnoldi_dmd` — preferred when D \u003e 5000 (large hidden dimension)\n   - `edmd_rbf` — nonlinear fallback when residual \u003e 0.3\n\n3. **Eigenvalue decomposition**: Each kernel factors the trajectory into eigenvalues and DMD modes.\n   The spectral radius (largest |eigenvalue|) is the primary stability indicator.\n\n4. **AbstainGate**: A three-way decision (`pass` / `abstain` / `fail`) with bootstrap CI is\n   applied on the spectral radius. Under the default `fail-closed` policy, `abstain` maps to\n   exit code 2 (same as `fail`).\n\n5. **KoopmanFingerprint**: A JSON-LD record capturing eigenvalues, spectral radius, stability\n   label, and provenance (model ID, revision SHA, prompt hash, koopgauge version).\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/architecture.png\" alt=\"koopgauge architecture\" width=\"840\"\u003e\n\u003c/div\u003e\n\n## Key features\n\n- 5 DMD kernels: exact, Hankel, TLS (denoising), Arnoldi (large-D), EDMD-RBF (nonlinear)\n- Auto-selects kernel based on trajectory size and noise level\n- AbstainGate: pass / abstain / fail with bootstrap CI\n- `KoopmanFingerprint` schema v1.0 (JSON-LD + HTML embed)\n- sklearn-compatible `SpectralAuditor` (fit / transform / predict / score)\n- CLI: `koopgauge audit`, `koopgauge extract`, `koopgauge calibrate`, `koopgauge gate`, `koopgauge upload`\n- HF Hub fingerprint publishing (planned for v0.1.1)\n\n## Paper credits\n\n- RKSP: Kim et al. (2026), arXiv 2602.22988 — training-time Koopman profiling\n- Transformer Dynamics: arXiv 2502.12131\n- DMD: Brunton \u0026 Kutz, *Data-Driven Science and Engineering* (2022)\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhinanohart%2Fkoopgauge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhinanohart%2Fkoopgauge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhinanohart%2Fkoopgauge/lists"}