RouteKitAI 0.1.0__py3-none-any.whl

routekitai/memory/episodic.py

@@ -0,0 +1,242 @@
+"""Episodic memory with SQLite backend."""
+
+import json
+import sqlite3
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from routekitai.core.memory import Memory
+
+
+class EpisodicMemory(Memory):
+    """Episodic memory with SQLite-backed persistent store.
+
+    Stores episodes in a SQLite database with:
+    - id: Unique episode ID
+    - ts: Timestamp
+    - content: Episode content (JSON)
+    - metadata: Additional metadata (JSON)
+    """
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        """Initialize episodic memory.
+
+        Args:
+            db_path: Path to SQLite database file (defaults to .routekit/episodic.db)
+        """
+        if db_path is None:
+            db_path = Path(".routekit") / "episodic.db"
+        elif isinstance(db_path, str):
+            db_path = Path(db_path)
+
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize database schema."""
+        with sqlite3.connect(self.db_path) as conn:
+            # Enable WAL mode for better concurrent access and file locking on Windows
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS episodes (
+                    id TEXT PRIMARY KEY,
+                    ts REAL NOT NULL,
+                    content TEXT NOT NULL,
+                    metadata TEXT NOT NULL
+                )
+                """
+            )
+            conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_ts ON episodes(ts)
+                """
+            )
+            conn.commit()
+
+    async def get(self, key: str) -> Any:
+        """Get episode by ID.
+
+        Args:
+            key: Episode ID
+
+        Returns:
+            Episode data or None if not found
+        """
+        import asyncio
+
+        # SQLite operations are synchronous, but we need async interface
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._get_sync, key)
+
+    def _get_sync(self, key: str) -> Any:
+        """Synchronous get operation."""
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.execute(
+                "SELECT id, ts, content, metadata FROM episodes WHERE id = ?",
+                (key,),
+            )
+            row = cursor.fetchone()
+            if row:
+                return {
+                    "id": row["id"],
+                    "ts": row["ts"],
+                    "content": json.loads(row["content"]),
+                    "metadata": json.loads(row["metadata"]),
+                }
+        return None
+
+    async def set(self, key: str, value: Any) -> None:
+        """Store episode by ID.
+
+        Args:
+            key: Episode ID
+            value: Episode data (dict with content and optional metadata)
+        """
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._set_sync, key, value)
+
+    def _set_sync(self, key: str, value: Any) -> None:
+        """Synchronous set operation."""
+        if not isinstance(value, dict):
+            value = {"content": value}
+
+        content = value.get("content", {})
+        metadata = value.get("metadata", {})
+
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO episodes (id, ts, content, metadata)
+                VALUES (?, ?, ?, ?)
+                """,
+                (key, time.time(), json.dumps(content), json.dumps(metadata)),
+            )
+            conn.commit()
+
+    async def append(self, event: dict[str, Any]) -> None:
+        """Append an event as a new episode.
+
+        Args:
+            event: Event dictionary to append
+        """
+        import asyncio
+
+        episode_id = str(uuid.uuid4())
+        content = event.get("content", event)
+        metadata = event.get("metadata", {})
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(
+            None, self._set_sync, episode_id, {"content": content, "metadata": metadata}
+        )
+
+    async def search(self, query: str, k: int = 5) -> list[dict[str, Any]]:
+        """Search episodes by content (simple substring search for MVP).
+
+        Args:
+            query: Search query
+            k: Number of results to return
+
+        Returns:
+            List of matching episodes
+        """
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._search_sync, query, k)
+
+    def _search_sync(self, query: str, k: int) -> list[dict[str, Any]]:
+        """Synchronous search operation."""
+        results = []
+        query_lower = query.lower()
+
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.execute("SELECT id, ts, content, metadata FROM episodes ORDER BY ts DESC")
+            for row in cursor:
+                content_str = json.dumps(row["content"]).lower()
+                if query_lower in content_str:
+                    results.append(
+                        {
+                            "id": row["id"],
+                            "ts": row["ts"],
+                            "content": json.loads(row["content"]),
+                            "metadata": json.loads(row["metadata"]),
+                        }
+                    )
+                    if len(results) >= k:
+                        break
+
+        return results
+
+    async def get_recent(self, limit: int = 10) -> list[dict[str, Any]]:
+        """Get recent episodes.
+
+        Args:
+            limit: Maximum number of episodes to return
+
+        Returns:
+            List of recent episodes
+        """
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._get_recent_sync, limit)
+
+    def _get_recent_sync(self, limit: int) -> list[dict[str, Any]]:
+        """Synchronous get_recent operation."""
+        results = []
+        with sqlite3.connect(self.db_path) as conn:
+            conn.row_factory = sqlite3.Row
+            cursor = conn.execute(
+                "SELECT id, ts, content, metadata FROM episodes ORDER BY ts DESC LIMIT ?",
+                (limit,),
+            )
+            for row in cursor:
+                results.append(
+                    {
+                        "id": row["id"],
+                        "ts": row["ts"],
+                        "content": json.loads(row["content"]),
+                        "metadata": json.loads(row["metadata"]),
+                    }
+                )
+        return results
+
+    def close(self) -> None:
+        """Close any open database connections.
+
+        On Windows, SQLite can hold file locks briefly after connections close.
+        This method forces SQLite to release locks by opening and closing a connection.
+        """
+        import gc
+        import sys
+        import time
+
+        try:
+            # Force garbage collection to ensure any lingering connections are cleaned up
+            gc.collect()
+            # Open and immediately close a connection to ensure locks are released
+            # Use a short timeout to avoid hanging
+            with sqlite3.connect(str(self.db_path), timeout=1.0) as conn:
+                # Checkpoint WAL to ensure all data is written and locks are released
+                try:
+                    conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+                except sqlite3.Error:
+                    # WAL checkpoint may fail if not in WAL mode, ignore
+                    pass
+                # Execute a simple query to ensure connection is fully established
+                conn.execute("SELECT 1")
+                # On Windows, SQLite needs a moment to release file locks
+                if sys.platform == "win32":
+                    time.sleep(0.05)
+        except (sqlite3.Error, OSError, TimeoutError):
+            # Ignore errors during cleanup - file may already be closed or locked
+            pass

