dialectical-framework 2.0.8__tar.gz → 2.0.11__tar.gz

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dialectical-framework
-Version: 2.0.8
+Version: 2.0.11
 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.8 → dialectical_framework-2.0.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "2.0.8"
+version = "2.0.11"
 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.8 → dialectical_framework-2.0.11}/src/dialectical_framework/agents/consultant/consultant.py

@@ -42,6 +42,7 @@ from contextlib import aclosing
 from typing import Any, AsyncGenerator, Optional
 
 from mirascope import llm
+from mirascope.llm.exceptions import ProviderError
 
 from dialectical_framework.agents.advisor.advisor import ChatResponse
 from dialectical_framework.agents.advisor.system_prompts import (
@@ -145,9 +146,21 @@ _TOOL_TOKENS = (
 
 def _failed_draw(error: BaseException) -> FailedDrawView:
     """A failed draw's record: the exception's type, the provider's refusal
-    category when it is a `ModelRefusal` that carries one, and its text."""
+    category when it is a `ModelRefusal` that carries one, and its text.
+
+    The type is the PROVIDER's where Mirascope wrapped one: its `ProviderError`
+    subclasses carry the SDK exception as `original_exception`, and that is
+    the name a host counts by (`APITimeoutError` for a stalled draw, where the
+    wrapper says only `TimeoutError` — the builtin's name too). `ParseError`
+    is not a `ProviderError` and keeps its own name.
+    """
+    original = (
+        getattr(error, "original_exception", None)
+        if isinstance(error, ProviderError)
+        else None
+    )
     return FailedDrawView(
-        kind=type(error).__name__,
+        kind=type(original if isinstance(original, BaseException) else error).__name__,
         category=getattr(error, "category", None) if isinstance(error, ModelRefusal) else None,
         message=str(error) or None,
     )

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/agents/conversation_facilitator.py

@@ -567,8 +567,19 @@ class ConversationFacilitator(SettingsAware):
                     self._strip_caller_from_messages(response.messages)
                     # The continuation is a conversational round too (and it is
                     # Mirascope's own request, so nothing in `use_brain` marks it).
+                    # Retried like the streamed resume (`_start_stream_round`):
+                    # since the Bedrock client's own retry went to 0
+                    # (`bedrock_provider._SDK_MAX_RETRIES`) this is the one
+                    # provider request with no other retry layer. Safe to re-ask
+                    # — `resume_async` is `response.messages + [user(outputs)]`
+                    # with no mutation of the response — and the tools have
+                    # already run, so a retry re-sends their outputs, never
+                    # re-executes them.
                     with conversational_round():
-                        response = await response.resume(tool_outputs)
+                        resuming = response
+                        response = await retry_transient(
+                            lambda: resuming.resume(tool_outputs), what="Resume"
+                        )
                     # 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:

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/concerns/transformation_sketch.py

@@ -53,8 +53,30 @@ one-shot can replace it there is a separate, gated measurement
 (`one-shot-transformation.md`, "Open"). Texts only, nothing persisted, no
 scores — a number here would be an unchecked guess.
 
-Unthinking, like every concern: nothing measured thinking on this call, and
-the measured arm ran without it.
+Unthinking, like every concern. Measured once, on Sonnet 5.5 under the
+structured-output constraint (2026-10-09, `probe_structured_s_minus.py`, 100
+pairs): the same call thinking at `low` (`format_mode="json", thinking="low"`)
+kept Ac- (+4, within noise) where the in-turn wording alone cost it a little
+(−8 / −4 over two runs), at no latency on that model (4.7 s against 4.4 s a
+write); on S- it added nothing beyond the wording (+15 either way). Not wired:
+on a model that keeps forced tool use it would also move this call to JSON
+mode, where no figure for it was taken. The next lever, if Ac- under the
+constraint needs one.
+
+THE CONSTRAINT AND S- (2026-10-09)
+=================================
+On a model whose structured calls carry `output_config.format`
+(`format_compat.structured_output_format`; Sonnet 5.5 first), the reply comes
+back as one compact line with terser texts — no prose, no thinking, the same
+request otherwise (`probe_structured_wire.py`) — and S- came back as the two
+traps IN TURN: a distinct third failure in 42% of 100 (four runs: 42/44/41/42)
+against 57% for the same call without the constraint (+15, CI +2..+28), which
+is what the first app measured on its cards (63% → 41% / 33%). Ac-/Re- were
+not hurt; the constraint helps them (96-98% valid against 91-93%). The rule
+now names the in-turn forms (`SYNTHESIS_SHAPE`), which restores S- to the
+unconstrained level under the constraint and is neutral without it. The
+constraint stays: it ended the parse re-asks, and the loss was a shape the
+rule did not name.
 
 SELECTION: AVAILABLE, OFF BY DEFAULT
 ====================================
@@ -99,8 +121,19 @@ TRANSFORMATION_POSITIONS = """1. The action (Ac): the concrete move that carries
 
 #: What the developments produce together. The S- sentences are the measured
 #: fix (`one-shot-transformation.md`: third-trap 4/17 → 12/17 on graph-built
-#: wheels once the synthesis prompt carried them) and are kept word for word.
-SYNTHESIS_SHAPE = """S+ is what emerges only when Ac+ and Re+ run together — a gain in dimension, not a middle: not "both", not the two strengths listed side by side. S- is the ONE named state Ac- and Re- produce together: a single way of failing that is neither trap on its own and not a choice between them. "Either X or Y", "X versus Y" and "X while Y" with X and Y the two traps are the inputs listed, not the collapse named."""
+#: wheels once the synthesis prompt carried them) and are kept word for word,
+#: with the two IN-TURN forms added on 2026-10-09: a writer under a structured-
+#: output constraint (Sonnet 5.5, `format_compat.structured_output_format`)
+#: wrote S- as the two traps in sequence ("X, then Y", "X alternating with Y")
+#: in 13-14 of ~58 failures per 100 against 4 of 43 without the constraint,
+#: and the rule named only the side-by-side forms. With them named: S- as a
+#: distinct third failure 42% → 57% on 100 pairs, twice (+15 / +16, both clear
+#: of noise), back to the unconstrained writer's 57%; neutral on Sonnet 5
+#: (−1, 100 pairs). Price: a pairwise "which S- is more specific" judge
+#: prefers the trap-restating headline (30-48 against this wording; an arm
+#: that asked for particulars won that read 60-19 and lost the whole shape
+#: gain), so that read is not a shape read. `tests/e2e/probe_structured_s_minus.py`.
+SYNTHESIS_SHAPE = """S+ is what emerges only when Ac+ and Re+ run together — a gain in dimension, not a middle: not "both", not the two strengths listed side by side. S- is the ONE named state Ac- and Re- produce together: a single way of failing that is neither trap on its own and not a choice between them. "Either X or Y", "X versus Y", "X while Y", "X, then Y" and "X alternating with Y" with X and Y the two traps are the inputs listed, side by side or in turn, not the collapse named."""
 
 #: How a one-shot call builds it: the poles FIRST, because a degraded action
 #: needs an action to degrade (the measured order), then the developments,
@@ -236,7 +269,8 @@ class TransformationSketchDto(BaseModel):
     s_minus: str = Field(
         description=(
             "S- — what Ac- and Re- running together collapse into: ONE named way of "
-            "failing that is neither T- nor A- on its own. Never 'either X or Y'."
+            "failing that is neither T- nor A- on its own. Never 'either X or Y', "
+            "'X then Y' or 'X alternating with Y'."
         )
     )
 

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/settings.py

@@ -40,8 +40,8 @@ class Settings(BaseModel):
 
     Per process (read once, from the base `DialecticalReasoning.setup()` installs;
     a value inside `using_settings` has no effect): `graph_db_*` (the connection is
-    a Singleton), `llm_connect_timeout_s` (the provider is registered once),
-    `effect_log_dir` (installed in `setup`). `DIALEXITY_MAX_CONCURRENT_LLM_CALLS`
+    a Singleton), `llm_connect_timeout_s` and `llm_read_timeout_s` (the provider
+    is registered once), `effect_log_dir` (installed in `setup`). `DIALEXITY_MAX_CONCURRENT_LLM_CALLS`
     is not a field at all: an env var behind one process-wide semaphore.
     """
 
@@ -276,6 +276,29 @@ class Settings(BaseModel):
     # slow generation is not the problem being solved here.
     llm_connect_timeout_s: float = Field(default=30.0, description="TCP/TLS connect timeout for LLM calls, in seconds. Raise on slow or high-latency links.")
 
+    # Read timeout for the Bedrock client, in seconds: how long one provider
+    # call may go without a byte arriving before it raises (`APITimeoutError`,
+    # which the ladder retries ONCE — `use_brain._STALL_RETRY_MAX`).
+    #
+    # The SDK's default is 600s, and the client used to keep it, so a stalled
+    # call held whatever was waiting on it for ten minutes with no error and no
+    # retry on record (a 610s turn, `prompt-vs-machinery`; the handoff that set
+    # this field: one of three gathered draws hung a 20-31s card for 300s,
+    # 2026-10-09, Sonnet 5.5). On a NON-streamed call the body arrives whole,
+    # so this is a ceiling on one generation; on a streamed round it is the gap
+    # between two chunks, and a thinking turn streams its deltas (the
+    # facilitator asks for `include_thoughts`), so the long silence is the
+    # non-streamed case only. 120s clears every unstalled generation in the
+    # archive (the longest measured conversational rounds sit under a minute on
+    # Sonnet 5 with thinking) while cutting a stall from 600s to two minutes. A
+    # host whose calls are short sets it lower: the first app's draws run ~15s,
+    # texts ~8s, structured calls ~3s on Sonnet 5.5, and it runs at 30s. Too
+    # low, and a legitimately long generation (a digest of a 40k-character
+    # part, an Opus round with a large dump) is cut and re-asked — the retry
+    # does not help a call that needed the time. Read once, with the connect
+    # timeout, when the provider registers.
+    llm_read_timeout_s: float = Field(default=120.0, description="Read timeout for LLM calls, in seconds: the longest one call may wait for the provider's next byte. Lower where every call is short; a stall then surfaces as a timeout instead of holding the caller.")
+
     @classmethod
     def from_partial(cls, partial_settings: Optional[Settings] = None) -> Self:
         """
@@ -353,5 +376,6 @@ class Settings(BaseModel):
             # something. `**` on an empty dict sends nothing.
             **_env_thinking_level(),
             llm_connect_timeout_s=float(os.getenv("DIALEXITY_LLM_CONNECT_TIMEOUT_S", 30.0)),
+            llm_read_timeout_s=float(os.getenv("DIALEXITY_LLM_READ_TIMEOUT_S", 120.0)),
             effect_log_dir=os.getenv("DIALEXITY_GRAPH_LOG_DIR"),
         )

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/settings_context.py

@@ -31,8 +31,8 @@ TWO TIERS, as the code already treats them (see `Settings`):
   through `SettingsAware.settings` (word limits, thinking level, the Advisor's
   floors and caps, the audit switches);
 - read ONCE per process, from the base only: `graph_db_*` (the connection is a
-  Singleton), `llm_connect_timeout_s` (the provider is registered once),
-  `effect_log_dir` (installed in `setup`). A value for these inside
+  Singleton), `llm_connect_timeout_s` and `llm_read_timeout_s` (the provider is
+  registered once), `effect_log_dir` (installed in `setup`). A value for these inside
   `using_settings` has no effect, by construction, not by accident.
 
 `container.settings.override(...)` RAISES: it would replace this provider with one

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/utils/bedrock_provider.py

