agentdatabase 0.1.0__py3-none-any.whl

agentdb/governance/lifecycle_manager.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone  # noqa: F401 — timezone used in run_sweep
+
+from agentdb.core.models import Origin
+from agentdb.core.store import MemoryStore
+from agentdb.core.system import SystemStats
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _origin_value(origin) -> str:
+    """Return the string value of an origin, whether it's an Origin enum or a raw string."""
+    if isinstance(origin, Origin):
+        return origin.value
+    return str(origin)
+
+
+class LifecycleManager:
+    CONFIDENCE_DECAY_RATE: float = 0.0   # off by default; set > 0 to enable
+    ARCHIVAL_THRESHOLD: float = 0.10     # archive if confidence falls below this
+    STALENESS_DAYS: int = 90             # archive if not retrieved for this many days
+    REINFORCE_RATE: float = 0.10         # confidence boost per reinforce call
+
+    def __init__(
+        self,
+        store: MemoryStore,
+        system: SystemStats,
+        session_record_ids: dict | None = None,
+        embedding_store=None,
+        skill_store=None,
+        confidence_decay_rate: float | None = None,
+        archival_threshold: float | None = None,
+        staleness_days: int | None = None,
+        reinforce_rate: float | None = None,
+    ) -> None:
+        self._store = store
+        self._system = system
+        self._session_record_ids: dict[str, list[str]] = (
+            session_record_ids if session_record_ids is not None else {}
+        )
+        self._embedding_store = embedding_store
+        self._skill_store = skill_store
+        cls = type(self)
+        self.CONFIDENCE_DECAY_RATE = confidence_decay_rate if confidence_decay_rate is not None else cls.CONFIDENCE_DECAY_RATE
+        self.ARCHIVAL_THRESHOLD = archival_threshold if archival_threshold is not None else cls.ARCHIVAL_THRESHOLD
+        self.STALENESS_DAYS = staleness_days if staleness_days is not None else cls.STALENESS_DAYS
+        self.REINFORCE_RATE = reinforce_rate if reinforce_rate is not None else cls.REINFORCE_RATE
+
+    # ------------------------------------------------------------------
+    # Sweep
+    # ------------------------------------------------------------------
+
+    def run_sweep(self) -> dict:
+        """
+        On-demand lifecycle sweep.
+
+        1. If CONFIDENCE_DECAY_RATE > 0: apply decay to agent_inferred +
+           provider_ingested records (human_approved is immune).
+        2. Archive records whose confidence is below ARCHIVAL_THRESHOLD.
+        3. Archive records not retrieved for more than STALENESS_DAYS.
+
+        Returns {"decayed": N, "archived": N}.
+        human_approved records are immune to all lifecycle operations.
+        """
+        now = _utcnow()
+        decayed = 0
+        archived_ids: set[str] = set()
+
+        records = self._store.list_all()
+
+        # --- Step 0: archive expired records (expiry_time has passed) ---
+        for record in records:
+            if _origin_value(record.origin) == Origin.HUMAN_APPROVED.value:
+                continue  # human_approved records never expire
+            if record.expiry_time is not None:
+                expiry = record.expiry_time
+                if expiry.tzinfo is None:
+                    expiry = expiry.replace(tzinfo=timezone.utc)
+                if expiry <= now:
+                    self._store.archive_record(record.id)
+                    archived_ids.add(record.id)
+
+        records = self._store.list_all()
+
+        # --- Step 1: optional decay ---
+        if self.CONFIDENCE_DECAY_RATE > 0:
+            for record in records:
+                origin = _origin_value(record.origin)
+                if origin == Origin.HUMAN_APPROVED.value:
+                    continue
+                new_conf = max(0.0, record.confidence - self.CONFIDENCE_DECAY_RATE)
+                if new_conf != record.confidence:
+                    self._store.update_confidence(record.id, new_conf)
+                    decayed += 1
+
+        # Re-read after potential mutations so archival thresholds are current
+        records = self._store.list_all()
+
+        # --- Step 2: archive below threshold ---
+        for record in records:
+            if record.id in archived_ids:
+                continue
+            origin = _origin_value(record.origin)
+            if origin == Origin.HUMAN_APPROVED.value:
+                continue
+            if record.confidence < self.ARCHIVAL_THRESHOLD:
+                self._store.archive_record(record.id)
+                archived_ids.add(record.id)
+
+        # --- Step 3: archive stale records ---
+        records = self._store.list_all()
+        for record in records:
+            if record.id in archived_ids:
+                continue
+            origin = _origin_value(record.origin)
+            if origin == Origin.HUMAN_APPROVED.value:
+                continue
+
+            # Use last_retrieved if available, else created_at
+            reference_time = record.last_retrieved or record.created_at
+            # Ensure timezone-aware for comparison
+            if reference_time.tzinfo is None:
+                reference_time = reference_time.replace(tzinfo=timezone.utc)
+            days_since = (now - reference_time).days
+            if days_since >= self.STALENESS_DAYS:
+                self._store.archive_record(record.id)
+                archived_ids.add(record.id)
+
+        # Embedding orphan cleanup
+        if self._embedding_store is not None:
+            active_memory_ids = [r.id for r in self._store.list_all()]
+            self._embedding_store.prune_orphans("memories", active_memory_ids)
+
+            if self._skill_store is not None:
+                active_skill_ids = self._skill_store.list_all_active_ids()
+                self._embedding_store.prune_orphans("skills", active_skill_ids)
+
+        return {"decayed": decayed, "archived": len(archived_ids)}
+
+    # ------------------------------------------------------------------
+    # Reinforce
+    # ------------------------------------------------------------------
+
+    def reinforce(self, record_id: str) -> None:
+        """Boost confidence toward 1.0 and reset last_retrieved."""
+        record = self._store.get_by_id(record_id)
+        if record is None or record.archived:
+            return
+        if _origin_value(record.origin) == Origin.HUMAN_APPROVED.value:
+            return  # immune
+
+        new_conf = min(1.0, record.confidence + self.REINFORCE_RATE)
+        self._store.update_confidence(record_id, new_conf)
+        self._store.increment_retrieval_count(record_id)
+
+    # ------------------------------------------------------------------
+    # Record outcome (core logic, moved from AgentDB)
+    # ------------------------------------------------------------------
+
+    def record_outcome(
+        self,
+        session_id: str,
+        agent_id: str,
+        outcome_type: str,
+        outcome_value: float,
+    ) -> list[str]:
+        """
+        Adjust confidence for records retrieved in this session.
+
+        Rules by origin:
+        - agent_inferred:    positive (+0.05 * outcome_value, cap +0.1),
+                             negative (-0.02 * (1 - outcome_value), cap -0.1)
+        - provider_ingested: positive (no change), negative (same as above)
+        - human_approved:    never adjusted
+
+        Clears the session record IDs after adjusting.
+        Returns list of adjusted record IDs (for audit log use by the caller).
+        """
+        seen_ids = list(dict.fromkeys(self._session_record_ids.get(session_id, [])))
+        is_positive = outcome_value >= 0.5
+        adjusted_ids: list[str] = []
+
+        for record_id in seen_ids:
+            record = self._store.get_by_id(record_id)
+            if record is None:
+                continue
+
+            origin = _origin_value(record.origin)
+            if origin == Origin.HUMAN_APPROVED.value:
+                continue
+
+            if origin == Origin.AGENT_INFERRED.value:
+                if is_positive:
+                    delta = min(0.05 * outcome_value, 0.1)
+                    new_conf = min(1.0, record.confidence + delta)
+                else:
+                    delta = min(0.02 * (1 - outcome_value), 0.1)
+                    new_conf = max(0.0, record.confidence - delta)
+                self._store.update_confidence(record_id, new_conf)
+                adjusted_ids.append(record_id)
+            elif origin == Origin.PROVIDER_INGESTED.value:
+                if not is_positive:
+                    delta = min(0.02 * (1 - outcome_value), 0.1)
+                    new_conf = max(0.0, record.confidence - delta)
+                    self._store.update_confidence(record_id, new_conf)
+                    adjusted_ids.append(record_id)
+
+        # Clear session record IDs so the next retrieve starts fresh
+        if session_id in self._session_record_ids:
+            self._session_record_ids[session_id] = []
+
+        # Persist outcome row
+        now = _utcnow().isoformat()
+        with self._store._connect() as conn:
+            conn.execute(
+                "INSERT INTO outcomes "
+                "(id, session_id, agent_id, outcome_type, outcome_value, linked_retrieval_sequence, created_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (str(uuid.uuid4()), session_id, agent_id, outcome_type, outcome_value, None, now),
+            )
+
+        return adjusted_ids

