agentdatabase 0.1.0__py3-none-any.whl

agentdb/embeddings/store.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import struct
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger("agentdb")
+
+_CREATE_METADATA = """
+CREATE TABLE IF NOT EXISTS metadata (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+)
+"""
+
+_CREATE_EMBEDDINGS = """
+CREATE TABLE IF NOT EXISTS embeddings (
+    table_name   TEXT NOT NULL,
+    record_id    TEXT NOT NULL,
+    embedding    BLOB NOT NULL,
+    working_dirs TEXT NOT NULL DEFAULT '[]',
+    created_at   TEXT NOT NULL,
+    PRIMARY KEY (table_name, record_id)
+)
+"""
+
+_CREATE_SESSION_TOPICS = """
+CREATE TABLE IF NOT EXISTS session_topics (
+    session_id TEXT PRIMARY KEY,
+    embedding  BLOB NOT NULL,
+    created_at TEXT NOT NULL
+)
+"""
+
+
+def _pack(vec: list[float]) -> bytes:
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+def _unpack(blob: bytes) -> list[float]:
+    n = len(blob) // 4
+    return list(struct.unpack(f"{n}f", blob))
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class EmbeddingStore:
+    def __init__(self, db_path, model_name: str, dimensions: int) -> None:
+        self._db_path = Path(db_path)
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._model_name = model_name
+        self._dimensions = dimensions
+        with self._connect() as conn:
+            conn.execute(_CREATE_METADATA)
+            conn.execute(_CREATE_EMBEDDINGS)
+            conn.execute(_CREATE_SESSION_TOPICS)
+        self._validate_or_reset()
+
+    @contextmanager
+    def _connect(self):
+        conn = sqlite3.connect(str(self._db_path))
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _validate_or_reset(self) -> None:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT key, value FROM metadata WHERE key IN ('model_name', 'dimensions')"
+            ).fetchall()
+            meta = {r["key"]: r["value"] for r in rows}
+
+            if not meta:
+                conn.execute(
+                    "INSERT OR REPLACE INTO metadata (key, value) VALUES ('model_name', ?)",
+                    (self._model_name,),
+                )
+                conn.execute(
+                    "INSERT OR REPLACE INTO metadata (key, value) VALUES ('dimensions', ?)",
+                    (str(self._dimensions),),
+                )
+                return
+
+            stored_name = meta.get("model_name")
+            stored_dims = int(meta.get("dimensions", "0"))
+            name_changed = stored_name != self._model_name
+            # Only treat dimensions as changed when both sides are known (non-zero)
+            dims_changed = (
+                self._dimensions != 0
+                and stored_dims != 0
+                and stored_dims != self._dimensions
+            )
+
+            if name_changed or dims_changed:
+                logger.warning(
+                    "agentdb: embedding config changed (model '%s'→'%s', dims %d→%d) — "
+                    "wiping all stored embeddings; they will regenerate lazily.",
+                    stored_name,
+                    self._model_name,
+                    stored_dims,
+                    self._dimensions,
+                )
+                conn.execute("DELETE FROM embeddings")
+                conn.execute("DELETE FROM session_topics")
+                conn.execute(
+                    "INSERT OR REPLACE INTO metadata (key, value) VALUES ('model_name', ?)",
+                    (self._model_name,),
+                )
+                conn.execute(
+                    "INSERT OR REPLACE INTO metadata (key, value) VALUES ('dimensions', ?)",
+                    (str(self._dimensions),),
+                )
+
+    def put(
+        self,
+        table: str,
+        record_id: str,
+        embedding: list[float],
+        working_dirs: list[str],
+    ) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO embeddings
+                    (table_name, record_id, embedding, working_dirs, created_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (table, record_id, _pack(embedding), json.dumps(working_dirs), _utcnow()),
+            )
+
+    def get(self, table: str, record_id: str) -> list[float] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT embedding FROM embeddings WHERE table_name = ? AND record_id = ?",
+                (table, record_id),
+            ).fetchone()
+        return _unpack(row["embedding"]) if row else None
+
+    def get_batch(self, table: str, record_ids: list[str]) -> dict[str, list[float]]:
+        if not record_ids:
+            return {}
+        placeholders = ",".join("?" * len(record_ids))
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT record_id, embedding FROM embeddings "
+                f"WHERE table_name = ? AND record_id IN ({placeholders})",
+                [table] + list(record_ids),
+            ).fetchall()
+        return {row["record_id"]: _unpack(row["embedding"]) for row in rows}
+
+    def delete(self, table: str, record_id: str) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "DELETE FROM embeddings WHERE table_name = ? AND record_id = ?",
+                (table, record_id),
+            )
+
+    def prune_orphans(self, table: str, valid_ids: list[str]) -> int:
+        if not valid_ids:
+            return 0
+        placeholders = ",".join("?" * len(valid_ids))
+        with self._connect() as conn:
+            cursor = conn.execute(
+                f"DELETE FROM embeddings WHERE table_name = ? "
+                f"AND record_id NOT IN ({placeholders})",
+                [table] + list(valid_ids),
+            )
+            return cursor.rowcount
+
+    def put_session_topic(self, session_id: str, embedding: list[float]) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO session_topics (session_id, embedding, created_at)
+                VALUES (?, ?, ?)
+                """,
+                (session_id, _pack(embedding), _utcnow()),
+            )
+
+    def get_session_topic(self, session_id: str) -> list[float] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT embedding FROM session_topics WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+        return _unpack(row["embedding"]) if row else None

agentdb/embeddings/text.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import json
+
+from ..core.models import MemoryRecord, Skill
+
+
+def _embed_text_for_record(r: MemoryRecord) -> str:
+    """Build the text representation of a memory record for embedding."""
+    key_readable = r.key.replace("/", " ").strip()
+    if isinstance(r.value, (dict, list)):
+        value_str = json.dumps(r.value)[:2000]
+    else:
+        value_str = str(r.value)[:2000]
+    return f"{key_readable}: {value_str}"
+
+
+def _embed_text_for_skill(skill: Skill) -> str:
+    """Build the text representation of a skill for embedding."""
+    return f"{skill.name}: {skill.content}"[:2000]

agentdb/gateway/__init__.py

@@ -0,0 +1,189 @@
+"""
+db.gateway — governed event dispatch, conflict queue, and proposal workflow.
+
+Gateway is the single surface for:
+  - Reconciliation event subscribe/dispatch (previously scattered on AgentDB)
+  - Conflict queue (read-only view into conflict/ memory records)
+  - Proposal workflow: propose → approve/reject → list_proposals
+"""
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from ..interface.client import AgentDB
+
+
+class Gateway:
+    """
+    Unified governance surface attached to an AgentDB instance as `db.gateway`.
+
+    No new tables are created.  Proposals are stored as agent_inferred memory
+    records with key prefix ``proposal/<proposal_id>``.  Conflicts are memory
+    records with key prefix ``conflict/`` (written by a future conflict-detection
+    task; this surface exposes the read-only view).
+    """
+
+    def __init__(self, db: "AgentDB") -> None:
+        self._db = db
+        # Reconciliation handlers: trigger -> [callables]
+        self._handlers: dict[str, list[Callable]] = {}
+
+    # ------------------------------------------------------------------
+    # Reconciliation
+    # ------------------------------------------------------------------
+
+    def subscribe(self, trigger: str, handler: Callable) -> None:
+        """Register a handler for a named reconciliation trigger."""
+        self._handlers.setdefault(trigger, []).append(handler)
+
+    def dispatch(self, trigger: str, **kwargs) -> int:
+        """Fire all handlers for *trigger*.  Returns the handler count."""
+        handlers = self._handlers.get(trigger, [])
+        for handler in handlers:
+            handler(**kwargs)
+        return len(handlers)
+
+    # ------------------------------------------------------------------
+    # Conflict queue
+    # ------------------------------------------------------------------
+
+    def conflict_queue(self, resolved: bool = False) -> list:
+        """
+        Return conflict records from the conflicts table.
+
+        Args:
+            resolved: if True, return resolved conflicts; defaults to False (pending only).
+        """
+        return self._db._store.list_conflicts(resolved=resolved)
+
+    # ------------------------------------------------------------------
+    # Proposal workflow
+    # ------------------------------------------------------------------
+
+    def propose(
+        self,
+        name: str,
+        content: str,
+        scope: list[str],
+        agent_id: str,
+        entities: Optional[list[str]] = None,
+        session_id: Optional[str] = None,
+    ) -> str:
+        """
+        Draft a skill proposal.
+
+        Writes the draft as an agent_inferred memory record under
+        ``proposal/<proposal_id>`` and returns the proposal_id.
+        """
+        proposal_id = str(uuid.uuid4())
+        self._db.write(
+            key=f"proposal/{proposal_id}",
+            value={
+                "proposal_id": proposal_id,
+                "name": name,
+                "content": content,
+                "scope": scope,
+                "agent_id": agent_id,
+                "status": "pending",
+            },
+            origin="agent_inferred",
+            agent_id=agent_id,
+            session_id=session_id,
+            entities=entities or [],
+        )
+        self._db.audit_log.append(
+            "proposal_created",
+            {"proposal_id": proposal_id, "name": name, "agent_id": agent_id},
+        )
+        return proposal_id
+
+    def approve(self, proposal_id: str, resolution: Optional[str] = None) -> None:
+        """
+        Approve a pending proposal.
+
+        Promotes the draft to a skill via skills_api.create_skill and archives
+        the proposal memory record.
+        """
+        record = self._db.read(f"proposal/{proposal_id}")
+        if record is None:
+            raise KeyError(f"Proposal not found: {proposal_id}")
+
+        payload = record.value
+        self._db.skills_api.create_skill(
+            skill_id=proposal_id,
+            name=payload["name"],
+            content=payload["content"],
+            scope=payload["scope"],
+        )
+
+        # Archive the proposal record now that the skill has been created
+        self._db._store.delete_by_key(f"proposal/{proposal_id}")
+
+        self._db.audit_log.append(
+            "proposal_approved",
+            {
+                "proposal_id": proposal_id,
+                "resolution": resolution,
+                "agent_id": payload.get("agent_id"),
+            },
+        )
+
+    def reject(self, proposal_id: str, reason: Optional[str] = None) -> None:
+        """
+        Reject a pending proposal.
+
+        Archives the proposal memory record without touching skills_api.
+        """
+        record = self._db.read(f"proposal/{proposal_id}")
+        if record is None:
+            raise KeyError(f"Proposal not found: {proposal_id}")
+
+        payload = record.value
+        self._db._store.delete_by_key(f"proposal/{proposal_id}")
+
+        self._db.audit_log.append(
+            "proposal_rejected",
+            {
+                "proposal_id": proposal_id,
+                "reason": reason,
+                "agent_id": payload.get("agent_id"),
+            },
+        )
+
+    def list_proposals(self, status: str = "pending") -> list[dict]:
+        """
+        Return proposals filtered by status.
+
+        Status is encoded in the record value.  Approved and rejected proposals
+        have their memory records archived; we use the audit log for those.
+
+        For simplicity:
+          - ``pending``  — active (non-archived) memory records with key prefix proposal/
+          - ``approved`` — read from audit_log events of type proposal_approved
+          - ``rejected`` — read from audit_log events of type proposal_rejected
+        """
+        if status == "pending":
+            results: list[dict] = []
+            for record in self._db._store._by_id.values():
+                if record.key.startswith("proposal/") and not record.archived:
+                    results.append(dict(record.value))
+            return results
+
+        event_type = f"proposal_{status}"  # proposal_approved / proposal_rejected
+        entries = self._db.audit_log.replay()
+        return [
+            {
+                "proposal_id": e.payload["proposal_id"],
+                "agent_id": e.payload.get("agent_id"),
+                "status": status,
+            }
+            for e in entries
+            if e.event_type == event_type
+        ]
+
+
+from .adapter import GatewayAdapter  # noqa: E402 — keep at bottom to avoid circular import
+
+__all__ = ["Gateway", "GatewayAdapter"]

agentdb/gateway/adapter.py

@@ -0,0 +1,58 @@
+"""
+GatewayAdapter — base class for all AgentDB runtime adapters.
+
+Subclasses (e.g. AgentDBClaudeMiddleware) inherit a direct reference to the
+db.gateway surface so they can subscribe to triggers, dispatch events, and
+interact with the proposal workflow without importing Gateway directly.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..interface.client import AgentDB
+    from . import Gateway
+
+
+class GatewayAdapter:
+    """
+    Base class that wires an adapter to db.gateway.
+
+    Subclasses should call super().__init__(db, agent_id, profile) and may
+    override prepare_turn, pre_tool_use, and finalize_turn.
+
+    ``self.profile_name`` holds the raw profile string passed at construction.
+    Subclasses that need the fully resolved per-agent config should call
+    ``db.config_for(agent_id)`` themselves and store it (e.g. AgentDBClaudeMiddleware's
+    ``self._resolved``) rather than reconstructing profile data by hand.
+    """
+
+    def __init__(
+        self,
+        db: "AgentDB",
+        agent_id: str,
+        profile: str = "budget_optimized",
+    ) -> None:
+        self._db = db
+        self._agent_id = agent_id
+        self.profile_name: str = profile
+        self.gateway: "Gateway" = db.gateway
+
+    @property
+    def agent_id(self) -> str:
+        """Public accessor for the agent_id this adapter was constructed with.
+
+        Downstream apps need this to scope their own gateway calls (e.g. the
+        scope= argument on gateway.propose()) without reaching into the
+        underscore-prefixed private attribute.
+        """
+        return self._agent_id
+
+    def prepare_turn(self, user_query: str, session_id: str) -> None:  # pragma: no cover
+        pass
+
+    def pre_tool_use(self, tool_name: str, tool_input: dict, session_id: str) -> None:  # pragma: no cover
+        pass
+
+    def finalize_turn(self, session_id: str, **kwargs) -> None:  # pragma: no cover
+        pass

