selectools 0.27.1__tar.gz → 0.28.0__tar.gz

{selectools-0.27.1/src/selectools.egg-info → selectools-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.27.1
+Version: 0.28.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>
@@ -59,14 +59,18 @@ Provides-Extra: toolbox
 Requires-Dist: requests>=2.28.0; extra == "toolbox"
 Requires-Dist: slack-sdk>=3.27.0; extra == "toolbox"
 Requires-Dist: pdfplumber>=0.11.0; extra == "toolbox"
+Requires-Dist: pytz>=2023.3; extra == "toolbox"
 Provides-Extra: aws
 Requires-Dist: boto3>=1.34.0; extra == "aws"
 Provides-Extra: browser
 Requires-Dist: playwright>=1.40.0; extra == "browser"
 Provides-Extra: mongo
 Requires-Dist: pymongo>=4.0.0; extra == "mongo"
+Provides-Extra: cache
+Requires-Dist: redis>=4.0.0; extra == "cache"
 Provides-Extra: evals
 Requires-Dist: pyyaml>=6.0.0; extra == "evals"
+Requires-Dist: jsonschema>=4.0.0; extra == "evals"
 Provides-Extra: mcp
 Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
 Provides-Extra: litellm
@@ -77,7 +81,7 @@ Provides-Extra: supabase
 Requires-Dist: supabase>=2.0.0; extra == "supabase"
 Provides-Extra: serve
 Requires-Dist: pyyaml>=6.0.0; extra == "serve"
-Requires-Dist: starlette>=0.27.0; extra == "serve"
+Requires-Dist: starlette<1.0,>=0.27.0; extra == "serve"
 Requires-Dist: uvicorn[standard]>=0.24.0; extra == "serve"
 Requires-Dist: httpx>=0.24.0; extra == "serve"
 Dynamic: license-file
@@ -114,8 +118,27 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.28
+
+### v0.28.0 — Hardening Sweep: Shell Safety, Session Namespaces & Typed Public API
+
+A full audit-driven tech-debt sweep — mostly additive and bugfix, with one called-out behavior change.
+
+- **`execute_shell` is now a real boundary, not a best-effort filter** — it parses with `shlex` and runs with `shell=False`, so pipes, chaining (`;`, `&&`), redirection, subshells, globbing, and backgrounding can never be interpreted (closes the previously-bypassable `\n` and bare-`&` holes). **Behavior change:** commands relying on shell features now fail fast instead of running through `/bin/sh`.
+- **SSRF guard extended to the headless-browser tools and the serve webhook** — `browser_scrape_page`/`browser_screenshot` and the eval-alert webhook now reject loopback/private/link-local targets; SSRF logic is consolidated into one shared validator.
+- **Session namespaces fixed across all backends** — `SessionStore.branch()` gained an optional `namespace` parameter, and `list()` now returns a round-trippable storage key consistently (JSON/Redis/Mongo/DynamoDB previously returned a bare id that couldn't be reloaded for namespaced sessions).
+- **Embedding providers accept `timeout` + `max_retries`** (OpenAI/Voyage/Cohere, default 60s/2) so a hung or rate-limited call can't block ingestion.
+- **Typed public API** — `AgentResult.trace`/`.usage` and the ten `AgentConfig` nested-group fields are now their concrete types instead of `Any` (full autocomplete + type-checking); tightening surfaced and fixed two real bugs the `Any` had masked.
+- **Packaging** — added the missing `[cache]` extra (`redis`), `pytz` to `[toolbox]`, and `jsonschema` to `[evals]`.
+
+See `CHANGELOG.md` for the full entry (7,796 tests, 115 examples, 115 models).
+
 ## What's New in v0.27
 
+### v0.27.2 — Provider Model Fix & Tool-less Agents
+
+Fixes a P0: the agent ignored every provider's default model and sent `gpt-5-mini` to all of them, so **any non-OpenAI provider (Anthropic, Gemini, Ollama, LiteLLM) 404'd on every request**. `AgentConfig.model` now defaults to `None` and resolves to the provider's own default. Also: `Agent(tools=[])` is now valid (pure conversational agents), and the structured-output (`result.parsed` vs `.content`) and streaming (accumulate `StreamChunk` deltas, not the terminal `AgentResult`) sharp edges are documented.
+
 ### v0.27.1 — Bug-Hunt Patch
 
 An adversarial bug hunt of the v0.27.0 surface fixed 10 confirmed bugs (no API changes, no breaking changes). Highlights: scheduled agents recorded the `AgentResult` repr instead of the answer text; `PromptInjectionGuardrail` blocked benign requests ("pretend you are a pirate", "show the rules"); `s3_get_object` leaked its HTTP connection; and unified memory persisted un-redacted input in async mode. See `CHANGELOG.md` for the full list.
@@ -294,7 +317,7 @@ The first AI agent framework to ship a visual graph builder in a single `pip ins
 
 **[Try the builder in your browser →](https://selectools.dev/builder/)** — no install required.
 
-[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-96_scripts-06b6d4)](https://selectools.dev/examples/)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-115_scripts-06b6d4)](https://selectools.dev/examples/)
 
 ```bash
 pip install selectools
@@ -596,7 +619,7 @@ report = suite.run()
 report.to_html("report.html")
 ```
 
-- **50 Evaluators** — 30 deterministic + 21 LLM-as-judge
+- **50 Evaluators** — 29 deterministic + 21 LLM-as-judge
 - **A/B Testing**, regression detection, snapshot testing
 - **HTML reports**, JUnit XML, CLI, GitHub Action integration
 
@@ -678,7 +701,7 @@ report.to_html("report.html")
 | **Knowledge Graph** | Relationship triple extraction with in-memory and SQLite storage and keyword-based querying. |
 | **Cross-Session Knowledge** | Daily logs + persistent facts with auto-registered `remember` + `recall` tools. |
 | **MCP Integration** | Connect to any MCP tool server (stdio + HTTP). MCPClient, MultiMCPClient, MCPServer. Circuit breaker, retry, graceful degradation. |
-| **Eval Framework** | 50 built-in evaluators (30 deterministic + 21 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
+| **Eval Framework** | 50 built-in evaluators (29 deterministic + 21 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
 | **Multi-Agent Orchestration** | `AgentGraph` for directed agent graphs, `SupervisorAgent` with 4 strategies, HITL via generator nodes, parallel execution, checkpointing, subgraph composition. |
 | **Composable Pipelines** | `Pipeline` + `@step` + `|` operator + `parallel()` + `branch()` — chain agents, tools, and transforms with plain Python. |
 | **AgentObserver Protocol** | 46-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
@@ -725,7 +748,7 @@ report.to_html("report.html")
 - **Multi-Agent Orchestration**: `AgentGraph` with routing, parallel execution, HITL, checkpointing; `SupervisorAgent` with 4 strategies (plan_and_execute, round_robin, dynamic, magentic)
 - **Composable Pipelines**: `Pipeline` + `@step` + `|` operator + `parallel()` + `branch()` — chain agents, tools, and transforms
 - **115 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions (incl. Supabase), entity memory, knowledge graph, eval framework, advanced agent patterns, stability markers, HTML trace viewer, agent-as-API, A2A, routing, unified memory, scheduled agents, reasoning tools, and more
-- **Built-in Eval Framework**: 50 evaluators (30 deterministic + 21 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
+- **Built-in Eval Framework**: 50 evaluators (29 deterministic + 21 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
 - **AgentObserver Protocol**: 46 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
 - **7700+ Tests**: Unit, integration, regression, and E2E with real API calls
 
@@ -1353,7 +1376,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-7268 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, serve API, A2A, routing, and E2E integration with real API calls.
+7,796 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, serve API, A2A, routing, and E2E integration with real API calls.
 
 ## License
 

{selectools-0.27.1 → selectools-0.28.0}/README.md

@@ -30,8 +30,27 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.28
+
+### v0.28.0 — Hardening Sweep: Shell Safety, Session Namespaces & Typed Public API
+
+A full audit-driven tech-debt sweep — mostly additive and bugfix, with one called-out behavior change.
+
+- **`execute_shell` is now a real boundary, not a best-effort filter** — it parses with `shlex` and runs with `shell=False`, so pipes, chaining (`;`, `&&`), redirection, subshells, globbing, and backgrounding can never be interpreted (closes the previously-bypassable `\n` and bare-`&` holes). **Behavior change:** commands relying on shell features now fail fast instead of running through `/bin/sh`.
+- **SSRF guard extended to the headless-browser tools and the serve webhook** — `browser_scrape_page`/`browser_screenshot` and the eval-alert webhook now reject loopback/private/link-local targets; SSRF logic is consolidated into one shared validator.
+- **Session namespaces fixed across all backends** — `SessionStore.branch()` gained an optional `namespace` parameter, and `list()` now returns a round-trippable storage key consistently (JSON/Redis/Mongo/DynamoDB previously returned a bare id that couldn't be reloaded for namespaced sessions).
+- **Embedding providers accept `timeout` + `max_retries`** (OpenAI/Voyage/Cohere, default 60s/2) so a hung or rate-limited call can't block ingestion.
+- **Typed public API** — `AgentResult.trace`/`.usage` and the ten `AgentConfig` nested-group fields are now their concrete types instead of `Any` (full autocomplete + type-checking); tightening surfaced and fixed two real bugs the `Any` had masked.
+- **Packaging** — added the missing `[cache]` extra (`redis`), `pytz` to `[toolbox]`, and `jsonschema` to `[evals]`.
+
+See `CHANGELOG.md` for the full entry (7,796 tests, 115 examples, 115 models).
+
 ## What's New in v0.27
 
+### v0.27.2 — Provider Model Fix & Tool-less Agents
+
+Fixes a P0: the agent ignored every provider's default model and sent `gpt-5-mini` to all of them, so **any non-OpenAI provider (Anthropic, Gemini, Ollama, LiteLLM) 404'd on every request**. `AgentConfig.model` now defaults to `None` and resolves to the provider's own default. Also: `Agent(tools=[])` is now valid (pure conversational agents), and the structured-output (`result.parsed` vs `.content`) and streaming (accumulate `StreamChunk` deltas, not the terminal `AgentResult`) sharp edges are documented.
+
 ### v0.27.1 — Bug-Hunt Patch
 
 An adversarial bug hunt of the v0.27.0 surface fixed 10 confirmed bugs (no API changes, no breaking changes). Highlights: scheduled agents recorded the `AgentResult` repr instead of the answer text; `PromptInjectionGuardrail` blocked benign requests ("pretend you are a pirate", "show the rules"); `s3_get_object` leaked its HTTP connection; and unified memory persisted un-redacted input in async mode. See `CHANGELOG.md` for the full list.
@@ -210,7 +229,7 @@ The first AI agent framework to ship a visual graph builder in a single `pip ins
 
 **[Try the builder in your browser →](https://selectools.dev/builder/)** — no install required.
 
-[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-96_scripts-06b6d4)](https://selectools.dev/examples/)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-115_scripts-06b6d4)](https://selectools.dev/examples/)
 
 ```bash
 pip install selectools
@@ -512,7 +531,7 @@ report = suite.run()
 report.to_html("report.html")
 ```
 
-- **50 Evaluators** — 30 deterministic + 21 LLM-as-judge
+- **50 Evaluators** — 29 deterministic + 21 LLM-as-judge
 - **A/B Testing**, regression detection, snapshot testing
 - **HTML reports**, JUnit XML, CLI, GitHub Action integration
 
@@ -594,7 +613,7 @@ report.to_html("report.html")
 | **Knowledge Graph** | Relationship triple extraction with in-memory and SQLite storage and keyword-based querying. |
 | **Cross-Session Knowledge** | Daily logs + persistent facts with auto-registered `remember` + `recall` tools. |
 | **MCP Integration** | Connect to any MCP tool server (stdio + HTTP). MCPClient, MultiMCPClient, MCPServer. Circuit breaker, retry, graceful degradation. |
-| **Eval Framework** | 50 built-in evaluators (30 deterministic + 21 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
+| **Eval Framework** | 50 built-in evaluators (29 deterministic + 21 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
 | **Multi-Agent Orchestration** | `AgentGraph` for directed agent graphs, `SupervisorAgent` with 4 strategies, HITL via generator nodes, parallel execution, checkpointing, subgraph composition. |
 | **Composable Pipelines** | `Pipeline` + `@step` + `|` operator + `parallel()` + `branch()` — chain agents, tools, and transforms with plain Python. |
 | **AgentObserver Protocol** | 46-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
@@ -641,7 +660,7 @@ report.to_html("report.html")
 - **Multi-Agent Orchestration**: `AgentGraph` with routing, parallel execution, HITL, checkpointing; `SupervisorAgent` with 4 strategies (plan_and_execute, round_robin, dynamic, magentic)
 - **Composable Pipelines**: `Pipeline` + `@step` + `|` operator + `parallel()` + `branch()` — chain agents, tools, and transforms
 - **115 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions (incl. Supabase), entity memory, knowledge graph, eval framework, advanced agent patterns, stability markers, HTML trace viewer, agent-as-API, A2A, routing, unified memory, scheduled agents, reasoning tools, and more
-- **Built-in Eval Framework**: 50 evaluators (30 deterministic + 21 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
+- **Built-in Eval Framework**: 50 evaluators (29 deterministic + 21 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
 - **AgentObserver Protocol**: 46 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
 - **7700+ Tests**: Unit, integration, regression, and E2E with real API calls
 
@@ -1269,7 +1288,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-7268 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, serve API, A2A, routing, and E2E integration with real API calls.
+7,796 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, serve API, A2A, routing, and E2E integration with real API calls.
 
 ## License
 

{selectools-0.27.1 → selectools-0.28.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.27.1"
+version = "0.28.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.9"
@@ -79,6 +79,7 @@ toolbox = [
     "requests>=2.28.0",
     "slack-sdk>=3.27.0",
     "pdfplumber>=0.11.0",
+    "pytz>=2023.3",
 ]
 aws = [
     "boto3>=1.34.0",
@@ -89,8 +90,12 @@ browser = [
 mongo = [
     "pymongo>=4.0.0",
 ]
+cache = [
+    "redis>=4.0.0",
+]
 evals = [
     "pyyaml>=6.0.0",
+    "jsonschema>=4.0.0",
 ]
 mcp = [
     "mcp>=1.0.0,<2.0.0",
@@ -106,7 +111,7 @@ supabase = [
 ]
 serve = [
     "pyyaml>=6.0.0",
-    "starlette>=0.27.0",
+    "starlette>=0.27.0,<1.0",
     "uvicorn[standard]>=0.24.0",
     "httpx>=0.24.0",
 ]

{selectools-0.27.1 → selectools-0.28.0}/src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.27.1"
+__version__ = "0.28.0"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, evals, guardrails, models, observe, patterns, rag, toolbox

selectools-0.28.0/src/selectools/_ssrf.py

@@ -0,0 +1,88 @@
+"""
+Shared SSRF (server-side request forgery) URL validation.
+
+A single source of truth for the blocked-network list and the
+hostname-resolution check used by every outbound-request surface in the
+library (web search/scrape tools, headless-browser tools, RAG document
+loaders, and the serve webhook dispatcher).
+
+Two entry points expose the same logic under the two contracts callers
+need:
+
+- :func:`validate_url` returns an error string (or ``None`` when safe), for
+  tool functions that report errors as their return value.
+- :func:`check_url` raises :class:`ValueError`, for internal callers that
+  prefer exceptions.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import List, Optional, Union
+from urllib.parse import urlparse
+
+# Private / loopback / link-local networks that must never be reached from a
+# user- or model-supplied URL.
+_BLOCKED_NETWORKS: List[Union[ipaddress.IPv4Network, ipaddress.IPv6Network]] = [
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("169.254.0.0/16"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),
+    ipaddress.ip_network("fe80::/10"),
+]
+
+
+def validate_url(url: str) -> Optional[str]:
+    """Validate *url* against SSRF rules.
+
+    Returns a human-readable error message if the URL uses a non-HTTP
+    scheme, has no hostname, targets a loopback/internal name, or resolves
+    to a private/reserved IP range. Returns ``None`` when the URL is safe to
+    request.
+    """
+    parsed = urlparse(url)
+
+    if parsed.scheme not in ("http", "https"):
+        return f"Error: URL scheme {parsed.scheme!r} is not allowed."
+
+    hostname = parsed.hostname
+    if not hostname:
+        return "Error: URL has no hostname."
+
+    lower_host = hostname.lower()
+    if lower_host in ("localhost", "0.0.0.0"):  # nosec B104 — comparison, not a bind
+        return f"Error: Requests to {hostname!r} are blocked (loopback/internal address)."
+
+    try:
+        addr_infos = socket.getaddrinfo(hostname, None)
+    except socket.gaierror as e:
+        return f"Error: Could not resolve hostname {hostname!r}: {e}"
+
+    for _family, _type, _proto, _canonname, sockaddr in addr_infos:
+        ip = ipaddress.ip_address(sockaddr[0])
+        for network in _BLOCKED_NETWORKS:
+            if ip in network:
+                return (
+                    f"Error: URL resolves to private/reserved address {ip} "
+                    f"(network {network}). Requests to internal networks are blocked."
+                )
+
+    return None
+
+
+def check_url(url: str) -> None:
+    """Raise :class:`ValueError` if *url* fails SSRF validation.
+
+    Equivalent to :func:`validate_url` but raises instead of returning the
+    message (with the ``"Error: "`` prefix stripped).
+    """
+    message = validate_url(url)
+    if message is not None:
+        raise ValueError(message.removeprefix("Error: "))
+
+
+__all__ = ["validate_url", "check_url"]

{selectools-0.27.1 → selectools-0.28.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, Any, Callable, Dict, List, Optional, Tuple, cast
+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
@@ -65,8 +65,15 @@ class _ProviderCallerMixin:
                 temperature=self.config.temperature,
             )
             cached = self.config.cache.get(cache_key)
-            if cached is not None:
-                cached_msg = cast(Message, cached[0])
+            # Only treat a well-formed (Message, usage) pair as a cache hit;
+            # anything else (key collision, schema drift) falls through to a
+            # real provider call instead of crashing on a bad cast.
+            if (
+                isinstance(cached, (tuple, list))
+                and len(cached) >= 2
+                and isinstance(cached[0], Message)
+            ):
+                cached_msg = cached[0]
                 cached_usage = cached[1]
                 self.usage.add_usage(cached_usage, tool_name=None)
                 if run_id:
@@ -273,8 +280,15 @@ class _ProviderCallerMixin:
                 temperature=self.config.temperature,
             )
             cached = self.config.cache.get(cache_key)
-            if cached is not None:
-                cached_msg = cast(Message, cached[0])
+            # Only treat a well-formed (Message, usage) pair as a cache hit;
+            # anything else (key collision, schema drift) falls through to a
+            # real provider call instead of crashing on a bad cast.
+            if (
+                isinstance(cached, (tuple, list))
+                and len(cached) >= 2
+                and isinstance(cached[0], Message)
+            ):
+                cached_msg = cached[0]
                 cached_usage = cached[1]
                 self.usage.add_usage(cached_usage, tool_name=None)
                 if run_id:
@@ -524,21 +538,29 @@ class _ProviderCallerMixin:
                     elif isinstance(chunk, ToolCall):
                         tool_calls.append(chunk)
         else:
-            for chunk in self.provider.stream(
-                model=self._effective_model,
-                system_prompt=self._system_prompt,
-                messages=self._history,
-                tools=self.tools,
-                temperature=self.config.temperature,
-                max_tokens=self.config.max_tokens,
-                timeout=self.config.request_timeout,
-            ):
-                if isinstance(chunk, str):
-                    if chunk:
-                        aggregated.append(chunk)
-                        if stream_handler:
-                            stream_handler(chunk)
-                elif isinstance(chunk, ToolCall):
-                    tool_calls.append(chunk)
+            # Sync-generator fallback: wrap in closing() so a stream_handler
+            # exception or caller disconnect deterministically closes the
+            # provider generator (the sync analog of the aclosing path above).
+            from contextlib import closing
+
+            with closing(
+                self.provider.stream(
+                    model=self._effective_model,
+                    system_prompt=self._system_prompt,
+                    messages=self._history,
+                    tools=self.tools,
+                    temperature=self.config.temperature,
+                    max_tokens=self.config.max_tokens,
+                    timeout=self.config.request_timeout,
+                )
+            ) as stream:
+                for chunk in stream:
+                    if isinstance(chunk, str):
+                        if chunk:
+                            aggregated.append(chunk)
+                            if stream_handler:
+                                stream_handler(chunk)
+                    elif isinstance(chunk, ToolCall):
+                        tool_calls.append(chunk)
 
         return "".join(aggregated), tool_calls

{selectools-0.27.1 → selectools-0.28.0}/src/selectools/agent/_tool_executor.py

@@ -107,7 +107,7 @@ class _ToolExecutorMixin:
             return False
         if tool is None or getattr(tool, "terminal", False):
             return False
-        return len(result) > tcfg.compress_threshold
+        return bool(len(result) > tcfg.compress_threshold)
 
     def _stop_condition_hit(self, tool_name: str, result: str) -> bool:
         """True if config.stop_condition fires for this result (terminal path)."""
@@ -138,6 +138,7 @@ class _ToolExecutorMixin:
             tool_name,
             type(exc).__name__,
             exc,
+            exc_info=exc,
         )
 
     def _build_compression_request(self, tool_name: str, result: str) -> Message:
@@ -203,7 +204,7 @@ class _ToolExecutorMixin:
     def _compression_max_tokens(self) -> int:
         """Token budget for the summary: comfortably under the char threshold."""
         threshold = self.config.tool.compress_threshold
-        return max(128, min(1000, threshold // 4))
+        return int(max(128, min(1000, threshold // 4)))
 
     def _compress_tool_result(
         self,

{selectools-0.27.1 → selectools-0.28.0}/src/selectools/agent/config.py

@@ -22,6 +22,18 @@ if TYPE_CHECKING:
     from ..providers.base import Provider
     from ..sessions import SessionStore
     from ..usage import AgentUsage
+    from .config_groups import (
+        BudgetConfig,
+        CoherenceConfig,
+        CompressConfig,
+        GuardrailsConfig,
+        MemoryConfig,
+        RetryConfig,
+        SessionConfig,
+        SummarizeConfig,
+        ToolConfig,
+        TraceConfig,
+    )
 
 ConfirmAction = Union[
     Callable[[str, Dict[str, Any], str], bool],
@@ -123,7 +135,10 @@ class AgentConfig:
     """
 
     name: str = "agent"
-    model: str = "gpt-5-mini"
+    # None means "use the provider's own default_model". A hardcoded default
+    # here would be sent to EVERY provider — e.g. an OpenAI model id reaching
+    # the Anthropic API and 404-ing on every call.
+    model: Optional[str] = None
     temperature: float = 0.0
     max_tokens: int = 1000
     max_iterations: int = 6
@@ -176,16 +191,17 @@ class AgentConfig:
 
     # -- Nested config groups (optional, for YAML / clean APIs) --
     # When provided, nested values take precedence over flat fields.
-    retry: Optional[Any] = None  # RetryConfig
-    tool: Optional[Any] = None  # ToolConfig
-    coherence: Optional[Any] = None  # CoherenceConfig (name collision with coherence_check)
-    guardrail: Optional[Any] = None  # GuardrailsConfig
-    session: Optional[Any] = None  # SessionConfig
-    summarize: Optional[Any] = None  # SummarizeConfig
-    memory: Optional[Any] = None  # MemoryConfig
-    budget: Optional[Any] = None  # BudgetConfig
-    trace: Optional[Any] = None  # TraceConfig
-    compress: Optional[Any] = None  # CompressConfig
+    # (CoherenceConfig's attribute name collides with the flat coherence_check.)
+    retry: Optional["RetryConfig"] = None
+    tool: Optional["ToolConfig"] = None
+    coherence: Optional["CoherenceConfig"] = None
+    guardrail: Optional["GuardrailsConfig"] = None
+    session: Optional["SessionConfig"] = None
+    summarize: Optional["SummarizeConfig"] = None
+    memory: Optional["MemoryConfig"] = None
+    budget: Optional["BudgetConfig"] = None
+    trace: Optional["TraceConfig"] = None
+    compress: Optional["CompressConfig"] = None
 
     # -- Planning-as-config (ROADMAP P2). See PlanningConfig below and
     # agent/_planning.py for the adapter. Self-contained: default None means

{selectools-0.27.1 → selectools-0.28.0}/src/selectools/agent/core.py

@@ -142,16 +142,14 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
         Initialize a new Agent instance.
 
         Args:
-            tools: List of Tool instances the agent can use (minimum 1 required).
+            tools: List of Tool instances the agent can use. May be empty for a
+                pure conversational agent (the provider is called with no tools).
             provider: LLM provider adapter. Defaults to OpenAIProvider().
             prompt_builder: Custom prompt builder. Defaults to PromptBuilder().
             parser: Custom tool call parser. Defaults to ToolCallParser().
             config: Agent configuration options. Defaults to AgentConfig().
             memory: Optional conversation memory for maintaining history across turns.
 
-        Raises:
-            ValueError: If tools list is empty.
-
         Example:
             >>> agent = Agent(
             ...     tools=[search, calculator],
@@ -160,11 +158,10 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
             ...     memory=ConversationMemory(max_messages=20)
             ... )
         """
-        if not tools:
-            raise ValueError("Agent requires at least one tool.")
-
-        self.tools = tools
-        self._tools_by_name = {tool.name: tool for tool in tools}
+        # An empty tool list is valid: a pure conversational agent (no tools)
+        # is a normal use case — the provider is simply called with no tools.
+        self.tools = tools or []
+        self._tools_by_name = {tool.name: tool for tool in self.tools}
         self.provider = provider or OpenAIProvider()
         strategy = config.reasoning_strategy if config else None
         if prompt_builder:
@@ -248,10 +245,16 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
     def _effective_model(self) -> str:
         """The model to use for the current iteration.
 
-        Returns the model set by ``model_selector`` if active, otherwise
-        falls back to ``self.config.model``.
+        Resolution order: a ``model_selector`` override, then an explicit
+        ``config.model``, then the provider's own ``default_model``. Without the
+        provider fallback a non-OpenAI provider would receive the OpenAI default
+        and 404. The final ``"gpt-5-mini"`` only applies to providers that expose
+        no default (e.g. the LocalProvider stub, which ignores the model).
         """
-        return getattr(self, "_current_model", None) or self.config.model
+        override = getattr(self, "_current_model", None) or self.config.model
+        if override:
+            return override
+        return getattr(self.provider, "default_model", None) or "gpt-5-mini"
 
     def __call__(
         self,
@@ -316,14 +319,11 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
 
         Raises:
             KeyError: If no tool with that name exists.
-            ValueError: If removing would leave the agent with zero tools.
         """
         if tool_name not in self._tools_by_name:
             raise KeyError(
                 f"Tool '{tool_name}' not found. Available: {', '.join(self._tools_by_name.keys())}"
             )
-        if len(self.tools) <= 1:
-            raise ValueError("Agent requires at least one tool.")
 
         removed = self._tools_by_name.pop(tool_name)
         self.tools = [t for t in self.tools if t.name != tool_name]
@@ -1076,6 +1076,10 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
                     result = AgentResult(
                         message=Message(role=Role.ASSISTANT, content=f"Batch error: {exc}"),
                     )
+            # No lock needed here (unlike sync batch(), which uses real OS
+            # threads): merge() and the increment are synchronous with no
+            # await, so under asyncio's single-threaded event loop they run
+            # atomically relative to the other gathered coroutines.
             self.usage.merge(clone.usage)
             completed += 1
             if on_progress:
@@ -1121,6 +1125,14 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
         Returns:
             AgentResult with the final response and tool call metadata.
 
+        Error handling:
+            If the provider keeps failing after ``config.max_retries`` attempts,
+            the agent does NOT raise — it returns an ``AgentResult`` whose
+            ``content`` is ``"Provider error: <detail>"`` (graceful degradation),
+            and the failure is recorded on ``result.trace`` with the error.
+            Check ``result.trace`` (or test for the ``"Provider error:"`` prefix)
+            if you need to distinguish a provider failure from a real answer.
+
         Examples:
             >>> result = agent.run("What is Python?")
             >>> result = agent.run([Message(role=Role.USER, content="Hello")])
@@ -1212,7 +1224,7 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
                             # agent with a tight tool-iteration budget should
                             # still allow the full RetryConfig.max_retries
                             # worth of structured-validation retries.
-                            retry_budget = self.config.retry.max_retries
+                            retry_budget = self.config.max_retries
                             if ctx.structured_retries < retry_budget:
                                 ctx.structured_retries += 1
                                 ctx.trace.add(
@@ -1370,7 +1382,7 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
         clone.analytics = None
         return clone
 
-    @deprecated(since="1.0.0", replacement="clone_for_isolation")
+    @deprecated(since="0.25.0", replacement="clone_for_isolation")
     def _clone_for_isolation(self) -> "Agent":
         """Deprecated alias for :meth:`clone_for_isolation`."""
         return self.clone_for_isolation()
@@ -1391,8 +1403,21 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
             parent_run_id: Optional run-ID of a parent agent for trace linking.
 
         Yields:
-            StreamChunk: Intermediate content chunks.
-            AgentResult: The final result object (yielded at the very end).
+            StreamChunk: incremental content deltas (and tool-call chunks).
+            AgentResult: the final, complete result — yielded once at the very
+                end. Its ``.content`` is the WHOLE answer, not a delta.
+
+        Consuming the stream — accumulate the ``StreamChunk`` deltas and treat
+        the terminal ``AgentResult`` separately. Do NOT add the final
+        ``AgentResult.content`` to the accumulated deltas, or you will get the
+        answer twice::
+
+            text = ""
+            async for chunk in agent.astream("..."):
+                if isinstance(chunk, StreamChunk):
+                    text += chunk.content or ""   # deltas only
+                else:                              # AgentResult (terminal)
+                    result = chunk                 # full answer + metadata
         """
         messages = self._normalize_messages(messages)
 
@@ -1636,7 +1661,7 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
                             # agent with a tight tool-iteration budget should
                             # still allow the full RetryConfig.max_retries
                             # worth of structured-validation retries.
-                            retry_budget = self.config.retry.max_retries
+                            retry_budget = self.config.max_retries
                             if ctx.structured_retries < retry_budget:
                                 ctx.structured_retries += 1
                                 ctx.trace.add(
@@ -1955,7 +1980,7 @@ class Agent(_ToolExecutorMixin, _ProviderCallerMixin, _LifecycleMixin, _MemoryMa
                             # agent with a tight tool-iteration budget should
                             # still allow the full RetryConfig.max_retries
                             # worth of structured-validation retries.
-                            retry_budget = self.config.retry.max_retries
+                            retry_budget = self.config.max_retries
                             if ctx.structured_retries < retry_budget:
                                 ctx.structured_retries += 1
                                 ctx.trace.add(