routekitai/memory/kv.py

@@ -0,0 +1,34 @@
+"""Key-value memory for agents."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class KVMemory(BaseModel):
+    """Key-value memory store for agent state.
+
+    TODO: Implement persistent key-value storage for agent memory.
+    """
+
+    store: dict[str, Any] = Field(default_factory=dict, description="In-memory key-value store")
+
+    async def get(self, key: str) -> Any:
+        """Get value by key.
+
+        Args:
+            key: Key to retrieve
+
+        Returns:
+            Stored value or None if not found
+        """
+        return self.store.get(key)
+
+    async def set(self, key: str, value: Any) -> None:
+        """Set value by key.
+
+        Args:
+            key: Key to set
+            value: Value to store
+        """
+        self.store[key] = value

routekitai/memory/retrieval.py

@@ -0,0 +1,192 @@
+"""Retrieval memory with TF-IDF/substring fallback."""
+
+import re
+from collections import Counter
+from typing import Any
+
+from routekitai.core.memory import Memory
+
+
+class RetrievalMemory(Memory):
+    """Retrieval memory with TF-IDF or substring search fallback.
+
+    For MVP, provides simple text-based retrieval without vector embeddings.
+    """
+
+    def __init__(self, use_tfidf: bool = True) -> None:
+        """Initialize retrieval memory.
+
+        Args:
+            use_tfidf: Whether to use TF-IDF (True) or simple substring search (False)
+        """
+        self.use_tfidf = use_tfidf
+        self._documents: list[dict[str, Any]] = []
+        self._idf: dict[str, float] = {}
+
+    async def get(self, key: str) -> Any:
+        """Get document by ID.
+
+        Args:
+            key: Document ID
+
+        Returns:
+            Document data or None if not found
+        """
+        for doc in self._documents:
+            if doc.get("id") == key:
+                return doc
+        return None
+
+    async def set(self, key: str, value: Any) -> None:
+        """Store document by ID.
+
+        Args:
+            key: Document ID
+            value: Document data
+        """
+        if isinstance(value, dict):
+            doc = value.copy()
+            doc["id"] = key
+        else:
+            doc = {"id": key, "content": value}
+
+        # Update or add document
+        for i, existing_doc in enumerate(self._documents):
+            if existing_doc.get("id") == key:
+                self._documents[i] = doc
+                self._update_idf()
+                return
+
+        self._documents.append(doc)
+        self._update_idf()
+
+    async def append(self, event: dict[str, Any]) -> None:
+        """Append an event as a new document.
+
+        Args:
+            event: Event dictionary to append
+        """
+        import uuid
+
+        doc_id = str(uuid.uuid4())
+        doc = event.copy()
+        doc["id"] = doc_id
+        # Ensure content field exists for search (extract from event if needed)
+        if "content" not in doc:
+            # Try to extract content from event
+            if isinstance(event, dict) and "content" in event:
+                doc["content"] = event["content"]
+            else:
+                doc["content"] = str(event)
+        self._documents.append(doc)
+        self._update_idf()
+
+    async def search(self, query: str, k: int = 5) -> list[dict[str, Any]]:
+        """Search documents using TF-IDF or substring matching.
+
+        Args:
+            query: Search query
+            k: Number of results to return
+
+        Returns:
+            List of matching documents with scores
+        """
+        if not self._documents:
+            return []
+
+        if self.use_tfidf:
+            return await self._search_tfidf(query, k)
+        else:
+            return await self._search_substring(query, k)
+
+    async def _search_tfidf(self, query: str, k: int) -> list[dict[str, Any]]:
+        """Search using TF-IDF scoring.
+
+        Args:
+            query: Search query
+            k: Number of results
+
+        Returns:
+            List of documents with TF-IDF scores
+        """
+        query_terms = self._tokenize(query)
+
+        scores = []
+        for doc in self._documents:
+            content = str(doc.get("content", ""))
+            doc_terms = self._tokenize(content)
+            doc_tf = Counter(doc_terms)
+
+            score = 0.0
+            for term in query_terms:
+                if term in doc_tf:
+                    tf = doc_tf[term] / len(doc_terms) if doc_terms else 0
+                    idf = self._idf.get(term, 0.0)
+                    score += tf * idf
+
+            if score > 0:
+                result = doc.copy()
+                result["score"] = score
+                scores.append(result)
+
+        # Sort by score descending
+        scores.sort(key=lambda x: x.get("score", 0), reverse=True)
+        return scores[:k]
+
+    async def _search_substring(self, query: str, k: int) -> list[dict[str, Any]]:
+        """Search using simple substring matching.
+
+        Args:
+            query: Search query
+            k: Number of results
+
+        Returns:
+            List of matching documents
+        """
+        query_lower = query.lower()
+        results = []
+
+        for doc in self._documents:
+            content = str(doc.get("content", "")).lower()
+            if query_lower in content:
+                result = doc.copy()
+                result["score"] = 1.0  # Simple binary match
+                results.append(result)
+                if len(results) >= k:
+                    break
+
+        return results
+
+    def _tokenize(self, text: str) -> list[str]:
+        """Tokenize text into words.
+
+        Args:
+            text: Text to tokenize
+
+        Returns:
+            List of lowercase tokens
+        """
+        # Simple tokenization: lowercase, split on non-word chars
+        tokens = re.findall(r"\b\w+\b", text.lower())
+        return tokens
+
+    def _update_idf(self) -> None:
+        """Update inverse document frequency for all terms."""
+        if not self._documents:
+            self._idf = {}
+            return
+
+        doc_count = len(self._documents)
+        term_doc_count: dict[str, int] = {}
+
+        for doc in self._documents:
+            content = str(doc.get("content", ""))
+            terms = set(self._tokenize(content))
+            for term in terms:
+                term_doc_count[term] = term_doc_count.get(term, 0) + 1
+
+        # Calculate IDF: log(total_docs / docs_with_term)
+        self._idf = {
+            term: __import__("math").log(doc_count / count) if count > 0 else 0.0
+            for term, count in term_doc_count.items()
+        }