Metadata-Version: 2.4
Name: tree-of-thoughts-ai
Version: 0.1.0
Summary: Deliberate Problem Solving with Large Language Models - Implementation of Tree of Thoughts paper
Author-email: AI Agent Research Team <team@example.com>
License: MIT
Project-URL: Homepage, https://github.com/Carlos-Zen/tree-of-thoughts
Project-URL: Documentation, https://github.com/Carlos-Zen/tree-of-thoughts#readme
Project-URL: Repository, https://github.com/Carlos-Zen/tree-of-thoughts
Keywords: ai,agent,tree-of-thoughts,llm,reasoning,problem-solving
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Dynamic: license-file

# Tree of Thoughts

<p align="center">
  <strong>Deliberate Problem Solving with Large Language Models</strong>
</p>

<p align="center">
  <a href="README_CN.md">中文文档</a> | <a href="README.md">English</a>
</p>

<p align="center">
  <a href="#architecture">Architecture</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-reference">API Reference</a>
</p>

---

A Python implementation of **Tree of Thoughts (ToT)**, a framework that frames problem solving as a search over a tree of thoughts.

## Architecture

```
Tree of Thoughts Architecture
│
├── ToTAgent (Main Agent)
│   ├── Orchestrates the search process
│   ├── Uses thought generators and evaluators
│   └── Applies search strategies
│
├── ThoughtTree (Tree Structure)
│   ├── ThoughtNode - Individual reasoning steps
│   ├── Path tracking from root to leaf
│   └── Pruning and visualization
│
├── SearchStrategy (Traversal Methods)
│   ├── BFSStrategy - Breadth-First Search
│   ├── DFSStrategy - Depth-First Search
│   ├── BestFirstStrategy - Value-based prioritization
│   └── BeamSearchStrategy - Memory-efficient search
│
└── Types (Data Structures)
    ├── Problem - Task to solve
    ├── Thought - Single reasoning step
    ├── Solution - Final answer with reasoning
    └── SearchResult - Search statistics
```

## Core Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Tree of Thoughts Process                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Problem ──▶ Generate Thoughts ──▶ Evaluate ──▶ Select Best    │
│       │              │                │              │          │
│       │              └────────────────┴──────────────┘          │
│       │                       │                                  │
│       │                       ▼                                  │
│       │              Check Solution? ──▶ Yes ──▶ Return Answer   │
│       │                       │                                  │
│       │                       No                                 │
│       │                       │                                  │
│       └───────────────────────┴──▶ Expand Tree ──▶ Repeat       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Installation

```bash
pip install tree-of-thoughts
```

## Quick Start

```python
from tot import ToTAgent, Problem, BestFirstStrategy

# Define thought generator (typically uses an LLM)
def generate_thoughts(state: str, n: int) -> list:
    # Generate n possible next thoughts
    # response = llm.generate(f"Generate {n} next thoughts: {state}")
    return ["Thought 1", "Thought 2", "Thought 3"][:n]

# Define thought evaluator
def evaluate_thought(state: str, thought: str) -> float:
    # Return value between 0-1 (higher is better)
    # response = llm.generate(f"Rate this thought: {thought}")
    return 0.8

# Define solution checker
def check_solution(state: str, thought: str) -> tuple:
    # Return (is_solution, answer)
    # Check if we've reached a valid solution
    return (False, "")  # or (True, "final answer")

# Create and run agent
agent = ToTAgent(
    generate_thoughts,
    evaluate_thought,
    check_solution,
    strategy=BestFirstStrategy(),
    max_depth=5,
)

result = agent.solve(Problem(question="Solve this problem"))
print(f"Success: {result.success}")
print(f"Answer: {result.solution.answer if result.solution else 'Not found'}")
```

## Search Strategies

| Strategy | Description | Best For |
|----------|-------------|----------|
| **BFS** | Explores all nodes at depth before going deeper | Shortest solution path |
| **DFS** | Explores as deep as possible before backtracking | Quick any solution |
| **Best-First** | Prioritizes highest-value nodes | Quality solutions |
| **Beam Search** | Keeps only top-k candidates per level | Memory efficiency |

## CLI Usage

```bash
# Run with different strategies
tot run "What is 15 * 17?" --strategy best
tot run "Solve this puzzle" --strategy bfs

# Interactive mode
tot interactive --strategy dfs

# Export trajectory
tot run "Question" --export result.json
```

## API Reference

### ToTAgent

| Parameter | Description |
|-----------|-------------|
| `generate_thoughts` | Function to generate next thoughts |
| `evaluate_thought` | Function to score thoughts (0-1) |
| `check_solution` | Function to check if solved |
| `strategy` | Search strategy (default: BestFirst) |
| `max_depth` | Maximum tree depth |
| `max_nodes` | Maximum nodes to explore |
| `branching_factor` | Thoughts per node |

## Academic Reference

Implementation of the **Tree of Thoughts** paper:

> **Tree of Thoughts: Deliberate Problem Solving with Large Language Models**
>
> Shunyu Yao, Dian Yu, Jeffrey Zhao, Izhak Shafran, Thomas L. Griffiths, Yuan Cao, Karthik R. Narasimhan
>
> *NeurIPS 2023*
>
> Paper: https://arxiv.org/abs/2305.10601

```bibtex
@inproceedings{yao2023tree,
  title={Tree of Thoughts: Deliberate Problem Solving with Large Language Models},
  author={Yao, Shunyu and Yu, Dian and Zhao, Jeffrey and Shafran, Izhak and Griffiths, Thomas L and Cao, Yuan and Narasimhan, Karthik R},
  booktitle={Advances in Neural Information Processing Systems (NeurIPS)},
  year={2023}
}
```

## License

MIT License

---

<p align="center">
  Made with ❤️ by AI Agent Research Team
</p>
