rootmemory 0.1.0__py3-none-any.whl

rootmemory/integrations/async_client.py

@@ -0,0 +1,268 @@
+"""An async face on the memory layer.
+
+LangGraph, LangChain and most agent runtimes are async. The memory core is
+synchronous SQLAlchemy, so every call here is handed to a worker thread. That
+is the right trade for this workload: the calls are short database operations,
+not long ones, and it keeps a single well-tested code path instead of a second
+async ORM stack that could drift from it.
+
+Each call runs in its own session and commits, so a crashed agent step cannot
+leave a half-written belief behind.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+from sqlalchemy.orm import Session
+
+from rootmemory.client import RootMemory
+from rootmemory.db.session import get_session_factory
+from rootmemory.models.enums import EpistemicStatus
+from rootmemory.services.promotion_service import PromotionPolicy
+
+T = TypeVar("T")
+
+#: Ids arrive as strings as often as UUIDs here: LangGraph checkpoints state as
+#: JSON, and this client hands ids back as strings so they survive that trip.
+#: Coercing at the boundary means callers never have to think about it.
+IdLike = uuid.UUID | str
+
+
+def as_uuid(value: IdLike) -> uuid.UUID:
+    """Accept either form of id and return a UUID."""
+    if isinstance(value, uuid.UUID):
+        return value
+    try:
+        return uuid.UUID(str(value))
+    except (ValueError, AttributeError, TypeError) as exc:
+        raise ValueError(f"not a valid id: {value!r}") from exc
+
+
+class AsyncRootMemory:
+    """Async wrapper over :class:`RootMemory`.
+
+    Returns plain dictionaries rather than ORM objects, because framework state
+    has to be serializable - LangGraph checkpoints it, and a detached ORM
+    instance would not survive that.
+    """
+
+    def __init__(
+        self,
+        session_factory: Callable[[], Session] | None = None,
+        policy: PromotionPolicy | None = None,
+    ) -> None:
+        self._session_factory = session_factory or get_session_factory()
+        self._policy = policy
+
+    async def _run(self, work: Callable[[RootMemory], T]) -> T:
+        def call() -> T:
+            session = self._session_factory()
+            try:
+                result = work(RootMemory(session, self._policy))
+                session.commit()
+                return result
+            except Exception:
+                session.rollback()
+                raise
+            finally:
+                session.close()
+
+        return await asyncio.to_thread(call)
+
+    # ------------------------------------------------------------------
+    # agents and evidence
+    # ------------------------------------------------------------------
+
+    async def register_agent(self, name: str, role: str = "") -> uuid.UUID:
+        """Register an agent and return its id. Idempotent on name."""
+        return await self._run(lambda m: m.register_agent(name, role).id)
+
+    async def record_observation(
+        self,
+        source_type: str,
+        content: str,
+        source_uri: str | None = None,
+        source_actor: str | None = None,
+        reliability_score: float = 1.0,
+        source_family_id: str | None = None,
+    ) -> uuid.UUID:
+        """Record something that entered from outside: a tool result, a
+        retrieved document, a user message."""
+        return await self._run(
+            lambda m: m.create_observation(
+                source_type=source_type,
+                content=content,
+                source_uri=source_uri,
+                source_actor=source_actor,
+                reliability_score=reliability_score,
+                source_family_id=source_family_id,
+            ).id
+        )
+
+    # ------------------------------------------------------------------
+    # beliefs
+    # ------------------------------------------------------------------
+
+    async def record_belief(
+        self,
+        agent_id: IdLike,
+        text: str,
+        claim_key: str | None,
+        confidence: float,
+        derived_from: Sequence[IdLike],
+        llm_generated: bool = True,
+        meta: dict | None = None,
+    ) -> uuid.UUID:
+        """Record what an agent concluded, citing everything it read.
+
+        ``derived_from`` may mix observation and belief ids; the type of each
+        parent is resolved here so callers do not have to track it.
+
+        Raises ProvenanceRequiredError if nothing is cited - which is the whole
+        point. An agent cannot contribute an opinion without saying where it
+        came from.
+        """
+
+        agent = as_uuid(agent_id)
+        parent_ids = [as_uuid(node_id) for node_id in derived_from]
+
+        def work(memory: RootMemory) -> uuid.UUID:
+            parents = [_resolve(memory, node_id) for node_id in parent_ids]
+            return memory.create_belief(
+                agent_id=agent,
+                claim_text=text,
+                claim_key=claim_key,
+                confidence=confidence,
+                derived_from=parents,
+                epistemic_status=EpistemicStatus.INFERRED,
+                llm_generated=llm_generated,
+                meta=meta,
+            ).id
+
+        return await self._run(work)
+
+    async def belief(self, belief_id: IdLike) -> dict[str, Any]:
+        """Read one belief back, as another agent would see it."""
+
+        node_id = as_uuid(belief_id)
+
+        def work(memory: RootMemory) -> dict[str, Any]:
+            found = memory.get_belief(node_id)
+            return {
+                "id": str(found.id),
+                "text": found.claim_text,
+                "claim_key": found.normalized_claim_key,
+                "confidence": found.confidence,
+                "status": found.epistemic_status,
+                "agent_id": str(found.agent_id),
+            }
+
+        return await self._run(work)
+
+    async def evidence_roots(self, belief_id: IdLike) -> list[dict[str, Any]]:
+        """The observations a belief ultimately rests on."""
+
+        node_id = as_uuid(belief_id)
+
+        def work(memory: RootMemory) -> list[dict[str, Any]]:
+            belief = memory.get_belief(node_id)
+            return [
+                {
+                    "id": str(o.id),
+                    "source_type": o.source_type,
+                    "content": o.content,
+                    "validity_status": o.validity_status,
+                }
+                for o in memory.evidence_roots(belief)
+            ]
+
+        return await self._run(work)
+
+    # ------------------------------------------------------------------
+    # claims
+    # ------------------------------------------------------------------
+
+    async def claim(self, claim_key: str, text: str) -> uuid.UUID:
+        return await self._run(lambda m: m.get_or_create_claim(claim_key, text).id)
+
+    async def support(self, claim_id: IdLike, belief_id: IdLike) -> None:
+        claim, belief = as_uuid(claim_id), as_uuid(belief_id)
+        await self._run(lambda m: m.support_claim(claim, belief))
+
+    async def contradict(self, claim_id: IdLike, belief_id: IdLike) -> None:
+        claim, belief = as_uuid(claim_id), as_uuid(belief_id)
+        await self._run(lambda m: m.contradict_claim(claim, belief))
+
+    async def claim_context(self, claim_id: IdLike) -> dict[str, Any]:
+        """What an agent should read instead of a bare fact: both sides, with
+        agreement and independent-evidence counts kept apart."""
+        claim = as_uuid(claim_id)
+        return await self._run(lambda m: m.get_claim_context(claim).as_dict())
+
+    async def evaluate(self, claim_id: IdLike) -> dict[str, Any]:
+        """Run the promotion gate without changing anything."""
+        claim = as_uuid(claim_id)
+        return await self._run(lambda m: m.evaluate_claim(claim).as_dict())
+
+    async def promote(self, claim_id: IdLike) -> dict[str, Any]:
+        """Attempt to move a claim into shared memory."""
+        claim = as_uuid(claim_id)
+        return await self._run(lambda m: m.promote_claim(claim).as_dict())
+
+    async def safe_to_act(self, claim_id: IdLike) -> bool:
+        """True only when the claim passes the gate on independent evidence."""
+        verdict = await self.evaluate(claim_id)
+        return bool(verdict["decision"] == "promote")
+
+    # ------------------------------------------------------------------
+    # decisions and repair
+    # ------------------------------------------------------------------
+
+    async def record_decision(
+        self,
+        agent_id: IdLike,
+        decision_type: str,
+        content: str,
+        depends_on: Sequence[IdLike] = (),
+        meta: dict | None = None,
+    ) -> uuid.UUID:
+        """Record an action and the claims it rests on, so a later retraction
+        can flag it."""
+
+        agent = as_uuid(agent_id)
+        claim_ids = [as_uuid(c) for c in depends_on]
+
+        def work(memory: RootMemory) -> uuid.UUID:
+            return memory.decision_service.create_decision(
+                agent_id=agent,
+                decision_type=decision_type,
+                content=content,
+                claim_ids=claim_ids,
+                meta=meta,
+            ).id
+
+        return await self._run(work)
+
+    async def retract_source(self, observation_id: IdLike, reason: str) -> dict[str, Any]:
+        """Invalidate a source and repair everything built on it."""
+        node_id = as_uuid(observation_id)
+        return await self._run(
+            lambda m: m.invalidate_observation(node_id, reason).as_dict()
+        )
+
+
+def _resolve(memory: RootMemory, node_id: uuid.UUID):  # type: ignore[no-untyped-def]
+    """Look up a parent by id without the caller having to say what it is."""
+    observation = memory.observations.get(node_id)
+    if observation is not None:
+        return observation
+    belief = memory.find_belief(node_id)
+    if belief is not None:
+        return belief
+    from rootmemory.errors import NodeNotFoundError
+
+    raise NodeNotFoundError(f"no observation or belief with id {node_id}")

rootmemory/integrations/langchain_tools.py

@@ -0,0 +1,237 @@
+"""LangChain tool adapter.
+
+LangChain's tool interface is the closest thing the ecosystem has to a common
+plug: CrewAI, AutoGen's tool bridge, LangGraph's prebuilt agents and anything
+built on `bind_tools` all accept it. Exposing the memory as tools therefore
+covers far more than LangChain itself.
+
+    from rootmemory.integrations.langchain_tools import build_tools
+    tools = build_tools(memory, agent_id)
+    model = ChatAnthropic(model="claude-sonnet-4-5").bind_tools(tools)
+
+The tools are deliberately shaped so an LLM cannot record an opinion without
+citing something: ``record_belief`` requires ``derived_from``, and the memory
+layer rejects the call if it is empty.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+from rootmemory.integrations.async_client import AsyncRootMemory
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from langchain_core.tools import BaseTool
+
+
+def _require_langchain() -> Any:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ModuleNotFoundError as exc:  # pragma: no cover - environment dependent
+        raise ModuleNotFoundError(
+            "LangChain tools need langchain-core. Install it with: "
+            'pip install "rootmemory[langchain]"'
+        ) from exc
+    return StructuredTool
+
+
+# ----------------------------------------------------------------------
+# argument schemas - these become the tool signatures the model sees
+# ----------------------------------------------------------------------
+
+
+class RecordObservationArgs(BaseModel):
+    source_type: str = Field(description="Where this came from: email, api, document, web...")
+    content: str = Field(description="The evidence itself, quoted as received.")
+    source_actor: str | None = Field(
+        default=None, description="Who or what produced it, if known."
+    )
+    reliability_score: float = Field(
+        default=1.0, ge=0.0, le=1.0, description="How much this source can be trusted."
+    )
+
+
+class RecordBeliefArgs(BaseModel):
+    text: str = Field(description="What you have concluded.")
+    claim_key: str = Field(description="Short stable key naming the proposition.")
+    confidence: float = Field(ge=0.0, le=1.0, description="How strongly you hold it.")
+    derived_from: list[str] = Field(
+        description=(
+            "REQUIRED. Ids of every observation or belief you read to reach this. "
+            "If you read another agent's belief, cite that belief - not the evidence "
+            "underneath it."
+        ),
+    )
+
+
+class ClaimArgs(BaseModel):
+    claim_key: str = Field(description="Short stable key naming the proposition.")
+    text: str = Field(description="The proposition in plain language.")
+
+
+class LinkArgs(BaseModel):
+    claim_id: str = Field(description="Id of the claim.")
+    belief_id: str = Field(description="Id of the belief.")
+
+
+class ClaimIdArgs(BaseModel):
+    claim_id: str = Field(description="Id of the claim.")
+
+
+class BeliefIdArgs(BaseModel):
+    belief_id: str = Field(description="Id of the belief.")
+
+
+# ----------------------------------------------------------------------
+
+
+def build_tools(
+    memory: AsyncRootMemory,
+    agent_id: uuid.UUID,
+    include_write_tools: bool = True,
+) -> list[BaseTool]:
+    """Build the memory toolset for one agent.
+
+    Set ``include_write_tools=False`` for an agent that should only read shared
+    memory and never contribute to it.
+    """
+    StructuredTool = _require_langchain()
+
+    async def record_observation(**kwargs: Any) -> str:
+        return str(await memory.record_observation(**kwargs))
+
+    async def record_belief(
+        text: str, claim_key: str, confidence: float, derived_from: list[str]
+    ) -> str:
+        belief_id = await memory.record_belief(
+            agent_id=agent_id,
+            text=text,
+            claim_key=claim_key,
+            confidence=confidence,
+            derived_from=[uuid.UUID(x) for x in derived_from],
+        )
+        return str(belief_id)
+
+    async def open_claim(claim_key: str, text: str) -> str:
+        return str(await memory.claim(claim_key, text))
+
+    async def support_claim(claim_id: str, belief_id: str) -> str:
+        await memory.support(uuid.UUID(claim_id), uuid.UUID(belief_id))
+        return "recorded as support"
+
+    async def contradict_claim(claim_id: str, belief_id: str) -> str:
+        await memory.contradict(uuid.UUID(claim_id), uuid.UUID(belief_id))
+        return "recorded as a contradiction"
+
+    async def read_claim(claim_id: str) -> str:
+        context = await memory.claim_context(uuid.UUID(claim_id))
+        support = context["support"]
+        against = context["contradictions"]
+        return (
+            f"Claim: {context['claim']}\n"
+            f"Status: {context['status']}\n"
+            f"Support: {support['belief_count']} beliefs from "
+            f"{support['agreeing_agents']} agents, but only "
+            f"{support['independent_sources']} INDEPENDENT source(s), "
+            f"confidence {support['confidence']}\n"
+            f"Against: {against['belief_count']} beliefs from "
+            f"{against['independent_sources']} independent source(s), "
+            f"confidence {against['confidence']}\n"
+            "Agreement between agents is not evidence. Judge this on the "
+            "independent source counts."
+        )
+
+    async def check_claim(claim_id: str) -> str:
+        verdict = await memory.evaluate(uuid.UUID(claim_id))
+        return (
+            f"{verdict['decision'].upper()}: {verdict['explanation']} "
+            f"({verdict['agreeing_agents']} agents, "
+            f"{verdict['independent_support_count']} independent source(s))"
+        )
+
+    async def trace_belief(belief_id: str) -> str:
+        roots = await memory.evidence_roots(uuid.UUID(belief_id))
+        if not roots:
+            return "This belief rests on no valid evidence at all."
+        lines = [
+            f"- [{r['validity_status']}] {r['source_type']}: {r['content'][:120]}" for r in roots
+        ]
+        return f"Rests on {len(roots)} observation(s):\n" + "\n".join(lines)
+
+    read_tools = [
+        StructuredTool.from_function(
+            coroutine=read_claim,
+            name="read_claim",
+            description=(
+                "Read what is currently believed about a claim. Returns both sides with "
+                "the number of INDEPENDENT evidence sources, which is not the same as "
+                "the number of agents who agree."
+            ),
+            args_schema=ClaimIdArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=check_claim,
+            name="check_claim_is_safe_to_act_on",
+            description=(
+                "Ask whether a claim has enough independent evidence behind it to act on. "
+                "Use this before taking any consequential action."
+            ),
+            args_schema=ClaimIdArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=trace_belief,
+            name="trace_belief_to_evidence",
+            description=(
+                "Trace a belief back to the original observations it rests on, so you can "
+                "tell first-hand evidence from a repeated conclusion."
+            ),
+            args_schema=BeliefIdArgs,
+        ),
+    ]
+
+    if not include_write_tools:
+        return read_tools
+
+    return [
+        StructuredTool.from_function(
+            coroutine=record_observation,
+            name="record_observation",
+            description=(
+                "Record evidence that came from outside: a document, an API result, a "
+                "user message. Returns the observation id, which you must cite when you "
+                "later draw a conclusion from it."
+            ),
+            args_schema=RecordObservationArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=record_belief,
+            name="record_belief",
+            description=(
+                "Record a conclusion. You MUST cite in derived_from every observation or "
+                "belief you read to reach it. A conclusion with nothing cited is rejected."
+            ),
+            args_schema=RecordBeliefArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=open_claim,
+            name="open_claim",
+            description="Create or fetch the claim that beliefs argue about.",
+            args_schema=ClaimArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=support_claim,
+            name="support_claim",
+            description="Attach one of your beliefs to a claim as support.",
+            args_schema=LinkArgs,
+        ),
+        StructuredTool.from_function(
+            coroutine=contradict_claim,
+            name="contradict_claim",
+            description="Attach one of your beliefs to a claim as a contradiction.",
+            args_schema=LinkArgs,
+        ),
+        *read_tools,
+    ]

