quantprobe 1.3.0__tar.gz → 1.4.0__tar.gz

quantprobe-1.4.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: quantprobe
+Version: 1.4.0
+Summary: Probe-then-quantize for LLMs: measure a model's fragility curve, plan bit/tier placement by the tiered decode law, and emit ready-to-run llama.cpp recipes.
+Author: Federico Sciuca
+License: MIT
+Project-URL: Homepage, https://github.com/FedericoTs/quantprobe
+Keywords: llm,quantization,llama.cpp,gguf,inference,moe
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gguf>=0.9
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# quantprobe
+
+### Placement beats budget
+
+**Where your bits sit — which layers, which memory tier — matters more than how many you have. Four falsification-tested laws for running big LLMs on hardware you already own, every number measured on one 2016 desktop (GTX 1060 6 GB · 16 GB DDR4 · SATA SSD).**
+
+![smoke](https://github.com/FedericoTs/quantprobe/actions/workflows/smoke.yml/badge.svg) ![license](https://img.shields.io/badge/license-MIT-0f766e) ![hardware](https://img.shields.io/badge/measured_on-2016_GTX_1060_6GB-d73027) ![data--free](https://img.shields.io/badge/quantization-data--free-1d9e70) ![models](https://img.shields.io/badge/validated-7B_→_744B-378add) [![x](https://img.shields.io/badge/author-@federico__sciuca-14181f)](https://x.com/federico_sciuca)
+
+<p align="center"><img src="weights/data/hero_placement.png" width="880" alt="Placement across memory tiers: disk 2-bit cold experts, RAM 2-bit experts + probed fragile band at 4-bit, VRAM 4-bit attention — one law ties them"></p>
+
+> **▶ Try the interactive calculator: [Will it run — and how fast?](https://federicots.github.io/quantprobe/)**
+> Pick any model + your machine → predicted tok/s, memory fit, quality cost, and your cheapest next upgrade — from the law below, with your config plotted against every validated measurement.
+
+
+**New here? → [QUICKSTART.md](QUICKSTART.md) gets you running in 60 seconds.** Two tiers: `plan`/`target` and the web calculator need *nothing* installed; `quantize`/`probe`/`run`/`bench`/`dashboard` drive [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point quantprobe at it with `--llama-dir`, `QUANTPROBE_LLAMA_DIR`, or `PATH`). Preview any command without llama.cpp using `--dry`. 16 machine presets ship in (`--machine`): GTX 1060 → RTX 5090, Apple `mac-m2/m3/m4-*`, DGX Spark, Epyc — or pass raw specs. Multi-GPU / RAID? Comma lists aggregate: `--vram 24,24 --disk-bw 14,14`. Big-VRAM + disk-streaming rigs get the three-tier expert-cache row (v1.3).
+
+
+---
+
+## What this is
+
+My 2016 desktop can't run frontier models the way a datacenter does — so instead of brute force, I asked *where* every bit and byte should go, and answered it by measurement. Months of experiments later, the result is four laws, a 30-minute probe tool, copy-paste llama.cpp recipes, and one equation that predicts decode speed from 7B to 744B — validated against my own pre-registered predictions and against [colibri](https://github.com/JustVugg/colibri)'s independently published 744B numbers.
+
+## Headline results
+
+| result | number |
+|---|---|
+| 16B MoE, 2-bit, **data-free**, resident on a 6 GB card | ppl 6.31 → 6.96 (**1.10×**) — beats calibrated SOTA's gap-ratio |
+| Same bytes, different layers (Gemma 4 12B, stock llama.cpp) | **byte-identical files, 2.25 ppl apart** (12.27 vs 10.02) |
+| Gemma 4 12B depth-aware 2-bit | 1.91× → **1.45×** quality cost, ~4.5 GB resident |
+| Qwen3-30B-A3B on the 2016 desktop | **19.3 tok/s** — hybrid placement, *predicted 19 before measuring* |
+| GLM-4.5-Air **110B** from a SATA drive, 16 GB RAM | 0.19 tok/s — inside the law's pre-registered 0.2–0.3 band |
+| RAM overclock (XMP, 2133→3000) | dense **+52%**, pre-registered ×1.41+ |
+
+## Why the evidence is unusually strong
+
+Most benchmark posts report what happened. I report what I **predicted before it happened** — I wrote the number down, then ran the hardware, and this is the strongest form of empirical evidence I know how to produce:
+
+| prediction (made first) | measured (after) |
+|---|---|
+| 110B streamed from SATA: **0.2–0.3 tok/s** | **0.19** |
+| RAM overclock scales in-RAM decode **×1.41+** | **×1.52** |
+| 30B hybrid placement: **~19 tok/s** | **19.30 ± 0.88** |
+| a day-old 118B (Laguna S 2.1) streamed from this SATA drive: **0.2–0.4** ([staked pre-download](preregistrations/2026-07-23-laguna-s-2.1-on-2016-desktop.md)) | **0.38 ± 0.17** |
+| colibri's own 128 GB / 25 GB tiers, from our η bands | land **inside** the bands |
+
+Add to that: a **byte-identical control** (two GGUFs the same size, 2.25 ppl apart — only placement differs), a full **claim → script → log manifest** (every number reproducible in-tree), and a set of **documented dead ends** (dynamic top-k, semantic paging, self-speculation — all measured-dead, because a law you only confirm is a law you haven't tested).
+
+<p align="center"><img src="weights/data/validation_19tok/live_run_20tps.png" width="880" alt="One frame: Task Manager showing 16 GB DDR4-3000 and the GTX 1060 6GB beside llama.cpp chatting Qwen3-30B-A3B live at 20.4 tok/s generation"></p>
+<p align="center"><em>One frame, no cuts: Task Manager (16 GB @ 3000 MT/s, GTX 1060 6 GB, RAM at 91% — the hybrid placement using the whole machine) beside llama.cpp chatting Qwen3-30B-A3B at <b>20.4 tok/s generation</b> — above the pre-registered 19. Raw logs, hardware attestation + GGUF SHA256: <a href="weights/data/validation_19tok/EVIDENCE.txt">EVIDENCE.txt</a>. Third bench run: 19.26 ± 0.45 (series 19.30 → 19.55 → 19.26).</em></p>
+
+**Open pre-registrations** — predictions staked publicly *before* measurement: [colibri v1.1, five falsifiable predictions (2026-07-23)](preregistrations/2026-07-23-colibri-v1.1.md) — dual-SSD scaling, int3 speedup, lattice-vs-scalar, AVX-512 tier-scoping, MTP×MoE antagonism.
+
+
+## The four placement laws
+
+Full statements, each with its establishing measurement and a falsifiable prediction, in **[LAWS.md](LAWS.md)**.
+
+1. **Rotation is rank-conditional.** Incoherence rotation (QuIP#/QTIP/QuaRot) helps full-rank tensors (+0.006 ppl) and destroys low-rank bottlenecks (+1623 ppl) — a ~270,000× swing on effective rank alone.
+2. **Trained networks are dense everywhere.** Experts sit *exactly* at the rate-distortion floor; routing is flat (even across domains — Jaccard 1.00 prose vs code); activations are diffuse. **2-bit is the floor.**
+3. **Fragility is measurable, not predictable.** Gemma late-fragile 4×, Mistral **early-fragile 25×** — architectural near-twins pointing opposite ways. Weight statistics mislead. **Only a 30-minute functional probe decides.**
+4. **The tiered decode law.** `tok/s = η(tier)·BW ÷ active-bytes`, η collapsing per tier across 7B→744B and both projects' hardware. **v1.1 adds the context term**: each generated token also re-reads the whole KV cache from *its* tier — `--ctx` prices it, `bench --depth` measures it (measured here: 20.02 → 16.12 tok/s at 16k depth).
+
+<p align="center"><img src="weights/data/x_chart_E_scalinglaw.png" width="700" alt="One scaling law, 7B to 744B, predicted vs measured, including colibri's published tiers"></p>
+
+<p align="center"><img src="weights/data/x_chart_D_placement.png" width="700" alt="Byte-identical GGUF files, 2.25 perplexity apart — placement is worth twice the byte budget"></p>
+<p align="center"><img src="weights/data/x_chart_I_kvdepth.png" width="700" alt="Decode speed versus context depth: measured 20.02 tok/s at depth zero falling to 16.12 at 16384, on the Law 4 v2 curve with eta_kv 0.70"></p>
+
+
+## Install — and the ten commands
+
+```bash
+pip install quantprobe
+```
+
+**Zero-config on your own box**: `quantprobe plan --gguf model.gguf` auto-detects the machine and reads the model from the file. Presets/flags estimate any *other* machine. `hw`/`plan`/`target`/`optimize` need nothing else installed; the rest drive stock [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point at it with `--llama-dir`/`QUANTPROBE_LLAMA_DIR`/`PATH`; preview any command with `--dry`).
+
+```bash
+quantprobe hw                                            # what the law sees on THIS machine (every value source-tagged)
+quantprobe plan     --gguf model.gguf                    # zero-config prediction: placement + tok/s + the launch command
+quantprobe optimize --tps 20                             # CHEAPEST PATH to a target: bits x placement x hardware, Pareto-ranked
+quantprobe target   --tps 5 --machine gaming --ladder    # inverse: target -> smartest model + speed-intelligence ladder
+quantprobe fetch    qwen3-30b ./models                   # robust, resumable download
+quantprobe quantize --gguf f16.gguf --out 2bit.gguf      # COMPRESS: depth-aware ~2-bit GGUF (verified: loads + generates)
+quantprobe probe    --gguf f16.gguf --eval wiki.test.raw # measure YOUR model's fragile band (~30 min); --apply builds it
+quantprobe run      --gguf 2bit.gguf                     # plan the placement, then LAUNCH llama.cpp chat
+quantprobe bench    --gguf 2bit.gguf --contribute        # predicted vs measured on your box; opt-in datapoint
+quantprobe dashboard --gguf 2bit.gguf                    # chat while every reply is scored against the prediction
+```
+
+The loop is self-validating: `plan` predicted 17.5 for a file we then measured at **18.32 ± 0.17**; the config months of research converged to is what `optimize` picks blind. A measured example of what that's worth: the same model, mis-specified vs law-routed, is **3.38 vs 18.32 tok/s (×5.4)** — [worked examples](docs/EXAMPLES.md).
+
+## Help grow the law
+
+`quantprobe bench --contribute` prints exactly what would be shared (hardware label, model, predicted-vs-measured) plus a pre-filled issue link — **you review and submit; nothing is ever sent automatically**. Contributed points land on the law chart; the ones *outside* the bands are the most valuable. Open falsifiable predictions anyone can settle: [preregistrations/](preregistrations/).
+
+## Deep dives
+
+| | |
+|---|---|
+| [QUICKSTART.md](QUICKSTART.md) | 60-second start, three levels; Ollama interop; llama.cpp version notes |
+| [LAWS.md](LAWS.md) | the four laws — statements, measurements, falsifiable predictions, the general form |
+| [docs/EXAMPLES.md](docs/EXAMPLES.md) | worked examples with real outputs: zero-config, the ×5.4 optimizer A/B, probe walkthrough, troubleshooting |
+| [docs/HARDWARE.md](docs/HARDWARE.md) | the 2016 box: exact specs, measured bandwidths, what the next euro buys |
+| [docs/DEEP-DIVE.md](docs/DEEP-DIVE.md) | what's new vs. what's built-on, parity tables, the 744B-at-home projection, repository map |
+| [preregistrations/](preregistrations/) | every staked prediction with its verdict — hits, the near-miss, and the honest miss |
+| [papers/arxiv/](papers/arxiv/) | the paper (submission-ready LaTeX) |
+| [CHANGELOG.md](CHANGELOG.md) | v1.0 → v1.4, every release |
+
+## Honest limitations
+
+- Perplexity on WikiText-2 is my primary metric; I haven't run task-level evals (MMLU/HellaSwag) yet.
+- My fragility atlas covers four model families — enough to *disprove* universality, not to chart every architecture.
+- 0.19 tok/s for a 110B is a **capacity demonstration, not usable inference** — the honest speed only arrives with faster storage.
+- Speed numbers are single-stream decode on one machine (±25% across environments); the tiered-decode η values are fitted, not derived.
+- No custom runtime: everything rides stock llama.cpp and streaming eval harnesses. The one CUDA kernel is verified in reference, not built.
+
+
+## Credits
+
+[colibri](https://github.com/JustVugg/colibri) (744B on 25 GB, pure C) inspired the tier-streaming exploration. The quantization stack builds on [llama.cpp](https://github.com/ggml-org/llama.cpp) and the QTIP/QuIP# incoherence codecs — whose central tool our first law bounds. Independent research by Federico Sciuca, AI-supported, on one desktop; every claim is measured, and every negative that redirected the work is documented. The Law 4 context term (v1.1) was prompted by **u/RogerAI--fyi** (Reddit), who correctly observed the original formulation omitted per-token KV reads — measured, confirmed, and shipped within a day.
+
+## License
+
+MIT — see [LICENSE](LICENSE). © 2026 Federico Sciuca.

quantprobe-1.4.0/README.md

@@ -0,0 +1,125 @@
+# quantprobe
+
+### Placement beats budget
+
+**Where your bits sit — which layers, which memory tier — matters more than how many you have. Four falsification-tested laws for running big LLMs on hardware you already own, every number measured on one 2016 desktop (GTX 1060 6 GB · 16 GB DDR4 · SATA SSD).**
+
+![smoke](https://github.com/FedericoTs/quantprobe/actions/workflows/smoke.yml/badge.svg) ![license](https://img.shields.io/badge/license-MIT-0f766e) ![hardware](https://img.shields.io/badge/measured_on-2016_GTX_1060_6GB-d73027) ![data--free](https://img.shields.io/badge/quantization-data--free-1d9e70) ![models](https://img.shields.io/badge/validated-7B_→_744B-378add) [![x](https://img.shields.io/badge/author-@federico__sciuca-14181f)](https://x.com/federico_sciuca)
+
+<p align="center"><img src="weights/data/hero_placement.png" width="880" alt="Placement across memory tiers: disk 2-bit cold experts, RAM 2-bit experts + probed fragile band at 4-bit, VRAM 4-bit attention — one law ties them"></p>
+
+> **▶ Try the interactive calculator: [Will it run — and how fast?](https://federicots.github.io/quantprobe/)**
+> Pick any model + your machine → predicted tok/s, memory fit, quality cost, and your cheapest next upgrade — from the law below, with your config plotted against every validated measurement.
+
+
+**New here? → [QUICKSTART.md](QUICKSTART.md) gets you running in 60 seconds.** Two tiers: `plan`/`target` and the web calculator need *nothing* installed; `quantize`/`probe`/`run`/`bench`/`dashboard` drive [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point quantprobe at it with `--llama-dir`, `QUANTPROBE_LLAMA_DIR`, or `PATH`). Preview any command without llama.cpp using `--dry`. 16 machine presets ship in (`--machine`): GTX 1060 → RTX 5090, Apple `mac-m2/m3/m4-*`, DGX Spark, Epyc — or pass raw specs. Multi-GPU / RAID? Comma lists aggregate: `--vram 24,24 --disk-bw 14,14`. Big-VRAM + disk-streaming rigs get the three-tier expert-cache row (v1.3).
+
+
+---
+
+## What this is
+
+My 2016 desktop can't run frontier models the way a datacenter does — so instead of brute force, I asked *where* every bit and byte should go, and answered it by measurement. Months of experiments later, the result is four laws, a 30-minute probe tool, copy-paste llama.cpp recipes, and one equation that predicts decode speed from 7B to 744B — validated against my own pre-registered predictions and against [colibri](https://github.com/JustVugg/colibri)'s independently published 744B numbers.
+
+## Headline results
+
+| result | number |
+|---|---|
+| 16B MoE, 2-bit, **data-free**, resident on a 6 GB card | ppl 6.31 → 6.96 (**1.10×**) — beats calibrated SOTA's gap-ratio |
+| Same bytes, different layers (Gemma 4 12B, stock llama.cpp) | **byte-identical files, 2.25 ppl apart** (12.27 vs 10.02) |
+| Gemma 4 12B depth-aware 2-bit | 1.91× → **1.45×** quality cost, ~4.5 GB resident |
+| Qwen3-30B-A3B on the 2016 desktop | **19.3 tok/s** — hybrid placement, *predicted 19 before measuring* |
+| GLM-4.5-Air **110B** from a SATA drive, 16 GB RAM | 0.19 tok/s — inside the law's pre-registered 0.2–0.3 band |
+| RAM overclock (XMP, 2133→3000) | dense **+52%**, pre-registered ×1.41+ |
+
+## Why the evidence is unusually strong
+
+Most benchmark posts report what happened. I report what I **predicted before it happened** — I wrote the number down, then ran the hardware, and this is the strongest form of empirical evidence I know how to produce:
+
+| prediction (made first) | measured (after) |
+|---|---|
+| 110B streamed from SATA: **0.2–0.3 tok/s** | **0.19** |
+| RAM overclock scales in-RAM decode **×1.41+** | **×1.52** |
+| 30B hybrid placement: **~19 tok/s** | **19.30 ± 0.88** |
+| a day-old 118B (Laguna S 2.1) streamed from this SATA drive: **0.2–0.4** ([staked pre-download](preregistrations/2026-07-23-laguna-s-2.1-on-2016-desktop.md)) | **0.38 ± 0.17** |
+| colibri's own 128 GB / 25 GB tiers, from our η bands | land **inside** the bands |
+
+Add to that: a **byte-identical control** (two GGUFs the same size, 2.25 ppl apart — only placement differs), a full **claim → script → log manifest** (every number reproducible in-tree), and a set of **documented dead ends** (dynamic top-k, semantic paging, self-speculation — all measured-dead, because a law you only confirm is a law you haven't tested).
+
+<p align="center"><img src="weights/data/validation_19tok/live_run_20tps.png" width="880" alt="One frame: Task Manager showing 16 GB DDR4-3000 and the GTX 1060 6GB beside llama.cpp chatting Qwen3-30B-A3B live at 20.4 tok/s generation"></p>
+<p align="center"><em>One frame, no cuts: Task Manager (16 GB @ 3000 MT/s, GTX 1060 6 GB, RAM at 91% — the hybrid placement using the whole machine) beside llama.cpp chatting Qwen3-30B-A3B at <b>20.4 tok/s generation</b> — above the pre-registered 19. Raw logs, hardware attestation + GGUF SHA256: <a href="weights/data/validation_19tok/EVIDENCE.txt">EVIDENCE.txt</a>. Third bench run: 19.26 ± 0.45 (series 19.30 → 19.55 → 19.26).</em></p>
+
+**Open pre-registrations** — predictions staked publicly *before* measurement: [colibri v1.1, five falsifiable predictions (2026-07-23)](preregistrations/2026-07-23-colibri-v1.1.md) — dual-SSD scaling, int3 speedup, lattice-vs-scalar, AVX-512 tier-scoping, MTP×MoE antagonism.
+
+
+## The four placement laws
+
+Full statements, each with its establishing measurement and a falsifiable prediction, in **[LAWS.md](LAWS.md)**.
+
+1. **Rotation is rank-conditional.** Incoherence rotation (QuIP#/QTIP/QuaRot) helps full-rank tensors (+0.006 ppl) and destroys low-rank bottlenecks (+1623 ppl) — a ~270,000× swing on effective rank alone.
+2. **Trained networks are dense everywhere.** Experts sit *exactly* at the rate-distortion floor; routing is flat (even across domains — Jaccard 1.00 prose vs code); activations are diffuse. **2-bit is the floor.**
+3. **Fragility is measurable, not predictable.** Gemma late-fragile 4×, Mistral **early-fragile 25×** — architectural near-twins pointing opposite ways. Weight statistics mislead. **Only a 30-minute functional probe decides.**
+4. **The tiered decode law.** `tok/s = η(tier)·BW ÷ active-bytes`, η collapsing per tier across 7B→744B and both projects' hardware. **v1.1 adds the context term**: each generated token also re-reads the whole KV cache from *its* tier — `--ctx` prices it, `bench --depth` measures it (measured here: 20.02 → 16.12 tok/s at 16k depth).
+
+<p align="center"><img src="weights/data/x_chart_E_scalinglaw.png" width="700" alt="One scaling law, 7B to 744B, predicted vs measured, including colibri's published tiers"></p>
+
+<p align="center"><img src="weights/data/x_chart_D_placement.png" width="700" alt="Byte-identical GGUF files, 2.25 perplexity apart — placement is worth twice the byte budget"></p>
+<p align="center"><img src="weights/data/x_chart_I_kvdepth.png" width="700" alt="Decode speed versus context depth: measured 20.02 tok/s at depth zero falling to 16.12 at 16384, on the Law 4 v2 curve with eta_kv 0.70"></p>
+
+
+## Install — and the ten commands
+
+```bash
+pip install quantprobe
+```
+
+**Zero-config on your own box**: `quantprobe plan --gguf model.gguf` auto-detects the machine and reads the model from the file. Presets/flags estimate any *other* machine. `hw`/`plan`/`target`/`optimize` need nothing else installed; the rest drive stock [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point at it with `--llama-dir`/`QUANTPROBE_LLAMA_DIR`/`PATH`; preview any command with `--dry`).
+
+```bash
+quantprobe hw                                            # what the law sees on THIS machine (every value source-tagged)
+quantprobe plan     --gguf model.gguf                    # zero-config prediction: placement + tok/s + the launch command
+quantprobe optimize --tps 20                             # CHEAPEST PATH to a target: bits x placement x hardware, Pareto-ranked
+quantprobe target   --tps 5 --machine gaming --ladder    # inverse: target -> smartest model + speed-intelligence ladder
+quantprobe fetch    qwen3-30b ./models                   # robust, resumable download
+quantprobe quantize --gguf f16.gguf --out 2bit.gguf      # COMPRESS: depth-aware ~2-bit GGUF (verified: loads + generates)
+quantprobe probe    --gguf f16.gguf --eval wiki.test.raw # measure YOUR model's fragile band (~30 min); --apply builds it
+quantprobe run      --gguf 2bit.gguf                     # plan the placement, then LAUNCH llama.cpp chat
+quantprobe bench    --gguf 2bit.gguf --contribute        # predicted vs measured on your box; opt-in datapoint
+quantprobe dashboard --gguf 2bit.gguf                    # chat while every reply is scored against the prediction
+```
+
+The loop is self-validating: `plan` predicted 17.5 for a file we then measured at **18.32 ± 0.17**; the config months of research converged to is what `optimize` picks blind. A measured example of what that's worth: the same model, mis-specified vs law-routed, is **3.38 vs 18.32 tok/s (×5.4)** — [worked examples](docs/EXAMPLES.md).
+
+## Help grow the law
+
+`quantprobe bench --contribute` prints exactly what would be shared (hardware label, model, predicted-vs-measured) plus a pre-filled issue link — **you review and submit; nothing is ever sent automatically**. Contributed points land on the law chart; the ones *outside* the bands are the most valuable. Open falsifiable predictions anyone can settle: [preregistrations/](preregistrations/).
+
+## Deep dives
+
+| | |
+|---|---|
+| [QUICKSTART.md](QUICKSTART.md) | 60-second start, three levels; Ollama interop; llama.cpp version notes |
+| [LAWS.md](LAWS.md) | the four laws — statements, measurements, falsifiable predictions, the general form |
+| [docs/EXAMPLES.md](docs/EXAMPLES.md) | worked examples with real outputs: zero-config, the ×5.4 optimizer A/B, probe walkthrough, troubleshooting |
+| [docs/HARDWARE.md](docs/HARDWARE.md) | the 2016 box: exact specs, measured bandwidths, what the next euro buys |
+| [docs/DEEP-DIVE.md](docs/DEEP-DIVE.md) | what's new vs. what's built-on, parity tables, the 744B-at-home projection, repository map |
+| [preregistrations/](preregistrations/) | every staked prediction with its verdict — hits, the near-miss, and the honest miss |
+| [papers/arxiv/](papers/arxiv/) | the paper (submission-ready LaTeX) |
+| [CHANGELOG.md](CHANGELOG.md) | v1.0 → v1.4, every release |
+
+## Honest limitations
+
+- Perplexity on WikiText-2 is my primary metric; I haven't run task-level evals (MMLU/HellaSwag) yet.
+- My fragility atlas covers four model families — enough to *disprove* universality, not to chart every architecture.
+- 0.19 tok/s for a 110B is a **capacity demonstration, not usable inference** — the honest speed only arrives with faster storage.
+- Speed numbers are single-stream decode on one machine (±25% across environments); the tiered-decode η values are fitted, not derived.
+- No custom runtime: everything rides stock llama.cpp and streaming eval harnesses. The one CUDA kernel is verified in reference, not built.
+
+
+## Credits
+
+[colibri](https://github.com/JustVugg/colibri) (744B on 25 GB, pure C) inspired the tier-streaming exploration. The quantization stack builds on [llama.cpp](https://github.com/ggml-org/llama.cpp) and the QTIP/QuIP# incoherence codecs — whose central tool our first law bounds. Independent research by Federico Sciuca, AI-supported, on one desktop; every claim is measured, and every negative that redirected the work is documented. The Law 4 context term (v1.1) was prompted by **u/RogerAI--fyi** (Reddit), who correctly observed the original formulation omitted per-token KV reads — measured, confirmed, and shipped within a day.
+
+## License
+
+MIT — see [LICENSE](LICENSE). © 2026 Federico Sciuca.

{quantprobe-1.3.0 → quantprobe-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantprobe"
-version = "1.3.0"
+version = "1.4.0"
 description = "Probe-then-quantize for LLMs: measure a model's fragility curve, plan bit/tier placement by the tiered decode law, and emit ready-to-run llama.cpp recipes."
 readme = "README.md"
 license = { text = "MIT" }

{quantprobe-1.3.0 → quantprobe-1.4.0}/quantprobe/__init__.py

@@ -8,4 +8,4 @@ Three commands, all grounded in measured laws (see LAWS.md in the repo):
 Every constant in `plan` is fitted from measurements published in the repo, including two
 pre-registered hardware predictions confirmed within 8%.
 """
-__version__ = "1.3.0"
+__version__ = "1.4.0"

{quantprobe-1.3.0 → quantprobe-1.4.0}/quantprobe/cli.py

@@ -84,6 +84,13 @@ def main():
     z.add_argument("--llama-dir", default=None)
     z.add_argument("--dry", action="store_true")
 
+    o = sub.add_parser("optimize", help="cheapest path to a target speed: search bits x placement x KV x hardware over the law")
+    o.add_argument("--tps", type=float, default=None, help="target tok/s (omit for the speed frontier)")
+    o.add_argument("--max-quality", type=float, default=None, help="quality-cost ceiling (default 1.12)")
+    o.add_argument("--any-runtime", action="store_true", help="include placements needing expert-caching runtimes (ktransformers-class), not just stock llama.cpp")
+    o.add_argument("--allow-prune", action="store_true", help="include REAP-class pruned variants (domain-specialized: +39%% out-of-domain ppl measured)")
+    hwargs(o)
+
     hwp = sub.add_parser("hw", help="detect THIS machine's memory tiers (no flags needed); every value tagged with its source")
     hwp.add_argument("--measure", default=None, metavar="FILE", help="also MEASURE sequential disk read on a real file (e.g. a GGUF)")
 
@@ -109,6 +116,9 @@ def main():
     elif a.cmd == "target":
         from . import target
         target.run(a)
+    elif a.cmd == "optimize":
+        from . import optimize
+        optimize.run(a)
     elif a.cmd == "hw":
         from . import detect
         detect.run(a)

quantprobe-1.4.0/quantprobe/optimize.py

@@ -0,0 +1,133 @@
+"""quantprobe optimize — the cheapest path to a target speed.
+
+A pure SEARCH LAYER over the frozen decode law: enumerate lever combinations, price each with
+plan.evaluate(), rank by (meets target, quality cost, euros, speed). The law is never modified —
+the optimizer only reads it, so every published anchor is untouchable by construction.
+
+Levers and their measured gates:
+  bits      effective bits/weight ladder, priced with the DEPTH-AWARE quality curve (measured;
+            uniform quantization costs ~1.3x more quality at <=2.5 bits — Gemma 1.91x vs 1.45x)
+  kv-q8     quantized K-cache (kvp x0.75). GATED OFF on weak-decode GPUs: measured -83%
+            at 16k depth on Pascal (2026-07-24, no flash attention -> per-token dequant tax).
+            Offered [est] only where geta >= 0.5; verify with `bench --depth`.
+  prune     REAP-class 50% expert pruning (total x0.82, file shrinks, active bytes UNCHANGED).
+            Measured +39% out-of-domain perplexity (pre-registration #8) — domain-specialized,
+            never ranked first without --allow-prune.
+  hardware  euro-priced deltas from the projections table: XMP (free), +16GB RAM (~40), NVMe (~100).
+"""
+from __future__ import annotations
+from . import plan as planmod
+
+BITS_LADDER = [2.0, 2.5, 3.0, 3.5, 4.5]
+REALIZE = {
+    2.0: 'quantize --gguf <f16> --protect-late 8   (base Q2_K, narrow probed band)',
+    2.5: 'quantize --gguf <f16> --protect-late 12  (base Q2_K - the validated default)',
+    3.0: 'quantize --gguf <f16> --protect-late 20  (or base Q3_K_S)',
+    3.5: 'fetch a Q3_K_M and probe --apply',
+    4.5: 'fetch a Q4_K_M (straight; no probe needed at 4-bit)',
+}
+HW_DELTAS = [
+    ("as-is", 0, {}),
+    ("+16GB RAM (~40 EUR used)", 40, {"rc": +16}),
+    ("NVMe SSD (~100 EUR)", 100, {"db_min": 3.5}),
+    ("+RAM & NVMe (~140 EUR)", 140, {"rc": +16, "db_min": 3.5}),
+]
+
+
+def resolve(a):
+    """Model + machine resolution, same semantics as plan.run (autospec + autodetect included)."""
+    from . import spec as specmod
+    specmod.apply(a, quiet=True)
+    if getattr(a, "bits", None) is None:
+        a.bits = 2.5
+    m = dict(planmod.MODELS[a.model]) if getattr(a, "model", None) in planmod.MODELS else {}
+    t = a.total or m.get("t") or 13.0
+    ac = a.active or m.get("a") or t
+    ne = a.always_active or m.get("ne") or (ac if ac >= t * 0.9 else ac * 0.35)
+    moe = m.get("moe", ac < t * 0.9)
+    hw = dict(planmod.MACHINES[a.machine]) if getattr(a, "machine", None) in planmod.MACHINES else {}
+    if not hw and all(getattr(a, k, None) is None for k in ("vram", "vram_bw", "ram", "ram_bw", "disk_bw")):
+        from . import detect as detmod
+        auto, _ = detmod.detect()
+        hw = dict(vc=auto["vram"], vb=auto["vram_bw"], rc=auto["ram"], rb=auto["ram_bw"],
+                  db=auto["disk_bw"], geta=auto.get("geta", 0.45), gl=auto.get("gl"),
+                  hint="THIS machine [auto-detected]")
+        print("[quantprobe] hardware auto-detected (pass --machine/flags to optimize another box)")
+    vc = planmod.agg_cap(a.vram) if a.vram is not None else hw.get("vc", 0)
+    vb = planmod.agg_bw(a.vram_bw, 0.85) if a.vram_bw is not None else hw.get("vb", 0)
+    rc = a.ram if a.ram is not None else hw.get("rc", 16)
+    rb = a.ram_bw if a.ram_bw is not None else hw.get("rb", 40)
+    db = planmod.agg_bw(a.disk_bw, 0.75) if a.disk_bw is not None else hw.get("db", 0.5)
+    geta = hw.get("geta", 0.45); gl = hw.get("gl")
+    ctx = getattr(a, "ctx", 0) or 0
+    kvp = (a.kv_per_pos * 1024 if getattr(a, "kv_per_pos", None) else m.get("kvp", planmod.DEFAULT_KVP))
+    return m, t, ac, ne, moe, (vc or 0, vb or 0, rc or 16, rb or 40, db or 0.5, geta, gl), ctx, kvp
+
+
+def run(a):
+    m, t, ac, ne, moe, (vc, vb, rc, rb, db, geta, gl), ctx, kvp = resolve(a)
+    tgt = getattr(a, "tps", None)
+    maxq = getattr(a, "max_quality", None) or 1.12
+    allow_prune = getattr(a, "allow_prune", False)
+    kvq_ok = geta >= 0.5                      # measured gate: Pascal-class collapses (-83% @16k)
+    rows = []
+    for hw_name, euro, delta in HW_DELTAS:
+        rc2 = rc + delta.get("rc", 0)
+        db2 = max(db, delta.get("db_min", db))
+        if euro and rc2 == rc and db2 == db:
+            continue                           # delta changes nothing on this box
+        for bits in BITS_LADDER:
+            for prune, pf in ((False, 1.0),) + (((True, 0.82),) if allow_prune and moe else ()):
+                for kvq, kf in ((False, 1.0),) + (((True, 0.75),) if kvq_ok and ctx > 0 else ()):
+                    q = planmod.qual_of(moe, bits) * (1.0 if not prune else 1.0)  # in-domain qual; OOD flagged in text
+                    if q > maxq:
+                        continue
+                    _, _, cfgs = planmod.evaluate(t * pf, ac, ne, moe, bits, vc, vb, rc2, rb, db2,
+                                                  geta, 1.0, gl, ctx=ctx, kvp=kvp * kf)
+                    if not cfgs:
+                        continue
+                    if not getattr(a, "any_runtime", False):
+                        cfgs = [c for c in cfgs if "expert cache" not in c[0]] or cfgs
+                    name, tps, warn, flags = cfgs[0]
+                    desc = f"{bits:g}-bit depth-aware + {name}"
+                    tags = []
+                    if prune:
+                        tags.append("PRUNED: +39% out-of-domain ppl measured - domain use only")
+                    if kvq:
+                        tags.append("KV q8 [est - needs FA; measured trap on Pascal-class]")
+                    if hw_name != "as-is":
+                        desc += f" + {hw_name}"
+                    rows.append(dict(tps=tps, q=q, euro=euro, bits=bits, desc=desc,
+                                     tags=tags, flags=flags, warn=warn))
+    # Pareto: drop rows beaten on every axis
+    keep = []
+    for r in sorted(rows, key=lambda x: (-x["tps"], x["q"], x["euro"])):
+        if not any(k["tps"] >= r["tps"] and k["q"] <= r["q"] and k["euro"] <= r["euro"]
+                   and (k["tps"], k["q"], k["euro"]) != (r["tps"], r["q"], r["euro"]) for k in keep):
+            keep.append(r)
+    if tgt:
+        meeting = [r for r in keep if r["tps"] >= tgt]
+        ranked = (sorted(meeting, key=lambda x: (x["q"], x["euro"], -x["tps"])) or
+                  sorted(keep, key=lambda x: -x["tps"])[:1])
+        headline = "cheapest configuration meeting the target" if meeting else \
+                   "TARGET NOT REACHABLE on this hardware - fastest available:"
+    else:
+        ranked = sorted(keep, key=lambda x: (-x["tps"], x["q"], x["euro"]))
+        headline = "speed frontier (quality ceiling x%.2f)" % maxq
+    print(f"\nquantprobe optimize - {m.get('hint', 'custom model')} on "
+          f"{'this machine' if not getattr(a, 'machine', None) else a.machine}"
+          + (f" | target {tgt:g} tok/s" if tgt else "") + (f" | ctx {ctx}" if ctx else ""))
+    print(f"  {headline}\n")
+    for i, r in enumerate(ranked[:6]):
+        star = "*" if i == 0 else " "
+        euro = "free" if r["euro"] == 0 else f"~{r['euro']}EUR"
+        print(f"  {star} {r['tps']:6.1f} tok/s  quality x{r['q']:.2f}  {euro:>7s}  {r['desc']}")
+        for tag in r["tags"]:
+            print(f"                [{tag}]")
+    best = ranked[0]
+    print(f"\n  realize the pick:")
+    print(f"    quantprobe {REALIZE.get(best['bits'], 'quantize')}")
+    print(f"    quantprobe run --gguf <the file> ...   # launches with: {best['flags']}")
+    print("\n  (search over the validated law only - no new physics; quality = depth-aware recipe,")
+    print("   uniform quantization costs ~1.3x more at <=2.5 bits. Estimates +/-25%.)")
+    return ranked

{quantprobe-1.3.0 → quantprobe-1.4.0}/quantprobe/plan.py

@@ -204,5 +204,24 @@ def run(args):
     if c2[0][1] > best[1] * 1.08: alts.append(("NVMe SSD", c2[0][1]))
     if alts:
         print("  upgrade advisor: " + " | ".join(f"{n} -> ~{v:.1f} tok/s" for n, v in alts))
+    # tier-boundary advisor: the biggest cliffs sit at tier boundaries (REAP finding, pre-reg #8 P-c).
+    # If a modest shave of the FILE crosses one, say so and price it.
+    kvg = ctx * kvp / 1e9 if ctx > 0 else 0.0
+    size_now = size
+    for tier_name, cap, lever in (("VRAM (all-in-VRAM)", vc * 0.90, "next quant step down / tighter probed band / pruned variant"),
+                                  ("RAM (pure-CPU)", max(rc - 4, 1), "next quant step down / tighter probed band")):
+        if cap <= 0 or size_now + kvg <= cap:
+            continue
+        gap = size_now + kvg - cap
+        if gap > size_now * 0.30:
+            continue                                   # not a "shave" - a different model class
+        fit_scale = max(0.05, (cap - kvg) / size_now) * 0.995
+        _, _, c9 = evaluate(t, a, ne, moe, args.bits, vc, vb, rc, rb, db, geta, fit_scale, gl,
+                            ctx=ctx, kvp=kvp)
+        promoted = [x for x in c9 if x[0].startswith("all in VRAM")] if "VRAM" in tier_name else                    [x for x in c9 if x[0].startswith("pure CPU")]
+        if promoted and promoted[0][1] > best[1] * 1.15:
+            print(f"  tier-boundary advisor: this config is {gap:.1f} GB over the {tier_name} boundary - "
+                  f"shave it ({lever}) -> ~{promoted[0][1]:.1f} tok/s (x{promoted[0][1]/best[1]:.1f})")
+        break                                          # nearest boundary only
     print("\n  (eta bands fitted from published measurements; estimates +/-25%. "
           "Hybrid needs --no-mmap.)")

quantprobe-1.4.0/quantprobe.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: quantprobe
+Version: 1.4.0
+Summary: Probe-then-quantize for LLMs: measure a model's fragility curve, plan bit/tier placement by the tiered decode law, and emit ready-to-run llama.cpp recipes.
+Author: Federico Sciuca
+License: MIT
+Project-URL: Homepage, https://github.com/FedericoTs/quantprobe
+Keywords: llm,quantization,llama.cpp,gguf,inference,moe
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gguf>=0.9
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# quantprobe
+
+### Placement beats budget
+
+**Where your bits sit — which layers, which memory tier — matters more than how many you have. Four falsification-tested laws for running big LLMs on hardware you already own, every number measured on one 2016 desktop (GTX 1060 6 GB · 16 GB DDR4 · SATA SSD).**
+
+![smoke](https://github.com/FedericoTs/quantprobe/actions/workflows/smoke.yml/badge.svg) ![license](https://img.shields.io/badge/license-MIT-0f766e) ![hardware](https://img.shields.io/badge/measured_on-2016_GTX_1060_6GB-d73027) ![data--free](https://img.shields.io/badge/quantization-data--free-1d9e70) ![models](https://img.shields.io/badge/validated-7B_→_744B-378add) [![x](https://img.shields.io/badge/author-@federico__sciuca-14181f)](https://x.com/federico_sciuca)
+
+<p align="center"><img src="weights/data/hero_placement.png" width="880" alt="Placement across memory tiers: disk 2-bit cold experts, RAM 2-bit experts + probed fragile band at 4-bit, VRAM 4-bit attention — one law ties them"></p>
+
+> **▶ Try the interactive calculator: [Will it run — and how fast?](https://federicots.github.io/quantprobe/)**
+> Pick any model + your machine → predicted tok/s, memory fit, quality cost, and your cheapest next upgrade — from the law below, with your config plotted against every validated measurement.
+
+
+**New here? → [QUICKSTART.md](QUICKSTART.md) gets you running in 60 seconds.** Two tiers: `plan`/`target` and the web calculator need *nothing* installed; `quantize`/`probe`/`run`/`bench`/`dashboard` drive [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point quantprobe at it with `--llama-dir`, `QUANTPROBE_LLAMA_DIR`, or `PATH`). Preview any command without llama.cpp using `--dry`. 16 machine presets ship in (`--machine`): GTX 1060 → RTX 5090, Apple `mac-m2/m3/m4-*`, DGX Spark, Epyc — or pass raw specs. Multi-GPU / RAID? Comma lists aggregate: `--vram 24,24 --disk-bw 14,14`. Big-VRAM + disk-streaming rigs get the three-tier expert-cache row (v1.3).
+
+
+---
+
+## What this is
+
+My 2016 desktop can't run frontier models the way a datacenter does — so instead of brute force, I asked *where* every bit and byte should go, and answered it by measurement. Months of experiments later, the result is four laws, a 30-minute probe tool, copy-paste llama.cpp recipes, and one equation that predicts decode speed from 7B to 744B — validated against my own pre-registered predictions and against [colibri](https://github.com/JustVugg/colibri)'s independently published 744B numbers.
+
+## Headline results
+
+| result | number |
+|---|---|
+| 16B MoE, 2-bit, **data-free**, resident on a 6 GB card | ppl 6.31 → 6.96 (**1.10×**) — beats calibrated SOTA's gap-ratio |
+| Same bytes, different layers (Gemma 4 12B, stock llama.cpp) | **byte-identical files, 2.25 ppl apart** (12.27 vs 10.02) |
+| Gemma 4 12B depth-aware 2-bit | 1.91× → **1.45×** quality cost, ~4.5 GB resident |
+| Qwen3-30B-A3B on the 2016 desktop | **19.3 tok/s** — hybrid placement, *predicted 19 before measuring* |
+| GLM-4.5-Air **110B** from a SATA drive, 16 GB RAM | 0.19 tok/s — inside the law's pre-registered 0.2–0.3 band |
+| RAM overclock (XMP, 2133→3000) | dense **+52%**, pre-registered ×1.41+ |
+
+## Why the evidence is unusually strong
+
+Most benchmark posts report what happened. I report what I **predicted before it happened** — I wrote the number down, then ran the hardware, and this is the strongest form of empirical evidence I know how to produce:
+
+| prediction (made first) | measured (after) |
+|---|---|
+| 110B streamed from SATA: **0.2–0.3 tok/s** | **0.19** |
+| RAM overclock scales in-RAM decode **×1.41+** | **×1.52** |
+| 30B hybrid placement: **~19 tok/s** | **19.30 ± 0.88** |
+| a day-old 118B (Laguna S 2.1) streamed from this SATA drive: **0.2–0.4** ([staked pre-download](preregistrations/2026-07-23-laguna-s-2.1-on-2016-desktop.md)) | **0.38 ± 0.17** |
+| colibri's own 128 GB / 25 GB tiers, from our η bands | land **inside** the bands |
+
+Add to that: a **byte-identical control** (two GGUFs the same size, 2.25 ppl apart — only placement differs), a full **claim → script → log manifest** (every number reproducible in-tree), and a set of **documented dead ends** (dynamic top-k, semantic paging, self-speculation — all measured-dead, because a law you only confirm is a law you haven't tested).
+
+<p align="center"><img src="weights/data/validation_19tok/live_run_20tps.png" width="880" alt="One frame: Task Manager showing 16 GB DDR4-3000 and the GTX 1060 6GB beside llama.cpp chatting Qwen3-30B-A3B live at 20.4 tok/s generation"></p>
+<p align="center"><em>One frame, no cuts: Task Manager (16 GB @ 3000 MT/s, GTX 1060 6 GB, RAM at 91% — the hybrid placement using the whole machine) beside llama.cpp chatting Qwen3-30B-A3B at <b>20.4 tok/s generation</b> — above the pre-registered 19. Raw logs, hardware attestation + GGUF SHA256: <a href="weights/data/validation_19tok/EVIDENCE.txt">EVIDENCE.txt</a>. Third bench run: 19.26 ± 0.45 (series 19.30 → 19.55 → 19.26).</em></p>
+
+**Open pre-registrations** — predictions staked publicly *before* measurement: [colibri v1.1, five falsifiable predictions (2026-07-23)](preregistrations/2026-07-23-colibri-v1.1.md) — dual-SSD scaling, int3 speedup, lattice-vs-scalar, AVX-512 tier-scoping, MTP×MoE antagonism.
+
+
+## The four placement laws
+
+Full statements, each with its establishing measurement and a falsifiable prediction, in **[LAWS.md](LAWS.md)**.
+
+1. **Rotation is rank-conditional.** Incoherence rotation (QuIP#/QTIP/QuaRot) helps full-rank tensors (+0.006 ppl) and destroys low-rank bottlenecks (+1623 ppl) — a ~270,000× swing on effective rank alone.
+2. **Trained networks are dense everywhere.** Experts sit *exactly* at the rate-distortion floor; routing is flat (even across domains — Jaccard 1.00 prose vs code); activations are diffuse. **2-bit is the floor.**
+3. **Fragility is measurable, not predictable.** Gemma late-fragile 4×, Mistral **early-fragile 25×** — architectural near-twins pointing opposite ways. Weight statistics mislead. **Only a 30-minute functional probe decides.**
+4. **The tiered decode law.** `tok/s = η(tier)·BW ÷ active-bytes`, η collapsing per tier across 7B→744B and both projects' hardware. **v1.1 adds the context term**: each generated token also re-reads the whole KV cache from *its* tier — `--ctx` prices it, `bench --depth` measures it (measured here: 20.02 → 16.12 tok/s at 16k depth).
+
+<p align="center"><img src="weights/data/x_chart_E_scalinglaw.png" width="700" alt="One scaling law, 7B to 744B, predicted vs measured, including colibri's published tiers"></p>
+
+<p align="center"><img src="weights/data/x_chart_D_placement.png" width="700" alt="Byte-identical GGUF files, 2.25 perplexity apart — placement is worth twice the byte budget"></p>
+<p align="center"><img src="weights/data/x_chart_I_kvdepth.png" width="700" alt="Decode speed versus context depth: measured 20.02 tok/s at depth zero falling to 16.12 at 16384, on the Law 4 v2 curve with eta_kv 0.70"></p>
+
+
+## Install — and the ten commands
+
+```bash
+pip install quantprobe
+```
+
+**Zero-config on your own box**: `quantprobe plan --gguf model.gguf` auto-detects the machine and reads the model from the file. Presets/flags estimate any *other* machine. `hw`/`plan`/`target`/`optimize` need nothing else installed; the rest drive stock [llama.cpp](https://github.com/ggml-org/llama.cpp/releases) (point at it with `--llama-dir`/`QUANTPROBE_LLAMA_DIR`/`PATH`; preview any command with `--dry`).
+
+```bash
+quantprobe hw                                            # what the law sees on THIS machine (every value source-tagged)
+quantprobe plan     --gguf model.gguf                    # zero-config prediction: placement + tok/s + the launch command
+quantprobe optimize --tps 20                             # CHEAPEST PATH to a target: bits x placement x hardware, Pareto-ranked
+quantprobe target   --tps 5 --machine gaming --ladder    # inverse: target -> smartest model + speed-intelligence ladder
+quantprobe fetch    qwen3-30b ./models                   # robust, resumable download
+quantprobe quantize --gguf f16.gguf --out 2bit.gguf      # COMPRESS: depth-aware ~2-bit GGUF (verified: loads + generates)
+quantprobe probe    --gguf f16.gguf --eval wiki.test.raw # measure YOUR model's fragile band (~30 min); --apply builds it
+quantprobe run      --gguf 2bit.gguf                     # plan the placement, then LAUNCH llama.cpp chat
+quantprobe bench    --gguf 2bit.gguf --contribute        # predicted vs measured on your box; opt-in datapoint
+quantprobe dashboard --gguf 2bit.gguf                    # chat while every reply is scored against the prediction
+```
+
+The loop is self-validating: `plan` predicted 17.5 for a file we then measured at **18.32 ± 0.17**; the config months of research converged to is what `optimize` picks blind. A measured example of what that's worth: the same model, mis-specified vs law-routed, is **3.38 vs 18.32 tok/s (×5.4)** — [worked examples](docs/EXAMPLES.md).
+
+## Help grow the law
+
+`quantprobe bench --contribute` prints exactly what would be shared (hardware label, model, predicted-vs-measured) plus a pre-filled issue link — **you review and submit; nothing is ever sent automatically**. Contributed points land on the law chart; the ones *outside* the bands are the most valuable. Open falsifiable predictions anyone can settle: [preregistrations/](preregistrations/).
+
+## Deep dives
+
+| | |
+|---|---|
+| [QUICKSTART.md](QUICKSTART.md) | 60-second start, three levels; Ollama interop; llama.cpp version notes |
+| [LAWS.md](LAWS.md) | the four laws — statements, measurements, falsifiable predictions, the general form |
+| [docs/EXAMPLES.md](docs/EXAMPLES.md) | worked examples with real outputs: zero-config, the ×5.4 optimizer A/B, probe walkthrough, troubleshooting |
+| [docs/HARDWARE.md](docs/HARDWARE.md) | the 2016 box: exact specs, measured bandwidths, what the next euro buys |
+| [docs/DEEP-DIVE.md](docs/DEEP-DIVE.md) | what's new vs. what's built-on, parity tables, the 744B-at-home projection, repository map |
+| [preregistrations/](preregistrations/) | every staked prediction with its verdict — hits, the near-miss, and the honest miss |
+| [papers/arxiv/](papers/arxiv/) | the paper (submission-ready LaTeX) |
+| [CHANGELOG.md](CHANGELOG.md) | v1.0 → v1.4, every release |
+
+## Honest limitations
+
+- Perplexity on WikiText-2 is my primary metric; I haven't run task-level evals (MMLU/HellaSwag) yet.
+- My fragility atlas covers four model families — enough to *disprove* universality, not to chart every architecture.
+- 0.19 tok/s for a 110B is a **capacity demonstration, not usable inference** — the honest speed only arrives with faster storage.
+- Speed numbers are single-stream decode on one machine (±25% across environments); the tiered-decode η values are fitted, not derived.
+- No custom runtime: everything rides stock llama.cpp and streaming eval harnesses. The one CUDA kernel is verified in reference, not built.
+
+
+## Credits
+
+[colibri](https://github.com/JustVugg/colibri) (744B on 25 GB, pure C) inspired the tier-streaming exploration. The quantization stack builds on [llama.cpp](https://github.com/ggml-org/llama.cpp) and the QTIP/QuIP# incoherence codecs — whose central tool our first law bounds. Independent research by Federico Sciuca, AI-supported, on one desktop; every claim is measured, and every negative that redirected the work is documented. The Law 4 context term (v1.1) was prompted by **u/RogerAI--fyi** (Reddit), who correctly observed the original formulation omitted per-token KV reads — measured, confirmed, and shipped within a day.
+
+## License
+
+MIT — see [LICENSE](LICENSE). © 2026 Federico Sciuca.