rootmemory 0.1.0__py3-none-any.whl

rootmemory/integrations/langgraph_store.py

@@ -0,0 +1,402 @@
+"""A LangGraph ``BaseStore`` backed by RootMemory.
+
+This is the drop-in for the long-term memory slot::
+
+    agent = create_react_agent(model, tools, store=RootMemoryStore(memory, agent_id))
+
+Two things are worth understanding before using it.
+
+**Which slot this is.** ``create_react_agent`` has two memory parameters.
+``checkpointer=`` holds thread state - the message history of one conversation -
+and this is *not* that; keep using ``MemorySaver`` or a Postgres checkpointer
+there. ``store=`` is long-term memory shared across threads, and that is what
+this fills.
+
+**What the store interface can and cannot enforce.** ``BaseStore.put`` is a
+plain key-value write with nowhere to say "here is what I read first". So this
+adapter infers it: the store remembers every item it has served to the agent,
+and cites those as the parents of whatever the agent writes next. An agent that
+writes a conclusion after reading a colleague's note is therefore recorded as
+deriving from that note, automatically, with no cooperation required.
+
+That gives you provenance capture for free. It does not give you enforcement:
+a store cannot stop a model from ignoring what it read. For that, use the tools
+in ``langchain_tools`` (which make citation a required argument) or the node
+wrapper in ``langgraph_memory``. The three are complementary - this one is the
+lowest-effort way in.
+
+Namespaces
+----------
+
+``("observations",)``          evidence from outside; writing here records a source
+``("beliefs", <claim_key>)``   conclusions about one proposition
+``("claims",)``                read-only view of claims, with the honest counts
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from rootmemory.client import RootMemory
+from rootmemory.db.session import get_session_factory
+from rootmemory.errors import ImmutableRecordError, NodeNotFoundError, ProvenanceRequiredError
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.services.promotion_service import PromotionPolicy
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from langgraph.store.base import Item, Op, Result, SearchItem
+
+OBSERVATIONS = "observations"
+BELIEFS = "beliefs"
+CLAIMS = "claims"
+
+
+def _require_langgraph() -> Any:
+    try:
+        from langgraph.store import base
+    except ModuleNotFoundError as exc:  # pragma: no cover - environment dependent
+        raise ModuleNotFoundError(
+            "The LangGraph store adapter needs langgraph. Install it with: "
+            'pip install "rootmemory[langgraph]"'
+        ) from exc
+    return base
+
+
+def _base_store_class() -> Any:
+    return _require_langgraph().BaseStore
+
+
+class RootMemoryStore(_base_store_class()):  # type: ignore[misc]
+    """LangGraph long-term memory whose writes carry provenance.
+
+    ``BaseStore`` only requires ``batch`` and ``abatch``; every convenience
+    method (``get``, ``put``, ``search``, ``aput`` ...) is built on those, so
+    implementing the pair makes the whole interface work.
+
+    One instance per agent: read tracking is per-instance, which is what lets a
+    write cite the reads that preceded it.
+    """
+
+    #: How many recent reads may be cited by a single write.
+    max_cited_reads = 16
+
+    def __init__(
+        self,
+        agent_id: uuid.UUID,
+        session_factory: Any = None,
+        policy: PromotionPolicy | None = None,
+        auto_cite_reads: bool = True,
+    ) -> None:
+        self.agent_id = agent_id
+        self._session_factory = session_factory or get_session_factory()
+        self._policy = policy
+        self._auto_cite_reads = auto_cite_reads
+        #: ids this agent has been shown, most recent last
+        self._reads: list[uuid.UUID] = []
+
+    # ------------------------------------------------------------------
+    # BaseStore contract
+    # ------------------------------------------------------------------
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        base = _require_langgraph()
+        session = self._session_factory()
+        try:
+            memory = RootMemory(session, self._policy)
+            results = [self._apply(memory, op, base) for op in ops]
+            session.commit()
+            return results
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        materialized = list(ops)
+        return await asyncio.to_thread(self.batch, materialized)
+
+    # ------------------------------------------------------------------
+
+    def _apply(self, memory: RootMemory, op: Op, base: Any) -> Result:
+        if isinstance(op, base.GetOp):
+            return self._get(memory, op, base)
+        if isinstance(op, base.PutOp):
+            self._put(memory, op)
+            return None
+        if isinstance(op, base.SearchOp):
+            return self._search(memory, op, base)
+        if isinstance(op, base.ListNamespacesOp):
+            return self._namespaces(memory)
+        raise NotImplementedError(f"unsupported store operation: {type(op).__name__}")
+
+    # ------------------------------------------------------------------
+    # reads
+    # ------------------------------------------------------------------
+
+    def _get(self, memory: RootMemory, op: Any, base: Any) -> Item | None:
+        node_id = _as_uuid(op.key)
+        if node_id is None:
+            return None
+        root = op.namespace[0] if op.namespace else ""
+
+        if root == OBSERVATIONS:
+            observation = memory.observations.get(node_id)
+            if observation is None:
+                return None
+            self._note_read(observation.id)
+            return _item(op.namespace, op.key, self._observation_value(observation), base)
+
+        if root == BELIEFS:
+            belief = memory.find_belief(node_id)
+            if belief is None:
+                return None
+            self._note_read(belief.id)
+            return _item(op.namespace, op.key, self._belief_value(memory, belief), base)
+
+        if root == CLAIMS:
+            claim = memory.claims.get(node_id)
+            if claim is None:
+                return None
+            return _item(op.namespace, op.key, self._claim_value(memory, claim.id), base)
+
+        return None
+
+    def _search(self, memory: RootMemory, op: Any, base: Any) -> list[SearchItem]:
+        prefix = op.namespace_prefix
+        root = prefix[0] if prefix else ""
+        query = (op.query or "").lower()
+        items: list[SearchItem] = []
+
+        if root in ("", OBSERVATIONS):
+            for observation in memory.observations.list():
+                if query and query not in observation.content.lower():
+                    continue
+                self._note_read(observation.id)
+                items.append(
+                    _search_item(
+                        (OBSERVATIONS,),
+                        str(observation.id),
+                        self._observation_value(observation),
+                        base,
+                    )
+                )
+
+        if root in ("", BELIEFS):
+            claim_key = prefix[1] if len(prefix) > 1 else None
+            for belief in memory.list_beliefs():
+                if claim_key and belief.normalized_claim_key != claim_key:
+                    continue
+                if query and query not in belief.claim_text.lower():
+                    continue
+                self._note_read(belief.id)
+                items.append(
+                    _search_item(
+                        (BELIEFS, belief.normalized_claim_key),
+                        str(belief.id),
+                        self._belief_value(memory, belief),
+                        base,
+                    )
+                )
+
+        if root in ("", CLAIMS):
+            for claim in memory.claims.list():
+                if query and query not in claim.canonical_text.lower():
+                    continue
+                items.append(
+                    _search_item(
+                        (CLAIMS,), str(claim.id), self._claim_value(memory, claim.id), base
+                    )
+                )
+
+        return items[op.offset : op.offset + op.limit]
+
+    def _namespaces(self, memory: RootMemory) -> list[tuple[str, ...]]:
+        keys = {b.normalized_claim_key for b in memory.list_beliefs()}
+        return [(OBSERVATIONS,), (CLAIMS,), *[(BELIEFS, key) for key in sorted(keys)]]
+
+    # ------------------------------------------------------------------
+    # writes
+    # ------------------------------------------------------------------
+
+    def _put(self, memory: RootMemory, op: Any) -> None:
+        if op.value is None:
+            # Memory is append-only: nothing is ever deleted (spec section 46).
+            raise ImmutableRecordError(
+                "RootMemory does not delete. Retract the underlying source instead, "
+                "which downgrades what was built on it and leaves the history intact."
+            )
+
+        namespace = op.namespace
+        root = namespace[0] if namespace else ""
+        value = dict(op.value)
+
+        if root == OBSERVATIONS:
+            observation = memory.create_observation(
+                source_type=str(value.get("source_type", "agent_input")),
+                content=str(value.get("content", "")),
+                source_actor=value.get("source_actor"),
+                source_uri=value.get("source_uri"),
+                created_by_agent_id=self.agent_id,
+                reliability_score=float(value.get("reliability_score", 1.0)),
+                source_family_id=value.get("source_family_id"),
+            )
+            self._note_read(observation.id)
+            return None
+
+        if root == BELIEFS:
+            claim_key = namespace[1] if len(namespace) > 1 else str(value.get("claim_key", ""))
+            if not claim_key:
+                raise ProvenanceRequiredError(
+                    "a belief needs a claim key: write to ('beliefs', '<claim_key>')"
+                )
+            parents = self._resolve_parents(memory, value)
+            if not parents:
+                raise ProvenanceRequiredError(
+                    "nothing to cite: this agent has not read any evidence, and no "
+                    "'derived_from' was supplied. Read from the store first, or pass "
+                    "derived_from explicitly."
+                )
+            belief = memory.create_belief(
+                agent_id=self.agent_id,
+                claim_text=str(value.get("content", value.get("text", ""))),
+                claim_key=claim_key,
+                confidence=float(value.get("confidence", 0.5)),
+                derived_from=parents,
+                llm_generated=bool(value.get("llm_generated", True)),
+                meta={"store_key": op.key},
+            )
+            claim_text = str(value.get("claim_text", claim_key))
+            claim = memory.get_or_create_claim(claim_key, claim_text)
+            if str(value.get("stance", "support")) == "contradict":
+                memory.contradict_claim(claim.id, belief.id)
+            else:
+                memory.support_claim(claim.id, belief.id)
+            return None
+
+        raise NotImplementedError(
+            f"writes to namespace {namespace!r} are not supported; use "
+            f"('{OBSERVATIONS}',) for evidence or ('{BELIEFS}', '<claim_key>') for a conclusion"
+        )
+
+    def _resolve_parents(self, memory: RootMemory, value: dict) -> list[Any]:
+        """What this write should cite.
+
+        An explicit ``derived_from`` always wins. Otherwise the agent cites what
+        it was actually shown, which is the honest reading of "where did this
+        come from".
+        """
+        explicit = value.get("derived_from")
+        if explicit:
+            ids = [_as_uuid(str(x)) for x in explicit]
+            missing = [x for x, parsed in zip(explicit, ids, strict=True) if parsed is None]
+            if missing:
+                raise NodeNotFoundError(f"derived_from contains unusable ids: {missing}")
+            candidates = [i for i in ids if i is not None]
+        elif self._auto_cite_reads:
+            candidates = list(self._reads[-self.max_cited_reads :])
+        else:
+            candidates = []
+
+        parents: list[Any] = []
+        for node_id in candidates:
+            observation = memory.observations.get(node_id)
+            if observation is not None:
+                parents.append(observation)
+                continue
+            belief = memory.find_belief(node_id)
+            if belief is not None:
+                parents.append(belief)
+            elif explicit:
+                raise NodeNotFoundError(f"no observation or belief with id {node_id}")
+        return parents
+
+    # ------------------------------------------------------------------
+    # values handed back to the agent
+    # ------------------------------------------------------------------
+
+    def _observation_value(self, observation: Any) -> dict[str, Any]:
+        return {
+            "kind": "observation",
+            "content": observation.content,
+            "source_type": observation.source_type,
+            "source_actor": observation.source_actor,
+            "validity_status": observation.validity_status,
+            "reliability_score": observation.reliability_score,
+        }
+
+    def _belief_value(self, memory: RootMemory, belief: Any) -> dict[str, Any]:
+        roots = memory.provenance.find_evidence_root_observations(NodeRef.belief(belief.id))
+        return {
+            "kind": "belief",
+            "content": belief.claim_text,
+            "claim_key": belief.normalized_claim_key,
+            "confidence": belief.confidence,
+            "status": belief.epistemic_status,
+            "held_by_agent_id": str(belief.agent_id),
+            # The agent is always told how much real evidence is underneath.
+            "independent_source_count": len({o.independence_key for o in roots}),
+            "evidence": [
+                {"source_type": o.source_type, "content": o.content, "status": o.validity_status}
+                for o in roots
+            ],
+        }
+
+    def _claim_value(self, memory: RootMemory, claim_id: uuid.UUID) -> dict[str, Any]:
+        context = memory.get_claim_context(claim_id)
+        payload: dict[str, Any] = dict(context.as_dict())
+        support: dict[str, Any] = payload["support"]
+        payload["warning"] = (
+            "agreement between agents is not evidence; judge this on independent_sources"
+        )
+        if context.support.shares_single_source:
+            payload["false_corroboration"] = (
+                f"{support['belief_count']} beliefs from {support['agreeing_agents']} agents "
+                "all descend from one source"
+            )
+        return payload
+
+    # ------------------------------------------------------------------
+
+    def _note_read(self, node_id: uuid.UUID) -> None:
+        if node_id in self._reads:
+            self._reads.remove(node_id)
+        self._reads.append(node_id)
+
+    def forget_reads(self) -> None:
+        """Clear the read history.
+
+        Call this between independent tasks so a new conclusion does not cite
+        evidence the agent looked at while doing something unrelated.
+        """
+        self._reads.clear()
+
+    @property
+    def cited_reads(self) -> list[uuid.UUID]:
+        """What the next write would cite, oldest first."""
+        return list(self._reads[-self.max_cited_reads :])
+
+
+def _item(namespace: tuple[str, ...], key: str, value: dict, base: Any) -> Item:
+    now = datetime.now(UTC)
+    return base.Item(
+        value=value, key=key, namespace=namespace, created_at=now, updated_at=now
+    )
+
+
+def _search_item(namespace: tuple[str, ...], key: str, value: dict, base: Any) -> SearchItem:
+    now = datetime.now(UTC)
+    return base.SearchItem(
+        namespace=namespace, key=key, value=value, created_at=now, updated_at=now
+    )
+
+
+def _as_uuid(value: str) -> uuid.UUID | None:
+    try:
+        return uuid.UUID(value)
+    except (ValueError, AttributeError, TypeError):
+        return None

rootmemory/logging_config.py

@@ -0,0 +1,30 @@
+"""Structured logging setup (spec section 50)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import structlog
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Configure structlog + stdlib logging once at process start."""
+    logging.basicConfig(format="%(message)s", level=getattr(logging, level.upper(), logging.INFO))
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            getattr(logging, level.upper(), logging.INFO)
+        ),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str, **initial: Any) -> Any:
+    """Return a bound structlog logger."""
+    return structlog.get_logger(name).bind(**initial)

rootmemory/main.py

@@ -0,0 +1,133 @@
+"""FastAPI application entry point."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, Request, Response
+from fastapi.responses import FileResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from rootmemory.api import ROUTERS
+from rootmemory.api.errors import register_error_handlers
+from rootmemory.api.security import require_api_key
+from rootmemory.config import get_settings
+from rootmemory.db.session import init_db
+from rootmemory.logging_config import configure_logging, get_logger
+from rootmemory.services.promotion_service import PromotionPolicy
+
+DESCRIPTION = """
+A provenance-aware memory layer for multi-agent AI systems.
+
+It prevents agents from mistaking repeated copies of the same inference for
+independent evidence: every belief is traced back to the observations it rests
+on, and only claims backed by enough *independent* sources enter shared memory.
+"""
+
+logger = get_logger("rootmemory.api")
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    settings = get_settings()
+    configure_logging(settings.log_level)
+    # Convenient for local/dev and SQLite; PostgreSQL deployments run Alembic.
+    init_db()
+    logger.info(
+        "startup",
+        database=settings.database_url.split("@")[-1],
+        policy=PromotionPolicy.from_settings(settings).as_dict(),
+        auth_enabled=settings.auth_enabled,
+        claim_normalization=settings.claim_normalization,
+    )
+    if not settings.auth_enabled:
+        logger.warning(
+            "auth_disabled",
+            detail=(
+                "No API_KEYS configured: every endpoint is open, including "
+                "observation invalidation. Set API_KEYS before exposing this."
+            ),
+        )
+    yield
+
+
+app = FastAPI(
+    title="RootMemory",
+    version="0.1.0",
+    description=DESCRIPTION,
+    lifespan=lifespan,
+)
+register_error_handlers(app)
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+for router in ROUTERS:
+    app.include_router(router, dependencies=[Depends(require_api_key)])
+
+
+@app.middleware("http")
+async def log_requests(
+    request: Request, call_next: Callable[[Request], Awaitable[Response]]
+) -> Response:
+    """Structured request logging (spec section 50)."""
+    request_id = str(uuid.uuid4())
+    started = time.perf_counter()
+    response = await call_next(request)
+    response.headers["X-Request-ID"] = request_id
+    logger.info(
+        "request",
+        request_id=request_id,
+        method=request.method,
+        path=request.url.path,
+        status_code=response.status_code,
+        duration_ms=round((time.perf_counter() - started) * 1000, 2),
+    )
+    return response
+
+
+@app.get("/", include_in_schema=False)
+def index() -> RedirectResponse:
+    return RedirectResponse("/ui")
+
+
+@app.get("/ui", tags=["meta"], include_in_schema=False)
+def portal() -> FileResponse:
+    """The visualization portal.
+
+    Served from the API itself so the page talks to the same origin and sees
+    whatever is in the configured database.
+    """
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+@app.get("/health", tags=["meta"])
+def health() -> dict[str, str]:
+    """Liveness. Deliberately does no database work and needs no API key, so a
+    load balancer can call it cheaply."""
+    return {"status": "ok"}
+
+
+@app.get("/ready", tags=["meta"])
+def ready() -> dict[str, object]:
+    """Readiness: verifies the database is actually reachable."""
+    from sqlalchemy import text as sql_text
+
+    from rootmemory.db.session import get_engine
+
+    try:
+        with get_engine().connect() as connection:
+            connection.execute(sql_text("SELECT 1"))
+    except Exception as exc:  # noqa: BLE001 - the probe reports, never raises
+        return {"status": "unavailable", "database": "unreachable", "detail": str(exc)}
+    return {"status": "ok", "database": "reachable"}
+
+
+@app.get("/policy", tags=["meta"])
+def policy() -> dict[str, object]:
+    """The promotion policy currently in force."""
+    return PromotionPolicy.from_settings().as_dict()

