monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/kernel/loss.py

@@ -0,0 +1,81 @@
+"""Loss — quantifies prediction error.
+
+Loss measures how far the actual outcome deviates from the expected outcome.
+Loss = 0.0 means perfect prediction.
+Loss = 1.0 means maximum error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Loss:
+    """Quantifies prediction error across multiple dimensions."""
+    
+    value: float = 1.0  # 0.0 = perfect, 1.0 = maximum error
+    components: dict[str, float] = field(default_factory=dict)
+    metadata: dict = field(default_factory=dict)
+    
+    def is_perfect(self) -> bool:
+        return self.value <= 0.0
+    
+    def is_acceptable(self, threshold: float = 0.3) -> bool:
+        return self.value <= threshold
+
+
+def compute_loss(predicted: dict, actual: dict) -> Loss:
+    """Compute loss between predicted and actual outcomes.
+    
+    Compares:
+    - Entity matching (names, statuses)
+    - Count accuracy
+    - Answer completeness
+    """
+    components = {}
+    
+    # Entity name matching
+    pred_names = set(predicted.get("names", []))
+    actual_names = set(actual.get("names", []))
+    if actual_names:
+        name_matches = len(pred_names & actual_names)
+        components["name_accuracy"] = name_matches / len(actual_names)
+    else:
+        components["name_accuracy"] = 1.0 if not pred_names else 0.5
+    
+    # Count matching
+    pred_count = predicted.get("count", 0)
+    actual_count = actual.get("count", 0)
+    if actual_count > 0:
+        components["count_accuracy"] = min(pred_count, actual_count) / actual_count
+    else:
+        components["count_accuracy"] = 1.0 if pred_count == 0 else 0.5
+    
+    # Status matching
+    pred_statuses = set(predicted.get("statuses", []))
+    actual_statuses = set(actual.get("statuses", []))
+    if actual_statuses:
+        status_matches = len(pred_statuses & actual_statuses)
+        components["status_accuracy"] = status_matches / len(actual_statuses)
+    else:
+        components["status_accuracy"] = 1.0 if not pred_statuses else 0.5
+    
+    # Answer presence
+    components["has_answer"] = 1.0 if actual.get("answer") else 0.0
+    
+    # Weighted average
+    weights = {
+        "name_accuracy": 0.3,
+        "count_accuracy": 0.3,
+        "status_accuracy": 0.2,
+        "has_answer": 0.2,
+    }
+    
+    total = sum(components[k] * weights.get(k, 0) for k in components)
+    loss = 1.0 - total
+    
+    return Loss(
+        value=max(0.0, min(1.0, loss)),
+        components=components,
+    )

src/monkey_brain/kernel/nlp/__init__.py

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

src/monkey_brain/kernel/nlp/compat.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+
+F = TypeVar("F", bound=Callable[[str], bool])
+
+
+def question_text(question: str | TokenizedQuestion) -> str:
+    if isinstance(question, TokenizedQuestion):
+        return question.normalized
+    return question
+
+
+def adapt_predicate(predicate: F) -> Callable[[str | TokenizedQuestion], bool]:
+    """Wrap a str-only predicate so it also accepts TokenizedQuestion."""
+
+    def adapted(question: str | TokenizedQuestion) -> bool:
+        return predicate(question_text(question))
+
+    return adapted

src/monkey_brain/kernel/nlp/models.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class TokenizedQuestion:
+    raw: str
+    normalized: str
+    tokens: list[str]
+    lemmas: list[str]
+    entities: list[str]

src/monkey_brain/kernel/nlp/question_analyzer.py

@@ -0,0 +1,203 @@
+from src.monkey_brain.kernel.nlp.spacy_parser import get_nlp
+
+_INTERROGATIVES = {"what", "who", "which", "where", "when", "how", "why"}
+
+
+def _normalize_phrase(text: str) -> str:
+    """
+    Normalize extracted phrases.
+
+    Examples:
+        "A compression workstation" -> "compression workstation"
+        "the workstation SOP" -> "workstation SOP"
+    """
+    nlp = get_nlp()
+    doc = nlp(text)
+
+    tokens = [
+        token.text
+        for token in doc
+        if token.pos_ not in ("DET", "PRON")
+    ]
+
+    return " ".join(tokens).strip()
+
+
+def _deduplicate_and_rank(phrases: set[str]) -> list[str]:
+    """
+    Keep only the richest phrases.
+
+    Example:
+
+        Tablet Line A      ✓
+        Line A             ✗
+
+        Batch BATCH-2026-001 ✓
+        Batch 001            ✗
+
+        workstation SOP      ✓
+        SOP                  ✗
+    """
+
+    cleaned = []
+
+    for phrase in phrases:
+        phrase = " ".join(phrase.split()).strip()
+
+        if not phrase:
+            continue
+
+        if len(phrase) < 2:
+            continue
+
+        cleaned.append(phrase)
+
+    cleaned = list(set(cleaned))
+
+    # Longest / richest phrases first
+    cleaned.sort(
+        key=lambda p: (
+            len(p.split()),
+            len(p)
+        ),
+        reverse=True
+    )
+
+    kept = []
+
+    for candidate in cleaned:
+
+        candidate_lower = candidate.lower()
+
+        skip = False
+
+        for existing in kept:
+
+            existing_lower = existing.lower()
+
+            # If candidate is mostly represented by a richer phrase
+            if candidate_lower in existing_lower:
+                skip = True
+                break
+
+        if not skip:
+            kept.append(candidate)
+
+    return kept
+
+
+def analyze_question(question: str):
+
+    nlp = get_nlp()
+    doc = nlp(question)
+
+    result = {
+        "verb": "",
+        "target": "",
+        "entities": [],
+        "filters": [],
+        "projections": [],
+        "noun_chunks": [],
+        "phrases": []
+    }
+
+    # ----------------------------------------------------------
+    # Main verb
+    # ----------------------------------------------------------
+
+    for token in doc:
+        if token.pos_ in ("VERB", "AUX") and token.dep_ != "det":
+            result["verb"] = token.lemma_.lower()
+            break
+
+    # ----------------------------------------------------------
+    # Filters
+    # ----------------------------------------------------------
+
+    for token in doc:
+        if token.pos_ == "ADJ":
+            result["filters"].append(token.lemma_.lower())
+
+    # ----------------------------------------------------------
+    # Named entities
+    # ----------------------------------------------------------
+
+    for ent in doc.ents:
+        result["entities"].append(ent.text)
+
+    # ----------------------------------------------------------
+    # Target object
+    # ----------------------------------------------------------
+
+    for token in doc:
+        if (
+            token.dep_ in ("dobj", "attr", "pobj", "nsubj")
+            and token.lemma_.lower() not in _INTERROGATIVES
+        ):
+            result["target"] = token.lemma_.lower()
+            break
+
+    # ----------------------------------------------------------
+    # Candidate phrase extraction
+    # ----------------------------------------------------------
+
+    phrases = set()
+
+    # Noun chunks
+    for chunk in doc.noun_chunks:
+
+        phrase = _normalize_phrase(chunk.text)
+
+        if phrase:
+            phrases.add(phrase)
+            result["noun_chunks"].append(phrase)
+
+    # Named entities
+    for ent in doc.ents:
+
+        phrase = ent.text.strip()
+
+        if phrase:
+            phrases.add(phrase)
+
+    result["phrases"] = _deduplicate_and_rank(phrases)
+
+    return result
+
+
+def analyze_prompt(prompt: str):
+    """
+    Extract candidate phrases from arbitrary text.
+
+    Returns a ranked list of phrases suitable for
+    embedding classification.
+    """
+
+    nlp = get_nlp()
+    doc = nlp(prompt)
+
+    phrases = set()
+
+    # Noun chunks
+    for chunk in doc.noun_chunks:
+
+        phrase = _normalize_phrase(chunk.text)
+
+        if phrase:
+            phrases.add(phrase)
+
+    # Named entities
+    for ent in doc.ents:
+
+        phrase = ent.text.strip()
+
+        if phrase:
+            phrases.add(phrase)
+
+    result = _deduplicate_and_rank(phrases)
+
+    print("\nCandidate Phrases:")
+    for phrase in result:
+        print(f"  - {phrase}")
+
+    return result

src/monkey_brain/kernel/nlp/spacy_parser.py

@@ -0,0 +1,53 @@
+"""Minimal spaCy parser wrapper."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+_nlp = None
+
+
+def get_nlp():
+    """Get or initialize the spaCy NLP model."""
+    global _nlp
+    if _nlp is None:
+        try:
+            import spacy
+            _nlp = spacy.load("en_core_web_sm")
+        except Exception as e:
+            logger.warning(f"Could not load spaCy model: {e}")
+            # Return a minimal fallback
+            _nlp = _MinimalNLP()
+    return _nlp
+
+
+class _MinimalNLP:
+    """Minimal NLP fallback when spaCy is not available."""
+    
+    def __call__(self, text: str) -> "_MinimalDoc":
+        return _MinimalDoc(text)
+
+
+class _MinimalDoc:
+    """Minimal document fallback."""
+    
+    def __init__(self, text: str):
+        self.text = text
+        self.tokens = [_MinimalToken(t) for t in text.split()]
+        self.ents = []
+        self.noun_chunks = []
+    
+    def __iter__(self):
+        return iter(self.tokens)
+
+
+class _MinimalToken:
+    """Minimal token fallback."""
+    
+    def __init__(self, text: str):
+        self.text = text
+        self.lemma_ = text.lower()
+        self.pos_ = "NOUN"
+        self.dep_ = "nsubj"