agentdb/governance/__init__.py

@@ -0,0 +1,3 @@
+from .permission_router import PermissionRouter, PermissionDenied
+
+__all__ = ["PermissionRouter", "PermissionDenied"]

agentdb/governance/conflict_detector.py

@@ -0,0 +1,103 @@
+"""
+Phase 1 conflict detector — temporal and authority conflicts only.
+
+Temporal:  same key + same origin → two records with equal authority, neither
+           supersedes the other.
+Authority: agent_inferred / provider_ingested tries to overwrite human_approved
+           → the agent has less authority than the existing human-approved value.
+
+Human-approved overwriting anything lower is NOT a conflict — it supersedes cleanly.
+"""
+from __future__ import annotations
+
+from agentdb.core.models import ConflictRecord, MemoryRecord
+
+# Origins that are considered "agent-tier" (lower authority than human_approved)
+_AGENT_TIER_ORIGINS = {"agent_inferred", "provider_ingested"}
+
+
+class ConflictDetector:
+    """Checks whether a new write conflicts with an existing record."""
+
+    def check(
+        self,
+        new_record: MemoryRecord,
+        existing: MemoryRecord,
+    ) -> ConflictRecord | None:
+        """
+        Returns a ConflictRecord if new_record conflicts with existing, else None.
+
+        Rules:
+        - Different keys → no conflict (caller should not invoke in this case).
+        - Same key + same origin → temporal conflict.
+        - New is agent_inferred/provider_ingested AND existing is human_approved
+          → authority conflict.
+        - New is human_approved, existing is anything lower → no conflict (supersedes).
+        """
+        if new_record.key != existing.key:
+            return None
+
+        new_origin = str(new_record.origin)
+        existing_origin = str(existing.origin)
+
+        # Authority conflict: agent/provider overwriting human_approved
+        if existing_origin == "human_approved" and new_origin in _AGENT_TIER_ORIGINS:
+            return ConflictRecord(
+                record_a_id=existing.id,
+                record_b_id=new_record.id,
+                conflict_type="authority",
+            )
+
+        # Human supersedes lower-trust: no conflict (only when existing is NOT also human_approved)
+        if new_origin == "human_approved" and existing_origin in _AGENT_TIER_ORIGINS:
+            return None
+
+        # Same origin → temporal conflict (covers human_approved vs human_approved too)
+        if new_origin == existing_origin:
+            return ConflictRecord(
+                record_a_id=existing.id,
+                record_b_id=new_record.id,
+                conflict_type="temporal",
+            )
+
+        return None
+
+    @staticmethod
+    def check_semantic_batch(
+        new_record: "MemoryRecord",
+        candidates: list,
+        embedding_store,
+        threshold: float = 0.92,
+    ) -> list:
+        """
+        Returns ConflictRecords for any candidate with cosine(new, candidate) >= threshold.
+        Caps at 50 candidates. Skips if embedding_store is None or new_record has no embedding.
+        """
+        if embedding_store is None:
+            return []
+
+        new_vec = embedding_store.get("memories", new_record.id)
+        if new_vec is None:
+            return []
+
+        from ..embeddings.provider import _cosine
+
+        capped = [c for c in candidates if c.id != new_record.id][:50]
+        if not capped:
+            return []
+
+        candidate_ids = [c.id for c in capped]
+        stored = embedding_store.get_batch("memories", candidate_ids)
+
+        conflicts = []
+        for candidate in capped:
+            c_vec = stored.get(candidate.id)
+            if c_vec is None:
+                continue
+            if _cosine(new_vec, c_vec) >= threshold:
+                conflicts.append(ConflictRecord(
+                    record_a_id=candidate.id,
+                    record_b_id=new_record.id,
+                    conflict_type="semantic",
+                ))
+        return conflicts