rootmemory 0.1.0__py3-none-any.whl

rootmemory/models/belief.py

@@ -0,0 +1,39 @@
+"""Beliefs: agent interpretations of evidence (spec section 11)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Float, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column, utcnow
+from rootmemory.models.enums import EpistemicStatus, Visibility
+
+
+class Belief(Base):
+    """An interpretation produced by one agent. A belief is not a fact.
+
+    Every belief must have at least one causal parent (an observation or
+    another belief). A belief with no provenance can never enter shared memory
+    (spec section 16).
+    """
+
+    __tablename__ = "beliefs"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    agent_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("agents.id"), index=True)
+    claim_text: Mapped[str] = mapped_column(Text)
+    normalized_claim_key: Mapped[str] = mapped_column(String(300), index=True)
+    confidence: Mapped[float] = mapped_column(Float, default=0.5)
+    epistemic_status: Mapped[str] = mapped_column(
+        String(20), default=EpistemicStatus.INFERRED, index=True
+    )
+    visibility: Mapped[str] = mapped_column(String(20), default=Visibility.PRIVATE, index=True)
+    # True when the belief text was produced by an LLM rather than by
+    # deterministic code (spec section 47).
+    llm_generated: Mapped[bool] = mapped_column(default=False)
+    created_at: Mapped[datetime] = timestamp_column()
+    updated_at: Mapped[datetime] = timestamp_column(onupdate=utcnow)
+    meta: Mapped[dict] = json_column()

rootmemory/models/claim.py

@@ -0,0 +1,52 @@
+"""Claims: normalized propositions that beliefs support or contradict."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+from rootmemory.models.enums import ClaimStatus, LinkRole
+
+
+class Claim(Base):
+    """A proposition that several beliefs may map onto.
+
+    Only the PromotionService may set status to confirmed (spec section 46).
+    """
+
+    __tablename__ = "claims"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    claim_key: Mapped[str] = mapped_column(String(300), unique=True, index=True)
+    canonical_text: Mapped[str] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(20), default=ClaimStatus.UNCONFIRMED, index=True)
+    confidence: Mapped[float] = mapped_column(Float, default=0.0)
+    independent_support_count: Mapped[int] = mapped_column(Integer, default=0)
+    independent_contradiction_count: Mapped[int] = mapped_column(Integer, default=0)
+    # Timezone-aware like every other timestamp: PromotionService writes an
+    # aware datetime, and a naive column would silently strip the offset on
+    # PostgreSQL (SQLite does not notice, which is how this hid).
+    promoted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), default=None
+    )
+    created_at: Mapped[datetime] = timestamp_column()
+    meta: Mapped[dict] = json_column()
+
+
+class ClaimBeliefLink(Base):
+    """Association between a claim and a belief that supports or contradicts it."""
+
+    __tablename__ = "claim_belief_links"
+    __table_args__ = (
+        UniqueConstraint("claim_id", "belief_id", "role", name="claim_id_belief_id_role"),
+    )
+
+    id: Mapped[uuid.UUID] = pk_column()
+    claim_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("claims.id"), index=True)
+    belief_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("beliefs.id"), index=True)
+    role: Mapped[str] = mapped_column(String(20), default=LinkRole.SUPPORTS, index=True)
+    created_at: Mapped[datetime] = timestamp_column()

rootmemory/models/decision.py

