Metadata-Version: 2.3
Name: saturnus-llm
Version: 0.1.0
Summary: Lightweight LLM connectivity and protocol compatibility tools.
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=4.26.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Saturnus

轻量、通用、可扩展的 LLM 开发工具库。

Saturnus 提供模型交互所需的机制与操作工具，由开发者掌握消息历史、应用执行流程和模型选择。

设计原则：**稳定字段统一，等价差异映射，特殊能力透传，未知信息保留。**

## 当前范围

第一阶段提供基于 Chat Completions 的异步模型连接与协议兼容层：

- 根据开发者提供的 Base URL、鉴权配置和模型 ID 调用服务。
- 支持非流式请求和基础 SSE 流式读取。
- 校验请求的基本结构及 JSON 数据。
- 通过显式配置完成字段名称映射、取值转换和自定义请求校验。
- 支持顶层扩展字段、消息内部扩展字段和自定义请求头。
- 保留响应 JSON 中的标准字段和未知扩展字段。
- 区分本地校验错误、通信错误、HTTP 错误和响应协议错误。
- 提供异步上下文管理和手动资源关闭。

第二阶段增加可选的 `ResponseAccumulator`，将流式响应块聚合为正文、思考内容和现代函数工具调用，并收集响应标识、模型、时间和用量。聚合器独立于客户端，由开发者决定是否使用，以及何时读取快照、结束聚合或处理工具调用。

第三阶段增加可选的 `Messages`，便于构造常见角色消息、保存原始消息和编辑消息内部字段。通过 `snapshot()` 取得普通消息列表后交给客户端，原有字典接口继续可用。

第四阶段增加可选的 `ToolRegistry`，支持显式注册函数工具、选择独立工具子集、导出工具定义、解析并校验调用参数，以及辅助执行同步或异步处理函数。调用校验错误提供稳定分类和调用信息；执行结果通过 `ToolResult` 提供输入参数快照与输出，由应用决定如何接回消息和继续执行。

要求 Python 3.11 或更高版本。

Saturnus 不内置模型目录，也不自动发现模型能力。Agent Loop、工具执行时机和消息历史策略由开发者决定。

## 非流式调用

以下示例从环境变量读取连接配置，并在项目环境中运行。

```python
import asyncio
import os

from saturnus import ChatClient


async def main():
    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=30.0,
    ) as client:
        response = await client.create(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        )

    print(response)


asyncio.run(main())
```

`base_url` 应为包含主机名的绝对 HTTP(S) 地址，并包含服务要求的路径前缀，例如 `https://your-service.example/v1`，末尾是否有 `/` 均可。地址中的查询字符串保持原样。不接受空白字符、控制字符、fragment（`#...`）或 URL 中的用户名和密码。

`endpoint_path` 默认为 `chat/completions`，追加在 Base URL 的路径之后。它必须是非空相对路径，不以 `/` 开头，不包含 query、fragment、空白字符、控制字符或 `.`、`..` 路径段。例如，Base URL 为 `https://your-service.example/v1?api-version=2024-01-01`、端点为 `deployments/demo/chat/completions` 时，最终路径为 `/v1/deployments/demo/chat/completions`，查询字符串保持原样。

提供 `api_key` 时，客户端发送 `Authorization: Bearer ...`。密钥必须是非空 ASCII 字符串，不接受空白字符或控制字符，也不会自动去除首尾空格。

通过 `auth_headers` 可以配置自定义鉴权，例如 `auth_headers={"api-key": "your-key"}` 或 `auth_headers={"Authorization": "Token your-key"}`。这些请求头同样接受基础校验，不能设置由 HTTP 客户端控制的 `Content-Type`、`Content-Length`、`Transfer-Encoding` 和 `Host`。

`api_key` 和 `auth_headers` 不能同时提供，即使 `auth_headers` 是空字典也会冲突。两者均省略或为 `None` 时，不添加鉴权头。

`timeout` 接受有限正数，不接受布尔值、字符串、`None`、NaN 或 Infinity。它用于配置 HTTPX 各阶段的超时，不代表整个模型生成过程的总时限。

非法连接配置在创建底层 HTTP 客户端之前抛出 `ValidationError`。

`create()` 返回完整的 JSON 字典，不要求开发者使用特定的响应对象。

## 消息构造与编辑

`Messages` 独立于客户端，只保存应用当前维护的工作消息。下面的代码在已打开客户端的异步上下文中运行：

```python
from saturnus import Messages

messages = Messages()
messages.add_system("你是一个有用的助手")
messages.add_user("你好")

response = await client.create(
    model="your-model",
    messages=messages.snapshot(),
)
messages.add(response["choices"][0]["message"])
messages.add_user("请再简短一些")
```

