monkeybrain-introspection 1.0.0__py3-none-any.whl

introspection/__init__.py

@@ -0,0 +1,38 @@
+"""Lemon — Observability Layer for AgentOS.
+
+Complete end-to-end visibility into every aspect of the runtime.
+
+Provides:
+- Distributed tracing (Trace, Span)
+- Metrics collection (counters, gauges, histograms)
+- Structured logging (JSON, trace-enriched)
+- Health monitoring (healthy, degraded, unhealthy)
+- Alerting (rules, firing, resolution)
+
+Lemon observes everything.
+Lemon changes nothing.
+"""
+
+from introspection.lemon import Lemon
+from introspection.tracing import Tracer, Trace, Span
+from introspection.metrics import MetricsCollector, Metric
+from introspection.structured_logging import StructuredLogger, LogEntry
+from introspection.health import HealthMonitor, HealthCheck
+from introspection.alerting import AlertManager, Alert, AlertRule, AlertSeverity
+
+__all__ = [
+    "Lemon",
+    "Tracer",
+    "Trace",
+    "Span",
+    "MetricsCollector",
+    "Metric",
+    "StructuredLogger",
+    "LogEntry",
+    "HealthMonitor",
+    "HealthCheck",
+    "AlertManager",
+    "Alert",
+    "AlertRule",
+    "AlertSeverity",
+]

introspection/alerting.py

