selectools 1.0.0__tar.gz → 1.1.0__tar.gz

{selectools-1.0.0/src/selectools.egg-info → selectools-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 1.0.0
+Version: 1.1.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>
@@ -103,6 +103,8 @@ An open-source project from **[NichevLabs](https://nichevlabs.com)**.
 
 **Multi-agent orchestration in plain Python.** Build agent graphs, compose pipelines with `|`, deploy with one command. No DSL, no compile step, no paid debugger. Works with OpenAI, Anthropic, Gemini, and Ollama.
 
+> 🎉 **selectools is 1.0 — stable.** The public API is frozen; `@stable` symbols carry a 2-minor compatibility promise. Python 3.10+. See [What's New in v1.0](#whats-new-in-v10).
+
 ### 3 Ways to Build
 
 ```python

{selectools-1.0.0 → selectools-1.1.0}/README.md

@@ -16,6 +16,8 @@ An open-source project from **[NichevLabs](https://nichevlabs.com)**.
 
 **Multi-agent orchestration in plain Python.** Build agent graphs, compose pipelines with `|`, deploy with one command. No DSL, no compile step, no paid debugger. Works with OpenAI, Anthropic, Gemini, and Ollama.
 
+> 🎉 **selectools is 1.0 — stable.** The public API is frozen; `@stable` symbols carry a 2-minor compatibility promise. Python 3.10+. See [What's New in v1.0](#whats-new-in-v10).
+
 ### 3 Ways to Build
 
 ```python

{selectools-1.0.0 → selectools-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "1.0.0"
+version = "1.1.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"
@@ -154,15 +154,16 @@ ignore = [
     "E501",  # line too long (handled by formatter)
     "E402",  # module-level import not at top
     "E721",  # type comparison with == (allowed; legacy test pattern)
-    "F401",  # unused imports (common in __init__.py re-exports)
     "F541",  # f-string without placeholder
-    "F841",  # local variable assigned but never used
     "B011",  # do not call assert False
     "B023",  # function definition does not bind loop variable
     "B904",  # raise without `from` in except (TODO: fix pre-existing violations)
 ]
 
 [tool.ruff.lint.per-file-ignores]
+# F401 unused-import is expected in __init__.py re-export hubs (the public-API
+# surface). Everywhere else, unused imports and unused locals are real findings.
+"**/__init__.py" = ["F401"]
 "tests/*" = ["B"]
 "examples/*" = ["B", "F"]
 "scripts/*" = ["B", "F"]

{selectools-1.0.0 → selectools-1.1.0}/src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.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.1.0/src/selectools/_time.py

@@ -0,0 +1,42 @@
+"""Internal time helpers.
+
+Centralizes ISO-8601 timestamp parsing so every persistence backend handles a
+trailing ``Z`` (UTC designator) the same way.
+
+``datetime.fromisoformat`` did not accept the ``Z`` suffix until Python 3.11.
+On Python 3.10 (the project's minimum) a ``Z``-suffixed timestamp such as
+``"2026-06-15T12:00:00Z"`` raises ``ValueError``. Postgres/Supabase/Redis and
+other stores routinely return that form, so parsing it inline crashed the
+knowledge and checkpoint loaders on 3.10. ``parse_iso`` normalizes the suffix
+before delegating, so the same code works on every supported interpreter.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Union
+
+
+def parse_iso(value: Union[str, datetime]) -> datetime:
+    """Parse an ISO-8601 timestamp, tolerating a trailing ``Z`` (UTC).
+
+    Accepts either a string or an already-parsed ``datetime`` (returned as-is,
+    so callers reading columns that may already be typed do not need their own
+    ``isinstance`` guard). Timezone awareness is preserved exactly as encoded:
+    an offset-bearing string (including ``Z``) yields an aware datetime; a naive
+    string yields a naive datetime. Use :func:`ensure_aware` when a guaranteed
+    aware value is required.
+    """
+    if isinstance(value, datetime):
+        return value
+    s = str(value)
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    return datetime.fromisoformat(s)
+
+
+def ensure_aware(dt: datetime, *, tz: timezone = timezone.utc) -> datetime:
+    """Attach ``tz`` (default UTC) to a naive datetime; pass aware ones through."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=tz)
+    return dt

{selectools-1.0.0 → selectools-1.1.0}/src/selectools/agent/_lifecycle.py

@@ -8,7 +8,7 @@ import threading
 from typing import TYPE_CHECKING, Any, Optional, cast
 
 if TYPE_CHECKING:
-    from ..memory import ConversationMemory
+    pass
 
 logger = logging.getLogger(__name__)
 

{selectools-1.0.0 → selectools-1.1.0}/src/selectools/agent/_memory_manager.py

@@ -9,7 +9,6 @@ from ..trace import AgentTrace, StepType, TraceStep
 from ..types import Message, Role
 
 if TYPE_CHECKING:
-    from ..memory import ConversationMemory
     from .core import _RunContext
 
 

{selectools-1.0.0 → selectools-1.1.0}/src/selectools/agent/_provider_caller.py

@@ -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.0 → selectools-1.1.0}/src/selectools/agent/_tool_executor.py

@@ -57,8 +57,8 @@ def _get_parallel_dispatch_executor() -> ThreadPoolExecutor:
 
 
 from .._async_utils import run_in_executor_copyctx
-from ..coherence import CoherenceResult, acheck_coherence, check_coherence
-from ..policy import ApprovalRequest, PolicyDecision, PolicyResult, ToolPolicy
+from ..coherence import acheck_coherence, check_coherence
+from ..policy import ApprovalRequest, PolicyDecision, PolicyResult
 from ..security import screen_output as screen_tool_output
 from ..trace import StepType, TraceStep
 from ..types import Message, Role

{selectools-1.0.0 → selectools-1.1.0}/src/selectools/agent/config.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Coroutine, Dict, List, Optional, Union
 
-from ..stability import beta, stable
+from ..stability import stable
 
 if TYPE_CHECKING:
     from ..cache import Cache
@@ -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.0 → selectools-1.1.0}/src/selectools/agent/config_groups.py

@@ -24,23 +24,20 @@ Usage::
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 
-from ..stability import stable
+from ..stability import beta, stable
 
 if TYPE_CHECKING:
-    from ..cache import Cache
     from ..cancellation import CancellationToken
     from ..entity_memory import EntityMemory
     from ..guardrails import GuardrailsPipeline
     from ..knowledge import KnowledgeMemory
     from ..knowledge_graph import KnowledgeGraphMemory
-    from ..observer import AgentObserver
     from ..policy import ToolPolicy
     from ..providers.base import Provider
     from ..sessions import SessionStore
     from ..unified_memory import UnifiedMemory
-    from ..usage import AgentUsage
 
 
 @stable
@@ -177,6 +174,32 @@ 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 one extra provider call per run.
+            Default: False.
+    """
+
+    native: bool = True
+    final_turn_only: bool = False
+
+
 @stable
 @dataclass
 class SessionConfig:
@@ -326,6 +349,7 @@ __stability__ = "stable"
 
 __all__ = [
     "RetryConfig",
+    "StructuredOutputConfig",
     "ToolConfig",
     "CoherenceConfig",
     "GuardrailsConfig",