@@ -0,0 +1,38 @@
+"""Decisions: downstream outputs that depend on claims (spec section 14)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import ForeignKey, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+from rootmemory.models.enums import DecisionStatus
+
+
+class Decision(Base):
+    """An action or conclusion an agent produced from one or more claims."""
+
+    __tablename__ = "decisions"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    agent_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("agents.id"), index=True)
+    decision_type: Mapped[str] = mapped_column(String(100), index=True)
+    content: Mapped[str] = mapped_column(Text)
+    status: Mapped[str] = mapped_column(String(20), default=DecisionStatus.ACTIVE, index=True)
+    created_at: Mapped[datetime] = timestamp_column()
+    meta: Mapped[dict] = json_column()
+
+
+class DecisionDependency(Base):
+    """Explicit link from a decision to a claim it relies on."""
+
+    __tablename__ = "decision_dependencies"
+    __table_args__ = (UniqueConstraint("decision_id", "claim_id", name="decision_id_claim_id"),)
+
+    id: Mapped[uuid.UUID] = pk_column()
+    decision_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("decisions.id"), index=True)
+    claim_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("claims.id"), index=True)
+    created_at: Mapped[datetime] = timestamp_column()

rootmemory/models/edge.py

@@ -0,0 +1,43 @@
+"""Provenance edges: the causal dependency graph (spec section 12)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Float, Index, String, UniqueConstraint, Uuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+
+
+class ProvenanceEdge(Base):
+    """A directed edge between two knowledge nodes.
+
+    Edges are polymorphic (they connect observations, beliefs, claims and
+    decisions) so the endpoints are stored as (id, type) pairs rather than as
+    foreign keys into a single table.
+
+    Edges are append-only in normal operation: nothing in the service layer
+    updates or deletes them.
+    """
+
+    __tablename__ = "provenance_edges"
+    __table_args__ = (
+        UniqueConstraint(
+            "from_node_id", "to_node_id", "edge_type", name="from_node_id_to_node_id_edge_type"
+        ),
+        Index("ix_provenance_edges_from_node_id", "from_node_id"),
+        Index("ix_provenance_edges_to_node_id", "to_node_id"),
+        Index("ix_provenance_edges_edge_type", "edge_type"),
+    )
+
+    id: Mapped[uuid.UUID] = pk_column()
+    from_node_id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True))
+    from_node_type: Mapped[str] = mapped_column(String(20))
+    to_node_id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True))
+    to_node_type: Mapped[str] = mapped_column(String(20))
+    edge_type: Mapped[str] = mapped_column(String(20))
+    weight: Mapped[float] = mapped_column(Float, default=1.0)
+    created_at: Mapped[datetime] = timestamp_column()
+    meta: Mapped[dict] = json_column()

rootmemory/models/enums.py

@@ -0,0 +1,104 @@
+"""Enumerations shared by the ORM models, schemas and services.
+
+All of these are stored as plain strings so the schema is portable across
+SQLite and PostgreSQL and so new values never require a migration.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class NodeType(StrEnum):
+    """The four knowledge objects that can appear in the provenance graph."""
+
+    OBSERVATION = "observation"
+    BELIEF = "belief"
+    CLAIM = "claim"
+    DECISION = "decision"
+
+
+class EdgeType(StrEnum):
+    """Provenance edge types.
+
+    Direction convention, applied consistently across the whole system:
+
+        an edge always points from the *dependent* node to the node it
+        *depends on* (child -> parent).
+
+        belief   --derived_from--> observation | belief
+        decision --depends_on---->  claim
+        belief   --supports----->  claim        (annotation, see below)
+        belief   --contradicts-->  claim        (annotation, see below)
+
+    ``derived_from`` and ``depends_on`` are the *causal* edges: they are the
+    ones walked by evidence-root discovery and by cycle detection.
+
+    ``supports`` / ``contradicts`` are recorded for audit and read naturally
+    left-to-right ("belief supports claim"). Because a claim is downstream of
+    the beliefs that support it, they are NOT walked as causal parent edges;
+    claim membership is resolved through ``claim_belief_links``.
+    """
+
+    DERIVED_FROM = "derived_from"
+    SUPPORTS = "supports"
+    CONTRADICTS = "contradicts"
+    DEPENDS_ON = "depends_on"
+
+
+#: Edge types that express causal ancestry (dependent -> dependency).
+CAUSAL_EDGE_TYPES: frozenset[str] = frozenset({EdgeType.DERIVED_FROM, EdgeType.DEPENDS_ON})
+
+
+class ValidityStatus(StrEnum):
+    """Validity of an observation. Observations are immutable; only this moves."""
+
+    VALID = "valid"
+    INVALID = "invalid"
+    DISPUTED = "disputed"
+    UNKNOWN = "unknown"
+
+
+class EpistemicStatus(StrEnum):
+    """How strongly an agent currently holds a belief."""
+
+    INFERRED = "inferred"
+    BELIEVED = "believed"
+    UNCERTAIN = "uncertain"
+    CONFIRMED = "confirmed"
+    CONTRADICTED = "contradicted"
+    RETRACTED = "retracted"
+
+
+class Visibility(StrEnum):
+    """Private reasoning vs shared memory (spec section 29)."""
+
+    PRIVATE = "private"
+    CANDIDATE_SHARED = "candidate_shared"
+    SHARED = "shared"
+
+
+class ClaimStatus(StrEnum):
+    UNCONFIRMED = "unconfirmed"
+    PROVISIONAL = "provisional"
+    CONFIRMED = "confirmed"
+    CONTRADICTED = "contradicted"
+    RETRACTED = "retracted"
+
+
+class DecisionStatus(StrEnum):
+    ACTIVE = "active"
+    NEEDS_REVIEW = "needs_review"
+    INVALIDATED = "invalidated"
+
+
+class LinkRole(StrEnum):
+    """How a belief relates to a claim."""
+
+    SUPPORTS = "supports"
+    CONTRADICTS = "contradicts"
+
+
+class PromotionResultType(StrEnum):
+    PROMOTED = "promoted"
+    REJECTED = "rejected"

rootmemory/models/node_ref.py

@@ -0,0 +1,42 @@
+"""NodeRef: a typed pointer to any node in the provenance graph."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from rootmemory.models.enums import NodeType
+
+
+@dataclass(frozen=True, slots=True)
+class NodeRef:
+    """A (id, type) pair identifying one node.
+
+    The provenance graph spans four tables, so edges and traversal results
+    address nodes by this pair rather than by a bare id.
+    """
+
+    id: uuid.UUID
+    type: NodeType
+
+    def __str__(self) -> str:
+        return f"{self.type}:{self.id}"
+
+    def as_dict(self) -> dict[str, str]:
+        return {"id": str(self.id), "type": str(self.type)}
+
+    @classmethod
+    def observation(cls, node_id: uuid.UUID) -> NodeRef:
+        return cls(node_id, NodeType.OBSERVATION)
+
+    @classmethod
+    def belief(cls, node_id: uuid.UUID) -> NodeRef:
+        return cls(node_id, NodeType.BELIEF)
+
+    @classmethod
+    def claim(cls, node_id: uuid.UUID) -> NodeRef:
+        return cls(node_id, NodeType.CLAIM)
+
+    @classmethod
+    def decision(cls, node_id: uuid.UUID) -> NodeRef:
+        return cls(node_id, NodeType.DECISION)

