prompture 1.16.1.dev1__tar.gz → 1.16.2.dev1__tar.gz

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.16.1.dev1
+Version: 1.16.2.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT

prompture-1.16.2.dev1/VERSION

@@ -0,0 +1 @@
+1.16.1

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.16.1.dev1'
-__version_tuple__ = version_tuple = (1, 16, 1, 'dev1')
+__version__ = version = '1.16.2.dev1'
+__version_tuple__ = version_tuple = (1, 16, 2, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/agents/agent.py

@@ -368,6 +368,7 @@ class Agent(Generic[DepsType]):
 
         self._lifecycle = AgentState.idle
         self._stop_requested = False
+        self._stop_final_answer = True
 
     # ------------------------------------------------------------------
     # Public API
@@ -394,7 +395,7 @@ class Agent(Generic[DepsType]):
         """Current lifecycle state of the agent."""
         return self._lifecycle
 
-    def stop(self) -> None:
+    def stop(self, *, final_answer: bool = True) -> None:
         """Request graceful shutdown after the current iteration.
 
         Sets the agent-level flag and forwards the request to the
@@ -405,11 +406,26 @@ class Agent(Generic[DepsType]):
         of the run, so the flag is never merely decorative.
 
         Safe to call from a tool, a callback, or another thread.
+
+        Args:
+            final_answer: With ``False`` the run ends right after the current
+                tool round, with no further model call. For a tool that hands
+                the turn back to a person (a question, a form, an approval):
+                the default would ask the model for one more answer, written
+                without the person's reply.
         """
         self._stop_requested = True
+        self._stop_final_answer = final_answer
         conv = self._active_conversation or self._conversation
         if conv is not None:
+            self._forward_stop(conv)
+
+    def _forward_stop(self, conv: Any) -> None:
+        """Pass a pending stop on to *conv*, keeping ``final_answer=False``."""
+        if self._stop_final_answer:
             conv.request_stop()
+        else:
+            conv.request_stop(final_answer=False)
 
     @property
     def callbacks(self) -> AgentCallbacks:
@@ -1045,7 +1061,7 @@ class Agent(Generic[DepsType]):
         """
         self._active_conversation = conv
         if self._stop_requested:
-            conv.request_stop()
+            self._forward_stop(conv)
         return conv
 
     def _execute(self, prompt: str, steps: list[AgentStep], deps: Any) -> AgentResult:

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/agents/async_agent.py

@@ -305,6 +305,7 @@ class AsyncAgent(Generic[DepsType]):
 
         self._lifecycle = AgentState.idle
         self._stop_requested = False
+        self._stop_final_answer = True
 
     # ------------------------------------------------------------------
     # Public API
@@ -328,7 +329,7 @@ class AsyncAgent(Generic[DepsType]):
         """Current lifecycle state of the agent."""
         return self._lifecycle
 
-    def stop(self) -> None:
+    def stop(self, *, final_answer: bool = True) -> None:
         """Request graceful shutdown after the current iteration.
 
         Sets the agent-level flag and forwards the request to the conversation
@@ -339,11 +340,26 @@ class AsyncAgent(Generic[DepsType]):
         the flag is never merely decorative.
 
         Safe to call from a tool, a callback, or another thread.
+
+        Args:
+            final_answer: With ``False`` the run ends right after the current
+                tool round, with no further model call. For a tool that hands
+                the turn back to a person (a question, a form, an approval):
+                the default would ask the model for one more answer, written
+                without the person's reply.
         """
         self._stop_requested = True
+        self._stop_final_answer = final_answer
         conv = self._active_conversation or self._conversation
         if conv is not None:
+            self._forward_stop(conv)
+
+    def _forward_stop(self, conv: Any) -> None:
+        """Pass a pending stop on to *conv*, keeping ``final_answer=False``."""
+        if self._stop_final_answer:
             conv.request_stop()
+        else:
+            conv.request_stop(final_answer=False)
 
     @property
     def callbacks(self) -> AgentCallbacks:
@@ -1073,7 +1089,7 @@ class AsyncAgent(Generic[DepsType]):
         """
         self._active_conversation = conv
         if self._stop_requested:
-            conv.request_stop()
+            self._forward_stop(conv)
         return conv
 
     async def _execute(

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/agents/async_conversation.py

@@ -146,6 +146,7 @@ class AsyncConversation(ToolContextMixin):
 
         # Cooperative stop (C2) and graceful max-rounds (C4) state.
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
 
         # Budget enforcement
@@ -231,13 +232,37 @@ class AsyncConversation(ToolContextMixin):
         self._full_tool_results.clear()
         self._reset_tool_context()
 
-    def request_stop(self) -> None:
+    def request_stop(self, *, final_answer: bool = True) -> None:
         """Request a cooperative stop of the tool loop.
 
         The loop checks the flag between rounds; when set, it finishes
         with one final no-tools answer instead of executing more tools.
+
+        Args:
+            final_answer: With ``False`` the turn ends right after the
+                current round, with no further model call: the reply is
+                the text the model wrote alongside its last tool calls.
+                For a tool that hands the turn back to a person (a
+                question, a form, an approval) and must not be followed
+                by an answer written without them.
         """
         self._stop_requested = True
+        self._stop_final_answer = final_answer
+
+    def _text_on_stop(self) -> str:
+        """The reply of a turn stopped with ``final_answer=False``.
+
+        The text of the last assistant message when it carried native tool
+        calls, else ``""`` (a simulated-tools round holds only the call).
+        """
+        for msg in reversed(self._messages):
+            if msg.get("role") != "assistant":
+                continue
+            content = msg.get("content")
+            if msg.get("tool_calls") and isinstance(content, str):
+                return content
+            return ""
+        return ""
 
     @property
     def max_rounds_reached(self) -> bool:
@@ -673,6 +698,7 @@ class AsyncConversation(ToolContextMixin):
     ) -> str:
         """Async tool-use loop: send -> check tool_calls -> execute -> re-send."""
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -682,6 +708,9 @@ class AsyncConversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return self._text_on_stop()
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 return await self._final_answer_without_tools(msgs, merged)
             self._check_budget()
@@ -776,6 +805,7 @@ class AsyncConversation(ToolContextMixin):
 
         # Native tool calling with event emission
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -785,6 +815,9 @@ class AsyncConversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 final_text = await self._final_answer_without_tools(msgs, merged)
                 yield {"type": "text_delta", "text": final_text}
@@ -926,6 +959,7 @@ class AsyncConversation(ToolContextMixin):
             return
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -935,6 +969,10 @@ class AsyncConversation(ToolContextMixin):
 
         for round_idx in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    yield TurnComplete(usage=dict(self._usage))
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 final_text = await self._final_answer_without_tools(msgs, merged)
                 yield TextDelta(text=final_text)
@@ -1078,6 +1116,7 @@ class AsyncConversation(ToolContextMixin):
         from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
         augmented_system = self._simulated_system_prompt()
@@ -1087,6 +1126,9 @@ class AsyncConversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 answer = await self._final_answer_simulated(augmented_system, merged)
                 yield {"type": "text_delta", "text": answer}
@@ -1160,6 +1202,7 @@ class AsyncConversation(ToolContextMixin):
         from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
         augmented_system = self._simulated_system_prompt()
@@ -1170,6 +1213,9 @@ class AsyncConversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return self._text_on_stop()
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 return await self._final_answer_simulated(augmented_system, merged)
             self._check_budget()

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/agents/conversation.py

@@ -148,6 +148,7 @@ class Conversation(ToolContextMixin):
 
         # Cooperative stop (C2) and graceful max-rounds (C4) state.
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
 
         # Budget enforcement
@@ -233,13 +234,37 @@ class Conversation(ToolContextMixin):
         self._full_tool_results.clear()
         self._reset_tool_context()
 
-    def request_stop(self) -> None:
+    def request_stop(self, *, final_answer: bool = True) -> None:
         """Request a cooperative stop of the tool loop.
 
         The loop checks the flag between rounds; when set, it finishes
         with one final no-tools answer instead of executing more tools.
+
+        Args:
+            final_answer: With ``False`` the turn ends right after the
+                current round, with no further model call: the reply is
+                the text the model wrote alongside its last tool calls.
+                For a tool that hands the turn back to a person (a
+                question, a form, an approval) and must not be followed
+                by an answer written without them.
         """
         self._stop_requested = True
+        self._stop_final_answer = final_answer
+
+    def _text_on_stop(self) -> str:
+        """The reply of a turn stopped with ``final_answer=False``.
+
+        The text of the last assistant message when it carried native tool
+        calls, else ``""`` (a simulated-tools round holds only the call).
+        """
+        for msg in reversed(self._messages):
+            if msg.get("role") != "assistant":
+                continue
+            content = msg.get("content")
+            if msg.get("tool_calls") and isinstance(content, str):
+                return content
+            return ""
+        return ""
 
     @property
     def max_rounds_reached(self) -> bool:
@@ -687,6 +712,7 @@ class Conversation(ToolContextMixin):
     ) -> str:
         """Execute the tool-use loop: send -> check tool_calls -> execute -> re-send."""
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -697,6 +723,9 @@ class Conversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return self._text_on_stop()
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 return self._final_answer_without_tools(msgs, merged)
             self._check_budget()
