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

contract_archive/config.py

@@ -0,0 +1,257 @@
+"""
+全局配置：XDG 配置文件 + 进程环境的统一加载。
+
+设计（对齐 clig.dev + 本项目的简洁取向）：
+- 配置文件走 XDG：$XDG_CONFIG_HOME/contract-archive/config.json（默认 ~/.config/...）。
+- 优先级 env > 配置文件 > 默认值，纯只读短路：`os.getenv() or file or default`。
+  cli.py 的 load_dotenv() 已把项目 .env 注入 os.environ（override=False，shell export
+  仍优先），所以 .env 天然落在 env 层——保留老 .env 用户零中断。
+- load_settings() 只读，**绝不回写 os.environ**；任何字段缺失都不报错
+  （api_key 缺失返回空串，由调用方在真要调 LLM 时降级，沿用既有"返回 {}+warning"语义）。
+- secret（api_key）落盘是明文，靠目录 0700 + 文件 0600 + 展示掩码保护；
+  不上 keyring（对单用户本地 CLI 过重，边际收益低）。
+- 故意不收：XDG_DATA_HOME（由 archive/paths.py 决定 data 位置，收进来是循环依赖）、
+  MinerU 子进程 environ（基础设施，非配置项）；COMPUTE_DEVICE/LOG_LEVEL 是运行时旋钮，
+  保持 env-only，不做持久配置。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+APP_CONFIG_DIR = "contract-archive"
+CONFIG_FILENAME = "config.json"
+DEFAULT_DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/api/v1"
+DEFAULT_DASHSCOPE_MODEL = "qwen3.7-max"
+DEFAULT_DASHSCOPE_VL_MODEL = "qwen3.6-flash"  # 多模态签章核查（OpenAI 兼容接口）；更准用 qwen3.6-plus
+DEFAULT_DASHSCOPE_OCR_MODEL = "qwen-vl-ocr-latest"  # OCR 阶段专用 OCR 模型，逐页调用（maxInput 30000，不能一次塞多页）
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigKey:
+    """一个受支持的全局配置键。"""
+
+    name: str               # 用户输入名 / 文件键名，如 "dashscope.api_key"
+    env_name: str           # 对应环境变量名（严格沿用现存名，保证老 .env 值仍被读到）
+    secret: bool = False    # 敏感项，展示时掩码
+    default: str | None = None
+
+
+# DashScope 四件套（LLM 抽取 / VL 签章 / OCR）+ 档案库路径。env_name 必须 = 现存环境变量名。
+CONFIG_KEYS: tuple[ConfigKey, ...] = (
+    ConfigKey("dashscope.api_key", "DASHSCOPE_API_KEY", secret=True),
+    ConfigKey("dashscope.base_url", "DASHSCOPE_BASE_URL", default=DEFAULT_DASHSCOPE_BASE_URL),
+    ConfigKey("dashscope.model", "DASHSCOPE_LLM_MODEL", default=DEFAULT_DASHSCOPE_MODEL),
+    ConfigKey("dashscope.vl_model", "DASHSCOPE_VL_MODEL", default=DEFAULT_DASHSCOPE_VL_MODEL),
+    ConfigKey("dashscope.ocr_model", "DASHSCOPE_OCR_MODEL", default=DEFAULT_DASHSCOPE_OCR_MODEL),
+    ConfigKey("archive.dir", "CONTRACT_ARCHIVE_DIR"),
+)
+_KEYS_BY_NAME = {k.name: k for k in CONFIG_KEYS}
+
+
+@dataclass(slots=True)
+class Settings:
+    """运行时配置：全局配置文件 + 进程环境合并后的取值。"""
+
+    dashscope_api_key: str
+    dashscope_base_url: str
+    dashscope_model: str
+    dashscope_vl_model: str
+    dashscope_ocr_model: str
+    archive_dir: str | None
+    config_path: Path
+
+
+def find_key(name: str) -> ConfigKey | None:
+    """按 name 查配置键定义；未注册返回 None。"""
+    return _KEYS_BY_NAME.get(name.strip())
+
+
+def config_path() -> Path:
+    """XDG 配置文件路径：$XDG_CONFIG_HOME/contract-archive/config.json（默认 ~/.config/...）。"""
+    return _xdg_base_dir("XDG_CONFIG_HOME", Path.home() / ".config") / APP_CONFIG_DIR / CONFIG_FILENAME
+
+
+def _xdg_base_dir(env_name: str, fallback: Path) -> Path:
+    """返回绝对 XDG 基目录，否则回退（与 archive/paths.py 同风格：仅绝对路径生效）。"""
+    raw = os.getenv(env_name)
+    if not raw:
+        return fallback
+    candidate = Path(raw).expanduser()
+    return candidate if candidate.is_absolute() else fallback
+
+
+def load_config_values(path: Path | None = None) -> dict[str, str]:
+    """
+    读配置文件为 {name: value}。文件不存在/损坏/含未知键都不报错——
+    只读路径必须健壮（坏配置不能让所有命令崩），未知键跳过并 warning。
+    """
+    cfg = path or config_path()
+    if not cfg.exists():
+        return {}
+    try:
+        payload = json.loads(cfg.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("配置文件读取失败，忽略 %s: %s", cfg, e)
+        return {}
+    if not isinstance(payload, dict):
+        logger.warning("配置文件必须是 JSON 对象，忽略: %s", cfg)
+        return {}
+    out: dict[str, str] = {}
+    for raw_key, raw_value in payload.items():
+        name = str(raw_key).strip()
+        if name not in _KEYS_BY_NAME:
+            logger.warning("配置文件含未知键，跳过: %s", name)
+            continue
+        if raw_value is None:
+            continue
+        value = str(raw_value).strip()
+        if value:
+            out[name] = value
+    return out
+
+
+def save_config_values(values: dict[str, str], path: Path | None = None) -> Path:
+    """写配置文件；目录 0700 / 文件 0600（每次都 chmod，防 umask 宽松导致 secret 可被他人读）。"""
+    cfg = path or config_path()
+    cfg.parent.mkdir(parents=True, exist_ok=True)
+    cfg.parent.chmod(0o700)
+    cfg.write_text(json.dumps(values, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    cfg.chmod(0o600)
+    return cfg
+
+
+def _read_value(values: dict[str, str], key: ConfigKey) -> str | None:
+    """
+    优先级 os.getenv(含 .env 注入) > 配置文件 > 默认值。只读，不回写 os.environ，不报错。
+
+    strip 后判 truthy，把"未设 / 空串 / 纯空白"三者一视同仁地回落下一层——一把消除
+    特殊情况（空串与空白串行为一致），与历史 _resolve_archive 的 truthy 语义一致。
+    默认值在此兜底（base_url/model 有 default），故 load_settings 无需再 `or DEFAULT`，
+    默认保持单一真相源（只在 CONFIG_KEYS 里定义一次）。
+    """
+    for candidate in (os.getenv(key.env_name), values.get(key.name), key.default):
+        if candidate and candidate.strip():
+            return candidate.strip()
+    return None
+
+
+def load_settings(path: Path | None = None) -> Settings:
+    """
+    加载运行时配置。惰性（每次现读，无缓存——CLI 一次进程读几次，缓存只会让
+    `config set` 同进程不生效 + 污染测试）。任何字段缺失都不报错。
+    """
+    values = load_config_values(path)
+
+    def read(name: str) -> str | None:
+        return _read_value(values, _KEYS_BY_NAME[name])
+
+    # 默认值的单一真相源是 CONFIG_KEYS 里的 default（_read_value 已兜底）。
+    # 这里的 `or DEFAULT_*` 不是第二默认源（引用同一常量），只是把 read() 的 str|None
+    # 类型收敛成 Settings 字段要求的 str。api_key 无 default，`or ""` 同理收敛。
+    return Settings(
+        dashscope_api_key=read("dashscope.api_key") or "",
+        dashscope_base_url=read("dashscope.base_url") or DEFAULT_DASHSCOPE_BASE_URL,
+        dashscope_model=read("dashscope.model") or DEFAULT_DASHSCOPE_MODEL,
+        dashscope_vl_model=read("dashscope.vl_model") or DEFAULT_DASHSCOPE_VL_MODEL,
+        dashscope_ocr_model=read("dashscope.ocr_model") or DEFAULT_DASHSCOPE_OCR_MODEL,
+        archive_dir=read("archive.dir"),
+        config_path=path or config_path(),
+    )
+
+
+def set_value(key: str, value: str, path: Path | None = None) -> Path:
+    """设置一个配置项。key 必须是注册表里的 name，否则报错列出支持的键。"""
+    name = _validate_key(key)
+    values = load_config_values(path)
+    values[name] = value.strip()
+    return save_config_values(values, path)
+
+
+def unset_value(key: str, path: Path | None = None) -> Path:
+    """从配置文件删除一个配置项（不影响环境变量）。"""
+    name = _validate_key(key)
+    values = load_config_values(path)
+    values.pop(name, None)
+    return save_config_values(values, path)
+
+
+def _validate_key(key: str) -> str:
+    name = key.strip()
+    if name not in _KEYS_BY_NAME:
+        supported = ", ".join(k.name for k in CONFIG_KEYS)
+        raise ValueError(f"不支持的配置键: {key}。支持的键: {supported}")
+    return name
+
+
+def get_timeout_s(env_name: str, default: float) -> float:
+    """
+    读一个"秒数"类运行时旋钮（如 DASHSCOPE_TIMEOUT_S / CONTRACT_ARCHIVE_MINERU_TIMEOUT_S）。
+
+    超时是运行时旋钮而非持久配置（同 LOG_LEVEL/COMPUTE_DEVICE），保持 env-only、不进 CONFIG_KEYS。
+    坏值（非数字/非正数/缺失）一律回退 default 并 warning——坏配置不该让命令崩，
+    与 load_config_values 的"坏配置不崩、warning 后降级"取向一致。
+    """
+    raw = os.getenv(env_name)
+    if not raw or not raw.strip():
+        return default
+    try:
+        val = float(raw.strip())
+    except ValueError:
+        logger.warning("%s=%r 不是合法数字，回退默认 %ss", env_name, raw, default)
+        return default
+    if val <= 0:
+        logger.warning("%s=%r 非正数，回退默认 %ss", env_name, raw, default)
+        return default
+    return val
+
+
+def display_value(key: ConfigKey, value: str | None, *, reveal: bool) -> str:
+    """展示用：secret 不 reveal 时掩码，空值显示 <unset>。"""
+    if not value:
+        return "<unset>"
+    if key.secret and not reveal:
+        return "********"
+    return value
+
+
+def visible_items(*, reveal: bool = False, path: Path | None = None) -> list[tuple[str, str]]:
+    """config show 用：按注册表顺序给出 (name, 展示值)，值已按 env>file>default 解析。"""
+    values = load_config_values(path)
+    return [(k.name, display_value(k, _read_value(values, k), reveal=reveal)) for k in CONFIG_KEYS]
+
+
+def describe_items(*, reveal: bool = False, path: Path | None = None) -> list[dict[str, object]]:
+    """
+    config show --format json 用：每个配置键的结构化描述（让 agent 程序化发现配置旋钮）。
+
+    含 key / env（对应环境变量名）/ secret / default / value（按 env>file>default 解析，
+    secret 默认掩码）/ source（值来自 env|file|default|unset）。source 判定与 _read_value 同序。
+    """
+    values = load_config_values(path)
+    out: list[dict[str, object]] = []
+    for k in CONFIG_KEYS:
+        env_v = os.getenv(k.env_name)
+        file_v = values.get(k.name)
+        if env_v and env_v.strip():
+            source = "env"
+        elif file_v and file_v.strip():
+            source = "file"
+        elif k.default:
+            source = "default"
+        else:
+            source = "unset"
+        out.append({
+            "key": k.name,
+            "env": k.env_name,
+            "secret": k.secret,
+            "default": k.default,
+            "value": display_value(k, _read_value(values, k), reveal=reveal),
+            "source": source,
+        })
+    return out

contract_archive/errors.py

@@ -0,0 +1,163 @@
+"""
+结构化错误模型——给机器（Agent / 自动化编排）一个可据以决策的错误信号。
+
+为什么存在：历史上错误是自由文本（`f"mineru: {e}"`），退出码只有 0/1，
+Agent 无法区分「限流（该退避重试）」与「缺 API key（重试无用，该停下改配置）」，
+只能正则匹配错误串——供应商一改措辞就崩。这里把错误归一成
+`code / category / retryable`，让上层（尤其 ingest 的 JSON 输出）携带可判定信号。
+
+设计原则：
+- 分类靠 duck-typing（异常类名 + status_code），**不 import openai**——
+  errors 是底层模块，不该绑死某个 SDK 的异常类层级，也避免无谓的强依赖。
+- ErrorInfo 是 pydantic 模型，可直接嵌进 DocumentExtraction 落盘、可 model_dump 进 JSON 输出。
+- retryable 是给 Agent 的核心信号：transient 类（限流/超时/网络/5xx）为 True，
+  config/permission/validation/user 类为 False。
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class ErrorCategory(str, Enum):
+    """错误大类。retryable 默认由类别决定（transient→可重试，其余不可）。"""
+
+    user = "user"              # 用户输入错（不存在的 id / 非 PDF）
+    validation = "validation"  # 入参/上游响应不合法（400、空抽取）
+    config = "config"          # 配置缺失或无效（缺 API key、key 失效）
+    permission = "permission"  # 鉴权通过但无权限（403）
+    transient = "transient"    # 瞬时故障，重试可能成功（限流/超时/网络/5xx）
+    infra = "infra"            # 基础设施/外部工具故障（MinerU 崩、DB 锁）
+    unknown = "unknown"        # 未能归类
+
+
+class ErrorInfo(BaseModel):
+    """
+    一条结构化错误。嵌进抽取信封落盘、并由 CLI 的 --format json 原样吐出。
+
+    :param code: 稳定的机器可读错误码（如 RATE_LIMITED），供 Agent switch。
+    :param category: 错误大类（见 ErrorCategory）。
+    :param message: 人类可读详情（已截断，避免把超长 traceback 灌进 JSON）。
+    :param retryable: 给 Agent 的核心信号——是否值得退避后重试。
+    :param retry_after_s: 建议的重试等待秒数（限流场景），未知为 None。
+    """
+
+    code: str
+    category: str
+    message: str
+    retryable: bool
+    retry_after_s: Optional[float] = None
+
+
+# message 截断长度：够定位问题，又不至于把整个 traceback/超长上游响应灌进 JSON。
+_MAX_MESSAGE_LEN = 500
+
+
+def _short(text: str) -> str:
+    """错误文本归一：去首尾空白 + 截断，保证 JSON 体积可控。"""
+    text = (text or "").strip()
+    return text if len(text) <= _MAX_MESSAGE_LEN else text[: _MAX_MESSAGE_LEN - 1] + "…"
+
+
+def classify_exception(exc: BaseException) -> ErrorInfo:
+    """
+    把一个（多半来自外部 API 调用的）异常归类成 ErrorInfo。
+
+    用 duck-typing 而非 isinstance(openai.XxxError)：读异常类名 + status_code，
+    既能识别 openai SDK 的异常（RateLimitError/AuthenticationError/...），
+    也能兜住自建网关/其他 SDK 抛出的形似异常。无法识别时归 UNKNOWN（不可重试，保守）。
+    """
+    name = type(exc).__name__
+    status = getattr(exc, "status_code", None)
+    if not isinstance(status, int):
+        status = None
+    msg = _short(str(exc))
+
+    # 限流：429 / RateLimitError。可重试，给默认退避建议。
+    if name == "RateLimitError" or status == 429:
+        return ErrorInfo(
+            code="RATE_LIMITED", category=ErrorCategory.transient.value,
+            message=msg, retryable=True, retry_after_s=_retry_after(exc),
+        )
+    # 认证失败 / key 无效：401。属配置问题，重试无用，应改配置。
+    if name == "AuthenticationError" or status == 401:
+        return ErrorInfo(
+            code="AUTH_FAILED", category=ErrorCategory.config.value,
+            message=msg, retryable=False,
+        )
+    # 鉴权通过但无权限：403。
+    if name == "PermissionDeniedError" or status == 403:
+        return ErrorInfo(
+            code="PERMISSION_DENIED", category=ErrorCategory.permission.value,
+            message=msg, retryable=False,
+        )
+    # 请求不合法：400（模型 id 错、参数非法）。重试无用。
+    if name == "BadRequestError" or status == 400:
+        return ErrorInfo(
+            code="BAD_REQUEST", category=ErrorCategory.validation.value,
+            message=msg, retryable=False,
+        )
+    # 超时：408 / openai 或 httpx 的超时异常 / 文本含 timeout。瞬时，可重试。
+    if (
+        name in ("APITimeoutError", "ReadTimeout", "ConnectTimeout")
+        or status == 408
+        or "timed out" in msg.lower()
+        or "timeout" in msg.lower()
+    ):
+        return ErrorInfo(
+            code="TIMEOUT", category=ErrorCategory.transient.value,
+            message=msg, retryable=True,
+        )
+    # 连接错误 / 上游 5xx：瞬时，可重试（含 httpx 裸 ConnectError）。
+    if name in ("APIConnectionError", "ConnectError", "InternalServerError") or (status is not None and status >= 500):
+        return ErrorInfo(
+            code="UPSTREAM_ERROR", category=ErrorCategory.transient.value,
+            message=msg, retryable=True,
+        )
+    return ErrorInfo(
+        code="UNKNOWN", category=ErrorCategory.unknown.value,
+        message=msg, retryable=False,
+    )
+
+
+def _retry_after(exc: BaseException) -> Optional[float]:
+    """尽力从异常/响应头取 Retry-After 秒数；取不到返回 None（由调用方自定退避）。"""
+    resp = getattr(exc, "response", None)
+    headers = getattr(resp, "headers", None)
+    if headers:
+        raw = headers.get("retry-after") or headers.get("Retry-After")
+        if raw:
+            try:
+                return float(raw)
+            except (TypeError, ValueError):
+                return None
+    return None
+
+
+# ---------- 非异常来源的常见错误构造器（语义清晰，省得各处手拼 ErrorInfo） ----------
+
+
+def config_missing(detail: str) -> ErrorInfo:
+    """缺必要配置（最常见：缺 DASHSCOPE_API_KEY）。重试无用，须先配置。"""
+    return ErrorInfo(
+        code="CONFIG_MISSING", category=ErrorCategory.config.value,
+        message=_short(detail), retryable=False,
+    )
+
+
+def extract_empty(detail: str) -> ErrorInfo:
+    """LLM 调用成功但抽取产出为空（非缺 key 场景）。保守标不可重试。"""
+    return ErrorInfo(
+        code="EXTRACT_EMPTY", category=ErrorCategory.validation.value,
+        message=_short(detail), retryable=False,
+    )
+
+
+def mineru_failed(detail: str) -> ErrorInfo:
+    """MinerU 解析失败（subprocess 非零/崩溃）。归基础设施类。"""
+    return ErrorInfo(
+        code="MINERU_FAILED", category=ErrorCategory.infra.value,
+        message=_short(detail), retryable=False,
+    )

