monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/persistence/reducer.py

@@ -0,0 +1,111 @@
+"""Reducer — pure state mutation.
+
+Reducers receive:
+  Current Runtime State * Execution Event
+  ↓
+  Updated Runtime State
+  ↓
+  Persistence Commands
+
+Reducers remain pure.
+Reducers never perform I/O.
+Reducers emit persistence operations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+
+
+@dataclass
+class StateMutation:
+    """A state mutation with persistence commands."""
+    
+    state_updates: dict[str, Any] = field(default_factory=dict)
+    persistence_events: list[PersistenceEvent] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Reducer:
+    """Pure state reducer.
+    
+    Responsibilities:
+    - Transform state based on events
+    - Emit persistence operations
+    - Never perform I/O
+    """
+    
+    def __init__(self):
+        self._reducers: dict[str, Callable] = {}
+    
+    def register(self, event_type: str, reducer_fn: Callable) -> None:
+        """Register a reducer for an event type."""
+        self._reducers[event_type] = reducer_fn
+    
+    def reduce(self, state: dict[str, Any], event: dict[str, Any]) -> StateMutation:
+        """Apply reducer to state and event."""
+        event_type = event.get("type", "unknown")
+        
+        reducer_fn = self._reducers.get(event_type)
+        if reducer_fn:
+            return reducer_fn(state, event)
+        
+        return StateMutation()
+    
+    def entity_created(
+        self,
+        entity_type: str,
+        entity_id: str,
+        data: dict[str, Any],
+    ) -> StateMutation:
+        """Emit entity created mutation."""
+        return StateMutation(
+            state_updates={entity_type: {entity_id: data}},
+            persistence_events=[
+                PersistenceEvent(
+                    event_type=EventType.ENTITY_CREATED,
+                    entity_type=entity_type,
+                    entity_id=entity_id,
+                    data=data,
+                )
+            ],
+        )
+    
+    def entity_updated(
+        self,
+        entity_type: str,
+        entity_id: str,
+        data: dict[str, Any],
+    ) -> StateMutation:
+        """Emit entity updated mutation."""
+        return StateMutation(
+            state_updates={entity_type: {entity_id: data}},
+            persistence_events=[
+                PersistenceEvent(
+                    event_type=EventType.ENTITY_UPDATED,
+                    entity_type=entity_type,
+                    entity_id=entity_id,
+                    data=data,
+                )
+            ],
+        )
+    
+    def entity_deleted(
+        self,
+        entity_type: str,
+        entity_id: str,
+    ) -> StateMutation:
+        """Emit entity deleted mutation."""
+        return StateMutation(
+            state_updates={entity_type: {entity_id: None}},
+            persistence_events=[
+                PersistenceEvent(
+                    event_type=EventType.ENTITY_DELETED,
+                    entity_type=entity_type,
+                    entity_id=entity_id,
+                )
+            ],
+        )

src/monkey_brain/runtime/__init__.py

@@ -0,0 +1,49 @@
+"""MonkeyBrain Runtime (Wolverine).
+
+The Runtime executes pipelines.
+
+Responsibilities:
+- Pipeline Execution
+- Process Management
+- Thread Pool
+- Memory
+- Streaming
+- Scheduling
+- Supervision
+- Resource Management
+
+The Runtime never performs planning.
+The Runtime never performs learning.
+The Runtime never owns execution policy.
+"""
+
+from src.monkey_brain.runtime.runtime import Runtime, StepResult, ExecutionResult
+from src.monkey_brain.runtime.engine import Engine, EngineConfig
+from src.monkey_brain.runtime.process import Process, ProcessState, ProcessPriority, Message
+from src.monkey_brain.runtime.scheduler import Scheduler, SchedulerPolicy
+from src.monkey_brain.runtime.worker_pool import WorkerPool, Worker
+from src.monkey_brain.runtime.message_bus import MessageBus
+from src.monkey_brain.runtime.supervisor import Supervisor, SupervisorConfig, RestartStrategy
+from src.monkey_brain.runtime.resource_manager import ResourceManager, ResourceLimits
+
+__all__ = [
+    "Runtime",
+    "StepResult",
+    "ExecutionResult",
+    "Engine",
+    "EngineConfig",
+    "Process",
+    "ProcessState",
+    "ProcessPriority",
+    "Message",
+    "Scheduler",
+    "SchedulerPolicy",
+    "WorkerPool",
+    "Worker",
+    "MessageBus",
+    "Supervisor",
+    "SupervisorConfig",
+    "RestartStrategy",
+    "ResourceManager",
+    "ResourceLimits",
+]

src/monkey_brain/runtime/depedencies.py

@@ -0,0 +1,8 @@
+"""Runtime dependencies."""
+
+from fastapi import Request
+
+
+def get_runtime(request: Request):
+    """Get runtime from app state."""
+    return request.app.state.runtime

src/monkey_brain/runtime/engine.py

@@ -0,0 +1,183 @@
+"""Engine — the Wolverine Process Execution Engine.
+
+The engine orchestrates all process execution.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine
+from uuid import uuid4
+
+from src.monkey_brain.runtime.process import Process, ProcessState, ProcessPriority
+from src.monkey_brain.runtime.scheduler import Scheduler
+from src.monkey_brain.runtime.worker_pool import WorkerPool
+from src.monkey_brain.runtime.message_bus import MessageBus
+from src.monkey_brain.runtime.supervisor import Supervisor, SupervisorConfig
+from src.monkey_brain.runtime.resource_manager import ResourceManager, ResourceLimits
+
+
+@dataclass
+class EngineConfig:
+    """Configuration for the execution engine."""
+    
+    worker_pool_size: int = 4
+    scheduler_policy: str = "priority"
+    max_processes: int = 1000
+    enable_work_stealing: bool = True
+    enable_supervision: bool = True
+
+
+class Engine:
+    """Wolverine Process Execution Engine.
+    
+    Orchestrates all process execution.
+    """
+    
+    def __init__(self, config: EngineConfig | None = None):
+        self._config = config or EngineConfig()
+        self._scheduler = Scheduler(policy=self._config.scheduler_policy)
+        self._worker_pool = WorkerPool(size=self._config.worker_pool_size)
+        self._message_bus = MessageBus()
+        self._supervisor = Supervisor()
+        self._resource_manager = ResourceManager()
+        self._processes: dict[str, Process] = {}
+        self._running = False
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+        self._scheduler.set_lemon(lemon)
+        self._worker_pool.set_lemon(lemon)
+        self._message_bus.set_lemon(lemon)
+        self._supervisor.set_lemon(lemon)
+    
+    async def submit(
+        self,
+        name: str,
+        coroutine: Coroutine,
+        args: tuple = (),
+        kwargs: dict[str, Any] | None = None,
+        priority: ProcessPriority = ProcessPriority.NORMAL,
+        parent_id: str | None = None,
+    ) -> Process:
+        """Submit a new process for execution."""
+        process = Process(
+            name=name,
+            coroutine=coroutine,
+            args=args,
+            kwargs=kwargs or {},
+            priority=priority,
+            parent_id=parent_id,
+        )
+        
+        self._processes[process.process_id] = process
+        self._scheduler.submit(process)
+        
+        if self._config.enable_supervision:
+            self._supervisor.add_child(process)
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.processes_created")
+        
+        return process
+    
+    async def execute_process(self, process: Process) -> Any:
+        """Execute a single process."""
+        process.state = ProcessState.RUNNING
+        process.started_at = time.time()
+        
+        worker = self._worker_pool.acquire_worker()
+        if worker:
+            worker.current_process = process
+        
+        try:
+            if asyncio.iscoroutinefunction(process.coroutine):
+                result = await process.coroutine(*process.args, **process.kwargs)
+            else:
+                result = process.coroutine(*process.args, **process.kwargs)
+            
+            process.result = result
+            process.state = ProcessState.COMPLETED
+            process.completed_at = time.time()
+            process.metrics.cpu_time_ms = process.elapsed_ms
+            
+            self._scheduler.complete(process)
+            
+            if worker:
+                self._worker_pool.release_worker(worker)
+            
+            if self._lemon:
+                self._lemon.counter("wolverine.processes_completed")
+            
+            return result
+            
+        except Exception as e:
+            process.state = ProcessState.FAILED
+            process.error = str(e)
+            process.completed_at = time.time()
+            
+            self._scheduler.fail(process, str(e))
+            
+            if worker:
+                self._worker_pool.release_worker(worker)
+            
+            # Handle failure with supervisor
+            if self._config.enable_supervision:
+                should_restart = self._supervisor.handle_failure(process, str(e))
+                if should_restart:
+                    self._scheduler.submit(process)
+            
+            if self._lemon:
+                self._lemon.counter("wolverine.processes_failed")
+            
+            raise
+    
+    async def execute_pipeline(
+        self,
+        steps: list[dict[str, Any]],
+        state: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Execute a pipeline of steps as processes."""
+        current_state = dict(state or {})
+        results = []
+        
+        for step in steps:
+            step_name = step.get("name", "step")
+            capability = step.get("capability")
+            
+            if capability:
+                process = await self.submit(
+                    name=step_name,
+                    coroutine=capability.execute,
+                    args=(current_state,),
+                )
+                
+                result = await self.execute_process(process)
+                current_state.update(result)
+                results.append({"step": step_name, "result": result})
+        
+        return {"state": current_state, "results": results}
+    
+    def get_process(self, process_id: str) -> Process | None:
+        return self._processes.get(process_id)
+    
+    def get_all_processes(self) -> list[Process]:
+        return list(self._processes.values())
+    
+    def summary(self) -> dict:
+        return {
+            "config": {
+                "worker_pool_size": self._config.worker_pool_size,
+                "scheduler_policy": self._config.scheduler_policy,
+                "max_processes": self._config.max_processes,
+            },
+            "scheduler": self._scheduler.summary(),
+            "worker_pool": self._worker_pool.summary(),
+            "message_bus": self._message_bus.summary(),
+            "supervisor": self._supervisor.summary(),
+            "resource_manager": self._resource_manager.summary(),
+            "total_processes": len(self._processes),
+        }

src/monkey_brain/runtime/message_bus.py

@@ -0,0 +1,82 @@
+"""Message Bus — inter-process communication.
+
+Supports:
+- Request/Response
+- Event broadcasting
+- Notification
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Callable
+from uuid import uuid4
+
+from src.monkey_brain.runtime.process import Message
+
+
+class MessageBus:
+    """Inter-process message bus.
+    
+    Supports:
+    - Request/Response
+    - Event broadcasting
+    - Notification
+    - Message history
+    """
+    
+    def __init__(self):
+        self._subscribers: dict[str, list[Callable]] = defaultdict(list)
+        self._history: list[Message] = []
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def publish(self, message: Message) -> None:
+        """Publish a message to subscribers."""
+        self._history.append(message)
+        
+        if len(self._history) > 10000:
+            self._history = self._history[-5000:]
+        
+        # Notify subscribers
+        for callback in self._subscribers.get(message.message_type, []):
+            try:
+                result = callback(message)
+                if asyncio.iscoroutine(result):
+                    asyncio.create_task(result)
+            except Exception:
+                pass
+        
+        if self._lemon:
+            self._lemon.counter("wolverine.messages_published", type=message.message_type)
+    
+    def subscribe(self, message_type: str, callback: Callable) -> None:
+        """Subscribe to a message type."""
+        self._subscribers[message_type].append(callback)
+    
+    def unsubscribe(self, message_type: str, callback: Callable) -> bool:
+        """Unsubscribe from a message type."""
+        if message_type in self._subscribers:
+            try:
+                self._subscribers[message_type].remove(callback)
+                return True
+            except ValueError:
+                pass
+        return False
+    
+    def get_history(self, message_type: str | None = None, limit: int = 100) -> list[Message]:
+        """Get message history."""
+        if message_type:
+            return [m for m in self._history if m.message_type == message_type][-limit:]
+        return self._history[-limit:]
+    
+    def summary(self) -> dict:
+        return {
+            "total_messages": len(self._history),
+            "subscribers": {k: len(v) for k, v in self._subscribers.items()},
+        }

src/monkey_brain/runtime/process.py

@@ -0,0 +1,144 @@
+"""Process — lightweight execution unit.
+
+Every execution is a Process.
+Processes communicate through messages.
+Processes never directly manipulate another process's memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Coroutine
+from uuid import uuid4
+
+
+class ProcessState(str, Enum):
+    CREATED = "created"
+    QUEUED = "queued"
+    SCHEDULED = "scheduled"
+    RUNNING = "running"
+    WAITING = "waiting"
+    RESUMED = "resumed"
+    COMPLETED = "completed"
+    OBSERVED = "observed"
+    DESTROYED = "destroyed"
+    FAILED = "failed"
+
+
+class ProcessPriority(int, Enum):
+    LOW = 0
+    NORMAL = 1
+    HIGH = 2
+    CRITICAL = 3
+
+
+@dataclass
+class Message:
+    """A message between processes."""
+    
+    message_id: str = field(default_factory=lambda: f"msg-{uuid4().hex[:8]}")
+    sender: str = ""
+    receiver: str = ""
+    message_type: str = "request"  # request | response | event | broadcast | notification
+    payload: Any = None
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class ProcessMetrics:
+    """Metrics for a process."""
+    
+    cpu_time_ms: float = 0.0
+    memory_bytes: int = 0
+    context_switches: int = 0
+    messages_sent: int = 0
+    messages_received: int = 0
+    retries: int = 0
+
+
+@dataclass
+class Process:
+    """A lightweight execution process.
+    
+    Every execution is a Process.
+    Processes communicate through messages.
+    """
+    
+    process_id: str = field(default_factory=lambda: f"proc-{uuid4().hex[:8]}")
+    name: str = ""
+    parent_id: str | None = None
+    
+    # State
+    state: ProcessState = ProcessState.CREATED
+    priority: ProcessPriority = ProcessPriority.NORMAL
+    
+    # Execution
+    coroutine: Any = None
+    args: tuple = ()
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    result: Any = None
+    error: str | None = None
+    
+    # Context
+    execution_context: dict[str, Any] = field(default_factory=dict)
+    
+    # Mailbox
+    mailbox: list[Message] = field(default_factory=list)
+    mailbox_max_size: int = 100
+    
+    # Metrics
+    metrics: ProcessMetrics = field(default_factory=ProcessMetrics)
+    
+    # Timing
+    created_at: float = field(default_factory=time.time)
+    started_at: float | None = None
+    completed_at: float | None = None
+    
+    # Tracing
+    trace_id: str | None = None
+    
+    # Metadata
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def elapsed_ms(self) -> float:
+        if self.started_at is None:
+            return 0.0
+        end = self.completed_at or time.time()
+        return (end - self.started_at) * 1000
+    
+    @property
+    def is_terminal(self) -> bool:
+        return self.state in (ProcessState.COMPLETED, ProcessState.FAILED, ProcessState.DESTROYED)
+    
+    def send(self, message: Message) -> bool:
+        """Send a message to this process's mailbox."""
+        if len(self.mailbox) >= self.mailbox_max_size:
+            return False
+        self.mailbox.append(message)
+        self.metrics.messages_received += 1
+        return True
+    
+    def receive(self) -> Message | None:
+        """Receive a message from the mailbox."""
+        if self.mailbox:
+            return self.mailbox.pop(0)
+        return None
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "process_id": self.process_id,
+            "name": self.name,
+            "parent_id": self.parent_id,
+            "state": self.state.value,
+            "priority": self.priority.value,
+            "elapsed_ms": round(self.elapsed_ms, 2),
+            "cpu_time_ms": round(self.metrics.cpu_time_ms, 2),
+            "messages_sent": self.metrics.messages_sent,
+            "messages_received": self.metrics.messages_received,
+            "retries": self.metrics.retries,
+            "error": self.error,
+        }

