keep-skill 0.1.0__py3-none-any.whl

keep/providers/llm.py

@@ -0,0 +1,371 @@
+"""
+Summarization and tagging providers using LLMs.
+"""
+
+import json
+import os
+from typing import Any
+
+from .base import SummarizationProvider, TaggingProvider, get_registry
+
+
+# -----------------------------------------------------------------------------
+# Summarization Providers
+# -----------------------------------------------------------------------------
+
+class AnthropicSummarization:
+    """
+    Summarization provider using Anthropic's Claude API.
+    
+    Requires: ANTHROPIC_API_KEY environment variable.
+    Optionally reads from OpenClaw config via OPENCLAW_CONFIG env var.
+    """
+    
+    SYSTEM_PROMPT = """You are a precise summarization assistant. 
+Create a concise summary of the provided document that captures:
+- The main purpose or topic
+- Key points or functionality
+- Important details that would help someone decide if this document is relevant
+
+Be factual and specific. Do not include phrases like "This document" - just state the content directly."""
+    
+    def __init__(
+        self,
+        model: str = "claude-3-5-haiku-20241022",
+        api_key: str | None = None,
+        max_tokens: int = 200,
+    ):
+        try:
+            from anthropic import Anthropic
+        except ImportError:
+            raise RuntimeError("AnthropicSummarization requires 'anthropic' library")
+        
+        self.model = model
+        self.max_tokens = max_tokens
+        
+        # Try environment variable first, then OpenClaw config
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not key:
+            # Try to read from OpenClaw config (OAuth tokens stored separately)
+            # For now, just require explicit API key
+            raise ValueError("ANTHROPIC_API_KEY environment variable required")
+        
+        self.client = Anthropic(api_key=key)
+    
+    def summarize(self, content: str) -> str:
+        """Generate summary using Anthropic Claude."""
+        # Truncate very long content
+        truncated = content[:50000] if len(content) > 50000 else content
+        
+        try:
+            response = self.client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=self.SYSTEM_PROMPT,
+                messages=[
+                    {"role": "user", "content": truncated}
+                ],
+            )
+            
+            # Extract text from response
+            if response.content and len(response.content) > 0:
+                return response.content[0].text
+            return truncated[:500]  # Fallback
+        except Exception as e:
+            # Fallback to truncation on error
+            return truncated[:500]
+
+
+class OpenAISummarization:
+    """
+    Summarization provider using OpenAI's chat API.
+    
+    Requires: KEEP_OPENAI_API_KEY or OPENAI_API_KEY environment variable.
+    """
+    
+    SYSTEM_PROMPT = """You are a precise summarization assistant. 
+Create a concise summary of the provided document that captures:
+- The main purpose or topic
+- Key points or functionality
+- Important details that would help someone decide if this document is relevant
+
+Be factual and specific. Do not include phrases like "This document" - just state the content directly."""
+    
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        api_key: str | None = None,
+        max_tokens: int = 200,
+    ):
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise RuntimeError("OpenAISummarization requires 'openai' library")
+        
+        self.model = model
+        self.max_tokens = max_tokens
+        
+        key = api_key or os.environ.get("KEEP_OPENAI_API_KEY") or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise ValueError("OpenAI API key required")
+        
+        self._client = OpenAI(api_key=key)
+    
+    def summarize(self, content: str, *, max_length: int = 500) -> str:
+        """Generate a summary using OpenAI."""
+        # Truncate very long content to avoid token limits
+        truncated = content[:50000] if len(content) > 50000 else content
+        
+        response = self._client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": self.SYSTEM_PROMPT},
+                {"role": "user", "content": truncated},
+            ],
+            max_tokens=self.max_tokens,
+            temperature=0.3,
+        )
+        
+        return response.choices[0].message.content.strip()
+
+
+class OllamaSummarization:
+    """
+    Summarization provider using Ollama's local API.
+    """
+    
+    SYSTEM_PROMPT = OpenAISummarization.SYSTEM_PROMPT
+    
+    def __init__(
+        self,
+        model: str = "llama3.2",
+        base_url: str = "http://localhost:11434",
+    ):
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+    
+    def summarize(self, content: str, *, max_length: int = 500) -> str:
+        """Generate a summary using Ollama."""
+        import requests
+        
+        truncated = content[:50000] if len(content) > 50000 else content
+        
+        response = requests.post(
+            f"{self.base_url}/api/chat",
+            json={
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": self.SYSTEM_PROMPT},
+                    {"role": "user", "content": truncated},
+                ],
+                "stream": False,
+            },
+        )
+        response.raise_for_status()
+        
+        return response.json()["message"]["content"].strip()
+
+
+class PassthroughSummarization:
+    """
+    Summarization provider that returns the first N characters.
+    
+    Useful for testing or when LLM summarization is not needed.
+    """
+    
+    def __init__(self, max_chars: int = 500):
+        self.max_chars = max_chars
+    
+    def summarize(self, content: str, *, max_length: int = 500) -> str:
+        """Return truncated content as summary."""
+        limit = min(self.max_chars, max_length)
+        if len(content) <= limit:
+            return content
+        return content[:limit].rsplit(" ", 1)[0] + "..."
+
+
+# -----------------------------------------------------------------------------
+# Tagging Providers
+# -----------------------------------------------------------------------------
+
+class AnthropicTagging:
+    """
+    Tagging provider using Anthropic's Claude API with JSON output.
+    """
+    
+    SYSTEM_PROMPT = """Analyze the document and generate relevant tags as a JSON object.
+
+Generate tags for these categories when applicable:
+- content_type: The type of content (e.g., "documentation", "code", "article", "config")
+- language: Programming language if code (e.g., "python", "javascript")
+- domain: Subject domain (e.g., "authentication", "database", "api", "testing")
+- framework: Framework or library if relevant (e.g., "react", "django", "fastapi")
+
+Only include tags that clearly apply. Values should be lowercase.
+
+Respond with a JSON object only, no explanation."""
+    
+    def __init__(
+        self,
+        model: str = "claude-3-5-haiku-20241022",
+        api_key: str | None = None,
+    ):
+        try:
+            from anthropic import Anthropic
+        except ImportError:
+            raise RuntimeError("AnthropicTagging requires 'anthropic' library")
+        
+        self.model = model
+        
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not key:
+            raise ValueError("ANTHROPIC_API_KEY environment variable required")
+        
+        self._client = Anthropic(api_key=key)
+    
+    def tag(self, content: str) -> dict[str, str]:
+        """Generate tags using Anthropic Claude."""
+        truncated = content[:20000] if len(content) > 20000 else content
+        
+        try:
+            response = self._client.messages.create(
+                model=self.model,
+                max_tokens=200,
+                temperature=0.2,
+                system=self.SYSTEM_PROMPT,
+                messages=[
+                    {"role": "user", "content": truncated}
+                ],
+            )
+            
+            # Parse JSON from response
+            if response.content and len(response.content) > 0:
+                tags = json.loads(response.content[0].text)
+                return {str(k): str(v) for k, v in tags.items()}
+            return {}
+        except (json.JSONDecodeError, Exception):
+            return {}
+
+
+class OpenAITagging:
+    """
+    Tagging provider using OpenAI's chat API with JSON output.
+    """
+    
+    SYSTEM_PROMPT = """Analyze the document and generate relevant tags as a JSON object.
+
+Generate tags for these categories when applicable:
+- content_type: The type of content (e.g., "documentation", "code", "article", "config")
+- language: Programming language if code (e.g., "python", "javascript")
+- domain: Subject domain (e.g., "authentication", "database", "api", "testing")
+- framework: Framework or library if relevant (e.g., "react", "django", "fastapi")
+
+Only include tags that clearly apply. Values should be lowercase.
+
+Respond with a JSON object only, no explanation."""
+    
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        api_key: str | None = None,
+    ):
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise RuntimeError("OpenAITagging requires 'openai' library")
+        
+        self.model = model
+        
+        key = api_key or os.environ.get("KEEP_OPENAI_API_KEY") or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise ValueError("OpenAI API key required")
+        
+        self._client = OpenAI(api_key=key)
+    
+    def tag(self, content: str) -> dict[str, str]:
+        """Generate tags using OpenAI."""
+        truncated = content[:20000] if len(content) > 20000 else content
+        
+        response = self._client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": self.SYSTEM_PROMPT},
+                {"role": "user", "content": truncated},
+            ],
+            response_format={"type": "json_object"},
+            max_tokens=200,
+            temperature=0.2,
+        )
+        
+        try:
+            tags = json.loads(response.choices[0].message.content)
+            # Ensure all values are strings
+            return {str(k): str(v) for k, v in tags.items()}
+        except json.JSONDecodeError:
+            return {}
+
+
+class OllamaTagging:
+    """
+    Tagging provider using Ollama's local API.
+    """
+    
+    SYSTEM_PROMPT = OpenAITagging.SYSTEM_PROMPT
+    
+    def __init__(
+        self,
+        model: str = "llama3.2",
+        base_url: str = "http://localhost:11434",
+    ):
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+    
+    def tag(self, content: str) -> dict[str, str]:
+        """Generate tags using Ollama."""
+        import requests
+        
+        truncated = content[:20000] if len(content) > 20000 else content
+        
+        response = requests.post(
+            f"{self.base_url}/api/chat",
+            json={
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": self.SYSTEM_PROMPT},
+                    {"role": "user", "content": truncated},
+                ],
+                "format": "json",
+                "stream": False,
+            },
+        )
+        response.raise_for_status()
+        
+        try:
+            tags = json.loads(response.json()["message"]["content"])
+            return {str(k): str(v) for k, v in tags.items()}
+        except (json.JSONDecodeError, KeyError):
+            return {}
+
+
+class NoopTagging:
+    """
+    Tagging provider that returns empty tags.
+    
+    Useful when tagging is disabled or for testing.
+    """
+    
+    def tag(self, content: str) -> dict[str, str]:
+        """Return empty tags."""
+        return {}
+
+
+# Register providers
+_registry = get_registry()
+_registry.register_summarization("anthropic", AnthropicSummarization)
+_registry.register_summarization("openai", OpenAISummarization)
+_registry.register_summarization("ollama", OllamaSummarization)
+_registry.register_summarization("passthrough", PassthroughSummarization)
+_registry.register_tagging("anthropic", AnthropicTagging)
+_registry.register_tagging("openai", OpenAITagging)
+_registry.register_tagging("ollama", OllamaTagging)
+_registry.register_tagging("noop", NoopTagging)