rootmemory/models/__init__.py

@@ -0,0 +1,22 @@
+"""ORM models. Importing this package registers every mapper."""
+
+from rootmemory.models.agent import Agent
+from rootmemory.models.audit import PromotionAudit, RepairReport
+from rootmemory.models.belief import Belief
+from rootmemory.models.claim import Claim, ClaimBeliefLink
+from rootmemory.models.decision import Decision, DecisionDependency
+from rootmemory.models.edge import ProvenanceEdge
+from rootmemory.models.observation import Observation
+
+__all__ = [
+    "Agent",
+    "Belief",
+    "Claim",
+    "ClaimBeliefLink",
+    "Decision",
+    "DecisionDependency",
+    "Observation",
+    "PromotionAudit",
+    "ProvenanceEdge",
+    "RepairReport",
+]

rootmemory/models/agent.py

@@ -0,0 +1,30 @@
+"""Agent registry (spec section 15)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Float, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+
+
+class Agent(Base):
+    """An actor that can create observations, beliefs and decisions.
+
+    ``trust_score`` is deliberately *not* used by the promotion gate. A trusted
+    agent can still repeat another agent's bad conclusion, so trust must never
+    stand in for provenance (spec section 15).
+    """
+
+    __tablename__ = "agents"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    name: Mapped[str] = mapped_column(String(200), unique=True, index=True)
+    role: Mapped[str] = mapped_column(String(200), default="")
+    description: Mapped[str] = mapped_column(String(2000), default="")
+    trust_score: Mapped[float] = mapped_column(Float, default=0.5)
+    created_at: Mapped[datetime] = timestamp_column()
+    meta: Mapped[dict] = json_column()

rootmemory/models/audit.py

@@ -0,0 +1,51 @@
+"""Audit records: every promotion decision and every repair is written down."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import JSON, Float, ForeignKey, Integer, String, Uuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+from rootmemory.db.base import Base, json_column, pk_column, timestamp_column
+
+
+class PromotionAudit(Base):
+    """Immutable record of one promotion evaluation (spec section 30).
+
+    Both agreement counts are stored, because the difference between them is
+    the whole point of the system (spec section 64).
+    """
+
+    __tablename__ = "promotion_audits"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    claim_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("claims.id"), index=True)
+    evaluated_at: Mapped[datetime] = timestamp_column()
+    supporting_belief_count: Mapped[int] = mapped_column(Integer, default=0)
+    agreeing_agent_count: Mapped[int] = mapped_column(Integer, default=0)
+    independent_support_count: Mapped[int] = mapped_column(Integer, default=0)
+    contradiction_count: Mapped[int] = mapped_column(Integer, default=0)
+    independent_contradiction_count: Mapped[int] = mapped_column(Integer, default=0)
+    aggregate_confidence: Mapped[float] = mapped_column(Float, default=0.0)
+    result: Mapped[str] = mapped_column(String(20), index=True)
+    reasons: Mapped[list] = mapped_column(JSON, default=list)
+    policy_version: Mapped[str] = mapped_column(String(50), default="v1")
+    policy_snapshot: Mapped[dict] = json_column()
+
+
+class RepairReport(Base):
+    """What a source invalidation touched (spec section 26)."""
+
+    __tablename__ = "repair_reports"
+
+    id: Mapped[uuid.UUID] = pk_column()
+    trigger_node_id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), index=True)
+    trigger_node_type: Mapped[str] = mapped_column(String(20), default="observation")
+    trigger_reason: Mapped[str] = mapped_column(String(2000), default="")
+    affected_beliefs: Mapped[list] = mapped_column(JSON, default=list)
+    affected_claims: Mapped[list] = mapped_column(JSON, default=list)
+    affected_decisions: Mapped[list] = mapped_column(JSON, default=list)
+    details: Mapped[dict] = json_column()
+    created_at: Mapped[datetime] = timestamp_column()