@@ -801,6 +830,7 @@ class Conversation(ToolContextMixin):
 
         # Native tool calling with event emission
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -810,6 +840,9 @@ class Conversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 final_text = self._final_answer_without_tools(msgs, merged)
                 yield {"type": "text_delta", "text": final_text}
@@ -966,6 +999,7 @@ class Conversation(ToolContextMixin):
             return
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
 
@@ -975,6 +1009,10 @@ class Conversation(ToolContextMixin):
 
         for round_idx in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    yield TurnComplete(usage=dict(self._usage))
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 final_text = self._final_answer_without_tools(msgs, merged)
                 yield TextDelta(text=final_text)
@@ -1124,6 +1162,7 @@ class Conversation(ToolContextMixin):
         from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
         augmented_system = self._simulated_system_prompt()
@@ -1133,6 +1172,9 @@ class Conversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 answer = self._final_answer_simulated(augmented_system, merged)
                 yield {"type": "text_delta", "text": answer}
@@ -1202,6 +1244,7 @@ class Conversation(ToolContextMixin):
         from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
+        self._stop_final_answer = True
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
         augmented_system = self._simulated_system_prompt()
@@ -1212,6 +1255,9 @@ class Conversation(ToolContextMixin):
 
         for _round in range(self._max_tool_rounds):
             if self._stop_requested:
