Fix provenance and publish reproducible LFM2.5 conversion recipe

Correct coreai-model-zoo attribution to the public community repository, pin the public exporter/runtime inputs, reduce the required patch set to the two patches this graph uses, scope performance to the published evidence, remove leaked local paths from bundle metadata, and add the exact 2.6B conversion wrapper and gates.

README.md

@@ -33,48 +33,56 @@ tags:
 - liquid
 - edge
 - int8
-- requires-nonpublic-runtime
+- community-model-zoo
 ---
 
-# LFM2.5-2.6B — Core AI (int8) — NOT RUNNABLE WITH PUBLIC TOOLING
+# LFM2.5-2.6B — Core AI (int8)
 
 An int8 Core AI conversion of **[LiquidAI/LFM2.5-2.6B](https://huggingface.co/LiquidAI/LFM2.5-2.6B)**
 for Apple silicon. This repository contains no trained weights of its own: it is a quantized
 format conversion of Liquid AI's model, and all model credit belongs to **Liquid AI**.
 
-> **Status: artifact archive, not a runnable release.** These are real, gated, verifiable
-> weights, but executing them requires a Core AI runtime patch stack that lives in a
-> non-public Apple repository. If you do not have access to `apple/coreai-model-zoo`, you can
-> download, hash-verify, inspect and study this conversion — you cannot run it. Details in the
-> next section.
+> **Runtime status:** runnable with public tooling, but not with an unmodified
+> `apple/coreai-models` checkout. LFM's fixed-shape convolution state requires two patches from
+> the public, community-maintained
+> [`john-rocky/coreai-model-zoo`](https://github.com/john-rocky/coreai-model-zoo). Exact public
+> commits and commands are below.
 
 Converted from source revision `dca1825886789bd40b94368f53b1d9ada4c94598`. Both upstream
 safetensors shards were SHA-256 verified against that revision before conversion.
 
-## Read this first: running it needs a runtime you may not be able to get
+## Runtime requirements
 
-**This asset will not run on a stock Core AI runtime.** It requires a patch stack that lives in
-Apple's `coreai-model-zoo`, which is **not a public repository**. Specifically:
+This graph has the normal growing key/value cache plus one fixed-shape `conv_state`. The stock
+pipelined engine handles only the KV pair. Apply these **two** public community patches—no
+per-token-input, static-input, or prefix-cache patch is required for this model:
 
-- The graph uses a **per-token input contract** (`input_ids [1,1]` plus explicit KV state) that
-  an unpatched runtime at the pinned commit rejects. The patches involved are named
-  `coreai-pipelined-per-token-inputs`, `-static-inputs`, `-extra-states`,
-  `coreai-prefix-cache` and `coreai-shared-product`.
-- Re-exporting additionally needs that repository's LFM2 **overlay**, which is what teaches the
-  converter this architecture at all.
+1. `apps/coreai-shared-product.patch`
+2. `apps/coreai-pipelined-extra-states.patch`
 
-Those patches are Apple's, not mine, so they are **not redistributed here** and this repository
-cannot make them available to you. Practically:
+Both come from
+[`john-rocky/coreai-model-zoo@95a29d41`](https://github.com/john-rocky/coreai-model-zoo/tree/95a29d41affed3bdf3ea5992ece094a908e21a04),
+a public community repository maintained by Daisuke Majima (`john-rocky`). It is not an Apple
+repository. The patches target Apple's public
+[`coreai-models`](https://github.com/apple/coreai-models) runtime at
+`5ed9981303b38d5a44aa6b45509bc4f6945029f5`.
 
-- **With access to `coreai-model-zoo`:** everything needed to build the runtime and reproduce
-  the conversion is pinned in [`RECIPE.md`](RECIPE.md).
-- **Without it:** you can download and inspect these weights, read every measurement, and reuse
-  the recipe — but you will not be able to execute the asset today. That is a real limitation,
-  stated here rather than buried.
+```bash
+git clone https://github.com/apple/coreai-models.git
+git -C coreai-models checkout 5ed9981303b38d5a44aa6b45509bc4f6945029f5
+
+git clone https://github.com/john-rocky/coreai-model-zoo.git
+git -C coreai-model-zoo checkout 95a29d41affed3bdf3ea5992ece094a908e21a04
+
+git -C coreai-models apply ../coreai-model-zoo/apps/coreai-shared-product.patch
+git -C coreai-models apply ../coreai-model-zoo/apps/coreai-pipelined-extra-states.patch
+swift build --package-path coreai-models -c release --product llm-runner
+```
 
-For the same reason **no conversion toolkit is shipped**: those scripts import modules from that
-non-public repo, so publishing them would either redistribute code that is not mine or hand you
-something that cannot run. [`RECIPE.md`](RECIPE.md) describes the recipe precisely instead.
+The public community zoo also supplies the LFM2 exporter and its `coreai-models` overlay. The
+small toolkit published here contains the 2.6B-specific wrapper, tokenizer/config corrections,
+quality gates, and locked Python environment used for this artifact. Full reproduction details
+are in [`RECIPE.md`](RECIPE.md).
 
 ## Which file do I want?
 
@@ -105,6 +113,7 @@ Full SHA-256 of each file as published.
 | `aimodelc-h16c/…h16c.aimodelc/…/resources.bin` | 3468949676 | `793907c101a01331ffa72aff7c9db5049c89a02ea03acee3174513a93c394e22` | same weights, AOT compiled | **`h16c` only** | faster cold load |
 | `aimodelc-h16c/…h16c.aimodelc/…/original_model_0.mpsgraph` | 363905 | `74a24870a8853bf797a6f12f40e7fcb988de014d98166da772b24cab643d5d4f` | compiled graph | `h16c` only | part of the above |
 | `tokenizer/tokenizer.json` | 17905598 | `695be7802a0e4b8a81048f0ff5ebb7fc811a0ba5a6be63dbb24deb5a81096f41` | upstream, unmodified | — | required |
+| `lfm2.5-2.6b-coreai-conversion-e0e375b.tar.gz` | 57118 | `665285044be7c0171e1b737167b9892f2799bc2e01e3c5441212887903456f2d` | exact wrapper + gates at local conversion commit `e0e375b` | — | reproduction |
 
 - **The two `tokenizer/tokenizer.json` copies are byte-identical** (same hash above). The one
   under `aimodelc-h16c/tokenizer/` is a **convenience copy**; you do not need both.
@@ -132,24 +141,19 @@ ordering — do not read the embedding row's 123 as "better". int4 is excluded o
 size: a minimum cosine of 0.51–0.80 is a different model. **Rejected variants are documented and
 deliberately not uploaded.** Full detail in [`RECIPE.md`](RECIPE.md).
 
-## Performance, and an unresolved caveat
+## Performance
 
 Decode here is **memory-bandwidth bound** — throughput tracks bytes read per token.
 
 | Measurement | Protocol | Result |
 | --- | --- | --- |
-| Development runs of this recipe | cold cache + 60 s settle, 5 trials × 3 independent runs, quiet machine | **138.15 tok/s**, between-run spread 0.31 % |
-| Re-measurement of *this published artifact* | same protocol, 5 trials | **107.98 tok/s**, sd 0.500 — machine demonstrably busy: load average 9–17, background disk 50–1400 MB/s |
+| This published artifact | 128 prompt tokens, 256 generated, greedy, 5 trials, M4 Max | **107.98 decode tok/s**, sd 0.500; **111.86 prompt tok/s** |
+| Earlier development build of the same recipe | separate runs on the same M4 Max | 138.15 decode tok/s |
 
-Both are real; neither is cherry-picked; **the gap is not explained**. Established: this
-artifact's storage budget is byte-identical to the one measured at 138, and its quality and
-conversion gate reproduce exactly, so these are measurements of the same recipe rather than of
-two different models. Not established: the cause. A bandwidth-bound workload losing throughput
-to competing memory traffic is the obvious candidate, but the machine never went quiet again
-during the session, so it was never isolated and another regression cannot be ruled out.
-
-Treat 138 as what this recipe has done on an idle M4 Max and 108 as what it did under the stated
-load, and **measure on your own hardware rather than trusting either.**
+Only **107.98 tok/s** is attached to the published artifact in `evidence/benchmark.json`. The
+earlier 138.15 result was not reproduced after publication, so it is retained as historical
+context rather than advertised as this download's performance. The workload is
+memory-bandwidth-bound and was measured while the machine was busy; measure on your own hardware.
 
 For reference, on the same Mac, MLX reported ~100 tok/s at 8-bit and ~60 tok/s at BF16. Those
 were throughput-only observations; MLX quality was not measured, so no quality comparison against
@@ -166,11 +170,14 @@ variants are in **[`RECIPE.md`](RECIPE.md)**. Summary:
 Source model : LiquidAI/LFM2.5-2.6B @ dca1825886789bd40b94368f53b1d9ada4c94598          (public)
 Converter    : github.com/apple/coreai-models @ b1cb71b8522d99408059fa0b98b8742171bcb0b8  (public)
 Runtime      : github.com/apple/coreai-models @ 5ed9981303b38d5a44aa6b45509bc4f6945029f5  (public)
-coreai-torch : c89f6a44713249a12a84beec9f3e0cf2206ecc38                                   (public)
-LFM2 overlay + runtime patch stack :
-               apple/coreai-model-zoo @ ebef921a1f358af66c9ff67e8c6e7d4e24efad0d      (NOT public)
+Community LFM2 exporter, overlay and two runtime patches:
+               github.com/john-rocky/coreai-model-zoo
+               @ 95a29d41affed3bdf3ea5992ece094a908e21a04                     (public)
+2.6B wrapper : lfm2.5-2.6b-coreai-conversion-e0e375b.tar.gz
+               SHA-256 665285044be7c0171e1b737167b9892f2799bc2e01e3c5441212887903456f2d
 Toolchain    : macOS 27.0 (26A5388g), Xcode 27.0 (27A5228h), Python 3.11.15,
-               torch 2.9.0, coremltools 9.0
+               torch 2.9.0, coreai-core 1.0.0b2, coreai-torch 0.4.1,
+               coreai-opt 0.2.1, coremltools 9.0
 ```
 
 **Verify a rebuild by the gates and the storage budget, not by hashing.** The exporter names each
@@ -194,6 +201,15 @@ With a runtime built as described above, the asset is driven as a pipelined Core
 model with `COREAI_CHUNK_THRESHOLD=1`, greedy decoding, using the model's own chat template at
 `tokenizer/chat_template.jinja`. Operational notes:
 
+```bash
+COREAI_CHUNK_THRESHOLD=1 coreai-models/.build/release/llm-runner \
+  --model ./LFM2.5-2.6B-CoreAI \
+  --prompt "The capital of France is" \
+  --max-tokens 64 --temperature 0 \
+  --inference-engine-variant coreai-pipelined \
+  --warmup exact --warmup-length 1
+```
+
 - **macOS 27.0+** on **Apple silicon**. Validated on M4 Max.
 - Runs on the **GPU** via an `MPSGraph` delegate. This is **not** an ANE asset: the KV dimension
   is dynamic, and `--preferred-compute` does not change the emitted delegate.
@@ -219,7 +235,8 @@ Four **separate** questions, not interchangeable:
 
 ## Limitations and negative results
 
-- **Not runnable without the non-public patch stack.** See the top of this card.
+- Requires the two public community runtime patches listed above; it does not run on an
+  unmodified `apple/coreai-models` runtime.
 - No task-benchmark evaluation; quality is a 125-position regression probe.
 - Multilingual support is inherited from upstream and was **not** re-verified per language; the
   probe is English.
@@ -240,6 +257,10 @@ upstream license, and claims **no authorship of the model**.
   [here](https://huggingface.co/LiquidAI/LFM2.5-2.6B/blob/dca1825886789bd40b94368f53b1d9ada4c94598/LICENSE),
   included verbatim as [`LICENSE.upstream`](LICENSE.upstream). Your use of these weights is
   governed by it.
-- Conversion tooling: Apple's `coreai-models`, `coreai-torch` and `coreai-model-zoo`, at the
-  commits pinned above. **No Apple source is redistributed here.**
+- Official Apple tooling: [`apple/coreai-models`](https://github.com/apple/coreai-models),
+  `coreai-core`, `coreai-torch`, and `coreai-opt`.
+- Community conversion/runtime work: public
+  [`john-rocky/coreai-model-zoo`](https://github.com/john-rocky/coreai-model-zoo), maintained
+  by **Daisuke Majima**, under its BSD-3-Clause license. Its repository includes third-party
+  notices for portions derived from Apple's BSD-licensed `coreai-models` project.
 - This repository contributes the conversion recipe, the gates, and the measurements.

RECIPE.md

@@ -1,37 +1,63 @@
 # Conversion recipe
 
-This document is the reproducibility record for the published asset. It is written from
-scratch and contains no code from Apple's repositories; it describes **what** was done
-precisely enough to redo it, for a reader who has access to the tooling described in
-"Prerequisites".
+This document is the reproducibility record for the published asset. The conversion used
+Apple's public `coreai-models` project, the public community-maintained
+`john-rocky/coreai-model-zoo`, and the 2.6B-specific wrapper and gates shipped here as
+`lfm2.5-2.6b-coreai-conversion-e0e375b.tar.gz`.
 
-No conversion scripts are shipped in this repository. They import modules from Apple's
-`coreai-model-zoo`, which is not publicly available, so publishing them would either
-redistribute code that is not mine or hand you something that cannot run. A precise
-description is more useful than either.
+The toolkit contains only the wrapper, targeted configuration fixes, gates, and locked Python
+environment from this conversion workspace. It does not vendor either upstream repository.
 
 ## Prerequisites
 
 | Component | Pin | Public? |
 | --- | --- | --- |
 | `LiquidAI/LFM2.5-2.6B` | `dca1825886789bd40b94368f53b1d9ada4c94598` | yes |
-| `github.com/apple/coreai-models` (converter) | `b1cb71b8522d99408059fa0b98b8742171bcb0b8` | yes |
-| `github.com/apple/coreai-models` (runtime) | `5ed9981303b38d5a44aa6b45509bc4f6945029f5` | yes |
-| `coreai-torch` | `c89f6a44713249a12a84beec9f3e0cf2206ecc38` | yes |
-| `apple/coreai-model-zoo` — LFM2 overlay **and** runtime patch stack | `ebef921a1f358af66c9ff67e8c6e7d4e24efad0d` | **no** |
+| [`apple/coreai-models`](https://github.com/apple/coreai-models) (converter base) | `b1cb71b8522d99408059fa0b98b8742171bcb0b8` | yes, official Apple |
+| [`apple/coreai-models`](https://github.com/apple/coreai-models) (runtime base) | `5ed9981303b38d5a44aa6b45509bc4f6945029f5` | yes, official Apple |
+| [`john-rocky/coreai-model-zoo`](https://github.com/john-rocky/coreai-model-zoo) — LFM2 exporter/overlay and runtime patches | `95a29d41affed3bdf3ea5992ece094a908e21a04` | yes, community-maintained |
+| 2.6B conversion toolkit in this repository | `e0e375b`; SHA-256 `665285044be7c0171e1b737167b9892f2799bc2e01e3c5441212887903456f2d` | yes |
+| `coreai-core` / `coreai-torch` / `coreai-opt` | `1.0.0b2` / `0.4.1` / `0.2.1` | yes |
 
 Toolchain used: macOS 27.0 (build `26A5388g`), Xcode 27.0 (`27A5228h`), Python 3.11.15,
 torch 2.9.0, coremltools 9.0.
 
-The zoo is the blocker for both directions, and there is no way around it from here:
+The public community zoo is required in both directions:
 
 - **Conversion** needs the zoo's overlay, because that overlay is what carries the LFM2
-  authoring module (`models/macos/lfm2.py`) — the converter alone does not know this
-  architecture.
-- **Inference** needs the zoo's runtime patch stack
-  (`coreai-pipelined-per-token-inputs`, `-static-inputs`, `-extra-states`,
-  `coreai-prefix-cache`, `coreai-shared-product`). An unpatched runtime at the pinned
-  commit does not accept this asset's per-token input contract.
+  authoring module (`models/macos/lfm2.py`)—Apple's converter base alone does not know this
+  architecture. The shipped wrapper additionally fixes the nested LFM2.5 RoPE configuration,
+  local-checkpoint loading, tokenizer staging, and the measured attention-precision choice.
+- **Inference** needs exactly two zoo patches:
+  `apps/coreai-shared-product.patch` followed by
+  `apps/coreai-pipelined-extra-states.patch`. The extra-state patch carries LFM's fixed-shape
+  convolution state beside the growing KV pair. This model does not require the zoo's
+  per-token-input, static-input, or prefix-cache patches.
+
+### Recreate the converter workspace
+
+```bash
+tar -xzf lfm2.5-2.6b-coreai-conversion-e0e375b.tar.gz
+cd lfm2.5-2.6b-coreai-conversion-e0e375b
+
+git clone https://github.com/apple/coreai-models.git /path/to/coreai-models
+git -C /path/to/coreai-models checkout b1cb71b8522d99408059fa0b98b8742171bcb0b8
+
+git clone https://github.com/john-rocky/coreai-model-zoo.git /path/to/coreai-model-zoo
+git -C /path/to/coreai-model-zoo checkout 95a29d41affed3bdf3ea5992ece094a908e21a04
+
+COREAI_MODELS_REPO=/path/to/coreai-models \
+COREAI_ZOO_REPO=/path/to/coreai-model-zoo \
+  bash scripts/setup-vendor.sh
+
+uv run python scripts/export_bundle.py --mode int8hu -- --head-sym --tag _attnfp16
+uv run python scripts/authored_parity.py
+uv run python scripts/quant_reference.py --mode int8hu -- --head-sym --tag _attnfp16
+uv run python scripts/gate_bundle.py --bundle <exported-bundle>
+```
+
+The source checkpoint itself is not included in the toolkit; obtain
+`LiquidAI/LFM2.5-2.6B` at the pinned revision under its upstream license.
 
 ## Quantization
 

aimodelc-h16c/metadata.json

@@ -6,7 +6,7 @@
     "main": "lfm2_5_2_6b_decode_int8hu_attnfp16_block32_sym.h16c.aimodelc"
   },
   "language": {
-    "tokenizer": "/Users/harsha/Developer/sst/LFM2.5-2.6B/runs/stage/LFM2.5-2.6B",
+    "tokenizer": "tokenizer",
     "vocab_size": 128000,
     "max_context_length": 4096,
     "embedded_tokenizer": true,
@@ -18,11 +18,11 @@
   },
   "source": {
     "model_definition": "torch",
-    "hf_model_id": "/Users/harsha/Developer/sst/LFM2.5-2.6B/runs/stage/LFM2.5-2.6B"
+    "hf_model_id": "LiquidAI/LFM2.5-2.6B"
   },
   "compression": null,
   "compilation": {
     "date": "2026-08-05T18:32:10.998903+00:00",
     "targets": []
   }
-}
+}

lfm2.5-2.6b-coreai-conversion-e0e375b.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:665285044be7c0171e1b737167b9892f2799bc2e01e3c5441212887903456f2d
+size 57118

metadata.json

@@ -6,7 +6,7 @@
     "main": "lfm2_5_2_6b_decode_int8hu_attnfp16_block32_sym.aimodel"
   },
   "language": {
-    "tokenizer": "/Users/harsha/Developer/sst/LFM2.5-2.6B/runs/stage/LFM2.5-2.6B",
+    "tokenizer": "tokenizer",
     "vocab_size": 128000,
     "max_context_length": 4096,
     "embedded_tokenizer": true,
@@ -18,11 +18,11 @@
   },
   "source": {
     "model_definition": "torch",
-    "hf_model_id": "/Users/harsha/Developer/sst/LFM2.5-2.6B/runs/stage/LFM2.5-2.6B"
+    "hf_model_id": "LiquidAI/LFM2.5-2.6B"
   },
   "compression": null,
   "compilation": {
     "date": "2026-08-05T18:32:10.998903+00:00",
     "targets": []
   }
-}
+}