monkeybrain-runtime 1.0.0__py3-none-any.whl

src/cortex/counterfactual.py

@@ -0,0 +1,162 @@
+"""Counterfactual — execute alternative scenarios.
+
+"What if we used a different capability?"
+"What if the state was different?"
+"What if we skipped this step?"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.kernel.pipeline import Pipeline, PipelineStep
+from src.monkey_brain.kernel.loss import Loss, compute_loss
+from src.cortex.prediction import Prediction, PredictionEngine
+
+
+@dataclass
+class Scenario:
+    """A counterfactual scenario."""
+    
+    scenario_id: str = field(default_factory=lambda: f"scen-{uuid4().hex[:8]}")
+    name: str = ""
+    description: str = ""
+    original_pipeline: Pipeline = field(default_factory=Pipeline)
+    modified_pipeline: Pipeline = field(default_factory=Pipeline)
+    modifications: dict[str, Any] = field(default_factory=dict)
+    prediction: Prediction | None = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class CounterfactualEngine:
+    """Executes alternative scenarios.
+    
+    Responsibilities:
+    - Create modified pipelines
+    - Predict counterfactual outcomes
+    - Compare scenarios
+    
+    The CounterfactualEngine never:
+    - Executes real capabilities
+    - Modifies production state
+    - Makes policy decisions
+    """
+    
+    def __init__(self, prediction_engine: PredictionEngine):
+        self._prediction_engine = prediction_engine
+        self._scenarios: list[Scenario] = []
+    
+    def what_if(
+        self,
+        pipeline: Pipeline,
+        state: dict[str, Any] | None,
+        modifications: dict[str, Any],
+    ) -> Scenario:
+        """Create a counterfactual scenario with modifications."""
+        modified_steps = []
+        
+        for step in pipeline.steps:
+            new_step = PipelineStep(
+                step_id=step.step_id,
+                capability_name=step.capability_name,
+                inputs=list(step.inputs),
+                outputs=list(step.outputs),
+                dependencies=list(step.dependencies),
+                metadata=dict(step.metadata),
+            )
+            
+            # Apply modifications
+            if step.step_id in modifications:
+                mod = modifications[step.step_id]
+                if "capability_name" in mod:
+                    new_step.capability_name = mod["capability_name"]
+                if "skip" in mod and mod["skip"]:
+                    continue
+            
+            modified_steps.append(new_step)
+        
+        modified_pipeline = Pipeline(
+            steps=modified_steps,
+            metadata=dict(pipeline.metadata),
+        )
+        
+        scenario = Scenario(
+            name=f"what-if-{len(self._scenarios) + 1}",
+            original_pipeline=pipeline,
+            modified_pipeline=modified_pipeline,
+            modifications=modifications,
+        )
+        
+        # Predict outcome
+        scenario.prediction = self._prediction_engine.predict(
+            modified_pipeline,
+            state,
+        )
+        
+        self._scenarios.append(scenario)
+        return scenario
+    
+    def alternative(
+        self,
+        original_pipeline: Pipeline,
+        alternative_pipeline: Pipeline,
+        state: dict[str, Any] | None,
+    ) -> tuple[Scenario, Scenario]:
+        """Compare two different pipelines."""
+        original_scenario = Scenario(
+            name="original",
+            original_pipeline=original_pipeline,
+            modified_pipeline=original_pipeline,
+        )
+        original_scenario.prediction = self._prediction_engine.predict(
+            original_pipeline,
+            state,
+        )
+        
+        alternative_scenario = Scenario(
+            name="alternative",
+            original_pipeline=original_pipeline,
+            modified_pipeline=alternative_pipeline,
+        )
+        alternative_scenario.prediction = self._prediction_engine.predict(
+            alternative_pipeline,
+            state,
+        )
+        
+        self._scenarios.extend([original_scenario, alternative_scenario])
+        return original_scenario, alternative_scenario
+    
+    def skip_step(
+        self,
+        pipeline: Pipeline,
+        step_id: str,
+        state: dict[str, Any] | None,
+    ) -> Scenario:
+        """Create scenario with a step skipped."""
+        return self.what_if(pipeline, state, {step_id: {"skip": True}})
+    
+    def swap_capability(
+        self,
+        pipeline: Pipeline,
+        step_id: str,
+        new_capability: str,
+        state: dict[str, Any] | None,
+    ) -> Scenario:
+        """Create scenario with a different capability."""
+        return self.what_if(pipeline, state, {step_id: {"capability_name": new_capability}})
+    
+    def get_scenario(self, scenario_id: str) -> Scenario | None:
+        for scen in self._scenarios:
+            if scen.scenario_id == scenario_id:
+                return scen
+        return None
+    
+    def get_scenarios(self) -> list[Scenario]:
+        return list(self._scenarios)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {"scenarios": len(self._scenarios)}

src/cortex/digital_twin.py

@@ -0,0 +1,90 @@
+"""Digital Twin — virtual replica of a real-world entity.
+
+Digital Twins maintain state and respond to commands
+exactly like their real counterparts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class TwinState:
+    """State snapshot of a digital twin."""
+    
+    state_id: str = field(default_factory=lambda: f"state-{uuid4().hex[:8]}")
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+class DigitalTwin:
+    """A virtual replica of a real-world entity.
+    
+    Responsibilities:
+    - Maintain current state
+    - Track state history
+    - Predict state transitions
+    - Support rollback
+    
+    The DigitalTwin never:
+    - Executes capabilities
+    - Makes policy decisions
+    - Manages connections
+    """
+    
+    def __init__(self, entity_type: str, entity_id: str):
+        self.entity_type = entity_type
+        self.entity_id = entity_id
+        self._state: dict[str, Any] = {}
+        self._history: list[TwinState] = []
+        self._id = f"twin-{uuid4().hex[:8]}"
+    
+    @property
+    def id(self) -> str:
+        return self._id
+    
+    def get_state(self) -> dict[str, Any]:
+        """Get current twin state."""
+        return dict(self._state)
+    
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Update twin state, preserving history."""
+        self._history.append(TwinState(data=dict(self._state)))
+        self._state.update(state)
+    
+    def replace_state(self, state: dict[str, Any]) -> None:
+        """Replace entire twin state."""
+        self._history.append(TwinState(data=dict(self._state)))
+        self._state = dict(state)
+    
+    def predict(self, action: dict[str, Any]) -> dict[str, Any]:
+        """Predict state after action (without executing)."""
+        predicted = dict(self._state)
+        effects = action.get("effects", {})
+        predicted.update(effects)
+        return predicted
+    
+    def rollback(self, steps: int = 1) -> dict[str, Any] | None:
+        """Rollback to previous state."""
+        if len(self._history) >= steps:
+            for _ in range(steps):
+                prev = self._history.pop()
+            self._state = dict(prev.data)
+            return self._state
+        return None
+    
+    def history(self) -> list[TwinState]:
+        return list(self._history)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self._id,
+            "entity_type": self.entity_type,
+            "entity_id": self.entity_id,
+            "state": dict(self._state),
+            "history_length": len(self._history),
+        }

src/cortex/experience.py

@@ -0,0 +1,83 @@
+"""Experience Store — stores every execution as an Experience.
+
+Experience contains:
+- State
+- Action
+- Reward
+- Loss
+- Next State
+
+Support replay, offline learning, and benchmark replay.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class Experience:
+    """A single experience from execution."""
+    
+    experience_id: str = field(default_factory=lambda: f"exp-{uuid4().hex[:12]}")
+    state: dict[str, Any] = field(default_factory=dict)
+    action: str = ""
+    reward: float = 0.0
+    loss: float = 0.0
+    next_state: dict[str, Any] = field(default_factory=dict)
+    done: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class ExperienceStore:
+    """Stores every execution as an Experience.
+    
+    Supports:
+    - Replay
+    - Offline Learning
+    - Benchmark Replay
+    - Regression Validation
+    """
+    
+    def __init__(self, max_size: int = 10000):
+        self._experiences: list[Experience] = []
+        self._max_size = max_size
+    
+    def store(self, experience: Experience) -> None:
+        """Store an experience."""
+        self._experiences.append(experience)
+        
+        if len(self._experiences) > self._max_size:
+            self._experiences = self._experiences[-self._max_size // 2:]
+    
+    def sample(self, n: int = 32) -> list[Experience]:
+        """Sample random experiences for learning."""
+        import random
+        return random.sample(self._experiences, min(n, len(self._experiences)))
+    
+    def get_recent(self, n: int = 100) -> list[Experience]:
+        """Get recent experiences."""
+        return self._experiences[-n:]
+    
+    def get_by_action(self, action: str) -> list[Experience]:
+        """Get experiences for a specific action."""
+        return [e for e in self._experiences if e.action == action]
+    
+    def count(self) -> int:
+        return len(self._experiences)
+    
+    def summary(self) -> dict:
+        if not self._experiences:
+            return {"total": 0}
+        
+        rewards = [e.reward for e in self._experiences]
+        return {
+            "total": len(self._experiences),
+            "avg_reward": sum(rewards) / len(rewards),
+            "actions": len(set(e.action for e in self._experiences)),
+        }

src/cortex/feedback.py

@@ -0,0 +1,144 @@
+"""Feedback Engine — evaluates executions and drives learning.
+
+Every completed execution produces a Feedback Record.
+Learning is asynchronous and never blocks user responses.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class FeedbackRecord:
+    """A complete feedback record for an execution."""
+    
+    feedback_id: str = field(default_factory=lambda: f"fb-{uuid4().hex[:12]}")
+    
+    # Execution Context
+    question: str = ""
+    intent: str = ""
+    workflow: str = ""
+    pipeline_id: str = ""
+    capabilities: list[str] = field(default_factory=list)
+    
+    # Results
+    answer: str = ""
+    success: bool = False
+    latency_ms: float = 0.0
+    
+    # Ground Truth
+    ground_truth: dict[str, Any] = field(default_factory=dict)
+    
+    # User Feedback
+    user_feedback: dict[str, Any] = field(default_factory=dict)
+    
+    # Metrics
+    metrics: dict[str, Any] = field(default_factory=dict)
+    
+    # Learning
+    reward: float = 0.0
+    loss: float = 0.0
+    reward_components: dict[str, float] = field(default_factory=dict)
+    loss_components: dict[str, float] = field(default_factory=dict)
+    
+    # Timestamp
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "feedback_id": self.feedback_id,
+            "question": self.question,
+            "intent": self.intent,
+            "pipeline_id": self.pipeline_id,
+            "capabilities": self.capabilities,
+            "answer": self.answer,
+            "success": self.success,
+            "latency_ms": self.latency_ms,
+            "reward": self.reward,
+            "loss": self.loss,
+            "timestamp": self.timestamp,
+        }
+
+
+class FeedbackEngine:
+    """Evaluates executions and drives learning.
+    
+    Responsibilities:
+    - Collect execution feedback
+    - Compute rewards and losses
+    - Update policies
+    - Store experiences
+    - Emit telemetry
+    
+    Learning is asynchronous and never blocks user responses.
+    """
+    
+    def __init__(self):
+        self._records: list[FeedbackRecord] = []
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def record(
+        self,
+        question: str,
+        intent: str,
+        pipeline_id: str,
+        capabilities: list[str],
+        answer: str,
+        success: bool,
+        latency_ms: float,
+        ground_truth: dict[str, Any] | None = None,
+        user_feedback: dict[str, Any] | None = None,
+        metrics: dict[str, Any] | None = None,
+    ) -> FeedbackRecord:
+        """Record feedback for an execution."""
+        record = FeedbackRecord(
+            question=question,
+            intent=intent,
+            pipeline_id=pipeline_id,
+            capabilities=capabilities,
+            answer=answer,
+            success=success,
+            latency_ms=latency_ms,
+            ground_truth=ground_truth or {},
+            user_feedback=user_feedback or {},
+            metrics=metrics or {},
+        )
+        
+        self._records.append(record)
+        
+        if self._lemon:
+            self._lemon.counter("xavier.executions_evaluated")
+            self._lemon.histogram("xavier.latency_ms", latency_ms)
+        
+        return record
+    
+    def get_records(self, limit: int = 100) -> list[FeedbackRecord]:
+        return self._records[-limit:]
+    
+    def get_record(self, feedback_id: str) -> FeedbackRecord | None:
+        for r in self._records:
+            if r.feedback_id == feedback_id:
+                return r
+        return None
+    
+    def summary(self) -> dict:
+        if not self._records:
+            return {"total": 0}
+        
+        rewards = [r.reward for r in self._records]
+        losses = [r.loss for r in self._records]
+        
+        return {
+            "total": len(self._records),
+            "avg_reward": sum(rewards) / len(rewards),
+            "avg_loss": sum(losses) / len(losses),
+            "success_rate": sum(1 for r in self._records if r.success) / len(self._records),
+        }

src/cortex/loss.py

@@ -0,0 +1,116 @@
+"""Loss Engine — computes loss across multiple dimensions.
+
+Loss functions are independently configurable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LossResult:
+    """Result of loss computation."""
+    
+    total_loss: float = 0.0
+    components: dict[str, float] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class LossEngine:
+    """Computes loss across multiple dimensions.
+    
+    Loss dimensions:
+    - Intent Loss
+    - Execution Loss
+    - Answer Quality Loss
+    - Grounding Loss
+    - Latency Loss
+    - Capability Loss
+    """
+    
+    def __init__(self):
+        self._weights: dict[str, float] = {
+            "intent_loss": 0.2,
+            "execution_loss": 0.2,
+            "answer_quality_loss": 0.3,
+            "grounding_loss": 0.2,
+            "latency_loss": 0.1,
+            "capability_loss": 0.1,
+        }
+    
+    def compute(
+        self,
+        success: bool,
+        latency_ms: float = 0.0,
+        ground_truth: dict[str, Any] | None = None,
+        answer: str = "",
+        intent: str = "",
+        expected_intent: str = "",
+        capabilities: list[str] | None = None,
+        expected_capabilities: list[str] | None = None,
+    ) -> LossResult:
+        """Compute loss from execution outcomes."""
+        components = {}
+        
+        # Intent loss
+        if expected_intent:
+            components["intent_loss"] = 0.0 if intent == expected_intent else 1.0
+        else:
+            components["intent_loss"] = 0.0
+        
+        # Execution loss
+        components["execution_loss"] = 0.0 if success else 1.0
+        
+        # Answer quality loss
+        if ground_truth and answer:
+            gt_answer = ground_truth.get("answer", "")
+            if gt_answer:
+                # Simple string similarity
+                common = set(gt_answer.lower().split()) & set(answer.lower().split())
+                total = set(gt_answer.lower().split()) | set(answer.lower().split())
+                similarity = len(common) / len(total) if total else 0.0
+                components["answer_quality_loss"] = 1.0 - similarity
+            else:
+                components["answer_quality_loss"] = 0.0
+        else:
+            components["answer_quality_loss"] = 0.0
+        
+        # Grounding loss
+        if ground_truth and answer:
+            gt_keywords = set(ground_truth.get("keywords", []))
+            answer_words = set(answer.lower().split())
+            if gt_keywords:
+                overlap = len(gt_keywords & answer_words)
+                components["grounding_loss"] = 1.0 - (overlap / len(gt_keywords))
+            else:
+                components["grounding_loss"] = 0.0
+        else:
+            components["grounding_loss"] = 0.0
+        
+        # Latency loss (target: <100ms)
+        target_latency = 100.0
+        components["latency_loss"] = min(1.0, max(0.0, (latency_ms - target_latency) / target_latency))
+        
+        # Capability loss
+        if expected_capabilities and capabilities:
+            expected_set = set(expected_capabilities)
+            actual_set = set(capabilities)
+            if expected_set:
+                components["capability_loss"] = 1.0 - len(expected_set & actual_set) / len(expected_set)
+            else:
+                components["capability_loss"] = 0.0
+        else:
+            components["capability_loss"] = 0.0
+        
+        # Compute weighted total
+        total = 0.0
+        for component, value in components.items():
+            weight = self._weights.get(component, 0.0)
+            total += value * weight
+        
+        return LossResult(
+            total_loss=total,
+            components=components,
+        )