cosens-sdk 0.1.0__tar.gz

cosens_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+*.sqlite3
+*.sqlite3-*
+*.egg-info/
+dist/
+build/
+typescript/node_modules/
+python/docs/testing/latest-cn/

cosens_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: cosens-sdk
+Version: 0.1.0
+Summary: CoSens Python SDK for OpenAI and RSI workflows
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: openai<2.55,>=2.54
+Provides-Extra: agents
+Requires-Dist: openai-agents<0.21,>=0.20; extra == 'agents'
+Provides-Extra: examples
+Requires-Dist: openai-agents<0.21,>=0.20; extra == 'examples'
+Requires-Dist: python-dotenv<2,>=1; extra == 'examples'
+Provides-Extra: test
+Requires-Dist: build>=1; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# CoSens Python SDK
+
+在现有 OpenAI 应用中加入 Recipe、Memory 召回，以及 RSI 任务消息与结果上报。业务任务由你的 OpenAI 客户端或 Agents SDK 执行，CoSens 负责上下文与经验流程。
+
+[安装](#安装) · [配置](#配置) · [快速开始](#快速开始) · [三种可运行示例](#三种可运行示例) · [常见问题](#常见问题) · [API 参考](docs/api-reference.md)
+
+新增任务工作流的 Python / TypeScript 原子方法与恢复约束见[开发契约](docs/2026-10-28-task-workflow-sdk-design.md)。本页的透明包装及显式 Run 示例仍使用旧 `/v1/runs` 协议。
+
+新版 Memory 与 guided Run 原子方法已加入 `client.atoms` 和 `client.sync_atoms`：来源版本写入、Memory 列表、guided 取下一步/提交步骤/完成及事件读取。方法参数见 [API 参考](docs/api-reference.md)。2026-10-29 固定 CN 区域后，Recipe、Memory 召回/列表、来源版本更新、guided Run 完整步骤流及 Task → Execution → Revision 冒烟测试通过，见 [验证记录](docs/testing/2026-10-29-v3-cn-contract.json)。Memory 抽取作业仍 pending；文档上传的四个原子方法已实现并完成离线测试，使用方式见 [API 参考](docs/api-reference.md#文档上传)；一次性上传的 grant 路由尚未出现在 CN OpenAPI 中，真实联调待下游部署。
+
+在 IDEA 中选择 `00_all_tests_CN` 可运行两种语言的完整离线测试和 CN 网关检查；`00_all_tests_CN_live` 还会执行两种语言的真实模型示例。`04_task_workflow_CN` 单独检查新工作流。网关尚未部署新路由时，新工作流测试只读退出（代码 2）；详见根目录 [测试说明](../README.md#开发与验证)。
+
+## 安装
+
+要求 **Python 3.10+**。当前支持 `openai` 2.54.x，Agent 接入使用 `openai-agents` 0.20.x。以下命令均从 **CoSens-SDK 仓库根目录**执行：
+
+```bash
+python3 -m venv python/.venv
+source python/.venv/bin/activate
+python -m pip install -e "./python[examples]"
+```
+
+Windows 激活命令为 `python\.venv\Scripts\activate`。`examples` 安装三个示例所需的 Agents SDK 和 dotenv。仅使用透明包装可安装 `python -m pip install ./python`；仅增加 Agent 支持可安装 `"./python[agents]"`。这里使用源码安装，不依赖同名 PyPI 包是否已发布。
+
+## 配置
+
+复制 [.env.example](.env.example) 为同目录的 `python/.env`，填写：
+
+```dotenv
+OPENAI_API_KEY=your-openai-key
+OPENAI_MODEL=your-model-name
+RSI_API_KEY=your-friday-key
+```
+
+| 配置项 | 用途 | 必填 |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | OpenAI 或兼容模型服务的凭证 | 是 |
+| `OPENAI_MODEL` | 你有权限调用的模型名，示例使用 Responses API | 是 |
+| `RSI_API_KEY` | Friday 用户 Key，用于 CoSens 网关 | 是 |
+| `OPENAI_BASE_URL` | 自定义兼容模型服务地址；不填使用 OpenAI 默认地址 | 否 |
+| `COSENS_MODE` | 透明示例的模式，默认 `auto`，可改为 `disable` | 否 |
+| `COSENS_INPUT` | 示例任务文字，不填使用内置集成测试问题 | 否 |
+| `COSENS_REGION` | CoSens 服务区域，`cn`（默认）或 `us` | 否 |
+| `RSI_API_KEY_CN` / `RSI_API_KEY_US` | 示例按区域选用的 Friday Key；未配置时使用 `RSI_API_KEY` | 否 |
+
+三个示例自动读取 `python/.env`，已有进程环境变量优先。**SDK 本身不自动读取 `.env`**；你自己的应用可使用环境变量或 `load_dotenv()`。
+
+CoSens 网关由 SDK 内部按 `COSENS_REGION` 选择：国内 `cn` 为 `https://friday-rsi-cn.stardust-ai.com/api`，美国 `us` 为 `https://rsi.cosens.ai/api`。无需传入 CoSens `base_url` 或 `X_User_Id`，用户身份由网关注入。`OPENAI_BASE_URL` 仅配置模型服务。
+
+### 国内区与美国区测试
+
+三个示例共用同一套代码，在 `python/.env` 中配置区域与对应 Key：
+
+```dotenv
+COSENS_REGION=us
+RSI_API_KEY_CN=your-cn-friday-key
+RSI_API_KEY_US=your-us-friday-key
+```
+
+这些值是占位符，真实联调需要有效 Key。示例优先使用对应区域的 Key，未设置或为空时回退到 `RSI_API_KEY`；显式填了占位符则在发送任何请求前提示补全配置，不会回退。不要假设两区 Key 通用。这个 Key 选择逻辑属于示例辅助代码；应用直接使用 SDK 时仍通过 `api_key` 或 `RSI_API_KEY` / `COSENS_API_KEY` 提供当前区域凭证。
+
+IDEA 本地运行配置 `01_transparent`、`02_explicit_run`、`03_atomic` 固定测试国内区；同名加 `_US` 的三个入口测试美国区。也可直接打开示例运行，此时使用 `.env` 中的区域。终端临时切换示例：
+
+```bash
+COSENS_REGION=us python/.venv/bin/python python/examples/01_transparent.py
+COSENS_REGION=us python/.venv/bin/python python/examples/02_explicit_run.py
+COSENS_REGION=us python/.venv/bin/python python/examples/03_atomic.py
+```
+
+客户端在初始化时固定区域，切换区域需新建客户端。两区的 Run 恢复状态和消息确认游标相互隔离；国内区已有状态继续可用。
+
+每个 CoSens 服务端请求携带 `X-Auth-Type: api_key` 和 `Authorization: Bearer <api_key>`。Friday Key 经 HTTPS 发送，证书验证保持开启，不跟随重定向；这两个头不会加到原生 OpenAI 模型请求。请使用环境变量或部署平台密钥管理；`.env` 已被 Git 忽略。不要把真实 Key 写入提交到仓库的源码。
+
+## 快速开始
+
+```python
+import os
+from openai import OpenAI
+from cosens import cosens
+
+native = OpenAI()
+client = cosens(native, api_key=os.environ["RSI_API_KEY"], mode="auto")
+try:
+    response = client.responses.create(
+        model=os.environ["OPENAI_MODEL"],
+        input="请帮我总结这次任务中可以复用的经验。",
+    )
+    print(response.output_text)
+finally:
+    client.close()
+```
+
+接入只需 `native`、`api_key`、`mode`。SDK 默认复用业务请求的模型做提交判断，无需额外填写 `decision_model` 或 `session`。Friday Key 也可省略参数从环境读取，优先级为显式 `api_key` → `RSI_API_KEY` → `COSENS_API_KEY`。
+
+## 三种可运行示例
+
+在 PyCharm / IntelliJ Python 插件 / VS Code 中，把解释器选为本项目的 **`python/.venv/bin/python`**（Windows 为 `python\.venv\Scripts\python.exe`）。完成 `.env` 配置后，打开对应文件点击 **Run Python File / Run**。也可从仓库根目录运行下列命令。
+
+### 1. 透明包装 OpenAI
+
+**[打开 01_transparent.py](examples/01_transparent.py)**
+
+```bash
+python python/examples/01_transparent.py
+```
+
+核心调用仍为原生 OpenAI 形式，不显式调用 CoSens `run()`：
+
+```python
+client = cosens(native, api_key=friday_key, mode="auto")
+response = client.responses.create(model=model, input=user_input)
+print(response.output_text)
+```
+
+`auto` 先用模型判断是否需要 RSI Run；命中则准备 Run、获取冻结上下文，再执行业务模型、上报消息和提交结果。不命中或分类失败时，通过公开 Recipe + Memory 接口召回，不创建 Run。`disable` 跳过自动判断和自动 Run，但仍然召回。
+
+运行会输出答案、capture、turn_id、run_id 和本地 state。**auto 没有创建 Run 是合法结果**；不要将 `run_id: None` 直接视为失败。`auto` 的决策请求增加一次模型调用，模型服务需支持 Responses 结构化输出。高级参数 `decision_model` 可覆盖默认选择。
+
+### 2. 显式调用 run
+
+**[打开 02_explicit_run.py](examples/02_explicit_run.py)**
+
+```bash
+python python/examples/02_explicit_run.py
+```
+
+```python
+agent = Agent(name="assistant", model=model, tools=[])
+client = cosens(agent, api_key=friday_key, mode="disable")
+result = await client.run(agent, user_input, session=session)
+print(result.final_output)
+```
+
+完整文件使用 `OpenAIResponsesModel` 绑定真实 `AsyncOpenAI`，因此你配置的模型 Key 和模型地址会被实际使用。`disable` 关闭自动触发，显式 `run()` 仍组合原子步骤完成 RSI 流程；不会再调用分类模型。
+
+示例使用 Agents SDK 的 `SQLiteSession` 保存聊天历史，数据库位于 `~/.cosens/example-sessions.sqlite3`，控制台打印 session_id。每次点击生成一个新会话；连续聊天应复用同一个 Session。历史中已获得 `durable_ack` 的事件不重复上报。示例关闭 Agents tracing，避免额外发送 tracing 数据；可按应用需要自行开启。
+
+### 3. 直接编排原子接口
+
+**[打开 03_atomic.py](examples/03_atomic.py)**
+
+```bash
+python python/examples/03_atomic.py
+```
+
+完整文件展开以下主要流程：
+
+```text
+上传输入 artifact
+  → prepare（processing 时以同一 key 有界轮询）
+  → get_run，冻结 Recipe / Context / Snapshot
+  → session_events，确认用户消息 ACK
+  → 应用调用真实 OpenAI 模型，使用冻结上下文
+  → session_events，确认助手回复 ACK
+  → 上传输出 artifact → submit → get_trace
+```
+
+这里不调用包装器 `run()`，应用自己组织原子方法。服务端召回发生在模型调用前，工具循环应复用冻结结果。示例是单任务演示：每次运行生成新的 key；打印的 key、run_id 和实际输出须用于失败后的对账，不能直接重跑代替恢复。
+
+有决策分支的任务可加入 `guidance` / `checkpoint`；只有拿到真实反馈后才调用 `feedback` / `improve`，发布需显式调用管理员原子接口。完整方法与调用时机见 [API 参考](docs/api-reference.md)。生产应用还需持久化原子流程自身的任务状态和 ACK 游标。
+
+## 模式与兼容性
+
+| 入口 / 模式 | 模型调用前召回 | 创建 RSI Run | 执行者 |
+| --- | --- | --- | --- |
+| 透明 `auto` | 每 turn 一次 | 由模型判断 | 原始 OpenAI client |
+| 透明 `disable` | 每 turn 一次 | 不自动创建 | 原始 OpenAI client |
+| 显式 `run()` + `disable` | 每 turn 一次 | 显式创建 | OpenAI Agents SDK |
+| 原子接口 | 由应用在模型前调用 | 应用显式 prepare | 应用自己的模型/工具代码 |
+
+当前透明 `approval` 协调器契约未确认，命中审批流程会明确报错；不要用于这些示例。
+
+同步 `OpenAI`、异步 `AsyncOpenAI` 均可包装。对话生成适配 Responses / Chat Completions 的 create、parse、stream；文件、向量库等其他资源方法透传，原生返回值保持原形。`with_options()` / `copy()` 仍返回包装对象。对于无法安全捕获的生成请求，SDK 保留原生调用，设置 `rsi_capture="unsupported"`，此时不保证 RSI 召回与上报。直接调用 `client.native` 会绕过包装。
+
+## Session 与故障恢复
+
+不传 Session 的透明调用只能捕获本次请求可见的消息，无法读取应用未提供的旧聊天。外部历史、稳定 turn 边界和工具循环的进阶接入见 [Session 说明](docs/api-reference.md#session工具和恢复)。
+
+CoSens 默认把状态和 ACK 游标写入 `~/.cosens/state.sqlite3`，可用高级参数 `state_path` 指定。记录按服务及凭证摘要隔离；部署时应持久化该文件。只有远端 ACK 确认后才推进消息游标，丢失本地状态后不能保证跨 Run 全局去重。
+
+```python
+turn_id = client.cosens.last_turn_id
+state = client.cosens.get_turn(turn_id)
+```
+
+如果模型结果已经返回，但 state 为 `completion_pending`，不要直接重新执行模型或工具。保留原 Session、状态文件和 turn_id，透明同步客户端使用 `client.cosens.reconcile(turn_id)` 对账，异步 OpenAI 客户端使用 `await`。显式 Agent 示例把 Session 传给了 `run()`，恢复时也必须传入同一个 Session：
+
+```python
+# 重启后用控制台记录的原 session_id 和同一数据库重新创建 SQLiteSession。
+await client.cosens.reconcile(turn_id, session=session)
+```
+
+原生执行结果不明或抛出 `RSIRecoveryRequired` 时，需要应用先核实实际执行情况。详见 [恢复边界](docs/api-reference.md#恢复与服务端边界)。
+
+## 常见问题
+
+| 现象 | 处理方式 |
+| --- | --- |
+| `ModuleNotFoundError: cosens / agents / dotenv` | 确认 IDE 使用安装过 `./python[examples]` 的解释器 |
+| 提示缺少配置 | 将 `.env.example` 复制到 `python/.env`，填写三个必填值；检查 IDE 环境变量是否覆盖它 |
+| 模型 401 / 403 / 404 | 核对 OpenAI Key、模型访问权限、模型名与模型服务地址 |
+| 网关 401 / 403 | 核对 Friday 用户 Key 及网关权限，无需自己填写 X_User_Id |
+| 召回失败、未调用业务模型 | 检查网关连通性与返回契约；SDK 不把错误静默当成空召回 |
+| 模型有答案、RSI 未完成 | 保存 turn_id / run_id，按恢复流程处理，避免重复执行 |
+| 想验证每次都创建 Run | 运行显式 run 或原子示例；auto 的创建与否由模型决策 |
+
+示例错误只输出类型、HTTP 状态和 request_id，不输出远端错误正文。请结合上述信息和服务端日志定位。
+
+## 开发与测试
+
+```bash
+python -m pip install -e "./python[examples,test]"
+python -m pytest python/tests
+python -m build python
+```
+
+`tests/test_runnable_examples.py` 从不同工作目录执行三个脚本，使用真实 OpenAI SDK、真实 Agents Runner 和本地状态存储，仅模拟 HTTP 服务，验证召回顺序、上下文注入、消息上报和凭证隔离。它不会消耗真实模型额度。
+
+`examples/validate_gateway.py` 与 `examples/validate_wrapped_gateway.py` 是独立网关联调脚本，后者使用本地模型替身；它们与上述真实模型示例用途不同。复现方式、已验证范围见 [网关联调报告](docs/2026-10-27-gateway-validation.md) 和 [API 参考](docs/api-reference.md#复现网关联调)。
+
+## 进一步阅读
+
+- [设计文档与每步调用时机](docs/2026-10-26-cosens-python-sdk-design.md)
+- [原子 API 与恢复边界](docs/api-reference.md)
+- [OpenAI Python SDK](https://github.com/openai/openai-python)
+- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
+
+新增 30 个请求边界回归测试（Python / TypeScript 各 15 个），已纳入现有测试入口；用例清单、单独运行命令、缺陷修复与最新验证结果见[测试说明](docs/testing/2026-10-29-sdk-request-regression.md)。

cosens_sdk-0.1.0/README.md

@@ -0,0 +1,228 @@
+# CoSens Python SDK
+
+在现有 OpenAI 应用中加入 Recipe、Memory 召回，以及 RSI 任务消息与结果上报。业务任务由你的 OpenAI 客户端或 Agents SDK 执行，CoSens 负责上下文与经验流程。
+
+[安装](#安装) · [配置](#配置) · [快速开始](#快速开始) · [三种可运行示例](#三种可运行示例) · [常见问题](#常见问题) · [API 参考](docs/api-reference.md)
+
+新增任务工作流的 Python / TypeScript 原子方法与恢复约束见[开发契约](docs/2026-10-28-task-workflow-sdk-design.md)。本页的透明包装及显式 Run 示例仍使用旧 `/v1/runs` 协议。
+
+新版 Memory 与 guided Run 原子方法已加入 `client.atoms` 和 `client.sync_atoms`：来源版本写入、Memory 列表、guided 取下一步/提交步骤/完成及事件读取。方法参数见 [API 参考](docs/api-reference.md)。2026-10-29 固定 CN 区域后，Recipe、Memory 召回/列表、来源版本更新、guided Run 完整步骤流及 Task → Execution → Revision 冒烟测试通过，见 [验证记录](docs/testing/2026-10-29-v3-cn-contract.json)。Memory 抽取作业仍 pending；文档上传的四个原子方法已实现并完成离线测试，使用方式见 [API 参考](docs/api-reference.md#文档上传)；一次性上传的 grant 路由尚未出现在 CN OpenAPI 中，真实联调待下游部署。
+
+在 IDEA 中选择 `00_all_tests_CN` 可运行两种语言的完整离线测试和 CN 网关检查；`00_all_tests_CN_live` 还会执行两种语言的真实模型示例。`04_task_workflow_CN` 单独检查新工作流。网关尚未部署新路由时，新工作流测试只读退出（代码 2）；详见根目录 [测试说明](../README.md#开发与验证)。
+
+## 安装
+
+要求 **Python 3.10+**。当前支持 `openai` 2.54.x，Agent 接入使用 `openai-agents` 0.20.x。以下命令均从 **CoSens-SDK 仓库根目录**执行：
+
+```bash
+python3 -m venv python/.venv
+source python/.venv/bin/activate
+python -m pip install -e "./python[examples]"
+```
+
+Windows 激活命令为 `python\.venv\Scripts\activate`。`examples` 安装三个示例所需的 Agents SDK 和 dotenv。仅使用透明包装可安装 `python -m pip install ./python`；仅增加 Agent 支持可安装 `"./python[agents]"`。这里使用源码安装，不依赖同名 PyPI 包是否已发布。
+
+## 配置
+
+复制 [.env.example](.env.example) 为同目录的 `python/.env`，填写：
+
+```dotenv
+OPENAI_API_KEY=your-openai-key
+OPENAI_MODEL=your-model-name
+RSI_API_KEY=your-friday-key
+```
+
+| 配置项 | 用途 | 必填 |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | OpenAI 或兼容模型服务的凭证 | 是 |
+| `OPENAI_MODEL` | 你有权限调用的模型名，示例使用 Responses API | 是 |
+| `RSI_API_KEY` | Friday 用户 Key，用于 CoSens 网关 | 是 |
+| `OPENAI_BASE_URL` | 自定义兼容模型服务地址；不填使用 OpenAI 默认地址 | 否 |
+| `COSENS_MODE` | 透明示例的模式，默认 `auto`，可改为 `disable` | 否 |
+| `COSENS_INPUT` | 示例任务文字，不填使用内置集成测试问题 | 否 |
+| `COSENS_REGION` | CoSens 服务区域，`cn`（默认）或 `us` | 否 |
+| `RSI_API_KEY_CN` / `RSI_API_KEY_US` | 示例按区域选用的 Friday Key；未配置时使用 `RSI_API_KEY` | 否 |
+
+三个示例自动读取 `python/.env`，已有进程环境变量优先。**SDK 本身不自动读取 `.env`**；你自己的应用可使用环境变量或 `load_dotenv()`。
+
+CoSens 网关由 SDK 内部按 `COSENS_REGION` 选择：国内 `cn` 为 `https://friday-rsi-cn.stardust-ai.com/api`，美国 `us` 为 `https://rsi.cosens.ai/api`。无需传入 CoSens `base_url` 或 `X_User_Id`，用户身份由网关注入。`OPENAI_BASE_URL` 仅配置模型服务。
+
+### 国内区与美国区测试
+
+三个示例共用同一套代码，在 `python/.env` 中配置区域与对应 Key：
+
+```dotenv
+COSENS_REGION=us
+RSI_API_KEY_CN=your-cn-friday-key
+RSI_API_KEY_US=your-us-friday-key
+```
+
+这些值是占位符，真实联调需要有效 Key。示例优先使用对应区域的 Key，未设置或为空时回退到 `RSI_API_KEY`；显式填了占位符则在发送任何请求前提示补全配置，不会回退。不要假设两区 Key 通用。这个 Key 选择逻辑属于示例辅助代码；应用直接使用 SDK 时仍通过 `api_key` 或 `RSI_API_KEY` / `COSENS_API_KEY` 提供当前区域凭证。
+
+IDEA 本地运行配置 `01_transparent`、`02_explicit_run`、`03_atomic` 固定测试国内区；同名加 `_US` 的三个入口测试美国区。也可直接打开示例运行，此时使用 `.env` 中的区域。终端临时切换示例：
+
+```bash
+COSENS_REGION=us python/.venv/bin/python python/examples/01_transparent.py
+COSENS_REGION=us python/.venv/bin/python python/examples/02_explicit_run.py
+COSENS_REGION=us python/.venv/bin/python python/examples/03_atomic.py
+```
+
+客户端在初始化时固定区域，切换区域需新建客户端。两区的 Run 恢复状态和消息确认游标相互隔离；国内区已有状态继续可用。
+
+每个 CoSens 服务端请求携带 `X-Auth-Type: api_key` 和 `Authorization: Bearer <api_key>`。Friday Key 经 HTTPS 发送，证书验证保持开启，不跟随重定向；这两个头不会加到原生 OpenAI 模型请求。请使用环境变量或部署平台密钥管理；`.env` 已被 Git 忽略。不要把真实 Key 写入提交到仓库的源码。
+
+## 快速开始
+
+```python
+import os
+from openai import OpenAI
+from cosens import cosens
+
+native = OpenAI()
+client = cosens(native, api_key=os.environ["RSI_API_KEY"], mode="auto")
+try:
+    response = client.responses.create(
+        model=os.environ["OPENAI_MODEL"],
+        input="请帮我总结这次任务中可以复用的经验。",
+    )
+    print(response.output_text)
+finally:
+    client.close()
+```
+
+接入只需 `native`、`api_key`、`mode`。SDK 默认复用业务请求的模型做提交判断，无需额外填写 `decision_model` 或 `session`。Friday Key 也可省略参数从环境读取，优先级为显式 `api_key` → `RSI_API_KEY` → `COSENS_API_KEY`。
+
+## 三种可运行示例
+
+在 PyCharm / IntelliJ Python 插件 / VS Code 中，把解释器选为本项目的 **`python/.venv/bin/python`**（Windows 为 `python\.venv\Scripts\python.exe`）。完成 `.env` 配置后，打开对应文件点击 **Run Python File / Run**。也可从仓库根目录运行下列命令。
+
+### 1. 透明包装 OpenAI
+
+**[打开 01_transparent.py](examples/01_transparent.py)**
+
+```bash
+python python/examples/01_transparent.py
+```
+
+核心调用仍为原生 OpenAI 形式，不显式调用 CoSens `run()`：
+
+```python
+client = cosens(native, api_key=friday_key, mode="auto")
+response = client.responses.create(model=model, input=user_input)
+print(response.output_text)
+```
+
+`auto` 先用模型判断是否需要 RSI Run；命中则准备 Run、获取冻结上下文，再执行业务模型、上报消息和提交结果。不命中或分类失败时，通过公开 Recipe + Memory 接口召回，不创建 Run。`disable` 跳过自动判断和自动 Run，但仍然召回。
+
+运行会输出答案、capture、turn_id、run_id 和本地 state。**auto 没有创建 Run 是合法结果**；不要将 `run_id: None` 直接视为失败。`auto` 的决策请求增加一次模型调用，模型服务需支持 Responses 结构化输出。高级参数 `decision_model` 可覆盖默认选择。
+
+### 2. 显式调用 run
+
+**[打开 02_explicit_run.py](examples/02_explicit_run.py)**
+
+```bash
+python python/examples/02_explicit_run.py
+```
+
+```python
+agent = Agent(name="assistant", model=model, tools=[])
+client = cosens(agent, api_key=friday_key, mode="disable")
+result = await client.run(agent, user_input, session=session)
+print(result.final_output)
+```
+
+完整文件使用 `OpenAIResponsesModel` 绑定真实 `AsyncOpenAI`，因此你配置的模型 Key 和模型地址会被实际使用。`disable` 关闭自动触发，显式 `run()` 仍组合原子步骤完成 RSI 流程；不会再调用分类模型。
+
+示例使用 Agents SDK 的 `SQLiteSession` 保存聊天历史，数据库位于 `~/.cosens/example-sessions.sqlite3`，控制台打印 session_id。每次点击生成一个新会话；连续聊天应复用同一个 Session。历史中已获得 `durable_ack` 的事件不重复上报。示例关闭 Agents tracing，避免额外发送 tracing 数据；可按应用需要自行开启。
+
+### 3. 直接编排原子接口
+
+**[打开 03_atomic.py](examples/03_atomic.py)**
+
+```bash
+python python/examples/03_atomic.py
+```
+
+完整文件展开以下主要流程：
+
+```text
+上传输入 artifact
+  → prepare（processing 时以同一 key 有界轮询）
+  → get_run，冻结 Recipe / Context / Snapshot
+  → session_events，确认用户消息 ACK
+  → 应用调用真实 OpenAI 模型，使用冻结上下文
+  → session_events，确认助手回复 ACK
+  → 上传输出 artifact → submit → get_trace
+```
+
+这里不调用包装器 `run()`，应用自己组织原子方法。服务端召回发生在模型调用前，工具循环应复用冻结结果。示例是单任务演示：每次运行生成新的 key；打印的 key、run_id 和实际输出须用于失败后的对账，不能直接重跑代替恢复。
+
+有决策分支的任务可加入 `guidance` / `checkpoint`；只有拿到真实反馈后才调用 `feedback` / `improve`，发布需显式调用管理员原子接口。完整方法与调用时机见 [API 参考](docs/api-reference.md)。生产应用还需持久化原子流程自身的任务状态和 ACK 游标。
+
+## 模式与兼容性
+
+| 入口 / 模式 | 模型调用前召回 | 创建 RSI Run | 执行者 |
+| --- | --- | --- | --- |
+| 透明 `auto` | 每 turn 一次 | 由模型判断 | 原始 OpenAI client |
+| 透明 `disable` | 每 turn 一次 | 不自动创建 | 原始 OpenAI client |
+| 显式 `run()` + `disable` | 每 turn 一次 | 显式创建 | OpenAI Agents SDK |
+| 原子接口 | 由应用在模型前调用 | 应用显式 prepare | 应用自己的模型/工具代码 |
+
+当前透明 `approval` 协调器契约未确认，命中审批流程会明确报错；不要用于这些示例。
+
+同步 `OpenAI`、异步 `AsyncOpenAI` 均可包装。对话生成适配 Responses / Chat Completions 的 create、parse、stream；文件、向量库等其他资源方法透传，原生返回值保持原形。`with_options()` / `copy()` 仍返回包装对象。对于无法安全捕获的生成请求，SDK 保留原生调用，设置 `rsi_capture="unsupported"`，此时不保证 RSI 召回与上报。直接调用 `client.native` 会绕过包装。
+
+## Session 与故障恢复
+
+不传 Session 的透明调用只能捕获本次请求可见的消息，无法读取应用未提供的旧聊天。外部历史、稳定 turn 边界和工具循环的进阶接入见 [Session 说明](docs/api-reference.md#session工具和恢复)。
+
+CoSens 默认把状态和 ACK 游标写入 `~/.cosens/state.sqlite3`，可用高级参数 `state_path` 指定。记录按服务及凭证摘要隔离；部署时应持久化该文件。只有远端 ACK 确认后才推进消息游标，丢失本地状态后不能保证跨 Run 全局去重。
+
+```python
+turn_id = client.cosens.last_turn_id
+state = client.cosens.get_turn(turn_id)
+```
+
+如果模型结果已经返回，但 state 为 `completion_pending`，不要直接重新执行模型或工具。保留原 Session、状态文件和 turn_id，透明同步客户端使用 `client.cosens.reconcile(turn_id)` 对账，异步 OpenAI 客户端使用 `await`。显式 Agent 示例把 Session 传给了 `run()`，恢复时也必须传入同一个 Session：
+
+```python
+# 重启后用控制台记录的原 session_id 和同一数据库重新创建 SQLiteSession。
+await client.cosens.reconcile(turn_id, session=session)
+```
+
+原生执行结果不明或抛出 `RSIRecoveryRequired` 时，需要应用先核实实际执行情况。详见 [恢复边界](docs/api-reference.md#恢复与服务端边界)。
+
+## 常见问题
+
+| 现象 | 处理方式 |
+| --- | --- |
+| `ModuleNotFoundError: cosens / agents / dotenv` | 确认 IDE 使用安装过 `./python[examples]` 的解释器 |
+| 提示缺少配置 | 将 `.env.example` 复制到 `python/.env`，填写三个必填值；检查 IDE 环境变量是否覆盖它 |
+| 模型 401 / 403 / 404 | 核对 OpenAI Key、模型访问权限、模型名与模型服务地址 |
+| 网关 401 / 403 | 核对 Friday 用户 Key 及网关权限，无需自己填写 X_User_Id |
+| 召回失败、未调用业务模型 | 检查网关连通性与返回契约；SDK 不把错误静默当成空召回 |
+| 模型有答案、RSI 未完成 | 保存 turn_id / run_id，按恢复流程处理，避免重复执行 |
+| 想验证每次都创建 Run | 运行显式 run 或原子示例；auto 的创建与否由模型决策 |
+
+示例错误只输出类型、HTTP 状态和 request_id，不输出远端错误正文。请结合上述信息和服务端日志定位。
+
+## 开发与测试
+
+```bash
+python -m pip install -e "./python[examples,test]"
+python -m pytest python/tests
+python -m build python
+```
+
+`tests/test_runnable_examples.py` 从不同工作目录执行三个脚本，使用真实 OpenAI SDK、真实 Agents Runner 和本地状态存储，仅模拟 HTTP 服务，验证召回顺序、上下文注入、消息上报和凭证隔离。它不会消耗真实模型额度。
+
+`examples/validate_gateway.py` 与 `examples/validate_wrapped_gateway.py` 是独立网关联调脚本，后者使用本地模型替身；它们与上述真实模型示例用途不同。复现方式、已验证范围见 [网关联调报告](docs/2026-10-27-gateway-validation.md) 和 [API 参考](docs/api-reference.md#复现网关联调)。
+
+## 进一步阅读
+
+- [设计文档与每步调用时机](docs/2026-10-26-cosens-python-sdk-design.md)
+- [原子 API 与恢复边界](docs/api-reference.md)
+- [OpenAI Python SDK](https://github.com/openai/openai-python)
+- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
+
+新增 30 个请求边界回归测试（Python / TypeScript 各 15 个），已纳入现有测试入口；用例清单、单独运行命令、缺陷修复与最新验证结果见[测试说明](docs/testing/2026-10-29-sdk-request-regression.md)。

cosens_sdk-0.1.0/docs/api-reference.md

@@ -0,0 +1,129 @@
+# Python SDK 进阶与原子 API
+
+基础安装和可运行示例见 [接入文档](../README.md)。以下是可选能力，普通透明接入只需 `native`、`api_key`、`mode`。
+
+## 新任务工作流
+
+`client.atoms` 和 `client.sync_atoms` 已增加 Task、Execution、Revision、Attribution、Recipe Candidate、Verification、Memory v3 与 guided Run 的原子方法。方法名、请求体、幂等键和恢复语义见[任务工作流 SDK 开发契约](2026-10-28-task-workflow-sdk-design.md)。下方分别列出旧 `/v1/runs`、Memory 与文档上传 API。
+
+## 原子编排入口
+
+`CoSensClient(api_key=...)` 是异步上下文管理器，`rsi.atoms` 不会替应用执行模型或工具。
+
+所有 CoSens 原子接口（包括 `admin.atoms`）均发送 `X-Auth-Type: api_key` 与 `Authorization: Bearer <api_key>`；`Idempotency-Key` 仅在相应调用提供稳定幂等键时发送。显式提供的键必须为非空、最多 256 字符且不含控制字符；可选键传入空字符串会报错，不会静默省略。
+
+| 方法 | 调用时机 | 网关 `/api` 后路径 |
+| --- | --- | --- |
+| `artifact(name=..., content=...)` | 有真实输入材料或输出文本时 | `POST /v1/artifacts` |
+| `prepare(objective=..., key=...)` | 新任务，模型调用前；同任务重试复用 key | `POST /v1/runs/prepare` |
+| `get_run(run_id)` | prepare 就绪后冻结 snapshot；或恢复对账 | `GET /v1/runs/{run_id}` |
+| `session_events(run_id, events)` | 上报未 ACK 的事件；收到 durable_ack 才推进游标 | `POST /v1/runs/{run_id}/session-events` |
+| `initial_inputs(run_id, artifact_ids)` | 补充实际初始材料 | `POST /v1/runs/{run_id}/initial-inputs` |
+| `submit(run_id, data=..., key=...)` | 本地模型/工具完成后，提交实际输出 | `POST /v1/runs/{run_id}/submit` |
+| `feedback(run_id, data=..., key=...)` | 有真实用户反馈或验收证据后 | `POST /v1/runs/{run_id}/feedback` |
+| `improve(run_id, reason=..., key=...)` | 明确要求发起改进时 | `POST /v1/runs/{run_id}/improvements` |
+| `get_improvement(job_id)` / `wait_improvement(job_id)` | 查询/有界轮询异步改进 | `GET /v1/improvements/{job_id}` |
+| `resume_improvement(job_id)` | 确认任务可恢复后 | `POST /v1/improvements/{job_id}/resume` |
+| `admin.atoms.publish(job_id, expected_revision=..., reason=...)` | 显式批准发布时，须由外部网关实施管理员授权 | `POST /internal/admin/v1/improvements/{job_id}/publish` |
+
+`prepare` 返回 `processing` 时，使用同一个 key 有界轮询；只有 `ready` 才进入模型调用。不要将一次请求超时当成失败后创建新任务的依据。三种入口的详细接口时机见 [设计文档](2026-10-26-cosens-python-sdk-design.md)。
+
+## Session、工具和恢复
+
+透明方式的 `session` 为高级可选项：不传时捕获本次请求可见的用户文本、回复及已适配工具事件，不能读取应用未提供的历史。外部 Session 需提供稳定的 `session_id` 和 `get_items()`。建议模型调用前写入本次用户消息，保持稳定消息 ID；后写入的新 ID 无法证明与已合成事件相同。用 `client.cosens.scope(session_id="...", turn_id="...")` 显式划定一个逻辑 turn，工具循环复用它。
+
+显式 Agent 的 Session 交给 Agents SDK 管理；不传 Session 时会提交最终结果，但没有 Session 聊天事件可增量上报。可运行的 [显式示例](../examples/02_explicit_run.py) 使用持久化 `SQLiteSession`。恢复需使用原 session_id、Session 数据库和 CoSens 状态文件。
+
+原生 Agent 工具审批中断时不会提交最终结果。通过 `await client.pending_state(agent, turn_id)` 取得原生 `RunState`，按 Agents SDK `approve()`/`reject()` 后，调用 `await client.resume(agent, turn_id, native_state, session=session)` 继续。`input_artifacts=[{"name": "...", "content": "..."}]` 上传真实输入文本；`final_output` 含 `files` 列表时可上传实际输出文件。
+
+## 恢复与服务端边界
+
+Session 事件只在收到 `durable_ack` 后推进本地游标。失败后可查 `client.cosens.get_turn(turn_id)`；原生执行已完成但提交回执不明时用 `client.cosens.reconcile(turn_id)` 对账（异步客户端使用 `await`），不重新执行模型或工具。Agent 若在 `run()` 中传入 Session，对账也须显式 `await client.cosens.reconcile(turn_id, session=session)`；重启后先恢复原 session_id 和 Session 数据库，否则无法补报未 ACK 的历史。原生执行结果不明时抛 `RSIRecoveryRequired`，由宿主确认实际执行情况。透明调用的重试及工具续接必须保持 turn 创建时的 `mode`；模式变化或旧记录缺少模式时，SDK 会在模型调用和远端写入前拒绝隐式恢复。请持久化 `state_path`；丢失本地状态后，当前服务端不能保证跨 Run 的消息全局去重。
+
+网关 OpenAPI 当前标识为 1.0.0；以本次 curl 附件、网关实际返回和联调报告为准。审批协调器 `/v1/invocations` 仍未确认，透明 `approval` 命中时保持明确报错。单元测试使用模拟 HTTP；真实网关联调使用独立测试标识并写入合成测试数据，模型执行用本地替身验证编排，未调用真实模型或银行系统。详细时机与限制见 [设计文档](2026-10-26-cosens-python-sdk-design.md)。
+
+## Recipe、Memory 与决策接口
+
+普通原子接口（`atoms` 异步，`sync_atoms` 提供新增接口的同步形式）：
+
+| SDK 方法 | 网关 `/api` 后的路径 |
+| --- | --- |
+| `get_active_recipe(task_family=...)` | `GET /v1/recipes/active?task_family=...` |
+| `memory_ingest(content=..., request_key=..., source_id=..., expected_revision=..., source_kind=..., durable=...)` | `POST /v1/memory/ingest` |
+| `memory_recall(query=..., token_budget=1000)` | `POST /v1/memory/recall`；预算 1–8000 |
+| `get_memory_items(limit=200)` | `GET /v1/memory/items?limit=...`；limit 1–500 |
+| `get_memory_job(job_id)` | `GET /v1/memory/jobs/{job_id}` |
+| `get_memory_experience(experience_id, revision=...)` | `GET /v1/memory/experiences/{experience_id}` |
+| `get_memory()` | `GET /v1/memory` |
+| `get_recipe_step(run_id, node_id)` | `GET /v1/runs/{run_id}/recipe/steps/{node_id}` |
+| `guidance(run_id, data=...)` | `POST /v1/runs/{run_id}/guidance` |
+| `checkpoint(run_id, data=...)` | `POST /v1/runs/{run_id}/checkpoint` |
+| `get_decision(run_id, decision_id)` | `GET /v1/runs/{run_id}/decisions/{decision_id}` |
+| `get_trace(run_id)` | `GET /v1/runs/{run_id}/trace` |
+| `next_step(run_id)` | `POST /v1/runs/{run_id}/steps/next` |
+| `submit_step(run_id, attempt_id, attempt_token=..., outputs=..., decision_id=..., actual_action_id=...)` | `POST /v1/runs/{run_id}/steps/{attempt_id}/submit` |
+| `complete_guided(run_id)` | `POST /v1/runs/{run_id}/complete` |
+| `get_events(run_id)` | `GET /v1/runs/{run_id}/events` |
+
+`memory_ingest` 为兼容既有调用，SDK 仍显式发送 `source_kind="decision"`、`durable=True`；原始服务省略字段时的默认值分别是 `message`、`false`。需要原始服务默认语义时显式传 `source_kind="message", durable=False`。新增来源可省略 `expected_revision`（服务默认 0）；更新来源时传入 `source_id` 和当前 revision。`memory_ingest` 返回 `pending` 时使用原 `job_id` 查询至 `committed` 或 `failed`。`prepare(..., execution_mode="guided")` 启用 guided；`managed` 被客户端拒绝。guided 步骤的 `attempt_id`/`attempt_token` 应持久保存；原生动作结果未知时先对账，不能重放动作。`get_events` 与 `get_trace` 是不同接口，`complete_guided` 不代替 assist 的 `submit`。
+
+CN 已验证：`next_step` 的 `step_ready` 回执在 `node.output_contract` 声明输出端口。artifact 端口应传 `outputs={"files": [{"artifact_id": ..., "name": ..., "content_hash": ...}]}`，引用上传回执；单独 ID 不满足该端口。`submit_step` 的 HTTP 200 仍可能返回 `repair_required`，只有 `step_passed` 表示步骤通过。全流程完成后 `complete_guided` 返回 `completed`；`get_events` 返回含 `items` 列表的对象。
+
+`admin.atoms` 新增显式调用：`bootstrap_bundle`、`evaluate_decision`、`evaluate_recipe`，对应附件的 Recipe 注册、决策评估、Recipe 评估接口。它们不会由透明包装自动触发；调用者须提交实际执行和评估证据。`feedback` 不等于经验已经 verified，异步写入需轮询 Job/经验版本确认。
+
+`recall_context` 顺序读取 Recipe 和 Memory 后冻结本地结果，服务端未承诺两个独立读取拥有同一个事务快照。`disable` 使用 `general` 任务族；`auto` 未命中时使用分类结果的任务族。Recipe `not_found` 或 Memory 空列表是合法结果，HTTP 错误和缺失字段仍阻止业务模型调用。
+
+## 复现网关联调
+
+先由运行环境注入 `RSI_API_KEY`（没有设置时脚本隐藏输入 Key），在仓库根目录运行：
+
+两个诊断脚本均支持 `COSENS_REGION=cn`（默认）或 `us`，网关分别为 `https://friday-rsi-cn.stardust-ai.com/api`、`https://rsi.cosens.ai/api`。它们不加载 `.env` 或选择 `RSI_API_KEY_US`；请将目标区域的 Key 注入进程的 `RSI_API_KEY`。三种可直接运行的模型示例会读取 `.env` 并选择区域 Key，详见 [区域配置](../README.md#国内区与美国区测试)。
+
+```bash
+# 只读验证：健康状态和无 Run 召回
+python python/examples/validate_gateway.py --output /tmp/cosens-readonly.json
+
+# 会写入合成 Recipe、Memory、Run 和评估记录
+python python/examples/validate_gateway.py --write \
+  --transcript /path/to/FULL_CURL_TRANSCRIPT.md --output /tmp/cosens-workflow.json
+
+# 真实网关 + 本地模型/Agent 替身；会创建测试 Run，需要 agents 可选依赖
+python python/examples/validate_wrapped_gateway.py --output /tmp/cosens-wrapped.json
+```
+
+## 文档上传
+
+Python 异步 `client.atoms` 和同步 `client.sync_atoms` 均支持以下四个方法：
+
+| 方法 | 请求 |
+| --- | --- |
+| `create_document_upload_grant(filename=..., mime_type=..., **metadata)` | 签发一次性上传 grant |
+| `upload_document_to_grant(grant, content=...)` | 将非空原始字节上传一次 |
+| `upload_document(filename=..., mime_type=..., content=..., **metadata)` | 普通 multipart 上传 |
+| `get_document_status(document_ids)` | 查询非空文档 ID 列表 |
+
+```python
+import asyncio
+import os
+from pathlib import Path
+from cosens import CoSensClient
+
+async def main():
+    os.environ["COSENS_REGION"] = "cn"
+    async with CoSensClient(api_key=os.environ["RSI_API_KEY"]) as client:
+        content = Path("notes.txt").read_bytes()
+        grant = await client.atoms.create_document_upload_grant(
+            filename="notes.txt", mime_type="text/plain", wait_for_processing=False,
+        )
+        receipt = await client.atoms.upload_document_to_grant(grant, content=content)
+        # 持久化回执并检查业务状态；HTTP 200 不等于文件已完成处理。
+        if receipt.get("document_id"):
+            status = await client.atoms.get_document_status([receipt["document_id"]])
+            print(status)
+
+asyncio.run(main())
+```
+
+普通 multipart 可单独使用 `await client.atoms.upload_document(filename="notes.txt", mime_type="text/plain", content=content)`；它与 grant 上传是两种入口，不应对同一结果不明的文件依次尝试。同步宿主改用 `client.sync_atoms` 并去掉方法调用的 `await`。
+
+元数据、URL 校验和恢复规则见[开发契约第 8.4 节](2026-10-28-task-workflow-sdk-design.md#84-文档上传)。SDK 不接受用户身份覆盖，不自动重试一次性令牌，也不执行 grant 内的命令文本。Key 来自构造参数或进程环境 `RSI_API_KEY` / `COSENS_API_KEY`，SDK 本身不自动加载 `.env`。CN grant 路径尚未部署，以上代码需待服务上线后联调；离线契约测试已通过。

cosens_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cosens-sdk"
+version = "0.1.0"
+description = "CoSens Python SDK for OpenAI and RSI workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "openai>=2.54,<2.55"]
+
+[project.optional-dependencies]
+agents = ["openai-agents>=0.20,<0.21"]
+examples = ["openai-agents>=0.20,<0.21", "python-dotenv>=1,<2"]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "build>=1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cosens"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/cosens", "README.md", "pyproject.toml", "docs/api-reference.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"