rootmemory 0.1.0__py3-none-any.whl

rootmemory/cli.py

@@ -0,0 +1,96 @@
+"""The ``rootmemory`` command.
+
+    rootmemory version
+    rootmemory demo             run the four scenarios against a naive baseline
+    rootmemory serve            start the API and the portal
+    rootmemory policy           show the promotion policy in force
+
+Kept deliberately thin: the API and the demo are optional extras, so this
+imports them lazily and explains what to install if they are missing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _missing(extra: str, what: str) -> int:
+    print(f"{what} needs the optional '{extra}' extra:", file=sys.stderr)
+    print(f'    pip install "rootmemory[{extra}]"', file=sys.stderr)
+    return 1
+
+
+def cmd_version() -> int:
+    from rootmemory import __version__
+
+    print(f"rootmemory {__version__}")
+    return 0
+
+
+def cmd_policy() -> int:
+    import json
+
+    from rootmemory.services.promotion_service import PromotionPolicy
+
+    print(json.dumps(PromotionPolicy.from_settings().as_dict(), indent=2))
+    return 0
+
+
+def cmd_serve(host: str, port: int, reload: bool) -> int:
+    try:
+        import uvicorn
+    except ModuleNotFoundError:
+        return _missing("api", "serve")
+
+    uvicorn.run("rootmemory.main:app", host=host, port=port, reload=reload)
+    return 0
+
+
+def cmd_demo() -> int:
+    try:
+        from experiments.run_demo import main as run_demo
+    except ModuleNotFoundError:
+        print(
+            "The demo scenarios ship with the source repository, not the wheel.\n"
+            "Clone it to run them:\n"
+            "    git clone https://github.com/Shubs5758/RootMemory",
+            file=sys.stderr,
+        )
+        return 1
+    return int(run_demo([]))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="rootmemory",
+        description="Provenance-aware memory for multi-agent AI systems.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("version", help="print the installed version")
+    sub.add_parser("policy", help="print the promotion policy in force")
+    sub.add_parser("demo", help="run the demo scenarios (source checkout only)")
+
+    serve = sub.add_parser("serve", help="start the API and the portal at /ui")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8000)
+    serve.add_argument("--reload", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        return cmd_version()
+    if args.command == "policy":
+        return cmd_policy()
+    if args.command == "demo":
+        return cmd_demo()
+    if args.command == "serve":
+        return cmd_serve(args.host, args.port, args.reload)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rootmemory/client.py

@@ -0,0 +1,219 @@
+"""RootMemory: the interface agents use (spec section 48).
+
+Agents never touch the database or the ORM. They go through this façade, which
+keeps the memory layer framework-agnostic: the same client works for a plain
+Python agent, a LangGraph node or a CrewAI worker.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+
+from sqlalchemy.orm import Session
+
+from rootmemory.errors import NodeNotFoundError
+from rootmemory.models.agent import Agent
+from rootmemory.models.belief import Belief
+from rootmemory.models.claim import Claim
+from rootmemory.models.decision import Decision
+from rootmemory.models.enums import EpistemicStatus, NodeType, ValidityStatus
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.models.observation import Observation
+from rootmemory.repositories.agent_repo import AgentRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.decision_repo import DecisionRepository
+from rootmemory.repositories.observation_repo import ObservationRepository
+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.invalidation_service import InvalidationService, RepairSummary
+from rootmemory.services.promotion_service import (
+    PromotionEvaluation,
+    PromotionPolicy,
+    PromotionService,
+)
+from rootmemory.services.provenance_service import ProvenanceService
+
+
+class RootMemory:
+    """A thin, typed API over the memory services."""
+
+    def __init__(self, session: Session, policy: PromotionPolicy | None = None) -> None:
+        self.session = session
+        self.agents = AgentRepository(session)
+        self.observations = ObservationRepository(session)
+        self.claims = ClaimRepository(session)
+        self.decisions = DecisionRepository(session)
+        self.decision_service = DecisionService(session)
+        self.beliefs = BeliefService(session)
+        self.provenance = ProvenanceService(session)
+        self.contradictions = ContradictionService(session)
+        self.promotion = PromotionService(session, policy)
+        self.invalidation = InvalidationService(session, policy)
+
+    # ------------------------------------------------------------------
+    # agents
+    # ------------------------------------------------------------------
+
+    def register_agent(
+        self, name: str, role: str = "", description: str = "", trust_score: float = 0.5
+    ) -> Agent:
+        existing = self.agents.get_by_name(name)
+        if existing is not None:
+            return existing
+        return self.agents.create(
+            name=name, role=role, description=description, trust_score=trust_score
+        )
+
+    # ------------------------------------------------------------------
+    # evidence
+    # ------------------------------------------------------------------
+
+    def create_observation(
+        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,
+        meta: dict | None = None,
+    ) -> Observation:
+        """Record a piece of external evidence."""
+        return self.observations.create(
+            source_type=source_type,
+            content=content,
+            source_uri=source_uri,
+            source_actor=source_actor,
+            created_by_agent_id=created_by_agent_id,
+            reliability_score=reliability_score,
+            source_family_id=source_family_id,
+            meta=meta or {},
+        )
+
+    def invalidate_observation(self, observation_id: uuid.UUID, reason: str) -> RepairSummary:
+        """Retract a source and repair everything downstream."""
+        return self.invalidation.invalidate_observation(observation_id, reason)
+
+    # ------------------------------------------------------------------
+    # beliefs
+    # ------------------------------------------------------------------
+
+    def create_belief(
+        self,
+        agent_id: uuid.UUID,
+        claim_text: str,
+        claim_key: str | None,
+        confidence: float,
+        derived_from: Sequence[Observation | Belief],
+        epistemic_status: EpistemicStatus = EpistemicStatus.INFERRED,
+        llm_generated: bool = False,
+        meta: dict | None = None,
+    ) -> Belief:
+        """Form a belief from observations and/or other beliefs.
+
+        ``derived_from`` takes model instances so callers cannot forget to say
+        which type each parent is.
+
+        ``claim_key`` may be None, in which case the configured normalizer
+        works out which proposition this belief is about.
+        """
+        parents = [ParentSpec(id=node.id, type=_node_type_of(node)) for node in derived_from]
+        return self.beliefs.create_belief(
+            agent_id=agent_id,
+            claim_text=claim_text,
+            normalized_claim_key=claim_key,
+            confidence=confidence,
+            parents=parents,
+            epistemic_status=epistemic_status,
+            llm_generated=llm_generated,
+            meta=meta,
+        )
+
+    def get_belief(self, belief_id: uuid.UUID) -> Belief:
+        belief = self.beliefs.beliefs.get(belief_id)
+        if belief is None:
+            raise NodeNotFoundError(f"belief {belief_id} does not exist")
+        return belief
+
+    def find_belief(self, belief_id: uuid.UUID) -> Belief | None:
+        """Look a belief up without raising when it is absent."""
+        return self.beliefs.beliefs.get(belief_id)
+
+    def list_beliefs(self) -> Sequence[Belief]:
+        """Every belief, oldest first."""
+        return self.beliefs.beliefs.list()
+
+    def propose_shared_belief(self, belief_id: uuid.UUID) -> Belief:
+        """Submit a private belief as a candidate for shared memory."""
+        return self.beliefs.submit_for_promotion(belief_id)
+
+    def evidence_roots(self, belief: Belief) -> list[Observation]:
+        """The observations a belief ultimately rests on."""
+        return self.provenance.find_evidence_root_observations(NodeRef.belief(belief.id))
+
+    # ------------------------------------------------------------------
+    # claims
+    # ------------------------------------------------------------------
+
+    def get_or_create_claim(self, claim_key: str, canonical_text: str) -> Claim:
+        return self.claims.get_or_create(claim_key, canonical_text)
+
+    def support_claim(self, claim_id: uuid.UUID, belief_id: uuid.UUID) -> None:
+        self.contradictions.register_support(claim_id, belief_id)
+
+    def contradict_claim(self, claim_id: uuid.UUID, belief_id: uuid.UUID) -> None:
+        self.contradictions.register_contradiction(claim_id, belief_id)
+
+    def get_claim_context(self, claim_id: uuid.UUID) -> ClaimContext:
+        """Read a claim the honest way: both sides, with independence counts."""
+        return self.contradictions.build_context(claim_id)
+
+    def evaluate_claim(self, claim_id: uuid.UUID) -> PromotionEvaluation:
+        """Run the promotion gate without changing the claim."""
+        return self.promotion.evaluate(claim_id)
+
+    def promote_claim(self, claim_id: uuid.UUID) -> PromotionEvaluation:
+        """Attempt promotion into shared memory. Always re-evaluates."""
+        return self.promotion.promote(claim_id)
+
+    # ------------------------------------------------------------------
+    # decisions
+    # ------------------------------------------------------------------
+
+    def create_decision(
+        self,
+        agent_id: uuid.UUID,
+        decision_type: str,
+        content: str,
+        depends_on_claims: Sequence[Claim] = (),
+        meta: dict | None = None,
+    ) -> Decision:
+        """Record a decision and the claims it rests on."""
+        return self.decision_service.create_decision(
+            agent_id=agent_id,
+            decision_type=decision_type,
+            content=content,
+            claim_ids=[claim.id for claim in depends_on_claims],
+            meta=meta,
+        )
+
+    # ------------------------------------------------------------------
+    # misc
+    # ------------------------------------------------------------------
+
+    def observation_status(self, observation_id: uuid.UUID) -> ValidityStatus:
+        observation = self.observations.get(observation_id)
+        if observation is None:
+            raise NodeNotFoundError(f"observation {observation_id} does not exist")
+        return ValidityStatus(observation.validity_status)
+
+
+def _node_type_of(node: Observation | Belief) -> NodeType:
+    if isinstance(node, Observation):
+        return NodeType.OBSERVATION
+    if isinstance(node, Belief):
+        return NodeType.BELIEF
+    raise TypeError(f"a belief cannot be derived from {type(node).__name__}")