@@ -0,0 +1,142 @@
+"""Alerting — event-driven alert system.
+
+Generate alerts for:
+- Failures
+- Latency thresholds
+- Memory pressure
+- Queue saturation
+- Capability failures
+- Provider failures
+- Database connectivity
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable
+from uuid import uuid4
+
+
+class AlertSeverity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+class AlertStatus(str, Enum):
+    FIRING = "firing"
+    RESOLVED = "resolved"
+    SILENCED = "silenced"
+
+
+@dataclass
+class Alert:
+    """An alert instance."""
+    
+    alert_id: str = field(default_factory=lambda: f"alert-{uuid4().hex[:8]}")
+    name: str = ""
+    severity: AlertSeverity = AlertSeverity.WARNING
+    status: AlertStatus = AlertStatus.FIRING
+    message: str = ""
+    source: str = ""
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "alert_id": self.alert_id,
+            "name": self.name,
+            "severity": self.severity.value,
+            "status": self.status.value,
+            "message": self.message,
+            "source": self.source,
+            "timestamp": self.timestamp,
+        }
+
+
+class AlertRule:
+    """A rule that triggers alerts."""
+    
+    def __init__(
+        self,
+        name: str,
+        condition: Callable[[dict], bool],
+        severity: AlertSeverity = AlertSeverity.WARNING,
+        message_template: str = "",
+    ):
+        self.name = name
+        self.condition = condition
+        self.severity = severity
+        self.message_template = message_template
+    
+    def evaluate(self, context: dict) -> Alert | None:
+        try:
+            if self.condition(context):
+                return Alert(
+                    name=self.name,
+                    severity=self.severity,
+                    message=self.message_template.format(**context),
+                )
+        except Exception:
+            pass
+        return None
+
+
+class AlertManager:
+    """Alert management system.
+    
+    Responsibilities:
+    - Evaluate alert rules
+    - Fire alerts
+    - Track alert history
+    - Support alert suppression
+    """
+    
+    def __init__(self):
+        self._rules: list[AlertRule] = []
+        self._alerts: list[Alert] = []
+        self._active: dict[str, Alert] = {}
+    
+    def add_rule(self, rule: AlertRule) -> None:
+        self._rules.append(rule)
+    
+    def evaluate(self, context: dict) -> list[Alert]:
+        """Evaluate all rules against context."""
+        new_alerts = []
+        for rule in self._rules:
+            alert = rule.evaluate(context)
+            if alert:
+                self._alerts.append(alert)
+                self._active[alert.alert_id] = alert
+                new_alerts.append(alert)
+        return new_alerts
+    
+    def fire(self, name: str, message: str, severity: AlertSeverity = AlertSeverity.WARNING, **metadata: Any) -> Alert:
+        """Manually fire an alert."""
+        alert = Alert(name=name, severity=severity, message=message, metadata=metadata)
+        self._alerts.append(alert)
+        self._active[alert.alert_id] = alert
+        return alert
+    
+    def resolve(self, alert_id: str) -> bool:
+        """Resolve an active alert."""
+        if alert_id in self._active:
+            self._active[alert_id].status = AlertStatus.RESOLVED
+            del self._active[alert_id]
+            return True
+        return False
+    
+    def get_active(self) -> list[Alert]:
+        return list(self._active.values())
+    
+    def get_history(self, limit: int = 50) -> list[Alert]:
+        return self._alerts[-limit:]
+    
+    def summary(self) -> dict:
+        return {
+            "rules": len(self._rules),
+            "active_alerts": len(self._active),
+            "total_alerts": len(self._alerts),
+        }

introspection/health.py

@@ -0,0 +1,101 @@
+"""Health — health monitoring for all subsystems.
+
+Every subsystem reports health:
+- Healthy
+- Degraded
+- Unavailable
+- Unknown
+
+Health checks include dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class HealthCheck:
+    """A single health check result."""
+    
+    check_id: str = field(default_factory=lambda: f"health-{uuid4().hex[:8]}")
+    name: str = ""
+    status: str = "healthy"  # healthy | degraded | unhealthy | unknown
+    latency_ms: float = 0.0
+    message: str = ""
+    dependencies: list[dict[str, Any]] = field(default_factory=list)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "check_id": self.check_id,
+            "name": self.name,
+            "status": self.status,
+            "latency_ms": round(self.latency_ms, 2),
+            "message": self.message,
+            "dependencies": self.dependencies,
+            "timestamp": self.timestamp,
+        }
+
+
+class HealthMonitor:
+    """Health monitoring manager.
+    
+    Responsibilities:
+    - Run health checks
+    - Track health history
+    - Aggregate health status
+    """
+    
+    def __init__(self):
+        self._checks: dict[str, HealthCheck] = {}
+        self._history: list[HealthCheck] = []
+    
+    def check(self, name: str, status: str = "healthy", message: str = "", **metadata: Any) -> HealthCheck:
+        """Record a health check."""
+        check = HealthCheck(
+            name=name,
+            status=status,
+            message=message,
+            metadata=metadata,
+        )
+        self._checks[name] = check
+        self._history.append(check)
+        if len(self._history) > 1000:
+            self._history = self._history[-500:]
+        return check
+    
+    def healthy(self, name: str, **metadata: Any) -> HealthCheck:
+        return self.check(name, "healthy", **metadata)
+    
+    def degraded(self, name: str, message: str = "", **metadata: Any) -> HealthCheck:
+        return self.check(name, "degraded", message, **metadata)
+    
+    def unhealthy(self, name: str, message: str = "", **metadata: Any) -> HealthCheck:
+        return self.check(name, "unhealthy", message, **metadata)
+    
+    def get_health(self, name: str) -> HealthCheck | None:
+        return self._checks.get(name)
+    
+    def overall_status(self) -> str:
+        statuses = [c.status for c in self._checks.values()]
+        if not statuses:
+            return "unknown"
+        if "unhealthy" in statuses:
+            return "unhealthy"
+        if "degraded" in statuses:
+            return "degraded"
+        if all(s == "healthy" for s in statuses):
+            return "healthy"
+        return "unknown"
+    
+    def summary(self) -> dict:
+        return {
+            "overall": self.overall_status(),
+            "checks": {name: check.status for name, check in self._checks.items()},
+            "total_checks": len(self._checks),
+        }

introspection/lemon.py

