docs: descriptive model card

README.md

@@ -2,13 +2,16 @@
 license: gemma
 base_model: google/embeddinggemma-300m
 library_name: coreai
+pipeline_tag: sentence-similarity
 tags:
-  - coreai
+  - core-ai
   - aimodel
-  - sentence-embedding
-  - on-device
   - apple-silicon
-pipeline_tag: sentence-similarity
+  - on-device
+  - embeddings
+  - sentence-embedding
+  - quantized
+  - int8
 extra_gated_heading: Access EmbeddingGemma on Hugging Face
 extra_gated_description: >-
   This artifact is a derivative of google/embeddinggemma-300m and is governed by
@@ -17,52 +20,133 @@ extra_gated_description: >-
 
 # embeddinggemma-300m — Core AI (.aimodel)
 
-`google/embeddinggemma-300m` exported as a single static fp32 Core AI graph
-(transformer -> mean pooling -> dense stack -> L2 normalize, all in-graph).
+`google/embeddinggemma-300m` exported as a single static Core AI graph for Apple silicon by
+the [Visible](https://visible.cx) project. The whole embedding pipeline is **in the graph**:
+transformer → mean pooling → dense stack → L2 normalise, one call in, one 768-d unit vector
+out. There is no host-side pooling to get wrong.
+
+Two variants ship here: an **fp32** bundle (built from the verified zoo recipe) and an
+**int8** bundle produced by compressing that graph in place. Their qualification status is
+not the same — read the status table before choosing.
+
+This repo is the Core AI *leg* of Visible's embedding story, not the production one. Core ML
+is the app's serving embedding path; this bundle is constructed always but only executes in
+`VISIBLE_COREAI_KIT` builds on macOS 27+.
+
+## Provenance
 
 | | |
 |---|---|
-| Recipe | `coreai-model-zoo/conversion/export_embeddinggemma.py --dtype float32 --seq-len 256` |
-| Recipe index | `models/qwen3-embedding/recipe.toml` -> `["embeddinggemma-300m"]` (`status = "verified"`) |
-| Upstream bundle | `mlboydaisuke/embeddinggemma-300m-CoreAI` |
-| Producer | `coreai-core 1.0.0b2` (coreai-torch 0.4.1, torch 2.9.0) |
-| I/O | `input_ids [1,256] int32`, `attention_mask [1,256] int32` -> `embedding [1,768]` fp32, L2-normalized |
+| Base checkpoint | `google/embeddinggemma-300m` |
+| Recipe (fp32) | `coreai-model-zoo/conversion/export_embeddinggemma.py --dtype float32 --seq-len 256` |
+| Recipe index | `models/qwen3-embedding/recipe.toml` → `["embeddinggemma-300m"]`, `status = "verified"` |
+| Upstream reference bundle | `mlboydaisuke/embeddinggemma-300m-CoreAI` @ `d9a60a18d384484a8dab809b3070b82fb41458ce` |
+| Producer fingerprint | `coreai-core 1.0.0b2` on both inner asset `metadata.json` files |
+| Asset creation dates | `20260817T201458Z` (fp32), `20260817T212021Z` (int8) |
+| Toolchain | `coreai-torch 0.4.1`, `coreai-core 1.0.0b2`, `coreai-opt 0.2.1`, `torch 2.9.0` |
+| Asset metadata | `author: "Google DeepMind"`, `license: "Gemma"` (fp32 bundle) |
+| Conversion host | Linux x86_64 (Debian 13), CPU only |
 
-Built on Linux x86_64 (conversion only). **Runtime parity is not measured here** —
-Core AI cannot execute on Linux; the on-device parity gate runs on macOS against
-`model/reference.json`.
+The `int8/` bundle is **not a second export**. It is the fp32 bundle put through
+`coreai_opt.coreai_utils.quantize_weights(dtype=DType.INT8)` — the Core AI *graph*
+compression path, which rewrites an existing program's weight constants in place. There was
+no PyTorch round-trip and no re-trace: the graph, the input signature and the tokenizer are
+the fp32 bundle's, unchanged. The pass accepted the graph first try, in about a minute of
+box time.
 
-## License
+## Contents
 
-Derivative of EmbeddingGemma; use is subject to the
-[Gemma Terms of Use](https://ai.google.dev/gemma/terms) and the
-[Gemma Prohibited Use Policy](https://ai.google.dev/gemma/prohibited_use_policy).
+| Path | Bytes | Weights | Sequence length |
+|---|---:|---|---|
+| `model/embeddinggemma-300m_float32_static.aimodel` + `model/reference.json` + `model/tokenizer/` | 1,277,545,730 | fp32 | 256 |
+| `int8/embeddinggemma-300m_int8_static.aimodel` + `int8/reference.json` + `int8/tokenizer/` | 356,639,960 | int8 (graph-compressed) | 256 |
 
+| File | fp32 (`model/`) | int8 (`int8/`) |
+|---|---:|---:|
+| `main.mlirb` | 1,244,157,766 | **323,252,231** (0.26×) |
+| `main.hash` | 32 | 32 |
+| asset `metadata.json` | 340 | 105 |
+| `reference.json` | 1,615 | 1,615 |
+| `tokenizer/tokenizer.json` | 33,385,272 | 33,385,272 |
+| `tokenizer/tokenizer_config.json` | 705 | 705 |
 
-## EXPERIMENTAL - int8 graph-compressed bundle (`int8/`)
+`reference.json` and `tokenizer/` in `int8/` are byte-identical copies of the fp32
+bundle's, carried so the folder is self-contained.
 
-> **EXPERIMENTAL. Do not use for production embeddings until vector-parity has been
-> qualified on a Mac against the fp32 bundle above.** No numerics gate has been run on
-> this artifact: the conversion box is Linux with no GPU delegate, so nothing here has
-> produced a vector.
+`reference.json` is the exporter's own torch oracle: four reference texts and their
+pairwise cosines, for checking the source pipeline end to end.
 
-`int8/embeddinggemma-300m_int8_static.aimodel` is the fp32 bundle in
-`model/` (this repo @ `2bee70c5bc49cafc3c9e7f88d4d0095508cbfd4b`) put through **`coreai_opt.coreai_utils.quantize_weights`
-with `dtype=INT8`** - a Core AI *graph* compression pass that rewrites the weight
-constants of an existing `.aimodel` in place. There is **no PyTorch round-trip and no
-re-export**: the graph, the input signature (`seq_len 256`, 768-d output) and the
-tokenizer are the fp32 bundle's.
+## Requirements
 
-| | fp32 (`model/`) | int8 (`int8/`) |
-|---|---|---|
-| `main.mlirb` | 1,244,157,766 B | 323,252,231 B |
-| ratio | 1.00x | **0.26x** |
-| producer | `coreai-core 1.0.0b2` | `coreai-core 1.0.0b2` |
+- **Apple silicon Mac**, Core AI runtime, macOS 27+.
+- **Static input signature:** `input_ids [1, 256] int32`, `attention_mask [1, 256] int32`
+  → `embedding [1, 768]` fp32, L2-normalised. Sequence length 256 is baked into the graph
+  — pad or truncate to it; there is no dynamic-length variant.
+- Weights ≈ 1.24 GB resident (fp32) or ≈ 0.32 GB (int8). No KV cache; this is an encoder,
+  so there is no per-token memory growth and no context ladder.
+- Note the sequence-length difference from the Core ML artifact in this org, which is
+  **seq 128**. The two are not drop-in substitutes for each other.
 
-The `reference.json` and `tokenizer/` beside it are byte-identical copies of the fp32
-bundle's, carried so the folder is self-contained.
+## Measured performance
 
-**Qualification gate before any use:** embed a fixed corpus with both bundles on a Mac
-and compare vectors (cosine similarity per vector and retrieval-rank agreement), not
-just spot-check output shapes. fp16 embeddinggemma is already known to fail vector
-precision parity; int8 has not been shown to pass.
+**None, from either bundle.** No embedding vector has been computed from either artifact:
+they were built on a Linux box, where Core AI cannot execute (it needs Apple silicon), and
+no Mac-side run has been recorded. Everything below is a *build and bytes* result, not a
+runtime result.
+
+For contrast: the catalog's generation bundles carry throughput measured on a 10-row guided
+enrichment harness on a 16 GB M2 Pro Mac. There is no equivalent measurement here — not a
+slower number, no number.
+
+## Qualification status
+
+| Artifact | Status |
+|---|---|
+| `model/` (fp32, seq 256) | **BUILT AND FINGERPRINTED, RUNTIME-UNQUALIFIED.** The recipe is the zoo's `status = "verified"` entry, the producer fingerprint passes, and the exporter's own pre-export gate (wrapper vs `sentence_transformers.encode` cosine > 0.999) passed. No vector has been computed from the *exported graph* on a Mac. |
+| `int8/` (graph-compressed) | **EXPERIMENTAL.** Named gate: **cross-runtime vector parity against the fp32 bundle on a Mac** — cosine similarity per vector *and* retrieval-rank agreement, on a fixed corpus, not a spot-check of output shapes. Do not use for production embeddings until that passes. |
+
+The int8 caveat is not boilerplate. fp16 embeddinggemma is already **known** to fail
+vector-precision parity — the exporter's own comment records that a full `.to(float16)`
+overflows Gemma3 activations and emits NaN embeddings, which independently matches
+Visible's earlier finding. A 4× compression passing parity is therefore a hypothesis, not
+an expectation.
+
+## Verification
+
+- **Producer fingerprint:** both inner asset `metadata.json` files read
+  `producer: "coreai-core 1.0.0b2"`. The pair to reject is `coreai-torch 0.4.0` /
+  `coreai-core 1.0.0b1`, whose bundles abort in-process at load and take the host
+  application down uncatchably. Read the **inner** asset file — the bundle manifest never
+  carries a `producer` field, for good and bad bundles alike.
+- **Determinism — this bundle is NOT reproducible, and the sibling Core ML repo is.**
+  Rebuilt from the same recipe, `main.mlirb` differed from the published upstream bundle by
+  **+262 bytes**. Two runs on the same box nine minutes apart with an identical command
+  differed from *each other* by **+32 bytes**. So the difference is not a
+  macOS→Linux or toolchain-version artifact: the exporter is simply not byte-deterministic.
+  The tokenizer half is identical in every comparison made. **"Verify by rebuilding" is not
+  available for `.aimodel` bundles**; integrity rests on per-file SHA-256 of the exact
+  published bytes.
+
+  For the contrast, see `visible-cx/embeddinggemma-300m-CoreML`, where the same model's
+  Core ML `weight.bin` reproduced **bit-exactly** across operating systems — 0 of
+  308,616,576 bytes differing. Two artifacts of one model, two different supply-chain
+  arguments.
+- **The torch oracle agrees to ~6e-8.** `reference.json`'s pairwise cosines from the box
+  rebuild match the published values to roughly seven decimal places (largest deviation
+  ~6e-8, e.g. `query_bike|query_capital` 0.14591985940933228 vs 0.1459198147058487). That
+  is CPU float nondeterminism across machines, not a different model. It validates the
+  **source** pipeline — checkpoint → prompts → pooling → dense → L2 — and explicitly does
+  **not** validate the exported graph's execution.
+- No ANE-residency measurement exists for either bundle. `export_embeddinggemma.py` exposes
+  only `--dtype`, `--seq-len`, `--output-dir`, `--overwrite`; there is no compute-unit flag,
+  so an ANE-shaped variant would be model authoring rather than configuration.
+
+## License
+
+EmbeddingGemma is Gemma-family. These bundles are a derivative of
+`google/embeddinggemma-300m`, and use is subject to the
+[Gemma Terms of Use](https://ai.google.dev/gemma/terms) and the
+[Gemma Prohibited Use Policy](https://ai.google.dev/gemma/prohibited_use_policy). The
+fp32 bundle's own asset metadata carries `license: "Gemma"` and
+`author: "Google DeepMind"`. Those terms travel with the artifact and with any
+redistribution of it; Visible's contribution is the conversion, not the weights.