# 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-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# modelweave

`modelweave` 是一个围绕 OpenAI Responses API 的轻量工具包，专门处理两类问题：

- 构造标准输入消息
- 统一解析流式/非流式返回结果

## 安装

### 1. 直接从本地目录安装

```bash
pip install /path/to/modelweave
```

或

```bash
uv add /path/to/modelweave
```

### 2. 从 Git 仓库安装

如果仓库是公开的，可以直接从 Gitee 安装：

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

```bash
uv add "git+https://gitee.com/c031001/modelweave.git@master"
```

安装时会自动带上 `openai>=2.30.0`，不需要再单独安装 `openai`。

## 用法

### 非流式

```python
from openai import OpenAI
from modelweave import build_user_message, create_response

client = OpenAI(api_key="xxx", base_url="xxx")

parsed = create_response(
    client,
    model="gpt-4.1",
    input=[build_user_message("你好")],
)

print(parsed.text_blocks)
```

### 流式

```python
from openai import OpenAI
from modelweave import build_user_message, stream_response

client = OpenAI(api_key="xxx", base_url="xxx")

parsed = stream_response(
    client,
    model="gpt-4.1",
    input=[build_user_message("你好")],
    on_text_delta=lambda delta, item_id, content_index: print(delta, end="", flush=True),
)

print(parsed.text_blocks)
```

## 对外 API

- `build_user_message`
- `build_developer_message`
- `build_assistant_message`
- `build_function_call_item`
- `build_function_call_output_item`
- `create_response`
- `stream_response`
- `ParsedResponse`
- `ToolCall`
- `TextDeltaHandler`
- `ReasoningDeltaHandler`
- `ToolCallHandler`

## 返回结构说明

`build_function_call_item` 可用于手动构造一条 function call 输入项：

```python
build_function_call_item(
    name="lookup_weather",
    arguments='{"city":"Shanghai"}',
    call_id="call_123",
)
```

`ParsedResponse.tool_calls` 中的每个元素都是 `ToolCall`：

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

- `arguments` 是解析后的字典，便于业务直接使用
- `raw_arguments` 是模型原始返回的 JSON 字符串，便于排查问题或保留原始数据

`ParsedResponse` 当前结构是：

```python
ParsedResponse(
    text_blocks: list[str],
    reasoning_blocks: list[str],
    response_items: list[dict[str, Any]],
    next_input_items: list[dict[str, Any]],
    tool_calls: list[ToolCall],
    raw_response: Any,
)
```

- `text_blocks` 保留 message 级别边界
- `reasoning_blocks` 保留 reasoning 级别边界
- `response_items` 是模型本次返回的消息项列表，对应旧版的 `next_input_items`
- `next_input_items` 是“本次传入的 input + 模型本次返回的 items”，可直接回填到下一轮模型输入，主要用于多轮对话或 agent 场景
- `has_text` 用于快速判断当前响应里是否包含文本输出
- `has_reasoning` 用于快速判断当前响应里是否包含 reasoning 输出
- `has_tool_calls` 用于快速判断当前响应里是否包含 tool call

流式回调签名：

- `on_text_delta(delta: str, item_id: str, content_index: int)`
- `on_reasoning_delta(delta: str, item_id: str, summary_index: int)`
- `on_tool_call(tool_call: ToolCall)`