非流式响应的 `choice.message` 可以通过 `add()` 原样添加。聚合器的 `finalize()` 结果同样可以取出 `choice.message` 添加；消息必须包含合法的 `role`，缺失时由调用方明确补充。扩展字段包括思考内容、工具调用和厂商元数据，均按接收的原始结构保留，不自动决定下一轮是否需要发送。

### 接口

| 接口 | 行为 |
| --- | --- |
| `Messages(messages=None)` | 从原始消息列表创建独立副本；允许从空列表开始 |
| `add(message)` | 添加一条原始消息字典 |
| `add_system(content, *, extra=None)` | 添加 system 消息 |
| `add_user(content, *, extra=None)` | 添加 user 消息 |
| `add_assistant(content=None, *, extra=None)` | 添加 assistant 消息；省略 content 时明确写入 `None` |
| `add_tool_result(*, tool_call_id, content, extra=None)` | 添加 tool 结果消息，要求调用 ID 为非空白字符串 |
| `get(index)` | 返回指定消息的深拷贝 |
| `insert(index, message)` | 在指定位置前插入一条原始消息 |
| `replace(index, message)` | 用一条原始消息完整替换指定消息，不合并旧字段 |
| `remove(index)` | 删除指定位置的消息 |
| `snapshot()` | 返回全部工作消息的深拷贝，可传给客户端 |
| `len(messages)` | 返回消息数量 |

索引从 0 开始，支持负数索引，`-1` 指向最后一条消息。已有 n 条消息时，读取、替换和删除接受 `-n <= index < n`；插入接受 `-n <= index <= n`，`index=n` 表示末尾追加，负数表示在对应消息前插入。空容器只能在 0 处插入。越界或非整数索引抛出 `ValidationError`，不接受布尔值，也不把越界插入位置自动截断到首尾。

添加、插入、替换、删除及各快捷构造方法均返回 `None`。消息输入、内部数据、`get()` 结果和 `snapshot()` 结果彼此隔离；结构校验、JSON 校验或索引检查失败时，已有工作消息保持不变。

### 消息内部的扩展字段

快捷构造方法的 `extra` 合并到当前消息的顶层，与请求顶层的 `extra_body` 分开。例如，目标服务支持 assistant 消息中的 `partial` 时：

```python
from saturnus import Messages

messages = Messages()
messages.add_assistant("从前有座山", extra={"partial": True})
```

`extra` 必须为字典或 `None`，不能覆盖快捷方法构造的 `role`、`content`，工具结果中也不能覆盖 `tool_call_id`，即使重复值相同也会报错。其他合法 JSON 字段保持原样。需要自定义角色或省略 `content` 时，直接通过 `add()` 传入原始字典。

嵌套字段使用普通字典和列表操作，修改副本后显式替换原消息：

```python
messages.add(
    {
        "role": "user",
        "content": "分析这段内容",
        "vendor_options": {"mode": "brief"},
    }
)

message = messages.get(-1)
message["vendor_options"]["mode"] = "detailed"
messages.replace(-1, message)
```

上述扩展名称仅示意操作方法，是否支持及其实际含义由目标服务决定。`Messages` 不按模型名称猜测字段，不自动改名、删除或转换嵌套内容。需要反复执行消息第一层字段改名时，可以配置下文 `Compatibility` 的 `message_field_mappings` 参数。

### 校验与工具结果

消息沿用客户端的基础结构要求：`role` 为非空白字符串，`content` 可以缺失或为字符串、列表、`None`，未知角色和扩展字段均可保留。快捷方法显式写入 `content`，接受相同的基础类型。所有数据必须符合本项目的 JSON 要求。这些检查不代表特定模型支持该消息、内容块或角色组合；空消息容器可以用于组装，发送请求时仍要求非空消息列表。

`add_tool_result()` 只构造消息。应用自行执行工具并决定输出格式，例如把结果显式序列化成字符串后添加：

```python
import json

messages.add_tool_result(
    tool_call_id="call-1",
    content=json.dumps({"time": "12:00"}),
)
```

上述 `Messages` 操作只构造消息，不执行工具、序列化任意 Python 返回值或检查调用 ID 与上下文中的工具调用是否匹配。需要本地工具执行时，可以显式使用下面的 `ToolRegistry`；消息顺序、历史裁剪、思考内容的回传规则和应用循环由开发者掌握。

## 工具注册与执行

`ToolRegistry` 接收显式提供的工具名称、说明、参数 JSON Schema 和处理函数。应用通过 `definitions()` 获取 Chat Completions 的工具定义，通过 `execute()` 显式执行模型返回的工具调用。

以下示例中的循环、最大轮数和结束条件由应用定义。运行前配置 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`，并选择支持现代函数工具调用的模型。

```python
import asyncio
import os
from datetime import datetime

from saturnus import ChatClient, Messages, ToolRegistry


def get_time() -> dict[str, str]:
    return {"time": datetime.now().astimezone().isoformat()}


