keep-skill 0.1.0__py3-none-any.whl

keep/logging_config.py

@@ -0,0 +1,73 @@
+"""
+Logging configuration for keep.
+
+Suppress verbose library output by default for better UX.
+"""
+
+import os
+import sys
+import warnings
+
+# Set environment variables BEFORE any imports to suppress warnings early
+if not os.environ.get("KEEP_VERBOSE"):
+    os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+    os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+    os.environ["TOKENIZERS_PARALLELISM"] = "false"
+    os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"
+    os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+
+
+def configure_quiet_mode(quiet: bool = True):
+    """
+    Configure logging to suppress verbose library output.
+    
+    This silences:
+    - HuggingFace transformers progress bars
+    - MLX model loading messages
+    - Library warnings (deprecation, etc.)
+    
+    Args:
+        quiet: If True, suppress verbose output. If False, show everything.
+    """
+    if quiet:
+        # Suppress HuggingFace progress bars and warnings
+        os.environ["HF_HUB_DISABLE_PROGRESS_BARS"] = "1"
+        os.environ["TRANSFORMERS_VERBOSITY"] = "error"
+        os.environ["TOKENIZERS_PARALLELISM"] = "false"
+        
+        # Suppress Python warnings (including deprecation warnings)
+        warnings.filterwarnings("ignore")
+        
+        # Suppress MLX verbosity if available
+        try:
+            import mlx.core as mx
+            # MLX doesn't have a global verbosity setting currently,
+            # but we can redirect stderr if needed
+        except ImportError:
+            pass
+        
+        # Configure Python logging to be less verbose
+        import logging
+        logging.getLogger("transformers").setLevel(logging.ERROR)
+        logging.getLogger("sentence_transformers").setLevel(logging.ERROR)
+        logging.getLogger("mlx").setLevel(logging.ERROR)
+        logging.getLogger("chromadb").setLevel(logging.ERROR)
+
+
+def enable_verbose_mode():
+    """Re-enable verbose output for debugging."""
+    configure_quiet_mode(quiet=False)
+    
+    # Restore defaults
+    os.environ.pop("HF_HUB_DISABLE_PROGRESS_BARS", None)
+    os.environ.pop("TRANSFORMERS_VERBOSITY", None)
+    
+    # Re-enable warnings
+    warnings.filterwarnings("default")
+    
+    # Reset logging levels
+    import logging
+    logging.getLogger("transformers").setLevel(logging.INFO)
+    logging.getLogger("sentence_transformers").setLevel(logging.INFO)
+    logging.getLogger("mlx").setLevel(logging.INFO)
+    logging.getLogger("chromadb").setLevel(logging.INFO)

keep/paths.py

