tcaicc 1.4.0rc1__tar.gz

tcaicc-1.4.0rc1/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / coverage caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# 明文默认 mTLS 证书源材料(由 hardcode.sh 加密进 _default_certs.py;密文可提交,明文不提交)
+cert/
+
+# doc/ 下 demo*.py 是权威文档示例,随仓库提交;doc.html 不在本仓库,维护于 ../aicc-sdk-doc/。

tcaicc-1.4.0rc1/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: tcaicc
+Version: 1.4.0rc1
+Summary: Tencent AICC confidential-model SDK for Python
+Author: Tencent
+License-Expression: Apache-2.0
+Keywords: aicc,confidential-computing,encryption,ml-kem,remote-attestation,sev-snp,tencent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=48
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# tcaicc
+
+Tencent AICC 机密模型的 Python SDK。
+
+接入分两步：
+
+1. **建立安全会话** —— 与运行在 SEV-SNP TEE 中的 aicc-service 握手，取得两端一致的 32B SessionKey（含远程证明验证）。推荐用 `SessionPool` 托管会话生命周期。
+2. **加密的 LLM 调用** —— 用该 SessionKey 加密 prompt、解密网关回文。加解密全程在本地完成，网关只见密文。
+
+完整文档见 **[`doc/doc-python.html`](doc/doc-python.html)**（用法说明 + 原理简介）；可运行示例分两套：按 model 经 `ModelPool` 发现端点的 [`doc/demo.py`](doc/demo.py)（非流式）/ [`doc/demo_stream.py`](doc/demo_stream.py)（流式），与直接指定端点的 [`doc/demo_endpoint.py`](doc/demo_endpoint.py)（非流式）/ [`doc/demo_endpoint_stream.py`](doc/demo_endpoint_stream.py)（流式，额外需 `AICC_ENDPOINT`）。
+
+## 安装
+
+要求 Python ≥ 3.10。
+
+```bash
+bash install.sh                     # 从源码构建并安装（覆盖旧版）
+bash install.sh --prod xxx.whl      # 安装指定 wheel
+pip install tcaicc                  # 或从私有源安装
+```
+
+运行时依赖 `cryptography`（≥48）、`httpx`（≥0.27）；测试依赖 `pytest`、`ruff`。
+
+## 快速开始
+
+```python
+import json
+import os
+
+import httpx
+
+from tcaicc import ModelPool, SessionFactory, SessionPool, default_policy, Protocol
+
+base_url = os.getenv("AICC_BASE_URL") or "https://aicc.example.com/v1/aicc"
+gateway_url = os.getenv("AICC_GATEWAY_URL") or "https://aicc.example.com/v1/chat/completions"
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME") or "your-model"
+
+
+def build(endpoint):                                    # 每端点一个独立工厂；端点由 ModelPool 统一注入
+    return SessionPool(
+        SessionFactory(base_url=base_url, ttl=60 * 60 * 8, api_key=api_key),
+        4,                                              # num = 池容量（会话数），非并发上限
+    )
+
+
+with ModelPool(base_url, api_key, 60 * 60 * 8, build) as models:
+    req = models.new_request(model_name)                # 发现+绑定+取会话+本轮请求（每轮一个）
+    policy = default_policy(Protocol.OPENAI)            # 内置默认路径，与网关互锚
+    body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+    enc_body = req.encrypt_request(json.dumps(body).encode(), policy)  # 按 policy 路径加密整个 body
+
+    r = httpx.post(gateway_url, content=enc_body,
+                   headers={"Content-Type": "application/json",
+                            "X-AICC-Mode": "1",
+                            "Authorization": f"Bearer {api_key}",
+                            "X-AICC-Endpoint": req.endpoint})   # 握手时的集群端点，网关据此路由
+    plain = req.decrypt_response(r.content, policy)     # 按 policy 路径解密整个响应
+    print(json.loads(plain)["choices"][0]["message"]["content"])
+```
+
+> **每轮 HTTP 请求必须新建一个 `Request`**：同一请求内所有密文段须出自同一个 `Request`，否则网关因凭证不一致返回 400。
+
+> `set_api_key` 只展开 `Authorization: Bearer`（不再带 `X-AICC-Mode`）。
+
+`req.encrypt` / `req.decrypt` 为 raw 级（原始信封字节，base64 由调用方处理，须显式给位置）；`req.encrypt_request` / `req.decrypt_response` 为 JSON 结构级（内部 base64，按 `Policy` 路径处理整个 body，位置自算）。两者示例见下节。
+
+### 逐段加解密（raw）与整体加解密
+
+整体（按 `Policy` 路径批量处理整个 body / 响应，位置由 SDK 自算）——即上文快速开始用法：
+
+```python
+from tcaicc import default_policy, Protocol
+
+policy = default_policy(Protocol.OPENAI)               # 内置默认路径
+enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+plain = req.decrypt_response(resp_bytes, policy)
+```
+
+逐段（raw，精确控制单字段）——返回/接收原始信封字节，调用方自行 base64 并置入 JSON，须显式给位置（`field_path` = 该字段的 policy 路径、`seq` = 同路径内第几段，从 0 起）：
+
+```python
+import base64
+
+# 加密：密文信封 base64 后置入请求字段
+body = {
+    "model": model_name,
+    "messages": [{"role": "user",
+                  "content": base64.b64encode(
+                      req.encrypt("你好".encode(), "messages.content", 0)).decode()}],
+}
+# 解密：从响应字段取出 base64 → 信封字节 → 明文
+field = r.json()["choices"][0]["message"]["content"]
+plain = req.decrypt(base64.b64decode(field), "choices.message.content", 0).decode()
+```
+
+### 流式响应（SSE）
+
+流式响应由调用方自行按 SSE 切分事件，逐事件交给 `StreamDecryptor` 解密。`decrypt_event` 按 `policy` 自动定位密文段（与 `decrypt_response` 同一套路径），返回 `(事件 JSON, is_last)`；返回 `None` 表示该事件是网关合成的尾片（勿转发），零命中 / 非 JSON 事件（如 `[DONE]`）原样返回事件字节，`is_last` 收到合法尾片后恒为 `True`。**只有 Strict 有尾片**:默认 Compatible / Simple 对新 gateway 不发尾片、`is_last` 恒 `False`,以协议终止帧(`[DONE]` / `message_stop` / Responses 终止事件)+ EOF 收束,且只有逐片完整性(丢片 / 截断不可察),要整流完整性用 `Mode.STRICT`。同一 `Request` 勿并发多条流;Compatible / Simple 下流结束后 gateway 异步释放槽位,勿把同一 `Request` 立刻用于下一次 HTTP 请求。非流式 `decrypt_response` 缺尾片只在 Strict 报 `ErrStreamTruncated`（`tcaicc.common.security`）。
+
+```python
+sd = req.new_stream_decryptor()
+with httpx.stream("POST", gateway_url, content=enc_body,
+                  headers={"Content-Type": "application/json",
+                           "X-AICC-Mode": "1",
+                           "Authorization": f"Bearer {api_key}",
+                           "X-AICC-Endpoint": req.endpoint}) as r:
+    for line in r.iter_lines():
+        if not line.startswith("data:"):
+            continue
+        data = line[len("data:"):].strip()
+        if data == "[DONE]":
+            break
+        plain, is_last = sd.decrypt_event(data.encode(), policy)
+        choices = json.loads(plain).get("choices") if plain else None
+        if choices:                                 # usage 等事件 choices 为空
+            print(choices[0].get("delta", {}).get("content") or "", end="")
+        if is_last:  # 对新 gateway 仅 Strict 会翻 True
+            break
+```
+
+### 长度隐藏
+
+prompt 与非流式 response 的内层按 1.5 倍几何桶填充（256 B 起，顶桶 9,695,112，共 27 桶），中间层只见所在的桶、不见精确长度；`pl` 即桶长，Hash 仍只盖真实数据。单段明文 ≤ `MAX_PADDED_PLAINTEXT_LEN`（9,695,108 B），超出抛 `TooLargeError`；`padded_len(n)` 可预估填充后长度。流式 chunk 不填充，片长仍可见；非流式回文仅在中间层逐字节透传时成立。
+
+### 会话池 / 端点池 / 模型池
+
+- `SessionPool(factory, num, key_generator=None)`：惰性托管至多 `num` 个共享会话；`get()` 取一个共享会话（勿 `close`），`new_request()` 一步取本轮请求（取到即被淘汰时自动重取）。`set_endpoint()` / `get_endpoint()` 转调工厂。默认 derive 模式，传 `key_generator`（返回 32B）走 import:会话经 `factory.new_session_with_key_generator(key_gen)` 建立,建会话与该会话每次 `renew()` 都重调一次(长度不符 `CryptoKeySizeError`（security 包的 `KeySizeError`，顶层别名）、回调抛错 → `KeyGeneratorError`(`"aicc sdk: key generator: <原错误>"`,原异常在 `__cause__`,无错误码),均在出网前;key 用后随机重写);`new_session(key)` 固定 key 的会话 `renew` 重导入同一把;同一会话并发 `renew` 串行化。
+- `EndpointPool(ttl)`：`endpoint → SessionPool` 固定寿命托管（`ttl` 秒，`-1` 永不过期）；`set/get/delete/close`，到期或替换即关旧池。
+- `ModelPool(base_url, api_key, ttl, build)`：按 `model+flags` 经 `describe_endpoints` 发现集群端点、绑定期 `ttl`、引用计数、刷新失败沿用旧绑定；`build(endpoint) -> SessionPool` 须每端点新建独立工厂。
+- 集群端点：`describe_endpoints` 返回不透明句柄（形如 `ept-…`），经 `factory.set_endpoint()` 于握手时以 `X-AICC-Endpoint` 头发出（不校验、不入 transcript）；`session.get_endpoint()` / `request.endpoint` 读回该路由值。
+- flags 词表：`FLAG_PROMPT_SHORT` / `FLAG_PROMPT_LONG`（路由提示，服务端本期不解析）。
+- 端点发现失败（服务端端点密钥未配等）抛 `SecuritySessionError`，`code == ENDPOINT_NOT_CONFIGURED`；不影响握手与数据面。
+- 默认位置校验模式为 **Compatible**（位置/协议不符记 info 日志后照解，默认阈值下不可见）；要拒绝不符显式 `factory.set_mode(Mode.STRICT)`（`Mode` 自 `tcaicc.common.cipherx` 导入）。
+- 握手与 `describe_endpoints` 每次尝试 15 秒超时（重试各自计时，默认传输施加）；`CreateSecuritySession` 与 `describe_endpoints` 遇传输失败 / 超时 / 5xx 有限重试（最多再试 2 次，退避 200ms、400ms，同一 RequestId）；业务错误与 Import / Derive 一次性消费不重试；单次响应上限 1 MiB。`set_transport` 注入的函数返回 None 或抛异常视同网络错误（文案含 `transport returned nil response` / 原异常），按上述规则重试。
+
+### 日志
+
+日志是**进程全局**的，没有按对象的设置项（对齐 Go `sdk.SetLogger` / `sdk.SetLogLevel`，spec `2026-10-10-sdk-logging-levels-design.md`）：
+
+```python
+import tcaicc
+
+tcaicc.set_logger(my_logger)              # 实现 debugf(msg) / infof(msg) / errorf(msg) 三方法即可;None 恢复默认(stderr)
+tcaicc.set_log_level(tcaicc.LogLevel.INFO)  # 阈值 DEBUG < INFO < ERROR < NONE;默认 ERROR;非法值 no-op
+```
+
+- 四级：`debug` 每请求 / 每次尝试的细节（握手每个 Action 的成功与重试、发现结果、请求创建、加解密命中数、池新建决策）；`info` 生命周期与被容忍 / 吞掉的事件（建会话、续约、会话入池出池、端点绑定换绑释放、Compatible / Simple 容忍的不一致、聚合分支、建会话失败回落、刷新失败沿用旧绑定、未钉 ARK）；`error` 当前没有落点；`none` 不落任何日志。
+- **默认阈值 error，而 SDK 当前没有 error 级落点，故默认零输出**；要看容忍 / 回落 / 生命周期开 info，看每请求细节开 debug。
+- logger 收到的是已格式化的一行文本，全部以 `aicc sdk: ` 开头，不含明文、密钥、api_key、token。默认实现写 stderr，前缀 `[DEBUG] ` / `[INFO] ` / `[ERROR] `。
+- 两个设置立即生效，对已建的工厂 / 池 / 会话 / 请求 / 流一视同仁；logger 须线程安全、勿阻塞、勿抛异常。SDK 不在自身锁内调用 logger（`renew` 期间握手层日志除外），但 logger 内勿同步等待自己可能正处于其中的 SDK 工作：同一会话的 `renew`、任何会落到同一 `SessionPool` 的取用、同一 `ModelPool` 同键的发现。
+
+## 模块
+
+| 模块 | 职责 |
+|---|---|
+| `tcaicc.common.security` | 安全会话握手（`SessionFactory` / `SecuritySession` / `SessionPool`）+ 数据面加解密（`Request` / `StreamDecryptor` / `Policy`）+ 错误码 |
+| `tcaicc.common.cipherx` | prompt/response/chunk 的 Envelope 密文格式（AES-256-GCM + AAD 绑定） |
+| `tcaicc.common.cryptox` | 底层原语：AEAD、HKDF、HMAC、LP 编码、X25519 + ML-KEM-768 混合 KEX、常数时间比较 |
+
+内置 AMD 信任锚以 PEM 文件随包分发（`tcaicc/common/security/trust_anchors/`），加载时逐字节校验 DER 的 SHA-256。
+
+## 测试
+
+```bash
+uv run pytest          # 全量用例（含参考服务端端到端握手；tests/ 被仓库 .gitignore 忽略，fresh clone 无此目录）
+uv run ruff check .    # lint
+```
+
+覆盖：cipherx KAT 黄金向量比对、内层填充（桶表字面值 / 桶校验 / 剥离失败）、DEK/token 派生固定向量、`Policy` 路径遍历与 JSON 结构级加解密、SEV 报告解析/链验/签名/绑定、参考服务端完整两趟握手（derive/import）、`SessionPool`（num 容量/共享取用/到期删除/重取）与 `EndpointPool`/`ModelPool`（发现/绑定/换绑/引用计数/并发单发现）、flags 词表与集群端点头快照、内置信任锚 DER SHA-256。
+
+## 目录结构
+
+```
+aicc-sdk/python/
+├── src/tcaicc/
+│   ├── __init__.py                 # SDK 入口（常用公开 API 经此导出；Mode 等少数名字在 tcaicc.common.* 下）
+│   └── common/
+│       ├── security/               # 握手 + 数据面 + 会话池 + 信任锚
+│       ├── cipherx/                # Envelope 密文格式 + KAT
+│       └── cryptox/                # 底层密码学原语
+├── doc/
+│   ├── doc-python.html             # 完整文档（用法说明 + 原理简介）
+│   ├── demo.py                     # 非流式 demo(ModelPool 发现端点)
+│   ├── demo_stream.py              # 流式 demo(ModelPool 发现端点)
+│   ├── demo_endpoint.py            # 非流式 demo(固定端点)
+│   └── demo_endpoint_stream.py     # 流式 demo(固定端点)
+├── tests/                          # pytest 用例（未入库：被仓库根 .gitignore 忽略）
+├── pyproject.toml
+└── install.sh
+```
+
+## License
+
+Apache-2.0。

