open-agent-docs 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,266 @@
1
+ Metadata-Version: 2.5
2
+ Name: open-agent-docs
3
+ Version: 0.3.0
4
+ Summary: Open Agent Docs 的 Python SDK:同步 / 异步客户端、事件流、webhook 验签、JWT、本地起服务器
5
+ Project-URL: Homepage, https://github.com/kadaliao/open-agent-docs
6
+ Project-URL: Source, https://github.com/kadaliao/open-agent-docs/tree/main/sdks/python
7
+ License-Expression: MIT
8
+ Classifier: Framework :: AsyncIO
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3 :: Only
11
+ Classifier: Typing :: Typed
12
+ Requires-Python: >=3.9
13
+ Requires-Dist: httpx>=0.27
14
+ Requires-Dist: pydantic>=2
15
+ Provides-Extra: server
16
+ Requires-Dist: open-agent-docs-server==0.3.0; extra == 'server'
17
+ Description-Content-Type: text/markdown
18
+
19
+ # open-agent-docs(Python SDK)
20
+
21
+ [English](README.en.md)
22
+
23
+ [Open Agent Docs](https://github.com/kadaliao/open-agent-docs) 的 Python 客户端:同步、异步两套一样的方法,模型是 pydantic v2,
24
+ 带事件流、webhook 验签、签 JWT、嵌入地址和本地起服务器。依赖只有 `httpx` 和 `pydantic`,Python 3.9 起。
25
+
26
+ ## 安装
27
+
28
+ ```sh
29
+ pip install open-agent-docs
30
+ pip install "open-agent-docs[server]" # 再加上进程内的服务器(oad.start() 就不用下载二进制了)
31
+ ```
32
+
33
+ ## 建客户端
34
+
35
+ ```python
36
+ import open_agent_docs as oad
37
+
38
+ client = oad.Client(base_url="https://docs.example.com", token="oad_…")
39
+ client = oad.Client() # 读环境变量 OAD_BASE_URL(默认 http://127.0.0.1:8848)、OAD_TOKEN
40
+ ```
41
+
42
+ `token` 可以是 Agent 的 token(`oad_…`)、登录后的会话令牌,或者 `OAD_AUTH=jwt` 时宿主签的 JWT。其它参数:
43
+
44
+ | 参数 | 默认 | 说明 |
45
+ | --- | --- | --- |
46
+ | `timeout` | 60 | 单个请求的超时(秒);事件流只管连接 |
47
+ | `max_retries` | 2 | 429、502/503/504、连不上时重试几次(POST、PATCH 遇到 5xx 不重试) |
48
+ | `locale` | 无 | `zh` / `en`:服务器错误信息的语言 |
49
+ | `headers` | 无 | 每个请求额外带的头 |
50
+ | `header_secret` / `jwt_secret` | 无 | 替用户调,见下面 |
51
+ | `jwt_issuer`、`jwt_audience`、`jwt_ttl` | 无、无、3600 | `with_user` 签 JWT 时写进去 |
52
+ | `http_client` | 无 | 自己的 `httpx.Client`(代理、证书之类) |
53
+
54
+ 方法名和接口一一对应(点路径见 [sdks/operations.json](../operations.json)):`client.pages.versions.list(...)`、`client.me.get()`、`client.search(ws, q=...)`……
55
+ 路径参数按顺序是位置参数,别的都是关键字参数。
56
+
57
+ ## 建页面、写 Markdown
58
+
59
+ ```python
60
+ ws = client.default_workspace() # /me 里的第一个工作区(每个客户端只取一次)
61
+ page = client.pages.create(ws, title="周报", markdown="# 本周\n\n- 上线了 Python SDK") # 建完再写正文,两步
62
+
63
+ content = client.pages.content.get(page.id) # content.markdown、content.version
64
+ client.pages.content.replace(page.id, markdown=content.markdown + "\n更多", base=content.version)
65
+ client.pages.update(page.id, title="第 47 周")
66
+ client.pages.update(page.id, after=None) # 明确发 null:放到最前
67
+ for p in client.pages.list(ws):
68
+ print(p.id, p.title)
69
+ ```
70
+
71
+ 可选参数不传就不发;要发 `null` 就传 `None`(`oad.NOT_GIVEN` 是“没给”)。
72
+
73
+ 翻页的接口(`pages.versions.list`、`me.notifications.list`、`trash.list`……)返回一页 `oad.CursorPage`,直接 `for` 就会逐条取完所有页:
74
+
75
+ ```python
76
+ page = client.pages.versions.list(page_id, limit=20)
77
+ page.items, page.next_cursor, page.has_next_page() # 这一页
78
+ for v in page: # 自动带 cursor 取后面的
79
+ print(v.id, v.label)
80
+ ```
81
+
82
+ 上传、下载:
83
+
84
+ ```python
85
+ f = client.files.upload(ws, b"hello", "a.txt") # 也可以是 pathlib.Path、打开的文件、(文件名, bytes, 类型)
86
+ data = client.files.download(f.id) # bytes
87
+ db = client.databases.import_csv(ws, "名字,数量\n苹果,3\n", title="水果")
88
+ ```
89
+
90
+ ## 异步
91
+
92
+ ```python
93
+ async with oad.AsyncClient() as client:
94
+ ws = await client.default_workspace()
95
+ page = await client.pages.create(ws, title="周报")
96
+ async for v in client.pages.versions.list(page.id): # 翻页:直接 async for(await 它拿第一页)
97
+ ...
98
+ ```
99
+
100
+ ## 替用户调(宿主后端)
101
+
102
+ 宿主自己做登录,后端以当前用户的身份调 Open Agent Docs。服务器配 `OAD_AUTH=header` + `OAD_HEADER_SECRET`,或者 `OAD_AUTH=jwt` + `OAD_JWT_SECRET`:
103
+
104
+ ```python
105
+ admin = oad.Client(base_url=..., header_secret=SECRET) # 或 jwt_secret=SECRET
106
+ u = admin.with_user("u-42", name="王小明", email="x@example.com")
107
+ u.pages.list(u.default_workspace())
108
+ ```
109
+
110
+ `with_user` 返回一个新的客户端(共享连接池和配置),原来的不变。header 模式带 `X-OAD-Secret`、`X-OAD-User-Id / -Name / -Email`;
111
+ JWT 模式签一个 HS256 的 JWT(缓存到过期前 60 秒),`workspaces=["ws1"]` 或 `[{"id": "ws1", "role": "viewer"}]` 写进 claims。
112
+
113
+ FastAPI 里:
114
+
115
+ ```python
116
+ from fastapi import Depends, FastAPI, Request
117
+ import open_agent_docs as oad
118
+
119
+ app = FastAPI()
120
+ docs = oad.AsyncClient(base_url="http://127.0.0.1:8848", header_secret=SECRET) # 全局一个
121
+
122
+ async def docs_for(request: Request) -> oad.AsyncClient:
123
+ user = await my_current_user(request) # 宿主自己的登录
124
+ return docs.with_user(user.id, name=user.name, email=user.email)
125
+
126
+ @app.post("/notes")
127
+ async def create_note(title: str, text: str, d: oad.AsyncClient = Depends(docs_for)):
128
+ page = await d.pages.create(await d.default_workspace(), title=title, markdown=text)
129
+ return {"id": page.id}
130
+ ```
131
+
132
+ 完整的例子(进程内起服务器、两个用户):[examples/python-inprocess](../../examples/python-inprocess)。
133
+
134
+ ## 嵌入:签 JWT、iframe 地址
135
+
136
+ ```python
137
+ token = oad.sign_jwt(SECRET, "u-42", name="王小明", workspaces=["ws1"], ttl=3600) # HS256,只用标准库
138
+ url = oad.embed_url("https://docs.example.com", page_id, theme="dark", token=token)
139
+ # https://docs.example.com/p/<id>?embed=1&theme=dark#token=… (token 在 # 后面:不进服务器日志)
140
+ ```
141
+
142
+ 要 RS256 / ES256 的用自己的 JWT 库签,claims:`sub`、`name`、`email`、`workspaces`、`iat`、`exp`、`iss`、`aud`。
143
+
144
+ ## 事件
145
+
146
+ ```python
147
+ with client.workspaces.events(ws) as events: # 进 with 就连上了:之后发生的事件不会漏
148
+ for ev in events: # ev.name、ev.id、ev.data
149
+ if ev.name == "page.created":
150
+ print("新页面", ev.data.title) # data 按事件名解析成模型(Page……),不认识的给原始 JSON
151
+ elif ev.name == "resync":
152
+ ... # 落下了:重新拉一遍
153
+ ```
154
+
155
+ 断了自动重连(1 秒起翻倍、最多 30 秒,带 `Last-Event-ID`);401、403、404 不重连,直接抛错。别的线程里 `events.close()` 能让它停下。
156
+ 异步版:`async with client.workspaces.events(ws) as events: async for ev in events: ...`。
157
+
158
+ Agent 收通知(取 → 处理 → 确认):
159
+
160
+ ```python
161
+ bot = oad.Client(token=AGENT_TOKEN)
162
+ with bot.agent.notifications.stream() as stream: # 先补发没确认的,再实时推;每条 data 是 AgentNotification
163
+ for ev in stream:
164
+ note = ev.data
165
+ reply = handle(note.prompt) # prompt 可以直接当消息发给你的 Agent
166
+ bot.threads.reply(note.thread_id, body=reply)
167
+ bot.agent.notifications.ack(ids=[note.id]) # 处理完再确认:断了重连会补发没确认的
168
+ ```
169
+
170
+ 不想开长连接就轮询:`bot.agent.notifications.list(wait=30)`(长轮询,返回一页)。
171
+
172
+ ## Webhook
173
+
174
+ Agent 配了 webhook 地址时,服务器把通知 POST 过去,带 `X-OAD-Timestamp`、`X-OAD-Signature`。用建 Agent 时给的 `webhook_secret` 验:
175
+
176
+ ```python
177
+ note = oad.verify_webhook(WEBHOOK_SECRET, headers, raw_body) # 返回 AgentNotification
178
+ # 不对抛 oad.WebhookVerificationError,e.kind 是 signature / stale / malformed;时间戳差超过 300 秒算 stale
179
+ ```
180
+
181
+ 一定用原始的正文字节(别解析了再序列化)。FastAPI:
182
+
183
+ ```python
184
+ from fastapi import FastAPI, HTTPException, Request
185
+
186
+ @app.post("/oad-webhook")
187
+ async def webhook(request: Request):
188
+ try:
189
+ note = oad.verify_webhook(WEBHOOK_SECRET, request.headers, await request.body())
190
+ except oad.WebhookVerificationError as e:
191
+ raise HTTPException(401, e.kind)
192
+ background_tasks.add_task(handle, note) # 尽快回 2xx,慢活放后台
193
+ return {"ok": True}
194
+ ```
195
+
196
+ Flask:
197
+
198
+ ```python
199
+ from flask import Flask, abort, request
200
+
201
+ @app.post("/oad-webhook")
202
+ def webhook():
203
+ try:
204
+ note = oad.verify_webhook(WEBHOOK_SECRET, request.headers, request.get_data())
205
+ except oad.WebhookVerificationError:
206
+ abort(401)
207
+ queue.put(note)
208
+ return {"ok": True}
209
+ ```
210
+
211
+ ## 本地起服务器
212
+
213
+ ```python
214
+ with oad.start(data_dir="./data", auth="header", header_secret=SECRET) as server:
215
+ client = oad.Client(base_url=server.url, header_secret=SECRET)
216
+ ...
217
+ # 退出 with 时关掉(页面都存好再返回);或者 server = oad.start(...); ...; server.close()
218
+ ```
219
+
220
+ - 关键字参数转成环境变量:`data_dir` → `OAD_DATA_DIR`、`auth` → `OAD_AUTH`……(和命令行一样,见 docs/zh/configuration.md);不给 `port` 挑一个空端口。
221
+ - 装了 `open-agent-docs[server]` 就在进程里跑(Rust,自己的线程,不占 GIL)。
222
+ - 没装就跑二进制:`binary=` → 环境变量 `OAD_BINARY` → 缓存(`~/Library/Caches/open-agent-docs/v<版本>/`、`~/.cache/open-agent-docs/v<版本>/`)→
223
+ 从 GitHub 发布页下载(用同一个 release 的 `SHA256SUMS` 校验)。支持 macOS(arm64、x86_64)和 Linux(x86_64、aarch64),别的平台用 Docker。
224
+
225
+ ## 错误
226
+
227
+ ```python
228
+ try:
229
+ client.pages.get("nope")
230
+ except oad.NotFoundError as e:
231
+ print(e.status, e.code, e.message) # 404 not_found 页面 nope 不存在
232
+ except oad.RateLimitError as e:
233
+ time.sleep(e.retry_after or 1)
234
+ except oad.APIError as e: # 服务器回的别的错误:e.status、e.code、e.message、e.request_id
235
+ ...
236
+ except oad.APIConnectionError: # 连不上(oad.APITimeoutError 是超时)
237
+ ...
238
+ ```
239
+
240
+ | 状态码 | 类 |
241
+ | --- | --- |
242
+ | 400 | `BadRequestError` |
243
+ | 401 | `AuthenticationError` |
244
+ | 403 | `PermissionDeniedError` |
245
+ | 404 | `NotFoundError` |
246
+ | 409 | `ConflictError`(比如 `base` 版本对不上) |
247
+ | 410 | `GoneError` |
248
+ | 413 | `TooLargeError` |
249
+ | 429 | `RateLimitError`(`retry_after`) |
250
+ | 502 | `BadGatewayError` |
251
+ | 其它 5xx | `InternalServerError`(`BadGatewayError` 是它的子类) |
252
+
253
+ 所有错误的基类是 `oad.OADError`;配置不对是 `oad.ConfigurationError`。
254
+
255
+ ## 开发
256
+
257
+ ```sh
258
+ cd sdks/python
259
+ uv venv .venv && uv pip install --python .venv/bin/python -e . pytest pytest-asyncio pyright
260
+ python codegen/generate.py # 改了 docs/openapi.json 或 sdks/operations.json 后重新生成(src/open_agent_docs/_generated/)
261
+ python codegen/generate.py --check # 生成的是不是最新的(tests/test_codegen.py 也会查)
262
+ .venv/bin/python -m pytest # 单元测试;设了 OAD_BINARY 还跑场景测试(tests/conformance,S1–S15)
263
+ .venv/bin/pyright # 类型检查(strict)
264
+ ```
265
+
266
+ 模型和资源类是生成的(别手改),手写的运行时在 `src/open_agent_docs/_*.py`。
@@ -0,0 +1,22 @@
1
+ open_agent_docs/__init__.py,sha256=wWDRSbXTuMGWW0DMUQVYc1qMlE6DlF8ieU8goJ5hqtg,2323
2
+ open_agent_docs/_base_client.py,sha256=96Vd3ekFCbCgESGDB4dLRALNuVYscr3RsiIqhHN5D4A,25236
3
+ open_agent_docs/_client.py,sha256=A5t96K1gPgrSOb0dyuViFlpQsqF7otgwWykmQov1zmk,3995
4
+ open_agent_docs/_embed.py,sha256=mFXLtZigo7gLTynkKqb0xvK7DRl52rSeQRvNAJhnJUY,2885
5
+ open_agent_docs/_errors.py,sha256=Po9FZFDcutqND5gYmi4AMY9gx0nN-AB4ia4gyA_ESbk,5456
6
+ open_agent_docs/_files.py,sha256=iUXt3P5Py4MoTk6etiN3A0GGqPhwSbR24MvECON_kBQ,1708
7
+ open_agent_docs/_models.py,sha256=IMQID5XcdoEibE6hvhDHmmNl1JlJfGrQiL23na9HDRM,616
8
+ open_agent_docs/_pagination.py,sha256=T4NvaiVUuBth46ZN_B4vPIsUkbtBLtuwY1GJxvo96rw,4539
9
+ open_agent_docs/_server.py,sha256=I019YeieNYcO6yZnvXUFXUj3Zx-Jg2rVv6HplUyWemE,11617
10
+ open_agent_docs/_sse.py,sha256=VUgBlsI1OTNLkzOGhDb58cX_z3YpvXiA1T-T_U2uSOE,11649
11
+ open_agent_docs/_types.py,sha256=35f4OXsXGi1kbrCntVloZc1zrvhSu05AvsOZelSXiRc,876
12
+ open_agent_docs/_utils.py,sha256=gLFIQULfwZEGqPx0PR_bmJbKgVw9MJjDW2MUm09RZN0,438
13
+ open_agent_docs/_version.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
14
+ open_agent_docs/_webhook.py,sha256=veKXQ_WPCaWeyzmb3ld7jTspW0dICPvx9d3iDmbr41U,3541
15
+ open_agent_docs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
16
+ open_agent_docs/types.py,sha256=5Daq7AQXBOHsuN1z0J5L_r68wkbKHnSh82IVjYsCGfs,201
17
+ open_agent_docs/_generated/__init__.py,sha256=SDa4bU2upDSwHaIb_iGTH4R4JqepDUnWT6erjxwN0hQ,203
18
+ open_agent_docs/_generated/models.py,sha256=B-63LeGIAbWaJi3n_t23W5uZfoSSgS1v0e4sYJOkLvc,36676
19
+ open_agent_docs/_generated/resources.py,sha256=g6EwEXqIXv-9Nz1wBk4xW6XW4-1X9PNkIPmFiJTp6Ks,134502
20
+ open_agent_docs-0.3.0.dist-info/METADATA,sha256=rD1s-eNDPRa9n6E88wv8_-PUKI8vfjoYoUhNzdjUL0k,11449
21
+ open_agent_docs-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
22
+ open_agent_docs-0.3.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any