+                if not self._stop_final_answer:
+                    logger.info("Stop requested; ending the turn without a final answer")
+                    return self._text_on_stop()
                 logger.info("Stop requested; finishing with a final answer (no more tool calls)")
                 return self._final_answer_simulated(augmented_system, merged)
             self._check_budget()

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/drivers/_openai_compat_stream.py

@@ -522,6 +522,28 @@ def _bearer_headers(api_key: str) -> dict[str, str]:
     return {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
 
 
+def _compat_url(driver: Any) -> str:
+    """The driver's ``/chat/completions`` URL.
+
+    Raw-HTTP drivers name their base URL ``api_base`` or ``base_url``; both are
+    accepted so a driver can't break streaming tool calls by its naming.
+    """
+    base = getattr(driver, "api_base", None) or getattr(driver, "base_url", None)
+    if not base:
+        raise AttributeError(f"{type(driver).__name__} has no api_base or base_url for streaming tool calls")
+    base = str(base).rstrip("/")
+    return base if base.endswith("/chat/completions") else f"{base}/chat/completions"
+
+
+def _compat_headers(driver: Any) -> dict[str, str]:
+    """The driver's own request headers when it keeps them (attribution
+    headers, provider extras), else a plain bearer header."""
+    own = getattr(driver, "headers", None)
+    if isinstance(own, dict) and own:
+        return {"Content-Type": "application/json", **own}
+    return _bearer_headers(driver.api_key)
+
+
 def stream_raw_http_compat_tool_call(
     driver: Any,
     messages: list[dict[str, Any]],
@@ -541,8 +563,8 @@ def stream_raw_http_compat_tool_call(
     of using the OpenAI SDK).
 
     Defaults assume the driver exposes:
-    - ``self.api_base`` — base URL (no trailing ``/chat/completions``)
-    - ``self.api_key`` — used as ``Authorization: Bearer <key>``
+    - ``self.api_base`` or ``self.base_url`` — base URL (no trailing ``/chat/completions``)
+    - ``self.headers`` (used as is) or ``self.api_key`` (``Authorization: Bearer <key>``)
 
     Override *url* or *headers* if the driver uses a different shape.
     Pass a complete *payload* (including streaming options) to preserve a
@@ -562,8 +584,8 @@ def stream_raw_http_compat_tool_call(
         )
     else:
         model = payload["model"]
-    resolved_url = url or f"{driver.api_base}/chat/completions"
-    resolved_headers = headers or _bearer_headers(driver.api_key)
+    resolved_url = url or _compat_url(driver)
+    resolved_headers = headers or _compat_headers(driver)
 
     state = _fresh_state()
     with requests.post(
@@ -634,8 +656,8 @@ async def astream_raw_http_compat_tool_call(
         )
     else:
         model = payload["model"]
-    resolved_url = url or f"{driver.api_base}/chat/completions"
-    resolved_headers = headers or _bearer_headers(driver.api_key)
+    resolved_url = url or _compat_url(driver)
+    resolved_headers = headers or _compat_headers(driver)
 
     state = _fresh_state()
     async with (

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/resilience/async_driver.py

@@ -202,6 +202,12 @@ class AsyncResilientDriver(AsyncDriver):
                 self._plan.observe(target, event)
                 yield _attach_route_to_event(event, route)
         except Exception as exc:
+            # Mid-stream failures do not fail over, on purpose. Events already
+            # reached the caller (text, tool calls), and replaying the request on
+            # another model would duplicate or contradict them. The target is
+            # penalized so the next request routes around it; the caller decides
+            # whether to retry the turn. Failures before the first event do fail
+            # over, because the opener runs inside ``_route``.
             self._plan.penalize(target, classify_error(exc))
             raise
 

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/resilience/errors.py

@@ -51,6 +51,8 @@ class ErrorInfo:
     retry_after: float | None = None
     message: str = ""
     provider: str | None = None
+    error_type: str | None = None
+    """Class name of the exception that was classified (e.g. ``KeyError``)."""
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -59,6 +61,7 @@ class ErrorInfo:
             "status_code": self.status_code,
             "retry_after": self.retry_after,
             "message": self.message,
+            "error_type": self.error_type,
         }
 
 
@@ -148,6 +151,16 @@ _DEFAULT_RULES: list[ErrorRule] = [
         pattern=r"does not support|not supported|unsupported|does not have access|not enabled for",
         priority=60,
     ),
+    # A valid OpenAI-schema request that one upstream validates against its own
+    # native schema (content block tags, part types). The next target is fine.
+    ErrorRule(
+        "provider_schema",
+        _A.FAILOVER,
+        pattern=r"does not match any of the expected tags|input tag .{0,80} found using|"
+        r"(?:invalid|unknown|unexpected|unrecognized) content (?:block|part|type)|"
+        r"content (?:block|part) type .{0,60} (?:is )?not (?:supported|allowed|permitted)",
+        priority=55,
+    ),
     ErrorRule("overloaded", _A.COOLDOWN, pattern=r"overloaded|at capacity|server is busy", priority=50),
     ErrorRule("rate_limit", _A.COOLDOWN, pattern=r"rate[_ ]limit|too many requests", priority=40),
     # Status-only rules.
@@ -355,7 +368,7 @@ def classify_error(exc: BaseException) -> ErrorInfo:
     message = str(exc) or type(exc).__name__
 
     def info(category: str, action: ErrorAction) -> ErrorInfo:
-        return ErrorInfo(action, category, status, retry_after, message, provider)
+        return ErrorInfo(action, category, status, retry_after, message, provider, type(exc).__name__)
 
     # Local capability gaps and missing configuration never improve on retry.
     # DriverError subclasses NotImplementedError for historical reasons, so

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture/resilience/router.py

@@ -305,6 +305,25 @@ def should_retry_same(policy: RetryPolicy, info: ErrorInfo, attempt: int, is_las
     return None
 
 
+_REASON_MAX = 160
+
+
+def _reason(err: dict[str, Any]) -> str:
+    """The failure's own words, shortened to one line.
+
+    A status code says little on its own and an ``unknown`` category says
+    nothing, so the summary carries what the exception said (and, when there
+    is no HTTP status, its type) to make a failed route diagnosable.
+    """
+    message = " ".join(str(err.get("message") or "").split())
+    error_type = err.get("error_type")
+    if error_type and not err.get("status_code") and error_type not in message:
+        message = f"{error_type}: {message}" if message else error_type
+    if len(message) > _REASON_MAX:
+        message = message[: _REASON_MAX - 3].rstrip() + "..."
+    return message
+
+
 def failure_message(attempts: list[dict[str, Any]]) -> str:
     if not attempts:
         return "No route targets were available"
@@ -314,5 +333,8 @@ def failure_message(attempts: list[dict[str, Any]]) -> str:
         detail = err.get("category") or a["outcome"]
         if err.get("status_code"):
             detail += f" {err['status_code']}"
+        reason = _reason(err) if err else ""
+        if reason and reason != err.get("category"):
+            detail += f" ({reason})"
         parts.append(f"{a['model']}: {detail}")
     return "All route targets failed (" + "; ".join(parts) + ")"

{prompture-1.16.1.dev1 → prompture-1.16.2.dev1}/prompture.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.16.1.dev1
+Version: 1.16.2.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT

prompture-1.16.1.dev1/VERSION

@@ -1 +0,0 @@
-1.16.0