agentdb/governance/permission_router.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class PermissionDenied(Exception):
+    pass
+
+
+# Prefixes owned by AgentDB's own framework machinery (not agent business
+# data) — writable by default regardless of default_policy/can_write,
+# because gating them requires every integrating deployment to remember a
+# permissions.yaml edit before the feature works at all. An explicit
+# cannot_write entry still overrides this (see check_write below) — this is
+# a default, not an unconditional bypass.
+FRAMEWORK_MANAGED_WRITE_PREFIXES: tuple[str, ...] = ("proposal/",)
+
+
+class PermissionRouter:
+    """
+    Routes permission checks based on a YAML policy file.
+
+    YAML format:
+        default_policy: deny
+        human_zone_prefixes:
+          - "skills/"
+        agents:
+          agent_id:
+            can_write:
+              - "memory/working/"
+            cannot_write:
+              - "skills/"
+            can_read:
+              - "memory/working/"
+    """
+
+    def __init__(self, permissions_path: Any) -> None:
+        path = Path(permissions_path)
+        with path.open("r", encoding="utf-8") as f:
+            self._config: dict = yaml.safe_load(f) or {}
+
+        self._default_policy: str = self._config.get("default_policy", "deny")
+        self._human_zone_prefixes: list[str] = self._config.get("human_zone_prefixes", [])
+        self._agents: dict = self._config.get("agents", {})
+
+    def _matches_any(self, key: str, patterns: list[str]) -> bool:
+        for pattern in patterns:
+            # Treat patterns ending with '/' as prefix matches,
+            # also support glob patterns
+            if pattern.endswith("/"):
+                if key.startswith(pattern):
+                    return True
+            elif fnmatch.fnmatch(key, pattern + "*") or fnmatch.fnmatch(key, pattern):
+                return True
+        return False
+
+    def is_human_zone(self, key: str) -> bool:
+        for prefix in self._human_zone_prefixes:
+            if key.startswith(prefix):
+                return True
+        return False
+
+    def check_write(self, key: str, agent_id: str, trust_zone: str) -> None:
+        """
+        Raises PermissionDenied if the agent is not allowed to write the key.
+
+        Rules:
+        - If trust_zone == "agent_inferred" and key is in a human_zone_prefix: deny
+        - Check cannot_write before can_write
+        - default_policy: deny means deny unless explicitly allowed
+        """
+        # Agent-inferred writes to human zones are always denied
+        if trust_zone == "agent_inferred" and self.is_human_zone(key):
+            raise PermissionDenied(
+                f"Agent '{agent_id}' cannot write to human zone key '{key}' "
+                f"with trust_zone '{trust_zone}'"
+            )
+
+        agent_config = self._agents.get(agent_id, {})
+
+        # Check cannot_write first
+        cannot_write = agent_config.get("cannot_write", [])
+        if self._matches_any(key, cannot_write):
+            raise PermissionDenied(
+                f"Agent '{agent_id}' is explicitly denied write access to '{key}'"
+            )
+
+        # Check can_write
+        can_write = agent_config.get("can_write", [])
+        if self._matches_any(key, can_write):
+            return  # allowed
+
+        # Framework-managed prefixes are writable by default (cannot_write,
+        # checked above, still overrides this).
+        if self._matches_any(key, FRAMEWORK_MANAGED_WRITE_PREFIXES):
+            return  # allowed
+
+        # Fall through to default policy
+        if self._default_policy == "deny":
+            raise PermissionDenied(
+                f"Agent '{agent_id}' has no explicit write permission for '{key}' "
+                f"and default_policy is 'deny'"
+            )
+
+    def unconfigured_agents(self, agent_ids: list[str]) -> list[str]:
+        """Return the subset of agent_ids that have no entry in this config.
+
+        Useful for pre-flight checks at startup: call with all known bot
+        identities and warn/fail if any are returned.
+        """
+        return [a for a in agent_ids if a not in self._agents]
+
+    def check_read(self, key: str, agent_id: str) -> None:
+        """
+        Raises PermissionDenied if the agent is not allowed to read the key.
+        """
+        agent_config = self._agents.get(agent_id, {})
+
+        can_read = agent_config.get("can_read", [])
+        if self._matches_any(key, can_read):
+            return  # allowed
+
+        if self._default_policy == "deny":
+            raise PermissionDenied(
+                f"Agent '{agent_id}' has no explicit read permission for '{key}' "
+                f"and default_policy is 'deny'"
+            )

agentdb/interface/__init__.py

@@ -0,0 +1,25 @@
+from .client import (
+    AgentDB,
+    AuditLog,
+    AuditEntry,
+    RetrievalResult,
+    SystemStats,
+    SkillsAPI,
+    EVENT_MEMORY_WRITE,
+    EVENT_MEMORY_RETRIEVE,
+    EVENT_MEMORY_OUTCOME,
+    EVENT_EXTERNAL_CONFLICT_DETECTED,
+)
+
+__all__ = [
+    "AgentDB",
+    "AuditLog",
+    "AuditEntry",
+    "RetrievalResult",
+    "SystemStats",
+    "SkillsAPI",
+    "EVENT_MEMORY_WRITE",
+    "EVENT_MEMORY_RETRIEVE",
+    "EVENT_MEMORY_OUTCOME",
+    "EVENT_EXTERNAL_CONFLICT_DETECTED",
+]