apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/cognition/registry.py

@@ -0,0 +1,192 @@
+"""CognitionPipeline — auto-wiring container for the cognition pipeline.
+
+Instantiates and connects MetricsCollector, PerformanceIndexComputer,
+GapDetector, StrategyAdjuster, and MetaLearner into a single callable
+pipeline.  Called once at Colony startup; ``run_tick()`` is driven by the
+autonomy loop on every event-processing cycle.
+
+Usage::
+
+    pipeline = CognitionPipeline(graph=graph_client)
+    # In the autonomy loop tick:
+    await pipeline.run_tick()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, List, Optional
+
+from .gap_detector import GapDetector, GapSeverity
+from .metalearner import MetaLearner, MetaLearnerConfig, CycleResult
+from .metrics_collector import MetricsCollector
+from .performance_index import PerformanceIndexComputer
+from .strategy_adjuster import StrategyAdjuster
+
+logger = logging.getLogger(__name__)
+
+
+class CognitionPipeline:
+    """Auto-wiring container for the five cognition modules.
+
+    Connects MetricsCollector → PerformanceIndexComputer → GapDetector →
+    StrategyAdjuster → MetaLearner and exposes a single ``run_tick()``
+    coroutine that drives one full evaluate-detect-adjust cycle.
+
+    Args:
+        graph: Colony graph client (passed through to sub-components).
+        event_bus: Optional event bus; if supplied, pipeline subscribes to
+            ``goal.completed``, ``task.completed``, and ``anomaly.detected``
+            to record metrics in real time.
+        config: Optional MetaLearnerConfig to customise cycle behaviour.
+    """
+
+    def __init__(
+        self,
+        graph: Any,
+        event_bus: Optional[Any] = None,
+        config: Optional[MetaLearnerConfig] = None,
+        params: Optional[Any] = None,
+    ) -> None:
+        self.graph = graph
+        self.event_bus = event_bus
+
+        # Instantiate sub-components
+        self.metrics = MetricsCollector(graph)
+        self.performance_index = PerformanceIndexComputer(graph)
+        self.gap_detector = GapDetector()
+        self.strategy_adjuster = StrategyAdjuster(graph, params=params)
+        self.meta_learner = MetaLearner(graph, config=config or MetaLearnerConfig())
+
+        # Wire sub-components into MetaLearner via dependency-injection setters
+        self.meta_learner.set_metrics_collector(self.metrics)
+        self.meta_learner.set_performance_index(self.performance_index)
+        self.meta_learner.set_gap_detector(self.gap_detector)
+        self.meta_learner.set_strategy_adjuster(self.strategy_adjuster)
+
+        # Subscribe to event-bus events if a bus was provided
+        if event_bus is not None:
+            self._subscribe(event_bus)
+
+        logger.info(
+            "CognitionPipeline initialised. Components: %s",
+            self.meta_learner.available_components,
+        )
+
+    # ── event-bus subscriptions ──────────────────────────────────────
+
+    def _subscribe(self, event_bus: Any) -> None:
+        """Register event handlers on *event_bus*.
+
+        Supports any bus that exposes ``subscribe(event_name, callback)``.
+        Errors during subscription are logged but not raised so that the
+        pipeline degrades gracefully when the bus API differs.
+        """
+        handlers: List[tuple[str, Callable]] = [
+            ("goal.completed", self._on_goal_completed),
+            ("task.completed", self._on_task_completed),
+            ("anomaly.detected", self._on_anomaly),
+        ]
+        for event_name, handler in handlers:
+            try:
+                event_bus.subscribe(event_name, handler)
+                logger.debug("CognitionPipeline subscribed to %r", event_name)
+            except Exception as exc:
+                logger.warning(
+                    "CognitionPipeline: could not subscribe to %r: %s", event_name, exc
+                )
+
+    def _on_goal_completed(self, event: Any) -> None:
+        """Record a goal-completed metric (synchronous hook)."""
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                loop.create_task(
+                    self.metrics.record("goal_completed", 1.0, domain="goal_progress")
+                )
+        except Exception as exc:
+            logger.debug("CognitionPipeline._on_goal_completed error: %s", exc)
+
+    def _on_task_completed(self, event: Any) -> None:
+        """Record a task-completed metric (synchronous hook)."""
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+            task_type = getattr(event, "task_type", None) or (
+                event.get("task_type") if isinstance(event, dict) else "unknown"
+            )
+            duration = getattr(event, "duration_minutes", None) or (
+                event.get("duration_minutes") if isinstance(event, dict) else 0.0
+            )
+            if loop.is_running():
+                loop.create_task(
+                    self.metrics.record_task_completion(
+                        str(task_type), float(duration or 0.0)
+                    )
+                )
+        except Exception as exc:
+            logger.debug("CognitionPipeline._on_task_completed error: %s", exc)
+
+    def _on_anomaly(self, event: Any) -> None:
+        """Record an anomaly signal (synchronous hook)."""
+        import asyncio
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                loop.create_task(
+                    self.metrics.record("anomaly_detected", 1.0, domain="general")
+                )
+        except Exception as exc:
+            logger.debug("CognitionPipeline._on_anomaly error: %s", exc)
+
+    # ── main tick ────────────────────────────────────────────────────
+
+    async def run_tick(self) -> CycleResult:
+        """Execute one full cognition cycle.
+
+        Called once per autonomy-loop tick.  Runs:
+        1. Performance evaluation (compute CPI)
+        2. Gap detection
+        3. Strategy adjustment (up to ``config.max_adjustments_per_cycle``)
+
+        Returns:
+            ``CycleResult`` with CPI, detected gaps, and applied adjustments.
+            Errors within sub-steps are captured in ``result.errors`` rather
+            than propagated so the autonomy loop is never blocked.
+        """
+        result = await self.meta_learner.run_cycle()
+
+        if result.errors:
+            logger.warning(
+                "CognitionPipeline.run_tick completed with %d error(s): %s",
+                len(result.errors),
+                "; ".join(result.errors[:3]),
+            )
+        else:
+            overall = result.cpi.overall if result.cpi else 0.0
+            gap_count = len(result.gaps)
+            logger.debug(
+                "CognitionPipeline.run_tick: CPI=%.1f, gaps=%d, adjustments=%d",
+                overall,
+                gap_count,
+                len(result.adjustments),
+            )
+
+        return result
+
+    # ── convenience accessors ────────────────────────────────────────
+
+    @property
+    def is_healthy(self) -> bool:
+        """True if all five sub-components are wired."""
+        return self.meta_learner.is_fully_wired
+
+    async def record_metric(
+        self,
+        metric_type: str,
+        value: float,
+        domain: str = "general",
+    ) -> None:
+        """Convenience proxy: record a metric directly into the pipeline."""
+        await self.metrics.record(metric_type, value, domain=domain)

apsimo/intelligence/cognition/strategy_adjuster.py

@@ -0,0 +1,222 @@
+"""Strategy adjustment for cognitive gaps."""
+import logging
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+from datetime import datetime
+from enum import Enum
+
+from apsimo.self_model.benchmark import cognition_p4_mode
+
+logger = logging.getLogger(__name__)
+
+
+class AdjustmentStatus(str, Enum):
+    """Status of an adjustment."""
+    PROPOSED = "proposed"
+    APPLIED = "applied"
+    FAILED = "failed"
+    REVERTED = "reverted"
+
+
+@dataclass
+class Adjustment:
+    """Strategy adjustment for a gap."""
+    adjustment_type: str
+    hypothesis: str
+    target_gap: "Gap"
+    actions: list  # List of action dicts
+    expected_impact: float  # Expected CPI improvement
+    status: AdjustmentStatus = AdjustmentStatus.PROPOSED
+    applied_at: Optional[datetime] = None
+    result: Optional[Dict[str, Any]] = None
+
+
+class StrategyAdjuster:
+    """Generate experiment proposals from legacy CPI gaps.
+
+    This component is retained as a detector adapter. It deliberately never
+    writes an adaptive parameter or graph policy; ExperimentEngine is the one
+    controlled writer and requires exposure/outcome evidence.
+    """
+
+    # Gap type to adjustment strategies mapping
+    STRATEGIES = {
+        "low_memory_quality": {
+            "hypothesis": "Memory retrieval quality is low due to weak embeddings",
+            "actions": [
+                {"type": "reindex_memories", "params": {}},
+                # Tighten the consolidator so near-miss pairs stop merging
+                # (weak embeddings inflate similarity; merging makes recall
+                # quality worse). Bounded by the param store [0.85, 0.98].
+                {"type": "adjust_consolidation_threshold", "params": {"threshold": 0.95}},
+            ],
+            "expected_impact": 10.0,
+        },
+        "semantic_mismatch": {
+            "hypothesis": "Queries not matching stored memories semantically",
+            "actions": [
+                # Raise the recall relevance floor so low-score noise stops
+                # outranking real matches. Bounded by the param store [0, 0.5].
+                {"type": "adjust_similarity_threshold", "params": {"threshold": 0.35}},
+                {"type": "expand_query_terms", "params": {}},
+            ],
+            "expected_impact": 8.0,
+        },
+        "insufficient_data": {
+            "hypothesis": "Not enough data to make accurate predictions",
+            "actions": [
+                {"type": "increase_observation_window", "params": {"days": 14}},
+                {"type": "prompt_user_for_data", "params": {}},
+            ],
+            "expected_impact": 5.0,
+        },
+        "stale_data": {
+            "hypothesis": "Data is too old to be relevant",
+            "actions": [
+                {"type": "refresh_data_source", "params": {}},
+                {"type": "decay_old_signals", "params": {"factor": 0.5}},
+            ],
+            "expected_impact": 7.0,
+        },
+        "missing_preference": {
+            "hypothesis": "User preference not captured",
+            "actions": [
+                {"type": "ask_preference", "params": {}},
+                {"type": "infer_from_behavior", "params": {}},
+            ],
+            "expected_impact": 6.0,
+        },
+        "low_prediction_accuracy": {
+            "hypothesis": "Prediction model not calibrated to user patterns",
+            "actions": [
+                {"type": "recalibrate_baselines", "params": {}},
+                {"type": "adjust_confidence_threshold", "params": {"threshold": 0.6}},
+            ],
+            "expected_impact": 12.0,
+        },
+        "tool_inefficiency": {
+            "hypothesis": "Tools being used suboptimally",
+            "actions": [
+                {"type": "audit_tool_usage", "params": {}},
+                {"type": "optimize_tool_selection", "params": {}},
+            ],
+            "expected_impact": 8.0,
+        },
+        "initiative_mismatch": {
+            "hypothesis": "Proactive suggestions not matching user needs",
+            "actions": [
+                {"type": "adjust_suggestion_frequency", "params": {"factor": 0.7}},
+                {"type": "refine_suggestion_criteria", "params": {}},
+            ],
+            "expected_impact": 6.0,
+        },
+    }
+
+    def __init__(self, graph: "ColonyGraph", params: Any = None):
+        self.graph = graph
+        # params remains a constructor compatibility argument. Only the
+        # ExperimentEngine owns parameter writes; this detector proposes.
+        self._experiment_proposer: Any = None
+        self._applied_adjustments: list = []
+
+    def set_experiment_proposer(self, proposer: Any) -> None:
+        """Wire ExperimentEngine after boot without creating another writer."""
+
+        self._experiment_proposer = proposer
+
+    async def generate(self, gap: "Gap") -> Adjustment:
+        """Generate adjustment strategy for a gap."""
+        gap_type_str = gap.gap_type.value if hasattr(gap.gap_type, "value") else str(gap.gap_type)
+        strategy = self.STRATEGIES.get(gap_type_str, self._default_strategy())
+
+        adjustment = Adjustment(
+            adjustment_type=gap_type_str,
+            hypothesis=strategy["hypothesis"],
+            target_gap=gap,
+            actions=strategy["actions"],
+            expected_impact=strategy["expected_impact"],
+        )
+
+        return adjustment
+
+    async def apply(self, adjustment: Adjustment) -> bool:
+        """Record typed proposals without executing legacy adjustment actions."""
+        results = []
+        for action in adjustment.actions:
+            result = {
+                "success": False,
+                "action": action.get("type"),
+                "params": dict(action.get("params") or {}),
+                "proposal_required": True,
+                "reason": "legacy CPI detectors may propose; ExperimentEngine writes",
+            }
+            spec = self._experiment_spec(adjustment, action)
+            if spec is not None:
+                result["experiment_proposal"] = spec
+                if (self._experiment_proposer is not None
+                        and cognition_p4_mode() in {"shadow", "live"}):
+                    try:
+                        saved = self._experiment_proposer.propose(**spec)
+                        result["proposal_id"] = saved.get("id")
+                    except ValueError as exc:
+                        # An already-open proposal is the expected dedupe path.
+                        result["proposal_error"] = str(exc)
+            results.append(result)
+        adjustment.result = {
+            "actions_taken": len(results),
+            "successful": 0,
+            "proposals": len(results),
+            "details": results,
+        }
+        adjustment.status = AdjustmentStatus.PROPOSED
+        logger.info(
+            "legacy cognition gap %s emitted %d controlled-learning proposal(s)",
+            adjustment.adjustment_type, len(results))
+        return False
+
+    @staticmethod
+    def _experiment_spec(adjustment: Adjustment,
+                         action: dict) -> Optional[Dict[str, Any]]:
+        """Map the two real legacy knobs into typed, non-started proposals."""
+
+        action_type = action.get("type")
+        raw = dict(action.get("params") or {})
+        if action_type == "adjust_similarity_threshold":
+            ref = "recall.min_relevance"
+        elif action_type == "adjust_consolidation_threshold":
+            ref = "consolidation.similarity_threshold"
+        else:
+            return None
+        if "threshold" not in raw:
+            return None
+        return {
+            "hypothesis": adjustment.hypothesis,
+            "ref": ref,
+            "variant": float(raw["threshold"]),
+            "metric": "recall.fact_coverage",
+            "metric_version": "v2",
+            "assignment_mode": "cohort",
+            "max_regression": 0.05,
+            "window_days": 7,
+            "source": f"legacy-cpi-gap:{adjustment.adjustment_type}",
+        }
+
+
+    def _default_strategy(self) -> dict:
+        """Default strategy for unknown gap types."""
+        return {
+            "hypothesis": "Performance gap detected, root cause unclear",
+            "actions": [
+                {"type": "log_gap", "params": {}},
+                {"type": "monitor", "params": {"duration_hours": 24}},
+            ],
+            "expected_impact": 3.0,
+        }
+
+    def get_recent_adjustments(self, hours: int = 24) -> list:
+        """Get recently applied adjustments."""
+        cutoff = datetime.now()
+        return [
+            adj for adj in self._applied_adjustments
+            if adj.applied_at and (cutoff - adj.applied_at).total_seconds() / 3600 < hours
+        ]

apsimo/intelligence/cognition/types.py

@@ -0,0 +1,16 @@
+"""Shared types for the cognition package.
+
+Centralising enums and dataclasses here breaks the circular dependency between
+metalearner and gap_detector (both previously importing from each other).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class GapSeverity(str, Enum):
+    """Severity levels for cognitive performance gaps."""
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"