rootmemory/config.py

@@ -0,0 +1,64 @@
+"""Application configuration.
+
+Every knob that changes epistemic behaviour (the promotion policy) is exposed
+here so experiments can vary it without touching service code.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime settings, read from the environment and an optional .env file."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # Default is SQLite so the demo, the tests and a fresh clone all run with no
+    # infrastructure. docker-compose / .env point this at PostgreSQL.
+    database_url: str = "sqlite+pysqlite:///./rootmemory.db"
+    sql_echo: bool = False
+    log_level: str = "INFO"
+
+    promotion_min_independent_support: int = Field(default=2, ge=1)
+    promotion_min_confidence: float = Field(default=0.75, ge=0.0, le=1.0)
+    promotion_max_high_confidence_contradictions: int = Field(default=0, ge=0)
+    promotion_contradiction_confidence_threshold: float = Field(default=0.75, ge=0.0, le=1.0)
+    promotion_policy_version: str = "v1"
+
+    # Comma-separated. Empty means authentication is disabled, which is the
+    # right default for local development and the wrong one on a network.
+    api_keys: str = ""
+
+    # Claim normalization: how free-text beliefs are mapped onto a claim key.
+    # "manual"        - the caller always supplies claim_key (V1 behaviour)
+    # "deterministic" - derive a slug from the text, no LLM
+    # "llm"           - ask a model to match an existing claim, with the
+    #                   deterministic slug as the fallback
+    claim_normalization: Literal["manual", "deterministic", "llm"] = "manual"
+
+    openai_api_key: str | None = None
+    openai_model: str | None = None
+    openai_base_url: str | None = None
+
+    @property
+    def is_sqlite(self) -> bool:
+        return self.database_url.startswith("sqlite")
+
+    @property
+    def api_key_list(self) -> list[str]:
+        return [key.strip() for key in self.api_keys.split(",") if key.strip()]
+
+    @property
+    def auth_enabled(self) -> bool:
+        """Authentication is on exactly when at least one key is configured."""
+        return bool(self.api_key_list)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

rootmemory/db/base.py

@@ -0,0 +1,42 @@
+"""Declarative base and shared column helpers."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, DateTime, MetaData, Uuid
+from sqlalchemy.orm import DeclarativeBase, mapped_column
+
+NAMING_CONVENTION = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    """Base class for every ORM model."""
+
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+def utcnow() -> datetime:
+    """Timezone-aware 'now'. Used as a Python-side default so behaviour is
+    identical on SQLite and PostgreSQL."""
+    return datetime.now(UTC)
+
+
+def pk_column():  # type: ignore[no-untyped-def]
+    """UUID primary key, generated client-side so callers know the id up front."""
+    return mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+
+
+def timestamp_column(**kwargs):  # type: ignore[no-untyped-def]
+    return mapped_column(DateTime(timezone=True), default=utcnow, **kwargs)
+
+
+def json_column(**kwargs):  # type: ignore[no-untyped-def]
+    return mapped_column(JSON, default=dict, **kwargs)

rootmemory/db/migrations/env.py

@@ -0,0 +1,59 @@
+"""Alembic environment.
+
+The database URL comes from the application settings, so migrations and the
+running app can never drift apart.
+"""
+
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+import rootmemory.models  # noqa: F401  (register every mapper before autogenerate)
+from rootmemory.config import get_settings
+from rootmemory.db.base import Base
+
+config = context.config
+config.set_main_option("sqlalchemy.url", get_settings().database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            # Needed for SQLite, harmless on PostgreSQL.
+            render_as_batch=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

rootmemory/db/migrations/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: str | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}