docs: simplify and align model card

README.md

@@ -16,197 +16,181 @@ pipeline_tag: feature-extraction
 
 # constella-zero
 
-**constella-zero** is the smallest query encoder in an asymmetric retrieval family. Documents are
-indexed once, in the cloud, with the frozen
-[`stella-en-400M-v5-doc-onnx`](https://huggingface.co/DylanCouzon/stella-en-400M-v5-doc-onnx)
-tower; Zero or the stronger [`constella-nano`](https://huggingface.co/DylanCouzon/constella-nano)
-can then query that same 1024-dimensional index without re-encoding it. Zero is a 30,522 × 1024
-int8 lookup table—not a transformer—so encoding is a gather and weighted sum.
+constella-zero is a small English query encoder for semantic search. It uses an int8 token lookup
+table instead of a transformer, making it useful when query latency matters more than maximum
+retrieval quality.
 
-> **Research preview.** The registered reserved-four evaluation and broad descriptive BEIR-18
-> validation are pending and unspent; no result is claimed for either. The three models are
-> registered on the preview branch below, not in an upstream FastEmbed release yet.
+It produces normalized 1024-dimensional vectors that search documents encoded by
+[`stella-en-400M-v5-doc-onnx`](https://huggingface.co/DylanCouzon/stella-en-400M-v5-doc-onnx).
+The same document index also works with the stronger
+[`constella-nano`](https://huggingface.co/DylanCouzon/constella-nano) query encoder.
 
-## Usage
+| Property | Value |
+|---|---|
+| Role | Query encoder |
+| Output | 1024-dimensional normalized fp32 vector |
+| Architecture | 30,522 x 1,024 int8 token lookup table |
+| Languages | English |
+| Maximum input length | 512 tokens |
+| Query prefix | None |
+| Document encoder | `DylanCouzon/stella-en-400M-v5-doc-onnx` |
+
+## Installation
+
+Native FastEmbed support is currently available from the Constella preview branch:
 
 ```console
 pip install "fastembed @ git+https://github.com/Dylancouzon/fastembed.git@constella-research-preview"
 pip install qdrant-client
 ```
 
+## Usage
+
+Encode documents once with the document model, then encode queries with constella-zero. The
+example below creates an in-memory Qdrant collection, but the vectors can be used with any vector
+database that supports cosine similarity.
+
 ```python
-import numpy as np
 from fastembed import TextEmbedding
+from qdrant_client import QdrantClient, models
 
 NAME = "DylanCouzon/constella-zero"
-query_model = TextEmbedding(NAME)
-q = np.asarray(next(iter(query_model.embed(["how do mrna vaccines work?"]))))
-assert q.shape == (1024,) and q.dtype == np.float32
-```
-
-FastEmbed fetches `model.onnx` and the tokenizer. Pooling and L2 normalization happen inside the
-graph.
-
-### The document side
-
-```python
 DOC_NAME = "DylanCouzon/stella-en-400M-v5-doc-onnx"
-doc_model = TextEmbedding(DOC_NAME)
-docs = [
+
+documents = [
     "mRNA vaccines deliver messenger RNA encoding a viral antigen.",
     "The Treaty of Westphalia ended the Thirty Years' War in 1648.",
 ]
-D = np.stack(list(doc_model.embed(docs)))
-assert D.shape == (2, 1024) and D.dtype == np.float32
-```
-
-The document tower runs once per document; Zero runs on every query. Do not use the document
-model's unprompted path as a Stella query encoder.
 
-### With Qdrant
-
-```python
-from qdrant_client import QdrantClient, models
+document_model = TextEmbedding(DOC_NAME)
 
 client = QdrantClient(":memory:")
 client.create_collection(
-    "docs", vectors_config=models.VectorParams(size=1024, distance=models.Distance.COSINE)
+    "documents",
+    vectors_config=models.VectorParams(size=1024, distance=models.Distance.COSINE),
 )
 client.upsert(
-    "docs",
+    "documents",
     points=[
-        models.PointStruct(id=i, vector=D[i].tolist(), payload={"text": text})
-        for i, text in enumerate(docs)
+        models.PointStruct(id=i, vector=embedding.tolist(), payload={"text": text})
+        for i, (text, embedding) in enumerate(
+            zip(documents, document_model.embed(documents))
+        )
     ],
 )
-hits = client.query_points("docs", query=q.tolist(), limit=2).points
-print(hits[0].payload["text"])
+
+query_model = TextEmbedding(NAME)
+query_embedding = next(iter(query_model.embed(["how do mRNA vaccines work?"])))
+results = client.query_points(
+    "documents", query=query_embedding.tolist(), limit=2
+).points
+
+for result in results:
+    print(result.score, result.payload["text"])
 ```
 
-### Without FastEmbed
+FastEmbed handles pooling and L2 normalization. Do not use the document model as an unprompted
+query encoder. Use constella-zero, constella-nano, or Stella's prompted query path instead.
 
-`zero_encoder.py` is the NumPy/tokenizers reference path:
+### NumPy reference implementation
+
+The repository also includes `zero_encoder.py`, a reference implementation that does not require
+FastEmbed or ONNX Runtime:
 
 ```python
 from huggingface_hub import snapshot_download
 import sys
 
-d = snapshot_download("DylanCouzon/constella-zero")
-sys.path.insert(0, d)
+model_directory = snapshot_download("DylanCouzon/constella-zero")
+sys.path.insert(0, model_directory)
+
 from zero_encoder import ZeroQueryEncoder
 
-enc = ZeroQueryEncoder(d, variant="int8")
-q_np = enc.encode(["how do mrna vaccines work?"])
-assert np.abs(q_np[0] - q).max() < 1e-5
+model = ZeroQueryEncoder(model_directory, variant="int8")
+query_embeddings = model.encode(["how do mRNA vaccines work?"])
 ```
 
-Zero and Nano share a document space, not a retrieval-quality guarantee: they have different
-measured behavior, and interchangeability does not mean parity, equivalence, or a tie.
-
 ## How it works
 
-Tokenize with WordPiece, special tokens on, no prefix, and truncation at 512 tokens. A token that
-appears `c` times carries total weight `sqrt(c)`, so repetition saturates. The graph sums the rows,
-divides by the weight sum, and L2-normalizes; an empty or near-zero bag falls back to normalized
-`[CLS]`. Learned token weights are folded into the rows. This is still a bag of tokens: word order,
-negation, and syntax are not represented.
+The encoder tokenizes each query with WordPiece, looks up a learned vector for every token, and
+combines those vectors into one query embedding. Repeated tokens receive diminishing weight: a
+token that occurs `c` times contributes a total weight of `sqrt(c)`. The result is L2-normalized.
 
-The reported model is int8, which was within 0.00013 nDCG@10 of fp16.
+This is a bag-of-tokens model. It does not represent word order, syntax, or negation directly.
+Learned token weights are already included in the table.
 
-## Files
-
-| file | purpose | size |
-|---|---|---:|
-| `model.onnx` | FastEmbed/ONNX Runtime; pooled normalized `(batch, 1024)` output | 31 MB |
-| `model_tokens.onnx` | token-level `(batch, sequence, 1024)` output | 31 MB |
-| `model.npz` | NumPy reference path | 94 MB |
+## Retrieval results
 
-Both graphs use opset 17 and standard operators. The int8 table is dequantized in-graph with one
-fp32 scale per row. Tokenizer metadata enforces the frozen 512-token rule and dynamic padding.
+The table reports exact-search nDCG@10. ArguAna and FiQA are marked because the Stella teacher
+discloses training or evaluation contact with those datasets. Results on those two datasets should
+therefore be interpreted separately from the other four.
 
-## Results
-
-The headline partition is **clean-4**: NFCorpus, SCIDOCS, SciFact, and TREC-COVID. ArguAna and
-FiQA remain beside it with `†` because Stella discloses training/evaluation contact with them.
-All values are exact-search nDCG@10.
-
-| system | NFCorpus **(clean-4)** | SCIDOCS **(clean-4)** | SciFact **(clean-4)** | TREC-COVID **(clean-4)** | ArguAna† | FiQA† |
+| System | NFCorpus | SCIDOCS | SciFact | TREC-COVID | ArguAna* | FiQA* |
 |---|---:|---:|---:|---:|---:|---:|
-| constella-zero (int8) | 0.3124 | 0.1677 | 0.6101 | 0.5490 | 0.5916 | 0.3728 |
+| constella-zero | 0.3124 | 0.1677 | 0.6101 | 0.5490 | 0.5916 | 0.3728 |
 | constella-nano | 0.363080 | 0.217710 | 0.721097 | 0.787116 | 0.623296 | 0.477765 |
 | BM25 | 0.3180 | 0.1565 | 0.6791 | 0.6099 | 0.4878 | 0.2532 |
-| Stella teacher, symmetric | 0.4134 | 0.2395 | 0.7796 | 0.8234 | 0.6369 | 0.5536 |
-
-† Stella-disclosed training/evaluation contact; excluded from clean-4.
-
-Zero did **not** confirmatorily beat BM25. M7 C2 was +0.0165 across all six with raw 95% interval
-[+0.0017, +0.0311], but its sign-flip p=0.0149 failed the Holm threshold of 0.0083. On clean-4,
-the descriptive contrast was -0.0311 [-0.0517, -0.0109], with Zero at 0.4098 versus BM25 at
-0.4409. Superiority is **UNESTABLISHED**.
-
-The deployable hybrid recommendation and registered operator of record are distinct:
+| Stella query encoder | 0.4134 | 0.2395 | 0.7796 | 0.8234 | 0.6369 | 0.5536 |
 
-| Zero + BM25 fusion | prefetch | all-six macro | clean-4 macro |
-|---|---:|---:|---:|
-| Qdrant DBSF | 100 | 0.4887 | 0.4912 |
-| M7 convex0 (`w=0.8`) | 1000 | 0.4911 | 0.4866 |
+Note: Stella discloses training or evaluation contact with ArguAna and FiQA.
 
-Both rows use `bm25s` with Lucene defaults as the lexical side, not Qdrant's own BM25, which has a
-fixed `avg_len` and its own tokenizer — DBSF normalises over returned scores, so a different
-lexical implementation shifts its inputs. For the DBSF row, each query's own document is excluded
-*before* the prefetch is truncated to 100 (`must_not` on the point id); without that filter a
-plain `limit: 100` spends a slot on the self-match. That affects only ArguAna (1,298 of 1,406
-queries) and FiQA (55), so the clean-4 figures are unchanged either way.
+For hybrid retrieval, combine constella-zero with BM25 using Qdrant's distribution-based score
+fusion (DBSF) and prefetch 100 candidates from each side. This setup scored 0.4887 mean nDCG@10
+across all six datasets and 0.4912 across the four datasets without disclosed Stella contact.
+The evaluated lexical side used `bm25s` with Lucene defaults, so results may differ with another
+BM25 implementation.
 
-Use Qdrant DBSF at prefetch 100 in deployments. M7's convex0 is the registered operator of record,
-but Qdrant does not implement it. No confidence interval compared these observations, so neither
-superiority nor equivalence is established. M7 C3 likewise did not establish fusion superiority
-over OpenSearch: +0.0043, raw 95% interval [-0.0063, +0.0151], p=0.219.
+Zero did not establish an improvement over BM25 in the six-dataset statistical test. Its measured
+difference was +0.0165 nDCG@10, but the adjusted test threshold was not met. This is not an
+equivalence claim.
 
-Full per-dataset fusion rows, registered contrasts, and source traces are in the
-[M21 benchmark ledger](https://github.com/Dylancouzon/asymmetric-dual-encoders/blob/main/m21/BENCHMARKS.md).
+## Query encoding cost
 
-## Limits
+These measurements cover the query encoder only. They use batch size 1, four CPU threads, five
+warmups, and twenty synthetic 20-word queries in each of three fresh processes. They do not
+include vector search or end-to-end application latency.
 
-- Reserved-four and BEIR-18 evidence is pending and unspent; the six datasets do not establish
-  broad domain coverage.
-- Stella contact with ArguAna and FiQA makes all-six results secondary to clean-4.
-- Zero is an English-only bag of tokens and truncates beyond 512 wordpieces.
-- The document side is not cheap: the 400M-parameter Stella tower still runs at indexing time.
-
-## Costs
-
-These are synthetic query latencies, not workload estimates. The common three-model protocol used
-three fresh processes per model, batch one, four CPU threads; hydration includes imports,
-verification, and load but excludes interpreter startup; first inference is separate; warm timing
-uses five warmups and twenty 20-word samples; the OS disk cache was not flushed.
-
-| model | hydration | first query | warm 20-word p50 | peak RSS | model assets |
+| Model | Load time | First query | Warm query p50 | Peak RSS | Measured assets |
 |---|---:|---:|---:|---:|---:|
 | constella-zero | 0.2618 s | 0.3529 ms | 0.1119 ms | 275.4 MiB | 90.1 MiB |
 | bge-small | 0.6726 s | 8.2401 ms | 6.8400 ms | 291.0 MiB | 127.6 MiB |
 | constella-nano | 0.6907 s | 7.6685 ms | 7.2511 ms | 280.9 MiB | 132.3 MiB |
 
-This measures query encoders only, not retrieval, ANN, or end-to-end system latency. The asset
-column follows the common protocol; `model.onnx` itself is the 31 MB query graph listed above.
+## Files
+
+| File | Purpose | Size |
+|---|---|---:|
+| `model.onnx` | Pooled and normalized FastEmbed graph | 31 MB |
+| `model_tokens.onnx` | Token-level output for custom pooling | 31 MB |
+| `model.npz` | NumPy reference implementation | 94 MB |
+
+Both ONNX graphs use opset 17 and standard operators. The int8 table is dequantized inside the
+graph with one fp32 scale per row.
 
 ## Training
 
-The table was trained by L2 regression against Stella query embeddings over 340,850 pairs plus
-220,632 query-only rows from Amazon ESCI, FEVER, HotpotQA, SQuAD, NQ Open, TriviaQA, and Mr. TyDi
-(English); MS MARCO was excluded. Wikipedia-derived sources retain CC BY-SA attribution; ESCI and
-TriviaQA are Apache-2.0.
+The released table was trained by L2 regression against Stella query embeddings. Training used
+338,076 usable query-document pairs plus 220,632 query-only rows from Amazon ESCI, FEVER,
+HotpotQA, SQuAD, NQ Open, TriviaQA, and Mr. TyDi English. MS MARCO was excluded.
 
-## Provenance
+Wikipedia-derived data retains CC BY-SA attribution. Amazon ESCI and TriviaQA are Apache-2.0.
 
-```text
-run_id      p35w-2m-s2500
-table       a7007b1a6af120b976f093fd69ddcb5001996ec0b84b5864b4fd25d7af878abf
-teacher     NovaSearch/stella_en_400M_v5 @ ffeb2b7ee715c226d4ffe5e4619f7dbb48624c20
-comparator  BAAI/bge-small-en-v1.5 @ 5c38ec7c405ec4b44b94cc5a9bb96e735b38267a
-preproc     prefix="" · special tokens · max_length=512 · pool_mode=sqrt
-fingerprint adb24fb2e8cad66f
-```
+## Limitations
+
+- The model is English-only and truncates inputs after 512 tokens.
+- As a bag-of-tokens model, it is weak at distinctions that depend on word order, syntax, or
+  negation.
+- Retrieval quality is lower than constella-nano and the full Stella query encoder on the six
+  reported datasets.
+- Document indexing still requires the 400M-parameter Stella document encoder.
+- The reported retrieval evaluation covers six datasets and does not establish performance in
+  other domains or applications.
+
+## License and provenance
+
+The model is MIT licensed. It was distilled from
+[`NovaSearch/stella_en_400M_v5`](https://huggingface.co/NovaSearch/stella_en_400M_v5) at revision
+`ffeb2b7ee715c226d4ffe5e4619f7dbb48624c20`, which is also MIT licensed.
 
-The weights are MIT licensed. The pinned Stella teacher/document tower and bge-small comparator
-are also MIT and are attributed above.
+The released int8 table has SHA-256
+`a7007b1a6af120b976f093fd69ddcb5001996ec0b84b5864b4fd25d7af878abf`.