Metadata-Version: 2.4
Name: mimir-decisions
Version: 1.0.0
Summary: Typed, calibrated and certified decisions from MIMIR, a non-generative decision model
Keywords: decision-model,classification,abstention,calibration,onnx,agents
Author: Mythologic
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1,<1
Requires-Dist: packaging>=24
Requires-Dist: pydantic>=2.11,<3
Requires-Dist: rich>=13.9,<16
Requires-Dist: typer>=0.16,<1
Requires-Dist: google-adk>=2.10,<3 ; extra == 'adk'
Requires-Dist: agent-framework-core>=1.19,<2 ; extra == 'agent-framework'
Requires-Dist: mimir-decisions[local,server,mcp] ; extra == 'all'
Requires-Dist: crewai>=1.15,<2 ; python_full_version < '3.14' and extra == 'crewai'
Requires-Dist: langchain>=1.3,<2 ; extra == 'langchain'
Requires-Dist: llama-index-core>=0.14.25,<0.15 ; extra == 'llamaindex'
Requires-Dist: huggingface-hub>=1.0,<2 ; extra == 'local'
Requires-Dist: numpy>=2.3,<3 ; extra == 'local'
Requires-Dist: onnx>=1.23,<2 ; extra == 'local'
Requires-Dist: onnxruntime==1.30.0 ; extra == 'local'
Requires-Dist: sigstore>=4.5,<5 ; extra == 'local'
Requires-Dist: tokenizers>=0.23.2,<0.24 ; extra == 'local'
Requires-Dist: huggingface-hub>=1.0,<2 ; extra == 'local-gpu'
Requires-Dist: numpy>=2.3,<3 ; extra == 'local-gpu'
Requires-Dist: onnx>=1.23,<2 ; extra == 'local-gpu'
Requires-Dist: onnxruntime-gpu==1.30.0 ; extra == 'local-gpu'
Requires-Dist: sigstore>=4.5,<5 ; extra == 'local-gpu'
Requires-Dist: tokenizers>=0.23.2,<0.24 ; extra == 'local-gpu'
Requires-Dist: mcp>=2.2,<3 ; extra == 'mcp'
Requires-Dist: pyyaml>=6.0.3,<7 ; extra == 'mcp'
Requires-Dist: uvicorn>=0.54,<1 ; extra == 'mcp'
Requires-Dist: openai-agents>=0.21,<1 ; extra == 'openai-agents'
Requires-Dist: pydantic-ai-slim>=2.16,<3 ; extra == 'pydantic-ai'
Requires-Dist: fastapi>=0.141.1,<1 ; extra == 'server'
Requires-Dist: prometheus-client>=0.26,<1 ; extra == 'server'
Requires-Dist: pyyaml>=6.0.3,<7 ; extra == 'server'
Requires-Dist: uvicorn>=0.54,<1 ; extra == 'server'
Requires-Dist: smolagents>=1.26,<2 ; extra == 'smolagents'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/abderahmane-ai/mimir
Project-URL: Documentation, https://abderahmane-ai.github.io/mimir/
Project-URL: Changelog, https://github.com/abderahmane-ai/mimir/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/abderahmane-ai/mimir
Project-URL: Tracker, https://github.com/abderahmane-ai/mimir/issues
Project-URL: Model, https://huggingface.co/Mythologic/MIMIR-1
Provides-Extra: adk
Provides-Extra: agent-framework
Provides-Extra: all
Provides-Extra: crewai
Provides-Extra: langchain
Provides-Extra: llamaindex
Provides-Extra: local
Provides-Extra: local-gpu
Provides-Extra: mcp
Provides-Extra: openai-agents
Provides-Extra: pydantic-ai
Provides-Extra: server
Provides-Extra: smolagents
Description-Content-Type: text/markdown

# mimir-decisions

**Decisions your agents can act on.** MIMIR is a non-generative decision model: give it
a context, a question and the options, and get back a typed answer with calibrated
probabilities, the evidence behind it, and a certified verdict on whether to act or
escalate. No text generated. Nothing to parse. Nothing to hallucinate.