async def main():
    tools = ToolRegistry()
    tools.register(
        name="get_time",
        description="获取运行机器的当前时间",
        parameters={
            "type": "object",
            "properties": {},
            "additionalProperties": False,
        },
        handler=get_time,
    )
    active_tools = tools.select(["get_time"])

    messages = Messages()
    messages.add_user("请调用 get_time，告诉我现在的时间。")

    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=120.0,
    ) as client:
        for _ in range(10):
            response = await client.create(
                model=os.environ["LLM_MODEL"],
                messages=messages.snapshot(),
                extra_body={"tools": active_tools.definitions()},
            )

            choice = response["choices"][0]
            message = choice["message"]
            reason = choice["finish_reason"]
            calls = message.get("tool_calls") or []
            messages.add(message)

            if reason == "stop" and not calls:
                print(message.get("content") or "")
                break

            if reason != "tool_calls" or not calls:
                raise RuntimeError(f"Unexpected completion state: {reason!r}")

            for call in calls:
                result = await active_tools.execute(call)
                messages.add_tool_result(
                    tool_call_id=result.tool_call_id,
                    content=result.content,
                )
        else:
            raise RuntimeError("Agent exceeded maximum turns")


asyncio.run(main())
```

模型需要的其他请求参数由应用添加到 `extra_body`。工具定义是否受目标模型支持，以及思考内容的多轮回传规则，由开发者根据服务要求配置。

### 接口与校验

| 接口 | 行为 |
| --- | --- |
| `register(name=..., description=..., parameters=..., handler=...)` | 校验并保存定义与处理函数，名称重复时拒绝注册 |
| `definitions()` | 按注册顺序返回工具定义的深拷贝，不包含本地处理函数 |
| `select(names)` | 返回包含指定工具的独立注册表，按父注册表的注册顺序导出，校验和执行也受该子集限制 |
| `validate_call(call)` | 检查调用结构、工具名称和参数，返回解析后的参数字典，不执行处理函数 |
| `await execute(call)` | 先校验调用，再执行处理函数并返回 `ToolResult` |

名称必须为非空白字符串，说明必须为字符串，处理函数必须可调用。参数 Schema 必须为字典且顶层为 `type="object"`，同时满足本项目的 JSON 数据要求。注册和导出时均保存独立副本，后续修改原始 Schema 或导出结果不会改变已注册的定义。

未声明 `$schema` 时采用 JSON Schema Draft 2020-12；声明后使用对应的已识别版本，未知版本明确报错。Schema 自身在注册时检查，实际参数在调用时检查。`default` 不自动填充参数，`format` 默认不做格式断言。开发者负责使 Schema 与处理函数接收的关键字参数保持一致；函数签名不匹配时，执行阶段会抛出 `ToolExecutionError`。

`validate_call()` 和 `execute()` 接收完整的现代函数工具调用字典，要求包含非空调用 ID、`type="function"`、已注册的函数名，以及字符串形式的 `function.arguments`。参数必须解析为合法 JSON 对象，并满足注册的 Schema。输入调用保持原样，合法的未知扩展字段不影响校验，返回的参数字典与原始调用隔离。

流式场景应先正常读完响应，通过 `ResponseAccumulator.finalize()` 获得完整的工具调用，再交给工具接口。工具接口不修复残缺 JSON，不从自然语言中猜测调用。

### 工具子集与披露范围

请求中的工具定义和本地执行应使用同一个作用域。上面的示例通过 `active_tools.definitions()` 导出定义，并通过 `active_tools.execute(call)` 执行调用；未选中的工具在该作用域内按未知工具拒绝，即使父注册表中存在同名工具。

`select()` 接受工具名称列表，拒绝非列表、非字符串、空白名称、重复名称和未知名称。空列表返回空注册表；已有子集继续选择时只能选择自身已有的工具。

选择顺序不影响导出顺序：父注册顺序为 A、B、C 时，选择 `[C, A]` 或 `[A, C]` 都按 A、C 导出。定义和 Schema 独立复制，处理函数保留原引用，因此有状态处理对象仍是同一个对象。返回值是普通的 `ToolRegistry`，应用后续在父表或子表显式注册新工具，互不影响。

开发者可以按任务阶段重新选择工具，构建渐进式披露流程；发现哪些工具、何时切换，以及文件或网络资源的访问约束由应用实现。稳定的定义和顺序有助于减少请求前缀变化，实际缓存复用取决于目标服务，选择接口不承诺缓存命中。

### 结构化调用校验错误

`validate_call()` 或 `execute()` 的调用校验失败时抛出 `ToolCallValidationError`，它继承 `ValidationError`，现有的 `except ValidationError` 继续有效。注册信息或选择配置非法时仍抛出普通 `ValidationError`。

应用可读取以下稳定字段，无需解析错误说明文本：

| 字段 | 含义 |
| --- | --- |
| `code` | 下表中的错误代码 |
| `tool_call_id` | 有效的原始调用 ID；缺失或不合法时为 `None` |
| `tool_name` | 有效的原始函数名；缺失或不合法时为 `None`，未知工具仍保留其请求名称 |
| `argument_path` | Schema 不匹配时的参数路径列表，元素为字段名或数组索引；其他情况为 `None` |
| `__cause__` | 适用时保留原始 JSON、数据或 Schema 校验异常 |

| `code` | 含义 |
| --- | --- |
| `invalid_call` | 调用结构、必需字段或调用数据的 JSON 结构非法；包括 arguments 字段本身不是字符串 |
| `unknown_tool` | 当前注册表或子集中没有该工具 |
| `invalid_arguments_json` | arguments 字符串无法解析为本项目接受的有限 JSON 数据 |
| `invalid_arguments_type` | 已解析的合法 JSON 值不是对象 |
| `arguments_schema_mismatch` | 参数不满足已注册的 Schema |
| `schema_validation_error` | Schema 无法正常求值，例如本地引用无法解析；与参数不满足 Schema 分开处理 |

`argument_path=[]` 表示参数根对象，`["items", 0, "name"]` 表示对应的嵌套位置。缺失必填字段时，路径指向执行该 required 检查的对象，不自动补上缺失的字段名。

错误分类供应用决定停止、展示或回传模型，库不自动恢复。缺失有效调用 ID 时不会生成替代 ID。处理函数尚未执行的调用校验错误直接向外传播；处理函数自身抛出的异常仍归为下面的执行失败。

### 执行结果与错误

`ToolResult` 提供：

- `tool_call_id`：原始工具调用 ID。
- `arguments`：校验成功后、处理函数开始前保存的输入参数深拷贝，适合用于应用快照和调用记录。
- `value`：处理函数返回值的独立副本，必须可以表示为合法 JSON。
- `content`：供工具结果消息使用的文本；字符串原样保留，其他 JSON 值序列化为字符串。

`execute()` 每次只执行一次调用校验。`arguments` 与处理函数接收的数据、`value` 以及其他执行结果彼此隔离，处理函数修改嵌套参数不会改变输入快照。直接构造 `ToolResult` 时仍可使用原有的三个字段；省略 `arguments` 会创建独立的空字典。

结果字段不能重新赋值，但 `value` 和 `arguments` 内部的字典和列表可以修改。`content` 是执行完成时生成的文本快照，不随后续修改重新生成。

异步处理函数在调用方事件循环中等待；同步函数通过线程执行，返回可等待对象时继续等待其结果。

调用结构或参数校验失败时抛出 `ToolCallValidationError`，处理函数尚未执行。处理函数异常或结果转换失败时抛出 `ToolExecutionError`，通过 `tool_call_id`、`tool_name` 获取调用信息，通过 `__cause__` 获取原始异常。

异步取消继续向外传播。取消同步函数的等待不会强制终止已经运行的线程。并发、超时、重试，以及是否把错误转换成工具结果消息，由应用决定。

## 流式调用

```python
import asyncio
import os

