docs: descriptive model card

README.md

@@ -0,0 +1,149 @@
+---
+license: gemma
+base_model: google/embeddinggemma-300m
+library_name: coreml
+pipeline_tag: sentence-similarity
+tags:
+  - coreml
+  - core-ml
+  - apple-silicon
+  - on-device
+  - ane
+  - quantized
+  - int8
+  - embeddings
+  - sentence-embedding
+---
+
+# embeddinggemma-300m — Core ML (int8, seq 128, ANE)
+
+`google/embeddinggemma-300m` as a compiled Core ML encoder for Apple silicon, mirrored and
+independently rebuild-verified by the [Visible](https://visible.cx) project. **This is the
+embedding model Visible actually serves.** Core ML is the production embedding path in the
+app; the LiteRT artifact is retained as a benchmark instrument and never as a serving
+fallback, and the Core AI embedding bundle only runs in a specific build configuration on
+macOS 27+.
+
+It is also the one artifact in this entire catalog whose weights are **provably
+reproducible**: a rebuild from the recipe on Linux produced a `weight.bin` that is
+byte-for-byte identical to the published one.
+
+## 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 |
+| ANE residency | **~99.80%**, 1950/1954 ops (published claim; not re-measured by Visible) |
+| Pinned in the app as | `CoreMLEmbeddingGemmaBundle` |
+
+The mirror was verified byte-exact against upstream on all six files of the published
+artifact before this card was written.
+
+## Contents
+
+Two top-level directories. The first is the artifact; the second is the evidence.
+
+**`3fa12f0b97b8afe23264f76800afe14af4615ca5/`** — the pinned upstream artifact, byte for
+byte, under its own upstream revision as the directory name. 309,358,096 B total.
+
+| File | Bytes |
+|---|---:|
+| `encoder.mlmodelc/weights/weight.bin` | 308,616,576 |
+| `encoder.mlmodelc/model.mil` | 735,948 |
+| `encoder.mlmodelc/metadata.json` | 2,570 |
+| `encoder.mlmodelc/coremldata.bin` | 408 |
+| `encoder.mlmodelc/analytics/coremldata.bin` | 243 |
+| `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
+below can be checked rather than taken on trust. 309,346,242 B total.
+
+| File | Bytes |
+|---|---:|
+| `encoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin` | 308,616,576 |
+| `encoder.mlpackage/Data/com.apple.CoreML/model.mlmodel` | 723,393 |
+| `encoder.mlpackage/Manifest.json` | 617 |
+| `model_config.json` | 2,351 |
+| `SHA256SUMS` | 427 |
+| `VERIFICATION.md` | 2,878 |
+
+Note the shapes differ deliberately: the pinned artifact is a **compiled** `.mlmodelc`, the
+rebuild is the **uncompiled** `.mlpackage` the recipe emits. Compilation is a macOS-only
+step (`xcrun coremlcompiler`) and was not faked on Linux.
+
+## Requirements
+
+- **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. This is a small model by every measure in this catalog and
+  imposes no meaningful memory tier.
+- `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.
+
+## Measured performance
+
+**No throughput or latency figure is published here.** The rebuild verification was run on
+a Linux conversion box, where Core ML cannot execute at all
+(`coremltools.libcoremlpython` does not load), so no vector was computed and no timing was
+taken during that work.
+
+The ANE residency figure (99.80%, 1950/1954 ops) is the **upstream published claim**, not a
+Visible measurement. A re-measure via `MLComputePlan` is an open follow-up.
+
+The last cross-runtime quality datapoint on record is a cosine of **~0.966** between the
+Core ML leg and the LiteRT leg on short text, measured 2026-08-11 against the previously
+installed copies — not against the artifacts in this repo.
+
+## Qualification status
+
+| Artifact | Status |
+|---|---|
+| `3fa12f0b…/encoder.mlmodelc` + `model_config.json` | **SHIP** — this is the production embedding path in the Visible app, pinned by `CoreMLEmbeddingGemmaBundle`, with the compiled-in `weight.bin` SHA-256 matching. |
+| `rebuild-verification/2026-08-17/encoder.mlpackage` | **VERIFICATION EVIDENCE, not a runtime artifact.** It is uncompiled and has never been executed. Compiling it and diffing the result against the pinned `.mlmodelc` is a named open gate (below). |
+
+## Verification — the bit-exact result, stated precisely
+
+The recipe was re-run on **Debian 13 / x86_64 / torch 2.7.1+cpu / coremltools 9.0 /
+transformers 5.15.0**, against a bundle originally built on **macOS**. What reproduced:
+
+| File class | Verdict |
+|---|---|
+| `weights/weight.bin` (308,616,576 B) | **IDENTICAL** — same SHA-256 `f81f60eb…`, `cmp -l` reports **0 differing bytes**. Also equal to the app's compiled-in `CoreMLEmbeddingGemmaBundle.weightSha256`. |
+| `model_config.json` (2,351 B) | **IDENTICAL** — SHA-256 `0b949875…` |
+| tokenizer / config JSON emitted by the recipe | **IDENTICAL** — all files |
+| `encoder.mlmodelc/model.mil`, `coremldata.bin` ×2, `metadata.json` | **not produced on Linux** — these are products of `xcrun coremlcompiler`, which is Xcode/macOS-only |
+
+So the honest claim is: **everything the recipe produces reproduces exactly, across
+operating systems and CPU architectures; the remaining four files are a macOS compile step
+that could not be run and was not faked.**
+
+This is worth stating against the rest of the catalog, because it is the exception. Core AI
+`.aimodel` bundles are **not** byte-reproducible — the exporter is not deterministic even
+against itself, with two runs of an identical command nine minutes apart on the same box
+differing by 32 bytes in `main.mlirb`. For those artifacts, integrity has to rest on
+per-file SHA-256 of the exact published bytes. For this one, "verify by rebuilding" is
+genuinely available for the weights.
+
+### The open gate
+
+Compile `rebuild-verification/2026-08-17/encoder.mlpackage` with
+`xcrun coremlcompiler compile` on a Mac and diff the resulting `encoder.mlmodelc` against
+the pinned root artifact. That closes the four remaining files and would establish whether
+the *whole* Core ML artifact is reproducible or only its weights. Until then the claim is
+scoped to the weights and the config, as written above.
+
+## License
+
+EmbeddingGemma is Gemma-family. 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. Visible's contribution is
+the mirror and the rebuild verification, not the weights.