monkeybrain-runtime 1.0.0__py3-none-any.whl

src/cortex/prediction.py

@@ -0,0 +1,142 @@
+"""Prediction — forecast pipeline outcomes without execution.
+
+Predictions use digital twins and historical data to estimate
+what would happen if a pipeline were executed.
+"""
+
+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
+from src.monkey_brain.kernel.loss import Loss, compute_loss
+from src.cortex.digital_twin import DigitalTwin
+
+
+@dataclass
+class Prediction:
+    """A predicted outcome of pipeline execution."""
+    
+    prediction_id: str = field(default_factory=lambda: f"pred-{uuid4().hex[:8]}")
+    pipeline_id: str = ""
+    predicted_state: dict[str, Any] = field(default_factory=dict)
+    predicted_answer: str = ""
+    confidence: float = 0.0
+    components: dict[str, float] = field(default_factory=dict)
+    twins_used: list[str] = field(default_factory=list)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class PredictionEngine:
+    """Predicts outcomes of capability execution.
+    
+    Responsibilities:
+    - Maintain digital twins
+    - Predict pipeline outcomes
+    - Track prediction accuracy
+    
+    The PredictionEngine never:
+    - Executes real capabilities
+    - Modifies production state
+    - Makes policy decisions
+    """
+    
+    def __init__(self):
+        self._twins: dict[str, DigitalTwin] = {}
+        self._predictions: list[Prediction] = []
+    
+    def register_twin(self, twin: DigitalTwin) -> None:
+        """Register a digital twin."""
+        key = f"{twin.entity_type}:{twin.entity_id}"
+        self._twins[key] = twin
+    
+    def get_twin(self, entity_type: str, entity_id: str) -> DigitalTwin | None:
+        """Get a digital twin by type and ID."""
+        key = f"{entity_type}:{entity_id}"
+        return self._twins.get(key)
+    
+    def get_twins(self, entity_type: str | None = None) -> list[DigitalTwin]:
+        """Get all twins, optionally filtered by type."""
+        if entity_type:
+            return [t for t in self._twins.values() if t.entity_type == entity_type]
+        return list(self._twins.values())
+    
+    def predict(
+        self,
+        pipeline: Pipeline,
+        state: dict[str, Any] | None = None,
+    ) -> Prediction:
+        """Predict pipeline outcome without execution.
+        
+        Uses digital twins to simulate each step.
+        """
+        prediction = Prediction(
+            pipeline_id=pipeline.pipeline_id,
+        )
+        
+        current_state = dict(state or {})
+        twins_used = []
+        
+        for step in pipeline.steps:
+            # Try to find relevant twin
+            entity_type = step.metadata.get("entity_type")
+            entity_id = step.metadata.get("entity_id")
+            
+            if entity_type and entity_id:
+                twin = self.get_twin(entity_type, entity_id)
+                if twin:
+                    twins_used.append(f"{entity_type}:{entity_id}")
+                    # Predict step effect
+                    predicted = twin.predict({
+                        "effects": {
+                            f"step:{step.step_id}": {
+                                "capability": step.capability_name,
+                                "status": "predicted",
+                            }
+                        }
+                    })
+                    current_state.update(predicted)
+            
+            # Record predicted step
+            prediction.predicted_state[f"step:{step.step_id}"] = {
+                "capability": step.capability_name,
+                "outputs": step.outputs,
+            }
+        
+        prediction.predicted_state.update(current_state)
+        prediction.twins_used = twins_used
+        prediction.confidence = self._calculate_confidence(twins_used, pipeline)
+        
+        self._predictions.append(prediction)
+        return prediction
+    
+    def _calculate_confidence(
+        self,
+        twins_used: list[str],
+        pipeline: Pipeline,
+    ) -> float:
+        """Calculate prediction confidence based on twin coverage."""
+        if not pipeline.steps:
+            return 0.0
+        
+        coverage = len(twins_used) / len(pipeline.steps)
+        return min(1.0, coverage * 0.8 + 0.2)
+    
+    def get_prediction(self, prediction_id: str) -> Prediction | None:
+        for pred in self._predictions:
+            if pred.prediction_id == prediction_id:
+                return pred
+        return None
+    
+    def get_predictions(self) -> list[Prediction]:
+        return list(self._predictions)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "twins": len(self._twins),
+            "predictions": len(self._predictions),
+        }

