dialectical-framework 2.1.2__tar.gz → 2.1.3__tar.gz

{dialectical_framework-2.1.2 → dialectical_framework-2.1.3}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dialectical-framework"
-version = "2.1.2"
+version = "2.1.3"
 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.1.2 → dialectical_framework-2.1.3}/src/dialectical_framework/agents/conversation_facilitator.py

@@ -35,7 +35,8 @@ from dialectical_framework.utils.call_census import record_call
 from dialectical_framework.utils.thinking_compat import conversational_round
 from dialectical_framework.utils.retry_accounting import (RetryAccount,
                                                           retry_account)
-from dialectical_framework.utils.use_brain import (prefill_token_kwargs,
+from dialectical_framework.utils.use_brain import (last_structured_reply_text,
+                                                  prefill_token_kwargs,
                                                   retry_transient, use_brain)
 
 from mirascope.llm import FinishReason, TextChunk, ThoughtChunk, ToolOutput
@@ -333,6 +334,15 @@ class ConversationFacilitator(SettingsAware):
         # prefill-sensitive quantity — the one prompt caching can move — is
         # `CallRecord.first_token_seconds` on the turn's first round, not this.
         self.last_submit_first_delta_s: Optional[float] = None
+        # The last STRUCTURED reply of this turn as the model wrote it, before
+        # parsing — the JSON text, or the tool call's arguments as text. `None`
+        # on a turn that made no structured call (a reused written reply, a
+        # mocked one). A DTO that validates can still carry a field the model
+        # cut short and continued in the next one (the first app's handoff,
+        # 2026-10-27); nothing in a parse can see that, but a host's own check
+        # can, and then it needs the bytes to say whether the split was the
+        # writing or the wire. See `use_brain.last_structured_reply_text`.
+        self.last_structured_reply_text: Optional[str] = None
         # Bumped once per submit, and captured by `submit_stream` so its `finally`
         # can tell "this turn is still the current one" from "a turn the consumer
         # walked away from, being finalised now".
@@ -522,6 +532,7 @@ class ConversationFacilitator(SettingsAware):
         self.last_tool_rounds = []
         self.last_submit_seconds = 0.0
         self.last_submit_retries = RetryAccount()
+        self.last_structured_reply_text = None
         # Reset here too although this path can never set it: a facilitator is
         # reused across turns, so without this a non-streaming submit would report
         # the previous STREAMED turn's figure as its own.
@@ -701,6 +712,7 @@ class ConversationFacilitator(SettingsAware):
         self.last_submit_seconds = 0.0
         self.last_submit_retries = RetryAccount()
         self.last_submit_first_delta_s = None
+        self.last_structured_reply_text = None
 
         # Re-entered per await instead of wrapped around the whole generator, and
         # `retry_account` explains why: a contextvar set across a `yield` installs
@@ -1442,6 +1454,8 @@ class ConversationFacilitator(SettingsAware):
             return messages
 
         result = await _llm_call()
+        # Same task as the call, so this is THIS call's text (see use_brain).
+        self.last_structured_reply_text = last_structured_reply_text()
         self._messages.append(
             llm.messages.assistant(
                 self._assistant_history_text(result),

{dialectical_framework-2.1.2 → dialectical_framework-2.1.3}/src/dialectical_framework/settings.py

@@ -36,7 +36,9 @@ class Settings(BaseModel):
     `dialectical_framework.settings_context` scopes them to one asyncio context):
     `ai_model`, `reasoning_model`, and everything read through
     `SettingsAware.settings` — word limits, the thinking level, the Advisor's
-    floors and caps, the audit switches.
+    floors and caps, the audit switches. `llm_stream_awaited_calls` and
+    `llm_stream_headers_timeout_s` are read at the provider on every call, so
+    they scope the same way.
 
     Per process (read once, from the base `DialecticalReasoning.setup()` installs;
     a value inside `using_settings` has no effect): `graph_db_*` (the connection is
@@ -304,7 +306,8 @@ class Settings(BaseModel):
     # Every awaited Bedrock call (`BedrockAnthropicProvider._create_async`) is
     # sent as a stream and assembled into the same `Message` before Mirascope
     # decodes it, so a stall is caught where it happens instead of at the whole
-    # read timeout: the response must OPEN within 5s (`_STREAM_HEADERS_TIMEOUT_S`),
+    # read timeout: the response must OPEN within `llm_stream_headers_timeout_s`
+    # (5s by default),
     # content must start within `llm_read_timeout_s`, and a gap past 5s once it
     # flows is a stall. Measured on the first app's promise run (2026-10-12,
     # Sonnet 5.5, 59 cases, read timeout 20s): ~5.5% of calls hang, ALL before
@@ -314,7 +317,29 @@ class Settings(BaseModel):
     # exists as an off switch for a model or provider the measurement did not
     # cover (`docs/dev-notes/streaming-latency-and-retry.md`, "Hangs are caught
     # at the opening"). Per request.
-    llm_stream_awaited_calls: bool = Field(default=True, description="Send awaited provider calls as streams and assemble the message, so a hung call is caught when the response fails to open (5s) rather than at the whole read timeout. On by default; off only for a model or provider where streaming misbehaves.")
+    llm_stream_awaited_calls: bool = Field(default=True, description="Send awaited provider calls as streams and assemble the message, so a hung call is caught when the response fails to open (`llm_stream_headers_timeout_s`) rather than at the whole read timeout. On by default; off only for a model or provider where streaming misbehaves.")
+
+    # How long a streamed awaited call may wait for the response to OPEN
+    # (headers, `message_start`) before it counts as a stall and is re-asked
+    # (`bedrock_provider._stream_to_message`; the re-ask is the stall curve's
+    # one, `use_brain._STALL_RETRY_MAX`). The default is the Bedrock
+    # measurement: the first app's promise run (2026-10-12, Sonnet 5.5, 890
+    # streamed calls) saw every stall (48, 5.4%) hang before the headers while
+    # healthy calls opened at a median 1.2s, p99 3.6s, whatever their size (6
+    # of 842 past 5s) — streamed, the opening is the one wait that does not
+    # grow with the output, so one short budget fits every call size.
+    #
+    # A setting since 2026-10-27 because the figure is per transport and
+    # account, not per model: on the native `anthropic/` transport the same
+    # 5s lost six of twelve fresh sessions in the first app (both attempts past
+    # the budget, with the SDK's own retry at zero so that is real
+    # time-to-first-byte), where on Bedrock the one re-ask had recovered every
+    # stall. Whether the native opening is slow (a wider budget lands the call)
+    # or hangs more often (only a retry would) is what the setting lets a host
+    # find out: widen it where the logged phase says "before headers" at a rate
+    # the re-ask does not absorb. Clamped to the read timeout; lowering it below
+    # the healthy p99 buys nothing. Per request, read at the call.
+    llm_stream_headers_timeout_s: float = Field(default=5.0, description="How long a streamed provider call may wait for the response to open, in seconds, before it counts as a stall and is re-asked once. 5s is the Bedrock measurement; widen it on a transport whose opening tail is longer. Never more than the read timeout.")
 
     @classmethod
     def from_partial(cls, partial_settings: Optional[Settings] = None) -> Self:
@@ -395,5 +420,6 @@ class Settings(BaseModel):
             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)),
             llm_stream_awaited_calls=os.getenv("DIALEXITY_LLM_STREAM_AWAITED_CALLS", "true").lower() == "true",
+            llm_stream_headers_timeout_s=float(os.getenv("DIALEXITY_LLM_STREAM_HEADERS_TIMEOUT_S", 5.0)),
             effect_log_dir=os.getenv("DIALEXITY_GRAPH_LOG_DIR"),
         )

