Add Model

Add or update a model preset

A preset is ground truth for the physics. Every number below changes the prediction, so copy it from the official config.json, never from memory or a blog post. Today is later than the assistant's training data: fetch the config.

1. Get the facts (do not skip)

1. Fetch https://huggingface.co/<org>/<model>/raw/main/config.json (WebFetch works; it is plain JSON). For multimodal repos the text model is under text_config / language_config — use those values. Also read https://huggingface.co/api/models/<org>/<model> for safetensors.total (true parameter count), cardData.license, createdAt.
2. If the config is not public (API-only model), do not invent dimensions. Either skip it or add it with specStatus: 'preview' and a specNote that names the proxy you used.
3. Record the source URL — it goes in specSourceUrl.

2. Map config → preset fields

Choosing attentionMechanism

Why this matters: the engine computes KV bytes as Σ_layers min(depth, window) × 2 × kvHeads × headDim × 2 bytes (MLA: (kvLoraRank + ropeDim) × 2), and attention FLOPs from the same layer mix. A wrong mix is a 2–10× KV error at long context.

3. Where to add it (all five, in order)

1. MODEL_PRESETS in engine.js (the physics engine that index.html loads before its page script), next to its family. Key convention: family[version]_size[_aNb] → qwen3.8_27b, gemma4_26b_a4b, ornith_1.5_397b_a17b, muse_glimmer_30b. Keys must be unique (the integrity test fails on duplicates — later keys would silently override). npm test re-stamps the engine.js?v=<hash> cache key in index.html and rebuilds dist/ (the SDK ships the same catalog) — commit those too. When the model replaces an older release, add old_key: 'new_key' to PRESET_SUPERSEDED_BY (engine.js): the landing page then prefers the new model, the picker shows an upgrade link on the old one, and the SDK reports supersededBy. Keep the old preset — its gold rows still calibrate.
2. Picker groups: the modelCategories map and featuredModelKeys inside the DOMContentLoaded handler (search const modelCategories = {). Uncategorized presets fall into "Other" — don't leave them there. Put the newest release first in its family and in "New & popular".
3. Evidence rule: MODEL_PRESET_RULES in scripts/refresh-localmaxxing.mjs — a regex on the Hugging Face id (base model and community quants both resolve through baseModel). Without it, no community run of the model becomes gold evidence and the planner cannot calibrate it. Put more specific patterns first (muse-glimmer-30b-assistant before muse-glimmer-30b).
4. Showcase (optional): QUICKSTART_SHOWCASES for a landing-page row when a setup is interesting and no measured row exists yet.
5. README model list when it is a headline family.

Pruned/REAP/abliterated/"distill" derivatives are different models: give them their own preset (see deepseek_v4_flash_reap_180b) or leave them out — mapping them onto the base preset makes real runs "beat physics".

4. Sanity-check the physics before trusting it

Run the engine for one obvious setup and compare with the back-of-envelope:

node -e "import('file:///'+process.cwd().replace(/\\\\/g,'/')+'/tests/load-index-app.mjs').then(({loadApp})=>{const app=loadApp();const H=app.hooks;
H.setDevices([{id:1,template:'RTX 5090',...JSON.parse(JSON.stringify(H.DEVICE_TEMPLATES['RTX 5090'])),name:'RTX 5090'}]);
app.applyPreset('<key>');app.setValue('quantizationType','q4');app.setValue('runtimeFramework','llama_cpp');app.setValue('parallelismStrategy','pipeline');
app.setValue('batchSize',1);app.setValue('promptTokens',2048);app.setValue('outputTokens',256);app.setValue('seqLength',2304);
const m=H.calculateMetrics()[0];console.log({decode:m.decodeTokensPerSecond,prefill:m.prefillTokensPerSecond,weightsGB:m.activeWeightSizeGB,kvGB:m.decodeKvCacheGB,b:m.decodeTimeBreakdown});})"

Expectations: decode ≈ 1 / (activeBytes/(BW×0.78) + layers×~45µs×(2 for GDN)×(1.4 MoE) + 0.2 ms) (active bytes use the quant format when one is set — Q4_K_M is 4.9 bits/weight, UD-IQ4_XS 4.0, NVFP4 4.5, AWQ/GPTQ 4.3, Q8_0 8.5 — times a 1.16 storage overhead for k-quants; see QUANT_FORMATS); KV per token ≈ fullLayers × 2 × kvHeads × headDim × 2 bytes (e.g. Qwen 3.8 27B: 16 × 2 × 4 × 256 × 2 = 64 KB). If a community number exists (Localmaxxing, r/LocalLLaMA, the model card), the engine should be within ~1.5× of it at the same depth; if not, the preset is wrong before the physics is.

5. Verify

• npm test — duplicate keys, preset metadata tests, anchors, XSS, waterfall consistency.
• npm run refresh:localmaxxing — pulls the latest runs (needs network); then npm run audit:gold and look for the new preset in the worst-outlier list. A row that beats the physical roofline means the preset (bytes, layer mix, KV) or the row's semantics is wrong — never an efficiency constant.
• If the model is important, add an anchor to tests/integrity.test.mjs ("decode anchors hold…") with the measured number and a ±35% band, citing where the measurement came from, and a KNOWN band in tests/sanity-matrix.test.mjs (wide tolerance: these catch unrealistic outliers, not drift). Add the preset to the matrix's MODELS list so every physics invariant is exercised on it.
• Browser check: load the preset in the planner; the execution map shows the head dim and "n Q / m KV heads"; the "How it scales" decode curve should bend where the KV cache becomes comparable to the weight bytes.

6. Commit

One commit per family is fine. Mention config verification in the message (specStatus: 'verified' presets are trusted by users).