src/monkey_brain/kernel/observer.py

@@ -0,0 +1,97 @@
+"""Observer — passive execution recorder.
+
+The Observer watches execution but never controls it.
+It records what happened, not what should happen.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from uuid import uuid4
+
+
+@dataclass
+class Observation:
+    """A single observation of execution."""
+    
+    observation_id: str = field(default_factory=lambda: f"obs-{uuid4().hex[:8]}")
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    capability: str = ""
+    action: str = ""
+    input_state: dict = field(default_factory=dict)
+    output_state: dict = field(default_factory=dict)
+    reward: float = 0.0
+    latency_ms: float = 0.0
+    success: bool = True
+    metadata: dict = field(default_factory=dict)
+
+
+class Observer:
+    """Passive execution observer.
+    
+    Responsibilities:
+    - Record every capability execution
+    - Compute execution metrics
+    - Feed observations to Learning
+    
+    The Observer never:
+    - Reorders execution
+    - Schedules work
+    - Modifies Policy
+    - Chooses capabilities
+    """
+    
+    def __init__(self):
+        self._observations: list[Observation] = []
+    
+    def observe(
+        self,
+        capability: str,
+        action: str,
+        input_state: dict,
+        output_state: dict,
+        reward: float = 0.0,
+        latency_ms: float = 0.0,
+        success: bool = True,
+        **metadata,
+    ) -> Observation:
+        """Record an execution observation."""
+        obs = Observation(
+            capability=capability,
+            action=action,
+            input_state=input_state,
+            output_state=output_state,
+            reward=reward,
+            latency_ms=latency_ms,
+            success=success,
+            metadata=metadata,
+        )
+        self._observations.append(obs)
+        return obs
+    
+    def get_observations(self) -> list[Observation]:
+        return list(self._observations)
+    
+    def get_last_observation(self) -> Observation | None:
+        return self._observations[-1] if self._observations else None
+    
+    def clear(self):
+        self._observations.clear()
+    
+    def summary(self) -> dict:
+        if not self._observations:
+            return {"count": 0}
+        
+        rewards = [o.reward for o in self._observations]
+        latencies = [o.latency_ms for o in self._observations]
+        successes = [o.success for o in self._observations]
+        
+        return {
+            "count": len(self._observations),
+            "total_reward": sum(rewards),
+            "avg_reward": sum(rewards) / len(rewards),
+            "avg_latency_ms": sum(latencies) / len(latencies),
+            "success_rate": sum(successes) / len(successes),
+            "capabilities_used": list(set(o.capability for o in self._observations)),
+        }

src/monkey_brain/kernel/parser/__init__.py

@@ -0,0 +1,3 @@
+"""Parser module."""
+from src.monkey_brain.kernel.parser.ast import IntentAST
+__all__ = ["IntentAST"]

src/monkey_brain/kernel/parser/ast.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class EntityRef:
+    type: str
+    value: str
+
+
+@dataclass(slots=True)
+class Filter:
+    field: str
+    operator: str
+    value: Any
+
+
+@dataclass(slots=True)
+class IntentAST:
+    raw_query: str
+    verb: str
+    target: str | None = None
+    entities: list[EntityRef] = field(default_factory=list)
+    filters: list[Filter] = field(default_factory=list)
+    projections: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)

src/monkey_brain/kernel/parser/extractors/__init__.py

@@ -0,0 +1,11 @@
+from src.monkey_brain.kernel.parser.extractors.entities import extract_entities
+from src.monkey_brain.kernel.parser.extractors.filters import extract_time_filters
+from src.monkey_brain.kernel.parser.extractors.projections import extract_projections
+from src.monkey_brain.kernel.parser.extractors.verbs import extract_verb
+
+__all__ = [
+    "extract_entities",
+    "extract_time_filters",
+    "extract_projections",
+    "extract_verb",
+]

src/monkey_brain/kernel/parser/extractors/entities.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+from src.monkey_brain.kernel.parser.ast import EntityRef
+from src.monkey_brain.kernel.parser.rules import ENTITY_PATTERNS
+
+
+def extract_entities(tokenized: TokenizedQuestion) -> list[EntityRef]:
+    seen: set[tuple[str, str]] = set()
+    entities: list[EntityRef] = []
+
+    for entity_type, pattern in ENTITY_PATTERNS:
+        for match in pattern.finditer(tokenized.raw):
+            value = match.group(0)
+            key = (entity_type, value.lower())
+            if key in seen:
+                continue
+            seen.add(key)
+            entities.append(EntityRef(type=entity_type, value=value))
+
+    return entities

src/monkey_brain/kernel/parser/extractors/filters.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+from src.monkey_brain.kernel.parser.ast import Filter
+from src.monkey_brain.kernel.parser.rules import TIME_FILTER_PHRASES
+
+
+def extract_time_filters(tokenized: TokenizedQuestion) -> list[Filter]:
+    filters: list[Filter] = []
+    normalized = tokenized.normalized
+
+    for phrase, value in TIME_FILTER_PHRASES:
+        if phrase in normalized:
+            filters.append(Filter(field="time", operator="=", value=value))
+
+    return filters

src/monkey_brain/kernel/parser/extractors/projections.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+from src.monkey_brain.kernel.parser.rules import PROJECTION_ALIASES
+
+
+def _clean_token(token: str) -> str:
+    return re.sub(r"[^\w-]+", "", token).lower()
+
+
+def extract_projections(tokenized: TokenizedQuestion) -> list[str]:
+    seen: set[str] = set()
+    projections: list[str] = []
+
+    for token in tokenized.tokens:
+        canonical = PROJECTION_ALIASES.get(_clean_token(token))
+        if canonical is not None and canonical not in seen:
+            seen.add(canonical)
+            projections.append(canonical)
+
+    for lemma in tokenized.lemmas:
+        canonical = PROJECTION_ALIASES.get(_clean_token(lemma))
+        if canonical is not None and canonical not in seen:
+            seen.add(canonical)
+            projections.append(canonical)
+
+    for alias, canonical in PROJECTION_ALIASES.items():
+        if len(alias) <= 3:
+            continue
+        if re.search(rf"\b{re.escape(alias)}\b", tokenized.normalized) and canonical not in seen:
+            seen.add(canonical)
+            projections.append(canonical)
+
+    return projections

src/monkey_brain/kernel/parser/extractors/verbs.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+from src.monkey_brain.kernel.parser.rules import (
+    CANONICAL_VERBS,
+    DEFAULT_VERB,
+    INTERROGATIVE_LEMMAS,
+    VERB_ALIASES,
+)
+
+
+def extract_verb(tokenized: TokenizedQuestion) -> str:
+    for token in tokenized.tokens:
+        canonical = VERB_ALIASES.get(token.lower())
+        if canonical is not None:
+            return canonical
+
+    for lemma in tokenized.lemmas:
+        if lemma in CANONICAL_VERBS:
+            return lemma
+        canonical = VERB_ALIASES.get(lemma)
+        if canonical is not None:
+            return canonical
+
+    if tokenized.lemmas and tokenized.lemmas[0] in INTERROGATIVE_LEMMAS:
+        return DEFAULT_VERB
+
+    if any(lemma in INTERROGATIVE_LEMMAS for lemma in tokenized.lemmas[:3]):
+        return DEFAULT_VERB
+
+    return DEFAULT_VERB

src/monkey_brain/kernel/parser/parser.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from src.monkey_brain.kernel.nlp.models import TokenizedQuestion
+from src.monkey_brain.kernel.parser.ast import EntityRef, IntentAST
+from src.monkey_brain.kernel.parser.extractors import (
+    extract_entities,
+    extract_projections,
+    extract_time_filters,
+    extract_verb,
+)
+
+ASSET_ENTITY_TYPES = frozenset({"line", "pump", "motor", "machine"})
+DOCUMENT_ENTITY_TYPES = frozenset({"document"})
+
+
+def infer_target(
+    *,
+    entities: list[EntityRef],
+    projections: list[str],
+) -> str | None:
+    if projections:
+        return "metric"
+
+    entity_types = {entity.type for entity in entities}
+    if "work_order" in entity_types:
+        return "work_order"
+    if "purchase_order" in entity_types:
+        return "purchase_order"
+    if "batch" in entity_types:
+        return "batch"
+    if entity_types & DOCUMENT_ENTITY_TYPES:
+        return "document"
+    if entity_types & ASSET_ENTITY_TYPES:
+        return "asset"
+
+    return None
+
+
+def parse_question(tokenized: TokenizedQuestion) -> IntentAST:
+    entities = extract_entities(tokenized)
+    projections = extract_projections(tokenized)
+    filters = extract_time_filters(tokenized)
+    verb = extract_verb(tokenized)
+    target = infer_target(entities=entities, projections=projections)
+
+    return IntentAST(
+        raw_query=tokenized.raw,
+        verb=verb,
+        target=target,
+        entities=entities,
+        filters=filters,
+        projections=projections,
+        metadata={
+            "normalized": tokenized.normalized,
+            "token_count": len(tokenized.tokens),
+        },
+    )