apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/components/self_reflector.py

@@ -0,0 +1,252 @@
+"""Self Reflector — evaluate own performance and identify improvements.
+
+Analyzes:
+    - Response quality patterns
+    - Error patterns
+    - Improvement opportunities
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Score thresholds for issue/improvement classification
+_CRITICAL_THRESHOLD = 0.5
+_WARN_THRESHOLD = 0.7
+_GOOD_THRESHOLD = 0.85
+
+
+@dataclass
+class Reflection:
+    """A self-reflection on performance.
+
+    Attributes:
+        id: Unique reflection identifier
+        area: What was reflected on ("response_quality", "tool_usage", "memory_recall")
+        score: Quality score (0-1)
+        issues: Problems identified during reflection
+        improvements: Suggested improvements
+        timestamp: When the reflection occurred
+    """
+
+    id: str
+    area: str
+    score: float
+    issues: List[str] = field(default_factory=list)
+    improvements: List[str] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class SelfReflector:
+    """Evaluate and improve own performance.
+
+    Performs self-reflection across different areas (response quality,
+    memory recall, tool usage) and tracks improvement opportunities.
+    Attempts to query ``metrics_collector`` for real performance data;
+    falls back to sensible defaults when metrics are unavailable.
+
+    Args:
+        metrics_collector: Colony metrics collector for gathering performance data
+        event_bus: Colony event bus for emitting reflection events
+    """
+
+    def __init__(self, metrics_collector: Any, event_bus: Any) -> None:
+        self.metrics = metrics_collector
+        self.events = event_bus
+        self._reflections: List[Reflection] = []
+
+    async def reflect(self, area: Optional[str] = None) -> Reflection:
+        """Perform self-reflection on an area.
+
+        Args:
+            area: Specific area to reflect on, or None for default (response_quality)
+
+        Returns:
+            Reflection with score, issues, and suggested improvements
+        """
+        if area == "response_quality" or area is None:
+            reflection = await self._reflect_on_responses()
+        elif area == "memory_recall":
+            reflection = await self._reflect_on_memory()
+        elif area == "tool_usage":
+            reflection = await self._reflect_on_tool_usage()
+        else:
+            reflection = Reflection(
+                id=f"reflect-{area}-{datetime.now().isoformat()}",
+                area=area,
+                score=0.5,
+                issues=[f"No reflection handler for area: {area}"],
+                improvements=["Add dedicated reflection handler for this area"],
+            )
+
+        self._reflections.append(reflection)
+        logger.debug("Completed reflection on %s: score=%.2f", reflection.area, reflection.score)
+        return reflection
+
+    async def get_recent_reflections(self, limit: int = 10) -> List[Reflection]:
+        """Get the most recent reflections.
+
+        Args:
+            limit: Maximum number of reflections to return
+
+        Returns:
+            Most recent reflections, newest first
+        """
+        return list(reversed(self._reflections[-limit:]))
+
+    async def get_area_trend(self, area: str) -> Dict[str, Any]:
+        """Compute trend statistics for a specific reflection area.
+
+        Args:
+            area: The reflection area to analyse
+
+        Returns:
+            Dict with 'count', 'avg_score', 'min_score', 'max_score', 'trend'
+            (positive = improving, negative = declining).
+        """
+        area_reflections = [r for r in self._reflections if r.area == area]
+        if not area_reflections:
+            return {"count": 0, "avg_score": None, "min_score": None, "max_score": None, "trend": 0.0}
+
+        scores = [r.score for r in area_reflections]
+        trend = 0.0
+        if len(scores) >= 2:
+            trend = scores[-1] - scores[0]
+
+        return {
+            "count": len(scores),
+            "avg_score": sum(scores) / len(scores),
+            "min_score": min(scores),
+            "max_score": max(scores),
+            "trend": trend,
+        }
+
+    async def _reflect_on_responses(self) -> Reflection:
+        """Reflect on response quality using available metrics."""
+        score = 0.75
+        issues: List[str] = []
+        improvements: List[str] = []
+
+        try:
+            if hasattr(self.metrics, "get_recent_stats"):
+                stats = await self.metrics.get_recent_stats()
+                if isinstance(stats, dict):
+                    score = float(stats.get("response_quality", 0.75))
+        except Exception:
+            pass
+
+        score = max(0.0, min(1.0, score))
+
+        if score < _CRITICAL_THRESHOLD:
+            issues.extend([
+                "Response quality significantly below threshold",
+                "High error rate detected in recent responses",
+            ])
+            improvements.extend([
+                "Review response generation strategy immediately",
+                "Add output validation layer",
+            ])
+        elif score < _WARN_THRESHOLD:
+            issues.append("Response quality below acceptable level")
+            improvements.append("Add brevity scoring to response evaluation")
+        elif score < _GOOD_THRESHOLD:
+            issues.append("Could be more concise in some responses")
+            improvements.append("Implement response length optimization")
+        else:
+            improvements.append("Maintain current quality standards")
+
+        return Reflection(
+            id=f"reflect-responses-{datetime.now().isoformat()}",
+            area="response_quality",
+            score=score,
+            issues=issues,
+            improvements=improvements,
+        )
+
+    async def _reflect_on_memory(self) -> Reflection:
+        """Reflect on memory recall accuracy."""
+        score = 0.8
+        issues: List[str] = []
+        improvements: List[str] = []
+
+        try:
+            if hasattr(self.metrics, "get_memory_stats"):
+                stats = await self.metrics.get_memory_stats()
+                if isinstance(stats, dict):
+                    score = float(stats.get("recall_accuracy", 0.8))
+        except Exception:
+            pass
+
+        score = max(0.0, min(1.0, score))
+
+        if score < _CRITICAL_THRESHOLD:
+            issues.extend([
+                "Memory recall accuracy critically low",
+                "Significant number of false positives in recall",
+            ])
+            improvements.extend([
+                "Rebuild memory index",
+                "Increase memory index refresh frequency",
+            ])
+        elif score < _WARN_THRESHOLD:
+            issues.append("Some stale memories surfaced in recent recalls")
+            improvements.append("Increase recency weighting in recall scoring")
+        elif score < _GOOD_THRESHOLD:
+            issues.append("Occasional irrelevant memories retrieved")
+            improvements.append("Tune vector similarity threshold for recall")
+        else:
+            improvements.append("Consider expanding memory retention window")
+
+        return Reflection(
+            id=f"reflect-memory-{datetime.now().isoformat()}",
+            area="memory_recall",
+            score=score,
+            issues=issues,
+            improvements=improvements,
+        )
+
+    async def _reflect_on_tool_usage(self) -> Reflection:
+        """Reflect on tool usage effectiveness."""
+        score = 0.7
+        issues: List[str] = []
+        improvements: List[str] = []
+
+        try:
+            if hasattr(self.metrics, "get_tool_stats"):
+                stats = await self.metrics.get_tool_stats()
+                if isinstance(stats, dict):
+                    score = float(stats.get("tool_success_rate", 0.7))
+        except Exception:
+            pass
+
+        score = max(0.0, min(1.0, score))
+
+        if score < _CRITICAL_THRESHOLD:
+            issues.extend([
+                "Significant tool failures detected",
+                "Wrong tools selected for task types",
+            ])
+            improvements.extend([
+                "Review tool selection criteria",
+                "Consult ToolLearner preferences before every tool call",
+            ])
+        elif score < _WARN_THRESHOLD:
+            issues.append("Some tools used for wrong task types")
+            improvements.append("Cross-reference tool learner preferences before selection")
+        elif score < _GOOD_THRESHOLD:
+            issues.append("Occasional suboptimal tool choices")
+            improvements.append("Expand tool preference learning dataset")
+        else:
+            improvements.append("Tool usage patterns are effective; continue monitoring")
+
+        return Reflection(
+            id=f"reflect-tools-{datetime.now().isoformat()}",
+            area="tool_usage",
+            score=score,
+            issues=issues,
+            improvements=improvements,
+        )

apsimo/intelligence/components/session_continuity.py

@@ -0,0 +1,154 @@
+"""Session Continuity — maintain context across conversation sessions.
+
+Manages:
+    - Session handoff
+    - Context preservation
+    - Long-term memory bridging
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SessionContext:
+    """Context carried across sessions.
+
+    Attributes:
+        session_id: Unique session identifier
+        user_id: User this session belongs to
+        started_at: When the session began
+        last_activity: Most recent activity timestamp
+        topics: Topics discussed in this session
+        entities: Referenced entity IDs (people, projects, etc.)
+        pending_tasks: Tasks still in progress
+        metadata: Additional session-specific data
+    """
+
+    session_id: str
+    user_id: str
+    started_at: datetime = field(default_factory=datetime.now)
+    last_activity: datetime = field(default_factory=datetime.now)
+    topics: List[str] = field(default_factory=list)
+    entities: List[str] = field(default_factory=list)
+    pending_tasks: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class SessionContinuity:
+    """Maintain context across sessions.
+
+    Tracks active sessions per user, resumes existing sessions within
+    the timeout window, and preserves topics, entities, and pending
+    tasks across session boundaries.
+
+    Args:
+        graph_client: Colony graph client for persistent session storage
+        event_bus: Colony event bus for session lifecycle events
+    """
+
+    def __init__(self, graph_client: Any, event_bus: Any) -> None:
+        self.graph = graph_client
+        self.events = event_bus
+        self._active_sessions: Dict[str, SessionContext] = {}
+        self._session_timeout = timedelta(hours=24)
+
+    async def start_session(self, user_id: str) -> SessionContext:
+        """Start a new session, potentially continuing from a previous one.
+
+        If an active session exists for the user within the timeout window,
+        it is resumed instead of creating a new one.
+
+        Args:
+            user_id: The user starting or resuming a session
+
+        Returns:
+            Active or newly created SessionContext
+        """
+        existing = await self._find_existing_session(user_id)
+
+        if existing:
+            existing.last_activity = datetime.now()
+            logger.debug("Resumed session %s for user %s", existing.session_id, user_id)
+            return existing
+
+        session_id = f"session-{user_id}-{datetime.now().isoformat()}"
+        context = SessionContext(
+            session_id=session_id,
+            user_id=user_id,
+        )
+        self._active_sessions[session_id] = context
+
+        logger.debug("Started new session %s for user %s", session_id, user_id)
+        return context
+
+    async def update_context(
+        self,
+        session_id: str,
+        topics: Optional[List[str]] = None,
+        entities: Optional[List[str]] = None,
+        pending_tasks: Optional[List[str]] = None,
+    ) -> None:
+        """Update session context with new information.
+
+        Deduplicates topics and entities. Appends pending tasks.
+
+        Args:
+            session_id: Session to update
+            topics: New topics to add
+            entities: New entity IDs to add
+            pending_tasks: New pending tasks to add
+        """
+        if session_id not in self._active_sessions:
+            logger.warning("Attempted to update unknown session %s", session_id)
+            return
+
+        ctx = self._active_sessions[session_id]
+        ctx.last_activity = datetime.now()
+
+        if topics:
+            ctx.topics.extend(t for t in topics if t not in ctx.topics)
+        if entities:
+            ctx.entities.extend(e for e in entities if e not in ctx.entities)
+        if pending_tasks:
+            ctx.pending_tasks.extend(pending_tasks)
+
+    async def end_session(self, session_id: str) -> Optional[SessionContext]:
+        """Explicitly end a session.
+
+        Args:
+            session_id: Session to end
+
+        Returns:
+            The ended session context, or None if not found
+        """
+        ctx = self._active_sessions.pop(session_id, None)
+        if ctx:
+            logger.debug("Ended session %s", session_id)
+        return ctx
+
+    async def get_active_session(self, user_id: str) -> Optional[SessionContext]:
+        """Get the active session for a user, if any.
+
+        Args:
+            user_id: User to look up
+
+        Returns:
+            Active session or None
+        """
+        return await self._find_existing_session(user_id)
+
+    async def _find_existing_session(self, user_id: str) -> Optional[SessionContext]:
+        """Find an existing active session within the timeout window."""
+        cutoff = datetime.now() - self._session_timeout
+
+        for ctx in self._active_sessions.values():
+            if ctx.user_id == user_id and ctx.last_activity > cutoff:
+                return ctx
+
+        return None