dialectical-framework 2.0.5__tar.gz → 2.0.7__tar.gz

{dialectical_framework-2.0.5 → dialectical_framework-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 2.0.5
+Version: 2.0.7
 Summary: A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.).
 License: MIT
 Keywords: dialectics,dialectical-reasoning,synthesis,thesis-antithesis,ai,artificial-intelligence,llm,reasoning-framework,philosophy,logic,argumentation,conflict-resolution,decision-making,critical-thinking,semantic-graph,mirascope,pydantic,perspectives,polarity-reasoning

{dialectical_framework-2.0.5 → dialectical_framework-2.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "2.0.5"
+version = "2.0.7"
 description = "A dialectical framework for augmented intelligence. AI reasoning powered with dialectics supports humans in: system optimization (psychology, engineering, business, politics, etc.); dispute resolution (mediation, conflicts, negotiations, etc.); decision-making (dilemmas, challenging situations, win-win, etc.)."
 authors = ["Evaldas Taroza <evaldas@dialexity.com>"]
 readme = "README.md"

{dialectical_framework-2.0.5 → dialectical_framework-2.0.7}/src/dialectical_framework/agents/advisor/advisor.py

@@ -42,6 +42,7 @@ from dialectical_framework.agents.stream_events import (ResponseComplete,
                                                         StreamEvent, TextDelta,
                                                         ToolResult, ToolStart)
 from dialectical_framework.agents.toolsets import merge_app_tools
+from dialectical_framework.exceptions.provider_errors import ModelRefusal
 from dialectical_framework.agents.turn_timing import (ClosingOutcome,
                                                        DeferralOutcome,
                                                        TurnTiming)
@@ -850,7 +851,13 @@ class Advisor(SettingsAware):
             # Around the provider round ONLY — the closing seam and the
             # off-turn scheduling below run outside it on purpose.
             with speaking(user_message):
-                result = await self._conversation.submit(ChatResponse, user_message)
+                try:
+                    result = await self._conversation.submit(
+                        ChatResponse, user_message
+                    )
+                except ModelRefusal:
+                    await self._settle_refused_turn(user_message)
+                    raise
             reply_path_s = (
                 deferred_wait_s
                 + context_render_s
@@ -966,33 +973,37 @@ class Advisor(SettingsAware):
             # Entered here, before the stream is opened, because the tool runs
             # inside the generator while it is being iterated.
             with speaking(user_message):
-                async with aclosing(
-                    self._conversation.submit_stream(ChatResponse, user_message)
-                ) as rounds:
-                    async for event in rounds:
-                        if isinstance(event, ResponseComplete):
-                            final_event = event
-                            reply = event.message
-                            # `continue`, so `submit_stream` is asked for one more
-                            # event and runs to its own end instead of being closed
-                            # while suspended at its yield. The seconds read below are
-                            # safe either way — it stamps them as this event passes
-                            # through it, not on exit — but running out is still the
-                            # cleaner exit: the provider's connection is let go of by
-                            # exhaustion rather than by a close unwinding a live frame.
-                            continue
-                        if hygiene is not None:
-                            if isinstance(event, TextDelta):
-                                clean = hygiene.feed(event.text)
-                                if clean:
-                                    yield TextDelta(text=clean)
+                try:
+                    async with aclosing(
+                        self._conversation.submit_stream(ChatResponse, user_message)
+                    ) as rounds:
+                        async for event in rounds:
+                            if isinstance(event, ResponseComplete):
+                                final_event = event
+                                reply = event.message
+                                # `continue`, so `submit_stream` is asked for one more
+                                # event and runs to its own end instead of being closed
+                                # while suspended at its yield. The seconds read below are
+                                # safe either way — it stamps them as this event passes
+                                # through it, not on exit — but running out is still the
+                                # cleaner exit: the provider's connection is let go of by
+                                # exhaustion rather than by a close unwinding a live frame.
                                 continue
-                            if isinstance(event, (ToolStart, ToolResult)):
-                                tail = hygiene.flush()
-                                if tail:
-                                    yield TextDelta(text=tail)
-                                hygiene = HashCitationFilter()
-                        yield event
+                            if hygiene is not None:
+                                if isinstance(event, TextDelta):
+                                    clean = hygiene.feed(event.text)
+                                    if clean:
+                                        yield TextDelta(text=clean)
+                                    continue
+                                if isinstance(event, (ToolStart, ToolResult)):
+                                    tail = hygiene.flush()
+                                    if tail:
+                                        yield TextDelta(text=tail)
+                                    hygiene = HashCitationFilter()
+                            yield event
+                except ModelRefusal:
+                    await self._settle_refused_turn(user_message)
+                    raise
             if hygiene is not None:
                 tail = hygiene.flush()
                 if tail:
@@ -2829,6 +2840,27 @@ class Advisor(SettingsAware):
             logger.exception("Accepted-cost ground resolution failed (fail-soft)")
         return None
 
+    async def _settle_refused_turn(self, user_message: str) -> None:
+        """The closing work a refused turn still owes, before the refusal goes on.
+
+        A refusal can arrive AFTER tool rounds: the resume round is the one
+        declined, so `record_decision` may already have written a Decision and
+        `note` may already have kept a Note. The facilitator drops the turn
+        from history, but the graph keeps what the tools wrote — and without
+        this the recorded decision never gets its pathway weave (the seam's
+        MODEL_RECORDED branch is what schedules it) and the noted tensions wait
+        for the next turn to be offered. Only the work the tools already did is
+        followed up: the classifier is not asked about a turn that was refused,
+        so no decision is written here that the model did not write.
+        Fail-soft: the refusal is what the host must see.
+        """
+        try:
+            if self._recorded_decision_this_turn():
+                await self._repair_unrecorded_decision(user_message, "")
+            self._schedule_noted_tensions()
+        except Exception:
+            logger.exception("Closing work after a refused turn failed (fail-soft)")
+
     def _recorded_decision_this_turn(self) -> bool:
         """Did `record_decision` already run, successfully, on this turn?
 

{dialectical_framework-2.0.5 → dialectical_framework-2.0.7}/src/dialectical_framework/agents/conversation_facilitator.py

@@ -29,6 +29,7 @@ from dialectical_framework.agents.stream_events import (
     ToolStart,
 )
 from dialectical_framework.agents.turn_timing import ToolRound
+from dialectical_framework.exceptions.provider_errors import ModelRefusal
 from dialectical_framework.protocols.has_config import SettingsAware
 from dialectical_framework.utils.call_census import record_call
 from dialectical_framework.utils.thinking_compat import conversational_round
@@ -37,7 +38,7 @@ from dialectical_framework.utils.retry_accounting import (RetryAccount,
 from dialectical_framework.utils.use_brain import (prefill_token_kwargs,
                                                   retry_transient, use_brain)
 
-from mirascope.llm import TextChunk, ThoughtChunk, ToolOutput
+from mirascope.llm import FinishReason, TextChunk, ThoughtChunk, ToolOutput
 
 if TYPE_CHECKING:
     from mirascope.llm import UserContent
@@ -513,6 +514,7 @@ class ConversationFacilitator(SettingsAware):
         Returns:
             Structured response matching response_model
         """
+        history_before = len(self._messages)
         self._messages.append(llm.messages.user(user_content))
         self.last_tool_calls = []
         self.last_tool_results = []
@@ -567,6 +569,10 @@ class ConversationFacilitator(SettingsAware):
                     # Mirascope's own request, so nothing in `use_brain` marks it).
                     with conversational_round():
                         response = await response.resume(tool_outputs)
+                    # Mirascope's own request, below `use_brain`: a provider that
+                    # does not raise on a refusal itself only says so here.
+                    if getattr(response, "finish_reason", None) == FinishReason.REFUSAL:
+                        raise ModelRefusal(getattr(response, "model_id", "unknown"))
 
                 # Sync full conversation history from the response chain
                 self._messages = list(response.messages)
@@ -580,6 +586,9 @@ class ConversationFacilitator(SettingsAware):
 
                 # Extract structured response
                 return await self._call_with_response_model(response_model)
+        except ModelRefusal:
+            self._forget_refused_turn(history_before)
+            raise
         finally:
             if epoch == self._turn_epoch:
                 self.last_submit_seconds = time.monotonic() - started
@@ -631,6 +640,7 @@ class ConversationFacilitator(SettingsAware):
         #: with a later reading, or every ordinary turn would silently absorb
         #: however long the consumer took to come back for the last event.
         recorded = False
+        history_before = len(self._messages)
         # Held in a name so it can be closed; see the docstring.
         rounds = self._stream_turn(
             response_model,
@@ -644,6 +654,9 @@ class ConversationFacilitator(SettingsAware):
                     self.last_submit_seconds = time.monotonic() - started
                     recorded = True
                 yield event
+        except ModelRefusal:
+            self._forget_refused_turn(history_before)
+            raise
         finally:
             # Before the close, which can raise: the figure is the point.
             if not recorded and epoch == self._turn_epoch:
@@ -802,6 +815,13 @@ class ConversationFacilitator(SettingsAware):
                 first_chunk_at=first_chunk_at,
                 yielded_s=yielded_s,
             )
+            if getattr(stream, "finish_reason", None) == FinishReason.REFUSAL:
+                # The awaited path raises at the provider; a stream only says so
+                # in its last chunk, after any text has been yielded. The host
+                # has shown a partial reply and should replace it — the
+                # exception is the signal. No `stop_details` on this path.
+                raise ModelRefusal(getattr(stream, "model_id", "unknown"))
+
             if self.last_submit_first_delta_s is None and first_delta_at is not None:
                 # From the TURN's start, not this round's: the person has been
                 # waiting since they hit send, through the context re-render's
@@ -900,6 +920,17 @@ class ConversationFacilitator(SettingsAware):
 
     # --- Internal helpers ---
 
+    def _forget_refused_turn(self, history_before: int) -> None:
+        """Drop the refused turn from history, user message included.
+
+        A refused exchange left in history is the context the next request is
+        refused in again; the provider's guidance on a refusal is to change or
+        drop the turn that triggered it. The turn did not happen, so history
+        returns to where it stood before it — the host still has the person's
+        words and can offer them back for rephrasing.
+        """
+        del self._messages[history_before:]
+
     #: Answer written into the synthetic tool_result when the tool loop is cut
     #: short. Addressed to the model, because the model reads it: it must
     #: understand that the tool did not run and that it should wrap up with

dialectical_framework-2.0.7/src/dialectical_framework/exceptions/provider_errors.py

@@ -0,0 +1,42 @@
+"""
+Provider verdicts that are not transport faults.
+
+`ModelRefusal` is raised when the model stops with ``stop_reason: "refusal"``
+(the provider's policy classifiers intervened). It is deliberately its own
+type: before it existed a refusal reached the framework as an empty or cut-off
+reply, so a structured call re-asked it as a ParseError (ten times) and a
+conversational turn fell through to a second, structured call that was refused
+again. A refusal is the provider's answer to THIS request, so nothing retries
+it; the caller decides — a concern fails soft as on any error, a host shows the
+person something and lets them rephrase.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ModelRefusal(RuntimeError):
+    """The model declined the request (``stop_reason: "refusal"``).
+
+    ``category`` and ``explanation`` are the provider's ``stop_details`` when it
+    sends them (``"cyber"``, ``"bio"``, or None for an unnamed category); a
+    streamed round does not carry them and leaves both None. The explanation
+    text is not guaranteed stable by the provider — show it, never branch on it.
+    """
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        category: Optional[str] = None,
+        explanation: Optional[str] = None,
+    ) -> None:
+        self.model = model
+        self.category = category
+        self.explanation = explanation
+        detail = f" ({category})" if category else ""
+        super().__init__(
+            f"Model {model} refused the request{detail}"
+            + (f": {explanation}" if explanation else "")
+        )

{dialectical_framework-2.0.5 → dialectical_framework-2.0.7}/src/dialectical_framework/utils/bedrock_provider.py

@@ -16,10 +16,16 @@ from mirascope.llm.responses import AsyncResponse, AsyncStreamResponse, Response
 from typing_extensions import Unpack
 
 from dialectical_framework.enums.di import DI
+from dialectical_framework.exceptions.provider_errors import ModelRefusal
 from dialectical_framework.settings import Settings
+from dialectical_framework.utils.format_compat import (
+    learn_format_mode_from_error,
+    with_format_compat,
+)
 from dialectical_framework.utils.thinking_compat import (
     learn_thinking_shape_from_error,
     with_thinking_compat,
+    without_earlier_turn_thinking,
 )
 
 if TYPE_CHECKING:
@@ -288,6 +294,62 @@ def _bedrock_model_name(model_id: str) -> str:
     return model_id.removeprefix("bedrock/").removeprefix("anthropic/")
 
 
+class _LearningStreamManager:
+    """`messages.stream(...)` that learns the thinking shape from a 400, once.
+
+    The request is made when the manager is ENTERED (Mirascope's decoder does
+    `async with` on the first chunk), before anything has been yielded, so a
+    rejected shape can be re-sent without replaying a token — and the streamed
+    conversational round is exactly where an unset level goes out as "off",
+    so without this a wrong name heuristic would fail every streamed turn until
+    some awaited call taught the process. Thinking only: a learned FORMAT mode
+    would change the response's parser, which the caller already holds.
+    """
+
+    def __init__(
+        self, client: Any, kwargs: dict[str, Any], params: Mapping[str, Any]
+    ) -> None:
+        self._client = client
+        self._kwargs = kwargs
+        self._params = params
+        self._manager: Any = None
+
+    def _open(self) -> Any:
+        return self._client.messages.stream(
+            **with_thinking_compat(self._kwargs["model"], self._kwargs, self._params)
+        )
+
+    async def __aenter__(self) -> Any:
+        self._manager = self._open()
+        try:
+            return await self._manager.__aenter__()
+        except Exception as e:
+            if not learn_thinking_shape_from_error(self._kwargs["model"], e):
+                raise
+            self._manager = self._open()
+            return await self._manager.__aenter__()
+
+    async def __aexit__(self, *exc: Any) -> Any:
+        return await self._manager.__aexit__(*exc)
+
+
+def raise_on_refusal(response: Any, model_name: str) -> None:
+    """Raise `ModelRefusal` when the provider stopped on a refusal.
+
+    Raised at the provider, below `use_brain`, so no retry ladder ever re-asks
+    it (an unknown exception re-raises there) and the tool loop's resumes —
+    Mirascope's own requests, which reach this provider too — are covered.
+    """
+    if getattr(response, "stop_reason", None) != "refusal":
+        return
+    details = getattr(response, "stop_details", None)
+    raise ModelRefusal(
+        model_name,
+        category=getattr(details, "category", None),
+        explanation=getattr(details, "explanation", None),
+    )
+
+
 class BedrockAnthropicProvider(AnthropicProvider):
     """Mirascope v2 provider that routes through AnthropicBedrock client (async-native).
 
@@ -305,6 +367,53 @@ class BedrockAnthropicProvider(AnthropicProvider):
         self.async_client = AsyncAnthropicBedrock(timeout=timeout)
         self._beta_provider = None
 
+    @staticmethod
+    def _encode(
+        model_id: str,
+        messages: Sequence[Message],
+        toolkit: AsyncToolkit | Toolkit,
+        format: FormatSpec[FormattableT] | None,
+        params: Mapping[str, Any],
+    ) -> tuple[Any, Any, dict[str, Any]]:
+        """Encode a request in the formatting mode this model can take.
+
+        Forced tool use is re-asked as JSON for a model that refuses it (Claude
+        5.5); see format_compat. Encoding happens here, BEFORE the request is
+        built, because the mode decides the request's shape — tools and
+        tool_choice for one, system instructions for the other — and the
+        decoded response's parser follows the resolved format. Earlier turns'
+        thinking blocks are dropped here too, for a model that binds them to
+        their prefix (see `without_earlier_turn_thinking`).
+
+        A call moved OFF forced tool use is also sent with thinking off unless
+        it asked for thinking: forced tool choice is what kept every structured
+        call from thinking by default (0 thinking tokens with no parameter,
+        2026-09-24), and JSON mode with nothing sent is the provider's default,
+        thinking on. Without this every concern on a 5.5 model would think —
+        a cost, latency and behaviour change no figure was taken under.
+        `with_thinking_compat` turns "disabled" into the model's own off.
+        """
+        model_name = _bedrock_model_name(model_id)
+        compatible = with_format_compat(model_name, format)
+        input_messages, resolved_format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=compatible,
+            params=params,
+        )
+        kwargs["model"] = model_name
+        # A structured call is never a round of the tool loop: no tools, and in
+        # JSON mode extra system text, so even THIS turn's blocks are bound to a
+        # prefix the request no longer has. Drop them all there.
+        kwargs["messages"] = without_earlier_turn_thinking(
+            model_name, kwargs["messages"], every_turn=format is not None
+        )
+        if compatible is not format and "thinking" not in kwargs:
+            kwargs["thinking"] = {"type": "disabled"}
+        _fix_cache_breakpoints(kwargs)
+        return input_messages, resolved_format, kwargs
+
     async def _create_async(
         self, kwargs: dict[str, Any], params: Mapping[str, Any]
     ) -> AnthropicMessage:
@@ -353,18 +462,23 @@ class BedrockAnthropicProvider(AnthropicProvider):
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Always use standard path — bedrock doesn't support beta structured outputs."""
-        input_messages, resolved_format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=toolkit,
-            format=format,
-            params=params,
-        )
-        kwargs["model"] = _bedrock_model_name(model_id)
-        _fix_cache_breakpoints(kwargs)
-        anthropic_response = cast(
-            AnthropicMessage, await self._create_async(kwargs, params)
+        input_messages, resolved_format, kwargs = self._encode(
+            model_id, messages, toolkit, format, params
         )
+        try:
+            anthropic_response = cast(
+                AnthropicMessage, await self._create_async(kwargs, params)
+            )
+        except Exception as e:
+            if not learn_format_mode_from_error(kwargs["model"], format, e):
+                raise
+            input_messages, resolved_format, kwargs = self._encode(
+                model_id, messages, toolkit, format, params
+            )
+            anthropic_response = cast(
+                AnthropicMessage, await self._create_async(kwargs, params)
+            )
+        raise_on_refusal(anthropic_response, kwargs["model"])
         include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id, include_thoughts=include_thoughts
@@ -393,21 +507,10 @@ class BedrockAnthropicProvider(AnthropicProvider):
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream responses from Bedrock Anthropic."""
-        input_messages, resolved_format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=toolkit,
-            format=format,
-            params=params,
+        input_messages, resolved_format, kwargs = self._encode(
+            model_id, messages, toolkit, format, params
         )
-        kwargs["model"] = _bedrock_model_name(model_id)
-        _fix_cache_breakpoints(kwargs)
-        # Streaming cannot learn from a 400: the error surfaces when the caller
-        # consumes the iterator, by which point retrying would replay tokens
-        # already yielded. The name heuristic is applied, and a genuine mismatch
-        # raises to the caller.
-        kwargs = with_thinking_compat(kwargs["model"], kwargs, params)
-        anthropic_stream = self.async_client.messages.stream(**kwargs)
+        anthropic_stream = _LearningStreamManager(self.async_client, kwargs, params)
         include_thoughts = _utils.get_include_thoughts(params)
         chunk_iterator = _utils.decode_async_stream(
             anthropic_stream, include_thoughts=include_thoughts
@@ -433,16 +536,23 @@ class BedrockAnthropicProvider(AnthropicProvider):
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Always use standard path — bedrock doesn't support beta structured outputs."""
-        input_messages, resolved_format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=toolkit,
-            format=format,
-            params=params,
+        input_messages, resolved_format, kwargs = self._encode(
+            model_id, messages, toolkit, format, params
         )
-        kwargs["model"] = _bedrock_model_name(model_id)
-        _fix_cache_breakpoints(kwargs)
-        anthropic_response = cast(AnthropicMessage, self._create_sync(kwargs, params))
+        try:
+            anthropic_response = cast(
+                AnthropicMessage, self._create_sync(kwargs, params)
+            )
+        except Exception as e:
+            if not learn_format_mode_from_error(kwargs["model"], format, e):
+                raise
+            input_messages, resolved_format, kwargs = self._encode(
+                model_id, messages, toolkit, format, params
+            )
+            anthropic_response = cast(
+                AnthropicMessage, self._create_sync(kwargs, params)
+            )
+        raise_on_refusal(anthropic_response, kwargs["model"])
         include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id, include_thoughts=include_thoughts

dialectical_framework-2.0.7/src/dialectical_framework/utils/format_compat.py

@@ -0,0 +1,136 @@
+"""
+Per-model compatibility for how a STRUCTURED call asks for its DTO.
+
+Mirascope's default formatting mode is forced tool use (``tool_choice`` of type
+``tool``, or ``any`` with several tools), and every concern has always used it.
+Claude 5.5 models refuse it on Bedrock — reported 2026-10-08 on Sonnet 5.5 and
+Opus 5.5, and probed the same day on Fable 5.1 (Fable 5 still accepts it): ``tool_choice: type "tool" and "any" are not supported for this
+model`` — so with a 5.5 model configured every structured call 400s: the
+coherence judge, the tetrad writers, every concern. JSON mode works on both
+(it asks for the JSON in the reply instead), and it is the shape the framework
+already uses where a structured call must think (`format_mode="json"`).
+
+The mode is therefore chosen by MODEL at the provider, the way
+`thinking_compat` chooses the thinking shape: a request that asked for forced
+tool use, explicitly or by default, is sent in JSON mode to a model that cannot
+take it. A request that asked for another mode (json, strict, parser) is left
+alone. Selection is by model name with a learned fallback — if the heuristic
+misses a future model, its first 400 teaches the process and the call is
+re-encoded once.
+
+What this does NOT decide: whether JSON mode is the better default for models
+that accept both. It parses as reliably on a DTO-shaped call and costs less
+prefill (`probe_format_mode_thinking.py`), but the framework's measured figures
+were taken on forced tool use, so switching every model is a measurement, not
+a compatibility fix.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Optional, get_origin
+
+from mirascope import llm
+from mirascope.llm.formatting.format import Format
+
+logger = logging.getLogger(__name__)
+
+#: The mode substituted for forced tool use on a model that refuses it.
+JSON = "json"
+
+#: Model name -> True when it was LEARNED (from a 400) to refuse forced tool use.
+_LEARNED: dict[str, bool] = {}
+
+#: ``claude-<family>-<major>[-<minor>]``. The minor is one or two digits NOT
+#: followed by another digit, so a date suffix is never read as a minor:
+#: ``claude-haiku-4-5-20251001`` is 4.5, ``claude-sonnet-5`` is 5.0,
+#: ``claude-sonnet-5-5`` is 5.5, and ``claude-3-5-sonnet`` does not match.
+_FAMILY_VERSION = re.compile(r"claude-([a-z]+)-(\d+)(?:-(\d{1,2})(?!\d))?")
+
+
+def claude_version(model_name: str) -> Optional[tuple[int, int]]:
+    """(major, minor) of a Claude 4+-style model name; None when unreadable."""
+    match = _FAMILY_VERSION.search(model_name)
+    if not match:
+        return None
+    return int(match.group(2)), int(match.group(3) or 0)
+
+
+def claude_family(model_name: str) -> Optional[str]:
+    """``sonnet`` / ``opus`` / ... of a Claude 4+-style model name."""
+    match = _FAMILY_VERSION.search(model_name)
+    return match.group(1) if match else None
+
+
+def refuses_forced_tool_use(model_name: str) -> bool:
+    """True when this model rejects ``tool_choice`` of type ``tool``/``any``."""
+    if model_name in _LEARNED:
+        return _LEARNED[model_name]
+    version = claude_version(model_name)
+    if version is None:
+        return False
+    # Probed 2026-10-08: Sonnet/Opus 5.5 and Fable 5.1 refuse; Fable 5 accepts.
+    if claude_family(model_name) in ("fable", "mythos"):
+        return version >= (5, 1)
+    return version >= (5, 5)
+
+
+def _forced_tool(format: Any) -> Any:
+    """The formattable when `format` asks for forced tool use, else None.
+
+    A bare DTO class resolves to Mirascope's default mode, which is ``tool``; a
+    `Format` says its own mode. An `OutputParser` is never forced tool use.
+    """
+    if isinstance(format, Format):
+        return format.formattable if format.mode == "tool" else None
+    # A class, or a parameterised generic (`list[str]`), which is not a `type`
+    # but resolves to the default mode exactly as one does.
+    if isinstance(format, type) or get_origin(format) is not None:
+        return format
+    return None
+
+
+def with_format_compat(model_name: str, format: Any) -> Any:
+    """`format` as this model can take it. Pure; None passes through."""
+    if format is None or not refuses_forced_tool_use(model_name):
+        return format
+    formattable = _forced_tool(format)
+    if formattable is None:
+        return format
+    return llm.format(formattable, mode=JSON)
+
+
+def learn_format_mode_from_error(
+    model_name: str, format: Any, error: BaseException
+) -> bool:
+    """Record that this model refuses forced tool use. True if worth retrying once.
+
+    Only when the failed request asked for forced tool use and the error says
+    so; every other error returns False and surfaces unchanged.
+    """
+    if format is None or _forced_tool(format) is None:
+        return False
+    message = str(error)
+    # The provider's text: 'tool_choice: type "tool" and "any" are not
+    # supported for this model.' Matched on the forced types, so a 400 about
+    # some other tool_choice field cannot move a capable model to JSON.
+    if "tool_choice" not in message or "not supported" not in message:
+        return False
+    if '"tool"' not in message and '"any"' not in message:
+        return False
+    if refuses_forced_tool_use(model_name):
+        # Already sent as JSON and it still failed — the mode is not the problem.
+        return False
+    _LEARNED[model_name] = True
+    logger.warning(
+        "Model %s rejected forced tool use; structured calls go in JSON mode for "
+        "the rest of this process. Adjust format_compat if this is a naming gap.",
+        model_name,
+    )
+    return True
+
+
+def reset_learned_format_modes() -> None:
+    """Test seam — the learned map is process-global by design."""
+    _LEARNED.clear()