# modelweave

**Repository Path**: c031001/modelweave

## Basic Information

- **Project Name**: modelweave
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# modelweave

`modelweave` 是 OpenAI Python SDK 的轻量封装，提供两套协议的消息构造与结果解析：

- `modelweave.completions`：Chat Completions API（`/chat/completions`），适合传统消息列表协议。
- `modelweave.responses`：Responses API（`/responses`），适合推理、流式响应、图片生成和结构化工具调用。

## 安装

```bash
pip install "git+https://gitee.com/c031001/modelweave.git@master"
```

本地开发安装：

```bash
pip install -e .
```

依赖中已包含 `openai`。下面的示例使用环境变量，避免把密钥写进代码：

```python
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL"),  # 使用官方 API 时可删除此行
)
```

## 协议选择

| 场景                                     | 推荐接口                                                         |
| ---------------------------------------- | ---------------------------------------------------------------- |
| 常规对话、兼容既有 Chat Completions 代码 | `modelweave.completions`                                       |
| Responses 非流式文本、视觉理解、函数工具 | `modelweave.responses.create_response`                         |
| Responses 流式文本、推理或图片预览       | `modelweave.responses.stream_response`                         |
| 仅需一次性文生图或参考图编辑             | OpenAI SDK 的`client.images.generate` / `client.images.edit` |

`create_completion()` 只封装非流式 Chat Completions 响应。Responses 的流式请求请使用 `stream_response()` 或 `open_response_stream()`。

## Chat Completions

### 基本文本对话

```python
from modelweave.completions import build_user_message, create_completion

result = create_completion(
    client,
    model="gpt-4.1-mini",
    messages=[build_user_message("用一句话解释什么是递归。")],
)

print(result.text)
```

### system、developer、assistant 消息

```python
from modelweave.completions import (
    build_assistant_message,
    build_developer_message,
    build_system_message,
    build_user_message,
    create_completion,
)

result = create_completion(
    client,
    model="gpt-4.1-mini",
    messages=[
        build_system_message("你是一位简洁的中文助手。"),
        # GPT 最新模型使用 developer 替代 system
        build_developer_message("回答不超过三句话。"),
        build_user_message("Python 的 list 和 tuple 有什么区别？"),
        build_assistant_message("它们都是 Python 的有序容器。"),
        build_user_message("继续说明可变性方面的区别。"),
    ],
)

print(result.text)
```

### 图片理解

Chat Completions 的图片输入使用 `InputImage(url=...)`。`url` 可以是公网 URL 或 `data:image/...;base64,...` 数据 URL。

```python
from modelweave.completions import InputImage, build_user_message, create_completion

result = create_completion(
    client,
    model="gpt-4.1-mini",
    messages=[
        build_user_message(
            "描述这张图片中的主体、颜色与风格。",
            InputImage("https://example.com/photo.png", detail="high"),
        )
    ],
)

print(result.text)
```

### 函数工具调用

`result.tool_calls` 已将函数参数 JSON 解析为字典。执行工具后，使用 `build_assistant_message()` 和 `build_tool_message()` 继续对话。

```python
import json

from modelweave.completions import (
    build_assistant_message,
    build_tool_message,
    build_user_message,
    create_completion,
)

weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的实时天气。",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
    },
}

messages = [build_user_message("上海现在天气如何？")]
first = create_completion(
    client,
    model="gpt-4.1-mini",
    messages=messages,
    tools=[weather_tool],
)

if first.tool_calls:
    tool_call = first.tool_calls[0]
    weather = {"city": tool_call.arguments["city"], "temperature": "24°C", "condition": "晴"}
    messages.extend([
        build_assistant_message(tool_calls=first.tool_calls),
        build_tool_message(json.dumps(weather, ensure_ascii=False), tool_call),
    ])
    final = create_completion(client, model="gpt-4.1-mini", messages=messages, tools=[weather_tool])
    print(final.text)
```

## Responses

### 基本文本对话（非流式）

```python
from modelweave.responses import build_user_message, create_response

result = create_response(
    client,
    model="gpt-4.1-mini",
    input=[build_user_message("用一句话解释什么是递归。")],
)

print(result.text)
print(result.reasoning)  # 没有推理摘要时为空字符串
```

### developer、assistant 消息

```python
from modelweave.responses import (
    build_assistant_message,
    build_developer_message,
    build_user_message,
    create_response,
)

result = create_response(
    client,
    model="gpt-4.1-mini",
    input=[
        build_developer_message("用中文回答，且不超过三句话。"),
        build_user_message("Python 的 list 和 tuple 有什么区别？"),
        build_assistant_message("它们都是 Python 的有序容器。"),
        build_user_message("继续说明可变性方面的区别。"),
    ],
)

print(result.text)
```

