# `Jido.AI.Reasoning.TreeOfThoughts.Strategy`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/reasoning/tree_of_thoughts/strategy.ex#L1)

Tree-of-Thoughts (ToT) execution strategy for Jido agents.

This strategy implements branching exploration by generating multiple candidate
thoughts at each step, evaluating them, and expanding the most promising branches.

## Overview

Tree-of-Thoughts extends Chain-of-Thought by:
- Generating multiple candidate thoughts at each step
- Evaluating each thought's potential
- Exploring promising branches while pruning poor ones
- Supporting different traversal strategies (BFS, DFS, best-first)

This approach is effective for problems requiring search, like:
- Puzzles and games
- Planning and scheduling
- Creative writing
- Complex reasoning tasks

## Architecture

This strategy uses a pure state machine (`Jido.AI.Reasoning.TreeOfThoughts.Machine`) for
all state transitions. The strategy acts as a thin adapter that:
- Converts instructions to machine messages
- Converts machine directives to SDK-specific directive structs
- Manages the machine state within the agent

## Configuration

Configure via strategy options when defining your agent:

    use Jido.Agent,
      name: "my_tot_agent",
      strategy: {
        Jido.AI.Reasoning.TreeOfThoughts.Strategy,
        model: "anthropic:claude-sonnet-4-20250514",
        branching_factor: 3,
        max_depth: 4,
        traversal_strategy: :best_first
      }

### Options

- `:model` (optional) - Model alias or direct model spec, defaults to :fast (resolved via Jido.AI.resolve_model/1)
- `:branching_factor`, `:max_depth`, `:traversal_strategy` (optional) - Core tree search controls
- `:top_k`, `:min_depth`, `:max_nodes`, `:max_duration_ms`, `:beam_width` (optional) - Search budget and shaping controls
- `:early_success_threshold`, `:convergence_window`, `:min_score_improvement`, `:max_parse_retries` (optional) - Completion/parser controls
- `:tools`, `:tool_context`, `:tool_timeout_ms`, `:tool_max_retries`, `:tool_retry_backoff_ms`, `:max_tool_round_trips` (optional) - Tool execution controls
- `:effect_policy`, `:agent_effect_policy`, `:strategy_effect_policy` (optional) - Effect policy controls
- `:generation_prompt` (optional) - Custom prompt for thought generation
- `:evaluation_prompt` (optional) - Custom prompt for thought evaluation

## Signal Routing

This strategy implements `signal_routes/1` which AgentServer uses to
automatically route these signals to strategy commands:

- `"ai.tot.query"` → `:tot_start`
- `"ai.llm.response"` → `:tot_llm_result`
- `"ai.llm.delta"` → `:tot_llm_partial`

## State

State is stored under `agent.state.__strategy__` with tree structure.

# `config`

```elixir
@type config() :: %{
  model: String.t(),
  branching_factor: pos_integer(),
  max_depth: pos_integer(),
  traversal_strategy:
    Jido.AI.Reasoning.TreeOfThoughts.Machine.traversal_strategy(),
  generation_prompt: String.t(),
  evaluation_prompt: String.t(),
  top_k: pos_integer(),
  min_depth: non_neg_integer(),
  max_nodes: pos_integer(),
  max_duration_ms: pos_integer() | nil,
  beam_width: pos_integer() | nil,
  early_success_threshold: float(),
  convergence_window: pos_integer(),
  min_score_improvement: float(),
  max_parse_retries: non_neg_integer(),
  tools: [module()],
  actions_by_name: %{required(String.t()) => module()},
  reqllm_tools: [ReqLLM.Tool.t()],
  tool_context: map(),
  tool_timeout_ms: pos_integer(),
  tool_max_retries: non_neg_integer(),
  tool_retry_backoff_ms: non_neg_integer(),
  max_tool_round_trips: pos_integer(),
  effect_policy: map()
}
```

# `get_best_node`

```elixir
@spec get_best_node(Jido.Agent.t()) ::
  Jido.AI.Reasoning.TreeOfThoughts.Machine.thought_node() | nil
```

Returns the best scoring node in the tree.

# `get_nodes`

```elixir
@spec get_nodes(Jido.Agent.t()) :: %{
  required(String.t()) =>
    Jido.AI.Reasoning.TreeOfThoughts.Machine.thought_node()
}
```

Returns all nodes in the tree.

# `get_result`

```elixir
@spec get_result(Jido.Agent.t()) :: map() | nil
```

Returns the solution content (the result).

# `get_solution_path`

```elixir
@spec get_solution_path(Jido.Agent.t()) :: [String.t()]
```

Returns the solution path (list of node IDs from root to solution).

# `llm_partial_action`

```elixir
@spec llm_partial_action() :: :tot_llm_partial
```

Returns the action atom for handling streaming LLM partial tokens.

# `llm_result_action`

```elixir
@spec llm_result_action() :: :tot_llm_result
```

Returns the action atom for handling LLM results.

# `request_error_action`

```elixir
@spec request_error_action() :: :tot_request_error
```

Returns the action atom for handling request rejection events.

# `start_action`

```elixir
@spec start_action() :: :tot_start
```

Returns the action atom for starting a ToT exploration.

# `tool_result_action`

```elixir
@spec tool_result_action() :: :tot_tool_result
```

Returns the action atom for handling tool result events.

---

*Consult [api-reference.md](api-reference.md) for complete listing*