tcaicc-1.4.0rc1/README.md

@@ -0,0 +1,195 @@
+# tcaicc
+
+Tencent AICC 机密模型的 Python SDK。
+
+接入分两步：
+
+1. **建立安全会话** —— 与运行在 SEV-SNP TEE 中的 aicc-service 握手，取得两端一致的 32B SessionKey（含远程证明验证）。推荐用 `SessionPool` 托管会话生命周期。
+2. **加密的 LLM 调用** —— 用该 SessionKey 加密 prompt、解密网关回文。加解密全程在本地完成，网关只见密文。
+
+完整文档见 **[`doc/doc-python.html`](doc/doc-python.html)**（用法说明 + 原理简介）；可运行示例分两套：按 model 经 `ModelPool` 发现端点的 [`doc/demo.py`](doc/demo.py)（非流式）/ [`doc/demo_stream.py`](doc/demo_stream.py)（流式），与直接指定端点的 [`doc/demo_endpoint.py`](doc/demo_endpoint.py)（非流式）/ [`doc/demo_endpoint_stream.py`](doc/demo_endpoint_stream.py)（流式，额外需 `AICC_ENDPOINT`）。
+
+## 安装
+
+要求 Python ≥ 3.10。
+
+```bash
+bash install.sh                     # 从源码构建并安装（覆盖旧版）
+bash install.sh --prod xxx.whl      # 安装指定 wheel
+pip install tcaicc                  # 或从私有源安装
+```
+
+运行时依赖 `cryptography`（≥48）、`httpx`（≥0.27）；测试依赖 `pytest`、`ruff`。
+
+## 快速开始
+
+```python
+import json
+import os
+
+import httpx
+
+from tcaicc import ModelPool, SessionFactory, SessionPool, default_policy, Protocol
+
+base_url = os.getenv("AICC_BASE_URL") or "https://aicc.example.com/v1/aicc"
+gateway_url = os.getenv("AICC_GATEWAY_URL") or "https://aicc.example.com/v1/chat/completions"
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME") or "your-model"
+
+
+def build(endpoint):                                    # 每端点一个独立工厂；端点由 ModelPool 统一注入
+    return SessionPool(
+        SessionFactory(base_url=base_url, ttl=60 * 60 * 8, api_key=api_key),
+        4,                                              # num = 池容量（会话数），非并发上限
+    )
+
+
+with ModelPool(base_url, api_key, 60 * 60 * 8, build) as models:
+    req = models.new_request(model_name)                # 发现+绑定+取会话+本轮请求（每轮一个）
+    policy = default_policy(Protocol.OPENAI)            # 内置默认路径，与网关互锚
+    body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+    enc_body = req.encrypt_request(json.dumps(body).encode(), policy)  # 按 policy 路径加密整个 body
+
+    r = httpx.post(gateway_url, content=enc_body,
+                   headers={"Content-Type": "application/json",
+                            "X-AICC-Mode": "1",
+                            "Authorization": f"Bearer {api_key}",
+                            "X-AICC-Endpoint": req.endpoint})   # 握手时的集群端点，网关据此路由
+    plain = req.decrypt_response(r.content, policy)     # 按 policy 路径解密整个响应
+    print(json.loads(plain)["choices"][0]["message"]["content"])
+```
+
+> **每轮 HTTP 请求必须新建一个 `Request`**：同一请求内所有密文段须出自同一个 `Request`，否则网关因凭证不一致返回 400。
+
+> `set_api_key` 只展开 `Authorization: Bearer`（不再带 `X-AICC-Mode`）。
+
+`req.encrypt` / `req.decrypt` 为 raw 级（原始信封字节，base64 由调用方处理，须显式给位置）；`req.encrypt_request` / `req.decrypt_response` 为 JSON 结构级（内部 base64，按 `Policy` 路径处理整个 body，位置自算）。两者示例见下节。
+
+### 逐段加解密（raw）与整体加解密
+
+整体（按 `Policy` 路径批量处理整个 body / 响应，位置由 SDK 自算）——即上文快速开始用法：
+
+```python
+from tcaicc import default_policy, Protocol
+
+policy = default_policy(Protocol.OPENAI)               # 内置默认路径
+enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+plain = req.decrypt_response(resp_bytes, policy)
+```
+
+逐段（raw，精确控制单字段）——返回/接收原始信封字节，调用方自行 base64 并置入 JSON，须显式给位置（`field_path` = 该字段的 policy 路径、`seq` = 同路径内第几段，从 0 起）：
+
+```python
+import base64
+
+# 加密：密文信封 base64 后置入请求字段
+body = {
+    "model": model_name,
+    "messages": [{"role": "user",
+                  "content": base64.b64encode(
+                      req.encrypt("你好".encode(), "messages.content", 0)).decode()}],
+}
+# 解密：从响应字段取出 base64 → 信封字节 → 明文
+field = r.json()["choices"][0]["message"]["content"]
+plain = req.decrypt(base64.b64decode(field), "choices.message.content", 0).decode()
+```
+
+### 流式响应（SSE）
+
+流式响应由调用方自行按 SSE 切分事件，逐事件交给 `StreamDecryptor` 解密。`decrypt_event` 按 `policy` 自动定位密文段（与 `decrypt_response` 同一套路径），返回 `(事件 JSON, is_last)`；返回 `None` 表示该事件是网关合成的尾片（勿转发），零命中 / 非 JSON 事件（如 `[DONE]`）原样返回事件字节，`is_last` 收到合法尾片后恒为 `True`。**只有 Strict 有尾片**:默认 Compatible / Simple 对新 gateway 不发尾片、`is_last` 恒 `False`,以协议终止帧(`[DONE]` / `message_stop` / Responses 终止事件)+ EOF 收束,且只有逐片完整性(丢片 / 截断不可察),要整流完整性用 `Mode.STRICT`。同一 `Request` 勿并发多条流;Compatible / Simple 下流结束后 gateway 异步释放槽位,勿把同一 `Request` 立刻用于下一次 HTTP 请求。非流式 `decrypt_response` 缺尾片只在 Strict 报 `ErrStreamTruncated`（`tcaicc.common.security`）。
+
+```python
+sd = req.new_stream_decryptor()
+with httpx.stream("POST", gateway_url, content=enc_body,
+                  headers={"Content-Type": "application/json",
+                           "X-AICC-Mode": "1",
+                           "Authorization": f"Bearer {api_key}",
+                           "X-AICC-Endpoint": req.endpoint}) as r:
+    for line in r.iter_lines():
+        if not line.startswith("data:"):
+            continue
+        data = line[len("data:"):].strip()
+        if data == "[DONE]":
+            break
+        plain, is_last = sd.decrypt_event(data.encode(), policy)
+        choices = json.loads(plain).get("choices") if plain else None
+        if choices:                                 # usage 等事件 choices 为空
+            print(choices[0].get("delta", {}).get("content") or "", end="")
+        if is_last:  # 对新 gateway 仅 Strict 会翻 True
+            break
+```
+
+### 长度隐藏
+
+prompt 与非流式 response 的内层按 1.5 倍几何桶填充（256 B 起，顶桶 9,695,112，共 27 桶），中间层只见所在的桶、不见精确长度；`pl` 即桶长，Hash 仍只盖真实数据。单段明文 ≤ `MAX_PADDED_PLAINTEXT_LEN`（9,695,108 B），超出抛 `TooLargeError`；`padded_len(n)` 可预估填充后长度。流式 chunk 不填充，片长仍可见；非流式回文仅在中间层逐字节透传时成立。
+
+### 会话池 / 端点池 / 模型池
+
+- `SessionPool(factory, num, key_generator=None)`：惰性托管至多 `num` 个共享会话；`get()` 取一个共享会话（勿 `close`），`new_request()` 一步取本轮请求（取到即被淘汰时自动重取）。`set_endpoint()` / `get_endpoint()` 转调工厂。默认 derive 模式，传 `key_generator`（返回 32B）走 import:会话经 `factory.new_session_with_key_generator(key_gen)` 建立,建会话与该会话每次 `renew()` 都重调一次(长度不符 `CryptoKeySizeError`（security 包的 `KeySizeError`，顶层别名）、回调抛错 → `KeyGeneratorError`(`"aicc sdk: key generator: <原错误>"`,原异常在 `__cause__`,无错误码),均在出网前;key 用后随机重写);`new_session(key)` 固定 key 的会话 `renew` 重导入同一把;同一会话并发 `renew` 串行化。
+- `EndpointPool(ttl)`：`endpoint → SessionPool` 固定寿命托管（`ttl` 秒，`-1` 永不过期）；`set/get/delete/close`，到期或替换即关旧池。
+- `ModelPool(base_url, api_key, ttl, build)`：按 `model+flags` 经 `describe_endpoints` 发现集群端点、绑定期 `ttl`、引用计数、刷新失败沿用旧绑定；`build(endpoint) -> SessionPool` 须每端点新建独立工厂。
+- 集群端点：`describe_endpoints` 返回不透明句柄（形如 `ept-…`），经 `factory.set_endpoint()` 于握手时以 `X-AICC-Endpoint` 头发出（不校验、不入 transcript）；`session.get_endpoint()` / `request.endpoint` 读回该路由值。
+- flags 词表：`FLAG_PROMPT_SHORT` / `FLAG_PROMPT_LONG`（路由提示，服务端本期不解析）。
+- 端点发现失败（服务端端点密钥未配等）抛 `SecuritySessionError`，`code == ENDPOINT_NOT_CONFIGURED`；不影响握手与数据面。
+- 默认位置校验模式为 **Compatible**（位置/协议不符记 info 日志后照解，默认阈值下不可见）；要拒绝不符显式 `factory.set_mode(Mode.STRICT)`（`Mode` 自 `tcaicc.common.cipherx` 导入）。
+- 握手与 `describe_endpoints` 每次尝试 15 秒超时（重试各自计时，默认传输施加）；`CreateSecuritySession` 与 `describe_endpoints` 遇传输失败 / 超时 / 5xx 有限重试（最多再试 2 次，退避 200ms、400ms，同一 RequestId）；业务错误与 Import / Derive 一次性消费不重试；单次响应上限 1 MiB。`set_transport` 注入的函数返回 None 或抛异常视同网络错误（文案含 `transport returned nil response` / 原异常），按上述规则重试。
+
+### 日志
+
+日志是**进程全局**的，没有按对象的设置项（对齐 Go `sdk.SetLogger` / `sdk.SetLogLevel`，spec `2026-10-10-sdk-logging-levels-design.md`）：
+
+```python
+import tcaicc
+
+tcaicc.set_logger(my_logger)              # 实现 debugf(msg) / infof(msg) / errorf(msg) 三方法即可;None 恢复默认(stderr)
+tcaicc.set_log_level(tcaicc.LogLevel.INFO)  # 阈值 DEBUG < INFO < ERROR < NONE;默认 ERROR;非法值 no-op
+```
+
+- 四级：`debug` 每请求 / 每次尝试的细节（握手每个 Action 的成功与重试、发现结果、请求创建、加解密命中数、池新建决策）；`info` 生命周期与被容忍 / 吞掉的事件（建会话、续约、会话入池出池、端点绑定换绑释放、Compatible / Simple 容忍的不一致、聚合分支、建会话失败回落、刷新失败沿用旧绑定、未钉 ARK）；`error` 当前没有落点；`none` 不落任何日志。
+- **默认阈值 error，而 SDK 当前没有 error 级落点，故默认零输出**；要看容忍 / 回落 / 生命周期开 info，看每请求细节开 debug。
+- logger 收到的是已格式化的一行文本，全部以 `aicc sdk: ` 开头，不含明文、密钥、api_key、token。默认实现写 stderr，前缀 `[DEBUG] ` / `[INFO] ` / `[ERROR] `。
+- 两个设置立即生效，对已建的工厂 / 池 / 会话 / 请求 / 流一视同仁；logger 须线程安全、勿阻塞、勿抛异常。SDK 不在自身锁内调用 logger（`renew` 期间握手层日志除外），但 logger 内勿同步等待自己可能正处于其中的 SDK 工作：同一会话的 `renew`、任何会落到同一 `SessionPool` 的取用、同一 `ModelPool` 同键的发现。
+
+## 模块
+
+| 模块 | 职责 |
+|---|---|
+| `tcaicc.common.security` | 安全会话握手（`SessionFactory` / `SecuritySession` / `SessionPool`）+ 数据面加解密（`Request` / `StreamDecryptor` / `Policy`）+ 错误码 |
+| `tcaicc.common.cipherx` | prompt/response/chunk 的 Envelope 密文格式（AES-256-GCM + AAD 绑定） |
+| `tcaicc.common.cryptox` | 底层原语：AEAD、HKDF、HMAC、LP 编码、X25519 + ML-KEM-768 混合 KEX、常数时间比较 |
+
+内置 AMD 信任锚以 PEM 文件随包分发（`tcaicc/common/security/trust_anchors/`），加载时逐字节校验 DER 的 SHA-256。
+
+## 测试
+
+```bash
+uv run pytest          # 全量用例（含参考服务端端到端握手；tests/ 被仓库 .gitignore 忽略，fresh clone 无此目录）
+uv run ruff check .    # lint
+```
+
+覆盖：cipherx KAT 黄金向量比对、内层填充（桶表字面值 / 桶校验 / 剥离失败）、DEK/token 派生固定向量、`Policy` 路径遍历与 JSON 结构级加解密、SEV 报告解析/链验/签名/绑定、参考服务端完整两趟握手（derive/import）、`SessionPool`（num 容量/共享取用/到期删除/重取）与 `EndpointPool`/`ModelPool`（发现/绑定/换绑/引用计数/并发单发现）、flags 词表与集群端点头快照、内置信任锚 DER SHA-256。
+
+## 目录结构
+
+```
+aicc-sdk/python/
+├── src/tcaicc/
+│   ├── __init__.py                 # SDK 入口（常用公开 API 经此导出；Mode 等少数名字在 tcaicc.common.* 下）
+│   └── common/
+│       ├── security/               # 握手 + 数据面 + 会话池 + 信任锚
+│       ├── cipherx/                # Envelope 密文格式 + KAT
+│       └── cryptox/                # 底层密码学原语
+├── doc/
+│   ├── doc-python.html             # 完整文档（用法说明 + 原理简介）
+│   ├── demo.py                     # 非流式 demo(ModelPool 发现端点)
+│   ├── demo_stream.py              # 流式 demo(ModelPool 发现端点)
+│   ├── demo_endpoint.py            # 非流式 demo(固定端点)
+│   └── demo_endpoint_stream.py     # 流式 demo(固定端点)
+├── tests/                          # pytest 用例（未入库：被仓库根 .gitignore 忽略）
+├── pyproject.toml
+└── install.sh
+```
+
+## License
+
+Apache-2.0。

