Selectools Implementation Documentation

June 13, 2026 · View on GitHub

Version: 0.16.6 Last Updated: March 2026

Welcome to the comprehensive technical documentation for selectools - a production-ready Python framework for building AI agents with tool-calling capabilities and RAG support.

📚 Documentation Structure

Getting Started

  • QUICKSTART.md - Start here. Build your first agent in 5 minutes, no API key needed.

Main Documentation

  • ARCHITECTURE.md - Complete system overview, architecture diagrams, data flows, and design principles.

Reference

  • KEYS.md - Environment variables and API keys for all providers
  • RELEASE_GUIDE.md - PyPI release process and checklist

Module Documentation

Detailed technical documentation for each module:

  1. AGENT.md - Agent loop, structured output, traces, reasoning, batch, policy, observer, caching
  2. STREAMING.md - E2E streaming, parallel execution, routing mode, AgentResult, context propagation
  3. TOOLS.md - Tool definition, validation, registry, and streaming
  4. DYNAMIC_TOOLS.md - ToolLoader, dynamic tool loading, hot-reload, plugin systems
  5. PARSER.md - TOOL_CALL contract and JSON extraction strategies
  6. PROMPT.md - System prompt generation and tool schema formatting
  7. PROVIDERS.md - LLM provider adapters, message formatting, and FallbackProvider
  8. MEMORY.md - Conversation memory, sliding windows, and tool-pair-aware trimming
  9. USAGE.md - Usage tracking, cost calculation, and analytics
  10. RAG.md - Complete RAG pipeline from documents to answers
  11. HYBRID_SEARCH.md - BM25, hybrid search, fusion methods, and reranking
  12. ADVANCED_CHUNKING.md - Semantic and contextual document chunking
  13. EMBEDDINGS.md - Embedding providers and semantic search
  14. VECTOR_STORES.md - Vector database implementations
  15. MODELS.md - 115 models across 5 providers with June 2026 pricing
  16. GUARDRAILS.md - Input/output validation pipeline, PII redaction, topic blocking
  17. AUDIT.md - JSONL audit logging with privacy controls
  18. SECURITY.md - Tool output screening and coherence checking
  19. TOOLBOX.md - 56 pre-built tools across 19 categories (file, web, data, datetime, text, code, search, and more)
  20. EXCEPTIONS.md - Error hierarchy, exception attributes, catch patterns
  21. SESSIONS.md - Persistent session storage with 4 backends
  22. ENTITY_MEMORY.md - Named entity extraction and tracking
  23. KNOWLEDGE_GRAPH.md - Relationship triple extraction and graph memory
  24. KNOWLEDGE.md - Cross-session knowledge with daily logs and persistent facts

🎯 Quick Navigation

By Role

For Developers:

For Contributors:

For DevOps/Production:

By Feature

Tool Calling:

RAG System:

Security & Compliance:

Memory & Persistence:

Streaming & Performance:

  • STREAMING.md - E2E streaming, parallel execution, routing mode

Cost Management & Caching:

📊 Documentation Stats

  • Total files: 25 (1 main + 24 modules)
  • ASCII diagrams: 30+ diagrams
  • Code examples: 250+ examples

🔍 Understanding the Flow

Standard Tool-Calling Flow

1. User Query
   ↓
2. INPUT GUARDRAILS validate/redact user message (PII, topic, toxicity)
   ↓
3. AGENT loads history (MEMORY) and calls PROVIDER (or FALLBACK chain)
   ↓
4. CACHE checked (if configured) → hit? Return cached response
   ↓
5. PROVIDER formats prompt (PROMPT + STRUCTURED schema) and calls LLM → CACHE stores result
   ↓
6. OUTPUT GUARDRAILS validate LLM response (format, length, toxicity)
   ↓
7. PARSER extracts TOOL_CALL from response; REASONING extracted
   ↓
8. POLICY ENGINE evaluates tool call → allow/review/deny
   ↓
8b. If review: HUMAN-IN-THE-LOOP callback → approve/reject
   ↓
9. COHERENCE CHECK verifies tool call matches user intent
   ↓
10. TOOLS validates and executes (parallel if multiple)
   ↓
11. OUTPUT SCREENING checks tool results for prompt injection
   ↓
12. TRACE records each step; AUDIT LOGGER writes JSONL; USAGE tracks costs
   ↓
13. If response_format: STRUCTURED validates → retry on failure
   ↓
14. Loop continues or returns AgentResult (with .parsed, .trace, .reasoning)

Read:

  1. AGENT.md - Main loop
  2. PROVIDERS.md - LLM communication
  3. PARSER.md - Response parsing
  4. TOOLS.md - Tool execution

RAG Flow

1. Documents
   ↓
2. LOADERS read files/PDFs
   ↓
3. CHUNKING splits into pieces
   (TextSplitter → Recursive → Semantic → Contextual)
   ↓
4. EMBEDDINGS generate vectors
   ↓
5. VECTOR_STORES persist
   ↓
6. Query → Hybrid Search (Vector + BM25) → Fusion → Rerank → Answer

Read:

  1. RAG.md - Complete pipeline
  2. ADVANCED_CHUNKING.md - Semantic & contextual chunking
  3. EMBEDDINGS.md - Vector generation
  4. VECTOR_STORES.md - Storage
  5. HYBRID_SEARCH.md - BM25, hybrid search & reranking

🎓 Learning Path

