crprotocol 2.0.0__py3-none-any.whl

crp/observability/__init__.py

@@ -0,0 +1,30 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Observability — events, metrics, audit log, quality reporting, telemetry."""
+
+from crp.observability.audit import AuditLog
+from crp.observability.events import ALL_EVENT_TYPES, CRPEvent, EventEmitter
+from crp.observability.metrics import (
+    ExportFormat,
+    HealthMonitor,
+    HealthStatus,
+    MetricsExporter,
+)
+from crp.observability.quality import QualityReport, QualityReporter, QualityTier
+from crp.observability.telemetry import TelemetryWriter, WindowTelemetry
+
+__all__ = [
+    "ALL_EVENT_TYPES",
+    "AuditLog",
+    "CRPEvent",
+    "EventEmitter",
+    "ExportFormat",
+    "HealthMonitor",
+    "HealthStatus",
+    "MetricsExporter",
+    "QualityReport",
+    "QualityReporter",
+    "QualityTier",
+    "TelemetryWriter",
+    "WindowTelemetry",
+]

crp/observability/audit.py

@@ -0,0 +1,118 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Audit log — reconstruct sessions from recorded events (§8.9).
+
+AuditLog stores every emitted CRPEvent and provides query helpers to:
+  * Replay the full timeline for a session or time range.
+  * Filter by event type.
+  * Reconstruct how many facts were created / superseded / archived.
+
+Design goals:
+  * In-memory by default (no external DB).
+  * Thread-safe append + query.
+  * Easy to hook into EventEmitter via ``emitter.on_all(audit.record)``.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from crp.observability.events import CRPEvent
+
+
+class AuditLog:
+    """Immutable append-only event log with query support.
+
+    Usage::
+
+        audit = AuditLog()
+        emitter.on_all(audit.record)   # auto-capture every event
+        ...
+        timeline = audit.query(session_id="abc")
+        fact_events = audit.query(event_type="fact.created")
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._events: list[CRPEvent] = []
+
+    # -- recording --------------------------------------------------------
+
+    def record(self, event: CRPEvent) -> None:
+        """Append an event (thread-safe, never raises)."""
+        with self._lock:
+            self._events.append(event)
+
+    # -- querying ---------------------------------------------------------
+
+    def query(
+        self,
+        *,
+        event_type: str | None = None,
+        session_id: str | None = None,
+        since: float | None = None,
+        until: float | None = None,
+    ) -> list[CRPEvent]:
+        """Return events matching all supplied filters.
+
+        Args:
+            event_type: Exact event type string (e.g. "dispatch.completed").
+            session_id: Match events whose ``data["session_id"]`` equals this.
+            since: Only events with ``timestamp >= since``.
+            until: Only events with ``timestamp <= until``.
+        """
+        with self._lock:
+            results: list[CRPEvent] = []
+            for ev in self._events:
+                if event_type is not None and ev.event_type != event_type:
+                    continue
+                if session_id is not None and ev.data.get("session_id") != session_id:
+                    continue
+                if since is not None and ev.timestamp < since:
+                    continue
+                if until is not None and ev.timestamp > until:
+                    continue
+                results.append(ev)
+            return results
+
+    def reconstruct_session(self, session_id: str) -> dict[str, Any]:
+        """Build a summary dict for *session_id* from the event stream.
+
+        Returns a dict with keys:
+          * ``session_id``
+          * ``events`` — full ordered list of events (as dicts).
+          * ``dispatch_count`` — number of dispatch.completed events.
+          * ``facts_created`` — count of fact.created events.
+          * ``facts_superseded`` — count of fact.superseded events.
+          * ``duration_s`` — seconds between first and last event.
+        """
+        events = self.query(session_id=session_id)
+        dispatch_count = sum(1 for e in events if e.event_type == "dispatch.completed")
+        facts_created = sum(1 for e in events if e.event_type == "fact.created")
+        facts_superseded = sum(1 for e in events if e.event_type == "fact.superseded")
+
+        if events:
+            duration = events[-1].timestamp - events[0].timestamp
+        else:
+            duration = 0.0
+
+        return {
+            "session_id": session_id,
+            "events": [e.to_dict() for e in events],
+            "dispatch_count": dispatch_count,
+            "facts_created": facts_created,
+            "facts_superseded": facts_superseded,
+            "duration_s": round(duration, 3),
+        }
+
+    @property
+    def count(self) -> int:
+        """Total number of recorded events."""
+        with self._lock:
+            return len(self._events)
+
+    def clear(self) -> None:
+        """Remove all stored events (useful in testing)."""
+        with self._lock:
+            self._events.clear()