rootmemory/integrations/langgraph_memory.py

@@ -0,0 +1,179 @@
+"""LangGraph adapter.
+
+The hard part of wiring provenance into a graph framework is not the API - it
+is that state must carry *what a node read*, not just text. A node returning
+``{"analysis": "supplier is unstable"}`` has thrown away the fact that it was
+reading a colleague rather than a document, and that is exactly the fact the
+memory layer needs.
+
+``MemoryState`` carries belief ids alongside the text, and ``remembering()``
+wraps an ordinary node so the citation happens automatically: whatever ids were
+in state when the node ran become the parents of whatever it concluded.
+
+Usage::
+
+    graph = StateGraph(MemoryState)
+    graph.add_node("research", remembering(memory, research_agent_id,
+                                           claim_key="supplier_risk")(research))
+    graph.add_node("risk", remembering(memory, risk_agent_id,
+                                       claim_key="supplier_risk")(assess))
+
+Each wrapped node returns ``{"text": ..., "confidence": ...}`` and the wrapper
+adds ``belief_id`` and appends to ``belief_ids``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Annotated, Any, TypedDict
+
+from rootmemory.integrations.async_client import AsyncRootMemory
+
+
+def keep_last(_current: Any, incoming: Any) -> Any:
+    """Reducer: last write wins."""
+    return incoming
+
+
+def append_unique(current: list[Any] | None, incoming: list[Any] | Any) -> list[Any]:
+    """Reducer: accumulate ids across nodes without duplicating them.
+
+    LangGraph merges state per key, so this is what lets a node see everything
+    produced upstream of it.
+    """
+    merged = list(current or [])
+    items = incoming if isinstance(incoming, list) else [incoming]
+    for item in items:
+        if item is not None and item not in merged:
+            merged.append(item)
+    return merged
+
+
+class MemoryState(TypedDict, total=False):
+    """State that remembers where its contents came from.
+
+    ``belief_ids`` accumulates every belief produced so far in the run, which
+    is what a downstream node cites. ``observation_ids`` does the same for
+    evidence pulled in from outside.
+    """
+
+    text: Annotated[str, keep_last]
+    confidence: Annotated[float, keep_last]
+    belief_id: Annotated[uuid.UUID | None, keep_last]
+    belief_ids: Annotated[list[uuid.UUID], append_unique]
+    observation_ids: Annotated[list[uuid.UUID], append_unique]
+    claim_id: Annotated[uuid.UUID | None, keep_last]
+    verdict: Annotated[dict, keep_last]
+
+
+#: A node is any async callable taking state and returning a partial update.
+Node = Callable[[dict], Awaitable[dict]]
+
+
+def remembering(
+    memory: AsyncRootMemory,
+    agent_id: uuid.UUID,
+    claim_key: str,
+    *,
+    stance: str = "support",
+    cite: str = "all",
+) -> Callable[[Node], Node]:
+    """Wrap a node so whatever it concludes is recorded with its provenance.
+
+    ``cite`` controls what the new belief points at:
+
+    ``"all"``   everything upstream - every belief and observation in state.
+    ``"latest"`` only the immediately preceding belief, which is the honest
+                model of an agent that read one colleague's output.
+
+    The wrapped node returns its own ``{"text": ..., "confidence": ...}``; the
+    wrapper adds the belief id and, when the state carries a ``claim_id``,
+    attaches the belief to that claim.
+    """
+    if cite not in {"all", "latest"}:
+        raise ValueError("cite must be 'all' or 'latest'")
+
+    def decorate(node: Node) -> Node:
+        @wraps(node)
+        async def wrapper(state: dict) -> dict:
+            update = await node(state)
+            text = update.get("text")
+            if text is None:
+                # The node did not conclude anything; nothing to remember.
+                return update
+
+            parents = _parents(state, cite)
+            if not parents:
+                raise ValueError(
+                    f"node {node.__name__!r} produced a conclusion with nothing to cite; "
+                    "put an observation id in state before the first reasoning node"
+                )
+
+            belief_id = await memory.record_belief(
+                agent_id=agent_id,
+                text=text,
+                claim_key=claim_key,
+                confidence=float(update.get("confidence", 0.5)),
+                derived_from=parents,
+                llm_generated=bool(update.get("llm_generated", True)),
+                meta={"node": node.__name__},
+            )
+
+            claim_id = state.get("claim_id")
+            if claim_id is not None:
+                if stance == "contradict":
+                    await memory.contradict(claim_id, belief_id)
+                else:
+                    await memory.support(claim_id, belief_id)
+
+            return {**update, "belief_id": belief_id, "belief_ids": [belief_id]}
+
+        return wrapper
+
+    return decorate
+
+
+def _parents(state: dict, cite: str) -> list[uuid.UUID]:
+    if cite == "latest":
+        latest = state.get("belief_id")
+        if latest is not None:
+            return [latest]
+        # Nothing upstream yet: fall back to the evidence in state.
+        return list(state.get("observation_ids") or [])
+    return [*(state.get("belief_ids") or []), *(state.get("observation_ids") or [])]
+
+
+async def observe_into_state(
+    memory: AsyncRootMemory,
+    source_type: str,
+    content: str,
+    **kwargs: Any,
+) -> dict:
+    """Pull evidence in from outside and put it in state.
+
+    Use this as the entry node of a graph, so later nodes have something
+    legitimate to cite.
+    """
+    observation_id = await memory.record_observation(source_type, content, **kwargs)
+    return {"observation_ids": [observation_id]}
+
+
+async def gate(memory: AsyncRootMemory, state: dict) -> dict:
+    """A node that runs the promotion gate and puts the verdict in state.
+
+    Route on ``state["verdict"]["decision"]`` to stop a graph from acting on a
+    claim that only looks corroborated.
+    """
+    claim_id = state.get("claim_id")
+    if claim_id is None:
+        raise ValueError("gate() needs a claim_id in state")
+    return {"verdict": await memory.evaluate(claim_id)}
+
+
+def route_on_verdict(state: dict, *, on_promote: str, on_reject: str) -> str:
+    """Conditional-edge helper: send the graph one way or the other depending
+    on whether the evidence is genuinely independent."""
+    verdict = state.get("verdict") or {}
+    return on_promote if verdict.get("decision") == "promote" else on_reject