Beginner

  1. Follow QUICKSTART.md - Build your first agent in 5 minutes
  2. Read ARCHITECTURE.md - Get the big picture
  3. Read AGENT.md - Understand the core loop
  4. Read TOOLS.md - Learn to create tools

Intermediate

  1. Read PARSER.md - Understand parsing
  2. Read PROVIDERS.md - Switch providers
  3. Read MEMORY.md - Add conversations
  4. Read USAGE.md - Track costs

Advanced

  1. Read RAG.md - Add document search
  2. Read HYBRID_SEARCH.md - Hybrid search & reranking
  3. Read ADVANCED_CHUNKING.md - Semantic & contextual chunking
  4. Read STREAMING.md - Streaming, parallel execution, routing
  5. Read DYNAMIC_TOOLS.md - Plugin systems & hot-reload

Production / Enterprise

  1. Read GUARDRAILS.md - Input/output validation pipeline
  2. Read AUDIT.md - Compliance logging
  3. Read SECURITY.md - Prompt injection defence

Memory & Persistence

  1. Read SESSIONS.md - Persistent sessions
  2. Read ENTITY_MEMORY.md - Entity tracking
  3. Read KNOWLEDGE_GRAPH.md - Knowledge graphs
  4. Read KNOWLEDGE.md - Cross-session knowledge
  5. Build production RAG and agent systems!

💡 Key Concepts

Design Principles

  1. Provider Agnosticism - Switch LLMs without code changes
  2. Library-First - Composable, no framework lock-in
  3. Production Hardened - Retries, timeouts, validation
  4. Developer Friendly - Type hints, decorators, clear errors
  5. Observable - AgentObserver + AsyncAgentObserver protocol, OTel span export, usage tracking
  6. Cost Aware - Automatic tracking and warnings
  7. Performance Optimized - Parallel tool execution, response caching, async-first design
  8. Enterprise Secure - Guardrails, PII redaction, prompt injection screening, coherence checking, audit logging

Core Patterns

  • Agent Loop - Iterative tool calling until completion
  • Structured Output - Pydantic/JSON Schema validation with auto-retry
  • Execution Traces - Structured timeline on every run (result.trace)
  • Reasoning Visibility - Why the agent chose a tool (result.reasoning)
  • Provider Fallback - Priority-ordered providers with circuit breaker
  • Batch Processing - Concurrent multi-prompt execution
  • Tool Policy Engine - Declarative allow/review/deny with HITL approval
  • Native Tool Calling - Provider-native function calling APIs
  • Parallel Execution - Concurrent tool calls via asyncio.gather
  • Tool Calling Contract - TOOL_CALL with JSON payload
  • Schema Generation - Automatic from type hints
  • Injected Parameters - Hide secrets from LLM
  • Streaming - Progressive results via generators
  • Response Caching - LRU+TTL caching for identical LLM requests
  • RAG Pipeline - Load → Chunk → Embed → Store → Search
  • Hybrid Search - BM25 + vector fusion with optional reranking
  • Semantic Chunking - Embedding-based topic-boundary splitting
  • Contextual Chunking - LLM-enriched chunks for better retrieval
  • Dynamic Tool Loading - Plugin discovery, hot-reload, runtime tool management
  • Routing Mode - Tool selection without execution for intent classification
  • Guardrails Engine - Input/output content validation with block/rewrite/warn actions
  • Audit Logging - JSONL audit trail with privacy controls and daily rotation
  • Tool Output Screening - Pattern-based prompt injection detection
  • Coherence Checking - LLM-based intent verification for tool calls

🔧 Common Tasks

Create an Agent

See: AGENT.md

Define a Tool

See: TOOLS.md

Use Pre-Built Tools

See: TOOLBOX.md

Handle Errors

See: EXCEPTIONS.md

Look Up Model Pricing

See: MODELS.md — Programmatic Pricing API

Add RAG

See: RAG.md

Get Structured Output

See: AGENT.md — Structured Output

See Execution Traces

See: AGENT.md — Execution Traces

Add Provider Fallback

See: PROVIDERS.md — FallbackProvider

Batch Processing

See: AGENT.md — Batch Processing

Add Tool Policies

See: AGENT.md — Tool Policy

Add Guardrails

See: GUARDRAILS.md

Add Audit Logging

See: AUDIT.md

Screen Tool Outputs for Injection

See: SECURITY.md — Tool Output Screening

Enable Coherence Checking

See: SECURITY.md — Coherence Checking

Monitor with AgentObserver

See: AGENT.md — AgentObserver Protocol

Export Traces to OpenTelemetry

See: AGENT.md — AgentObserver Protocol (result.trace.to_otel_spans())

Switch Providers

See: PROVIDERS.md

See: HYBRID_SEARCH.md

Use Advanced Chunking

See: ADVANCED_CHUNKING.md

Stream Responses

See: STREAMING.md

Load Tools Dynamically

See: DYNAMIC_TOOLS.md

Track Costs

See: USAGE.md

Choose a Model

See: MODELS.md

🚀 Next Steps

  1. Read the ARCHITECTURE.md for system overview
  2. Explore module docs based on your needs
  3. Check the main README for quick start examples
  4. Review the Roadmap for upcoming features

📝 Contributing

Found an error or want to improve the docs?

  1. Check the source code in src/selectools/
  2. Submit issues or PRs on GitHub
  3. Follow the patterns established in existing docs

Built with ❤️ for developers who want to understand their tools.