crp/observability/events.py

@@ -0,0 +1,233 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Event emitter for CRP observability — structured event bus (§09 §9.5).
+
+EventEmitter is a lightweight publish/subscribe bus that lets CLI,
+diagnostics, and future metrics sinks observe protocol activity
+without coupling to internals.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger("crp.events")
+
+
+# ---------------------------------------------------------------------------
+# Canonical event type constants (§8.9) — 30+ named event types.
+#
+# Naming convention: ``<domain>.<action>``  (e.g. "session.created").
+# All lowercase, dots as separators, past-tense verbs.
+# ---------------------------------------------------------------------------
+
+# Session lifecycle
+SESSION_CREATED = "session.created"
+SESSION_CLOSED = "session.closed"
+SESSION_EXPIRED = "session.expired"
+SESSION_RESTORED = "session.restored"
+
+# Dispatch / window lifecycle
+DISPATCH_STARTED = "dispatch.started"
+DISPATCH_COMPLETED = "dispatch.completed"
+DISPATCH_FAILED = "dispatch.failed"
+WINDOW_OPENED = "window.opened"
+WINDOW_COMPLETED = "window.completed"
+WINDOW_CONTINUED = "window.continued"
+WINDOW_CANCELLED = "window.cancelled"
+
+# Extraction
+FACT_CREATED = "fact.created"
+FACT_SUPERSEDED = "fact.superseded"
+FACT_COMPACTED = "fact.compacted"
+FACT_ARCHIVED = "fact.archived"
+FACT_RESTORED = "fact.restored"
+EXTRACTION_COMPLETED = "extraction.completed"
+
+# Ingestion
+INGEST_STARTED = "ingest.started"
+INGEST_COMPLETED = "ingest.completed"
+
+# Envelope / context
+ENVELOPE_BUILT = "envelope.built"
+ENVELOPE_SATURATED = "envelope.saturated"  # saturation > 0.95
+CONTEXT_OVERFLOW = "context.overflow"
+CONTEXT_TRUNCATED = "context.truncated"
+
+# Budget / cost
+BUDGET_WARNING = "budget.warning"
+BUDGET_EXHAUSTED = "budget.exhausted"
+OVERHEAD_SHED = "overhead.shed"
+COST_RECORDED = "cost.recorded"
+
+# Provider / LLM
+PROVIDER_CONNECTED = "provider.connected"
+PROVIDER_DISCONNECTED = "provider.disconnected"
+PROVIDER_ERROR = "provider.error"
+PROVIDER_RETRY = "provider.retry"
+
+# Quality
+QUALITY_ASSESSED = "quality.assessed"
+QUALITY_DEGRADED = "quality.degraded"
+
+# Security
+AUTH_SUCCESS = "auth.success"
+AUTH_FAILURE = "auth.failure"
+
+# Health
+HEALTH_CHECK_PASSED = "health.check.passed"
+HEALTH_CHECK_FAILED = "health.check.failed"
+
+# Startup
+STARTUP_COMPLETED = "startup.completed"
+STARTUP_FAILED = "startup.failed"
+
+# Collect all event types for programmatic access (useful for audit/metrics).
+ALL_EVENT_TYPES: frozenset[str] = frozenset([
+    SESSION_CREATED, SESSION_CLOSED, SESSION_EXPIRED, SESSION_RESTORED,
+    DISPATCH_STARTED, DISPATCH_COMPLETED, DISPATCH_FAILED,
+    WINDOW_OPENED, WINDOW_COMPLETED, WINDOW_CONTINUED, WINDOW_CANCELLED,
+    FACT_CREATED, FACT_SUPERSEDED, FACT_COMPACTED, FACT_ARCHIVED,
+    FACT_RESTORED, EXTRACTION_COMPLETED,
+    INGEST_STARTED, INGEST_COMPLETED,
+    ENVELOPE_BUILT, ENVELOPE_SATURATED, CONTEXT_OVERFLOW, CONTEXT_TRUNCATED,
+    BUDGET_WARNING, BUDGET_EXHAUSTED, OVERHEAD_SHED, COST_RECORDED,
+    PROVIDER_CONNECTED, PROVIDER_DISCONNECTED, PROVIDER_ERROR, PROVIDER_RETRY,
+    QUALITY_ASSESSED, QUALITY_DEGRADED,
+    AUTH_SUCCESS, AUTH_FAILURE,
+    HEALTH_CHECK_PASSED, HEALTH_CHECK_FAILED,
+    STARTUP_COMPLETED, STARTUP_FAILED,
+])
+
+# ---------------------------------------------------------------------------
+# Event dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CRPEvent:
+    """Single protocol event."""
+
+    event_type: str  # e.g. "session.created", "dispatch.started", "window.completed"
+    timestamp: float = field(default_factory=time.time)
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_type": self.event_type,
+            "timestamp": self.timestamp,
+            "data": self.data,
+        }
+
+
+# Listener type: callable that receives one CRPEvent.
+Listener = Callable[[CRPEvent], None]
+
+
+# ---------------------------------------------------------------------------
+# EventEmitter
+# ---------------------------------------------------------------------------
+
+
+class EventEmitter:
+    """Simple synchronous event bus.
+
+    Usage::
+
+        emitter = EventEmitter()
+        emitter.on("dispatch.started", my_callback)
+        emitter.emit("dispatch.started", {"task": "..."})
+    """
+
+    def __init__(self, *, max_listeners_per_event: int = 100) -> None:
+        self._listeners: dict[str, list[Listener]] = {}
+        self._global_listeners: list[Listener] = []
+        self._started = False
+        self._max_listeners = max_listeners_per_event
+
+    # -- lifecycle --------------------------------------------------------
+
+    def start(self) -> None:
+        """Mark the emitter as active (startup step 6)."""
+        self._started = True
+        logger.debug("EventEmitter started")
+
+    def stop(self) -> None:
+        """Stop accepting and delivering events."""
+        self._started = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._started
+
+    # -- subscription -----------------------------------------------------
+
+    def on(self, event_type: str, listener: Listener) -> None:
+        """Subscribe *listener* to *event_type*.
+
+        Deduplicates listeners and enforces a per-event cap (§audit4 REL-M2).
+        """
+        listeners = self._listeners.setdefault(event_type, [])
+        if listener in listeners:
+            return
+        if len(listeners) >= self._max_listeners:
+            logger.warning(
+                "Max listeners (%d) reached for event '%s' — ignoring",
+                self._max_listeners, event_type,
+            )
+            return
+        listeners.append(listener)
+
+    def on_all(self, listener: Listener) -> None:
+        """Subscribe *listener* to every event type."""
+        if listener in self._global_listeners:
+            return
+        if len(self._global_listeners) >= self._max_listeners:
+            logger.warning(
+                "Max global listeners (%d) reached — ignoring",
+                self._max_listeners,
+            )
+            return
+        self._global_listeners.append(listener)
+
+    def off(self, event_type: str, listener: Listener) -> bool:
+        """Remove a specific listener. Returns True if removed."""
+        listeners = self._listeners.get(event_type, [])
+        try:
+            listeners.remove(listener)
+            return True
+        except ValueError:
+            return False
+
+    # -- emission ---------------------------------------------------------
+
+    def emit(self, event_type: str, data: dict[str, Any] | None = None) -> None:
+        """Emit an event to all matching listeners.
+
+        If the emitter has not been started, events are silently dropped.
+        Listener exceptions are logged but never propagate.
+        """
+        if not self._started:
+            return
+        event = CRPEvent(event_type=event_type, data=data or {})
+
+        for listener in self._listeners.get(event_type, []):
+            try:
+                listener(event)
+            except Exception:
+                logger.exception("Listener error for %s", event_type)
+
+        for listener in self._global_listeners:
+            try:
+                listener(event)
+            except Exception:
+                logger.exception("Global listener error for %s", event_type)
+
+    @property
+    def listener_count(self) -> int:
+        total = sum(len(v) for v in self._listeners.values())
+        return total + len(self._global_listeners)

