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

contract_archive/extraction/llm_extractor.py

@@ -0,0 +1,207 @@
+"""
+LLM-based 合同字段抽取。
+
+模型：DashScope qwen3.7-max（严格按用户指定的 model id，不要替换）
+
+策略：
+- 一次性把 markdown / raw_text 喂给 LLM，让其返回结构化 JSON
+- 用 JSON Schema/示例约束输出
+- 失败/超时时返回空字典，由调用方（contract_extractor）处理为空抽取
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from ..config import get_timeout_s, load_settings
+from ..errors import ErrorInfo, classify_exception, config_missing
+from ..utils.http_env import sanitized_httpx_proxy_env
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LlmResult:
+    """
+    一次 LLM 调用的产物 + 元数据。
+
+    把 parsed / model / usage 一起作为返回值传出，让"实际用了哪个模型""花了多少
+    token"成为可信的返回值，而非靠外部 monkeypatch 拦截偷取（SDK 一升级猴补就静默失效）。
+    评测据 usage 算成本；model 是单一真相源，杜绝"记录的模型≠实际跑的模型"。
+    失败路径返回 parsed={}，与历史"返回空 dict"语义一致（调用方判 `if not res.parsed`）。
+    """
+
+    parsed: dict[str, Any]                # 解析后的 JSON；失败为空 dict
+    model: str                            # 本次实际请求的 model id
+    usage: dict[str, Any] | None = None   # token 用量（DashScope resp["usage"]）；读不到为 None
+    error: Optional[ErrorInfo] = None     # 结构化错误（缺 key / API 异常）；成功为 None
+
+
+LLM_SYSTEM_PROMPT = """你是一名严谨的法律助理。请从给定的合同文本中抽取结构化字段。
+铁律：
+1. 只输出 JSON，不要任何解释、前缀、Markdown 代码块标记。
+2. 抽不到的字段填 null，禁止猜测、禁止拼凑。
+3. 如果合同里某个日期是占位符或空白（如"___年__月__日"、"2026年5月_日"），返回 null，不要补全。
+4. 日期统一为 ISO 8601 (YYYY-MM-DD)。
+5. 金额保留原文（如"人民币贰万元整"或"210000 元整"）。
+6. 签订日期(sign_date)：仅取合同最后落款/签字处的日期；如未明确则 null，不要把"付款日"或"交付日"当签订日。
+7. 到期日期(expire_date)：仅取合同明确的有效期/失效日；车位转让、买卖等一次性合同通常没有，应填 null。
+8. party_a / party_b：填全称（含公司类型如"有限公司"或买受人完整身份描述）。
+9. risk_clauses 是字符串数组，每条 ≤80 字，仅列违约/赔偿/争议解决/不可抗力/保密/管辖等"出问题后果"型条款。
+10. obligations 是动作清单——"X 方应/须于 Y 之前做 Z"型条款。
+    与 risk_clauses 严格区分：
+      - 动作类（要做某事、按时交付、提交资料、付款、验收、盖章、签订其他合同）→ obligations
+      - 后果类（违约金、解除权、争议解决、滞纳金、赔偿、不可抗力免责）→ risk_clauses
+    每条 obligation 必须含：actor、action、deadline（若无明确日期则 null）、evidence（原文片段≤120字）
+    actor 只能是 "party_a"|"party_b"|"both"，不要写实际人名/公司名。
+    action 用动宾短语，≤30字，例如"递交审贷资料"、"交付车位"、"支付定金"。
+    deadline 是 ISO 'YYYY-MM-DD'；原文为"签订本协议当日"/"30 日内"等相对时间无法换算时填 null。
+    宁缺毋滥：抽不出动作不要硬凑；典型合同 obligations 5-15 条为正常。
+
+JSON 字段定义：
+{
+  "contract_name": "合同名称",
+  "party_a": "甲方全称",
+  "party_b": "乙方全称（如有多人/多主体用顿号分隔）",
+  "amount": "合同金额原文",
+  "sign_date": "签订日期 ISO 8601 或 null",
+  "expire_date": "到期/终止日期 ISO 8601 或 null",
+  "auto_renewal": true/false/null,
+  "risk_clauses": ["违约金/赔偿/解除/争议解决等罚则", "..."],
+  "obligations": [
+    {
+      "actor": "party_a"|"party_b"|"both",
+      "action": "动宾短语",
+      "deadline": "YYYY-MM-DD 或 null",
+      "evidence": "原文片段"
+    }
+  ]
+}
+"""
+
+
+def call_llm_extract(
+    document_text: str,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    max_chars: int = 24000,
+) -> LlmResult:
+    """
+    调用 DashScope LLM（OpenAI 兼容口）进行合同字段抽取。
+
+    见 CLAUDE.md：DashScope 一律走 OpenAI 兼容接口（原生 Generation 不认部分模型 id）。
+    :param document_text: 已 OCR 得到的合同全文（推荐用 markdown 版本）
+    :param model: 默认从 DASHSCOPE_LLM_MODEL env 读，最终默认 qwen3.7-max
+    :param max_chars: 截断阈值，避免超过模型上下文
+    :return: LlmResult（parsed/model/usage）；失败时 parsed={}，调用方判 `if not res.parsed`
+    """
+    # 统一从 config 层取（env > 配置文件 > 默认）；显式传参仍优先（param or settings）。
+    settings = load_settings()
+    model = model or settings.dashscope_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 LLM extraction")
+        return LlmResult(
+            parsed={}, model=model,
+            error=config_missing("DASHSCOPE_API_KEY 缺失，跳过 LLM 抽取"),
+        )
+
+    user_msg = f"以下是合同正文，请抽取字段：\n\n{_truncate_middle(document_text, max_chars)}"
+    try:
+        content, usage = _call_openai_compat(LLM_SYSTEM_PROMPT, user_msg, model, api_key, base_url)
+    except Exception as e:  # noqa: BLE001 — 外部调用降级返回空，但保留结构化 error 供上层判重试
+        logger.exception("DashScope LLM call failed: %s", e)
+        return LlmResult(parsed={}, model=model, error=classify_exception(e))
+
+    if not content:
+        logger.warning("LLM empty response")
+        return LlmResult(parsed={}, model=model, usage=usage)
+    parsed = _parse_json_loose(content)
+    if not parsed:
+        logger.warning("LLM response not parseable as JSON: %s", content[:200])
+    return LlmResult(parsed=parsed, model=model, usage=usage)
+
+
+def _truncate_middle(text: str, max_chars: int) -> str:
+    """超长则头 1/3 尾 2/3 截断——尾部承载签字/金额/到期日等关键信息，权重更高。"""
+    if len(text) <= max_chars:
+        return text
+    head = max_chars // 3
+    return text[:head] + "\n\n[...省略中段...]\n\n" + text[-(max_chars - head):]
+
+
+def _usage_from_openai(resp: Any) -> dict[str, Any] | None:
+    """OpenAI 兼容响应的 token 用量 → 归一化 input/output/total_tokens。读不到返回 None。"""
+    u = getattr(resp, "usage", None)
+    if u is None:
+        return None
+    out = {
+        "input_tokens": getattr(u, "prompt_tokens", None),
+        "output_tokens": getattr(u, "completion_tokens", None),
+        "total_tokens": getattr(u, "total_tokens", None),
+    }
+    return out if any(v is not None for v in out.values()) else None
+
+
+def _call_openai_compat(
+    system_prompt: str, user_content: str, model: str, api_key: str, base_url: str
+) -> tuple[str, dict[str, Any] | None]:
+    """
+    经 DashScope 的 OpenAI 兼容接口调文本模型，返回 (content, usage)。失败抛异常由调用方降级。
+
+    见 CLAUDE.md：DashScope 一律走兼容口（原生 Generation 不认部分模型 id，如 qwen3.6-flash）。
+    开 json_object；**不设 max_tokens**（避免 JSON 被截断成非法串）；各 prompt 已含 "JSON" 字样。
+
+    显式 timeout（默认 300s，DASHSCOPE_TIMEOUT_S 可调）：不设则吃 SDK 默认 ~600s，
+    上游 hang 时 CI/agent 会静默干等近 10 分钟。300s 给长合同（截断后约 6 万字，
+    且故意不设 max_tokens）留足头寸，又不至无界等待。超时异常由调用方 except 兜底降级。
+    """
+    from openai import OpenAI
+
+    compat_url = base_url.replace("/api/v1", "/compatible-mode/v1")
+    with sanitized_httpx_proxy_env():
+        client = OpenAI(
+            api_key=api_key, base_url=compat_url,
+            timeout=get_timeout_s("DASHSCOPE_TIMEOUT_S", 300.0),
+        )
+        resp = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=0.1,
+            top_p=0.5,
+            response_format={"type": "json_object"},
+        )
+    return (resp.choices[0].message.content or ""), _usage_from_openai(resp)
+
+
+def _parse_json_loose(text: str) -> dict[str, Any]:
+    """
+    LLM 偶尔会带 markdown 代码块或前缀文字，做一次 best-effort 解析。
+    """
+    text = text.strip()
+    if text.startswith("```"):
+        # 去掉 ```json ... ``` 包裹
+        text = re.sub(r"^```(?:json)?\s*", "", text)
+        text = re.sub(r"\s*```$", "", text)
+    # 抓第一个 {...} 块
+    m = re.search(r"\{[\s\S]*\}", text)
+    if not m:
+        return {}
+    try:
+        return json.loads(m.group(0))
+    except json.JSONDecodeError:
+        # 修一下常见问题：单引号 / trailing comma
+        repaired = m.group(0).replace("'", '"')
+        repaired = re.sub(r",\s*([}\]])", r"\1", repaired)
+        try:
+            return json.loads(repaired)
+        except json.JSONDecodeError:
+            return {}

contract_archive/extraction/normalize.py

@@ -0,0 +1,210 @@
+"""
+确定性数值/结构归一化工具。
+
+这是项目里**唯一保留的"死代码 rule"**——但它做的不是字段抽取，而是把 LLM
+吐出的原文值规整成可存储/可比较的形态（中文大写金额→数值、日期→ISO、
+LLM 数组→强类型对象）。LLM 在精确数值/日期换算上不可靠，这类确定性转换
+交给代码更稳。字段"抽什么"全归 LLM。
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..schemas import ObligationItem
+
+
+# ---------- 日期 ----------
+
+
+def normalize_date(value: str | None) -> str | None:
+    """把原文日期粗糙归一化到 ISO 8601。失败原样返回。"""
+    if not value:
+        return None
+    # 兼容 OCR 输出里数字与"年/月"之间出现的空格
+    m = re.match(
+        r"^((?:19|20)\d{2}|二[〇零]{1,3}[一二三四五六七八九十]{1,3})"
+        r"\s*[年\-./]\s*(\d{1,2}|[一二三四五六七八九十]{1,3})"
+        r"\s*[月\-./]\s*(\d{1,2}|[一二三四五六七八九十]{1,3})",
+        value,
+    )
+    if not m:
+        return value
+    y, mo, d = m.group(1), m.group(2), m.group(3)
+    if not y.isdigit():
+        y = _cn_year_to_int(y)
+    if not mo.isdigit():
+        mo = _cn_num_to_int(mo)
+    if not d.isdigit():
+        d = _cn_num_to_int(d)
+    try:
+        return f"{int(y):04d}-{int(mo):02d}-{int(d):02d}"
+    except (ValueError, TypeError):
+        return value
+
+
+_CN_DIGITS = {"〇": 0, "零": 0, "一": 1, "二": 2, "三": 3, "四": 4, "五": 5,
+              "六": 6, "七": 7, "八": 8, "九": 9, "十": 10}
+
+
+def _cn_year_to_int(s: str) -> str:
+    digits = [str(_CN_DIGITS.get(ch, "")) for ch in s if ch in _CN_DIGITS]
+    return "".join(digits) or s
+
+
+def _cn_num_to_int(s: str) -> str:
+    if "十" in s:
+        parts = s.split("十")
+        tens = _CN_DIGITS.get(parts[0], 1) if parts[0] else 1
+        ones = _CN_DIGITS.get(parts[1], 0) if len(parts) > 1 and parts[1] else 0
+        return str(tens * 10 + ones)
+    return "".join(str(_CN_DIGITS.get(ch, "")) for ch in s) or s
+
+
+# ---------- 金额 ----------
+
+
+_CN_MONEY_DIGITS = {
+    "零": 0, "壹": 1, "贰": 2, "叁": 3, "肆": 4, "伍": 5,
+    "陆": 6, "柒": 7, "捌": 8, "玖": 9,
+    # 小写也支持（偶尔混用）
+    "一": 1, "二": 2, "三": 3, "四": 4, "五": 5,
+    "六": 6, "七": 7, "八": 8, "九": 9, "两": 2,
+}
+_CN_MONEY_UNITS = {
+    "拾": 10, "佰": 100, "仟": 1000, "万": 10000, "亿": 100000000,
+    "十": 10, "百": 100, "千": 1000,
+}
+
+
+def _cn_money_to_value(s: str) -> float | None:
+    """
+    中文大写金额 → 数值（元）。
+    "壹仟贰佰贰拾柒万玖仟捌佰捌拾玖元整" → 12279889.0
+    "陆拾贰万壹仟壹佰零陆元柒角壹分" → 621106.71
+    解析失败返回 None。
+    """
+    s = s.replace("人民币", "").replace("圆", "元").replace("整", "").strip()
+    if not s:
+        return None
+    # 小数部分：元后的 角(0.1) / 分(0.01)，如"…元柒角壹分" = .71
+    frac = 0.0
+    if "元" in s:
+        intpart, _, fracpart = s.partition("元")
+        for unit_ch, unit_val in (("角", 0.1), ("分", 0.01)):
+            idx = fracpart.find(unit_ch)
+            if idx >= 1:
+                d = _CN_MONEY_DIGITS.get(fracpart[idx - 1])
+                if d is not None:
+                    frac += d * unit_val
+        s = intpart
+    total = 0
+    section = 0   # 当前"万"以下的累加
+    digit = 0     # 上一个数字
+    saw_any = False
+    for ch in s:
+        if ch in _CN_MONEY_DIGITS:
+            digit = _CN_MONEY_DIGITS[ch]
+            saw_any = True
+        elif ch in _CN_MONEY_UNITS:
+            unit = _CN_MONEY_UNITS[ch]
+            if unit >= 10000:
+                # 万 / 亿 触发段结算
+                section = (section + digit) * unit
+                total += section
+                section = 0
+            else:
+                # 拾/佰/仟：digit 为 0 时按 1（"拾" 单独 = 10）
+                section += (digit if digit else 1) * unit
+            digit = 0
+            saw_any = True
+        elif ch.isspace():
+            continue
+        else:
+            return None  # 不认识的字符（含混阿拉伯/中文），交给阿拉伯路径
+    section += digit
+    total += section
+    result = float(total) + frac
+    return result if (saw_any or frac) and result > 0 else None
+
+
+def parse_money_value(value: str | None) -> float | None:
+    """从原文金额抽出数值（人民币元）。先试阿拉伯数字，再试中文大写。"""
+    if not value:
+        return None
+    # 阿拉伯数字优先（精度高，覆盖大多数情况）
+    m = re.search(r"([0-9]+(?:[,，]\d{3})*(?:\.\d+)?)\s*(万元|万|千元|百元|元|圆)?", value)
+    if m:
+        num = float(m.group(1).replace(",", "").replace("，", ""))
+        unit = m.group(2) or "元"
+        multiplier = {"万元": 10000, "万": 10000, "千元": 1000, "百元": 100,
+                      "元": 1, "圆": 1}.get(unit, 1)
+        return num * multiplier
+    # 退化到中文大写
+    return _cn_money_to_value(value)
+
+
+# ---------- LLM 数组 → 强类型 ----------
+
+
+def coerce_bool(value: Any) -> bool | None:
+    """LLM 的 auto_renewal 等布尔字段：兼容 true/false/是/否/null。"""
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return None
+    s = str(value).strip().lower()
+    if s in ("true", "是", "yes", "1"):
+        return True
+    if s in ("false", "否", "no", "0"):
+        return False
+    return None
+
+
+def coerce_str_list(value: Any, max_len: int = 200) -> list[str]:
+    """LLM 的字符串数组（如 risk_clauses）：过滤空项、截断。"""
+    if not isinstance(value, list):
+        return []
+    out: list[str] = []
+    for item in value:
+        s = str(item).strip() if item is not None else ""
+        if s:
+            out.append(s[:max_len])
+    return out
+
+
+def coerce_obligations(raw: Any) -> list[ObligationItem]:
+    """
+    把 LLM 返回的 obligations 数组（dict 列表）转 ObligationItem。
+    actor 兼容"甲方"/"乙方"中文别名；跳过缺 actor/action 的非法项，不抛异常。
+    """
+    if not isinstance(raw, list):
+        return []
+    actor_alias = {
+        "甲方": "party_a", "Party A": "party_a", "partyA": "party_a",
+        "乙方": "party_b", "Party B": "party_b", "partyB": "party_b",
+        "双方": "both", "Both": "both",
+    }
+    out: list[ObligationItem] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        actor = str(item.get("actor", "")).strip()
+        actor = actor_alias.get(actor, actor)
+        if actor not in ("party_a", "party_b", "both"):
+            continue
+        action = str(item.get("action", "")).strip()
+        if not action:
+            continue
+        deadline = item.get("deadline")
+        deadline = normalize_date(deadline) or None if isinstance(deadline, str) else None
+        evidence = str(item.get("evidence", "")).strip()[:500]
+        out.append(
+            ObligationItem(
+                actor=actor,  # type: ignore[arg-type]
+                action=action[:200],
+                deadline=deadline,
+                evidence=evidence,
+            )
+        )
+    return out

