hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/adapters/memory/session_memory.py

@@ -0,0 +1,178 @@
+"""Session Memory Plugin for conversation history."""
+
+import time
+from typing import Any
+
+from hexdag.builtin.adapters.memory.schemas import ConversationHistory
+from hexdag.core.logging import get_logger
+from hexdag.core.ports.memory import Memory
+
+logger = get_logger(__name__)
+
+
+class SessionMemoryPlugin:
+    """Memory plugin for conversation history and session context.
+
+    Wraps a base Memory adapter (InMemoryMemory, SQLiteMemoryAdapter, etc.)
+    and provides domain-specific operations for managing conversation history.
+
+    This plugin does NOT store data itself - it delegates to the underlying
+    Memory port implementation and adds session-specific logic.
+
+    Example
+    -------
+        from hexdag.builtin.adapters.memory import InMemoryMemory
+
+        # Use existing storage adapter
+        storage = InMemoryMemory()
+        session_memory = SessionMemoryPlugin(storage=storage, max_messages=100)
+
+        # Append messages
+        await session_memory.append_message("session123", "user", "Hello!")
+        await session_memory.append_message("session123", "assistant", "Hi there!")
+
+        # Get recent history
+        recent = await session_memory.get_recent_messages("session123", count=10)
+
+        # Get full history
+        history = await session_memory.get_history("session123")
+    """
+
+    plugin_type = "session"
+
+    def __init__(self, storage: Memory, max_messages: int = 100):
+        """Initialize session memory plugin.
+
+        Args
+        ----
+            storage: Base Memory port implementation (InMemoryMemory, SQLiteMemoryAdapter, etc.)
+            max_messages: Maximum messages to keep per session (auto-truncates)
+        """
+        self.storage = storage
+        self.max_messages = max_messages
+
+    async def aget(self, key: str) -> Any:
+        """Get value from session scope.
+
+        Delegates to underlying storage with session:: prefix.
+        """
+        return await self.storage.aget(f"session::{key}")
+
+    async def aset(self, key: str, value: Any) -> None:
+        """Set value in session scope.
+
+        Delegates to underlying storage with session:: prefix.
+        """
+        await self.storage.aset(f"session::{key}", value)
+
+    # Specialized methods for session memory
+
+    async def get_history(self, session_id: str) -> ConversationHistory:
+        """Get conversation history for session.
+
+        Args
+        ----
+            session_id: Session identifier
+
+        Returns
+        -------
+            ConversationHistory with messages and timestamps
+        """
+        data = await self.aget(session_id)
+        if data is None:
+            return ConversationHistory(
+                session_id=session_id,
+                messages=[],
+                timestamps=[],
+            )
+        return ConversationHistory.model_validate(data)
+
+    async def append_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Append message to conversation history with auto-truncation.
+
+        Args
+        ----
+            session_id: Session identifier
+            role: Message role ("user", "assistant", "system")
+            content: Message content
+            metadata: Optional metadata for this message
+        """
+        history = await self.get_history(session_id)
+
+        # Append new message
+        history.messages.append({"role": role, "content": content})
+        history.timestamps.append(time.time())
+
+        # Update token count (rough estimate: 4 chars per token)
+        history.token_count += len(content) // 4
+
+        # Auto-truncate to max_messages
+        if len(history.messages) > self.max_messages:
+            overflow = len(history.messages) - self.max_messages
+            history.messages = history.messages[overflow:]
+            history.timestamps = history.timestamps[overflow:]
+            logger.debug(
+                "Truncated session %s: removed %d old messages",
+                session_id,
+                overflow,
+            )
+
+        # Update metadata if provided
+        if metadata:
+            history.metadata.update(metadata)
+
+        await self.aset(session_id, history.model_dump())
+
+    async def get_recent_messages(
+        self,
+        session_id: str,
+        count: int = 10,
+    ) -> list[dict[str, str]]:
+        """Get recent N messages from conversation.
+
+        Args
+        ----
+            session_id: Session identifier
+            count: Number of recent messages to return
+
+        Returns
+        -------
+            List of recent message dicts
+        """
+        history = await self.get_history(session_id)
+        return history.messages[-count:]
+
+    async def clear_session(self, session_id: str) -> None:
+        """Clear conversation history for session.
+
+        Args
+        ----
+            session_id: Session identifier
+        """
+        empty_history = ConversationHistory(
+            session_id=session_id,
+            messages=[],
+            timestamps=[],
+        )
+        await self.aset(session_id, empty_history.model_dump())
+        logger.info("Cleared session %s", session_id)
+
+    async def get_token_count(self, session_id: str) -> int:
+        """Get approximate token count for session.
+
+        Args
+        ----
+            session_id: Session identifier
+
+        Returns
+        -------
+            Approximate token count
+        """
+        history = await self.get_history(session_id)
+        return history.token_count

hexdag/builtin/adapters/memory/sqlite_memory_adapter.py

@@ -0,0 +1,215 @@
+"""SQLite-backed Memory adapter that bridges DatabasePort to Memory Port.
+
+This adapter allows using SQLite databases as a Memory storage backend,
+providing persistent key-value storage with SQL database benefits.
+"""
+
+from typing import Any
+
+from hexdag.core.logging import get_logger
+from hexdag.core.ports.database import DatabasePort
+from hexdag.core.utils.sql_validation import validate_sql_identifier
+
+logger = get_logger(__name__)
+
+
+class SQLiteMemoryAdapter:
+    """Memory adapter backed by SQLite database.
+
+    Provides persistent key-value storage using SQLite, bridging the
+    DatabasePort and Memory Port. Automatically creates a key-value table
+    and provides async get/set operations.
+
+    This adapter is ideal for:
+    - Checkpoint persistence
+    - Configuration storage
+    - Any key-value data that needs SQL database benefits
+
+    Parameters
+    ----------
+    database : DatabasePort
+        SQLite database adapter (typically SQLiteAdapter)
+    table_name : str, default="memory_store"
+        Name of the key-value table
+    auto_init : bool, default=True
+        Automatically create table on first use
+
+    Examples
+    --------
+    Example usage::
+
+        from hexdag.builtin.adapters.database.sqlite import SQLiteAdapter
+        db = SQLiteAdapter(db_path="memory.db")
+        memory = SQLiteMemoryAdapter(database=db, table_name="memory_store")
+    """
+
+    # Type annotations for attributes
+    database: DatabasePort
+    table_name: str
+    auto_init: bool
+    _initialized: bool
+
+    def __init__(
+        self, database: DatabasePort, table_name: str = "memory_store", auto_init: bool = True
+    ) -> None:
+        """Initialize SQLite memory adapter.
+
+        Parameters
+        ----------
+        database : DatabasePort
+            SQLite database adapter
+        table_name : str
+            Name of the key-value table
+        auto_init : bool
+            Automatically create table if it doesn't exist
+
+        """
+        self.table_name = table_name
+        self.auto_init = auto_init
+        self.database = database
+        self._initialized = False
+
+        # Validate table name to prevent SQL injection
+        self._validate_table_name(self.table_name)
+
+    @staticmethod
+    def _validate_table_name(table_name: str) -> None:
+        """Validate table name to prevent SQL injection.
+
+        Parameters
+        ----------
+        table_name : str
+            Table name to validate
+        """
+        validate_sql_identifier(table_name, identifier_type="table", raise_on_invalid=True)
+
+    async def _ensure_table(self) -> None:
+        """Create key-value table if it doesn't exist."""
+        if self._initialized:
+            return
+
+        # Table name is validated in __init__, safe to use in f-string
+        sql = f"""
+        CREATE TABLE IF NOT EXISTS {self.table_name} (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL,
+            updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+        )
+        """  # nosec B608 - table_name is validated
+        await self.database.aexecute_query(sql)
+        self._initialized = True
+        logger.debug(f"Initialized table '{self.table_name}' for memory storage")
+
+    async def aget(self, key: str) -> Any:
+        """Retrieve a value from memory.
+
+        Parameters
+        ----------
+        key : str
+            The key to retrieve
+
+        Returns
+        -------
+        Any
+            The stored value, or None if key doesn't exist
+        """
+        if self.auto_init:
+            await self._ensure_table()
+
+        # Table name is validated, user data in parameters
+        sql = f"SELECT value FROM {self.table_name} WHERE key = :key"  # nosec B608
+        rows = await self.database.aexecute_query(sql, {"key": key})
+
+        if not rows:
+            return None
+
+        return rows[0]["value"]
+
+    async def aset(self, key: str, value: Any) -> None:
+        """Store a value in memory.
+
+        Parameters
+        ----------
+        key : str
+            The key to store under
+        value : Any
+            The value to store (must be serializable to string)
+        """
+        if self.auto_init:
+            await self._ensure_table()
+
+        # SQLite doesn't support standard UPSERT, use INSERT OR REPLACE
+        # Table name is validated, user data in parameters
+        sql = f"""
+        INSERT OR REPLACE INTO {self.table_name} (key, value, updated_at)
+        VALUES (:key, :value, CURRENT_TIMESTAMP)
+        """  # nosec B608
+        await self.database.aexecute_query(sql, {"key": key, "value": str(value)})
+        logger.debug(f"Stored key '{key}' in table '{self.table_name}'")
+
+    async def adelete(self, key: str) -> bool:
+        """Delete a key from memory.
+
+        Parameters
+        ----------
+        key : str
+            The key to delete
+
+        Returns
+        -------
+        bool
+            True if key existed and was deleted, False otherwise
+        """
+        if self.auto_init:
+            await self._ensure_table()
+
+        exists = await self.aget(key)
+        if exists is None:
+            return False
+
+        # Table name is validated, user data in parameters
+        sql = f"DELETE FROM {self.table_name} WHERE key = :key"  # nosec B608
+        await self.database.aexecute_query(sql, {"key": key})
+        logger.debug(f"Deleted key '{key}' from table '{self.table_name}'")
+        return True
+
+    async def alist_keys(self, prefix: str | None = None) -> list[str]:
+        """List all keys in memory, optionally filtered by prefix.
+
+        Parameters
+        ----------
+        prefix : str | None
+            Optional prefix to filter keys
+
+        Returns
+        -------
+        list[str]
+            List of matching keys
+        """
+        if self.auto_init:
+            await self._ensure_table()
+
+        if prefix:
+            # Table name is validated, user data in parameters
+            sql = f"SELECT key FROM {self.table_name} WHERE key LIKE :prefix"  # nosec B608
+            rows = await self.database.aexecute_query(sql, {"prefix": f"{prefix}%"})
+        else:
+            # Table name is validated
+            sql = f"SELECT key FROM {self.table_name}"  # nosec B608
+            rows = await self.database.aexecute_query(sql)
+
+        return [row["key"] for row in rows]
+
+    async def aclear(self) -> None:
+        """Clear all keys from memory."""
+        if self.auto_init:
+            await self._ensure_table()
+
+        # Table name is validated
+        sql = f"DELETE FROM {self.table_name}"  # nosec B608
+        await self.database.aexecute_query(sql)
+        logger.info(f"Cleared all keys from table '{self.table_name}'")
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return f"SQLiteMemoryAdapter(table='{self.table_name}')"

