update model card

README.md

@@ -8,41 +8,110 @@ language: [en]
 datasets: [jaredpalmer/kev-suites]
 ---
 
-# tinyjev-0.6b
+<div align="center">
 
-A tiny typed-decision model: a state plus typed questions (`choice`, `noul` yes/no, `score`) in, calibrated
-probabilities out, one forward pass, no text generation. Runs on MLX (Apple Silicon) or PyTorch.
-Code, every benchmark file and the research trail: **https://github.com/ankit-aglawe/tinyjev**
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ankit-aglawe/tinyjev/main/assets/tinyjev_header_dark.png">
+  <img alt="TinyJev" src="https://raw.githubusercontent.com/ankit-aglawe/tinyjev/main/assets/tinyjev_header.png" width="620">
+</picture>
 
-| | transfer-v4 dev | transfer-v4 test (read once) | ECE (test) |
-|---|---|---|---|
-| **tinyjev-0.6b** | **0.625** | **0.663** | 0.082 |
-| Kev-0.6B published (same base) | 0.620 | 0.642 | — |
-| Kev-4B published | 0.797 | 0.837 | — |
+<p>Typed decisions, on your laptop, in one forward pass.</p>
 
-Scored on Kev's frozen held-out suite with Kev's own harness. This is the same-size public anchor's level,
-slightly ahead on the locked test with lower ECE; it is not 4B-class. Full-fine-tuning, distillation from
-Kev-4B and a 149M encoder all failed to beat it — the numbers are in the GitHub README.
+<p>
+  <a href="https://github.com/ankit-aglawe/tinyjev">GitHub</a> ·
+  <a href="https://pypi.org/project/tinyjev/">PyPI</a> ·
+  <a href="https://github.com/ankit-aglawe/tinyjev/tree/main/examples">Examples</a>
+</p>
+
+</div>
+
+Send this model some state, a ticket or a record or a log line, plus questions with the answers you
+will accept. It returns a probability for every option you offered. It cannot answer with anything
+else, because it never generates text; it scores the options you gave it and stops.
+
+- `Choice` picks one option from a list, with a probability for each.
+- `Noul` measures whether a statement is true.
+- `Score` places state on an ordered scale.
+- Confidence is calibrated, so a threshold means something.
+
+596M parameters, about 1.2 GB. MLX on Apple Silicon, PyTorch everywhere else, fully offline.
+
+## Watch it decide
+
+<div align="center">
+  <img alt="TinyJev triaging support tickets" src="https://raw.githubusercontent.com/ankit-aglawe/tinyjev/main/assets/demo_triage.gif" width="860">
+</div>
+
+Eight real support tickets, three questions each in a single forward pass, about 110 ms per ticket on
+a base M1. Half route themselves. The other half do not: ticket six is late, the wrong size and double
+charged all at once, so probability spreads across all three teams and confidence falls to 0.14. Below
+the gate it goes to a person rather than being guessed at.
+
+## Use it
 
 ```bash
-pip install 'tinyjev[mlx]'     # Apple Silicon   |   pip install 'tinyjev[torch]'  # elsewhere
+pip install 'tinyjev[mlx]'     # Apple Silicon
+pip install 'tinyjev[torch]'   # everything else
 ```
 
 ```python
 import tinyjev
 agent = tinyjev.load("tinyjev-0.6b")
-agent.predict({"state": "I was charged twice. Please fix this ASAP.",
-               "questions": {"billing": {"type": "noul", "instructions": "Is this ticket about billing?"},
-                             "tone": {"type": "choice", "instructions": "What is the customer's tone?",
-                                      "criteria": {"calm": None, "frustrated": None, "angry": None}}}})
+
+agent.predict({
+    "state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges on my card.",
+    "questions": {
+        "team":     {"type": "choice", "instructions": "Which team should handle this?",
+                     "criteria": {"returns": "Exchanges, refunds, wrong or damaged items",
+                                  "shipping": "Delivery status, delays, lost packages",
+                                  "billing":  "Charges, invoices, payment problems"}},
+        "escalate": {"type": "noul",   "instructions": "Does this need urgent human attention?"},
+        "anger":    {"type": "score",  "instructions": "How angry is the customer?",
+                     "criteria": ["calm", "frustrated", "very angry"]},
+    }})
 ```
 
-`AutoModel.from_pretrained("AnkitAI/tinyjev-0.6b")` loads the backbone (a standard `Qwen3Model`, fp16); the
-decision head is in `head.safetensors` and needs `tinyjev` to turn hidden states into decisions.
+On Apple Silicon you can quantize as it loads. Eight bits is free: half the memory, slightly faster,
+and it scored identically to full precision on our held-out set.
+
+```python
+agent = tinyjev.load("tinyjev-0.6b", quantize=8)
+```
+
+Serve it over HTTP, speaking the System One request shape:
+
+```bash
+tinyjev serve tinyjev-0.6b        # POST /v1/systemone on 127.0.0.1:8077
+```
+
+## What is in this repo
+
+`AutoModel.from_pretrained("AnkitAI/tinyjev-0.6b")` loads the backbone on its own, a standard
+`Qwen3Model` in fp16. The decision head lives in `head.safetensors`, and `tinyjev` is what turns hidden
+states into calibrated answers.
+
+## How it was built, and how it scores
+
+Qwen3-0.6B-Base with a pointer head, LoRA r16 at lr 5e-5 merged back into the base, trained on the
+public `jaredpalmer/kev-suites` decision-v7 split. No held-out transfer source was used in training.
+A fitted temperature of 1.46 is applied at inference.
+
+| | transfer-v4 dev | transfer-v4 test, read once | ECE on test |
+| --- | --- | --- | --- |
+| tinyjev-0.6b | 0.625 | 0.663 | 0.082 |
+| Same-size public anchor | 0.620 | 0.642 | — |
+
+Scored with the upstream harness on its frozen held-out suite. This matches the same-size public anchor
+and edges ahead on the locked test with lower calibration error. It is not 4B-class, and it is not
+meant to be. Full fine-tuning, distillation from a 4B teacher, and a 149M encoder were all tried and
+all lost to the configuration above.
+
+It will not play games. Given state that is already structured and numeric, it stops discriminating;
+its competence is judgment about language. Use the confidence gate on anything far from what it saw.
 
-Architecture: Qwen3-0.6B-Base + a pointer head (Kev's design), LoRA r16 at lr 5e-5 merged into the base,
-trained on `jaredpalmer/kev-suites` decision-v7 (public sources + generated policy examples; no transfer-v4/v9
-holdout source used). Fitted temperature 1.46 is applied at inference. On a base M1 via MLX: 65 ms per
-request fp16, INT8 free, 4-bit −2.1 points.
+## Credits
 
-MIT. Base Qwen3-0.6B-Base (Apache-2.0). Training data, harness and head design from Kev (Apache-2.0).
+Built on [Qwen3-0.6B-Base](https://huggingface.co/Qwen/Qwen3-0.6B-Base) (Apache-2.0). The training data,
+evaluation suites and the pointer-head design come from [Kev](https://github.com/jaredpalmer/kev) by
+Jared Palmer (Apache-2.0). The typed-decision interface follows
+[TypeSafe's Jev](https://docs.typesafe.ai/introduction). MIT licensed.