tcaicc-1.4.0rc1/doc/demo.py

@@ -0,0 +1,47 @@
+# demo.py —— 非流式示例(ModelPool 按 model 发现端点):安全会话握手 → 加密请求 → 解密回文,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME
+#
+#   python doc/demo.py
+import json
+import os
+
+import httpx
+
+from tcaicc import ModelPool, Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+
+
+def run():
+    # ① 模型池:按 model 发现集群端点并握手,托管会话。
+    def build(endpoint):
+        return SessionPool(SessionFactory(base_url, api_key, ttl=60 * 60 * 8), 1)
+
+    with ModelPool(base_url, api_key, 60 * 60 * 8, build) as models:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with models.new_request(model_name) as req:
+            # ③ 加密请求体后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            r = httpx.post(gateway_url, content=enc_body, headers=headers, timeout=600)
+            if r.status_code != 200:
+                raise RuntimeError(f"gateway {r.status_code}: {r.text}")
+
+            # ④ 解密回文,打印明文回答。
+            plain = req.decrypt_response(r.content, policy)
+            print(json.loads(plain)["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0rc1/doc/demo_endpoint.py

@@ -0,0 +1,48 @@
+# demo_endpoint.py —— 非流式示例(固定端点):安全会话握手 → 加密请求 → 解密回文,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME、
+# AICC_ENDPOINT(集群端点;不经 DescribeEndpoints 发现,直接用于握手与数据面路由)
+#
+#   python doc/demo_endpoint.py
+import json
+import os
+
+import httpx
+
+from tcaicc import Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+endpoint = os.getenv("AICC_ENDPOINT")
+
+
+def run():
+    # ① 会话池:工厂固定集群端点,握手时带 X-AICC-Endpoint 头,托管会话。
+    factory = SessionFactory(base_url, api_key, ttl=60 * 60 * 8).set_endpoint(endpoint)
+
+    with SessionPool(factory, 1) as sessions:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with sessions.new_request() as req:
+            # ③ 加密请求体后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            r = httpx.post(gateway_url, content=enc_body, headers=headers, timeout=600)
+            if r.status_code != 200:
+                raise RuntimeError(f"gateway {r.status_code}: {r.text}")
+
+            # ④ 解密回文,打印明文回答。
+            plain = req.decrypt_response(r.content, policy)
+            print(json.loads(plain)["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0rc1/doc/demo_endpoint_stream.py

@@ -0,0 +1,62 @@
+# demo_endpoint_stream.py —— 流式示例(固定端点):安全会话握手 → 加密请求 → 逐 SSE 事件解密,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME、
+# AICC_ENDPOINT(集群端点;不经 DescribeEndpoints 发现,直接用于握手与数据面路由)
+#
+#   python doc/demo_endpoint_stream.py
+import json
+import os
+
+import httpx
+
+from tcaicc import Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+endpoint = os.getenv("AICC_ENDPOINT")
+
+
+def run():
+    # ① 会话池:工厂固定集群端点,握手时带 X-AICC-Endpoint 头,托管会话。
+    factory = SessionFactory(base_url, api_key, ttl=60 * 60 * 8).set_endpoint(endpoint)
+
+    with SessionPool(factory, 1) as sessions:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with sessions.new_request() as req:
+            # ③ 加密请求体(stream=true)后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}], "stream": True}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "Accept": "text/event-stream",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            timeout = httpx.Timeout(600, read=None)
+            with httpx.stream("POST", gateway_url, content=enc_body, headers=headers, timeout=timeout) as r:
+                if r.status_code != 200:
+                    raise RuntimeError(f"gateway {r.status_code}: {r.read().decode()}")
+
+                # ④ 逐个 SSE 事件解密,打印增量明文。
+                sd = req.new_stream_decryptor()
+                for line in r.iter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    data = line[len("data: "):]
+                    if data == "[DONE]":
+                        break
+                    plain, is_last = sd.decrypt_event(data.encode(), policy)
+                    choices = json.loads(plain).get("choices") if plain else None
+                    if choices:
+                        print(choices[0].get("delta", {}).get("content") or "", end="", flush=True)
+                    if is_last:
+                        break
+            print()
+
+
+if __name__ == "__main__":
+    run()