monkeybrain-runtime 1.0.0__py3-none-any.whl

src/cortex/world_state.py

@@ -0,0 +1,121 @@
+"""WorldState — complete world state for simulation.
+
+Maintains three views of reality:
+- Current: what is actually happening
+- Expected: what should be happening
+- Counterfactual: what could happen
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class WorldSnapshot:
+    """A point-in-time snapshot of world state."""
+    
+    snapshot_id: str = field(default_factory=lambda: f"wsnap-{uuid4().hex[:8]}")
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    current: dict[str, Any] = field(default_factory=dict)
+    expected: dict[str, Any] = field(default_factory=dict)
+    counterfactual: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class WorldState:
+    """Complete world state for simulation.
+    
+    Responsibilities:
+    - Maintain current, expected, and counterfactual states
+    - Track state history
+    - Support snapshots and rollback
+    
+    The WorldState never:
+    - Executes capabilities
+    - Makes policy decisions
+    - Modifies real-world state
+    """
+    
+    def __init__(self):
+        self._current: dict[str, Any] = {}
+        self._expected: dict[str, Any] = {}
+        self._counterfactual: dict[str, Any] = {}
+        self._history: list[WorldSnapshot] = []
+    
+    @property
+    def current(self) -> dict[str, Any]:
+        return dict(self._current)
+    
+    @property
+    def expected(self) -> dict[str, Any]:
+        return dict(self._expected)
+    
+    @property
+    def counterfactual(self) -> dict[str, Any]:
+        return dict(self._counterfactual)
+    
+    def update_current(self, state: dict[str, Any]) -> None:
+        """Update current world state."""
+        self._current.update(state)
+    
+    def update_expected(self, state: dict[str, Any]) -> None:
+        """Update expected world state."""
+        self._expected.update(state)
+    
+    def update_counterfactual(self, state: dict[str, Any]) -> None:
+        """Update counterfactual world state."""
+        self._counterfactual.update(state)
+    
+    def replace_current(self, state: dict[str, Any]) -> None:
+        """Replace entire current state."""
+        self._current = dict(state)
+    
+    def replace_expected(self, state: dict[str, Any]) -> None:
+        """Replace entire expected state."""
+        self._expected = dict(state)
+    
+    def replace_counterfactual(self, state: dict[str, Any]) -> None:
+        """Replace entire counterfactual state."""
+        self._counterfactual = dict(state)
+    
+    def snapshot(self, metadata: dict[str, Any] | None = None) -> WorldSnapshot:
+        """Take a snapshot of all states."""
+        snap = WorldSnapshot(
+            current=dict(self._current),
+            expected=dict(self._expected),
+            counterfactual=dict(self._counterfactual),
+            metadata=metadata or {},
+        )
+        self._history.append(snap)
+        return snap
+    
+    def rollback(self, snapshot_id: str) -> bool:
+        """Rollback to a previous snapshot."""
+        for snap in self._history:
+            if snap.snapshot_id == snapshot_id:
+                self._current = dict(snap.current)
+                self._expected = dict(snap.expected)
+                self._counterfactual = dict(snap.counterfactual)
+                return True
+        return False
+    
+    def history(self) -> list[WorldSnapshot]:
+        return list(self._history)
+    
+    def clear(self) -> None:
+        """Clear all state."""
+        self._current.clear()
+        self._expected.clear()
+        self._counterfactual.clear()
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "current": dict(self._current),
+            "expected": dict(self._expected),
+            "counterfactual": dict(self._counterfactual),
+            "history_length": len(self._history),
+        }

src/cortex/xavier.py

@@ -0,0 +1,250 @@
+"""Xavier — Simulation, Feedback & Learning Engine.
+
+The closed learning loop of AgentOS.
+
+Xavier predicts, evaluates, learns, and optimizes.
+Xavier never executes capabilities directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src.cortex.world_model import WorldModel
+from src.cortex.simulator import Simulator, SimulationResult
+from src.cortex.cost import CostEngine, CostEstimate
+from src.cortex.reward import RewardEngine, RewardResult
+from src.cortex.loss import LossEngine, LossResult
+from src.cortex.feedback import FeedbackEngine, FeedbackRecord
+from src.cortex.experience import ExperienceStore, Experience
+from src.monkey_brain.kernel.rl.policy import BellmanPolicy
+from src.monkey_brain.kernel.observer import Observer
+from src.monkey_brain.kernel.learning import Learning
+from src.monkey_brain.kernel.rl.transition import Transition
+from src.monkey_brain.kernel.llm_explorer import LLMExplorer
+
+
+class Xavier:
+    """Simulation, Feedback & Learning Engine.
+    
+    Xavier predicts, evaluates, learns, and optimizes.
+    Xavier never executes capabilities directly.
+    
+    Flow:
+    1. LLM Explorer generates candidates (exploration)
+    2. Simulator evaluates candidates
+    3. Policy selects best candidate (exploitation)
+    4. Runtime executes (Wolverine)
+    5. Xavier evaluates outcome
+    6. Reward/Loss computed
+    7. Policy updated
+    8. World Model updated
+    9. Experience stored
+    """
+    
+    def __init__(
+        self,
+        policy: BellmanPolicy | None = None,
+        observer: Observer | None = None,
+        learning: Learning | None = None,
+    ):
+        # Core engines
+        self.world_model = WorldModel()
+        self.simulator = Simulator(self.world_model)
+        self.cost_engine = CostEngine()
+        self.reward_engine = RewardEngine()
+        self.loss_engine = LossEngine()
+        self.feedback_engine = FeedbackEngine()
+        self.experience_store = ExperienceStore()
+        self.llm_explorer = LLMExplorer()
+        
+        # Dependencies
+        self._policy = policy or BellmanPolicy()
+        self._observer = observer or Observer()
+        self._learning = learning or Learning()
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+        self.feedback_engine.set_lemon(lemon)
+        self.llm_explorer.set_lemon(lemon)
+        self._policy.set_lemon(lemon)
+    
+    # --- Exploration (LLM generates candidates) ---
+    
+    def explore(
+        self,
+        question: str,
+        intent: str,
+        state: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Generate candidate workflows using LLM (exploration)."""
+        candidates = self.llm_explorer.generate_candidates(question, intent)
+        
+        if self._lemon:
+            self._lemon.counter("xavier.explorations")
+        
+        return [
+            {
+                "name": c.name,
+                "description": c.description,
+                "steps": c.steps,
+                "cost": c.estimated_cost,
+                "latency": c.estimated_latency_ms,
+            }
+            for c in candidates
+        ]
+    
+    # --- Simulation (evaluate without side effects) ---
+    
+    def simulate(
+        self,
+        pipeline_id: str,
+        capabilities: list[str],
+        state: dict[str, Any] | None = None,
+    ) -> SimulationResult:
+        """Simulate a pipeline execution (no side effects)."""
+        result = self.simulator.simulate(pipeline_id, capabilities, state)
+        
+        if self._lemon:
+            self._lemon.counter("xavier.simulations")
+        
+        return result
+    
+    # --- Selection (Policy evaluates) ---
+    
+    def select(
+        self,
+        candidates: list[dict[str, Any]],
+        state: Any = None,
+    ) -> dict[str, Any]:
+        """Select best candidate using Policy (exploitation)."""
+        from src.monkey_brain.kernel.pipeline import Pipeline, PipelineStep
+        
+        pipelines = []
+        for c in candidates:
+            steps = [
+                PipelineStep(capability_name=s.get("capability", "retrieve"))
+                for s in c.get("steps", [])
+            ]
+            pipelines.append(Pipeline(steps=steps, metadata=c))
+        
+        if not pipelines:
+            return candidates[0] if candidates else {}
+        
+        selected = self._policy.select(pipelines, state)
+        return selected.metadata
+    
+    # --- Evaluation (after execution) ---
+    
+    def evaluate(
+        self,
+        question: str,
+        intent: str,
+        pipeline_id: str,
+        capabilities: list[str],
+        answer: str,
+        success: bool,
+        latency_ms: float,
+        state: dict[str, Any] | None = None,
+        next_state: dict[str, Any] | None = None,
+        ground_truth: dict[str, Any] | None = None,
+        user_feedback: dict[str, Any] | None = None,
+    ) -> FeedbackRecord:
+        """Evaluate an execution and update learning."""
+        # Record feedback
+        record = self.feedback_engine.record(
+            question=question,
+            intent=intent,
+            pipeline_id=pipeline_id,
+            capabilities=capabilities,
+            answer=answer,
+            success=success,
+            latency_ms=latency_ms,
+            ground_truth=ground_truth,
+            user_feedback=user_feedback,
+        )
+        
+        # Compute reward
+        reward_result = self.reward_engine.compute(
+            success=success,
+            latency_ms=latency_ms,
+            user_feedback=user_feedback,
+            ground_truth=ground_truth,
+            answer=answer,
+            capabilities=capabilities,
+        )
+        record.reward = reward_result.total_reward
+        record.reward_components = reward_result.components
+        
+        # Compute loss
+        loss_result = self.loss_engine.compute(
+            success=success,
+            latency_ms=latency_ms,
+            ground_truth=ground_truth,
+            answer=answer,
+            intent=intent,
+            capabilities=capabilities,
+        )
+        record.loss = loss_result.total_loss
+        record.loss_components = loss_result.components
+        
+        # Compute cost
+        cost_result = self.cost_engine.estimate(latency_ms=latency_ms)
+        
+        # Update world model
+        self.world_model.update_pipeline(
+            pipeline_id,
+            success=success,
+            reward=reward_result.normalized,
+            cost=cost_result.total_cost,
+            latency_ms=latency_ms,
+        )
+        for cap in capabilities:
+            self.world_model.update_capability(cap, success, latency_ms, cost_result.total_cost / len(capabilities))
+        
+        # Update policy
+        if state and next_state:
+            transition = Transition(
+                state=state,
+                action=pipeline_id,
+                reward=reward_result.normalized,
+                next_state=next_state,
+                done=True,
+            )
+            self._policy.update(transition)
+        
+        # Store experience
+        experience = Experience(
+            state=state or {},
+            action=pipeline_id,
+            reward=reward_result.normalized,
+            loss=loss_result.total_loss,
+            next_state=next_state or {},
+            done=True,
+            metadata={
+                "cost": cost_result.total_cost,
+                "latency_ms": latency_ms,
+            },
+        )
+        self.experience_store.store(experience)
+        
+        # Emit telemetry
+        if self._lemon:
+            self._lemon.counter("xavier.executions_evaluated")
+            self._lemon.histogram("xavier.reward", reward_result.total_reward)
+            self._lemon.histogram("xavier.loss", loss_result.total_loss)
+            self._lemon.histogram("xavier.cost", cost_result.total_cost)
+        
+        return record
+    
+    # --- Summary ---
+    
+    def summary(self) -> dict:
+        return {
+            "world_model": self.world_model.summary(),
+            "feedback": self.feedback_engine.summary(),
+            "experience_store": self.experience_store.summary(),
+            "policy": self._policy.summary() if self._policy else None,
+            "llm_explorer": self.llm_explorer.summary(),
+        }

src/deepdive/__init__.py

@@ -0,0 +1,29 @@
+"""Aggregation Layer — cross-node analytics and knowledge.
+
+Persists everything in Elasticsearch.
+Provides full-text search, semantic search, analytics, and dashboards.
+
+Aggregation never performs cognition.
+Aggregation never controls execution.
+Aggregation never executes pipelines.
+"""
+
+from src.deepdive.aggregation import Aggregation
+from src.deepdive.elasticsearch_adapter import ElasticsearchAdapter
+from src.deepdive.fleet_analytics import FleetAnalytics, NodeMetrics, FleetMetrics
+from src.deepdive.knowledge_aggregator import KnowledgeAggregator, KnowledgeEntry, AggregatedKnowledge
+from src.deepdive.digital_twin_aggregator import DigitalTwinAggregator, TwinSnapshot, AggregatedTwin
+
+__all__ = [
+    "Aggregation",
+    "ElasticsearchAdapter",
+    "FleetAnalytics",
+    "NodeMetrics",
+    "FleetMetrics",
+    "KnowledgeAggregator",
+    "KnowledgeEntry",
+    "AggregatedKnowledge",
+    "DigitalTwinAggregator",
+    "TwinSnapshot",
+    "AggregatedTwin",
+]

src/deepdive/aggregation.py

@@ -0,0 +1,113 @@
+"""Aggregation Layer — cross-node analytics and knowledge.
+
+Persists everything in Elasticsearch.
+Provides full-text search, semantic search, analytics, and dashboards.
+
+Aggregation never performs cognition.
+Aggregation never controls execution.
+Aggregation never executes pipelines.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src.deepdive.elasticsearch_adapter import ElasticsearchAdapter
+from src.deepdive.fleet_analytics import FleetAnalytics, NodeMetrics, FleetMetrics
+from src.deepdive.knowledge_aggregator import KnowledgeAggregator, KnowledgeEntry, AggregatedKnowledge
+from src.deepdive.digital_twin_aggregator import DigitalTwinAggregator, TwinSnapshot, AggregatedTwin
+
+
+class Aggregation:
+    """Aggregation Layer for AgentOS.
+    
+    Responsibilities:
+    - Fleet analytics
+    - Knowledge aggregation
+    - Digital twin aggregation
+    - Long-term storage
+    - Enterprise dashboards
+    - Cross-site learning
+    
+    Aggregation never performs cognition.
+    Aggregation never controls execution.
+    Aggregation never executes pipelines.
+    """
+    
+    def __init__(self, elasticsearch_url: str = "http://localhost:9200"):
+        self.es = ElasticsearchAdapter(url=elasticsearch_url)
+        self.fleet = FleetAnalytics(elasticsearch_adapter=self.es)
+        self.knowledge = KnowledgeAggregator(elasticsearch_adapter=self.es)
+        self.twins = DigitalTwinAggregator(elasticsearch_adapter=self.es)
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        """Set the Lemon observability manager."""
+        self._lemon = lemon
+    
+    async def connect(self) -> None:
+        """Connect to Elasticsearch."""
+        await self.es.connect()
+        if self._lemon:
+            self._lemon.health_check("elasticsearch", "healthy" if self.es.is_connected() else "unhealthy")
+    
+    async def disconnect(self) -> None:
+        await self.es.disconnect()
+    
+    # --- Fleet Analytics ---
+    
+    def record_node_metrics(self, metrics: NodeMetrics) -> None:
+        self.fleet.record_node_metrics(metrics)
+        if self._lemon:
+            self._lemon.counter("aggregation.node_metrics", node=metrics.node_id)
+    
+    def aggregate_fleet(self, fleet_id: str = "default") -> FleetMetrics:
+        return self.fleet.aggregate_fleet(fleet_id)
+    
+    # --- Knowledge ---
+    
+    def add_knowledge(self, entry: KnowledgeEntry) -> None:
+        self.knowledge.add_entry(entry)
+        if self._lemon:
+            self._lemon.counter("aggregation.knowledge_entries", type=entry.knowledge_type)
+    
+    def aggregate_knowledge(self, knowledge_type: str) -> AggregatedKnowledge:
+        return self.knowledge.aggregate(knowledge_type)
+    
+    # --- Digital Twins ---
+    
+    def add_twin_snapshot(self, snapshot: TwinSnapshot) -> None:
+        self.twins.add_snapshot(snapshot)
+        if self._lemon:
+            self._lemon.counter("aggregation.twin_snapshots", entity=snapshot.entity_type)
+    
+    def get_aggregated_twin(self, entity_type: str, entity_id: str) -> AggregatedTwin | None:
+        return self.twins.get_aggregated(entity_type, entity_id)
+    
+    # --- Persistence ---
+    
+    async def persist_all(self) -> dict[str, Any]:
+        """Persist all aggregated data to Elasticsearch."""
+        results = {}
+        results["fleet"] = await self.fleet.persist_to_elasticsearch()
+        results["knowledge"] = await self.knowledge.persist_to_elasticsearch()
+        results["twins"] = await self.twins.persist_to_elasticsearch()
+        return results
+    
+    # --- Search ---
+    
+    async def search(self, index: str, query: dict[str, Any], size: int = 100) -> list[dict]:
+        return await self.es.search(index, query, size)
+    
+    async def aggregate_query(self, index: str, aggs: dict[str, Any]) -> dict[str, Any]:
+        return await self.es.aggregate(index, aggs)
+    
+    # --- Summary ---
+    
+    def summary(self) -> dict:
+        return {
+            "elasticsearch": {"connected": self.es.is_connected()},
+            "fleet": self.fleet.summary(),
+            "knowledge": self.knowledge.summary(),
+            "twins": self.twins.summary(),
+        }

src/deepdive/digital_twin_aggregator.py

@@ -0,0 +1,128 @@
+"""Digital Twin Aggregation — cross-node twin synchronization.
+
+Aggregates digital twin state across edge nodes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class TwinSnapshot:
+    """A snapshot of a digital twin from an edge node."""
+    
+    snapshot_id: str = field(default_factory=lambda: f"twin-{uuid4().hex[:12]}")
+    node_id: str = ""
+    entity_type: str = ""
+    entity_id: str = ""
+    state: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AggregatedTwin:
+    """Aggregated digital twin state across nodes."""
+    
+    entity_type: str = ""
+    entity_id: str = ""
+    latest_state: dict[str, Any] = field(default_factory=dict)
+    contributing_nodes: list[str] = field(default_factory=list)
+    snapshot_count: int = 0
+    last_updated: str = ""
+
+
+class DigitalTwinAggregator:
+    """Aggregates digital twin state across edge nodes.
+    
+    Responsibilities:
+    - Collect twin snapshots from nodes
+    - Merge twin states
+    - Track twin versions
+    - Support twin sync
+    
+    Aggregation never performs cognition.
+    Aggregation never controls execution.
+    """
+    
+    def __init__(self, elasticsearch_adapter: Any = None):
+        self._es = elasticsearch_adapter
+        self._snapshots: dict[str, list[TwinSnapshot]] = {}
+        self._aggregated: dict[str, AggregatedTwin] = {}
+    
+    def add_snapshot(self, snapshot: TwinSnapshot) -> None:
+        """Add a twin snapshot from a node."""
+        key = f"{snapshot.entity_type}:{snapshot.entity_id}"
+        if key not in self._snapshots:
+            self._snapshots[key] = []
+        self._snapshots[key].append(snapshot)
+        
+        if len(self._snapshots[key]) > 100:
+            self._snapshots[key] = self._snapshots[key][-50:]
+        
+        self._update_aggregated(key)
+    
+    def _update_aggregated(self, key: str) -> None:
+        """Update aggregated twin state."""
+        snapshots = self._snapshots.get(key, [])
+        if not snapshots:
+            return
+        
+        latest = snapshots[-1]
+        nodes = list(set(s.node_id for s in snapshots))
+        
+        self._aggregated[key] = AggregatedTwin(
+            entity_type=latest.entity_type,
+            entity_id=latest.entity_id,
+            latest_state=latest.state,
+            contributing_nodes=nodes,
+            snapshot_count=len(snapshots),
+            last_updated=latest.timestamp,
+        )
+    
+    def get_aggregated(self, entity_type: str, entity_id: str) -> AggregatedTwin | None:
+        key = f"{entity_type}:{entity_id}"
+        return self._aggregated.get(key)
+    
+    def get_all_aggregated(self, entity_type: str | None = None) -> list[AggregatedTwin]:
+        if entity_type:
+            return [t for t in self._aggregated.values() if t.entity_type == entity_type]
+        return list(self._aggregated.values())
+    
+    def get_history(self, entity_type: str, entity_id: str, limit: int = 100) -> list[TwinSnapshot]:
+        key = f"{entity_type}:{entity_id}"
+        return self._snapshots.get(key, [])[-limit:]
+    
+    async def persist_to_elasticsearch(self) -> dict[str, Any]:
+        """Persist aggregated twins to Elasticsearch."""
+        if not self._es:
+            return {"status": "no_elasticsearch"}
+        
+        for key, twin in self._aggregated.items():
+            from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+            event = PersistenceEvent(
+                event_type=EventType.ENTITY_UPDATED,
+                entity_type="digital_twin",
+                entity_id=f"{twin.entity_type}:{twin.entity_id}",
+                data={
+                    "entity_type": twin.entity_type,
+                    "entity_id": twin.entity_id,
+                    "latest_state": twin.latest_state,
+                    "contributing_nodes": twin.contributing_nodes,
+                    "snapshot_count": twin.snapshot_count,
+                },
+            )
+            await self._es.persist(event)
+        
+        return {"status": "persisted", "twins": len(self._aggregated)}
+    
+    def summary(self) -> dict:
+        types = set(t.entity_type for t in self._aggregated.values())
+        return {
+            "total_twins": len(self._aggregated),
+            "entity_types": list(types),
+        }