@@ -36,27 +36,51 @@ if TYPE_CHECKING:
     from mirascope.llm.tools import AsyncToolkit, Toolkit
 
 
-def _connect_timeout(connect_timeout_s: float | None) -> httpx.Timeout:
-    """SDK default timeouts with a widened CONNECT phase only.
-
-    The SDK's 5s connect timeout assumes a warm datacenter link. A cold TLS
-    handshake over a tethered/VPN/mobile connection measured 7.7s, so the first
-    call on every fresh connection failed — and the parallel stages failed
-    hardest, since each concurrent call opens its own cold connection while a
-    sequential one reuses a handshaked socket. Read/write keep the SDK defaults:
-    a slow-to-connect link is a different problem from a slow generation, and
-    conflating them would mask real hangs.
+def _client_timeout(
+    connect_timeout_s: float | None, read_timeout_s: float | None = None
+) -> httpx.Timeout:
+    """SDK default timeouts with the CONNECT and READ phases set by the framework.
+
+    Connect: the SDK's 5s assumes a warm datacenter link. A cold TLS handshake
+    over a tethered/VPN/mobile connection measured 7.7s, so the first call on
+    every fresh connection failed — and the parallel stages failed hardest,
+    since each concurrent call opens its own cold connection while a sequential
+    one reuses a handshaked socket.
+
+    Read: the SDK's 600s is the length of a stall nobody asked for. A provider
+    call that stops sending holds its caller for ten minutes with no error, and
+    where callers are gathered (the view turn's best-of-3) one stalled draw
+    holds the two that finished (a 300s card where the same case took 20-31s,
+    2026-10-09). `Settings.llm_read_timeout_s` sets it; a timeout raises
+    `APITimeoutError`, which the ladder classifies as a stall and re-asks once.
+    Write and pool keep the SDK defaults: nothing has stalled on either.
     """
-    seconds = connect_timeout_s if connect_timeout_s is not None else 30.0
+    connect = connect_timeout_s if connect_timeout_s is not None else 30.0
+    read = read_timeout_s if read_timeout_s is not None else 120.0
     default = DEFAULT_TIMEOUT
     return httpx.Timeout(
-        connect=seconds,
-        read=default.read,
+        connect=connect,
+        read=read,
         write=default.write,
         pool=default.pool,
     )
 
 
+#: The Anthropic SDK's own retry is OFF: every retry the framework makes is one
+#: it can see. The SDK defaults to two retries of a timeout, a connection error
+#: or a 408/409/429/5xx with its own backoff, BELOW `use_brain`'s ladder and
+#: `retry_transient` — so a stalled call cost three read timeouts before the
+#: ladder saw one failure, and `retry_accounting`/`call_census` recorded none of
+#: it (a 610s turn with `retry_count` 0, `prompt-vs-machinery`). With this at 0
+#: the bound on one call is the ladder's: a stall is (`_STALL_RETRY_MAX`) × the
+#: read timeout plus its flat delay, and the retry is on the account. Every
+#: provider request the framework makes passes a retry layer of its own — the
+#: ladder (`use_brain`), the streamed open and resume (`retry_transient` in
+#: `_start_stream_round`) and, since this went to 0, the awaited resume too
+#: (`ConversationFacilitator.submit`), which until then had only the SDK's.
+_SDK_MAX_RETRIES = 0
+
+
 #: Start of the Advisor's mutable graph dump inside its system prompt.
 #:
 #: `_CONTEXT_SLOT` (`agents/advisor/system_prompts.py`) is the LAST section and the
@@ -361,11 +385,19 @@ class BedrockAnthropicProvider(AnthropicProvider):
     id = "bedrock"
     default_scope = "bedrock/"
 
-    def __init__(self, *, connect_timeout_s: float | None = None, **kwargs) -> None:  # noqa: ARG002
+    def __init__(
+        self,
+        *,
+        connect_timeout_s: float | None = None,
+        read_timeout_s: float | None = None,
+        **kwargs,  # noqa: ARG002
+    ) -> None:
         # Skip super().__init__() — parent creates Anthropic/AsyncAnthropic clients we don't need
-        timeout = _connect_timeout(connect_timeout_s)
-        self.client = AnthropicBedrock(timeout=timeout)
-        self.async_client = AsyncAnthropicBedrock(timeout=timeout)
+        timeout = _client_timeout(connect_timeout_s, read_timeout_s)
+        self.client = AnthropicBedrock(timeout=timeout, max_retries=_SDK_MAX_RETRIES)
+        self.async_client = AsyncAnthropicBedrock(
+            timeout=timeout, max_retries=_SDK_MAX_RETRIES
+        )
         self._beta_provider = None
 
     @staticmethod
@@ -594,17 +626,19 @@ def ensure_bedrock_provider(
 ) -> None:
     """Register the bedrock provider if not already registered. Idempotent.
 
-    Registration happens on the first call, so `llm_connect_timeout_s` is read
-    from DI here rather than in `__init__` (Mirascope constructs providers with
-    no arguments). Consequence of the idempotence: changing the setting after
-    the first LLM call of the process has no effect.
+    Registration happens on the first call, so `llm_connect_timeout_s` and
+    `llm_read_timeout_s` are read from DI here rather than in `__init__`
+    (Mirascope constructs providers with no arguments). Consequence of the
+    idempotence: changing either setting after the first LLM call of the
+    process has no effect.
     """
     global _registered
     if _registered:
         return
     llm.register_provider(
         BedrockAnthropicProvider(
-            connect_timeout_s=getattr(settings, "llm_connect_timeout_s", None)
+            connect_timeout_s=getattr(settings, "llm_connect_timeout_s", None),
+            read_timeout_s=getattr(settings, "llm_read_timeout_s", None),
         ),
         scope="bedrock/",
     )

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/utils/format_compat.py

@@ -38,6 +38,17 @@ refuse forced tool use — the ones whose structured calls go in JSON mode in
 the first place, explicitly (`format_mode="json"`) or by substitution — and
 to no other: Sonnet 5 / Opus 5 took it too in the probe, but every judged
 figure there was taken without it, so widening it is a measurement.
+
+**The constraint changes what is written, not only how it parses.** Under it
+the reply is one compact line with terser texts (`tests/e2e/
+probe_structured_wire.py`), and `TransformationSketch`'s S- came back as the
+two traps in turn: a distinct third failure 42% against 57% unconstrained on
+Sonnet 5.5 (100 pairs, +15 clear of noise; the first app saw 63% → 33-41%),
+while Ac-/Re- validity rose. The repair was the prompt, not the constraint:
+`SYNTHESIS_SHAPE` names the in-turn forms since 2026-10-09 and S- is back at
+57% with the constraint on (`tests/e2e/probe_structured_s_minus.py`, the gate
+for this seam on the transformation layer). A judged figure taken on a
+forced-tool model does not transfer to the constrained call by itself.
 """
 
 from __future__ import annotations

{dialectical_framework-2.0.8 → dialectical_framework-2.0.11}/src/dialectical_framework/utils/use_brain.py

@@ -86,7 +86,8 @@ def use_brain(
     Retries on ParseError (validation failures) with a FLAT delay — waiting does
     not fix a wrong shape, see `_PARSE_RETRY_DELAY_S` — and on rate limits /
     throttling, transient connection failures and transient 5xx with exponential
-    backoff (each with its own curve — see `_is_connection_error`).
+    backoff (each with its own curve — see `_is_connection_error`); a provider
+    STALL (read timeout) is re-asked once (`_STALL_RETRY_MAX`).
     Automatically traces all LLM calls via Langfuse when configured.
 
     When ``format`` is provided, returns the parsed model instance.
@@ -192,6 +193,7 @@ def use_brain(
             rate_delay = _RATE_LIMIT_BASE_S
             connect_delay = _CONNECT_RETRY_BASE_S
             connect_attempts = 0
+            stall_attempts = 0
             server_delay = _SERVER_RETRY_BASE_S
             server_attempts = 0
             last_error: Exception | None = None
@@ -325,6 +327,33 @@ def use_brain(
                             )
                             await asyncio.sleep(rate_delay)
                             rate_delay = min(rate_delay * 2.0, _RATE_LIMIT_CAP_S)
+                    elif _is_stall_error(e):
+                        # Checked BEFORE the connection branch: a read timeout is
+                        # a connection error by class, and it must not get that
+                        # curve's three attempts. Every stalled attempt has
+                        # already cost the whole read timeout, so the bound on
+                        # one call is `_STALL_RETRY_MAX` × that timeout plus one
+                        # flat delay — the figure `Settings.llm_read_timeout_s`
+                        # promises.
+                        stall_attempts += 1
+                        if stall_attempts >= _STALL_RETRY_MAX:
+                            raise
+                        last_error = e
+                        logging.getLogger(__name__).warning(
+                            "Provider stalled on %s (attempt %d/%d, %.0fs waited), "
+                            "re-asking in %.0fs: %s",
+                            format_name or method.__qualname__,
+                            stall_attempts, _STALL_RETRY_MAX,
+                            time.monotonic() - attempt_started, _STALL_RETRY_BASE_S, e,
+                        )
+                        if attempt < attempts - 1:
+                            slept_s += _STALL_RETRY_BASE_S
+                            record_retry(
+                                "stall",
+                                sleep_s=_STALL_RETRY_BASE_S,
+                                attempt_s=time.monotonic() - attempt_started,
+                            )
+                            await asyncio.sleep(_STALL_RETRY_BASE_S)
                     elif _is_connection_error(e):
                         # Bounded separately from `attempts`: a down endpoint must
                         # surface as an error, not consume the whole retry budget.
@@ -783,8 +812,61 @@ _CONNECT_RETRY_MAX = 3
 _CONNECT_RETRY_BASE_S = 2.0
 
 
+#: A STALL — the provider accepted the request and then stopped sending — is
+#: retried once, not on the connection curve. The two look alike by class (both
+#: arrive as the SDK's `APITimeoutError`, Mirascope's `TimeoutError`) and differ
+#: in what an attempt costs: a connect failure fails in milliseconds, a stall
+#: fails after the WHOLE read timeout (`Settings.llm_read_timeout_s`). Three
+#: attempts of that is three read timeouts before the caller hears anything,
+#: and where callers are gathered (the view turn's best-of-3) every finished
+#: draw waits for it. One re-ask is worth it — a stall is usually one bad
+#: backend instance and a fresh request lands elsewhere — and a second stall in
+#: a row is the ceiling. The delay is flat: waiting does not un-stall a server.
+#: Bound on one call, in full: `_STALL_RETRY_MAX` × read timeout + the delay.
+_STALL_RETRY_MAX = 2
+_STALL_RETRY_BASE_S = 2.0
+
+
+def _exception_chain(e: BaseException) -> Iterator[BaseException]:
+    """The exception and what it wraps: Mirascope's `original_exception`, then
+    `__cause__`/`__context__`. The SDK raises `APITimeoutError from
+    httpx.ReadTimeout` and Mirascope raises its `TimeoutError from` that, so the
+    phase that timed out is two links down."""
+    seen: set[int] = set()
+    pending: list[BaseException | None] = [e]
+    while pending:
+        current = pending.pop(0)
+        if current is None or id(current) in seen or len(seen) >= 10:
+            continue
+        seen.add(id(current))
+        yield current
+        pending.append(getattr(current, "original_exception", None))
+        pending.append(current.__cause__)
+        pending.append(current.__context__)
+
+
+def _is_stall_error(e: Exception) -> bool:
+    """Detect a READ timeout: the request was sent and the provider went quiet.
+
+    Decided by the httpx phase class in the chain. `ReadTimeout` is a stall;
+    `ConnectTimeout`/`WriteTimeout`/`PoolTimeout` are the link, left to
+    `_is_connection_error`. A timeout class with no phase in its chain (the
+    SDK's `APITimeoutError` or Mirascope's `TimeoutError` raised bare) is read
+    as a stall too — the shorter budget is the safe guess.
+    """
+    names = [type(x).__name__ for x in _exception_chain(e)]
+    if any(name.endswith("ReadTimeout") for name in names):
+        return True
+    if any(
+        name.endswith(("ConnectTimeout", "WriteTimeout", "PoolTimeout"))
+        for name in names
+    ):
+        return False
+    return any(name in ("APITimeoutError", "TimeoutError") for name in names)
+
+
 def _is_connection_error(e: Exception) -> bool:
-    """Detect transient network failures worth retrying.
+    """Detect transient network failures worth retrying — a stall excluded.
 
     Real failure this catches: the framework's parallel stages
     (ExplorationPipeline, ExploreTransformations) open many connections at once,
@@ -795,13 +877,18 @@ def _is_connection_error(e: Exception) -> bool:
     Matched by class name, not by import: Mirascope re-raises provider
     exceptions as its own `mirascope.llm.exceptions.ConnectionError`/`TimeoutError`,
     and importing those shadows the builtins in this module.
+
+    Exclusive with `_is_stall_error`, by construction: a read timeout is a
+    timeout by class but gets the stall budget, not this curve's three.
     """
+    if _is_stall_error(e):
+        return False
     name = type(e).__name__
     if name in ("ConnectionError", "TimeoutError", "APIConnectionError", "APITimeoutError"):
         return True
     # httpx raises distinct classes per phase (ConnectTimeout, ReadTimeout,
     # ConnectError, RemoteProtocolError); the shared suffix is the reliable tell.
-    return name.endswith(("ConnectError", "ConnectTimeout", "ReadTimeout"))
+    return name.endswith(("ConnectError", "ConnectTimeout"))
 
 
 #: Provider-side transient failures: the request was well-formed and the service
@@ -898,6 +985,8 @@ def _transient_kind(e: Exception) -> Optional[str]:
         return None
     if _is_rate_limit_error(e):
         return "rate_limit"
+    if _is_stall_error(e):
+        return "stall"
     if _is_connection_error(e):
         return "connection"
     if _is_transient_server_error(e):
@@ -930,9 +1019,10 @@ async def retry_transient(
     deterministic answer.
 
     Bounded per kind, with no overall ceiling, so the worst case is not any single
-    curve: a failure sequence that keeps CHANGING kind gets each budget in full, 7
-    attempts and ~51s of sleep before it surfaces. Bounded is what matters here, but
-    "30s" is the throttle-only figure and not the promise.
+    curve: a failure sequence that keeps CHANGING kind gets each budget in full, 8
+    attempts and ~53s of sleep before it surfaces (plus a read timeout for the one
+    stalled attempt). Bounded is what matters here, but "30s" is the throttle-only
+    figure and not the promise.
 
     `operation` must be safe to call again. That is a real precondition and not a
     formality: the caller re-sends a whole prompt, so it must have no side effects
@@ -946,6 +1036,7 @@ async def retry_transient(
     """
     delay = {
         "rate_limit": _RATE_LIMIT_BASE_S,
+        "stall": _STALL_RETRY_BASE_S,
         "connection": _CONNECT_RETRY_BASE_S,
         "server": _SERVER_RETRY_BASE_S,
     }
@@ -960,6 +1051,7 @@ async def retry_transient(
     #: surface as an error instead of spending a throttle-sized budget on it.
     budget = {
         "rate_limit": _RATE_LIMIT_RETRY_MAX,
+        "stall": _STALL_RETRY_MAX,
         "connection": _CONNECT_RETRY_MAX,
         "server": _SERVER_RETRY_MAX,
     }