rootmemory 0.1.0__py3-none-any.whl

rootmemory/repositories/decision_repo.py

@@ -0,0 +1,76 @@
+"""Data access for decisions and their claim dependencies."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.decision import Decision, DecisionDependency
+from rootmemory.models.enums import DecisionStatus
+
+
+class DecisionRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        agent_id: uuid.UUID,
+        decision_type: str,
+        content: str,
+        meta: dict | None = None,
+    ) -> Decision:
+        decision = Decision(
+            agent_id=agent_id,
+            decision_type=decision_type,
+            content=content,
+            meta=meta or {},
+        )
+        self.session.add(decision)
+        self.session.flush()
+        return decision
+
+    def get(self, decision_id: uuid.UUID) -> Decision | None:
+        return self.session.get(Decision, decision_id)
+
+    def list(self) -> Sequence[Decision]:
+        return self.session.execute(select(Decision).order_by(Decision.created_at)).scalars().all()
+
+    def add_dependency(self, decision_id: uuid.UUID, claim_id: uuid.UUID) -> DecisionDependency:
+        existing = self.session.execute(
+            select(DecisionDependency).where(
+                DecisionDependency.decision_id == decision_id,
+                DecisionDependency.claim_id == claim_id,
+            )
+        ).scalar_one_or_none()
+        if existing is not None:
+            return existing
+        dependency = DecisionDependency(decision_id=decision_id, claim_id=claim_id)
+        self.session.add(dependency)
+        self.session.flush()
+        return dependency
+
+    def decisions_for_claims(self, claim_ids: Sequence[uuid.UUID]) -> Sequence[Decision]:
+        if not claim_ids:
+            return []
+        stmt = (
+            select(Decision)
+            .join(DecisionDependency, DecisionDependency.decision_id == Decision.id)
+            .where(DecisionDependency.claim_id.in_(list(claim_ids)))
+            .distinct()
+        )
+        return self.session.execute(stmt).scalars().all()
+
+    def claims_for_decision(self, decision_id: uuid.UUID) -> Sequence[uuid.UUID]:
+        stmt = select(DecisionDependency.claim_id).where(
+            DecisionDependency.decision_id == decision_id
+        )
+        return list(self.session.execute(stmt).scalars().all())
+
+    def set_status(self, decision: Decision, status: DecisionStatus) -> Decision:
+        decision.status = str(status)
+        self.session.flush()
+        return decision

rootmemory/repositories/edge_repo.py

@@ -0,0 +1,77 @@
+"""Data access for provenance edges."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterable, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.edge import ProvenanceEdge
+from rootmemory.models.enums import EdgeType
+from rootmemory.models.node_ref import NodeRef
+
+
+class EdgeRepository:
+    """Append-only access to the provenance edge table."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        source: NodeRef,
+        target: NodeRef,
+        edge_type: EdgeType,
+        weight: float = 1.0,
+        meta: dict | None = None,
+    ) -> ProvenanceEdge:
+        """Create an edge pointing from ``source`` to ``target``."""
+        edge = ProvenanceEdge(
+            from_node_id=source.id,
+            from_node_type=str(source.type),
+            to_node_id=target.id,
+            to_node_type=str(target.type),
+            edge_type=str(edge_type),
+            weight=weight,
+            meta=meta or {},
+        )
+        self.session.add(edge)
+        self.session.flush()
+        return edge
+
+    def exists(self, source: NodeRef, target: NodeRef, edge_type: EdgeType) -> bool:
+        stmt = select(ProvenanceEdge.id).where(
+            ProvenanceEdge.from_node_id == source.id,
+            ProvenanceEdge.to_node_id == target.id,
+            ProvenanceEdge.edge_type == str(edge_type),
+        )
+        return self.session.execute(stmt).first() is not None
+
+    def outgoing(
+        self, node_ids: Iterable[uuid.UUID], edge_types: Iterable[str] | None = None
+    ) -> Sequence[ProvenanceEdge]:
+        """Edges whose ``from_node_id`` is one of ``node_ids`` (node -> parents)."""
+        ids = list(node_ids)
+        if not ids:
+            return []
+        stmt = select(ProvenanceEdge).where(ProvenanceEdge.from_node_id.in_(ids))
+        if edge_types is not None:
+            stmt = stmt.where(ProvenanceEdge.edge_type.in_([str(e) for e in edge_types]))
+        return self.session.execute(stmt).scalars().all()
+
+    def incoming(
+        self, node_ids: Iterable[uuid.UUID], edge_types: Iterable[str] | None = None
+    ) -> Sequence[ProvenanceEdge]:
+        """Edges whose ``to_node_id`` is one of ``node_ids`` (node -> children)."""
+        ids = list(node_ids)
+        if not ids:
+            return []
+        stmt = select(ProvenanceEdge).where(ProvenanceEdge.to_node_id.in_(ids))
+        if edge_types is not None:
+            stmt = stmt.where(ProvenanceEdge.edge_type.in_([str(e) for e in edge_types]))
+        return self.session.execute(stmt).scalars().all()
+
+    def all_edges(self) -> Sequence[ProvenanceEdge]:
+        return self.session.execute(select(ProvenanceEdge)).scalars().all()

rootmemory/repositories/observation_repo.py

@@ -0,0 +1,76 @@
+"""Data access for observations."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from collections.abc import Iterable, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.enums import ValidityStatus
+from rootmemory.models.observation import Observation
+
+
+def content_hash(content: str) -> str:
+    """Stable hash of observation content, used to spot literal duplicates."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+class ObservationRepository:
+    """Observations are append-only: there is deliberately no delete method."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        source_type: str,
+        content: str,
+        source_uri: str | None = None,
+        source_actor: str | None = None,
+        created_by_agent_id: uuid.UUID | None = None,
+        reliability_score: float = 1.0,
+        source_family_id: str | None = None,
+        validity_status: ValidityStatus = ValidityStatus.VALID,
+        meta: dict | None = None,
+    ) -> Observation:
+        observation = Observation(
+            source_type=source_type,
+            source_uri=source_uri,
+            source_actor=source_actor,
+            content=content,
+            content_hash=content_hash(content),
+            created_by_agent_id=created_by_agent_id,
+            reliability_score=reliability_score,
+            source_family_id=source_family_id,
+            validity_status=str(validity_status),
+            meta=meta or {},
+        )
+        self.session.add(observation)
+        self.session.flush()
+        return observation
+
+    def get(self, observation_id: uuid.UUID) -> Observation | None:
+        return self.session.get(Observation, observation_id)
+
+    def get_many(self, observation_ids: Iterable[uuid.UUID]) -> Sequence[Observation]:
+        ids = list(observation_ids)
+        if not ids:
+            return []
+        stmt = select(Observation).where(Observation.id.in_(ids))
+        return self.session.execute(stmt).scalars().all()
+
+    def list(self) -> Sequence[Observation]:
+        stmt = select(Observation).order_by(Observation.created_at)
+        return self.session.execute(stmt).scalars().all()
+
+    def set_validity(
+        self, observation: Observation, status: ValidityStatus, reason: str | None = None
+    ) -> Observation:
+        """Change validity only. The content of an observation is never edited."""
+        observation.validity_status = str(status)
+        observation.validity_reason = reason
+        self.session.flush()
+        return observation

