monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/kernel/parser/rules.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import re
+from re import Pattern
+
+CANONICAL_VERBS = frozenset(
+    {
+        "query",
+        "create",
+        "update",
+        "delete",
+        "analyze",
+        "schedule",
+        "approve",
+        "reject",
+    }
+)
+
+VERB_ALIASES: dict[str, str] = {
+    "show": "query",
+    "list": "query",
+    "find": "query",
+    "get": "query",
+    "fetch": "query",
+    "display": "query",
+    "tell": "query",
+    "create": "create",
+    "add": "create",
+    "update": "update",
+    "modify": "update",
+    "change": "update",
+    "delete": "delete",
+    "remove": "delete",
+    "analyze": "analyze",
+    "compare": "analyze",
+    "schedule": "schedule",
+    "approve": "approve",
+    "reject": "reject",
+}
+
+INTERROGATIVE_LEMMAS = frozenset({"what", "which", "how", "when", "where", "who"})
+
+DEFAULT_VERB = "query"
+
+PROJECTION_ALIASES: dict[str, str] = {
+    "oee": "oee",
+    "mtbf": "mtbf",
+    "mttr": "mttr",
+    "yield": "yield",
+    "downtime": "downtime",
+    "availability": "availability",
+    "performance": "performance",
+    "quality": "quality",
+}
+
+TIME_FILTER_PHRASES: tuple[tuple[str, str], ...] = (
+    ("this week", "this week"),
+    ("last week", "last week"),
+    ("this month", "this month"),
+    ("last month", "last month"),
+    ("yesterday", "yesterday"),
+    ("today", "today"),
+)
+
+ENTITY_PATTERNS: tuple[tuple[str, Pattern[str]], ...] = (
+    ("work_order", re.compile(r"\bWO-\d+\b", re.IGNORECASE)),
+    ("purchase_order", re.compile(r"\bPO-\d+\b", re.IGNORECASE)),
+    ("batch", re.compile(r"\bBatch-\d+\b", re.IGNORECASE)),
+    ("document", re.compile(r"\bSOP-\d+\b", re.IGNORECASE)),
+    ("document", re.compile(r"\bBMR-\d+\b", re.IGNORECASE)),
+    ("pump", re.compile(r"\bPump-\d+\b", re.IGNORECASE)),
+    ("motor", re.compile(r"\bMotor-\d+\b", re.IGNORECASE)),
+    ("line", re.compile(r"\bLine-\d+\b", re.IGNORECASE)),
+    ("machine", re.compile(r"\bMachine-\d+\b", re.IGNORECASE)),
+)

src/monkey_brain/kernel/pipeline.py

@@ -0,0 +1,44 @@
+"""Pipeline — executable capability graph.
+
+A Pipeline is a sequence of capability steps that the Runtime executes.
+The Kernel produces Pipelines. The Runtime executes them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+
+@dataclass
+class PipelineStep:
+    """A single step in a capability pipeline."""
+    
+    step_id: str = field(default_factory=lambda: f"step-{uuid4().hex[:8]}")
+    capability_name: str = ""
+    inputs: list[str] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class Pipeline:
+    """An executable graph of capability steps.
+    
+    The Kernel generates candidate Pipelines.
+    The Policy selects which Pipeline to execute.
+    The Runtime executes the selected Pipeline.
+    """
+    
+    pipeline_id: str = field(default_factory=lambda: f"pipe-{uuid4().hex[:8]}")
+    steps: list[PipelineStep] = field(default_factory=list)
+    estimated_cost: float = 1.0
+    estimated_latency: float = 1.0
+    metadata: dict = field(default_factory=dict)
+    
+    def step_names(self) -> list[str]:
+        return [s.capability_name for s in self.steps]
+    
+    def is_empty(self) -> bool:
+        return len(self.steps) == 0

src/monkey_brain/kernel/planner.py

@@ -0,0 +1,57 @@
+"""Planner — generates candidate capability pipelines.
+
+The Planner takes a Goal and produces candidate Pipelines.
+The Policy selects which Pipeline to execute.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from uuid import uuid4
+
+from src.monkey_brain.kernel.goals.goal import Goal
+from src.monkey_brain.kernel.pipeline import Pipeline, PipelineStep
+
+
+class Planner(ABC):
+    """Abstract planner interface."""
+    
+    @abstractmethod
+    def plan(self, goal: Goal) -> list[Pipeline]:
+        """Generate candidate pipelines for a goal."""
+        ...
+
+
+class GenericPlanner(Planner):
+    """Default planner that creates simple sequential pipelines.
+    
+    One capability per required output.
+    No optimization — just converts goal to pipeline.
+    """
+    
+    def plan(self, goal: Goal) -> list[Pipeline]:
+        steps = []
+        for output in goal.required_outputs:
+            steps.append(
+                PipelineStep(
+                    capability_name="retrieve",
+                    inputs=[],
+                    outputs=[output],
+                    metadata={"goal_type": goal.goal_type, "intent": goal.name},
+                )
+            )
+        
+        if not steps:
+            steps.append(PipelineStep(capability_name="retrieve"))
+        
+        pipeline = Pipeline(
+            steps=steps,
+            metadata={
+                "goal_id": goal.goal_id,
+                "goal_type": goal.goal_type,
+                "intent": goal.name,
+                "entities": goal.entities,
+            },
+        )
+        
+        return [pipeline]

