selectools 1.0.1__tar.gz → 1.2.0__tar.gz

{selectools-1.0.1/src/selectools.egg-info → selectools-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 1.0.1
+Version: 1.2.0
 Summary: Production-ready Python framework for AI agents with multi-agent graphs, hybrid RAG, guardrails, audit logging, 50 evaluators, and a visual builder. Supports OpenAI, Anthropic, Gemini, Ollama. By NichevLabs.
 Author-email: John Nichev <johnnichev@gmail.com>
 Maintainer-email: NichevLabs <support@nichevlabs.com>

{selectools-1.0.1 → selectools-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "1.0.1"
+version = "1.2.0"
 description = "Production-ready Python framework for AI agents with multi-agent graphs, hybrid RAG, guardrails, audit logging, 50 evaluators, and a visual builder. Supports OpenAI, Anthropic, Gemini, Ollama. By NichevLabs."
 readme = "README.md"
 requires-python = ">=3.10"

{selectools-1.0.1 → selectools-1.2.0}/src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "1.0.1"
+__version__ = "1.2.0"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, evals, guardrails, models, observe, patterns, rag, toolbox
@@ -13,6 +13,7 @@ from .agent.config_groups import (
     MemoryConfig,
     RetryConfig,
     SessionConfig,
+    StructuredOutputConfig,
     SummarizeConfig,
     ToolConfig,
     TraceConfig,

{selectools-1.0.1 → selectools-1.2.0}/src/selectools/agent/_provider_caller.py

@@ -6,7 +6,7 @@ import asyncio
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
-from typing import TYPE_CHECKING, Callable, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple
 
 # Module-level singleton for running sync provider calls in an async context.
 # Creating a new ThreadPoolExecutor per call (inside a retry loop) wastes
@@ -50,8 +50,18 @@ class _ProviderCallerMixin:
         stream_handler: Optional[Callable[[str], None]] = None,
         trace: Optional[AgentTrace] = None,
         run_id: Optional[str] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        tools_override: Optional[List[Any]] = None,
+        system_prompt_override: Optional[str] = None,
     ) -> Message:
         call_start = time.time()
+        effective_tools = self.tools if tools_override is None else tools_override
+        effective_system_prompt = (
+            system_prompt_override if system_prompt_override is not None else self._system_prompt
+        )
+        provider_extra: Dict[str, Any] = {}
+        if response_format is not None:
+            provider_extra["response_format"] = response_format
 
         cache_key: Optional[str] = None
         if self.config.cache and not (
@@ -59,10 +69,11 @@ class _ProviderCallerMixin:
         ):
             cache_key = CacheKeyBuilder.build(
                 model=self._effective_model,
-                system_prompt=self._system_prompt,
+                system_prompt=effective_system_prompt,
                 messages=self._history,
-                tools=self.tools,
+                tools=effective_tools,
                 temperature=self.config.temperature,
+                response_format=response_format,
             )
             cached = self.config.cache.get(cache_key)
             # Only treat a well-formed (Message, usage) pair as a cache hit;
@@ -82,7 +93,7 @@ class _ProviderCallerMixin:
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
                     self._notify_observers(
                         "on_llm_end",
@@ -122,12 +133,15 @@ class _ProviderCallerMixin:
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
 
                 if self.config.stream and getattr(self.provider, "supports_streaming", False):
                     response_text, streamed_tool_calls = self._streaming_call(
-                        stream_handler=stream_handler
+                        stream_handler=stream_handler,
+                        response_format=response_format,
+                        tools=effective_tools,
+                        system_prompt=effective_system_prompt,
                     )
                     if run_id:
                         self._notify_observers("on_llm_end", run_id, response_text, None)
@@ -139,12 +153,13 @@ class _ProviderCallerMixin:
 
                 response_msg, usage_stats = self.provider.complete(
                     model=self._effective_model,
-                    system_prompt=self._system_prompt,
+                    system_prompt=effective_system_prompt,
                     messages=self._history,
-                    tools=self.tools,
+                    tools=effective_tools,
                     temperature=self.config.temperature,
                     max_tokens=self.config.max_tokens,
                     timeout=self.config.request_timeout,
+                    **provider_extra,
                 )
                 response_text = response_msg.content or ""
 
@@ -229,21 +244,29 @@ class _ProviderCallerMixin:
         )
 
     def _streaming_call(
-        self, stream_handler: Optional[Callable[[str], None]] = None
+        self,
+        stream_handler: Optional[Callable[[str], None]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        tools: Optional[List[Any]] = None,
+        system_prompt: Optional[str] = None,
     ) -> Tuple[str, List[ToolCall]]:
         if not getattr(self.provider, "supports_streaming", False):
             raise ProviderError(f"Provider {self.provider.name} does not support streaming.")
 
+        provider_extra: Dict[str, Any] = {}
+        if response_format is not None:
+            provider_extra["response_format"] = response_format
         aggregated: List[str] = []
         tool_calls: List[ToolCall] = []
         for chunk in self.provider.stream(
             model=self._effective_model,
-            system_prompt=self._system_prompt,
+            system_prompt=self._system_prompt if system_prompt is None else system_prompt,
             messages=self._history,
-            tools=self.tools,
+            tools=self.tools if tools is None else tools,
             temperature=self.config.temperature,
             max_tokens=self.config.max_tokens,
             timeout=self.config.request_timeout,
+            **provider_extra,
         ):
             if isinstance(chunk, str):
                 if chunk:
@@ -264,9 +287,19 @@ class _ProviderCallerMixin:
         stream_handler: Optional[Callable[[str], None]] = None,
         trace: Optional[AgentTrace] = None,
         run_id: Optional[str] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        tools_override: Optional[List[Any]] = None,
+        system_prompt_override: Optional[str] = None,
     ) -> Message:
         """Async version of _call_provider with retry logic."""
         call_start = time.time()
+        effective_tools = self.tools if tools_override is None else tools_override
+        effective_system_prompt = (
+            system_prompt_override if system_prompt_override is not None else self._system_prompt
+        )
+        provider_extra: Dict[str, Any] = {}
+        if response_format is not None:
+            provider_extra["response_format"] = response_format
 
         cache_key: Optional[str] = None
         if self.config.cache and not (
@@ -274,10 +307,11 @@ class _ProviderCallerMixin:
         ):
             cache_key = CacheKeyBuilder.build(
                 model=self._effective_model,
-                system_prompt=self._system_prompt,
+                system_prompt=effective_system_prompt,
                 messages=self._history,
-                tools=self.tools,
+                tools=effective_tools,
                 temperature=self.config.temperature,
+                response_format=response_format,
             )
             cached = self.config.cache.get(cache_key)
             # Only treat a well-formed (Message, usage) pair as a cache hit;
@@ -297,14 +331,14 @@ class _ProviderCallerMixin:
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
                     await self._anotify_observers(
                         "on_llm_start",
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
                     self._notify_observers(
                         "on_llm_end",
@@ -357,19 +391,22 @@ class _ProviderCallerMixin:
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
                     await self._anotify_observers(
                         "on_llm_start",
                         run_id,
                         self._history,
                         self._effective_model,
-                        self._system_prompt,
+                        effective_system_prompt,
                     )
 
                 if self.config.stream and getattr(self.provider, "supports_streaming", False):
                     response_text, streamed_tool_calls = await self._astreaming_call(
-                        stream_handler=stream_handler
+                        stream_handler=stream_handler,
+                        response_format=response_format,
+                        tools=effective_tools,
+                        system_prompt=effective_system_prompt,
                     )
                     if run_id:
                         self._notify_observers("on_llm_end", run_id, response_text, None)
@@ -386,12 +423,13 @@ class _ProviderCallerMixin:
                 ):
                     response_msg, usage_stats = await self.provider.acomplete(
                         model=self._effective_model,
-                        system_prompt=self._system_prompt,
+                        system_prompt=effective_system_prompt,
                         messages=self._history,
-                        tools=self.tools,
+                        tools=effective_tools,
                         temperature=self.config.temperature,
                         max_tokens=self.config.max_tokens,
                         timeout=self.config.request_timeout,
+                        **provider_extra,
                     )
                     response_text = response_msg.content or ""
                 else:
@@ -405,12 +443,13 @@ class _ProviderCallerMixin:
                         _get_async_provider_executor(),
                         lambda: self.provider.complete(
                             model=self._effective_model,
-                            system_prompt=self._system_prompt,
+                            system_prompt=effective_system_prompt,
                             messages=self._history,
-                            tools=self.tools,
+                            tools=effective_tools,
                             temperature=self.config.temperature,
                             max_tokens=self.config.max_tokens,
                             timeout=self.config.request_timeout,
+                            **provider_extra,
                         ),
                     )
                     response_text = response_msg.content or ""
@@ -506,12 +545,21 @@ class _ProviderCallerMixin:
         )
 
     async def _astreaming_call(
-        self, stream_handler: Optional[Callable[[str], None]] = None
+        self,
+        stream_handler: Optional[Callable[[str], None]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        tools: Optional[List[Any]] = None,
+        system_prompt: Optional[str] = None,
     ) -> Tuple[str, List[ToolCall]]:
         """Async version of _streaming_call."""
         if not getattr(self.provider, "supports_streaming", False):
             raise ProviderError(f"Provider {self.provider.name} does not support streaming.")
 
+        provider_extra: Dict[str, Any] = {}
+        if response_format is not None:
+            provider_extra["response_format"] = response_format
+        effective_tools = self.tools if tools is None else tools
+        effective_system_prompt = self._system_prompt if system_prompt is None else system_prompt
         aggregated: List[str] = []
         tool_calls: List[ToolCall] = []
 
@@ -521,12 +569,13 @@ class _ProviderCallerMixin:
             async with aclosing(
                 self.provider.astream(  # type: ignore[attr-defined]
                     model=self._effective_model,
-                    system_prompt=self._system_prompt,
+                    system_prompt=effective_system_prompt,
                     messages=self._history,
-                    tools=self.tools,
+                    tools=effective_tools,
                     temperature=self.config.temperature,
                     max_tokens=self.config.max_tokens,
                     timeout=self.config.request_timeout,
+                    **provider_extra,
                 )
             ) as stream:
                 async for chunk in stream:
@@ -546,12 +595,13 @@ class _ProviderCallerMixin:
             with closing(
                 self.provider.stream(
                     model=self._effective_model,
-                    system_prompt=self._system_prompt,
+                    system_prompt=effective_system_prompt,
                     messages=self._history,
-                    tools=self.tools,
+                    tools=effective_tools,
                     temperature=self.config.temperature,
                     max_tokens=self.config.max_tokens,
                     timeout=self.config.request_timeout,
+                    **provider_extra,
                 )
             ) as stream:
                 for chunk in stream:

{selectools-1.0.1 → selectools-1.2.0}/src/selectools/agent/_tool_executor.py

@@ -861,6 +861,11 @@ class _ToolExecutorMixin:
             cached_entry = self._check_tool_cache(tool, parameters)
             if cached_entry is not None:
                 raw, compressed = cached_entry
+                # Guardrails run on cache hits too — an entry written before
+                # a guardrail was configured must not bypass the stage.
+                guarded = self._run_tool_result_guardrails(tool_name, raw, trace, run_ctx=run_ctx)
+                if guarded != raw:
+                    raw, compressed = guarded, None
                 return _Result(
                     tc, raw, False, 0.0, tool, 0, cached=True, cached_compressed=compressed
                 )
@@ -886,7 +891,10 @@ class _ToolExecutorMixin:
             try:
                 result = self._execute_tool_with_timeout(tool, parameters, chunk_cb)
                 result = self._screen_tool_result(tool_name, result)
+                # Cache the pre-guardrail value: guardrails run at use time
+                # (fresh AND cached), so config changes apply retroactively.
                 self._store_tool_cache(tool, parameters, result)
+                result = self._run_tool_result_guardrails(tool_name, result, trace, run_ctx=run_ctx)
                 dur = time.time() - start
                 if run_id:
                     self._notify_observers(
@@ -1103,6 +1111,13 @@ class _ToolExecutorMixin:
             cached_entry = self._check_tool_cache(tool, parameters)
             if cached_entry is not None:
                 raw, compressed = cached_entry
+                # Guardrails run on cache hits too — an entry written before
+                # a guardrail was configured must not bypass the stage.
+                guarded = await self._arun_tool_result_guardrails(
+                    tool_name, raw, trace, run_ctx=run_ctx
+                )
+                if guarded != raw:
+                    raw, compressed = guarded, None
                 return _Result(
                     tc, raw, False, 0.0, tool, 0, cached=True, cached_compressed=compressed
                 )
@@ -1130,7 +1145,12 @@ class _ToolExecutorMixin:
             try:
                 result = await self._aexecute_tool_with_timeout(tool, parameters, chunk_cb)
                 result = self._screen_tool_result(tool_name, result)
+                # Cache the pre-guardrail value: guardrails run at use time
+                # (fresh AND cached), so config changes apply retroactively.
                 self._store_tool_cache(tool, parameters, result)
+                result = await self._arun_tool_result_guardrails(
+                    tool_name, result, trace, run_ctx=run_ctx
+                )
                 dur = time.time() - start
                 if run_id:
                     self._notify_observers(
@@ -1437,6 +1457,13 @@ class _ToolExecutorMixin:
         cached_entry = self._check_tool_cache(tool, parameters)
         if cached_entry is not None:
             cached_raw, cached_compressed = cached_entry
+            # Guardrails run on cache hits too — an entry written before a
+            # guardrail was configured must not bypass the stage.
+            guarded = self._run_tool_result_guardrails(
+                tool_name, cached_raw, ctx.trace, run_ctx=ctx
+            )
+            if guarded != cached_raw:
+                cached_raw, cached_compressed = guarded, None
             ctx.trace.add(
                 TraceStep(
                     type=StepType.CACHE_HIT,
@@ -1475,15 +1502,16 @@ class _ToolExecutorMixin:
 
             result = self._execute_tool_with_timeout(tool, parameters, chunk_callback)
             result = self._screen_tool_result(tool_name, result)
+            # Cache the pre-guardrail value: guardrails run at use time
+            # (fresh AND cached), so config changes apply retroactively.
+            self._store_tool_cache(tool, parameters, result)
+            result = self._run_tool_result_guardrails(tool_name, result, ctx.trace, run_ctx=ctx)
             duration = time.time() - start_time
 
             self._notify_observers(
                 "on_tool_end", ctx.run_id, call_id, tool_name, result, duration * 1000
             )
 
-            # Store in tool result cache
-            self._store_tool_cache(tool, parameters, result)
-
             ctx.trace.add(
                 TraceStep(
                     type=StepType.TOOL_EXECUTION,
@@ -1673,6 +1701,13 @@ class _ToolExecutorMixin:
         cached_entry = self._check_tool_cache(tool, parameters)
         if cached_entry is not None:
             cached_raw, cached_compressed = cached_entry
+            # Guardrails run on cache hits too — an entry written before a
+            # guardrail was configured must not bypass the stage.
+            guarded = await self._arun_tool_result_guardrails(
+                tool_name, cached_raw, ctx.trace, run_ctx=ctx
+            )
+            if guarded != cached_raw:
+                cached_raw, cached_compressed = guarded, None
             ctx.trace.add(
                 TraceStep(
                     type=StepType.CACHE_HIT,
@@ -1714,6 +1749,12 @@ class _ToolExecutorMixin:
 
             result = await self._aexecute_tool_with_timeout(tool, parameters, chunk_callback)
             result = self._screen_tool_result(tool_name, result)
+            # Cache the pre-guardrail value: guardrails run at use time
+            # (fresh AND cached), so config changes apply retroactively.
+            self._store_tool_cache(tool, parameters, result)
+            result = await self._arun_tool_result_guardrails(
+                tool_name, result, ctx.trace, run_ctx=ctx
+            )
             duration = time.time() - start_time
 
             self._notify_observers(
@@ -1723,9 +1764,6 @@ class _ToolExecutorMixin:
                 "on_tool_end", ctx.run_id, call_id, tool_name, result, duration * 1000
             )
 
-            # Store in tool result cache
-            self._store_tool_cache(tool, parameters, result)
-
             ctx.trace.add(
                 TraceStep(
                     type=StepType.TOOL_EXECUTION,

{selectools-1.0.1 → selectools-1.2.0}/src/selectools/agent/config.py

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
         MemoryConfig,
         RetryConfig,
         SessionConfig,
+        StructuredOutputConfig,
         SummarizeConfig,
         ToolConfig,
         TraceConfig,
@@ -202,6 +203,8 @@ class AgentConfig:
     budget: Optional["BudgetConfig"] = None
     trace: Optional["TraceConfig"] = None
     compress: Optional["CompressConfig"] = None
+    # Structured-output behavior (beta, v1.1). Group-only — no flat mirrors.
+    structured_output: Optional["StructuredOutputConfig"] = None
 
     # -- Planning-as-config (ROADMAP P2). See PlanningConfig below and
     # agent/_planning.py for the adapter. Self-contained: default None means
@@ -217,6 +220,7 @@ class AgentConfig:
             MemoryConfig,
             RetryConfig,
             SessionConfig,
+            StructuredOutputConfig,
             SummarizeConfig,
             ToolConfig,
             TraceConfig,
@@ -382,6 +386,10 @@ class AgentConfig:
                 keep_recent=self.compress_keep_recent,
             )
 
+        self.structured_output = _unpack(self.structured_output, StructuredOutputConfig)
+        if self.structured_output is None:
+            self.structured_output = StructuredOutputConfig()
+
         # -- Planning-as-config: auto-unpack dicts (for YAML / dict configs) --
         if isinstance(self.planning, dict):
             self.planning = PlanningConfig(**self.planning)

{selectools-1.0.1 → selectools-1.2.0}/src/selectools/agent/config_groups.py

@@ -24,9 +24,9 @@ Usage::
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
 
-from ..stability import stable
+from ..stability import beta, stable
 
 if TYPE_CHECKING:
     from ..cancellation import CancellationToken
@@ -37,6 +37,7 @@ if TYPE_CHECKING:
     from ..policy import ToolPolicy
     from ..providers.base import Provider
     from ..sessions import SessionStore
+    from ..types import Message
     from ..unified_memory import UnifiedMemory
 
 
@@ -174,6 +175,63 @@ class GuardrailsConfig:
     output_screening_patterns: Optional[List[str]] = None
 
 
+@beta
+@dataclass
+class StructuredOutputConfig:
+    """Structured-output (``response_format``) behavior settings (beta, v1.1).
+
+    Attributes:
+        native: Use the provider's native structured-output mode (OpenAI
+            ``json_schema``, Gemini ``response_json_schema``) when the provider
+            advertises support, instead of injecting a schema instruction into
+            the system prompt. Providers without native support keep the
+            prompt-injection + parse behavior unchanged. Default: True.
+        final_turn_only: Keep the schema out of tool-loop turns entirely.
+            The loop runs to convergence with no schema pressure (so tool
+            calling and the text ``ToolCallParser`` work normally), then one
+            extra synthesis call — with the schema applied and no tools —
+            produces the validated structured final answer. In ``astream()``
+            the synthesis JSON is delivered only via the terminal
+            ``AgentResult`` (``.content`` / ``.parsed``), never leaked as
+            content chunks. Costs at most one extra provider call per run
+            (see ``reuse_loop_answer`` / ``should_finalize`` /
+            ``single_pass`` for the paths that avoid it). Default: False.
+        reuse_loop_answer: In ``final_turn_only`` mode, when the loop's
+            converged answer validates against the schema, use it directly
+            and skip the synthesis call entirely (v1.2, issue #164). The
+            gate is conservative: the WHOLE answer must be a single JSON
+            object (fragments embedded in prose never qualify), Pydantic
+            schemas validate fully, and dict schemas must carry every
+            top-level ``required`` key. Anything else falls back to the
+            synthesis call. Default: True.
+        should_finalize: Optional predicate ``(messages, last_response_text)
+            -> bool`` consulted in ``final_turn_only`` mode when the
+            converged answer did NOT validate. Return ``False`` to skip the
+            synthesis call for turns that need no structured output — the
+            run finishes with ``parsed=None`` and
+            ``AgentResult.structured_status == "skipped"``. A validating
+            answer wins before the predicate runs (even with
+            ``reuse_loop_answer=False``). Like ``stop_condition``, an
+            exception raised by the predicate propagates and aborts the run.
+            Default: None (always finalize, the v1.1 behavior).
+        single_pass: In ``final_turn_only`` mode with a provider that
+            advertises ``supports_native_structured_output_with_tools``
+            (OpenAI/Azure), carry the schema natively on the loop calls so
+            the converged answer IS the structured object — combined with
+            ``reuse_loop_answer`` this eliminates the synthesis call (v1.2,
+            issue #166). Providers without combined support fall back to the
+            separate synthesis call. NOTE: in ``astream()`` the final answer
+            is then JSON and streams as content chunks (like plain native
+            mode). Default: False.
+    """
+
+    native: bool = True
+    final_turn_only: bool = False
+    reuse_loop_answer: bool = True
+    should_finalize: Optional[Callable[[List["Message"], str], bool]] = None
+    single_pass: bool = False
+
+
 @stable
 @dataclass
 class SessionConfig:
@@ -323,6 +381,7 @@ __stability__ = "stable"
 
 __all__ = [
     "RetryConfig",
+    "StructuredOutputConfig",
     "ToolConfig",
     "CoherenceConfig",
     "GuardrailsConfig",