from saturnus import ChatClient


async def main():
    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=60.0,
    ) as client:
        async with client.stream(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        ) as chunks:
            async for chunk in chunks:
                for choice in chunk.get("choices", []):
                    text = choice.get("delta", {}).get("content")
                    if isinstance(text, str):
                        print(text, end="", flush=True)

    print()


asyncio.run(main())
```

`stream()` 返回异步上下文管理器，其中的迭代器逐个产生 SSE `data` 事件中的 JSON 对象，保留每个对象的全部字段。

调用者自行读取文本、思考内容、工具调用或用量信息。`stream()` 本身不拼接完整回复；需要聚合时，显式使用下面的 `ResponseAccumulator`。

正常完成要求收到数据为 `[DONE]` 的完整 SSE 事件。事件必须由空行结束；仅在文件末尾出现 `data: [DONE]` 或其后只有一次换行，不算完成。连接在完整结束事件之前终止时，抛出 `ResponseError`。

除 `[DONE]` 外，每个 `data` 事件的数据必须是合法 JSON 对象。空字符串数据、非对象 JSON 或无效 JSON 都会抛出 `ResponseError`，并通过 `event_data` 保留对应的数据原文。SSE 注释和不含 `data` 字段的事件不会产生响应块。

退出流式 `async with` 块时会关闭响应，包括读取完成、提前退出、发生异常或任务取消的情况。

## 流式响应聚合

以下示例正常读完流后，再显式生成最终聚合结果：

```python
import asyncio
import os

from saturnus import ChatClient, ResponseAccumulator


