MIMIR

mimir-decisions

让 Agent 采取行动的决策。 MIMIR 是一种非生成式决策模型：向它提供上下文、问题和选项，即可获得结构化答案、经过校准的概率、背后的证据，以及一份经认证的判定，说明应采取行动还是升级处理。不生成文本。无需解析。无从产生幻觉。

在十项任务中，有六项与 Laya 和 GLiNER2.5-Decide 正面较量时胜出——在 Banking77 上高出 54.7 个百分点，在 MASSIVE 上高出 42.3 个百分点，在结构化决策上高出 36.3 个百分点；遇到无法为答案提供依据的情况时，它会弃答，而不是猜测。

pip install "mimir-decisions[local]"        # the local engine (CPU and CUDA)
pip install mimir-decisions                  # data models and HTTP client only

Python 3.11+。文档：https://abderahmane-ai.github.io/mimir/

---

为什么选择 MIMIR

大多数 Agent 使用通用大模型进行路由、分类和验证：速度慢、成本高，而且无法审计。MIMIR 专为结构化决策而构建。它基于 Torch 在本地运行，可使用 CPU 或 GPU；每个答案都会附带经过校准的概率，并提供一份证书——在保留数据上进行测量，证明通过其阈值的答案，其风险保持在你指定的水平或以下。

• 不生成内容。 答案从你提供的选项中选出，而非合成生成。模型无法产生列表中不存在的答案。
• 置信度经过校准。 概率不是 softmax 分数，而是经过校准，与保留数据上的实际准确率相匹配。
• 始终给出答案。 每次决策都会返回模型的预测及其概率。在 threshold 和 certified 模式下，低于下限的答案会以 deferred 状态返回，供审核——绝不会被扣下不返。
• 统一的结构化契约。 七种决策类型——选择、多选、是/否、验证、排序、评分、估算——对任何上下文都返回相同的结果结构。
• 可移植。 同一套 Python 接口可在本地 CPU 或 GPU 上使用，也可通过 HTTP 和 MCP 使用。还为八种 Agent SDK 提供了框架适配器。

---

快速入门

from mimir import Context, Field, Mimir, Passage

model = Mimir.from_pretrained("Mythologic/MIMIR-1")

# The short form: the chosen option id, or None when the model abstains or defers
team = model.pick(
    "Hi, invoice INV-8821 was billed twice. Please refund the duplicate.",
    ["billing", "technical", "sales"],
)  # "billing"

# Context pairs prose passages with typed structured fields (amounts, IDs, metadata)
context = Context(
    passages=[
        Passage(
            title="Ticket #4091",
            text="Hi, we were billed twice ($2,400 total) on invoice INV-8821. Please refund the $1,200 duplicate today or we will cancel our plan.",
        )
    ],
    fields=Field.from_json({
        "invoice_id": "INV-8821",
        "duplicate_amount": 1200,
        "customer_plan": "enterprise",
    }),
)

# The question is optional: model.choose(context, options) asks "Which option applies to this context?"
result = model.choose(
    context,
    "Which department should handle this request?",
    options={
        "billing": "Billing: invoices, payments, refunds",
        "technical": "Technical: bugs, outages, system errors",
        "sales": "Sales: pricing, new contracts",
        "other": "Other: everything else",
    },
)

result.status         # Status.DECIDED, Status.ABSTAINED or Status.DEFERRED
result.answer         # "billing", or None when no option applies
result.probabilities  # calibrated probability of each option id
result.certificate    # mathematical proof of risk bound on held-out data

answer 始终是模型的预测结果。status 表示答案是否达到运行下限：

• DECIDED — 根据 answer 采取行动。
• ABSTAINED — 没有适用的列出选项（明确拒绝分布外输入）。
• DEFERRED — 答案低于证书下限；将其交由人工审核员处理。

风险调节：从关键任务 SLA 到高吞吐量 Agent

此版本对四种有限样本风险级别的阈值进行了认证（model.info().risk_levels = (0.005, 0.01, 0.02, 0.05)）：

• risk=0.01（99.0% SLA） — 关键任务航空航天／金融 SLA：设定极严格的统计下限。只有几乎确定的答案才会自动执行；任何不确定的答案都会交由人工审核，而不是冒险执行。
• risk=0.05（95.0% SLA，默认值） — 高吞吐量 Web Agent／客户工作流：这是自主 Agent 的理想选择，既能自动处理有效请求，又能在保留数据上以数学方式限定错误率。
• mode="standard" — 返回经过校准的 argmax，不会因有限样本风险而延后处理；此时 risk 只用于选择附加到结果中的证书。mode="certified" 也会将低于 risk 对应认证阈值的答案延后处理。

提供按用户原话撰写的工单及其结构化字段——若对一行摘要使用相同选项，结果可能会是 ABSTAINED。决策指南介绍了决定结果的问题和选项格式。

首次调用时，会从 Hugging Face Hub 下载此软件包版本指定的修订版模型，验证其 Sigstore 签名，根据清单中的 SHA-256 校验每个文件，然后加载模型。

