Upload README.md with huggingface_hub

README.md

@@ -47,27 +47,34 @@ model-index:
 
 # MIMIR-1
 
-**English-only, non-generative decision model.** Give it a **context**, a **question** and
-the **options**; it returns a typed answer with calibrated probabilities, the parts of
-the context it relied on, and a certified signal for when to act and when to escalate.
-419M parameters: a ModernBERT-Large encoder plus a decision head that refines one readout
-per iteration over four iterations, with a certified early exit at depth 2. It never
-generates text, so there is nothing to parse and nothing to hallucinate.
+**Decisions your agents can act on.** MIMIR is an English-only, non-generative decision
+model: give it a **context**, a **question** and the **options**, and it returns a typed
+answer with calibrated probabilities, the parts of the context it relied on, and a
+certified signal for when to act and when to escalate. It never generates text, so there
+is nothing to parse and nothing to hallucinate.
+
+**419M parameters** — a ModernBERT-Large encoder plus a decision head that refines one
+readout per iteration over four iterations, with a certified early exit at depth 2.
+Against Laya and GLiNER2.5-Decide, each run by us on identical records, it leads both on
+six of ten tasks: **+54.7 points on Banking77, +42.3 on MASSIVE English, +36.3 on typed
+decisions, +27.6 on prompt injections**. Where it cannot back an answer it abstains
+instead of guessing. Built for the decision layer under agents: routing requests, gating
+tool calls, verifying claims.
 
 ## Installation
 
+The `mimirai` package is launched and is the way to use this model:
+
 ```bash
-pip install "mimirai[local]"
+pip install "mimirai[local]"      # CPU engine
+pip install "mimirai[local-gpu]"  # CUDA engine
+pip install mimirai               # data models and HTTP client only
 ```
 
-Python 3.12. `mimirai` is the package, `mimir` the import.
+Python 3.11 or later. `mimirai` is the package, `mimir` the import.
 
 ## Quickstart
 
-> **Three outcomes, not two.** Every call ends `DECIDED`, `ABSTAINED` or `DEFERRED`.
-> `ABSTAINED` means none of the listed options is supported; `DEFERRED` means the
-> certificate does not cover this call at your risk level. Both are answers, not errors.
-
 ```python
 from mimir import Mimir
 
@@ -78,32 +85,39 @@ result = model.choose(
     "Which team should handle this?",
     options={"billing": "Billing: payments, refunds", "security": "Security: account access"},
 )
-print(result.status)  # DECIDED
-print(result.answer)  # billing, with calibrated probabilities over the options
+print(result.status)          # DECIDED
+print(result.answer)          # billing
+print(result.probabilities)   # calibrated probability of each option
+print(result.certificate)     # the certified threshold the decision was checked against
 ```
 
