alma-memory 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

alma/extraction/auto_learner.py

@@ -0,0 +1,265 @@
+"""
+ALMA Auto-Learning Module.
+
+Bridges LLM-powered fact extraction with ALMA's learning protocols.
+Enables Mem0-style automatic learning from conversations.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from alma.extraction import (
+    ExtractedFact,
+    FactExtractor,
+    FactType,
+    create_extractor,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AutoLearner:
+    """
+    Automatic learning from conversations.
+
+    This class bridges the gap between Mem0's automatic extraction
+    and ALMA's explicit learning protocols. It:
+
+    1. Extracts facts from conversations using LLM or rules
+    2. Validates facts against agent scopes
+    3. Deduplicates against existing memories
+    4. Commits valid facts to ALMA storage
+
+    Usage:
+        alma = ALMA.from_config(".alma/config.yaml")
+        auto_learner = AutoLearner(alma)
+
+        # After a conversation
+        results = auto_learner.learn_from_conversation(
+            messages=[
+                {"role": "user", "content": "Test the login form"},
+                {"role": "assistant", "content": "I tested using incremental validation..."},
+            ],
+            agent="helena",
+        )
+    """
+
+    def __init__(
+        self,
+        alma,  # ALMA instance - avoid circular import
+        extractor: Optional[FactExtractor] = None,
+        auto_commit: bool = True,
+        min_confidence: float = 0.5,
+    ):
+        """
+        Initialize AutoLearner.
+
+        Args:
+            alma: ALMA instance for storage and retrieval
+            extractor: Custom extractor, or None for auto-detection
+            auto_commit: Whether to automatically commit extracted facts
+            min_confidence: Minimum confidence threshold for facts
+        """
+        self.alma = alma
+        self.extractor = extractor or create_extractor()
+        self.auto_commit = auto_commit
+        self.min_confidence = min_confidence
+
+    def learn_from_conversation(
+        self,
+        messages: List[Dict[str, str]],
+        agent: str,
+        user_id: Optional[str] = None,
+        commit: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """
+        Extract and learn from a conversation.
+
+        Args:
+            messages: Conversation messages
+            agent: Agent that had the conversation
+            user_id: Optional user ID for preferences
+            commit: Override auto_commit setting
+
+        Returns:
+            Dict with extraction results and commit status
+        """
+        should_commit = commit if commit is not None else self.auto_commit
+
+        # Get agent scope for context
+        scope = self.alma.scopes.get(agent)
+        agent_context = None
+        if scope:
+            agent_context = f"Agent '{agent}' can learn: {scope.can_learn}. Cannot learn: {scope.cannot_learn}"
+
+        # Get existing facts to avoid duplicates
+        existing_memories = self.alma.retrieve(
+            task=" ".join(m["content"] for m in messages[-3:]),  # Recent context
+            agent=agent,
+            top_k=20,
+        )
+        existing_facts = []
+        for h in existing_memories.heuristics:
+            existing_facts.append(f"{h.condition}: {h.strategy}")
+        for ap in existing_memories.anti_patterns:
+            existing_facts.append(f"AVOID: {ap.pattern}")
+        for dk in existing_memories.domain_knowledge:
+            existing_facts.append(dk.fact)
+
+        # Extract facts
+        extraction_result = self.extractor.extract(
+            messages=messages,
+            agent_context=agent_context,
+            existing_facts=existing_facts if existing_facts else None,
+        )
+
+        # Filter by confidence and scope
+        valid_facts = []
+        rejected_facts = []
+
+        for fact in extraction_result.facts:
+            # Check confidence
+            if fact.confidence < self.min_confidence:
+                rejected_facts.append(
+                    {
+                        "fact": fact,
+                        "reason": f"Low confidence: {fact.confidence} < {self.min_confidence}",
+                    }
+                )
+                continue
+
+            # Check scope for heuristics and anti-patterns
+            if scope and fact.fact_type in (FactType.HEURISTIC, FactType.ANTI_PATTERN):
+                # Infer domain from content
+                inferred_domain = self._infer_domain(fact.content)
+                if inferred_domain and not scope.is_allowed(inferred_domain):
+                    rejected_facts.append(
+                        {
+                            "fact": fact,
+                            "reason": f"Outside agent scope: {inferred_domain}",
+                        }
+                    )
+                    continue
+
+            valid_facts.append(fact)
+
+        # Commit if enabled
+        committed = []
+        if should_commit:
+            for fact in valid_facts:
+                try:
+                    result = self._commit_fact(fact, agent, user_id)
+                    if result:
+                        committed.append({"fact": fact, "id": result})
+                except Exception as e:
+                    logger.error(f"Failed to commit fact: {e}")
+                    rejected_facts.append(
+                        {
+                            "fact": fact,
+                            "reason": f"Commit failed: {str(e)}",
+                        }
+                    )
+
+        return {
+            "extracted_count": len(extraction_result.facts),
+            "valid_count": len(valid_facts),
+            "committed_count": len(committed),
+            "rejected_count": len(rejected_facts),
+            "extraction_time_ms": extraction_result.extraction_time_ms,
+            "tokens_used": extraction_result.tokens_used,
+            "committed": committed,
+            "rejected": rejected_facts,
+            "valid_facts": valid_facts,
+        }
+
+    def _commit_fact(
+        self,
+        fact: ExtractedFact,
+        agent: str,
+        user_id: Optional[str],
+    ) -> Optional[str]:
+        """Commit a single fact to ALMA storage."""
+
+        if fact.fact_type == FactType.HEURISTIC:
+            # Use learning protocol for heuristics
+            return self.alma.learning.add_heuristic_direct(
+                agent=agent,
+                project_id=self.alma.project_id,
+                condition=fact.condition or fact.content,
+                strategy=fact.strategy or fact.content,
+                confidence=fact.confidence,
+                metadata={"source": "auto_extraction"},
+            )
+
+        elif fact.fact_type == FactType.ANTI_PATTERN:
+            return self.alma.learning.add_anti_pattern(
+                agent=agent,
+                project_id=self.alma.project_id,
+                pattern=fact.content,
+                why_bad=fact.condition,
+                better_alternative=fact.strategy,
+            )
+
+        elif fact.fact_type == FactType.PREFERENCE:
+            if user_id:
+                pref = self.alma.add_user_preference(
+                    user_id=user_id,
+                    category=fact.category or "general",
+                    preference=fact.content,
+                    source="auto_extraction",
+                )
+                return pref.id
+
+        elif fact.fact_type == FactType.DOMAIN_KNOWLEDGE:
+            # add_domain_knowledge now raises ScopeViolationError instead of returning None
+            knowledge = self.alma.add_domain_knowledge(
+                agent=agent,
+                domain=fact.domain or "general",
+                fact=fact.content,
+                source="auto_extraction",
+            )
+            return knowledge.id
+
+        elif fact.fact_type == FactType.OUTCOME:
+            # Outcomes need success/failure info we don't have
+            # Store as domain knowledge instead
+            knowledge = self.alma.add_domain_knowledge(
+                agent=agent,
+                domain="outcomes",
+                fact=fact.content,
+                source="auto_extraction",
+            )
+            return knowledge.id
+
+        return None
+
+    def _infer_domain(self, content: str) -> Optional[str]:
+        """Infer domain from fact content using keywords."""
+        content_lower = content.lower()
+
+        domain_keywords = {
+            "testing": ["test", "assert", "selenium", "playwright", "cypress"],
+            "frontend": ["css", "html", "react", "vue", "ui", "button", "form"],
+            "backend": ["api", "database", "sql", "server", "endpoint"],
+            "security": ["auth", "token", "password", "encrypt", "csrf"],
+            "performance": ["latency", "cache", "optimize", "slow", "fast"],
+        }
+
+        for domain, keywords in domain_keywords.items():
+            if any(kw in content_lower for kw in keywords):
+                return domain
+
+        return None
+
+
+def add_auto_learning_to_alma(alma) -> AutoLearner:
+    """
+    Convenience function to add auto-learning to an ALMA instance.
+
+    Usage:
+        alma = ALMA.from_config(".alma/config.yaml")
+        auto_learner = add_auto_learning_to_alma(alma)
+
+        # Now use auto_learner.learn_from_conversation()
+    """
+    return AutoLearner(alma)

alma/extraction/extractor.py

@@ -0,0 +1,420 @@
+"""
+ALMA Fact Extraction Module.
+
+LLM-powered extraction of facts, preferences, and learnings from conversations.
+This bridges the gap between Mem0's automatic extraction and ALMA's explicit learning.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class FactType(Enum):
+    """Types of facts that can be extracted from conversations."""
+
+    HEURISTIC = "heuristic"  # Strategy that worked
+    ANTI_PATTERN = "anti_pattern"  # What NOT to do
+    PREFERENCE = "preference"  # User preference
+    DOMAIN_KNOWLEDGE = "domain_knowledge"  # Factual information
+    OUTCOME = "outcome"  # Task result
+
+
+@dataclass
+class ExtractedFact:
+    """A fact extracted from conversation."""
+
+    fact_type: FactType
+    content: str
+    confidence: float  # 0.0 to 1.0
+    source_text: str  # Original text this was extracted from
+    metadata: Dict[str, Any] = None
+
+    # For heuristics/anti-patterns
+    condition: Optional[str] = None  # When does this apply?
+    strategy: Optional[str] = None  # What to do?
+
+    # For preferences
+    category: Optional[str] = None
+
+    # For domain knowledge
+    domain: Optional[str] = None
+
+
+@dataclass
+class ExtractionResult:
+    """Result of fact extraction from a conversation."""
+
+    facts: List[ExtractedFact]
+    raw_response: str  # LLM's raw response for debugging
+    tokens_used: int
+    extraction_time_ms: int
+
+
+class FactExtractor(ABC):
+    """Abstract base class for fact extraction."""
+
+    @abstractmethod
+    def extract(
+        self,
+        messages: List[Dict[str, str]],
+        agent_context: Optional[str] = None,
+        existing_facts: Optional[List[str]] = None,
+    ) -> ExtractionResult:
+        """
+        Extract facts from a conversation.
+
+        Args:
+            messages: List of {"role": "user"|"assistant", "content": "..."}
+            agent_context: Optional context about the agent's domain
+            existing_facts: Optional list of already-known facts to avoid duplicates
+
+        Returns:
+            ExtractionResult with extracted facts
+        """
+        pass
+
+
+class LLMFactExtractor(FactExtractor):
+    """
+    LLM-powered fact extraction.
+
+    Uses structured prompting to extract facts, preferences, and learnings
+    from conversations. Supports OpenAI, Anthropic, and local models.
+    """
+
+    EXTRACTION_PROMPT = """You are a fact extraction system for an AI agent memory architecture.
+
+Analyze the following conversation and extract facts worth remembering.
+
+IMPORTANT: Only extract facts that are:
+1. Specific and actionable (not vague observations)
+2. Likely to be useful in future similar situations
+3. Not already in the existing facts list
+
+Categorize each fact as one of:
+- HEURISTIC: A strategy or approach that worked well
+- ANTI_PATTERN: Something that failed or should be avoided
+- PREFERENCE: A user preference or constraint
+- DOMAIN_KNOWLEDGE: A factual piece of information about the domain
+- OUTCOME: The result of a specific task
+
+For HEURISTIC and ANTI_PATTERN, also extract:
+- condition: When does this apply?
+- strategy: What to do (or not do)?
+
+For PREFERENCE, extract:
+- category: What type of preference (communication, code_style, workflow, etc.)
+
+For DOMAIN_KNOWLEDGE, extract:
+- domain: What knowledge domain this belongs to
+
+{agent_context}
+
+{existing_facts_section}
+
+CONVERSATION:
+{conversation}
+
+Respond in JSON format:
+```json
+{{
+  "facts": [
+    {{
+      "fact_type": "HEURISTIC|ANTI_PATTERN|PREFERENCE|DOMAIN_KNOWLEDGE|OUTCOME",
+      "content": "The main fact statement",
+      "confidence": 0.0-1.0,
+      "condition": "optional - when this applies",
+      "strategy": "optional - what to do",
+      "category": "optional - preference category",
+      "domain": "optional - knowledge domain"
+    }}
+  ]
+}}
+```
+
+If no facts worth extracting, return: {{"facts": []}}
+"""
+
+    def __init__(
+        self,
+        provider: str = "openai",
+        model: str = "gpt-4o-mini",
+        api_key: Optional[str] = None,
+        temperature: float = 0.1,
+    ):
+        """
+        Initialize LLM fact extractor.
+
+        Args:
+            provider: "openai", "anthropic", or "local"
+            model: Model name/identifier
+            api_key: API key (or use environment variable)
+            temperature: LLM temperature for extraction
+        """
+        self.provider = provider
+        self.model = model
+        self.api_key = api_key
+        self.temperature = temperature
+        self._client = None
+
+    def _get_client(self):
+        """Lazy initialization of LLM client."""
+        if self._client is None:
+            if self.provider == "openai":
+                from openai import OpenAI
+
+                self._client = OpenAI(api_key=self.api_key)
+            elif self.provider == "anthropic":
+                from anthropic import Anthropic
+
+                self._client = Anthropic(api_key=self.api_key)
+            else:
+                raise ValueError(f"Unsupported provider: {self.provider}")
+        return self._client
+
+    def extract(
+        self,
+        messages: List[Dict[str, str]],
+        agent_context: Optional[str] = None,
+        existing_facts: Optional[List[str]] = None,
+    ) -> ExtractionResult:
+        """Extract facts from conversation using LLM."""
+        import time
+
+        start_time = time.time()
+
+        # Format conversation
+        conversation = "\n".join(
+            f"{msg['role'].upper()}: {msg['content']}" for msg in messages
+        )
+
+        # Build prompt
+        agent_context_section = ""
+        if agent_context:
+            agent_context_section = f"\nAGENT CONTEXT:\n{agent_context}\n"
+
+        existing_facts_section = ""
+        if existing_facts:
+            facts_list = "\n".join(f"- {f}" for f in existing_facts)
+            existing_facts_section = (
+                f"\nEXISTING FACTS (do not duplicate):\n{facts_list}\n"
+            )
+
+        prompt = self.EXTRACTION_PROMPT.format(
+            agent_context=agent_context_section,
+            existing_facts_section=existing_facts_section,
+            conversation=conversation,
+        )
+
+        # Call LLM
+        client = self._get_client()
+        tokens_used = 0
+
+        if self.provider == "openai":
+            response = client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=self.temperature,
+            )
+            raw_response = response.choices[0].message.content
+            tokens_used = response.usage.total_tokens if response.usage else 0
+
+        elif self.provider == "anthropic":
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=2000,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            raw_response = response.content[0].text
+            tokens_used = response.usage.input_tokens + response.usage.output_tokens
+
+        # Parse response
+        facts = self._parse_response(raw_response, conversation)
+
+        extraction_time_ms = int((time.time() - start_time) * 1000)
+
+        return ExtractionResult(
+            facts=facts,
+            raw_response=raw_response,
+            tokens_used=tokens_used,
+            extraction_time_ms=extraction_time_ms,
+        )
+
+    def _parse_response(
+        self,
+        raw_response: str,
+        source_text: str,
+    ) -> List[ExtractedFact]:
+        """Parse LLM response into ExtractedFact objects."""
+        import json
+        import re
+
+        # Extract JSON from response (handle markdown code blocks)
+        json_match = re.search(r"```json\s*(.*?)\s*```", raw_response, re.DOTALL)
+        if json_match:
+            json_str = json_match.group(1)
+        else:
+            # Try to find raw JSON
+            json_match = re.search(r"\{.*\}", raw_response, re.DOTALL)
+            if json_match:
+                json_str = json_match.group(0)
+            else:
+                logger.warning(
+                    f"Could not parse JSON from response: {raw_response[:200]}"
+                )
+                return []
+
+        try:
+            data = json.loads(json_str)
+        except json.JSONDecodeError as e:
+            logger.warning(f"JSON parse error: {e}")
+            return []
+
+        facts = []
+        for item in data.get("facts", []):
+            try:
+                fact_type = FactType[item["fact_type"].upper()]
+                facts.append(
+                    ExtractedFact(
+                        fact_type=fact_type,
+                        content=item["content"],
+                        confidence=float(item.get("confidence", 0.7)),
+                        source_text=source_text[:500],  # Truncate for storage
+                        condition=item.get("condition"),
+                        strategy=item.get("strategy"),
+                        category=item.get("category"),
+                        domain=item.get("domain"),
+                    )
+                )
+            except (KeyError, ValueError) as e:
+                logger.warning(f"Could not parse fact: {item}, error: {e}")
+                continue
+
+        return facts
+
+
+class RuleBasedExtractor(FactExtractor):
+    """
+    Rule-based fact extraction for offline/free usage.
+
+    Uses pattern matching and heuristics instead of LLM calls.
+    Less accurate but free and fast.
+    """
+
+    # Patterns that indicate different fact types
+    HEURISTIC_PATTERNS = [
+        r"(?:worked|succeeded|fixed|solved|helped).*(?:by|using|with)",
+        r"(?:better|best|good)\s+(?:to|approach|way|strategy)",
+        r"(?:should|always|recommend).*(?:use|try|do)",
+    ]
+
+    ANTI_PATTERN_PATTERNS = [
+        r"(?:don't|do not|never|avoid).*(?:use|do|try)",
+        r"(?:failed|broke|caused|error).*(?:because|when|due)",
+        r"(?:bad|wrong|incorrect)\s+(?:to|approach|way)",
+    ]
+
+    PREFERENCE_PATTERNS = [
+        r"(?:i|user)\s+(?:prefer|like|want|need)",
+        r"(?:always|never).*(?:for me|i want)",
+    ]
+
+    def extract(
+        self,
+        messages: List[Dict[str, str]],
+        agent_context: Optional[str] = None,
+        existing_facts: Optional[List[str]] = None,
+    ) -> ExtractionResult:
+        """Extract facts using pattern matching."""
+        import re
+        import time
+
+        start_time = time.time()
+        facts = []
+
+        for msg in messages:
+            content = msg["content"].lower()
+
+            # Check for heuristics
+            for pattern in self.HEURISTIC_PATTERNS:
+                if re.search(pattern, content, re.IGNORECASE):
+                    facts.append(
+                        ExtractedFact(
+                            fact_type=FactType.HEURISTIC,
+                            content=msg["content"][:200],
+                            confidence=0.5,  # Lower confidence for rule-based
+                            source_text=msg["content"],
+                        )
+                    )
+                    break
+
+            # Check for anti-patterns
+            for pattern in self.ANTI_PATTERN_PATTERNS:
+                if re.search(pattern, content, re.IGNORECASE):
+                    facts.append(
+                        ExtractedFact(
+                            fact_type=FactType.ANTI_PATTERN,
+                            content=msg["content"][:200],
+                            confidence=0.5,
+                            source_text=msg["content"],
+                        )
+                    )
+                    break
+
+            # Check for preferences
+            for pattern in self.PREFERENCE_PATTERNS:
+                if re.search(pattern, content, re.IGNORECASE):
+                    facts.append(
+                        ExtractedFact(
+                            fact_type=FactType.PREFERENCE,
+                            content=msg["content"][:200],
+                            confidence=0.5,
+                            source_text=msg["content"],
+                        )
+                    )
+                    break
+
+        extraction_time_ms = int((time.time() - start_time) * 1000)
+
+        return ExtractionResult(
+            facts=facts,
+            raw_response="rule-based extraction",
+            tokens_used=0,
+            extraction_time_ms=extraction_time_ms,
+        )
+
+
+def create_extractor(
+    provider: str = "auto",
+    **kwargs,
+) -> FactExtractor:
+    """
+    Factory function to create appropriate extractor.
+
+    Args:
+        provider: "openai", "anthropic", "local", "rule-based", or "auto"
+        **kwargs: Additional arguments for the extractor
+
+    Returns:
+        Configured FactExtractor instance
+    """
+    if provider == "auto":
+        # Try to use LLM if API key is available
+        import os
+
+        if os.environ.get("OPENAI_API_KEY"):
+            provider = "openai"
+        elif os.environ.get("ANTHROPIC_API_KEY"):
+            provider = "anthropic"
+        else:
+            provider = "rule-based"
+
+    if provider == "rule-based":
+        return RuleBasedExtractor()
+    else:
+        return LLMFactExtractor(provider=provider, **kwargs)