agentsonar 0.1.2__py3-none-any.whl

agentsonar/__init__.py

@@ -0,0 +1,52 @@
+"""
+AgentSonar — detect coordination failures in multi-agent AI systems.
+
+Two lines to integrate:
+
+    # CrewAI
+    from agentsonar import AgentSonarListener
+    sonar = AgentSonarListener()
+    # ...run your crew normally.
+
+    # LangGraph / LangChain — option 1: pass the callback yourself
+    from agentsonar import AgentSonarCallback
+    result = graph.invoke(input, config={"callbacks": [AgentSonarCallback()]})
+
+    # LangGraph / LangChain — option 2: wrap the graph (auto-merges callbacks)
+    from agentsonar import monitor
+    graph = monitor(graph)
+    result = graph.invoke(input)                                # auto-monitored
+    result = graph.invoke(input, config={"callbacks": [my_cb]}) # my_cb preserved
+
+Detection and terminal output happen automatically. No config, no API
+keys, no accounts. Alerts stream to stderr and to timestamped log files
+(`agentsonar_*.log`) in the working directory.
+
+Public API:
+    AgentSonarListener  — CrewAI integration (requires `agentsonar[crewai]`)
+    AgentSonarCallback  — LangGraph/LangChain integration (requires `agentsonar[langgraph]`)
+    monitor             — LangGraph wrapper that auto-merges AgentSonar
+                          into the callback list without overriding existing
+                          user callbacks. Recommended when you already have
+                          your own callbacks configured.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# Everything below is the ONLY public surface. Framework integrations use
+# conditional imports for their underlying framework — they remain
+# importable even when the optional extra is not installed, and raise a
+# clear RuntimeError at instantiation time instead.
+from agentsonar._integrations.crewai_listener import AgentSonarListener
+from agentsonar._integrations.langgraph_callback import (
+    AgentSonarCallback,
+    monitor,
+)
+
+__all__ = [
+    "AgentSonarListener",
+    "AgentSonarCallback",
+    "monitor",
+    "__version__",
+]

agentsonar/_core/__init__.py

@@ -0,0 +1,6 @@
+"""
+AgentSonar core — internal detection engine.
+
+Not part of the public API. Consumers should import from `agentsonar`
+directly (AgentSonarListener, AgentSonarCallback).
+"""

agentsonar/_core/constants.py

@@ -0,0 +1,16 @@
+"""
+AgentSonar schema and detection constants.
+
+Token tracking, cost estimation, and velocity metrics are out of scope
+for v0.1.0. The schema intentionally omits these fields.
+"""
+from __future__ import annotations
+
+SCHEMA_VERSION = "0.1.0"
+
+# Default thresholds — may be overridden via DetectionEngine config dict
+DEFAULT_CYCLE_WARNING_ROTATIONS = 3
+DEFAULT_CYCLE_CRITICAL_ROTATIONS = 10
+DEFAULT_REPETITIVE_WARNING_COUNT = 5
+DEFAULT_REPETITIVE_CRITICAL_COUNT = 15
+DEFAULT_STALL_THRESHOLD_SECONDS = 300

agentsonar/_core/detectors/__init__.py

@@ -0,0 +1,22 @@
+"""
+Detection layer implementations. Internal — not part of the public API.
+
+Layer 1: SlidingWindowLimiter      — rate-limit circuit breaker
+Layer 2: ExponentialDecayDetector  — decay-weighted edge anomaly
+Layer 3: CycleDetector             — incremental cycle detection
+Layer 4: AlertStateManager         — alert state machine (WARNING → CRITICAL → RESOLVED)
+Layer 5: PeriodicSCCAnalyzer       — backup SCC sweep
+"""
+from agentsonar._core.detectors.alert_state import AlertStateManager
+from agentsonar._core.detectors.cycle_detector import CycleDetector
+from agentsonar._core.detectors.rate_limiter import SlidingWindowLimiter
+from agentsonar._core.detectors.repetitive_detector import ExponentialDecayDetector
+from agentsonar._core.detectors.scc_analyzer import PeriodicSCCAnalyzer
+
+__all__ = [
+    "AlertStateManager",
+    "CycleDetector",
+    "ExponentialDecayDetector",
+    "PeriodicSCCAnalyzer",
+    "SlidingWindowLimiter",
+]

agentsonar/_core/detectors/alert_state.py

@@ -0,0 +1,202 @@
+"""
+Layer 4: AlertStateManager — O(1) alert dedup / state machine.
+
+Progressive alert lifecycle with hysteresis recovery. Separated from the
+PeriodicSCCAnalyzer (Layer 5) because they have nothing to do with each
+other — one manages alert state, the other runs backup SCC sweeps.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentsonar._core.models import Alert
+
+
+@dataclass
+class _TrackedAlert:
+    fingerprint: tuple
+    state: str                      # "ACTIVE", "ESCALATED", "RESOLVED"
+    pattern: str                    # "cycle", "edge_anomaly", "scc_cycle"
+    current_rotations: int = 0
+    last_alert_rotations: int = 0
+    last_alert_time: float = 0.0
+    last_activity_time: float = 0.0
+    created_at: float = 0.0
+    alert_count: int = 0
+
+
+class AlertStateManager:
+    """Progressive alert state machine with hysteresis recovery.
+
+    Tracks each detected anomaly by fingerprint and manages transitions:
+      (new) → ACTIVE (WARNING) → ESCALATED (CRITICAL) → RESOLVED (INFO)
+                                         ↑ re-alerts every N rotations
+      RESOLVED → ACTIVE on regression
+
+    Args:
+        warning_threshold: Rotations/count to trigger first WARNING (default 5).
+        critical_threshold: Rotations/count to trigger CRITICAL (default 15).
+        re_alert_interval: After CRITICAL, re-alert every N additional rotations (default 30).
+        resolve_after_seconds: Quiet period before marking RESOLVED (default 60).
+    """
+
+    def __init__(
+        self,
+        warning_threshold: int = 5,
+        critical_threshold: int = 15,
+        re_alert_interval: int = 30,
+        resolve_after_seconds: float = 60.0,
+    ):
+        self.warning_threshold = warning_threshold
+        self.critical_threshold = critical_threshold
+        self.re_alert_interval = re_alert_interval
+        self.resolve_after_seconds = resolve_after_seconds
+        self._tracked: dict[tuple, _TrackedAlert] = {}
+
+    def process(
+        self,
+        fingerprint: tuple,
+        rotations: int,
+        pattern: str,
+        now: float,
+        extra_details: dict | None = None,
+    ) -> Alert | None:
+        """Feed a detection result into the state machine.
+
+        Returns an Alert if one should be emitted, None otherwise.
+        """
+        details = dict(extra_details or {})
+        details["fingerprint"] = fingerprint
+        details["rotations"] = rotations
+
+        tracked = self._tracked.get(fingerprint)
+
+        # --- New fingerprint ---
+        if tracked is None:
+            if rotations >= self.warning_threshold:
+                tracked = _TrackedAlert(
+                    fingerprint=fingerprint,
+                    state="ACTIVE",
+                    pattern=pattern,
+                    current_rotations=rotations,
+                    last_alert_rotations=rotations,
+                    last_alert_time=now,
+                    last_activity_time=now,
+                    created_at=now,
+                    alert_count=1,
+                )
+                self._tracked[fingerprint] = tracked
+                return Alert(
+                    pattern=pattern,
+                    severity="WARNING",
+                    details=details,
+                    timestamp=now,
+                )
+            return None
+
+        # --- Existing fingerprint ---
+        # NOTE: do NOT mutate `tracked.current_rotations` or
+        # `last_activity_time` unconditionally at the top. The old
+        # implementation wrote both of these BEFORE the state
+        # dispatch decided whether to emit an alert, which meant a
+        # no-op call (returning None) still silently corrupted
+        # state — e.g. a spurious rotations=4 event after rotations=5
+        # would ratchet the count DOWN and refresh the activity
+        # time, masking the real rotation count from subsequent
+        # recovery checks. Mutations now happen ONLY on paths that
+        # actually fire an alert OR represent real progress (see
+        # the monotonic-update block below each state branch).
+        previous_rotations = tracked.current_rotations
+
+        if tracked.state == "ACTIVE":
+            if rotations >= self.critical_threshold:
+                tracked.state = "ESCALATED"
+                tracked.current_rotations = rotations
+                tracked.last_activity_time = now
+                tracked.last_alert_rotations = rotations
+                tracked.last_alert_time = now
+                tracked.alert_count += 1
+                return Alert(
+                    pattern=pattern,
+                    severity="CRITICAL",
+                    details=details,
+                    timestamp=now,
+                )
+            # No alert fires, but rotations may still be increasing
+            # toward the critical threshold — ratchet forward ONLY
+            # if the new count is >= the old one. This preserves
+            # monotonic progress without ever decreasing.
+            if rotations >= previous_rotations:
+                tracked.current_rotations = rotations
+                tracked.last_activity_time = now
+            return None
+
+        if tracked.state == "ESCALATED":
+            if rotations >= tracked.last_alert_rotations + self.re_alert_interval:
+                tracked.current_rotations = rotations
+                tracked.last_activity_time = now
+                tracked.last_alert_rotations = rotations
+                tracked.last_alert_time = now
+                tracked.alert_count += 1
+                return Alert(
+                    pattern=pattern,
+                    severity="CRITICAL",
+                    details=details,
+                    timestamp=now,
+                )
+            # No re-alert fires — same monotonic guard as ACTIVE.
+            if rotations >= previous_rotations:
+                tracked.current_rotations = rotations
+                tracked.last_activity_time = now
+            return None
+
+        if tracked.state == "RESOLVED":
+            if rotations > previous_rotations or rotations > tracked.last_alert_rotations:
+                tracked.state = "ACTIVE"
+                tracked.current_rotations = rotations
+                tracked.last_activity_time = now
+                tracked.last_alert_time = now
+                # CRITICAL round-3 fix: update `last_alert_rotations`
+                # on the regression path. Without this, a future
+                # ESCALATED re-alert fires at `OLD_last_alert_rotations
+                # + re_alert_interval` instead of the correct
+                # `rotations + re_alert_interval`, firing one
+                # cycle earlier than designed.
+                tracked.last_alert_rotations = rotations
+                tracked.alert_count += 1
+                details["regression"] = True
+                return Alert(
+                    pattern=pattern,
+                    severity="WARNING",
+                    details=details,
+                    timestamp=now,
+                )
+            return None
+
+        return None
+
+    def check_recoveries(self, now: float) -> list[Alert]:
+        """Check all tracked alerts for recovery (quiet period elapsed).
+
+        Returns list of INFO alerts for newly resolved anomalies.
+        """
+        resolved: list[Alert] = []
+        for tracked in self._tracked.values():
+            if tracked.state in ("ACTIVE", "ESCALATED"):
+                if now - tracked.last_activity_time >= self.resolve_after_seconds:
+                    tracked.state = "RESOLVED"
+                    resolved.append(Alert(
+                        pattern=tracked.pattern,
+                        severity="INFO",
+                        details={
+                            "fingerprint": tracked.fingerprint,
+                            "rotations": tracked.current_rotations,
+                            "message": "resolved after quiet period",
+                        },
+                        timestamp=now,
+                    ))
+        return resolved
+
+    def reset(self) -> None:
+        """Clear all tracked alerts."""
+        self._tracked.clear()

