monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/dlm/ttl.py

@@ -0,0 +1,140 @@
+"""TTL Manager — Time-To-Live management for data objects.
+
+Supports configurable TTL per data class.
+Tracks object creation time and expiration.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.dlm.lifecycle import LifecyclePolicy, get_policy
+
+
+@dataclass
+class TtlEntry:
+    """An entry with TTL tracking."""
+    
+    entry_id: str = field(default_factory=lambda: f"ttl-{uuid4().hex[:8]}")
+    data_type: str = ""
+    object_id: str = ""
+    created_at: float = field(default_factory=time.time)
+    ttl_seconds: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def age_seconds(self) -> float:
+        return time.time() - self.created_at
+    
+    @property
+    def remaining_seconds(self) -> float | None:
+        if self.ttl_seconds is None:
+            return None
+        remaining = self.ttl_seconds - self.age_seconds
+        return max(0.0, remaining)
+    
+    @property
+    def is_expired(self) -> bool:
+        if self.ttl_seconds is None:
+            return False
+        return self.age_seconds >= self.ttl_seconds
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "entry_id": self.entry_id,
+            "data_type": self.data_type,
+            "object_id": self.object_id,
+            "created_at": self.created_at,
+            "age_seconds": round(self.age_seconds, 2),
+            "ttl_seconds": self.ttl_seconds,
+            "remaining_seconds": round(self.remaining_seconds, 2) if self.remaining_seconds is not None else None,
+            "is_expired": self.is_expired,
+        }
+
+
+class TtlManager:
+    """Manages TTL for all data objects.
+    
+    Responsibilities:
+    - Track object creation and expiration
+    - Query expired objects
+    - Apply TTL policies
+    """
+    
+    def __init__(self):
+        self._entries: dict[str, TtlEntry] = {}
+        self._by_type: dict[str, list[str]] = {}
+    
+    def register(
+        self,
+        data_type: str,
+        object_id: str,
+        ttl_seconds: int | None = None,
+        **metadata: Any,
+    ) -> TtlEntry:
+        """Register an object with TTL."""
+        policy = get_policy(data_type)
+        effective_ttl = ttl_seconds if ttl_seconds is not None else policy.ttl_seconds
+        
+        entry = TtlEntry(
+            data_type=data_type,
+            object_id=object_id,
+            ttl_seconds=effective_ttl,
+            metadata=metadata,
+        )
+        
+        self._entries[entry.entry_id] = entry
+        
+        if data_type not in self._by_type:
+            self._by_type[data_type] = []
+        self._by_type[data_type].append(entry.entry_id)
+        
+        return entry
+    
+    def is_expired(self, entry_id: str) -> bool:
+        """Check if an entry has expired."""
+        entry = self._entries.get(entry_id)
+        return entry.is_expired if entry else False
+    
+    def get_expired(self, data_type: str | None = None) -> list[TtlEntry]:
+        """Get all expired entries."""
+        expired = []
+        for entry in self._entries.values():
+            if entry.is_expired:
+                if data_type is None or entry.data_type == data_type:
+                    expired.append(entry)
+        return expired
+    
+    def get_by_type(self, data_type: str) -> list[TtlEntry]:
+        """Get all entries of a type."""
+        entry_ids = self._by_type.get(data_type, [])
+        return [self._entries[eid] for eid in entry_ids if eid in self._entries]
+    
+    def remove(self, entry_id: str) -> bool:
+        """Remove an entry."""
+        if entry_id in self._entries:
+            entry = self._entries[entry_id]
+            self._by_type.get(entry.data_type, []).remove(entry_id)
+            del self._entries[entry_id]
+            return True
+        return False
+    
+    def count(self, data_type: str | None = None) -> int:
+        """Count entries."""
+        if data_type:
+            return len(self._by_type.get(data_type, []))
+        return len(self._entries)
+    
+    def summary(self) -> dict:
+        expired_count = sum(1 for e in self._entries.values() if e.is_expired)
+        by_type = {dt: len(ids) for dt, ids in self._by_type.items()}
+        return {
+            "total": len(self._entries),
+            "expired": expired_count,
+            "active": len(self._entries) - expired_count,
+            "by_type": by_type,
+        }

src/monkey_brain/documents/document_ocr.py

@@ -0,0 +1,6 @@
+class DocumentOcrError(Exception):
+    pass
+
+
+async def extract_document_text_with_qwen_ocr(*args, **kwargs):
+    raise DocumentOcrError("OCR module not implemented")

src/monkey_brain/kernel/__init__.py

@@ -0,0 +1,53 @@
+"""MonkeyBrain Cognitive Kernel (Deadpool).
+
+The Kernel owns cognition only.
+
+Responsibilities:
+- Intent: classify what the user wants
+- Goal: structure the intent for execution
+- Planner: generate candidate capability pipelines
+- Policy: select which pipeline to execute (Bellman/RL)
+- LLM Explorer: generate candidate workflows (exploration)
+- ExecutionState: single source of truth
+- Observer: passive execution recording
+- Loss: quantify prediction error
+- Learning: update Policy from Loss
+
+The Kernel never executes capabilities.
+The Kernel never manages threads.
+The Kernel never performs integrations.
+The Kernel only produces executable capability pipelines.
+"""
+
+from src.monkey_brain.kernel.pipeline import Pipeline, PipelineStep
+from src.monkey_brain.kernel.capability_interface import ICapability
+from src.monkey_brain.kernel.observer import Observer, Observation
+from src.monkey_brain.kernel.loss import Loss, compute_loss
+from src.monkey_brain.kernel.learning import Learning, Transition
+from src.monkey_brain.kernel.rl.policy import IPolicy, BellmanPolicy
+from src.monkey_brain.kernel.rl.transition import Transition as RLTransition, TransitionTable
+from src.monkey_brain.kernel.rl.reward import RewardModel, RewardSignal
+from src.monkey_brain.kernel.rl.learner import Learner, LearningMetrics
+from src.monkey_brain.kernel.llm_explorer import LLMExplorer, WorkflowCandidate
+
+__all__ = [
+    "Pipeline",
+    "PipelineStep",
+    "ICapability",
+    "Observer",
+    "Observation",
+    "Loss",
+    "compute_loss",
+    "Learning",
+    "Transition",
+    "IPolicy",
+    "BellmanPolicy",
+    "RLTransition",
+    "TransitionTable",
+    "RewardModel",
+    "RewardSignal",
+    "Learner",
+    "LearningMetrics",
+    "LLMExplorer",
+    "WorkflowCandidate",
+]

src/monkey_brain/kernel/capability_interface.py

@@ -0,0 +1,144 @@
+"""Capability Interface — Uniform execution interface for all runtime capabilities.
+
+This module defines the ICapability interface that all capabilities must implement.
+Every capability transforms execution state and contributes to policy learning.
+
+Key Principles:
+- Every capability implements the same interface
+- All capabilities are treated identically by the runtime
+- No privileged execution stages
+- Every capability augments execution state
+- Every capability contributes policy observations
+- Bellman selects capabilities, not pipelines
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from src.monkey_brain.kernel.execution_state import ExecutionState, CapabilityResult
+
+
+class ICapability(ABC):
+    """Core capability interface — all capabilities must implement.
+    
+    Every capability:
+    - consumes an execution state
+    - augments the execution state
+    - emits observations
+    - contributes policy updates
+    - returns a new execution state
+    
+    The runtime treats all capabilities identically.
+    """
+    
+    @property
+    @abstractmethod
+    def capability_name(self) -> str:
+        """Unique name of this capability."""
+        ...
+    
+    @property
+    @abstractmethod
+    def capability_type(self) -> str:
+        """Type of capability (e.g., 'entity_resolution', 'knowledge_retrieval')."""
+        ...
+    
+    @abstractmethod
+    async def execute(self, state: ExecutionState, **kwargs: Any) -> CapabilityResult:
+        """Execute the capability and return updated state.
+        
+        Args:
+            state: Current execution state
+            **kwargs: Additional execution context
+            
+        Returns:
+            CapabilityResult with updated state and execution metadata
+        """
+        ...
+    
+    @abstractmethod
+    def can_execute(self, state: ExecutionState) -> bool:
+        """Determine if this capability can execute given current state.
+        
+        Used by Bellman for capability selection.
+        
+        Args:
+            state: Current execution state
+            
+        Returns:
+            True if capability can execute, False otherwise
+        """
+        ...
+    
+    @abstractmethod
+    def estimate_reward(self, state: ExecutionState) -> float:
+        """Estimate expected reward for executing this capability.
+        
+        Used by Bellman for policy evaluation.
+        
+        Args:
+            state: Current execution state
+            
+        Returns:
+            Estimated reward (0.0 to 1.0)
+        """
+        ...
+    
+    @abstractmethod
+    def estimate_cost(self, state: ExecutionState) -> float:
+        """Estimate execution cost for this capability.
+        
+        Used by Bellman for cost-benefit analysis.
+        
+        Args:
+            state: Current execution state
+            
+        Returns:
+            Estimated cost (0.0 to 1.0, where higher is more expensive)
+        """
+        ...
+    
+    def compute_confidence(self, state: ExecutionState) -> float:
+        """Compute confidence that this capability will succeed.
+        
+        Args:
+            state: Current execution state
+            
+        Returns:
+            Confidence score (0.0 to 1.0)
+        """
+        return 0.5  # Default confidence - override in subclasses
+
+
+class EntityResolutionCapability(ICapability):
+    """Base class for entity resolution capabilities."""
+    
+    @property
+    def capability_type(self) -> str:
+        return "entity_resolution"
+
+
+class KnowledgeRetrievalCapability(ICapability):
+    """Base class for knowledge retrieval capabilities."""
+    
+    @property
+    def capability_type(self) -> str:
+        return "knowledge_retrieval"
+
+
+class AnalysisCapability(ICapability):
+    """Base class for analysis capabilities."""
+    
+    @property
+    def capability_type(self) -> str:
+        return "analysis"
+
+
+class AnswerGenerationCapability(ICapability):
+    """Base class for answer generation capabilities."""
+    
+    @property
+    def capability_type(self) -> str:
+        return "answer_generation"