---

决策类型

规范	答案
Choice(question, options)	一个选项 ID，或 None
MultiChoice(question, options)	适用的选项 ID
YesNo(question)	True 或 False
Verify(claim)	supported、contradicted 或 not_enough_information
Rank(question, candidates)	候选项 ID，按优先级从高到低排列
Rate(question, levels)	一个等级 ID；等级按从低到高给出
Estimate(question, low, high, unit)	[low, high] 范围内的数字，并附带置信区间

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)

上下文可以是字符串、字符串列表、按 JSON 状态读取的字典，或由类型化段落、表格和字段组成的 Context。Table.from_dataframe(frame) 可读取 pandas 或 polars DataFrame。decide_many 可批量处理多个决策，每个方法都有对应的异步版本（adecide、adecide_many 等）。

---

认证

decide 在 standard 模式下回答所有请求。threshold 模式会暂缓低于 min_confidence 的回答；certified 模式会暂缓低于该版本在 risk 下设定阈值的回答（model.info().risk_levels），并在答案通过时附上证书。对于错误操作会造成重大损失的关键任务，可设置 risk=0.01（99% SLA）；对于高吞吐量的自主 Agent，可设置 risk=0.05（95% SLA）。decide_uncertified 会返回未经策略处理的原始模型答案。

证书适用于一组精确配置：权重、Torch 版本、设备和硬件。在证书未列出的硬件上，首次加载时会运行该版本的等价性测试集，并要求每项决策都匹配。要使用自己的标注数据认证阈值：

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

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

---

远程使用

from mimir import MimirClient

remote = MimirClient("https://mimir.internal", api_key="...")
remote.choose(
    "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan.",
    "Which department should handle this request?",
    options={
        "billing": "Billing: invoices, payments, refunds",
        "technical": "Technical: bugs, outages, system errors",
        "sales": "Sales: pricing, new contracts",
        "other": "Other: everything else",
    },
)

MimirClient 与 Mimir 使用相同的接口，因此所有代码、决策工具和框架适配器都可接受其中任意一个。它只需要基础安装。连接错误、超时以及 429/502/503/504/529 响应会以指数退避方式重试，并遵循 Retry-After。

---

决策工具

from mimir import Choice

route_ticket = model.tool(
    "route_ticket",
    Choice(
        "Which department should handle this request?",
        {
            "billing": "Billing: invoices, payments, refunds",
            "technical": "Technical: bugs, outages, system errors",
            "sales": "Sales: pricing, new contracts",
            "other": "Other: everything else",
        },
    ),
    description="Route a support ticket to the team that owns it.",
)
route_ticket(
    "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan."
)
route_ticket.input_schema, route_ticket.output_schema

也可以在 YAML 文件中声明工具，HTTP 和 MCP 服务会加载该文件：

tools:
  - name: route_ticket
    description: Route a support ticket to the team that owns it.
    decision:
      type: choice
      question: Which department should handle this request?
      options:
        billing: "Billing: invoices, payments, refunds"
        technical: "Technical: bugs, outages, system errors"
        sales: "Sales: pricing, new contracts"
        other: "Other: everything else"

---

工具调用检查

工具调用检查会根据你编写的规则，判断 Agent 等待执行的工具调用是否可以运行。明确肯定时允许执行，明确否定时拒绝执行，其他情况则升级给人工处理。

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

---

基准测试

benchmarks/mimir_vs_laya_enterprise_benchmark.ipynb（在 Colab 中运行）运行十种场景，每种场景包含一项书面策略和一个等待执行的工具调用：五种符合策略，五种违反策略。每个系统看到的提示词、工具、参数和策略文本都相同。记录的运行环境：Colab CPU、mimir-decisions 1.2.0、laya 0.4.0。

系统	正确数	执行的违规策略调用数（共 5 次）	执行的合规调用数（共 5 次）	中位延迟
Laya，仅路由器	4/10	5	4	1,988 ms
Laya，路由器 + noul 闸门	6/10	1	2	4,556 ms
MIMIR-1，pick + tool_call_check	9/10	0	4	10,076 ms

这套测试由 MIMIR 作者编写，共包含十种场景，因此这些数据仅描述这套测试，不代表普遍情况。MIMIR-1 的四次升级都发生在 pick 步骤；其策略检查会允许或拒绝操作，并拒绝了路由器确实路由到请求工具的两次违规调用（4B 和 5B）。MIMIR-1 以 threshold 模式运行，阈值为 0.50。延迟数据来自 Colab CPU 运行环境，每项决策需运行两次模型。

benchmarks/sysone-bench 记录了在独立的 sysone-bench 测试集上的运行结果。

---

Agent 框架

每个适配器都会将决策工具转换为框架原生的工具类型，并将工具调用检查接入该框架自己的审批钩子。