src/monkey_brain/kernel/rl/__init__.py

@@ -0,0 +1,33 @@
+"""Reinforcement Learning — Policy learning for the Cognitive Kernel.
+
+Provides:
+- IPolicy: abstract policy interface
+- BellmanPolicy: initial Q-learning implementation
+- Transition: RL transition model
+- TransitionTable: transition storage
+- RewardModel: reward computation
+- Learner: Q-value updates
+
+Evolution path:
+- Current: BellmanPolicy (Q-Table)
+- Next: DeepQPolicy (Neural Network)
+- Next: ActorCriticPolicy (Actor + Critic)
+- Next: PPOPolicy (Proximal Policy Optimization)
+"""
+
+from src.monkey_brain.kernel.rl.policy import IPolicy, BellmanPolicy
+from src.monkey_brain.kernel.rl.transition import Transition, TransitionTable, hash_state
+from src.monkey_brain.kernel.rl.reward import RewardModel, RewardSignal
+from src.monkey_brain.kernel.rl.learner import Learner, LearningMetrics
+
+__all__ = [
+    "IPolicy",
+    "BellmanPolicy",
+    "Transition",
+    "TransitionTable",
+    "hash_state",
+    "RewardModel",
+    "RewardSignal",
+    "Learner",
+    "LearningMetrics",
+]

src/monkey_brain/kernel/rl/learner.py

