card: bigsmall 4.0.0 - autopilot + Ferrell Duo

README.md

@@ -1,15 +1,11 @@
----
-title: README
-emoji: "🗜"
-colorFrom: gray
-colorTo: blue
-sdk: static
-pinned: false
----
+> **DRAFT — DO NOT UPLOAD.** Strip this block before publishing. Publishes at V4-REL on Will's
+> word (V4_DOCS_SPEC.md Deliverable 8/9). Every number is traced in V4_DOCS_REPORT.md appendix A
+> (claims ledger). Supersedes _v315/PUBLIC_DRAFTS/hf_card_README.md (the "Coming in 3.15" block
+> there is obsolete — 3.15 shipped 2026-06-11, and this card is the 4.0 story).
 
 # BigSmall — Lossless AI Model Compression
 
-**Make any AI model ~34% smaller. Bit-identical weights. Drop-in replacement for `from_pretrained`.**
+**Lossless AI model compression — ~34% smaller with bit-identical weights; the autopilot profiles your machine, picks the highest fidelity that runs, and streams models bigger than your RAM.**
 
 ```bash
 pip install bigsmall          # CLI + compression/decompression
@@ -23,9 +19,9 @@ identical to the original** (md5 verified per tensor on decompress).
 - **Not quantization.** Nothing is rounded; the model's behaviour cannot change.
 - **Not pruning, not approximation.** The same idea as ZIP for text, tuned for the statistics
   of trained BF16 weights.
-- **Fine-tunes ship as deltas.** A ≥7B official instruct tune stored against its public base
+- **Fine-tunes ship as deltas.** A >=7B official instruct tune stored against its public base
   measures 34–50% of the full model. Delta size is pair-dependent (measured range: under 1% for
-  the best ≥7B SFT pairs, up to ~61% for small-model full tunes) — the docs carry the full
+  the best >=7B SFT pairs, up to ~61% for small-model full tunes) — the docs carry the full
   measured table.
 
 ## Using a pre-compressed model
@@ -41,32 +37,49 @@ model = AutoModelForCausalLM.from_pretrained(
 BigSmall decompresses transparently on load. Prefer the CLI? Download the repo and run
 `bigsmall decompress model-00001-of-00002.bs -o model.safetensors`.
 
+## New in 4.0 — the autopilot release
+
+Three commands replace every settings decision:
+
+```bash
+bigsmall profile     # once: ~10s hardware probe (GPU read via NVML only, never touched)
+bigsmall plan f.bs   # one sentence: what would run, where, how faithfully, how fast
+bigsmall run f.bs    # do it
+```
+
+The rule is *highest fidelity at usable speed*, and the honesty rules are enforced by the test
+suite: anything below bit-exact is announced before it happens, never silently.
+
+- **The Ferrell Duo (`.bsd`)** — one file. Two models: the fast one and the real one. A
+  lossy-INT4 fast member (load by reading ~21% of raw bytes) *and* the lossless residual that
+  reconstructs the original bits; the bit-exact gate runs before the file may exist. Measured
+  cost: ~2.9 pp of raw over lossless-only. To our knowledge (as of 2026-06-12) the only shipped
+  LLM-weights format whose top tier is the bit-exact original — adjacent art (MatQuant,
+  Any-Precision LLM, audio hybrid formats) credited in the repo's comparison page.
+- **Streaming executor** — run models bigger than your RAM with a bounded, promised, measured
+  resident set. Receipt at 7B: Qwen2.5-7B (14.2 GB raw, 65.95% compressed) streamed forward
+  **bit-exact** vs the fully-loaded model (identical logits sha256) in ~2.5 GB of hot state.
+- **FP8-native lossless** — a real fp8 release (Qwen3-0.6B-FP8) compressed to **0.829 of its
+  fp8 weight bytes**, 507/507 tensors bit-exact.
+- **`bigsmall xray`** — checkpoint forensics with a "looks untrained" trap that catches
+  silently-randomized loads; works on bf16 and fp8.
+
 ## Honest numbers
 
 The lossless floor for trained BF16 weights is real and measured: across 4,143 weight matrices
-in 8 architectures the per-tensor entropy floor is flat (CV ≈ 0), and trained mantissa/sign bits
+in 8 architectures the per-tensor entropy floor is flat (CV ~ 0), and trained mantissa/sign bits
 are coder-equivalent to matched random controls — training only writes the exponent. BigSmall
 codes at that wall. Head-to-head under the same accounting, BigSmall codes below DFloat11's
 bound on **every layer type of every model measured** (+0.45–0.55 pp model-level, +12–18 pp on
-norm scales) — see `docs/dfloat11.md` in the source repo.
-
-## New in 3.15.0
-
-- Fail-safe delta engine: both codings measured per tensor, a delta can never come out larger
-  than standalone.
-- KV cache entry format v3: per-depth sequential dispatcher (end-to-end wins grow with context,
-  0.27% → 0.58% at ≤2048 tokens; up to +7.7% on early-layer K), plus FP8 entries, 32k+ chunked
-  streaming entries, and device-routing `AutoKVCache`. v1/v2 entries decode forever.
-- `bigsmall xray`: checkpoint forensics — per-tensor substream entropies vs a matched-random
-  control, lineage/anomaly flags, and a "looks untrained" detector that catches
-  silently-randomized checkpoints.
-- Opt-in role-group stream packing for small same-role tensors.
+norm scales) — see `docs/dfloat11.md` in the source repo; the full landscape (DFloat11, ZipNN,
+ZipServ, Unweight, quantization, and the rest) is one honest page at `docs/comparison.md`.
 
 ## Links
 
 - **PyPI** — https://pypi.org/project/bigsmall/
 - **Source** — https://github.com/wpferrell/Bigsmall
 - **Paper / DOI** — https://doi.org/10.5281/zenodo.20279247
+- **Ferrell Duo paper** — https://doi.org/10.5281/zenodo.20673133 (the dual-fidelity format: method, premium history, receipts)
 - **License** — Elastic License 2.0 (free for personal, research, and internal commercial use);
   model weights in `.bs` format keep the license of the original model.
 - **Contact** — wpferrell@gmail.com