src/monkey_brain/runtime/resource_manager.py

@@ -0,0 +1,100 @@
+"""Resource Manager — tracks and limits resource usage.
+
+Tracks:
+- CPU Time
+- Memory Usage
+- Queue Length
+- Thread Utilization
+- Process Count
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class ResourceLimits:
+    """Configurable resource limits."""
+    
+    max_processes: int = 1000
+    max_memory_bytes: int = 1024 * 1024 * 1024  # 1GB
+    max_cpu_time_ms: float = 60000  # 1 minute
+    max_queue_length: int = 10000
+
+
+@dataclass
+class ResourceSnapshot:
+    """Point-in-time resource snapshot."""
+    
+    snapshot_id: str = field(default_factory=lambda: f"res-{uuid4().hex[:8]}")
+    timestamp: float = field(default_factory=time.time)
+    process_count: int = 0
+    memory_bytes: int = 0
+    cpu_time_ms: float = 0.0
+    queue_length: int = 0
+    thread_utilization: float = 0.0
+
+
+class ResourceManager:
+    """Tracks and limits resource usage.
+    
+    Responsibilities:
+    - Track resource usage
+    - Enforce limits
+    - Provide resource snapshots
+    """
+    
+    def __init__(self, limits: ResourceLimits | None = None):
+        self._limits = limits or ResourceLimits()
+        self._usage: dict[str, float] = {}
+        self._snapshots: list[ResourceSnapshot] = []
+    
+    def check_limits(self, process_count: int, memory_bytes: int) -> dict[str, Any]:
+        """Check if resource limits are exceeded."""
+        violations = []
+        
+        if process_count > self._limits.max_processes:
+            violations.append(f"Process count {process_count} exceeds limit {self._limits.max_processes}")
+        
+        if memory_bytes > self._limits.max_memory_bytes:
+            violations.append(f"Memory {memory_bytes} exceeds limit {self._limits.max_memory_bytes}")
+        
+        return {
+            "allowed": len(violations) == 0,
+            "violations": violations,
+        }
+    
+    def record_usage(self, resource: str, value: float) -> None:
+        """Record resource usage."""
+        self._usage[resource] = value
+    
+    def get_usage(self, resource: str | None = None) -> float | dict:
+        if resource:
+            return self._usage.get(resource, 0.0)
+        return dict(self._usage)
+    
+    def snapshot(self, process_count: int = 0, memory_bytes: int = 0, queue_length: int = 0) -> ResourceSnapshot:
+        """Take a resource snapshot."""
+        snap = ResourceSnapshot(
+            process_count=process_count,
+            memory_bytes=memory_bytes,
+            queue_length=queue_length,
+        )
+        self._snapshots.append(snap)
+        if len(self._snapshots) > 1000:
+            self._snapshots = self._snapshots[-500:]
+        return snap
+    
+    def summary(self) -> dict:
+        return {
+            "limits": {
+                "max_processes": self._limits.max_processes,
+                "max_memory_bytes": self._limits.max_memory_bytes,
+            },
+            "usage": dict(self._usage),
+            "snapshots": len(self._snapshots),
+        }

src/monkey_brain/runtime/routers.py

@@ -0,0 +1,8 @@
+"""Runtime routers."""
+
+from fastapi import APIRouter, Request
+
+router = APIRouter()
+
+def get_mongo_client(request: Request):
+    return request.app.state.mongo_client