coderouter-cli 1.7.0__py3-none-any.whl

coderouter/output_filters.py

@@ -0,0 +1,407 @@
+"""v1.0-A: Declarative output filter chain.
+
+Context
+-------
+Quantized local models (and some cloud families) leak harness-internal
+markers into the assistant text stream that spec-strict clients either
+display verbatim or outright reject:
+
+    ``<think>...</think>``       — Qwen3 / DeepSeek-R1-Distill thinking track.
+    ``<|turn|>`` / ``<|end|>``   — Gemma-ish turn separators.
+    ``<|python_tag|>``           — Llama 3.x tool-use marker.
+    ``<|im_end|>``               — ChatML / Qwen end-of-turn.
+    ``<|eot_id|>``               — Llama 3.x end-of-turn.
+    ``<|channel>thought``        — OpenAI-harmony channel marker.
+
+``capabilities.reasoning_passthrough`` (v0.5-C) only governs the
+non-standard ``message.reasoning`` field; markers embedded in the
+assistant *content* slip past it. v1.0-A adds a declarative, per-
+provider opt-in chain that scrubs them at the adapter boundary.
+
+Design decisions
+----------------
+- Opt-in per provider via ``output_filters: [strip_thinking, ...]``.
+  Empty by default — the existing v0.5-C passive strip remains
+  orthogonal, and providers that WANT the thinking track (e.g.
+  CodeRouter fronting a reasoning-aware downstream) stay untouched.
+- Stateful streaming: a filter instance holds state across ``feed()``
+  calls so a ``<think>...</think>`` block spanning multiple SSE deltas
+  is coalesced. Safe-to-emit suffix management is explicit — callers
+  never see partial tags.
+- Non-streaming convenience: ``apply_output_filters(names, text)``
+  creates a chain, feeds with ``eof=True``, returns the scrubbed text.
+- Unknown filter names raise ``ValueError`` at chain construction, so
+  ``schemas.ProviderConfig`` wires this through a ``model_validator``
+  and bad configs fail at load time rather than on first request.
+- Pairs with ``coderouter doctor`` (v0.7-B): the reasoning-leak probe
+  is extended in this same sub-release to detect content-embedded
+  ``<think>`` and suggest ``output_filters: [strip_thinking]``.
+
+Reference: plan.md §10.2 "出力クリーニング" / docs/retrospectives/v0.7.md
+"transformation には probe が伴う".
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+__all__ = [
+    "DEFAULT_STOP_MARKERS",
+    "KNOWN_FILTERS",
+    "OutputFilter",
+    "OutputFilterChain",
+    "StripStopMarkersFilter",
+    "StripThinkingFilter",
+    "apply_output_filters",
+    "validate_output_filters",
+]
+
+
+# ---------------------------------------------------------------------------
+# Public constants
+# ---------------------------------------------------------------------------
+
+
+DEFAULT_STOP_MARKERS: tuple[str, ...] = (
+    "<|turn|>",
+    "<|end|>",
+    "<|python_tag|>",
+    "<|im_end|>",
+    "<|eot_id|>",
+    "<|channel>thought",
+)
+"""Default stop/harness markers stripped by ``strip_stop_markers``.
+
+Covers Llama 3.x (``<|python_tag|>``, ``<|eot_id|>``), ChatML / Qwen
+(``<|im_end|>``, ``<|end|>``), Gemma-ish (``<|turn|>``) and OpenAI-
+harmony (``<|channel>thought``). Extending this tuple is an ABI change
+— users who need a bespoke set can add a dedicated filter entry in
+a later minor; for v1.0-A the fixed list covers observed leaks.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+class OutputFilter(Protocol):
+    """Stateful streaming text filter.
+
+    Implementations MUST:
+        - Tolerate arbitrary chunking: partial tags at the end of a
+          ``feed`` input must be buffered and re-examined on the next
+          call. The caller will invoke ``feed(..., eof=True)`` exactly
+          once at the end to flush any remaining buffer.
+        - Set ``modified`` to True the first time any character in the
+          input stream would be suppressed or rewritten (regardless of
+          whether that specific ``feed`` call produced visible output).
+        - Be cheap to construct — one instance per request/stream.
+    """
+
+    name: str
+    modified: bool
+
+    def feed(self, text: str, *, eof: bool = False) -> str:
+        """Consume ``text`` and return the portion safe to emit now."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Helper: find how much of the trailing buffer could be a prefix of `needle`
+# ---------------------------------------------------------------------------
+
+
+def _max_suffix_overlap(buffer: str, needle: str) -> int:
+    """Return the longest N where ``buffer[-N:]`` equals ``needle[:N]``.
+
+    Used to decide how much of the trailing buffer to hold back so a
+    partial tag spanning chunk boundaries is not prematurely emitted.
+    Zero means the buffer ends on a character that cannot be the start
+    of ``needle``, so every byte is safe to release.
+    """
+    max_k = min(len(buffer), len(needle) - 1)
+    for k in range(max_k, 0, -1):
+        if buffer.endswith(needle[:k]):
+            return k
+    return 0
+
+
+def _max_suffix_overlap_multi(buffer: str, needles: tuple[str, ...]) -> int:
+    """``_max_suffix_overlap`` lifted over a tuple of needles — take the max."""
+    best = 0
+    for needle in needles:
+        k = _max_suffix_overlap(buffer, needle)
+        if k > best:
+            best = k
+    return best
+
+
+# ---------------------------------------------------------------------------
+# strip_thinking
+# ---------------------------------------------------------------------------
+
+
+_THINK_OPEN = "<think>"
+_THINK_CLOSE = "</think>"
+
+
+class StripThinkingFilter:
+    """Remove ``<think>...</think>`` blocks from assistant content.
+
+    State spans ``feed`` calls so a block split across SSE chunks (or
+    across a single prose paragraph containing both tags) is handled
+    correctly. The filter does NOT attempt to preserve balanced nesting
+    — the first ``</think>`` after a ``<think>`` closes the block.
+    Unmatched open tag at EOF is suppressed (the entire remainder of
+    the stream is treated as thinking).
+
+    ``modified`` flips True on the first ``<think>`` observed in the
+    stream, not on every suppressed character — the adapter uses it to
+    gate a log-once info line.
+    """
+
+    name = "strip_thinking"
+
+    def __init__(self) -> None:
+        """Initialize the per-request buffer + in-think state to empty."""
+        self.modified: bool = False
+        self._in_think: bool = False
+        self._buffer: str = ""
+
+    def feed(self, text: str, *, eof: bool = False) -> str:
+        """Append ``text`` to the buffer and return the safe-to-emit prefix.
+
+        Tags are matched greedily; a partial prefix at the buffer end
+        is held back across calls so a ``<think>`` split across two
+        SSE deltas is still recognized. At ``eof`` any unmatched open
+        tag is silently dropped (remainder treated as thinking).
+        """
+        self._buffer += text
+        out_parts: list[str] = []
+
+        while True:
+            if not self._in_think:
+                idx = self._buffer.find(_THINK_OPEN)
+                if idx != -1:
+                    out_parts.append(self._buffer[:idx])
+                    self._buffer = self._buffer[idx + len(_THINK_OPEN) :]
+                    self._in_think = True
+                    self.modified = True
+                    continue
+                # No open tag — emit all but a potential partial prefix.
+                overlap = _max_suffix_overlap(self._buffer, _THINK_OPEN)
+                if overlap:
+                    out_parts.append(self._buffer[:-overlap])
+                    self._buffer = self._buffer[-overlap:]
+                else:
+                    out_parts.append(self._buffer)
+                    self._buffer = ""
+                break
+            # in_think: suppress until we find the close tag.
+            idx = self._buffer.find(_THINK_CLOSE)
+            if idx != -1:
+                self._buffer = self._buffer[idx + len(_THINK_CLOSE) :]
+                self._in_think = False
+                continue
+            # No close tag — retain potential partial suffix, drop the rest.
+            overlap = _max_suffix_overlap(self._buffer, _THINK_CLOSE)
+            self._buffer = self._buffer[-overlap:] if overlap else ""
+            break
+
+        if eof:
+            if not self._in_think:
+                # Flush any remaining buffer (known-safe at eof).
+                out_parts.append(self._buffer)
+            # If still in_think at eof, silently drop the partial block.
+            self._buffer = ""
+        return "".join(out_parts)
+
+
+# ---------------------------------------------------------------------------
+# strip_stop_markers
+# ---------------------------------------------------------------------------
+
+
+class StripStopMarkersFilter:
+    """Remove harness/turn markers (``<|python_tag|>``, ``<|eot_id|>``, ...).
+
+    Unlike ``strip_thinking`` this is a set of point deletions rather
+    than a block suppression. The streaming concern is the same: any
+    chunk boundary might land inside a marker, so a trailing partial
+    prefix is held back until the next ``feed``.
+
+    The marker list is :data:`DEFAULT_STOP_MARKERS` — fixed for v1.0-A.
+    """
+
+    name = "strip_stop_markers"
+
+    def __init__(self, markers: tuple[str, ...] = DEFAULT_STOP_MARKERS) -> None:
+        """Initialize with an optional custom marker set.
+
+        The default :data:`DEFAULT_STOP_MARKERS` covers the observed
+        Llama 3.x / ChatML / Qwen / Gemma / harmony leaks. Tests and
+        future extensions may pass a bespoke tuple; v1.0-A does not
+        expose this knob via providers.yaml.
+        """
+        self.modified: bool = False
+        self._buffer: str = ""
+        self._markers: tuple[str, ...] = markers
+
+    def _earliest_match(self, buffer: str) -> tuple[int, str] | None:
+        """Return (position, marker) of the earliest marker in ``buffer``."""
+        best: tuple[int, str] | None = None
+        for m in self._markers:
+            idx = buffer.find(m)
+            if idx == -1:
+                continue
+            if best is None or idx < best[0]:
+                best = (idx, m)
+        return best
+
+    def feed(self, text: str, *, eof: bool = False) -> str:
+        """Emit ``text`` minus any marker matches; buffer partial prefixes.
+
+        A complete marker anywhere in the buffer is excised in place.
+        A trailing partial prefix that could complete on the next
+        :meth:`feed` is held back; at ``eof`` it is flushed verbatim
+        (we only hide bytes that are definitively part of a marker).
+        """
+        self._buffer += text
+        out_parts: list[str] = []
+
+        while True:
+            hit = self._earliest_match(self._buffer)
+            if hit is None:
+                break
+            idx, marker = hit
+            if idx:
+                out_parts.append(self._buffer[:idx])
+            self._buffer = self._buffer[idx + len(marker) :]
+            self.modified = True
+
+        # No complete match — hold back a potential partial suffix.
+        overlap = _max_suffix_overlap_multi(self._buffer, self._markers)
+        if overlap and not eof:
+            out_parts.append(self._buffer[:-overlap])
+            self._buffer = self._buffer[-overlap:]
+        else:
+            out_parts.append(self._buffer)
+            self._buffer = ""
+
+        return "".join(out_parts)
+
+
+# ---------------------------------------------------------------------------
+# Registry + chain
+# ---------------------------------------------------------------------------
+
+
+KNOWN_FILTERS: dict[str, type[OutputFilter]] = {
+    StripThinkingFilter.name: StripThinkingFilter,
+    StripStopMarkersFilter.name: StripStopMarkersFilter,
+}
+"""Registry of string-name → filter class.
+
+Declared as a dict rather than a frozen mapping so tests and future
+extensions can poke in additional filters without a schema change, but
+adapter callers should treat it as read-only.
+"""
+
+
+def validate_output_filters(names: list[str]) -> None:
+    """Raise ``ValueError`` if any name in ``names`` is not registered.
+
+    Called from ``ProviderConfig`` at config-load time so a typo like
+    ``output_filters: [strp_thinking]`` fails at startup rather than
+    silently no-op'ing forever. The error message lists all known
+    filter names so the fix is one line.
+    """
+    unknown = [n for n in names if n not in KNOWN_FILTERS]
+    if unknown:
+        raise ValueError(
+            f"Unknown output_filters entries: {unknown}. Known filters: {sorted(KNOWN_FILTERS)}"
+        )
+
+
+class OutputFilterChain:
+    """Ordered composition of ``OutputFilter`` instances.
+
+    Each ``feed`` call pipes text through every filter in declaration
+    order. ``any_applied`` is the disjunction of per-filter ``modified``
+    flags — the adapter uses it to emit a single ``output-filter-
+    applied`` info log the first time a request would have been
+    affected (dedupe mirrors the v0.5-C reasoning-strip log-once).
+
+    An empty chain is a legal no-op: ``feed`` returns ``text`` verbatim
+    and ``any_applied`` never becomes True. Adapters can unconditionally
+    thread a chain through their hot path without branching on
+    ``output_filters == []``.
+    """
+
+    def __init__(self, filter_names: list[str]) -> None:
+        """Construct a fresh chain of filters by name.
+
+        Raises :class:`ValueError` via :func:`validate_output_filters`
+        if any name is unknown — callers should be
+        :class:`ProviderConfig` (validation happens at config-load
+        time) so bad configs fail loudly at startup.
+        """
+        validate_output_filters(filter_names)
+        self._filters: list[OutputFilter] = [KNOWN_FILTERS[n]() for n in filter_names]
+        self._names: list[str] = list(filter_names)
+
+    @property
+    def names(self) -> list[str]:
+        """Ordered list of filter names (for log payloads / debugging)."""
+        return list(self._names)
+
+    @property
+    def is_empty(self) -> bool:
+        """True when no filters were configured — lets callers skip the hot path."""
+        return not self._filters
+
+    @property
+    def any_applied(self) -> bool:
+        """True if ANY filter has modified text since construction."""
+        return any(f.modified for f in self._filters)
+
+    def applied_filters(self) -> list[str]:
+        """Names of filters that actually modified text (subset of ``names``).
+
+        Stable order — matches construction order. Useful in the log
+        payload so operators can see exactly which filter triggered.
+        """
+        return [f.name for f in self._filters if f.modified]
+
+    def feed(self, text: str, *, eof: bool = False) -> str:
+        """Pipe ``text`` through every filter. ``eof`` flushes at end."""
+        for f in self._filters:
+            text = f.feed(text, eof=eof)
+        return text
+
+
+# ---------------------------------------------------------------------------
+# Non-streaming convenience
+# ---------------------------------------------------------------------------
+
+
+def apply_output_filters(filter_names: list[str], text: str) -> tuple[str, list[str]]:
+    """Run a one-shot chain over a complete text.
+
+    Returns ``(scrubbed_text, applied_filter_names)``. The second
+    element is the subset of ``filter_names`` that actually modified
+    ``text`` — the adapter passes it into the log-once helper on
+    non-streaming paths (streaming paths keep a live chain instead).
+
+    This is equivalent to::
+
+        chain = OutputFilterChain(filter_names)
+        out = chain.feed(text, eof=True)
+        applied = chain.applied_filters()
+    """
+    if not filter_names:
+        return text, []
+    chain = OutputFilterChain(filter_names)
+    out = chain.feed(text, eof=True)
+    return out, chain.applied_filters()

coderouter/routing/__init__.py

@@ -0,0 +1,13 @@
+"""Profile-based routing and fallback engine."""
+
+from coderouter.routing.fallback import (
+    FallbackEngine,
+    MidStreamError,
+    NoProvidersAvailableError,
+)
+
+__all__ = [
+    "FallbackEngine",
+    "MidStreamError",
+    "NoProvidersAvailableError",
+]

coderouter/routing/auto_router.py

@@ -0,0 +1,244 @@
+"""v1.6-A: task-aware auto routing — request-body inspection → profile name.
+
+Slots into the v0.6-D precedence chain below the mode header and above
+``default_profile``::
+
+    body.profile
+      > X-CodeRouter-Profile
+      > X-CodeRouter-Mode
+      > auto_router  (fires only when default_profile == "auto")
+      > default_profile
+
+The classifier is **rule-based** — no ML, no external calls, no small-LLM
+pre-pass. Each rule is a matcher + target profile; first match wins. If
+no rule matches, ``default_rule_profile`` is used.
+
+Design reference: ``docs/designs/v1.6-auto-router.md``.
+
+Pydantic schemas (:class:`RuleMatcher`, :class:`AutoRouteRule`,
+:class:`AutoRouterConfig`) live in ``coderouter.config.schemas`` to keep
+the routing package free of circular imports with the config loader;
+they are re-exported here for call-site ergonomics.
+
+Public surface:
+
+- :data:`BUNDLED_RULES` — the zero-config default ruleset (image →
+  multi / dense-code → coding). Falls through to ``writing`` via
+  :data:`BUNDLED_DEFAULT_RULE_PROFILE`.
+- :data:`BUNDLED_REQUIRED_PROFILES` — the three profile names the
+  bundled ruleset needs present in ``profiles[]`` (validated at load).
+- :data:`RESERVED_PROFILE_NAME` — ``"auto"``. Not allowed as a
+  user-defined profile name.
+- :func:`classify` — the classifier entry point.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING, Any
+
+from coderouter.config.schemas import AutoRouterConfig, AutoRouteRule, RuleMatcher
+
+if TYPE_CHECKING:
+    from coderouter.config.schemas import CodeRouterConfig
+
+logger = logging.getLogger("coderouter.routing.auto_router")
+
+RESERVED_PROFILE_NAME = "auto"
+BUNDLED_DEFAULT_RULE_PROFILE = "writing"
+BUNDLED_REQUIRED_PROFILES: tuple[str, ...] = ("multi", "coding", "writing")
+
+
+# ---------------------------------------------------------------------------
+# Bundled ruleset
+# ---------------------------------------------------------------------------
+
+
+BUNDLED_RULES: list[AutoRouteRule] = [
+    AutoRouteRule(
+        id="builtin:image-attachment",
+        profile="multi",
+        match=RuleMatcher(has_image=True),
+    ),
+    AutoRouteRule(
+        id="builtin:code-fence-dense",
+        profile="coding",
+        match=RuleMatcher(code_fence_ratio_min=0.3),
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Classifier
+# ---------------------------------------------------------------------------
+
+
+_FENCE_RE = re.compile(r"```[\s\S]*?```")
+
+
+def _latest_user_message(body: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the most recent ``role: user`` message, or None."""
+    messages = body.get("messages")
+    if not isinstance(messages, list):
+        return None
+    for msg in reversed(messages):
+        if isinstance(msg, dict) and msg.get("role") == "user":
+            return msg
+    return None
+
+
+def _has_image(message: dict[str, Any]) -> bool:
+    """True iff the message has any image content block.
+
+    Handles both OpenAI format (``type: image_url``) and Anthropic format
+    (``type: image``) plus the top-level ``input_image`` extension.
+    """
+    content = message.get("content")
+    if isinstance(content, list):
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            btype = block.get("type")
+            if btype in ("image_url", "image", "input_image"):
+                return True
+    return False
+
+
+def _extract_text(message: dict[str, Any]) -> str:
+    """Concatenate all text content from a message into one string.
+
+    String content stays verbatim. List content (OpenAI / Anthropic
+    multimodal format) contributes only the ``text`` of text-type blocks.
+    """
+    content = message.get("content")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        pieces: list[str] = []
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "text":
+                text = block.get("text")
+                if isinstance(text, str):
+                    pieces.append(text)
+            elif "text" in block and isinstance(block["text"], str):
+                pieces.append(block["text"])
+        return "\n".join(pieces)
+    return ""
+
+
+def _code_fence_ratio(text: str) -> float:
+    """Return the fraction of ``text`` that lies inside ``` ``` fences.
+
+    0.0 if the text is empty or has no fences. Fenced regions include
+    their opening and closing triple backticks so the math stays stable
+    regardless of language hints (```` ```python ```` vs ```` ``` ````).
+    """
+    if not text:
+        return 0.0
+    fenced = sum(len(m.group(0)) for m in _FENCE_RE.finditer(text))
+    return fenced / len(text)
+
+
+def _match_rule(rule: AutoRouteRule, message: dict[str, Any], text: str) -> bool:
+    m = rule.match
+    if m.has_image is True:
+        return _has_image(message)
+    if m.code_fence_ratio_min is not None:
+        return _code_fence_ratio(text) >= m.code_fence_ratio_min
+    if m.content_contains is not None:
+        return m.content_contains in text
+    if m.content_regex is not None:
+        return re.search(m.content_regex, text) is not None
+    return False  # pragma: no cover — _exactly_one guards against this
+
+
+def classify(body: dict[str, Any], config: CodeRouterConfig) -> str:
+    """Resolve an incoming request body to a profile name.
+
+    Rule order (first match wins) is determined by:
+
+    - ``config.auto_router.rules`` when ``auto_router`` is set and
+      ``rules`` is non-empty.
+    - :data:`BUNDLED_RULES` otherwise.
+
+    Fallthrough (no rule matches, or ``disabled`` is True) goes to
+    ``config.auto_router.default_rule_profile`` when configured, else
+    :data:`BUNDLED_DEFAULT_RULE_PROFILE`.
+
+    Emits one of two log events: ``auto-router-resolved`` on match, or
+    ``auto-router-fallthrough`` on default-rule fall.
+    """
+    user_msg = _latest_user_message(body)
+    text = _extract_text(user_msg) if user_msg is not None else ""
+
+    auto_cfg = config.auto_router
+    if auto_cfg is not None and auto_cfg.disabled:
+        _emit_fallthrough(auto_cfg.default_rule_profile, text, disabled=True)
+        return auto_cfg.default_rule_profile
+
+    rules = auto_cfg.rules if (auto_cfg is not None and auto_cfg.rules) else BUNDLED_RULES
+    default_profile = (
+        auto_cfg.default_rule_profile
+        if auto_cfg is not None
+        else BUNDLED_DEFAULT_RULE_PROFILE
+    )
+
+    if user_msg is None:
+        _emit_fallthrough(default_profile, text)
+        return default_profile
+
+    for rule in rules:
+        if _match_rule(rule, user_msg, text):
+            _emit_resolved(rule, user_msg, text)
+            return rule.profile
+
+    _emit_fallthrough(default_profile, text)
+    return default_profile
+
+
+def _emit_resolved(
+    rule: AutoRouteRule, message: dict[str, Any], text: str
+) -> None:
+    logger.info(
+        "auto-router-resolved",
+        extra={
+            "rule_id": rule.id,
+            "resolved_profile": rule.profile,
+            "signals": {
+                "has_image": _has_image(message),
+                "code_fence_ratio": round(_code_fence_ratio(text), 3),
+                "content_len": len(text),
+            },
+        },
+    )
+
+
+def _emit_fallthrough(
+    profile: str, text: str, disabled: bool = False
+) -> None:
+    logger.info(
+        "auto-router-fallthrough",
+        extra={
+            "resolved_profile": profile,
+            "signals": {
+                "code_fence_ratio": round(_code_fence_ratio(text), 3),
+                "content_len": len(text),
+                "disabled": disabled,
+            },
+        },
+    )
+
+
+__all__ = [
+    "BUNDLED_DEFAULT_RULE_PROFILE",
+    "BUNDLED_REQUIRED_PROFILES",
+    "BUNDLED_RULES",
+    "RESERVED_PROFILE_NAME",
+    "AutoRouteRule",
+    "AutoRouterConfig",
+    "RuleMatcher",
+    "classify",
+]