知识建模：实体、事实、推断

from dataclasses import dataclass, field
from typing import Literal
from datetime import date
@dataclass
class Entity:
    """实体层：解决「说的是同一个东西吗」"""
    id: str
    canonical: str                       # 标准名
    aliases: list[str] = field(default_factory=list)
    kind: Literal["region", "metric", "org", "project", "system"] = "region"
    parent: str | None = None            # 上级实体，用于层级聚合
    attrs: dict = field(default_factory=dict)
    def match(self, mention: str) -> bool:
        m = mention.strip().lower()
        return m == self.canonical.lower() or any(m == a.lower() for a in self.aliases)
@dataclass
class Fact:
    """
    事实层：可溯源的关系与数值。
    三个字段缺一不可 —— 缺来源则不可信，缺口径版本则不可比，缺时间则不知时效。
    """
    id: str
    subject: str                         # 实体 id
    predicate: str                       # 关系/指标名：指标=转化率
    value: str                           # 值
    period: str                          # 期：2025Q3
    source: str                          # 来源系统：bi.sales.daily_agg
    caliber_version: str                 # 口径版本：v3  ← 最容易被漏掉的一个
    updated_at: str                      # 更新时间
    dims: dict = field(default_factory=dict)   # 附加维度：{"客群": "新客"}
    def comparable_with(self, other: "Fact") -> bool:
        """两个事实能不能直接比较：同指标、同口径版本、同维度才可比"""
        return (self.predicate == other.predicate
                and self.caliber_version == other.caliber_version
                and self.dims == other.dims)
    def render(self) -> str:
        dims = "·".join(f"{k}={v}" for k, v in self.dims.items())
        return (f"{self.subject} {self.predicate} {self.value}"
                f"（{self.period}{'·' + dims if dims else ''}）"
                f"　[来源 {self.source}｜口径 {self.caliber_version}｜更新 {self.updated_at}]")
@dataclass
class Inference:
    """推断层：必须带依据链，且永远不能替代事实"""
    id: str
    conclusion: str
    based_on: list[str]                  # 依据：事实 id 列表 —— 没有它就不允许存在
    producer: str                        # 谁产出的：人 / 模型 + 版本
    produced_at: str
    confidence: float = 0.7
    def is_valid(self) -> bool:
        return len(self.based_on) > 0 and 0.0 <= self.confidence <= 1.0
    def render(self) -> str:
        return (f"[推断·{self.confidence:.1f}] {self.conclusion}\n"
                f"  依据：{', '.join(self.based_on) or '（缺失，不应展示）'}\n"
                f"  产出：{self.producer}　{self.produced_at}")
def resolve_conflict(a: Fact, b: Fact) -> tuple[Fact | None, str]:
    """
    两层之间的冲突消解原则。
    返回 (应采用的事实, 说明)。选择 None 表示无法裁决，应暴露冲突。
    """
    if a.predicate != b.predicate:
        return None, "两个事实不是同一指标，不可比较，不应裁决"
    # 口径版本不同 → 不可比，必须显式暴露
    if a.caliber_version != b.caliber_version:
        return None, (f"口径版本不同（{a.caliber_version} vs {b.caliber_version}），"
                      f"数值不可直接比较。请确认应使用哪个口径。")
    # 口径相同、期相同、值不同 → 数据源冲突
    if a.period == b.period and a.value != b.value:
        return None, (f"同期同口径出现两个值（{a.value} vs {b.value}），"
                      f"来源分别为 {a.source} / {b.source}，需要人工确认以哪个为准。")
    # 期不同 → 取更新的
    newer, older = (a, b) if a.updated_at > b.updated_at else (b, a)
    return newer, f"取更新的一条（{newer.updated_at} > {older.updated_at}），旧值保留为历史"
def render_for_prompt(facts: list[Fact], inferences: list[Inference],
                      budget_chars: int = 5000) -> str:
    """
    回喂给模型的形态：事实在前、推断在后，推断必须带依据，
    并且整体带「来源/口径/更新」标签 —— 让模型自己判断该信谁。
    """
    blocks = []
    for f in facts:
        blocks.append(f"[事实] {f.render()}")
    for i in inferences:
        if i.is_valid():                 # 无效推断（无依据链）直接不展示
            blocks.append(f"{i.render()}")
    text, used = [], 0
    for b in blocks:
        if used + len(b) > budget_chars:
            break
        text.append(b)
        used += len(b)
    head = ("以下为可核验材料。【事实】可直接作为结论依据；"
            "【推断】仅代表某一时期的分析观点，需判断其依据是否仍然成立。\n\n")
    return head + "\n\n".join(text)