monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/runtime/runtime.py

@@ -0,0 +1,199 @@
+"""Runtime — executes capability pipelines.
+
+The Runtime is the Wolverine execution engine.
+It executes pipelines exactly as an OS executes machine instructions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from src.monkey_brain.kernel.capability_interface import ICapability
+from src.monkey_brain.kernel.pipeline import Pipeline
+from src.monkey_brain.kernel.execution_state import ExecutionState
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+
+
+class Runtime:
+    """Capability execution runtime (Wolverine).
+    
+    Responsibilities:
+    - Execute capability pipelines
+    - Manage execution lifecycle
+    - Emit persistence events
+    - Report metrics
+    
+    The Runtime never:
+    - Plans pipelines
+    - Selects capabilities
+    - Performs learning
+    - Owns execution policy
+    """
+    
+    def __init__(self, thread_pool_size: int = 4):
+        self._capabilities: dict[str, ICapability] = {}
+        self._execution_count = 0
+        self._persistence_manager = None
+        self._lemon = None
+    
+    def set_persistence_manager(self, manager) -> None:
+        self._persistence_manager = manager
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def register(self, capability: ICapability) -> None:
+        self._capabilities[capability.name] = capability
+    
+    def register_many(self, capabilities: list[ICapability]) -> None:
+        for cap in capabilities:
+            self.register(cap)
+    
+    def get_capability(self, name: str) -> ICapability | None:
+        return self._capabilities.get(name)
+    
+    def has_capability(self, name: str) -> bool:
+        return name in self._capabilities
+    
+    async def execute(
+        self,
+        pipeline: Pipeline,
+        state: ExecutionState | None = None,
+    ) -> ExecutionResult:
+        """Execute a capability pipeline."""
+        start_time = time.monotonic()
+        self._execution_count += 1
+        
+        # Start trace
+        if self._lemon:
+            self._lemon.start_trace(f"runtime:{pipeline.pipeline_id}")
+            self._lemon.counter("runtime.executions")
+        
+        state_dict = state.to_dict() if state else {}
+        step_results = []
+        current_state = dict(state_dict)
+        
+        for step in pipeline.steps:
+            capability = self._capabilities.get(step.capability_name)
+            
+            if capability is None:
+                result = StepResult(
+                    step_id=step.step_id,
+                    capability_name=step.capability_name,
+                    success=False,
+                    output={},
+                    error=f"Capability '{step.capability_name}' not found",
+                )
+                step_results.append(result)
+                if self._lemon:
+                    self._lemon.counter("runtime.capability_not_found")
+                continue
+            
+            # Start span
+            if self._lemon:
+                self._lemon.start_span(f"capability:{step.capability_name}", component="runtime")
+            
+            # Execute step
+            step_start = time.monotonic()
+            try:
+                output = await capability.execute(current_state)
+                latency_ms = (time.monotonic() - step_start) * 1000
+                
+                result = StepResult(
+                    step_id=step.step_id,
+                    capability_name=step.capability_name,
+                    success=True,
+                    output=output,
+                    latency_ms=latency_ms,
+                )
+                
+                current_state.update(output)
+                
+                if self._lemon:
+                    self._lemon.finish_span("ok")
+                    self._lemon.counter("runtime.steps_succeeded")
+                    self._lemon.histogram("runtime.step_latency_ms", latency_ms, capability=step.capability_name)
+                
+            except Exception as e:
+                latency_ms = (time.monotonic() - step_start) * 1000
+                result = StepResult(
+                    step_id=step.step_id,
+                    capability_name=step.capability_name,
+                    success=False,
+                    output={},
+                    latency_ms=latency_ms,
+                    error=str(e),
+                )
+                
+                if self._lemon:
+                    self._lemon.finish_span("error")
+                    self._lemon.counter("runtime.steps_failed")
+            
+            step_results.append(result)
+            
+            if not result.success:
+                break
+        
+        total_latency = (time.monotonic() - start_time) * 1000
+        success = all(r.success for r in step_results) if step_results else False
+        
+        execution_result = ExecutionResult(
+            pipeline_id=pipeline.pipeline_id,
+            success=success,
+            steps=step_results,
+            final_state=current_state,
+            total_latency_ms=total_latency,
+        )
+        
+        # Emit persistence event
+        if self._persistence_manager:
+            event = PersistenceEvent(
+                event_type=EventType.PIPELINE_EXECUTED,
+                entity_type="execution",
+                entity_id=pipeline.pipeline_id,
+                data={"success": success, "latency_ms": total_latency, "steps": len(step_results)},
+            )
+            await self._persistence_manager.persist(event)
+        
+        # Finish trace
+        if self._lemon:
+            self._lemon.finish_trace()
+            self._lemon.histogram("runtime.pipeline_latency_ms", total_latency)
+        
+        return execution_result
+    
+    def summary(self) -> dict:
+        return {
+            "capabilities": list(self._capabilities.keys()),
+            "executions": self._execution_count,
+            "persistence_enabled": self._persistence_manager is not None,
+            "lemon_enabled": self._lemon is not None,
+        }
+
+
+# Re-export result types for convenience
+from dataclasses import dataclass, field
+
+
+@dataclass
+class StepResult:
+    step_id: str = ""
+    capability_name: str = ""
+    success: bool = True
+    output: dict[str, Any] = field(default_factory=dict)
+    latency_ms: float = 0.0
+    error: str | None = None
+
+
+@dataclass
+class ExecutionResult:
+    pipeline_id: str = ""
+    success: bool = True
+    steps: list[StepResult] = field(default_factory=list)
+    final_state: dict[str, Any] = field(default_factory=dict)
+    total_latency_ms: float = 0.0
+    
+    def step_count(self) -> int:
+        return len(self.steps)

src/monkey_brain/runtime/scheduler.py

@@ -0,0 +1,165 @@
+"""Scheduler — production scheduler with work stealing.
+
+Supports:
+- Ready Queue
+- Waiting Queue
+- Blocked Queue
+- Completed Queue
+- Failed Queue
+- Work Stealing
+- Configurable policies
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import time
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.runtime.process import Process, ProcessState, ProcessPriority
+
+
+class SchedulerPolicy(str, Enum):
+    FIFO = "fifo"
+    PRIORITY = "priority"
+    ROUND_ROBIN = "round_robin"
+    WORK_STEALING = "work_stealing"
+
+
+class Scheduler:
+    """Production scheduler for process execution.
+    
+    Supports:
+    - Multiple queues (ready, waiting, blocked, completed, failed)
+    - Configurable scheduling policies
+    - Work stealing between workers
+    - Process lifecycle management
+    """
+    
+    def __init__(self, policy: str = "priority"):
+        self._ready: collections.deque[str] = collections.deque()
+        self._waiting: dict[str, Process] = {}
+        self._blocked: dict[str, Process] = {}
+        self._completed: dict[str, Process] = {}
+        self._failed: dict[str, Process] = {}
+        self._all_processes: dict[str, Process] = {}
+        self._policy = policy
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def submit(self, process: Process) -> None:
+        """Submit a process to the scheduler."""
+        process.state = ProcessState.QUEUED
+        self._all_processes[process.process_id] = process
+        self._ready.append(process.process_id)
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_submitted")
+            self._lemon.gauge("wolverine.queue_length", len(self._ready))
+    
+    def schedule(self) -> Process | None:
+        """Schedule the next process to run."""
+        if not self._ready:
+            return None
+        
+        if self._policy == "priority":
+            return self._schedule_priority()
+        else:
+            return self._schedule_fifo()
+    
+    def _schedule_fifo(self) -> Process | None:
+        """FIFO scheduling."""
+        process_id = self._ready.popleft()
+        process = self._all_processes.get(process_id)
+        if process:
+            process.state = ProcessState.SCHEDULED
+            if self._lemon:
+                self._lemon.counter("wolverine.processes_scheduled")
+        return process
+    
+    def _schedule_priority(self) -> Process | None:
+        """Priority scheduling."""
+        if not self._ready:
+            return None
+        
+        # Sort ready processes by priority
+        ready_processes = []
+        for pid in self._ready:
+            p = self._all_processes.get(pid)
+            if p:
+                ready_processes.append((p.priority.value, p))
+        
+        ready_processes.sort(key=lambda x: x[0], reverse=True)
+        
+        if ready_processes:
+            _, process = ready_processes[0]
+            self._ready.remove(process.process_id)
+            process.state = ProcessState.SCHEDULED
+            if self._lemon:
+                self._lemon.counter("wolverine.processes_scheduled")
+            return process
+        
+        return None
+    
+    def complete(self, process: Process) -> None:
+        """Mark a process as completed."""
+        process.state = ProcessState.COMPLETED
+        process.completed_at = time.time()
+        self._completed[process.process_id] = process
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_completed")
+            self._lemon.histogram("wolverine.process_latency_ms", process.elapsed_ms)
+    
+    def fail(self, process: Process, error: str) -> None:
+        """Mark a process as failed."""
+        process.state = ProcessState.FAILED
+        process.error = error
+        process.completed_at = time.time()
+        self._failed[process.process_id] = process
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_failed")
+            self._lemon.error(f"Process {process.process_id} failed: {error}", component="scheduler")
+    
+    def block(self, process: Process) -> None:
+        """Block a process (waiting for I/O)."""
+        process.state = ProcessState.WAITING
+        self._blocked[process.process_id] = process
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_blocked")
+    
+    def unblock(self, process: Process) -> None:
+        """Unblock a process and move it to ready queue."""
+        process.state = ProcessState.QUEUED
+        self._blocked.pop(process.process_id, None)
+        self._ready.append(process.process_id)
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_unblocked")
+    
+    def get_process(self, process_id: str) -> Process | None:
+        return self._all_processes.get(process_id)
+    
+    def get_queue_lengths(self) -> dict[str, int]:
+        return {
+            "ready": len(self._ready),
+            "waiting": len(self._waiting),
+            "blocked": len(self._blocked),
+            "completed": len(self._completed),
+            "failed": len(self._failed),
+        }
+    
+    def summary(self) -> dict:
+        return {
+            "policy": self._policy,
+            "total_processes": len(self._all_processes),
+            "queues": self.get_queue_lengths(),
+        }