### 图片理解

Responses 的图片 part 使用 `InputImage(image_url=...)` 或 `InputImage(file_id=...)`。

```python
from modelweave.responses import InputImage, build_user_message, create_response

result = create_response(
    client,
    model="gpt-4.1-mini",
    input=[
        build_user_message(
            "描述这张图片中的主体、颜色与风格。",
            InputImage(image_url="https://example.com/photo.png", detail="high"),
        )
    ],
)

print(result.text)
```

### 函数工具调用

Responses 的函数工具格式与 Chat Completions 不同：`name`、`description`、`parameters` 直接位于工具对象顶层。

```python
import json

from modelweave.responses import (
    build_function_call_item,
    build_function_call_output_item,
    build_user_message,
    create_response,
)

weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "查询指定城市的实时天气。",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": False,
    },
}

user_message = build_user_message("上海现在天气如何？")
first = create_response(
    client,
    model="gpt-4.1-mini",
    input=[user_message],
    tools=[weather_tool],
)

if first.tool_calls:
    tool_call = first.tool_calls[0]
    weather = {"city": tool_call.arguments["city"], "temperature": "24°C", "condition": "晴"}
    final = create_response(
        client,
        model="gpt-4.1-mini",
        input=[
            user_message,
            build_function_call_item(tool_call),
            build_function_call_output_item(tool_call, json.dumps(weather, ensure_ascii=False)),
        ],
        tools=[weather_tool],
    )
    print(final.text)
```

### 文生图（非流式）

Responses 的图片生成通过 `image_generation` 工具完成，完整图片位于 `result.image_generation_calls[*].result`（Base64）。使用支持该工具的主线模型；以下为 VibeAPI 的 `gpt-5.5` 示例。

```python
"""
ImageGeneration参数列表：
	1. action: Literal["generate", "edit", "auto"]
    Whether to generate a new image or edit an existing image. Default: `auto`.

    2. background: Literal["transparent", "opaque", "auto"]
    Allows to set transparency for the background of the generated image(s). Must be
    one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used,
    the model will automatically determine the best background for the image.
    Transparent backgrounds are available for supported GPT Image models. For
    `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When
    using `transparent`, set the output format to `png` or `webp`.

    3. input_fidelity: Optional[Literal["high", "low"]]
    Control how much effort the model will exert to match the style and features,
    especially facial features, of input images. This parameter is only supported
    for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for
    `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

    4. model: Union[
        str,
        Literal[
            "gpt-image-1",
            "gpt-image-1-mini",
            "gpt-image-2",
            "gpt-image-2-2026-04-21",
            "gpt-image-1.5",
            "chatgpt-image-latest",
        ],
    ]

    5. partial_images: int
    Number of partial images to generate in streaming mode, from 0 (default value) to 3.

    6. quality: Literal["low", "medium", "high", "auto"]
    The quality of the generated image.
    One of `low`, `medium`, `high`, or `auto`. Default: `auto`.

    7. size: Union[str, Literal["1024x1024", "1024x1536", "1536x1024", "auto"]]
    The size of the generated images.
    For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are
    supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height
    must both be divisible by 16 and the requested aspect ratio must be between 1:3
    and 3:1. Resolutions above `2560x1440` are experimental, and the maximum
    supported resolution is `3840x2160`. The requested size must also satisfy the
    model's current pixel and edge limits. The standard sizes `1024x1024`,
    `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is
    supported for models that allow automatic sizing. For `dall-e-2`, use one of
    `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`,
    `1792x1024`, or `1024x1792`.
