monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/kernel/execution_state.py

@@ -0,0 +1,257 @@
+"""Execution State — Single source of truth for runtime execution.
+
+This module implements the unified ExecutionState that gets incrementally
+augmented by capabilities. Every capability consumes the current state,
+performs its operation, and returns an updated state.
+
+Key Principles:
+- Single source of truth for all runtime data
+- Incrementally augmented, never replaced
+- Contains all knowledge accumulated during execution
+- Used by Bellman for policy decisions
+- Observed by ExecutionObserver for loss calculation
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+from enum import Enum
+
+
+class ExecutionPhase(str, Enum):
+    """Current phase of execution."""
+    INITIALIZED = "initialized"
+    ENTITY_RESOLUTION = "entity_resolution"
+    HIERARCHY_RESOLUTION = "hierarchy_resolution"
+    KNOWLEDGE_RETRIEVAL = "knowledge_retrieval"
+    ANALYSIS = "analysis"
+    ANSWER_GENERATION = "answer_generation"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class ExecutionState:
+    """Unified execution state that gets incrementally augmented by capabilities."""
+    
+    # Core execution context
+    question: str = ""
+    intent: str = ""
+    phase: ExecutionPhase = ExecutionPhase.INITIALIZED
+    
+    # Entity resolution results
+    entities: list[dict[str, Any]] = field(default_factory=list)
+    resolved_entities: dict[str, dict[str, Any]] = field(default_factory=dict)  # entity_type -> entity
+    
+    # Hierarchy resolution results  
+    hierarchy: dict[str, Any] = field(default_factory=dict)
+    relationships: list[dict[str, Any]] = field(default_factory=list)
+    
+    # Knowledge retrieval results
+    graph_entities: list[dict[str, Any]] = field(default_factory=list)
+    documents: list[dict[str, Any]] = field(default_factory=list)
+    web_results: list[dict[str, Any]] = field(default_factory=list)
+    
+    # Execution metadata
+    execution_stats: dict[str, Any] = field(default_factory=dict)
+    observations: list[dict[str, Any]] = field(default_factory=list)
+    policy_updates: list[dict[str, Any]] = field(default_factory=list)
+    
+    # Capability execution history
+    capability_history: list[str] = field(default_factory=list)
+    execution_trace: list[dict[str, Any]] = field(default_factory=list)
+    
+    # Current answer state
+    current_answer: str = ""
+    answer_quality: float = 0.0
+    confidence: float = 0.0
+    
+    # Error handling
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    
+    def add_entity(self, entity_type: str, entity: dict[str, Any]) -> None:
+        """Add a resolved entity to the state."""
+        self.entities.append(entity)
+        self.resolved_entities[entity_type] = entity
+        
+    def add_hierarchy(self, hierarchy_data: dict[str, Any]) -> None:
+        """Add hierarchy information to the state."""
+        self.hierarchy.update(hierarchy_data)
+        
+    def add_relationship(self, relationship: dict[str, Any]) -> None:
+        """Add a relationship to the state."""
+        self.relationships.append(relationship)
+        
+    def add_graph_entities(self, entities: list[dict[str, Any]]) -> None:
+        """Add graph entities to the state."""
+        self.graph_entities.extend(entities)
+        
+    def add_documents(self, documents: list[dict[str, Any]]) -> None:
+        """Add documents to the state."""
+        self.documents.extend(documents)
+        
+    def add_web_results(self, results: list[dict[str, Any]]) -> None:
+        """Add web search results to the state."""
+        self.web_results.extend(results)
+        
+    def record_capability_execution(self, capability_name: str, result: dict[str, Any]) -> None:
+        """Record that a capability was executed."""
+        self.capability_history.append(capability_name)
+        self.execution_trace.append({
+            "capability": capability_name,
+            "result": result,
+            "timestamp": result.get("timestamp", "")
+        })
+        
+    def add_observation(self, observation: dict[str, Any]) -> None:
+        """Add an observation for policy learning."""
+        self.observations.append(observation)
+        
+    def add_policy_update(self, policy_update: dict[str, Any]) -> None:
+        """Add a policy update for Bellman optimization."""
+        self.policy_updates.append(policy_update)
+        
+    def set_answer(self, answer: str, quality: float = 0.0, confidence: float = 0.0) -> None:
+        """Set the current answer state."""
+        self.current_answer = answer
+        self.answer_quality = quality
+        self.confidence = confidence
+        
+    def add_error(self, error: str) -> None:
+        """Add an error to the state."""
+        self.errors.append(error)
+        
+    def add_warning(self, warning: str) -> None:
+        """Add a warning to the state."""
+        self.warnings.append(warning)
+        
+    def is_complete(self) -> bool:
+        """Check if execution is complete."""
+        return self.phase == ExecutionPhase.COMPLETED or self.phase == ExecutionPhase.FAILED
+        
+    def has_errors(self) -> bool:
+        """Check if there are any errors."""
+        return len(self.errors) > 0
+        
+    def get_entity(self, entity_type: str) -> Optional[dict[str, Any]]:
+        """Get a resolved entity by type."""
+        return self.resolved_entities.get(entity_type)
+    
+    def has_data(self, key: str) -> bool:
+        """Check if state contains specific data."""
+        return key in self.execution_stats
+    
+    def get_data(self, key: str) -> Any:
+        """Get data from execution stats."""
+        return self.execution_stats.get(key)
+        
+    def to_dict(self) -> dict[str, Any]:
+        """Convert state to dictionary for serialization."""
+        return {
+            "question": self.question,
+            "intent": self.intent,
+            "phase": self.phase.value,
+            "entities": self.entities,
+            "resolved_entities": self.resolved_entities,
+            "hierarchy": self.hierarchy,
+            "relationships": self.relationships,
+            "graph_entities": self.graph_entities,
+            "documents": self.documents,
+            "web_results": self.web_results,
+            "execution_stats": self.execution_stats,
+            "observations": self.observations,
+            "policy_updates": self.policy_updates,
+            "capability_history": self.capability_history,
+            "execution_trace": self.execution_trace,
+            "current_answer": self.current_answer,
+            "answer_quality": self.answer_quality,
+            "confidence": self.confidence,
+            "errors": self.errors,
+            "warnings": self.warnings
+        }
+        
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ExecutionState:
+        """Create state from dictionary."""
+        state = cls(
+            question=data.get("question", ""),
+            intent=data.get("intent", ""),
+            phase=ExecutionPhase(data.get("phase", ExecutionPhase.INITIALIZED.value))
+        )
+        
+        # Restore all the collected data
+        state.entities = data.get("entities", [])
+        state.resolved_entities = data.get("resolved_entities", {})
+        state.hierarchy = data.get("hierarchy", {})
+        state.relationships = data.get("relationships", [])
+        state.graph_entities = data.get("graph_entities", [])
+        state.documents = data.get("documents", [])
+        state.web_results = data.get("web_results", [])
+        state.execution_stats = data.get("execution_stats", {})
+        state.observations = data.get("observations", [])
+        state.policy_updates = data.get("policy_updates", [])
+        state.capability_history = data.get("capability_history", [])
+        state.execution_trace = data.get("execution_trace", [])
+        state.current_answer = data.get("current_answer", "")
+        state.answer_quality = data.get("answer_quality", 0.0)
+        state.confidence = data.get("confidence", 0.0)
+        state.errors = data.get("errors", [])
+        state.warnings = data.get("warnings", [])
+        
+        return state
+
+
+@dataclass
+class CapabilityResult:
+    """Result returned by every capability execution."""
+    
+    # Updated execution state
+    updated_state: ExecutionState
+    
+    # Execution metadata
+    capability_name: str = ""
+    success: bool = True
+    latency: float = 0.0
+    timestamp: str = ""
+    
+    # Policy learning data
+    observations: list[dict[str, Any]] = field(default_factory=list)
+    transition_reward: float = 0.0
+    execution_cost: float = 0.0
+    confidence: float = 0.0
+    
+    # Execution details
+    execution_metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "capability_name": self.capability_name,
+            "success": self.success,
+            "latency": self.latency,
+            "timestamp": self.timestamp,
+            "observations": self.observations,
+            "transition_reward": self.transition_reward,
+            "execution_cost": self.execution_cost,
+            "confidence": self.confidence,
+            "execution_metadata": self.execution_metadata,
+            "updated_state": self.updated_state.to_dict()
+        }
+        
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CapabilityResult:
+        """Create from dictionary."""
+        return cls(
+            updated_state=ExecutionState.from_dict(data["updated_state"]),
+            capability_name=data.get("capability_name", ""),
+            success=data.get("success", True),
+            latency=data.get("latency", 0.0),
+            timestamp=data.get("timestamp", ""),
+            observations=data.get("observations", []),
+            transition_reward=data.get("transition_reward", 0.0),
+            execution_cost=data.get("execution_cost", 0.0),
+            confidence=data.get("confidence", 0.0),
+            execution_metadata=data.get("execution_metadata", {})
+        )

src/monkey_brain/kernel/goal_planner.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from src.monkey_brain.kernel.goals.goal import Goal
+from src.monkey_brain.kernel.parser import IntentAST
+
+if TYPE_CHECKING:
+    from src.monkey_brain.kernel.intents.intent_registry import IntentDefinition
+
+
+def build_goal(
+    intent_ast: IntentAST,
+    intent_name: str | None = None,
+    intent_definition: IntentDefinition | None = None,
+) -> Goal:
+    if intent_definition is not None:
+        name = intent_definition.intent
+        required_inputs = list(intent_definition.required_inputs)
+        required_outputs = list(intent_definition.required_outputs)
+        augmentations = list(intent_definition.default_augmentations)
+        constraints = dict(intent_definition.constraints)
+    else:
+        name = intent_name or "generic"
+        required_inputs = []
+        required_outputs = [name]
+        augmentations = []
+        constraints = {}
+
+    if intent_ast is not None and getattr(intent_ast, "projections", []):
+        required_outputs = list(intent_ast.projections)
+
+    goal_type = name
+    if intent_ast is not None and getattr(intent_ast, "verb", None):
+        goal_type = intent_ast.verb
+
+    entities = []
+    if intent_ast is not None and hasattr(intent_ast, "entities"):
+        for e in intent_ast.entities:
+            if hasattr(e, "value"):
+                entities.append(e.value)
+            elif isinstance(e, str):
+                entities.append(e)
+
+    metadata = {}
+    if intent_ast is not None:
+        metadata["verb"] = getattr(intent_ast, "verb", "query")
+        metadata["target"] = getattr(intent_ast, "target", None)
+
+        filters_list = []
+        if hasattr(intent_ast, "filters"):
+            for f in intent_ast.filters:
+                filters_list.append({
+                    "field": getattr(f, "field", ""),
+                    "operator": getattr(f, "operator", ""),
+                    "value": getattr(f, "value", None),
+                })
+        metadata["filters"] = filters_list
+
+        entity_constraints = []
+        if hasattr(intent_ast, "entities"):
+            for e in intent_ast.entities:
+                entity_constraints.append({
+                    "type": getattr(e, "type", ""),
+                    "value": getattr(e, "value", ""),
+                })
+        metadata["entity_constraints"] = entity_constraints
+
+        if hasattr(intent_ast, "metadata") and intent_ast.metadata:
+            metadata.update(intent_ast.metadata)
+
+    if not required_outputs:
+        required_outputs = [name or "generic"]
+
+    return Goal(
+        goal_type=goal_type,
+        name=name,
+        required_inputs=required_inputs,
+        required_outputs=required_outputs,
+        entities=entities,
+        augmentations=augmentations,
+        constraints=constraints,
+        metadata=metadata,
+        description=f"Goal for intent '{name}' with entities {entities}",
+    )

src/monkey_brain/kernel/goal_router.py

@@ -0,0 +1,20 @@
+"""Goal Router — routes questions to goals."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def route_question(question: str, classified_intent: dict | None = None) -> Any:
+    """Route a question to a goal."""
+    from src.monkey_brain.kernel.goals.goal import Goal, GoalType
+    
+    intent_name = "unknown"
+    if classified_intent:
+        intent_name = classified_intent.get("intent", "unknown")
+    
+    return Goal(
+        name=intent_name,
+        goal_type=GoalType.QUERY,
+        metadata={"question": question},
+    )