async def main():
    accumulator = ResponseAccumulator()

    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=120.0,
    ) as client:
        async with client.stream(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        ) as chunks:
            async for chunk in chunks:
                accumulator.add_chunk(chunk)
                # 可以在这里读取 snapshot()，由应用自行更新界面。

    result = accumulator.finalize()
    for choice in result["choices"]:
        message = choice["message"]
        print("正文:", message.get("content", ""))
        print("思考:", message.get("reasoning_content", ""))
        print("工具调用:", message.get("tool_calls", []))
        print("结束原因:", choice["finish_reason"])

    print("用量:", result.get("usage"))


asyncio.run(main())
```

同一个响应块可以同时包含正文、思考和工具调用，聚合器会分别处理。正文、思考和函数参数按收到的顺序拼接，不去除空白，也不解析自然语言中的工具调用语句。

### 接口与结果

| 接口 | 行为 |
| --- | --- |
| `add_chunk(chunk)` | 接收单个响应块字典，先校验整个块，再更新状态；失败时抛出 `ValidationError`，已有状态和原始块记录保持不变 |
| `snapshot()` | 返回当前聚合结果的独立快照，允许结果尚未完成 |
| `raw_chunks` | 返回已接受的全部原始响应块的深拷贝，包含未知扩展字段 |
| `finalize()` | 检查完成条件，成功后封存并返回独立快照；重复调用返回内容相同的独立快照 |
| `is_finalized` | 表示显式封存是否成功，初始为 `False`；它不是网络连接状态 |

`add_chunk()` 接收流式响应中的 `choice.delta` 结构，不接收 `create()` 返回的 `choice.message` 结构。非流式响应已经是完整字典，可以直接读取，无需经过流式聚合器。

聚合结果包含 `choices` 列表，每项包含 `index`、`message` 和 `finish_reason`，按 choice index 排序。`message` 按实际收到的数据提供 `role`、`content`、`reasoning_content` 和 `tool_calls`。未收到的消息字段不自动补齐；`null` 文本不参与拼接，choice 尚未结束时收到的空字符串则保留其字段。

根级 `id`、`model` 收集首次收到的非 `null` 值，后续不同值会触发冲突错误。`created` 保留首次收到的非 `null` 值，不比较大小，也不用于判断响应身份；各分片中的原始值完整保存在 `raw_chunks`。`null` 不创建或清除这些字段。`id`、`model` 必须是非空字符串；`created` 必须是非负整数，不接受布尔值。

`usage` 必须为字典或 `null`。它按最新的非 `null` 字典整体替换，不累加 Token，也不合并不同快照；空字典同样会替换旧值。后续 `null` 不清除已有用量。未收到 `usage` 时结果不含该键；只收到 `null` 时结果包含 `usage: None`。用量可以随普通 choice 返回，也可以单独放在 `choices=[]` 的响应块中。

结果是聚合视图，不是原始响应的完整替代。`object`、`logprobs`、`annotations` 及其他未聚合字段保存在 `raw_chunks`，不会猜测它们的合并语义。输入数据、结果快照和对外返回的原始块副本彼此隔离。

### 显式配置来源字段

| 配置参数 | 默认来源字段 | 固定输出字段 |
| --- | --- | --- |
| `content_field` | `content` | `message.content` |
| `reasoning_field` | `reasoning_content` | `message.reasoning_content` |
| `tool_calls_field` | `tool_calls` | `message.tool_calls` |

例如，服务使用其他字段名，但字段结构和增量语义相同时：

```python
from saturnus import ResponseAccumulator

