temporal-belief-graph 0.1.0__tar.gz

temporal_belief_graph-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+venv/
+.venv/
+*.egg

temporal_belief_graph-0.1.0/.old/bayesian.py

@@ -0,0 +1,210 @@
+"""
+bayesian.py
+-----------
+BayesianUpdater : evidence 가 누적될 때마다 BeliefEdge.p_forward 를 갱신한다.
+
+핵심 수식
+---------
+P(A→B | evidence) ∝ P(evidence | A→B) × P(A→B)
+
+likelihood 는 evidence 의 방향성(supports_forward)과
+소스 신뢰도 가중치(weight)로 결정한다.
+
+업데이트 방식
+-------------
+1. 단일 evidence  : update_edge()
+2. 복수 evidence  : update_edge_batch()
+3. 앙상블 통합    : ensemble_update()
+   - 여러 소스가 서로 다른 p_forward 를 주장할 때
+     가중 평균으로 통합한 뒤 베이즈 업데이트 1회 적용
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from .graph import BeliefGraph
+from .schema import BeliefEdge
+
+
+# ---------------------------------------------------------------------------
+# Evidence
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Evidence:
+    """
+    하나의 증거 단위.
+
+    Parameters
+    ----------
+    key : str
+        증거 식별자. (예: "corpus/event_chain.json#kain_001")
+    supports_forward : bool
+        True  → source → target 순서를 지지
+        False → target → source 순서를 지지
+    strength : float
+        증거의 강도. (0.0, 1.0] 범위.
+        1.0 = 완전히 확실한 증거, 0.1 = 매우 약한 힌트.
+    source : str
+        증거 출처 키. PriorConfig.source_weights 와 매핑된다.
+    """
+
+    key: str
+    supports_forward: bool
+    strength: float = 0.5
+    source: str = ""
+
+    def __post_init__(self):
+        if not (0.0 < self.strength <= 1.0):
+            raise ValueError(
+                f"Evidence.strength={self.strength} 는 (0, 1] 범위여야 합니다."
+            )
+        if not self.key:
+            raise ValueError("Evidence.key 는 빈 문자열일 수 없습니다.")
+
+
+# ---------------------------------------------------------------------------
+# BayesianUpdater
+# ---------------------------------------------------------------------------
+
+class BayesianUpdater:
+    """
+    Parameters
+    ----------
+    graph : BeliefGraph
+        업데이트 대상 그래프. 내부 엣지를 직접 수정한다.
+    clip : float
+        p_forward 의 최솟값/최댓값 클리핑. 기본 0.01.
+        확률이 0 또는 1 로 수렴해 버리는 것을 방지한다.
+    """
+
+    def __init__(self, graph: BeliefGraph, clip: float = 0.01):
+        if not (0.0 < clip < 0.5):
+            raise ValueError(
+                f"clip={clip} 는 (0, 0.5) 범위여야 합니다."
+            )
+        self.graph = graph
+        self.clip = clip
+
+    # ------------------------------------------------------------------
+    # 단일 업데이트
+    # ------------------------------------------------------------------
+
+    def update_edge(
+        self,
+        source_id: str,
+        target_id: str,
+        evidence: Evidence,
+    ) -> BeliefEdge:
+        """
+        단일 evidence 로 엣지 하나를 베이즈 업데이트한다.
+
+        Returns
+        -------
+        BeliefEdge
+            업데이트된 엣지 (그래프 내 객체를 직접 수정 후 반환).
+        """
+        edge = self.graph.get_edge(source_id, target_id)
+        source_weight = self.graph._config.source_weights.get(evidence.source, 1.0)
+
+        # likelihood 계산
+        # strength=0.1 → lf=0.55, lb=0.45 (약한 신호)
+        # strength=1.0 → lf=1.0,  lb=0.0  (강한 신호)
+        # source_weight 는 supports 방향 likelihood 에 스케일로 적용
+        base_lf = 0.5 + evidence.strength * 0.5
+        base_lb = 0.5 - evidence.strength * 0.5
+        if evidence.supports_forward:
+            lf = base_lf * source_weight
+            lb = base_lb
+        else:
+            lf = base_lb
+            lb = base_lf * source_weight
+
+        # 베이즈 업데이트
+        prior_f = edge.p_forward
+        prior_b = edge.p_backward
+
+        posterior_f_unnorm = lf * prior_f
+        posterior_b_unnorm = lb * prior_b
+        total = posterior_f_unnorm + posterior_b_unnorm
+
+        if total == 0:
+            return edge  # 업데이트 불가 (수치 안정성)
+
+        new_p = posterior_f_unnorm / total
+        edge.p_forward = max(self.clip, min(1.0 - self.clip, new_p))
+
+        # evidence key 누적
+        if evidence.key not in edge.evidence_keys:
+            edge.evidence_keys.append(evidence.key)
+
+        return edge
+
+    # ------------------------------------------------------------------
+    # 배치 업데이트
+    # ------------------------------------------------------------------
+
+    def update_edge_batch(
+        self,
+        source_id: str,
+        target_id: str,
+        evidences: list[Evidence],
+    ) -> BeliefEdge:
+        """
+        복수의 evidence 를 순서대로 적용한다.
+        각 evidence 가 이전 posterior 를 다음 prior 로 사용한다.
+        """
+        for ev in evidences:
+            self.update_edge(source_id, target_id, ev)
+        return self.graph.get_edge(source_id, target_id)
+
+    # ------------------------------------------------------------------
+    # 앙상블 업데이트
+    # ------------------------------------------------------------------
+
+    def ensemble_update(
+        self,
+        source_id: str,
+        target_id: str,
+        claims: list[tuple[float, float]],
+    ) -> BeliefEdge:
+        """
+        여러 소스의 p_forward 주장을 가중 평균으로 통합한 뒤
+        베이즈 업데이트 1회 적용한다.
+
+        Parameters
+        ----------
+        claims : list[tuple[float, float]]
+            (p_forward_주장, 소스_가중치) 쌍의 목록.
+            예: [(0.9, 1.5), (0.6, 0.8), (0.4, 1.0)]
+
+        Returns
+        -------
+        BeliefEdge
+            업데이트된 엣지.
+        """
+        if not claims:
+            raise ValueError("claims 가 비어 있습니다.")
+
+        for p, w in claims:
+            if not (0.0 <= p <= 1.0):
+                raise ValueError(f"claim p_forward={p} 는 [0, 1] 범위여야 합니다.")
+            if w <= 0:
+                raise ValueError(f"claim weight={w} 는 0 보다 커야 합니다.")
+
+        total_weight = sum(w for _, w in claims)
+        ensemble_p = sum(p * w for p, w in claims) / total_weight
+
+        # 앙상블 결과를 단일 evidence 로 변환해 베이즈 업데이트
+        # ensemble_p=0.5 (중립) → strength≈0 (prior 유지)
+        # ensemble_p=1.0 → strength=1.0 (강한 순방향)
+        supports_forward = ensemble_p >= 0.5
+        strength = abs(ensemble_p - 0.5) * 2.0   # [0, 1]
+        strength = max(0.01, min(1.0, strength))
+
+        ev = Evidence(
+            key=f"ensemble:{source_id}→{target_id}",
+            supports_forward=supports_forward,
+            strength=strength,
+            source="ensemble",
+        )
+        return self.update_edge(source_id, target_id, ev)

temporal_belief_graph-0.1.0/.old/graph.py

@@ -0,0 +1,147 @@
+"""
+graph.py
+--------
+BeliefGraph : 확률 엣지 기반 DAG 구조.
+
+- EventNode 를 노드로, BeliefEdge 를 엣지로 관리한다.
+- 엣지의 p_forward 는 이후 베이즈 업데이터(bayesian.py)가 갱신한다.
+- 이 파일은 구조(추가/조회/삭제)만 담당한다.
+"""
+
+from __future__ import annotations
+from typing import Optional
+from .schema import EventNode, BeliefEdge, PriorConfig
+
+
+class BeliefGraph:
+    """
+    확률 엣지 기반 방향 그래프.
+
+    Parameters
+    ----------
+    prior_config : PriorConfig
+        초기 조건. 생략하면 default PriorConfig() 사용.
+    """
+
+    def __init__(self, prior_config: Optional[PriorConfig] = None):
+        self._config: PriorConfig = prior_config or PriorConfig()
+        self._nodes: dict[str, EventNode] = {}
+        # (source_id, target_id) → BeliefEdge
+        self._edges: dict[tuple[str, str], BeliefEdge] = {}
+
+    # ------------------------------------------------------------------
+    # 노드
+    # ------------------------------------------------------------------
+
+    def add_node(self, node: EventNode) -> None:
+        """노드를 추가한다. 같은 id 가 이미 있으면 덮어쓴다."""
+        self._nodes[node.id] = node
+
+    def get_node(self, node_id: str) -> EventNode:
+        if node_id not in self._nodes:
+            raise KeyError(f"노드 '{node_id}' 가 그래프에 없습니다.")
+        return self._nodes[node_id]
+
+    def remove_node(self, node_id: str) -> None:
+        """노드와 해당 노드에 연결된 모든 엣지를 함께 제거한다."""
+        if node_id not in self._nodes:
+            raise KeyError(f"노드 '{node_id}' 가 그래프에 없습니다.")
+        del self._nodes[node_id]
+        to_remove = [
+            key for key in self._edges
+            if key[0] == node_id or key[1] == node_id
+        ]
+        for key in to_remove:
+            del self._edges[key]
+
+    @property
+    def nodes(self) -> list[EventNode]:
+        return list(self._nodes.values())
+
+    # ------------------------------------------------------------------
+    # 엣지
+    # ------------------------------------------------------------------
+
+    def add_edge(self, edge: BeliefEdge) -> None:
+        """
+        엣지를 추가한다.
+        - source/target 노드가 그래프에 없으면 KeyError.
+        - 같은 (source, target) 쌍이 이미 있으면 덮어쓴다.
+        """
+        if edge.source_id not in self._nodes:
+            raise KeyError(f"source 노드 '{edge.source_id}' 가 그래프에 없습니다.")
+        if edge.target_id not in self._nodes:
+            raise KeyError(f"target 노드 '{edge.target_id}' 가 그래프에 없습니다.")
+        self._edges[(edge.source_id, edge.target_id)] = edge
+
+    def get_edge(self, source_id: str, target_id: str) -> BeliefEdge:
+        key = (source_id, target_id)
+        if key not in self._edges:
+            raise KeyError(f"엣지 '{source_id} → {target_id}' 가 그래프에 없습니다.")
+        return self._edges[key]
+
+    def remove_edge(self, source_id: str, target_id: str) -> None:
+        key = (source_id, target_id)
+        if key not in self._edges:
+            raise KeyError(f"엣지 '{source_id} → {target_id}' 가 그래프에 없습니다.")
+        del self._edges[key]
+
+    @property
+    def edges(self) -> list[BeliefEdge]:
+        return list(self._edges.values())
+
+    # ------------------------------------------------------------------
+    # 조회 유틸
+    # ------------------------------------------------------------------
+
+    def successors(self, node_id: str) -> list[EventNode]:
+        """node_id 에서 출발하는 엣지의 target 노드 목록."""
+        return [
+            self._nodes[t]
+            for (s, t) in self._edges
+            if s == node_id and t in self._nodes
+        ]
+
+    def predecessors(self, node_id: str) -> list[EventNode]:
+        """node_id 로 들어오는 엣지의 source 노드 목록."""
+        return [
+            self._nodes[s]
+            for (s, t) in self._edges
+            if t == node_id and s in self._nodes
+        ]
+
+    def uncertain_edges(self) -> list[BeliefEdge]:
+        """p_forward 가 [0.4, 0.6] 인 불확실 엣지 목록."""
+        return [e for e in self._edges.values() if e.is_uncertain]
+
+    # ------------------------------------------------------------------
+    # 초기화 헬퍼
+    # ------------------------------------------------------------------
+
+    def init_uniform(self, source_id: str, target_id: str) -> BeliefEdge:
+        """
+        두 노드 사이에 uniform prior(p=0.5) 엣지를 생성하고 추가한다.
+        이미 엣지가 있으면 기존 엣지를 반환한다.
+        """
+        key = (source_id, target_id)
+        if key in self._edges:
+            return self._edges[key]
+        edge = BeliefEdge(
+            source_id=source_id,
+            target_id=target_id,
+            p_forward=self._config.default_p,
+        )
+        self.add_edge(edge)
+        return edge
+
+    # ------------------------------------------------------------------
+    # 표현
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return (
+            f"BeliefGraph("
+            f"nodes={len(self._nodes)}, "
+            f"edges={len(self._edges)}, "
+            f"uncertain={len(self.uncertain_edges())})"
+        )

temporal_belief_graph-0.1.0/.old/schema.py

@@ -0,0 +1,169 @@
+"""
+schema.py
+---------
+tbg의 기본 데이터 스키마.
+
+EventNode   : 이벤트 하나를 표현하는 노드
+BeliefEdge  : A → B 순서 관계의 확률을 담는 엣지
+PriorConfig : 사람이 처음 한 번만 설정하는 초기 조건
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# EventNode
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EventNode:
+    """
+    스토리/세계관에서 하나의 사건(이벤트)을 표현한다.
+
+    Parameters
+    ----------
+    id : str
+        고유 식별자. 영문 소문자 + 언더스코어 권장. (예: "kain_incident")
+    label : str
+        사람이 읽을 이름. (예: "카인 사건")
+    era : Optional[str]
+        이 노드가 속한 시대/구간 이름.
+        None 이면 era 미지정 상태 → validator 가 경고.
+    description : str
+        사건에 대한 자유 텍스트 설명.
+    sources : list[str]
+        이 사건을 뒷받침하는 소스 키 목록.
+        (예: ["corpus/event_chain.json#001"])
+    """
+
+    id: str
+    label: str
+    era: Optional[str] = None
+    description: str = ""
+    sources: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.id:
+            raise ValueError("EventNode.id 는 빈 문자열일 수 없습니다.")
+        if not self.label:
+            raise ValueError("EventNode.label 은 빈 문자열일 수 없습니다.")
+        # pseudo era 금지 목록 (validator 에서도 재검사, 여기서는 즉시 차단)
+        _PSEUDO = {"현재", "과거", "미래", "언젠가", "나중에", "예전에"}
+        if self.era in _PSEUDO:
+            raise ValueError(
+                f"EventNode.era='{self.era}' 는 pseudo era 입니다. "
+                "구체적인 사건명/시대명을 사용하세요."
+            )
+
+
+# ---------------------------------------------------------------------------
+# BeliefEdge
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BeliefEdge:
+    """
+    두 EventNode 사이의 순서 관계를 확률로 표현하는 엣지.
+
+    'source → target' 순서일 확률을 p_forward 로 저장한다.
+    p_forward = 0.5  → 순서를 모른다 (uniform prior)
+    p_forward = 1.0  → source 가 반드시 먼저
+    p_forward = 0.0  → target 이 반드시 먼저
+
+    Parameters
+    ----------
+    source_id : str
+        선행 이벤트 후보 노드 id.
+    target_id : str
+        후행 이벤트 후보 노드 id.
+    p_forward : float
+        P(source → target). 0.0 이상 1.0 이하.
+    evidence_keys : list[str]
+        이 엣지의 확률을 뒷받침하는 증거 키 목록.
+    weight : float
+        앙상블에서 이 엣지 소스의 신뢰도 가중치. 기본 1.0.
+    """
+
+    source_id: str
+    target_id: str
+    p_forward: float = 0.5
+    evidence_keys: list[str] = field(default_factory=list)
+    weight: float = 1.0
+
+    def __post_init__(self):
+        if not (0.0 <= self.p_forward <= 1.0):
+            raise ValueError(
+                f"BeliefEdge.p_forward={self.p_forward} 는 [0, 1] 범위여야 합니다."
+            )
+        if self.weight <= 0:
+            raise ValueError(
+                f"BeliefEdge.weight={self.weight} 는 0 보다 커야 합니다."
+            )
+        if self.source_id == self.target_id:
+            raise ValueError(
+                "BeliefEdge 의 source_id 와 target_id 는 같을 수 없습니다. "
+                "(self-loop 금지)"
+            )
+
+    @property
+    def p_backward(self) -> float:
+        """P(target → source) = 1 - p_forward"""
+        return 1.0 - self.p_forward
+
+    @property
+    def is_uncertain(self) -> bool:
+        """p_forward 가 [0.4, 0.6] 구간이면 '불확실' 상태로 간주."""
+        return 0.4 <= self.p_forward <= 0.6
+
+
+# ---------------------------------------------------------------------------
+# PriorConfig
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PriorConfig:
+    """
+    사람이 처음 한 번만 설정하는 초기 조건 스키마.
+
+    이후 evidence 가 누적되면 BeliefEdge.p_forward 가 자동 갱신되므로
+    PriorConfig 는 '시작점'만 정의한다.
+
+    Parameters
+    ----------
+    default_p : float
+        아무 정보 없을 때 기본 prior. 보통 0.5 (uniform).
+    source_weights : dict[str, float]
+        소스별 초기 신뢰도 가중치.
+        (예: {"corpus/event_chain.json": 1.5, "fan_wiki": 0.7})
+    pseudo_era_list : list[str]
+        추가로 막을 pseudo era 키워드. 기본 목록에 합산된다.
+    """
+
+    default_p: float = 0.5
+    source_weights: dict[str, float] = field(default_factory=dict)
+    pseudo_era_list: list[str] = field(default_factory=list)
+
+    # 기본 pseudo era 목록 (EventNode.__post_init__ 과 동일하게 유지)
+    _BASE_PSEUDO: list[str] = field(
+        default_factory=lambda: ["현재", "과거", "미래", "언젠가", "나중에", "예전에"],
+        init=False,
+        repr=False,
+    )
+
+    def __post_init__(self):
+        if not (0.0 < self.default_p < 1.0):
+            raise ValueError(
+                f"PriorConfig.default_p={self.default_p} 는 (0, 1) 열린 구간이어야 합니다."
+            )
+        for src, w in self.source_weights.items():
+            if w <= 0:
+                raise ValueError(
+                    f"source_weights['{src}']={w} 는 0 보다 커야 합니다."
+                )
+
+    @property
+    def all_pseudo_eras(self) -> list[str]:
+        """기본 목록 + 사용자 추가 목록을 합친 전체 pseudo era 목록."""
+        return list(set(self._BASE_PSEUDO + self.pseudo_era_list))