{dialectical_framework-2.1.2 → dialectical_framework-2.1.3}/src/dialectical_framework/utils/bedrock_provider.py

@@ -415,15 +415,6 @@ logger = logging.getLogger(__name__)
 #: so it is a backstop; the measured hangs are all caught at the opening.
 _STREAM_GAP_TIMEOUT_S = 5.0
 
-#: How long a streamed awaited call may wait for the response to OPEN (headers,
-#: `message_start`) before it counts as a stall. Measured on the first app's
-#: promise run (2026-10-12, Sonnet 5.5, 890 streamed calls): every stall (48,
-#: 5.4%) hung before the headers, while healthy calls opened at a median 1.2s,
-#: p99 3.6s, whatever their size (6 of 842 past 5s). Streamed, the opening is
-#: the one wait that does not grow with the output, so it is where a hang is
-#: caught: here at 5s rather than at the whole read timeout.
-_STREAM_HEADERS_TIMEOUT_S = 5.0
-
 #: Deltas that are the answer being written, as opposed to thinking or
 #: bookkeeping. The SDK's stream yields both the raw `content_block_delta` and
 #: a synthesized event per delta kind.
@@ -450,14 +441,18 @@ def _is_content_event(event: Any) -> bool:
 
 
 async def _stream_to_message(
-    manager: _LearningStreamManager, model_name: str, read_timeout_s: float
+    manager: _LearningStreamManager,
+    model_name: str,
+    read_timeout_s: float,
+    headers_timeout_s: float,
 ) -> AnthropicMessage:
     """Consume one stream and return the assembled `Message`, policing silence.
 
-    Three budgets: the response must OPEN within `_STREAM_HEADERS_TIMEOUT_S`
-    (where the measured hangs are), the first content must follow within the
-    read timeout (queueing, prefill, thinking), and once content flows a gap
-    longer than `_STREAM_GAP_TIMEOUT_S` is a stall.
+    Three budgets: the response must OPEN within `headers_timeout_s`
+    (`Settings.llm_stream_headers_timeout_s` — where the measured hangs are,
+    and never more than the read timeout), the first content must follow
+    within the read timeout (queueing, prefill, thinking), and once content
+    flows a gap longer than `_STREAM_GAP_TIMEOUT_S` is a stall.
 
     The provider's `ping`s do not count as progress: a stream that only pings
     is a hang the socket's read timeout would never see. Every stall is logged
@@ -467,7 +462,7 @@ async def _stream_to_message(
     """
     loop = asyncio.get_running_loop()
     started = time.monotonic()