src/cortex/replay.py

@@ -0,0 +1,130 @@
+"""Replay — replay historical executions.
+
+Used for:
+- Debugging failed executions
+- Training Policy on past outcomes
+- Comparing predicted vs actual
+"""
+
+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
+from src.monkey_brain.kernel.loss import Loss, compute_loss
+from src.monkey_brain.runtime.runtime import ExecutionResult
+
+
+@dataclass
+class Recording:
+    """A recorded execution for replay."""
+    
+    recording_id: str = field(default_factory=lambda: f"rec-{uuid4().hex[:8]}")
+    pipeline: Pipeline = field(default_factory=Pipeline)
+    initial_state: dict[str, Any] = field(default_factory=dict)
+    result: ExecutionResult | None = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Comparison:
+    """Comparison of predicted vs actual outcome."""
+    
+    comparison_id: str = field(default_factory=lambda: f"comp-{uuid4().hex[:8]}")
+    prediction_id: str = ""
+    actual_pipeline_id: str = ""
+    predicted_state: dict[str, Any] = field(default_factory=dict)
+    actual_state: dict[str, Any] = field(default_factory=dict)
+    loss: Loss = field(default_factory=Loss)
+    component_losses: dict[str, float] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ReplayEngine:
+    """Replays historical executions.
+    
+    Responsibilities:
+    - Record executions for later replay
+    - Replay recorded executions
+    - Compare predicted vs actual outcomes
+    
+    The ReplayEngine never:
+    - Executes real capabilities
+    - Modifies production state
+    - Makes policy decisions
+    """
+    
+    def __init__(self):
+        self._recordings: list[Recording] = []
+        self._comparisons: list[Comparison] = []
+    
+    def record(self, execution: ExecutionResult, pipeline: Pipeline, initial_state: dict[str, Any] | None = None) -> Recording:
+        """Record an execution for later replay."""
+        recording = Recording(
+            pipeline=pipeline,
+            initial_state=initial_state or {},
+            result=execution,
+            metadata={
+                "success": execution.success,
+                "latency_ms": execution.total_latency_ms,
+                "step_count": execution.step_count(),
+            },
+        )
+        self._recordings.append(recording)
+        return recording
+    
+    def get_recording(self, recording_id: str) -> Recording | None:
+        for rec in self._recordings:
+            if rec.recording_id == recording_id:
+                return rec
+        return None
+    
+    def get_recordings(self) -> list[Recording]:
+        return list(self._recordings)
+    
+    def compare(
+        self,
+        prediction_id: str,
+        predicted_state: dict[str, Any],
+        actual: ExecutionResult,
+        actual_state: dict[str, Any] | None = None,
+    ) -> Comparison:
+        """Compare predicted vs actual outcome."""
+        actual_state = actual_state or actual.final_state
+        
+        loss = compute_loss(predicted_state, actual_state)
+        
+        comparison = Comparison(
+            prediction_id=prediction_id,
+            actual_pipeline_id=actual.pipeline_id,
+            predicted_state=predicted_state,
+            actual_state=actual_state,
+            loss=loss,
+            component_losses=loss.components,
+            metadata={
+                "actual_success": actual.success,
+                "actual_latency_ms": actual.total_latency_ms,
+            },
+        )
+        self._comparisons.append(comparison)
+        return comparison
+    
+    def get_comparison(self, comparison_id: str) -> Comparison | None:
+        for comp in self._comparisons:
+            if comp.comparison_id == comparison_id:
+                return comp
+        return None
+    
+    def get_comparisons(self) -> list[Comparison]:
+        return list(self._comparisons)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "recordings": len(self._recordings),
+            "comparisons": len(self._comparisons),
+        }