It beats Laya and GLiNER2.5-Decide head-to-head on six of ten tasks — by 54.7 points on
Banking77, 42.3 on MASSIVE, 36.3 on typed decisions — and where it cannot back an
answer, it abstains instead of guessing.

```bash
pip install "mimir-decisions[local]"        # CPU engine
pip install "mimir-decisions[local-gpu]"    # CUDA engine
pip install mimir-decisions                  # data models and HTTP client only
```

Python 3.11+. Documentation: <https://abderahmane-ai.github.io/mimir/>

---

## Why MIMIR

Most agents route, classify, and verify using a general-purpose language model: slow, expensive, and impossible to audit. MIMIR is built for structured decisions. It runs on ONNX Runtime in milliseconds, returns calibrated probabilities with every answer, and issues a mathematical certificate — a formal guarantee that its realised error rate stays at or below the risk level you ask for, measured on held-out data.

- **No generation.** Answers are drawn from the options you supply, not synthesised. The model cannot hallucinate an answer that wasn't on the list.
- **Calibrated confidence.** Probabilities are not softmax scores; they are calibrated to match realised accuracy on held-out data.
- **Certified deferral.** When confidence falls short of the certified threshold, the decision defers rather than guessing. The coverage and the error rate of taken decisions are proven.
- **One typed contract.** Seven decision types — choice, multi-choice, yes/no, verify, rank, rate, estimate — all returning the same result shape, over any context.
- **Portable.** The same Python interface works locally on CPU or GPU, over HTTP, and over MCP. Framework adapters exist for eight agent SDKs.

---

## Quickstart

```python
from mimir import Mimir

model = Mimir.from_pretrained("Mythologic/MIMIR-1")
result = model.choose(
    "My card was charged twice for the same order.",
    "Which team should handle this ticket?",
    options={"billing": "Billing: payments, refunds", "security": "Security: account access"},
)

result.status         # Status.DECIDED, Status.ABSTAINED or Status.DEFERRED
result.answer         # an option id, or None when no option applies
result.probabilities  # calibrated probability of each option id
result.certificate    # the certified threshold the decision was checked against
```

`answer` is the model's prediction. `status` is the policy's verdict:

- `DECIDED` — the answer is an option and is certified at the requested risk level.
- `ABSTAINED` — no listed option applies, and that is certified.
- `DEFERRED` — not certified; `result.deferral.reason` is `below_threshold`, `out_of_distribution`, or `no_certified_threshold`.

The first call downloads the model from the Hugging Face Hub at the revision this package version pins, verifies its Sigstore signature, checks every file against the manifest's SHA-256, and loads it.

---

## Decision types

| Spec | Answer |
|---|---|
| `Choice(question, options)` | an option id, or `None` |
| `MultiChoice(question, options)` | the option ids that apply |
| `YesNo(question)` | `True` or `False` |
| `Verify(claim)` | `supported`, `contradicted`, or `not_enough_information` |
| `Rank(question, candidates)` | candidate ids, best first |
| `Rate(question, levels)` | a level id; levels given lowest first |
| `Estimate(question, low, high, unit)` | a number in `[low, high]`, with a confidence interval |

```python
from mimir import Context, Field, Passage, Rate, Table

context = Context(
    passages=[Passage(title="Ticket #4412", text="The export has failed every night this week.")],
    tables=[Table.from_rows([["2026-03-02", "failed"]], header=["date", "status"])],
    fields=Field.from_json({"customer": {"plan": "enterprise", "seats": 240}}),
)
result = model.decide(context, Rate("How urgent is this?", ["low", "medium", "high"]), risk=0.01)
```

A context can be a string, a list of strings, a dict read as a JSON state, or a `Context` of typed passages, tables, and fields. `Table.from_dataframe(frame)` reads a pandas or polars DataFrame. `decide_many` batches multiple decisions, and every method has an async counterpart (`adecide`, `adecide_many`, …).

---

## Certification

`decide` takes a risk level certified by the loaded policy (`model.info().risk_levels`). A decision is taken only when its calibrated confidence clears a threshold certified on held-out data to keep the realised error rate at or below that risk with 95% confidence, and when the context passes the out-of-distribution gate. `decide_uncertified` returns the raw model answer with no policy applied.

