@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.0

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/llm/compat.py

@@ -0,0 +1,316 @@
+"""OpenAI-compatible vendor compatibility matrix.
+
+Every place a vendor's "OpenAI-compatible" endpoint diverges from the
+reference OpenAI v1 schema is data here, not a branch inside the provider:
+
+* **Request-shape flags** gate what the provider sends. A wrong value is a
+  vendor-side HTTP 400, so these are strict booleans/enums.
+* **Response-shape fields** name where a value is read from. Defaults are
+  tolerant (every known location is tried in order); a vendor entry may
+  narrow the tuple to pin documented behavior or extend it for a new shape.
+
+Adding a vendor means adding one entry to ``PROVIDER_COMPAT`` — request
+building and stream parsing do not change (that is the acceptance bar).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+_MAX_TOKENS_FIELDS = ("max_tokens", "max_completion_tokens")
+
+#: Single source of truth for the wire surface: ``(wire_key, field_name,
+#: kind, description)`` per flag. ``from_dict`` derives its key map from
+#: this table and `describe_compat_flags` serves it to hosts, so a new
+#: flag appears on the wire and in host settings UIs by adding one row.
+#: ``kind`` is ``"bool"``, ``"enum:max_tokens,max_completion_tokens"``-style,
+#: or ``"string-list"`` (comma-separated in host UIs).
+_FLAG_WIRE_SPEC: tuple[tuple[str, str, str, str], ...] = (
+    (
+        "supportsUsageInStreaming",
+        "supports_usage_in_streaming",
+        "bool",
+        "Send stream_options.include_usage; disable for vendors that reject it",
+    ),
+    (
+        "maxTokensField",
+        "max_tokens_field",
+        "enum:max_tokens,max_completion_tokens",
+        "Request field that caps the response length",
+    ),
+    (
+        "supportsReasoningEffort",
+        "supports_reasoning_effort",
+        "bool",
+        "Send reasoning_effort when the env clamp yields a level",
+    ),
+    (
+        "supportsTemperature",
+        "supports_temperature",
+        "bool",
+        "Send temperature; disable for fixed-temperature reasoning models",
+    ),
+    (
+        "reasoningDeltaFields",
+        "reasoning_delta_fields",
+        "string-list",
+        "Delta keys read as reasoning text, in preference order",
+    ),
+    (
+        "reasoningEchoField",
+        "reasoning_echo_field",
+        "string",
+        "Message key for echoing plaintext reasoning back to the vendor",
+    ),
+    (
+        "supportsForcedToolChoice",
+        "supports_forced_tool_choice",
+        "bool",
+        "Accept tool_choice=required; disable to downgrade it to auto",
+    ),
+    (
+        "echoEmptyReasoningForToolCalls",
+        "echo_empty_reasoning_for_tool_calls",
+        "bool",
+        'Echo the reasoning field as "" on every assistant turn that produced no reasoning',
+    ),
+    (
+        "cachedTokensFields",
+        "cached_tokens_fields",
+        "string-list",
+        "Usage locations read for cached prompt tokens (dotted paths ok)",
+    ),
+)
+
+
+def describe_compat_flags() -> list[dict[str, Any]]:
+    """Wire-level descriptor of every compat flag for host settings UIs.
+
+    Hosts (desktop settings page) render their compat section from this
+    list instead of hardcoding flag names, so the framework stays the
+    single source of truth for the flag vocabulary (ALIGN 2.3.3).
+    """
+    defaults = OpenAICompatFlags()
+    return [
+        {
+            "key": wire,
+            "field": field_name,
+            "kind": kind,
+            "default": getattr(defaults, field_name),
+            "description": description,
+        }
+        for wire, field_name, kind, description in _FLAG_WIRE_SPEC
+    ]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAICompatFlags:
+    """Per-vendor compatibility overrides for the OpenAI-compatible path.
+
+    Defaults match the reference OpenAI API; a vendor entry overrides only
+    what diverges. Explicit host-passed request fields (extra kwargs) always
+    win — flags only gate what the provider itself adds.
+    """
+
+    # ── request shape ────────────────────────────────────────────────
+    #: Whether ``stream_options: {"include_usage": True}` is accepted.
+    #: Without the final usage chunk, budget accounting and calibration are
+    #: blind — but strict vendors reject the unknown field outright.
+    supports_usage_in_streaming: bool = True
+    #: Which request field caps the response. Newer OpenAI models reject
+    #: ``max_tokens`` in favor of ``max_completion_tokens``.
+    max_tokens_field: Literal["max_tokens", "max_completion_tokens"] = "max_tokens"
+    #: Whether ``reasoning_effort`` may be sent when the env clamp yields a
+    #: level. Vendors without a reasoning knob reject the field.
+    supports_reasoning_effort: bool = True
+    #: Whether ``temperature`` may be sent. Reasoning-only model families
+    #: (o-series class) reject it.
+    supports_temperature: bool = True
+    #: Whether ``tool_choice: "required"`` is accepted. Thinking-mode
+    #: gateways (DeepSeek live-verified 2026-09-08: "Thinking mode does not
+    #: support this tool_choice") 400 the forced value while plain ``auto``
+    #: works — flagging off downgrades ``required`` → ``auto`` on the wire.
+    supports_forced_tool_choice: bool = True
+
+    # ── response shape ───────────────────────────────────────────────
+    #: Delta keys read as reasoning text, in preference order. DeepSeek uses
+    #: ``reasoning_content``; OpenRouter's GLM path uses ``reasoning``.
+    reasoning_delta_fields: tuple[str, ...] = ("reasoning_content", "reasoning")
+    #: Message key for echoing plaintext reasoning back on the next request.
+    #: OpenRouter normalizes to ``reasoning`` (the reference default);
+    #: DeepSeek thinking mode *requires* the round-trip under its own
+    #: ``reasoning_content`` key — echoing as ``reasoning`` is an HTTP 400
+    #: ("The `reasoning_content` in the thinking mode must be passed back to
+    #: the API.", live-verified 2026-09-08 with deepseek-v4-flash).
+    reasoning_echo_field: str = "reasoning"
+    #: Whether an assistant message with *no* reasoning must still echo the
+    #: field (as ``""``). DeepSeek thinking mode 400s the follow-up when
+    #: ``reasoning_content`` is absent from **any** replayed assistant
+    #: message, not only tool-call rounds: a narration-requested final
+    #: summary, a cut draft, or a resumed record can all legitimately have
+    #: no reasoning and still poison the next request. Reference vendors omit
+    #: the field instead.
+    echo_empty_reasoning_for_tool_calls: bool = False
+    #: Usage locations read for cached prompt tokens, in preference order.
+    #: Dotted paths resolve nested objects. OpenAI nests under
+    #: ``prompt_tokens_details.cached_tokens``; DeepSeek reports top-level
+    #: ``prompt_cache_hit_tokens``.
+    cached_tokens_fields: tuple[str, ...] = (
+        "prompt_tokens_details.cached_tokens",
+        "prompt_cache_hit_tokens",
+    )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OpenAICompatFlags:
+        """Build flags from a camelCase host payload (sidecar ``compat``
+        param). Unknown keys fail loud — a typo'd flag must not silently
+        degrade to reference behavior."""
+        key_map = {wire: field for wire, field, *_ in _FLAG_WIRE_SPEC}
+        unknown = set(data) - set(key_map)
+        if unknown:
+            raise ValueError(
+                f"unknown OpenAICompatFlags keys: {sorted(unknown)} "
+                f"(known: {sorted(key_map)})"
+            )
+        kwargs: dict[str, Any] = {}
+        for wire, field in key_map.items():
+            if wire not in data:
+                continue
+            value = data[wire]
+            if field in ("reasoning_delta_fields", "cached_tokens_fields"):
+                kwargs[field] = tuple(str(v) for v in value)
+            elif field == "reasoning_echo_field":
+                kwargs[field] = str(value)
+            elif field == "max_tokens_field":
+                if value not in _MAX_TOKENS_FIELDS:
+                    raise ValueError(
+                        f"maxTokensField must be one of {_MAX_TOKENS_FIELDS}, "
+                        f"got {value!r}"
+                    )
+                kwargs[field] = value
+            else:
+                kwargs[field] = bool(value)
+        return cls(**kwargs)
+
+
+#: Known-vendor overrides as ``(host substring, flags)`` pairs, matched
+#: against the request base URL in order. The sidecar's provider *kinds* are
+#: generic ("openai_compat"), so the host is the only reliable vendor
+#: signal. Entries pin divergences observed against the live vendor;
+#: anything not listed runs on reference defaults. New divergences land here
+#: as data — adding a vendor must not touch request-building or parsing.
+PROVIDER_COMPAT_HOSTS: list[tuple[str, OpenAICompatFlags]] = [
+    # DeepSeek: reasoning arrives as ``reasoning_content`` and cache hits as
+    # top-level ``prompt_cache_hit_tokens``. Thinking mode additionally
+    # REQUIRES the reasoning round-trip under ``reasoning_content`` — the
+    # reference echo key ``reasoning`` is ignored and the follow-up request
+    # 400s (live-verified 2026-09-08, deepseek-v4-flash tool-turn: "The
+    # `reasoning_content` in the thinking mode must be passed back to the
+    # API."). The tolerant delta-field defaults already cover parsing; the
+    # echo key is the divergence pinned here.
+    (
+        "api.deepseek.com",
+        OpenAICompatFlags(
+            reasoning_delta_fields=("reasoning_content", "reasoning"),
+            reasoning_echo_field="reasoning_content",
+            # Thinking mode 400s ``tool_choice="required"`` ("Thinking mode
+            # does not support this tool_choice", live-verified 2026-09-08
+            # with deepseek-v4-flash); ``auto`` and omission both work.
+            supports_forced_tool_choice=False,
+            # Thinking mode also 400s when the ``reasoning_content`` key is
+            # missing from *any* replayed assistant message, even when that
+            # round produced no reasoning at all (live-verified 2026-09-13
+            # on a resumed record; reproduced 2026-09-16 on a
+            # narration-requested final summary: "The `reasoning_content` in
+            # the thinking mode must be passed back to the API."). Echo an
+            # empty string on every assistant message without reasoning.
+            echo_empty_reasoning_for_tool_calls=True,
+            cached_tokens_fields=(
+                "prompt_cache_hit_tokens",
+                "prompt_tokens_details.cached_tokens",
+            ),
+        ),
+    ),
+    # Moonshot (kimi-k2.5/k2.6/k2.7-code/k3): thinking models REJECT an
+    # explicit ``temperature`` (fixed 1.0 thinking / 0.6 non-thinking, any
+    # other value → HTTP 400 ``invalid temperature`` — platform.kimi.ai
+    # model-parameter reference, reproduced live by vercel/ai#19543) and
+    # reject ``reasoning_effort`` on every k2.x model (only k3 accepts
+    # low/high/max). Both flags flip off for the host; a host that knows it
+    # drives k3 can still pass either field explicitly — host extra kwargs
+    # always win over flags. Reasoning arrives as ``reasoning_content``
+    # (default covers it; pinned as data). Doc-verified 2026-08-30 against
+    # platform.kimi.ai/docs/api/models-overview; flags stay doc-sourced,
+    # not live-verified (no Moonshot key available for a run).
+    (
+        "api.moonshot.cn",
+        OpenAICompatFlags(
+            supports_temperature=False,
+            supports_reasoning_effort=False,
+            reasoning_delta_fields=("reasoning_content", "reasoning"),
+        ),
+    ),
+    (
+        "api.moonshot.ai",
+        OpenAICompatFlags(
+            supports_temperature=False,
+            supports_reasoning_effort=False,
+            reasoning_delta_fields=("reasoning_content", "reasoning"),
+        ),
+    ),
+    # OpenRouter normalizes every upstream reasoning shape into the
+    # ``reasoning`` delta field (docs: "reasoning tokens will appear in the
+    # ``reasoning`` field"; SDK ChatStreamDelta.reasoning), with
+    # ``reasoning_details`` as the structured companion. Pin ``reasoning``
+    # first so the normalized path wins; ``reasoning_content`` stays as the
+    # pass-through fallback for upstreams OpenRouter does not rewrite.
+    # Doc-verified 2026-08-30 against openrouter.ai/docs reasoning-tokens
+    # guide; live-verified 2026-08-31 (W5.4.3): deepseek/deepseek-r1 over the
+    # gateway delivered thinking in `reasoning` + `reasoning_details` on the
+    # raw wire, and the pinned order surfaced 965 reasoning chars plus the
+    # answer text through the framework's normalized chunk stream.
+    #
+    # ``stream_options.include_usage`` stays ON: the 404 ("No endpoints
+    # found") came from pairing it with ``require_parameters`` on the Z.ai
+    # pin, not from include_usage itself — without require_parameters the
+    # pinned endpoint returns usage (on a final choices-bearing chunk, which
+    # the stream parser handles). Token accounting depends on it.
+    (
+        "openrouter.ai",
+        OpenAICompatFlags(
+            reasoning_delta_fields=("reasoning", "reasoning_content"),
+        ),
+    ),
+    # DashScope / Alibaba Model Studio compatible mode (Qwen3 thinking,
+    # DeepSeek hosted): reasoning arrives as ``reasoning_content`` and
+    # ``stream_options.include_usage`` is documented-supported, so the
+    # reference defaults already fit — this entry pins that coverage as
+    # data. Thinking is toggled by the nonstandard ``enable_thinking``
+    # extra-body field; hosts opt in via explicit extra kwargs, which
+    # always win over flags. Doc-verified 2026-08-30 against
+    # help.aliyun.com/en/model-studio deep-thinking guide; live-key run
+    # pending.
+    (
+        "dashscope.aliyuncs.com",
+        OpenAICompatFlags(
+            reasoning_delta_fields=("reasoning_content", "reasoning"),
+        ),
+    ),
+    (
+        "dashscope-intl.aliyuncs.com",
+        OpenAICompatFlags(
+            reasoning_delta_fields=("reasoning_content", "reasoning"),
+        ),
+    ),
+]
+
+
+def compat_for_base_url(base_url: str | None) -> OpenAICompatFlags | None:
+    """First registry entry whose host substring appears in ``base_url``."""
+    if not base_url:
+        return None
+    for host, flags in PROVIDER_COMPAT_HOSTS:
+        if host in base_url:
+            return flags
+    return None

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/llm/errors.py

@@ -0,0 +1,207 @@
+"""Provider error taxonomy — structured classification for retry policy.
+
+Codex grades failures with ``is_retryable``; dsh carries structured error
+codes with a retryPolicy. The runtime's equivalent: every provider adapter
+raises ``LLMError`` with a ``kind``, and ``RetryHooks`` routes on it instead
+of treating every failure as "transient".
+
+Kinds and their default retry routing:
+
+- ``transport`` — connection reset / timeout / DNS. Retryable (backoff).
+- ``rate_limit`` — HTTP 429. Retryable (backoff; honor ``Retry-After`` when
+  the provider sends one).
+- ``server`` — HTTP 5xx. Retryable (backoff).
+- ``context_overflow`` — prompt exceeds the model's window. NOT retryable
+  as-is: the same request must fail again. ``CompactionHooks`` intercepts
+  this kind and retries with a compacted transcript.
+- ``auth`` — HTTP 401/403. Not retryable; surfaces immediately.
+- ``invalid_request`` — other 4xx. Not retryable.
+- ``unknown`` — unclassified. Retryable, preserving the pre-taxonomy
+  "retry everything" default for adapters that don't classify yet.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+LLMErrorKind = Literal[
+    "transport",
+    "rate_limit",
+    "context_overflow",
+    "auth",
+    "invalid_request",
+    "server",
+    "unknown",
+]
+
+#: Kinds RetryHooks will retry with backoff. context_overflow is deliberately
+#: absent — retrying the identical over-long request is a guaranteed re-fail;
+#: it needs a transcript rewrite (see CompactionHooks.on_request_error).
+RETRYABLE_KINDS: frozenset[LLMErrorKind] = frozenset(
+    {"transport", "rate_limit", "server", "unknown"}
+)
+
+
+class LLMError(Exception):
+    """Provider failure carrying a classified ``kind``."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        kind: LLMErrorKind,
+        status_code: int | None = None,
+        provider: str | None = None,
+        raw: Any | None = None,
+        retry_after_ms: int | None = None,
+        proxy: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.status_code = status_code
+        self.provider = provider
+        self.raw = raw
+        self.retry_after_ms = retry_after_ms
+        #: Proxy the request went through, credentials stripped; None means
+        #: the request went direct. A failure report shows this so the reader
+        #: knows which hop failed without having to reproduce the settings.
+        self.proxy = proxy
+
+    @property
+    def retryable(self) -> bool:
+        return self.kind in RETRYABLE_KINDS
+
+
+#: Cause-chain walk depth for :func:`describe_transport_error`. httpx →
+#: httpcore → anyio → ssl/socket is four; a little headroom costs nothing.
+_MAX_CAUSE_DEPTH = 6
+
+
+def describe_transport_error(exc: BaseException) -> str:
+    """Flatten a transport exception into one diagnosable string.
+
+    httpx reports a proxy that accepted ``CONNECT`` and then dropped the
+    tunnel as ``ConnectError('')`` — the empty message is httpcore's, and the
+    ``ssl.SSLEOFError`` or ``socket.gaierror`` that explains it is three
+    ``__cause__`` hops down. Logging ``str(exc)`` alone therefore produced
+    ``transport error: `` with nothing after it. This walks the chain and
+    keeps every hop that names something, outermost first.
+
+    The walk follows ``__cause__``; it falls back to ``__context__`` only
+    when the raiser did not set ``__cause__`` and did not ask for the
+    context to be suppressed (``raise ... from None``), so an explicit
+    suppression does not leak the exception it hid.
+
+    Consecutive hops of the same class with no message each collapse into
+    one: httpcore re-wraps its own ``ConnectError`` on the proxy path, and
+    ``ConnectError <- ConnectError`` names nothing the first hop did not.
+
+    A chain with no message at all still returns the class names, so the
+    line never ends in silence.
+    """
+    parts: list[tuple[str, str]] = []
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and len(seen) < _MAX_CAUSE_DEPTH:
+        if id(current) in seen:
+            break
+        seen.add(id(current))
+        name = type(current).__name__
+        text = str(current).strip()
+        if text or not parts or parts[-1] != (name, ""):
+            parts.append((name, text))
+        cause = current.__cause__
+        if cause is None and not current.__suppress_context__:
+            cause = current.__context__
+        current = cause if cause is not None and cause is not current else None
+    return " <- ".join(f"{name}: {text}" if text else name for name, text in parts)
+
+
+#: Body substrings that mark a 400/413 as a context-window overflow rather
+#: than a generic invalid request. Covers OpenAI, Ollama, vLLM, DeepSeek,
+#: and Anthropic phrasings (matched case-insensitively).
+_OVERFLOW_MARKERS = (
+    "context length",
+    "context window",
+    "context_length",
+    "context window",
+    "maximum context",
+    "too many tokens",
+    "prompt is too long",
+    "reduce the length",
+    "exceeds the context",
+    "context size",
+    "token limit",
+)
+
+
+def parse_retry_after_ms(value: object, *, cap_ms: int = 180_000) -> int | None:
+    """Parse HTTP ``Retry-After`` delta-seconds into a bounded wait.
+
+    HTTP-date values are ignored. Cap so a day-long header cannot stall wrap.
+    """
+    if value is None:
+        return None
+    raw = str(value).strip()
+    if not raw:
+        return None
+    try:
+        seconds = float(raw)
+    except ValueError:
+        return None
+    if seconds <= 0:
+        return None
+    return min(int(seconds * 1000), cap_ms)
+
+
+def classify_http_status(status_code: int, body: str = "") -> LLMErrorKind:
+    """Map an HTTP failure status (+ optional response body) to a kind."""
+    lowered = body.lower()
+    looks_overflow = any(marker in lowered for marker in _OVERFLOW_MARKERS)
+    if status_code in (400, 413) and looks_overflow:
+        return "context_overflow"
+    if status_code in (401, 403):
+        return "auth"
+    if status_code == 429:
+        return "rate_limit"
+    if status_code == 408:
+        return "transport"
+    if 500 <= status_code < 600:
+        return "server"
+    if 400 <= status_code < 500:
+        return "invalid_request"
+    return "unknown"
+
+
+def classify_error(error: BaseException) -> LLMErrorKind:
+    """Best-effort classification of an arbitrary provider exception.
+
+    Adapters raise ``LLMError`` directly; this helper keeps hooks working
+    when a raw httpx/asyncio exception slips through.
+    """
+    if isinstance(error, LLMError):
+        return error.kind
+    # httpx without importing it unconditionally (adapters import lazily).
+    try:
+        import httpx
+    except ImportError:  # pragma: no cover - httpx is a runtime dep in practice
+        httpx = None  # type: ignore[assignment]
+    if httpx is not None:
+        if isinstance(error, httpx.HTTPStatusError):
+            body = ""
+            try:
+                body = error.response.text or ""
+            except Exception:  # noqa: BLE001 - unreadable body
+                body = ""
+            return classify_http_status(error.response.status_code, body)
+        if isinstance(error, httpx.TransportError):
+            return "transport"
+    # asyncio.TimeoutError / ConnectionError and friends are transport-level.
+    if isinstance(error, (TimeoutError, ConnectionError)):
+        return "transport"
+    return "unknown"
+
+
+def is_retryable(error: BaseException) -> bool:
+    """Default retry predicate: route on the classified kind."""
+    return classify_error(error) in RETRYABLE_KINDS