src/cortex/reward.py

@@ -0,0 +1,113 @@
+"""Reward Engine — computes rewards from execution outcomes.
+
+Reward functions are configurable.
+Reward signals are normalized.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RewardResult:
+    """Result of reward computation."""
+    
+    total_reward: float = 0.0
+    components: dict[str, float] = field(default_factory=dict)
+    normalized: float = 0.0  # 0.0 to 1.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class RewardEngine:
+    """Computes rewards from execution outcomes.
+    
+    Reward signals:
+    - Correctness
+    - User Feedback
+    - Ground Truth Match
+    - Execution Success
+    - Latency
+    - Resource Consumption
+    - Capability Success
+    - Workflow Success
+    """
+    
+    def __init__(self):
+        self._weights: dict[str, float] = {
+            "correctness": 0.3,
+            "user_feedback": 0.25,
+            "execution_success": 0.2,
+            "latency": 0.1,
+            "capability_success": 0.1,
+            "ground_truth_match": 0.05,
+        }
+    
+    def compute(
+        self,
+        success: bool,
+        latency_ms: float = 0.0,
+        user_feedback: dict[str, Any] | None = None,
+        ground_truth: dict[str, Any] | None = None,
+        answer: str = "",
+        capabilities: list[str] | None = None,
+        metrics: dict[str, Any] | None = None,
+    ) -> RewardResult:
+        """Compute reward from execution outcomes."""
+        components = {}
+        
+        # Execution success
+        components["execution_success"] = 1.0 if success else 0.0
+        
+        # Latency reward (lower is better, max 100ms)
+        if latency_ms > 0:
+            components["latency"] = max(0.0, 1.0 - (latency_ms / 1000.0))
+        else:
+            components["latency"] = 1.0
+        
+        # User feedback
+        if user_feedback:
+            feedback_reward = 0.0
+            if user_feedback.get("accepted"):
+                feedback_reward += 1.0
+            if user_feedback.get("thumb") == "up":
+                feedback_reward += 0.5
+            if user_feedback.get("thumb") == "down":
+                feedback_reward -= 0.5
+            if user_feedback.get("rating"):
+                feedback_reward += (user_feedback["rating"] - 3) / 2
+            components["user_feedback"] = max(-1.0, min(1.0, feedback_reward))
+        else:
+            components["user_feedback"] = 0.5  # Neutral
+        
+        # Ground truth match
+        if ground_truth and answer:
+            gt_answer = ground_truth.get("answer", "")
+            if gt_answer and gt_answer.lower() in answer.lower():
+                components["ground_truth_match"] = 1.0
+            else:
+                components["ground_truth_match"] = 0.0
+        else:
+            components["ground_truth_match"] = 0.5  # Neutral
+        
+        # Capability success
+        if capabilities:
+            components["capability_success"] = 1.0  # All succeeded if we got here
+        else:
+            components["capability_success"] = 0.0
+        
+        # Compute weighted total
+        total = 0.0
+        for component, value in components.items():
+            weight = self._weights.get(component, 0.0)
+            total += value * weight
+        
+        # Normalize to -1.0 to 1.0
+        normalized = max(-1.0, min(1.0, total))
+        
+        return RewardResult(
+            total_reward=total,
+            components=components,
+            normalized=normalized,
+        )

src/cortex/simulator.py

@@ -0,0 +1,102 @@
+"""Simulator — evaluates candidate execution strategies before execution.
+
+Simulation inputs:
+- Current State
+- Goal
+- Intent
+- Available Pipelines
+- Available Capabilities
+- Runtime Constraints
+- Memory
+- Historical Experience
+- Policies
+
+Simulation outputs:
+- Expected Reward
+- Expected Cost
+- Expected Latency
+- Expected Confidence
+- Expected Success Probability
+- Predicted Next State
+
+Simulation shall never produce side effects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from src.cortex.world_model import WorldModel
+
+
+@dataclass
+class SimulationResult:
+    """Result of a simulation."""
+    
+    simulation_id: str = field(default_factory=lambda: f"sim-{uuid4().hex[:8]}")
+    pipeline_id: str = ""
+    expected_reward: float = 0.0
+    expected_cost: float = 0.0
+    expected_latency_ms: float = 0.0
+    expected_confidence: float = 0.5
+    success_probability: float = 0.5
+    predicted_state: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Simulator:
+    """Evaluates candidate execution strategies.
+    
+    Simulation shall never produce side effects.
+    """
+    
+    def __init__(self, world_model: WorldModel):
+        self._world = world_model
+    
+    def simulate(
+        self,
+        pipeline_id: str,
+        capabilities: list[str],
+        state: dict[str, Any] | None = None,
+    ) -> SimulationResult:
+        """Simulate a pipeline execution without side effects."""
+        result = SimulationResult(pipeline_id=pipeline_id)
+        
+        # Estimate based on world model
+        total_latency = 0.0
+        total_cost = 0.0
+        success_prob = 1.0
+        
+        for cap_name in capabilities:
+            cap_state = self._world.get_capability(cap_name)
+            if cap_state:
+                total_latency += cap_state.avg_latency_ms
+                total_cost += cap_state.cost_per_execution
+                success_prob *= cap_state.reliability
+            else:
+                total_latency += 50.0
+                total_cost += 0.01
+                success_prob *= 0.8
+        
+        result.expected_latency_ms = total_latency
+        result.expected_cost = total_cost
+        result.success_probability = success_prob
+        result.expected_reward = success_prob * 0.8
+        result.expected_confidence = success_prob
+        
+        return result
+    
+    def simulate_alternative(
+        self,
+        original_pipeline: str,
+        alternative_pipeline: str,
+        original_capabilities: list[str],
+        alternative_capabilities: list[str],
+        state: dict[str, Any] | None = None,
+    ) -> tuple[SimulationResult, SimulationResult]:
+        """Compare two pipeline alternatives."""
+        original = self.simulate(original_pipeline, original_capabilities, state)
+        alternative = self.simulate(alternative_pipeline, alternative_capabilities, state)
+        return original, alternative