hexdag/builtin/adapters/memory/state_memory.py

@@ -0,0 +1,280 @@
+"""State Memory Plugin for structured entities and belief states."""
+
+import time
+from typing import Any
+
+from hexdag.builtin.adapters.memory.schemas import BeliefState, EntityState
+from hexdag.core.logging import get_logger
+from hexdag.core.ports.memory import Memory
+
+logger = get_logger(__name__)
+
+
+class StateMemoryPlugin:
+    """Memory plugin for structured state (entities, relationships, beliefs).
+
+    Wraps a base Memory adapter and provides domain-specific operations for:
+    - Entity state: entities with properties and relationships
+    - Belief state: Hinton-style probability distributions over hypotheses
+
+    This plugin does NOT store data itself - it delegates to the underlying
+    Memory port implementation and adds state management logic.
+
+    Example
+    -------
+        from hexdag.builtin.adapters.memory import InMemoryMemory
+
+        storage = InMemoryMemory()
+        state_memory = StateMemoryPlugin(storage=storage)
+
+        # Entity operations
+        await state_memory.update_entity("agent1", "user_123", {"name": "Alice"})
+        await state_memory.add_relationship("agent1", "user_123", "knows", "user_456")
+        entities = await state_memory.get_entities("agent1")
+
+        # Belief operations (Hinton-style Bayesian updates)
+        await state_memory.update_beliefs("agent1", {"hypothesis_a": 0.7}, "new evidence")
+        belief = await state_memory.get_belief_state("agent1")
+    """
+
+    plugin_type = "state"
+
+    def __init__(self, storage: Memory):
+        """Initialize state memory plugin.
+
+        Args
+        ----
+            storage: Base Memory port implementation (InMemoryMemory, SQLiteMemoryAdapter, etc.)
+        """
+        self.storage = storage
+
+    async def aget(self, key: str) -> Any:
+        """Get value from state scope.
+
+        Delegates to underlying storage with state:: prefix.
+        """
+        return await self.storage.aget(f"state::{key}")
+
+    async def aset(self, key: str, value: Any) -> None:
+        """Set value in state scope.
+
+        Delegates to underlying storage with state:: prefix.
+        """
+        await self.storage.aset(f"state::{key}", value)
+
+    # Entity state operations
+
+    async def get_entities(self, agent_id: str) -> EntityState:
+        """Get entity state for agent.
+
+        Args
+        ----
+            agent_id: Agent identifier
+
+        Returns
+        -------
+            EntityState with entities and relationships
+        """
+        data = await self.aget(f"entities:{agent_id}")
+        if data is None:
+            return EntityState(
+                entities={},
+                relationships=[],
+                updated_at=time.time(),
+            )
+        return EntityState.model_validate(data)
+
+    async def update_entity(
+        self,
+        agent_id: str,
+        entity_id: str,
+        properties: dict[str, Any],
+    ) -> None:
+        """Update or create entity with properties.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            entity_id: Entity identifier
+            properties: Entity properties to set/update
+        """
+        state = await self.get_entities(agent_id)
+        state.entities[entity_id] = properties
+        state.updated_at = time.time()
+        await self.aset(f"entities:{agent_id}", state.model_dump())
+        logger.debug("Updated entity %s for agent %s", entity_id, agent_id)
+
+    async def get_entity(
+        self,
+        agent_id: str,
+        entity_id: str,
+    ) -> dict[str, Any] | None:
+        """Get single entity by ID.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            entity_id: Entity identifier
+
+        Returns
+        -------
+            Entity properties or None if not found
+        """
+        state = await self.get_entities(agent_id)
+        return state.entities.get(entity_id)
+
+    async def add_relationship(
+        self,
+        agent_id: str,
+        subject: str,
+        predicate: str,
+        object: str,
+    ) -> None:
+        """Add relationship between entities.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            subject: Subject entity ID
+            predicate: Relationship type
+            object: Object entity ID
+        """
+        state = await self.get_entities(agent_id)
+        relationship = (subject, predicate, object)
+
+        # Avoid duplicates
+        if relationship not in state.relationships:
+            state.relationships.append(relationship)
+            state.updated_at = time.time()
+            await self.aset(f"entities:{agent_id}", state.model_dump())
+            logger.debug(
+                "Added relationship (%s, %s, %s) for agent %s",
+                subject,
+                predicate,
+                object,
+                agent_id,
+            )
+
+    async def query_relationships(
+        self,
+        agent_id: str,
+        subject: str | None = None,
+        predicate: str | None = None,
+        object: str | None = None,
+    ) -> list[tuple[str, str, str]]:
+        """Query relationships by subject, predicate, or object.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            subject: Optional subject to filter by
+            predicate: Optional predicate to filter by
+            object: Optional object to filter by
+
+        Returns
+        -------
+            List of matching relationships
+        """
+        state = await self.get_entities(agent_id)
+        results = []
+
+        for rel in state.relationships:
+            s, p, o = rel
+            if subject is not None and s != subject:
+                continue
+            if predicate is not None and p != predicate:
+                continue
+            if object is not None and o != object:
+                continue
+            results.append(rel)
+
+        return results
+
+    # Belief state operations (Hinton-style)
+
+    async def get_belief_state(self, agent_id: str) -> BeliefState:
+        """Get Hinton-style belief state for agent.
+
+        Args
+        ----
+            agent_id: Agent identifier
+
+        Returns
+        -------
+            BeliefState with probability distribution over hypotheses
+        """
+        data = await self.aget(f"belief:{agent_id}")
+        if data is None:
+            return BeliefState(
+                beliefs={},
+                confidence=0.0,
+                evidence=[],
+                updated_at=time.time(),
+            )
+        return BeliefState.model_validate(data)
+
+    async def update_beliefs(
+        self,
+        agent_id: str,
+        new_beliefs: dict[str, float],
+        evidence: str,
+    ) -> None:
+        """Bayesian belief update with new evidence.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            new_beliefs: New belief values (likelihoods)
+            evidence: Description of the evidence
+        """
+        state = await self.get_belief_state(agent_id)
+
+        # Bayesian update: P(H|E) ∝ P(E|H) * P(H)
+        for hypothesis, prior in list(state.beliefs.items()):
+            if hypothesis in new_beliefs:
+                likelihood = new_beliefs[hypothesis]
+                state.beliefs[hypothesis] = likelihood * prior
+
+        # Add new hypotheses
+        for hypothesis, prob in new_beliefs.items():
+            if hypothesis not in state.beliefs:
+                state.beliefs[hypothesis] = prob
+
+        # Normalize to sum to 1.0
+        total = sum(state.beliefs.values())
+        if total > 0:
+            state.beliefs = {h: p / total for h, p in state.beliefs.items()}
+
+        # Update confidence (max posterior probability)
+        state.confidence = max(state.beliefs.values()) if state.beliefs else 0.0
+
+        # Record evidence
+        state.evidence.append(evidence)
+        state.updated_at = time.time()
+
+        await self.aset(f"belief:{agent_id}", state.model_dump())
+        logger.debug(
+            "Updated beliefs for agent %s: confidence=%.2f",
+            agent_id,
+            state.confidence,
+        )
+
+    async def set_belief(
+        self,
+        agent_id: str,
+        hypothesis: str,
+        probability: float,
+    ) -> None:
+        """Set belief probability for single hypothesis.
+
+        Args
+        ----
+            agent_id: Agent identifier
+            hypothesis: Hypothesis name
+            probability: Belief probability (0.0-1.0)
+        """
+        state = await self.get_belief_state(agent_id)
+        state.beliefs[hypothesis] = max(0.0, min(1.0, probability))
+        state.confidence = max(state.beliefs.values()) if state.beliefs else 0.0
+        state.updated_at = time.time()
+        await self.aset(f"belief:{agent_id}", state.model_dump())