@@ -0,0 +1,243 @@
+"""Lemon — Observability Layer for AgentOS.
+
+Persists all metrics to Elasticsearch for querying and dashboards.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from introspection.tracing import Tracer, Trace, Span
+from introspection.metrics import MetricsCollector, Metric
+from introspection.structured_logging import StructuredLogger, LogEntry
+from introspection.health import HealthMonitor, HealthCheck
+from introspection.alerting import AlertManager, Alert, AlertRule, AlertSeverity
+
+
+class Lemon:
+    """Observability manager for AgentOS.
+    
+    Persists all metrics to Elasticsearch for querying.
+    """
+    
+    def __init__(self, elasticsearch_url: str = "http://localhost:9200"):
+        self.tracer = Tracer()
+        self.metrics = MetricsCollector()
+        self.logger = StructuredLogger()
+        self.health = HealthMonitor()
+        self.alerts = AlertManager()
+        self._es_url = elasticsearch_url
+        self._es_client = None
+        self._persist_buffer: list[dict] = []
+    
+    async def connect_elasticsearch(self) -> None:
+        """Connect to Elasticsearch for persistence."""
+        try:
+            from elasticsearch import AsyncElasticsearch
+            self._es_client = AsyncElasticsearch([self._es_url])
+            await self._es_client.ping()
+        except Exception:
+            self._es_client = None
+    
+    async def persist_metrics(self) -> dict[str, Any]:
+        """Persist all metrics to Elasticsearch."""
+        if not self._es_client:
+            return {"status": "no_elasticsearch"}
+        
+        export = self.metrics.export()
+        timestamp = datetime.now(timezone.utc).isoformat()
+        
+        doc = {
+            "timestamp": timestamp,
+            "counters": export.get("counters", {}),
+            "gauges": export.get("gauges", {}),
+            "histograms": export.get("histograms", {}),
+        }
+        
+        try:
+            await self._es_client.index(index="agentos-metrics", document=doc)
+            return {"status": "persisted", "timestamp": timestamp}
+        except Exception as e:
+            return {"status": "error", "error": str(e)}
+    
+    async def persist_traces(self) -> dict[str, Any]:
+        """Persist recent traces to Elasticsearch."""
+        if not self._es_client:
+            return {"status": "no_elasticsearch"}
+        
+        traces = list(self.tracer._traces.values())[-100:]
+        
+        for trace in traces:
+            doc = trace.to_dict()
+            try:
+                await self._es_client.index(index="agentos-traces", document=doc)
+            except Exception:
+                pass
+        
+        return {"status": "persisted", "count": len(traces)}
+    
+    async def persist_logs(self, limit: int = 100) -> dict[str, Any]:
+        """Persist recent logs to Elasticsearch."""
+        if not self._es_client:
+            return {"status": "no_elasticsearch"}
+        
+        logs = self.logger.get_entries(limit=limit)
+        
+        for log in logs:
+            doc = log.to_dict()
+            try:
+                await self._es_client.index(index="agentos-logs", document=doc)
+            except Exception:
+                pass
+        
+        return {"status": "persisted", "count": len(logs)}
+    
+    async def persist_all(self) -> dict[str, Any]:
+        """Persist all observability data to Elasticsearch."""
+        results = {}
+        results["metrics"] = await self.persist_metrics()
+        results["traces"] = await self.persist_traces()
+        results["logs"] = await self.persist_logs()
+        return results
+    
+    async def query_metrics(self, metric_name: str | None = None, size: int = 100) -> list[dict]:
+        """Query metrics from Elasticsearch."""
+        if not self._es_client:
+            return []
+        
+        try:
+            if metric_name:
+                query = {"query": {"term": {"counters." + metric_name: {"exists": True}}}}
+            else:
+                query = {"query": {"match_all": {}}, "sort": [{"timestamp": "desc"}]}
+            
+            result = await self._es_client.search(index="agentos-metrics", body={"size": size, **query})
+            return [hit["_source"] for hit in result["hits"]["hits"]]
+        except Exception:
+            return []
+    
+    async def query_traces(self, trace_id: str | None = None, size: int = 100) -> list[dict]:
+        """Query traces from Elasticsearch."""
+        if not self._es_client:
+            return []
+        
+        try:
+            if trace_id:
+                query = {"query": {"term": {"trace_id": trace_id}}}
+            else:
+                query = {"query": {"match_all": {}}, "sort": [{"timestamp": "desc"}]}
+            
+            result = await self._es_client.search(index="agentos-traces", body={"size": size, **query})
+            return [hit["_source"] for hit in result["hits"]["hits"]]
+        except Exception:
+            return []
+    
+    async def query_logs(self, severity: str | None = None, component: str | None = None, size: int = 100) -> list[dict]:
+        """Query logs from Elasticsearch."""
+        if not self._es_client:
+            return []
+        
+        try:
+            must = []
+            if severity:
+                must.append({"term": {"severity": severity}})
+            if component:
+                must.append({"term": {"component": component}})
+            
+            query = {"query": {"bool": {"must": must or [{"match_all": {}}]}}}
+            result = await self._es_client.search(index="agentos-logs", body={"size": size, "sort": [{"timestamp": "desc"}], **query})
+            return [hit["_source"] for hit in result["hits"]["hits"]]
+        except Exception:
+            return []
+    
+    async def get_dashboard(self) -> dict[str, Any]:
+        """Get dashboard data for all metrics."""
+        metrics = await self.query_metrics(size=1)
+        traces = await self.query_traces(size=10)
+        logs = await self.query_logs(size=10)
+        
+        return {
+            "latest_metrics": metrics[0] if metrics else {},
+            "recent_traces": len(traces),
+            "recent_logs": len(logs),
+            "health": self.health.summary(),
+            "alerts": [a.to_dict() for a in self.alerts.get_active()],
+        }
+    
+    # --- Tracing ---
+    def start_trace(self, name: str = "", **metadata: Any) -> Trace:
+        return self.tracer.start_trace(name, **metadata)
+    
+    def start_span(self, name: str, component: str = "", **attributes: Any) -> Span:
+        return self.tracer.start_span(name, component, **attributes)
+    
+    def finish_span(self, status: str = "ok") -> None:
+        self.tracer.finish_span(status)
+    
+    def finish_trace(self) -> None:
+        self.tracer.finish_trace()
+    
+    # --- Metrics ---
+    def record_metric(self, name: str, value: float, unit: str = "", **tags: str) -> Metric:
+        return self.metrics.record(name, value, unit, **tags)
+    
+    def counter(self, name: str, increment: int = 1, **tags: str) -> None:
+        self.metrics.counter(name, increment, **tags)
+    
+    def gauge(self, name: str, value: float, **tags: str) -> None:
+        self.metrics.gauge(name, value, **tags)
+    
+    def histogram(self, name: str, value: float, **tags: str) -> None:
+        self.metrics.histogram(name, value, **tags)
+    
+    # --- Logging ---
+    def log(self, severity: str, message: str, component: str = "", **kwargs: Any) -> LogEntry:
+        trace = self.tracer.get_current_trace()
+        if trace:
+            kwargs["trace_id"] = trace.trace_id
+        return self.logger.log(severity, message, component=component, **kwargs)
+    
+    def info(self, message: str, component: str = "", **kwargs: Any) -> LogEntry:
+        return self.logger.info(message, component=component, **kwargs)
+    
+    def warn(self, message: str, component: str = "", **kwargs: Any) -> LogEntry:
+        return self.logger.warn(message, component=component, **kwargs)
+    
+    def error(self, message: str, component: str = "", **kwargs: Any) -> LogEntry:
+        return self.logger.error(message, component=component, **kwargs)
+    
+    # --- Health ---
+    def health_check(self, name: str, status: str = "healthy", **metadata: Any) -> HealthCheck:
+        return self.health.check(name, status, **metadata)
+    
+    def overall_health(self) -> str:
+        return self.health.overall_status()
+    
+    # --- Alerts ---
+    def alert(self, name: str, message: str, severity: AlertSeverity = AlertSeverity.WARNING, **metadata: Any) -> Alert:
+        return self.alerts.fire(name, message, severity, **metadata)
+    
+    def add_alert_rule(self, rule: AlertRule) -> None:
+        self.alerts.add_rule(rule)
+    
+    # --- Summary ---
+    def summary(self) -> dict[str, Any]:
+        return {
+            "tracing": self.tracer.summary(),
+            "metrics": self.metrics.summary(),
+            "logging": self.logger.summary(),
+            "health": self.health.summary(),
+            "alerts": self.alerts.summary(),
+            "elasticsearch_connected": self._es_client is not None,
+        }
+    
+    def export(self) -> dict[str, Any]:
+        """Export all observability data."""
+        return {
+            "summary": self.summary(),
+            "metrics": self.metrics.export(),
+            "health": self.health.summary(),
+            "active_alerts": [a.to_dict() for a in self.alerts.get_active()],
+        }

introspection/metrics.py

@@ -0,0 +1,106 @@
+"""Metrics — performance and operational metrics collection.
+
+Captures execution time, latency, throughput, resource usage,
+and AI-specific metrics across all subsystems.
+"""
+
+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 collections import defaultdict
+
+
+@dataclass
+class Metric:
+    """A single metric measurement."""
+    
+    metric_id: str = field(default_factory=lambda: f"metric-{uuid4().hex[:8]}")
+    name: str = ""
+    value: float = 0.0
+    unit: str = ""  # ms | count | bytes | ratio | tokens
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    tags: dict[str, str] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class MetricsCollector:
+    """Collects and aggregates metrics across all subsystems.
+    
+    Responsibilities:
+    - Record metric values
+    - Aggregate metrics (count, sum, avg, min, max)
+    - Track rate metrics (requests/sec)
+    - Export metrics for dashboards
+    """
+    
+    def __init__(self):
+        self._metrics: dict[str, list[Metric]] = defaultdict(list)
+        self._counters: dict[str, int] = defaultdict(int)
+        self._gauges: dict[str, float] = {}
+        self._histograms: dict[str, list[float]] = defaultdict(list)
+    
+    def record(self, name: str, value: float, unit: str = "", **tags: str) -> Metric:
+        """Record a metric measurement."""
+        metric = Metric(name=name, value=value, unit=unit, tags=tags)
+        self._metrics[name].append(metric)
+        return metric
+    
+    def counter(self, name: str, increment: int = 1, **tags: str) -> None:
+        """Increment a counter."""
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        self._counters[key] += increment
+    
+    def gauge(self, name: str, value: float, **tags: str) -> None:
+        """Set a gauge value."""
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        self._gauges[key] = value
+    
+    def histogram(self, name: str, value: float, **tags: str) -> None:
+        """Record a histogram value."""
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        self._histograms[key].append(value)
+        if len(self._histograms[key]) > 1000:
+            self._histograms[key] = self._histograms[key][-500:]
+    
+    def get_counter(self, name: str, **tags: str) -> int:
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        return self._counters.get(key, 0)
+    
+    def get_gauge(self, name: str, **tags: str) -> float | None:
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        return self._gauges.get(key)
+    
+    def get_histogram_stats(self, name: str, **tags: str) -> dict:
+        key = f"{name}:{':'.join(f'{k}={v}' for k, v in sorted(tags.items()))}"
+        values = self._histograms.get(key, [])
+        if not values:
+            return {"count": 0}
+        return {
+            "count": len(values),
+            "min": min(values),
+            "max": max(values),
+            "avg": sum(values) / len(values),
+            "p50": sorted(values)[len(values)//2],
+            "p95": sorted(values)[int(len(values)*0.95)] if len(values) > 1 else values[0],
+            "p99": sorted(values)[int(len(values)*0.99)] if len(values) > 1 else values[0],
+        }
+    
+    def summary(self) -> dict:
+        return {
+            "counters": len(self._counters),
+            "gauges": len(self._gauges),
+            "histograms": len(self._histograms),
+            "total_metrics": sum(len(v) for v in self._metrics.values()),
+        }
+    
+    def export(self) -> dict[str, Any]:
+        """Export all metrics for dashboards."""
+        return {
+            "counters": dict(self._counters),
+            "gauges": dict(self._gauges),
+            "histograms": {k: self.get_histogram_stats(k.split(":")[0]) for k in self._histograms},
+        }

introspection/structured_logging.py

@@ -0,0 +1,147 @@
+"""Logging — structured logging for all subsystems.
+
+Every log entry includes:
+- Timestamp
+- Trace ID
+- Span ID
+- Workflow ID
+- Pipeline ID
+- Capability ID
+- User ID
+- Severity
+- Component
+- Duration
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class LogEntry:
+    """A structured log entry."""
+    
+    log_id: str = field(default_factory=lambda: f"log-{uuid4().hex[:8]}")
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    severity: str = "info"  # debug | info | warn | error | fatal
+    component: str = ""
+    message: str = ""
+    trace_id: str | None = None
+    span_id: str | None = None
+    workflow_id: str | None = None
+    pipeline_id: str | None = None
+    capability_id: str | None = None
+    user_id: str | None = None
+    duration_ms: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> dict[str, Any]:
+        d = {
+            "log_id": self.log_id,
+            "timestamp": self.timestamp,
+            "severity": self.severity,
+            "component": self.component,
+            "message": self.message,
+        }
+        if self.trace_id: d["trace_id"] = self.trace_id
+        if self.span_id: d["span_id"] = self.span_id
+        if self.pipeline_id: d["pipeline_id"] = self.pipeline_id
+        if self.capability_id: d["capability_id"] = self.capability_id
+        if self.user_id: d["user_id"] = self.user_id
+        if self.duration_ms is not None: d["duration_ms"] = self.duration_ms
+        if self.metadata: d["metadata"] = self.metadata
+        return d
+    
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str)
+
+
+class StructuredLogger:
+    """Structured logging manager.
+    
+    Responsibilities:
+    - Create structured log entries
+    - Enrich logs with trace context
+    - Filter by severity
+    - Export logs
+    """
+    
+    def __init__(self, min_level: str = "info"):
+        self._min_level = min_level
+        self._entries: list[LogEntry] = []
+        self._levels = {"debug": 0, "info": 1, "warn": 2, "error": 3, "fatal": 4}
+    
+    def _should_log(self, level: str) -> bool:
+        return self._levels.get(level, 0) >= self._levels.get(self._min_level, 0)
+    
+    def log(
+        self,
+        severity: str,
+        message: str,
+        component: str = "",
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        pipeline_id: str | None = None,
+        capability_id: str | None = None,
+        duration_ms: float | None = None,
+        **metadata: Any,
+    ) -> LogEntry:
+        if not self._should_log(severity):
+            return None
+        
+        entry = LogEntry(
+            severity=severity,
+            component=component,
+            message=message,
+            trace_id=trace_id,
+            span_id=span_id,
+            pipeline_id=pipeline_id,
+            capability_id=capability_id,
+            duration_ms=duration_ms,
+            metadata=metadata,
+        )
+        self._entries.append(entry)
+        return entry
+    
+    def debug(self, message: str, **kwargs: Any) -> LogEntry:
+        return self.log("debug", message, **kwargs)
+    
+    def info(self, message: str, **kwargs: Any) -> LogEntry:
+        return self.log("info", message, **kwargs)
+    
+    def warn(self, message: str, **kwargs: Any) -> LogEntry:
+        return self.log("warn", message, **kwargs)
+    
+    def error(self, message: str, **kwargs: Any) -> LogEntry:
+        return self.log("error", message, **kwargs)
+    
+    def fatal(self, message: str, **kwargs: Any) -> LogEntry:
+        return self.log("fatal", message, **kwargs)
+    
+    def get_entries(
+        self,
+        severity: str | None = None,
+        component: str | None = None,
+        trace_id: str | None = None,
+        limit: int = 100,
+    ) -> list[LogEntry]:
+        entries = self._entries
+        if severity:
+            entries = [e for e in entries if e.severity == severity]
+        if component:
+            entries = [e for e in entries if e.component == component]
+        if trace_id:
+            entries = [e for e in entries if e.trace_id == trace_id]
+        return entries[-limit:]
+    
+    def summary(self) -> dict:
+        counts = {}
+        for e in self._entries:
+            counts[e.severity] = counts.get(e.severity, 0) + 1
+        return {"total": len(self._entries), "by_severity": counts}