src/cortex/world_model.py

@@ -0,0 +1,180 @@
+"""World Model — continuously evolving environment representation.
+
+Maintains:
+- Environment State
+- Entity State
+- Capability State
+- Pipeline Performance
+- Policy Confidence
+- Historical Outcomes
+- Resource Availability
+- Failure Statistics
+- Cost Models
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class EntityState:
+    """State of a single entity."""
+    
+    entity_id: str = ""
+    entity_type: str = ""
+    confidence: float = 1.0
+    last_updated: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CapabilityState:
+    """State of a capability."""
+    
+    capability_name: str = ""
+    accuracy: float = 0.5
+    reliability: float = 0.5
+    avg_latency_ms: float = 0.0
+    failure_rate: float = 0.0
+    total_executions: int = 0
+    total_failures: int = 0
+    cost_per_execution: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class PipelineState:
+    """State of a pipeline."""
+    
+    pipeline_id: str = ""
+    success_rate: float = 0.5
+    avg_reward: float = 0.0
+    avg_cost: float = 0.0
+    avg_latency_ms: float = 0.0
+    total_executions: int = 0
+    total_failures: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class WorldModel:
+    """Continuously evolving environment representation.
+    
+    Maintains state across all subsystems.
+    Supports incremental updates.
+    """
+    
+    def __init__(self):
+        self._entities: dict[str, EntityState] = {}
+        self._capabilities: dict[str, CapabilityState] = {}
+        self._pipelines: dict[str, PipelineState] = {}
+        self._environment: dict[str, Any] = {}
+        self._cost_models: dict[str, dict[str, float]] = {}
+        self._failure_stats: dict[str, int] = {}
+    
+    # --- Entity State ---
+    
+    def update_entity(self, entity_id: str, entity_type: str, **metadata: Any) -> None:
+        self._entities[entity_id] = EntityState(
+            entity_id=entity_id,
+            entity_type=entity_type,
+            metadata=metadata,
+        )
+    
+    def get_entity(self, entity_id: str) -> EntityState | None:
+        return self._entities.get(entity_id)
+    
+    def get_entities_by_type(self, entity_type: str) -> list[EntityState]:
+        return [e for e in self._entities.values() if e.entity_type == entity_type]
+    
+    # --- Capability State ---
+    
+    def update_capability(
+        self,
+        name: str,
+        success: bool,
+        latency_ms: float = 0.0,
+        cost: float = 0.0,
+    ) -> None:
+        if name not in self._capabilities:
+            self._capabilities[name] = CapabilityState(capability_name=name)
+        
+        cap = self._capabilities[name]
+        cap.total_executions += 1
+        if not success:
+            cap.total_failures += 1
+        
+        # Update rolling averages
+        n = cap.total_executions
+        cap.avg_latency_ms = cap.avg_latency_ms * (n-1)/n + latency_ms/n
+        cap.failure_rate = cap.total_failures / n if n > 0 else 0.0
+        cap.reliability = 1.0 - cap.failure_rate
+        cap.accuracy = 0.5 + 0.5 * cap.reliability  # Simplified
+        cap.cost_per_execution = cap.cost_per_execution * (n-1)/n + cost/n
+    
+    def get_capability(self, name: str) -> CapabilityState | None:
+        return self._capabilities.get(name)
+    
+    # --- Pipeline State ---
+    
+    def update_pipeline(
+        self,
+        pipeline_id: str,
+        success: bool,
+        reward: float = 0.0,
+        cost: float = 0.0,
+        latency_ms: float = 0.0,
+    ) -> None:
+        if pipeline_id not in self._pipelines:
+            self._pipelines[pipeline_id] = PipelineState(pipeline_id=pipeline_id)
+        
+        pipe = self._pipelines[pipeline_id]
+        pipe.total_executions += 1
+        if not success:
+            pipe.total_failures += 1
+        
+        n = pipe.total_executions
+        pipe.avg_reward = pipe.avg_reward * (n-1)/n + reward/n
+        pipe.avg_cost = pipe.avg_cost * (n-1)/n + cost/n
+        pipe.avg_latency_ms = pipe.avg_latency_ms * (n-1)/n + latency_ms/n
+        pipe.success_rate = 1.0 - (pipe.total_failures / n if n > 0 else 0.0)
+    
+    def get_pipeline(self, pipeline_id: str) -> PipelineState | None:
+        return self._pipelines.get(pipeline_id)
+    
+    # --- Environment ---
+    
+    def update_environment(self, **kwargs: Any) -> None:
+        self._environment.update(kwargs)
+    
+    def get_environment(self) -> dict[str, Any]:
+        return dict(self._environment)
+    
+    # --- Cost Model ---
+    
+    def update_cost_model(self, component: str, costs: dict[str, float]) -> None:
+        self._cost_models[component] = costs
+    
+    def get_cost_model(self, component: str) -> dict[str, float]:
+        return self._cost_models.get(component, {})
+    
+    # --- Failure Stats ---
+    
+    def record_failure(self, component: str) -> None:
+        self._failure_stats[component] = self._failure_stats.get(component, 0) + 1
+    
+    def get_failure_stats(self) -> dict[str, int]:
+        return dict(self._failure_stats)
+    
+    def summary(self) -> dict:
+        return {
+            "entities": len(self._entities),
+            "capabilities": len(self._capabilities),
+            "pipelines": len(self._pipelines),
+            "environment_keys": len(self._environment),
+            "cost_models": len(self._cost_models),
+            "failure_components": len(self._failure_stats),
+        }