"""

import base64
from pathlib import Path

from openai.types.responses.tool_param import ImageGeneration
from modelweave.responses import build_user_message, create_response

result = create_response(
    client,
    model="gpt-5.5",
    input=[build_user_message("生成一张水彩风格的冬日山景，远处雪山、近处松树和木屋，暖色晨光。")],
    tools=[
        ImageGeneration(
            type="image_generation",
            quality="high",
            size="1536x1024",
            output_format="png",
        )
    ],
)

if not result.image_generation_calls or not result.image_generation_calls[0].result:
    raise RuntimeError("模型未返回图片")

Path("generated.png").write_bytes(base64.b64decode(result.image_generation_calls[0].result))
```

### 文本流式输出

```python
from modelweave.responses import build_user_message, stream_response

result = stream_response(
    client,
    model="gpt-4.1-mini",
    input=[build_user_message("介绍一下 Python 的生成器。")],
    on_text_delta=lambda delta, _item_id, _content_index: print(delta, end="", flush=True),
    on_reasoning_delta=lambda delta, _item_id, _summary_index: print(delta, end="", flush=True),
)

print("\n\n完整文本：", result.text)
```

### 图片生成（流式预览）

`on_image_generation_delta` 在收到 `response.image_generation_call.partial_image` 事件时被调用。每个预览均是完整的 Base64 图片，可直接覆盖同一个文件。

```python
import base64
from pathlib import Path

from openai.types.responses.tool_param import ImageGeneration
from modelweave.responses import build_user_message, stream_response


def save_preview(image_b64: str, _item_id: str) -> None:
    Path("preview.png").write_bytes(base64.b64decode(image_b64))


result = stream_response(
    client,
    model="gpt-5.5",
    input=[build_user_message("生成一张水彩风格的冬日山景。")],
    tools=[
        ImageGeneration(
            type="image_generation",
            quality="high",
            size="1536x1024",
            output_format="png",
            partial_images=1,
        )
    ],
    on_image_generation_delta=save_preview,
)

if result.image_generation_calls and result.image_generation_calls[0].result:
    Path("generated.png").write_bytes(
        base64.b64decode(result.image_generation_calls[0].result)
    )
```

### 手动消费流

需要自行处理完整 SSE 事件时，使用 `open_response_stream()`。处理完后调用 `session.build()` 获取 `ParsedResponse`。

```python
from modelweave.responses import build_user_message, open_response_stream

with open_response_stream(
    client,
    model="gpt-4.1-mini",
    input=[build_user_message("你好")],
) as session:
    for event in session.iter_events():
        print(event["type"])
        session.consume_event(event)

result = session.build()
print(result.text)
```

## Image API（OpenAI SDK 直连）

`modelweave` 只封装 Chat Completions 和 Responses。只需单次生成或编辑图片时，直接使用 OpenAI SDK 的 Image API 即可。

```python
import base64
from pathlib import Path
from urllib.request import urlopen

image = client.images.generate(
    model="gpt-image-2",
    prompt="生成一张极简风格的山间日出插画。",
    quality="medium",
    size="1536x1024",
    output_format="png",
).data[0]

if image.b64_json:
    Path("generated.png").write_bytes(base64.b64decode(image.b64_json))
elif image.url:
    with urlopen(image.url, timeout=60) as response:
        Path("generated.png").write_bytes(response.read())
else:
    raise RuntimeError("图片响应中既没有 b64_json，也没有 url")
```

编辑参考图时改用 `client.images.edit()`，并传入二进制文件：

```python
from pathlib import Path

with Path("source.png").open("rb") as source:
    result = client.images.edit(
        model="gpt-image-2",
        image=source,
        prompt="将画面改为水彩风格。",
        quality="medium",
        size="1536x1024",
    )
```

不同兼容网关可能返回 `data[0].b64_json` 或 `data[0].url`，保存图片时应兼容两者，如上例所示。

## 返回类型

### `ParsedCompletion`

`create_completion()` 返回：

```text
ParsedCompletion(
    text: str,
    reasoning: str,
    tool_calls: list[ToolCall],
    raw_response: Any,
)
```

### `ParsedResponse`

`create_response()` 和 `stream_response()` 返回：

```text
ParsedResponse(
    text: str,
    reasoning: str,
    tool_calls: list[ToolCall],
    image_generation_calls: list[ImageGenerationCall],
    raw_response: Any,
)
```

两类结果均提供 `has_text`、`has_reasoning`、`has_tool_calls` 属性。`ParsedResponse` 额外提供 `has_image_generation_calls`。

`ToolCall` 的字段如下：

```text
ToolCall(
    name: str,
    arguments: dict[str, Any],
    raw_arguments: str,
    call_id: str,
)
```

## 对外 API

### `modelweave.completions`

- `create_completion`
- `ParsedCompletion`、`ToolCall`
- `InputImage`
- `build_system_message`、`build_developer_message`、`build_user_message`
- `build_assistant_message`、`build_tool_message`

### `modelweave.responses`

- `create_response`、`stream_response`、`open_response_stream`
- `ParsedResponse`、`ToolCall`、`ImageGenerationCall`
- `TextDeltaHandler`、`ReasoningDeltaHandler`、`ImageGenerationDeltaHandler`
- `InputImage`
- `build_developer_message`、`build_user_message`、`build_assistant_message`
- `build_function_call_item`、`build_function_call_output_item`