selectools 0.23.0__tar.gz → 0.25.0__tar.gz

{selectools-0.23.0/src/selectools.egg-info → selectools-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.23.0
+Version: 0.25.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>
@@ -55,10 +55,16 @@ Requires-Dist: beautifulsoup4>=4.12.0; extra == "rag"
 Provides-Extra: observe
 Requires-Dist: opentelemetry-api>=1.20.0; extra == "observe"
 Requires-Dist: langfuse>=2.0.0; extra == "observe"
+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"
 Provides-Extra: evals
 Requires-Dist: pyyaml>=6.0.0; extra == "evals"
 Provides-Extra: mcp
 Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0.0; extra == "litellm"
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
 Provides-Extra: supabase
@@ -67,6 +73,7 @@ Provides-Extra: serve
 Requires-Dist: pyyaml>=6.0.0; extra == "serve"
 Requires-Dist: starlette>=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
 
 ```
@@ -101,6 +108,51 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.25
+
+### v0.25.0 — Hardening & v1.0 Prep
+
+Five new features plus the final v1.0 groundwork: the entire 433-symbol public surface is now stability-marked (205 stable, 228 beta) with a CI gate, the long-deprecated `AgentConfig.hooks` is removed, and the security audit is published.
+
+- **Planning-as-config** — `AgentConfig(planning=PlanningConfig(...))` adds plan→execute→synthesize to any agent via isolated clones, with a complexity gate, cross-clone budget caps, and a plan approval handler.
+- **Agent-level HITL** — `ToolConfig(require_approval=[...], approval_handler=...)` gates tool execution behind a sync or async approval callback (fail-closed, denials memoized per run).
+- **Tool result compression** — `ToolConfig(compress_results=True)` summarizes oversized tool results via a one-shot LLM call before they enter context, with raw-text retention for stop conditions and loop detection.
+- **Knowledge pre-save sanitization** — `pre_save` hook on `KnowledgeMemory` plus built-in sanitizers: `defang_delimiters` (prompt-injection markers), `strip_surrogates`, `dedupe_against`.
+- **Pending intent hooks** — `pop_if_intent` (structured confirm/cancel from chat buttons, bypasses the text parser) and `tighten_ttl` (id-pinned atomic Lua rewrite on Redis).
+- **Stability marking sweep** — 100% of the public surface marked; 19 beta→stable promotions (AgentGraph + orchestration core, all 5 pattern agents, checkpoint stores, `RedisSessionStore`, `AzureOpenAIProvider`, ...); module-level `__stability__` on all 123 public modules; CI gate enforces markers forever.
+- **Wart removal** — `Agent.clone_for_isolation()` is public (`@beta`); `__all__` reconciled (11 documented symbols now exported, incl. the Pipeline family and `RouterProvider`); **BREAKING**: `AgentConfig(hooks=...)` now raises `TypeError` (deprecated since v0.16) — migrate to `AgentObserver` via `docs/MIGRATION_1.0.md`.
+- **Security audit published** — `docs/SECURITY_AUDIT.md`: bandit clean at medium/high, all 73 `nosec` suppressions justified, pip-audit pass, SBOM regenerated.
+- **Protocol isinstance fix** — stability markers no longer break third-party `isinstance` checks against `Cache`/`KnowledgeStore`/`CheckpointStore` on Python 3.9–3.11.
+
+See `CHANGELOG.md` for the full entry (7,268 tests, 111 examples).
+
+## What's New in v0.24
+
+### v0.24.0 — Production Interop
+
+Twelve features focused on running agents in production and connecting them to everything else: serve agents as REST APIs, talk to other agents over A2A, reach 100+ models through LiteLLM, route by cost, and persist memory anywhere.
+
+- **Agent-as-API** — `selectools.serve.AgentAPI` turns any Agent (or list of agents) into a production Starlette ASGI app: `POST /v1/chat`, SSE streaming, session CRUD, bearer auth, per-user session isolation. CLI: `selectools serve agent.yaml --api --port 8000`.
+- **A2A protocol** — `A2AServer` + `A2AClient` for agent-to-agent communication: Agent Card discovery (`/.well-known/agent.json`) and JSON-RPC 2.0 `message/send`/`tasks/get`/`tasks/cancel`.
+- **LiteLLMProvider** — instant access to 100+ models (DeepSeek, Groq, Bedrock, ...) via `pip install selectools[litellm]`.
+- **RouterProvider** — cost-optimized routing across model tiers with a deterministic complexity classifier and failure escalation.
+- **Anthropic prompt caching** — opt-in `cache_system=True` / `cache_tools=True` with cache hit-rate fields on `UsageStats`.
+- **UnifiedMemory** — tiered memory orchestrating conversation, knowledge, entity, and the new episodic tier, with token-aware compaction and federated `recall()`.
+- **Cross-session search** — `store.search(query)` on all four SessionStore backends (FTS5-accelerated on SQLite).
+- **KnowledgeBackend** — Supabase/Redis blob persistence for `KnowledgeMemory` on ephemeral infrastructure (Railway, Lambda, Cloud Run).
+- **ToolResult + Artifact** — typed tool results with a `kind` discriminator, plus an `emit_artifact()` side-channel surfaced on `AgentResult.artifacts`.
+- **Deferred confirmation flow** — `selectools.pending` for chat-channel destructive tools where the user's "yes" arrives as a separate webhook turn.
+- **Toolbox expansion** — 15 new tools (33 → 48): safe calculator, email, PDF extraction, Slack, Notion, Linear.
+- **Gemini schema sanitization** — bare `list` and `Dict[K, V]` tool parameters no longer 400 on the Gemini API; loud warnings for flash-lite's silent-empty-response failure mode.
+
+```python
+from selectools.serve import AgentAPI
+
+api = AgentAPI(agent, auth_key="secret")  # ASGI app: uvicorn main:api
+```
+
+See `CHANGELOG.md` for the full entry (6,187 tests, 111 examples).
+
 ## What's New in v0.23
 
 ### v0.23.0 — Supabase Sessions + Builder RAG
@@ -570,7 +622,15 @@ report.to_html("report.html")
 | **Audit Logging** | JSONL audit trail with privacy controls (redact, hash, omit) and daily rotation. |
 | **Tool Output Screening** | Prompt injection detection with 15 built-in patterns. Per-tool or global. |
 | **Coherence Checking** | LLM-based verification that tool calls match user intent — catches injection-driven tool misuse. |
-| **Persistent Sessions** | `SessionStore` with JSON file, SQLite, and Redis backends. Auto-save/load with TTL expiry. |
+| **Persistent Sessions** | `SessionStore` with JSON file, SQLite, Redis, and Supabase backends. Auto-save/load with TTL expiry, cross-session `search()`. |
+| **Agent-as-API** | `AgentAPI` serves any agent as a Starlette REST API — chat, SSE streaming, session CRUD, bearer auth, per-user session isolation. |
+| **A2A Protocol** | `A2AServer` + `A2AClient`: Agent Card discovery and JSON-RPC 2.0 messaging between agents. |
+| **LiteLLM Bridge** | `LiteLLMProvider` unlocks 100+ models (DeepSeek, Groq, Bedrock, ...) through one provider class. |
+| **Cost-Based Routing** | `RouterProvider` classifies request complexity and routes to model tiers with automatic failure escalation. |
+| **Unified Memory** | `UnifiedMemory` orchestrates conversation, knowledge, entity, and episodic tiers with token-aware compaction and federated `recall()`. |
+| **Typed Tool Results** | `ToolResult` base with `kind` discriminator; `emit_artifact()` side-channel surfaces files/URLs on `AgentResult.artifacts`. |
+| **Deferred Confirmation** | `selectools.pending` — confirm destructive chat-channel tools across webhook turns with TTL, scope, and args-digest matching. |
+| **Prompt Caching** | Anthropic `cache_system`/`cache_tools` markers with cache hit-rate fields on `UsageStats`. |
 | **Entity Memory** | LLM-based entity extraction with deduplication, LRU pruning, and system prompt injection. |
 | **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. |
@@ -578,14 +638,16 @@ report.to_html("report.html")
 | **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`. |
+| **AgentObserver Protocol** | 46-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
 | **Runtime Controls** | Token/cost budget limits, cooperative cancellation, per-tool approval gates, model switching per iteration. |
 | **Production Hardened** | Retries with backoff, per-tool timeouts, iteration caps, cost warnings, observability hooks + observers. |
 | **Library-First** | Not a framework. No magic globals, no hidden state. Use as much or as little as you need. |
 
 ## What's Included
 
-- **5 LLM Providers**: OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama + FallbackProvider (auto-failover)
+- **6 LLM Providers**: OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama, LiteLLM (100+ models) + FallbackProvider (auto-failover) + RouterProvider (cost-based routing)
+- **Agent-as-API**: `AgentAPI` — production REST endpoints (chat, SSE streaming, sessions) from any agent
+- **A2A Protocol**: Agent Card discovery + JSON-RPC 2.0 agent-to-agent messaging
 - **Structured Output**: Pydantic / JSON Schema `response_format` with auto-retry
 - **Execution Traces**: `result.trace` with typed timeline of every agent step
 - **Reasoning Visibility**: `result.reasoning` explains *why* the agent chose a tool
@@ -598,9 +660,14 @@ report.to_html("report.html")
 - **Dynamic Tool Loading**: Plugin system with hot-reload support
 - **Response Caching**: InMemoryCache and RedisCache with stats tracking
 - **152 Model Registry**: Type-safe constants with pricing and metadata
-- **Pre-built Toolbox**: 24 tools for files, data, text, datetime, web
-- **Persistent Sessions**: 3 backends (JSON file, SQLite, Redis) with TTL
+- **Pre-built Toolbox**: 48 tools for files, data, text, datetime, web, code, search, GitHub, DB, calculator, email, PDF, Slack, Notion, Linear
+- **Persistent Sessions**: 4 backends (JSON file, SQLite, Redis, Supabase) with TTL and cross-session search
 - **Entity Memory**: LLM-based named entity extraction and tracking
+- **Unified Memory**: tiered conversation/knowledge/entity/episodic memory with token-aware compaction
+- **Knowledge Backends**: Supabase/Redis blob persistence for KnowledgeMemory on ephemeral infra
+- **Typed Tool Results**: `ToolResult` base class + `Artifact` side-channel via `emit_artifact()`
+- **Deferred Confirmation**: `selectools.pending` for chat-channel destructive-tool confirmation
+- **Anthropic Prompt Caching**: `cache_system`/`cache_tools` with hit-rate visibility on `UsageStats`
 - **Knowledge Graph**: Triple extraction with in-memory and SQLite storage
 - **Cross-Session Knowledge**: Daily logs + persistent memory with `remember` tool, pluggable stores (File, SQLite), importance scoring, TTL
 - **Token Budget & Cancellation**: `max_total_tokens`, `max_cost_usd` hard limits; `CancellationToken` for cooperative stopping
@@ -611,10 +678,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
-- **96 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, and more
+- **111 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, 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
-- **5332 Tests**: Unit, integration, regression, and E2E with real API calls
+- **AgentObserver Protocol**: 46 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
+- **7268 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -940,7 +1007,7 @@ agent = Agent(
 )
 ```
 
-45 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG, budget exceeded, cancelled, prompt compressed, plus 13 graph events (graph start/end, node start/end, routing, interrupt, resume, parallel, stall, loop, supervisor replan). See `observer.py` for full reference.
+46 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG, budget exceeded, cancelled, prompt compressed, plus 13 graph events (graph start/end, node start/end, routing, interrupt, resume, parallel, stall, loop, supervisor replan). See `observer.py` for full reference.
 
 ### E2E Streaming & Parallel Execution
 
@@ -960,6 +1027,8 @@ See [docs/modules/STREAMING.md](https://github.com/johnnichev/selectools/blob/ma
 | **Anthropic** | Yes | Yes | Yes | Paid |
 | **Gemini** | Yes | Yes | Yes | Free tier |
 | **Ollama** | Yes | No | No | Free (local) |
+| **LiteLLM** | Yes | Yes | Yes | Varies (100+ models) |
+| **Router** | Yes | Yes | Yes | Varies (cost-routes tiers) |
 | **Fallback** | Yes | Yes | Yes | Varies (wraps others) |
 | **Local** | No | No | No | Free (testing) |
 
@@ -1114,7 +1183,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 |---|---|---|---|
 | 01 | `01_hello_world.py` | First agent, `@tool`, `ask()` | No |
 | 02 | `02_search_weather.py` | ToolRegistry, multiple tools | No |
-| 03 | `03_toolbox.py` | 24 pre-built tools (file, data, text, datetime, web) | No |
+| 03 | `03_toolbox.py` | 48 pre-built tools (file, data, text, datetime, web, code, search, and more) | No |
 | 04 | `04_conversation_memory.py` | Multi-turn memory | Yes |
 | 05 | `05_cost_tracking.py` | Token counting, cost warnings | Yes |
 | 06 | `06_async_agent.py` | `arun()`, concurrent agents, FastAPI | Yes |
@@ -1123,7 +1192,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 | 09 | `09_caching.py` | InMemoryCache, RedisCache, cache stats | Yes |
 | 10 | `10_routing_mode.py` | Routing mode, intent classification | Yes |
 | 11 | `11_tool_analytics.py` | Call counts, success rates, timing | Yes |
-| 12 | `12_observability_hooks.py` | Lifecycle hooks, tool validation | Yes |
+| 12 | `12_observability_hooks.py` | Lifecycle observers, tool validation | Yes |
 | 13 | `13_dynamic_tools.py` | ToolLoader, plugins, hot-reload | Yes |
 | 14 | `14_rag_basic.py` | RAG pipeline, document loading, vector search | Yes + `[rag]` |
 | 15 | `15_semantic_search.py` | Pure semantic search, metadata filtering | Yes + `[rag]` |
@@ -1238,7 +1307,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-5332 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.
+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.
 
 ## License
 

{selectools-0.23.0 → selectools-0.25.0}/README.md

@@ -30,6 +30,51 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.25
+
+### v0.25.0 — Hardening & v1.0 Prep
+
+Five new features plus the final v1.0 groundwork: the entire 433-symbol public surface is now stability-marked (205 stable, 228 beta) with a CI gate, the long-deprecated `AgentConfig.hooks` is removed, and the security audit is published.
+
+- **Planning-as-config** — `AgentConfig(planning=PlanningConfig(...))` adds plan→execute→synthesize to any agent via isolated clones, with a complexity gate, cross-clone budget caps, and a plan approval handler.
+- **Agent-level HITL** — `ToolConfig(require_approval=[...], approval_handler=...)` gates tool execution behind a sync or async approval callback (fail-closed, denials memoized per run).
+- **Tool result compression** — `ToolConfig(compress_results=True)` summarizes oversized tool results via a one-shot LLM call before they enter context, with raw-text retention for stop conditions and loop detection.
+- **Knowledge pre-save sanitization** — `pre_save` hook on `KnowledgeMemory` plus built-in sanitizers: `defang_delimiters` (prompt-injection markers), `strip_surrogates`, `dedupe_against`.
+- **Pending intent hooks** — `pop_if_intent` (structured confirm/cancel from chat buttons, bypasses the text parser) and `tighten_ttl` (id-pinned atomic Lua rewrite on Redis).
+- **Stability marking sweep** — 100% of the public surface marked; 19 beta→stable promotions (AgentGraph + orchestration core, all 5 pattern agents, checkpoint stores, `RedisSessionStore`, `AzureOpenAIProvider`, ...); module-level `__stability__` on all 123 public modules; CI gate enforces markers forever.
+- **Wart removal** — `Agent.clone_for_isolation()` is public (`@beta`); `__all__` reconciled (11 documented symbols now exported, incl. the Pipeline family and `RouterProvider`); **BREAKING**: `AgentConfig(hooks=...)` now raises `TypeError` (deprecated since v0.16) — migrate to `AgentObserver` via `docs/MIGRATION_1.0.md`.
+- **Security audit published** — `docs/SECURITY_AUDIT.md`: bandit clean at medium/high, all 73 `nosec` suppressions justified, pip-audit pass, SBOM regenerated.
+- **Protocol isinstance fix** — stability markers no longer break third-party `isinstance` checks against `Cache`/`KnowledgeStore`/`CheckpointStore` on Python 3.9–3.11.
+
+See `CHANGELOG.md` for the full entry (7,268 tests, 111 examples).
+
+## What's New in v0.24
+
+### v0.24.0 — Production Interop
+
+Twelve features focused on running agents in production and connecting them to everything else: serve agents as REST APIs, talk to other agents over A2A, reach 100+ models through LiteLLM, route by cost, and persist memory anywhere.
+
+- **Agent-as-API** — `selectools.serve.AgentAPI` turns any Agent (or list of agents) into a production Starlette ASGI app: `POST /v1/chat`, SSE streaming, session CRUD, bearer auth, per-user session isolation. CLI: `selectools serve agent.yaml --api --port 8000`.
+- **A2A protocol** — `A2AServer` + `A2AClient` for agent-to-agent communication: Agent Card discovery (`/.well-known/agent.json`) and JSON-RPC 2.0 `message/send`/`tasks/get`/`tasks/cancel`.
+- **LiteLLMProvider** — instant access to 100+ models (DeepSeek, Groq, Bedrock, ...) via `pip install selectools[litellm]`.
+- **RouterProvider** — cost-optimized routing across model tiers with a deterministic complexity classifier and failure escalation.
+- **Anthropic prompt caching** — opt-in `cache_system=True` / `cache_tools=True` with cache hit-rate fields on `UsageStats`.
+- **UnifiedMemory** — tiered memory orchestrating conversation, knowledge, entity, and the new episodic tier, with token-aware compaction and federated `recall()`.
+- **Cross-session search** — `store.search(query)` on all four SessionStore backends (FTS5-accelerated on SQLite).
+- **KnowledgeBackend** — Supabase/Redis blob persistence for `KnowledgeMemory` on ephemeral infrastructure (Railway, Lambda, Cloud Run).
+- **ToolResult + Artifact** — typed tool results with a `kind` discriminator, plus an `emit_artifact()` side-channel surfaced on `AgentResult.artifacts`.
+- **Deferred confirmation flow** — `selectools.pending` for chat-channel destructive tools where the user's "yes" arrives as a separate webhook turn.
+- **Toolbox expansion** — 15 new tools (33 → 48): safe calculator, email, PDF extraction, Slack, Notion, Linear.
+- **Gemini schema sanitization** — bare `list` and `Dict[K, V]` tool parameters no longer 400 on the Gemini API; loud warnings for flash-lite's silent-empty-response failure mode.
+
+```python
+from selectools.serve import AgentAPI
+
+api = AgentAPI(agent, auth_key="secret")  # ASGI app: uvicorn main:api
+```
+
+See `CHANGELOG.md` for the full entry (6,187 tests, 111 examples).
+
 ## What's New in v0.23
 
 ### v0.23.0 — Supabase Sessions + Builder RAG
@@ -499,7 +544,15 @@ report.to_html("report.html")
 | **Audit Logging** | JSONL audit trail with privacy controls (redact, hash, omit) and daily rotation. |
 | **Tool Output Screening** | Prompt injection detection with 15 built-in patterns. Per-tool or global. |
 | **Coherence Checking** | LLM-based verification that tool calls match user intent — catches injection-driven tool misuse. |
-| **Persistent Sessions** | `SessionStore` with JSON file, SQLite, and Redis backends. Auto-save/load with TTL expiry. |
+| **Persistent Sessions** | `SessionStore` with JSON file, SQLite, Redis, and Supabase backends. Auto-save/load with TTL expiry, cross-session `search()`. |
+| **Agent-as-API** | `AgentAPI` serves any agent as a Starlette REST API — chat, SSE streaming, session CRUD, bearer auth, per-user session isolation. |
+| **A2A Protocol** | `A2AServer` + `A2AClient`: Agent Card discovery and JSON-RPC 2.0 messaging between agents. |
+| **LiteLLM Bridge** | `LiteLLMProvider` unlocks 100+ models (DeepSeek, Groq, Bedrock, ...) through one provider class. |
+| **Cost-Based Routing** | `RouterProvider` classifies request complexity and routes to model tiers with automatic failure escalation. |
+| **Unified Memory** | `UnifiedMemory` orchestrates conversation, knowledge, entity, and episodic tiers with token-aware compaction and federated `recall()`. |
+| **Typed Tool Results** | `ToolResult` base with `kind` discriminator; `emit_artifact()` side-channel surfaces files/URLs on `AgentResult.artifacts`. |
+| **Deferred Confirmation** | `selectools.pending` — confirm destructive chat-channel tools across webhook turns with TTL, scope, and args-digest matching. |
+| **Prompt Caching** | Anthropic `cache_system`/`cache_tools` markers with cache hit-rate fields on `UsageStats`. |
 | **Entity Memory** | LLM-based entity extraction with deduplication, LRU pruning, and system prompt injection. |
 | **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. |
@@ -507,14 +560,16 @@ report.to_html("report.html")
 | **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`. |
+| **AgentObserver Protocol** | 46-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` + `SimpleStepObserver`. |
 | **Runtime Controls** | Token/cost budget limits, cooperative cancellation, per-tool approval gates, model switching per iteration. |
 | **Production Hardened** | Retries with backoff, per-tool timeouts, iteration caps, cost warnings, observability hooks + observers. |
 | **Library-First** | Not a framework. No magic globals, no hidden state. Use as much or as little as you need. |
 
 ## What's Included
 
-- **5 LLM Providers**: OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama + FallbackProvider (auto-failover)
+- **6 LLM Providers**: OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama, LiteLLM (100+ models) + FallbackProvider (auto-failover) + RouterProvider (cost-based routing)
+- **Agent-as-API**: `AgentAPI` — production REST endpoints (chat, SSE streaming, sessions) from any agent
+- **A2A Protocol**: Agent Card discovery + JSON-RPC 2.0 agent-to-agent messaging
 - **Structured Output**: Pydantic / JSON Schema `response_format` with auto-retry
 - **Execution Traces**: `result.trace` with typed timeline of every agent step
 - **Reasoning Visibility**: `result.reasoning` explains *why* the agent chose a tool
@@ -527,9 +582,14 @@ report.to_html("report.html")
 - **Dynamic Tool Loading**: Plugin system with hot-reload support
 - **Response Caching**: InMemoryCache and RedisCache with stats tracking
 - **152 Model Registry**: Type-safe constants with pricing and metadata
-- **Pre-built Toolbox**: 24 tools for files, data, text, datetime, web
-- **Persistent Sessions**: 3 backends (JSON file, SQLite, Redis) with TTL
+- **Pre-built Toolbox**: 48 tools for files, data, text, datetime, web, code, search, GitHub, DB, calculator, email, PDF, Slack, Notion, Linear
+- **Persistent Sessions**: 4 backends (JSON file, SQLite, Redis, Supabase) with TTL and cross-session search
 - **Entity Memory**: LLM-based named entity extraction and tracking
+- **Unified Memory**: tiered conversation/knowledge/entity/episodic memory with token-aware compaction
+- **Knowledge Backends**: Supabase/Redis blob persistence for KnowledgeMemory on ephemeral infra
+- **Typed Tool Results**: `ToolResult` base class + `Artifact` side-channel via `emit_artifact()`
+- **Deferred Confirmation**: `selectools.pending` for chat-channel destructive-tool confirmation
+- **Anthropic Prompt Caching**: `cache_system`/`cache_tools` with hit-rate visibility on `UsageStats`
 - **Knowledge Graph**: Triple extraction with in-memory and SQLite storage
 - **Cross-Session Knowledge**: Daily logs + persistent memory with `remember` tool, pluggable stores (File, SQLite), importance scoring, TTL
 - **Token Budget & Cancellation**: `max_total_tokens`, `max_cost_usd` hard limits; `CancellationToken` for cooperative stopping
@@ -540,10 +600,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
-- **96 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, and more
+- **111 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, 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
-- **5332 Tests**: Unit, integration, regression, and E2E with real API calls
+- **AgentObserver Protocol**: 46 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
+- **7268 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -869,7 +929,7 @@ agent = Agent(
 )
 ```
 
-45 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG, budget exceeded, cancelled, prompt compressed, plus 13 graph events (graph start/end, node start/end, routing, interrupt, resume, parallel, stall, loop, supervisor replan). See `observer.py` for full reference.
+46 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG, budget exceeded, cancelled, prompt compressed, plus 13 graph events (graph start/end, node start/end, routing, interrupt, resume, parallel, stall, loop, supervisor replan). See `observer.py` for full reference.
 
 ### E2E Streaming & Parallel Execution
 
@@ -889,6 +949,8 @@ See [docs/modules/STREAMING.md](https://github.com/johnnichev/selectools/blob/ma
 | **Anthropic** | Yes | Yes | Yes | Paid |
 | **Gemini** | Yes | Yes | Yes | Free tier |
 | **Ollama** | Yes | No | No | Free (local) |
+| **LiteLLM** | Yes | Yes | Yes | Varies (100+ models) |
+| **Router** | Yes | Yes | Yes | Varies (cost-routes tiers) |
 | **Fallback** | Yes | Yes | Yes | Varies (wraps others) |
 | **Local** | No | No | No | Free (testing) |
 
@@ -1043,7 +1105,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 |---|---|---|---|
 | 01 | `01_hello_world.py` | First agent, `@tool`, `ask()` | No |
 | 02 | `02_search_weather.py` | ToolRegistry, multiple tools | No |
-| 03 | `03_toolbox.py` | 24 pre-built tools (file, data, text, datetime, web) | No |
+| 03 | `03_toolbox.py` | 48 pre-built tools (file, data, text, datetime, web, code, search, and more) | No |
 | 04 | `04_conversation_memory.py` | Multi-turn memory | Yes |
 | 05 | `05_cost_tracking.py` | Token counting, cost warnings | Yes |
 | 06 | `06_async_agent.py` | `arun()`, concurrent agents, FastAPI | Yes |
@@ -1052,7 +1114,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 | 09 | `09_caching.py` | InMemoryCache, RedisCache, cache stats | Yes |
 | 10 | `10_routing_mode.py` | Routing mode, intent classification | Yes |
 | 11 | `11_tool_analytics.py` | Call counts, success rates, timing | Yes |
-| 12 | `12_observability_hooks.py` | Lifecycle hooks, tool validation | Yes |
+| 12 | `12_observability_hooks.py` | Lifecycle observers, tool validation | Yes |
 | 13 | `13_dynamic_tools.py` | ToolLoader, plugins, hot-reload | Yes |
 | 14 | `14_rag_basic.py` | RAG pipeline, document loading, vector search | Yes + `[rag]` |
 | 15 | `15_semantic_search.py` | Pure semantic search, metadata filtering | Yes + `[rag]` |
@@ -1167,7 +1229,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-5332 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.
+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.
 
 ## License
 

{selectools-0.23.0 → selectools-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.23.0"
+version = "0.25.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"
@@ -75,12 +75,20 @@ observe = [
     "opentelemetry-api>=1.20.0",
     "langfuse>=2.0.0",
 ]
+toolbox = [
+    "requests>=2.28.0",
+    "slack-sdk>=3.27.0",
+    "pdfplumber>=0.11.0",
+]
 evals = [
     "pyyaml>=6.0.0",
 ]
 mcp = [
     "mcp>=1.0.0,<2.0.0",
 ]
+litellm = [
+    "litellm>=1.0.0",
+]
 postgres = [
     "psycopg2-binary>=2.9.0",
 ]
@@ -91,6 +99,7 @@ serve = [
     "pyyaml>=6.0.0",
     "starlette>=0.27.0",
     "uvicorn[standard]>=0.24.0",
+    "httpx>=0.24.0",
 ]
 
 [project.scripts]

{selectools-0.23.0 → selectools-0.25.0}/src/selectools/__init__.py

@@ -1,10 +1,10 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.23.0"
+__version__ = "0.25.0"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, evals, guardrails, models, observe, patterns, rag, toolbox
-from .agent import Agent, AgentConfig
+from .agent import Agent, AgentConfig, PlanningConfig
 from .agent.config_groups import (
     BudgetConfig,
     CoherenceConfig,
@@ -50,11 +50,17 @@ from .guardrails import (
 )
 from .knowledge import (
     FileKnowledgeStore,
+    KnowledgeBackend,
     KnowledgeEntry,
     KnowledgeMemory,
     KnowledgeStore,
+    PreSaveHook,
     SQLiteKnowledgeStore,
 )
+from .knowledge_backends import (
+    RedisKnowledgeBackend,
+    SupabaseKnowledgeBackend,
+)
 from .knowledge_graph import (
     InMemoryTripleStore,
     KnowledgeGraphMemory,
@@ -62,6 +68,11 @@ from .knowledge_graph import (
     Triple,
     TripleStore,
 )
+from .knowledge_sanitizers import (
+    dedupe_against,
+    defang_delimiters,
+    strip_surrogates,
+)
 from .loop_detection import (
     BaseDetector,
     LoopDetectedError,
@@ -122,21 +133,39 @@ from .patterns import (
     TeamLeadAgent,
     TeamLeadResult,
 )
+from .pending import (
+    ChannelAgent,
+    ConfirmOutcome,
+    ConfirmParser,
+    InMemoryPendingStore,
+    PendingAction,
+    PendingActionExistsError,
+    PendingActionStore,
+    PendingConfirmation,
+    RedisPendingStore,
+    RegexConfirmParser,
+    compute_args_digest,
+    stash_pending,
+)
 from .pipeline import Pipeline, Step, StepResult, branch, cache_step, parallel, retry, step
-from .policy import PolicyDecision, PolicyResult, ToolPolicy
+from .policy import ApprovalRequest, PolicyDecision, PolicyResult, ToolPolicy
 from .pricing import PRICING, calculate_cost, calculate_embedding_cost, get_model_pricing
 from .prompt import REASONING_STRATEGIES, PromptBuilder
 from .providers.anthropic_provider import AnthropicProvider
 from .providers.azure_openai_provider import AzureOpenAIProvider
 from .providers.fallback import FallbackProvider
 from .providers.gemini_provider import GeminiProvider
+from .providers.litellm_provider import LiteLLMProvider
 from .providers.ollama_provider import OllamaProvider
 from .providers.openai_provider import OpenAIProvider
+from .providers.router import RouterConfig, RouterProvider
 from .providers.stubs import LocalProvider
+from .results import Ambiguous, Artifact, NotFound, ToolResult, emit_artifact
 from .sessions import (
     JsonFileSessionStore,
     RedisSessionStore,
     SessionMetadata,
+    SessionSearchResult,
     SessionStore,
     SQLiteSessionStore,
     SupabaseSessionStore,
@@ -147,11 +176,22 @@ from .token_estimation import TokenEstimate, estimate_run_tokens, estimate_token
 from .tools import Tool, ToolParameter, ToolRegistry, tool
 from .trace import AgentTrace, StepType, TraceStep, trace_to_html, trace_to_json
 from .types import AgentResult, ContentPart, Message, Role, ToolCall, image_message, text_content
+from .unified_memory import (
+    DEFAULT_IMPORTANCE_RULES,
+    Episode,
+    EpisodicMemory,
+    ImportanceRule,
+    InMemoryKnowledgeStore,
+    RecallResult,
+    UnifiedMemory,
+    score_importance,
+)
 from .usage import AgentUsage, UsageStats
 
 __all__ = [
     "Agent",
     "AgentConfig",
+    "PlanningConfig",
     "AgentResult",
     "AgentAnalytics",
     "ToolMetrics",
@@ -172,10 +212,23 @@ __all__ = [
     "AnthropicProvider",
     "GeminiProvider",
     "OllamaProvider",
+    "LiteLLMProvider",
+    "RouterProvider",
+    "RouterConfig",
     "LocalProvider",
     "FallbackProvider",
     "ToolRegistry",
     "tool",
+    # Pipeline composition (public since 0.19.3, @beta)
+    "Pipeline",
+    "Step",
+    "StepResult",
+    "compose",
+    "step",
+    "parallel",
+    "branch",
+    "retry",
+    "cache_step",
     # Cancellation
     "CancellationToken",
     # Exceptions
@@ -214,10 +267,30 @@ __all__ = [
     "SemanticCache",
     # Tool policy
     "ToolPolicy",
+    "ApprovalRequest",
     "PolicyDecision",
     "PolicyResult",
     # Structured output
     "ResponseFormat",
+    # Typed tool results + artifact side-channel (issue #59)
+    "ToolResult",
+    "Ambiguous",
+    "NotFound",
+    "Artifact",
+    "emit_artifact",
+    # Deferred confirmation flow (issue #58)
+    "PendingAction",
+    "PendingActionStore",
+    "PendingActionExistsError",
+    "InMemoryPendingStore",
+    "RedisPendingStore",
+    "ConfirmOutcome",
+    "ConfirmParser",
+    "RegexConfirmParser",
+    "PendingConfirmation",
+    "ChannelAgent",
+    "stash_pending",
+    "compute_args_digest",
     # Stability markers
     "stable",
     "beta",
@@ -261,6 +334,7 @@ __all__ = [
     # Sessions
     "SessionStore",
     "SessionMetadata",
+    "SessionSearchResult",
     "JsonFileSessionStore",
     "SQLiteSessionStore",
     "RedisSessionStore",
@@ -277,6 +351,15 @@ __all__ = [
     # Knowledge stores (optional deps: redis, supabase)
     # from selectools.knowledge_store_redis import RedisKnowledgeStore
     # from selectools.knowledge_store_supabase import SupabaseKnowledgeStore
+    # Knowledge backends (blob persistence between deploys; lazy optional deps)
+    "KnowledgeBackend",
+    "SupabaseKnowledgeBackend",
+    "RedisKnowledgeBackend",
+    # Knowledge pre-save sanitizers (beta)
+    "PreSaveHook",
+    "defang_delimiters",
+    "strip_surrogates",
+    "dedupe_against",
     # Token estimation
     "TokenEstimate",
     "estimate_tokens",
@@ -287,6 +370,15 @@ __all__ = [
     "InMemoryTripleStore",
     "SQLiteTripleStore",
     "KnowledgeGraphMemory",
+    # Unified Memory (tiered memory with auto-promotion)
+    "UnifiedMemory",
+    "EpisodicMemory",
+    "Episode",
+    "ImportanceRule",
+    "InMemoryKnowledgeStore",
+    "RecallResult",
+    "DEFAULT_IMPORTANCE_RULES",
+    "score_importance",
     # Submodules (for lazy loading)
     "embeddings",
     "observe",

selectools-0.25.0/src/selectools/_json_utils.py

@@ -0,0 +1,37 @@
+"""Internal JSON helpers shared across modules.
+
+Home for JSON-parsing utilities that multiple subsystems need (orchestration
+supervisor, team-lead and plan-and-execute patterns). Internal — not part of
+the public API.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_JSON_BLOCK_RE = re.compile(r"(\[.*\]|\{.*\})", re.DOTALL)
+
+
+def safe_json_parse(text: str, default: Any = None) -> Any:
+    """Try to extract and parse JSON from an LLM response.
+
+    Strips markdown code fences, then attempts a direct parse; falls back to
+    extracting the first JSON array or object embedded in surrounding prose.
+    Returns *default* when nothing parses.
+    """
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        text = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        m = _JSON_BLOCK_RE.search(text)
+        if m:
+            try:
+                return json.loads(m.group(1))
+            except json.JSONDecodeError:
+                pass
+    return default