monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/kernel/intents/telemetry_adapter.py

@@ -0,0 +1,274 @@
+"""Telemetry Execution Adapter — converts semantic telemetry plans into InfluxDB queries.
+
+Converts operation + entity + time_window + metrics into validated SQL queries.
+Never generates raw Flux. Never hallucinates measurements.
+"""
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.request import Request, urlopen
+from urllib.parse import urlencode
+
+from services.common.config import settings
+
+logger = logging.getLogger(__name__)
+
+# Valid metrics — only these column names are allowed in queries
+VALID_METRICS = frozenset({"temperature", "vibration", "pressure", "utilization", "speed", "power"})
+DEFAULT_METRICS = ["temperature", "vibration", "pressure", "utilization"]
+
+# Valid operations
+VALID_OPERATIONS = frozenset({
+    "latest_value", "trend_analysis", "average_window", "rolling_aggregation",
+    "threshold_breach", "anomaly_detection", "peak_detection",
+    "variance_analysis", "temporal_comparison", "utilization_analysis",
+    "predictive_forecast",
+})
+
+# Time window → SQL interval mapping
+_TW_TO_INTERVAL = {
+    "last_1_hour": "INTERVAL '1 hour'",
+    "last_1_day": "INTERVAL '1 day'",
+    "last_1_week": "INTERVAL '7 days'",
+    "last_1_month": "INTERVAL '30 days'",
+    "today": "INTERVAL '1 day'",
+    "yesterday": "INTERVAL '1 day'",
+    "current_shift": "INTERVAL '8 hours'",
+    "current_week": "INTERVAL '7 days'",
+    "current_month": "INTERVAL '30 days'",
+}
+
+# Configurable constants
+DEFAULT_TIME_WINDOW = "INTERVAL '7 days'"
+DEFAULT_LIMIT = 1000
+DEFAULT_THRESHOLD = 3.0
+QUERY_TIMEOUT = 10
+
+
+def _sanitize_sql_string(value: str) -> str:
+    if not isinstance(value, str):
+        value = str(value)
+    return value.replace("'", "''").replace("\\", "\\\\")
+
+
+def _validate_limit(limit: Any) -> int:
+    try:
+        limit = int(limit)
+    except (TypeError, ValueError):
+        limit = DEFAULT_LIMIT
+    return max(1, min(limit, 100000))
+
+
+def _validate_metric(metric: str) -> str:
+    if metric not in VALID_METRICS:
+        logger.warning("Invalid metric '%s', defaulting to 'temperature'", metric)
+        return "temperature"
+    return metric
+
+
+def _build_time_filter(time_window: str) -> str:
+    if not time_window:
+        return f"time >= now() - {DEFAULT_TIME_WINDOW}"
+    interval = _TW_TO_INTERVAL.get(time_window)
+    if not interval:
+        logger.warning("Unknown time_window '%s', using default 7 days", time_window)
+        interval = "INTERVAL '7 days'"
+    return f"time >= now() - {interval}"
+
+
+def _build_entity_filter(entity_id: str, entity_name: str) -> str:
+    if entity_id and entity_id != "none":
+        eid = _sanitize_sql_string(entity_id)
+        return f"machine_id = '{eid}'"
+    return "1=1"
+
+
+def _select_columns(metrics: list[str]) -> str:
+    cols = [m for m in metrics if m in VALID_METRICS]
+    if not cols:
+        cols = list(DEFAULT_METRICS)
+    return ", ".join(cols)
+
+
+@dataclass
+class TelemetryQueryPlan:
+    operation: str
+    entity_id: str
+    entity_name: str
+    metrics: list[str]
+    time_window: str = ""
+    limit: int = DEFAULT_LIMIT
+
+
+@dataclass
+class TelemetryQueryResult:
+    plan: TelemetryQueryPlan
+    rows: list[dict[str, Any]]
+    sql: str
+    error: str = ""
+
+
+class TelemetryExecutionAdapter:
+    """Converts semantic telemetry plans into InfluxDB SQL queries."""
+
+    def __init__(self):
+        self.url = settings.INFLUXDB_URL.rstrip("/")
+        self.token = settings.INFLUXDB_TOKEN
+        self.db = settings.INFLUXDB_BUCKET
+
+    def build_plan(self, operation: str, entities: list[dict], metrics: list[str] = None,
+                   time_window: str = "", **kwargs) -> TelemetryQueryPlan:
+        entity_id = ""
+        entity_name = ""
+        if entities and isinstance(entities[0], dict):
+            entity_id = entities[0].get("id", "")
+            entity_name = entities[0].get("name", "")
+        safe_metrics = [_validate_metric(m) for m in (metrics or [])] or list(DEFAULT_METRICS)
+        return TelemetryQueryPlan(
+            operation=operation, entity_id=entity_id, entity_name=entity_name,
+            metrics=safe_metrics, time_window=time_window,
+            limit=_validate_limit(kwargs.get("limit", DEFAULT_LIMIT)),
+        )
+
+    def execute(self, plan: TelemetryQueryPlan) -> TelemetryQueryResult:
+        if not plan.operation or plan.operation not in VALID_OPERATIONS:
+            logger.warning("Unknown telemetry operation '%s', falling back to trend_analysis", plan.operation)
+            plan.operation = "trend_analysis"
+        if plan.operation == "latest_value":
+            return self._execute_latest(plan)
+        elif plan.operation == "trend_analysis":
+            return self._execute_trend(plan)
+        elif plan.operation == "average_window":
+            return self._execute_average(plan)
+        elif plan.operation == "anomaly_detection":
+            metric = _validate_metric(plan.metrics[0]) if plan.metrics else "temperature"
+            return self._execute_anomaly(plan, metric)
+        elif plan.operation == "threshold_breach":
+            metric = _validate_metric(plan.metrics[0]) if plan.metrics else "temperature"
+            return self._execute_threshold(plan, metric, DEFAULT_THRESHOLD)
+        elif plan.operation == "peak_detection":
+            metric = _validate_metric(plan.metrics[0]) if plan.metrics else "temperature"
+            return self._execute_threshold(plan, metric, 0)
+        elif plan.operation == "utilization_analysis":
+            return self._execute_average(plan)
+        return self._execute_trend(plan)
+
+    def _execute_latest(self, plan: TelemetryQueryPlan) -> TelemetryQueryResult:
+        cols = _select_columns(plan.metrics)
+        entity_filter = _build_entity_filter(plan.entity_id, plan.entity_name)
+        where = "WHERE time >= now() - INTERVAL '1 hour'"
+        if entity_filter != "1=1":
+            where += f" AND {entity_filter}"
+        sql = f"SELECT {cols} FROM \"telemetry\" {where} ORDER BY time DESC LIMIT 1"
+        rows = self._query(sql)
+        return TelemetryQueryResult(plan=plan, rows=rows, sql=sql)
+
+    def _execute_trend(self, plan: TelemetryQueryPlan) -> TelemetryQueryResult:
+        cols = _select_columns(plan.metrics)
+        time_filter = _build_time_filter(plan.time_window)
+        entity_filter = _build_entity_filter(plan.entity_id, plan.entity_name)
+        where = f"WHERE {time_filter}"
+        if entity_filter != "1=1":
+            where += f" AND {entity_filter}"
+        limit = _validate_limit(plan.limit)
+        sql = f"SELECT {cols} FROM \"telemetry\" {where} ORDER BY time ASC LIMIT {limit}"
+        rows = self._query(sql)
+        return TelemetryQueryResult(plan=plan, rows=rows, sql=sql)
+
+    def _execute_average(self, plan: TelemetryQueryPlan) -> TelemetryQueryResult:
+        cols = _select_columns(plan.metrics)
+        avg_cols = ", ".join(f"avg(CAST({c} AS DOUBLE)) as avg_{c}" for c in cols.split(", "))
+        time_filter = _build_time_filter(plan.time_window)
+        entity_filter = _build_entity_filter(plan.entity_id, plan.entity_name)
+        where = f"WHERE {time_filter}"
+        if entity_filter != "1=1":
+            where += f" AND {entity_filter}"
+        sql = f"SELECT {avg_cols} FROM \"telemetry\" {where}"
+        rows = self._query(sql)
+        return TelemetryQueryResult(plan=plan, rows=rows, sql=sql)
+
+    def _execute_threshold(self, plan: TelemetryQueryPlan, metric: str, threshold_value: float) -> TelemetryQueryResult:
+        safe_metric = _sanitize_sql_string(metric)
+        time_filter = _build_time_filter(plan.time_window)
+        entity_filter = _build_entity_filter(plan.entity_id, plan.entity_name)
+        where = f"WHERE {time_filter}"
+        if entity_filter != "1=1":
+            where += f" AND {entity_filter}"
+        if threshold_value > 0:
+            where += f" AND CAST({safe_metric} AS DOUBLE) > {threshold_value}"
+        limit = _validate_limit(plan.limit)
+        sql = f"SELECT {safe_metric} FROM \"telemetry\" {where} ORDER BY time DESC LIMIT {limit}"
+        rows = self._query(sql)
+        return TelemetryQueryResult(plan=plan, rows=rows, sql=sql)
+
+    def _execute_anomaly(self, plan: TelemetryQueryPlan, metric: str) -> TelemetryQueryResult:
+        safe_metric = _sanitize_sql_string(metric)
+        time_filter = _build_time_filter(plan.time_window)
+        entity_filter = _build_entity_filter(plan.entity_id, plan.entity_name)
+        where = f"WHERE {time_filter}"
+        if entity_filter != "1=1":
+            where += f" AND {entity_filter}"
+        sql = (
+            f"SELECT {safe_metric}, "
+            f"avg(CAST({safe_metric} AS DOUBLE)) as avg_{safe_metric}, "
+            f"stddev(CAST({safe_metric} AS DOUBLE)) as std_{safe_metric} "
+            f"FROM \"telemetry\" {where}"
+        )
+        rows = self._query(sql)
+        return TelemetryQueryResult(plan=plan, rows=rows, sql=sql)
+
+    def _query(self, sql: str) -> list[dict[str, Any]]:
+        params = urlencode({"db": self.db, "q": sql})
+        url = f"{self.url}/api/v3/query_sql?{params}"
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        req = Request(url, headers=headers, method="GET")
+        try:
+            with urlopen(req, timeout=QUERY_TIMEOUT) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+                return data if isinstance(data, list) else [data] if data else []
+        except Exception as e:
+            logger.error("InfluxDB telemetry query failed: %s", e)
+            return []
+
+    def format_answer(self, result: TelemetryQueryResult) -> str:
+        if result.error:
+            return f"Error: {result.error}"
+        rows = result.rows
+        if not rows:
+            return "No telemetry data found."
+        if rows and "error" in rows[0]:
+            return f"Error querying telemetry: {rows[0]['error'][:100]}"
+
+        op = result.plan.operation
+        metric = _validate_metric(result.plan.metrics[0]) if result.plan.metrics else "temperature"
+
+        if op == "latest_value" and rows:
+            val = rows[0].get(metric, rows[0].get(f"latest_{metric}", ""))
+            return f"Current {metric}: {val}"
+        elif op == "average_window" and rows:
+            val = rows[0].get(f"avg_{metric}", rows[0].get(metric, ""))
+            tw = result.plan.time_window or "period"
+            return f"Average {metric} over {tw}: {val}"
+        elif op == "trend_analysis" and rows:
+            vals = [r.get(metric, "") for r in rows[:5]]
+            return f"{metric} trend ({len(rows)} readings): {', '.join(str(v) for v in vals)}"
+        elif op == "threshold_breach" and rows:
+            val = rows[0].get(metric, "")
+            return f"Latest {metric} reading: {val}"
+        elif op == "anomaly_detection" and rows:
+            if len(rows) == 1:
+                avg = rows[0].get(f"avg_{metric}", "")
+                std = rows[0].get(f"std_{metric}", "")
+                return f"Average {metric}: {avg}, StdDev: {std}"
+            return f"Anomaly analysis: {len(rows)} data points analyzed"
+        elif op == "utilization_analysis" and rows:
+            vals = [r.get("utilization", "") for r in rows[:5]]
+            return f"Utilization trend ({len(rows)} readings): {', '.join(str(v) for v in vals)}"
+        elif op == "peak_detection" and rows:
+            val = rows[0].get(metric, "")
+            return f"Peak {metric}: {val}"
+        elif op == "variance_analysis" and rows:
+            val = rows[0].get(f"std_{metric}", "")
+            return f"{metric} standard deviation: {val}"
+        return f"Telemetry query returned {len(rows)} data points."

