Pure state machine for the Graph-of-Thoughts (GoT) reasoning pattern.

This module implements state transitions for a GoT agent without any side effects. It uses Fsmx for state machine management and returns directives that describe what external effects should be performed.

Overview

Graph-of-Thoughts extends Tree-of-Thoughts by allowing nodes to have multiple parents and supporting merging/aggregation of thoughts. This enables more complex reasoning patterns like combining insights from different branches.

States

• :idle - Initial state, waiting for a prompt
• :generating - Generating a thought for the current context
• :connecting - Finding connections between nodes
• :aggregating - Aggregating multiple nodes into one
• :completed - Final state, solution found
• :error - Error state

Graph Structure

The graph is stored as nodes and edges:

%{
  nodes: %{
    "node_1" => %{
      id: "node_1",
      content: "Initial problem...",
      score: nil,
      depth: 0,
      metadata: %{}
    },
    ...
  },
  edges: [
    %{from: "node_1", to: "node_2", type: :generates},
    %{from: "node_2", to: "node_3", type: :refines},
    ...
  ]
}

Edge Types

• :generates - Parent thought generates child thought
• :refines - Refinement of existing thought
• :aggregates - Multiple thoughts aggregated into one
• :connects - Conceptual connection between thoughts

Usage

The machine is used by the GoT strategy:

machine = Machine.new()
{machine, directives} = Machine.update(machine, {:start, prompt, call_id}, env)

All state transitions are pure - side effects are described in directives.

Status Type Boundary

Internal (Machine struct): Status is stored as strings ("idle", "completed") due to Fsmx library requirements.

External (Strategy state, Snapshots): Status is converted to atoms (:idle, :completed) via to_map/1 before storage in agent state.

Never compare machine.status directly with atoms - use Machine.to_map/1 first.