-    headers_budget = min(_STREAM_HEADERS_TIMEOUT_S, read_timeout_s)
+    headers_budget = min(headers_timeout_s, read_timeout_s)
     try:
         stream = await asyncio.wait_for(manager.__aenter__(), timeout=headers_budget)
     except asyncio.TimeoutError as e:
@@ -476,7 +471,7 @@ async def _stream_to_message(
             model_name, time.monotonic() - started,
         )
         raise StreamReadTimeout(
-            f"stream did not open within {headers_budget:.0f}s"
+            f"stream did not open within {headers_budget:g}s"
         ) from e
     except Exception as e:
         if type(e).__name__.endswith(("TimeoutError", "ReadTimeout")):
@@ -653,14 +648,18 @@ class _AnthropicTransport(AnthropicProvider):
         stream and comes back as the same assembled `Message`, so a stall is
         caught by the gap between chunks (`_stream_to_message`) instead of by a
         ceiling on the whole generation. The stream manager learns the thinking
-        shape the same way.
+        shape the same way. The opening budget is read here, per request
+        (`llm_stream_headers_timeout_s`); the read timeout was read once, when
+        the client was built.
         """
         model_name = kwargs["model"]
-        if get_current_settings().llm_stream_awaited_calls:
+        settings = get_current_settings()
+        if settings.llm_stream_awaited_calls:
             return await _stream_to_message(
                 _LearningStreamManager(self.async_client, kwargs, params),
                 model_name,
                 self._read_timeout_s,
+                settings.llm_stream_headers_timeout_s,
             )
         try:
             return await self.async_client.messages.create(

{dialectical_framework-2.1.2 → dialectical_framework-2.1.3}/src/dialectical_framework/utils/use_brain.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import json
 import logging
 import time
@@ -262,7 +263,7 @@ def use_brain(
                     )
                     if has_format:
                         try:
-                            return response.parse()
+                            parsed = response.parse()
                         except ParseError as e:
                             salvaged = _salvage_envelope(
                                 response,
@@ -276,6 +277,7 @@ def use_brain(
                                 e,
                             )
                             if salvaged is not None:
+                                _keep_structured_reply(response, format_name)
                                 return salvaged
                             # Nothing fit, so this is about to cost a re-ask and
                             # a nap. Say what the model actually sent, ONCE per
@@ -288,6 +290,8 @@ def use_brain(
                             if attempt == 0:
                                 _log_unsalvageable(response, format_name)
                             raise
+                        _keep_structured_reply(response, format_name)
+                        return parsed
                     return response
                 except ModelRefusal:
                     # Never retried, and never classified: its explanation is
@@ -481,6 +485,46 @@ def _framing_leak_note(text: str) -> str:
     )
 
 
+#: The text of the last structured reply parsed in this context, exactly as
+#: the model wrote it. A reply that PARSES can still be wrong in a way no
+#: parser sees: a string field cut mid-word with its tail written into the
+#: next field (the first app's handoff of 2026-10-27, one Lithuanian card of
+#: two) is valid JSON, and the DTO carries only the fields. The framework
+#: cannot tell such a field from a whole one — any check would be a reading of
+#: the content, which is the host's judge, not a parse — so what it does is
+#: keep the bytes: a host whose own check fires reads them back through
+#: `ConversationFacilitator.last_structured_reply_text` and can say whether
+#: the split was the model's writing or something on the way. A ContextVar,
+#: set in the caller's own task, so a draw gathered on another task never
+#: overwrites it; `None` until a structured call has returned here.
+_last_structured_reply: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "last_structured_reply", default=None
+)
+
+
+def last_structured_reply_text() -> Optional[str]:
+    """The raw text of the last structured reply parsed in this context."""
+    return _last_structured_reply.get()
+
+
+def _keep_structured_reply(response: Any, format_name: Optional[str]) -> None:
+    """Record a parsed reply as written, and say so at DEBUG, in full.
+
+    Whole and never clipped, unlike `_log_unsalvageable`: the tail is the part a
+    split-field diagnosis needs, and DEBUG is off unless a host turns it on for
+    exactly that. Payload text only — no prompt, no system prompt. Never
+    raises: this runs on the success path.
+    """
+    try:
+        text = response.text("") or ""
+    except Exception:  # noqa: BLE001
+        return
+    _last_structured_reply.set(text)
+    logging.getLogger(__name__).debug(
+        "Structured %s reply as written (%d chars): %s", format_name, len(text), text
+    )
+
+
 def _log_unsalvageable(response: Any, format_name: Optional[str]) -> None:
     """Log what the model actually sent, so the next envelope is a one-line fix.