rootmemory 0.1.0__py3-none-any.whl

rootmemory/db/migrations/versions/d336d5cf7fb9_initial_schema.py

@@ -0,0 +1,260 @@
+"""initial schema
+
+Revision ID: d336d5cf7fb9
+Revises: 
+Create Date: 2026-09-08 18:58:54.903233
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = 'd336d5cf7fb9'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('agents',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('name', sa.String(length=200), nullable=False),
+    sa.Column('role', sa.String(length=200), nullable=False),
+    sa.Column('description', sa.String(length=2000), nullable=False),
+    sa.Column('trust_score', sa.Float(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_agents'))
+    )
+    with op.batch_alter_table('agents', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_agents_name'), ['name'], unique=True)
+
+    op.create_table('claims',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('claim_key', sa.String(length=300), nullable=False),
+    sa.Column('canonical_text', sa.Text(), nullable=False),
+    sa.Column('status', sa.String(length=20), nullable=False),
+    sa.Column('confidence', sa.Float(), nullable=False),
+    sa.Column('independent_support_count', sa.Integer(), nullable=False),
+    sa.Column('independent_contradiction_count', sa.Integer(), nullable=False),
+    sa.Column('promoted_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_claims'))
+    )
+    with op.batch_alter_table('claims', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_claims_claim_key'), ['claim_key'], unique=True)
+        batch_op.create_index(batch_op.f('ix_claims_status'), ['status'], unique=False)
+
+    op.create_table('provenance_edges',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('from_node_id', sa.Uuid(), nullable=False),
+    sa.Column('from_node_type', sa.String(length=20), nullable=False),
+    sa.Column('to_node_id', sa.Uuid(), nullable=False),
+    sa.Column('to_node_type', sa.String(length=20), nullable=False),
+    sa.Column('edge_type', sa.String(length=20), nullable=False),
+    sa.Column('weight', sa.Float(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_provenance_edges')),
+    sa.UniqueConstraint('from_node_id', 'to_node_id', 'edge_type', name='from_node_id_to_node_id_edge_type')
+    )
+    with op.batch_alter_table('provenance_edges', schema=None) as batch_op:
+        batch_op.create_index('ix_provenance_edges_edge_type', ['edge_type'], unique=False)
+        batch_op.create_index('ix_provenance_edges_from_node_id', ['from_node_id'], unique=False)
+        batch_op.create_index('ix_provenance_edges_to_node_id', ['to_node_id'], unique=False)
+
+    op.create_table('repair_reports',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('trigger_node_id', sa.Uuid(), nullable=False),
+    sa.Column('trigger_node_type', sa.String(length=20), nullable=False),
+    sa.Column('trigger_reason', sa.String(length=2000), nullable=False),
+    sa.Column('affected_beliefs', sa.JSON(), nullable=False),
+    sa.Column('affected_claims', sa.JSON(), nullable=False),
+    sa.Column('affected_decisions', sa.JSON(), nullable=False),
+    sa.Column('details', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_repair_reports'))
+    )
+    with op.batch_alter_table('repair_reports', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_repair_reports_trigger_node_id'), ['trigger_node_id'], unique=False)
+
+    op.create_table('beliefs',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('agent_id', sa.Uuid(), nullable=False),
+    sa.Column('claim_text', sa.Text(), nullable=False),
+    sa.Column('normalized_claim_key', sa.String(length=300), nullable=False),
+    sa.Column('confidence', sa.Float(), nullable=False),
+    sa.Column('epistemic_status', sa.String(length=20), nullable=False),
+    sa.Column('visibility', sa.String(length=20), nullable=False),
+    sa.Column('llm_generated', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.ForeignKeyConstraint(['agent_id'], ['agents.id'], name=op.f('fk_beliefs_agent_id_agents')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_beliefs'))
+    )
+    with op.batch_alter_table('beliefs', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_beliefs_agent_id'), ['agent_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_beliefs_epistemic_status'), ['epistemic_status'], unique=False)
+        batch_op.create_index(batch_op.f('ix_beliefs_normalized_claim_key'), ['normalized_claim_key'], unique=False)
+        batch_op.create_index(batch_op.f('ix_beliefs_visibility'), ['visibility'], unique=False)
+
+    op.create_table('decisions',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('agent_id', sa.Uuid(), nullable=False),
+    sa.Column('decision_type', sa.String(length=100), nullable=False),
+    sa.Column('content', sa.Text(), nullable=False),
+    sa.Column('status', sa.String(length=20), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.ForeignKeyConstraint(['agent_id'], ['agents.id'], name=op.f('fk_decisions_agent_id_agents')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_decisions'))
+    )
+    with op.batch_alter_table('decisions', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_decisions_agent_id'), ['agent_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_decisions_decision_type'), ['decision_type'], unique=False)
+        batch_op.create_index(batch_op.f('ix_decisions_status'), ['status'], unique=False)
+
+    op.create_table('observations',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('source_type', sa.String(length=100), nullable=False),
+    sa.Column('source_uri', sa.String(length=1000), nullable=True),
+    sa.Column('source_actor', sa.String(length=300), nullable=True),
+    sa.Column('content', sa.Text(), nullable=False),
+    sa.Column('content_hash', sa.String(length=64), nullable=False),
+    sa.Column('timestamp', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('created_by_agent_id', sa.Uuid(), nullable=True),
+    sa.Column('validity_status', sa.String(length=20), nullable=False),
+    sa.Column('validity_reason', sa.String(length=2000), nullable=True),
+    sa.Column('reliability_score', sa.Float(), nullable=False),
+    sa.Column('source_family_id', sa.String(length=200), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('meta', sa.JSON(), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_agent_id'], ['agents.id'], name=op.f('fk_observations_created_by_agent_id_agents')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_observations'))
+    )
+    with op.batch_alter_table('observations', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_observations_content_hash'), ['content_hash'], unique=False)
+        batch_op.create_index(batch_op.f('ix_observations_created_by_agent_id'), ['created_by_agent_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_observations_source_family_id'), ['source_family_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_observations_source_type'), ['source_type'], unique=False)
+        batch_op.create_index(batch_op.f('ix_observations_validity_status'), ['validity_status'], unique=False)
+
+    op.create_table('promotion_audits',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('claim_id', sa.Uuid(), nullable=False),
+    sa.Column('evaluated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('supporting_belief_count', sa.Integer(), nullable=False),
+    sa.Column('agreeing_agent_count', sa.Integer(), nullable=False),
+    sa.Column('independent_support_count', sa.Integer(), nullable=False),
+    sa.Column('contradiction_count', sa.Integer(), nullable=False),
+    sa.Column('independent_contradiction_count', sa.Integer(), nullable=False),
+    sa.Column('aggregate_confidence', sa.Float(), nullable=False),
+    sa.Column('result', sa.String(length=20), nullable=False),
+    sa.Column('reasons', sa.JSON(), nullable=False),
+    sa.Column('policy_version', sa.String(length=50), nullable=False),
+    sa.Column('policy_snapshot', sa.JSON(), nullable=False),
+    sa.ForeignKeyConstraint(['claim_id'], ['claims.id'], name=op.f('fk_promotion_audits_claim_id_claims')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_promotion_audits'))
+    )
+    with op.batch_alter_table('promotion_audits', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_promotion_audits_claim_id'), ['claim_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_promotion_audits_result'), ['result'], unique=False)
+
+    op.create_table('claim_belief_links',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('claim_id', sa.Uuid(), nullable=False),
+    sa.Column('belief_id', sa.Uuid(), nullable=False),
+    sa.Column('role', sa.String(length=20), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['belief_id'], ['beliefs.id'], name=op.f('fk_claim_belief_links_belief_id_beliefs')),
+    sa.ForeignKeyConstraint(['claim_id'], ['claims.id'], name=op.f('fk_claim_belief_links_claim_id_claims')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_claim_belief_links')),
+    sa.UniqueConstraint('claim_id', 'belief_id', 'role', name='claim_id_belief_id_role')
+    )
+    with op.batch_alter_table('claim_belief_links', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_claim_belief_links_belief_id'), ['belief_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_claim_belief_links_claim_id'), ['claim_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_claim_belief_links_role'), ['role'], unique=False)
+
+    op.create_table('decision_dependencies',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('decision_id', sa.Uuid(), nullable=False),
+    sa.Column('claim_id', sa.Uuid(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['claim_id'], ['claims.id'], name=op.f('fk_decision_dependencies_claim_id_claims')),
+    sa.ForeignKeyConstraint(['decision_id'], ['decisions.id'], name=op.f('fk_decision_dependencies_decision_id_decisions')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_decision_dependencies')),
+    sa.UniqueConstraint('decision_id', 'claim_id', name='decision_id_claim_id')
+    )
+    with op.batch_alter_table('decision_dependencies', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_decision_dependencies_claim_id'), ['claim_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_decision_dependencies_decision_id'), ['decision_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('decision_dependencies', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_decision_dependencies_decision_id'))
+        batch_op.drop_index(batch_op.f('ix_decision_dependencies_claim_id'))
+
+    op.drop_table('decision_dependencies')
+    with op.batch_alter_table('claim_belief_links', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_claim_belief_links_role'))
+        batch_op.drop_index(batch_op.f('ix_claim_belief_links_claim_id'))
+        batch_op.drop_index(batch_op.f('ix_claim_belief_links_belief_id'))
+
+    op.drop_table('claim_belief_links')
+    with op.batch_alter_table('promotion_audits', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_promotion_audits_result'))
+        batch_op.drop_index(batch_op.f('ix_promotion_audits_claim_id'))
+
+    op.drop_table('promotion_audits')
+    with op.batch_alter_table('observations', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_observations_validity_status'))
+        batch_op.drop_index(batch_op.f('ix_observations_source_type'))
+        batch_op.drop_index(batch_op.f('ix_observations_source_family_id'))
+        batch_op.drop_index(batch_op.f('ix_observations_created_by_agent_id'))
+        batch_op.drop_index(batch_op.f('ix_observations_content_hash'))
+
+    op.drop_table('observations')
+    with op.batch_alter_table('decisions', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_decisions_status'))
+        batch_op.drop_index(batch_op.f('ix_decisions_decision_type'))
+        batch_op.drop_index(batch_op.f('ix_decisions_agent_id'))
+
+    op.drop_table('decisions')
+    with op.batch_alter_table('beliefs', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_beliefs_visibility'))
+        batch_op.drop_index(batch_op.f('ix_beliefs_normalized_claim_key'))
+        batch_op.drop_index(batch_op.f('ix_beliefs_epistemic_status'))
+        batch_op.drop_index(batch_op.f('ix_beliefs_agent_id'))
+
+    op.drop_table('beliefs')
+    with op.batch_alter_table('repair_reports', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_repair_reports_trigger_node_id'))
+
+    op.drop_table('repair_reports')
+    with op.batch_alter_table('provenance_edges', schema=None) as batch_op:
+        batch_op.drop_index('ix_provenance_edges_to_node_id')
+        batch_op.drop_index('ix_provenance_edges_from_node_id')
+        batch_op.drop_index('ix_provenance_edges_edge_type')
+
+    op.drop_table('provenance_edges')
+    with op.batch_alter_table('claims', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_claims_status'))
+        batch_op.drop_index(batch_op.f('ix_claims_claim_key'))
+
+    op.drop_table('claims')
+    with op.batch_alter_table('agents', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_agents_name'))
+
+    op.drop_table('agents')
+    # ### end Alembic commands ###

rootmemory/db/session.py

@@ -0,0 +1,138 @@
+"""Engine/session management."""
+
+from __future__ import annotations
+
+from collections.abc import Generator, Iterator
+from contextlib import contextmanager
+
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.pool import StaticPool
+
+from rootmemory.config import get_settings
+from rootmemory.db.base import Base
+
+_engine: Engine | None = None
+_session_factory: sessionmaker[Session] | None = None
+
+
+def build_engine(database_url: str, echo: bool = False) -> Engine:
+    """Create an engine with the dialect-specific settings this app needs."""
+    is_sqlite = database_url.startswith("sqlite")
+    kwargs: dict[str, object] = {"echo": echo, "future": True}
+    if is_sqlite:
+        kwargs["connect_args"] = {"check_same_thread": False}
+        if ":memory:" in database_url:
+            # Every connection to an in-memory SQLite database gets its own
+            # empty database, so the whole app must share one connection.
+            kwargs["poolclass"] = StaticPool
+    engine = create_engine(database_url, **kwargs)
+    if is_sqlite:
+        # Foreign keys are off by default on SQLite; the integrity rules in
+        # spec section 46 depend on them being enforced.
+        @event.listens_for(engine, "connect")
+        def _fk_pragma(dbapi_connection, _record):  # type: ignore[no-untyped-def]
+            cursor = dbapi_connection.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+    return engine
+
+
+def get_engine() -> Engine:
+    global _engine
+    if _engine is None:
+        settings = get_settings()
+        _engine = build_engine(settings.database_url, settings.sql_echo)
+    return _engine
+
+
+def create_isolated_session(database_url: str = "sqlite+pysqlite:///:memory:") -> Session:
+    """A session on a private, freshly created database.
+
+    Used by the test-suite and by the experiment harness, where every scenario
+    must start from an empty graph without disturbing the process-wide engine.
+    """
+    import rootmemory.models  # noqa: F401  (register mappers)
+
+    engine = build_engine(database_url)
+    Base.metadata.create_all(bind=engine)
+    return sessionmaker(bind=engine, expire_on_commit=False, future=True)()
+
+
+def get_session_factory() -> sessionmaker[Session]:
+    global _session_factory
+    if _session_factory is None:
+        _session_factory = sessionmaker(bind=get_engine(), expire_on_commit=False, future=True)
+    return _session_factory
+
+
+def init_db() -> None:
+    """Create tables for local/dev/test use.
+
+    Production schema changes go through Alembic; this is the zero-infrastructure
+    path used by the demo and the test-suite.
+    """
+    import rootmemory.models  # noqa: F401  (register mappers)
+
+    Base.metadata.create_all(bind=get_engine())
+
+
+@contextmanager
+def session_scope() -> Iterator[Session]:
+    """Transactional scope for scripts and services outside the API."""
+    session = get_session_factory()()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+
+@contextmanager
+def open_memory(
+    database_url: str = "sqlite+pysqlite:///rootmemory.db",
+    create_tables: bool = True,
+) -> Iterator[Session]:
+    """Open a memory on its own database, in one line.
+
+    The library front door for embedding RootMemory in another application::
+
+        with open_memory("sqlite+pysqlite:///memory.db") as session:
+            memory = RootMemory(session)
+
+    Uses a private engine, so it never disturbs process-wide configuration and
+    two memories can be open at once. Commits on clean exit, rolls back on an
+    exception.
+    """
+    import rootmemory.models  # noqa: F401  (register mappers)
+
+    engine = build_engine(database_url)
+    if create_tables:
+        Base.metadata.create_all(bind=engine)
+
+    session = sessionmaker(bind=engine, expire_on_commit=False, future=True)()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+
+def get_db() -> Generator[Session, None, None]:
+    """FastAPI dependency."""
+    session = get_session_factory()()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

rootmemory/errors.py

@@ -0,0 +1,27 @@
+"""Domain errors, mapped to HTTP status codes in app/api/errors.py."""
+
+from __future__ import annotations
+
+
+class RootMemoryError(Exception):
+    """Base class for all domain errors."""
+
+
+class NodeNotFoundError(RootMemoryError):
+    """A referenced observation, belief, claim, decision or agent does not exist."""
+
+
+class ProvenanceRequiredError(RootMemoryError):
+    """A belief was submitted without any causal parent (spec section 16)."""
+
+
+class ProvenanceCycleError(RootMemoryError):
+    """The requested edge would make a belief depend on itself."""
+
+
+class ImmutableRecordError(RootMemoryError):
+    """An attempt was made to mutate an append-only record."""
+
+
+class PromotionForbiddenError(RootMemoryError):
+    """Shared/confirmed state may only be reached through the PromotionService."""

rootmemory/integrations/__init__.py

@@ -0,0 +1,16 @@
+"""Adapters that plug the memory layer into agent frameworks.
+
+Nothing in ``app/`` outside this package imports a framework, and nothing in
+this package is imported unless you ask for it. Each adapter imports its
+framework lazily and raises a readable error if it is not installed, so the
+core stays dependency-free.
+
+    from rootmemory.integrations import AsyncRootMemory          # any async code
+    from rootmemory.integrations.langchain_tools import build_tools # LangChain / any
+                                                             # tool-calling agent
+    from rootmemory.integrations.langgraph_memory import remembering, MemoryState
+"""
+
+from rootmemory.integrations.async_client import AsyncRootMemory
+
+__all__ = ["AsyncRootMemory"]