Doc-style delta bars in radar; reorder sections to Mini structure; condense training detail

README.md

@@ -10,7 +10,6 @@ tags:
 - smaug
 - abacusai
 ---
-
 <div align="center">
   <picture>
       <img src="https://cdn-avatars.huggingface.co/v1/production/uploads/63128dd099791aa61d180c72/dJ6uR23m09M-YEafBpmea.png" width="20%" alt="Smaug-Flash">
@@ -29,198 +28,59 @@ tags:
 
 **Abacus.AI** · August 2026
 
-Smaug-Flash is an agentic-coding finetune of [DeepSeek-V4-Flash-0731](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731). It improves
-end-to-end agentic performance by a wide margin (+14.3 on LiveBench
-agentic-coding, +5.6 on Terminal Bench 2.1 under the DeepSeek Harness, +9.6 on
-AutomationBench, +19 on NL2Repo-Bench) while holding the base model's general
-capabilities at parity (overall LiveBench +3.4). The weights load exactly like
-the official release: same layout, same quantization formats, same context
-length (1M), same reasoning interface.
-
-This report describes the training methodology, the data curation and mining
-techniques, and the architecture-specific weight-merging procedure. Dataset
-contents are not disclosed; all training data consists of **curated agentic
-loop traces from various sources — public repositories and traces synthesized
-from agentic product use cases** — plus programmatically generated and
-verified instruction-following tasks.
+Smaug-Flash is an agentic-coding finetune of [DeepSeek-V4-Flash-0731](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731). It improves end-to-end agentic performance by a wide margin (+14.3 on LiveBench agentic-coding, +5.6 on Terminal Bench 2.1 under the DeepSeek Harness, +9.6 on AutomationBench, +19 on NL2Repo-Bench) while holding the base model's general capabilities at parity (overall LiveBench +3.4). The weights load exactly like the official release: same layout, same quantization formats, same context length (1M), same reasoning interface.
+
+This card describes the training approach and the evaluation results. Dataset contents are not disclosed; training data consists of curated agentic loop traces from various sources — public repositories and traces synthesized from agentic product use cases — plus programmatically generated and verified instruction-following tasks.
 
 ---
 
 ## 1. Training regime: match the serving regime
 