A certificate covers one exact configuration: model files, variant, ONNX Runtime version, execution provider, and options. On hardware not listed in the certificate, the first load runs the release's equivalence set and requires every decision to match. To certify thresholds on your own labelled data:

```bash
mimir calibrate labelled.jsonl --risk 0.01 --confidence 0.95 --out policy.json
```

```python
model = Mimir.from_pretrained("Mythologic/MIMIR-1", policy="policy.json")
```

---

## Remote use

```python
from mimir import MimirClient

remote = MimirClient("https://mimir.internal", api_key="...")
remote.choose("...", "Which team?", options=["billing", "security"])
```

`MimirClient` has the same interface as `Mimir`, so all code, decision tools, and framework adapters accept either. It requires only the base install. Connection errors, timeouts, and 429/502/503/504/529 responses are retried with exponential backoff that honours `Retry-After`.

---

## Decision tools

```python
from mimir import Choice

route_ticket = model.tool(
    "route_ticket",
    Choice("Which team should handle this ticket?", options=["billing", "security"]),
    description="Route a support ticket to the team that owns it.",
)
route_ticket("My card was charged twice")
route_ticket.input_schema, route_ticket.output_schema
```

Tools can also be declared in a YAML file, which the HTTP and MCP servers load:

```yaml
tools:
  - name: route_ticket
    description: Route a support ticket to the team that owns it.
    decision:
      type: choice
      question: Which team should handle this ticket?
      options: [billing, security]
```

---

## Tool-call checks

A tool-call check decides, against rules you write, whether an agent's pending tool call may run. A certified yes allows it, a certified no denies it, and anything else escalates to a person.

```python
check = model.tool_call_check(
    ["Refunds above 500 dollars need a manager's approval."], tools=["issue_refund"]
)
outcome = check("issue_refund", {"order": "4412", "amount": 900})
outcome.permission    # Permission.ALLOW, Permission.DENY or Permission.ESCALATE
outcome.reason        # one sentence for the agent or the approver
```

---

## Agent frameworks

Each adapter turns decision tools into the framework's native tool type and wires a tool-call check into that framework's own approval hook.

| Framework | Install | Tools | Tool-call check |
|---|---|---|---|
| OpenAI Agents SDK | `mimir-decisions[openai-agents]` | `as_function_tool` | `guard`: escalations pause the run for approval |
| LangChain / LangGraph | `mimir-decisions[langchain]` | `as_structured_tool` | `ToolCallCheckMiddleware`: escalations interrupt with the human-in-the-loop request |
| PydanticAI | `mimir-decisions[pydantic-ai]` | `as_toolset` | `guard`: escalations end the run with `DeferredToolRequests` |
| CrewAI | `mimir-decisions[crewai]` | `as_crewai_tool` | `tool_call_hook`: escalations go to your approver |
| Google ADK | `mimir-decisions[adk]` | `as_adk_tool` | `tool_call_callback`: escalations ask for ADK confirmation |
| Microsoft Agent Framework | `mimir-decisions[agent-framework]` | `as_function_tool` | `ToolCallCheckMiddleware`: only certified calls run |
| LlamaIndex | `mimir-decisions[llamaindex]` | `as_llamaindex_tool` | none |
| smolagents | `mimir-decisions[smolagents]` | `as_smolagents_tool` | none |

```python
from agents import Agent
from mimir.integrations.openai_agents import as_function_tool

agent = Agent(name="support", tools=[as_function_tool(route_ticket)])
```

Every framework also reaches MIMIR through its own MCP client. [`examples/`](examples) has a native, an MCP, and a checked agent for each framework, plus a Vercel AI SDK agent in TypeScript.

---

## HTTP server

```bash
pip install "mimir-decisions[local,server]"
MIMIR_API_KEYS=key-one,key-two mimir serve --host 0.0.0.0 --tools tools.yaml
```

| Route | Does |
|---|---|
| `POST /v1/decide` | one certified decision: `{context, decision, risk, alpha}` |
| `POST /v1/decide/uncertified` | the model's raw answer: `{context, decision}` |
| `POST /v1/decide/batch` | up to 64 decisions in one call |
| `POST /v1/tools/{name}` | a tool from `--tools`, given only `{context}` |
| `POST /v1/systemone` | Jev's request and response format |
| `GET /v1/models` | model, revision, runtime and certified risk levels |
| `GET /healthz`, `GET /readyz` | liveness, and readiness once the model is loaded |
| `GET /metrics` | Prometheus metrics |

