# Tree of Thoughts, absorbed into Swarms but still filed under its old name

> A search based reasoning agent for language models, 4590 stars, whose README now tells you to install a different package and whose packaging metadata disagrees with its own badge about the licence.

**kyegomez/tree-of-thoughts** — Plug in and Play Implementation of Tree of Thoughts: Deliberate Problem Solving with Large Language Models that Elevates Model Reasoning by atleast 70% 

- Repository: https://github.com/kyegomez/tree-of-thoughts
- Website: https://discord.gg/qUtxnK2NMf
- Stars: 4,595 · Forks: 373
- Language: Python
- License: Apache-2.0
- Published: 2026-10-08 · Updated: 2026-10-08 · Language: en
- Canonical page: https://hysenlabs.com/projects/kyegomez-tree-of-thoughts

## The repository that tells you to install something else

The most important line in this README is a note near the top: Tree of Thoughts now ships as part of the Swarms framework as `TreeOfThoughts`, and the examples and docs below use that implementation. The install command confirms it:

```bash
pip3 install -U swarms
```

There is no `tree-of-thoughts` package to install in any current sense. The PyPI badge at the top points at swarms, the docs badge points at docs.swarms.world, and the banner badge says it was built with Swarms. The paper link goes to arXiv 2305.10601, and the README credits the original authors with a link to their own implementation at princeton-nlp, which is a detail worth respecting: this is a reimplementation, not the research code.

What remains here is the documentation, the examples, and a package manifest. The examples directory still holds the substance: separate `bfs.py` and `dfs.py` scripts for Game of 24, plus `physics`, `reasoning` and `frontier_math` subdirectories. Those are the files worth reading, and each one is written to state its expected answer in its own docstring.

The repository has 4590 stars, which makes it the most starred project in this batch, and 9 open issues, which is remarkably few for a repository of that visibility. Last push was 2026-09-29.

## Search instead of a single pass, in four operations

The mechanism is described precisely enough to be useful. A language model reasons by search rather than in one pass: it proposes several candidate next steps, scores each one, prunes weak branches, and backtracks when a line of reasoning fails. The README reports the paper's headline result, that GPT-4 with chain-of-thought prompting solved 4 percent of Game of 24 puzzles while Tree of Thoughts solved 74 percent.

Those 70 percentage points are the source of the repository description's claim that reasoning is lifted by at least 70 percent. Treat that number as a property of one puzzle benchmark in one paper, not as a general claim about the technique. Nothing in the repository measures it on your workload, and the README does not claim it does either.

The implementation is four operations. Generate proposes `num_thoughts` candidate next steps from a node, either all in one call under `propose` or one call per step under `sample`. Evaluate scores each candidate from 0 to 1, either on its own under `value` or comparatively with a vote under `vote`. Search explores breadth-first with a beam under `bfs` or depth-first with backtracking under `dfs`, pruning candidates below `value_threshold`. Answer writes the final output from the best path found.

Two implementation details deserve more attention than they get. Every model output is a function call validated against a Pydantic schema, so the search never parses free-form prose, which removes an entire class of failure where a model explains itself in a sentence you then have to parse. And calls at the same level of the tree run concurrently, bounded by `max_workers`, defaulting to 8.

## Twenty configuration knobs and the four that matter

The configuration table is long, and most readers should ignore most of it. Four parameters do the real work. `thought_description` describes what a single step looks like for your task, and `evaluation_criteria` describes how to judge progress. The README's guidance is that these two adapt the search to a domain more than any other setting, and that is correct: they are the only inputs that let the generic machinery know anything about your problem. The quickstart shows both in use.

```python
from swarms import TreeOfThoughts

agent = TreeOfThoughts(
    model_name="gpt-5.4",
    search_algorithm="dfs",
    max_depth=3,
    thought_description="One arithmetic operation on two of the remaining numbers.",
    evaluation_criteria="Can the remaining numbers still reach 24?",
)

answer = agent.run("Use 4, 9, 10 and 13 with + - * / to make 24.")
print(answer)```

The remaining four set cost. `num_thoughts` defaults to 3 candidate steps per expanded node, `breadth` to 2 as the beam width, `max_depth` to 3, and `n_evaluate_samples` to 1. Since every expanded node multiplies out, the search cost grows fast with these, which is why `max_expansions` exists as a hard cap and why the README tells you to use it. The DFS example in the examples directory is explicitly described as using that cap.

The model is reached through LiteLLM, so `model_name` accepts any provider that supports function calling, and the README notes you can set `ANTHROPIC_API_KEY`, `GROQ_API_KEY` or another provider's key instead of the OpenAI one. Function calling is a hard requirement, not a preference, and that constraint rules out a number of models people would otherwise try.

The result object is worth inspecting, which the README shows:

```python
result = agent.last_result

for number, step in enumerate(result.steps, 1):  # the best reasoning path
    print(f"{number}. {step}")

print(result.solved)                  # True if a final step cleared value_threshold
print(result.nodes_expanded)          # nodes that had candidates generated
print(result.llm_calls)               # model calls, including the final answer
print(result.usage["total_tokens"])   # token usage for this search
tree = result.to_dict()               # the whole tree as JSON-serializable data
```

`llm_calls` and `usage` are the fields that make this agent accountable, because a search that backtracks a lot will spend real money and you need to see that in your own logs rather than infer it from a bill.

