examples/10_aot-agent/CONCEPT.md

# Concept: Atom of Thought (AoT) Pattern for AI Agents

## The Core Idea

**Atom of Thought = "SQL for Reasoning"**

Just as SQL breaks complex data operations into atomic, composable statements, AoT breaks reasoning into minimal, executable steps.

## What is an Atom?

An atom is the **smallest unit of reasoning** that:
1. Expresses exactly **one** idea
2. Can be **validated independently**
3. Can be **executed deterministically**
4. **Cannot hide** a mistake

### Examples

❌ **Not atomic** (compound statement):
```
"Search for rooms in Graz and filter by capacity"
```

✅ **Atomic** (separate steps):
```
1. Search for rooms in Graz
2. Filter rooms by minimum capacity of 30
```

## The Three Layers
```
┌─────────────────────────────────┐
│   LLM (Planning Layer)          │
│   - Proposes atomic plan        │
│   - Does NOT execute            │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   Validator (Safety Layer)      │
│   - Checks plan structure       │
│   - Validates dependencies      │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   Executor (Execution Layer)    │
│   - Runs atoms deterministically│
│   - Manages state               │
└─────────────────────────────────┘
```

## Why Separation Matters

### Traditional LLM Approach (ReAct)
```
LLM thinks → LLM acts → LLM thinks → LLM acts
```
**Problem:** Execution logic lives inside the model (black box)

### Atom of Thought Approach
```
LLM plans → System validates → System executes
```
**Benefit:** Execution logic lives in code (white box)

## Mental Model

Think of AoT as the difference between:

| Cooking | Programming |
|---------|------------|
| **Recipe** (AoT plan) | **Algorithm** |
| "Boil water" | `boilWater()` |
| "Add pasta" | `addPasta()` |
| "Cook 8 minutes" | `cook(8)` |

vs.

| Improvising | Natural Language |
|-------------|------------------|
| "Make dinner" | "Figure it out" |
| (figure it out) | (hallucinate) |

## The Atom Structure
```javascript
{
  "id": 2,
  "kind": "tool",           // tool | decision | final
  "name": "multiply",       // operation name
  "input": {                // explicit inputs
    "a": "<result_of_1>",   // reference to previous result
    "b": 3
  },
  "dependsOn": [1]          // must wait for atom 1
}
```

**Why this structure?**
- `id`: Establishes order
- `kind`: Categorizes operation type
- `name`: References executable function
- `input`: Makes data flow explicit
- `dependsOn`: Declares dependencies

## Dependency Graph

Atoms form a **directed acyclic graph (DAG)**:
```
     ┌─────┐
     │  1  │ add(15, 7)
     └──┬──┘
        │
     ┌──▼──┐
     │  2  │ multiply(result_1, 3)
     └──┬──┘
        │
     ┌──▼──┐
     │  3  │ subtract(result_2, 10)
     └──┬──┘
        │
     ┌──▼──┐
     │  4  │ final
     └─────┘
```

**Properties:**
- Can be executed in topological order
- Can parallelize independent branches
- Failures stop at failed node
- Easy to visualize and debug

## State Management
```javascript
const state = {};

// After atom 1
state[1] = 22;  // result of add(15, 7)

// After atom 2
state[2] = 66;  // result of multiply(22, 3)

// After atom 3
state[3] = 56;  // result of subtract(66, 10)
```

**State is:**
- Explicit (key-value map)
- Immutable per atom (no overwrites)
- Traceable (full history)
- Inspectable (debugging)

## Comparison: AoT vs ReAct

### Question: "What is (15 + 7) × 3 - 10?"

#### ReAct Output (text):
```
Thought: I need to add 15 and 7 first
Action: add(15, 7)
Observation: 22
Thought: Now multiply by 3
Action: multiply(22, 3)
Observation: 66
Thought: Finally subtract 10
Action: subtract(66, 10)
Observation: 56
Answer: 56
```

#### AoT Output (JSON):
```json
{
  "atoms": [
    {"id": 1, "kind": "tool", "name": "add", "input": {"a": 15, "b": 7}},
    {"id": 2, "kind": "tool", "name": "multiply", "input": {"a": "<result_of_1>", "b": 3}, "dependsOn": [1]},
    {"id": 3, "kind": "tool", "name": "subtract", "input": {"a": "<result_of_2>", "b": 10}, "dependsOn": [2]},
    {"id": 4, "kind": "final", "name": "report", "dependsOn": [3]}
  ]
}
```

### Key Differences

| Aspect | ReAct | AoT |
|--------|-------|-----|
| **Format** | Natural language | Structured data |
| **Validation** | Impossible | Before execution |
| **Testing** | Mock entire LLM | Test executor independently |
| **Debugging** | Read through text | Inspect atom N |
| **Replay** | Re-run entire conversation | Re-run from any atom |
| **Audit trail** | Conversational history | Data structure |

## When AoT Shines

### ✅ Perfect for:
- **Multi-step workflows** (booking, pipelines)
- **API orchestration** (call A, then B with A's result)
- **Financial transactions** (auditable, reversible)
- **Compliance-sensitive systems** (every step logged)
- **Production agents** (failures must be clean)

### ❌ Not ideal for:
- **Creative writing**
- **Open-ended exploration**
- **Brainstorming**
- **Single-step queries**

## Real-World Analogy

**ReAct is like a chef improvising:**
- Flexible
- Creative
- Hard to replicate exactly
- Mistakes hidden in process

**AoT is like following a recipe:**
- Repeatable
- Testable
- Step X failed? Start from step X-1
- Every ingredient and action is explicit

## The Hidden Benefit: Debuggability

When something goes wrong:

**ReAct:**
```
"The model said something weird in iteration 7"
→ Re-read entire conversation
→ Guess where it went wrong
→ Hope it doesn't happen again
```

**AoT:**
```
"Atom 3 failed with 'Division by zero'"
→ Look at atom 3's inputs
→ Check where those inputs came from (atom 1, 2)
→ Fix tool or add validation
→ Re-run from atom 3
```

## Implementation Checklist

✅ **LLM side:**
- [ ] System prompt enforces JSON output
- [ ] Grammar constrains to valid schema
- [ ] Atoms are minimal (one operation each)
- [ ] Dependencies are explicit

✅ **System side:**
- [ ] Validator checks tool names
- [ ] Validator checks dependencies
- [ ] Executor resolves references
- [ ] Executor is deterministic
- [ ] State is immutable

## The Bottom Line

**ReAct asks:**
"What would an intelligent agent say next?"

**AoT asks:**
"What is the minimal, executable plan?"

For production systems, you want the second question.