-A central thesis of this work, validated repeatedly during development:
-**finetune in exactly the regime the model will be served in.** For a
-reasoning-first agentic model this means:
-
-- Multi-turn agentic episodes in the model's native request format (Responses
-  API semantics), with tool schemas, tool results, and interleaved reasoning
-  present in context exactly as at inference time.
-- Maximum reasoning effort during data generation and evaluation.
-- **Reasoning tokens loss-masked everywhere.** Gradients flow only through
-  action tokens (tool calls) and user-visible message content — never through
-  chain-of-thought. This preserves the base model's reasoning distribution
-  while steering its actions.
-
-Deviating from this (training on single-turn reformattings, letting loss touch
-reasoning, or sampling training data at a different effort level) consistently
-produced checkpoints that benchmarked well in mismatched harnesses and
-regressed in the real serving path.
-
-## 2. Training stages
-
-Smaug-Flash is the composition of three LoRA adapters trained in sequence, each
-with a distinct objective, merged as full deltas (§4).
-
-### 2.1 Agentic SFT: teacher-agreement action cloning + verified self-distillation
-
-The backbone adapter. Two complementary supervision sources over curated
-agentic loop traces:
-
-1. **Teacher-agreement action cloning.** At each decision point of a trace, the
-   base model produces its own on-policy reasoning; the supervised target is
-   the action a stronger teacher took *when independent signals agree the
-   action was correct*. Cloning actions (not reasoning) on top of on-policy
-   thinking avoids the distribution shift of imitating a foreign model's
-   chain-of-thought.
-2. **Verified-correct self-distillation.** The model's own rollouts on tasks
-   with programmatic verifiers, filtered to verifier-passing episodes only —
-   outcome-gated, never outcome-blind.
-
-A hard negative result worth reporting: self-distillation on *retired*
-generations of evolving benchmarks transferred to retired-style questions but
-not to fresh ones. Any gate built on retired data over-reads models trained on
-it. All quality gates in this program use fresh, held-out task generations.
-
-### 2.2 Preference stage: decision-point KTO on minimal pairs
-
-A small KTO adapter (~10² preference pairs — dataset efficiency comes from
-construction quality, not scale) targeting failure modes that SFT alone did not
-fix: perseveration loops, premature finalization, and degenerate emissions in
-long agentic episodes.
-
-Key techniques (§3 details the mining):
-
-- **Minimal-pair construction.** POS/NEG in a pair share the identical context
-  and differ *only* in the target behavior (e.g. escaping vs. repeating a
-  loop; finalizing with vs. without evidence of completed work). The gradient
-  then carries the behavioral contrast and nothing else.
-- **Loss on the action row only.** As in SFT, preference loss attaches to the
-  tool-call/decision tokens.
-- **Evidence-conditioned finalization.** "Finish the task" is only a positive
-  when the context contains evidence the work is complete; finalization
-  without evidence is a negative. Teaching unconditional finalization measurably
-  causes premature submits.
-- **Dose–response is non-monotone.** Checkpoint selection across KTO training
-  steps was gated per-behavior; the mildest checkpoint was not the safest.
-
-### 2.3 Targeted repair SFT on the merged model
-
-Constrained instruction-following (exact word counts, keyword placement,
-format contracts) degrades slightly under agentic SFT. A third adapter repairs
-it: tasks are **generated programmatically from a constraint registry with
-jittered parameters and checked by exact verifiers**; training targets are
-teacher rolls that pass verification.
-
-Critically, this adapter is trained **on the already-merged agentic model**,
-not on the base. Trained separately and stacked in weight space, its benefit
-is destroyed by cross-adapter interference; trained on the merge, it composes
-(+3–8 points instruction-following, agentic gains intact).
-
-## 3. Data curation and mining techniques
-
-The mining pipeline turns raw agentic traces into decision-point training data.
-The techniques below are dataset-agnostic and, in our experience, where nearly
-all of the quality lives.
-
-**Decision-point truncation and on-policy resampling.** Long traces are
-truncated at behaviorally interesting trigger points (an opaque tool result, an
-empty result, a repeat-primed context, a completion point). The model being
-trained is resampled k times at each truncation point; its own behavioral
-distribution at that decision — not the original trace's continuation — is
-what gets labeled.
-
-**Single-decision labeling.** Labels attach to one decision (repeat = negative,
-escape/progress = positive; finalize-with-evidence = positive,
-finalize-without = negative), with automated labelers audited by hand.
-Trajectory-level labels are too coarse; they smear credit across dozens of
-correct actions to reach one wrong one.
-
-**Depth-escalation mining.** Failure probability at a decision point rises
-steeply with the depth of prior repetition (in our measurements, from
-single-digit percentages at depth 1 to 50–80% at depth 3). Escalated contexts —
-the model's own repeated action and its replayed result appended, then
-resampled — are the richest source of both hard negatives and gold escapes.
-Single-shot sampling at natural contexts under-elicits the pathology.
-
-**Anti-confound lints (the difference between a fix and a new regression):**
-
-- *Length matching.* Preference optimization's cheapest gradient is "long
-  completions are bad." If negatives are systematically longer than positives
-  (e.g. truncated mid-generation), the model learns to avoid long emissions —
-  which in an agentic product means avoiding exactly the file-writing and
-  deployment turns that finish a task. All pairs are length-linted.
-- *Degeneracy filters.* High-scoring but degenerate completions (repetitive
-  filler around a correct answer) are excluded from positives.
-- *Format-mass balance.* Required output markers (answer wrappers, artifact
-  emissions) must appear with at least as much probability mass in positives
-  as negatives, or the model learns to drop the format itself.
-- *No anti-format gradients, ever.* Negatives never consist of "the right
-  answer in the right format, penalized for another reason."
-
-**Capability anchors.** Every preference run mixes in regenerated on-policy
-traces of the capabilities being protected (agentic episodes, math, reasoning),
-so the adapter's gradient has an explicit "do not move" component. Anchor
-weight is a first-class hyperparameter.
-
-**Hygiene.** Evaluation fixtures and live benchmark questions are excluded from
-mining pools by construction; held-out probe sets are never trained on;
-training-data canaries in third-party benchmarks are respected.
-
-## 4. Architecture-specific weight merging
-
-DeepSeek-V4-Flash ships with a heterogeneous quantization layout: attention
-matrices in block-FP8 (e4m3 values, e8m0 scales, 128×128 blocks), routed
-experts packed in FP4, plus a speculative-decoding module. Naive handling of
-this layout silently destroys the model. Our merging procedure:
-
-1. **Adapt only the MLA attention factor matrices** (the low-rank query/output
-   projection factors; 129 matrices total). Experts, router, embeddings, and
-   the speculative module are never touched — they remain byte-identical to
-   the official release, packed FP4 included.
-2. **Full-delta composition.** Each adapter's contribution is applied as its
-   complete ΔW = s·BA at trained scale, adapters summed in sequence order —
-   **no SVD re-factorization, no rank truncation**. We measured rank
-   truncation directly: combining three adapters (aggregate rank ~192) into a
-   rank-64 addon cost several points across coding and reasoning; rank-128
-   recovered most but not all. Truncation is not free; full deltas are.
-3. **Surgical requantization.** Touched matrices are dequantized to bf16,
-   deltas added, then requantized to the *checkpoint-native* format (e4m3
-   values, e8m0 per-block scales recomputed per 128×128 block). Round-trip
-   relative error ≈ 3×10⁻³ per matrix. Every untouched tensor is copied
-   byte-for-byte.
-4. **Serve in the native format.** Re-quantizing merged weights into a
-   different scheme (e.g. per-32-element MXFP8 at load time) measurably
-   degrades precision-sensitive behavior — in our measurements, up to ~10
-   points of instruction-following at identical weights, scaling with adapter
-   delta mass. Coarse capabilities are insensitive; constrained writing is
-   not. If your serving stack requantizes on load, benchmark against a
-   native-format reference before trusting any number.
-
-A corollary we relied on throughout: because only attention matrices change,
-any serving stack that runs the official release runs Smaug-Flash unmodified —
-including FP4 expert kernels and speculative decoding paths.
-
-## 5. Serving recommendations
-
-- SGLang ≥ 0.5.15 on Blackwell: tp=4/8 with `--enable-dp-attention`,
-  `--moe-runner-backend flashinfer_mxfp4` (required for the packed-FP4
-  experts), fp8 KV cache, full 1M context.
-- Reasoning effort **max**; sampling temperature 1.0, top-p 0.95.
-- For agentic harnesses, note that wall-clock task budgets are effectively
-  *inference-compute* budgets: serving throughput changes measured scores on
-  timeout-bounded benchmarks. Benchmark on serving comparable to what you
-  deploy.
+Smaug-Flash follows the same central thesis as our other Smaug releases: **finetune in exactly the regime the model will be served in.** For this model that means multi-turn agentic episodes in the model's native request format (Responses API semantics) — tool schemas, tool results, and interleaved reasoning present in context exactly as at inference time — generated and evaluated at maximum reasoning effort, with **reasoning tokens loss-masked everywhere**: gradients flow only through action tokens (tool calls) and user-visible message content, never through chain-of-thought, preserving the base model's reasoning distribution while steering its actions.
+
+## 2. Training method
+
+Smaug-Flash is the composition of three LoRA adapters trained in sequence and merged as full deltas: an **agentic SFT** backbone (teacher-agreement action cloning on top of the model's own on-policy reasoning, plus self-distillation of verifier-passing rollouts), a small **decision-point KTO** stage on minimal pairs targeting perseveration loops and premature finalization, and a **targeted repair SFT** for constrained instruction-following, trained on the already-merged model. Training data is mined at decision points with on-policy resampling and single-decision labels, with anti-confound lints (length matching, format-mass balance) and capability anchors protecting base skills; evaluation fixtures and live benchmark questions are excluded from mining pools by construction.
+
+Only the MLA attention factor matrices (129 in total) are adapted; experts, router, embeddings, and the speculative-decoding module remain byte-identical to the official release, packed FP4 included. Adapter deltas are applied in full (no rank truncation) and touched matrices are requantized to the checkpoint-native block-FP8 format. Because only attention changes, any serving stack that runs the official release runs Smaug-Flash unmodified — FP4 expert kernels and speculative decoding paths included. One caution: serve in the checkpoint-native format; requantizing merged weights into a different scheme at load time measurably degrades constrained instruction-following.
+
+## 3. Evaluation
+
+Measured on fresh 2026 task generations, self-served under the recipe in §5 (agentic cells via the benchmarks' public harnesses), with the base model run through identical harnesses for every paired comparison.
+
+### Smaug-Flash vs its base
+
+*Higher is better. Paired runs under the same harness; starred base scores are vendor-reported references for the identical public task set. The AA-LCR difference is within run noise.*
+
+<div align="center">
+  <img src="figures/smaug_flash_vs_base.png" width="100%" alt="Smaug-Flash vs DeepSeek-V4-Flash-0731 across agentic benchmarks">
+</div>
+
+### LiveBench category profile
+
+*Scores 0–100; overall = mean of the seven category averages. Same harness, same questions (LiveBench 2026-06-25 release), paired against the base model.*
+
+<div align="center">
+  <img src="figures/smaug_flash_livebench_categories.png" width="100%" alt="Smaug-Flash LiveBench category profile vs base">
+</div>
+
+Terminal Bench 2.1 (terminus-2) remeasured 2026-09-02 on the dedicated FP8 Fireworks deployment: 89 tasks, temperature 1.0, top_p 0.95, reasoning_effort max, 32768-token per-step cap, interleaved thinking (reasoning_content carried across steps). 62/89 = 69.7 at uniform 1× task timeouts; the 9 timed-out tasks rerun at 3× timeout converted exactly one, giving the reported 63/89 = 70.8. Supersedes the earlier 65.9 (pre-interleaved-thinking serving).
+
+DeepSWE v1.1 measured 2026-09-02 on the official leaderboard protocol (datacurve-pier 0.3.1 driving stock mini-swe-agent 2.4.6, native tool calling): full 113-task corpus, temperature 1.0, top_p 0.95, reasoning_effort max, 65536-token per-step cap, no step limit; 64/113 = 56.6, zero harness errors (the single verifier timeout is a model-induced test hang, counted as a fail). Smaug-Flash served in checkpoint-native FP8 on a dedicated Fireworks deployment.
+
+AA-LCR (Artificial Analysis Long Context Reasoning) measured 2026-09-01: temperature 1.0, top_p 1.0 (non-agentic regime), reasoning_effort max, 65536-token output cap, pinned LLM judge; 3 runs (Smaug-Flash) vs 2 runs (base), run-to-run spread ±2 points; both models served in checkpoint-native FP8 on Fireworks (dedicated vs serverless).
+
+Reproducibility notes, in the spirit of honest reporting: vendor-published agent-benchmark numbers are frequently not reproducible under released harnesses (we could not reproduce the base model's published Terminal Bench 2.1 score with either public scaffold, from either of two serving providers); paired same-harness comparisons are the only numbers we consider load-bearing. Cross-scaffold analysis of all four Terminal Bench runs shows **zero tasks where Smaug-Flash robustly regresses** from base under both scaffolds.
+
+## 4. Known behaviors and limitations
+
+Smaug-Flash is more decisive than its base: it finishes tasks in fewer, denser turns and submits sooner. Under tight wall-clock budgets this is an asset (it wins several timeout-bound tasks the base loses); under hidden-test grading it can submit at ~98% spec coverage without spending remaining budget on self-verification. If your use case rewards exhaustive verification over decisiveness, prompt for explicit self-testing before completion. Improving autonomous verification discipline is the focus of our next training round.
 
+## 5. Deployment
+
+- SGLang ≥ 0.5.15 on Blackwell: tp=4/8 with `--enable-dp-attention`, `--moe-runner-backend flashinfer_mxfp4` (required for the packed-FP4 experts), fp8 KV cache, full 1M context.
+- Reasoning effort **max**; sampling temperature 1.0, top-p 0.95.
+- For agentic harnesses, note that wall-clock task budgets are effectively *inference-compute* budgets: serving throughput changes measured scores on timeout-bounded benchmarks. Benchmark on serving comparable to what you deploy.
 
 ### Chat template and encoding
 
@@ -244,7 +104,7 @@ tokens = tokenizer.encode(prompt)
 
 ### Running with vLLM
 
-Because only attention matrices differ from the official release (§4), any stack that serves DeepSeek-V4-Flash-0731 serves Smaug-Flash unmodified, DSpark speculative decoding included. Example, single 4×GB300 node (see the base model's [vLLM recipe](https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash?hardware=b300&features=tool_calling,reasoning) for other hardware):
+Because only attention matrices differ from the official release (§2), any stack that serves DeepSeek-V4-Flash-0731 serves Smaug-Flash unmodified, DSpark speculative decoding included. Example, single 4×GB300 node (see the base model's [vLLM recipe](https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash?hardware=b300&features=tool_calling,reasoning) for other hardware):
 
 ```bash
 vllm serve abacusai/Smaug-Flash \
@@ -271,57 +131,11 @@ sglang serve \
 
 For the `high` and `max` reasoning effort levels we recommend a maximum output length of **384K** tokens. Local weight conversion and interactive demos: see the [`inference`](inference/README.md) folder.
 
-## 6. Evaluation
-
-Measured on fresh 2026 task generations, self-served under the recipe above
-(agentic cells via the benchmarks' public harnesses), with the base model run
-through identical harnesses for every paired comparison.
-
-### Smaug-Flash vs its base
-
-*Higher is better. Paired runs under the same harness; starred base scores are vendor-reported references for the identical public task set. The AA-LCR difference is within run noise.*
-
-<div align="center">
-  <img src="figures/smaug_flash_vs_base.png" width="100%" alt="Smaug-Flash vs DeepSeek-V4-Flash-0731 across agentic benchmarks">
-</div>
-
-### LiveBench category profile
-
-*Scores 0–100; overall = mean of the seven category averages. Same harness, same questions (LiveBench 2026-06-25 release), paired against the base model.*
-
-<div align="center">
-  <img src="figures/smaug_flash_livebench_categories.png" width="100%" alt="Smaug-Flash LiveBench category profile vs base">
-</div>
-
-Terminal Bench 2.1 (terminus-2) remeasured 2026-09-02 on the dedicated FP8 Fireworks deployment: 89 tasks, temperature 1.0, top_p 0.95, reasoning_effort max, 32768-token per-step cap, interleaved thinking (reasoning_content carried across steps). 62/89 = 69.7 at uniform 1× task timeouts; the 9 timed-out tasks rerun at 3× timeout converted exactly one, giving the reported 63/89 = 70.8. Supersedes the earlier 65.9 (pre-interleaved-thinking serving).
-
-DeepSWE v1.1 measured 2026-09-02 on the official leaderboard protocol (datacurve-pier 0.3.1 driving stock mini-swe-agent 2.4.6, native tool calling): full 113-task corpus, temperature 1.0, top_p 0.95, reasoning_effort max, 65536-token per-step cap, no step limit; 64/113 = 56.6, zero harness errors (the single verifier timeout is a model-induced test hang, counted as a fail). Smaug-Flash served in checkpoint-native FP8 on a dedicated Fireworks deployment.
-
-AA-LCR (Artificial Analysis Long Context Reasoning) measured 2026-09-01: temperature 1.0, top_p 1.0 (non-agentic regime), reasoning_effort max, 65536-token output cap, pinned LLM judge; 3 runs (Smaug-Flash) vs 2 runs (base), run-to-run spread ±2 points; both models served in checkpoint-native FP8 on Fireworks (dedicated vs serverless).
-
-Reproducibility notes, in the spirit of honest reporting: vendor-published
-agent-benchmark numbers are frequently not reproducible under released
-harnesses (we could not reproduce the base model's published Terminal Bench
-2.1 score with either public scaffold, from either of two serving providers);
-paired same-harness comparisons are the only numbers we consider load-bearing.
-Cross-scaffold analysis of all four Terminal Bench runs shows **zero tasks
-where Smaug-Flash robustly regresses** from base under both scaffolds.
-
-## 7. Known behaviors and limitations
-
-Smaug-Flash is more decisive than its base: it finishes tasks in fewer, denser
-turns and submits sooner. Under tight wall-clock budgets this is an asset (it
-wins several timeout-bound tasks the base loses); under hidden-test grading it
-can submit at ~98% spec coverage without spending remaining budget on
-self-verification. If your use case rewards exhaustive verification over
-decisiveness, prompt for explicit self-testing before completion. Improving
-autonomous verification discipline is the focus of our next training round.
-
-## 8. License
+## 6. License
 
 This repository and the model weights are licensed under the [MIT License](LICENSE), matching the base release.
 
-## 9. Citation
+## 7. Citation
 
 ```bibtex
 @misc{abacusai2026smaugflash,
@@ -345,11 +159,9 @@ The Smaug line and the DPO-Positive method behind it:
 }
 ```
 
-## 10. Base model
-
 Smaug-Flash builds on DeepSeek-V4-Flash-0731 by DeepSeek-AI:
 
-```
+```bibtex
 @misc{deepseekai2026deepseekv4,
       title={DeepSeek-V4: Towards Highly Efficient Million-Token Context Intelligence},
       author={DeepSeek-AI},
@@ -357,6 +169,6 @@ Smaug-Flash builds on DeepSeek-V4-Flash-0731 by DeepSeek-AI:
 }
 ```
 
-## 11. Contact
+## 8. Contact us
 
-Abacus.AI — https://abacus.ai
+For questions about Smaug-Flash, reach out at [https://abacus.ai](https://abacus.ai).