selectools 0.19.0__tar.gz → 0.19.2__tar.gz

{selectools-0.19.0/src/selectools.egg-info → selectools-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.19.0
+Version: 0.19.2
 Summary: Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking.
 Author-email: John Nichev <johnnichev@gmail.com>
 Maintainer-email: NichevLabs <support@nichevlabs.com>
@@ -40,6 +40,7 @@ Requires-Dist: isort>=5.13.0; extra == "dev"
 Requires-Dist: flake8>=7.0.0; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
 Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
 Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
 Provides-Extra: rag
 Requires-Dist: chromadb>=0.4.0; extra == "rag"
@@ -63,7 +64,7 @@ Dynamic: license-file
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://johnnichev.github.io/selectools)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![Evaluators](https://img.shields.io/badge/evaluators-39-06b6d4.svg)](https://johnnichev.github.io/selectools/modules/EVALS/)
+[![Evaluators](https://img.shields.io/badge/evaluators-50-06b6d4.svg)](https://johnnichev.github.io/selectools/modules/EVALS/)
 
 An open-source project from **[NichevLabs](https://nichevlabs.com)**.
 
@@ -83,7 +84,83 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
-## What's New in v0.18
+## What's New in v0.19
+
+### v0.19.2 — Enterprise Hardening
+
+```python
+from selectools.stability import stable, beta, deprecated
+from selectools import trace_to_html
+
+# Mark your own extensions with stability levels
+@stable
+class MyProductionAgent: ...
+
+@beta
+class MyExperimentalFeature: ...
+
+@deprecated(since="0.19", replacement="MyProductionAgent")
+class MyOldAgent: ...
+
+# Visualise any trace as a waterfall HTML timeline
+Path("trace.html").write_text(trace_to_html(result.trace))
+```
+
+- **Stability markers** — `@stable`, `@beta`, `@deprecated(since, replacement)` for public API signalling
+- **Trace HTML viewer** — `trace_to_html(trace)` renders a standalone waterfall timeline
+- **Deprecation policy** — 2-minor-version window, programmatic introspection via `.__stability__`
+- **Security audit** — all 41 `# nosec` annotations reviewed and published in `docs/SECURITY.md`
+- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (3135 tests total)
+
+### v0.19.1 — Advanced Agent Patterns
+
+```python
+from selectools.patterns import PlanAndExecuteAgent, ReflectiveAgent, DebateAgent, TeamLeadAgent
+
+# PlanAndExecute — planner generates typed steps, executor runs them sequentially
+agent = PlanAndExecuteAgent(planner=planner, executor=executor, provider=provider)
+result = agent.run("Research and write a blog post about LLM safety")
+
+# ReflectiveAgent — actor drafts, critic reviews, actor revises until approved
+agent = ReflectiveAgent(actor=actor, critic=critic, provider=provider, max_reflections=3)
+result = agent.run("Draft a product announcement email")
+
+# DebateAgent — multiple agents argue, judge synthesizes conclusion
+agent = DebateAgent(agents={"optimist": opt, "skeptic": skep}, judge=judge, provider=provider)
+result = agent.run("Should we migrate our infrastructure to microservices?")
+
+# TeamLeadAgent — lead delegates subtasks, team executes in parallel or sequentially
+agent = TeamLeadAgent(lead=lead, team={"researcher": r, "writer": w}, provider=provider)
+result = agent.run("Produce a competitive analysis report")
+```
+
+- **PlanAndExecuteAgent** — Typed `PlanStep` list; optional replanning on step failure
+- **ReflectiveAgent** — Actor–critic loop with `ReflectionRound` records per revision
+- **DebateAgent** — N-agent debate with transcript, judge synthesis, `DebateResult`
+- **TeamLeadAgent** — `sequential`, `parallel`, or `dynamic` delegation strategies
+
+### v0.19.0 — Serve, Deploy & Complete Composition
+
+```python
+# One command deploys your agent over HTTP with SSE streaming
+# selectools serve agent.yaml
+
+# Compose tools into a single callable
+from selectools import compose
+search_and_summarize = compose(search_web, summarize)
+
+# Streaming composition
+async for chunk in pipeline.astream("input"):
+    print(chunk)
+```
+
+- **`selectools serve`** — HTTP deployment with SSE streaming, Playground UI, `/health`, `/schema`
+- **YAML config** — `AgentConfig.from_yaml("agent.yaml")`, 5 built-in templates
+- **`compose()`** — Chain tools into composite tool; `retry()` and `cache_step()` wrappers
+- **PostgresCheckpointStore** — Durable graph checkpointing backed by PostgreSQL
+
+<details>
+<summary><strong>v0.18.x highlights</strong></summary>
 
 ### v0.18.0 — Multi-Agent Orchestration
 
@@ -154,6 +231,8 @@ route = branch(
 - **parallel()** — Fan-out to multiple steps and merge results
 - **branch()** — Conditional routing based on input data
 
+</details>
+
 <details>
 <summary><strong>v0.17.x highlights</strong></summary>
 
@@ -276,7 +355,7 @@ report = suite.run()
 report.to_html("report.html")
 ```
 
-- **39 Evaluators** — 22 deterministic + 17 LLM-as-judge
+- **50 Evaluators** — 30 deterministic + 21 LLM-as-judge
 - **A/B Testing**, regression detection, snapshot testing
 - **HTML reports**, JUnit XML, CLI, GitHub Action integration
 
@@ -316,10 +395,12 @@ report.to_html("report.html")
 | `StateGraph` + `add_node` + `add_edge` + `compile()` | `AgentGraph.chain(a, b, c).run(prompt)` |
 | LCEL `prompt \| llm \| parser` with Runnable protocol | `@step` + `\|` on plain functions |
 | `interrupt()` restarts the whole node on resume | `yield InterruptRequest()` resumes at yield point |
-| LangSmith (paid) for tracing and evals | Built-in: 39 evaluators + traces, zero cost |
+| LangSmith (paid) for tracing and evals | Built-in: 50 evaluators + traces, zero cost |
 | 5+ packages (`langchain-core`, `langgraph`, `langsmith`...) | 1 package: `pip install selectools` |
 | `langserve` for deployment | `selectools serve agent.yaml` |
 
+> Full migration guide with code examples: **[Coming from LangChain](docs/MIGRATION.md)**
+
 ## Why Selectools
 
 | Capability | What You Get |
@@ -346,7 +427,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` tool. |
 | **MCP Integration** | Connect to any MCP tool server (stdio + HTTP). MCPClient, MultiMCPClient, MCPServer. Circuit breaker, retry, graceful degradation. |
-| **Eval Framework** | 39 built-in evaluators (22 deterministic + 17 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
+| **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. |
 | **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** | 45-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
@@ -382,10 +463,10 @@ report.to_html("report.html")
 - **Conversation Branching**: `ConversationMemory.branch()` and `SessionStore.branch()` for A/B exploration and checkpointing
 - **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
-- **61 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, eval framework, and more
-- **Built-in Eval Framework**: 39 evaluators (22 deterministic + 17 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
+- **75 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, eval framework, advanced agent patterns, stability markers, HTML trace viewer, 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
 - **AgentObserver Protocol**: 45 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
-- **2529 Tests**: Unit, integration, regression, and E2E with real API calls
+- **3135 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -934,6 +1015,18 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 | 59 | `59_agent_graph_checkpointing.py` | Checkpoint, interrupt, resume | No |
 | 60 | `60_supervisor_agent.py` | SupervisorAgent with 4 strategies | No |
 | 61 | `61_agent_graph_subgraph.py` | Nested subgraph composition | No |
+| 62 | `62_yaml_config.py` | Load AgentConfig from YAML | No |
+| 63 | `63_agent_templates.py` | Built-in agent templates | No |
+| 64 | `64_selectools_serve.py` | Serve agent over HTTP with `selectools serve` | No |
+| 65 | `65_tool_composition.py` | `compose()` tool chaining | No |
+| 66 | `66_streaming_pipeline.py` | `pipeline.astream()` streaming composition | No |
+| 67 | `67_type_safe_pipeline.py` | Type-safe step contracts | No |
+| 68 | `68_postgres_checkpoints.py` | PostgresCheckpointStore for AgentGraph | Yes + `[postgres]` |
+| 69 | `69_trace_store.py` | Trace storage and querying | No |
+| 70 | `70_plan_and_execute.py` | PlanAndExecuteAgent with typed steps | No |
+| 71 | `71_reflective_agent.py` | ReflectiveAgent actor–critic loop | No |
+| 72 | `72_debate_agent.py` | DebateAgent with optimist/skeptic/judge | No |
+| 73 | `73_team_lead_agent.py` | TeamLeadAgent with all 3 delegation strategies | No |
 
 Run any example:
 
@@ -970,12 +1063,13 @@ Also available in [`docs/`](docs/README.md):
 | [GUARDRAILS](docs/modules/GUARDRAILS.md) | Input/output validation pipeline |
 | [AUDIT](docs/modules/AUDIT.md) | JSONL audit logging |
 | [SECURITY](docs/modules/SECURITY.md) | Screening & coherence checking |
-| [EVALS](docs/modules/EVALS.md) | 39 evaluators, A/B testing, regression |
+| [EVALS](docs/modules/EVALS.md) | 50 evaluators, A/B testing, regression |
 | [MCP](docs/modules/MCP.md) | MCP client/server integration |
 | [BUDGET](docs/modules/BUDGET.md) | Token/cost budget limits |
 | [CANCELLATION](docs/modules/CANCELLATION.md) | Cooperative cancellation |
 | [ORCHESTRATION](docs/modules/ORCHESTRATION.md) | AgentGraph, routing, parallel, HITL |
 | [SUPERVISOR](docs/modules/SUPERVISOR.md) | SupervisorAgent, 4 strategies |
+| [PATTERNS](docs/modules/PATTERNS.md) | PlanAndExecute, Reflective, Debate, TeamLead |
 | [PARSER](docs/modules/PARSER.md) | Tool call parsing |
 | [PROMPT](docs/modules/PROMPT.md) | System prompt generation |
 
@@ -986,7 +1080,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-2529 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, and E2E integration with real API calls.
+3135 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, and E2E integration with real API calls.
 
 ## License
 

{selectools-0.19.0 → selectools-0.19.2}/README.md

@@ -4,7 +4,7 @@
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://johnnichev.github.io/selectools)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![Evaluators](https://img.shields.io/badge/evaluators-39-06b6d4.svg)](https://johnnichev.github.io/selectools/modules/EVALS/)
+[![Evaluators](https://img.shields.io/badge/evaluators-50-06b6d4.svg)](https://johnnichev.github.io/selectools/modules/EVALS/)
 
 An open-source project from **[NichevLabs](https://nichevlabs.com)**.
 
@@ -24,7 +24,83 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
-## What's New in v0.18
+## What's New in v0.19
+
+### v0.19.2 — Enterprise Hardening
+
+```python
+from selectools.stability import stable, beta, deprecated
+from selectools import trace_to_html
+
+# Mark your own extensions with stability levels
+@stable
+class MyProductionAgent: ...
+
+@beta
+class MyExperimentalFeature: ...
+
+@deprecated(since="0.19", replacement="MyProductionAgent")
+class MyOldAgent: ...
+
+# Visualise any trace as a waterfall HTML timeline
+Path("trace.html").write_text(trace_to_html(result.trace))
+```
+
+- **Stability markers** — `@stable`, `@beta`, `@deprecated(since, replacement)` for public API signalling
+- **Trace HTML viewer** — `trace_to_html(trace)` renders a standalone waterfall timeline
+- **Deprecation policy** — 2-minor-version window, programmatic introspection via `.__stability__`
+- **Security audit** — all 41 `# nosec` annotations reviewed and published in `docs/SECURITY.md`
+- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (3135 tests total)
+
+### v0.19.1 — Advanced Agent Patterns
+
+```python
+from selectools.patterns import PlanAndExecuteAgent, ReflectiveAgent, DebateAgent, TeamLeadAgent
+
+# PlanAndExecute — planner generates typed steps, executor runs them sequentially
+agent = PlanAndExecuteAgent(planner=planner, executor=executor, provider=provider)
+result = agent.run("Research and write a blog post about LLM safety")
+
+# ReflectiveAgent — actor drafts, critic reviews, actor revises until approved
+agent = ReflectiveAgent(actor=actor, critic=critic, provider=provider, max_reflections=3)
+result = agent.run("Draft a product announcement email")
+
+# DebateAgent — multiple agents argue, judge synthesizes conclusion
+agent = DebateAgent(agents={"optimist": opt, "skeptic": skep}, judge=judge, provider=provider)
+result = agent.run("Should we migrate our infrastructure to microservices?")
+
+# TeamLeadAgent — lead delegates subtasks, team executes in parallel or sequentially
+agent = TeamLeadAgent(lead=lead, team={"researcher": r, "writer": w}, provider=provider)
+result = agent.run("Produce a competitive analysis report")
+```
+
+- **PlanAndExecuteAgent** — Typed `PlanStep` list; optional replanning on step failure
+- **ReflectiveAgent** — Actor–critic loop with `ReflectionRound` records per revision
+- **DebateAgent** — N-agent debate with transcript, judge synthesis, `DebateResult`
+- **TeamLeadAgent** — `sequential`, `parallel`, or `dynamic` delegation strategies
+
+### v0.19.0 — Serve, Deploy & Complete Composition
+
+```python
+# One command deploys your agent over HTTP with SSE streaming
+# selectools serve agent.yaml
+
+# Compose tools into a single callable
+from selectools import compose
+search_and_summarize = compose(search_web, summarize)
+
+# Streaming composition
+async for chunk in pipeline.astream("input"):
+    print(chunk)
+```
+
+- **`selectools serve`** — HTTP deployment with SSE streaming, Playground UI, `/health`, `/schema`
+- **YAML config** — `AgentConfig.from_yaml("agent.yaml")`, 5 built-in templates
+- **`compose()`** — Chain tools into composite tool; `retry()` and `cache_step()` wrappers
+- **PostgresCheckpointStore** — Durable graph checkpointing backed by PostgreSQL
+
+<details>
+<summary><strong>v0.18.x highlights</strong></summary>
 
 ### v0.18.0 — Multi-Agent Orchestration
 
@@ -95,6 +171,8 @@ route = branch(
 - **parallel()** — Fan-out to multiple steps and merge results
 - **branch()** — Conditional routing based on input data
 
+</details>
+
 <details>
 <summary><strong>v0.17.x highlights</strong></summary>
 
@@ -217,7 +295,7 @@ report = suite.run()
 report.to_html("report.html")
 ```
 
-- **39 Evaluators** — 22 deterministic + 17 LLM-as-judge
+- **50 Evaluators** — 30 deterministic + 21 LLM-as-judge
 - **A/B Testing**, regression detection, snapshot testing
 - **HTML reports**, JUnit XML, CLI, GitHub Action integration
 
@@ -257,10 +335,12 @@ report.to_html("report.html")
 | `StateGraph` + `add_node` + `add_edge` + `compile()` | `AgentGraph.chain(a, b, c).run(prompt)` |
 | LCEL `prompt \| llm \| parser` with Runnable protocol | `@step` + `\|` on plain functions |
 | `interrupt()` restarts the whole node on resume | `yield InterruptRequest()` resumes at yield point |
-| LangSmith (paid) for tracing and evals | Built-in: 39 evaluators + traces, zero cost |
+| LangSmith (paid) for tracing and evals | Built-in: 50 evaluators + traces, zero cost |
 | 5+ packages (`langchain-core`, `langgraph`, `langsmith`...) | 1 package: `pip install selectools` |
 | `langserve` for deployment | `selectools serve agent.yaml` |
 
+> Full migration guide with code examples: **[Coming from LangChain](docs/MIGRATION.md)**
+
 ## Why Selectools
 
 | Capability | What You Get |
@@ -287,7 +367,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` tool. |
 | **MCP Integration** | Connect to any MCP tool server (stdio + HTTP). MCPClient, MultiMCPClient, MCPServer. Circuit breaker, retry, graceful degradation. |
-| **Eval Framework** | 39 built-in evaluators (22 deterministic + 17 LLM-as-judge). A/B testing, regression detection, snapshot testing, HTML reports, JUnit XML, CI integration. |
+| **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. |
 | **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** | 45-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
@@ -323,10 +403,10 @@ report.to_html("report.html")
 - **Conversation Branching**: `ConversationMemory.branch()` and `SessionStore.branch()` for A/B exploration and checkpointing
 - **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
-- **61 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, eval framework, and more
-- **Built-in Eval Framework**: 39 evaluators (22 deterministic + 17 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
+- **75 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, eval framework, advanced agent patterns, stability markers, HTML trace viewer, 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
 - **AgentObserver Protocol**: 45 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
-- **2529 Tests**: Unit, integration, regression, and E2E with real API calls
+- **3135 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -875,6 +955,18 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 | 59 | `59_agent_graph_checkpointing.py` | Checkpoint, interrupt, resume | No |
 | 60 | `60_supervisor_agent.py` | SupervisorAgent with 4 strategies | No |
 | 61 | `61_agent_graph_subgraph.py` | Nested subgraph composition | No |
+| 62 | `62_yaml_config.py` | Load AgentConfig from YAML | No |
+| 63 | `63_agent_templates.py` | Built-in agent templates | No |
+| 64 | `64_selectools_serve.py` | Serve agent over HTTP with `selectools serve` | No |
+| 65 | `65_tool_composition.py` | `compose()` tool chaining | No |
+| 66 | `66_streaming_pipeline.py` | `pipeline.astream()` streaming composition | No |
+| 67 | `67_type_safe_pipeline.py` | Type-safe step contracts | No |
+| 68 | `68_postgres_checkpoints.py` | PostgresCheckpointStore for AgentGraph | Yes + `[postgres]` |
+| 69 | `69_trace_store.py` | Trace storage and querying | No |
+| 70 | `70_plan_and_execute.py` | PlanAndExecuteAgent with typed steps | No |
+| 71 | `71_reflective_agent.py` | ReflectiveAgent actor–critic loop | No |
+| 72 | `72_debate_agent.py` | DebateAgent with optimist/skeptic/judge | No |
+| 73 | `73_team_lead_agent.py` | TeamLeadAgent with all 3 delegation strategies | No |
 
 Run any example:
 
@@ -911,12 +1003,13 @@ Also available in [`docs/`](docs/README.md):
 | [GUARDRAILS](docs/modules/GUARDRAILS.md) | Input/output validation pipeline |
 | [AUDIT](docs/modules/AUDIT.md) | JSONL audit logging |
 | [SECURITY](docs/modules/SECURITY.md) | Screening & coherence checking |
-| [EVALS](docs/modules/EVALS.md) | 39 evaluators, A/B testing, regression |
+| [EVALS](docs/modules/EVALS.md) | 50 evaluators, A/B testing, regression |
 | [MCP](docs/modules/MCP.md) | MCP client/server integration |
 | [BUDGET](docs/modules/BUDGET.md) | Token/cost budget limits |
 | [CANCELLATION](docs/modules/CANCELLATION.md) | Cooperative cancellation |
 | [ORCHESTRATION](docs/modules/ORCHESTRATION.md) | AgentGraph, routing, parallel, HITL |
 | [SUPERVISOR](docs/modules/SUPERVISOR.md) | SupervisorAgent, 4 strategies |
+| [PATTERNS](docs/modules/PATTERNS.md) | PlanAndExecute, Reflective, Debate, TeamLead |
 | [PARSER](docs/modules/PARSER.md) | Tool call parsing |
 | [PROMPT](docs/modules/PROMPT.md) | System prompt generation |
 
@@ -927,7 +1020,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-2529 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, and E2E integration with real API calls.
+3135 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, and E2E integration with real API calls.
 
 ## License
 

{selectools-0.19.0 → selectools-0.19.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.19.0"
+version = "0.19.2"
 description = "Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -51,6 +51,7 @@ dev = [
     "flake8>=7.0.0",
     "mypy>=1.8.0",
     "bandit>=1.7.0",
+    "hypothesis>=6.100.0",
     "mkdocs-material>=9.5.0",
 ]
 rag = [
@@ -142,8 +143,10 @@ testpaths = ["tests"]
 pythonpath = ["src", "."]
 asyncio_mode = "strict"
 addopts = "-v"
+python_files = ["test_*.py", "sim_*.py"]
 markers = [
     "e2e: mark test as end-to-end (requires real API keys, use --run-e2e to run)",
+    "integration: mark test as integration (no API keys, uses real implementations with mocks)",
     "openai: mark test as requiring OpenAI API key",
     "anthropic: mark test as requiring Anthropic API key",
     "gemini: mark test as requiring Gemini API key",

{selectools-0.19.0 → selectools-0.19.2}/src/selectools/__init__.py

@@ -1,9 +1,9 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.19.0"
+__version__ = "0.19.2"
 
 # Import submodules (lazy loading for optional dependencies)
-from . import embeddings, evals, guardrails, models, rag, toolbox
+from . import embeddings, evals, guardrails, models, patterns, rag, toolbox
 from .agent import Agent, AgentConfig
 from .agent.config_groups import (
     BudgetConfig,
@@ -99,6 +99,19 @@ from .orchestration import (
     SupervisorStrategy,
 )
 from .parser import ToolCallParser
+from .patterns import (
+    DebateAgent,
+    DebateResult,
+    DebateRound,
+    PlanAndExecuteAgent,
+    PlanStep,
+    ReflectionRound,
+    ReflectiveAgent,
+    ReflectiveResult,
+    Subtask,
+    TeamLeadAgent,
+    TeamLeadResult,
+)
 from .pipeline import Pipeline, Step, StepResult, branch, cache_step, parallel, retry, step
 from .policy import PolicyDecision, PolicyResult, ToolPolicy
 from .pricing import PRICING, calculate_cost, calculate_embedding_cost, get_model_pricing
@@ -116,10 +129,11 @@ from .sessions import (
     SessionStore,
     SQLiteSessionStore,
 )
+from .stability import beta, deprecated, stable
 from .structured import ResponseFormat
 from .token_estimation import TokenEstimate, estimate_run_tokens, estimate_tokens
 from .tools import Tool, ToolParameter, ToolRegistry, tool
-from .trace import AgentTrace, StepType, TraceStep
+from .trace import AgentTrace, StepType, TraceStep, trace_to_html
 from .types import AgentResult, Message, Role, ToolCall
 from .usage import AgentUsage, UsageStats
 
@@ -188,6 +202,10 @@ __all__ = [
     "PolicyResult",
     # Structured output
     "ResponseFormat",
+    # Stability markers
+    "stable",
+    "beta",
+    "deprecated",
     # Observability
     "AgentObserver",
     "AsyncAgentObserver",
@@ -196,6 +214,7 @@ __all__ = [
     "AgentTrace",
     "StepType",
     "TraceStep",
+    "trace_to_html",
     # Guardrails
     "guardrails",
     "Guardrail",
@@ -267,4 +286,17 @@ __all__ = [
     "SupervisorAgent",
     "SupervisorStrategy",
     "ModelSplit",
+    # Patterns
+    "patterns",
+    "PlanAndExecuteAgent",
+    "PlanStep",
+    "ReflectiveAgent",
+    "ReflectionRound",
+    "ReflectiveResult",
+    "DebateAgent",
+    "DebateRound",
+    "DebateResult",
+    "TeamLeadAgent",
+    "Subtask",
+    "TeamLeadResult",
 ]

{selectools-0.19.0 → selectools-0.19.2}/src/selectools/agent/_memory_manager.py

@@ -159,7 +159,8 @@ class _MemoryManagerMixin:
             return
 
         # Each "turn" is one user + one assistant message, so keep_recent * 2 messages.
-        keep_recent = self.config.compress_keep_recent * 2
+        # Always keep at least 1 message so the current user prompt is never compressed away.
+        keep_recent = max(self.config.compress_keep_recent * 2, 1)
         system_msgs: List[Message] = []
         non_system: List[Message] = []
         for m in self._history:

{selectools-0.19.0 → selectools-0.19.2}/src/selectools/agent/_provider_caller.py

@@ -3,10 +3,30 @@
 from __future__ import annotations
 
 import asyncio
+import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, cast
 
+# Module-level singleton for running sync provider calls in an async context.
+# Creating a new ThreadPoolExecutor per call (inside a retry loop) wastes
+# resources and prevents thread reuse (pitfall #20).
+_async_provider_executor: Optional[ThreadPoolExecutor] = None
+_async_provider_executor_lock = threading.Lock()
+
+
+def _get_async_provider_executor() -> ThreadPoolExecutor:
+    """Return the shared ThreadPoolExecutor for sync provider calls in async context."""
+    global _async_provider_executor
+    if _async_provider_executor is None:
+        with _async_provider_executor_lock:
+            if _async_provider_executor is None:
+                _async_provider_executor = ThreadPoolExecutor(
+                    max_workers=16, thread_name_prefix="selectools_provider"
+                )
+    return _async_provider_executor
+
+
 from ..cache import CacheKeyBuilder
 from ..providers.base import ProviderError
 from ..trace import StepType, TraceStep
@@ -252,19 +272,39 @@ class _ProviderCallerMixin:
                         self._effective_model,
                         self._system_prompt,
                     )
+                    await self._anotify_observers(
+                        "on_llm_start",
+                        run_id,
+                        self._history,
+                        self._effective_model,
+                        self._system_prompt,
+                    )
                     self._notify_observers(
                         "on_llm_end",
                         run_id,
                         cached_msg.content,
                         cached_usage,
                     )
+                    await self._anotify_observers(
+                        "on_llm_end",
+                        run_id,
+                        cached_msg.content,
+                        cached_usage,
+                    )
                     self._notify_observers(
                         "on_cache_hit",
                         run_id,
                         self._effective_model,
                         cached_msg.content or "",
                     )
+                    await self._anotify_observers(
+                        "on_cache_hit",
+                        run_id,
+                        self._effective_model,
+                        cached_msg.content or "",
+                    )
                     self._notify_observers("on_usage", run_id, cached_usage)
+                    await self._anotify_observers("on_usage", run_id, cached_usage)
                 if self.config.verbose:
                     print("[agent] cache hit -- skipping provider call")
                 if trace is not None:
@@ -322,21 +362,21 @@ class _ProviderCallerMixin:
                     )
                     response_text = response_msg.content or ""
                 else:
-                    # Fallback to sync in executor
-                    loop = asyncio.get_event_loop()
-                    with ThreadPoolExecutor() as executor:
-                        response_msg, usage_stats = await loop.run_in_executor(
-                            executor,
-                            lambda: self.provider.complete(
-                                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,
-                            ),
-                        )
+                    # Fallback to sync in executor — reuse the module-level singleton
+                    # to avoid spawning a new thread pool on every retry attempt.
+                    loop = asyncio.get_running_loop()
+                    response_msg, usage_stats = await loop.run_in_executor(
+                        _get_async_provider_executor(),
+                        lambda: self.provider.complete(
+                            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,
+                        ),
+                    )
                     response_text = response_msg.content or ""
 
                 self.usage.add_usage(usage_stats, tool_name=None)