rootmemory/schemas/__init__.py

@@ -0,0 +1,52 @@
+"""Pydantic request/response models. No business logic lives here."""
+
+from rootmemory.schemas.agent import AgentCreate, AgentRead
+from rootmemory.schemas.belief import BeliefCreate, BeliefRead, BeliefWithProvenance
+from rootmemory.schemas.claim import (
+    ClaimContextResponse,
+    ClaimCreate,
+    ClaimLinkRequest,
+    ClaimRead,
+    EvidenceSide,
+)
+from rootmemory.schemas.common import ErrorResponse, NodeReference
+from rootmemory.schemas.observation import (
+    InvalidationRequest,
+    InvalidationResponse,
+    ObservationCreate,
+    ObservationRead,
+    RepairReportRead,
+)
+from rootmemory.schemas.promotion import PromotionAuditRead, PromotionEvaluationResponse
+from rootmemory.schemas.provenance import (
+    DecisionCreate,
+    DecisionRead,
+    EvidenceRootRead,
+    ProvenanceResponse,
+)
+
+__all__ = [
+    "AgentCreate",
+    "AgentRead",
+    "BeliefCreate",
+    "BeliefRead",
+    "BeliefWithProvenance",
+    "ClaimContextResponse",
+    "ClaimCreate",
+    "ClaimLinkRequest",
+    "ClaimRead",
+    "DecisionCreate",
+    "DecisionRead",
+    "ErrorResponse",
+    "EvidenceRootRead",
+    "EvidenceSide",
+    "InvalidationRequest",
+    "InvalidationResponse",
+    "NodeReference",
+    "ObservationCreate",
+    "ObservationRead",
+    "PromotionAuditRead",
+    "PromotionEvaluationResponse",
+    "ProvenanceResponse",
+    "RepairReportRead",
+]

rootmemory/schemas/agent.py