agentsonar/_core/detectors/cycle_detector.py

@@ -0,0 +1,81 @@
+"""
+Layer 3: CycleDetector — O(V+E) cycle detection via has_path.
+
+Detects when a delegation creates or extends a graph cycle.  Uses
+has_path + shortest_path rather than simple_cycles for efficiency.
+Reports CycleInfo; does NOT decide severity (that's AlertStateManager).
+"""
+from __future__ import annotations
+
+import networkx as nx
+
+from agentsonar._core.models import CycleInfo, InteractionEvent
+
+
+class CycleDetector:
+    """Stateless cycle detector.
+
+    On each event (src -> dst), checks whether a path already exists from
+    dst back to src in the graph.  If so, extracts the cycle path and
+    computes rotation count (min edge count around the loop).
+    """
+
+    def __init__(self) -> None:
+        pass  # stateless — thresholds live in AlertStateManager
+
+    def check(self, graph: nx.DiGraph, event: InteractionEvent) -> CycleInfo | None:
+        """Check if the latest event creates or extends a cycle.
+
+        Returns CycleInfo if a cycle exists through this edge, else None.
+        """
+        src = event.source_agent
+        dst = event.target_agent
+
+        # Self-loop is not a meaningful coordination cycle
+        if src == dst:
+            return None
+
+        # If dst can reach src, then src->dst closes a cycle
+        try:
+            if not graph.has_node(dst) or not graph.has_node(src):
+                return None
+            if not nx.has_path(graph, dst, src):
+                return None
+        except (nx.NetworkXError, nx.NodeNotFound):
+            return None
+
+        try:
+            path = nx.shortest_path(graph, dst, src)
+        except (nx.NetworkXNoPath, nx.NodeNotFound):
+            return None
+
+        # Full cycle: src -> ... path from dst to src ... but path starts at dst
+        # path = [dst, ..., src], so full cycle = [src] + [dst, ..., src] minus trailing src
+        # i.e. cycle_path = [src] + path[:-1]  (the cycle loops back to src implicitly)
+        cycle_path = [src] + path[:-1]
+
+        # Build edges around the cycle: (A,B), (B,C), (C,A)
+        cycle_edges = list(zip(cycle_path, cycle_path[1:] + cycle_path[:1]))
+        edge_counts: dict[tuple[str, str], int] = {}
+        counts = []
+        for u, v in cycle_edges:
+            if graph.has_edge(u, v):
+                c = graph.edges[u, v].get("count", 0)
+            else:
+                c = 0
+            edge_counts[(u, v)] = c
+            counts.append(c)
+
+        rotations = min(counts) if counts else 0
+        fingerprint = tuple(sorted(set(cycle_path)))
+
+        return CycleInfo(
+            fingerprint=fingerprint,
+            cycle_path=cycle_path,
+            rotations=rotations,
+            edge_counts=edge_counts,
+        )
+
+    def reset(self) -> None:
+        """Nothing to reset (stateless)."""
+        pass