## Packaging metadata that contradicts the README three times

The `pyproject.toml` in this tree is the weakest part of the repository, and it disagrees with the README and with GitHub's own metadata on three separate points.

The first is the licence. `pyproject.toml` declares `license = "MIT"` and includes an `License :: OSI Approved :: MIT License` classifier. The README badge reads license Apache 2.0, and GitHub reports the repository licence as Apache-2.0. One of these is wrong, and the file you would actually read before depending on the package is the one that is least consistent.

The second is the Python version. The classifiers list `Programming Language :: Python :: 3.6`, while the dependency constraint in the same file is `python = "^3.10"` and the README badge advertises Python 3.10 or newer. A classifier claiming 3.6 support next to a floor of 3.10 is a copy-paste artefact from an older manifest, and it will mislead anyone building a version matrix from PyPI metadata.

The third is the description field, which reads `Tree of Thoughts - Pytorch`. There is no PyTorch in this project. The declared dependencies are swarms, numpy, pydantic, loguru and python-dotenv, and the implementation is built on the Swarms framework. The string looks like it was copied from a different project template.

There is a fourth, smaller inconsistency between the two dependency files. `requirements.txt` lists `swarm-models`, which the manifest does not declare, and omits `numpy`, which the manifest does declare. Neither file is authoritative and they disagree.

None of this affects the agent, because you are installing swarms rather than this project. All of it matters if you were considering depending on the `tree-of-thoughts` distribution directly, because the manifest is what a package index would serve you.

## A stale release history and a version number nobody shipped

The release history has not moved in three years. The newest tag is 0.3.6, published 2023-07-29, with an empty release body. Just before it, 0.3.5 carries the name Langchain TOT and a detailed changelog describing a `LangchainTOT` class that holds a language model instance, a problem description, a thought checker and a list of thoughts, with error handling in `check_thoughts` that raises a ValueError when no thoughts have been added.

That class does not exist in the current README. What is documented now is a `TreeOfThoughts` agent in the Swarms framework with a completely different configuration surface, no `LangchainTOT` class and no checker parameter. The release notes describe a different architecture to the one the README teaches, which is expected for a project that was rewritten, and it means the changelog is history rather than documentation.

Even the tag naming is inconsistent: there is a tag called `e28` from June 2023, which is an experiment marker rather than a version. And `pyproject.toml` declares `version = "0.6.5"`, a number more than twice the highest published tag. So the version in the manifest is not the version you can install, the highest tag is not the version in the manifest, and one tag is not a version at all.

Meanwhile the repository itself is not frozen. With a push on 2026-09-29 and documentation written against current models, the documentation is current while the tags and the manifest are not. That split is the accurate summary of this repository's state: live prose, frozen packaging.

## Conclusion

The technique is the durable part here, and this repository is a good place to read it written down by someone who has implemented it. Generate candidates, score them, prune below a threshold, search breadth-first or depth-first with backtracking, and stop at a depth where the answer must be complete. The four levers that matter in practice are `thought_description` and `evaluation_criteria`, which adapt the search to a domain, and `num_thoughts`, `breadth`, `max_depth` and `n_evaluate_samples`, which set the cost. What you should not do is treat the repository as the package. Install `swarms`, import `TreeOfThoughts` from there, and ignore the packaging metadata in this tree, which declares a different licence, a different Python version and a framework dependency it does not use.

## FAQ

### How does the tree of thought work?

It replaces a single reasoning pass with a search. From each node the model proposes several candidate next steps, each candidate is scored from 0 to 1, candidates below a threshold are pruned, and the search continues breadth-first with a beam or depth-first with backtracking. The best path found is used to write the final answer. In this implementation every model output is a function call validated against a Pydantic schema, so the search never parses prose.

### What is the difference between tree of thought and Chain-of-Thought?

Chain-of-Thought produces one linear chain of reasoning and commits to it, with no way to abandon a bad prefix. Tree of Thought keeps multiple candidate continuations alive at once, scores them, prunes the weak ones and backtracks when a branch fails. The paper's reported result is that GPT-4 with chain-of-thought prompting solved 4 percent of Game of 24 puzzles while Tree of Thoughts solved 74 percent, on that one benchmark.

### Can you give me an example of a tree of thought prompt?

The practical version of a tree of thought is not one prompt but a per-step description plus a per-step criterion. The README's quickstart uses the thought description One arithmetic operation on two of the remaining numbers and the evaluation criteria Can the remaining numbers still reach 24, on the task of using 4, 9, 10 and 13 with four operators to make 24. Those two strings, not the model prompt, are what steer the search.

### What is a tree of reasoning?

It is the same idea under another name: a model that keeps several partial solutions alive, evaluates them, and backtracks instead of committing to the first thing it generated. In this repository it is presented as the Tree of Thoughts method from arXiv 2305.10601, with the authors' own implementation hosted separately at princeton-nlp.

## Sources

- [kyegomez/tree-of-thoughts on GitHub](https://github.com/kyegomez/tree-of-thoughts)
- [License: Apache-2.0](https://github.com/kyegomez/tree-of-thoughts/blob/main/LICENSE)
- [Project website](https://discord.gg/qUtxnK2NMf)
- [README](https://github.com/kyegomez/tree-of-thoughts/blob/main/README.md)
- [Releases](https://github.com/kyegomez/tree-of-thoughts/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kyegomez-tree-of-thoughts