rootmemory 0.1.0__py3-none-any.whl

rootmemory/services/belief_service.py

@@ -0,0 +1,161 @@
+"""BeliefService: creating beliefs, always with provenance.
+
+The invariants from spec section 16 are enforced here, at the only place where
+beliefs enter the system:
+
+    * every belief has at least one causal parent
+    * every parent must already exist
+    * a belief may never become its own ancestor
+    * beliefs start private; only the promotion gate makes them shared
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from sqlalchemy.orm import Session
+
+from rootmemory.errors import (
+    NodeNotFoundError,
+    ProvenanceCycleError,
+    ProvenanceRequiredError,
+)
+from rootmemory.models.belief import Belief
+from rootmemory.models.enums import EdgeType, EpistemicStatus, NodeType, Visibility
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.repositories.agent_repo import AgentRepository
+from rootmemory.repositories.belief_repo import BeliefRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.edge_repo import EdgeRepository
+from rootmemory.services.normalization_service import ClaimNormalizer, build_normalizer
+from rootmemory.services.provenance_service import ProvenanceService
+
+#: Node types a belief is allowed to be derived from in V1 (spec section 16).
+ALLOWED_PARENT_TYPES: frozenset[NodeType] = frozenset({NodeType.OBSERVATION, NodeType.BELIEF})
+
+
+@dataclass(frozen=True, slots=True)
+class ParentSpec:
+    """A requested causal parent for a new belief."""
+
+    id: uuid.UUID
+    type: NodeType
+
+    def as_ref(self) -> NodeRef:
+        return NodeRef(self.id, self.type)
+
+
+class BeliefService:
+    def __init__(self, session: Session, normalizer: ClaimNormalizer | None = None) -> None:
+        self.session = session
+        self.beliefs = BeliefRepository(session)
+        self.agents = AgentRepository(session)
+        self.edges = EdgeRepository(session)
+        self.claims = ClaimRepository(session)
+        self.provenance = ProvenanceService(session)
+        self._normalizer = normalizer
+
+    @property
+    def normalizer(self) -> ClaimNormalizer:
+        """Built lazily so configuration is read at use, not at import."""
+        if self._normalizer is None:
+            self._normalizer = build_normalizer()
+        return self._normalizer
+
+    def resolve_claim_key(self, claim_text: str) -> str:
+        """Work out which proposition a belief is about.
+
+        Only reached when the caller did not supply a key. The normalizer sees
+        the keys already in use so it can file the belief alongside them
+        instead of starting a new claim for every rephrasing.
+        """
+        existing = [claim.claim_key for claim in self.claims.list()]
+        return self.normalizer.normalize(claim_text, existing)
+
+    def create_belief(
+        self,
+        agent_id: uuid.UUID,
+        claim_text: str,
+        normalized_claim_key: str | None,
+        confidence: float,
+        parents: Sequence[ParentSpec],
+        epistemic_status: EpistemicStatus = EpistemicStatus.INFERRED,
+        llm_generated: bool = False,
+        meta: dict | None = None,
+    ) -> Belief:
+        """Create a belief and wire it to the evidence it came from.
+
+        Raises ProvenanceRequiredError when no parent is supplied, so a belief
+        with no traceable origin can never exist in the first place.
+        """
+        claim_key = normalized_claim_key or self.resolve_claim_key(claim_text)
+        if not parents:
+            raise ProvenanceRequiredError(
+                "a belief must cite at least one observation or belief it was derived from"
+            )
+        if self.agents.get(agent_id) is None:
+            raise NodeNotFoundError(f"agent {agent_id} does not exist")
+
+        for parent in parents:
+            if parent.type not in ALLOWED_PARENT_TYPES:
+                raise ProvenanceRequiredError(
+                    f"a belief may only be derived from {sorted(ALLOWED_PARENT_TYPES)}, "
+                    f"got {parent.type}"
+                )
+            if not self.provenance.node_exists(parent.as_ref()):
+                raise NodeNotFoundError(f"parent {parent.type}:{parent.id} does not exist")
+
+        belief = self.beliefs.create(
+            agent_id=agent_id,
+            claim_text=claim_text,
+            normalized_claim_key=claim_key,
+            confidence=confidence,
+            epistemic_status=epistemic_status,
+            visibility=Visibility.PRIVATE,
+            llm_generated=llm_generated,
+            meta=meta or {},
+        )
+
+        for parent in parents:
+            self.add_parent(belief.id, parent)
+
+        return belief
+
+    def add_parent(self, belief_id: uuid.UUID, parent: ParentSpec) -> None:
+        """Attach one causal parent to an existing belief, refusing cycles."""
+        child = NodeRef.belief(belief_id)
+        parent_ref = parent.as_ref()
+
+        if self.provenance.would_create_cycle(child, parent_ref):
+            raise ProvenanceCycleError(
+                f"edge {child} -> {parent_ref} would make the node its own ancestor"
+            )
+        if self.edges.exists(child, parent_ref, EdgeType.DERIVED_FROM):
+            return
+        self.edges.create(child, parent_ref, EdgeType.DERIVED_FROM)
+
+    def submit_for_promotion(self, belief_id: uuid.UUID) -> Belief:
+        """Move a private belief to candidate_shared (spec section 29).
+
+        This is as far as an agent can push its own belief; only the promotion
+        gate can take it further.
+        """
+        belief = self._require(belief_id)
+        if belief.visibility == Visibility.PRIVATE:
+            belief.visibility = str(Visibility.CANDIDATE_SHARED)
+            self.session.flush()
+        return belief
+
+    def set_epistemic_status(self, belief_id: uuid.UUID, status: EpistemicStatus) -> Belief:
+        belief = self._require(belief_id)
+        belief.epistemic_status = str(status)
+        self.session.flush()
+        return belief
+
+    def _require(self, belief_id: uuid.UUID) -> Belief:
+        belief = self.beliefs.get(belief_id)
+        if belief is None:
+            raise NodeNotFoundError(f"belief {belief_id} does not exist")
+        return belief

rootmemory/services/contradiction_service.py

@@ -0,0 +1,148 @@
+"""ContradictionService: attaching beliefs to claims, and reading claims back.
+
+Two rules from the spec live here:
+
+  * A contradiction never deletes the belief it argues with. Both sides are
+    stored, both sides are reported (spec section 23).
+  * Agents never receive a bare "X is true". They receive the claim together
+    with how much independent evidence stands on each side (spec section 49).
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from sqlalchemy.orm import Session
+
+from rootmemory.errors import NodeNotFoundError, RootMemoryError
+from rootmemory.models.claim import Claim
+from rootmemory.models.enums import ClaimStatus, EdgeType, LinkRole
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.repositories.belief_repo import BeliefRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.edge_repo import EdgeRepository
+from rootmemory.services.independence_service import IndependenceReport, IndependenceService
+
+
+@dataclass(slots=True)
+class ClaimContext:
+    """Everything an agent needs to reason about a claim honestly."""
+
+    claim: Claim
+    support: IndependenceReport
+    contradiction: IndependenceReport
+
+    @property
+    def is_disputed(self) -> bool:
+        return self.contradiction.belief_count > 0
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "claim_id": str(self.claim.id),
+            "claim_key": self.claim.claim_key,
+            "claim": self.claim.canonical_text,
+            "status": self.claim.status,
+            "support": {
+                "belief_count": self.support.belief_count,
+                "agreeing_agents": self.support.agreeing_agent_count,
+                "independent_sources": self.support.independent_source_count,
+                "confidence": self.support.aggregate_confidence,
+                "naive_average_confidence": self.support.naive_confidence,
+                "root_observation_ids": [str(o) for o in self.support.root_observation_ids],
+            },
+            "contradictions": {
+                "belief_count": self.contradiction.belief_count,
+                "agreeing_agents": self.contradiction.agreeing_agent_count,
+                "independent_sources": self.contradiction.independent_source_count,
+                "confidence": self.contradiction.aggregate_confidence,
+                "root_observation_ids": [str(o) for o in self.contradiction.root_observation_ids],
+            },
+        }
+
+
+class ContradictionService:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+        self.claims = ClaimRepository(session)
+        self.beliefs = BeliefRepository(session)
+        self.edges = EdgeRepository(session)
+        self.independence = IndependenceService(session)
+
+    # ------------------------------------------------------------------
+    # attaching beliefs
+    # ------------------------------------------------------------------
+
+    def register_support(self, claim_id: uuid.UUID, belief_id: uuid.UUID) -> None:
+        self._link(claim_id, belief_id, LinkRole.SUPPORTS, EdgeType.SUPPORTS)
+
+    def register_contradiction(self, claim_id: uuid.UUID, belief_id: uuid.UUID) -> None:
+        self._link(claim_id, belief_id, LinkRole.CONTRADICTS, EdgeType.CONTRADICTS)
+
+    def _link(
+        self,
+        claim_id: uuid.UUID,
+        belief_id: uuid.UUID,
+        role: LinkRole,
+        edge_type: EdgeType,
+    ) -> None:
+        claim = self.claims.get(claim_id)
+        if claim is None:
+            raise NodeNotFoundError(f"claim {claim_id} does not exist")
+        if self.beliefs.get(belief_id) is None:
+            raise NodeNotFoundError(f"belief {belief_id} does not exist")
+
+        opposite = LinkRole.CONTRADICTS if role == LinkRole.SUPPORTS else LinkRole.SUPPORTS
+        already = {b.id for b in self.claims.beliefs_for_claim(claim_id, opposite)}
+        if belief_id in already:
+            raise RootMemoryError(
+                f"belief {belief_id} is already registered as {opposite} on this claim"
+            )
+
+        self.claims.link_belief(claim_id, belief_id, role)
+        # The link table drives the services; the edge is the audit trail.
+        source, target = NodeRef.belief(belief_id), NodeRef.claim(claim_id)
+        if not self.edges.exists(source, target, edge_type):
+            self.edges.create(source, target, edge_type)
+
+    # ------------------------------------------------------------------
+    # reading claims
+    # ------------------------------------------------------------------
+
+    def build_context(self, claim_id: uuid.UUID) -> ClaimContext:
+        """Independence analysis of both sides of a claim."""
+        claim = self.claims.get(claim_id)
+        if claim is None:
+            raise NodeNotFoundError(f"claim {claim_id} does not exist")
+
+        supporting = self.claims.beliefs_for_claim(claim_id, LinkRole.SUPPORTS)
+        contradicting = self.claims.beliefs_for_claim(claim_id, LinkRole.CONTRADICTS)
+        return ClaimContext(
+            claim=claim,
+            support=self.independence.analyze(supporting),
+            contradiction=self.independence.analyze(contradicting),
+        )
+
+    def sync_claim_metrics(self, context: ClaimContext) -> Claim:
+        """Write the independence numbers back onto the claim row.
+
+        Claim *status* is deliberately not set here - only the PromotionService
+        may move a claim into or out of confirmed (spec section 46).
+        """
+        claim = context.claim
+        claim.independent_support_count = context.support.independent_source_count
+        claim.independent_contradiction_count = context.contradiction.independent_source_count
+        claim.confidence = context.support.aggregate_confidence
+        self.session.flush()
+        return claim
+
+    def unresolved_contradictions(self, context: ClaimContext, threshold: float) -> list[uuid.UUID]:
+        """Contradicting beliefs strong enough to block promotion.
+
+        Retracted beliefs are already filtered out by the independence report.
+        """
+        beliefs = self.beliefs.get_many(context.contradiction.belief_ids)
+        return [b.id for b in beliefs if b.confidence >= threshold]
+
+    def mark_contradicted(self, claim: Claim) -> Claim:
+        return self.claims.set_status(claim, ClaimStatus.CONTRADICTED)