contract_archive/extraction/__init__.py

@@ -0,0 +1,14 @@
+from .contract_extractor import extract_contract
+from .document_extractor import call_llm_document, extract_document
+from .llm_extractor import call_llm_extract
+from .normalize import coerce_obligations, normalize_date, parse_money_value
+
+__all__ = [
+    "extract_contract",
+    "extract_document",
+    "call_llm_document",
+    "call_llm_extract",
+    "normalize_date",
+    "parse_money_value",
+    "coerce_obligations",
+]

contract_archive/extraction/amount_check.py

@@ -0,0 +1,87 @@
+"""
+金额自洽性校验：纯确定性数值规则，不依赖 LLM 算术。
+
+为什么不交给 LLM：抽取时 LLM 会忠实抄录原文金额，但对"首期 500000 却 > 总价
+200000"这类数量矛盾毫无警觉（实测 29 号车位即 LLM 照抄矛盾数字而未报）。算术与
+比较交给代码，LLM 只负责语义标注（is_total_component / is_installment）。
+
+两条规则，都只产出"疑似异常、请人工核对"——属辅助筛查、非终判：
+  规则A 分期超额：各分期付款项(is_installment)之和 > 总价(合计) 即报（如首期50W＋
+        余款15W=65W > 总价20W，首期多打一个0）。**只报正差**——分期和 < 总价是认购预付、
+        首付+贷款等正常场景（认购预付50W+定金50W ≪ 房屋总价1228W），报了是误报。
+  规则B 单项越界：未计入合计、也未标分期的单项金额却 > 合计，疑似多填/笔误，
+        作为 LLM 漏标分期时的兜底。
+"""
+from __future__ import annotations
+
+from ..schemas import CompletenessIssue, LabeledAmount
+
+
+def _tolerance(total: float) -> float:
+    """金额比较容差：取「1元」与「合计的 1%」中较大者。
+
+    既容忍分/角小数舍入，又不会把数量级矛盾（50W vs 20W）当成噪声放过。
+    """
+    return max(1.0, abs(total) * 0.01)
+
+
+def _merge_evidence(amounts: list[LabeledAmount]) -> str:
+    """拼接各分期项的出处，便于翻回原文逐笔核对。"""
+    parts = [f"{a.label}：{a.evidence}" for a in amounts if a.evidence]
+    return "；".join(parts)
+
+
+def check_amount_consistency(
+    amounts: list[LabeledAmount], computed_total: float | None
+) -> list[CompletenessIssue]:
+    """
+    金额自洽校验 → amount 类缺陷列表。
+
+    无合计基准（computed_total 为空或 ≤0）时不校验——没有"总价"做参照，
+    谈不上自洽，硬比会误报。
+    """
+    issues: list[CompletenessIssue] = []
+    if not computed_total or computed_total <= 0:
+        return issues
+    tol = _tolerance(computed_total)
+
+    # 规则A：分期付款项之和 **超过** 总价才报（只报正差）。
+    # 不报负差：认购/预售先付定金预付款、首付+贷款等，已列分期项之和本就小于总价
+    # 属正常（认购预付50W+定金50W ≪ 房屋总价1228W），报负差是误报。
+    # 分期之和 > 总价 才是硬矛盾（29号首期50W＋余款15W=65W > 总价20W，首期误填）。
+    installments = [a for a in amounts if a.is_installment and a.value is not None]
+    if installments:
+        inst_sum = round(sum(a.value for a in installments), 2)
+        overshoot = round(inst_sum - computed_total, 2)
+        if overshoot > tol:
+            labels = "＋".join(a.label for a in installments)
+            issues.append(CompletenessIssue(
+                item="分期款超过总价",
+                category="amount",
+                detail=(
+                    f"分期款之和（{labels}）={inst_sum:,.0f}元，"
+                    f"超过总价/合计 {computed_total:,.0f}元（多 {overshoot:,.0f}元），"
+                    f"疑似金额笔误，请人工核对"
+                ),
+                evidence=_merge_evidence(installments),
+            ))
+
+    # 规则B：未计入合计、也未标分期的单项却超过合计（兜底 LLM 漏标分期的场景）。
+    for a in amounts:
+        if (
+            not a.is_total_component
+            and not a.is_installment
+            and not a.unit            # 单价项（元/月·㎡ 等）量纲不同，不与合同金额比，跳过
+            and a.value is not None
+            and a.value > computed_total + tol
+        ):
+            issues.append(CompletenessIssue(
+                item=f"{a.label}超过合计",
+                category="amount",
+                detail=(
+                    f"{a.label}={a.value:,.0f}元 超过合计 {computed_total:,.0f}元，"
+                    f"疑似多填/笔误，请人工核对"
+                ),
+                evidence=a.evidence,
+            ))
+    return issues

