Usage: validated in-process and HTTP paths

klev is a library first, so the card now leads with an in-process call rather than a server. model/infer.py is the shared core: it reuses data/encoding.py, data/format.py and model/head.py with the scorer rather than reimplementing them, so the probabilities a user sees are the ones eval/eval_decisions.py measures. Plus examples/system_one.py for the shell and serve/server.py for when HTTP is actually wanted.

Every snippet was executed. Real output is pasted, not illustrative: noul p(true)=0.9169, choice atm 0.6136, score 1.485, rejection 0.168 and 0.027. The temperature table is called out because head.pt stores 1.0 (written during training; the head only tempers in eval mode) and serving raw costs 0.08 ECE.

The server routes match kev's own shapes, so eval/eval_systemone_http.py scores it unmodified -- verified over 120 decision-v7 development rows, zero failures. Also records that the ~195-token ceiling on the RX 6600M is a training limit only: a 703-token row was served 200 with the correct answer on that card.

README.md

@@ -239,33 +239,107 @@ Probe hyperparameters (in `stitch/probe-*.pt`): TweetEval `T = 105.19`, `beta =
 
 ## Usage
 
-Built and served with Unsloth — `import unsloth` must come **before** `transformers` / `peft`
-(it patches them at import time), which is why it is first below.
+klev is a **library first**. A decision model is small and stateless, so the normal way to use
+one is in-process: load it once, call it as many times as you like. No server, no port, no
+daemon. `import unsloth` must come **before** `transformers` / `peft` (it patches them at import
+time), which is why it is first.
 
 ```python