Concurrent requests are batched. With keys in `MIMIR_API_KEYS`, every route except the probes requires `Authorization: Bearer <key>`. A server with no keys listens only on loopback unless started with `--allow-no-auth`. The OpenAPI 3.1 document is [`openapi.json`](openapi.json).

---

## MCP server

Each configured tool becomes an MCP tool that takes only a context; `--generic-tools` adds `mimir_choose`, `mimir_verify`, `mimir_rank`, and `mimir_rate`. A deferred decision is a normal result telling the agent to escalate.

```bash
uvx --from "mimir-decisions[local,mcp]" mimir-decisions mcp --tools tools.yaml               # stdio
MIMIR_API_KEYS=... mimir mcp --http --host 0.0.0.0 --tools tools.yaml       # Streamable HTTP at /mcp
mimir mcp --tools tools.yaml --remote https://mimir.internal                  # forward to a server
mimir serve --mcp --tools tools.yaml                                          # HTTP API and /mcp together
```

In Claude Code:

```bash
claude mcp add mimir -- uvx --from "mimir-decisions[local,mcp]" mimir-decisions mcp --tools /path/to/tools.yaml
claude mcp add --transport http mimir https://mimir.internal/mcp --header "Authorization: Bearer ..."
```

Claude Desktop, Cursor, and VS Code take the same command or the same URL and header in their MCP configuration. The server is registered in the MCP Registry as `io.github.abderahmane-ai/mimir`.

<!-- mcp-name: io.github.abderahmane-ai/mimir -->

---

## Containers

```bash
docker run -p 8000:8000 -e MIMIR_API_KEYS=... -v mimir-models:/models ghcr.io/abderahmane-ai/mimir:1.0.0-cpu
docker run --gpus all -p 8000:8000 -e MIMIR_API_KEYS=... -v mimir-models:/models ghcr.io/abderahmane-ai/mimir:1.0.0-cuda
```

Images carry the runtime, never the model weights. On first start, the model is downloaded at the revision the package version pins, verified, and cached in `/models`. To run from that cache with no network access, append `serve --host 0.0.0.0 --model-cache /models --offline`.

Images are signed with Sigstore by the release workflow:

```bash
cosign verify ghcr.io/abderahmane-ai/mimir:1.0.0-cpu \
  --certificate-identity https://github.com/abderahmane-ai/mimir/.github/workflows/release.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

---

## Command line

| Command | Description |
|---|---|
| `mimir serve` | the HTTP server; `--mcp` also serves MCP at `/mcp` |
| `mimir mcp` | the MCP server, over stdio or `--http` |
| `mimir decide` | one decision from flags, or a JSON request on stdin |
| `mimir bench FILE` | accuracy, coverage and realised risk on labelled decisions |
| `mimir calibrate FILE` | certify thresholds on labelled decisions |
| `mimir schema` | JSON Schemas of every spec, result and request |
| `mimir download` | download and verify a release for offline use |
| `mimir doctor` | report the environment; `--verify` loads the model and runs the equivalence check |

---

## Integrity

Releases are loaded from a pinned Hugging Face revision. Before any model file is read, the manifest's Sigstore signature is verified against the `abderahmane-ai/mimir` release workflow, every file is checked against the manifest's SHA-256, and the ONNX graph is checked against its operator allowlist and signature. No pickle is used anywhere.

---

## Migrating

`mimir.compat.systemone.v1` converts Jev `/v1/systemone` requests and responses, and `mimir.compat.laya.v1` exposes `load(...).predict(state, questions)` in Laya 0.3.20's shape. See the [migration guides](https://abderahmane-ai.github.io/mimir/migrating/jev/) for step-by-step instructions.

---

## License

The `mimir-decisions` package is licensed under [Apache 2.0](LICENSE). The MIMIR model weights are distributed under their own license on the [Hugging Face Hub](https://huggingface.co/Mythologic/MIMIR-1).