agentsonar/_core/detectors/rate_limiter.py

@@ -0,0 +1,297 @@
+"""
+Layer 1: SlidingWindowLimiter — O(1) circuit breaker.
+
+Dumb circuit breaker. If any single edge or the whole system exceeds a
+hard delegation rate, fire immediate CRITICAL. No scoring, no analysis.
+
+Includes anti-flap hysteresis (half-open circuit breaker pattern): once
+an edge fires, further fires are suppressed until the estimated rate
+cools below `trip_limit * reset_ratio` (default 0.7). Without this,
+every single event over the threshold produced a fresh CRITICAL alert —
+the "machine-gun" anti-pattern called out in Prometheus and Datadog's
+alert-fatigue guidance.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentsonar._core.models import Alert
+
+# Default reset ratio for the half-open circuit-breaker pattern.
+# After the limiter fires at `limit`, it re-arms for the next fire
+# only when the estimated rate drops below `limit * RESET_RATIO`.
+# Value of 0.7 picked as a balance: low enough that brief spikes
+# don't re-arm immediately, high enough that real cooldown does.
+# Configurable via the `reset_ratio` constructor arg.
+_DEFAULT_RESET_RATIO = 0.7
+
+
+@dataclass
+class _EdgeWindow:
+    current_count: int = 0
+    previous_count: int = 0
+    window_start: float = 0.0
+
+    # Anti-flap state — set when the limiter fires on this window.
+    # Cleared when the estimated rate drops below the reset threshold.
+    # Multiple fires while `tripped` stays True are suppressed.
+    tripped: bool = False
+
+
+class SlidingWindowLimiter:
+    """Hard rate-limit circuit breaker with hysteresis.
+
+    Uses a two-counter sliding window approximation per edge plus one
+    global counter. When the estimated rate in the current window first
+    crosses the limit, an immediate CRITICAL alert is returned and the
+    window is latched into the "tripped" state. Subsequent events on
+    the same window DO NOT re-fire until the estimated rate has cooled
+    below `trip_limit * reset_ratio` — the classic circuit-breaker
+    half-open pattern.
+
+    Args:
+        window_size: Window duration in seconds (default 60).
+        per_edge_limit: Max delegations per single edge per window (default 50).
+        global_limit: Max total delegations across ALL edges per window (default 200).
+        reset_ratio: Hysteresis threshold as a fraction of the trip limit.
+            After a fire, the limiter re-arms for the next fire only when
+            the estimated rate drops below `limit * reset_ratio`. Default
+            0.7 — lower values (0.5) re-arm more eagerly; higher values
+            (0.9) require deeper cooldown. Must satisfy 0 < ratio < 1.
+    """
+
+    def __init__(
+        self,
+        window_size: float = 60.0,
+        per_edge_limit: int = 50,
+        global_limit: int = 200,
+        reset_ratio: float = _DEFAULT_RESET_RATIO,
+    ):
+        # Defensive validation — every knob has a range where the
+        # math makes sense, and outside that range the detector
+        # produces nonsense instead of raising. A surprised user
+        # who typed `window_size=-60` by accident would see alerts
+        # fire or suppress based on negative rate estimates. Reject
+        # at construction time with a clear error message.
+        if not 0.0 < reset_ratio < 1.0:
+            raise ValueError(
+                f"reset_ratio must be between 0 and 1 exclusive, got {reset_ratio}"
+            )
+        if not isinstance(window_size, (int, float)) or window_size <= 0:
+            raise ValueError(
+                f"window_size must be a positive number, got {window_size}"
+            )
+        import math as _math
+        if not _math.isfinite(float(window_size)):
+            raise ValueError(
+                f"window_size must be finite (not NaN or Infinity), got {window_size}"
+            )
+        if not isinstance(per_edge_limit, int) or per_edge_limit < 1:
+            raise ValueError(
+                f"per_edge_limit must be a positive integer, got {per_edge_limit}"
+            )
+        if not isinstance(global_limit, int) or global_limit < 1:
+            raise ValueError(
+                f"global_limit must be a positive integer, got {global_limit}"
+            )
+        self.window_size = float(window_size)
+        self.per_edge_limit = per_edge_limit
+        self.global_limit = global_limit
+        self.reset_ratio = reset_ratio
+        self._edges: dict[tuple[str, str], _EdgeWindow] = {}
+        self._global = _EdgeWindow()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _peek_estimate(self, window: _EdgeWindow, now: float) -> float:
+        """Return the current estimated rate for `window` WITHOUT
+        incrementing its counter.
+
+        Used on the suppressed-per-edge-event path so the global
+        window's counter isn't polluted by events the per-edge
+        gate already rejected. We still roll the window if it's
+        overdue — the rollover is just time bookkeeping and must
+        happen regardless of whether we count this event.
+        """
+        # Roll the window if it's expired (same bookkeeping as
+        # _roll_and_increment, minus the counter bump).
+        if window.window_start == 0.0:
+            window.window_start = now
+        elapsed = now - window.window_start
+        if elapsed >= self.window_size:
+            window.previous_count = window.current_count
+            window.current_count = 0
+            window.window_start = now
+            elapsed = 0.0
+            window.tripped = False
+
+        fraction_elapsed = elapsed / self.window_size if self.window_size > 0 else 1.0
+        estimated = window.current_count + window.previous_count * (1.0 - fraction_elapsed)
+        return estimated
+
+    def _roll_and_increment(self, window: _EdgeWindow, now: float) -> float:
+        """Roll over the window if needed, increment, return estimated count.
+
+        Window rollover also clears the `tripped` latch — rolling into a
+        fresh window is a natural re-arm point, so the next breach fires
+        a new alert rather than being suppressed by the old window's
+        hysteresis state.
+        """
+        if window.window_start == 0.0:
+            window.window_start = now
+
+        elapsed = now - window.window_start
+        if elapsed >= self.window_size:
+            window.previous_count = window.current_count
+            window.current_count = 0
+            window.window_start = now
+            elapsed = 0.0
+            # Fresh window — re-arm the circuit breaker. Any latched
+            # trip state from the previous window is stale.
+            window.tripped = False
+
+        window.current_count += 1
+
+        fraction_elapsed = elapsed / self.window_size if self.window_size > 0 else 1.0
+        estimated = window.current_count + window.previous_count * (1.0 - fraction_elapsed)
+        return estimated
+
+    def _try_fire(
+        self,
+        window: _EdgeWindow,
+        estimated: float,
+        trip_limit: int,
+    ) -> bool:
+        """Half-open circuit-breaker logic.
+
+        Returns True if the caller should FIRE an alert for this event;
+        False if the alert should be suppressed (already firing or
+        below the trip threshold).
+
+        State transitions:
+          * Not tripped + estimated > limit       → trip + fire (True)
+          * Not tripped + estimated <= limit      → quiet (False)
+          * Tripped + estimated < limit * ratio   → reset, quiet (False)
+          * Tripped + estimated >= limit * ratio  → suppressed (False)
+        """
+        reset_threshold = trip_limit * self.reset_ratio
+
+        if window.tripped:
+            # Already firing on this window. Only clear the latch when
+            # the rate has genuinely cooled.
+            if estimated < reset_threshold:
+                window.tripped = False
+            # Either way, do not fire a second alert from the tripped
+            # state — the user was already told about the problem.
+            return False
+
+        if estimated > trip_limit:
+            window.tripped = True
+            return True
+
+        return False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def check(self, src: str, dst: str, now: float) -> Alert | None:
+        """Check rate limits for a delegation event.
+
+        Returns CRITICAL Alert if the per-edge or global limit is
+        newly exceeded (first breach of the current window). Returns
+        None if the limit is not exceeded OR if the limiter is already
+        in the tripped state for this window.
+
+        Global counter policy: we only count events toward the global
+        window when the per-edge window would have let them through.
+        Without this, a single runaway edge spews events at the global
+        counter long after its per-edge alert has fired and subsequent
+        events were suppressed — eventually tripping the global
+        limit with a "triggering edge" that isn't actually the
+        culprit. The user sees a misleading `global_rate_exceeded`
+        attributed to the next benign edge that happened to push the
+        global counter past the threshold.
+
+        By skipping the global increment when per-edge is already
+        tripped, "global rate" means "events the per-edge gate let
+        through", which matches user intuition about what each alert
+        represents.
+        """
+        # Per-edge check
+        key = (src, dst)
+        if key not in self._edges:
+            self._edges[key] = _EdgeWindow()
+        edge_window = self._edges[key]
+        edge_est = self._roll_and_increment(edge_window, now)
+
+        # Per-edge first — gating against a single runaway edge is
+        # usually more actionable than global saturation. Evaluate
+        # before touching the global counter so we know whether this
+        # event should count toward the global window.
+        edge_fires = self._try_fire(edge_window, edge_est, self.per_edge_limit)
+
+        # Decide whether the event counts toward the global window.
+        #
+        # Count IF:
+        #   a) the per-edge window is not tripped at ALL (normal flow), OR
+        #   b) the per-edge window is tripped AND this event fired the
+        #      alert (the event that initially breached the limit is
+        #      legitimate throughput and should be globally counted)
+        #
+        # Skip IF:
+        #   c) the per-edge window is already latched tripped and this
+        #      event is being suppressed (the suppressed events should
+        #      NOT pollute the global counter)
+        #
+        # Concretely: if `edge_fires` is True, count globally. If
+        # `edge_fires` is False AND `edge_window.tripped` is True,
+        # skip. Otherwise (edge untripped, no fire) count normally.
+        event_counts_globally = edge_fires or not edge_window.tripped
+
+        if event_counts_globally:
+            global_est = self._roll_and_increment(self._global, now)
+        else:
+            # Still update the window rollover for time tracking, but
+            # without incrementing the counter. This is a no-op on
+            # the counter side; the window start still rolls when
+            # elapsed > window_size.
+            global_est = self._peek_estimate(self._global, now)
+
+        if edge_fires:
+            return Alert(
+                pattern="rate_limit_exceeded",
+                severity="CRITICAL",
+                details={
+                    "source": src,
+                    "target": dst,
+                    "estimated_rate": round(edge_est, 1),
+                    "limit": self.per_edge_limit,
+                    "window_size": self.window_size,
+                    "reset_ratio": self.reset_ratio,
+                },
+                timestamp=now,
+            )
+
+        # Global check — only reached if the per-edge check did NOT fire
+        if self._try_fire(self._global, global_est, self.global_limit):
+            return Alert(
+                pattern="global_rate_exceeded",
+                severity="CRITICAL",
+                details={
+                    "estimated_rate": round(global_est, 1),
+                    "limit": self.global_limit,
+                    "window_size": self.window_size,
+                    "reset_ratio": self.reset_ratio,
+                },
+                timestamp=now,
+            )
+
+        return None
+
+    def reset(self) -> None:
+        """Clear all rate-limit state (including hysteresis latches)."""
+        self._edges.clear()
+        self._global = _EdgeWindow()