简体中文 | English

matterloop-models

matterloop-models 给上层 Agent 一个稳定的异步模型协议，同时把供应商差异留在同一发行包的 matterloop_models.providers 子包。应用可以使用内置适配器，也可以直接实现 ModelClient。

pip install matterloop-models
# 需要 OpenAI 风格 SDK 时
pip install "matterloop-models[openai]"

客户端由应用创建

from openai import AsyncOpenAI

from matterloop_models import ModelRegistry, ModelRequest
from matterloop_models.providers import DeepSeekChatModelClient, DeepSeekModelConfig

sdk = AsyncOpenAI(api_key=secret, base_url=endpoint)
model = DeepSeekChatModelClient(
    DeepSeekModelConfig(model="application-selected-model"),
    client=sdk,
    owns_client=False,
)

models = ModelRegistry()
models.register("planner", model, descriptor=model.descriptor)

MatterLoop 不读取 .env、API key、base URL、代理或证书配置。owns_client=False 表示 SDK 的关闭 责任仍在应用；只有明确传 owns_client=True 时，适配器才会在关闭时处理注入客户端。

一次模型事务

ModelClient.generate() 接收中立 ModelRequest，返回 ModelResponse。工具调用可能需要多轮， 整个事务应持有同一注册表租约：

async with models.acquire("worker") as client:
    response = await client.generate(request)
    while response.tool_calls:
        outputs = await execute_tools(response.tool_calls)
        response = await client.generate(
            ModelRequest(
                messages=(),
                tools=request.tools,
                tool_outputs=tuple(outputs),
                previous_response_id=response.response_id,
                continuation=response.continuation,
            )
        )

这样热替换只影响新事务。continuation 绑定创建它的适配器、模型和内部历史，不能跨租户、端点或 客户端实例复用，也不应进入日志、事件、checkpoint 或数据库。

中立请求模型

response_schema 是本地严格校验的依据。供应商适配器可能使用原生 JSON Schema、降级为 JSON Object，或把约束写入提示；无论哪种方式，Agent 都必须再次验证结果。工具的 strict 标志也不能 替代 ToolRegistry 的本地参数校验与权限检查。

注册、选择与热替换

ModelRegistry.register(name, client, replace, descriptor) 注册名称； ModelRegistry.acquire(name) 为完整事务固定客户端； ModelRegistry.swap(name, client, descriptor) 原子换入新实例并返回可等待排空的 retirement。

retirement = models.swap("planner", replacement, replacement.descriptor)
old_client = await retirement.wait_drained()
await old_client.aclose()

get() 只适合短查询，不提供跨 await 的生命周期保证。register(..., replace=True) 不返回旧实例 排空句柄；需要安全关闭时使用 swap()。注册表本身不启动或关闭客户端。

模型能力使用 SUPPORTED / UNSUPPORTED / UNKNOWN，目的是在调用前拒绝已知不兼容组合，而不是 替代供应商的实时能力检查。模型、账号或地域仍可能在调用时拒绝某项能力。

内置 Provider

配置对象没有模型名默认值：

• OpenAIModelConfig(model)。
• DeepSeekModelConfig(model, thinking_mode, reasoning_effort, enable_strict_tools)。
• MiniMaxModelConfig(model)。
• QwenModelConfig(model, thinking_mode, thinking_budget, preserve_thinking, parallel_tool_calls)。
• ZhipuModelConfig(model, thinking_mode, reasoning_effort, clear_thinking, do_sample)； GLMModelConfig 是同类型别名。
• OpenAICompatibleChatConfig(provider, model, developer_role, structured_output_mode, max_tokens_field, enable_strict_tools, preserve_reasoning_content, extra_parameters)。

通用 compatible 适配器只适合调用方已经验证过的服务。extra_parameters 禁止承载 API key、 Authorization、base URL 和适配器自行管理的请求字段；能力配置描述的是本地映射方式，不是供应商 承诺。

各 Chat 适配器会把 assistant tool calls、tool outputs 和供应商要求的 reasoning continuation 一起 续轮。本地输出必须覆盖全部待处理 call_id，不能重复或夹带未知调用。

自定义与测试

任意对象只要实现下面的结构协议即可接入：

class MyModelClient:
    async def generate(self, request: ModelRequest) -> ModelResponse:
        ...

简单异步函数可用 CallableModelClient 包装。FakeModelClient 支持预设响应队列或 responder 回调， 并保留请求供测试断言；请求快照可能包含敏感业务数据，不应拿去做生产日志。

错误边界

认证、付费、限流、服务故障、调用失败、响应解析和能力不匹配分别归一化为类型化 ModelError。 安全异常只保留供应商、状态码或异常类型，不拼接 SDK 原始文本。远端已计费但本地解析失败时， ModelResponseParseError 可能携带 usage，预算包装器应先结算再抛出。

适配器不自动重试，也不查询实时模型列表、价格或账户额度。重试应在 SDK 或上层策略中配置，并与 调用次数、Token、费用和超时硬边界同时使用。多模块装配见 企业集成指南。