introspection/tracing.py

@@ -0,0 +1,162 @@
+"""Tracing — distributed trace management.
+
+Every request receives a globally unique Trace ID.
+Every operation inherits the same Trace ID.
+Supports nested spans for hierarchical tracing.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class Span:
+    """A single span in a trace."""
+    
+    span_id: str = field(default_factory=lambda: f"span-{uuid4().hex[:12]}")
+    trace_id: str = ""
+    parent_span_id: str | None = None
+    name: str = ""
+    component: str = ""
+    start_time: float = field(default_factory=time.monotonic)
+    end_time: float | None = None
+    status: str = "ok"  # ok | error | cancelled
+    attributes: dict[str, Any] = field(default_factory=dict)
+    events: list[dict[str, Any]] = field(default_factory=list)
+    
+    def finish(self, status: str = "ok") -> None:
+        self.end_time = time.monotonic()
+        self.status = status
+    
+    @property
+    def duration_ms(self) -> float:
+        if self.end_time is None:
+            return (time.monotonic() - self.start_time) * 1000
+        return (self.end_time - self.start_time) * 1000
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "span_id": self.span_id,
+            "trace_id": self.trace_id,
+            "parent_span_id": self.parent_span_id,
+            "name": self.name,
+            "component": self.component,
+            "duration_ms": round(self.duration_ms, 2),
+            "status": self.status,
+            "attributes": self.attributes,
+            "events": self.events,
+        }
+
+
+@dataclass
+class Trace:
+    """A complete trace of a request."""
+    
+    trace_id: str = field(default_factory=lambda: f"trace-{uuid4().hex[:12]}")
+    name: str = ""
+    start_time: float = field(default_factory=time.monotonic)
+    end_time: float | None = None
+    spans: list[Span] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def finish(self) -> None:
+        self.end_time = time.monotonic()
+    
+    @property
+    def duration_ms(self) -> float:
+        if self.end_time is None:
+            return (time.monotonic() - self.start_time) * 1000
+        return (self.end_time - self.start_time) * 1000
+    
+    def add_span(self, name: str, component: str = "", parent_span_id: str | None = None) -> Span:
+        span = Span(
+            trace_id=self.trace_id,
+            parent_span_id=parent_span_id,
+            name=name,
+            component=component,
+        )
+        self.spans.append(span)
+        return span
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "trace_id": self.trace_id,
+            "name": self.name,
+            "duration_ms": round(self.duration_ms, 2),
+            "span_count": len(self.spans),
+            "spans": [s.to_dict() for s in self.spans],
+            "metadata": self.metadata,
+        }
+
+
+class Tracer:
+    """Distributed tracing manager.
+    
+    Responsibilities:
+    - Create and manage traces
+    - Create and manage spans
+    - Track nested span relationships
+    """
+    
+    def __init__(self):
+        self._traces: dict[str, Trace] = {}
+        self._current_trace: Trace | None = None
+        self._current_span: Span | None = None
+    
+    def start_trace(self, name: str = "", **metadata: Any) -> Trace:
+        """Start a new trace."""
+        trace = Trace(name=name, metadata=metadata)
+        self._traces[trace.trace_id] = trace
+        self._current_trace = trace
+        return trace
+    
+    def start_span(self, name: str, component: str = "", **attributes: Any) -> Span:
+        """Start a new span within the current trace."""
+        if self._current_trace is None:
+            self.start_trace()
+        
+        parent_id = self._current_span.span_id if self._current_span else None
+        span = self._current_trace.add_span(
+            name=name,
+            component=component,
+            parent_span_id=parent_id,
+        )
+        span.attributes.update(attributes)
+        self._current_span = span
+        return span
+    
+    def finish_span(self, status: str = "ok") -> None:
+        """Finish the current span."""
+        if self._current_span:
+            self._current_span.finish(status)
+            # Move to parent span
+            if self._current_trace:
+                for s in reversed(self._current_trace.spans):
+                    if s.span_id == self._current_span.parent_span_id:
+                        self._current_span = s
+                        return
+            self._current_span = None
+    
+    def finish_trace(self) -> None:
+        """Finish the current trace."""
+        if self._current_trace:
+            self._current_trace.finish()
+            self._current_trace = None
+            self._current_span = None
+    
+    def get_trace(self, trace_id: str) -> Trace | None:
+        return self._traces.get(trace_id)
+    
+    def get_current_trace(self) -> Trace | None:
+        return self._current_trace
+    
+    def summary(self) -> dict:
+        return {
+            "total_traces": len(self._traces),
+            "current_trace": self._current_trace.trace_id if self._current_trace else None,
+        }

monkeybrain_introspection-1.0.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: monkeybrain-introspection
+Version: 1.0.0
+Summary: MonkeyBrain Introspection — Lemon observability layer for the Cognitive Operating System
+Author: Prashun Javeri
+License: Proprietary
+Keywords: observability,tracing,metrics,logging,health,alerting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# MonkeyBrain Introspection
+
+Lemon observability layer for the MonkeyBrain Cognitive Operating System.
+
+## Features
+
+- **Lemon** — unified observability facade
+- **Tracer** — distributed tracing with traces and spans
+- **MetricsCollector** — counters, gauges, and histograms
+- **StructuredLogger** — JSON structured logging with trace enrichment
+- **HealthMonitor** — health checks (healthy, degraded, unhealthy)
+- **AlertManager** — alert rules, firing, and resolution
+
+## Installation
+
+```bash
+pip install monkeybrain-introspection
+```
+
+## Quick Start
+
+```python
+from introspection import Lemon
+
+lemon = Lemon()
+lemon.start_trace("my-operation")
+# ... do work ...
+lemon.finish_trace()
+```
+
+## License
+
+Proprietary

monkeybrain_introspection-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+introspection/__init__.py,sha256=D8jRsv2OeQ5mAss92_KxAjS0lVITRv1W2YSkAgoR28w,1021
+introspection/alerting.py,sha256=x-eUmT3WaC1RFjS4yH1P98ELZ4ftbk7Lzx5aKwqNw0k,4011
+introspection/health.py,sha256=ngv5IV68JwIkMJYz78E-S3QZyLl6aob0aFsJi_PeMWE,3158
+introspection/lemon.py,sha256=8LPut0ZJtJ5PmTZQIyqeusPSy8jB7cxntztO2R11_o4,9461
+introspection/metrics.py,sha256=Kh2-PmPIbN_ePeeNU9P_KnGaJy_7cnRtMPV94SulMSM,4078
+introspection/structured_logging.py,sha256=IWOjyoMIyc1IBPrRh9V161pPcBlKUM8sejRz4RHgQlw,4566
+introspection/tracing.py,sha256=V3WAJxQP3vxt2FWQybJ5eATsHZPq_DiJf9SK2-caggc,5265
+monkeybrain_introspection-1.0.0.dist-info/METADATA,sha256=jTuJTTtSdVq6c3WyqLjuomumG36ZKx3_5-Ku2r7wC50,1524
+monkeybrain_introspection-1.0.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+monkeybrain_introspection-1.0.0.dist-info/top_level.txt,sha256=3RJ-vMpsRDQgpwxiTqt2ialeS0MJKPFWMwcU-JwGycs,14
+monkeybrain_introspection-1.0.0.dist-info/RECORD,,

monkeybrain_introspection-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

monkeybrain_introspection-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+introspection