selectools 0.22.0__tar.gz → 0.24.0__tar.gz

{selectools-0.22.0/src/selectools.egg-info → selectools-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.22.0
+Version: 0.24.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,16 +55,25 @@ 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
+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: uvicorn[standard]>=0.24.0; extra == "serve"
+Requires-Dist: httpx>=0.24.0; extra == "serve"
 Dynamic: license-file
 
 ```
@@ -99,6 +108,56 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## 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 (5,968 tests, 106 examples).
+
+## What's New in v0.23
+
+### v0.23.0 — Supabase Sessions + Builder RAG
+
+Two user-facing features plus a post-ship bug-hunt sweep that pinned 8 code-generator fixes in the visual builder.
+
+- **`SupabaseSessionStore`** — 4th `SessionStore` backend alongside JSON, SQLite, and Redis. Postgres-backed via Supabase PostgREST, with idempotent upserts, namespace isolation, and the same validation guards as `RedisSessionStore`. Optional dep: `pip install selectools[supabase]`. Demo: [`examples/96_supabase_session_store.py`](https://github.com/johnnichev/selectools/blob/main/examples/96_supabase_session_store.py).
+
+- **Visual builder: first-class RAG + session nodes** — drag `Retriever (RAG)` onto the canvas and pick any of 7 vector stores (memory, SQLite, Chroma, Pinecone, FAISS, Qdrant, pgvector), toggle Hybrid (BM25 + vector + RRF) and cross-encoder Rerank. Drag `Session Store` as a resource node and wire it into an agent via the new Session Store dropdown. Two new presets: **Hybrid RAG** and **Multi-Tenant RAG**. Python + YAML code generators emit real, runnable code.
+
+```python
+from supabase import create_client
+from selectools import SupabaseSessionStore, Agent, AgentConfig
+
+store = SupabaseSessionStore(client=create_client(URL, KEY))
+agent = Agent(
+    tools=[...],
+    config=AgentConfig(session_store=store, session_id="u-1", max_iterations=5),
+)
+```
+
+See `CHANGELOG.md` for the full entry including the 8 builder code-gen fixes.
+
 ## What's New in v0.22
 
 ### v0.22.0 — Competitor-Informed Bug Fixes
@@ -176,7 +235,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-94_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-96_scripts-06b6d4)](https://selectools.dev/examples/)
 
 ```bash
 pip install selectools
@@ -233,7 +292,7 @@ Path("trace.html").write_text(trace_to_html(result.trace))
 - **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 (5343 tests total)
+- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (5332 tests total)
 
 ### v0.19.1 — Advanced Agent Patterns
 
@@ -545,7 +604,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. |
@@ -560,7 +627,9 @@ report.to_html("report.html")
 
 ## 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
@@ -573,9 +642,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
@@ -586,10 +660,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
-- **76 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
+- **106 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
-- **5343 Tests**: Unit, integration, regression, and E2E with real API calls
+- **5968 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -935,6 +1009,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) |
 
@@ -1213,7 +1289,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-5343 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.
+5968 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.22.0 → selectools-0.24.0}/README.md

