# Pydantic AI Toolsets

A comprehensive collection of reasoning, reflection, and multi-agent toolsets for pydantic-ai agents.

## Table of Contents

- [Reasoning & Thinking Toolsets](#reasoning--thinking-toolsets)
  - [Reasoning Toolsets Comparison](#reasoning-toolsets-comparison)
- [Reflection & Refinement Toolsets](#reflection--refinement-toolsets)
  - [Reflection Toolsets Comparison](#reflection-toolsets-comparison)
- [Multi-Agent Toolsets](#multi-agent-toolsets)
  - [Multi-Agent Toolsets Comparison](#multi-agent-toolsets-comparison)
- [Utility Toolsets](#utility-toolsets)

---

## Reasoning & Thinking Toolsets

### Chain of Thought (CoT)

**What it does:** Enables agents to document and explore their reasoning process step-by-step. Agents can write sequential thoughts, revise previous reasoning, and branch into alternative paths.

**Perfect for:**
- Complex problems requiring multi-step reasoning
- Planning and design tasks that may need revision
- Analysis where understanding evolves over time
- Multi-step solutions needing context tracking
- Problems with uncertainty requiring exploration
- Hypothesis generation and verification

**Key Features:**
- Sequential thought tracking with revision support
- Branching for exploring alternative reasoning paths
- Thought metadata (revisions, branches, completion status)
- Flexible thought management with dynamic total estimates

---

### Tree of Thought (ToT)

**What it does:** Allows agents to explore multiple reasoning paths simultaneously in a tree structure. Agents create nodes for different approaches, evaluate branches for promise, prune dead ends, and merge insights from multiple paths.

**Perfect for:**
- Complex problems with multiple valid approaches
- Problems requiring exploration of alternatives
- Situations needing backtracking from dead ends
- Tasks where combining insights from different paths is valuable
- Problems where evaluation of paths is important

**Key Features:**
- Tree structure with nodes and branches
- Branch evaluation with scores and recommendations
- Pruning mechanism for dead ends
- Insight merging from multiple branches
- Solution node marking

---

### Graph of Thought (GoT)

**What it does:** Provides graph-based reasoning where nodes represent reasoning states and edges connect them with various relationships (dependency, aggregation, refinement, reference, merge). More flexible than trees, allowing cross-links and cycles.

**Perfect for:**
- Complex problems with interconnected sub-problems
- Tasks requiring synthesis from multiple perspectives
- Iterative refinement of solutions
- Problems with non-linear dependencies
- Building on partial solutions

**Key Features:**
- Directed graph structure (not limited to trees)
- Multiple edge types (dependency, aggregation, refinement, reference, merge)
- Node evaluation and scoring
- Node aggregation and refinement
- Path finding between nodes

---

### Beam Search

**What it does:** Implements beam search exploration, maintaining a "beam" of top-k candidates at each step. Agents expand candidates, score them, and prune to keep only the best, balancing exploration and exploitation.

**Perfect for:**
- Problems requiring simultaneous multi-path exploration
- Tasks needing systematic exploration with pruning
- Balancing exploration vs exploitation
- Problems with clear scoring/evaluation functions
- When breadth-first search is too expensive

**Key Features:**
- Beam width control (k candidates per step)
- Candidate expansion and scoring
- Pruning to top-k at each step
- Path reconstruction from initial to terminal candidates
- Terminal state marking

---

### Monte Carlo Tree Search (MCTS)

**What it does:** Implements Monte Carlo Tree Search for decision-making with exploration-exploitation balance. Uses UCB1 formula to select promising nodes, expands them, simulates outcomes, and backpropagates statistics.

**Perfect for:**
- Decision-making with many possible actions
- Game-like problems with win/loss outcomes
- Problems requiring exploration vs exploitation balance
- Sequential decision problems
- Situations where simulations can provide reward signals

**Key Features:**
- Four-phase MCTS process (selection, expansion, simulation, backpropagation)
- UCB1 formula for node selection
- Reward-based evaluation (0.0-1.0 scale)
- Visit and win statistics tracking
- Best action selection based on visit counts

---

### Reasoning Toolsets Comparison

| Feature | Chain of Thought | Tree of Thought | Graph of Thought | Beam Search | MCTS |
|---------|------------------|-----------------|------------------|-------------|------|
| **Structure** | Sequential chain | Tree (hierarchical) | Graph (flexible) | Beam (top-k per step) | Tree (with statistics) |
| **Path Exploration** | Single path with branches | Multiple paths simultaneously | Multiple paths with cross-links | Top-k paths per step | Single path per iteration |
| **Evaluation** | None (implicit) | Branch scoring (0-100) | Node scoring (0-100) | Candidate scoring (0-100) | UCB1 + simulation rewards |
| **Pruning** | Manual revision | Branch pruning | Node pruning | Top-k pruning per step | Implicit (UCB1 selection) |
| **Merging** | Branch merging | Branch merging | Node aggregation | Path reconstruction | N/A |
| **Best For** | Step-by-step reasoning | Multiple approaches | Interconnected problems | Systematic exploration | Decision-making with rewards |
| **Complexity** | Low | Medium | High | Medium | High |
| **Use Case** | Planning, analysis | Problem solving | Complex synthesis | Search problems | Game-like decisions |

---

## Reflection & Refinement Toolsets

### Reflection

**What it does:** Enables iterative output improvement through critical analysis. Agents create initial outputs, critique them systematically, and refine them based on identified problems. Supports multiple refinement cycles.

**Perfect for:**
- Tasks requiring high-quality, polished outputs
- Problems where initial solutions may have flaws
- Situations where iterative improvement is valuable
- Tasks where structured critique helps identify issues
- Problems where multiple refinement cycles improve results

**Key Features:**
- Structured critique framework (problems, strengths, suggestions)
- Refinement cycles with parent-child relationships
- Quality score tracking
- Final output marking
- Best output selection

---

### Self-Refine

**What it does:** Provides structured feedback-based refinement with support for quality thresholds and iteration limits. Agents generate outputs, provide structured feedback (additive, subtractive, transformative, corrective), and refine iteratively until quality thresholds are met.

**Perfect for:**
- Tasks requiring high-quality, polished outputs
- Problems where initial solutions may have flaws
- Situations where iterative improvement is valuable
- Tasks where structured feedback helps identify issues
- Problems where multiple refinement cycles improve results
- When you need to meet specific quality thresholds

**Key Features:**
- Structured feedback types (additive, subtractive, transformative, corrective)
- Feedback dimensions (factuality, coherence, completeness, style)
- Priority-weighted feedback
- Quality threshold support
- Iteration limit control
- Quality score tracking

---

### Self-Ask

**What it does:** Decomposes complex questions into simpler sub-questions in a hierarchical structure. Agents ask main questions, generate sub-questions at multiple depth levels, answer them sequentially or in parallel, and compose final answers from sub-question answers.

**Perfect for:**
- Complex questions requiring multi-hop reasoning
- Questions that need to be broken down into simpler parts
- Problems where intermediate answers build toward a final answer
- Questions requiring information gathering from multiple sources
- Situations where explicit decomposition makes reasoning transparent

**Key Features:**
- Hierarchical question decomposition (max depth 3)
- Question tree structure with parent-child relationships
- Sequential and parallel question answering
- Answer composition from sub-questions
- Confidence scoring for answers
- Follow-up question tracking

---

### Reflection Toolsets Comparison

| Feature | Reflection | Self-Refine | Self-Ask |
|---------|------------|------------|----------|
| **Primary Focus** | Output improvement | Output improvement with thresholds | Question decomposition |
| **Process** | Critique → Refine cycles | Feedback → Refine cycles | Question → Answer → Compose |
| **Feedback Structure** | Problems, strengths, suggestions | Types (additive/subtractive/transformative/corrective) + dimensions | Question-answer pairs |
| **Quality Control** | Quality scores (optional) | Quality thresholds + iteration limits | Confidence scores (optional) |
| **Iteration Control** | Manual (mark as final) | Automatic (threshold/limit based) | Depth limit (max 3) |
| **Output Tracking** | Refinement cycles | Refinement iterations | Question-answer tree |
| **Best For** | General output improvement | Quality-gated refinement | Complex question answering |
| **Use Case** | Writing, analysis | Polished outputs | Multi-hop reasoning |
| **Stopping Condition** | Manual final marking | Threshold met or limit reached | All questions answered |

---

## Multi-Agent Toolsets

### Multi-Persona Analysis

**What it does:** Enables analysis from multiple distinct personas or viewpoints WITHOUT debate structure. Personas provide independent analysis, engage in interactive dialogue, or use devil's advocate patterns. Results are synthesized into comprehensive solutions. This is NOT a debate toolset - it's for collaborative analysis.

**Perfect for:**
- Complex problems requiring diverse expertise
- Decisions needing multiple stakeholder perspectives
- Problems where different thinking styles improve outcomes
- Situations where role-playing different experts is valuable
- Tasks requiring comprehensive analysis from multiple angles

**Key Features:**
- Persona creation (expert, thinking_style, stakeholder)
- Process types (sequential, interactive, devil's advocate)
- Persona response tracking
- Synthesis of diverse perspectives
- Round-based interaction management
- No adversarial structure (collaborative analysis)

---

### Multi-Persona Debate

**What it does:** Enables structured debates between multiple personas with distinct expertise and viewpoints. Personas can propose positions, critique each other, agree with positions (coalition-building), and defend their arguments. Supports orchestration of multi-persona interactions.

**Perfect for:**
- Complex decisions requiring diverse expert perspectives
- Problems where multiple viewpoints need structured argumentation
- Situations where personas can both agree and disagree based on logic
- Tasks where coalition-building and consensus formation are valuable
- Problems requiring evidence-based evaluation from different experts

**Key Features:**
- Persona creation with expertise and viewpoints
- Position proposal and defense
- Critique and agreement mechanisms
- Round-based debate structure
- Resolution types (synthesis, winner, consensus)
- Multi-agent orchestration support

---

### Multi-Agent Toolsets Comparison

| Feature | Multi-Persona Analysis | Multi-Persona Debate |
|---------|------------------------|---------------------|
| **Structure** | Analysis (non-debate) | Structured debate |
| **Agent Types** | Custom personas | Custom personas |
| **Interaction** | Independent or interactive | Critique, agree, defend |
| **Agreement Support** | Yes (consensus) | Yes (coalition-building) |
| **Resolution** | Synthesis only | Synthesis/Winner/Consensus |
| **Setup Complexity** | Medium (create personas) | High (create personas) |
| **Best For** | Collaborative analysis | Custom expert debates |
| **Use Case** | Comprehensive analysis | Complex multi-expert decisions |
| **Adversarial** | No (collaborative) | Optional (can agree) |
| **Process Types** | Sequential/Interactive/Devil's Advocate | Debate rounds |

---

## Utility Toolsets

### To-Do

**What it does:** Provides simple task management for agents. Agents can create, track, and update tasks with status (pending, in_progress, completed). Helps manage complex multi-step tasks.

**Perfect for:**
- Complex multi-step tasks (3+ distinct steps)
- Non-trivial tasks requiring careful planning
- User provides multiple tasks
- After receiving new instructions - capture requirements as todos
- When starting a task - mark it as in_progress BEFORE beginning work
- After completing a task - mark it as completed immediately

**Key Features:**
- Task status tracking (pending, in_progress, completed)
- Simple task list management
- Status summary and hints
- Task completion tracking

---

### Search

**What it does:** Provides web search capabilities using Firecrawl and content extraction using Trafilatura. Agents can search the web for current information and extract readable content from webpages.

**Perfect for:**
- Finding current information on the web
- Researching topics that require up-to-date data
- Extracting readable content from webpages
- Gathering information from multiple sources
- Verifying facts or finding authoritative sources
- Discovering recent developments or news

**Key Features:**
- Web search with Firecrawl integration
- Content extraction with Trafilatura
- Multiple output formats (txt, markdown)
- Search result and content caching
- URL-based content extraction

---

## Installation

```bash
pip install pydantic-ai-toolsets
```

## Quick Start

```python
from pydantic_ai import Agent
from pydantic_ai_toolsets import create_cot_toolset

# Create an agent with Chain of Thought reasoning
agent = Agent("openai:gpt-4", toolsets=[create_cot_toolset()])
result = await agent.run("Solve this complex problem step by step")
```