rootmemory/models/observation.py

@@ -0,0 +1,51 @@
+"""Observations: immutable external evidence (spec section 10)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Float, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+from rootmemory.models.enums import ValidityStatus
+
+
+class Observation(Base):
+    """A raw piece of evidence from outside the system.
+
+    Observations are append-only. When one turns out to be wrong its
+    ``validity_status`` changes; the row itself is never edited or deleted, so
+    history stays reconstructable.
+    """
+
+    __tablename__ = "observations"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    source_type: Mapped[str] = mapped_column(String(100), index=True)
+    source_uri: Mapped[str | None] = mapped_column(String(1000), default=None)
+    source_actor: Mapped[str | None] = mapped_column(String(300), default=None)
+    content: Mapped[str] = mapped_column(Text)
+    content_hash: Mapped[str] = mapped_column(String(64), index=True)
+    timestamp: Mapped[datetime] = timestamp_column()
+    created_by_agent_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("agents.id"), default=None, index=True
+    )
+    validity_status: Mapped[str] = mapped_column(
+        String(20), default=ValidityStatus.VALID, index=True
+    )
+    validity_reason: Mapped[str | None] = mapped_column(String(2000), default=None)
+    reliability_score: Mapped[float] = mapped_column(Float, default=1.0)
+    # Two observations that copy the same original source share a family id and
+    # therefore count as ONE independent source (spec section 20).
+    source_family_id: Mapped[str | None] = mapped_column(String(200), default=None, index=True)
+    created_at: Mapped[datetime] = timestamp_column()
+    meta: Mapped[dict] = json_column()
+
+    @property
+    def independence_key(self) -> str:
+        """The key this observation contributes to an independence count."""
+        if self.source_family_id:
+            return f"family:{self.source_family_id}"
+        return f"obs:{self.id}"

rootmemory/repositories/__init__.py

@@ -0,0 +1,19 @@
+"""Repository layer: all SQL lives here, no business rules."""
+
+from rootmemory.repositories.agent_repo import AgentRepository
+from rootmemory.repositories.audit_repo import AuditRepository
+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
+
+__all__ = [
+    "AgentRepository",
+    "AuditRepository",
+    "BeliefRepository",
+    "ClaimRepository",
+    "DecisionRepository",
+    "EdgeRepository",
+    "ObservationRepository",
+]

rootmemory/repositories/agent_repo.py

@@ -0,0 +1,44 @@
+"""Data access for agents."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.agent import Agent
+
+
+class AgentRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        name: str,
+        role: str = "",
+        description: str = "",
+        trust_score: float = 0.5,
+        meta: dict | None = None,
+    ) -> Agent:
+        agent = Agent(
+            name=name,
+            role=role,
+            description=description,
+            trust_score=trust_score,
+            meta=meta or {},
+        )
+        self.session.add(agent)
+        self.session.flush()
+        return agent
+
+    def get(self, agent_id: uuid.UUID) -> Agent | None:
+        return self.session.get(Agent, agent_id)
+
+    def get_by_name(self, name: str) -> Agent | None:
+        return self.session.execute(select(Agent).where(Agent.name == name)).scalar_one_or_none()
+
+    def list(self) -> Sequence[Agent]:
+        return self.session.execute(select(Agent).order_by(Agent.created_at)).scalars().all()