keep/providers/mlx.py

@@ -0,0 +1,256 @@
+"""
+MLX providers for Apple Silicon.
+
+MLX is Apple's ML framework optimized for Apple Silicon. These providers
+run entirely locally with no API keys required.
+
+Requires: pip install mlx-lm mlx
+"""
+
+import os
+from typing import Any
+
+from .base import EmbeddingProvider, SummarizationProvider, get_registry
+
+
+class MLXEmbedding:
+    """
+    Embedding provider using MLX on Apple Silicon.
+    
+    Uses sentence-transformer compatible models converted to MLX format.
+    
+    Requires: pip install mlx sentence-transformers
+    """
+    
+    def __init__(self, model: str = "mlx-community/bge-small-en-v1.5"):
+        """
+        Args:
+            model: Model name from mlx-community hub or local path.
+                   Good options:
+                   - mlx-community/bge-small-en-v1.5 (small, fast)
+                   - mlx-community/bge-base-en-v1.5 (balanced)
+                   - mlx-community/bge-large-en-v1.5 (best quality)
+        """
+        try:
+            import mlx.core as mx
+            from sentence_transformers import SentenceTransformer
+        except ImportError:
+            raise RuntimeError(
+                "MLXEmbedding requires 'mlx' and 'sentence-transformers'. "
+                "Install with: pip install mlx sentence-transformers"
+            )
+        
+        self.model_name = model
+        
+        # sentence-transformers can use MLX backend on Apple Silicon
+        # For MLX-specific models, we use the direct approach
+        if model.startswith("mlx-community/"):
+            # Use sentence-transformers which auto-detects MLX
+            self._model = SentenceTransformer(model, device="mps")
+        else:
+            self._model = SentenceTransformer(model)
+        
+        self._dimension: int | None = None
+    
+    @property
+    def dimension(self) -> int:
+        """Get embedding dimension from the model."""
+        if self._dimension is None:
+            self._dimension = self._model.get_sentence_embedding_dimension()
+        return self._dimension
+    
+    def embed(self, text: str) -> list[float]:
+        """Generate embedding for a single text."""
+        embedding = self._model.encode(text, convert_to_numpy=True)
+        return embedding.tolist()
+    
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts."""
+        embeddings = self._model.encode(texts, convert_to_numpy=True)
+        return embeddings.tolist()
+
+
+class MLXSummarization:
+    """
+    Summarization provider using MLX-LM on Apple Silicon.
+    
+    Runs local LLMs optimized for Apple Silicon. No API key required.
+    
+    Requires: pip install mlx-lm
+    """
+    
+    SYSTEM_PROMPT = """You are a precise summarization assistant. 
+Create a concise summary of the provided document that captures:
+- The main purpose or topic
+- Key points or functionality
+- Important details that would help someone decide if this document is relevant
+
+Be factual and specific. Do not include phrases like "This document" - just state the content directly.
+Keep the summary under 200 words."""
+    
+    def __init__(
+        self,
+        model: str = "mlx-community/Llama-3.2-3B-Instruct-4bit",
+        max_tokens: int = 300,
+    ):
+        """
+        Args:
+            model: Model name from mlx-community hub or local path.
+                   Good options for summarization:
+                   - mlx-community/Llama-3.2-3B-Instruct-4bit (fast, small)
+                   - mlx-community/Llama-3.2-8B-Instruct-4bit (better quality)
+                   - mlx-community/Mistral-7B-Instruct-v0.3-4bit (good balance)
+                   - mlx-community/Phi-3.5-mini-instruct-4bit (very fast)
+            max_tokens: Maximum tokens in generated summary
+        """
+        try:
+            from mlx_lm import load
+        except ImportError:
+            raise RuntimeError(
+                "MLXSummarization requires 'mlx-lm'. "
+                "Install with: pip install mlx-lm"
+            )
+        
+        self.model_name = model
+        self.max_tokens = max_tokens
+        
+        # Load model and tokenizer (downloads on first use)
+        self._model, self._tokenizer = load(model)
+    
+    def summarize(self, content: str, *, max_length: int = 500) -> str:
+        """Generate a summary using MLX-LM."""
+        from mlx_lm import generate
+        
+        # Truncate very long content to fit context window
+        # Most models have 4k-8k context, leave room for prompt and response
+        max_content_chars = 12000
+        truncated = content[:max_content_chars] if len(content) > max_content_chars else content
+        
+        # Format as chat (works with instruction-tuned models)
+        if hasattr(self._tokenizer, "apply_chat_template"):
+            messages = [
+                {"role": "system", "content": self.SYSTEM_PROMPT},
+                {"role": "user", "content": f"Summarize the following:\n\n{truncated}"},
+            ]
+            prompt = self._tokenizer.apply_chat_template(
+                messages, 
+                tokenize=False, 
+                add_generation_prompt=True
+            )
+        else:
+            # Fallback for models without chat template
+            prompt = f"{self.SYSTEM_PROMPT}\n\nDocument:\n{truncated}\n\nSummary:"
+        
+        # Generate
+        response = generate(
+            self._model,
+            self._tokenizer,
+            prompt=prompt,
+            max_tokens=self.max_tokens,
+            verbose=False,
+        )
+        
+        return response.strip()
+
+
+class MLXTagging:
+    """
+    Tagging provider using MLX-LM on Apple Silicon.
+    
+    Uses local LLMs to generate structured tags. No API key required.
+    
+    Requires: pip install mlx-lm
+    """
+    
+    SYSTEM_PROMPT = """Analyze the document and generate relevant tags as a JSON object.
+
+Generate tags for these categories when applicable:
+- content_type: The type of content (e.g., "documentation", "code", "article", "config")
+- language: Programming language if code (e.g., "python", "javascript")
+- domain: Subject domain (e.g., "authentication", "database", "api", "testing")
+- framework: Framework or library if relevant (e.g., "react", "django", "fastapi")
+
+Only include tags that clearly apply. Values should be lowercase.
+Respond with ONLY a JSON object, no explanation or other text."""
+    
+    def __init__(
+        self,
+        model: str = "mlx-community/Llama-3.2-3B-Instruct-4bit",
+        max_tokens: int = 150,
+    ):
+        """
+        Args:
+            model: Model name from mlx-community hub
+            max_tokens: Maximum tokens in generated response
+        """
+        try:
+            from mlx_lm import load
+        except ImportError:
+            raise RuntimeError(
+                "MLXTagging requires 'mlx-lm'. "
+                "Install with: pip install mlx-lm"
+            )
+        
+        self.model_name = model
+        self.max_tokens = max_tokens
+        self._model, self._tokenizer = load(model)
+    
+    def tag(self, content: str) -> dict[str, str]:
+        """Generate tags using MLX-LM."""
+        import json
+        from mlx_lm import generate
+        
+        # Truncate content
+        max_content_chars = 8000
+        truncated = content[:max_content_chars] if len(content) > max_content_chars else content
+        
+        # Format prompt
+        if hasattr(self._tokenizer, "apply_chat_template"):
+            messages = [
+                {"role": "system", "content": self.SYSTEM_PROMPT},
+                {"role": "user", "content": truncated},
+            ]
+            prompt = self._tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True
+            )
+        else:
+            prompt = f"{self.SYSTEM_PROMPT}\n\nDocument:\n{truncated}\n\nJSON:"
+        
+        response = generate(
+            self._model,
+            self._tokenizer,
+            prompt=prompt,
+            max_tokens=self.max_tokens,
+            verbose=False,
+        )
+        
+        # Parse JSON from response
+        try:
+            # Try to extract JSON from response
+            response = response.strip()
+            # Handle case where model includes markdown code fence
+            if response.startswith("```"):
+                response = response.split("```")[1]
+                if response.startswith("json"):
+                    response = response[4:]
+            
+            tags = json.loads(response)
+            return {str(k): str(v) for k, v in tags.items()}
+        except (json.JSONDecodeError, IndexError):
+            return {}
+
+
+def is_apple_silicon() -> bool:
+    """Check if running on Apple Silicon."""
+    import platform
+    return platform.system() == "Darwin" and platform.machine() == "arm64"
+
+
+# Register providers (only on Apple Silicon)
+if is_apple_silicon():
+    _registry = get_registry()
+    _registry.register_embedding("mlx", MLXEmbedding)
+    _registry.register_summarization("mlx", MLXSummarization)
+    _registry.register_tagging("mlx", MLXTagging)