contract_archive/extraction/property_fee.py

@@ -0,0 +1,79 @@
+"""
+周期性费用的月度估算：纯确定性派生，不依赖 LLM 算术。
+
+为什么交给代码（同 amount_check.py 的哲学）：合同只给**单价**（物业服务费 2.25 元/月·㎡、
+服务费 4.55、能耗费 0.8），买受人真正关心的是"一个月实付多少钱"。LLM 照抄单价可靠，
+但让它把同量纲单价相加再乘建筑面积，既易算错又不可审计。算术与量纲判断交给代码，
+LLM 只负责抽出每项单价及其 unit。
+
+口径：
+  月物业费 ≈ Σ(按建筑面积计价的物业类单价，元/月·㎡) × 建筑面积
+  - **只并入「元/月·㎡」量纲**的项（unit 含 ㎡/平方米 且 含 月）；车位管理费"元/个/月"
+    量纲不同（应乘车位数而非建筑面积），不并入——混加是量纲错误。
+  - 建筑面积取「建筑面积/预测建筑面积」，**排除「套内/分摊」**——合同物业费明示按建筑面积计。
+
+产出"估算、供参考"——单价/面积任一抽不到即返回 (None, None)，不硬凑。
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from ..schemas import LabeledAmount, LabeledValue
+
+# 面积数值解析：从"286.92 平方米""286.92㎡"里取第一个数。
+_NUM_RE = re.compile(r"(\d+(?:\.\d+)?)")
+# 建筑面积标签里需排除的限定词——要的是「总建筑面积」，非套内/分摊。
+_AREA_EXCLUDE = ("套内", "分摊", "共有")
+
+
+def _is_per_sqm_month(unit: Optional[str]) -> bool:
+    """unit 是否为「元/月·㎡」量纲（按建筑面积、按月计的单价）。"""
+    u = unit or ""
+    has_sqm = "㎡" in u or "平方米" in u or "平米" in u or "m²" in u or "m2" in u.lower()
+    has_month = "月" in u
+    return has_sqm and has_month
+
+
+def _find_building_area(fields: list[LabeledValue]) -> Optional[float]:
+    """
+    从 fields 找建筑面积数值（㎡）。优先「预测建筑面积」或纯「建筑面积」，
+    排除「套内建筑面积/分摊共有建筑面积」（物业费按总建筑面积计）。抽不到返回 None。
+    """
+    candidates: list[tuple[str, float]] = []
+    for f in fields:
+        label = f.label or ""
+        if "建筑面积" in label and not any(x in label for x in _AREA_EXCLUDE):
+            m = _NUM_RE.search(f.value or "")
+            if m:
+                candidates.append((label, float(m.group(1))))
+    if not candidates:
+        return None
+    # 优先"预测建筑面积"/纯"建筑面积"，否则取首个候选。
+    for label, value in candidates:
+        if "预测" in label or label.strip() == "建筑面积":
+            return value
+    return candidates[0][1]
+
+
+def estimate_monthly_property_fee(
+    amounts: list[LabeledAmount], fields: list[LabeledValue]
+) -> tuple[Optional[float], Optional[str]]:
+    """
+    估算每月物业费 = Σ(按㎡·月计价的单价) × 建筑面积。
+
+    返回 (月费数值, 算式说明)；缺单价或缺建筑面积时返回 (None, None)。
+    算式说明 _text 保留各单价与面积，供人工翻回原文核对。
+    """
+    per_sqm = [a for a in amounts if a.value is not None and _is_per_sqm_month(a.unit)]
+    if not per_sqm:
+        return None, None
+    area = _find_building_area(fields)
+    if not area:
+        return None, None
+
+    unit_sum = round(sum(a.value for a in per_sqm if a.value is not None), 4)
+    monthly = round(unit_sum * area, 2)
+    parts = "＋".join(f"{a.label}{a.value:g}" for a in per_sqm)
+    text = f"（{parts}）={unit_sum:g}元/月·㎡ × {area:g}㎡ ≈ {monthly:,.2f}元/月"
+    return monthly, text