rootmemory/repositories/audit_repo.py

@@ -0,0 +1,43 @@
+"""Data access for promotion audits and repair reports."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.audit import PromotionAudit, RepairReport
+
+
+class AuditRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def record_promotion(self, **fields: object) -> PromotionAudit:
+        audit = PromotionAudit(**fields)
+        self.session.add(audit)
+        self.session.flush()
+        return audit
+
+    def promotions_for_claim(self, claim_id: uuid.UUID) -> Sequence[PromotionAudit]:
+        stmt = (
+            select(PromotionAudit)
+            .where(PromotionAudit.claim_id == claim_id)
+            .order_by(PromotionAudit.evaluated_at)
+        )
+        return self.session.execute(stmt).scalars().all()
+
+    def record_repair(self, **fields: object) -> RepairReport:
+        report = RepairReport(**fields)
+        self.session.add(report)
+        self.session.flush()
+        return report
+
+    def get_repair(self, report_id: uuid.UUID) -> RepairReport | None:
+        return self.session.get(RepairReport, report_id)
+
+    def list_repairs(self) -> Sequence[RepairReport]:
+        stmt = select(RepairReport).order_by(RepairReport.created_at)
+        return self.session.execute(stmt).scalars().all()

rootmemory/repositories/belief_repo.py

@@ -0,0 +1,63 @@
+"""Data access for beliefs."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterable, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.belief import Belief
+from rootmemory.models.enums import EpistemicStatus, Visibility
+
+
+class BeliefRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        agent_id: uuid.UUID,
+        claim_text: str,
+        normalized_claim_key: str,
+        confidence: float,
+        epistemic_status: EpistemicStatus = EpistemicStatus.INFERRED,
+        visibility: Visibility = Visibility.PRIVATE,
+        llm_generated: bool = False,
+        meta: dict | None = None,
+    ) -> Belief:
+        belief = Belief(
+            agent_id=agent_id,
+            claim_text=claim_text,
+            normalized_claim_key=normalized_claim_key,
+            confidence=confidence,
+            epistemic_status=str(epistemic_status),
+            visibility=str(visibility),
+            llm_generated=llm_generated,
+            meta=meta or {},
+        )
+        self.session.add(belief)
+        self.session.flush()
+        return belief
+
+    def get(self, belief_id: uuid.UUID) -> Belief | None:
+        return self.session.get(Belief, belief_id)
+
+    def get_many(self, belief_ids: Iterable[uuid.UUID]) -> Sequence[Belief]:
+        ids = list(belief_ids)
+        if not ids:
+            return []
+        stmt = select(Belief).where(Belief.id.in_(ids))
+        return self.session.execute(stmt).scalars().all()
+
+    def list_by_claim_key(self, claim_key: str) -> Sequence[Belief]:
+        stmt = select(Belief).where(Belief.normalized_claim_key == claim_key)
+        return self.session.execute(stmt).scalars().all()
+
+    def list_by_agent(self, agent_id: uuid.UUID) -> Sequence[Belief]:
+        stmt = select(Belief).where(Belief.agent_id == agent_id).order_by(Belief.created_at)
+        return self.session.execute(stmt).scalars().all()
+
+    def list(self) -> Sequence[Belief]:
+        return self.session.execute(select(Belief).order_by(Belief.created_at)).scalars().all()