@@ -30,6 +30,56 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## 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 (5,968 tests, 106 examples).
+
+## What's New in v0.23
+
+### v0.23.0 — Supabase Sessions + Builder RAG
+
+Two user-facing features plus a post-ship bug-hunt sweep that pinned 8 code-generator fixes in the visual builder.
+
+- **`SupabaseSessionStore`** — 4th `SessionStore` backend alongside JSON, SQLite, and Redis. Postgres-backed via Supabase PostgREST, with idempotent upserts, namespace isolation, and the same validation guards as `RedisSessionStore`. Optional dep: `pip install selectools[supabase]`. Demo: [`examples/96_supabase_session_store.py`](https://github.com/johnnichev/selectools/blob/main/examples/96_supabase_session_store.py).
+
+- **Visual builder: first-class RAG + session nodes** — drag `Retriever (RAG)` onto the canvas and pick any of 7 vector stores (memory, SQLite, Chroma, Pinecone, FAISS, Qdrant, pgvector), toggle Hybrid (BM25 + vector + RRF) and cross-encoder Rerank. Drag `Session Store` as a resource node and wire it into an agent via the new Session Store dropdown. Two new presets: **Hybrid RAG** and **Multi-Tenant RAG**. Python + YAML code generators emit real, runnable code.
+
+```python
+from supabase import create_client
+from selectools import SupabaseSessionStore, Agent, AgentConfig
+
+store = SupabaseSessionStore(client=create_client(URL, KEY))
+agent = Agent(
+    tools=[...],
+    config=AgentConfig(session_store=store, session_id="u-1", max_iterations=5),
+)
+```
+
+See `CHANGELOG.md` for the full entry including the 8 builder code-gen fixes.
+
 ## What's New in v0.22
 
 ### v0.22.0 — Competitor-Informed Bug Fixes
@@ -107,7 +157,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-94_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-96_scripts-06b6d4)](https://selectools.dev/examples/)
 
 ```bash
 pip install selectools
@@ -164,7 +214,7 @@ Path("trace.html").write_text(trace_to_html(result.trace))
 - **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 (5343 tests total)
+- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (5332 tests total)
 
 ### v0.19.1 — Advanced Agent Patterns
 
@@ -476,7 +526,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. |
@@ -491,7 +549,9 @@ report.to_html("report.html")
 
 ## 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
@@ -504,9 +564,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
@@ -517,10 +582,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
-- **76 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
+- **106 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
-- **5343 Tests**: Unit, integration, regression, and E2E with real API calls
+- **5968 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -866,6 +931,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) |
 
@@ -1144,7 +1211,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-5343 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.
+5968 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.22.0 → selectools-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.22.0"
+version = "0.24.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,19 +75,31 @@ 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",
 ]
+supabase = [
+    "supabase>=2.0.0",
+]
 serve = [
     "pyyaml>=6.0.0",
     "starlette>=0.27.0",
     "uvicorn[standard]>=0.24.0",
+    "httpx>=0.24.0",
 ]
 
 [project.scripts]

{selectools-0.22.0 → selectools-0.24.0}/src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.22.0"
+__version__ = "0.24.0"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, evals, guardrails, models, observe, patterns, rag, toolbox
@@ -50,11 +50,16 @@ from .guardrails import (
 )
 from .knowledge import (
     FileKnowledgeStore,
+    KnowledgeBackend,
     KnowledgeEntry,
     KnowledgeMemory,
     KnowledgeStore,
     SQLiteKnowledgeStore,
 )
+from .knowledge_backends import (
+    RedisKnowledgeBackend,
+    SupabaseKnowledgeBackend,
+)
 from .knowledge_graph import (
     InMemoryTripleStore,
     KnowledgeGraphMemory,
@@ -122,6 +127,20 @@ 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 .pricing import PRICING, calculate_cost, calculate_embedding_cost, get_model_pricing
@@ -130,15 +149,19 @@ 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.stubs import LocalProvider
+from .results import Ambiguous, Artifact, NotFound, ToolResult, emit_artifact
 from .sessions import (
     JsonFileSessionStore,
     RedisSessionStore,
     SessionMetadata,
+    SessionSearchResult,
     SessionStore,
     SQLiteSessionStore,
+    SupabaseSessionStore,
 )
 from .stability import beta, deprecated, stable
 from .structured import ResponseFormat
@@ -146,6 +169,16 @@ 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__ = [
@@ -171,6 +204,7 @@ __all__ = [
     "AnthropicProvider",
     "GeminiProvider",
     "OllamaProvider",
+    "LiteLLMProvider",
     "LocalProvider",
     "FallbackProvider",
     "ToolRegistry",
@@ -217,6 +251,25 @@ __all__ = [
     "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",
@@ -260,9 +313,11 @@ __all__ = [
     # Sessions
     "SessionStore",
     "SessionMetadata",
+    "SessionSearchResult",
     "JsonFileSessionStore",
     "SQLiteSessionStore",
     "RedisSessionStore",
+    "SupabaseSessionStore",
     # Entity Memory
     "Entity",
     "EntityMemory",
@@ -275,6 +330,10 @@ __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",
     # Token estimation
     "TokenEstimate",
     "estimate_tokens",
@@ -285,6 +344,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.24.0/src/selectools/a2a/__init__.py

@@ -0,0 +1,54 @@
+"""
+A2A protocol — agent-to-agent communication (Google-backed standard).
+
+Serving::
+
+    from selectools.serve import A2AServer   # or selectools.a2a
+
+    server = A2AServer(agent=my_agent, auth_token="sk-...")
+    server.serve(port=8000)
+
+Consuming::
+
+    from selectools.a2a import A2AClient
+
+    client = A2AClient("https://other-agent.example.com")
+    card = await client.discover()       # reads /.well-known/agent.json
+    result = await client.send_task("Research quantum computing trends")
+
+The server requires ``starlette`` and the client requires ``httpx``
+(both ship with ``pip install selectools[serve]``); imports are lazy so
+this package loads without them.
+"""
+
+from typing import Any
+
+from .types import A2AError, A2ATask, AgentCard, AgentSkill, TaskState
+
+__all__ = [
+    "A2AClient",
+    "A2AError",
+    "A2AServer",
+    "A2ATask",
+    "AgentCard",
+    "AgentSkill",
+    "TaskState",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import the server (starlette) and client (httpx)."""
+    if name == "A2AServer":
+        try:
+            from .server import A2AServer
+        except ImportError as exc:
+            raise ImportError(
+                "A2AServer requires the 'starlette' package. "
+                "Install it with: pip install selectools[serve]"
+            ) from exc
+        return A2AServer
+    if name == "A2AClient":
+        from .client import A2AClient
+
+        return A2AClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")