Add Cite-32M package and model card

.gitattributes

@@ -1,35 +1,5 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,158 @@
+---
+license: mit
+language:
+- en
+library_name: cite
+tags:
+- cite
+- paragraph-citation
+- retrieval
+- question-answering
+- news
+- encoder
+- modernbert
+- on-device
+pipeline_tag: text-ranking
+base_model: jhu-clsp/ettin-encoder-32m
+---
+
+# Cite
+
+Which paragraphs answer the question.
+
+A small encoder that, given a question and ordered paragraph texts, returns a
+calibrated probability per paragraph and two thresholds (`needed`,
+`contributing`).
+
+| | |
+| --- | --- |
+| **Task** | Paragraph citation / needed-blocks |
+| **Size** | ~42 MB weights (trimmed vocab, int8 embeddings, fp16 rest) |
+| **Runtime** | CPU (PyTorch); Mac MPS optional |
+| **Weights** | [v0.1.0](https://huggingface.co/localangle/cite/tree/v0.1.0) |
+| **Demo** | [localangle/cite-demo](https://huggingface.co/spaces/localangle/cite-demo) |
+
+Cite does **not** write an answer. It ranks the paragraphs you already have and
+flags which ones are needed to answer the question.
+
+> Question: *Who voted against the library renovation?*
+> → Cite highlights the paragraph naming Paulsen and Chen.
+
+## Try it
+
+- **Live demo:** [localangle/cite-demo](https://huggingface.co/spaces/localangle/cite-demo) — paste an article, ask a question, see which paragraphs Cite cites.
+- **Local playground:** from the [cite](https://github.com/localangle/cite) repo, `uv run python deploy/cite_playground.py`.
+
+## Install
+
+```bash
+pip install "cite @ git+https://github.com/localangle/cite.git"
+# or, from a checkout:
+uv sync
+```
+
+Python ≥ 3.12. Needs `torch`, `transformers`, `safetensors`, `huggingface_hub`.
+
+## Usage
+
+```python
+from cite import CitePackage
+
+cite = CitePackage.from_pretrained("localangle/cite")
+
+paragraphs = [
+    "The council approved a $4.2 million library renovation.",
+    "Paulsen and Chen voted against the measure.",
+    "Construction starts in March.",
+]
+scores = cite.predict("Who voted against the renovation?", paragraphs)
+
+for score in scores:
+    if score.needed:
+        print(score.index, score.probability, paragraphs[score.index])
+```
+
+`score.needed` uses the packaged threshold (0.71). `score.contributing` is a
+looser relatedness cut (0.15). Logits are Platt-scaled to probabilities at load
+time; you do not fit thresholds yourself for the published package.
+
+Load a local folder the same way:
+
+```python
+cite = CitePackage.load("path/to/package")  # or from_pretrained("./path")
+```
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `cite.json` | Format, Platt scaling, thresholds, source metadata |
+| `weights.safetensors` | Trimmed encoder + head (int8 token embeddings, fp16 elsewhere) |
+| `encoder/` | ModernBERT/Ettin config for the trimmed vocabulary |
+| `tokenizer/` | Tokenizer with `[MASK]` as the block marker |
+
+Weights expand to fp32 at load; only storage is compressed.
+
+## Accuracy
+
+On a held-out real-news needed-blocks eval (v59, 1,800 questions over local
+news outlets; threshold chosen on a separate calibration split):
+
+| Metric | Cite-32M package |
+| --- | --- |
+| Coverage | 0.696 |
+| Exact set match | 0.727 |
+| Empty-set accuracy | 0.895 |
+| Any-extra rate | 0.057 |
+
+Same operating point as the fp32 student within the packaging tolerance. See
+the research reports in the [cite](https://github.com/localangle/cite) repository
+(`experiments/105-cite-distill`, `experiments/106-cite-compress`).
+
+## Latency
+
+Batch-1, CPU, AMD EPYC (HF `cpu-upgrade`, 8 vCPU) for the related ONNX int8
+form: about 44 ms p50 at 5–12 paragraphs and 268 ms at 33–60. The portable
+PyTorch package this repo ships is the accuracy-matched serving artifact; long
+documents are dominated by attention cost.
+
+## How it works
+
+Cite is a fine-tuned [Ettin](https://huggingface.co/jhu-clsp/ettin-encoder-32m)
+encoder (ModernBERT family). The question and each paragraph are packed into
+one sequence with a `[MASK]` marker before every paragraph; the head reads the
+marker states. A 400M teacher labeled real news; the 32M student was distilled
+and then compressed (trimmed vocabulary, int8 embeddings, fp16 weights).
+
+## Limitations
+
+- Cite ranks paragraphs; it does not generate answers or quote spans inside a
+  paragraph.
+- Eval is English news-style text. Other domains are unmeasured.
+- Empty-set accuracy drops a few points from calibration to eval; treat the
+  packaged threshold as a starting point for a new domain.
+- Documents longer than `max_tokens` (7999) drop trailing paragraphs.
+- Training used private teacher labels and news text that is not redistributed
+  here.
+
+## Built on
+
+- [Ettin encoder 32M](https://huggingface.co/jhu-clsp/ettin-encoder-32m) (MIT)
+  by JHU CLSP. Fine-tuned and compressed for Cite; see
+  `THIRD_PARTY_NOTICES.md`.
+
+## License
+
+MIT for the Cite code and this package's weights, subject to the Ettin MIT
+notice above.
+
+## Citation
+
+```bibtex
+@software{cite_2026,
+  title  = {Cite: Which paragraphs answer the question},
+  author = {Local Angle},
+  year   = {2026},
+  url    = {https://huggingface.co/localangle/cite},
+}
+```

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Ettin / ModernBERT backbone
+
+This package's encoder is derived from
+[`jhu-clsp/ettin-encoder-32m`](https://huggingface.co/jhu-clsp/ettin-encoder-32m)
+(MIT License). Cite fine-tunes and compresses those weights; the original
+license terms continue to apply to the Ettin contribution.
+
+Paper: Weller et al., "Ettin: an Open Suite of Paired Encoders and Decoders"
+(arXiv:2507.11412).

cite.json

@@ -0,0 +1,26 @@
+{
+  "format": "cite-package-1",
+  "kept": 41655,
+  "marker": "mask",
+  "max_tokens": 7999,
+  "platt": {
+    "bias": 0.28167128937742075,
+    "slope": 0.6159961343551152
+  },
+  "readout": "mlm_head",
+  "source": {
+    "base_model": {
+      "repo": "jhu-clsp/ettin-encoder-32m",
+      "revision": "1b8ba06455dd44f80fc9c1ca9e22806157a57379"
+    },
+    "experiment": "experiments/106-cite-compress",
+    "student": "cjdd3b/angle-core-private-evals/105-clip-32m-distill"
+  },
+  "storage": "token embeddings int8 per row; other weights fp16; computed in fp32",
+  "thresholds": {
+    "contributing": 0.15,
+    "needed": 0.71,
+    "needed_rule": "lowest threshold with graf_calibration empty-set accuracy >= 0.93 (104 amendment), per variant"
+  },
+  "vocabulary_full": 50368
+}

encoder/config.json

@@ -0,0 +1,67 @@
+{
+  "architectures": [
+    "ModernBertModel"
+  ],
+  "attention_bias": false,
+  "attention_dropout": 0.0,
+  "bos_token_id": 41651,
+  "causal_mask": false,
+  "classifier_activation": "gelu",
+  "classifier_bias": false,
+  "classifier_dropout": 0.0,
+  "classifier_pooling": "mean",
+  "cls_token_id": 41651,
+  "decoder_bias": true,
+  "deterministic_flash_attn": false,
+  "dtype": "float32",
+  "embedding_dropout": 0.0,
+  "eos_token_id": 41652,
+  "global_attn_every_n_layers": 3,
+  "gradient_checkpointing": false,
+  "hidden_activation": "gelu",
+  "hidden_size": 384,
+  "initializer_cutoff_factor": 2.0,
+  "initializer_range": 0.02,
+  "intermediate_size": 576,
+  "is_causal": false,
+  "layer_norm_eps": 1e-05,
+  "layer_types": [
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention"
+  ],
+  "local_attention": 128,
+  "max_position_embeddings": 7999,
+  "mlp_bias": false,
+  "mlp_dropout": 0.0,
+  "model_type": "modernbert",
+  "norm_bias": false,
+  "norm_eps": 1e-05,
+  "num_attention_heads": 6,
+  "num_hidden_layers": 10,
+  "pad_token_id": 41653,
+  "position_embedding_type": "sans_pos",
+  "rope_parameters": {
+    "full_attention": {
+      "rope_theta": 160000.0,
+      "rope_type": "default"
+    },
+    "sliding_attention": {
+      "rope_theta": 160000.0,
+      "rope_type": "default"
+    }
+  },
+  "sep_token_id": 41652,
+  "sparse_pred_ignore_index": -100,
+  "sparse_prediction": false,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.17.0",
+  "vocab_size": 41655
+}

tokenizer/tokenizer_config.json

@@ -0,0 +1,17 @@
+{
+  "backend": "tokenizers",
+  "clean_up_tokenization_spaces": true,
+  "cls_token": "[CLS]",
+  "is_local": false,
+  "local_files_only": false,
+  "mask_token": "[MASK]",
+  "model_input_names": [
+    "input_ids",
+    "attention_mask"
+  ],
+  "model_max_length": 8192,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "tokenizer_class": "TokenizersBackend",
+  "unk_token": "[UNK]"
+}

weights.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:88110b9fe6cbd84b5534e5957322d8e925bdae8785aefbec3771a8263a639aba
+size 41750550