selectools 0.23.0__tar.gz → 0.24.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.23.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,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,33 @@ 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
@@ -570,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. |
@@ -585,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
@@ -598,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
@@ -611,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
-- **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
+- **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
-- **5332 Tests**: Unit, integration, regression, and E2E with real API calls
+- **5968 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -960,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) |
 
@@ -1238,7 +1289,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.
+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.23.0 → selectools-0.24.0}/README.md

@@ -30,6 +30,33 @@ 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
@@ -499,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. |
@@ -514,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
@@ -527,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
@@ -540,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
-- **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
+- **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
-- **5332 Tests**: Unit, integration, regression, and E2E with real API calls
+- **5968 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -889,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) |
 
@@ -1167,7 +1211,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.
+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.23.0 → selectools-0.24.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.23.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,13 +149,16 @@ 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,
@@ -147,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__ = [
@@ -172,6 +204,7 @@ __all__ = [
     "AnthropicProvider",
     "GeminiProvider",
     "OllamaProvider",
+    "LiteLLMProvider",
     "LocalProvider",
     "FallbackProvider",
     "ToolRegistry",
@@ -218,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",
@@ -261,6 +313,7 @@ __all__ = [
     # Sessions
     "SessionStore",
     "SessionMetadata",
+    "SessionSearchResult",
     "JsonFileSessionStore",
     "SQLiteSessionStore",
     "RedisSessionStore",
@@ -277,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",
@@ -287,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}")

selectools-0.24.0/src/selectools/a2a/client.py

@@ -0,0 +1,174 @@
+"""
+A2A client — discover and talk to remote A2A agents.
+
+Usage::
+
+    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")
+    print(result.text)
+
+    # Sync code can use the *_sync wrappers:
+    card = client.discover_sync()
+
+Requires ``httpx`` (ships with ``pip install selectools[serve]``); the
+import is lazy so this module loads without it.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, List, Optional
+
+from .._async_utils import run_sync
+from ..stability import beta
+from .types import A2AError, A2ATask, AgentCard
+
+__all__ = ["A2AClient"]
+
+
+def _httpx() -> Any:
+    try:
+        import httpx
+    except ImportError as exc:
+        raise ImportError(
+            "A2AClient requires the 'httpx' package. Install it with: pip install selectools[serve]"
+        ) from exc
+    return httpx
+
+
+@beta
+class A2AClient:
+    """Client for a remote A2A agent (Agent Card discovery + task sending).
+
+    Args:
+        base_url: Root URL of the remote agent, e.g.
+            ``"https://other-agent.example.com"``. The Agent Card is read
+            from ``{base_url}/.well-known/agent.json`` and tasks are posted
+            to ``{base_url}/a2a``.
+        auth_token: Optional bearer token sent as
+            ``Authorization: Bearer <auth_token>`` on every request.
+        timeout: Request timeout in seconds (default 30).
+        transport: Optional ``httpx`` transport — pass
+            ``httpx.ASGITransport(app=server)`` to talk to an in-process
+            :class:`~selectools.a2a.server.A2AServer` without a socket.
+
+    Raises:
+        A2AError: On transport failures (non-2xx responses) and JSON-RPC
+            protocol errors. Agent failures are NOT raised — they come back
+            as an :class:`A2ATask` with ``state == TaskState.FAILED``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_token: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[Any] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._auth_token = auth_token
+        self._timeout = timeout
+        self._transport = transport
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self._auth_token:
+            headers["Authorization"] = f"Bearer {self._auth_token}"
+        return headers
+
+    def _async_client(self) -> Any:
+        httpx = _httpx()
+        kwargs: Dict[str, Any] = {"timeout": self._timeout}
+        if self._transport is not None:
+            kwargs["transport"] = self._transport
+        return httpx.AsyncClient(**kwargs)
+
+    @staticmethod
+    def _check_http(response: Any) -> None:
+        if response.status_code >= 400:
+            raise A2AError(f"HTTP {response.status_code} from A2A server: {response.text[:500]}")
+
+    # ── discovery ────────────────────────────────────────────────────────────
+
+    async def discover(self) -> AgentCard:
+        """Fetch and parse the remote Agent Card from /.well-known/agent.json."""
+        async with self._async_client() as client:
+            response = await client.get(
+                f"{self._base_url}/.well-known/agent.json", headers=self._headers()
+            )
+        self._check_http(response)
+        return AgentCard.from_dict(response.json())
+
+    def discover_sync(self) -> AgentCard:
+        """Synchronous wrapper around :meth:`discover`."""
+        return run_sync(self.discover())
+
+    # ── tasks ────────────────────────────────────────────────────────────────
+
+    async def _call(self, method: str, params: Dict[str, Any]) -> Any:
+        """Issue one JSON-RPC call against POST /a2a and return its result."""
+        payload = {
+            "jsonrpc": "2.0",
+            "id": uuid.uuid4().hex,
+            "method": method,
+            "params": params,
+        }
+        async with self._async_client() as client:
+            response = await client.post(
+                f"{self._base_url}/a2a", json=payload, headers=self._headers()
+            )
+        self._check_http(response)
+        body = response.json()
+        if "error" in body:
+            error = body["error"] or {}
+            raise A2AError(
+                str(error.get("message", "Unknown A2A error")),
+                code=error.get("code"),
+                data=error.get("data"),
+            )
+        return body.get("result")
+
+    async def send_task(
+        self,
+        text: str,
+        context_id: Optional[str] = None,
+        extra_parts: Optional[List[Dict[str, Any]]] = None,
+    ) -> A2ATask:
+        """Send a text task via ``message/send`` and return the final task.
+
+        Args:
+            text: The task prompt (becomes a part of kind ``"text"``).
+            context_id: Optional conversation context id to group tasks.
+            extra_parts: Optional additional A2A parts (``file``/``data``)
+                appended after the text part. The v1 server is text-first.
+        """
+        parts: List[Dict[str, Any]] = [{"kind": "text", "text": text}]
+        if extra_parts:
+            parts.extend(extra_parts)
+        message: Dict[str, Any] = {
+            "role": "user",
+            "parts": parts,
+            "messageId": uuid.uuid4().hex,
+            "kind": "message",
+        }
+        if context_id:
+            message["contextId"] = context_id
+        result = await self._call("message/send", {"message": message})
+        return A2ATask.from_dict(result or {})
+
+    def send_task_sync(
+        self,
+        text: str,
+        context_id: Optional[str] = None,
+        extra_parts: Optional[List[Dict[str, Any]]] = None,
+    ) -> A2ATask:
+        """Synchronous wrapper around :meth:`send_task`."""
+        return run_sync(self.send_task(text, context_id=context_id, extra_parts=extra_parts))
+
+    async def get_task(self, task_id: str) -> A2ATask:
+        """Fetch a previously created task via ``tasks/get``."""
+        result = await self._call("tasks/get", {"id": task_id})
+        return A2ATask.from_dict(result or {})