src/monkey_brain/kernel/intents/utils.py

@@ -0,0 +1,68 @@
+# Builds the GraphRagQueryResponse object based on the provided answer, semantic hits, graph paths, and policy decision information, while also cleaning the answer for user display and extracting citations from the hits and paths
+# This function centralizes the construction of the response object for graph RAG queries, ensuring consistent formatting and inclusion of relevant metadata such as citations and policy decisions, which can be used for auditing, 
+# feedback, or further processing in the application. It also handles the case where semantic hits or graph paths may be optional and ensures that the answer is appropriately cleaned for display to the user based on the original question.   
+from datetime import datetime, timezone
+from services.common.reasoning_traces import log_reasoning_trace
+from src.monkey_brain.kernel.intents.helpers import clean_user_answer_for_question, semantic_hit_citation
+from src.monkey_brain.api.models import GraphRagQueryRequest, GraphRagQueryResponse, SemanticHit
+from services.common.config import settings
+
+def graph_query_response(
+    payload: GraphRagQueryRequest,
+    answer: str,
+    semantic_hits: list[SemanticHit] | None = None,
+    graph_paths: list | None = None,
+    llm_answered: bool = False,
+    policy_decision: dict | None = None,
+    data_source: str | None = None,
+) -> GraphRagQueryResponse:
+    semantic_hits = semantic_hits or []
+    graph_paths = graph_paths or []
+    citations = [semantic_hit_citation(hit) for hit in semantic_hits] + [path.citation for path in graph_paths]
+    return GraphRagQueryResponse(
+        question=payload.question,
+        answer=clean_user_answer_for_question(answer, payload.question),
+        semantic_hits=semantic_hits,
+        graph_paths=graph_paths,
+        citations=list(dict.fromkeys(citations)),
+        llm_answered=llm_answered,
+        query_id=(policy_decision or {}).get("decision_id"),
+        policy_key=(policy_decision or {}).get("policy_key"),
+        strategy=(policy_decision or {}).get("selected_strategy"),
+        user_id=payload.user_id,
+        role=payload.role,
+        session_id=payload.session_id,
+        data_source=data_source,
+    )
+
+
+async def log_unmatched_graph_question(
+    mongo_client,
+    payload: GraphRagQueryRequest,
+    visible_question: str,
+    classified_intent: dict,
+    reason: str,
+) -> None:
+    record = {
+        "question": payload.question,
+        "visible_question": visible_question,
+        "reason": reason,
+        "classified_intent": classified_intent,
+        "collections": payload.collections or [],
+        "top_k": payload.top_k,
+        "created_at": datetime.now(timezone.utc),
+    }
+    try:
+        await mongo_client[settings.DB_NAME][settings.GRAPH_RAG_UNMATCHED_QUESTIONS_COLLECTION].insert_one(record)
+    except Exception:
+        pass
+    log_reasoning_trace(
+        "agentos",
+        stage="intent_classification_unmatched",
+        reasoning_summary="Question did not meet the GraphRAG intent confidence threshold and no deterministic route matched it.",
+        input_summary={"question": payload.question},
+        output_summary={"answer": "unsupported_intent"},
+        metadata=record,
+    )
+
+

