claude-smart 0.2.44 → 0.2.46

package/plugin/vendor/reflexio/reflexio/server/llm/litellm_client.py

@@ -31,6 +31,7 @@ from reflexio.server.llm.image_utils import (
     encode_image_to_base64 as _encode_image_to_base64,
 )
 from reflexio.server.llm.llm_utils import (
+    assert_provider_safe_schema,
     is_pydantic_model,
     strict_response_format_for_model,
 )
@@ -62,13 +63,17 @@ from reflexio.server.llm.providers.nomic_embedding_provider import (
 from reflexio.server.llm.providers.nomic_embedding_provider import (
     register_if_enabled as _register_nomic_embedder,
 )
+from reflexio.server.llm.providers.openclaw_provider import (
+    register_if_enabled as _register_openclaw,
+)
 
 # Suppress LiteLLM's verbose logging
 litellm.suppress_debug_info = True
 
-# Opt-in registration of claude-smart's local providers. All no-ops
-# unless the matching env var is set. Safe to call at import.
+# Opt-in registration of local CLI providers. All no-ops unless the
+# matching env var is set. Safe to call at import.
 _register_claude_code()
+_register_openclaw()
 _register_local_embedder()
 _register_nomic_embedder()
 
@@ -228,14 +233,17 @@ class LiteLLMConfig:
         temperature: Temperature for response generation (0.0 to 2.0).
         max_tokens: Maximum tokens to generate.
         timeout: Request timeout in seconds.
-        max_retries: Maximum retry attempts on the primary model. Passed
-            directly to litellm's num_retries. Default 3.
+        max_retries: Maximum same-model retry attempts. Used by the embedding
+            path (litellm's num_retries) and clamped in _build_completion_params.
+            NOT used on the chat-completion path — that forces num_retries=0 so a
+            hung primary can't be retried before the fallback (PYTHON-FASTAPI-62).
+            Default 3.
         retry_delay: Currently unused — LiteLLM owns retry backoff. Kept for
             backward compatibility; remove in a follow-up sweep.
         top_p: Top-p sampling parameter.
         api_key_config: Optional API key configuration from Config (overrides env vars).
-        fallback_models: Models LiteLLM tries in order after the primary
-            exhausts num_retries. Passed directly to litellm's fallbacks param.
+        fallback_models: Models LiteLLM tries in order after the primary's single
+            attempt. Passed directly to litellm's fallbacks param.
             Default is an empty list (no fallback) so local reflexio and the
             claude-smart integration are never silently routed to an unintended
             provider. Production opts in via the env var
@@ -260,12 +268,18 @@ class LiteLLMConfig:
     )
 
 
-# Reasoning models that routinely exceed the default 120s provider timeout on
-# large extraction contexts. Values are floors, not overrides: the effective
-# timeout is max(configured, floor), and an explicit per-call timeout kwarg
-# always wins.
+# Per-model provider-timeout floors. Values are floors, not overrides: the
+# effective timeout is max(configured, floor), and an explicit per-call timeout
+# kwarg always wins.
+#
+# MiniMax-M3 was pinned to 240s when it was the sole model. That let a *hung*
+# primary block ~240s before falling back, dominating the wasted time behind
+# Sentry PYTHON-FASTAPI-62. It is now floored at the 120s default so a hang is
+# abandoned sooner and the fallback (e.g. gpt-5-mini) is reached faster. This is
+# the key post-deploy tuning knob: raise it if legitimately-slow calls start
+# timing out, lower it to cut more waste.
 _MODEL_TIMEOUT_FLOOR_SECONDS: dict[str, int] = {
-    "minimax/MiniMax-M3": 240,
+    "minimax/MiniMax-M3": 120,
 }
 
 
@@ -285,6 +299,10 @@ class ToolCallingChatResponse:
         usage: Raw usage object from the LLM response (provider-dependent shape), or None.
         cost_usd: Estimated cost in USD for this call via litellm price table, or None when
             the provider is not in the table (local ONNX, claude-code CLI, etc.).
+        parsed_output: When ``response_format`` is passed alongside ``tools`` and the model
+            ends the turn with a plain (non-tool) response, the content parsed into the
+            ``response_format`` schema. None when the turn emitted tool calls, when no
+            ``response_format`` was requested, or when the content was not parseable.
     """
 
     content: str | None
@@ -292,6 +310,7 @@ class ToolCallingChatResponse:
     finish_reason: str | None
     usage: Any | None = None
     cost_usd: float | None = None
+    parsed_output: BaseModel | None = None
 
 
 class LiteLLMClientError(Exception):
@@ -349,6 +368,21 @@ class _CompletionResponseSnapshot:
 class _CompletionErrorSnapshot:
     type_name: str
     message: str
+    model: str | None = None
+    llm_provider: str | None = None
+
+
+def _snapshot_completion_error(
+    exc: BaseException, params: dict[str, Any]
+) -> _CompletionErrorSnapshot:
+    model = getattr(exc, "model", None) or params.get("model")
+    llm_provider = getattr(exc, "llm_provider", None)
+    return _CompletionErrorSnapshot(
+        type_name=type(exc).__name__,
+        message=str(exc),
+        model=str(model) if model else None,
+        llm_provider=str(llm_provider) if llm_provider else None,
+    )
 
 
 def _ensure_picklable(value: Any) -> Any:
@@ -421,14 +455,7 @@ def _litellm_completion_worker(
             ("ok", _picklable_completion_result(litellm.completion(**params)))
         )
     except BaseException as exc:
-        try:
-            pickle.dumps(exc)
-        except Exception:
-            result_queue.put(
-                ("error", _CompletionErrorSnapshot(type(exc).__name__, str(exc)))
-            )
-        else:
-            result_queue.put(("error", exc))
+        result_queue.put(("error", _snapshot_completion_error(exc, params)))
 
 
 class LiteLLMClient:
@@ -452,6 +479,15 @@ class LiteLLMClient:
         "xai/": "xai",
     }
 
+    # OpenAI-compatible providers that accept a ``json_schema`` response_format
+    # but that ``litellm.supports_response_schema`` reports as unsupported. For
+    # these, the gate below would fall back to handing LiteLLM the raw Pydantic
+    # model; LiteLLM then builds the ``json_schema`` itself and emits ``oneOf``
+    # for discriminated unions, which strict structured-output endpoints reject
+    # (Sentry PYTHON-FASTAPI-9J). Listing the provider here forces our own
+    # normalized strict schema (``oneOf`` folded into ``anyOf``) to be sent.
+    _JSON_SCHEMA_PROVIDER_ALLOWLIST: frozenset[str] = frozenset({"minimax"})
+
     # Models that only support temperature=1.0 (custom values cause errors or degraded performance)
     TEMPERATURE_RESTRICTED_MODELS = {
         "gpt-5",
@@ -1063,6 +1099,28 @@ class LiteLLMClient:
         except Exception:
             return False
 
+    @staticmethod
+    @lru_cache(maxsize=256)
+    def _provider_for_model(model: str) -> str | None:
+        try:
+            return litellm.get_llm_provider(model)[1]
+        except Exception:
+            return None
+
+    @classmethod
+    def _accepts_json_schema_response_format(cls, model: str) -> bool:
+        """Whether to send ``model`` an explicit strict ``json_schema`` schema.
+
+        True when LiteLLM reports native response-schema support, or when the
+        provider is a known OpenAI-compatible endpoint that LiteLLM
+        under-reports (see ``_JSON_SCHEMA_PROVIDER_ALLOWLIST``). In the latter
+        case LiteLLM would otherwise forward a ``json_schema`` it built itself,
+        emitting ``oneOf`` for discriminated unions that the endpoint rejects.
+        """
+        if cls._supports_response_schema(model):
+            return True
+        return cls._provider_for_model(model) in cls._JSON_SCHEMA_PROVIDER_ALLOWLIST
+
     def _provider_response_format(
         self,
         *,
@@ -1072,18 +1130,28 @@ class LiteLLMClient:
     ) -> Any:
         """Return the provider-facing response_format while preserving parser schema.
 
-        Callers pass a Pydantic model so local parsing stays type-safe. When
-        LiteLLM says the target model supports JSON Schema response formats, we
-        send an explicit strict schema to constrain generation. Unsupported
-        providers keep the existing Pydantic response_format behavior.
+        Callers pass a Pydantic model so local parsing stays type-safe. When the
+        target model accepts a JSON Schema response format — either LiteLLM
+        reports native support, or the provider is an OpenAI-compatible endpoint
+        LiteLLM under-reports (see ``_accepts_json_schema_response_format``) — we
+        send an explicit strict schema to constrain generation. Truly
+        unsupported providers keep the existing Pydantic response_format
+        behavior.
         """
 
-        if (
-            strict_response_format
-            and is_pydantic_model(response_format)
-            and self._supports_response_schema(model)
-        ):
-            return strict_response_format_for_model(response_format)
+        if not is_pydantic_model(response_format):
+            return response_format
+
+        # Build the native schema once and reuse it for both the boundary guard and
+        # (when applicable) the strict normalizer, avoiding a second schema build.
+        # Boundary guard: models inheriting StrictStructuredOutput are safe by
+        # construction; this catches a model that forgot the base (raises under
+        # tests, warns in prod) regardless of which path is taken below.
+        schema = response_format.model_json_schema()
+        assert_provider_safe_schema(schema, name=response_format.__name__)
+
+        if strict_response_format and self._accepts_json_schema_response_format(model):
+            return strict_response_format_for_model(response_format, schema=schema)
         return response_format
 
     def _compute_cost_usd(self, response: Any, model: str | None) -> float | None:
@@ -1107,20 +1175,38 @@ class LiteLLMClient:
         except Exception:
             return None
 
-    def _completion_with_hard_timeout(self, params: dict[str, Any]) -> Any:
+    def _coerce_timeout_seconds(self, params: dict[str, Any]) -> float:
+        """Coerce ``params['timeout']`` to a float, falling back to the config
+        default when it is missing or non-numeric."""
+        try:
+            return float(params.get("timeout", self.config.timeout))
+        except (TypeError, ValueError):
+            return float(self.config.timeout)
+
+    def _completion_with_hard_timeout(
+        self, params: dict[str, Any], hard_timeout: float
+    ) -> Any:
         """Run ``litellm.completion`` with a client-side wall-clock bound.
 
         Some providers can exceed LiteLLM's ``timeout`` kwarg. Run the blocking
         call in a child process so the caller can fail, release locks, and
         terminate the in-flight provider request instead of waiting indefinitely.
+
+        ``hard_timeout`` is the wall-clock kill bound for the whole subprocess.
+        Because LiteLLM walks ``[primary, *fallbacks]`` inside this one call
+        (copying ``timeout`` unchanged into each rung), the caller sizes
+        ``hard_timeout`` to cover the entire fallback ladder, not a single
+        attempt — otherwise the subprocess would be killed before LiteLLM ever
+        reaches a fallback (the root cause of Sentry PYTHON-FASTAPI-62).
         """
         provider_timeout = params.get("timeout", self.config.timeout)
-        try:
-            timeout_seconds = float(provider_timeout)
-        except (TypeError, ValueError):
-            timeout_seconds = float(self.config.timeout)
+        # timeout_seconds + grace_seconds below only classify test doubles in
+        # _should_process_isolate_completion (real litellm vs a monkeypatched
+        # closure) — they do NOT size the kill bound, which is the caller's
+        # ladder-wide ``hard_timeout``.
+        timeout_seconds = self._coerce_timeout_seconds(params)
         grace_seconds = self._hard_timeout_grace_seconds()
-        hard_timeout = max(0.001, timeout_seconds) + max(0.0, grace_seconds)
+        hard_timeout = max(0.001, hard_timeout)
 
         if not self._should_process_isolate_completion(timeout_seconds, grace_seconds):
             return litellm.completion(**params)
@@ -1156,11 +1242,15 @@ class LiteLLMClient:
 
             if status == "ok":
                 return payload
-            if isinstance(payload, _CompletionErrorSnapshot):
-                raise LiteLLMClientError(
-                    f"litellm.completion raised {payload.type_name}: {payload.message}"
-                )
-            raise payload
+            # The worker always reports errors as a picklable snapshot.
+            context_parts = [f"model={payload.model}"]
+            if payload.llm_provider:
+                context_parts.append(f"provider={payload.llm_provider}")
+            raise LiteLLMClientError(
+                "litellm.completion failed in isolated worker: "
+                f"{payload.type_name}: {payload.message} "
+                f"({', '.join(context_parts)})"
+            )
         finally:
             result_queue.close()
             result_queue.join_thread()
@@ -1289,14 +1379,15 @@ class LiteLLMClient:
         self, messages: list[dict[str, Any]], **kwargs: Any
     ) -> str | BaseModel | ToolCallingChatResponse:
         """
-        Make a request to the LLM, delegating retries and fallback to litellm.
-
-        Retry and fallback semantics are handed to ``litellm.completion`` via
-        the native ``num_retries`` and ``fallbacks`` kwargs. Per the documented
-        flow at https://docs.litellm.ai/docs/router_architecture, the primary
-        model is tried ``num_retries+1`` times, then each fallback gets a single
-        attempt. The one piece we still own at the client level is a single
-        retry for ``StructuredOutputParseError``: LiteLLM cannot detect a
+        Make a request to the LLM, delegating cross-model fallback to litellm.
+
+        Fallback is handed to ``litellm.completion`` via the native ``fallbacks``
+        kwarg, but ``num_retries`` is forced to 0: same-model retry of a *hung*
+        primary is what made the fallback unreachable and produced the 490s in
+        Sentry PYTHON-FASTAPI-62 (see the body comment). So the primary is tried
+        once, then each fallback once. The subprocess hard timeout is sized to
+        cover that whole ladder. The one retry we still own at the client level
+        is a single ``StructuredOutputParseError`` retry: LiteLLM cannot detect a
         post-hoc Pydantic re-validation failure because it sees a successful
         HTTP response.
 
@@ -1313,28 +1404,53 @@ class LiteLLMClient:
             LiteLLMClientError: If the request fails after all retries and
                 fallbacks have been exhausted by litellm.
         """
-        params, response_format, parse_structured_output, max_retries, fallbacks = (
+        params, response_format, parse_structured_output, _max_retries, fallbacks = (
             self._build_completion_params(messages, **kwargs)
         )
 
-        # Hand retries + fallbacks to litellm. ``num_retries`` is the documented
-        # alias for max_retries on litellm.completion.
-        params["num_retries"] = max_retries
+        # Hand the fallback ladder to litellm, but DISABLE same-model retries.
+        # litellm walks [primary, *fallbacks] inside one litellm.completion call,
+        # copying ``timeout`` unchanged into each rung. With num_retries>=1 it
+        # retries a *hung* primary num_retries+1 times (each up to a full
+        # provider timeout) before ever reaching a fallback — making the fallback
+        # unreachable within any sane wall-clock bound (root cause of Sentry
+        # PYTHON-FASTAPI-62). num_retries=0 makes the fallback LIST the resilience
+        # mechanism: each model is tried once, in order.
+        params["num_retries"] = 0
         if fallbacks:
             params["fallbacks"] = fallbacks
 
+        # Size the hard (wall-clock) timeout to cover the WHOLE ladder. litellm
+        # copies this single ``params["timeout"]`` into EVERY rung (primary + each
+        # fallback), so every rung shares the primary's per-attempt budget and the
+        # subprocess must be allowed to run ``(1 + len(fallbacks))`` of them plus
+        # one grace buffer before being killed — otherwise it is killed before
+        # litellm can reach a fallback.
+        #
+        # ASYMMETRIC-FLOOR FOOTGUN: because every rung shares one timeout, a
+        # fallback whose _MODEL_TIMEOUT_FLOOR_SECONDS floor is HIGHER than the
+        # primary's would run — and be killed — at the primary's shorter timeout,
+        # reintroducing the "fallback killed early" failure this fix removes. The
+        # floor table is single-valued today (MiniMax-M3 == the 120 default), so
+        # this is latent; revisit the sizing (e.g. max floor across rungs, passed
+        # as ``params["timeout"]``) before adding an asymmetric floor entry.
+        per_attempt_timeout = self._coerce_timeout_seconds(params)
+        hard_timeout = (
+            1 + len(fallbacks)
+        ) * per_attempt_timeout + self._hard_timeout_grace_seconds()
+
         request_start = time.perf_counter()
         self.logger.info(
-            "event=llm_request_start model=%s timeout=%s has_response_format=%s num_retries=%d fallbacks=%s",
+            "event=llm_request_start model=%s timeout=%s has_response_format=%s num_retries=0 fallbacks=%s hard_timeout=%.3f",
             params.get("model"),
             params.get("timeout"),
             response_format is not None,
-            max_retries,
             fallbacks,
+            hard_timeout,
         )
 
         def _call_and_parse() -> str | BaseModel | ToolCallingChatResponse:
-            response = self._completion_with_hard_timeout(params)
+            response = self._completion_with_hard_timeout(params, hard_timeout)
             self._emit_fallback_observability(response, params)
             message = response.choices[0].message  # type: ignore[reportAttributeAccessIssue]
             content = message.content
@@ -1353,12 +1469,28 @@ class LiteLLMClient:
             if "tools" in params:
                 raw_usage = getattr(response, "usage", None)
                 call_cost = self._compute_cost_usd(response, params.get("model"))
+                tool_calls = getattr(message, "tool_calls", None)
+                # Structured-output + tools: when the model ends the turn with a
+                # plain (non-tool) response and a response_format was requested,
+                # the content IS the final structured answer. Parse it here so a
+                # tool-loop caller can finish on it. A malformed parse raises
+                # StructuredOutputParseError, which the outer wrapper retries once.
+                parsed_output: BaseModel | None = None
+                if response_format is not None and not tool_calls:
+                    parsed = self._maybe_parse_structured_output(
+                        content,  # type: ignore[reportArgumentType]
+                        response_format,
+                        parse_structured_output,
+                    )
+                    if isinstance(parsed, BaseModel):
+                        parsed_output = parsed
                 return ToolCallingChatResponse(
                     content=content,
-                    tool_calls=getattr(message, "tool_calls", None),
+                    tool_calls=tool_calls,
                     finish_reason=response.choices[0].finish_reason,  # type: ignore[reportAttributeAccessIssue]
                     usage=raw_usage,
                     cost_usd=call_cost,
+                    parsed_output=parsed_output,
                 )
 
             return self._maybe_parse_structured_output(
@@ -1371,25 +1503,25 @@ class LiteLLMClient:
             try:
                 return _call_and_parse()
             except StructuredOutputParseError:
-                # LiteLLM's num_retries covers API errors, but a Pydantic
-                # re-validation failure happens AFTER litellm sees a
-                # successful 200 — so we owe one explicit second attempt at
-                # the model. PR #121 documented this as a MiniMax-M3
-                # mitigation.
+                # litellm's fallbacks cover API/timeout errors, but a Pydantic
+                # re-validation failure happens AFTER litellm sees a successful
+                # 200 — litellm can't detect it, so we owe one explicit second
+                # attempt at the model. PR #121 documented this as a MiniMax-M3
+                # mitigation. (A hard timeout is NOT retried here: same-model
+                # retry of a hang is what produced the 490s in PYTHON-FASTAPI-62;
+                # the fallback ladder inside _call_and_parse handles it instead.)
+                #
+                # This second pass re-walks the full ladder, so the worst-case
+                # wall clock is ~2x the ladder bound. That ceiling is only reached
+                # if a model returns a malformed-but-successful 200 AND runs near
+                # the timeout on BOTH passes — a hang (the common case) raises
+                # LLMHardTimeoutError, which is not caught here and exits after a
+                # single ladder.
                 self.logger.warning(
                     "event=llm_parse_retry model=%s — primary returned malformed structured output, retrying once",
                     params.get("model"),
                 )
                 return _call_and_parse()
-            except LLMHardTimeoutError:
-                # The hard timeout kills the litellm subprocess, so litellm's
-                # num_retries never gets a chance — we owe one explicit retry
-                # at this level to cover transient provider hangs.
-                self.logger.warning(
-                    "event=llm_hard_timeout_retry model=%s — request hit hard timeout, retrying once",
-                    params.get("model"),
-                )
-                return _call_and_parse()
         except Exception as e:
             self.logger.error(
                 "event=llm_request_end model=%s elapsed_seconds=%.3f success=False error_type=%s error=%s",
@@ -1636,21 +1768,76 @@ class LiteLLMClient:
         """
         content = content.strip()
 
+        # Prefer a balanced JSON container first. Structured JSON may contain
+        # markdown fences inside string values; grabbing the first code block
+        # would extract the inner snippet instead of the response object.
+        json_container = self._extract_first_json_container(content)
+        if json_container is not None:
+            return json_container
+
         # Try to extract from markdown code blocks
         json_block_pattern = r"```(?:json)?\s*([\s\S]*?)```"
         matches = re.findall(json_block_pattern, content)
         if matches:
             return matches[0].strip()
 
-        # Try to find JSON object or array
-        for start_char, end_char in [("{", "}"), ("[", "]")]:
-            start_idx = content.find(start_char)
-            end_idx = content.rfind(end_char)
-            if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
-                return content[start_idx : end_idx + 1]
-
         return content
 
+    def _extract_first_json_container(self, content: str) -> str | None:
+        """Return the first balanced JSON-like object/array in ``content``."""
+        for start_idx, ch in enumerate(content):
+            if ch not in "{[":
+                continue
+            end_idx = self._find_json_container_end(content, start_idx)
+            if end_idx is None:
+                continue
+            candidate = content[start_idx : end_idx + 1]
+            if self._is_parseable_json_candidate(candidate):
+                return candidate
+        return None
+
+    @staticmethod
+    def _find_json_container_end(content: str, start_idx: int) -> int | None:
+        """Find the matching end of a JSON container, respecting strings."""
+        pairs = {"{": "}", "[": "]"}
+        stack = [pairs[content[start_idx]]]
+        in_str = False
+        escape = False
+
+        for idx in range(start_idx + 1, len(content)):
+            ch = content[idx]
+            if escape:
+                escape = False
+                continue
+            if ch == "\\" and in_str:
+                escape = True
+                continue
+            if ch == '"':
+                in_str = not in_str
+                continue
+            if in_str:
+                continue
+            if ch in pairs:
+                stack.append(pairs[ch])
+            elif ch in ("}", "]"):
+                if not stack or stack.pop() != ch:
+                    return None
+                if not stack:
+                    return idx
+        return None
+
+    def _is_parseable_json_candidate(self, candidate: str) -> bool:
+        """Return True if a balanced candidate can parse after normal sanitizing."""
+        try:
+            json.loads(candidate)
+            return True
+        except Exception:
+            try:
+                json.loads(self._sanitize_json_string(candidate))
+                return True
+            except Exception:
+                return False
+
     def _looks_truncated_json(self, json_str: str) -> bool:
         """
         Return True when a JSON-like string appears to end before it is complete.

package/plugin/vendor/reflexio/reflexio/server/llm/llm_utils.py

@@ -1,11 +1,20 @@
 import inspect
 import logging
 import os
+import sys
 from copy import deepcopy
 from typing import Any
 
 from pydantic import BaseModel
 
+from reflexio.models.structured_output import find_schema_keyword
+
+logger = logging.getLogger(__name__)
+
+# JSON-Schema keywords that strict structured-output endpoints (OpenAI, minimax)
+# reject; see PYTHON-FASTAPI-9J.
+PROVIDER_UNSAFE_KEYWORDS = ("oneOf", "discriminator")
+
 
 def positive_int_env(name: str, default: int, logger: logging.Logger) -> int:
     """Resolve a strictly-positive int from environment variable ``name``.
@@ -89,10 +98,12 @@ def make_strict_json_schema(schema: dict[str, Any]) -> dict[str, Any]:
             node.pop(keyword, None)
 
         # Strict structured output (OpenAI) permits ``anyOf`` but rejects
-        # ``oneOf`` and ``discriminator``. Pydantic emits ``oneOf`` for
-        # discriminated unions; fold it into ``anyOf`` so generation is
-        # constrained to the same variants. Pydantic still enforces the
-        # discriminator after parse, so semantics are preserved.
+        # ``oneOf`` and ``discriminator``. Folded inline here, fused into this
+        # single structure-aware pass (the shared ``_fold_oneof_to_anyof`` helper
+        # does the same fold for the model-boundary hook; kept inline here to
+        # avoid a second full-tree walk). ``visit`` only ever recurses into
+        # property/$def *values*, never the name maps, so a field literally named
+        # ``oneOf`` is preserved — same contract as the helper.
         one_of = node.pop("oneOf", None)
         node.pop("discriminator", None)
         if isinstance(one_of, list):
@@ -127,14 +138,65 @@ def make_strict_json_schema(schema: dict[str, Any]) -> dict[str, Any]:
     return strict_schema
 
 
-def strict_response_format_for_model(model: type[BaseModel]) -> dict[str, Any]:
-    """Build a LiteLLM/OpenAI-compatible strict ``json_schema`` response format."""
+def assert_provider_safe_schema(schema: dict[str, Any], *, name: str = "") -> None:
+    """Enforce that an emitted structured-output schema is provider-safe.
+
+    Strict structured-output endpoints (OpenAI, minimax) reject ``oneOf`` /
+    ``discriminator`` (Sentry PYTHON-FASTAPI-9J). Models that inherit
+    ``StrictStructuredOutput`` are safe by construction; this is the runtime net
+    at the call boundary for anything that bypasses that guarantee — a model that
+    forgot the base, or a tool-argument / dynamically-built schema not covered by
+    the registry contract test.
+
+    Enforcement: under pytest (``"pytest" in sys.modules``) it RAISES so a
+    regression fails CI loudly — including at import/collection time, which a
+    per-test signal like ``PYTEST_CURRENT_TEST`` would miss. In prod it logs a
+    warning (observability) and returns; it does NOT mutate what is sent. So a
+    forgot-the-base model is meant to be caught **pre-merge** (by this raise plus
+    the registry contract test), not auto-repaired at runtime: on the strict /
+    allowlisted path ``make_strict_json_schema`` independently folds the schema,
+    but on the raw passthrough path the warning is the only signal and an unfolded
+    ``oneOf`` would still reach the provider. Keep every output model on
+    ``StrictStructuredOutput``.
+
+    Args:
+        schema (dict[str, Any]): The emitted JSON schema to check.
+        name (str): Identifier for the schema's source, used in the message.
+    """
+    offenders = [
+        kw for kw in PROVIDER_UNSAFE_KEYWORDS if find_schema_keyword(schema, kw)
+    ]
+    if not offenders:
+        return
+    msg = (
+        f"Structured-output schema {name or '<unnamed>'!r} contains provider-unsafe "
+        f"keyword(s) {offenders}; strict providers reject these. Inherit "
+        "StrictStructuredOutput so the schema folds oneOf->anyOf by construction "
+        "(Sentry PYTHON-FASTAPI-9J)."
+    )
+    if "pytest" in sys.modules:
+        raise ValueError(msg)
+    logger.warning(msg)
+
+
+def strict_response_format_for_model(
+    model: type[BaseModel], schema: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Build a LiteLLM/OpenAI-compatible strict ``json_schema`` response format.
+
+    Args:
+        model: The Pydantic model (supplies the schema ``name``).
+        schema: Optional pre-built ``model.model_json_schema()`` to reuse, avoiding
+            a second schema build when the caller already has one.
+    """
 
     return {
         "type": "json_schema",
         "json_schema": {
             "name": model.__name__,
-            "schema": make_strict_json_schema(model.model_json_schema()),
+            "schema": make_strict_json_schema(
+                schema if schema is not None else model.model_json_schema()
+            ),
             "strict": True,
         },
     }