rootmemory/repositories/claim_repo.py

@@ -0,0 +1,102 @@
+"""Data access for claims and claim/belief links."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from rootmemory.models.belief import Belief
+from rootmemory.models.claim import Claim, ClaimBeliefLink
+from rootmemory.models.enums import ClaimStatus, LinkRole
+
+
+class ClaimRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def create(
+        self,
+        claim_key: str,
+        canonical_text: str,
+        meta: dict | None = None,
+    ) -> Claim:
+        claim = Claim(claim_key=claim_key, canonical_text=canonical_text, meta=meta or {})
+        self.session.add(claim)
+        self.session.flush()
+        return claim
+
+    def get(self, claim_id: uuid.UUID) -> Claim | None:
+        return self.session.get(Claim, claim_id)
+
+    def get_for_update(self, claim_id: uuid.UUID) -> Claim | None:
+        """Read a claim and hold a row lock until the transaction ends.
+
+        The promotion gate reads a claim's support, decides, then writes the
+        result. Without this lock two workers can interleave those steps and
+        confirm a claim on evidence the other one is retracting.
+
+        SQLAlchemy emits FOR UPDATE on PostgreSQL and omits it on SQLite, which
+        has no row locks and serializes writers anyway - so this is correct on
+        both without a dialect branch.
+        """
+        stmt = select(Claim).where(Claim.id == claim_id).with_for_update()
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def get_by_key(self, claim_key: str) -> Claim | None:
+        stmt = select(Claim).where(Claim.claim_key == claim_key)
+        return self.session.execute(stmt).scalar_one_or_none()
+
+    def get_or_create(self, claim_key: str, canonical_text: str) -> Claim:
+        existing = self.get_by_key(claim_key)
+        if existing is not None:
+            return existing
+        return self.create(claim_key=claim_key, canonical_text=canonical_text)
+
+    def list(self) -> Sequence[Claim]:
+        return self.session.execute(select(Claim).order_by(Claim.created_at)).scalars().all()
+
+    def link_belief(
+        self, claim_id: uuid.UUID, belief_id: uuid.UUID, role: LinkRole
+    ) -> ClaimBeliefLink:
+        existing = self.session.execute(
+            select(ClaimBeliefLink).where(
+                ClaimBeliefLink.claim_id == claim_id,
+                ClaimBeliefLink.belief_id == belief_id,
+                ClaimBeliefLink.role == str(role),
+            )
+        ).scalar_one_or_none()
+        if existing is not None:
+            return existing
+        link = ClaimBeliefLink(claim_id=claim_id, belief_id=belief_id, role=str(role))
+        self.session.add(link)
+        self.session.flush()
+        return link
+
+    def beliefs_for_claim(self, claim_id: uuid.UUID, role: LinkRole) -> Sequence[Belief]:
+        stmt = (
+            select(Belief)
+            .join(ClaimBeliefLink, ClaimBeliefLink.belief_id == Belief.id)
+            .where(ClaimBeliefLink.claim_id == claim_id, ClaimBeliefLink.role == str(role))
+            .order_by(Belief.created_at)
+        )
+        return self.session.execute(stmt).scalars().all()
+
+    def claims_for_beliefs(self, belief_ids: Sequence[uuid.UUID]) -> Sequence[Claim]:
+        """Every claim any of these beliefs supports or contradicts."""
+        if not belief_ids:
+            return []
+        stmt = (
+            select(Claim)
+            .join(ClaimBeliefLink, ClaimBeliefLink.claim_id == Claim.id)
+            .where(ClaimBeliefLink.belief_id.in_(list(belief_ids)))
+            .distinct()
+        )
+        return self.session.execute(stmt).scalars().all()
+
+    def set_status(self, claim: Claim, status: ClaimStatus) -> Claim:
+        claim.status = str(status)
+        self.session.flush()
+        return claim