# princeton-nlp/tree-of-thought-llm architecture

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

- Interactive diagram: https://gitdiagram.com/princeton-nlp/tree-of-thought-llm
- Repository: https://github.com/princeton-nlp/tree-of-thought-llm

## Overview

##### Main components
- Task Layer: This is where the specific problem tasks are defined (see “src/tot/tasks” with its task modules for game24, crosswords, and text). Also include the data files under “src/tot/data” which provide input instances (e.g., 24.csv, crossword JSON files, text data).
- Method Layer: Contains the algorithms/strategies for exploring “thoughts.” In “src/tot/methods”, you have the BFS (and by extension, DFS in crosswords). These methods implement the core algorithmic ideas from the paper.
- API/LLM Interaction: The system uses GPT-4 (or similar language models) via the OpenAI API. Make sure to mark the external dependency on the OpenAI service (and configuration via the OPENAI_API_KEY).
- Experiment Logs: The “logs” directory contains experimental outputs and trajectories from running experiments for various tasks, giving insight into the performance of different methods (BFS, DFS, Naive sampling, etc.).
- Utility & Deployment Scripts: There are shell scripts and notebooks (located in “scripts” and a Jupyter Notebook in “scripts/crosswords”) which trigger various experimental runs.
- Entry Point: The “run.py” acts as a simple executable that ties together the arguments (e.g., temperature, selection method parameters) and invokes the chosen algorithm on a specific task, showcasing the overall control flow.

- From the Task, show access to its corresponding “Data” (stored under src/tot/data) and “Prompts” (from src/tot/prompts) used to interact with the LLM.
- The “Method Layer” (with modules like bfs.py) receives these prompts and orchestrates the idea of state generation, evaluation, and selection. This layer includes key parameters (like n_generate_sample, n_evaluate_sample, etc.)
- Once the LLM returns outputs, these are passed back to the method layer for evaluation and processing.
- Finally, outputs (the deduced answer or trajectory) are stored in logs and optionally visualized or printed for further analysis.

##### Architectural Patterns and Principles
- Modular Design: The separation between tasks, methods, prompts, and data encapsulates specific functionalities.
- Separation of Concerns: Different directories show clear boundaries (e.g., scripts for experiments vs. the src directory for core logic).

##### Specific Elements
- A clear label for each component (“Task Selector”, “Data Loader”, “Prompt Manager”, “Algorithm Executor”, “LLM Service”, “Logger”).
- From “run.py” → “Task Module” (Game24Task, CrosswordsTask, TextTask).
- From the “Task Module” → “Data” & “Prompts”.
- From “Algorithm Module” (e.g., BFS) → “LLM API” (sending prompts and receiving thought outputs).
- From “LLM API” back to “Algorithm Module” → “Logger” (persisting the trails).
- Use rectangles for internal modules.

##### Final Advice
- Remember that the tree-of-thoughts system is an iterative chain-of-thought approach that leverages LLMs in a non-deterministic manner—so ensuring that the flow from configuration to experimental logging is clearly illustrated will help capture the design’s intent.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client/Controller Layer
    subgraph "Client/Controller"
        A["run.py (Entry Point)"]:::controller
    end

    %% Task & Data Layer
    subgraph "Task & Data Layer"
        %% Task Modules
        B["Game24Task"]:::task
        C["CrosswordsTask"]:::task
        D["TextTask"]:::task

        %% Data Files subgraph
        subgraph "Data Files"
            E["24 Data"]:::data
            F["Crosswords Data"]:::data
            G["Text Data"]:::data
        end
    end

    %% Processing & Method Layer
    subgraph "Processing & Method Layer"
        H["BFS Module"]:::method
        I["DFS Integration"]:::method
    end

    %% Prompting & Evaluation Layer
    subgraph "Prompting & Evaluation Layer"
        J["Game24Prompt"]:::prompt
        K["CrosswordsPrompt"]:::prompt
        L["TextPrompt"]:::prompt
    end

    %% External Integration Layer
    subgraph "External Integration"
        M["LLM API (GPT-4)"]:::external
    end

    %% Logging/Results Layer
    subgraph "Logging/Results Layer"
        N["Game24 Logs"]:::logs
        O["Crosswords Logs"]:::logs
        P["Text Logs"]:::logs
    end

    %% Utility & Deployment Scripts Layer
    subgraph "Utility & Deployment Scripts"
        Q["Experiment Scripts"]:::scripts
        R["Crosswords Notebook"]:::scripts
    end

    %% Connections
    A -->|"initiates"| B
    A -->|"initiates"| C
    A -->|"initiates"| D

    B -->|"loads"| E
    C -->|"loads"| F
    D -->|"loads"| G

    B -->|"uses"| J
    C -->|"uses"| K
    D -->|"uses"| L

    B -->|"executes"| H
    C -->|"executes"| H
    D -->|"executes"| H

    C -->|"integratesDFS"| I

    J -->|"combinedWith"| H
    K -->|"combinedWith"| H
    L -->|"combinedWith"| H

    H -->|"sendsPrompt"| M
    M -->|"returnsThoughts"| H

    H -->|"logsOutputs"| N
    H -->|"logsOutputs"| O
    H -->|"logsOutputs"| P

    A -->|"triggers"| Q
    Q -->|"runsExperiments"| H
    Q -->|"usesNotebook"| R

    %% Click Events
    click A "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/run.py"
    click B "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/tasks/game24.py"
    click C "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/tasks/crosswords.py"
    click D "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/tasks/text.py"
    click E "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/src/tot/data/24"
    click F "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/src/tot/data/crosswords"
    click G "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/src/tot/data/text"
    click H "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/methods/bfs.py"
    click J "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/prompts/game24.py"
    click K "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/prompts/crosswords.py"
    click L "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/src/tot/prompts/text.py"
    click N "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/logs/game24"
    click O "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/logs/crosswords"
    click P "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/logs/text"
    click Q "https://github.com/princeton-nlp/tree-of-thought-llm/tree/master/scripts"
    click R "https://github.com/princeton-nlp/tree-of-thought-llm/blob/master/scripts/crosswords/search_crosswords-dfs.ipynb"

    %% Styles
    classDef controller fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef task fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef method fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef prompt fill:#87CEEB,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef logs fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef scripts fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
