selectools 0.27.2__tar.gz → 0.29.0__tar.gz

{selectools-0.27.2/src/selectools.egg-info → selectools-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.27.2
+Version: 0.29.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,6 +118,34 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.29
+
+### v0.29.0 — Stability Promotions (v1.0 Freeze Prep)
+
+The first beta → stable promotion pass toward the 1.0 API freeze. Additive only — promotions strengthen guarantees, nothing is removed or renamed.
+
+- **24 mature toolbox tools promoted to `@stable`** — calculator, code (incl. `execute_shell`), db, email, GitHub, Linear, Notion, PDF, web search, and Slack tools. They're 4–15 releases old with frozen signatures.
+- **`orchestration`, `patterns`, and `policy` are now stable modules** — their public surfaces (AgentGraph, the checkpoint stores, all five pattern agents, ToolPolicy) were already frozen in v0.25; this aligns the module-level promise. Also promoted `SessionSearchResult` and `PlanningConfig`.
+- **Held `@beta` on purpose** — the v0.27.0 additions (recall tool, injection guardrail, cache-rate cost, Mongo/Dynamo session stores) get one more cycle, and `evals` stays a beta module while its 50 evaluator classes keep growing (its 7 core types are `@stable`).
+- **New `scripts/stability_audit.py`** reports any symbol whose marker disagrees with its module promise, so promotion passes are reproducible.
+
+See `CHANGELOG.md` for the full entry.
+
+## 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
@@ -298,7 +330,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
@@ -600,7 +632,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
 
@@ -682,7 +714,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`. |
@@ -729,7 +761,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
 
@@ -1357,7 +1389,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.2 → selectools-0.29.0}/README.md

@@ -30,6 +30,34 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.29
+
+### v0.29.0 — Stability Promotions (v1.0 Freeze Prep)
+
+The first beta → stable promotion pass toward the 1.0 API freeze. Additive only — promotions strengthen guarantees, nothing is removed or renamed.
+
+- **24 mature toolbox tools promoted to `@stable`** — calculator, code (incl. `execute_shell`), db, email, GitHub, Linear, Notion, PDF, web search, and Slack tools. They're 4–15 releases old with frozen signatures.
+- **`orchestration`, `patterns`, and `policy` are now stable modules** — their public surfaces (AgentGraph, the checkpoint stores, all five pattern agents, ToolPolicy) were already frozen in v0.25; this aligns the module-level promise. Also promoted `SessionSearchResult` and `PlanningConfig`.
+- **Held `@beta` on purpose** — the v0.27.0 additions (recall tool, injection guardrail, cache-rate cost, Mongo/Dynamo session stores) get one more cycle, and `evals` stays a beta module while its 50 evaluator classes keep growing (its 7 core types are `@stable`).
+- **New `scripts/stability_audit.py`** reports any symbol whose marker disagrees with its module promise, so promotion passes are reproducible.
+
+See `CHANGELOG.md` for the full entry.
+
+## 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
@@ -214,7 +242,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
@@ -516,7 +544,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
 
@@ -598,7 +626,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`. |
@@ -645,7 +673,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
 
@@ -1273,7 +1301,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.2 → selectools-0.29.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.27.2"
+version = "0.29.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.2 → selectools-0.29.0}/src/selectools/__init__.py

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

selectools-0.29.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.2 → selectools-0.29.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.2 → selectools-0.29.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.2 → selectools-0.29.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],
@@ -179,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
@@ -391,7 +404,7 @@ step executes and must return one of:
 """
 
 
-@beta
+@stable
 @dataclass
 class PlanningConfig:
     """Opt-in planning for any Agent: plan -> (approve) -> execute -> synthesize.

{selectools-0.27.2 → selectools-0.29.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],
@@ -1078,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:
@@ -1123,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")])
@@ -1214,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(
@@ -1372,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()
@@ -1651,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(
@@ -1970,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(

{selectools-0.27.2 → selectools-0.29.0}/src/selectools/embeddings/anthropic.py

@@ -35,6 +35,8 @@ class AnthropicEmbeddingProvider(EmbeddingProvider):
         model: str = "voyage-3-lite",
         api_key: Optional[str] = None,
         truncate: bool = True,
+        timeout: float = 60.0,
+        max_retries: int = 2,
     ):
         """
         Initialize Anthropic/Voyage embedding provider.
@@ -43,6 +45,10 @@ class AnthropicEmbeddingProvider(EmbeddingProvider):
             model: Model name (default: voyage-3-lite)
             api_key: Voyage API key (defaults to VOYAGE_API_KEY env var)
             truncate: Whether to truncate inputs longer than context window
+            timeout: Per-request timeout in seconds (default: 60). Prevents a
+                hung embeddings call from blocking ingestion indefinitely.
+            max_retries: Number of automatic retries on transient errors,
+                handled by the Voyage SDK (default: 2).
         """
         try:
             import voyageai
@@ -52,7 +58,12 @@ class AnthropicEmbeddingProvider(EmbeddingProvider):
                 "Install with: pip install voyageai"
             ) from e
 
-        self.client = voyageai.Client(api_key=api_key)
+        try:
+            self.client = voyageai.Client(api_key=api_key, max_retries=max_retries, timeout=timeout)
+        except TypeError:
+            # Older voyageai versions lack the timeout/max_retries kwargs.
+            logger.debug("voyageai.Client does not accept timeout/max_retries; using defaults")
+            self.client = voyageai.Client(api_key=api_key)
         self.model = model
         self.truncate = truncate
         self._dimension = self._get_model_dimension()