-## Calibrate for tighter guarantees
-
-The shipped policy is certified on 95,550 held-out records (see
-[Certificate](#certificate)), but a policy fit on your own decisions is where the
-guarantees get tight. Calibrate from your context/decision/label triples:
+> **Three outcomes, not two.** Every call ends `DECIDED`, `ABSTAINED` or `DEFERRED`.
+> `ABSTAINED` means none of the listed options is supported; `DEFERRED` means the
+> certificate does not cover this call at your risk level — `result.deferral.reason` says
+> why (`below_threshold`, `out_of_distribution` or `no_certified_threshold`). Both are
+> answers, not errors: a decision layer that cannot refuse is a random generator with
+> calibrated-looking outputs.
 
-```python
-from mimir import Mimir
-from mimir.core.labels import LabelledDecision
-from mimir.runtime.calibrate import calibrate
+## What it decides
 
-model = Mimir.from_pretrained("Mythologic/MIMIR-1")
-labelled: list[LabelledDecision] = [...]  # your context/decision/label triples
-policy = calibrate(model, labelled, risk=0.01, confidence=0.95)
-```
+| You ask | You get |
+|---|---|
+| `choose` — pick one option, or none | an option id, or `None` |
+| multi-choice — pick every option that applies | the option ids that apply |
+| `yes_no` — answer a yes/no question | `True` or `False` |
+| `verify` — judge a claim against evidence | `supported`, `contradicted` or `not_enough_information` |
+| `rank` — order candidates, best first | candidate ids, best first |
+| `rate` — rate on your ordered scale | a level id |
+| `estimate` — estimate a number in `[low, high]` | a number with an interval |
 
-## Documentation
+Every result carries `status`, `confidence`, `relevant_context` (the context parts behind
+the answer, most relevant first), `certificate`, `deferral` and `latency_ms`. Choice,
+yes/no and verify results add `abstain_probability` and a conformal `prediction_set`.
 
-Package repository with HTTP, MCP and framework adapters, worked examples and the full
-API reference: [Mythologic/mimir](https://github.com/Mythologic/mimir).
+A context is a string, a list of passages, tables with typed numbers and dates, or a JSON
+state — and `decide_many` batches many decisions while every method has an async form.
 
----
+## Load paths
 
 **This repo holds all three load paths.** The release root is the `mimirai` contract
 (ONNX graphs plus certified policy); the same weights ship as plain `transformers` under
@@ -114,28 +128,41 @@ a subfolder, and only what you load is downloaded:
 | **`Mythologic/MIMIR-1`** (this repo root) | ONNX graphs + certified policy via `mimirai` | routing, gating, verification |
 | **`Mythologic/MIMIR-1`, `subfolder="transformers"`** | same weights for plain `transformers` | research, custom runtimes |
 
-## Quickstart: Package Mode (Recommended)
+### Package mode (recommended)
 
-`mimirai` is the recommended way to use MIMIR in production. It handles chunking, typed
-readouts, evidence, the distance gate and the certificate in one call:
+`mimirai` handles chunking, typed readouts, evidence, the distance gate and the
+certificate in one call, and additionally serves them over HTTP and MCP:
 
-```python
-from mimir import Mimir
+```bash
+mimir serve  # HTTP, configured decision endpoints
+mimir mcp    # MCP server: configured decision tools by default
+```
 
-model = Mimir.from_pretrained("Mythologic/MIMIR-1")
+Both serve the certified fp32 graph with the shipped policy, so the certificate below
+applies to what they return. Adapters for eight agent frameworks, worked examples and
+the full API reference are in the package repository, with a docs site.
 
-result = model.choose(
-    "My card was charged twice for the same order.",
-    "Which team should handle this?",
-    options={"billing": "Billing: payments, refunds", "security": "Security: account access"},
+### Transformers mode
+
+With no `mimirai` install (tested `transformers==5.17`):
+
+```python
+from transformers import AutoModel, AutoTokenizer
+
+model = AutoModel.from_pretrained(
+    "Mythologic/MIMIR-1", subfolder="transformers", trust_remote_code=True
 )
-print(result.status, result.answer)  # DECIDED billing
+tokenizer = AutoTokenizer.from_pretrained("Mythologic/MIMIR-1", subfolder="transformers")
+outputs = model(chunk_ids, chunk_mask, ...)  # the 21 graph inputs, in order
+outputs.utilities  # [4 depths, records, candidates]: every depth's readouts
 ```
 
-Every result carries the evidence spans behind the decision and the gate verdict, and
-where the certificate applies, whether the call should act or be escalated.
+Load plus forward on pre-encoded batches only: text handling, calibration, the server
+and MCP stay in `mimirai`. The staged modelling code holds the inference-only head
+forward — no loss, no training machinery — the same computation the shipped `model.onnx`
+already carries.
 
-### Why MIMIR: the evidence
+## Evidence
 
 Head-to-head against Laya (`convaiinnovations/laya`) and GLiNER2.5-Decide
 (`fastino/GLiNER2.5-Decide`), each run by us on identical records with paired bootstrap
@@ -159,36 +186,44 @@ its own fast-decisions showcase. DAIR Emotion is abstention, not error — the m
 "none of the listed options" on 1,792 of 2,000 records (mean abstain mass 0.656); forced
 to pick among the six emotions it scores 0.595, against Laya's 0.589.
 
-### Production: server and MCP
-
-```bash
-mimir serve  # HTTP, configured decision endpoints
-mimir mcp    # MCP server: configured decision tools by default
-```
+## Certificate
 
-Both serve the certified fp32 graph with the shipped policy, so the certificate below
-applies to what they return. Framework adapters and worked examples are in the package
-repository.
+The fp32 policy ships selective thresholds proven on 95,550 held-out records at four risk
+levels (origin `custom` in `policy/fp32.json`):
 
-## Single-Model Mode (transformers)
+| Type | 1% risk: taken | Errors |
+|---|---|---|
+| binary | 6,781 of 19,319 (35.1%) | 47 (0.69%) |
+| categorical | 19,947 of 54,728 (36.4%) | 166 (0.83%) |
+| ranking | 1,441 of 3,863 (37.3%) | 5 (0.35%) |
+| ordinal, multilabel | defer every record | — |
 
-If you need the raw weights for a dedicated pipeline, with no `mimirai` install:
+Read the table as a contract: at 1% risk the model acts on about a third of binary,
+categorical and ranking calls and its error rate on the acted calls stays under the risk.
+Thresholds were fit on the PyTorch model's outputs and transferred to the graph, whose
+outputs match the model on every decision over 312 verification records (max relative
+readout gap 6.5e-5, zero decision differences). The release also ships a 200-record
+equivalence set, so any CPU hardware replays the graph and must reproduce every shipped
+decision. The certified configuration is CPU, ONNX Runtime 1.30.0. Other runtimes
+calibrate their own policy from their own labels:
 
 ```python
-from transformers import AutoModel, AutoTokenizer
+from mimir import Mimir
+from mimir.core.labels import LabelledDecision
+from mimir.runtime.calibrate import calibrate
 
-model = AutoModel.from_pretrained(
-    "Mythologic/MIMIR-1", subfolder="transformers", trust_remote_code=True
-)
-tokenizer = AutoTokenizer.from_pretrained("Mythologic/MIMIR-1", subfolder="transformers")
-outputs = model(chunk_ids, chunk_mask, ...)  # the 21 graph inputs, in order
-outputs.utilities  # [4 depths, records, candidates]: every depth's readouts
+model = Mimir.from_pretrained("Mythologic/MIMIR-1")
+labelled: list[LabelledDecision] = [...]  # your context/decision/label triples
+policy = calibrate(model, labelled, risk=0.01, confidence=0.95)
 ```
 
-This path is load plus forward on pre-encoded batches only: text handling, calibration,
-the server and MCP stay in `mimirai`. The staged modelling code holds the
-inference-only head forward — no loss, no training machinery — the same computation the
-shipped `model.onnx` already carries.
+The fp16 graph ships without a policy; certify it the same way.
+
+## Speed
+
+About **1.7 decisions per second on an M4 CPU**, flat from 1 to 32 concurrent clients —
+the batching absorbs concurrency rather than queueing it. GPU throughput is not measured
+in this release.
 
 ## Architecture
 
@@ -208,47 +243,29 @@ shipped `model.onnx` already carries.
 
 Training data and procedure are private.
 
-## Benchmarks
+## FAQ
 
-### Speed
+**Why is DAIR Emotion 0.080?**
+Because the model refuses to guess: "none of the listed options" on 1,792 of 2,000
+records. Forced to pick, it scores 0.595 — above both competitors. If your pipeline
+needs a label on every row, read the argmax over the options; if it needs honesty, read
+the abstention.
 
-About **1.7 decisions per second on an M4 CPU**, flat from 1 to 32 concurrent clients —
-the batching absorbs concurrency rather than queueing it. GPU throughput is not measured
-in this release.
+**What do I do with ABSTAINED and DEFERRED?**
+Route them to a person or a stronger check. Pipelines that treat every call as an answer
+turn refusals into someone else's silent default.
 
-### Certificate
+**Can I use a GPU?**
+Yes, with the fp16 graph — but it ships without a policy, so calibrate your own or run
+the equivalence set first. There is no CUDA certificate in this release.
 
-The fp32 policy ships selective thresholds proven on 95,550 held-out records at four risk
-levels (origin `custom` in `policy/fp32.json`):
+**Why do ordinal and multilabel always defer?**
+Their first testable thresholds fail on held-out data. Shipping them would be shipping an
+unproven promise.
 
-| Type | 1% risk: taken | Errors |
-|---|---|---|
-| binary | 6,781 of 19,319 (35.1%) | 47 (0.69%) |
-| categorical | 19,947 of 54,728 (36.4%) | 166 (0.83%) |
-| ranking | 1,441 of 3,863 (37.3%) | 5 (0.35%) |
-| ordinal, multilabel | defer every record | — |
-
-Read the table as a contract: at 1% risk the model acts on about a third of binary,
-categorical and ranking calls and its error rate on the acted calls stays under the risk.
-Thresholds were fit on the PyTorch model's outputs and transferred to the graph, whose
-outputs match the model on every decision over 312 verification records (max relative
-readout gap 6.5e-5, zero decision differences). The release also ships a 200-record
-equivalence set, so any CPU hardware replays the graph and must reproduce every shipped
-decision. The certified configuration is CPU, ONNX Runtime 1.30.0. The fp16 graph ships
-without a policy; certify it the same way.
-
-## Honest Limits
-
-- **English only.** Non-English input is out of scope and unmeasured.
-- **Ordinal and multilabel always defer in this release.** Their first testable thresholds
-  fail on held-out data, so shipping them would be shipping an unproven promise.
-- **Tested limits: 150 options, 49 levels, 26,406 context tokens.** Larger inputs are
-  refused, not truncated silently.
-- **No CUDA certificate.** GPU users run the equivalence set or calibrate their own
-  policy; there is no GPU latency figure in this release.
-- **Abstention is load-bearing.** On DAIR Emotion the model refuses 1,792 of 2,000
-  records. If your pipeline treats every call as an answer, those refusals become someone
-  else's silent default — handle `ABSTAINED` and `DEFERRED` explicitly.
+**How do I reproduce the numbers?**
+The release carries a 200-record equivalence set: replay the graph on any CPU and every
+shipped decision must match.
 
 ## Files
 
@@ -270,7 +287,7 @@ No optimiser state, no scheduler state, no RNG. Training cannot be resumed from
 ## Links
 
 - Package: `mimirai` on PyPI (`https://pypi.org/project/mimirai/`), `from mimir import Mimir`
-- Code: [Mythologic/mimir](https://github.com/Mythologic/mimir) on GitHub
+- Code: [abderahmane-ai/mimirai](https://github.com/abderahmane-ai/mimirai) on GitHub
 
 ## Licence