accumulator = ResponseAccumulator(
    content_field="text_delta",
    reasoning_field="thought_text",
    tool_calls_field="function_calls",
)
```

这些参数选择 `choice.delta` 内的字段，不支持嵌套路径；名称必须是非空白字符串，彼此不同，也不能与 `role` 相同。配置其他名称后，不会回退读取默认字段。未选中的字段作为扩展数据保存在原始块中，不参与对应的聚合结构校验，但仍须是合法 JSON 数据。

字段配置只改变读取位置，不转换结构或语义。上例的 `function_calls` 仍须是现代工具调用增量数组，不代表支持旧版 `function_call` 对象。结构或增量语义不同的服务，应由调用方先显式转换，再交给聚合器。请求侧的 `Compatibility` 不作用于响应。

### 工具调用与完成边界

当前仅聚合现代 Chat Completions 中 `type="function"` 的工具调用，按 choice index 和工具 index 分组，各自独立累积。两类 index 都必须是非负整数且不能是布尔值；同一个响应块中不能重复出现 choice index。

工具的 `id`、`type`、`function.name` 按完整身份字段处理，不进行字符串片段拼接；允许暂时缺失或为 `null`，重复相同身份值不会重复累积，出现冲突则拒绝整个响应块。`function.arguments` 按字符串增量拼接，保留空字符串以及尚未组成合法 JSON 的内容。最终输出的工具列表按工具 index 排序，不包含流式增量专用的工具 index。

`finalize()` 要求至少出现一个 choice，并且每个已出现的 choice 都有非空 `finish_reason`。已有工具调用必须收齐 `id`、`type`、函数名和参数字符串；`finish_reason="tool_calls"` 时至少存在一个工具调用。聚合器不会补全缺失身份、校验参数 JSON 或执行工具；应用在执行前还需检查结束原因、解析参数并进行自己的校验。

`length`、`content_filter` 和服务扩展的结束原因原样保留，不会仅因原因不是 `stop` 就拒绝封存。封存成功表示满足聚合结构的完成条件，不表示答案成功、内容完整或工具参数可以执行。

同一个 choice 的非空 role 不允许改变。choice 收到结束原因后，不能更改该原因或追加正文、思考、工具调用；空文本、`null`、空工具列表和重复的相同 role、结束原因可作为无新增输出的尾块接受，不改变消息快照。结束后首次补入 role 会被拒绝。结束 choice 的扩展尾块仍保留在 `raw_chunks` 中，其他 choice 可以继续输出，根级用量也可以继续到达。

**聚合器看不到 SSE 的 `[DONE]`，也不知道调用方是否提前退出循环。** 应在正常读完整个流后调用 `finalize()`，不要在 `finally` 中无条件调用。读取异常、取消或提前退出时，可用 `snapshot()` 查看部分结果，保持 `is_finalized=False`。单独收到 `finish_reason` 不会自动封存。

封存校验失败不会改变状态；尚未结束的 choice 可以继续接收后续块。封存成功后拒绝所有新的 `add_chunk()`，包括用量块，因此每次模型请求应创建独立的聚合器。

聚合器会在内存中保存拼接数据和全部原始块，`snapshot()` 和 `raw_chunks` 还会生成副本。长输出场景应由应用控制读取快照的频率；只需要原始增量时，可以直接使用 `stream()`。

## 响应元信息

`create()` 返回完整字典，`stream()` 提供响应块迭代器。需要读取 HTTP 状态码或响应头时，使用对应的元信息接口。

以下代码在已打开客户端的异步上下文中运行：

```python
result = await client.create_with_response(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
)

print(result.data)
print(result.response.status_code)
print(result.response.headers.get("x-request-id"))

async with client.stream_with_response(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
) as result:
    print(result.response.status_code)
    print(result.response.headers.get("x-request-id"))

    async for chunk in result.chunks:
        print(chunk)
```

`create_with_response()` 返回 `ChatResponse`，包含完整响应字典 `data` 和原始 `httpx.Response` 对象 `response`。

`stream_with_response()` 提供 `ChatStreamResponse`，包含响应块迭代器 `chunks` 和原始 HTTP 响应 `response`。进入上下文后即可读取响应头，不会提前消费响应块。通过 `chunks` 在上下文内部读取流式数据，退出上下文时关闭响应。

这些包装保留原始模型字段，沿用普通接口的请求校验、兼容规则和错误分类。具体响应头是否存在，由目标服务决定。

## 扩展字段

`extra_body` 合并到请求 JSON 顶层。例如，在支持该参数的服务上关闭 Thinking：

```python
response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "thinking": {"type": "disabled"},
    },
)
```

消息可以直接使用字典。Saturnus 保留消息内部未知但合法的 JSON 字段，不保证目标服务支持这些字段。

`model`、`messages` 和 `stream` 由客户端接口控制，不能通过 `extra_body` 指定；发生冲突时抛出 `ValidationError`。

请求 JSON 要求对象键为字符串、数组使用列表，不接受 NaN、Infinity、循环引用或其他无法表示为 JSON 的数据。

自定义请求头通过 `extra_headers` 提供，仅作用于当前请求：

```python
response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_headers={"X-Request-ID": "example-request"},
)
```

当前请求头校验支持合法的 ASCII 名称和值，拒绝大小写不敏感的重复名称。以下请求头由客户端控制，不能通过 `extra_headers` 覆盖：

- `Authorization`
- `Content-Type`
- `Content-Length`
- `Transfer-Encoding`
- `Host`

通过 `auth_headers` 配置的所有请求头，也不能被 `extra_headers` 覆盖。冲突判断不区分大小写。客户端保存鉴权头的独立副本，后续修改原始配置字典不会改变已创建客户端的鉴权。

## 显式兼容规则

开发者根据目标服务配置 `Compatibility`，Saturnus 不根据模型名称自动选择规则。

```python
from saturnus import Compatibility

