model card: standard structure, measured facts, verified license declarations

README.md

@@ -1,8 +1,10 @@
 ---
 license: gemma
+license_link: https://ai.google.dev/gemma/terms
 base_model: google/embeddinggemma-300m
+base_model_relation: quantized
 library_name: coreml
-pipeline_tag: sentence-similarity
+pipeline_tag: feature-extraction
 tags:
   - coreml
   - core-ml
@@ -13,37 +15,36 @@ tags:
   - int8
   - embeddings
   - sentence-embedding
+  - sentence-similarity
+extra_gated_heading: Access EmbeddingGemma on Hugging Face
+extra_gated_description: >-
+  This artifact is a derivative of google/embeddinggemma-300m and is governed by
+  the Gemma Terms of Use, the Gemma Prohibited Use Policy and the Gemma license.
 ---
 
 # embeddinggemma-300m — Core ML (int8, seq 128, ANE)
 
-`google/embeddinggemma-300m` as a compiled Core ML encoder for Apple silicon, mirrored and
+`google/embeddinggemma-300m` as a compiled **Core ML** encoder for Apple silicon, mirrored and
 rebuild-verified by [visible-cx](https://huggingface.co/visible-cx). One call in, one 768-d
 L2-normalised embedding out.
 
-**Weights reproduce bit-exactly from the published recipe**: an independent rebuild on a
-different OS and CPU architecture produced a `weight.bin` identical to the published one,
-SHA-256 `f81f60eb…`, 0 of 308,616,576 bytes differing.
+**This is the one artifact in this org whose weights reproduce bit-exactly from the published
+recipe.** An independent rebuild on a different operating system and CPU architecture produced a
+`weight.bin` identical to the published one — SHA-256 `f81f60eb…`, **0 of 308,616,576 bytes
+differing**. Every Core AI `.aimodel` bundle in this org has to rest on digests instead, because
+that exporter is not deterministic even against itself.
 
-## Provenance
-
-| | |
-|---|---|
-| Base checkpoint | `google/embeddinggemma-300m` |
-| Upstream bundle | `mlboydaisuke/embeddinggemma-300m-coreml` @ `3fa12f0b97b8afe23264f76800afe14af4615ca5` |
-| Recipe | `john-rocky/CoreML-LLM` → `conversion/build_embeddinggemma_bundle.py --max-seq-len 128 --quantize int8` |
-| Format | Core ML `.mlmodelc` (compiled), int8 weights |
-| Sequence length | **128** (static) |
-| Output | 768-d embedding, mean pooling → dense stack → L2 normalise |
-| ANE residency | ~99.80%, 1950/1954 ops (upstream published claim, not re-measured here) |
-
-The mirror was verified byte-exact against upstream on all six files of the published
-artifact.
+> **This is Core ML, not Core AI.** It is an `.mlmodelc` loaded through `MLModel`, and the
+> `CoreAIKitEmbeddings.TextEmbedder` used by the sibling
+> [`visible-cx/embeddinggemma-300m-CoreAI`](https://huggingface.co/visible-cx/embeddinggemma-300m-CoreAI)
+> repo will not load it — that type looks for a `*.aimodel` in the bundle directory. Pooling,
+> the dense stack and L2 normalisation are inside this graph, so there is no host-side pooling
+> to implement either way.
 
 ## Contents
 
-**`3fa12f0b97b8afe23264f76800afe14af4615ca5/`** — the pinned upstream artifact, byte for
-byte, under its upstream revision as the directory name. 309,358,096 B total.
+**`3fa12f0b97b8afe23264f76800afe14af4615ca5/`** — the pinned upstream artifact, byte for byte,
+under its upstream revision as the directory name. **309,358,096 B** total.
 
 | File | Bytes |
 |---|---:|
@@ -55,8 +56,8 @@ byte, under its upstream revision as the directory name. 309,358,096 B total.
 | `model_config.json` | 2,351 |
 
 **`rebuild-verification/2026-08-17/`** — an independent rebuild of the same recipe on a
-different operating system and CPU architecture, published so the reproducibility claim can
-be checked. 309,346,242 B total.
+different operating system and CPU architecture, published so the reproducibility claim can be
+checked rather than taken on faith. **309,346,242 B** total.
 
 | File | Bytes |
 |---|---:|
@@ -67,39 +68,50 @@ be checked. 309,346,242 B total.
 | `SHA256SUMS` | 427 |
 | `VERIFICATION.md` | 2,878 |
 
-The shapes differ deliberately: the pinned artifact is a **compiled** `.mlmodelc`, the
-rebuild is the **uncompiled** `.mlpackage` the recipe emits. Compilation
-(`xcrun coremlcompiler`) is a macOS-only step and was not performed on the rebuild host.
+The shapes differ deliberately: the pinned artifact is a **compiled** `.mlmodelc`, the rebuild is
+the **uncompiled** `.mlpackage` the recipe emits. Compilation (`xcrun coremlcompiler`) is a
+macOS-only step and was not performed on the rebuild host.
 
-## Requirements
+## Provenance
 
-- **Apple silicon**, Core ML runtime. The encoder is shaped for the Neural Engine.
-- **Static sequence length 128.** Inputs must be padded or truncated to 128 tokens; this is
-  a compile-time property of the artifact, not a runtime option.
-- Weights ≈ 0.31 GB resident. **Minimum practical machine memory: 8 GB.**
-- `model_config.json` beside the encoder carries the pooling/dense/normalisation contract
-  the host must honour: mean pooling → dense stack → L2 normalise, 768-d out.
+| | |
+|---|---|
+| Base checkpoint | `google/embeddinggemma-300m` |
+| Upstream bundle | [`mlboydaisuke/embeddinggemma-300m-coreml`](https://huggingface.co/mlboydaisuke/embeddinggemma-300m-coreml) @ `3fa12f0b97b8afe23264f76800afe14af4615ca5` |
+| Recipe | `john-rocky/CoreML-LLM` → `conversion/build_embeddinggemma_bundle.py --max-seq-len 128 --quantize int8` |
+| Format | Core ML `.mlmodelc` (compiled), int8 weights |
+| Sequence length | **128** (static) |
+| Output | 768-d embedding; mean pooling → dense stack → L2 normalise, all in-graph |
+| ANE residency | ~99.80%, 1950/1954 ops — **upstream's published claim, not re-measured here** |
 
-Note the sequence-length difference from the Core AI artifact in this org, which is
-**seq 256**. The two are not drop-in substitutes for each other.
+The mirror was verified byte-exact against upstream on all six files of the published artifact.
+
+## Requirements
 
-## Performance
+- **Apple silicon**, Core ML runtime. The encoder is shaped for the Neural Engine.
+- **Static sequence length 128.** Inputs must be padded or truncated to 128 tokens; this is a
+  compile-time property of the artifact, not a runtime option.
+- Weights ≈ 0.31 GB resident. **No KV cache** — this is an encoder, so there is no per-token
+  memory growth and no context ladder. **Minimum practical machine memory: 8 GB.**
+- `model_config.json` beside the encoder carries the pooling / dense / normalisation contract the
+  host must honour.
 
-**No throughput or latency figure is published here.** The ANE residency figure above is
-the upstream published claim, not a measurement made here.
+Note the sequence-length difference from the Core AI artifact in this org, which is **seq 256**.
+The two are not drop-in substitutes for each other, and vectors from one should not be compared
+against vectors from the other.
 
-A cross-runtime quality datapoint on record is a cosine of **~0.966** on short text between
-this Core ML encoder and the LiteRT `.tflite` of the same base model, measured against
-previously installed copies rather than against the files in this repo.
+## Measurements
 
-## Status
+**No throughput or latency figure is published here**, and none has been taken. The ANE residency
+figure above is upstream's published claim, not a measurement made here.
 
-| Artifact | Status |
-|---|---|
-| `3fa12f0b…/encoder.mlmodelc` + `model_config.json` | **SHIP** — byte-exact mirror of the pinned upstream revision, with the `weight.bin` SHA-256 matching and independently reproduced. |
-| `rebuild-verification/2026-08-17/encoder.mlpackage` | **VERIFICATION EVIDENCE, not a runtime artifact** — uncompiled and never executed. |
+One cross-runtime quality datapoint is on record: a cosine of **~0.966** on short text between
+this Core ML encoder and the LiteRT `.tflite` of the same base model — measured against
+previously installed copies rather than against the files in this repo, so read it as an
+indication that the two runtimes agree closely on short text, not as a parity gate on these
+bytes.
 
-### Verification
+## Verification
 
 Weights and config reproduce bit-exactly from the recipe, across operating systems and CPU
 architectures:
@@ -113,19 +125,49 @@ architectures:
 
 So the claim is scoped precisely: **everything the recipe produces reproduces exactly; the
 remaining four files are a macOS compile step that was not run.** Closing that gap means
-compiling `rebuild-verification/2026-08-17/encoder.mlpackage` on a Mac and diffing the
-resulting `encoder.mlmodelc` against the pinned artifact.
+compiling `rebuild-verification/2026-08-17/encoder.mlpackage` on a Mac and diffing the resulting
+`encoder.mlmodelc` against the pinned artifact. `SHA256SUMS` and `VERIFICATION.md` in that folder
+carry the rebuild's own receipts.
+
+## Usage
+
+Core ML, no third-party package required. Load the compiled `.mlmodelc` directly and honour the
+contract in `model_config.json`:
+
+```swift
+import CoreML
+
+let url = /* …/3fa12f0b97b8afe23264f76800afe14af4615ca5/encoder.mlmodelc */
+let config = MLModelConfiguration()
+config.computeUnits = .cpuAndNeuralEngine   // the encoder is shaped for the ANE
 
-This is the exception in this org. Core AI `.aimodel` bundles are not byte-reproducible —
-the exporter is not deterministic even against itself — so their integrity rests on
-per-file SHA-256 of the exact published bytes. For this artifact, "verify by rebuilding" is
-genuinely available for the weights.
+let encoder = try MLModel(contentsOf: url, configuration: config)
+// inputs: token ids + attention mask, padded/truncated to 128
+// output: a 768-d L2-normalised embedding — cosine == dot product
+```
+
+Pooling, the dense stack and normalisation are already in the graph, so the output is directly
+comparable; do not re-normalise or re-pool.
+
+Two things to hold onto:
+
+- **Pad or truncate to exactly 128 tokens.** The length is compiled in.
+- **Apply EmbeddingGemma's query and document prompt prefixes yourself.** Unlike the Core AI
+  sibling — where `TextEmbedder` supplies them — nothing here does it for you, and embedding a
+  query with the document prefix quietly degrades retrieval.
+
+## Status
+
+| Artifact | Status |
+|---|---|
+| `3fa12f0b…/encoder.mlmodelc` + `model_config.json` | **SHIP** — byte-exact mirror of the pinned upstream revision, with the `weight.bin` SHA-256 matching and independently reproduced. |
+| `rebuild-verification/2026-08-17/encoder.mlpackage` | **VERIFICATION EVIDENCE, not a runtime artifact** — uncompiled and never executed. |
 
 ## License
 
-EmbeddingGemma is Gemma-family. These files are a derivative of
-`google/embeddinggemma-300m` and use is subject to the
+EmbeddingGemma is Gemma-family and the upstream checkpoint is **gated** on Hugging Face. These
+files 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). Those
-terms travel with the artifact and with any redistribution of it. The contribution here is
-the mirror and the rebuild verification, not the weights.
+[Gemma Prohibited Use Policy](https://ai.google.dev/gemma/prohibited_use_policy). Those terms
+travel with the artifact and with any redistribution of it. The contribution here is the mirror
+and the rebuild verification, not the weights.