contract-archive-cli 0.2.7__py3-none-any.whl

contract_archive/pipelines/vl_ocr.py

@@ -0,0 +1,160 @@
+"""DashScope OCR：用专用 OCR 模型（qwen-vl-ocr）逐页转写 PDF 图片。
+
+为什么逐页：qwen-vl-ocr 是专用 OCR 模型，maxInputTokens 仅 30000，一次塞不下多页
+高分辨率图（旧实现把整份 PDF 全部页塞进一个请求，只有上下文极大的通用 VL 模型
+qwen3.6-flash 才扛得住，且慢、易超时）。这里改为每页一次调用、拼接结果，既用上专用
+OCR 模型，也消除了"页数超上限就回退 mineru"的硬限制。
+
+模型取 settings.dashscope_ocr_model（默认 qwen-vl-ocr-latest）；签章核查仍用 vl_model，
+互不影响。
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from ..config import get_timeout_s, load_settings
+from ..utils.http_env import sanitized_httpx_proxy_env
+
+logger = logging.getLogger(__name__)
+
+
+VL_OCR_PAGE_PROMPT = """你是严谨的 OCR 助理。请只转写这张图片中的全部文本，输出简洁 Markdown，不要总结、不要解释、不要编造。
+
+要求：
+- 表格尽量转成 Markdown 表格；复杂表格逐行保留字段名和值。
+- 保留保险/合同/凭证中的编号、姓名、日期、金额、保障责任、电话、地址等关键字段。
+- 看不清的地方写 `[看不清]`，不要猜。
+- 只输出本页文本，不要自己加页码标题（调用方会统一加 `## 第 X 页`）。
+"""
+
+# 单页三种异常态各用独立标记，互不混淆 —— 关键是把"请求失败"和"模型识别不清"分开：
+#   _MARK_FAILED    请求级失败（SDK 自动重试耗尽后仍抛错）。混进 [看不清] 就永久救不回、
+#                   也无法事后审计/单页补跑，所以必须独立。
+#   _MARK_TRUNCATED 输出触达模型 8192 token 上限被截断；已得内容保留，但显式标记残页。
+#   _MARK_ILLEGIBLE 模型正常返回但本页无可识别文本。
+_MARK_FAILED = "[本页 OCR 调用失败]"
+_MARK_TRUNCATED = "[本页输出达模型上限被截断]"
+_MARK_ILLEGIBLE = "[看不清]"
+
+
+def _ocr_max_retries() -> int:
+    """逐页 OCR 的 SDK 重试次数（CONTRACT_ARCHIVE_VL_OCR_RETRIES 可调，默认 4）。
+
+    openai SDK 对 429/超时/5xx/连接错误本就会自动指数退避重试（且读 Retry-After），
+    这里只是把默认的 2 调高 —— 一份文档逐页要发几十上百个请求，偶发限流/抖动的概率
+    随页数累积，靠 SDK 多重试几次比手写循环干净，也避免单页偶发失败直接丢一整页内容。
+    """
+    raw = os.getenv("CONTRACT_ARCHIVE_VL_OCR_RETRIES")
+    if not raw or not raw.strip():
+        return 4
+    try:
+        val = int(raw.strip())
+    except ValueError:
+        logger.warning("CONTRACT_ARCHIVE_VL_OCR_RETRIES=%r 不是整数，回退默认 4", raw)
+        return 4
+    return val if val >= 0 else 4
+
+
+def ocr_pdf_images_with_vl(
+    image_paths: list[Path],
+    *,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Optional[str]:
+    """
+    用 DashScope 专用 OCR 模型（OpenAI 兼容口）逐页转写渲染好的 PDF 页图片。
+
+    每页一次请求，拼成 `## 第 X 页` 分隔的 Markdown。单页异常不中断整份，三种异常态各记
+    独立标记（调用失败 / 输出截断 / 看不清），只有无任何可用页时才返回 None 让调用方回退到
+    原 MinerU 路径。429/超时/5xx 由 SDK 自动重试（见 _ocr_max_retries）。无凭证时返回 None。
+    """
+    if not image_paths:
+        return ""
+
+    settings = load_settings()
+    model = model or settings.dashscope_ocr_model
+    api_key = api_key or settings.dashscope_api_key
+    base_url = base_url or settings.dashscope_base_url
+    if not api_key:
+        logger.warning("DASHSCOPE_API_KEY missing; skip VL OCR")
+        return None
+
+    from openai import OpenAI
+
+    compat_url = base_url.replace("/api/v1", "/compatible-mode/v1")
+    total = len(image_paths)
+    logger.info("[vl-ocr] %s page(s) via %s (逐页)", total, model)
+
+    parts: list[str] = []
+    ok_pages = 0
+    failed_pages = 0
+    truncated_pages = 0
+    with sanitized_httpx_proxy_env():
+        client = OpenAI(
+            api_key=api_key,
+            base_url=compat_url,
+            timeout=get_timeout_s("DASHSCOPE_TIMEOUT_S", 300.0),
+            max_retries=_ocr_max_retries(),
+        )
+        for idx, path in enumerate(image_paths, 1):
+            content = [
+                {"type": "image_url", "image_url": {"url": _encode_image(path)}},
+                {"type": "text", "text": VL_OCR_PAGE_PROMPT},
+            ]
+            try:
+                resp = client.chat.completions.create(
+                    model=model,
+                    messages=[{"role": "user", "content": content}],
+                    temperature=0.0,
+                )
+                choice = resp.choices[0]
+                page_text = (choice.message.content or "").strip()
+                truncated = choice.finish_reason == "length"
+            except Exception as e:  # noqa: BLE001 - 单页失败不能拖垮整份；全失败才回退 MinerU
+                logger.warning("[vl-ocr] page %s/%s failed after retries: %s", idx, total, e)
+                failed_pages += 1
+                parts.append(f"## 第 {idx} 页\n\n{_MARK_FAILED}")
+                continue
+
+            if truncated:
+                # qwen-vl-ocr 单页输出硬上限 8192 token，超了会被静默截断。
+                # 保留已得内容（残页也有价值），但显式标记，避免下游把残页当完整页。
+                truncated_pages += 1
+                logger.warning(
+                    "[vl-ocr] page %s/%s truncated at output cap (maxOutputTokens=8192)",
+                    idx,
+                    total,
+                )
+                page_text = f"{page_text}\n\n{_MARK_TRUNCATED}".strip()
+
+            if page_text:
+                ok_pages += 1
+                parts.append(f"## 第 {idx} 页\n\n{page_text}")
+            else:
+                parts.append(f"## 第 {idx} 页\n\n{_MARK_ILLEGIBLE}")
+
+    if ok_pages == 0:
+        logger.warning(
+            "[vl-ocr] no usable page (%s failed / %s total); caller will fall back",
+            failed_pages,
+            total,
+        )
+        return None
+    logger.info(
+        "[vl-ocr] done: %s/%s ok, %s failed, %s truncated",
+        ok_pages,
+        total,
+        failed_pages,
+        truncated_pages,
+    )
+    return "\n\n".join(parts).strip() or None
+
+
+def _encode_image(path: Path) -> str:
+    data = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:image/png;base64,{data}"

contract_archive/schemas/__init__.py

@@ -0,0 +1,67 @@
+from .document import (
+    PREVIEW_DIR,
+    FILE_EXTRACTION,
+    FILE_EXTRACTION_CONF,
+    FILE_LAYOUT,
+    FILE_MARKDOWN,
+    FILE_PIPELINE_META,
+    FILE_RAW_TEXT,
+    FILE_STRUCTURED,
+    DOC_TYPES,
+    BBox,
+    Completeness,
+    CompletenessIssue,
+    SubAgreement,
+    ContractExtraction,
+    DocumentExtraction,
+    ExtractedEntity,
+    ExtractionConfidence,
+    FieldConfidence,
+    LabeledAmount,
+    LabeledDate,
+    LabeledValue,
+    LayoutBlock,
+    ObligationItem,
+    PersonIdentity,
+    Seal,
+    PipelineMeta,
+    PipelineOutput,
+    Section,
+    StructuredDocument,
+    Table,
+    TableCell,
+)
+
+__all__ = [
+    "BBox",
+    "LayoutBlock",
+    "Section",
+    "Table",
+    "TableCell",
+    "ExtractedEntity",
+    "StructuredDocument",
+    "PipelineMeta",
+    "PipelineOutput",
+    "ContractExtraction",
+    "DocumentExtraction",
+    "Completeness",
+    "CompletenessIssue",
+    "SubAgreement",
+    "LabeledValue",
+    "LabeledAmount",
+    "LabeledDate",
+    "PersonIdentity",
+    "Seal",
+    "DOC_TYPES",
+    "ObligationItem",
+    "FieldConfidence",
+    "ExtractionConfidence",
+    "FILE_RAW_TEXT",
+    "FILE_MARKDOWN",
+    "FILE_STRUCTURED",
+    "FILE_LAYOUT",
+    "FILE_PIPELINE_META",
+    "FILE_EXTRACTION",
+    "FILE_EXTRACTION_CONF",
+    "PREVIEW_DIR",
+]

contract_archive/schemas/document.py

@@ -0,0 +1,408 @@
+"""
+统一文档 schema：所有 OCR pipeline 必须把自己的输出归一化到这里。
+Schema 的稳定性是这个项目的命脉——后续 compare.py 完全依赖它。
+
+设计原则（Linus 的"好品味"）：
+- 字段尽量扁平、不嵌过深
+- 缺失字段统一用 None / 空列表，绝不报错
+- bbox 坐标统一规约为 PDF 原始 point (1pt = 1/72inch)，render dpi 不影响 schema
+- 多 pipeline 通过 pipeline_name 字段区分来源
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from ..errors import ErrorInfo
+
+# -------- 共用基本块 --------
+
+
+class BBox(BaseModel):
+    """
+    版面坐标框。坐标系：PDF 原始坐标系 (point)，原点左上角，y 向下。
+    所有 pipeline 在归一化时必须做坐标换算 (px → pt)，确保 layout.json 可跨 pipeline 比较。
+    """
+
+    page: int = Field(..., description="0-based 页码")
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+    @property
+    def width(self) -> float:
+        return self.x1 - self.x0
+
+    @property
+    def height(self) -> float:
+        return self.y1 - self.y0
+
+
+class LayoutBlock(BaseModel):
+    """单个版面块——layout.json 的元素。"""
+
+    bbox: BBox
+    text: str = ""
+    block_type: Literal[
+        "title",
+        "paragraph",
+        "table",
+        "figure",
+        "header",
+        "footer",
+        "list",
+        "formula",
+        "stamp",
+        "signature",
+        "other",
+    ] = "other"
+    confidence: Optional[float] = None
+    reading_order: Optional[int] = None
+
+
+# -------- structured.json --------
+
+
+class TableCell(BaseModel):
+    row: int
+    col: int
+    rowspan: int = 1
+    colspan: int = 1
+    text: str = ""
+
+
+class Table(BaseModel):
+    """归一化表格结构。同时保留 HTML 与 cell 矩阵，方便不同评估方式。"""
+
+    page: int
+    bbox: Optional[BBox] = None
+    html: Optional[str] = None  # PP-StructureV3/MinerU 都能直接给
+    cells: list[TableCell] = Field(default_factory=list)
+    n_rows: int = 0
+    n_cols: int = 0
+    caption: Optional[str] = None
+
+
+class Section(BaseModel):
+    level: int = 1  # 1=H1, 2=H2 ...
+    title: str
+    text: str = ""
+    page_start: int
+    page_end: int
+
+
+class ExtractedEntity(BaseModel):
+    """structured.json 里的通用 entity。专用合同字段走 extraction_result.json。"""
+
+    entity_type: str  # "person" / "org" / "money" / "date" / "address" ...
+    text: str
+    page: Optional[int] = None
+    bbox: Optional[BBox] = None
+    confidence: Optional[float] = None
+
+
+class StructuredDocument(BaseModel):
+    """structured.json 主体。"""
+
+    title: Optional[str] = None
+    document_type: Optional[str] = None  # "contract" / "invoice" / "report" / ...
+    language: str = "zh"
+    pages: int = 0
+    sections: list[Section] = Field(default_factory=list)
+    tables: list[Table] = Field(default_factory=list)
+    extracted_entities: list[ExtractedEntity] = Field(default_factory=list)
+
+
+# -------- 顶层 pipeline 输出 --------
+
+
+class PipelineMeta(BaseModel):
+    pipeline_name: Literal["mineru"]
+    pipeline_version: str = ""
+    model: str = ""
+    device: str = "cpu"
+    source_pdf: str
+    started_at: datetime
+    finished_at: datetime
+    duration_seconds: float
+    notes: str = ""
+
+
+class PipelineOutput(BaseModel):
+    """
+    一个 pipeline 跑完一份 PDF 的全部产物（结构化部分）。
+    raw_text.txt / markdown.md / preview_images/ 直接写文件，
+    layout.json / structured.json / pipeline_meta.json 也直接落盘。
+    本对象用于 in-memory 传递和单元测试。
+    """
+
+    meta: PipelineMeta
+    raw_text: str = ""
+    markdown: str = ""
+    layout: list[LayoutBlock] = Field(default_factory=list)
+    structured: StructuredDocument = Field(default_factory=StructuredDocument)
+    preview_image_paths: list[str] = Field(default_factory=list)
+
+
+# -------- Semantic Extraction --------
+
+
+class ObligationItem(BaseModel):
+    """
+    合同义务/动作条款。
+    与 risk_clauses 区别：
+      - obligation = "X 方应该做什么"（动作 + 截止）
+      - risk_clause = "违约后果"（罚则/赔偿/解除条件）
+    """
+
+    actor: Literal["party_a", "party_b", "both"]
+    action: str                         # "递交审贷资料"
+    deadline: Optional[str] = None      # ISO 'YYYY-MM-DD' 或 None
+    evidence: str = ""                  # 原文片段
+
+
+class ContractExtraction(BaseModel):
+    """合同语义抽取的统一 schema。所有字段都允许 None（抽不到比硬塞更诚实）。"""
+
+    contract_name: Optional[str] = None
+    party_a: Optional[str] = None  # 甲方
+    party_b: Optional[str] = None  # 乙方
+    amount: Optional[str] = None  # 保留原文（含币种），不强制转 float
+    amount_value: Optional[float] = None  # 解析后的数值（人民币元）
+    sign_date: Optional[str] = None  # 签订日期 ISO 8601
+    expire_date: Optional[str] = None  # 到期/失效日期 ISO 8601
+    auto_renewal: Optional[bool] = None
+    risk_clauses: list[str] = Field(default_factory=list)
+    obligations: list[ObligationItem] = Field(default_factory=list)
+    raw_evidence: dict[str, str] = Field(
+        default_factory=dict,
+        description="字段→原文证据片段，用于人工抽检",
+    )
+
+
+# -------- 通用文档抽取（LLM-first，跨类型） --------
+#
+# 设计（贴合"LLM-first、少死代码"）：不为每种文档类型写死 pydantic 字段表，
+# 而是一个通用信封——可查询的公共核心 + 柔性键值/金额/日期列表。
+# 加新文档类型 = 零代码：LLM 自行决定 fields/amounts/key_dates 抽哪些。
+
+
+class LabeledValue(BaseModel):
+    """类型专属字段的通用键值对。"""
+
+    label: str   # "持证人" / "职位" / "身份证号" / "发票号" ...
+    value: str   # 原文值（统一用字符串承载；数值/日期另见 amounts/key_dates）
+
+
+class PersonIdentity(BaseModel):
+    """
+    单个主体（自然人/机构）精确绑定的固有标识。
+
+    与扁平 fields 的区别：fields 是文档级零散键值，常把多人混在一条里
+    （如"乙方身份证号: 330106…；420302…"分不清哪个号属于谁）；这里把每个标识
+    精确绑定到具体的人/机构，是跨文档身份核对（known_parties 基准库）的基础——
+    同一主体的身份证号/电话/银行账号本应稳定，OCR 读错或被改动即可比对告警。
+    """
+
+    name: str                                    # 主体名（须与 parties 中某项对应）
+    role: Optional[str] = None                   # 本文档中的角色：甲方/乙方/买受人/持证人 等
+    # 该主体的固有标识键值：身份证号/电话/银行账号/开户行/统一社会信用代码 等。
+    # 复用 LabeledValue（label=标识名，value=标识值）。
+    identifiers: list[LabeledValue] = Field(default_factory=list)
+
+
+class LabeledAmount(BaseModel):
+    """带标签的金额。"""
+
+    label: str                      # "年收入" / "月均收入" / "公积金(个人)" / "合同金额"
+    text: str                       # 原文（含大写/币种）
+    value: Optional[float] = None   # 归一化数值（人民币元；unit 非空时为该单位下的单价数值）
+    # 计量单位：None=绝对金额（人民币元，默认，与历史一致）；非 None=单价/费率，
+    # value 是「每单位」的数值，量纲见此字段（如"元/月·㎡""元/个/月""元/日"）。
+    # 用于区分"合同总价 1228 万元"(unit=None) 与"物业费 2.25 元/月·㎡"(unit 非空)——
+    # 后者量纲不同，不可与绝对金额相加，也不参与 computed_total / 金额自洽校验。
+    # 同 unit 的周期单价可由代码派生周期费用（如物业费 = Σ按㎡单价 × 建筑面积）。
+    unit: Optional[str] = None
+    # 是否计入文档主合计：收入证明的"年度税前收入""年度股权收益"=True；
+    # "月均收入""公积金"等不该重复累加的=False。供 computed_total_value 求和。
+    # 单价项（unit 非空）一律 False——单价不是合同总价的组成部分。
+    is_total_component: bool = False
+    # 是否为某总价的"分期/部分付款"项（首期款/余款/定金/尾款）。供金额自洽校验：
+    # 同一总价的各分期项之和应≈总价(合计)，不符即疑似金额笔误
+    # （如车位首期误填 500000 > 总价 200000）。一次性付款、单价(元/月)等非分期项=False。
+    is_installment: bool = False
+    # 该金额覆盖的时间区间（ISO）。如"上年度""近12个月"由 LLM 据出具日解析为具体起止。
+    period_start: Optional[str] = None
+    period_end: Optional[str] = None
+    # 出处定位：页码 + 原文片段，让人能翻回原文核对这笔金额从哪来（与签章缺陷出处同一原则）。
+    evidence: str = ""
+
+
+class LabeledDate(BaseModel):
+    """带标签的日期。"""
+
+    label: str                      # "出具日" / "签订日" / "到期日" / "入职日"
+    date: Optional[str] = None      # ISO 8601 'YYYY-MM-DD'
+
+
+class Seal(BaseModel):
+    """
+    印章（红章）。来源是 MinerU 检测+OCR 的盖章文字，质量参差：
+    清晰的能给出主体+章类型（"XX有限公司 合同专用章"），残缺的可能只剩单字。
+    不强求拆出编号——OCR 残字硬塞编号是幻觉，宁可只留 raw_text。
+    """
+
+    raw_text: str                   # 印章 OCR 原文（可能残缺/乱序），可追溯
+    owner: Optional[str] = None     # 盖章主体（公司/机构全称），认不出留 None
+    seal_type: Optional[str] = None  # "公章" / "合同专用章" / "财务专用章" / "发票专用章" ...
+
+
+class CompletenessIssue(BaseModel):
+    """单条完整性缺陷（缺签章 / 缺要素）。"""
+
+    item: str                                          # 缺失/异常要素，如"甲方签章""签订日期""转让价款"
+    # signature=签章类，field=要素缺失类，amount=金额自洽异常类（如分期之和≠总价，代码确定性判出），
+    # identity=主体固有标识与基准不符（known_parties 跨文档核对，如身份证号被 OCR 读错/被改）
+    category: Literal["signature", "field", "amount", "identity"] = "field"
+    detail: str = ""                                   # 缺什么/异常什么（简述），如"落款处空白无章"
+    # 出处定位：页码 + 原文片段（签章类带落款页码），让人能翻回原文核对。
+    # 审计性结论的底线——不可追溯的缺陷不合格，宁可不报。
+    evidence: str = ""
+
+
+class Completeness(BaseModel):
+    """
+    合同完整性核查（仅合同协议适用，LLM 判定）。
+
+    两类缺陷：
+      - signature：落款区应盖章/签字的主体空着（用户最初的痛点：甲方未签章）
+      - field：该合同类型应具备的要素缺失（双方/标的/价款/签订日 等）
+
+    两条诚实底线：
+      1. 红章 OCR 不可靠——检测不到章可能是真没盖，也可能是淡红/模糊没被识别。
+         故缺章一律表述为"疑似"、供人工复核，不作为终判。
+      2. 必填要素由 LLM 据合同类型自行判断（车位转让无到期日、框架协议无具体金额
+         都属正常），不套死清单——把"本就不该有"的当缺失是误报之源。
+    """
+
+    status: Literal["complete", "incomplete", "unknown"] = "unknown"
+    issues: list[CompletenessIssue] = Field(default_factory=list)
+
+
+class SubAgreement(BaseModel):
+    """
+    文档内的附属协议——主协议之后所附的《补充协议》等。
+
+    依附主协议（修改/补充原协议条款），但常有自己独立的签章落款区与生效条件
+    （如"自甲方加盖公章、乙方签字之日生效"），故单列：既体现"这份 PDF 其实含 N 份
+    协议"，又让 completeness 能逐个协议单元分别核查签章（主协议缺章 ≠ 补充协议缺章）。
+    依附主协议故不单列 amounts/obligations——关键变更写进 summary，可追溯片段进 evidence。
+    """
+
+    title: str                       # 协议标题，如 "补充协议" / "补充协议（二）"
+    summary: str = ""                # 这份补充协议改了/补充了什么（关键变更，便于检索回忆）
+    sign_date: Optional[str] = None  # 该补充协议自己的签订/生效日 ISO（可能空白→None）
+    seals: list[Seal] = Field(default_factory=list)  # 补充协议落款上的印章（供完整性核查）
+    evidence: str = ""               # 原文关键片段，可追溯
+
+
+# 粗粒度规范类型（用于 --type 过滤）。LLM 从中择一，更细的归类放进 title/fields。
+DOC_TYPES = ("合同协议", "保险凭证", "旅行资料", "证明", "发票票据", "报告", "证件", "其他")
+DocType = str  # 存库用 str（保持柔性，不上 Literal 以免 LLM 新类型被卡死）
+
+
+class DocumentExtraction(BaseModel):
+    """
+    通用文档抽取信封：任何文档类型都归一化到这里（LLM-first）。
+
+    公共核心（doc_type/title/summary/primary_*/parties）落 documents 表列、可查询；
+    柔性 fields/amounts/key_dates/obligations 整体存 details_json，承载类型专属信息。
+    所有字段允许空——抽不到比硬塞更诚实。
+    """
+
+    doc_type: str = "其他"                  # 规范类型，取自 DOC_TYPES
+    title: Optional[str] = None             # 文档标题/抬头
+    summary: Optional[str] = None           # 一句话摘要（可追溯的关键钩子）
+    parties: list[str] = Field(default_factory=list)   # 涉及主体（人/机构全称）
+    primary_date: Optional[str] = None      # 主日期 ISO（合同=签订日，证明=出具日）
+    primary_amount_text: Optional[str] = None
+    primary_amount_value: Optional[float] = None
+    # 计算值（非抽取）：amounts 中 is_total_component=True 项之和。
+    # 例：收入证明 = 年度税前收入 + 年度股权收益。无可累加项则为 None。
+    computed_total_value: Optional[float] = None
+    # 派生值（非抽取，代码确定性算）：每月物业费估算
+    # = Σ(按建筑面积计价的物业类单价，元/月·㎡) × 建筑面积。
+    # 合同只给单价（物业服务费 2.25 + 服务费 4.55 + 能耗费 0.8 元/月·㎡），
+    # 买受人关心的是月实付额——由代码乘算（按㎡项才并入，车位"元/个/月"等不同量纲不并）。
+    # 抽不到单价或建筑面积则为 None。_text 是可追溯的算式说明。
+    monthly_property_fee_value: Optional[float] = None
+    monthly_property_fee_text: Optional[str] = None
+    key_dates: list[LabeledDate] = Field(default_factory=list)
+    amounts: list[LabeledAmount] = Field(default_factory=list)
+    seals: list[Seal] = Field(default_factory=list)   # 文档上的印章（有则可验真/索引）
+    fields: list[LabeledValue] = Field(default_factory=list)
+    # 精确绑定到人的固有标识（身份证/电话/银行账号…）。与扁平 fields 互补：
+    # fields 易把多人号码混在一条，这里按人拆开，供 known_parties 基准库逐人核对。
+    person_identities: list[PersonIdentity] = Field(default_factory=list)
+    obligations: list[ObligationItem] = Field(default_factory=list)
+    # 附属协议（主协议之外的《补充协议》等）。一份 PDF 可能含主协议 + N 份补充协议，
+    # 每份有独立签章落款；completeness 会逐个协议单元核查。无则空列表。
+    sub_agreements: list[SubAgreement] = Field(default_factory=list)
+    # 完整性核查：仅合同协议填，其他类型 None
+    # （"该不该有甲乙签章/要素齐不齐"对证明/发票无意义，强判只会制造噪声）。
+    completeness: Optional[Completeness] = None
+    # 身份基本信息核对结果（跨文档类型，不限合同）：person_identities 与 known_parties
+    # 基准库比对的不一致项（category="identity"）。首见入库不产生 issue，再见冲突才报。
+    # 独立于 completeness（后者专司合同签章/要素），避免污染其"仅合同适用"的语义。
+    identity_issues: list[CompletenessIssue] = Field(default_factory=list)
+    raw_evidence: dict[str, str] = Field(
+        default_factory=dict, description="字段→原文证据片段，用于人工抽检"
+    )
+    # 抽取元数据（非文档内容）：本次实际调用的 LLM 模型名（如 qwen3.7-max）。
+    # 随 extraction_result.json 留存，并镜像到 documents.llm_model，供 show 追溯抽取来源。
+    # 仅成功调用 LLM 时填；--no-llm / 无 key / 调用失败为 None。
+    llm_model: Optional[str] = None
+    # 抽取元数据（非文档内容）：本次 LLM 调用的 token 用量（input/output/total_tokens）。
+    # 来源 DashScope resp["usage"]；供评测算成本、生产侧成本追踪。读不到 / 未调用为 None。
+    llm_usage: Optional[dict] = None
+    # 抽取元数据（非文档内容）：本次抽取失败的结构化错误，含 retryable 供 Agent 判重试。
+    # 成功 / --no-llm 为 None。随 extraction_result.json 留存，并由 ingest 读出填 IngestResult.error。
+    extraction_error: Optional[ErrorInfo] = None
+
+
+class FieldConfidence(BaseModel):
+    """单字段置信度。"""
+
+    value_source: Literal["rule", "llm", "merged", "missing"] = "missing"
+    confidence: float = 0.0  # [0, 1]
+    rule_hit: bool = False
+    llm_agreed: Optional[bool] = None  # None = 未交叉验证
+
+
+class ExtractionConfidence(BaseModel):
+    """extraction_confidence.json 主体。逐字段给出置信度。"""
+
+    contract_name: FieldConfidence = Field(default_factory=FieldConfidence)
+    party_a: FieldConfidence = Field(default_factory=FieldConfidence)
+    party_b: FieldConfidence = Field(default_factory=FieldConfidence)
+    amount: FieldConfidence = Field(default_factory=FieldConfidence)
+    sign_date: FieldConfidence = Field(default_factory=FieldConfidence)
+    expire_date: FieldConfidence = Field(default_factory=FieldConfidence)
+    auto_renewal: FieldConfidence = Field(default_factory=FieldConfidence)
+    risk_clauses: FieldConfidence = Field(default_factory=FieldConfidence)
+    overall: float = 0.0
+
+
+# -------- 文件名常量 --------
+
+FILE_RAW_TEXT = "raw_text.txt"
+FILE_MARKDOWN = "markdown.md"
+FILE_STRUCTURED = "structured.json"
+FILE_LAYOUT = "layout.json"
+FILE_PIPELINE_META = "pipeline_meta.json"
+FILE_EXTRACTION = "extraction_result.json"
+FILE_EXTRACTION_CONF = "extraction_confidence.json"
+PREVIEW_DIR = "preview_images"

contract_archive/utils/__init__.py

@@ -0,0 +1,27 @@
+from .device import Device, describe_device, select_device
+from .pdf import (
+    PageImage,
+    PdfPageInfo,
+    TextLayerStats,
+    analyze_text_layer,
+    extract_text_layer,
+    inspect_pdf_pages,
+    is_scanned_pdf,
+    is_text_layer_usable,
+    render_pdf_to_images,
+)
+
+__all__ = [
+    "Device",
+    "select_device",
+    "describe_device",
+    "PageImage",
+    "PdfPageInfo",
+    "TextLayerStats",
+    "inspect_pdf_pages",
+    "render_pdf_to_images",
+    "extract_text_layer",
+    "analyze_text_layer",
+    "is_text_layer_usable",
+    "is_scanned_pdf",
+]