compatibility = Compatibility(
    field_mappings={
        "output_tokens": "max_completion_tokens",
        "thinking_mode": "thinking",
    },
    value_mappings={
        "thinking_mode": {
            "off": {"type": "disabled"},
            "on": {"type": "enabled"},
        },
    },
)
```

创建客户端时传入 `compatibility=compatibility`，随后可以使用：

```python
response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "output_tokens": 64,
        "thinking_mode": "off",
    },
)
```

上述配置将两个扩展字段转换为：

```json
{
  "max_completion_tokens": 64,
  "thinking": {"type": "disabled"}
}
```

顶层 `field_mappings`、`value_mappings` 规则具有以下行为：

- 仅作用于请求顶层字段。
- 取值映射按转换前的来源字段名称配置，不会自动使用重命名后的目标字段名称查找规则。
- 仅字符串取值参与取值映射，映射结果可以是任意合法 JSON 值。数字、布尔值、对象、数组和 null 等来源值保持原样。
- 字段和取值映射各执行一次，不进行链式转换。
- 未配置的字段和未匹配的取值保持原样。
- 字段映射的来源、目标，以及取值映射的字段名均不能为空字符串；允许空规则表。
- 禁止映射 `model`、`messages` 和 `stream`。
- 映射目标已经存在，或多个实际请求字段指向同一目标时，抛出 `ValidationError`。
- 不修改调用者传入的请求数据。`apply()` 返回独立的数据快照，嵌套消息和扩展对象也与入参隔离。

还可以通过 `Compatibility(validator=...)` 提供同步校验函数。该函数接收转换后请求的深拷贝；对这份副本的修改不会写回请求。校验成功必须返回 `None`，校验失败应抛出 `ValidationError`。异步校验函数不受支持，函数中的其他异常原样向外传播。

兼容配置同样适用于 `create()`、`create_with_response()`、`stream()` 和 `stream_with_response()`。

### 按角色映射消息字段

通过 `message_field_mappings` 明确配置“消息角色 → 来源字段 → 目标字段”。例如，目标服务要求将 assistant 消息中的 `thought` 改名为 `reasoning_content`：

```python
from saturnus import Compatibility, Messages

compatibility = Compatibility(
    message_field_mappings={
        "assistant": {"thought": "reasoning_content"},
    },
)

messages = Messages(
    [
        {"role": "user", "content": "你好"},
        {"role": "assistant", "content": "你好呀", "thought": "简短回应"},
    ]
)

request = {"model": "your-model", "messages": messages.snapshot()}
mapped = compatibility.apply(request)

assert mapped["messages"][1] == {
    "role": "assistant",
    "content": "你好呀",
    "reasoning_content": "简短回应",
}
assert messages.get(1)["thought"] == "简短回应"
assert request["messages"][1]["thought"] == "简短回应"
```

上例通过 `apply()` 展示转换结果。实际请求只需把配置传入 `ChatClient(..., compatibility=compatibility)`，客户端会在发送时执行规则；应用继续传入 `messages.snapshot()` 或原始消息列表。

规则按以下约定执行：

- 角色与字段名称按字符串精确匹配，不自动去除空白或推断模型；允许自定义角色，不提供通配符语义。
- 只处理每条消息的第一层字段，不遍历 `content[]`、`tool_calls[]` 或其他嵌套对象，字段名中的点号等字符不解释为路径。
- 角色、来源和目标名称必须为非空白字符串；每个角色的规则必须为字典，允许空规则表。`None` 或空的总配置表示不开启消息映射。
- `role`、`content` 不能作为映射来源或目标。其他字段仅改名，取值保持原有类型和结构，包括 `None`、对象和列表。
- 角色不匹配或来源字段不存在时保持原样；来源缺失时不创建目标字段，也不删除已经存在的目标字段。
- 按原始消息字段映射一次，不进行链式转换。普通字段映射到自身时保持原样。
- 来源和不同名称的目标同时存在时抛出 `ValidationError`，即使值相同、目标为 `None`，或目标还配置了另一条改名规则也一样。
- 多个实际出现的来源字段映射到同一目标时抛出 `ValidationError`；不同消息分别处理，互不冲突。
- 消息结构、JSON 或映射冲突导致失败时，调用方消息和配置保持不变，客户端不会发送请求。冲突错误说明包含消息位置与目标名称。

转换顺序为请求顶层字段及取值映射、消息字段改名、最后执行 `validator`。校验函数接收全部转换完成后的独立副本，其修改仍不会写回请求。启用消息规则且请求包含 `messages` 时，还会检查消息列表与每条消息的基本结构。

消息规则可以和顶层规则同时配置，不会修改应用保存的工作消息或服务端返回的数据。响应聚合时的来源字段通过 `ResponseAccumulator` 单独配置；两种配置不会自动互相推导。字段结构转换、消息内取值映射和嵌套路径转换由应用按实际需求处理。

## 错误处理

所有库定义的错误继承自 `SaturnusError`。

| 错误类型 | 含义 | 可读取的信息 |
| --- | --- | --- |
| `ValidationError` | 本地连接配置、请求数据、兼容配置、消息操作、聚合数据及状态、工具注册或调用参数不合法 | 错误说明 |
| `ToolCallValidationError` | 工具调用校验失败，继承 `ValidationError` | `code`、`tool_call_id`、`tool_name`、`argument_path`、`__cause__` |
| `ToolExecutionError` | 工具处理函数或结果转换失败 | `tool_call_id`、`tool_name`、`__cause__` |
| `TransportError` | 连接失败、超时或流式读取中断 | `__cause__` 中的底层异常 |
| `APIError` | 服务端返回非成功 HTTP 状态 | `response` 中的 HTTP 响应及响应体 |
| `ResponseError` | 响应不符合预期协议 | `response`，以及适用时的 `event_data` |

`ResponseError` 包括非流式响应不是合法 JSON 对象、流式响应类型不正确、事件 JSON 无效或缺少 `[DONE]` 等情况。非流式响应和流式事件均拒绝非标准 JSON 数值常量 NaN、Infinity 和 -Infinity，并抛出 `ResponseError`。字符串 `"NaN"` 等普通文本不受影响。

客户端流式读取不会预先缓存整个响应；选择使用 `ResponseAccumulator` 时，由聚合器累计数据。解析事件失败时，可以通过 `event_data` 读取对应事件的数据原文。

## 资源管理

推荐通过 `async with ChatClient(...)` 管理客户端生命周期。

需要手动管理时，调用 `await client.aclose()` 关闭客户端。流式请求还需使用独立的 `async with client.stream(...)` 或 `async with client.stream_with_response(...)` 块管理响应生命周期。

## 自定义 HTTP 传输

客户端接受可选的 `transport` 参数，类型为 `httpx.AsyncBaseTransport`。可以传入 `httpx.MockTransport` 进行测试，或传入自行配置证书、代理等选项的 `httpx.AsyncHTTPTransport`。

以下示例在异步函数内运行，不访问真实服务：

```python
import httpx

