coderouter-cli 2.3.0a3__py3-none-any.whl → 2.4.0__py3-none-any.whl

coderouter/cli.py

@@ -293,6 +293,18 @@ def _build_parser() -> argparse.ArgumentParser:
         metavar="N",
         help="Use only the last N entries (applied after --since and --provider filters).",
     )
+    # P1-6: --suggest-rules — statistical analysis → routing rule proposals.
+    replay.add_argument(
+        "--suggest-rules",
+        action="store_true",
+        help=(
+            "P1-6: analyse the request journal and print actionable routing "
+            "rule suggestions as copy-paste YAML snippets. Suggestions cover "
+            "provider reordering by cost, prompt_cache enablement, drift "
+            "detection configuration, and goal profile creation. "
+            "Can be combined with --since / --limit to scope the analysis window."
+        ),
+    )
 
     return parser
 
@@ -684,6 +696,25 @@ def _run_replay(args: argparse.Namespace) -> int:
         print("replay: no matching entries found.")
         return 0
 
+    if getattr(args, "suggest_rules", False):
+        # P1-6: statistical rule suggestion mode.
+        # Always compute a full window summary (ignores --compare / --provider).
+        from coderouter.state.suggest_rules import format_suggestions, suggest_rules
+        from coderouter.state.replay import summarize_window as _sw
+
+        # Re-read without provider filter so we see all providers.
+        all_entries = read_request_log(log_path, since=args.since)
+        if args.limit is not None and args.limit > 0:
+            all_entries = all_entries[-args.limit:]
+        full_summary = _sw(all_entries)
+        suggestions = suggest_rules(full_summary)
+        print(f"Request journal: {len(all_entries)} entries analysed")
+        print(f"  Window: {full_summary.first_ts} → {full_summary.last_ts}")
+        print(f"  Providers: {', '.join(sorted(full_summary.providers))}")
+        print()
+        print(format_suggestions(suggestions))
+        return 0
+
     if args.compare:
         provider_a, provider_b = args.compare
         comparison = compare_providers(entries, provider_a, provider_b)

coderouter/config/schemas.py

@@ -658,6 +658,28 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    # --- P1-5: goal_mode — tighter drift thresholds for /goal sessions -------
+    #
+    # When True, the drift detector automatically switches to the
+    # ``THRESHOLDS_GOAL`` preset regardless of ``drift_detection_sensitivity``,
+    # and lowers ``min_window_fill`` to 4 so stall detection fires faster.
+    #
+    # Intended for profiles routed by the ``/goal`` meta-command where
+    # the agent is expected to make steady forward progress. Repetition and
+    # length collapse are much more meaningful signals in that context than
+    # in a general-purpose chat session.
+    goal_mode: bool = Field(
+        default=False,
+        description=(
+            "P1-5: when True, automatically applies the ``goal`` drift "
+            "threshold preset (stricter thresholds, lower ``min_window_fill`` "
+            "of 4) for this profile. Overrides ``drift_detection_sensitivity`` "
+            "when drift_detection_action is not ``off``. Designed for "
+            "agent/goal sessions where forward-progress stalls are more "
+            "actionable than in ad-hoc chat."
+        ),
+    )
+
     # --- v2.0-H (L6): Mid-stream partial stitching --------------------------
     #   * ``off``      — discard partial content on mid-stream failure (legacy).
     #   * ``surface``  — return partial content as a truncated-but-valid response.

coderouter/guards/__init__.py

@@ -12,6 +12,8 @@ to hit:
   * :mod:`coderouter.guards.self_healing`    — v2.0-J auto-exclude +
                                                  restart + recovery probe
   * :mod:`coderouter.guards.continuous_probe` — v2.0-I background probing
+  * :mod:`coderouter.guards._fingerprint`     — P1-4 response fingerprinting
+                                                 for goal_progress_stall signal
 
 Each guard is a pure-functional / single-class module that the engine
 consults at the appropriate dispatch point. Guards never block the

coderouter/guards/_fingerprint.py