src/monkey_brain/runtime/supervisor.py

@@ -0,0 +1,133 @@
+"""Supervisor — process supervision trees.
+
+Responsibilities:
+- Restart failed processes
+- Backoff strategies
+- Escalation
+- Health monitoring
+- Shutdown
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+from uuid import uuid4
+
+from src.monkey_brain.runtime.process import Process, ProcessState
+
+
+class RestartStrategy(str, Enum):
+    ONE_FOR_ONE = "one_for_one"
+    ONE_FOR_ALL = "one_for_all"
+    REST_FOR_ONE = "rest_for_one"
+
+
+class SupervisorState(str, Enum):
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+
+
+@dataclass
+class SupervisorConfig:
+    """Configuration for a supervisor."""
+    
+    max_restarts: int = 3
+    restart_period: float = 60.0  # seconds
+    backoff_factor: float = 2.0
+    max_backoff: float = 30.0
+    restart_strategy: RestartStrategy = RestartStrategy.ONE_FOR_ONE
+
+
+class Supervisor:
+    """Supervises child processes.
+    
+    Responsibilities:
+    - Restart failed processes
+    - Backoff strategies
+    - Escalation
+    - Health monitoring
+    """
+    
+    def __init__(self, supervisor_id: str | None = None, config: SupervisorConfig | None = None):
+        self.supervisor_id = supervisor_id or f"sup-{uuid4().hex[:8]}"
+        self._config = config or SupervisorConfig()
+        self._children: dict[str, Process] = {}
+        self._restart_counts: dict[str, int] = {}
+        self._restart_times: dict[str, list[float]] = {}
+        self._state = SupervisorState.RUNNING
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def add_child(self, process: Process) -> None:
+        """Add a child process to supervision."""
+        self._children[process.process_id] = process
+        self._restart_counts[process.process_id] = 0
+        self._restart_times[process.process_id] = []
+    
+    def remove_child(self, process_id: str) -> None:
+        """Remove a child from supervision."""
+        self._children.pop(process_id, None)
+        self._restart_counts.pop(process_id, None)
+        self._restart_times.pop(process_id, None)
+    
+    def handle_failure(self, process: Process, error: str) -> bool:
+        """Handle a child process failure.
+        
+        Returns True if restart was attempted, False if escalation needed.
+        """
+        process_id = process.process_id
+        restarts = self._restart_counts.get(process_id, 0)
+        
+        # Check restart limit
+        if restarts >= self._config.max_restarts:
+            if self._lemon:
+                self._lemon.counter("wolverine.supervisor_escalation")
+            return False
+        
+        # Check restart period
+        now = time.time()
+        restart_times = self._restart_times.get(process_id, [])
+        recent_restarts = [t for t in restart_times if now - t < self._config.restart_period]
+        
+        if len(recent_restarts) >= self._config.max_restarts:
+            if self._lemon:
+                self._lemon.counter("wolverine.supervisor_escalation")
+            return False
+        
+        # Calculate backoff
+        backoff = min(
+            self._config.backoff_factor ** restarts,
+            self._config.max_backoff,
+        )
+        
+        # Record restart
+        self._restart_counts[process_id] = restarts + 1
+        self._restart_times[process_id].append(now)
+        
+        # Reset process
+        process.state = ProcessState.CREATED
+        process.error = None
+        process.result = None
+        process.metrics.retries += 1
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_restarted")
+        
+        return True
+    
+    def get_children(self) -> list[Process]:
+        return list(self._children.values())
+    
+    def summary(self) -> dict:
+        return {
+            "supervisor_id": self.supervisor_id,
+            "state": self._state.value,
+            "children": len(self._children),
+            "restarts": dict(self._restart_counts),
+        }

src/monkey_brain/runtime/worker_pool.py

@@ -0,0 +1,111 @@
+"""Worker Pool — manages worker threads for process execution.
+
+Supports:
+- Work stealing
+- Thread reuse
+- Resource limits
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.runtime.process import Process, ProcessState
+
+
+@dataclass
+class Worker:
+    """A worker thread."""
+    
+    worker_id: str = field(default_factory=lambda: f"worker-{uuid4().hex[:8]}")
+    current_process: Process | None = None
+    busy: bool = False
+    tasks_completed: int = 0
+    total_cpu_time_ms: float = 0.0
+    
+    @property
+    def utilization(self) -> float:
+        if self.total_cpu_time_ms == 0:
+            return 0.0
+        return 1.0 if self.busy else 0.0
+
+
+class WorkerPool:
+    """Manages worker threads for process execution.
+    
+    Supports:
+    - Work stealing between idle workers
+    - Thread reuse
+    - Resource limits
+    """
+    
+    def __init__(self, size: int = 4):
+        self._size = size
+        self._workers: dict[str, Worker] = {}
+        self._idle_workers: list[str] = []
+        self._lemon = None
+        
+        # Initialize workers
+        for _ in range(size):
+            worker = Worker()
+            self._workers[worker.worker_id] = worker
+            self._idle_workers.append(worker.worker_id)
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def acquire_worker(self) -> Worker | None:
+        """Acquire an idle worker."""
+        if self._idle_workers:
+            worker_id = self._idle_workers.pop(0)
+            worker = self._workers[worker_id]
+            worker.busy = True
+            if self._lemon:
+                self._lemon.counter("wolverine.workers_acquired")
+            return worker
+        return None
+    
+    def release_worker(self, worker: Worker) -> None:
+        """Release a worker back to the idle pool."""
+        worker.busy = False
+        worker.current_process = None
+        self._idle_workers.append(worker.worker_id)
+        if self._lemon:
+            self._lemon.counter("wolverine.workers_released")
+    
+    def steal_work(self) -> tuple[Worker, Process] | None:
+        """Steal work from a busy worker."""
+        # Find a busy worker with work
+        for worker in self._workers.values():
+            if worker.busy and worker.current_process:
+                # Steal the process
+                process = worker.current_process
+                worker.current_process = None
+                worker.busy = False
+                self._idle_workers.append(worker.worker_id)
+                
+                if self._lemon:
+                    self._lemon.counter("wolverine.work_stolen")
+                
+                return worker, process
+        
+        return None
+    
+    def get_worker(self, worker_id: str) -> Worker | None:
+        return self._workers.get(worker_id)
+    
+    def get_all_workers(self) -> list[Worker]:
+        return list(self._workers.values())
+    
+    def summary(self) -> dict:
+        busy = sum(1 for w in self._workers.values() if w.busy)
+        return {
+            "size": self._size,
+            "idle": len(self._idle_workers),
+            "busy": busy,
+            "utilization": round(busy / self._size, 2) if self._size else 0,
+        }

src/plasticity/seed/__init__.py

@@ -0,0 +1,30 @@
+"""Seed — deterministic data seeding framework.
+
+Generates complete grounded datasets for:
+- Benchmarking
+- Development
+- Testing
+- Demonstrations
+- Regression validation
+
+All data generated from existing domain models.
+No direct database manipulation.
+"""
+
+from src.plasticity.seed.seeder import Seeder
+from src.plasticity.seed.seed_data import SeedConfig, SeedGenerator
+from src.plasticity.seed.scenario_builder import ScenarioBuilder, Scenario
+from src.plasticity.seed.event_generator import EventGenerator, Event
+from src.plasticity.seed.benchmark_generator import BenchmarkGenerator, BenchmarkEntry
+
+__all__ = [
+    "Seeder",
+    "SeedConfig",
+    "SeedGenerator",
+    "ScenarioBuilder",
+    "Scenario",
+    "EventGenerator",
+    "Event",
+    "BenchmarkGenerator",
+    "BenchmarkEntry",
+]