crp/observability/metrics.py

@@ -0,0 +1,264 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Metrics export and health monitoring (§8.9, §05).
+
+MetricsExporter  — collects counters/gauges and exports as Prometheus,
+                   OTLP-compatible JSON, or plain JSON.
+HealthMonitor    — liveness + readiness probes for the CRP runtime.
+
+Design goals:
+  * Zero external dependencies (no prometheus_client, no opentelemetry).
+  * Thread-safe counters via stdlib threading.Lock.
+  * Easy to read: one class per concern, plain dicts for state.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MetricsExporter (§9.2)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class ExportFormat(Enum):
+    """Supported output formats."""
+
+    JSON = "json"
+    PROMETHEUS = "prometheus"
+    OTLP_JSON = "otlp_json"
+
+
+class MetricsExporter:
+    """Collects CRP metrics (counters, gauges, histograms) and exports them.
+
+    Usage::
+
+        mx = MetricsExporter()
+        mx.incr("dispatch.count")
+        mx.gauge("overhead.ratio", 0.12)
+        mx.observe("dispatch.latency_ms", 42.3)
+        print(mx.export(ExportFormat.JSON))
+    """
+
+    _MAX_HISTOGRAM_SIZE = 10_000  # Cap per-metric observations to prevent unbounded growth
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # Counters: monotonically increasing integers.
+        self._counters: dict[str, int] = {}
+        # Gauges: point-in-time values that can go up or down.
+        self._gauges: dict[str, float] = {}
+        # Histograms: list of observed values (for percentiles).
+        self._histograms: dict[str, list[float]] = {}
+
+    # -- recording --------------------------------------------------------
+
+    def incr(self, name: str, delta: int = 1) -> None:
+        """Increment a counter by *delta* (default 1)."""
+        with self._lock:
+            self._counters[name] = self._counters.get(name, 0) + delta
+
+    def gauge(self, name: str, value: float) -> None:
+        """Set a gauge to the current *value*."""
+        with self._lock:
+            self._gauges[name] = value
+
+    def observe(self, name: str, value: float) -> None:
+        """Record an observation in a histogram bucket."""
+        with self._lock:
+            bucket = self._histograms.setdefault(name, [])
+            bucket.append(value)
+            if len(bucket) > self._MAX_HISTOGRAM_SIZE:
+                # Keep the most recent half to avoid repeated trimming
+                del bucket[: len(bucket) // 2]
+
+    # -- querying ---------------------------------------------------------
+
+    def get_counter(self, name: str) -> int:
+        with self._lock:
+            return self._counters.get(name, 0)
+
+    def get_gauge(self, name: str) -> float | None:
+        with self._lock:
+            return self._gauges.get(name)
+
+    def get_histogram(self, name: str) -> list[float]:
+        with self._lock:
+            return list(self._histograms.get(name, []))
+
+    # -- export -----------------------------------------------------------
+
+    def export(self, fmt: ExportFormat = ExportFormat.JSON) -> str:
+        """Export all metrics in the given format.
+
+        Supported:
+          * ``JSON``      — human-friendly nested dict.
+          * ``PROMETHEUS`` — text/plain Prometheus exposition format.
+          * ``OTLP_JSON``  — OpenTelemetry-compatible JSON envelope.
+        """
+        with self._lock:
+            counters = dict(self._counters)
+            gauges = dict(self._gauges)
+            histograms = {k: list(v) for k, v in self._histograms.items()}
+
+        if fmt == ExportFormat.JSON:
+            return self._export_json(counters, gauges, histograms)
+        if fmt == ExportFormat.PROMETHEUS:
+            return self._export_prometheus(counters, gauges, histograms)
+        if fmt == ExportFormat.OTLP_JSON:
+            return self._export_otlp(counters, gauges, histograms)
+        raise ValueError(f"Unknown export format: {fmt}")
+
+    def reset(self) -> None:
+        """Clear all collected metrics."""
+        with self._lock:
+            self._counters.clear()
+            self._gauges.clear()
+            self._histograms.clear()
+
+    # -- private helpers --------------------------------------------------
+
+    @staticmethod
+    def _export_json(
+        counters: dict[str, int],
+        gauges: dict[str, float],
+        histograms: dict[str, list[float]],
+    ) -> str:
+        return json.dumps(
+            {"counters": counters, "gauges": gauges, "histograms": histograms},
+            indent=2,
+        )
+
+    @staticmethod
+    def _export_prometheus(
+        counters: dict[str, int],
+        gauges: dict[str, float],
+        histograms: dict[str, list[float]],
+    ) -> str:
+        """Prometheus text exposition: each metric on its own line."""
+        lines: list[str] = []
+        for name, value in sorted(counters.items()):
+            safe = name.replace(".", "_")
+            lines.append(f"# TYPE crp_{safe} counter")
+            lines.append(f"crp_{safe} {value}")
+        for name, value in sorted(gauges.items()):  # type: ignore[assignment]
+            safe = name.replace(".", "_")
+            lines.append(f"# TYPE crp_{safe} gauge")
+            lines.append(f"crp_{safe} {value}")
+        for name, values in sorted(histograms.items()):
+            safe = name.replace(".", "_")
+            if values:
+                lines.append(f"# TYPE crp_{safe} summary")
+                lines.append(f"crp_{safe}_count {len(values)}")
+                lines.append(f"crp_{safe}_sum {sum(values)}")
+        return "\n".join(lines) + "\n" if lines else ""
+
+    @staticmethod
+    def _export_otlp(
+        counters: dict[str, int],
+        gauges: dict[str, float],
+        histograms: dict[str, list[float]],
+    ) -> str:
+        """OTLP-compatible JSON envelope (simplified)."""
+        metrics: list[dict[str, Any]] = []
+        for name, value in counters.items():
+            metrics.append({
+                "name": f"crp.{name}",
+                "type": "sum",
+                "data_points": [{"value": value, "time_unix_nano": int(time.time() * 1e9)}],
+            })
+        for name, value in gauges.items():  # type: ignore[assignment]
+            metrics.append({
+                "name": f"crp.{name}",
+                "type": "gauge",
+                "data_points": [{"value": value, "time_unix_nano": int(time.time() * 1e9)}],
+            })
+        for name, values in histograms.items():
+            metrics.append({
+                "name": f"crp.{name}",
+                "type": "histogram",
+                "data_points": [{
+                    "count": len(values),
+                    "sum": sum(values),
+                    "time_unix_nano": int(time.time() * 1e9),
+                }],
+            })
+        envelope = {
+            "resource_metrics": [{
+                "scope_metrics": [{"metrics": metrics}],
+            }],
+        }
+        return json.dumps(envelope, indent=2)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# HealthMonitor (§9.7)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+@dataclass
+class HealthStatus:
+    """Result of a health probe."""
+
+    alive: bool = True
+    ready: bool = True
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"alive": self.alive, "ready": self.ready, "details": self.details}
+
+
+class HealthMonitor:
+    """Liveness and readiness probes for the CRP runtime.
+
+    Register named checks with ``add_check(name, callable)``.  Each check
+    returns ``True`` (healthy) or ``False`` (unhealthy).
+
+    Usage::
+
+        hm = HealthMonitor()
+        hm.add_check("emitter", lambda: emitter.is_running)
+        hm.add_check("warm_store", lambda: warm_store is not None)
+        status = hm.probe()
+        assert status.alive
+    """
+
+    def __init__(self) -> None:
+        self._checks: dict[str, Any] = {}  # name → callable() → bool
+        self._alive = True
+
+    def add_check(self, name: str, check_fn: Any) -> None:
+        """Register a readiness check."""
+        self._checks[name] = check_fn
+
+    def remove_check(self, name: str) -> bool:
+        """Remove a check. Returns True if it existed."""
+        return self._checks.pop(name, None) is not None
+
+    def set_alive(self, alive: bool) -> None:
+        """Manually mark the runtime as alive or dead (e.g. on shutdown)."""
+        self._alive = alive
+
+    def probe(self) -> HealthStatus:
+        """Run all registered checks and return combined status.
+
+        Liveness: ``True`` unless ``set_alive(False)`` was called.
+        Readiness: ``True`` only if *all* registered checks pass.
+        """
+        details: dict[str, Any] = {}
+        all_ready = True
+        for name, fn in self._checks.items():
+            try:
+                ok = bool(fn())
+            except Exception:
+                ok = False
+            details[name] = ok
+            if not ok:
+                all_ready = False
+        return HealthStatus(alive=self._alive, ready=all_ready, details=details)