src/monkey_brain/kernel/classifier/__init__.py

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

src/monkey_brain/kernel/classifier/embed_classifier.py

@@ -0,0 +1,125 @@
+"""Embedding-based intent classifier with logistic regression head."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+
+from src.monkey_brain.kernel.classifier.intent_examples import INTENT_EXAMPLES
+
+
+
+import logging
+import numpy as np
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Module-level singleton
+_classifier: "EmbedClassifier | None" = None
+
+
+class EmbedClassifier:
+    """
+    Intent classifier using embeddings + logistic regression.
+    Model-agnostic: swap the SentenceTransformer and retrain.
+    ~30ms per call after warm-up. No generation, no Ollama round trip.
+    """
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        from sentence_transformers import SentenceTransformer
+        self.model = SentenceTransformer(model_name, device="cpu")
+        self.intent_labels: list[str] = []
+        self.intent_matrix: np.ndarray = self._build_matrix()
+        self.classifier = self._train_classifier()
+
+    def _build_matrix(self) -> np.ndarray:
+        sentences, labels = [], []
+        for intent, examples in INTENT_EXAMPLES.items():
+            for ex in examples:
+                sentences.append(ex)
+                labels.append(intent)
+        self.intent_labels = labels
+        vecs = self.model.encode(sentences, normalize_embeddings=True, show_progress_bar=False)
+        return vecs
+
+    def _train_classifier(self):
+        """Train a logistic regression classifier on embeddings."""
+        from sklearn.linear_model import LogisticRegression
+        from sklearn.preprocessing import LabelEncoder
+
+        X = self.intent_matrix
+        y = np.array(self.intent_labels)
+
+        le = LabelEncoder()
+        y_encoded = le.fit_transform(y)
+
+        clf = LogisticRegression(
+            max_iter=1000,
+            C=10.0,
+            class_weight="balanced",
+            solver="lbfgs",
+        )
+        clf.fit(X, y_encoded)
+        self._label_encoder = le
+        return clf
+
+    def invalidate(self):
+        """Force matrix rebuild on next classify() call — called after DB example updates."""
+        self.intent_matrix = None
+        self.classifier = None
+
+    def classify(self, prompt: str, question_analysis: dict, threshold: float = 0.45) -> dict[str, Any] | None:
+        if self.intent_matrix is None:
+            self.intent_matrix = self._build_matrix()
+            self.classifier = self._train_classifier()
+
+        qvec = self.model.encode([prompt], normalize_embeddings=True)[0]
+
+        proba = self.classifier.predict_proba([qvec])[0]
+        best_idx = int(np.argmax(proba))
+        confidence = float(proba[best_idx])
+        intent = self._label_encoder.inverse_transform([best_idx])[0]
+
+        if confidence < threshold:
+            logger.info("Below threshold (%.2f) — keyword fallback", confidence)
+            return None
+
+        return {"pipeline_id": intent, "confidence": confidence}
+
+
+# --- Module-level functions — these are what callers import ---
+
+def get_classifier() -> EmbedClassifier:
+    """Singleton — model loads once at startup, stays resident."""
+    global _classifier
+    if _classifier is None:
+        logger.info("Loading intent embedding model (one-time)...")
+        _classifier = EmbedClassifier()
+        logger.info("Intent model ready.")
+    return _classifier
+
+
+def classify_intent(prompt: str, question_analysis: dict, threshold: float = 0.0) -> dict[str, Any] | None:
+    """~30ms, synchronous, safe to call from async context without await.
+
+    Returns a dict with:
+      - intent: the intent class string (e.g. "work_order_query")
+      - confidence: float 0-1
+      - pipeline_id: resolved pipeline name
+    Or None if below threshold.
+    """
+    try:
+        result = get_classifier().classify(prompt, question_analysis, threshold)
+   
+        if result is None:
+            return None
+        return {
+            "intent": str(result["pipeline_id"]),
+            "confidence": float(result["confidence"]),
+            "pipeline_id": str(result["pipeline_id"]),
+        }
+    except Exception as e:
+        logger.warning("Embed classifier error (%s): %s", type(e).__name__, e)
+        return None

src/monkey_brain/kernel/classifier/intent_examples.py

@@ -0,0 +1,106 @@
+"""Intent examples for the embedding classifier."""
+
+INTENT_EXAMPLES: dict[str, list[str]] = {
+    "plant_topology": [
+        "show me the plant structure",
+        "what plants do we have",
+        "list all plants",
+        "plant hierarchy",
+    ],
+    "line": [
+        "show me the production lines",
+        "what lines exist",
+        "list all lines",
+        "production line details",
+    ],
+    "stage": [
+        "show me the stages",
+        "what stages are there",
+        "list all stages",
+        "process stages",
+    ],
+    "workstation": [
+        "show me workstations",
+        "what workstations exist",
+        "list all workstations",
+        "workstation details",
+    ],
+    "asset_management": [
+        "show me the machines",
+        "what equipment do we have",
+        "list all machines",
+        "machine details",
+    ],
+    "worker": [
+        "show me the workers",
+        "who works here",
+        "list all workers",
+        "worker details",
+    ],
+    "batch_record": [
+        "show me batch records",
+        "what batches are there",
+        "batch details",
+        "batch status",
+    ],
+    "work_order_query": [
+        "show me work orders",
+        "what work orders exist",
+        "work order details",
+        "work order status",
+    ],
+    "sop_compliance": [
+        "show me SOPs",
+        "what SOPs exist",
+        "SOP compliance",
+        "standard operating procedures",
+    ],
+    "production_kpi": [
+        "show me production KPIs",
+        "what is the OEE",
+        "production metrics",
+        "performance indicators",
+    ],
+    "maintenance": [
+        "show me maintenance records",
+        "what maintenance is due",
+        "maintenance schedule",
+        "preventive maintenance",
+    ],
+    "quality_approval": [
+        "show me approvals",
+        "what needs approval",
+        "approval status",
+        "quality approvals",
+    ],
+    "change_control": [
+        "show me change controls",
+        "what changes are pending",
+        "change control status",
+        "document changes",
+    ],
+    "knowledge_base": [
+        "search for information",
+        "find documentation",
+        "knowledge search",
+        "what do you know about",
+    ],
+    "simulation": [
+        "simulate this scenario",
+        "what if we change",
+        "predict the outcome",
+        "impact analysis",
+    ],
+    "count": [
+        "how many",
+        "count the",
+        "what is the total",
+        "number of",
+    ],
+    "web_search": [
+        "search the web",
+        "find online information",
+        "web search for",
+        "look up online",
+    ],
+}

src/monkey_brain/kernel/dag.py

@@ -0,0 +1,23 @@
+"""DAG — execution graph."""
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+@dataclass
+class DAGNode:
+    node_id: str = field(default_factory=lambda: f"node-{uuid4().hex[:8]}")
+    operator_type: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class DAGEdge:
+    source_node_id: str = ""
+    target_node_id: str = ""
+
+@dataclass
+class ExecutionDAG:
+    dag_id: str = field(default_factory=lambda: f"dag-{uuid4().hex[:8]}")
+    nodes: list[DAGNode] = field(default_factory=list)
+    edges: list[DAGEdge] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)