wuwei 3.2.1__tar.gz → 3.2.2__tar.gz

{wuwei-3.2.1 → wuwei-3.2.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 更新日志
 
+## 3.2.2 — 2026-10-28
+
+- OpenAI SDK 最低版本更新至 3.40.0，Responses 支持显式配置 prompt_cache_options / prompt_cache_key。
+- 缓存读取、缓存写入和推理 token 细分统计贯通普通/流式运行、委派与规划汇总，不重复计入总 token。
+- Responses 默认省略 temperature；保留显式配置、Chat Completions 默认值和适配器原有位置参数兼容性。
+- 补充缓存配置、预算估算边界及离线 SDK 契约测试。
+
 ## 3.2.1 — 2026-10-28
 
 - 更新补丁版本号，承接执行契约、模型接入及协议兼容性加固。

{wuwei-3.2.1 → wuwei-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wuwei
-Version: 3.2.1
+Version: 3.2.2
 Summary: Wuwei - 无为而治的 AI 智能体框架
 Author-email: xiaojiaenen <xiaojiaenen@163.com>
 License-Expression: Apache-2.0
@@ -10,7 +10,7 @@ Project-URL: Documentation, https://github.com/xiaojiaenen/wuwei
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: openai>=3.23.0
+Requires-Dist: openai>=3.40.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: httpx>=0.25.0

{wuwei-3.2.1 → wuwei-3.2.2}/USAGE.md

@@ -27,6 +27,35 @@ llm = LLMGateway({"provider": "openai", "client": client,
 
 框架自建 SDK client 默认关闭 SDK 重试，让网关负责分类重试。借入客户端也应明确 retry 所有权；否则 SDK 与框架尝试次数可能相乘。`set_fallback(other_gateway)` 借用完整 fallback 策略，调用方管理 other_gateway 生命周期。已发布流式内容、工具或 usage 元数据后不重放请求。确定性参数错误不做传输重试。
 
+## OpenAI Responses：缓存与新模型参数
+
+Responses 默认不发送 `temperature`，避免向不支持采样参数的模型强加旧默认值。显式配置数字仍会发送；`None` 表示省略，由服务端决定。Chat Completions 保留 `temperature=0.2` 兼容默认值；使用不支持该参数的模型时显式设为 `None`。
+
+```python
+import os
+from wuwei import LLMGateway
+
+llm = LLMGateway({
+    "provider": "responses",
+    "api_key": os.environ["OPENAI_API_KEY"],
+    "model": os.environ["OPENAI_MODEL"],
+    "max_output_tokens": 4096,
+    "prompt_cache_key": "wuwei:assistant:v1",
+    "prompt_cache_options": {"mode": "implicit", "ttl": "30m"},
+})
+# 使用完 await llm.aclose()。
+```
+
+缓存参数要求支持该能力的 OpenAI 模型和服务端；自定义兼容端点未必接受。模型名称不设硬编码白名单，`reasoning` 等提供商参数可透传，但具体参数组合仍须符合模型契约。缓存 key 仅为稳定路由提示，不保证命中，也不要放入密钥或敏感身份信息。
+
+上例采用隐式断点。`mode="explicit"` 需要额外的内容块断点；当前字符串消息入口不提供断点构建能力，不应只切换 mode 而期待缓存生效。请求级 TTL 与旧 `prompt_cache_retention` 含义不同，框架不会自动互相转换。
+
+Chat Completions 推理模型可配置 `temperature=None`、`max_completion_tokens=4096`；此时不会同时发送旧 `max_tokens`。`reasoning_effort` 等参数由模型决定是否支持，不通过模型名称猜测或静默删除显式配置。
+
+响应 `usage` 在服务端提供时包含 `cached_tokens`（缓存读取）、`cache_write_tokens`（缓存写入）、`reasoning_tokens`（推理输出）；普通运行、流式运行、子任务和规划汇总保留这些字段。缺失字段不伪造为已测量值。这些是输入/输出 token 的细分，不额外加到 `total_tokens`。
+
+预算仍按配置的输入/输出价格估算，不根据这些细分字段自动套用缓存折扣或写入附加费；需要精确账单时，以服务端账单为准。新模型应显式配置预算价格，避免使用通用估算价。
+
 ## 注册有参数契约的工具
 
 ```python

{wuwei-3.2.1 → wuwei-3.2.2}/docs/RELEASING.md

@@ -25,9 +25,9 @@
 ```bash
 git switch master
 git pull --ff-only origin master
-# 当前项目版本为 3.2.1；后续按实际版本修改标签。
-git tag -a v3.2.1 -m 'Release 3.2.1'
-git push origin v3.2.1
+# 当前项目版本为 3.2.2；后续按实际版本修改标签。
+git tag -a v3.2.2 -m 'Release 3.2.2'
+git push origin v3.2.2
 ```
 
 在 Actions 查看 Publish to PyPI，必要时批准 `pypi` 环境部署。推送标签会触发正式上传；不要在绑定完成前推送。标签必须严格等于 `v` + `project.version`，否则发布会被阻止。
@@ -35,7 +35,7 @@ git push origin v3.2.1
 上传后在 https://pypi.org/project/wuwei/ 确认版本，并在独立环境安装验证：
 
 ```bash
-uv run --isolated --no-project --with 'wuwei==3.2.1' \
+uv run --isolated --no-project --with 'wuwei==3.2.2' \
   python -c "from importlib.metadata import version; print(version('wuwei'))"
 ```
 

{wuwei-3.2.1 → wuwei-3.2.2}/docs/changelog.md

@@ -1,5 +1,12 @@
 # 更新日志
 
+## 3.2.2 — 2026-10-28
+
+- OpenAI SDK 最低版本更新至 3.40.0，Responses 支持显式配置 prompt_cache_options / prompt_cache_key。
+- 缓存读取、缓存写入和推理 token 细分统计贯通普通/流式运行、委派与规划汇总，不重复计入总 token。
+- Responses 默认省略 temperature；保留显式配置、Chat Completions 默认值和适配器原有位置参数兼容性。
+- 补充缓存配置、预算估算边界及离线 SDK 契约测试。
+
 ## 3.2.1 — 2026-10-28
 
 - 更新补丁版本号，承接执行契约、模型接入及协议兼容性加固。

{wuwei-3.2.1 → wuwei-3.2.2}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wuwei"
-version = "3.2.1"
+version = "3.2.2"
 description = "Wuwei - 无为而治的 AI 智能体框架"
 authors = [{name = "xiaojiaenen", email = "xiaojiaenen@163.com"}]
 license = "Apache-2.0"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "openai>=3.23.0",
+    "openai>=3.40.0",
     "pydantic>=2.0.0",
     "pyyaml>=6.0.3",
     "httpx>=0.25.0",

wuwei-3.2.2/tests/test_openai_sdk_capabilities.py

@@ -0,0 +1,127 @@
+from types import SimpleNamespace as Ns
+
+import pytest
+
+from wuwei.llm.adapters.openai import OpenAIAdapter
+from wuwei.llm.adapters.responses import ResponsesAdapter
+from wuwei.llm.gateway import LLMGateway
+from wuwei.runtime.agent_runner import _merge_usage
+
+
+def test_modern_responses_omits_sampling_unless_explicit():
+    adapter = LLMGateway({'provider': 'responses', 'api_key': 'unused', 'client': Ns()}).adapter
+    assert 'temperature' not in adapter.build_request([])
+    assert adapter.build_request([], temperature=0.7)['temperature'] == 0.7
+    assert 'temperature' not in adapter.build_request([], temperature=None)
+
+
+def test_legacy_chat_defaults_and_explicit_modern_parameters():
+    old = OpenAIAdapter('unused', client=Ns())
+    assert old.build_request([])['temperature'] == 0.2
+    modern = LLMGateway({'api_key': 'unused', 'client': Ns(), 'temperature': None,
+                         'max_completion_tokens': 100, 'reasoning_effort': 'high'})
+    request = modern.adapter.build_request([])
+    assert 'temperature' not in request and 'max_tokens' not in request
+    assert request['max_completion_tokens'] == 100
+    assert request['reasoning_effort'] == 'high'
+
+
+@pytest.mark.parametrize('stream', [False, True])
+def test_cache_parameters_reach_sdk(stream):
+    adapter = ResponsesAdapter('unused', client=Ns(),
+                               prompt_cache_options={'mode': 'explicit', 'ttl': '30m'},
+                               prompt_cache_key='stable-prefix')
+    request = adapter.build_request([], stream=stream)
+    assert request['prompt_cache_options'] == {'mode': 'explicit', 'ttl': '30m'}
+    assert request['prompt_cache_key'] == 'stable-prefix'
+    assert request['stream'] == stream
+
+
+def response_usage():
+    from openai.types.responses.response_usage import ResponseUsage
+    return ResponseUsage(input_tokens=100, output_tokens=30, total_tokens=130,
+                         input_tokens_details={'cached_tokens': 60, 'cache_write_tokens': 20},
+                         output_tokens_details={'reasoning_tokens': 10})
+
+
+def test_responses_usage_details_nonstream_and_stream():
+    adapter = ResponsesAdapter('unused', client=Ns())
+    raw = Ns(output=[], usage=response_usage(), status='completed', model='test')
+    usage = adapter.parse_response(raw).usage
+    assert usage == {'prompt_tokens': 100, 'completion_tokens': 30, 'total_tokens': 130,
+                     'cached_tokens': 60, 'cache_write_tokens': 20, 'reasoning_tokens': 10}
+    event = adapter.parse_stream_chunk(Ns(type='response.completed', response=raw))
+    assert event['usage'] == usage
+    total = {'prompt_tokens': 0, 'completion_tokens': 0, 'total_tokens': 0}
+    _merge_usage(total, usage)
+    _merge_usage(total, usage)
+    assert total['cached_tokens'] == 120 and total['total_tokens'] == 260
+
+
+def test_chat_usage_details_and_missing_fields():
+    usage = Ns(prompt_tokens=100, completion_tokens=30, total_tokens=130,
+               prompt_tokens_details=Ns(cached_tokens=60),
+               completion_tokens_details=Ns(reasoning_tokens=10))
+    parsed = OpenAIAdapter._parse_usage(usage)
+    assert parsed['cached_tokens'] == 60 and parsed['reasoning_tokens'] == 10
+    minimal = OpenAIAdapter._parse_usage(Ns(prompt_tokens=1, completion_tokens=2))
+    assert minimal == {'prompt_tokens': 1, 'completion_tokens': 2, 'total_tokens': 3}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('stream', [False, True])
+async def test_details_survive_agent_and_session(stream):
+    from tests.test_runtime_hardening import make_agent, response
+    answer = response('done')
+    answer.usage = ResponsesAdapter._parse_usage(response_usage())
+    agent = make_agent([answer])
+    session = agent.create_session()
+    if stream:
+        events = [event async for event in agent.stream_events('hello', session=session)]
+        usage = events[-1].data['usage']
+    else:
+        usage = (await agent.run('hello', session=session)).usage
+    assert usage['cached_tokens'] == 60 and usage['reasoning_tokens'] == 10
+    assert usage['total_tokens'] == 130
+    assert session.last_usage == usage
+
+
+def test_plan_aggregation_preserves_details():
+    from wuwei.planning import PlanExecutor
+    executor = PlanExecutor(Ns())
+    detail = ResponsesAdapter._parse_usage(response_usage())
+    executor._tasks_usage = [(detail, 1), (detail, 1)]
+    usage, calls = executor._aggregate_usage()
+    assert calls == 2 and usage['cache_write_tokens'] == 40
+    assert usage['total_tokens'] == 260
+
+
+@pytest.mark.asyncio
+async def test_cache_request_serialized_by_actual_sdk():
+    import json
+    import httpx
+    from openai import AsyncOpenAI
+
+    seen = []
+    def handler(request):
+        seen.append(json.loads(request.content))
+        return httpx.Response(200, json={'id': 'resp_1', 'object': 'response',
+                              'created_at': 0, 'status': 'completed', 'model': 'test',
+                              'output': [], 'usage': response_usage().model_dump()})
+
+    async with AsyncOpenAI(api_key='unused', max_retries=0,
+                           http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler))) as client:
+        adapter = ResponsesAdapter('unused', client=client,
+                                   prompt_cache_options={'mode': 'implicit', 'ttl': '30m'})
+        raw = await adapter.call(adapter.build_request([]))
+        assert adapter.parse_response(raw).usage['cached_tokens'] == 60
+    assert seen[0]['prompt_cache_options']['ttl'] == '30m'
+    assert 'temperature' not in seen[0]
+
+
+def test_responses_original_positional_constructor():
+    client = Ns()
+    adapter = ResponsesAdapter('unused', 'test', None, 0.4, 42, client)
+    request = adapter.build_request([])
+    assert request['max_output_tokens'] == 42 and request['temperature'] == 0.4
+    assert adapter.client is client

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/agent/agent.py

@@ -333,10 +333,9 @@ class Agent(BaseSessionAgent):
                     before = metadata["llm_calls"]
                     tasks = await p.plan_task(goal)
                     if before == metadata["llm_calls"]:
-                        for key in metadata["usage_total"]:
-                            metadata["usage_total"][key] += (
-                                getattr(p, "last_usage", {}) or {}
-                            ).get(key, 0)
+                        for key, value in (getattr(p, "last_usage", {}) or {}).items():
+                            totals = metadata["usage_total"]
+                            totals[key] = totals.get(key, 0) + (value or 0)
                         metadata["llm_calls"] += getattr(p, "last_llm_calls", 0)
                 for task in tasks:
                     task.status = "pending"

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/llm/adapters/openai.py

@@ -19,6 +19,7 @@ from ..types import (
     normalize_finish_reason,
 )
 from .base import BaseAdapter, make_client
+from .usage import parse_openai_usage
 
 
 class OpenAIAdapter(BaseAdapter):
@@ -31,7 +32,7 @@ class OpenAIAdapter(BaseAdapter):
         api_key: str,
         model: str = "gpt-4o",
         base_url: str | None = None,
-        temperature: float = 0.2,
+        temperature: float | None = 0.2,
         max_tokens: int = 4096,
         client=None,
         client_factory=None,
@@ -82,7 +83,7 @@ class OpenAIAdapter(BaseAdapter):
             request["tools"] = [
                 tool.to_schema() if hasattr(tool, "to_schema") else tool for tool in tools
             ]
-        return request
+        return {k: v for k, v in request.items() if v is not None}
 
     async def call(self, request: dict[str, Any]) -> Any:
         return await self.client.chat.completions.create(**request)
@@ -166,17 +167,7 @@ class OpenAIAdapter(BaseAdapter):
     @staticmethod
     def _parse_usage(usage: Any) -> dict[str, int]:
         """统一解析 usage，避免不同端点返回 None 或缺字段时崩溃。"""
-        if usage is None:
-            return {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
-        prompt = getattr(usage, "prompt_tokens", 0) or 0
-        completion = getattr(usage, "completion_tokens", 0) or 0
-        total = getattr(usage, "total_tokens", None)
-        total = total if total is not None else prompt + completion
-        return {
-            "prompt_tokens": prompt,
-            "completion_tokens": completion,
-            "total_tokens": total,
-        }
+        return parse_openai_usage(usage)
 
     @staticmethod
     def _get_extra_field(obj: Any, field_name: str) -> Any:

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/llm/adapters/responses.py

@@ -18,6 +18,7 @@ from ..types import (
     ToolCall,
 )
 from .base import BaseAdapter, make_client
+from .usage import parse_openai_usage
 
 
 class ResponsesAdapter(BaseAdapter):
@@ -30,11 +31,14 @@ class ResponsesAdapter(BaseAdapter):
         api_key: str,
         model: str = "gpt-4o",
         base_url: str | None = None,
-        temperature: float = 0.2,
+        temperature: float | None = None,
         max_output_tokens: int = 4096,
         client=None,
         client_factory=None,
         owns_client=None,
+        *,
+        prompt_cache_options: dict[str, Any] | None = None,
+        prompt_cache_key: str | None = None,
         **kwargs,
     ):
         self.client, self.owns_client = make_client(
@@ -43,6 +47,10 @@ class ResponsesAdapter(BaseAdapter):
         max_output_tokens = kwargs.pop("max_tokens", max_output_tokens)
         self.model = model
         self.default_params: dict[str, Any] = {k: v for k, v in kwargs.items() if v is not None}
+        if prompt_cache_options is not None:
+            self.default_params["prompt_cache_options"] = dict(prompt_cache_options)
+        if prompt_cache_key is not None:
+            self.default_params["prompt_cache_key"] = prompt_cache_key
         self.max_output_tokens = max_output_tokens
         self.temperature = temperature
 
@@ -125,7 +133,7 @@ class ResponsesAdapter(BaseAdapter):
             request["instructions"] = instructions
         if tools:
             request["tools"] = self._convert_tools(tools)
-        return request
+        return {k: v for k, v in request.items() if v is not None}
 
     async def call(self, request: dict[str, Any]) -> Any:
         return await self.client.responses.create(**request)
@@ -240,7 +248,7 @@ class ResponsesAdapter(BaseAdapter):
                 ]
             }
             usage = self._parse_usage(getattr(response, "usage", None))
-            if usage.get("total_tokens"):
+            if getattr(response, "usage", None) is not None:
                 result["usage"] = usage
             return result
 
@@ -250,14 +258,4 @@ class ResponsesAdapter(BaseAdapter):
 
     @staticmethod
     def _parse_usage(usage: Any) -> dict[str, int]:
-        if usage is None:
-            return {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
-        prompt = getattr(usage, "input_tokens", 0) or 0
-        completion = getattr(usage, "output_tokens", 0) or 0
-        total = getattr(usage, "total_tokens", None)
-        total = total if total is not None else prompt + completion
-        return {
-            "prompt_tokens": prompt,
-            "completion_tokens": completion,
-            "total_tokens": total,
-        }
+        return parse_openai_usage(usage, responses=True)

wuwei-3.2.2/wuwei/llm/adapters/usage.py

@@ -0,0 +1,27 @@
+"""Normalize OpenAI usage without counting detail tokens a second time."""
+
+
+def parse_openai_usage(usage, *, responses=False):
+    def field(obj, name, default=None):
+        return obj.get(name, default) if isinstance(obj, dict) else getattr(obj, name, default)
+
+    input_name, output_name = (
+        ("input_tokens", "output_tokens") if responses else ("prompt_tokens", "completion_tokens")
+    )
+    prompt = field(usage, input_name, 0) or 0
+    completion = field(usage, output_name, 0) or 0
+    total = field(usage, "total_tokens")
+    result = {
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "total_tokens": total if total is not None else prompt + completion,
+    }
+    for detail, names in (
+        (field(usage, f"{input_name}_details"), ("cached_tokens", "cache_write_tokens")),
+        (field(usage, f"{output_name}_details"), ("reasoning_tokens",)),
+    ):
+        for name in names:
+            value = field(detail, name)
+            if value is not None:
+                result[name] = value
+    return result

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/llm/gateway.py

@@ -110,7 +110,7 @@ class LLMGateway:
         adapter_kwargs: dict[str, Any] = {
             "api_key": config.get("api_key") or "missing",
             "model": config.get("model", spec["default_model"]),
-            "temperature": config.get("temperature", 0.2),
+            "temperature": config.get("temperature", None if provider == "responses" else 0.2),
         }
         if provider == "responses":
             adapter_kwargs["max_output_tokens"] = config.get(

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/planning/executor.py

@@ -310,7 +310,7 @@ class PlanExecutor:
         usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
         llm_calls = 0
         for u, calls in self._tasks_usage:
-            for k in usage:
-                usage[k] += u.get(k, 0)
+            for k, value in u.items():
+                usage[k] = usage.get(k, 0) + (value or 0)
             llm_calls += calls
         return usage, llm_calls

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei/runtime/agent_runner.py

@@ -28,8 +28,8 @@ def _empty_usage():
 
 
 def _merge_usage(total, usage):
-    for key in total:
-        total[key] += (usage or {}).get(key, 0) or 0
+    for key, value in (usage or {}).items():
+        total[key] = total.get(key, 0) + (value or 0)
 
 
 class AgentRunner:
@@ -373,10 +373,8 @@ class AgentRunner:
                                     pending = chunk.tool_calls_complete
                                 if chunk.finish_reason:
                                     finish = chunk.finish_reason
-                                for key in call_usage:
-                                    call_usage[key] = max(
-                                        call_usage[key], (chunk.usage or {}).get(key, 0) or 0
-                                    )
+                                for key, value in (chunk.usage or {}).items():
+                                    call_usage[key] = max(call_usage.get(key, 0), value or 0)
                         finally:
                             close = getattr(result, "aclose", None)
                             if close:

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wuwei
-Version: 3.2.1
+Version: 3.2.2
 Summary: Wuwei - 无为而治的 AI 智能体框架
 Author-email: xiaojiaenen <xiaojiaenen@163.com>
 License-Expression: Apache-2.0
@@ -10,7 +10,7 @@ Project-URL: Documentation, https://github.com/xiaojiaenen/wuwei
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: openai>=3.23.0
+Requires-Dist: openai>=3.40.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: httpx>=0.25.0

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei.egg-info/SOURCES.txt

@@ -59,6 +59,7 @@ tests/test_middleware.py
 tests/test_middleware_lifecycle.py
 tests/test_model_hardening.py
 tests/test_multi_agent_integration.py
+tests/test_openai_sdk_capabilities.py
 tests/test_runtime_hardening.py
 tests/test_sandbox.py
 tests/test_serve.py
@@ -126,6 +127,7 @@ wuwei/llm/adapters/anthropic.py
 wuwei/llm/adapters/base.py
 wuwei/llm/adapters/openai.py
 wuwei/llm/adapters/responses.py
+wuwei/llm/adapters/usage.py
 wuwei/mcp/__init__.py
 wuwei/mcp/client.py
 wuwei/mcp/config.py

{wuwei-3.2.1 → wuwei-3.2.2}/wuwei.egg-info/requires.txt

@@ -1,4 +1,4 @@
-openai>=3.23.0
+openai>=3.40.0
 pydantic>=2.0.0
 pyyaml>=6.0.3
 httpx>=0.25.0