@@ -0,0 +1,125 @@
+"""Response fingerprinting for goal_progress_stall detection (P1-4).
+
+A "fingerprint" is a compact, order-independent signature of the *content*
+of an assistant response — independent of surface variation (filler phrases,
+minor rewordings).  Two responses with the same fingerprint are considered
+semantically repetitive for stall-detection purposes.
+
+Algorithm
+---------
+1. Normalise: lowercase, strip punctuation, collapse whitespace.
+2. Extract the N most-frequent content words (excluding a small stop-list).
+3. Sort alphabetically, join with '|', SHA-256 → 12-hex prefix.
+
+The 12-hex prefix gives 281 trillion distinct values — collision probability
+across any 20-response window is negligible (< 1 in 10^15).
+
+Why top-N content words instead of full hash?
+----------------------------------------------
+A verbatim hash would fail to catch "I cannot do X. Let me try Y" vs
+"Let me try Y as I cannot do X" — same stall, different hash.  By
+extracting the dominant vocabulary we get useful fuzzy equality without
+the overhead of embedding models.
+
+Usage
+-----
+    from coderouter.guards._fingerprint import fingerprint_response
+
+    fp = fingerprint_response(response_text)
+    obs = ResponseObservation(..., response_fingerprint=fp)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+
+# ---------------------------------------------------------------------------
+# Stop-word list (English + common LLM filler)
+# ---------------------------------------------------------------------------
+
+_STOP_WORDS: frozenset[str] = frozenset(
+    {
+        # English function words
+        "a", "an", "the", "and", "or", "but", "if", "in", "on", "at", "to",
+        "for", "of", "with", "by", "from", "as", "is", "it", "its", "be",
+        "was", "are", "were", "been", "has", "have", "had", "do", "does",
+        "did", "will", "would", "could", "should", "may", "might", "shall",
+        "this", "that", "these", "those", "i", "you", "he", "she", "we",
+        "they", "me", "him", "her", "us", "them", "my", "your", "his",
+        "their", "our", "what", "which", "who", "how", "when", "where",
+        "why", "not", "no", "so", "up", "out", "into", "about", "than",
+        "then", "there", "here", "also", "just", "can", "get", "all",
+        # Common LLM assistant filler
+        "certainly", "sure", "absolutely", "great", "happy", "help",
+        "please", "let", "know", "feel", "free", "answer", "question",
+        "response", "following", "based", "provide", "using",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Number of top content words to include in the fingerprint
+# ---------------------------------------------------------------------------
+
+_TOP_N: int = 12
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def fingerprint_response(text: str, *, top_n: int = _TOP_N) -> str:
+    """Return a 12-hex fingerprint string for *text*.
+
+    Parameters
+    ----------
+    text:
+        Raw assistant response text (plain text, not JSON).
+    top_n:
+        Number of most-frequent content words to include in the signature.
+        Defaults to ``_TOP_N`` (12).  Lower values are more fuzzy; higher
+        values are more precise.
+
+    Returns
+    -------
+    A 12-character lowercase hexadecimal string, e.g. ``"a3f7b2c091de"``.
+    Returns ``""`` for empty / whitespace-only input.
+    """
+    if not text or not text.strip():
+        return ""
+
+    # 1. Unicode normalisation + lowercase
+    normalised = unicodedata.normalize("NFKC", text).lower()
+
+    # 2. Strip punctuation / digits, collapse whitespace
+    normalised = re.sub(r"[^\w\s]", " ", normalised)
+    normalised = re.sub(r"\d+", " ", normalised)
+    normalised = re.sub(r"\s+", " ", normalised).strip()
+
+    # 3. Tokenise and filter stop words (also skip very short tokens)
+    tokens = [w for w in normalised.split() if len(w) > 2 and w not in _STOP_WORDS]
+
+    if not tokens:
+        return ""
+
+    # 4. Count frequencies, take top-N
+    freq: dict[str, int] = {}
+    for tok in tokens:
+        freq[tok] = freq.get(tok, 0) + 1
+
+    # Require at least 3 distinct content words; single-word or near-empty
+    # responses (e.g. "xxxxx..." test stubs, error codes, bare ACKs) produce
+    # the same fingerprint every time and would falsely inflate the repetition
+    # rate.  Returning "" marks these as "not fingerprinted" so detect_drift
+    # skips them entirely.
+    if len(freq) < 3:
+        return ""
+
+    top_words = sorted(freq, key=lambda w: (-freq[w], w))[:top_n]
+
+    # 5. Sort alphabetically → stable join → hash
+    signature = "|".join(sorted(top_words))
+    digest = hashlib.sha256(signature.encode()).hexdigest()
+    return digest[:12]

coderouter/guards/drift_detection.py

@@ -34,6 +34,10 @@ Signals
   * ``stop_anomaly_rate`` — fraction of responses with unexpected stop_reason
     (not "end_turn" / "tool_use" / "max_tokens")
   * ``error_rate`` — fraction of attempts that ended in failure
+  * ``goal_progress_stall`` (P1-4) — fraction of fingerprinted responses
+    whose fingerprint matches a previously-seen fingerprint in the window,
+    indicating the model is repeating itself without making progress.
+    Only fires when ``response_fingerprint`` is populated on observations.
 
 Thresholds are bundled as :class:`DriftThresholds` with three presets
 (``low`` / ``normal`` / ``high`` sensitivity).
@@ -71,6 +75,15 @@ class ResponseObservation:
     is_error: bool = False
     """True if the attempt ended in provider-failed / provider-failed-midstream."""
     stream: bool = False
+    response_fingerprint: str | None = None
+    """P1-4: compact content fingerprint of the response text.
+
+    When set, used by the ``goal_progress_stall`` signal to detect
+    repetition: the same fingerprint appearing multiple times in the
+    window indicates the model is not making progress. Computed by
+    :func:`coderouter.guards._fingerprint.fingerprint_response`.
+    Pass ``None`` (default) to opt-out — the signal is silently skipped.
+    """
 
 
 # ---------------------------------------------------------------------------
@@ -100,6 +113,12 @@ class DriftThresholds:
     length_collapse_ratio: float = 0.5
     """If recent half median is < 50% of earlier half median → collapse."""
 
+    # P1-4: repetition/stall threshold
+    repetition_rate_threshold: float = 0.4
+    """P1-4: fraction of fingerprinted responses whose fingerprint has
+    appeared before in the window. Above this rate → goal_progress_stall
+    signal fires (mild). Default 0.4 = 2 out of 5 responses are repeats."""
+
     # Minimum observations before detection fires
     min_window_fill: int = 6
     """Don't trigger until at least this many observations in the window."""
@@ -112,6 +131,7 @@ THRESHOLDS_LOW = DriftThresholds(
     tool_silence_rate=0.8,
     stop_anomaly_rate=0.6,
     error_rate=0.4,
+    repetition_rate_threshold=0.6,
     min_window_fill=10,
 )
 
@@ -123,6 +143,19 @@ THRESHOLDS_HIGH = DriftThresholds(
     tool_silence_rate=0.5,
     stop_anomaly_rate=0.3,
     error_rate=0.15,
+    repetition_rate_threshold=0.25,
+    min_window_fill=4,
+)
+
+# P1-5: goal-mode preset — tighter thresholds + lower min_window_fill.
+# Applied automatically when the profile has goal_mode=True.
+THRESHOLDS_GOAL = DriftThresholds(
+    empty_response_rate=0.2,
+    length_collapse_ratio=0.6,
+    tool_silence_rate=0.5,
+    stop_anomaly_rate=0.3,
+    error_rate=0.15,
+    repetition_rate_threshold=0.2,
     min_window_fill=4,
 )
 
@@ -130,6 +163,7 @@ SENSITIVITY_PRESETS: dict[str, DriftThresholds] = {
     "low": THRESHOLDS_LOW,
     "normal": THRESHOLDS_NORMAL,
     "high": THRESHOLDS_HIGH,
+    "goal": THRESHOLDS_GOAL,
 }
 
 