@@ -0,0 +1,98 @@
+"""Learner — updates Q-values from transitions.
+
+Implements Q-learning update rule:
+Q(s,a) ← Q(s,a) + α[r + γ·max_a' Q(s',a') - Q(s,a)]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from src.monkey_brain.kernel.rl.transition import hash_state
+
+
+@dataclass
+class LearningMetrics:
+    """Metrics from a learning update."""
+    
+    td_error: float = 0.0
+    old_q: float = 0.0
+    new_q: float = 0.0
+    target: float = 0.0
+
+
+class Learner:
+    """Q-learning updater.
+    
+    Responsibilities:
+    - Convert transitions to Q-value updates
+    - Manage learning rate
+    - Track learning progress
+    
+    The Learner never:
+    - Selects pipelines
+    - Executes capabilities
+    - Manages threads
+    """
+    
+    def __init__(
+        self,
+        learning_rate: float = 0.1,
+        discount_factor: float = 0.95,
+    ):
+        self._lr = learning_rate
+        self._gamma = discount_factor
+        self._update_count = 0
+    
+    def update_q(
+        self,
+        q_table: dict[tuple[str, str], float],
+        state_hash: str,
+        action: str,
+        reward: float,
+        next_state_hash: str,
+        next_actions: list[str],
+        done: bool,
+    ) -> LearningMetrics:
+        """Q-learning update rule.
+        
+        Q(s,a) ← Q(s,a) + α[r + γ·max_a' Q(s',a') - Q(s,a)]
+        """
+        current_q = q_table.get((state_hash, action), 0.0)
+        
+        if done:
+            target = reward
+        else:
+            next_q_values = [q_table.get((next_state_hash, a), 0.0) for a in next_actions]
+            target = reward + self._gamma * max(next_q_values) if next_q_values else reward
+        
+        new_q = current_q + self._lr * (target - current_q)
+        q_table[(state_hash, action)] = new_q
+        self._update_count += 1
+        
+        return LearningMetrics(
+            td_error=abs(target - current_q),
+            old_q=current_q,
+            new_q=new_q,
+            target=target,
+        )
+    
+    @property
+    def learning_rate(self) -> float:
+        return self._lr
+    
+    @property
+    def discount_factor(self) -> float:
+        return self._gamma
+    
+    @property
+    def update_count(self) -> int:
+        return self._update_count
+    
+    def summary(self) -> dict:
+        return {
+            "learning_rate": self._lr,
+            "discount_factor": self._gamma,
+            "update_count": self._update_count,
+        }

src/monkey_brain/kernel/rl/policy.py

@@ -0,0 +1,254 @@
+"""Policy — RL policy interface and Bellman implementation.
+
+The Policy selects pipelines and learns from transitions.
+
+Flow:
+  LLM Explorer generates candidate workflows (exploration)
+  Policy evaluates and selects (exploitation)
+
+As experience increases, execution converges toward reinforcement learning.
+LLM is used for exploration, not exploitation.
+"""
+
+from __future__ import annotations
+
+import random
+from abc import ABC, abstractmethod
+from typing import Any
+
+from src.monkey_brain.kernel.pipeline import Pipeline
+from src.monkey_brain.kernel.execution_state import ExecutionState
+from src.monkey_brain.kernel.rl.transition import Transition, TransitionTable, hash_state
+from src.monkey_brain.kernel.rl.reward import RewardModel, RewardSignal
+from src.monkey_brain.kernel.rl.learner import Learner
+from src.monkey_brain.kernel.llm_explorer import LLMExplorer, WorkflowCandidate
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+
+
+class IPolicy(ABC):
+    """Policy interface — selects pipelines and learns from transitions.
+    
+    This interface remains unchanged as we evolve from Bellman
+    to Deep Q, Actor-Critic, PPO.
+    """
+    
+    @abstractmethod
+    def select(
+        self,
+        pipelines: list[Pipeline],
+        state: ExecutionState | None = None,
+    ) -> Pipeline:
+        """Select which pipeline to execute."""
+        ...
+    
+    @abstractmethod
+    def update(self, transition: Transition) -> None:
+        """Update policy from a transition."""
+        ...
+    
+    @abstractmethod
+    def value(self, state: ExecutionState, action: str) -> float:
+        """Estimate value of taking action in state."""
+        ...
+    
+    @abstractmethod
+    def save(self) -> dict:
+        """Serialize policy state."""
+        ...
+    
+    @abstractmethod
+    def load(self, data: dict) -> None:
+        """Deserialize policy state."""
+        ...
+
+
+class BellmanPolicy(IPolicy):
+    """Bellman equation-based policy.
+    
+    Uses Q-learning with Transition Tables and Reward Tables.
+    
+    Flow:
+      LLM Explorer generates candidate workflows (exploration)
+      Bellman evaluates Q-values and selects (exploitation)
+    
+    As experience increases, execution converges toward reinforcement learning.
+    """
+    
+    def __init__(
+        self,
+        exploration_rate: float = 0.1,
+        learning_rate: float = 0.1,
+        discount_factor: float = 0.95,
+    ):
+        self._exploration_rate = exploration_rate
+        self._transition_table = TransitionTable()
+        self._reward_model = RewardModel()
+        self._learner = Learner(learning_rate, discount_factor)
+        self._q_table: dict[tuple[str, str], float] = {}
+        self._llm_explorer = LLMExplorer()
+        self._persistence_manager = None
+        self._lemon = None
+    
+    def set_persistence_manager(self, manager) -> None:
+        """Set the persistence manager for event emission."""
+        self._persistence_manager = manager
+    
+    def set_lemon(self, lemon) -> None:
+        """Set the Lemon observability manager."""
+        self._lemon = lemon
+        self._llm_explorer.set_lemon(lemon)
+    
+    def generate_and_select(
+        self,
+        question: str,
+        intent: str,
+        state: ExecutionState | None = None,
+    ) -> Pipeline:
+        """Generate candidate workflows using LLM, then select using Bellman.
+        
+        This is the full exploration-exploitation loop:
+        1. LLM generates candidates (exploration)
+        2. Bellman selects best candidate (exploitation)
+        """
+        # 1. LLM generates candidates
+        candidates = self._llm_explorer.generate_candidates(question, intent)
+        
+        # 2. Convert to pipelines
+        pipelines = [self._llm_explorer.candidate_to_pipeline(c) for c in candidates]
+        
+        # 3. Bellman selects
+        selected = self.select(pipelines, state)
+        
+        return selected
+    
+    def select(
+        self,
+        pipelines: list[Pipeline],
+        state: ExecutionState | None = None,
+    ) -> Pipeline:
+        """Select pipeline using epsilon-greedy.
+        
+        Exploration: random selection or LLM-generated candidates
+        Exploitation: select by Q-value
+        """
+        if not pipelines:
+            raise ValueError("No pipelines to select")
+        
+        if len(pipelines) == 1:
+            if self._lemon:
+                self._lemon.counter("policy.selections")
+                self._lemon.gauge("policy.candidate_pipelines", 1)
+            return pipelines[0]
+        
+        # Exploration: random selection
+        if random.random() < self._exploration_rate:
+            if self._lemon:
+                self._lemon.counter("policy.explorations")
+            return random.choice(pipelines)
+        
+        # Exploitation: select by Q-value
+        state_dict = state.to_dict() if state else {}
+        state_hash = hash_state(state_dict)
+        
+        scored = []
+        for p in pipelines:
+            q = self._q_table.get((state_hash, p.pipeline_id), 0.0)
+            scored.append((q, p))
+        
+        scored.sort(key=lambda x: x[0], reverse=True)
+        
+        if self._lemon:
+            self._lemon.counter("policy.selections")
+            self._lemon.gauge("policy.candidate_pipelines", len(pipelines))
+            self._lemon.histogram("policy.q_value", scored[0][0])
+        
+        return scored[0][1]
+    
+    def update(self, transition: Transition) -> None:
+        """Update Q-table from transition."""
+        self._transition_table.store(transition)
+        
+        state_hash = hash_state(transition.state)
+        next_state_hash = hash_state(transition.next_state)
+        
+        next_actions = self._transition_table.get_actions(transition.next_state)
+        if not next_actions:
+            next_actions = [transition.action]
+        
+        metrics = self._learner.update_q(
+            self._q_table,
+            state_hash,
+            transition.action,
+            transition.reward,
+            next_state_hash,
+            next_actions,
+            transition.done,
+        )
+        
+        if self._lemon:
+            self._lemon.counter("policy.updates")
+            self._lemon.histogram("policy.td_error", metrics.td_error)
+            self._lemon.histogram("policy.reward", transition.reward)
+            self._lemon.gauge("policy.q_entries", len(self._q_table))
+    
+    async def update_async(self, transition: Transition) -> None:
+        """Update Q-table from transition with persistence."""
+        self.update(transition)
+        
+        if self._persistence_manager:
+            event = PersistenceEvent(
+                event_type=EventType.METRIC_RECORDED,
+                entity_type="rl_transition",
+                entity_id=transition.action,
+                data={
+                    "action": transition.action,
+                    "reward": transition.reward,
+                    "done": transition.done,
+                },
+            )
+            await self._persistence_manager.persist(event)
+    
+    def value(self, state: ExecutionState, action: str) -> float:
+        """Estimate Q-value for state-action pair."""
+        state_dict = state.to_dict()
+        state_hash = hash_state(state_dict)
+        return self._q_table.get((state_hash, action), 0.0)
+    
+    def reward_from_feedback(self, **kwargs: Any) -> RewardSignal:
+        """Compute reward from user feedback."""
+        return self._reward_model.from_feedback(**kwargs)
+    
+    def reward_from_loss(self, loss_value: float) -> RewardSignal:
+        """Compute reward from loss."""
+        return self._reward_model.from_loss(loss_value)
+    
+    def save(self) -> dict:
+        """Serialize policy state."""
+        return {
+            "q_table": {f"{k[0]}:{k[1]}": v for k, v in self._q_table.items()},
+            "exploration_rate": self._exploration_rate,
+            "learning_rate": self._learner.learning_rate,
+            "discount_factor": self._learner.discount_factor,
+            "update_count": self._learner.update_count,
+        }
+    
+    def load(self, data: dict) -> None:
+        """Deserialize policy state."""
+        self._q_table = {
+            tuple(k.split(":", 1)): v
+            for k, v in data.get("q_table", {}).items()
+        }
+        self._exploration_rate = data.get("exploration_rate", 0.1)
+    
+    def summary(self) -> dict:
+        return {
+            "type": "bellman",
+            "exploration_rate": self._exploration_rate,
+            "q_entries": len(self._q_table),
+            "transitions": self._transition_table.count(),
+            "rewards": self._reward_model.summary(),
+            "learner": self._learner.summary(),
+            "llm_explorer": self._llm_explorer.summary(),
+            "persistence_enabled": self._persistence_manager is not None,
+            "lemon_enabled": self._lemon is not None,
+        }

src/monkey_brain/kernel/rl/reward.py

@@ -0,0 +1,117 @@
+"""Reward — RL reward model.
+
+Computes rewards from execution outcomes.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class RewardSignal:
+    """A reward signal from execution."""
+    
+    reward: float = 0.0
+    components: dict[str, float] = field(default_factory=dict)
+    source: str = ""  # "feedback" | "loss" | "simulation"
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class RewardModel:
+    """Computes rewards from execution outcomes.
+    
+    Sources:
+    - User feedback (thumbs, ratings)
+    - Loss computation (predicted vs actual)
+    - Simulation (predicted vs expected)
+    """
+    
+    def __init__(self):
+        self._history: list[RewardSignal] = []
+    
+    def from_feedback(
+        self,
+        accepted: bool | None = None,
+        thumb: str | None = None,
+        rating: int | None = None,
+        feedback_text: str | None = None,
+    ) -> RewardSignal:
+        """Compute reward from user feedback."""
+        reward = 0.0
+        components = {}
+        
+        if accepted is True:
+            reward += 1.0
+            components["accepted"] = 1.0
+        elif accepted is False:
+            reward -= 1.0
+            components["accepted"] = -1.0
+        
+        if thumb == "up":
+            reward += 1.0
+            components["thumb_up"] = 1.0
+        elif thumb == "down":
+            reward -= 1.0
+            components["thumb_down"] = -1.0
+        
+        if rating is not None:
+            r = max(-1.0, min(1.0, (rating - 3) / 2))
+            reward += r
+            components["rating"] = r
+        
+        normalized = (feedback_text or "").lower()
+        if re.search(r"\b(?:wrong|incorrect|bad|still wrong)\b", normalized):
+            reward -= 1.0
+            components["negative_text"] = -1.0
+        if re.search(r"\b(?:good|correct|works|right)\b", normalized):
+            reward += 0.75
+            components["positive_text"] = 0.75
+        
+        signal = RewardSignal(
+            reward=max(-2.0, min(2.0, reward)),
+            components=components,
+            source="feedback",
+        )
+        self._history.append(signal)
+        return signal
+    
+    def from_loss(self, loss_value: float) -> RewardSignal:
+        """Compute reward from loss (loss=0 → reward=1)."""
+        reward = 1.0 - loss_value
+        signal = RewardSignal(
+            reward=reward,
+            components={"loss": loss_value},
+            source="loss",
+        )
+        self._history.append(signal)
+        return signal
+    
+    def from_simulation(
+        self,
+        predicted: dict[str, Any],
+        actual: dict[str, Any],
+    ) -> RewardSignal:
+        """Compute reward from simulation comparison."""
+        from src.monkey_brain.kernel.loss import compute_loss
+        loss = compute_loss(predicted, actual)
+        return self.from_loss(loss.value)
+    
+    def history(self) -> list[RewardSignal]:
+        return list(self._history)
+    
+    def summary(self) -> dict:
+        if not self._history:
+            return {"count": 0, "avg_reward": 0.0}
+        
+        rewards = [s.reward for s in self._history]
+        return {
+            "count": len(self._history),
+            "avg_reward": sum(rewards) / len(rewards),
+            "min_reward": min(rewards),
+            "max_reward": max(rewards),
+        }