-import unsloth  # noqa: F401  — must precede transformers / peft / trl
-import torch
-from huggingface_hub import snapshot_download
-from peft import PeftModel
-from unsloth import FastModel
-
-DELIMITERS = ["<|fim_prefix|>", "<|fim_suffix|>", "<|fim_middle|>",
-              "<|fim_pad|>", "<|repo_name|>"]
-
-ckpt = snapshot_download("lumierenoir/klev-0.8b", allow_patterns=["adapter/*", "head.pt"])
-model, processor = FastModel.from_pretrained(
-    "Qwen/Qwen3.5-0.8B", max_seq_length=2048, load_in_4bit=True)
-tokenizer = getattr(processor, "tokenizer", processor)
-tokenizer.add_special_tokens({"additional_special_tokens": DELIMITERS})
-model = PeftModel.from_pretrained(model, f"{ckpt}/adapter")
-saved = torch.load(f"{ckpt}/head.pt", map_location="cpu", weights_only=False)
-# apply saved["deltas"]["embed_tokens"] to the 5 delimiter rows and saved["head"] to
-# PointerHead(1024, dp=256, garbage=True), then read decisions exactly as in
-# eval/eval_decisions.py (code repo).
+import unsloth  # noqa: F401  — must precede transformers / peft
+from model.infer import load_klev, answer      # from github.com/felipepenhorate/klev
+
+model, tokenizer, head = load_klev("lumierenoir/klev-0.8b")   # or a local dir with adapter/ + head.pt
+
+result = answer(model, tokenizer, head, {
+    "state": "My card was declined twice at a supermarket and the ATM refused it too.",
+    "questions": {
+        "is_card": {"type": "noul",   "instructions": "Is the card being declined?",
+                    "criteria": {"false": "no", "true": "yes"}},
+        "action":  {"type": "choice", "instructions": "What should the agent do first?",
+                    "criteria": {"usage": "ask how the card was used",
+                                 "atm":   "raise an ATM fault",
+                                 "fraud": "run a fraud check"}},
+        "urgency": {"type": "score",  "instructions": "How urgent is this?",
+                    "criteria": ["no action needed", "next working day", "same day", "immediate"]},
+    }},
+    temperature=2.2974)
 ```
 
-The 5 delimiter ids are 248060, 248062, 248061, 248063, 248064 on this base. If you change the
-base, the ids must be re-derived with `tokenizer.convert_tokens_to_ids` — do not assume them.
+Verified output from that request:
+
+```json
+{"answers": {
+  "is_card": {"type": "noul", "noul": 0.9169, "none": 0.01314},
+  "action":  {"type": "choice", "choice": "atm", "confidence": 0.4848,
+              "probabilities": {"usage": 0.1311, "atm": 0.6136, "fraud": 0.0870},
+              "none": 0.16828},
+  "urgency": {"type": "score", "score": 1.485, "legend": {"0": "no action needed",
+              "1": "next working day", "2": "same day", "3": "immediate"},
+              "probabilities": {"0": 0.2936, "1": 0.2397, "2": 0.1817, "3": 0.2580, "4": 0.0270},
+              "confidence": 0.6288, "none": 0.026994}}}
+```
+
+`none` is the **rejection channel**: the mass on "none of these apply", renormalised off the K
+options so the returned distribution still sums to 1.
+
+The three question types are `noul` (`criteria` = `{false, true}`), `choice` (`criteria` = an
+option map) and `score` (`criteria` = an ordered level list). A request is validated by
+klev's own `SystemOneRequest` before any GPU work, and labels / `target` / `_meta` are ignored —
+so a labelled eval record can be passed straight through.
+
+**Temperature matters.** `answer(..., temperature=1.0)` is the **raw** readout, which is what the
+benchmark tables above score (ECE 0.113 on decision-v7 dev). The *served* numbers use the
+per-model temperature from `scripts/calibrate.py`:
+
+| arm | serve at |
+|---|---|
+| `lumierenoir/klev-0.8b` (IT) | **2.2974** |
+| `lumierenoir/klev-0.8b` + `/base` | **2.2449** |
+
+`head.pt` stores `1.0`, because it is written during training and the head only tempers in eval
+mode — so a deployment has to supply the fitted value itself. That is the one thing easy to get
+wrong, and it is worth 0.08 ECE.
+
+### From a shell, still no server
+
+```bash
+python examples/system_one.py --ckpt lumierenoir/klev-0.8b                    # built-in demo
+python examples/system_one.py --ckpt lumierenoir/klev-0.8b --request r.json  # your request
+echo '{"state":"...","questions":{...}}' | python examples/system_one.py --ckpt ... --request -
+```
+
+which ends with a plain-language readback — the quickest way to sanity-check a checkpoint. The
+built-in demo request (a card decline, with 2 options and a 4-level severity scale):
+
+```
+channel_issue  noul    p(true)=0.885  -> yes   reject=0.015
+next_step      choice  -> atm_fault   conf=0.371  reject=0.193
+severity       score   -> 1.52        reject=0.025
+```
+
+### If you would rather have HTTP
+
+Worth it when several processes share one warm copy of the weights, or when the caller is not
+Python. Otherwise it adds a port and a failure mode to save ~1 GB of load time.
+
+```bash
+python serve/server.py --ckpt lumierenoir/klev-0.8b --port 8090 --temperature 2.2974
+curl -s localhost:8090/v1/systemone -H 'content-type: application/json' -d @request.json
+```
+
+| route | |
+|---|---|
+| `POST /v1/systemone` | `{"state", "questions"}` → `{"answers": {qid: typed answer}}` |
+| `GET /v1/models` | loaded base, temperature, whether the rejection channel exists |
+| `GET /health` | `{"ok": true, "model": ...}` |
+
+Same routes and response shapes as `kev`'s own server, so `eval/eval_systemone_http.py` scores
+it on the bench records **unmodified** — verified here over 120 decision-v7 development rows with
+zero failures. It is stdlib `http.server` on purpose: no fastapi/uvicorn to install. One
+decision per request under a lock, since a forward is not re-entrant.
+
+Validated locally: 703-token decision-v7 row served `200` with the correct answer, malformed
+bodies `400`, unknown routes `404`, and rows over `--max-seq` `400` naming the token count.
 
 ## License and data