src/monkey_brain/kernel/goals/__init__.py

@@ -0,0 +1 @@
+"""Goals module."""

src/monkey_brain/kernel/goals/goal.py

@@ -0,0 +1,130 @@
+"""Goal model — inherits from IntentDefinition.
+
+Goals are structured intents with additional execution context.
+The intent defines WHAT the system should do.
+The goal defines HOW and WHY, carrying forward all intent properties.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+
+class GoalType(str, Enum):
+    QUERY = "query"
+    SEARCH = "search"
+    AGGREGATE = "aggregate"
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    ANALYZE = "analyze"
+    OTHER = "other"
+
+
+class GoalSource(str, Enum):
+    CHAT = "chat"
+    EVENT = "event"
+    SCHEDULER = "scheduler"
+    AGENT = "agent"
+    API = "api"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class Intent:
+    """Base intent — the classification of what the user wants."""
+    name: str
+    description: str = ""
+    required_inputs: list[str] = field(default_factory=list)
+    required_outputs: list[str] = field(default_factory=list)
+    constraints: dict[str, Any] = field(default_factory=dict)
+    confidence: float = 0.0
+
+
+@dataclass
+class Goal(Intent):
+    """Goal inherits from Intent — carries forward all intent properties.
+
+    Adds execution context: entities, metadata, source, pipeline routing.
+    The intent defines WHAT. The goal defines HOW and WHY.
+    """
+
+    goal_id: str = field(default_factory=lambda: f"goal-{uuid4().hex[:12]}")
+    goal_type: GoalType = GoalType.QUERY
+    source: GoalSource = GoalSource.UNKNOWN
+    entities: list[str] = field(default_factory=list)
+    augmentations: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_intent(cls, intent: Intent, **overrides: Any) -> Goal:
+        """Create a Goal from an Intent, inheriting all its properties."""
+        return cls(
+            name=intent.name,
+            description=intent.description,
+            required_inputs=list(intent.required_inputs),
+            required_outputs=list(intent.required_outputs),
+            constraints=dict(intent.constraints),
+            confidence=intent.confidence,
+            **overrides,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "goal_id": self.goal_id,
+            "goal_type": self.goal_type.value,
+            "name": self.name,
+            "description": self.description,
+            "source": self.source.value,
+            "required_inputs": self.required_inputs,
+            "required_outputs": self.required_outputs,
+            "constraints": self.constraints,
+            "confidence": self.confidence,
+            "entities": self.entities,
+            "augmentations": self.augmentations,
+            "metadata": self.metadata,
+        }
+
+
+def build_goal_from_question(
+    question: str,
+    intent_name: str,
+    entities: list[str] | None = None,
+    **metadata: Any,
+) -> Goal:
+    """Build a Goal from a question and classified intent.
+
+    The intent name determines the goal type and required outputs.
+    Entities are extracted from the question.
+    """
+    goal_type_map = {
+        "plant": GoalType.QUERY,
+        "line": GoalType.QUERY,
+        "line_stage": GoalType.QUERY,
+        "line_workstation": GoalType.QUERY,
+        "stage_workstation": GoalType.QUERY,
+        "document_search": GoalType.SEARCH,
+        "web_search": GoalType.SEARCH,
+    }
+
+    required_outputs_map = {
+        "plant": ["lines"],
+        "line": ["stages", "workstations"],
+        "line_stage": ["stages"],
+        "line_workstation": ["workstations"],
+        "stage_workstation": ["workstations"],
+        "document_search": ["documents"],
+        "web_search": ["search_results"],
+    }
+
+    return Goal(
+        name=intent_name,
+        description=f"Goal for '{question}'",
+        goal_type=goal_type_map.get(intent_name, GoalType.QUERY),
+        required_outputs=required_outputs_map.get(intent_name, [intent_name]),
+        entities=entities or [],
+        metadata={"question": question, **metadata},
+    )

src/monkey_brain/kernel/goals/goal_bootstrap.py

@@ -0,0 +1,38 @@
+"""Goal Bootstrap — manages goal registry."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class GoalBootstrap:
+    """Goal registry singleton."""
+    
+    _instance = None
+    _goals: dict[str, Any] = {}
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def get_goal(self, name: str) -> Any:
+        """Get a registered goal."""
+        return self._goals.get(name)
+    
+    def register_goal(self, name: str, goal: Any) -> None:
+        """Register a goal."""
+        self._goals[name] = goal
+    
+    def summary(self) -> dict[str, Any]:
+        """Get summary of all goals."""
+        return {
+            "goals": {
+                name: {
+                    "required_inputs": getattr(goal, 'required_inputs', []),
+                    "required_outputs": getattr(goal, 'required_outputs', []),
+                    "pipeline_id": getattr(goal, 'pipeline_id', name),
+                }
+                for name, goal in self._goals.items()
+            }
+        }