@@ -0,0 +1,67 @@
+"""
+Utility functions for locating paths.
+"""
+
+import os
+import warnings
+from pathlib import Path
+from typing import Optional
+
+
+def find_git_root(start_path: Optional[Path] = None) -> Optional[Path]:
+    """
+    Find the root of the git repository containing the given path.
+    
+    Args:
+        start_path: Path to start searching from. Defaults to cwd.
+    
+    Returns:
+        Path to git root, or None if not in a git repository.
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+    
+    current = start_path.resolve()
+    
+    while current != current.parent:
+        if (current / ".git").exists():
+            return current
+        current = current.parent
+    
+    # Check root as well
+    if (current / ".git").exists():
+        return current
+    
+    return None
+
+
+def get_default_store_path() -> Path:
+    """
+    Get the default store path.
+
+    Priority:
+    1. KEEP_STORE_PATH environment variable
+    2. .keep/ directory at git repository root
+    3. ~/.keep/ in user's home directory (if not in a repo)
+
+    Returns:
+        Path to the store directory (may not exist yet).
+    """
+    # Check environment variable first
+    env_path = os.environ.get("KEEP_STORE_PATH")
+    if env_path:
+        return Path(env_path).resolve()
+    
+    # Try to find git root
+    git_root = find_git_root()
+    if git_root:
+        return git_root / ".keep"
+
+    # Fall back to home directory with warning
+    home = Path.home()
+    warnings.warn(
+        f"Not in a git repository. Using {home / '.keep'} for storage. "
+        f"Set KEEP_STORE_PATH to specify a different location.",
+        stacklevel=2,
+    )
+    return home / ".keep"

keep/pending_summaries.py

@@ -0,0 +1,166 @@
+"""
+Pending summaries queue using SQLite.
+
+Stores content that needs summarization for later processing.
+This enables fast indexing with lazy summarization.
+"""
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class PendingSummary:
+    """A queued item awaiting summarization."""
+    id: str
+    collection: str
+    content: str
+    queued_at: str
+    attempts: int = 0
+
+
+class PendingSummaryQueue:
+    """
+    SQLite-backed queue for pending summarizations.
+
+    Items are added during fast indexing (with truncated placeholder summary)
+    and processed later by `keep process-pending` or programmatically.
+    """
+
+    def __init__(self, queue_path: Path):
+        """
+        Args:
+            queue_path: Path to SQLite database file
+        """
+        self._queue_path = queue_path
+        self._conn: Optional[sqlite3.Connection] = None
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize the SQLite database."""
+        self._queue_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self._queue_path), check_same_thread=False)
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS pending_summaries (
+                id TEXT NOT NULL,
+                collection TEXT NOT NULL,
+                content TEXT NOT NULL,
+                queued_at TEXT NOT NULL,
+                attempts INTEGER DEFAULT 0,
+                PRIMARY KEY (id, collection)
+            )
+        """)
+        self._conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_queued_at
+            ON pending_summaries(queued_at)
+        """)
+        self._conn.commit()
+
+    def enqueue(self, id: str, collection: str, content: str) -> None:
+        """
+        Add an item to the pending queue.
+
+        If the same id+collection already exists, replaces it (newer content wins).
+        """
+        now = datetime.now(timezone.utc).isoformat()
+        self._conn.execute("""
+            INSERT OR REPLACE INTO pending_summaries
+            (id, collection, content, queued_at, attempts)
+            VALUES (?, ?, ?, ?, 0)
+        """, (id, collection, content, now))
+        self._conn.commit()
+
+    def dequeue(self, limit: int = 10) -> list[PendingSummary]:
+        """
+        Get the oldest pending items for processing.
+
+        Items are returned but not removed - call `complete()` after successful processing.
+        Increments attempt counter on each dequeue.
+        """
+        cursor = self._conn.execute("""
+            SELECT id, collection, content, queued_at, attempts
+            FROM pending_summaries
+            ORDER BY queued_at ASC
+            LIMIT ?
+        """, (limit,))
+
+        items = []
+        for row in cursor.fetchall():
+            items.append(PendingSummary(
+                id=row[0],
+                collection=row[1],
+                content=row[2],
+                queued_at=row[3],
+                attempts=row[4],
+            ))
+
+        # Increment attempt counters
+        if items:
+            ids = [(item.id, item.collection) for item in items]
+            self._conn.executemany("""
+                UPDATE pending_summaries
+                SET attempts = attempts + 1
+                WHERE id = ? AND collection = ?
+            """, ids)
+            self._conn.commit()
+
+        return items
+
+    def complete(self, id: str, collection: str) -> None:
+        """Remove an item from the queue after successful processing."""
+        self._conn.execute("""
+            DELETE FROM pending_summaries
+            WHERE id = ? AND collection = ?
+        """, (id, collection))
+        self._conn.commit()
+
+    def count(self) -> int:
+        """Get count of pending items."""
+        cursor = self._conn.execute("SELECT COUNT(*) FROM pending_summaries")
+        return cursor.fetchone()[0]
+
+    def stats(self) -> dict:
+        """Get queue statistics."""
+        cursor = self._conn.execute("""
+            SELECT
+                COUNT(*) as total,
+                COUNT(DISTINCT collection) as collections,
+                MAX(attempts) as max_attempts,
+                MIN(queued_at) as oldest
+            FROM pending_summaries
+        """)
+        row = cursor.fetchone()
+        return {
+            "pending": row[0],
+            "collections": row[1],
+            "max_attempts": row[2] or 0,
+            "oldest": row[3],
+            "queue_path": str(self._queue_path),
+        }
+
+    def clear(self) -> int:
+        """Clear all pending items. Returns count of items cleared."""
+        count = self.count()
+        self._conn.execute("DELETE FROM pending_summaries")
+        self._conn.commit()
+        return count
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def __del__(self):
+        """Ensure connection is closed on garbage collection."""
+        self.close()

keep/providers/__init__.py

@@ -0,0 +1,40 @@
+"""
+Provider interfaces for associative memory services.
+
+Each provider type defines a protocol that concrete implementations must follow.
+Providers are configured at store initialization and handle the heavy lifting of:
+- Embedding generation (for semantic search)
+- Summarization (for human-readable recall)
+- Tagging (for structured navigation)
+- Document fetching (for URI resolution)
+
+Concrete providers are lazily loaded when first requested via the registry.
+This avoids import-time failures when optional dependencies are missing.
+"""
+
+from .base import (
+    Document,
+    EmbeddingProvider,
+    SummarizationProvider,
+    TaggingProvider,
+    DocumentProvider,
+    ProviderRegistry,
+    get_registry,
+)
+
+# Providers are now loaded lazily by ProviderRegistry._ensure_providers_loaded()
+# This avoids import-time failures when optional dependencies are missing
+
+__all__ = [
+    # Protocols
+    "EmbeddingProvider",
+    "SummarizationProvider", 
+    "TaggingProvider",
+    "DocumentProvider",
+    # Data types
+    "Document",
+    # Registry
+    "ProviderRegistry",
+    "get_registry",
+]
+