coderouter-cli 2.14.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

coderouter/ingress/openai_routes.py

@@ -29,12 +29,13 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 from fastapi import APIRouter, Header, HTTPException, Request
-from fastapi.responses import StreamingResponse
+from fastapi.responses import JSONResponse, StreamingResponse
 
 from coderouter.adapters.base import ChatRequest
 from coderouter.logging import get_logger
 from coderouter.routing import FallbackEngine, NoProvidersAvailableError
 from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.fallback_trace import current_fallback_trace
 
 router = APIRouter()
 logger = get_logger(__name__)
@@ -179,7 +180,7 @@ async def chat_completions(
     request: Request,
     x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
     x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
-) -> StreamingResponse | dict[str, Any]:
+) -> StreamingResponse | JSONResponse | dict[str, Any]:
     """OpenAI Chat Completions endpoint.
 
     Validates the body into :class:`ChatRequest`, resolves the profile
@@ -252,6 +253,34 @@ async def chat_completions(
     except NoProvidersAvailableError as exc:
         raise HTTPException(status_code=502, detail=str(exc)) from exc
 
+    # v2.15.0: fallback reason headers, same shape and same construction as
+    # ``anthropic_routes.messages`` — the engine filled the request-scoped
+    # trace while ``generate`` was awaited, and ``header_values()`` is empty
+    # unless the chain actually moved. A request served by its first
+    # provider therefore still returns the bare dict, byte-identical to
+    # v2.14.0.
+    #
+    # Only the non-streaming half exists here, and that is deliberate. The
+    # Anthropic streaming path can carry the trail two ways: chain-resolve
+    # hops ride the HTTP headers (``apply_context_budget`` resolves the
+    # chain before the response commits) and runtime hops ride the trailing
+    # ``coderouter_fallback`` SSE event (Anthropic's wire is typed, so an
+    # unknown event type is ignored by spec-compliant SDKs). Neither is
+    # available on the OpenAI wire: this route has no pre-dispatch chain
+    # resolution, and OpenAI SSE frames are untyped — every ``data:`` line
+    # is parsed as a ChatCompletionChunk, so injecting a metadata frame
+    # would hand strict clients an object they cannot deserialize. That is
+    # a breaking change, so the streaming OpenAI path stays untouched and
+    # its reasons are available via the ``fallback-occurred`` log lines.
+    fallback_trace = current_fallback_trace()
+    if fallback_trace is not None:
+        resp_headers = fallback_trace.header_values()
+        if resp_headers:
+            return JSONResponse(
+                content=response.model_dump(exclude_none=True),
+                headers=resp_headers,
+            )
+
     return response.model_dump(exclude_none=True)
 
 

coderouter/logging.py

@@ -1479,6 +1479,63 @@ def log_empty_response_detected(
     )
 
 
+# ---------------------------------------------------------------------------
+# v2.15.0 (stream-truncation): upstream SSE ended without a terminator
+#
+# Fired from the adapter's SSE parse loop when ``stream_truncation_action``
+# is ``warn`` or ``error`` and the upstream line iterator was exhausted
+# without a ``message_stop`` (Anthropic wire) / ``[DONE]`` or a
+# ``finish_reason`` (OpenAI wire).
+#
+# ``action`` records which knob value produced the line, so a dashboard can
+# separate "we only measured it" (``warn``) from "we acted on it" (``error``).
+# ``events_forwarded`` is how many events/chunks the adapter had already
+# yielded — 0 means nothing reached the engine and a clean fallback is still
+# possible. ``tool_call_in_flight`` is the sharp edge: True means a
+# ``tool_use`` / ``tool_calls`` block was still open, so whatever the
+# translation layer synthesizes closes a block whose argument JSON is
+# provably incomplete.
+# ---------------------------------------------------------------------------
+
+
+def log_stream_truncation_detected(
+    logger: logging.Logger,
+    provider: str,
+    *,
+    action: str,
+    wire: str,
+    events_forwarded: int,
+    saw_stream_start: bool,
+    tool_call_in_flight: bool = False,
+) -> None:
+    """Emit a ``stream-truncation-detected`` warn line.
+
+    Args:
+        logger: Target logger.
+        provider: ``ProviderConfig.name`` whose stream was cut.
+        action: The ``stream_truncation_action`` value in effect (``warn``
+            or ``error`` — ``off`` never reaches here).
+        wire: ``anthropic`` or ``openai`` — which SSE dialect was being
+            parsed, i.e. which terminator went missing.
+        events_forwarded: Count of events/chunks already yielded downstream.
+        saw_stream_start: Whether the opening event (``message_start`` /
+            first data chunk) had arrived at all. False means the upstream
+            produced nothing before closing.
+        tool_call_in_flight: Whether a tool-call block was still open.
+    """
+    logger.warning(
+        "stream-truncation-detected",
+        extra={
+            "provider": provider,
+            "action": action,
+            "wire": wire,
+            "events_forwarded": events_forwarded,
+            "saw_stream_start": saw_stream_start,
+            "tool_call_in_flight": tool_call_in_flight,
+        },
+    )
+
+
 # ---------------------------------------------------------------------------
 # v2.0-I: Continuous probe log shapes
 #
@@ -1612,3 +1669,89 @@ def log_probe_capabilities_drift(
         "in_registry": in_registry,
     }
     logger.warning("probe-capabilities-drift", extra=payload)
+
+
+# ---------------------------------------------------------------------------
+# v2.15.0: fallback reason logging
+#
+# One ``fallback-occurred`` line per hop. Fires only when the chain
+# actually moves — a request served by its first provider produces no
+# line at all, so this adds zero volume to the healthy path.
+#
+# The vocabulary of ``reason`` is defined in
+# :mod:`coderouter.routing.fallback_trace` (a single canonical set that
+# also names the pre-existing ``provider-does-not-support`` /
+# ``translation-lossy`` degrade reasons, which never appear here — a
+# degrade keeps the request on the same provider).
+#
+# ``to_provider`` is ``None`` when the hop is the chain's last one and no
+# successor was ever attempted (chain exhausted). The line is still
+# emitted: "we left A because of R and had nowhere to go" is the single
+# most diagnostic event in the whole engine.
+# ---------------------------------------------------------------------------
+
+
+class FallbackOccurredPayload(TypedDict):
+    """Structured shape of the ``fallback-occurred`` log record.
+
+    Fields
+        provider: the provider being left. Duplicated from
+            ``from_provider`` under the field name every other engine
+            event uses, so existing per-provider log queries keep working
+            without learning a new key.
+        from_provider: the provider being left.
+        to_provider: the provider taking over, or None if the chain was
+            exhausted with no successor.
+        reason: canonical fallback reason (see ``fallback_trace``).
+        detail: short human-readable context (HTTP status, truncated
+            error text), or None.
+        profile: the resolved profile name, when known.
+        stream: True when the hop happened on a streaming request.
+        pre_attempt: True when the provider was filtered out during chain
+            resolution (budget / health / paid gate) and therefore never
+            actually called; False when it was called and failed.
+        hop_index: 0-based position of this hop within the request.
+    """
+
+    provider: str
+    from_provider: str
+    to_provider: str | None
+    reason: str
+    detail: str | None
+    profile: str | None
+    stream: bool
+    pre_attempt: bool
+    hop_index: int
+
+
+def log_fallback_occurred(
+    logger: logging.Logger,
+    *,
+    from_provider: str,
+    to_provider: str | None,
+    reason: str,
+    detail: str | None = None,
+    profile: str | None = None,
+    stream: bool = False,
+    pre_attempt: bool = False,
+    hop_index: int = 0,
+) -> None:
+    """Emit a ``fallback-occurred`` warning line for one chain transition.
+
+    Warn level, matching ``provider-failed`` — a fallback is a
+    degradation of the intended routing even when the request ultimately
+    succeeds, and operators grep for it when a profile's primary provider
+    stops earning its place at the front of the chain.
+    """
+    payload: FallbackOccurredPayload = {
+        "provider": from_provider,
+        "from_provider": from_provider,
+        "to_provider": to_provider,
+        "reason": reason,
+        "detail": detail,
+        "profile": profile,
+        "stream": stream,
+        "pre_attempt": pre_attempt,
+        "hop_index": hop_index,
+    }
+    logger.warning("fallback-occurred", extra=payload)

coderouter/metrics/collector.py

@@ -53,6 +53,8 @@ Event inventory (dispatch table in :meth:`MetricsCollector._dispatch`)
     ``drift-reload-attempted``   → ``drift_reload_total`` / success
     ``partial-stitch-surfaced``  → ``partial_stitch_surfaced_total`` (v2.0-H)
     ``empty-response-detected``  → ``empty_responses_total`` + per-provider (⑧)
+    ``stream-truncation-detected`` → ``stream_truncated_total`` + per-provider
+                                   + per-action (v2.15.0)
     ``probe-completed`` (v2.0-I) → ``probe_total`` / ``probe_success`` / ``probe_failure``
                                    + per-provider latency gauge
     ``probe-round-completed``    → ``probe_rounds_total`` (v2.0-I)
@@ -111,6 +113,7 @@ _KNOWN_EVENTS: Final[frozenset[str]] = frozenset(
         "drift-reload-attempted",
         "partial-stitch-surfaced",
         "empty-response-detected",
+        "stream-truncation-detected",
         "probe-completed",
         "probe-round-completed",
         "probe-capabilities-drift",
@@ -281,6 +284,16 @@ class MetricsCollector(logging.Handler):
         self._empty_responses_total: int = 0
         self._empty_responses_by_provider: Counter[str] = Counter()
 
+        # v2.15.0 (stream-truncation): count of upstream SSE streams that
+        # ended without a protocol terminator, under either ``warn`` or
+        # ``error``. Per-provider answers "which backend goes quiet"; the
+        # per-action split separates measurement from enforcement so a
+        # dashboard can show the ``warn``-phase rate before an operator
+        # commits to ``error``.
+        self._stream_truncated_total: int = 0
+        self._stream_truncated_by_provider: Counter[str] = Counter()
+        self._stream_truncated_by_action: Counter[str] = Counter()
+
         # v2.0-I: continuous probe counters. Per-provider probe attempts
         # and outcomes, plus a round counter for the dashboard's
         # "probes/min" panel.
@@ -339,6 +352,7 @@ class MetricsCollector(logging.Handler):
             "drift-reload-attempted": self._on_drift_reload_attempted,
             "partial-stitch-surfaced": self._on_partial_stitch_surfaced,
             "empty-response-detected": self._on_empty_response_detected,
+            "stream-truncation-detected": self._on_stream_truncation_detected,
             "probe-completed": self._on_probe_completed,
             "probe-round-completed": self._on_probe_round_completed,
             "probe-capabilities-drift": self._on_probe_capabilities_drift,
@@ -691,6 +705,20 @@ class MetricsCollector(logging.Handler):
             self._empty_responses_by_provider[provider] += 1
         self._push_recent("empty-response-detected", extras, record)
 
+    def _on_stream_truncation_detected(
+        self, extras: dict[str, Any], record: logging.LogRecord
+    ) -> None:
+        # v2.15.0 (stream-truncation): an upstream SSE stream ended without
+        # its terminator under a ``warn`` / ``error`` action.
+        self._stream_truncated_total += 1
+        provider = _str(extras.get("provider"))
+        if provider:
+            self._stream_truncated_by_provider[provider] += 1
+        action = _str(extras.get("action"))
+        if action:
+            self._stream_truncated_by_action[action] += 1
+        self._push_recent("stream-truncation-detected", extras, record)
+
     def _on_probe_completed(
         self, extras: dict[str, Any], record: logging.LogRecord
     ) -> None:
@@ -914,6 +942,14 @@ class MetricsCollector(logging.Handler):
                     "empty_responses_by_provider": dict(
                         self._empty_responses_by_provider
                     ),
+                    # v2.15.0 (stream-truncation).
+                    "stream_truncated_total": self._stream_truncated_total,
+                    "stream_truncated_by_provider": dict(
+                        self._stream_truncated_by_provider
+                    ),
+                    "stream_truncated_by_action": dict(
+                        self._stream_truncated_by_action
+                    ),
                     # v2.0-I: continuous probe counters.
                     "probe_total": dict(self._probe_total),
                     "probe_success": dict(self._probe_success),
@@ -1071,6 +1107,10 @@ class MetricsCollector(logging.Handler):
             # ⑧ (empty-response)
             self._empty_responses_total = 0
             self._empty_responses_by_provider.clear()
+            # v2.15.0 (stream-truncation)
+            self._stream_truncated_total = 0
+            self._stream_truncated_by_provider.clear()
+            self._stream_truncated_by_action.clear()
             # v2.0-I
             self._probe_total.clear()
             self._probe_success.clear()

coderouter/metrics/prometheus.py

@@ -443,6 +443,52 @@ def format_prometheus(snapshot: dict[str, Any]) -> str:
             )
         )
 
+    # ---- v2.15.0: stream truncation metric -----------------------------------
+    # Exported per (provider, action) so the ``warn``-phase measurement and
+    # the ``error``-phase enforcement are separable on one dashboard: a
+    # rising ``action="warn"`` series is the evidence an operator needs
+    # before flipping a profile to ``error``.
+    stream_truncated_by_provider = counters.get("stream_truncated_by_provider", {})
+    stream_truncated_total = counters.get("stream_truncated_total", 0)
+    if stream_truncated_total:
+        trunc_samples: list[tuple[tuple[tuple[str, str], ...], int]] = [
+            ((("provider", provider),), count)
+            for provider, count in sorted(stream_truncated_by_provider.items())
+        ]
+        if not trunc_samples:
+            # Detections whose log line carried no provider still count.
+            trunc_samples = [((), stream_truncated_total)]
+        lines.extend(
+            _counter(
+                name="stream_truncated_total",
+                help_text=(
+                    "Upstream SSE streams that ended without a protocol "
+                    "terminator (no message_stop / no [DONE] and no "
+                    "finish_reason), by provider. Requires "
+                    "stream_truncation_action=warn or error."
+                ),
+                samples=trunc_samples,
+            )
+        )
+        action_samples: list[tuple[tuple[tuple[str, str], ...], int]] = [
+            ((("action", action),), count)
+            for action, count in sorted(
+                counters.get("stream_truncated_by_action", {}).items()
+            )
+        ]
+        if action_samples:
+            lines.extend(
+                _counter(
+                    name="stream_truncated_by_action_total",
+                    help_text=(
+                        "Stream truncation detections by the "
+                        "stream_truncation_action value in effect "
+                        "(warn = measured only, error = fallback attempted)."
+                    ),
+                    samples=action_samples,
+                )
+            )
+
     # ---- v2.0-I: continuous probe metrics ------------------------------------
     probe_total_samples: list[tuple[tuple[tuple[str, str], ...], int]] = []
     for provider, count in sorted(counters.get("probe_total", {}).items()):

coderouter/routing/__init__.py

@@ -5,9 +5,17 @@ from coderouter.routing.fallback import (
     MidStreamError,
     NoProvidersAvailableError,
 )
+from coderouter.routing.fallback_trace import (
+    FallbackHop,
+    FallbackTrace,
+    current_fallback_trace,
+)
 
 __all__ = [
     "FallbackEngine",
+    "FallbackHop",
+    "FallbackTrace",
     "MidStreamError",
     "NoProvidersAvailableError",
+    "current_fallback_trace",
 ]