dpe-sdk

DPE（Document / Page / Element）协议的 Python SDK：把结构化文档正确、增量、可靠地投递到任意 DPE 服务端。

• sans-IO 协议核心 + httpx 传输适配（sync / async）；
• 只接受 remote URL 与可插拔的 CredentialProvider，不封装任何服务端私有端点；
• hash 由 dpe-hash 计算（同版本精确依赖）；
• 规范与源码：https://github.com/A2C-SMCP/dpe-protocol。

数据模型

三层对象（core §2）是 pydantic v2 模型：线上对象 ElementObject / PageObject / DocumentObject（子对象以 hash 列表引用），以及展开视图 Document / Page（页与元素内联）。

from dpe_sdk import Document, ElementObject, Page

doc = Document(
    file_type="md",
    title="A",
    pages=[Page(elements=[ElementObject(category="NarrativeText", text="hello")])],
)
doc.doc_hash()  # "dpe1:…"
doc.hashes()  # {"doc_hash", "pages": [{"page_hash", "elements"}…]}

• 校验全部交给 dpe-hash，顺序与错误码遵循 core §2.8；封闭 schema、category 允许的字段、file_type 枚举都取自 dpe_hash 的常量；
• 构造、model_validate、model_validate_json 失败时抛 dpe_hash.DpeHashError，带规范错误码 code 与违例位置 path（RFC 6901）；model_validate_json 按 I-JSON 严格解析（拒绝重复键）；
• 模型保留输入的原样表示，序列化只输出显式给出的字段；null 与缺省、metadata 缺省与 {} 是否等价由 hash 判定（core §2.7）。

协议错误与响应报文

• dpe_sdk.errors：core §6 的每个错误码一个异常类（基类 DpeError），带 code 与 retryable（只表示原样重试可能成功）；from_problem(problem, retry_after) 按 problem 体的 code 构造异常（含 missing 清单与 Retry-After），不按 HTTP 状态码分派；core §6 之外的码构造为 UnknownCodeError；
• 客户端本地判定不经 DpeError：本地判定为不合法时（目前如 get_skeleton 的 uri 不符合 core §1.1）在发请求前即抛 dpe_hash.ValidationError（ValueError 子类，code 仍为 DPE_VALIDATION）；响应不合规抛 UnexpectedResponseError。捕获 DpeError 的调用方请按需一并处理；
• dpe_sdk.wire：各端点的响应模型（Capabilities、Head、Skeleton、ListPage、CommitResult 等）；信封对未知成员宽容，内嵌的三层对象仍是封闭 schema。

参考服务端（testing）

dpe_sdk.testing.Engine 是内存版 DPE 服务端的核心引擎（不含传输），按规范的求值顺序实现 core 语义（含暂存会话与分块上传，#43），供集成测试与第三方实现对照：

from dpe_sdk.testing import Engine, EngineConfig, IfAbsent

engine = Engine(EngineConfig(max_payload_bytes=1 << 20))
body = b'{"document": {"file_type": "md", "pages": []}}'
engine.commit(
    "caller", "s3://bucket/a.md", body, "dpe1", IfAbsent()
)  # CommitResult(status="created", …)
engine.head("caller", "s3://bucket/a.md", "dpe1")

# 暂存路径：negotiate → upload_*（页 / 元素 / blob，支持分块与断点查询）→ commit 引用会话
session = engine.negotiate("caller", negotiate_body, "dpe1")  # NegotiateResult
engine.upload_page("caller", session.staging_session.id, page_hash, page_bytes, "dpe1")
engine.upload_offset("caller", session.staging_session.id, page_hash)  # 断点查询，不续期

• 带 JSON 请求体的操作（batch_head、negotiate、commit、move）接收原始字节，传输层上限、I-JSON、契约声明、请求信封、对象校验、授权、前置条件都在引擎内按 core §3.3、§3.4、§5.2 的顺序判定；upload_page / upload_element / upload_blob 按 HTTP 绑定 §4.6、§4.7 的两套阶梯处理，结果为 UploadResult（含续期后的 expires_at 与下一层缺失清单）；
• negotiate 与上传响应的缺失清单、commit 的可得性判定使用同一去重范围；可配置限额、受支持契约（第一个为主契约）、去重范围（DedupScope.DOCUMENT / WRITABLE）与可插拔授权器（can_write / can_force）；
• EngineConfig 的 clock 与 session_id_factory 可注入（会话过期与确定性测试）；
• 错误以 dpe_sdk.errors 抛出（分块偏移不连续为 UploadOffsetError，带 offset）。HTTP（ASGI）与一致性测试钩子随 #44、#45 接入。

客户端协议核心、传输适配与增量推送尚在开发中（#12–#17）。