apsimo/intelligence/components/__init__.py

@@ -0,0 +1,66 @@
+"""Specialized intelligence components.
+
+Eight domain-specific components that provide tool learning, self-reflection,
+task planning, session continuity, research orchestration, preference learning,
+anomaly detection, and proactive initiative generation.
+
+Public API:
+    - ``ToolLearner`` / ``ToolUsage`` / ``ToolPreference`` — learn tool preferences
+    - ``SelfReflector`` / ``Reflection`` — self-evaluation and improvement
+    - ``TaskPlanner`` / ``TaskPlan`` / ``SubTask`` / ``TaskPriority`` — task decomposition
+    - ``SessionContinuity`` / ``SessionContext`` — cross-session context
+    - ``ResearchOrchestrator`` / ``ResearchReport`` / ``ResearchResult`` / ``ResearchSource`` / ``SourceType`` — multi-source research
+    - ``PreferenceLearner`` / ``Preference`` — user preference extraction
+    - ``AnomalyDetector`` / ``Anomaly`` / ``AnomalyType`` — unusual pattern detection
+    - ``InitiativeEngine`` / ``Initiative`` / ``InitiativeType`` — proactive suggestions
+"""
+
+from .tool_learner import ToolLearner, ToolPreference, ToolUsage
+from .self_reflector import Reflection, SelfReflector
+from .task_planner import SubTask, TaskPlan, TaskPlanner, TaskPriority
+from .session_continuity import SessionContext, SessionContinuity
+from .research_orchestrator import (
+    ResearchOrchestrator,
+    ResearchReport,
+    ResearchResult,
+    ResearchSource,
+    SourceType,
+)
+from .preference_learner import Preference, PreferenceLearner
+from .anomaly_detector import Anomaly, AnomalyDetector, AnomalyType
+from .initiative_engine import Initiative, InitiativeEngine, InitiativeType
+
+__all__ = [
+    # Tool learning
+    "ToolLearner",
+    "ToolUsage",
+    "ToolPreference",
+    # Self-reflection
+    "SelfReflector",
+    "Reflection",
+    # Task planning
+    "TaskPlanner",
+    "TaskPlan",
+    "SubTask",
+    "TaskPriority",
+    # Session continuity
+    "SessionContinuity",
+    "SessionContext",
+    # Research
+    "ResearchOrchestrator",
+    "ResearchReport",
+    "ResearchResult",
+    "ResearchSource",
+    "SourceType",
+    # Preferences
+    "PreferenceLearner",
+    "Preference",
+    # Anomaly detection
+    "AnomalyDetector",
+    "Anomaly",
+    "AnomalyType",
+    # Initiative
+    "InitiativeEngine",
+    "Initiative",
+    "InitiativeType",
+]