temporal_belief_graph-0.1.0/.old/validator.py

@@ -0,0 +1,149 @@
+"""
+validator.py
+------------
+Validator : BeliefGraph 의 유효성을 검사한다.
+
+검사 항목
+1. pseudo era 탐지   - EventNode.era 가 금지 키워드면 오류
+2. era 미지정 탐지   - EventNode.era 가 None 이면 경고
+3. 사이클 탐지       - p_forward > threshold 인 엣지만 확정 엣지로 보고
+                       DFS 로 사이클 존재 여부를 확인한다
+4. 고립 노드 탐지    - 엣지가 하나도 없는 노드 목록 반환
+
+ValidationResult 로 결과를 돌려주며 예외를 던지지 않는다.
+예외가 필요한 경우 .raise_if_errors() 를 호출한다.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from .graph import BeliefGraph
+
+
+# ---------------------------------------------------------------------------
+# 결과 컨테이너
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ValidationResult:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.errors) == 0
+
+    def raise_if_errors(self) -> None:
+        if self.errors:
+            msg = "\n".join(self.errors)
+            raise ValueError(f"BeliefGraph 유효성 오류:\n{msg}")
+
+    def __repr__(self) -> str:
+        return (
+            f"ValidationResult("
+            f"errors={len(self.errors)}, "
+            f"warnings={len(self.warnings)}, "
+            f"valid={self.is_valid})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Validator
+# ---------------------------------------------------------------------------
+
+class Validator:
+    """
+    Parameters
+    ----------
+    cycle_threshold : float
+        이 값보다 p_forward 가 크면 '확정 엣지'로 간주하고 사이클을 탐지한다.
+        기본 0.5 (불확실 엣지는 사이클 탐지에서 제외).
+    """
+
+    def __init__(self, cycle_threshold: float = 0.5):
+        if not (0.0 < cycle_threshold < 1.0):
+            raise ValueError(
+                f"cycle_threshold={cycle_threshold} 는 (0, 1) 범위여야 합니다."
+            )
+        self.cycle_threshold = cycle_threshold
+
+    # ------------------------------------------------------------------
+    # 퍼블릭 API
+    # ------------------------------------------------------------------
+
+    def validate(self, graph: BeliefGraph) -> ValidationResult:
+        """그래프 전체를 검사하고 ValidationResult 를 반환한다."""
+        result = ValidationResult()
+        self._check_pseudo_era(graph, result)
+        self._check_missing_era(graph, result)
+        self._check_cycles(graph, result)
+        self._check_isolated_nodes(graph, result)
+        return result
+
+    # ------------------------------------------------------------------
+    # 개별 검사
+    # ------------------------------------------------------------------
+
+    def _check_pseudo_era(self, graph: BeliefGraph, result: ValidationResult) -> None:
+        pseudo_set = set(graph._config.all_pseudo_eras)
+        for node in graph.nodes:
+            if node.era in pseudo_set:
+                result.errors.append(
+                    f"[pseudo_era] 노드 '{node.id}' 의 era='{node.era}' 는 "
+                    "금지된 pseudo era 입니다."
+                )
+
+    def _check_missing_era(self, graph: BeliefGraph, result: ValidationResult) -> None:
+        for node in graph.nodes:
+            if node.era is None:
+                result.warnings.append(
+                    f"[missing_era] 노드 '{node.id}' 에 era 가 설정되지 않았습니다."
+                )
+
+    def _check_cycles(self, graph: BeliefGraph, result: ValidationResult) -> None:
+        """
+        p_forward > cycle_threshold 인 엣지만 '확정 방향'으로 보고
+        DFS 로 사이클을 탐지한다.
+        """
+        # 인접 리스트 구성
+        adj: dict[str, list[str]] = {node.id: [] for node in graph.nodes}
+        for edge in graph.edges:
+            if edge.p_forward > self.cycle_threshold:
+                adj[edge.source_id].append(edge.target_id)
+
+        # DFS 상태: 0=미방문, 1=방문중, 2=완료
+        state: dict[str, int] = {node_id: 0 for node_id in adj}
+        cycle_path: list[str] = []
+
+        def dfs(node_id: str) -> bool:
+            state[node_id] = 1
+            cycle_path.append(node_id)
+            for neighbor in adj[node_id]:
+                if state[neighbor] == 1:
+                    # 사이클 발견 - 경로 추출
+                    idx = cycle_path.index(neighbor)
+                    cycle = cycle_path[idx:] + [neighbor]
+                    result.errors.append(
+                        f"[cycle] 사이클 탐지: {' → '.join(cycle)}"
+                    )
+                    return True
+                if state[neighbor] == 0:
+                    if dfs(neighbor):
+                        return True
+            cycle_path.pop()
+            state[node_id] = 2
+            return False
+
+        for node_id in adj:
+            if state[node_id] == 0:
+                dfs(node_id)
+
+    def _check_isolated_nodes(self, graph: BeliefGraph, result: ValidationResult) -> None:
+        connected = set()
+        for edge in graph.edges:
+            connected.add(edge.source_id)
+            connected.add(edge.target_id)
+        for node in graph.nodes:
+            if node.id not in connected:
+                result.warnings.append(
+                    f"[isolated] 노드 '{node.id}' 는 연결된 엣지가 없습니다."
+                )