src/monkey_brain/kernel/goals/goal_classifier.py

@@ -0,0 +1,132 @@
+"""Goal-based classifier — uses LLM to classify questions into goals.
+
+Replaces brittle predicate-based routing with LLM classification.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from src.monkey_brain.kernel.goals.goal import Goal, GoalType
+from src.monkey_brain.kernel.goals.goal_bootstrap import GoalBootstrap
+
+
+async def classify_goal(question: str) -> Goal | None:
+    """Classify a question into a Goal using LLM.
+
+    Reads all registered goals from GoalBootstrap and asks the LLM
+    which goal best matches the question.
+    """
+
+    bootstrap = GoalBootstrap()
+    goals_summary = bootstrap.summary()
+
+    # Build the system prompt with all available goals
+    goals_text = "\n".join(
+        f"- {name}: inputs={g['required_inputs']}, outputs={g['required_outputs']}, pipeline={g['pipeline_id']}"
+        for name, g in goals_summary["goals"].items()
+    )
+
+    system_prompt = f"""You are a goal classifier for an industrial manufacturing system.
+
+Available goals:
+{goals_text}
+
+Given a question, determine which goal best matches. Return a JSON object with:
+- "goal_name": the name of the matching goal (must be one of the available goal names)
+- "confidence": a number between 0 and 1
+
+Return ONLY the JSON object, no other text."""
+
+    user_prompt = f"Classify this question: {question}"
+
+    # Try OpenRouter first, then Ollama
+    result = await _classify_with_openrouter(system_prompt, user_prompt)
+    if result is None:
+        result = await _classify_with_ollama(system_prompt, user_prompt)
+
+    if result is None:
+        return None
+
+    # Parse the result
+    try:
+        data = json.loads(result)
+        goal_name = data.get("goal_name")
+        confidence = float(data.get("confidence", 0))
+
+        if not goal_name or confidence < 0.5:
+            return None
+
+        goal = bootstrap.get_goal(goal_name)
+        return goal
+
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+
+async def _classify_with_openrouter(system_prompt: str, user_prompt: str) -> str | None:
+    """Classify using OpenRouter API."""
+    import httpx
+
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        return None
+
+    payload = {
+        "model": os.getenv("OPENROUTER_MODEL", "openai/gpt-4o-mini"),
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(
+                "https://openrouter.ai/api/v1/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": os.getenv("APP_URL", "http://localhost:8032"),
+                    "X-Title": os.getenv("APP_NAME", "GraphRAG Service"),
+                },
+                json=payload,
+            )
+        if response.status_code != 200:
+            return None
+        data = response.json()
+        answer = data.get("choices", [{}])[0].get("message", {}).get("content")
+        return str(answer).strip() if answer else None
+    except Exception:
+        return None
+
+
+async def _classify_with_ollama(system_prompt: str, user_prompt: str) -> str | None:
+    """Classify using Ollama API."""
+    import httpx
+
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434").rstrip("/")
+    model = os.getenv("OLLAMA_MODEL") or os.getenv("OLLAMA_DEFAULT_MODEL", "gemma3:latest")
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(
+                f"{base_url}/api/chat",
+                json={
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    "options": {"num_predict": 200},
+                },
+            )
+        if response.status_code != 200:
+            return None
+        data = response.json()
+        answer = data.get("message", {}).get("content")
+        return str(answer).strip() if answer else None
+    except Exception:
+        return None