coderouter-cli 1.7.0__py3-none-any.whl

coderouter/ingress/metrics_routes.py

@@ -0,0 +1,92 @@
+"""Metrics endpoint — ``GET /metrics.json`` (v1.5-A).
+
+The endpoint returns a JSON-safe snapshot from the process-global
+:class:`coderouter.metrics.MetricsCollector`. It is mounted at the
+root (no ``/v1`` prefix) because the metrics payload is not part of
+the OpenAI / Anthropic API surface and because Prometheus-shaped
+exporters conventionally live at ``/metrics`` on the root.
+
+v1.5 scope (plan.md §12.3.4)
+    - ``GET /metrics.json``   — JSON shape, internal / dashboard consumer.
+    - ``GET /metrics``        — v1.5-B: Prometheus text exposition
+      format, content-type ``text/plain; version=0.0.4; charset=utf-8``.
+      Same collector singleton as ``/metrics.json``.
+    - ``GET /dashboard``      — HTML one-pager. Lands in v1.5-D.
+
+The JSON handler merges a little context from ``app.state`` (namely the
+resolved config's allow_paid + paid-vs-free provider classification)
+so the dashboard can compute the "local / free / paid" usage-mix
+without each UI re-reading providers.yaml. The Prometheus handler
+stays strict-spec — only the metrics payload, no extra stanzas — so
+``promtool check metrics`` round-trips cleanly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Request
+from fastapi.responses import PlainTextResponse
+
+from coderouter.metrics import format_prometheus, get_collector
+
+router = APIRouter()
+
+# Prometheus text exposition v0.0.4 content type. Prom parsers will fall
+# back to plain ``text/plain`` if missing, but being explicit pins the
+# negotiated media type when a Grafana Agent or OTel collector probes us.
+_PROM_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+
+@router.get("/metrics.json")
+async def metrics_json(request: Request) -> dict[str, Any]:
+    """Return the current MetricsCollector snapshot as JSON.
+
+    Merges in a ``config`` stanza sourced from ``app.state.config`` —
+    this is static for the lifetime of the process (providers.yaml is
+    loaded once at startup) so it's cheap to re-emit per request. The
+    dashboard uses it to classify providers into local / free / paid
+    for the usage-mix bar without a second endpoint round-trip.
+    """
+    snapshot = get_collector().snapshot()
+
+    config = getattr(request.app.state, "config", None)
+    if config is not None:
+        snapshot["config"] = {
+            "default_profile": config.default_profile,
+            "allow_paid": config.allow_paid,
+            # v1.5-E: display-only TZ hint for /dashboard + coderouter stats.
+            # Stays ``None`` when unset so clients can keep their UTC fallback
+            # without probing for a string value.
+            "display_timezone": config.display_timezone,
+            "providers": [
+                {
+                    "name": p.name,
+                    "kind": p.kind,
+                    "paid": p.paid,
+                    # ``HttpUrl`` is not JSON-serializable directly in Pydantic v2;
+                    # the cast also makes the shape stable if Pydantic switches types.
+                    "base_url": str(p.base_url),
+                }
+                for p in config.providers
+            ],
+            "profiles": [
+                {"name": pr.name, "providers": list(pr.providers)}
+                for pr in config.profiles
+            ],
+        }
+    return snapshot
+
+
+@router.get("/metrics", response_class=PlainTextResponse)
+async def metrics_prometheus() -> PlainTextResponse:
+    """Prometheus text exposition format (v1.5-B).
+
+    Convention-compliant endpoint path for Prometheus scrapers. Returns
+    the same counters the JSON snapshot surfaces, rendered per
+    https://prometheus.io/docs/instrumenting/exposition_formats/ .
+    Sits alongside :func:`metrics_json` (not a replacement) — JSON is
+    for internal UI, Prometheus is for external time-series DBs.
+    """
+    body = format_prometheus(get_collector().snapshot())
+    return PlainTextResponse(content=body, media_type=_PROM_CONTENT_TYPE)

coderouter/ingress/openai_routes.py

@@ -0,0 +1,153 @@
+"""OpenAI-compatible routes: POST /v1/chat/completions (+ minimal /v1/models).
+
+Profile selection precedence (first hit wins):
+    1. JSON body field:  {"profile": "fast", ...}
+    2. HTTP header:       X-CodeRouter-Profile: fast
+    3. HTTP header:       X-CodeRouter-Mode: coding  (v0.6-D, via mode_aliases)
+    4. auto_router       (v1.6-A, fires only when default_profile == "auto")
+    5. config.default_profile
+
+Body wins over header so that a caller who can embed the field has final say
+(useful when a single client talks to multiple routers behind a proxy that
+rewrites headers). Mode sits below Profile because Mode is an INTENT
+(``coding`` / ``long`` / ``fast``) and Profile is the concrete
+implementation — when a caller specifies the concrete profile, respect it.
+
+The auto router slot is intentionally narrow: it only fires when the operator
+opts in via ``default_profile: auto`` (the reserved sentinel). For every other
+configuration the chain behaves exactly as in v0.6-D — unresolved requests fall
+through to the engine, which applies ``config.default_profile``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import 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
+
+router = APIRouter()
+logger = get_logger(__name__)
+
+_PROFILE_HEADER = "x-coderouter-profile"
+_MODE_HEADER = "x-coderouter-mode"
+
+
+@router.get("/models")
+async def list_models(request: Request) -> dict[str, object]:
+    """Minimal /v1/models so OpenAI SDKs that probe it don't choke."""
+    config = request.app.state.config
+    return {
+        "object": "list",
+        "data": [
+            {
+                "id": p.name,
+                "object": "model",
+                "created": int(time.time()),
+                "owned_by": "coderouter",
+            }
+            for p in config.providers
+        ],
+    }
+
+
+@router.post("/chat/completions", response_model=None)
+async def chat_completions(
+    payload: dict[str, Any],
+    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]:
+    """OpenAI Chat Completions endpoint.
+
+    Validates the body into :class:`ChatRequest`, resolves the profile
+    per the precedence described in the module docstring, and dispatches
+    to the engine. Streaming requests return a :class:`StreamingResponse`
+    that serializes chunks onto the OpenAI SSE wire (``data: {json}`` +
+    trailing ``data: [DONE]``); non-streaming requests return the JSON
+    response body.
+    """
+    engine: FallbackEngine = request.app.state.engine
+    config = request.app.state.config
+
+    # Accept extension fields (e.g. "profile") without rejecting
+    try:
+        chat_req = ChatRequest.model_validate(payload)
+    except Exception as exc:  # pydantic.ValidationError, etc.
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # Header-based override (body wins if both are set — see module docstring)
+    if chat_req.profile is None and x_coderouter_profile:
+        chat_req.profile = x_coderouter_profile
+
+    # v0.6-D: ``X-CodeRouter-Mode`` → mode_aliases → profile. Only kicks
+    # in when neither body nor X-CodeRouter-Profile already nailed down
+    # the profile (profile > mode precedence).
+    if chat_req.profile is None and x_coderouter_mode:
+        try:
+            chat_req.profile = config.resolve_mode(x_coderouter_mode)
+        except KeyError as exc:
+            available = sorted(config.mode_aliases.keys())
+            raise HTTPException(
+                status_code=400,
+                detail=(f"unknown mode {x_coderouter_mode!r}. available modes: {available}"),
+            ) from exc
+        logger.info(
+            "mode-alias-resolved",
+            extra={"mode": x_coderouter_mode, "profile": chat_req.profile},
+        )
+
+    # v1.6-A: auto router slot. Only fires when the operator opted in by
+    # setting ``default_profile: auto`` and no higher-priority caller signal
+    # (body / profile header / mode header) already nailed down a profile.
+    # When inactive, the engine still falls through to
+    # ``config.default_profile`` on its own — same semantics as pre-v1.6.
+    if chat_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
+        chat_req.profile = classify(payload, config)
+
+    # Validate profile exists before we kick off any upstream call
+    if chat_req.profile is not None:
+        try:
+            config.profile_by_name(chat_req.profile)
+        except KeyError as exc:
+            available = [p.name for p in config.profiles]
+            raise HTTPException(
+                status_code=400,
+                detail=(f"unknown profile {chat_req.profile!r}. available: {available}"),
+            ) from exc
+
+    if chat_req.stream:
+        return StreamingResponse(
+            _sse_iterator(engine, chat_req),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    try:
+        response = await engine.generate(chat_req)
+    except NoProvidersAvailableError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    return response.model_dump(exclude_none=True)
+
+
+async def _sse_iterator(engine: FallbackEngine, chat_req: ChatRequest) -> AsyncIterator[str]:
+    """Wrap the engine's stream into SSE wire format."""
+    try:
+        async for chunk in engine.stream(chat_req):
+            data = chunk.model_dump(exclude_none=True)
+            yield f"data: {json.dumps(data, ensure_ascii=False)}\n\n"
+        yield "data: [DONE]\n\n"
+    except NoProvidersAvailableError as exc:
+        # Encode the error inside the SSE channel — OpenAI clients handle this
+        err = {"error": {"message": str(exc), "type": "no_providers_available"}}
+        yield f"data: {json.dumps(err, ensure_ascii=False)}\n\n"
+        yield "data: [DONE]\n\n"

coderouter/logging.py

@@ -0,0 +1,315 @@
+"""Tiny structured-logging helper.
+
+We don't pull in structlog/loguru — see plan.md §5.4. stdlib logging + a
+custom formatter that emits JSON lines is enough for v0.1.
+
+v0.5.1 additions
+    ``CapabilityDegradedReason`` / ``CapabilityDegradedPayload`` /
+    ``log_capability_degraded`` are the typed contract for the
+    ``capability-degraded`` log line (v0.5 gate trio). They live here —
+    rather than in ``coderouter/routing/capability.py`` where they fit
+    semantically — because (a) importing anything from the ``routing``
+    package eagerly triggers ``routing/__init__.py`` which pulls
+    ``FallbackEngine`` and creates a cycle with adapter modules that
+    want to emit the same log, and (b) logging.py is a dependency-free
+    leaf, so it is the safest home for a cross-cutting log shape.
+    ``capability.py`` re-exports all three for discoverability.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any, Literal, TypedDict
+
+
+class JsonLineFormatter(logging.Formatter):
+    """Emit each record as a single JSON line."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Render a LogRecord as a single-line JSON string.
+
+        Standard ``logging`` attributes (levelname, funcName, lineno, …)
+        are whitelisted out; everything attached via ``extra={...}`` is
+        included, so structured calls like
+        ``logger.info("evt", extra={"provider": "ollama"})`` surface
+        ``"provider": "ollama"`` verbatim in the output line.
+        """
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, datefmt="%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        # Pick up custom attributes attached via `extra={...}`
+        for key, value in record.__dict__.items():
+            if key in {
+                "args",
+                "asctime",
+                "created",
+                "exc_info",
+                "exc_text",
+                "filename",
+                "funcName",
+                "levelname",
+                "levelno",
+                "lineno",
+                "message",
+                "module",
+                "msecs",
+                "msg",
+                "name",
+                "pathname",
+                "process",
+                "processName",
+                "relativeCreated",
+                "stack_info",
+                "thread",
+                "threadName",
+                "taskName",
+            }:
+                continue
+            payload[key] = value
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Install JSON-line logging on the root logger. Idempotent."""
+    root = logging.getLogger()
+    root.setLevel(level.upper())
+    # Avoid duplicate handlers on reload
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(JsonLineFormatter())
+    root.addHandler(handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Alias for :func:`logging.getLogger` — exists so modules can import
+    from :mod:`coderouter.logging` without reaching into stdlib directly,
+    keeping future logger customization (tags, adapters, …) to one line.
+    """
+    return logging.getLogger(name)
+
+
+# ---------------------------------------------------------------------------
+# v0.5.1: capability-degraded log shape
+#
+# Single chokepoint for the log line emitted by the v0.5 capability gates
+# (thinking / cache_control / reasoning). See module docstring above for
+# why this lives in logging.py rather than in capability.py.
+# ---------------------------------------------------------------------------
+
+CapabilityDegradedReason = Literal[
+    "provider-does-not-support",
+    "translation-lossy",
+    "non-standard-field",
+]
+"""Why a capability was degraded.
+
+- ``provider-does-not-support``: the provider's wire format would 400 on
+  the field. v0.5-A thinking gate; request-side strip happens before the
+  call.
+- ``translation-lossy``: the field has no equivalent in the target wire
+  format so it is dropped during translation. v0.5-B cache_control;
+  observability only — no strip happens inside the gate itself (the
+  translation layer already drops the marker).
+- ``non-standard-field``: upstream emits a field that is not in the spec
+  the ingress speaks, so we strip it on the response-side boundary.
+  v0.5-C reasoning field.
+"""
+
+
+class CapabilityDegradedPayload(TypedDict):
+    """Structured shape of the ``capability-degraded`` log record.
+
+    Fields
+        provider: the ``name:`` of the ProviderConfig that degraded — so
+            operators can correlate with the ``provider-failed`` /
+            ``provider-ok`` lines sharing that key.
+        dropped: list of capability names affected. Single-element today
+            (``["thinking"]`` / ``["cache_control"]`` / ``["reasoning"]``)
+            but typed as a list so a single call can report multiple
+            simultaneous drops in the future without a schema break.
+        reason: see ``CapabilityDegradedReason``.
+    """
+
+    provider: str
+    dropped: list[str]
+    reason: CapabilityDegradedReason
+
+
+def log_capability_degraded(
+    logger: logging.Logger,
+    *,
+    provider: str,
+    dropped: list[str],
+    reason: CapabilityDegradedReason,
+) -> None:
+    """Emit a ``capability-degraded`` log record with the unified shape.
+
+    Single chokepoint for the log. Keyword-only args force callers through
+    the TypedDict contract at the static-type level. The ``logger``
+    argument is passed in so the record's ``logger`` name (captured by
+    JsonLineFormatter) reflects the site of the degradation — request-side
+    gates emit under ``coderouter.routing.fallback``, response-side under
+    ``coderouter.adapters.openai_compat``. That distinction is useful
+    when reading the log alongside the surrounding ``try-provider`` /
+    ``provider-ok`` trail.
+    """
+    payload: CapabilityDegradedPayload = {
+        "provider": provider,
+        "dropped": dropped,
+        "reason": reason,
+    }
+    logger.info("capability-degraded", extra=payload)
+
+
+# ---------------------------------------------------------------------------
+# v0.6-C: chain-paid-gate-blocked log shape
+#
+# Motivation (plan.md §9.3 #3, "宣言的 ALLOW_PAID gate"):
+#   v0.1 already filters ``paid: true`` providers from the chain when
+#   ``allow_paid=False`` (per-provider INFO ``skip-paid-provider``), but
+#   when the gate ends up filtering the ENTIRE chain to empty, the
+#   operator-visible symptom is a generic ``NoProvidersAvailableError``.
+#   A dedicated aggregate warn makes the gate "declarative" in the same
+#   sense as v0.5's capability gates: the rule is visible in one line.
+#
+# Scope:
+#   - Fires once per request (the 4 engine entry points), only when the
+#     chain resolves to ZERO adapters AND at least one provider was
+#     filtered out by the paid gate. Mixed chains where at least one
+#     free provider survives stay quiet — they proceed into the normal
+#     try-provider / provider-failed trail.
+#   - ``skip-paid-provider`` is still emitted per-provider at INFO so
+#     per-provider traceability is intact. This warn sits at a coarser
+#     granularity (one line per blocked chain).
+# ---------------------------------------------------------------------------
+
+_DEFAULT_PAID_GATE_HINT: str = (
+    "set ALLOW_PAID=true, mark a provider paid=false, "
+    "or add a free provider to this profile's chain"
+)
+
+
+class ChainPaidGateBlockedPayload(TypedDict):
+    """Structured shape of the ``chain-paid-gate-blocked`` log record.
+
+    Fields
+        profile: the active profile name (resolved, not user-supplied —
+            so after falling back to ``default_profile``).
+        blocked_providers: names of providers on this chain that were
+            ``paid: true`` and filtered out by the gate. Order matches
+            their position in the chain (same as what the ``skip-paid-
+            provider`` INFO lines report individually).
+        hint: a one-line remediation suggestion — stable text so it can
+            be grepped, overridable at the call site when context-
+            specific advice is warranted.
+    """
+
+    profile: str
+    blocked_providers: list[str]
+    hint: str
+
+
+def log_chain_paid_gate_blocked(
+    logger: logging.Logger,
+    *,
+    profile: str,
+    blocked_providers: list[str],
+    hint: str = _DEFAULT_PAID_GATE_HINT,
+) -> None:
+    """Emit a ``chain-paid-gate-blocked`` warn with the unified shape.
+
+    Single chokepoint mirroring :func:`log_capability_degraded`. Warn
+    level (not info) because an empty chain is always a config problem
+    the operator needs to see — whereas the per-provider
+    ``skip-paid-provider`` can stay info (the chain as a whole may still
+    be viable).
+    """
+    payload: ChainPaidGateBlockedPayload = {
+        "profile": profile,
+        "blocked_providers": blocked_providers,
+        "hint": hint,
+    }
+    logger.warning(
+        "chain-paid-gate-blocked",
+        extra=payload,
+    )
+
+
+# ---------------------------------------------------------------------------
+# v1.0-A: output-filter-applied log shape
+#
+# Motivation (plan.md §10.2 "出力クリーニング" / retrospective v0.7 "transformation
+# には probe が伴う"):
+#   ``output_filters`` is an operator opt-in (declared in providers.yaml)
+#   rather than a passive / silent strip, so it does not fit the
+#   ``capability-degraded`` vocabulary — nothing is "degraded" when a user
+#   explicitly asked for scrubbing. A dedicated typed log line keeps the
+#   observability surface legible (grep for ``output-filter-applied`` to
+#   see exactly when a filter fired, for which provider, via which
+#   filters).
+#
+# Scope:
+#   - Fires ONCE per generate()/stream() call (log-once, mirroring the
+#     v0.5-C reasoning-strip dedupe).
+#   - Only fires when at least one filter actually modified the stream.
+#     A chain configured but never triggered stays quiet.
+# ---------------------------------------------------------------------------
+
+
+class OutputFilterAppliedPayload(TypedDict):
+    """Structured shape of the ``output-filter-applied`` log record.
+
+    Fields
+        provider: the ``name:`` of the ProviderConfig whose adapter ran
+            the chain — correlates with surrounding ``provider-ok`` /
+            ``provider-failed`` log lines.
+        filters: names of filters that actually modified the stream
+            (subset of the configured chain, preserving declaration
+            order). Single-entry today when only ``strip_thinking``
+            triggers, multi-entry once an operator enables two+.
+        streaming: True if emitted from the streaming path, False from
+            non-streaming. Lets a log-reading operator distinguish
+            "filter fired mid-stream" from "filter fired on the final
+            body" without cross-referencing the surrounding request
+            metadata.
+    """
+
+    provider: str
+    filters: list[str]
+    streaming: bool
+
+
+def log_output_filter_applied(
+    logger: logging.Logger,
+    *,
+    provider: str,
+    filters: list[str],
+    streaming: bool,
+) -> None:
+    """Emit an ``output-filter-applied`` info record.
+
+    Single chokepoint mirroring :func:`log_capability_degraded`.
+    Called at most once per request/stream — adapter threads a
+    dedupe flag on the enclosing call. ``filters`` SHOULD be the subset
+    that actually modified text (see ``OutputFilterChain.applied_filters``),
+    not the declared chain — so a chain of ``[strip_thinking,
+    strip_stop_markers]`` where only the first triggers logs
+    ``filters=["strip_thinking"]``.
+    """
+    payload: OutputFilterAppliedPayload = {
+        "provider": provider,
+        "filters": filters,
+        "streaming": streaming,
+    }
+    logger.info(
+        "output-filter-applied",
+        extra=payload,
+    )

coderouter/metrics/__init__.py

@@ -0,0 +1,39 @@
+"""CodeRouter metrics collection (v1.5-A).
+
+The metrics layer taps the existing structured-logging stream rather than
+adding new instrumentation hooks throughout the routing/adapter code.
+Rationale (plan.md §12.3.1): every metric the v1.5 dashboard needs is
+already in a ``capability-degraded`` / ``provider-ok`` / ``try-provider``
+/ ``output-filter-applied`` / ``chain-paid-gate-blocked`` / ``skip-paid-
+provider`` / ``provider-failed`` record — so wiring a
+``logging.Handler`` subclass onto the root logger gives us lossless
+collection with zero risk of regression.
+
+Public surface
+    :class:`MetricsCollector`
+        ``logging.Handler`` subclass that maintains in-memory counters,
+        last-error snapshots per provider, and a ring buffer of recent
+        events. ``snapshot()`` returns a JSON-safe dict consumed by the
+        ``/metrics.json`` endpoint.
+
+    :func:`get_collector` / :func:`install_collector`
+        Module-level singleton accessors. The ingress ``create_app``
+        lifespan calls ``install_collector()`` at startup; ``/metrics.json``
+        and tests read via ``get_collector()``. Idempotent.
+"""
+
+from coderouter.metrics.collector import (
+    MetricsCollector,
+    get_collector,
+    install_collector,
+    uninstall_collector,
+)
+from coderouter.metrics.prometheus import format_prometheus
+
+__all__ = [
+    "MetricsCollector",
+    "format_prometheus",
+    "get_collector",
+    "install_collector",
+    "uninstall_collector",
+]