contract_archive/extraction/contract_extractor.py

@@ -0,0 +1,103 @@
+"""
+合同字段抽取（LLM-only）。
+
+Phase 2 起退役了 rule_extractor + rule/LLM hybrid 合并：合同抽取与其余文档类型
+一样走纯 LLM，只对 LLM 输出做确定性数值归一化（金额→数值、日期→ISO）。
+保留 ContractExtraction schema 与合同专属列/搜索（party/到期/续约/风险/义务），
+是因为这些是文档化的能力，不破坏。
+
+合同的 LLM prompt 仍是那份调校过的 LLM_SYSTEM_PROMPT（见 llm_extractor）。
+"""
+from __future__ import annotations
+
+import logging
+
+from ..schemas import (
+    ContractExtraction,
+    ExtractionConfidence,
+    FieldConfidence,
+)
+from .llm_extractor import call_llm_extract
+from .normalize import (
+    coerce_bool,
+    coerce_obligations,
+    coerce_str_list,
+    normalize_date,
+    parse_money_value,
+)
+
+logger = logging.getLogger(__name__)
+
+# 参与 overall 置信度均值的字段（与历史口径一致）
+_SCORED_FIELDS = (
+    "contract_name", "party_a", "party_b", "amount",
+    "sign_date", "expire_date", "auto_renewal", "risk_clauses",
+)
+
+
+def _build_confidence(ext: ContractExtraction) -> ExtractionConfidence:
+    """
+    LLM-only 置信度：有值即 llm/0.7，无值 missing/0.0。
+    无 rule 交叉验证，故不再有 merged/0.9 与 rule_hit 维度——诚实反映"只有 LLM 一票"。
+    """
+    conf = ExtractionConfidence()
+
+    def fc(present: bool) -> FieldConfidence:
+        return FieldConfidence(
+            value_source="llm" if present else "missing",
+            confidence=0.7 if present else 0.0,
+            rule_hit=False,
+            llm_agreed=None,
+        )
+
+    conf.contract_name = fc(bool(ext.contract_name))
+    conf.party_a = fc(bool(ext.party_a))
+    conf.party_b = fc(bool(ext.party_b))
+    conf.amount = fc(bool(ext.amount))
+    conf.sign_date = fc(bool(ext.sign_date))
+    conf.expire_date = fc(bool(ext.expire_date))
+    conf.auto_renewal = fc(ext.auto_renewal is not None)
+    conf.risk_clauses = fc(bool(ext.risk_clauses))
+    scores = [getattr(conf, f).confidence for f in _SCORED_FIELDS]
+    conf.overall = sum(scores) / len(scores)
+    return conf
+
+
+def extract_contract(
+    document_text: str,
+    llm_enabled: bool = True,
+    model: str | None = None,
+) -> tuple[ContractExtraction, ExtractionConfidence]:
+    """
+    合同字段抽取主入口（LLM-only）。
+
+    :param llm_enabled: False（或无 API key / LLM 失败）时返回空结果——
+                        纯 LLM 路径无 rule 兜底，抽不到比硬塞更诚实。
+    :param model: 覆盖抽取所用 model（默认 None=走 settings.dashscope_model）；
+                  合同线是双 LLM 调用之一，评测换模型时与 extract_document 同步穿透才保真。
+    """
+    if not llm_enabled:
+        return ContractExtraction(), ExtractionConfidence()
+
+    raw = call_llm_extract(document_text, model=model).parsed
+    if not raw:
+        return ContractExtraction(), ExtractionConfidence()
+
+    ext = ContractExtraction(
+        contract_name=(raw.get("contract_name") or None),
+        party_a=(raw.get("party_a") or None),
+        party_b=(raw.get("party_b") or None),
+        amount=(raw.get("amount") or None),
+        sign_date=normalize_date(raw.get("sign_date")) if isinstance(raw.get("sign_date"), str) else None,
+        expire_date=normalize_date(raw.get("expire_date")) if isinstance(raw.get("expire_date"), str) else None,
+        auto_renewal=coerce_bool(raw.get("auto_renewal")),
+        risk_clauses=coerce_str_list(raw.get("risk_clauses")),
+        obligations=coerce_obligations(raw.get("obligations")),
+    )
+    ext.amount_value = parse_money_value(ext.amount)
+    ext.raw_evidence = {
+        k: f"[LLM] {getattr(ext, k)}"
+        for k in ("contract_name", "party_a", "party_b", "amount", "sign_date")
+        if getattr(ext, k)
+    }
+    return ext, _build_confidence(ext)