hypermind 0.11.0__py3-none-any.whl

hypermind/observability/recorder.py

@@ -0,0 +1,344 @@
+"""Structured log recorder + Prometheus-shape counters.
+
+Mandated log fields (spec/13-observability.md):
+    ts_hlc, ts_wall, namespace, agent_id, event_type, kid, trace_id,
+    span_id, parent_span_id, key_fingerprint, sig_alg, peer_id, severity
+
+Mandated counters:
+    hypermind_seal_total{namespace, topic, result}
+    hypermind_dispute_open_total
+    hypermind_errors_total{class}
+    ...
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+import uuid
+from collections import Counter, deque
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+
+DEFAULT_MAX_RECORDS = 10_000
+
+
+@dataclass
+class LogRecord:
+    ts_wall_ms: int
+    ts_hlc: str
+    namespace: str
+    agent_id: str
+    event_type: str
+    severity: str
+    fields: dict[str, Any] = field(default_factory=dict)
+    namespace_id: str | None = None
+
+
+class Recorder:
+    """Thread-safe in-process recorder used by tests + by the runtime.
+
+    Records are kept in a bounded ring buffer (``maxlen=max_records``) so
+    long-running processes cannot leak memory through the global recorder.
+    When the buffer is full, the oldest record is evicted and
+    ``records_dropped_total`` is incremented.
+    """
+
+    def __init__(
+        self,
+        max_records: int = DEFAULT_MAX_RECORDS,
+        *,
+        namespace_id: str | None = None,
+        parent: Recorder | None = None,
+    ) -> None:
+        self._max_records = max_records
+        self.records: deque[LogRecord] = deque(maxlen=max_records)
+        self.counters: Counter[str] = Counter()
+        self.records_dropped_total: int = 0
+        self.namespace_id: str | None = namespace_id
+        # WS-G v0.7: scoped recorders also fan out to ``parent`` (the
+        # process-global recorder) so operators / tests reading the
+        # global view still see all activity. Parent never points back.
+        self._parent: Recorder | None = parent
+        self._lock = threading.Lock()
+        # v0.6.1 — tail() consumers. Each consumer gets its own asyncio.Event
+        # set on every emit() so they can wake up and read new records.
+        # We don't keep per-consumer indexes here; tail() owns the head pointer.
+        self._tail_consumers: list[asyncio.Event] = []
+
+    @classmethod
+    def scoped(
+        cls,
+        namespace_id: str,
+        *,
+        max_records: int = DEFAULT_MAX_RECORDS,
+        parent: Recorder | None = None,
+    ) -> Recorder:
+        """Return a fresh Recorder tagged with the given namespace.
+
+        v0.7 wires per-``_NamespaceWorld`` recorders through this
+        factory. ``parent`` defaults to the process-global recorder so
+        the global view continues to receive every emission for
+        operator/test compatibility.
+        """
+        if parent is None:
+            parent = _GLOBAL
+        return cls(max_records=max_records, namespace_id=namespace_id, parent=parent)
+
+    def emit(
+        self,
+        *,
+        namespace: str,
+        agent_id: str,
+        event_type: str,
+        severity: str = "info",
+        ts_hlc: str = "",
+        **fields: Any,
+    ) -> None:
+        record = LogRecord(
+            ts_wall_ms=int(time.time() * 1000),
+            ts_hlc=ts_hlc,
+            namespace=namespace,
+            agent_id=agent_id,
+            event_type=event_type,
+            severity=severity,
+            fields=dict(fields),
+            namespace_id=self.namespace_id,
+        )
+        with self._lock:
+            if len(self.records) == self._max_records:
+                # deque is full; appending will evict the oldest record.
+                self.records_dropped_total += 1
+            self.records.append(record)
+            consumers = list(self._tail_consumers)
+        # Wake any tail() consumers (best-effort; we never block emit()).
+        for ev in consumers:
+            try:
+                ev.set()
+            except RuntimeError:  # consumer's loop closed; pruned next tail()
+                pass
+        # Fan-out to parent (e.g. process-global) for unified visibility.
+        if self._parent is not None:
+            self._parent.emit(
+                namespace=namespace,
+                agent_id=agent_id,
+                event_type=event_type,
+                severity=severity,
+                ts_hlc=ts_hlc,
+                **fields,
+            )
+
+    async def tail(self, *, replay: bool = True) -> AsyncIterator[LogRecord]:
+        """Async generator: yields new LogRecords as they arrive.
+
+        ``replay=True`` (default) yields records that were already in the
+        buffer before the consumer subscribed. Set ``replay=False`` to
+        only see records emitted after subscription.
+
+        Each consumer gets its own asyncio.Event; emit() sets all
+        consumer events. Cancellation-safe.
+        """
+        ev = asyncio.Event()
+        with self._lock:
+            self._tail_consumers.append(ev)
+            head = 0 if replay else len(self.records)
+        try:
+            while True:
+                with self._lock:
+                    snapshot = list(self.records)
+                # The deque may have evicted entries below our head.
+                # Skip ahead to the current size if we've fallen behind.
+                if head > len(snapshot):
+                    head = len(snapshot)
+                while head < len(snapshot):
+                    yield snapshot[head]
+                    head += 1
+                # Wait for the next emit().
+                ev.clear()
+                await ev.wait()
+        finally:
+            with self._lock:
+                try:
+                    self._tail_consumers.remove(ev)
+                except ValueError:
+                    pass
+
+    def incr(self, metric: str, *, by: float = 1.0, **labels: Any) -> None:
+        key = metric
+        if labels:
+            label_str = ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+            key = f"{metric}{{{label_str}}}"
+        with self._lock:
+            self.counters[key] += by
+        if self._parent is not None:
+            self._parent.incr(metric, by=by, **labels)
+
+    def trace_id(self) -> str:
+        return uuid.uuid4().hex
+
+    def filter(self, *, event_type: str | None = None) -> list[LogRecord]:
+        with self._lock:
+            return [r for r in self.records if event_type is None or r.event_type == event_type]
+
+    def get_metrics(self) -> dict[str, Any]:
+        """Snapshot of recorder-internal metrics.
+
+        Exposes ``records_dropped_total`` so operators can detect when the
+        bounded ring buffer is dropping log lines.
+        """
+        with self._lock:
+            return {
+                "records_total": len(self.records),
+                "records_max": self._max_records,
+                "records_dropped_total": self.records_dropped_total,
+                "counters": dict(self.counters),
+                "namespace_id": self.namespace_id,
+            }
+
+    def reset(self) -> None:
+        with self._lock:
+            # ``deque.clear()`` preserves the maxlen invariant.
+            self.records.clear()
+            self.counters.clear()
+            self.records_dropped_total = 0
+
+    # ------------------------------------------------------------------ #
+    # OpenTelemetry integration (v0.8 production profile).
+    #
+    # The wrapped Recorder transparently forwards every public verb to
+    # the underlying instance and, for the agent verbs the spec calls
+    # out (``publish_claim``, ``consult``, ``dispute``, ``synthesize``,
+    # ``oracle_resolve``), also opens a span on the supplied tracer.
+    #
+    # If ``opentelemetry`` is not installed we emit a warning via the
+    # standard ``warnings`` module and return ``self`` unchanged so
+    # callers don't have to special-case the import path.
+    # ------------------------------------------------------------------ #
+    def with_otel(self, tracer_provider: Any | None = None) -> Recorder:
+        """Wrap this Recorder so agent verbs emit OTel spans.
+
+        ``tracer_provider`` is an ``opentelemetry.trace.TracerProvider``
+        instance (typed as ``Any`` here so we can keep the OTel import
+        optional). If None, the global provider is used.
+        """
+        try:
+            from opentelemetry import trace as _otel_trace  # noqa: F401
+        except ImportError:
+            import warnings
+
+            warnings.warn(
+                "with_otel: opentelemetry not installed; "
+                "install hypermind[otel] to enable span emission. "
+                "Returning the un-wrapped Recorder.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return self
+
+        return _OtelRecorder(self, tracer_provider)
+
+
+_GLOBAL = Recorder()
+
+
+# OTel verbs the spec mandates spans for. Kept module-level so it's
+# easy to extend without touching the wrapper class.
+_OTEL_TRACED_EVENTS: frozenset[str] = frozenset(
+    {"publish_claim", "consult", "dispute", "synthesize", "oracle_resolve"}
+)
+
+
+class _OtelRecorder(Recorder):
+    """Recorder facade that forwards to the wrapped instance and emits
+    OTel spans for traced agent verbs.
+
+    The wrapper subclasses ``Recorder`` so it satisfies the same
+    structural contract used everywhere else in the SDK; the parent
+    state (``records``, ``counters``, etc.) is intentionally unused —
+    every public method delegates to ``_inner``.
+    """
+
+    def __init__(self, inner: Recorder, tracer_provider: Any | None) -> None:
+        # Bypass Recorder.__init__ — we do not want a second buffer.
+        # We still need a lock placeholder so the parent class's
+        # ``__repr__`` (if any) doesn't blow up.
+        self._inner = inner
+        from opentelemetry import trace as _otel_trace
+
+        if tracer_provider is None:
+            self._tracer = _otel_trace.get_tracer("hypermind")
+        else:
+            self._tracer = tracer_provider.get_tracer("hypermind")
+
+    # ---- delegation -------------------------------------------------- #
+    @property
+    def records(self) -> deque[LogRecord]:  # type: ignore[override]
+        return self._inner.records
+
+    @property
+    def counters(self) -> Counter[str]:  # type: ignore[override]
+        return self._inner.counters
+
+    @property
+    def records_dropped_total(self) -> int:  # type: ignore[override]
+        return self._inner.records_dropped_total
+
+    @property
+    def namespace_id(self) -> str | None:  # type: ignore[override]
+        return self._inner.namespace_id
+
+    def emit(
+        self,
+        *,
+        namespace: str,
+        agent_id: str,
+        event_type: str,
+        severity: str = "info",
+        ts_hlc: str = "",
+        **fields: Any,
+    ) -> None:
+        if event_type in _OTEL_TRACED_EVENTS:
+            with self._tracer.start_as_current_span(f"hypermind.{event_type}") as span:
+                span.set_attribute("hypermind.namespace", namespace)
+                span.set_attribute("hypermind.agent_id", agent_id)
+                span.set_attribute("hypermind.severity", severity)
+                if ts_hlc:
+                    span.set_attribute("hypermind.hlc", ts_hlc)
+                self._inner.emit(
+                    namespace=namespace,
+                    agent_id=agent_id,
+                    event_type=event_type,
+                    severity=severity,
+                    ts_hlc=ts_hlc,
+                    **fields,
+                )
+        else:
+            self._inner.emit(
+                namespace=namespace,
+                agent_id=agent_id,
+                event_type=event_type,
+                severity=severity,
+                ts_hlc=ts_hlc,
+                **fields,
+            )
+
+    def incr(self, metric: str, *, by: float = 1.0, **labels: Any) -> None:
+        self._inner.incr(metric, by=by, **labels)
+
+    def trace_id(self) -> str:
+        return self._inner.trace_id()
+
+    def filter(self, *, event_type: str | None = None) -> list[LogRecord]:
+        return self._inner.filter(event_type=event_type)
+
+    def get_metrics(self) -> dict[str, Any]:
+        return self._inner.get_metrics()
+
+    def reset(self) -> None:
+        self._inner.reset()
+
+
+def get_recorder() -> Recorder:
+    return _GLOBAL