alma-memory 0.2.0__py3-none-any.whl

alma/learning/heuristic_extractor.py

@@ -0,0 +1,374 @@
+"""
+ALMA Heuristic Extraction.
+
+Analyzes outcomes to identify patterns and create heuristics.
+"""
+
+import uuid
+import logging
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any, Tuple
+from dataclasses import dataclass, field
+from collections import defaultdict
+
+from alma.types import Heuristic, Outcome, MemoryScope
+from alma.storage.base import StorageBackend
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PatternCandidate:
+    """A potential pattern for heuristic creation."""
+    task_type: str
+    strategy: str
+    occurrence_count: int
+    success_count: int
+    failure_count: int
+    outcomes: List[Outcome] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate."""
+        if self.occurrence_count == 0:
+            return 0.0
+        return self.success_count / self.occurrence_count
+
+    @property
+    def confidence(self) -> float:
+        """
+        Calculate confidence based on success rate and sample size.
+
+        Confidence is lower when sample size is small (uncertainty).
+        """
+        if self.occurrence_count == 0:
+            return 0.0
+
+        base_confidence = self.success_rate
+
+        # Apply sample size penalty (Bayesian-inspired)
+        # More samples = higher confidence, max confidence at 20+ samples
+        sample_factor = min(self.occurrence_count / 20.0, 1.0)
+
+        return base_confidence * (0.5 + 0.5 * sample_factor)
+
+
+@dataclass
+class ExtractionResult:
+    """Result of heuristic extraction."""
+    heuristics_created: int = 0
+    heuristics_updated: int = 0
+    patterns_analyzed: int = 0
+    patterns_rejected: int = 0
+    rejected_reasons: Dict[str, int] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "heuristics_created": self.heuristics_created,
+            "heuristics_updated": self.heuristics_updated,
+            "patterns_analyzed": self.patterns_analyzed,
+            "patterns_rejected": self.patterns_rejected,
+            "rejected_reasons": self.rejected_reasons,
+        }
+
+
+class HeuristicExtractor:
+    """
+    Extracts heuristics from outcome patterns.
+
+    Analyzes historical outcomes to identify successful strategies
+    and creates heuristics when patterns are validated.
+    """
+
+    def __init__(
+        self,
+        storage: StorageBackend,
+        scopes: Dict[str, MemoryScope],
+        min_occurrences: int = 3,
+        min_confidence: float = 0.5,
+        strategy_similarity_threshold: float = 0.5,
+    ):
+        """
+        Initialize extractor.
+
+        Args:
+            storage: Storage backend
+            scopes: Agent scope definitions
+            min_occurrences: Minimum outcomes before creating heuristic
+            min_confidence: Minimum confidence to create heuristic
+            strategy_similarity_threshold: How similar strategies must be to group
+        """
+        self.storage = storage
+        self.scopes = scopes
+        self.min_occurrences = min_occurrences
+        self.min_confidence = min_confidence
+        self.similarity_threshold = strategy_similarity_threshold
+
+    def extract(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+    ) -> ExtractionResult:
+        """
+        Extract heuristics from all outcomes.
+
+        Args:
+            project_id: Project to analyze
+            agent: Specific agent or None for all
+
+        Returns:
+            ExtractionResult with summary
+        """
+        result = ExtractionResult()
+
+        # Get all outcomes
+        outcomes = self.storage.get_outcomes(
+            project_id=project_id,
+            agent=agent,
+            top_k=10000,
+            success_only=False,
+        )
+
+        if not outcomes:
+            logger.info("No outcomes to analyze")
+            return result
+
+        # Group outcomes by agent and task type
+        grouped = self._group_outcomes(outcomes)
+
+        for (ag, task_type), type_outcomes in grouped.items():
+            # Find patterns within this group
+            patterns = self._identify_patterns(type_outcomes)
+            result.patterns_analyzed += len(patterns)
+
+            for pattern in patterns:
+                created, reason = self._maybe_create_heuristic(
+                    agent=ag,
+                    project_id=project_id,
+                    pattern=pattern,
+                )
+
+                if created:
+                    result.heuristics_created += 1
+                else:
+                    result.patterns_rejected += 1
+                    result.rejected_reasons[reason] = (
+                        result.rejected_reasons.get(reason, 0) + 1
+                    )
+
+        logger.info(
+            f"Extraction complete: {result.heuristics_created} heuristics created, "
+            f"{result.patterns_rejected} patterns rejected"
+        )
+
+        return result
+
+    def _group_outcomes(
+        self,
+        outcomes: List[Outcome],
+    ) -> Dict[Tuple[str, str], List[Outcome]]:
+        """Group outcomes by agent and task type."""
+        grouped: Dict[Tuple[str, str], List[Outcome]] = defaultdict(list)
+        for outcome in outcomes:
+            key = (outcome.agent, outcome.task_type)
+            grouped[key].append(outcome)
+        return grouped
+
+    def _identify_patterns(
+        self,
+        outcomes: List[Outcome],
+    ) -> List[PatternCandidate]:
+        """
+        Identify patterns in outcomes by grouping similar strategies.
+
+        Uses fuzzy matching to group strategies that are similar.
+        """
+        # Group by similar strategies
+        strategy_groups: Dict[str, List[Outcome]] = defaultdict(list)
+
+        for outcome in outcomes:
+            # Find existing group or create new one
+            matched = False
+            for canonical in list(strategy_groups.keys()):
+                if self._strategies_similar(outcome.strategy_used, canonical):
+                    strategy_groups[canonical].append(outcome)
+                    matched = True
+                    break
+
+            if not matched:
+                # Create new group
+                strategy_groups[outcome.strategy_used].append(outcome)
+
+        # Convert to PatternCandidates
+        patterns = []
+        for strategy, group_outcomes in strategy_groups.items():
+            success_count = sum(1 for o in group_outcomes if o.success)
+            patterns.append(PatternCandidate(
+                task_type=group_outcomes[0].task_type,
+                strategy=strategy,
+                occurrence_count=len(group_outcomes),
+                success_count=success_count,
+                failure_count=len(group_outcomes) - success_count,
+                outcomes=group_outcomes,
+            ))
+
+        return patterns
+
+    def _maybe_create_heuristic(
+        self,
+        agent: str,
+        project_id: str,
+        pattern: PatternCandidate,
+    ) -> Tuple[bool, str]:
+        """
+        Create a heuristic if the pattern meets criteria.
+
+        Returns:
+            Tuple of (created: bool, reason: str)
+        """
+        # Check minimum occurrences
+        scope = self.scopes.get(agent)
+        min_occ = self.min_occurrences
+        if scope:
+            min_occ = scope.min_occurrences_for_heuristic
+
+        if pattern.occurrence_count < min_occ:
+            return False, f"insufficient_occurrences_{pattern.occurrence_count}"
+
+        # Check confidence
+        if pattern.confidence < self.min_confidence:
+            return False, f"low_confidence_{pattern.confidence:.2f}"
+
+        # Check if heuristic already exists
+        existing = self._find_existing_heuristic(
+            agent=agent,
+            project_id=project_id,
+            task_type=pattern.task_type,
+            strategy=pattern.strategy,
+        )
+
+        if existing:
+            # Update existing heuristic
+            self._update_heuristic(existing, pattern)
+            return True, "updated"
+
+        # Create new heuristic
+        heuristic = Heuristic(
+            id=f"heur_{uuid.uuid4().hex[:12]}",
+            agent=agent,
+            project_id=project_id,
+            condition=f"task type: {pattern.task_type}",
+            strategy=pattern.strategy,
+            confidence=pattern.confidence,
+            occurrence_count=pattern.occurrence_count,
+            success_count=pattern.success_count,
+            last_validated=datetime.now(timezone.utc),
+            created_at=datetime.now(timezone.utc),
+        )
+
+        self.storage.save_heuristic(heuristic)
+        logger.info(
+            f"Created heuristic for {agent}: {pattern.strategy[:50]}... "
+            f"(confidence: {pattern.confidence:.0%})"
+        )
+
+        return True, "created"
+
+    def _find_existing_heuristic(
+        self,
+        agent: str,
+        project_id: str,
+        task_type: str,
+        strategy: str,
+    ) -> Optional[Heuristic]:
+        """Find an existing heuristic that matches this pattern."""
+        heuristics = self.storage.get_heuristics(
+            project_id=project_id,
+            agent=agent,
+            top_k=100,
+            min_confidence=0.0,
+        )
+
+        for h in heuristics:
+            if (task_type in h.condition and
+                    self._strategies_similar(h.strategy, strategy)):
+                return h
+
+        return None
+
+    def _update_heuristic(
+        self,
+        heuristic: Heuristic,
+        pattern: PatternCandidate,
+    ):
+        """Update an existing heuristic with new data."""
+        # Merge counts
+        heuristic.occurrence_count = max(
+            heuristic.occurrence_count,
+            pattern.occurrence_count
+        )
+        heuristic.success_count = max(
+            heuristic.success_count,
+            pattern.success_count
+        )
+
+        # Update confidence
+        heuristic.confidence = pattern.confidence
+        heuristic.last_validated = datetime.now(timezone.utc)
+
+        self.storage.save_heuristic(heuristic)
+        logger.debug(f"Updated heuristic {heuristic.id}")
+
+    def _strategies_similar(self, s1: str, s2: str) -> bool:
+        """
+        Check if two strategies are similar enough to be grouped.
+
+        Uses word overlap with normalization.
+        """
+        # Normalize strategies
+        words1 = set(self._normalize_strategy(s1))
+        words2 = set(self._normalize_strategy(s2))
+
+        if not words1 or not words2:
+            return s1.lower() == s2.lower()
+
+        # Jaccard similarity
+        intersection = len(words1 & words2)
+        union = len(words1 | words2)
+        similarity = intersection / union if union > 0 else 0
+
+        return similarity >= self.similarity_threshold
+
+    def _normalize_strategy(self, strategy: str) -> List[str]:
+        """Normalize strategy text for comparison."""
+        # Remove common stop words and normalize
+        stop_words = {
+            "the", "a", "an", "and", "or", "but", "in", "on", "at",
+            "to", "for", "of", "with", "by", "then", "first", "next",
+        }
+
+        words = strategy.lower().replace(",", " ").replace(".", " ").split()
+        return [w for w in words if w not in stop_words and len(w) > 2]
+
+
+def extract_heuristics_from_outcome(
+    outcome: Outcome,
+    existing_heuristics: List[Heuristic],
+    min_confidence: float = 0.5,
+) -> Optional[Dict[str, Any]]:
+    """
+    Convenience function to check if an outcome contributes to a heuristic.
+
+    Returns update details if the outcome should update a heuristic.
+    """
+    for h in existing_heuristics:
+        # Check if this outcome matches an existing heuristic
+        if h.agent == outcome.agent and outcome.task_type in h.condition:
+            return {
+                "heuristic_id": h.id,
+                "action": "validate" if outcome.success else "invalidate",
+                "current_confidence": h.confidence,
+            }
+
+    return None

alma/learning/protocols.py

@@ -0,0 +1,326 @@
+"""
+ALMA Learning Protocols.
+
+Defines how agents learn from outcomes while respecting scope constraints.
+"""
+
+import uuid
+import logging
+from datetime import datetime, timezone, timedelta
+from typing import Optional, Dict, Any
+
+from alma.types import (
+    Heuristic,
+    Outcome,
+    UserPreference,
+    DomainKnowledge,
+    AntiPattern,
+    MemoryScope,
+)
+from alma.storage.base import StorageBackend
+
+logger = logging.getLogger(__name__)
+
+
+class LearningProtocol:
+    """
+    Manages how agents learn from task outcomes.
+
+    Key principles:
+    - Validate scope before any learning
+    - Require minimum occurrences before creating heuristics
+    - Support forgetting to prevent memory bloat
+    """
+
+    def __init__(
+        self,
+        storage: StorageBackend,
+        scopes: Dict[str, MemoryScope],
+    ):
+        """
+        Initialize learning protocol.
+
+        Args:
+            storage: Storage backend for persistence
+            scopes: Dict of agent_name -> MemoryScope
+        """
+        self.storage = storage
+        self.scopes = scopes
+
+    def learn(
+        self,
+        agent: str,
+        project_id: str,
+        task: str,
+        outcome: bool,
+        strategy_used: str,
+        task_type: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        error_message: Optional[str] = None,
+        feedback: Optional[str] = None,
+    ) -> bool:
+        """
+        Learn from a task outcome.
+
+        Creates an Outcome record and potentially updates/creates heuristics.
+
+        Args:
+            agent: Agent that executed the task
+            project_id: Project context
+            task: Task description
+            outcome: True if successful, False if failed
+            strategy_used: The approach taken
+            task_type: Category for grouping
+            duration_ms: Execution time
+            error_message: Error details if failed
+            feedback: User feedback
+
+        Returns:
+            True if learning was accepted
+        """
+        # Validate agent has a scope (warn but don't block)
+        scope = self.scopes.get(agent)
+        if scope is None:
+            logger.warning(f"Agent '{agent}' has no defined scope")
+
+        # Create outcome record
+        outcome_record = Outcome(
+            id=f"out_{uuid.uuid4().hex[:12]}",
+            agent=agent,
+            project_id=project_id,
+            task_type=task_type or self._infer_task_type(task),
+            task_description=task,
+            success=outcome,
+            strategy_used=strategy_used,
+            duration_ms=duration_ms,
+            error_message=error_message,
+            user_feedback=feedback,
+            timestamp=datetime.now(timezone.utc),
+        )
+
+        # Save outcome
+        self.storage.save_outcome(outcome_record)
+        logger.info(f"Recorded outcome for {agent}: {'success' if outcome else 'failure'}")
+
+        # Check if we should create/update a heuristic
+        self._maybe_create_heuristic(
+            agent=agent,
+            project_id=project_id,
+            task_type=outcome_record.task_type,
+            strategy=strategy_used,
+            success=outcome,
+            scope=scope,
+        )
+
+        # If failure with clear pattern, consider anti-pattern
+        if not outcome and error_message:
+            self._maybe_create_anti_pattern(
+                agent=agent,
+                project_id=project_id,
+                task=task,
+                strategy=strategy_used,
+                error=error_message,
+            )
+
+        return True
+
+    def _maybe_create_heuristic(
+        self,
+        agent: str,
+        project_id: str,
+        task_type: str,
+        strategy: str,
+        success: bool,
+        scope: Optional[MemoryScope],
+    ):
+        """
+        Create or update a heuristic if we have enough occurrences.
+
+        Only creates heuristic after min_occurrences similar outcomes.
+        """
+        min_occurrences = 3
+        if scope:
+            min_occurrences = scope.min_occurrences_for_heuristic
+
+        # Get similar outcomes to check occurrence count
+        similar_outcomes = self.storage.get_outcomes(
+            project_id=project_id,
+            agent=agent,
+            task_type=task_type,
+            top_k=min_occurrences + 1,
+            success_only=False,
+        )
+
+        # Filter to same strategy
+        same_strategy = [
+            o for o in similar_outcomes
+            if self._strategies_similar(o.strategy_used, strategy)
+        ]
+
+        if len(same_strategy) >= min_occurrences:
+            success_count = sum(1 for o in same_strategy if o.success)
+            confidence = success_count / len(same_strategy)
+
+            # Only create heuristic if confidence is meaningful
+            if confidence > 0.5:
+                heuristic = Heuristic(
+                    id=f"heur_{uuid.uuid4().hex[:12]}",
+                    agent=agent,
+                    project_id=project_id,
+                    condition=f"task type: {task_type}",
+                    strategy=strategy,
+                    confidence=confidence,
+                    occurrence_count=len(same_strategy),
+                    success_count=success_count,
+                    last_validated=datetime.now(timezone.utc),
+                    created_at=datetime.now(timezone.utc),
+                )
+                self.storage.save_heuristic(heuristic)
+                logger.info(
+                    f"Created heuristic for {agent}: {strategy[:50]}... "
+                    f"(confidence: {confidence:.0%})"
+                )
+
+    def _maybe_create_anti_pattern(
+        self,
+        agent: str,
+        project_id: str,
+        task: str,
+        strategy: str,
+        error: str,
+    ):
+        """Create anti-pattern if we see repeated failures with same pattern."""
+        # Check for similar failures
+        similar_failures = self.storage.get_outcomes(
+            project_id=project_id,
+            agent=agent,
+            success_only=False,
+            top_k=10,
+        )
+
+        # Filter to failures with similar error
+        similar = [
+            o for o in similar_failures
+            if not o.success and o.error_message and
+            self._errors_similar(o.error_message, error)
+        ]
+
+        if len(similar) >= 2:  # At least 2 similar failures
+            anti_pattern = AntiPattern(
+                id=f"anti_{uuid.uuid4().hex[:12]}",
+                agent=agent,
+                project_id=project_id,
+                pattern=strategy,
+                why_bad=error,
+                better_alternative="[To be determined from successful outcomes]",
+                occurrence_count=len(similar),
+                last_seen=datetime.now(timezone.utc),
+            )
+            self.storage.save_anti_pattern(anti_pattern)
+            logger.info(f"Created anti-pattern for {agent}: {strategy[:50]}...")
+
+    def add_preference(
+        self,
+        user_id: str,
+        category: str,
+        preference: str,
+        source: str,
+    ) -> UserPreference:
+        """Add a user preference."""
+        pref = UserPreference(
+            id=f"pref_{uuid.uuid4().hex[:12]}",
+            user_id=user_id,
+            category=category,
+            preference=preference,
+            source=source,
+            confidence=1.0 if source == "explicit_instruction" else 0.7,
+            timestamp=datetime.now(timezone.utc),
+        )
+        self.storage.save_user_preference(pref)
+        return pref
+
+    def add_domain_knowledge(
+        self,
+        agent: str,
+        project_id: str,
+        domain: str,
+        fact: str,
+        source: str,
+    ) -> DomainKnowledge:
+        """Add domain knowledge."""
+        knowledge = DomainKnowledge(
+            id=f"dk_{uuid.uuid4().hex[:12]}",
+            agent=agent,
+            project_id=project_id,
+            domain=domain,
+            fact=fact,
+            source=source,
+            confidence=1.0 if source == "user_stated" else 0.8,
+            last_verified=datetime.now(timezone.utc),
+        )
+        self.storage.save_domain_knowledge(knowledge)
+        return knowledge
+
+    def forget(
+        self,
+        project_id: str,
+        agent: Optional[str] = None,
+        older_than_days: int = 90,
+        below_confidence: float = 0.3,
+    ) -> int:
+        """
+        Prune stale and low-confidence memories.
+
+        Returns:
+            Total number of items pruned
+        """
+        cutoff = datetime.now(timezone.utc) - timedelta(days=older_than_days)
+
+        # Delete old outcomes
+        outcomes_deleted = self.storage.delete_outcomes_older_than(
+            project_id=project_id,
+            older_than=cutoff,
+            agent=agent,
+        )
+
+        # Delete low-confidence heuristics
+        heuristics_deleted = self.storage.delete_low_confidence_heuristics(
+            project_id=project_id,
+            below_confidence=below_confidence,
+            agent=agent,
+        )
+
+        total = outcomes_deleted + heuristics_deleted
+        logger.info(
+            f"Forgot {total} items: {outcomes_deleted} outcomes, "
+            f"{heuristics_deleted} heuristics"
+        )
+        return total
+
+    def _infer_task_type(self, task: str) -> str:
+        """Infer task type from description."""
+        task_lower = task.lower()
+        if "test" in task_lower or "validate" in task_lower:
+            return "testing"
+        elif "api" in task_lower or "endpoint" in task_lower:
+            return "api_testing"
+        elif "form" in task_lower or "input" in task_lower:
+            return "form_testing"
+        elif "database" in task_lower or "query" in task_lower:
+            return "database_validation"
+        return "general"
+
+    def _strategies_similar(self, s1: str, s2: str) -> bool:
+        """Check if two strategies are similar enough to count together."""
+        # Simple word overlap check - could be improved with embeddings
+        words1 = set(s1.lower().split())
+        words2 = set(s2.lower().split())
+        overlap = len(words1 & words2)
+        return overlap >= min(3, len(words1) // 2)
+
+    def _errors_similar(self, e1: str, e2: str) -> bool:
+        """Check if two errors are similar."""
+        # Simple substring check
+        e1_lower = e1.lower()
+        e2_lower = e2.lower()
+        return e1_lower in e2_lower or e2_lower in e1_lower