rootmemory/services/decision_service.py

@@ -0,0 +1,65 @@
+"""DecisionService: downstream actions and the claims they rest on.
+
+A decision is the point where memory turns into consequence, so its
+dependencies are recorded twice on purpose: in ``decision_dependencies`` for
+fast lookup, and as ``depends_on`` provenance edges so a decision is reachable
+by the same graph traversal as everything else.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy.orm import Session
+
+from rootmemory.errors import NodeNotFoundError
+from rootmemory.models.decision import Decision
+from rootmemory.models.enums import DecisionStatus, EdgeType
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.repositories.agent_repo import AgentRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.decision_repo import DecisionRepository
+from rootmemory.repositories.edge_repo import EdgeRepository
+
+
+class DecisionService:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+        self.decisions = DecisionRepository(session)
+        self.claims = ClaimRepository(session)
+        self.agents = AgentRepository(session)
+        self.edges = EdgeRepository(session)
+
+    def create_decision(
+        self,
+        agent_id: uuid.UUID,
+        decision_type: str,
+        content: str,
+        claim_ids: Sequence[uuid.UUID] = (),
+        meta: dict | None = None,
+    ) -> Decision:
+        if self.agents.get(agent_id) is None:
+            raise NodeNotFoundError(f"agent {agent_id} does not exist")
+
+        decision = self.decisions.create(
+            agent_id=agent_id, decision_type=decision_type, content=content, meta=meta or {}
+        )
+        for claim_id in claim_ids:
+            self.add_dependency(decision.id, claim_id)
+        return decision
+
+    def add_dependency(self, decision_id: uuid.UUID, claim_id: uuid.UUID) -> None:
+        if self.claims.get(claim_id) is None:
+            raise NodeNotFoundError(f"claim {claim_id} does not exist")
+        self.decisions.add_dependency(decision_id, claim_id)
+        source = NodeRef.decision(decision_id)
+        target = NodeRef.claim(claim_id)
+        if not self.edges.exists(source, target, EdgeType.DEPENDS_ON):
+            self.edges.create(source, target, EdgeType.DEPENDS_ON)
+
+    def set_status(self, decision_id: uuid.UUID, status: DecisionStatus) -> Decision:
+        decision = self.decisions.get(decision_id)
+        if decision is None:
+            raise NodeNotFoundError(f"decision {decision_id} does not exist")
+        return self.decisions.set_status(decision, status)

rootmemory/services/graph_service.py

@@ -0,0 +1,316 @@
+"""GraphService: one snapshot of the whole memory, shaped for drawing.
+
+The portal needs the entire graph in a single call, with each node already
+carrying the numbers that matter: what a belief rests on, and how much of a
+claim's support is genuinely independent.
+
+Layout depth is computed here rather than in the browser, because the server
+already owns the traversal rules. Observations sit at depth 0 and everything
+else is one level above whatever it depends on, so a chain of echoes renders as
+a tall thin stack over a single source - which is the shape the whole project
+is about.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from sqlalchemy.orm import Session
+
+from rootmemory.models.enums import CAUSAL_EDGE_TYPES, LinkRole, NodeType
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.repositories.agent_repo import AgentRepository
+from rootmemory.repositories.belief_repo import BeliefRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.decision_repo import DecisionRepository
+from rootmemory.repositories.edge_repo import EdgeRepository
+from rootmemory.repositories.observation_repo import ObservationRepository
+from rootmemory.services.contradiction_service import ContradictionService
+from rootmemory.services.provenance_service import ProvenanceService
+
+#: Guard against a pathological graph making layout loop forever.
+MAX_DEPTH = 64
+
+
+@dataclass(slots=True)
+class GraphNode:
+    id: uuid.UUID
+    type: NodeType
+    label: str
+    status: str
+    depth: int = 0
+    detail: dict = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "id": str(self.id),
+            "type": str(self.type),
+            "label": self.label,
+            "status": self.status,
+            "depth": self.depth,
+            "detail": self.detail,
+        }
+
+
+@dataclass(slots=True)
+class GraphEdge:
+    source: uuid.UUID
+    target: uuid.UUID
+    edge_type: str
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "source": str(self.source),
+            "target": str(self.target),
+            "edge_type": self.edge_type,
+        }
+
+
+@dataclass(slots=True)
+class GraphSnapshot:
+    nodes: list[GraphNode] = field(default_factory=list)
+    edges: list[GraphEdge] = field(default_factory=list)
+    stats: dict = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "nodes": [n.as_dict() for n in self.nodes],
+            "edges": [e.as_dict() for e in self.edges],
+            "stats": self.stats,
+        }
+
+
+class GraphService:
+    """Assembles a drawable view of the whole graph."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+        self.observations = ObservationRepository(session)
+        self.beliefs = BeliefRepository(session)
+        self.claims = ClaimRepository(session)
+        self.decisions = DecisionRepository(session)
+        self.agents = AgentRepository(session)
+        self.edges = EdgeRepository(session)
+        self.provenance = ProvenanceService(session)
+        self.contradictions = ContradictionService(session)
+
+    def snapshot(self) -> GraphSnapshot:
+        agent_names = {a.id: a.name for a in self.agents.list()}
+        observations = list(self.observations.list())
+        beliefs = list(self.beliefs.list())
+        claims = list(self.claims.list())
+        decisions = list(self.decisions.list())
+
+        nodes: list[GraphNode] = []
+        nodes.extend(self._observation_nodes(observations))
+        nodes.extend(self._belief_nodes(beliefs, agent_names))
+        nodes.extend(self._claim_nodes(claims))
+        nodes.extend(self._decision_nodes(decisions, agent_names))
+
+        edges = [
+            GraphEdge(source=e.from_node_id, target=e.to_node_id, edge_type=e.edge_type)
+            for e in self.edges.all_edges()
+        ]
+
+        self._assign_depths(nodes, edges)
+
+        return GraphSnapshot(
+            nodes=nodes,
+            edges=edges,
+            stats=self._stats(observations, beliefs, claims, decisions, nodes),
+        )
+
+    # ------------------------------------------------------------------
+    # nodes
+    # ------------------------------------------------------------------
+
+    def _observation_nodes(self, observations: Sequence) -> list[GraphNode]:
+        return [
+            GraphNode(
+                id=o.id,
+                type=NodeType.OBSERVATION,
+                label=o.content,
+                status=str(o.validity_status),
+                detail={
+                    "source_type": o.source_type,
+                    "source_actor": o.source_actor,
+                    "source_uri": o.source_uri,
+                    "reliability_score": o.reliability_score,
+                    "source_family_id": o.source_family_id,
+                    "independence_key": o.independence_key,
+                    "validity_reason": o.validity_reason,
+                    "content": o.content,
+                    "timestamp": o.timestamp.isoformat() if o.timestamp else None,
+                },
+            )
+            for o in observations
+        ]
+
+    def _belief_nodes(self, beliefs: Sequence, agent_names: dict) -> list[GraphNode]:
+        nodes: list[GraphNode] = []
+        for b in beliefs:
+            roots = self.provenance.find_evidence_root_observations(NodeRef.belief(b.id))
+            nodes.append(
+                GraphNode(
+                    id=b.id,
+                    type=NodeType.BELIEF,
+                    label=b.claim_text,
+                    status=str(b.epistemic_status),
+                    detail={
+                        "agent": agent_names.get(b.agent_id, "unknown"),
+                        "agent_id": str(b.agent_id),
+                        "confidence": b.confidence,
+                        "visibility": str(b.visibility),
+                        "claim_key": b.normalized_claim_key,
+                        "llm_generated": b.llm_generated,
+                        "evidence_roots": [str(o.id) for o in roots],
+                        "independent_source_count": len({o.independence_key for o in roots}),
+                    },
+                )
+            )
+        return nodes
+
+    def _claim_nodes(self, claims: Sequence) -> list[GraphNode]:
+        nodes: list[GraphNode] = []
+        for claim in claims:
+            context = self.contradictions.build_context(claim.id)
+            nodes.append(
+                GraphNode(
+                    id=claim.id,
+                    type=NodeType.CLAIM,
+                    label=claim.canonical_text,
+                    status=str(claim.status),
+                    detail={
+                        "claim_key": claim.claim_key,
+                        "confidence": claim.confidence,
+                        "promoted_at": (
+                            claim.promoted_at.isoformat() if claim.promoted_at else None
+                        ),
+                        # The two numbers the whole system exists to keep apart.
+                        "support": {
+                            "belief_count": context.support.belief_count,
+                            "agreeing_agents": context.support.agreeing_agent_count,
+                            "independent_sources": context.support.independent_source_count,
+                            "confidence": context.support.aggregate_confidence,
+                            "naive_average_confidence": context.support.naive_confidence,
+                        },
+                        "contradictions": {
+                            "belief_count": context.contradiction.belief_count,
+                            "agreeing_agents": context.contradiction.agreeing_agent_count,
+                            "independent_sources": (
+                                context.contradiction.independent_source_count
+                            ),
+                            "confidence": context.contradiction.aggregate_confidence,
+                        },
+                        "shares_single_source": context.support.shares_single_source,
+                    },
+                )
+            )
+        return nodes
+
+    def _decision_nodes(self, decisions: Sequence, agent_names: dict) -> list[GraphNode]:
+        return [
+            GraphNode(
+                id=d.id,
+                type=NodeType.DECISION,
+                label=d.content,
+                status=str(d.status),
+                detail={
+                    "agent": agent_names.get(d.agent_id, "unknown"),
+                    "decision_type": d.decision_type,
+                    "depends_on": [str(c) for c in self.decisions.claims_for_decision(d.id)],
+                    "meta": d.meta,
+                },
+            )
+            for d in decisions
+        ]
+
+    # ------------------------------------------------------------------
+    # layout
+    # ------------------------------------------------------------------
+
+    def _assign_depths(self, nodes: list[GraphNode], edges: list[GraphEdge]) -> None:
+        """Depth = one above the deepest thing a node rests on.
+
+        Causal edges (derived_from, depends_on) point from a dependent node to
+        its dependency, so for those a node's parents are the targets of its
+        outgoing edges.
+
+        supports/contradicts read the other way round - they point from a
+        belief at the claim it argues about - so they are followed in reverse
+        here. Otherwise a claim would have no outgoing edges at all and would
+        be drawn underneath the beliefs it summarises.
+        """
+        parents: dict[uuid.UUID, list[uuid.UUID]] = {}
+        for edge in edges:
+            if edge.edge_type in CAUSAL_EDGE_TYPES:
+                parents.setdefault(edge.source, []).append(edge.target)
+            else:
+                # belief --supports--> claim: the claim sits above the belief.
+                parents.setdefault(edge.target, []).append(edge.source)
+
+        by_id = {node.id: node for node in nodes}
+        resolved: dict[uuid.UUID, int] = {}
+
+        def depth_of(node_id: uuid.UUID, seen: frozenset[uuid.UUID]) -> int:
+            if node_id in resolved:
+                return resolved[node_id]
+            # A cycle should be impossible, but layout must never hang.
+            if node_id in seen or len(seen) > MAX_DEPTH:
+                return 0
+            node = by_id.get(node_id)
+            if node is None or node.type == NodeType.OBSERVATION:
+                return 0
+            own_parents = parents.get(node_id, [])
+            if not own_parents:
+                return 0
+            deeper = seen | {node_id}
+            value = 1 + max(depth_of(parent, deeper) for parent in own_parents)
+            resolved[node_id] = value
+            return value
+
+        for node in nodes:
+            node.depth = depth_of(node.id, frozenset())
+
+    # ------------------------------------------------------------------
+    # stats
+    # ------------------------------------------------------------------
+
+    def _stats(
+        self,
+        observations: Sequence,
+        beliefs: Sequence,
+        claims: Sequence,
+        decisions: Sequence,
+        nodes: Sequence[GraphNode],
+    ) -> dict:
+        claim_nodes = [n for n in nodes if n.type == NodeType.CLAIM]
+        return {
+            "observations": len(observations),
+            "valid_observations": sum(1 for o in observations if o.validity_status == "valid"),
+            "beliefs": len(beliefs),
+            "claims": len(claims),
+            "decisions": len(decisions),
+            "independent_sources": len({o.independence_key for o in observations}),
+            "confirmed_claims": sum(1 for c in claims if c.status == "confirmed"),
+            "claims_on_a_single_source": sum(
+                1 for n in claim_nodes if n.detail.get("shares_single_source")
+            ),
+            "decisions_needing_review": sum(1 for d in decisions if d.status == "needs_review"),
+        }
+
+    def claim_supporters(self, claim_id: uuid.UUID) -> dict[str, list[str]]:
+        """Which beliefs sit on each side of a claim, for highlighting."""
+        return {
+            "supports": [
+                str(b.id) for b in self.claims.beliefs_for_claim(claim_id, LinkRole.SUPPORTS)
+            ],
+            "contradicts": [
+                str(b.id) for b in self.claims.beliefs_for_claim(claim_id, LinkRole.CONTRADICTS)
+            ],
+        }
+
+    def causal_edge_types(self) -> list[str]:
+        return sorted(str(e) for e in CAUSAL_EDGE_TYPES)