@@ -244,6 +278,27 @@ def detect_drift(
     if error_rate > thresholds.error_rate:
         mild_flags.append(f"error_rate={error_rate:.2f}")
 
+    # --- Signal 6: Goal progress stall (P1-4) ---
+    # Only active when at least some observations have a fingerprint.
+    # Computes: how many fingerprinted responses repeat a fingerprint
+    # already seen earlier in the window.  High repetition → stall.
+    fingerprinted = [
+        obs for obs in window if obs.response_fingerprint  # excludes None and ""
+    ]
+    if len(fingerprinted) >= 3:
+        seen: set[str] = set()
+        repeat_count = 0
+        for obs in fingerprinted:
+            fp = obs.response_fingerprint  # guaranteed non-empty by filter above
+            if fp in seen:
+                repeat_count += 1
+            else:
+                seen.add(fp)
+        repetition_rate = repeat_count / len(fingerprinted)
+        signals["goal_progress_stall"] = round(repetition_rate, 3)
+        if repetition_rate > thresholds.repetition_rate_threshold:
+            mild_flags.append(f"goal_progress_stall={repetition_rate:.2f}")
+
     # --- Severity synthesis ---
     if severe_flags:
         severity: Literal["none", "mild", "severe"] = "severe"

coderouter/plugins/__init__.py

@@ -43,17 +43,14 @@ from coderouter.plugins.loader import (
 from coderouter.plugins.registry import PluginRegistry
 
 __all__ = [
-    # Active hooks
-    "InputFilter",
-    "Observer",
-    # Future hooks (Protocol-only, no engine integration yet)
+    "PLUGIN_GROUPS_FUTURE",
+    "PLUGIN_GROUPS_V2_3",
+    "Adapter",
     "Frontend",
     "Guard",
+    "InputFilter",
+    "Observer",
     "OutputFilter",
-    "Adapter",
-    # Discovery + container
     "PluginRegistry",
     "discover_and_load",
-    "PLUGIN_GROUPS_V2_3",
-    "PLUGIN_GROUPS_FUTURE",
 ]

coderouter/routing/fallback.py

@@ -838,6 +838,12 @@ class FallbackEngine:
         # so tests that build the engine via ``FallbackEngine.__new__``
         # see an empty registry instead of AttributeError.
         self._plugin_registry: PluginRegistry = plugins or PluginRegistry.empty()
+        # v2.3.0: holds strong refs to in-flight Observer fanout tasks
+        # so the asyncio event loop's weak-ref bookkeeping doesn't GC
+        # them mid-flight (RUF006).  Tasks remove themselves on done
+        # via ``add_done_callback(_observer_tasks.discard)`` in
+        # :meth:`_fanout_observers`.
+        self._observer_tasks: set[asyncio.Task[None]] = set()
         # Cache adapters so we don't re-instantiate per request
         self._adapters: dict[str, BaseAdapter] = {
             p.name: build_adapter(p) for p in config.providers
@@ -1277,6 +1283,7 @@ class FallbackEngine:
         stop_reason: str | None = None,
         is_error: bool = False,
         stream: bool = False,
+        response_fingerprint: str | None = None,
     ) -> DriftVerdict | None:
         """v2.0-G (L4): record an observation and check for drift.
 
@@ -1288,9 +1295,18 @@ class FallbackEngine:
         - Emits ``drift-detected`` log.
         - If action is ``promote`` or ``reload``, demotes the provider
           via the adaptive rank machinery.
+
+        Parameters
+        ----------
+        response_fingerprint:
+            P1-4: compact content fingerprint from
+            :func:`coderouter.guards._fingerprint.fingerprint_response`.
+            When set, enables the ``goal_progress_stall`` signal.
+            Pass ``None`` (default) to skip that signal.
         """
         from coderouter.guards.drift_detection import (
             SENSITIVITY_PRESETS,
+            THRESHOLDS_GOAL,
             ResponseObservation,
             detect_drift,
         )
@@ -1316,6 +1332,7 @@ class FallbackEngine:
             stop_reason=stop_reason,
             is_error=is_error,
             stream=stream,
+            response_fingerprint=response_fingerprint,
         )
         self._drift_window.record(obs)
 
@@ -1338,10 +1355,15 @@ class FallbackEngine:
             return None
 
         # Run detection
+        # P1-5: goal_mode overrides the sensitivity preset with the tighter
+        # THRESHOLDS_GOAL regardless of drift_detection_sensitivity setting.
         window = self._drift_window.get_window(provider)
-        thresholds = SENSITIVITY_PRESETS.get(
-            chain_cfg.drift_detection_sensitivity, SENSITIVITY_PRESETS["normal"]
-        )
+        if getattr(chain_cfg, "goal_mode", False):
+            thresholds = THRESHOLDS_GOAL
+        else:
+            thresholds = SENSITIVITY_PRESETS.get(
+                chain_cfg.drift_detection_sensitivity, SENSITIVITY_PRESETS["normal"]
+            )
         verdict = detect_drift(window, thresholds)
 
         if not verdict.drifted:
@@ -1881,10 +1903,22 @@ class FallbackEngine:
         observers = self.plugins.observers
         if not observers:
             return
+        # Lazy-init the task set for engines built via ``__new__`` —
+        # mirrors the lazy ``plugins`` property pattern so legacy
+        # tests that bypass __init__ don't crash here.
+        if not hasattr(self, "_observer_tasks"):
+            self._observer_tasks = set()
         for obs in observers:
-            asyncio.create_task(
+            task = asyncio.create_task(
                 self._safe_observe(obs, event_type, payload)
             )
+            # Strong-ref keeps the task alive past the loop iteration;
+            # ``discard`` cleans up after the task completes (success
+            # or exception). Avoids the RUF006 footgun where
+            # asyncio.create_task's weakref-only bookkeeping can let
+            # the loop GC a fanout-in-progress task.
+            self._observer_tasks.add(task)
+            task.add_done_callback(self._observer_tasks.discard)
 
     async def _safe_observe(
         self,
@@ -2065,6 +2099,13 @@ class FallbackEngine:
                 adapter.name, profile=request.profile
             )
             # v2.0-G (L4): drift detection observation (success path).
+            # P1-4: compute response fingerprint for goal_progress_stall.
+            _fp_text = " ".join(
+                getattr(b, "text", "") or (b.get("text", "") if isinstance(b, dict) else "")
+                for b in (resp.content or [])
+                if (getattr(b, "type", None) or (b.get("type") if isinstance(b, dict) else None)) == "text"
+            )
+            from coderouter.guards._fingerprint import fingerprint_response as _fp
             self._observe_drift_signal(
                 adapter.name,
                 profile=request.profile,
@@ -2075,6 +2116,7 @@ class FallbackEngine:
                 request_had_tools=bool(request.tools),
                 stop_reason=resp.stop_reason,
                 stream=False,
+                response_fingerprint=_fp(_fp_text) if _fp_text else None,
             )
             # v1.9-A: pair every successful Anthropic response with a
             # cache-observed log line. Native Anthropic / LM Studio
@@ -2294,6 +2336,11 @@ class FallbackEngine:
                     adapter.name, exc, partial_content=acc.partial_content
                 ) from exc
             # v2.0-G (L4): drift detection observation (stream success).
+            # P1-4: compute response fingerprint for goal_progress_stall.
+            _stream_fp_text = " ".join(
+                b.get("text", "") for b in acc.partial_content if b.get("type") == "text"
+            )
+            from coderouter.guards._fingerprint import fingerprint_response as _fp_s
             self._observe_drift_signal(
                 adapter.name,
                 profile=request.profile,
@@ -2302,6 +2349,7 @@ class FallbackEngine:
                 request_had_tools=bool(request.tools),
                 stop_reason=acc.stop_reason,
                 stream=True,
+                response_fingerprint=_fp_s(_stream_fp_text) if _stream_fp_text else None,
             )
             # v1.9-B2: pair the successful stream with a cache-observed
             # log line carrying the aggregated usage counters that the

coderouter/state/__init__.py

@@ -1,15 +1,19 @@
 """Persistent state layer (v2.0-K).
 
-Four modules:
+Five modules:
 
-* :mod:`coderouter.state.store`       — sqlite3 KV store for operational
-                                         metadata (budget totals, health
-                                         state, self-healing exclusions).
-* :mod:`coderouter.state.audit_log`   — JSONL structured event log with
-                                         rotation and CLI reader.
-* :mod:`coderouter.state.request_log` — JSONL request metadata journal
-                                         (per-request token counts, cost,
-                                         provider — no request body).
-* :mod:`coderouter.state.replay`      — Statistical A/B analysis engine
-                                         over request journal entries.
+* :mod:`coderouter.state.store`         — sqlite3 KV store for operational
+                                           metadata (budget totals, health
+                                           state, self-healing exclusions).
+* :mod:`coderouter.state.audit_log`     — JSONL structured event log with
+                                           rotation and CLI reader.
+* :mod:`coderouter.state.request_log`   — JSONL request metadata journal
+                                           (per-request token counts, cost,
+                                           provider — no request body).
+* :mod:`coderouter.state.replay`        — Statistical A/B analysis engine
+                                           over request journal entries.
+* :mod:`coderouter.state.suggest_rules` — P1-6 rule suggestion engine:
+                                           analyses WindowSummary and emits
+                                           copy-paste YAML snippets for
+                                           routing optimisation.
 """

coderouter/state/suggest_rules.py

@@ -0,0 +1,413 @@
+"""Rule suggestion engine for ``coderouter replay --suggest-rules`` (P1-6).
+
+Analyses the request journal statistics produced by
+:func:`coderouter.state.replay.summarize_window` and emits a list of
+:class:`RuleSuggestion` objects — each containing a plain-English
+description, a copy-paste YAML snippet, and the numeric evidence that
+drove the recommendation.
+
+Design
+------
+Pure statistical analysis — no LLM required.  Rules are applied in
+priority order; each rule is independently evaluated so multiple
+suggestions can fire for the same provider.
+
+Rules (v1.0)
+------------
+
+1. **provider_reorder** — If provider B costs less per request than
+   provider A *and* B has meaningful traffic, suggest moving B earlier
+   in the fallback chain.
+
+2. **enable_prompt_cache** — If a provider has a large average input
+   token count (> ``CACHE_INPUT_THRESHOLD``) and a low cache-hit ratio
+   (< ``CACHE_HIT_RATIO_THRESHOLD``), suggest enabling
+   ``capabilities.prompt_cache: true``.
+
+3. **enable_drift_detection** — If any provider has a non-trivial
+   request volume and no drift-detection configuration is visible in
+   the stats (proxy: we see the provider at all), emit a reminder to
+   set ``drift_detection_action: promote``.
+
+4. **raise_min_window_fill** — If a provider has a low request count
+   (< ``SMALL_WINDOW_THRESHOLD``) and drift detection would fire early,
+   suggest raising ``drift_detection_sensitivity: low`` to avoid false
+   positives.
+
+5. **split_goal_profile** — If there is more than one provider with
+   significant traffic and average output tokens differ substantially,
+   suggest creating a ``goal`` profile with ``goal_mode: true`` that
+   routes to the highest-output provider.
+
+Confidence levels
+-----------------
+``high``   — clear numeric evidence, low false-positive risk
+``medium`` — heuristic, may need operator judgement
+``low``    — informational / reminder
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from coderouter.state.replay import ProviderSummary, WindowSummary
+
+# ---------------------------------------------------------------------------
+# Thresholds (module-level constants for easy tuning)
+# ---------------------------------------------------------------------------
+
+# Minimum requests per provider before we emit cost-based suggestions.
+_MIN_TRAFFIC: int = 5
+
+# Prompt-cache opportunity: avg input tokens above this → suggest caching.
+_CACHE_INPUT_THRESHOLD: int = 2_000
+
+# Prompt-cache opportunity: cache hit ratio below this → suggest enabling.
+_CACHE_HIT_RATIO_THRESHOLD: float = 0.10
+
+# Cost reorder: provider B is this fraction cheaper than A → suggest reorder.
+_COST_REORDER_THRESHOLD: float = 0.20  # 20% cheaper
+
+# Small-window guard: fewer requests than this → suggest low sensitivity.
+_SMALL_WINDOW_THRESHOLD: int = 10
+
+# Goal profile split: relative std-dev of avg output tokens across providers.
+_OUTPUT_DIVERGENCE_THRESHOLD: float = 0.40
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RuleSuggestion:
+    """One actionable suggestion derived from request journal statistics.
+
+    Attributes
+    ----------
+    rule:
+        Internal rule identifier, e.g. ``"provider_reorder"``.
+    title:
+        Short human-readable title for the suggestion.
+    description:
+        Plain-English explanation of what was observed and why the
+        change is recommended.
+    yaml_snippet:
+        Copy-paste YAML fragment showing the recommended change.
+        May span multiple lines; always valid YAML in isolation.
+    evidence:
+        Dict of metric name → value that drove this suggestion.
+    confidence:
+        ``"high"`` / ``"medium"`` / ``"low"``
+    providers_involved:
+        Provider names mentioned in this suggestion.
+    """
+
+    rule: str
+    title: str
+    description: str
+    yaml_snippet: str
+    evidence: dict[str, object] = field(default_factory=dict)
+    confidence: str = "medium"
+    providers_involved: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Rule implementations
+# ---------------------------------------------------------------------------
+
+
+def _rule_provider_reorder(
+    providers: list[ProviderSummary],
+) -> list[RuleSuggestion]:
+    """Suggest reordering providers by cost-per-request."""
+    suggestions: list[RuleSuggestion] = []
+    # Only consider providers with meaningful traffic.
+    # Include free providers (cost=0) — they are the best candidates.
+    active = [p for p in providers if p.request_count >= _MIN_TRAFFIC]
+    if len(active) < 2:
+        return []
+
+    # Sort by avg cost ascending (cheapest / free first)
+    active_by_cost = sorted(active, key=lambda p: p.avg_cost_usd)
+
+    # Compare every pair where the expensive provider costs something.
+    for i in range(len(active_by_cost)):
+        for j in range(i + 1, len(active_by_cost)):
+            cheap = active_by_cost[i]
+            expensive = active_by_cost[j]
+            if expensive.avg_cost_usd <= 0:
+                continue  # both free — no cost advantage to reorder
+            saving_pct = (expensive.avg_cost_usd - cheap.avg_cost_usd) / expensive.avg_cost_usd
+            if saving_pct >= _COST_REORDER_THRESHOLD:
+                suggestions.append(RuleSuggestion(
+                    rule="provider_reorder",
+                    title=f"Move {cheap.provider!r} before {expensive.provider!r}",
+                    description=(
+                        f"{cheap.provider!r} costs ${cheap.avg_cost_usd:.4f}/req on average, "
+                        f"{saving_pct * 100:.0f}% cheaper than {expensive.provider!r} "
+                        f"(${expensive.avg_cost_usd:.4f}/req). "
+                        f"Listing the cheaper provider earlier in the fallback chain "
+                        f"reduces cost without changing availability."
+                    ),
+                    yaml_snippet=(
+                        f"# In your profile's providers list, move {cheap.provider!r} earlier:\n"
+                        f"profiles:\n"
+                        f"  - name: default   # or your active profile\n"
+                        f"    providers:\n"
+                        f"      - {cheap.provider}\n"
+                        f"      - {expensive.provider}"
+                    ),
+                    evidence={
+                        "cheap_provider": cheap.provider,
+                        "cheap_avg_cost_usd": round(cheap.avg_cost_usd, 6),
+                        "expensive_provider": expensive.provider,
+                        "expensive_avg_cost_usd": round(expensive.avg_cost_usd, 6),
+                        "saving_pct": round(saving_pct * 100, 1),
+                    },
+                    confidence="high" if saving_pct >= 0.40 else "medium",
+                    providers_involved=[cheap.provider, expensive.provider],
+                ))
+    return suggestions
+
+
+def _rule_enable_prompt_cache(
+    providers: list[ProviderSummary],
+) -> list[RuleSuggestion]:
+    """Suggest enabling prompt_cache for large-input, low-hit providers."""
+    suggestions: list[RuleSuggestion] = []
+    for p in providers:
+        if p.request_count < _MIN_TRAFFIC:
+            continue
+        if p.avg_input_tokens < _CACHE_INPUT_THRESHOLD:
+            continue
+        if p.cache_hit_ratio >= _CACHE_HIT_RATIO_THRESHOLD:
+            continue
+        suggestions.append(RuleSuggestion(
+            rule="enable_prompt_cache",
+            title=f"Enable prompt_cache for {p.provider!r}",
+            description=(
+                f"{p.provider!r} averages {p.avg_input_tokens:.0f} input tokens/req "
+                f"but has only a {p.cache_hit_ratio * 100:.1f}% cache-hit ratio. "
+                f"Enabling prompt caching can significantly reduce input token costs "
+                f"on repeated system prompts (Anthropic models: ~10% cache-read price)."
+            ),
+            yaml_snippet=(
+                f"providers:\n"
+                f"  - name: {p.provider}\n"
+                f"    capabilities:\n"
+                f"      prompt_cache: true"
+            ),
+            evidence={
+                "provider": p.provider,
+                "avg_input_tokens": round(p.avg_input_tokens, 0),
+                "cache_hit_ratio_pct": round(p.cache_hit_ratio * 100, 1),
+                "requests": p.request_count,
+            },
+            confidence="high" if p.avg_input_tokens > 5_000 else "medium",
+            providers_involved=[p.provider],
+        ))
+    return suggestions
+
+
+def _rule_enable_drift_detection(
+    providers: list[ProviderSummary],
+    window_summary: WindowSummary,
+) -> list[RuleSuggestion]:
+    """Suggest enabling drift detection when there's meaningful traffic."""
+    active = [p for p in providers if p.request_count >= _MIN_TRAFFIC * 2]
+    if not active:
+        return []
+    # We can't know if drift detection is already on from stats alone,
+    # so this is a "low" confidence reminder for new operators.
+    names = ", ".join(f"{p.provider!r}" for p in active)
+    return [RuleSuggestion(
+        rule="enable_drift_detection",
+        title="Consider enabling L4 drift detection",
+        description=(
+            f"You have {window_summary.total_requests} requests across {names}. "
+            f"The L4 drift detector catches quality degradation in long-running "
+            f"agent sessions (empty responses, length collapse, tool silence). "
+            f"If not already configured, set drift_detection_action: promote to "
+            f"auto-demote providers that are silently degrading."
+        ),
+        yaml_snippet=(
+            "# Add to your profile in providers.yaml:\n"
+            "profiles:\n"
+            "  - name: default\n"
+            "    providers: [...]   # your provider list\n"
+            "    drift_detection_action: promote\n"
+            "    drift_detection_sensitivity: normal\n"
+            "    drift_detection_window_size: 20\n"
+            "    drift_detection_cooldown_s: 300"
+        ),
+        evidence={
+            "total_requests": window_summary.total_requests,
+            "active_providers": [p.provider for p in active],
+        },
+        confidence="low",
+        providers_involved=[p.provider for p in active],
+    )]
+
+
+def _rule_small_window_low_sensitivity(
+    providers: list[ProviderSummary],
+) -> list[RuleSuggestion]:
+    """Suggest low drift sensitivity for providers with small traffic."""
+    suggestions: list[RuleSuggestion] = []
+    for p in providers:
+        if 0 < p.request_count < _SMALL_WINDOW_THRESHOLD:
+            suggestions.append(RuleSuggestion(
+                rule="low_sensitivity_small_window",
+                title=f"Use low drift sensitivity for {p.provider!r} (sparse traffic)",
+                description=(
+                    f"{p.provider!r} has only {p.request_count} requests in the journal window. "
+                    f"With sparse traffic the drift detector's rolling window fills slowly, "
+                    f"which can cause false-positives. Setting drift_detection_sensitivity: low "
+                    f"requires more evidence before promoting the provider."
+                ),
+                yaml_snippet=(
+                    f"profiles:\n"
+                    f"  - name: default\n"
+                    f"    drift_detection_sensitivity: low   # was: normal or high\n"
+                    f"    drift_detection_window_size: 30    # larger window = more stable"
+                ),
+                evidence={
+                    "provider": p.provider,
+                    "request_count": p.request_count,
+                    "threshold": _SMALL_WINDOW_THRESHOLD,
+                },
+                confidence="medium",
+                providers_involved=[p.provider],
+            ))
+    return suggestions
+
+
+def _rule_goal_profile(
+    providers: list[ProviderSummary],
+) -> list[RuleSuggestion]:
+    """Suggest creating a goal profile when providers differ significantly in output length."""
+    import statistics as _stats
+
+    active = [p for p in providers if p.request_count >= _MIN_TRAFFIC and p.avg_output_tokens > 0]
+    if len(active) < 2:
+        return []
+
+    output_values = [p.avg_output_tokens for p in active]
+    mean_out = _stats.mean(output_values)
+    if mean_out == 0:
+        return []
+
+    stdev_out = _stats.stdev(output_values) if len(output_values) > 1 else 0.0
+    rel_stdev = stdev_out / mean_out
+
+    if rel_stdev < _OUTPUT_DIVERGENCE_THRESHOLD:
+        return []
+
+    # Highest-output provider is probably best for goal sessions
+    best = max(active, key=lambda p: p.avg_output_tokens)
+    return [RuleSuggestion(
+        rule="goal_profile",
+        title=f"Create a 'goal' profile with goal_mode: true → {best.provider!r}",
+        description=(
+            f"Output token lengths vary significantly across providers "
+            f"(relative std-dev {rel_stdev * 100:.0f}%). "
+            f"{best.provider!r} produces the most tokens on average "
+            f"({best.avg_output_tokens:.0f} tokens/req), making it the "
+            f"best candidate for a dedicated goal/agent profile. "
+            f"goal_mode: true activates tighter drift thresholds and "
+            f"the goal_progress_stall signal for repetition detection."
+        ),
+        yaml_snippet=(
+            "profiles:\n"
+            f"  - name: goal\n"
+            f"    providers:\n"
+            f"      - {best.provider}\n"
+            f"    goal_mode: true                   # P1-5: tighter thresholds\n"
+            f"    drift_detection_action: promote\n"
+            f"    drift_detection_sensitivity: high  # overridden by goal_mode\n"
+            f"    drift_detection_window_size: 15\n"
+            f"    drift_detection_cooldown_s: 180"
+        ),
+        evidence={
+            "best_provider": best.provider,
+            "best_avg_output_tokens": round(best.avg_output_tokens, 0),
+            "mean_output_tokens": round(mean_out, 0),
+            "relative_stdev_pct": round(rel_stdev * 100, 1),
+        },
+        confidence="medium",
+        providers_involved=[p.provider for p in active],
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def suggest_rules(summary: WindowSummary) -> list[RuleSuggestion]:
+    """Analyse a :class:`WindowSummary` and return a list of rule suggestions.
+
+    Parameters
+    ----------
+    summary:
+        Output of :func:`coderouter.state.replay.summarize_window`.
+
+    Returns
+    -------
+    List of :class:`RuleSuggestion` objects, ordered by confidence
+    (``high`` first) then rule name.
+    """
+    providers = list(summary.providers.values())
+    suggestions: list[RuleSuggestion] = []
+
+    suggestions.extend(_rule_provider_reorder(providers))
+    suggestions.extend(_rule_enable_prompt_cache(providers))
+    suggestions.extend(_rule_enable_drift_detection(providers, summary))
+    suggestions.extend(_rule_small_window_low_sensitivity(providers))
+    suggestions.extend(_rule_goal_profile(providers))
+
+    _CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
+    suggestions.sort(key=lambda s: (_CONFIDENCE_ORDER.get(s.confidence, 9), s.rule))
+    return suggestions
+
+
+def format_suggestions(suggestions: list[RuleSuggestion]) -> str:
+    """Render suggestions as a human-readable terminal report.
+
+    Returns a plain-text string with section headers, descriptions,
+    and copy-paste YAML snippets.
+    """
+    if not suggestions:
+        return "No routing rule suggestions — current configuration looks healthy."
+
+    lines: list[str] = []
+    lines.append(f"Found {len(suggestions)} suggestion(s):\n")
+
+    for i, s in enumerate(suggestions, 1):
+        conf_badge = {"high": "[HIGH]", "medium": "[MED] ", "low": "[LOW] "}.get(
+            s.confidence, "[?]   "
+        )
+        lines.append(f"  {i}. {conf_badge} {s.title}")
+        lines.append(f"     {s.description}")
+        if s.evidence:
+            evidence_str = ", ".join(f"{k}={v}" for k, v in s.evidence.items())
+            lines.append(f"     Evidence: {evidence_str}")
+        lines.append("")
+        lines.append("     YAML:")
+        for yaml_line in s.yaml_snippet.splitlines():
+            lines.append(f"       {yaml_line}")
+        lines.append("")
+        if i < len(suggestions):
+            lines.append("  " + "-" * 68)
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+__all__ = [
+    "RuleSuggestion",
+    "format_suggestions",
+    "suggest_rules",
+]

{coderouter_cli-2.3.0a3.dist-info → coderouter_cli-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.3.0a3
+Version: 2.4.0
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <a href="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml"><img src="https://github.com/zephel01/CodeRouter/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
-  <a href=""><img src="https://img.shields.io/badge/version-2.2.0-blue" alt="version"></a>
+  <a href="https://pypi.org/project/coderouter-cli/"><img src="https://img.shields.io/pypi/v/coderouter-cli?include_prereleases&color=blue&label=pypi" alt="pypi"></a>
   <a href=""><img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="python"></a>
   <a href=""><img src="https://img.shields.io/badge/deps-5-brightgreen" alt="deps"></a>
   <a href=""><img src="https://img.shields.io/badge/license-MIT-yellow" alt="license"></a>

{coderouter_cli-2.3.0a3.dist-info → coderouter_cli-2.4.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 coderouter/__init__.py,sha256=ghdjPrLtnRzY8fyQ4CJZI1UJKADyNTLtA3G7se8H7Ns,696
 coderouter/__main__.py,sha256=-LCgxJnvgUV240HjQKv7ly-mn2NuKHpC4nCpvTHjeSU,130
-coderouter/cli.py,sha256=CyD-35kb-XbuUd2zrldzOcE13od3_Qmmh4lUxNLA7-Q,26611
+coderouter/cli.py,sha256=lSrQBj7iYz39EbPfBNm8l-ZGe-dPIHUd_wG0KPTvpiQ,28154
 coderouter/cli_stats.py,sha256=CCjzc1G4hTRHZ2gG1XhxhDpUkJnnl3NXbcbp1T18jpg,29894
 coderouter/cost.py,sha256=jf70XTTjEfWddHkOohErqSo5TfmIG42zQpBT_5faPNA,5881
 coderouter/doctor.py,sha256=2luNk6BHSRvpQStJnHcqzNvNi-SKdOuKV0WZdorZhVk,82854
@@ -19,15 +19,16 @@ coderouter/config/__init__.py,sha256=FODEn74fN-qZnt4INPSHswqhOlEgpL6-_onxsitSx8g
 coderouter/config/capability_registry.py,sha256=F6DetVL5oM03R4QeK1g6h_Q_zrXH0opnYDp3duZmkN4,15808
 coderouter/config/env_file.py,sha256=CoMK27fuAXm-NtoLzXb8yN2E-wDFjHQuFwiIlmgTBQw,10356
 coderouter/config/loader.py,sha256=FUEe8m4Tnmj_aul0vSctD8vKvNW-oLRoMRbTpSKqSmc,4077
-coderouter/config/schemas.py,sha256=NuD107zOGiQTIg_8Ngu8i3Rcc5mIRv9QhvrlCEJ4rfU,54756
+coderouter/config/schemas.py,sha256=1vTYTYIe_vbjbgBKJ8hbrpU12K5l3XCKXAJE85HWebA,55853
 coderouter/data/__init__.py,sha256=uNyfD9jaCvTWsBAWtaw1Fr25OSxzv3psGMfBjT1z0Cc,328
 coderouter/data/model-capabilities.yaml,sha256=2ztY4PUbGN_cWG-UUB-iPy-baeVFnGV8OcZHJUfZE7c,19290
-coderouter/guards/__init__.py,sha256=D_4bEHvLIp4deEKX9odTIoeUCdEcpWBAaO6noLTUTRk,1011
+coderouter/guards/__init__.py,sha256=5qliYBqygvVPneej7nx0uSjxDKsz7t8VzvrDgVBJlvU,1170
+coderouter/guards/_fingerprint.py,sha256=qsgNzIq9jv3FHrKL39nGJARp0cMenpN_QmWoJu87vU4,4835
 coderouter/guards/backend_health.py,sha256=Xx5OpX1x7atxghmBNDVxtwGg62zQIOsk6FmrQV4ILa4,9113
 coderouter/guards/context_budget.py,sha256=moWulVr5NtVci13vXxS0ucV4EvX2b7tbA1W1d9eQnkw,13281
 coderouter/guards/continuous_probe.py,sha256=AKNMbJ7hUJG-FDoU160BCbSEQQUyw0hBxFYMTaBZg84,11681
 coderouter/guards/drift_actions.py,sha256=A6pY5CR480Ct5rCVyjlBvjPFVc93eu_r5qcUpK9mWKc,3602
-coderouter/guards/drift_detection.py,sha256=W6f9yhVZO-J4PCeyeM9MIc40BY0tYoHGewTPU0eze0g,11011
+coderouter/guards/drift_detection.py,sha256=vlepNw_GjvmpHZHTkMS5JM7XKxHaRxzjj_GfopRa1M0,13489
 coderouter/guards/memory_pressure.py,sha256=mul1KXO9oE1i424cs92Sk6uzoRrV6Seck2Lk3bu-w68,7903
 coderouter/guards/self_healing.py,sha256=_fT_EJvTTp5VSi-qAP93J_1LkgPK5jkzsyrUHdKC45A,13853
 coderouter/guards/tool_loop.py,sha256=EzeMcmU7BLeTW2jsRVevU81l5rhWcn1oUr7EpzgXjVM,15209
@@ -40,7 +41,7 @@ coderouter/ingress/openai_routes.py,sha256=Zw1efPw9DI6GgV8ZcLrzS6Cda0KLrFkKn2GBZ
 coderouter/metrics/__init__.py,sha256=7Es351DPS7yLM0yVF_F0eesmiD83n7Zzhie44chht38,1465
 coderouter/metrics/collector.py,sha256=Q0_CY0orX8_i0EICBME5sYW2RqL2VD4SpNs8qfCnBM0,47432
 coderouter/metrics/prometheus.py,sha256=YRqyT931s40zVkIj07D-M2UNfDhIEElVFRz3izdJcnQ,24419
-coderouter/plugins/__init__.py,sha256=BWqgSEIMRxyTNEDdUm7B0weHE6HyKyHNgMaIJFnwnfA,2083
+coderouter/plugins/__init__.py,sha256=76hMLe5dV_ilripHXzWn3HSYoIALjzlw4EJVyI-GyIM,1974
 coderouter/plugins/base.py,sha256=n9hsck2NCSqi6oeHIumKC5zhQ8JGwCXUz7J5AZQCQss,5772
 coderouter/plugins/loader.py,sha256=xAIf6bIuth0QXCzwxO_ja6aSUlLzIqZNbrbQNJDgSE8,6841
 coderouter/plugins/registry.py,sha256=Tx0QHJHozZ5LTUliGylBdNVcdzHTBV0nedCUwGlbLMM,3236
@@ -49,18 +50,19 @@ coderouter/routing/adaptive.py,sha256=G2o377twGSjbUh65wiIFx6klnpFGjsD_nI3oDvcBwh
 coderouter/routing/auto_router.py,sha256=4_sQR0ztSED9FgQSvQqgqSiydyQVY_qOSRvwyZ5BfRc,12909
 coderouter/routing/budget.py,sha256=A3_i44tmS3SrqVNnoGkLKMsiYwI_Ug6m5-3gitVoQSM,8452
 coderouter/routing/capability.py,sha256=ziIDuE5keH_jxYDlXSKufRVxxSYOAvUxJ6Rw5QkYDDU,18436
-coderouter/routing/fallback.py,sha256=o5GAAwfyn_rOulvtZKQq8Z1Xhi_UNLs4Tyn0jBocN-M,101836
-coderouter/state/__init__.py,sha256=mmINqwIyIu6-zt-Qo-7Ddxdxz_-5vzuPjLvjYW5T_bk,782
+coderouter/routing/fallback.py,sha256=P3f6Yna1EGnLAT-ZS5ADrrZ-qRWc-M5xvwEuan4rmcs,104568
+coderouter/state/__init__.py,sha256=XoGcPmmBQSiZWML2S0juSveQ78xfhtdeCliNnVyzu7E,1088
 coderouter/state/audit_log.py,sha256=JwGd0OkkDlkh0Fdc6SmnuyViwKzEaFA7Ux_VqHzakWE,8358
 coderouter/state/replay.py,sha256=Z_YHKroTKZdrL8qObFxcoLOAQWWXZvXFdLfxzvBhEJg,11230
 coderouter/state/request_log.py,sha256=bR814sOn--U_sKVtbezwS3bkZaNt4FGnboX75_2LLiU,5908
 coderouter/state/store.py,sha256=h-rsMJq8GILsOfCP94nI40cuHaj4Vqycsm9UNN77REI,7445
+coderouter/state/suggest_rules.py,sha256=z9a9dTUm-l7mvRV48G7_tWtV2p24F0bQo2ijz8kf_2k,16674
 coderouter/translation/__init__.py,sha256=PYXN7XVEwpG1uC8RLy6fvnGbzEZhhrEuUapH8IYOtG8,1788
 coderouter/translation/anthropic.py,sha256=JpvIWNXHUPVqOGvps7o_6ZADhXuJuvpU7RdMqQFtwwM,6421
 coderouter/translation/convert.py,sha256=-qyzFzmmr9hhQV6_Sg75kJnvCZvHe3n7vRdaZtk_JqQ,47269
 coderouter/translation/tool_repair.py,sha256=Ok2PF947Liegc5oaytfptv5MWMkpfJYQie-zdP1y3cY,9946
-coderouter_cli-2.3.0a3.dist-info/METADATA,sha256=hWfTPzx1x-ut7NIjf1hi4ETWo4MsEn4s3q_XlU9Sxfw,9993
-coderouter_cli-2.3.0a3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-coderouter_cli-2.3.0a3.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
-coderouter_cli-2.3.0a3.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
-coderouter_cli-2.3.0a3.dist-info/RECORD,,
+coderouter_cli-2.4.0.dist-info/METADATA,sha256=nCXZKj29kM_o53ajIWgOI9PaGx_k4nBtIw-WvO_6MsU,10067
+coderouter_cli-2.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+coderouter_cli-2.4.0.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
+coderouter_cli-2.4.0.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
+coderouter_cli-2.4.0.dist-info/RECORD,,