from saturnus import ChatClient

transport = httpx.MockTransport(
    lambda request: httpx.Response(200, json={"choices": []})
)

async with ChatClient(
    base_url="https://llm.example/v1",
    transport=transport,
) as client:
    response = await client.create(
        model="my-model",
        messages=[{"role": "user", "content": "hello"}],
    )
```

传入的 transport 由 `ChatClient` 管理生命周期。退出客户端上下文或调用 `aclose()` 时会关闭它，每个客户端应使用独立的 transport 实例。

退出单次流式上下文只关闭该响应，客户端及其 transport 可以继续用于后续请求。

## 第一阶段联调记录

2026-10-28，使用同一套客户端接口完成以下真实服务测试：

| 服务 | Base URL | 模型 | Token 上限字段 | 非流式 | 流式 |
| --- | --- | --- | --- | --- | --- |
| DeepSeek API | `https://api.deepseek.com` | `deepseek-flash` | `max_tokens` | 通过 | 通过 |
| MiMo Token Plan | `https://token-plan-cn.xiaomimimo.com/v1` | `mimo-v2.6-flash` | `max_completion_tokens` | 通过 | 通过 |

两项配置均通过显式规则将 `output_tokens` 映射为目标字段，并透传 `thinking: {"type": "disabled"}`。每次请求的输出上限为 64 Token，流式读取均正常收到 `[DONE]`。

此记录仅代表上述模型与配置的联调结果。MiMo Token Plan 使用套餐控制台提供的专属 Base URL 和 API Key。

## 第二阶段联调记录

2026-10-30，使用上述两项服务配置，通过同一个 `ResponseAccumulator` 接口完成以下真实流式聚合验收：

| 服务 | 模型 | 正文（Thinking 关闭） | 正文与思考（Thinking 开启） | 函数工具调用（Thinking 关闭） |
| --- | --- | --- | --- | --- |
| DeepSeek API | `deepseek-flash` | 通过 | 通过 | 通过 |
| MiMo Token Plan | `mimo-v2.6-flash` | 通过 | 通过 | 通过 |

六项请求均正常读完 SSE 流后调用 `finalize()`。验收检查了正文与思考的分别聚合、工具名称与参数字符串，以及已返回的根级元信息和最新用量快照的保留。工具参数由验收脚本单独解析和检查，未执行工具。

MiMo 思考响应的一个样本在相同 `id`、`model` 下返回了变化的 `created`。聚合器按统一规则保留首次收到的非 `null` 时间值，原始分片中的各个值仍完整保留，不根据厂商名称选择行为。

本地完整代码检查、格式检查、自动化测试、构建和 wheel 安装导入验证通过。上述联调只覆盖表中模型、配置和三种分别测试的模式，不代表所有兼容服务或 Thinking 与工具调用组合均已验证。

## 本地开发

```bash
uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest -q
uv build
```

GitHub CI 配置为在 Python 3.11–3.14 下执行代码检查、测试、构建和 wheel 安装导入验证。

自动化测试通过模拟 HTTP 传输运行，不需要真实 API Key。真实服务联调单独进行。
