# jieyilong/tree-of-thought-puzzle-solver architecture

> Architecture diagram of the GitHub repository jieyilong/tree-of-thought-puzzle-solver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jieyilong/tree-of-thought-puzzle-solver
- Repository: https://github.com/jieyilong/tree-of-thought-puzzle-solver

## Overview

##### Project Type and Purpose
- This is an AI-driven puzzle‐solver toolkit (not a web app).
- It implements a novel Tree-of-Thought orchestration around an LLM (OpenAI GPT) to solve Sudoku puzzles via various “solver types” (zero-shot, one-shot with CoT, few-shot with CoT, ToT).

##### File Structure
- Top-level runners:
- run_tot.py – CLI entry for the ToT solver
- run_expr.py – CLI entry for batch experiments
- Core orchestration:
- tot/tot.py – the ToT controller that drives multi-round thought tree exploration
- Modular “actors” under actors/:
- prompter.py – builds LLM prompts
- llm.py – wraps the LLM API call (OpenAI)
- parser.py – interprets LLM responses
- checker.py – validates candidate moves/partial solutions
- state.py – represents the current “thought” state / memory
- Common utilities under common/: configuration loader, constants, hyperparameters, enums, misc utils
- Data/experiments:
- data/benchmarks/sudoku – JSON puzzle sets
- experiments/chatbot_based_solvers.py – orchestrates solver variants
- experiments/execution_logs – stores run outputs
- Config file: config.yaml – holds LLM model choice and API key

##### Extract Additional Insights from README
- The README highlights:
- Four solver modes (zero-shot, one-shot CoT, few-shot CoT, ToT)
- Multi-agent, multi-round interaction with an LLM
- Backtracking support via tree structure of “thoughts”

##### Main Components
a. CLI Clients
- run_tot.py
- run_expr.py
b. Experiment Manager / Solver Factory
- experiments/chatbot_based_solvers.py
- Chooses solver_type and loads puzzle set from data/benchmarks
c. ToT Controller (tot/tot.py)
- Drives the tree search, backtracking logic, multi-round orchestration
d. Actors (modular components)
- Prompter (prompt builder)
- LLM Wrapper (OpenAI API client)
- Parser (response interpreter)
- Checker (validates/filters moves)
- State (maintains current puzzle state and thought nodes)
e. Data & Config
- Benchmarks (JSON puzzle inputs)
- config.yaml (LLM config)
f. External Service
- OpenAI API (Chat completion endpoint)
g. Logs & Outputs
- experiments/execution_logs

##### Relationships and Data Flow
- The CLI client invokes the Experiment Manager with a solver type and dataset path.
- Experiment Manager reads puzzle JSON, instantiates the appropriate solver (zero-shot / one-shot / few-shot / ToT).
- For ToT:
- The ToT Controller enters an iterative loop:
– Prompter constructs the next prompt using State.
– LLM Wrapper sends prompt to OpenAI, returns raw response.
– Parser extracts proposed moves/thoughts.
– Checker validates proposals against Sudoku rules.
– State updates the thought tree (accept, branch, backtrack).
– Loop until solution or search limit.
- Solutions are logged to experiments/execution_logs.

##### Architectural Patterns and Principles
- Modular “actor” pipeline: each responsibility is isolated in its own class.
- Controller pattern: ToT Controller orchestrates actor interactions.
- Data-driven experiments: Experiment Manager loads puzzles and logs results.
- Separation of concerns:
- Prompt engineering (Prompter)
- LLM communication (LLM Wrapper)
- Domain logic (Checker, State)
- Data I/O (Experiment Manager, Parser)

##### Technologies, Frameworks, Libraries
- Python 3.9+
- OpenAI Python SDK (wrapped by actors/llm.py)
- YAML for config (common/config.py)
- JSON for puzzle datasets
- Optional: logging modules, standard Python libs

##### Detailed Elements
- Clear labels (e.g., “ToT Controller (tot/tot.py)”)
- Arrowheads to indicate request/response or data updates
- Notes on loop boundaries (max depth, max iterations) near the Controller
- Call out external dependency (OpenAI API) with version/model info (e.g., “gpt-3.5-turbo”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Runners
    subgraph "CLI Runners"
        RunToT["run_tot.py"]:::core
        RunExpr["run_expr.py"]:::core
    end

    %% Experiment Manager
    ChatManager["experiments/chatbot_based_solvers.py"]:::core

    %% Controller
    ToTController["tot/tot.py<br/>(ToT Controller)"]:::core
    NoteController["Loop: max depth & iterations"]:::note

    %% Actors
    subgraph "Actors"
        Prompter["actors/prompter.py"]:::actor
        LLMWrapper["actors/llm.py"]:::actor
        Parser["actors/parser.py"]:::actor
        Checker["actors/checker.py"]:::actor
        State["actors/state.py"]:::actor
    end

    %% Data & Config
    subgraph "Data & Config"
        ConfigYAML["config.yaml"]:::data
        ConfigLoader["common/config.py"]:::data
        Hyperparams["common/hyperparams.py<br/>common/consts.py<br/>common/enums.py"]:::data
        Utils["common/utils.py"]:::data
        Benchmarks["Puzzle Benchmarks<br/>(JSON)"]:::data
        Logs["experiments/execution_logs/"]:::data
        Requirements["requirements.txt"]:::data
    end

    %% External Service
    OpenAIAPI["OpenAI API<br/>(gpt-3.5-turbo)"]:::external

    %% Connections
    RunToT --> ChatManager
    RunExpr --> ChatManager

    ChatManager -->|loads puzzles| Benchmarks
    ChatManager -->|instantiates ToT solver| ToTController

    ConfigYAML --> ConfigLoader
    ConfigLoader --> Prompter
    ConfigLoader --> LLMWrapper
    Hyperparams --> Prompter
    Hyperparams --> LLMWrapper
    Utils --> Parser
    Utils --> Checker

    ToTController --> NoteController
    ToTController --> Prompter
    Prompter --> LLMWrapper
    LLMWrapper --> OpenAIAPI
    OpenAIAPI --> Parser
    Parser --> Checker
    Checker --> State
    State --> ToTController

    ToTController -->|writes results| Logs

    %% Click Events
    click RunToT "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/run_tot.py"
    click RunExpr "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/run_expr.py"
    click ChatManager "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/experiments/chatbot_based_solvers.py"
    click ToTController "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/tot/tot.py"
    click Prompter "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/actors/prompter.py"
    click LLMWrapper "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/actors/llm.py"
    click Parser "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/actors/parser.py"
    click Checker "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/actors/checker.py"
    click State "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/actors/state.py"
    click ConfigLoader "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/common/config.py"
    click Hyperparams "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/common/hyperparams.py"
    click Utils "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/common/utils.py"
    click Benchmarks "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/data/benchmarks/sudoku/3x3_sudoku_puzzles.json"
    click Logs "https://github.com/jieyilong/tree-of-thought-puzzle-solver/tree/main/experiments/execution_logs/"
    click Requirements "https://github.com/jieyilong/tree-of-thought-puzzle-solver/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#D6E9FE,stroke:#3178C6,color:#0B3D91;
    classDef actor fill:#E3FCEF,stroke:#34A853,color:#126620;
    classDef data fill:#F5F5F5,stroke:#AAAAAA,color:#555555;
    classDef external fill:#FEF3C7,stroke:#F4B400,color:#A87700;
    classDef note fill:#FFFFFF,stroke:#888888,color:#333333,stroke-dasharray: 2 2;
    class NoteController note
```