@@ -0,0 +1,26 @@
+"""Agent request/response schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from rootmemory.schemas.common import ORMModel
+
+
+class AgentCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=200)
+    role: str = ""
+    description: str = ""
+    trust_score: float = Field(default=0.5, ge=0.0, le=1.0)
+
+
+class AgentRead(ORMModel):
+    id: uuid.UUID
+    name: str
+    role: str
+    description: str
+    trust_score: float
+    created_at: datetime

rootmemory/schemas/belief.py

@@ -0,0 +1,49 @@
+"""Belief request/response schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from rootmemory.models.enums import EpistemicStatus, Visibility
+from rootmemory.schemas.common import NodeReference, ORMModel
+
+
+class BeliefCreate(BaseModel):
+    agent_id: uuid.UUID
+    claim_text: str = Field(min_length=1)
+    normalized_claim_key: str | None = Field(
+        default=None,
+        max_length=300,
+        description=(
+            "Which proposition this belief is about. Omit it to let the "
+            "configured normalizer decide (see CLAIM_NORMALIZATION)."
+        ),
+    )
+    confidence: float = Field(ge=0.0, le=1.0)
+    parent_nodes: list[NodeReference] = Field(
+        min_length=1,
+        description="At least one observation or belief this was derived from.",
+    )
+    llm_generated: bool = False
+    metadata: dict = Field(default_factory=dict)
+
+
+class BeliefRead(ORMModel):
+    id: uuid.UUID
+    agent_id: uuid.UUID
+    claim_text: str
+    normalized_claim_key: str
+    confidence: float
+    epistemic_status: EpistemicStatus
+    visibility: Visibility
+    llm_generated: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class BeliefWithProvenance(BeliefRead):
+    evidence_roots: list[uuid.UUID]
+    independent_source_count: int

rootmemory/schemas/claim.py

@@ -0,0 +1,54 @@
+"""Claim request/response schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from rootmemory.models.enums import ClaimStatus
+from rootmemory.schemas.common import ORMModel
+
+
+class ClaimCreate(BaseModel):
+    claim_key: str = Field(min_length=1, max_length=300)
+    canonical_text: str = Field(min_length=1)
+    metadata: dict = Field(default_factory=dict)
+
+
+class ClaimRead(ORMModel):
+    id: uuid.UUID
+    claim_key: str
+    canonical_text: str
+    status: ClaimStatus
+    confidence: float
+    independent_support_count: int
+    independent_contradiction_count: int
+    promoted_at: datetime | None
+    created_at: datetime
+
+
+class ClaimLinkRequest(BaseModel):
+    belief_id: uuid.UUID
+
+
+class EvidenceSide(BaseModel):
+    """One side of a claim, with both counts kept separate on purpose."""
+
+    belief_count: int
+    agreeing_agents: int
+    independent_sources: int
+    confidence: float
+    root_observation_ids: list[uuid.UUID] = Field(default_factory=list)
+
+
+class ClaimContextResponse(BaseModel):
+    """What an agent receives instead of a bare true/false (spec section 49)."""
+
+    claim_id: uuid.UUID
+    claim_key: str
+    claim: str
+    status: ClaimStatus
+    support: EvidenceSide
+    contradictions: EvidenceSide

rootmemory/schemas/common.py

@@ -0,0 +1,27 @@
+"""Shared response pieces."""
+
+from __future__ import annotations
+
+import uuid
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rootmemory.models.enums import NodeType
+
+
+class ORMModel(BaseModel):
+    """Base for schemas read straight off an ORM row."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class NodeReference(BaseModel):
+    """A typed pointer to a node in the provenance graph."""
+
+    id: uuid.UUID
+    type: NodeType = Field(description="observation | belief | claim | decision")
+
+
+class ErrorResponse(BaseModel):
+    error: str
+    detail: str

rootmemory/schemas/observation.py