src/monkey_brain/kernel/learning.py

@@ -0,0 +1,98 @@
+"""Learning — updates Policy from execution observations.
+
+Learning converts Loss into Policy updates.
+Bellman learns. Capabilities do not. Observers do not.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.kernel.loss import Loss
+
+
+@dataclass
+class Transition:
+    """A single learning transition."""
+    
+    transition_id: str = ""
+    capability: str = ""
+    reward: float = 0.0
+    loss: float = 0.0
+    state_snapshot: dict[str, Any] = None
+    timestamp: str = ""
+    
+    def __post_init__(self):
+        if not self.transition_id:
+            self.transition_id = f"trans-{uuid4().hex[:8]}"
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+        if self.state_snapshot is None:
+            self.state_snapshot = {}
+
+
+class Learning:
+    """Policy learner.
+    
+    Responsibilities:
+    - Convert Loss into reward signals
+    - Update Policy scores
+    - Track learning progress
+    
+    Learning occurs through:
+    Execution → Observation → Loss → Transition → Policy Update
+    """
+    
+    def __init__(self, learning_rate: float = 0.1):
+        self._learning_rate = learning_rate
+        self._transitions: list[Transition] = []
+        self._scores: dict[str, float] = {}
+        self._counts: dict[str, int] = {}
+    
+    def update(
+        self,
+        capability: str,
+        loss: Loss,
+        state: dict[str, Any] | None = None,
+    ) -> Transition:
+        """Convert loss into a policy update."""
+        reward = 1.0 - loss.value  # reward = 1 - loss
+        
+        transition = Transition(
+            capability=capability,
+            reward=reward,
+            loss=loss.value,
+            state_snapshot=state or {},
+        )
+        self._transitions.append(transition)
+        
+        # Exponential moving average update
+        old_score = self._scores.get(capability, 0.0)
+        count = self._counts.get(capability, 0)
+        lr = self._learning_rate if count < 5 else self._learning_rate * 0.5
+        new_score = old_score + lr * (reward - old_score)
+        
+        self._scores[capability] = new_score
+        self._counts[capability] = count + 1
+        
+        return transition
+    
+    def get_score(self, capability: str) -> float:
+        return self._scores.get(capability, 0.0)
+    
+    def get_all_scores(self) -> dict[str, float]:
+        return dict(self._scores)
+    
+    def get_transitions(self) -> list[Transition]:
+        return list(self._transitions)
+    
+    def summary(self) -> dict:
+        return {
+            "total_transitions": len(self._transitions),
+            "capabilities_learned": len(self._scores),
+            "scores": dict(self._scores),
+            "counts": dict(self._counts),
+        }

src/monkey_brain/kernel/llm_explorer.py

@@ -0,0 +1,188 @@
+"""LLM Explorer — generates candidate workflows using LLM.
+
+The LLM is an exploration mechanism, not the execution policy.
+
+Flow:
+  LLM generates candidate workflows (exploration)
+  Policy evaluates and selects (exploitation)
+
+As experience increases, execution converges toward reinforcement learning.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from src.monkey_brain.kernel.pipeline import Pipeline, PipelineStep
+
+
+@dataclass
+class WorkflowCandidate:
+    """A candidate workflow generated by the LLM."""
+    
+    candidate_id: str = field(default_factory=lambda: f"wf-{uuid4().hex[:8]}")
+    name: str = ""
+    description: str = ""
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    estimated_cost: float = 1.0
+    estimated_latency_ms: float = 100.0
+    confidence: float = 0.5
+    source: str = "llm"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class LLMExplorer:
+    """LLM-based workflow exploration.
+    
+    The LLM generates candidate workflows.
+    The Policy selects which workflow to execute.
+    
+    As experience increases, execution converges toward reinforcement learning.
+    LLM is used for exploration, not exploitation.
+    """
+    
+    def __init__(self):
+        self._candidates: list[WorkflowCandidate] = []
+        self._llm_calls = 0
+        self._total_tokens = 0
+        self._lemon = None
+    
+    def set_lemon(self, lemon) -> None:
+        self._lemon = lemon
+    
+    def generate_candidates(
+        self,
+        question: str,
+        intent: str,
+        context: dict[str, Any] | None = None,
+    ) -> list[WorkflowCandidate]:
+        """Generate candidate workflows using LLM.
+        
+        In production, this calls the LLM to generate workflows.
+        For now, returns predefined candidates based on intent.
+        """
+        candidates = self._generate_from_intent(intent, context or {})
+        
+        self._llm_calls += 1
+        
+        if self._lemon:
+            self._lemon.counter("llm.explorer.calls")
+            self._lemon.histogram("llm.explorer.candidates", len(candidates))
+        
+        self._candidates.extend(candidates)
+        return candidates
+    
+    def _generate_from_intent(
+        self,
+        intent: str,
+        context: dict[str, Any],
+    ) -> list[WorkflowCandidate]:
+        """Generate candidates based on intent (simulated LLM)."""
+        
+        # Base workflow: simple retrieve
+        base_steps = [
+            {"name": "resolve_entity", "capability": "resolve_entity"},
+            {"name": "retrieve", "capability": "retrieve"},
+            {"name": "format", "capability": "format"},
+        ]
+        
+        candidates = []
+        
+        # Candidate 1: Simple pipeline
+        candidates.append(WorkflowCandidate(
+            name="simple_pipeline",
+            description="Basic retrieve and format",
+            steps=base_steps,
+            estimated_cost=1.0,
+            estimated_latency_ms=50.0,
+            confidence=0.5,
+            source="llm",
+        ))
+        
+        # Candidate 2: With entity resolution
+        if intent in ["batch_record", "plant_topology", "worker", "maintenance"]:
+            candidates.append(WorkflowCandidate(
+                name="entity_enriched",
+                description="Entity resolution with hierarchy",
+                steps=[
+                    {"name": "resolve_entity", "capability": "resolve_entity"},
+                    {"name": "resolve_hierarchy", "capability": "resolve_entity"},
+                    {"name": "retrieve", "capability": "retrieve"},
+                    {"name": "format", "capability": "format"},
+                ],
+                estimated_cost=1.5,
+                estimated_latency_ms=75.0,
+                confidence=0.6,
+                source="llm",
+            ))
+        
+        # Candidate 3: With analysis
+        if intent in ["production_kpi", "simulation", "decision_intelligence"]:
+            candidates.append(WorkflowCandidate(
+                name="analytical",
+                description="Retrieve with analysis",
+                steps=[
+                    {"name": "resolve_entity", "capability": "resolve_entity"},
+                    {"name": "retrieve", "capability": "retrieve"},
+                    {"name": "analyze", "capability": "retrieve"},
+                    {"name": "format", "capability": "format"},
+                ],
+                estimated_cost=2.0,
+                estimated_latency_ms=100.0,
+                confidence=0.4,
+                source="llm",
+            ))
+        
+        # Candidate 4: With knowledge search
+        if intent in ["knowledge_base", "sop_compliance", "change_control"]:
+            candidates.append(WorkflowCandidate(
+                name="knowledge_enriched",
+                description="Knowledge-augmented retrieval",
+                steps=[
+                    {"name": "resolve_entity", "capability": "resolve_entity"},
+                    {"name": "search_knowledge", "capability": "retrieve"},
+                    {"name": "retrieve", "capability": "retrieve"},
+                    {"name": "format", "capability": "format"},
+                ],
+                estimated_cost=1.8,
+                estimated_latency_ms=80.0,
+                confidence=0.55,
+                source="llm",
+            ))
+        
+        return candidates
+    
+    def candidate_to_pipeline(self, candidate: WorkflowCandidate) -> Pipeline:
+        """Convert a workflow candidate to an executable pipeline."""
+        steps = [
+            PipelineStep(
+                capability_name=step.get("capability", "retrieve"),
+                metadata=step,
+            )
+            for step in candidate.steps
+        ]
+        
+        return Pipeline(
+            steps=steps,
+            estimated_cost=candidate.estimated_cost,
+            estimated_latency=candidate.estimated_latency_ms,
+            metadata={
+                "candidate_id": candidate.candidate_id,
+                "name": candidate.name,
+                "source": candidate.source,
+            },
+        )
+    
+    def get_candidates(self) -> list[WorkflowCandidate]:
+        return list(self._candidates)
+    
+    def summary(self) -> dict:
+        return {
+            "total_candidates": len(self._candidates),
+            "llm_calls": self._llm_calls,
+            "total_tokens": self._total_tokens,
+        }