框架	安装	工具	工具调用检查
OpenAI Agents SDK	mimir-decisions[openai-agents]	as_function_tool	guard：升级处理会暂停运行，等待审批
LangChain / LangGraph	mimir-decisions[langchain]	as_structured_tool	ToolCallCheckMiddleware：升级处理会通过请求人工介入来中断运行
PydanticAI	mimir-decisions[pydantic-ai]	as_toolset	guard：升级处理会以 DeferredToolRequests 结束运行
CrewAI	mimir-decisions[crewai]	as_crewai_tool	tool_call_hook：升级处理会发送给你的审批人
Google ADK	mimir-decisions[adk]	as_adk_tool	tool_call_callback：升级处理会请求 ADK 确认
Microsoft Agent Framework	mimir-decisions[agent-framework]	as_function_tool	ToolCallCheckMiddleware：仅执行置信度足够高的调用
LlamaIndex	mimir-decisions[llamaindex]	as_llamaindex_tool	无
smolagents	mimir-decisions[smolagents]	as_smolagents_tool	无

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

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

每个框架也都会通过自己的 MCP 客户端接入 MIMIR。examples/ 中为每个框架提供了原生 Agent、MCP Agent 和经过检查的 Agent，此外还有一个使用 TypeScript 编写的 Vercel AI SDK Agent。

---

HTTP 服务

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

路由	功能
POST /v1/decide	单次决策：{context, decision, mode, min_confidence, risk, alpha}
POST /v1/decide/uncertified	模型的原始回答：{context, decision}
POST /v1/decide/batch	单次调用最多处理 64 项决策
POST /v1/tools/{name}	调用 --tools 中的工具，仅提供 {context}
POST /v1/systemone	Jev 的请求和响应格式
GET /v1/models	模型、修订版本、运行时和已认证的风险级别
GET /healthz、GET /readyz	存活状态，以及模型加载后的就绪状态
GET /metrics	Prometheus 指标

并发请求会批量处理。如果 MIMIR_API_KEYS 中设置了密钥，则除探测端点外的所有路由都需要 Authorization: Bearer <key>。未配置密钥的服务仅监听回环地址，除非使用 --allow-no-auth 启动。OpenAPI 3.1 文档位于 openapi.json。

---

MCP 服务

每个已配置的工具都会成为一个仅接受上下文的 MCP 工具；--generic-tools 会添加 mimir_choose、mimir_verify、mimir_rank 和 mimir_rate。延后处理的决策会以普通结果的形式告知 Agent 需要升级处理。

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

在 Claude Code 中：

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 和 VS Code 在其 MCP 配置中使用相同的命令，或相同的 URL 和请求头。该服务已在 MCP Registry 注册，名称为 io.github.abderahmane-ai/mimir。

---

容器

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

镜像包含运行时，不包含模型权重。首次启动时，系统会下载由软件包版本指定修订版本的模型，验证模型并将其缓存到 /models。如需使用该缓存离线运行，请追加 serve --host 0.0.0.0 --model-cache /models --offline。

发布工作流使用 Sigstore 对镜像进行签名：

cosign verify ghcr.io/abderahmane-ai/mimir:1.2.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

---

命令行

命令	描述
mimir serve	HTTP 服务；--mcp 还会在 /mcp 提供 MCP 服务
mimir mcp	通过标准输入输出或 --http 提供 MCP 服务
mimir decide	根据标志进行单次决策，或从标准输入读取 JSON 请求
mimir bench FILE	评估带标签决策的准确率、覆盖率、已认证占比和实际风险
mimir calibrate FILE	根据带标签的决策认证阈值
mimir schema	列出每个规范、结果和请求的 JSON Schema
mimir download	下载并验证供离线使用的发行版
mimir doctor	报告环境信息；--verify 会加载模型并运行等价性检查

---

完整性

发布版本从固定的 Hugging Face 修订版本加载。在读取任何模型文件之前，系统会根据 abderahmane-ai/mimir 发布工作流验证清单的 Sigstore 签名，并检查每个文件是否与清单中的 SHA-256 一致。整个过程中不会使用 pickle。

---

迁移

mimir.compat.systemone.v1 可转换 Jev /v1/systemone 请求和响应，mimir.compat.laya.v1 则按 Laya 0.3.20 的格式提供 load(...).predict(state, questions)。请参阅迁移指南，了解分步说明。

---

许可

MIMIR SDK 根据 Apache-2.0 许可授权；该许可仅适用于软件， 不适用于 MIMIR 模型权重。MIMIR-1 模型权重另行根据 MIMIR 模型许可授权。

符合条件的社区用户可在遵守 MIMIR 模型许可的前提下，免版税将 MIMIR-1 用于商业用途。任何人都可以下载、基准测试、评估和使用 MIMIR 进行原型开发，无需注册。

年总收入超过收入门槛（1,000,000 美元）的组织，或需要企业、OEM、再分发、托管或其他额外权利的组织，可向 Mythologic 获取商业协议。请参阅 COMMERCIAL-LICENSING.md。