@@ -0,0 +1,69 @@
+"""Observation request/response schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from rootmemory.models.enums import ValidityStatus
+from rootmemory.schemas.common import ORMModel
+
+
+class ObservationCreate(BaseModel):
+    source_type: str = Field(min_length=1, max_length=100)
+    content: str = Field(min_length=1)
+    source_uri: str | None = None
+    source_actor: str | None = None
+    created_by_agent_id: uuid.UUID | None = None
+    reliability_score: float = Field(default=1.0, ge=0.0, le=1.0)
+    source_family_id: str | None = Field(
+        default=None,
+        description=(
+            "Observations copied from a common origin should share this id; they then "
+            "count as one independent source rather than several."
+        ),
+    )
+    metadata: dict = Field(default_factory=dict)
+
+
+class ObservationRead(ORMModel):
+    id: uuid.UUID
+    source_type: str
+    source_uri: str | None
+    source_actor: str | None
+    content: str
+    content_hash: str
+    timestamp: datetime
+    created_by_agent_id: uuid.UUID | None
+    validity_status: ValidityStatus
+    validity_reason: str | None
+    reliability_score: float
+    source_family_id: str | None
+
+
+class InvalidationRequest(BaseModel):
+    reason: str = Field(default="", max_length=2000)
+
+
+class InvalidationResponse(BaseModel):
+    repair_report_id: uuid.UUID
+    trigger_node_id: uuid.UUID
+    trigger_reason: str
+    affected_beliefs: list[uuid.UUID]
+    affected_claims: list[uuid.UUID]
+    affected_decisions: list[uuid.UUID]
+    details: dict
+
+
+class RepairReportRead(ORMModel):
+    id: uuid.UUID
+    trigger_node_id: uuid.UUID
+    trigger_node_type: str
+    trigger_reason: str
+    affected_beliefs: list[str]
+    affected_claims: list[str]
+    affected_decisions: list[str]
+    details: dict
+    created_at: datetime

rootmemory/schemas/promotion.py

@@ -0,0 +1,50 @@
+"""Promotion request/response schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from rootmemory.schemas.common import ORMModel
+
+
+class PromotionEvaluationResponse(BaseModel):
+    """The gate's verdict.
+
+    ``agreeing_agents`` and ``independent_support_count`` are both present and
+    are never conflated - that difference is the point of the system
+    (spec section 64).
+    """
+
+    claim_id: uuid.UUID
+    claim_key: str
+    supporting_belief_count: int
+    agreeing_agents: int
+    independent_support_count: int
+    contradiction_count: int
+    independent_contradiction_count: int
+    aggregate_confidence: float
+    naive_average_confidence: float
+    decision: Literal["promote", "reject"]
+    reasons: list[str]
+    explanation: str
+    policy_version: str
+
+
+class PromotionAuditRead(ORMModel):
+    id: uuid.UUID
+    claim_id: uuid.UUID
+    evaluated_at: datetime
+    supporting_belief_count: int
+    agreeing_agent_count: int
+    independent_support_count: int
+    contradiction_count: int
+    independent_contradiction_count: int
+    aggregate_confidence: float
+    result: str
+    reasons: list[str]
+    policy_version: str
+    policy_snapshot: dict = Field(default_factory=dict)

rootmemory/schemas/provenance.py

@@ -0,0 +1,51 @@
+"""Provenance and decision schemas."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from rootmemory.models.enums import DecisionStatus, NodeType
+from rootmemory.schemas.common import ORMModel
+
+
+class EvidenceRootRead(BaseModel):
+    id: uuid.UUID
+    source_type: str
+    source_uri: str | None
+    validity_status: str
+    reliability_score: float
+    source_family_id: str | None
+    independence_key: str
+
+
+class ProvenanceResponse(BaseModel):
+    node_id: uuid.UUID
+    node_type: NodeType
+    evidence_roots: list[uuid.UUID]
+    excluded_roots: dict[str, str] = Field(
+        default_factory=dict,
+        description="Ancestor observations that were reached but are not valid evidence.",
+    )
+    independent_source_count: int
+    root_details: list[EvidenceRootRead] = Field(default_factory=list)
+    paths: list[list[str]] = Field(default_factory=list)
+
+
+class DecisionCreate(BaseModel):
+    agent_id: uuid.UUID
+    decision_type: str = Field(min_length=1, max_length=100)
+    content: str = Field(min_length=1)
+    depends_on_claim_ids: list[uuid.UUID] = Field(default_factory=list)
+    metadata: dict = Field(default_factory=dict)
+
+
+class DecisionRead(ORMModel):
+    id: uuid.UUID
+    agent_id: uuid.UUID
+    decision_type: str
+    content: str
+    status: DecisionStatus
+    created_at: datetime

rootmemory/services/__init__.py

@@ -0,0 +1,35 @@
+"""Service layer: all epistemic rules live here, none of them in the API layer."""
+
+from rootmemory.services.belief_service import BeliefService, ParentSpec
+from rootmemory.services.contradiction_service import ClaimContext, ContradictionService
+from rootmemory.services.decision_service import DecisionService
+from rootmemory.services.independence_service import IndependenceReport, IndependenceService
+from rootmemory.services.invalidation_service import InvalidationService, RepairSummary
+from rootmemory.services.promotion_service import (
+    PromotionEvaluation,
+    PromotionPolicy,
+    PromotionService,
+)
+from rootmemory.services.provenance_service import (
+    CascadeResult,
+    EvidenceRoots,
+    ProvenanceService,
+)
+
+__all__ = [
+    "BeliefService",
+    "CascadeResult",
+    "ClaimContext",
+    "ContradictionService",
+    "DecisionService",
+    "EvidenceRoots",
+    "IndependenceReport",
+    "IndependenceService",
+    "InvalidationService",
+    "ParentSpec",
+    "PromotionEvaluation",
+    "PromotionPolicy",
+    "PromotionService",
+    "ProvenanceService",
+    "RepairSummary",
+]