roampal 0.1.4__py3-none-any.whl

roampal/backend/modules/memory/memory_types.py

@@ -0,0 +1,296 @@
+"""
+Memory System Type Definitions
+
+Centralizes all type definitions, dataclasses, and type aliases used throughout
+the memory system. Extracted from UnifiedMemorySystem module-level definitions.
+
+Replaces loose JSON string serialization with proper typed dataclasses.
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Dict, Any, List, Optional, Literal
+import json
+
+
+# Type aliases (from lines 45, 94)
+CollectionName = Literal["books", "working", "history", "patterns", "memory_bank"]
+ContextType = str  # LLM discovers topics organically (coding, fitness, finance, etc.)
+
+
+@dataclass
+class OutcomeEntry:
+    """
+    A single outcome event for a memory.
+
+    Replaces JSON strings like:
+    {"outcome": "worked", "timestamp": "2024-12-10T...", "context": "coding"}
+    """
+    outcome: Literal["worked", "failed", "partial", "unknown"]
+    timestamp: str
+    context: Optional[str] = None
+    confidence: float = 1.0
+    implicit: bool = False
+    reason: Optional[str] = None
+
+
+@dataclass
+class OutcomeHistory:
+    """
+    History of outcomes for a memory item.
+
+    Provides proper serialization/deserialization instead of raw JSON strings
+    stored in ChromaDB metadata.
+    """
+    entries: List[OutcomeEntry] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        """Serialize to JSON string for ChromaDB storage."""
+        return json.dumps([asdict(e) for e in self.entries])
+
+    @classmethod
+    def from_json(cls, data: str) -> "OutcomeHistory":
+        """Deserialize from JSON string."""
+        if not data:
+            return cls()
+        try:
+            entries = [OutcomeEntry(**e) for e in json.loads(data)]
+            return cls(entries=entries)
+        except (json.JSONDecodeError, TypeError):
+            return cls()
+
+    def add_outcome(
+        self,
+        outcome: Literal["worked", "failed", "partial", "unknown"],
+        context: Optional[str] = None,
+        confidence: float = 1.0,
+        implicit: bool = False,
+        reason: Optional[str] = None
+    ):
+        """Add a new outcome entry."""
+        self.entries.append(OutcomeEntry(
+            outcome=outcome,
+            timestamp=datetime.now().isoformat(),
+            context=context,
+            confidence=confidence,
+            implicit=implicit,
+            reason=reason
+        ))
+
+    @property
+    def success_count(self) -> int:
+        """Count of worked + partial outcomes."""
+        return sum(1 for e in self.entries if e.outcome in ("worked", "partial"))
+
+    @property
+    def failure_count(self) -> int:
+        """Count of failed outcomes."""
+        return sum(1 for e in self.entries if e.outcome == "failed")
+
+    @property
+    def total_count(self) -> int:
+        """Total outcome count."""
+        return len(self.entries)
+
+
+@dataclass
+class PromotionRecord:
+    """Record of a single promotion/demotion event."""
+    from_collection: str
+    to_collection: str
+    timestamp: str
+    score: float
+    uses: int
+    reason: str = "score_threshold"
+
+
+@dataclass
+class PromotionHistory:
+    """
+    History of promotions/demotions for a memory item.
+    """
+    promotions: List[PromotionRecord] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        """Serialize to JSON string for ChromaDB storage."""
+        return json.dumps([asdict(p) for p in self.promotions])
+
+    @classmethod
+    def from_json(cls, data: str) -> "PromotionHistory":
+        """Deserialize from JSON string."""
+        if not data:
+            return cls()
+        try:
+            promotions = [PromotionRecord(**p) for p in json.loads(data)]
+            return cls(promotions=promotions)
+        except (json.JSONDecodeError, TypeError):
+            return cls()
+
+    def add_promotion(
+        self,
+        from_collection: str,
+        to_collection: str,
+        score: float,
+        uses: int,
+        reason: str = "score_threshold"
+    ):
+        """Record a promotion/demotion event."""
+        self.promotions.append(PromotionRecord(
+            from_collection=from_collection,
+            to_collection=to_collection,
+            timestamp=datetime.now().isoformat(),
+            score=score,
+            uses=uses,
+            reason=reason
+        ))
+
+
+@dataclass
+class ActionOutcome:
+    """
+    Tracks individual action outcomes with topic-based context awareness (v0.2.1 Causal Learning).
+
+    Copied from original UnifiedMemorySystem lines 97-153.
+
+    Enables learning: "In topic X, action Y leads to outcome Z"
+
+    Examples:
+    - For CODING: search_memory → 92% success (searching code patterns works well)
+    - For FITNESS: create_memory → 88% success (storing workout logs works well)
+    - For FINANCE: archive_memory → 75% success (archiving expenses works well)
+    """
+    action_type: str  # Tool name: "search_memory", "create_memory", "update_memory", etc.
+    context_type: ContextType  # LLM-classified topic: "coding", "fitness", "finance", etc.
+    outcome: Literal["worked", "failed", "partial"]
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    # Action details
+    action_params: Dict[str, Any] = field(default_factory=dict)  # Tool parameters
+    doc_id: Optional[str] = None  # If action involved a document
+    collection: Optional[str] = None  # Which collection was accessed
+
+    # Outcome details
+    failure_reason: Optional[str] = None
+    success_context: Optional[Dict[str, Any]] = None
+
+    # Causal attribution
+    chain_position: int = 0  # Position in action chain (0 = first action)
+    chain_length: int = 1  # Total actions in chain
+    caused_final_outcome: bool = True  # Did this action cause the final outcome?
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict for KG storage."""
+        return {
+            "action_type": self.action_type,
+            "context_type": self.context_type,
+            "outcome": self.outcome,
+            "timestamp": self.timestamp.isoformat(),
+            "action_params": self.action_params,
+            "doc_id": self.doc_id,
+            "collection": self.collection,
+            "failure_reason": self.failure_reason,
+            "success_context": self.success_context,
+            "chain_position": self.chain_position,
+            "chain_length": self.chain_length,
+            "caused_final_outcome": self.caused_final_outcome,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ActionOutcome":
+        """Deserialize from dict."""
+        data = data.copy()
+        data["timestamp"] = datetime.fromisoformat(data["timestamp"])
+        return cls(**data)
+
+
+@dataclass
+class MemoryMetadata:
+    """
+    Structured metadata for a memory item.
+
+    Provides type-safe access to commonly used metadata fields.
+    """
+    id: str
+    timestamp: str
+    collection: str
+    score: float = 0.5
+    uses: int = 0
+    importance: float = 0.7
+    confidence: float = 0.7
+    tags: List[str] = field(default_factory=list)
+    outcome_history: Optional[str] = None  # JSON string
+    promotion_history: Optional[str] = None  # JSON string
+    conversation_id: Optional[str] = None
+    context_type: Optional[str] = None
+    source: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict for ChromaDB storage."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryMetadata":
+        """Create from ChromaDB metadata dict."""
+        # Only include fields that exist in the dataclass
+        valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in valid_fields}
+        return cls(**filtered)
+
+
+@dataclass
+class SearchResult:
+    """
+    Structured search result.
+
+    Provides type-safe access to search result fields.
+    """
+    text: str
+    collection: str
+    distance: float
+    metadata: Dict[str, Any]
+    final_rank_score: float = 0.0
+    wilson_score: float = 0.5
+    embedding_similarity: float = 0.0
+    learned_score: float = 0.5
+    ce_score: Optional[float] = None  # Cross-encoder score
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SearchResult":
+        """Create from raw search result dict."""
+        return cls(
+            text=data.get("text", ""),
+            collection=data.get("collection", ""),
+            distance=data.get("distance", 0.0),
+            metadata=data.get("metadata", {}),
+            final_rank_score=data.get("final_rank_score", 0.0),
+            wilson_score=data.get("wilson_score", 0.5),
+            embedding_similarity=data.get("embedding_similarity", 0.0),
+            learned_score=data.get("learned_score", 0.5),
+            ce_score=data.get("ce_score"),
+        )
+
+
+# Type aliases for search results
+MemoryResult = Dict[str, Any]  # Generic memory result dict
+
+
+@dataclass
+class SearchMetadata:
+    """
+    Metadata about a search operation.
+
+    Returned alongside results when return_metadata=True.
+    """
+    query: str
+    collections_searched: List[str]
+    total_results: int
+    routing_phase: str = "unknown"  # exploration, medium, high
+    tier_scores: Dict[str, float] = field(default_factory=dict)
+    cached_doc_ids: List[str] = field(default_factory=list)
+    entity_boost_applied: bool = False
+    cross_encoder_used: bool = False
+    search_time_ms: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict for JSON serialization."""
+        return asdict(self)

roampal/backend/modules/memory/outcome_service.py

@@ -0,0 +1,400 @@
+"""
+OutcomeService - Extracted from UnifiedMemorySystem
+
+Handles outcome recording, score updates, and learning from feedback.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Dict, Any, Optional, List, Literal, Callable, Awaitable
+
+from .config import MemoryConfig
+
+logger = logging.getLogger(__name__)
+
+
+class OutcomeService:
+    """
+    Service for recording outcomes and updating memory scores.
+
+    Extracted from UnifiedMemorySystem.record_outcome and related methods.
+    Handles:
+    - Time-weighted score updates
+    - Outcome history tracking
+    - KG routing updates
+    - Problem-solution pattern tracking
+    """
+
+    def __init__(
+        self,
+        collections: Dict[str, Any],
+        kg_service: Any = None,
+        promotion_service: Any = None,
+        config: Optional[MemoryConfig] = None
+    ):
+        """
+        Initialize OutcomeService.
+
+        Args:
+            collections: Dict of collection name -> adapter
+            kg_service: KnowledgeGraphService for routing updates
+            promotion_service: PromotionService for promotion handling
+            config: Memory configuration
+        """
+        self.collections = collections
+        self.kg_service = kg_service
+        self.promotion_service = promotion_service
+        self.config = config or MemoryConfig()
+
+    async def record_outcome(
+        self,
+        doc_id: str,
+        outcome: Literal["worked", "failed", "partial"],
+        failure_reason: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Record outcome and trigger learning.
+
+        Args:
+            doc_id: Document that was used
+            outcome: Whether it worked
+            failure_reason: Reason for failure (if applicable)
+            context: Additional context for learning
+
+        Returns:
+            Updated metadata or None if document not found
+        """
+        # Find collection and document FIRST (needed for KG routing update)
+        collection_name = None
+        doc = None
+
+        for coll_name, adapter in self.collections.items():
+            if doc_id.startswith(coll_name):
+                collection_name = coll_name
+                doc = adapter.get_fragment(doc_id)
+                break
+
+        # UPDATE KG ROUTING FIRST - even for books/memory_bank
+        # This allows KG to learn which collections answer which queries
+        if doc and collection_name and self.kg_service:
+            metadata = doc.get("metadata", {})
+            # For quiz retrievals, use quiz_question from context; otherwise use stored query
+            problem_text = ""
+            if context and "quiz_question" in context:
+                problem_text = context["quiz_question"]
+            else:
+                problem_text = metadata.get("query", "") or metadata.get("text", "")[:200]
+
+            if problem_text:
+                await self.kg_service.update_kg_routing(problem_text, collection_name, outcome)
+                logger.info(f"[KG] Updated routing for '{problem_text[:50]}' -> {collection_name} (outcome={outcome})")
+
+        # SAFEGUARD: Books are reference material, not scorable memories
+        # But we still updated KG routing above so system learns to route to books
+        if doc_id.startswith("books_"):
+            logger.info(f"[KG] Learned routing pattern for books, but skipping score update (static reference material)")
+            return None
+
+        # SAFEGUARD: Memory bank is user identity/facts, not scorable patterns
+        # But we still updated KG routing above so system learns to route to memory_bank
+        if doc_id.startswith("memory_bank_"):
+            logger.info(f"[KG] Learned routing pattern for memory_bank, but skipping score update (persistent user facts)")
+            return None
+
+        if not doc:
+            logger.warning(f"Document {doc_id} not found")
+            return None
+
+        # Calculate score update
+        metadata = doc.get("metadata", {})
+        current_score = metadata.get("score", 0.5)
+        uses = metadata.get("uses", 0)
+
+        # Time-weighted score update
+        time_weight = self._calculate_time_weight(metadata.get("last_used"))
+        score_delta, new_score, uses = self._calculate_score_update(
+            outcome, current_score, uses, time_weight
+        )
+
+        # Update context tracking
+        if outcome == "worked" and context:
+            contexts = json.loads(metadata.get("success_contexts", "[]"))
+            contexts.append(context)
+            metadata["success_contexts"] = json.dumps(contexts)
+        elif outcome == "failed" and failure_reason:
+            reasons = json.loads(metadata.get("failure_reasons", "[]"))
+            reasons.append({
+                "reason": failure_reason,
+                "timestamp": datetime.now().isoformat()
+            })
+            metadata["failure_reasons"] = json.dumps(reasons)
+
+        # Update outcome history
+        outcome_history = json.loads(metadata.get("outcome_history", "[]"))
+        outcome_history.append({
+            "outcome": outcome,
+            "timestamp": datetime.now().isoformat(),
+            "reason": failure_reason
+        })
+        outcome_history = outcome_history[-10:]  # Keep last 10
+
+        # Update metadata
+        metadata.update({
+            "score": new_score,
+            "uses": uses,
+            "last_outcome": outcome,
+            "last_used": datetime.now().isoformat(),
+            "outcome_history": json.dumps(outcome_history)
+        })
+
+        # Persist to collection
+        self.collections[collection_name].update_fragment_metadata(doc_id, metadata)
+
+        logger.info(
+            f"Score update [{collection_name}]: {current_score:.2f} → {new_score:.2f} "
+            f"(outcome={outcome}, delta={score_delta:+.2f}, time_weight={time_weight:.2f}, uses={uses})"
+        )
+
+        # Update KG routing if service available
+        if self.kg_service:
+            problem_text = metadata.get("query", "")
+            await self._update_kg_with_outcome(
+                doc_id, outcome, problem_text, doc.get("content", ""),
+                new_score, metadata, failure_reason, context
+            )
+
+        # Handle promotion/demotion if service available
+        if self.promotion_service:
+            collection_size = self.collections[collection_name].collection.count()
+            await self.promotion_service.handle_promotion(
+                doc_id=doc_id,
+                collection=collection_name,
+                score=new_score,
+                uses=uses,
+                metadata=metadata,
+                collection_size=collection_size
+            )
+
+        logger.info(f"Outcome recorded: {doc_id} -> {outcome} (score: {new_score:.2f})")
+        return metadata
+
+    def _calculate_time_weight(self, last_used: Optional[str]) -> float:
+        """Calculate time weight for score updates."""
+        if not last_used:
+            return 1.0
+
+        try:
+            age_days = (datetime.now() - datetime.fromisoformat(last_used)).days
+            return 1.0 / (1 + age_days / 30)  # Decay over month
+        except:
+            return 1.0
+
+    def _calculate_score_update(
+        self,
+        outcome: str,
+        current_score: float,
+        uses: int,
+        time_weight: float
+    ) -> tuple:
+        """
+        Calculate score delta and new values.
+
+        Returns:
+            Tuple of (score_delta, new_score, new_uses)
+        """
+        if outcome == "worked":
+            score_delta = 0.2 * time_weight
+            new_score = min(1.0, current_score + score_delta)
+            uses += 1
+        elif outcome == "failed":
+            score_delta = -0.3 * time_weight
+            new_score = max(0.0, current_score + score_delta)
+        else:  # partial
+            score_delta = 0.05 * time_weight
+            new_score = min(1.0, current_score + score_delta)
+            uses += 1
+
+        return score_delta, new_score, uses
+
+    async def _update_kg_with_outcome(
+        self,
+        doc_id: str,
+        outcome: str,
+        problem_text: str,
+        solution_text: str,
+        new_score: float,
+        metadata: Dict[str, Any],
+        failure_reason: Optional[str],
+        context: Optional[Dict[str, Any]]
+    ):
+        """Update knowledge graph based on outcome."""
+        if not self.kg_service:
+            return
+
+        # Update routing patterns
+        # Extract collection name from doc_id (handles memory_bank correctly)
+        # doc_id format: collection_uuid or collection_name_uuid
+        if doc_id.startswith("memory_bank_"):
+            collection_name = "memory_bank"
+        elif doc_id.startswith("books_"):
+            collection_name = "books"
+        elif doc_id.startswith("working_"):
+            collection_name = "working"
+        elif doc_id.startswith("history_"):
+            collection_name = "history"
+        elif doc_id.startswith("patterns_"):
+            collection_name = "patterns"
+        else:
+            collection_name = doc_id.split("_")[0] if "_" in doc_id else "unknown"
+        await self.kg_service.update_kg_routing(problem_text, collection_name, outcome)
+
+        if outcome == "worked" and problem_text and solution_text:
+            # Extract concepts
+            problem_concepts = self.kg_service.extract_concepts(problem_text)
+            solution_concepts = self.kg_service.extract_concepts(solution_text)
+            all_concepts = list(set(problem_concepts + solution_concepts))
+
+            # Build relationships
+            self.kg_service.build_concept_relationships(all_concepts)
+
+            # Track problem category
+            problem_key = "_".join(sorted(problem_concepts)[:3])
+            self.kg_service.add_problem_category(problem_key, doc_id)
+
+            # Track solution pattern
+            self.kg_service.add_solution_pattern(
+                doc_id, solution_text, new_score,
+                [problem_key], solution_concepts[:5]
+            )
+
+            # Update success rate
+            self.kg_service.update_success_rate(doc_id, outcome)
+
+            # Track problem-solution mapping
+            await self._track_problem_solution(doc_id, metadata, context)
+
+        elif outcome == "failed":
+            # Track failure
+            self.kg_service.update_success_rate(doc_id, outcome)
+
+            if failure_reason:
+                self.kg_service.add_failure_pattern(
+                    failure_reason[:50], doc_id, problem_text[:100]
+                )
+
+        elif outcome == "partial":
+            self.kg_service.update_success_rate(doc_id, outcome)
+
+        # Save KG (debounced)
+        await self.kg_service.debounced_save_kg()
+
+    async def _track_problem_solution(
+        self,
+        doc_id: str,
+        metadata: Dict[str, Any],
+        context: Optional[Dict[str, Any]]
+    ):
+        """Track successful problem→solution patterns for future reuse."""
+        if not self.kg_service:
+            return
+
+        try:
+            problem_text = metadata.get("original_context", "") or metadata.get("query", "")
+            solution_text = metadata.get("text", "")
+
+            if not problem_text or not solution_text:
+                return
+
+            # Create problem signature
+            problem_concepts = self.kg_service.extract_concepts(problem_text)
+            problem_signature = "_".join(sorted(problem_concepts[:5]))
+
+            if not problem_signature:
+                return
+
+            # Track in KG
+            self.kg_service.add_problem_solution(
+                problem_signature=problem_signature,
+                doc_id=doc_id,
+                solution_text=solution_text,
+                context=context
+            )
+
+            # Track solution pattern
+            pattern_hash = f"{problem_signature}::{doc_id}"
+            self.kg_service.add_solution_pattern_entry(
+                pattern_hash=pattern_hash,
+                problem_text=problem_text,
+                solution_text=solution_text,
+                outcome="worked"
+            )
+
+            logger.info(f"Tracked problem→solution: {problem_signature[:30]}... -> {doc_id}")
+
+        except Exception as e:
+            logger.error(f"Error tracking problem→solution: {e}")
+
+    def count_successes_from_history(self, outcome_history_json: str) -> float:
+        """
+        Count successes from outcome history JSON.
+
+        Args:
+            outcome_history_json: JSON string of outcome history
+
+        Returns:
+            Weighted success count (worked=1, partial=0.5)
+        """
+        if not outcome_history_json or outcome_history_json == "[]":
+            return 0
+
+        try:
+            history = json.loads(outcome_history_json)
+            successes = 0.0
+            for entry in history:
+                outcome = entry.get("outcome", "")
+                if outcome == "worked":
+                    successes += 1.0
+                elif outcome == "partial":
+                    successes += 0.5
+            return successes
+        except json.JSONDecodeError:
+            return 0
+
+    def get_outcome_stats(self, doc_id: str) -> Dict[str, Any]:
+        """
+        Get outcome statistics for a document.
+
+        Args:
+            doc_id: Document ID
+
+        Returns:
+            Dict with outcome stats
+        """
+        for coll_name, adapter in self.collections.items():
+            if doc_id.startswith(coll_name):
+                doc = adapter.get_fragment(doc_id)
+                if doc:
+                    metadata = doc.get("metadata", {})
+                    outcome_history = json.loads(metadata.get("outcome_history", "[]"))
+
+                    worked = sum(1 for o in outcome_history if o.get("outcome") == "worked")
+                    failed = sum(1 for o in outcome_history if o.get("outcome") == "failed")
+                    partial = sum(1 for o in outcome_history if o.get("outcome") == "partial")
+
+                    return {
+                        "doc_id": doc_id,
+                        "collection": coll_name,
+                        "score": metadata.get("score", 0.5),
+                        "uses": metadata.get("uses", 0),
+                        "last_outcome": metadata.get("last_outcome"),
+                        "outcomes": {
+                            "worked": worked,
+                            "failed": failed,
+                            "partial": partial
+                        },
+                        "total_outcomes": len(outcome_history)
+                    }
+
+        return {"doc_id": doc_id, "error": "not_found"}