docs: descriptive model card

README.md

@@ -1,50 +1,165 @@
 ---
+license: other
+license_name: lfm1.0
+license_link: https://huggingface.co/LiquidAI/LFM2.5-2.6B/blob/main/LICENSE
+base_model: LiquidAI/LFM2.5-2.6B
 library_name: coreai
-tags: [core-ai, aimodel, on-device, apple]
+pipeline_tag: text-generation
+tags:
+  - core-ai
+  - aimodel
+  - apple-silicon
+  - on-device
+  - quantized
+  - int8
+  - lfm2.5
 ---
 
-# LFM2.5-2.6B-CoreAI
+# LFM2.5-2.6B — Core AI (.aimodel)
 
-Core AI `.aimodel` bundles converted for [Visible](https://visible.cx) on-device
-inference. **Derivative artifacts** — converted from the upstream checkpoints listed
-below; all original model licences apply and travel with these weights.
+`LiquidAI/LFM2.5-2.6B` converted to Core AI `.aimodel` bundles for Apple silicon by the
+[Visible](https://visible.cx) project. These are **derivative artifacts**: the weights are
+Liquid AI's, re-expressed as a Core AI graph with int8 block-32 symmetric weight
+quantization and a two-entrypoint (decode + chunked-prefill) function map. They run through
+Core AI on macOS; they are not PyTorch, GGUF or MLX checkpoints and cannot be loaded by
+those runtimes.
 
-| Bundle | Source checkpoint | Context | Functions | Producer | Created |
-|---|---|---|---|---|---|
-| `gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | LiquidAI/LFM2.5-2.6B | 4096 | main+prefill | coreai-core 1.0.0b2 | 20260817T111106Z |
+**This is the model the Visible app selects as its quality tier.** It is the strongest of
+the three LFM2.5 text bundles in this catalog on Visible's own enrichment task, and the one
+whose outputs were judged most specific.
 
 ## Provenance
 
-- Converted with the [coreai-model-zoo](https://github.com/john-rocky/coreai-model-zoo)
-  conversion recipes on the pinned `apple/coreai-models` base
-  `b1cb71b8522d99408059fa0b98b8742171bcb0b8` + the zoo python overlay.
-- Toolchain: `coreai-torch 0.4.1`, `coreai-core 1.0.0b2`, `coreai-opt 0.2.1`, `torch 2.9.0`.
-- Every bundle's inner `<name>.aimodel/metadata.json` reports
-  `producer: "coreai-core 1.0.0b2"`.
-- Gemma bundles: `eos_token` is set to `<turn|>` (Gemma 4 ends a *turn* with `<turn|>`;
-  stopping on the source's `<eos>` overruns the reply).
-- Bundles carry `runtime_env COREAI_CHUNK_THRESHOLD=1`.
+| | |
+|---|---|
+| Base checkpoint | `LiquidAI/LFM2.5-2.6B` |
+| Recipe | `export_lfm2_multifunction.py int8hu --head-sym --chunk 64` |
+| Toolchain base | `apple/coreai-models` @ `b1cb71b8522d99408059fa0b98b8742171bcb0b8` + the [coreai-model-zoo](https://github.com/john-rocky/coreai-model-zoo) python overlay |
+| Toolchain | `coreai-torch 0.4.1`, `coreai-core 1.0.0b2`, `coreai-opt 0.2.1`, `torch 2.9.0` |
+| Producer fingerprint | `coreai-core 1.0.0b2` on every inner `<name>.aimodel/metadata.json` — verified per bundle |
+| Weight format | int8, per-K-block-32, symmetric; symmetric head (`--head-sym`) |
+| Vocab | 128,000 |
+| Conversion host | Linux x86_64 (Debian 13), CPU tracing only |
 
-Upstream sources: `LiquidAI/LFM2.5-2.6B`
+`mf64` in the bundle name means **multifunction with a 64-wide prefill**: one asset
+exposing `main` (S=1 decode) and `prefill` (S=64 chunked prefill),
+`function_map: {"main": ["main", "prefill"]}`. Weights are deduplicated across the two
+entrypoints, so the prefill function costs well under a megabyte.
 
+### The `<think>` patch — read this before swapping in a fresh export
 
-## High-context bundles — ctx 8192
+Upstream's `chat_template.jinja` ends its generation prompt with an **open** think block
+(`<|im_start|>assistant\n<think>`). LFM2.5-2.6B is always-thinking, so an open block burns
+684–919 reasoning tokens per item. Every bundle in this repo ships the block **closed**:
 
-Same weights, same graph, same recipe as the 4096 bundles above — the exporter's
-`--max-ctx` only widens the dynamic sequence bound and the manifest's
-`language.max_context_length`. KV cache stays fp16.
+```jinja
+{{- "<|im_start|>assistant\n<think></think>\n" -}}
+```
 
-| Bundle | Source checkpoint | Context | Functions | KV dtype | Producer | Created |
-|---|---|---|---|---|---|---|
-| `ctx8192/gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | LiquidAI/LFM2.5-2.6B | 8192 | main+prefill | fp16 | coreai-core 1.0.0b2 | 20260817T205308Z |
+This correction is applied post-export and **is not in the exporter**. A fresh conversion
+from the recipe reproduces the weights faithfully and this behaviour wrongly.
 
+## Contents
 
-## High-context bundles — ctx 16384
+| Path | Bytes | Manifest context | Functions |
+|---|---:|---|---|
+| `gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | 3,655,243,493 | 4096 | main + prefill |
+| `ctx8192/gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | 3,655,243,501 | 8192 | main + prefill |
+| `ctx16384/gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | 3,655,243,498 | 16384 | main + prefill |
 
-Same weights, same graph, same recipe as the 4096 bundles above — the exporter's
-`--max-ctx` only widens the dynamic sequence bound and the manifest's
-`language.max_context_length`. KV cache stays fp16.
+Each folder holds `<name>.aimodel/` (`main.mlirb` ≈ 3.64 GB, `main.hash`, asset
+`metadata.json`), a bundle-level `metadata.json`, and `tokenizer/`
+(`tokenizer.json`, `tokenizer_config.json`, `generation_config.json`,
+`chat_template.jinja`).
 
-| Bundle | Source checkpoint | Context | Functions | KV dtype | Producer | Created |
-|---|---|---|---|---|---|---|
-| `ctx16384/gpu-pipelined/lfm2_5_2_6b_decode_int8hu_block32_sym_mf64` | LiquidAI/LFM2.5-2.6B | 16384 | main+prefill | fp16 | coreai-core 1.0.0b2 | 20260817T205517Z |
+**The three folders hold the same weights.** `--max-ctx` does not change the exported
+graph — function signatures, state descriptors and peak export RSS are identical at 4096,
+8192 and 16384. It changes exactly one thing: `language.max_context_length` in the bundle
+manifest. This was proved three ways, including a same-config control re-export whose
+`main.mlirb` differed from its twin by *more* bytes than a 4096→8192 pair does
+(conversion is not byte-deterministic; the context delta is inside that noise floor). Pick
+the folder whose manifest integer matches the window you intend to run, or edit the
+integer — you do not need a new conversion for a context bump.
+
+The small byte differences between the three folders are conversion nondeterminism, not
+content.
+
+## Requirements
+
+- **Apple silicon Mac**, Core AI runtime. Nothing here runs on Linux or on Intel.
+- **Engine contract: 2 inputs.** `input_ids`, `position_ids` → logits. No static inputs, no
+  per-step mask. Runs on both the pipelined engine and the sequential (logits-capable)
+  engine, which is what makes grammar-constrained decoding available.
+- **States:** `keyCache` / `valueCache` `Float16, 8 × 1 × 8 × ? × 64` plus
+  `convState Float16, 22 × 1 × 2048 × 2`. The sequence dim is dynamic, so the runtime
+  resolves a `GrowingKVCache` (initial capacity 256, doubling) rather than allocating the
+  manifest maximum up front. `convState` is fixed-size and does not scale with context.
+- **KV cost: 16,384 bytes per token of context** (fp16) — 67 MB at 4096, 134 MB at 8192,
+  268 MB at 16384.
+- **Memory envelope, 16 GB Mac** (Metal `recommendedMaxWorkingSetSize` ≈ 10.7 GB):
+  weights 3.64 GB resident, so KV is not the binding constraint at any context this bundle
+  declares. Measured peak RSS on the qualification run was **4.43 GB**.
+- `runtime_env COREAI_CHUNK_THRESHOLD=1` travels with the recipe.
+
+## Measured performance
+
+Measured on a **16 GB M2 Pro Mac (macOS 27 beta)** with the out-of-process `coreai-repro`
+harness: 10 real enrichment rows (5 POST, 5 COMMENT) from Visible's prompt corpus, the
+app's live `app_litert` JSON schema, greedy decoding through `respondJSON(to:schema:)`,
+`reset()` per row, sequential engine, 128-token cap. Load time excluded from `s/row`; row 1
+of each run excluded as a cache-warm outlier.
+
+| | |
+|---|---|
+| Cold load | 39.5 s |
+| Guided JSON parse | **10/10** |
+| s/row | **3.62** (POST) / **3.04** (COMMENT) |
+| Peak RSS | 4.43 GB |
+| Stop token | `<\|im_end\|>`, clean self-stop on every row |
+
+For scale within this catalog on the same harness and machine: LFM2.5-350M runs
+0.79/0.51 s/row, LFM2.5-1.2B 1.77/1.30 s/row. The 2.6B is ≈2× the 1.2B, which is what its
+parameter count predicts, and it produces the most specific `summary`/`context` fields of
+the three.
+
+A note on a figure that circulated internally: "1.75 s posts / 1.20 s comments" is the
+**1.2B's** number, not this model's. Plan the quality tier against 3.0–3.6 s/row.
+
+Nothing above was measured at 8192 or 16384 context; the `ctx8192`/`ctx16384` folders carry
+the 4096 folder's graph, so throughput should be unchanged, but quality and memory at depth
+are unmeasured.
+
+## Qualification status
+
+| Artifact | Status |
+|---|---|
+| `gpu-pipelined/…_mf64` (ctx 4096) | **SHIP** — measured on the harness above and selected by the Visible app as its quality tier |
+| `ctx8192/…_mf64` | **QUALIFIED BY EQUIVALENCE, UNMEASURED AT DEPTH** — byte-equivalent weights and an identical graph to the shipping bundle; no run has been made at >4096 tokens |
+| `ctx16384/…_mf64` | **QUALIFIED BY EQUIVALENCE, UNMEASURED AT DEPTH** — as above |
+
+## Verification
+
+- **Producer fingerprint:** every inner `<name>.aimodel/metadata.json` reads
+  `producer: "coreai-core 1.0.0b2"`. This matters: `coreai-torch 0.4.0` / `coreai-core
+  1.0.0b1` produce bundles that abort in-process at load and take the host application down
+  uncatchably. The fingerprint lives in the **inner asset** metadata, not the bundle
+  manifest — the manifest never carries a `producer` field, for good and bad bundles alike.
+- **Stop token:** `tokenizer_config.json` declares `eos_token = "<|im_end|>"` in all three
+  folders, verified. LFM bundles need no stop-token correction (unlike Gemma 4).
+- **Determinism:** `.aimodel` conversion is **not byte-reproducible**. Two runs of the same
+  command minutes apart on the same box differ in `main.mlirb`. The tokenizer half *is*
+  reproducible. So integrity for these bundles rests on per-file SHA-256 of the exact
+  published artifact, never on rebuilding and comparing hashes.
+- No oracle or PSNR gate has been run against a PyTorch reference for this bundle. The
+  qualification above is behavioural (parse rate, enum conformance, content sanity, clean
+  stop) on Visible's own task, not a numerics gate.
+
+## License
+
+`LiquidAI/LFM2.5-2.6B` is released under the **LFM Open License v1.0** (`lfm1.0`). These
+bundles are a derivative of that checkpoint and the same licence and its obligations travel
+with them — see the
+[upstream licence](https://huggingface.co/LiquidAI/LFM2.5-2.6B/blob/main/LICENSE). Anyone
+redistributing these files should redistribute the licence with them and comply with its
+terms. Nothing here relicenses Liquid AI's weights; Visible's contribution is the
+conversion recipe and the qualification evidence.