examples/04_think/CONCEPT.md

# Concept: Reasoning & Problem-Solving Agents

## Overview

This example demonstrates how to configure an LLM as a **reasoning agent** capable of analytical thinking and quantitative problem-solving. It shows the bridge between simple text generation and complex cognitive tasks.

## What is a Reasoning Agent?

A **reasoning agent** is an LLM configured to perform logical analysis, mathematical computation, and multi-step problem-solving through careful system prompt design.

### Human Analogy

```

Regular Chat                    Reasoning Agent

─────────────                  ──────────────────

"Can you help me?"            "I am a mathematician.

"Sure! What do you need?"     I analyze problems methodically

                              and compute exact answers."

```

## The Reasoning Challenge

### Why Reasoning is Hard for LLMs

LLMs are trained on text prediction, not explicit reasoning:

```

┌───────────────────────────────────────┐

│  LLM Training                         │

│  "Predict next word in text"         │

│                                       │

│  NOT explicitly trained for:         │

│  • Step-by-step logic                │

│  • Arithmetic computation            │

│  • Tracking multiple variables       │

│  • Systematic problem decomposition  │

└───────────────────────────────────────┘

```

However, they can learn reasoning patterns from training data and be guided by system prompts.

## Reasoning Through System Prompts

### Configuration Pattern

```

┌─────────────────────────────────────────┐

│  System Prompt Components              │

├─────────────────────────────────────────┤

│  1. Role: "Expert reasoner"            │

│  2. Task: "Analyze and solve problems" │

│  3. Method: "Compute exact answers"    │

│  4. Output: "Single numeric value"     │

└─────────────────────────────────────────┘

         ↓

   Reasoning Behavior

```

### Types of Reasoning Tasks

**Quantitative Reasoning (this example):**
```

Problem → Count entities → Calculate → Convert units → Answer

```

**Logical Reasoning:**
```

Premises → Apply rules → Deduce conclusions → Answer

```

**Analytical Reasoning:**
```

Data → Identify patterns → Form hypothesis → Conclude

```

## How LLMs "Reason"

### Pattern Matching vs. True Reasoning

LLMs don't reason like humans, but they can:

```

┌─────────────────────────────────────────────┐

│  What LLMs Actually Do                      │

│                                             │

│  1. Pattern Recognition                     │

│     "This looks like a counting problem"    │

│                                             │

│  2. Template Application                    │

│     "Similar problems follow this pattern"  │

│                                             │

│  3. Statistical Inference                   │

│     "These numbers likely combine this way" │

│                                             │

│  4. Learned Procedures                      │

│     "I've seen this type of calculation"    │

└─────────────────────────────────────────────┘

```

### The Reasoning Process

```

Input: Complex Word Problem

         ↓

    ┌────────────┐

    │   Parse    │  Identify entities and relationships

    └────────────┘

         ↓

    ┌────────────┐

    │  Decompose │  Break into sub-problems

    └────────────┘

         ↓

    ┌────────────┐

    │  Calculate │  Apply arithmetic operations

    └────────────┘

         ↓

    ┌────────────┐

    │  Synthesize│  Combine results

    └────────────┘

         ↓

     Final Answer

```

## Problem Complexity Hierarchy

### Levels of Reasoning Difficulty

```

Easy                                        Hard

│                                             │

│  Simple    Multi-step   Nested    Implicit │

│  Arithmetic  Logic    Conditions  Reasoning│

│                                             │

└─────────────────────────────────────────────┘



Examples:

Easy:    "What is 5 + 3?"

Medium:  "If 3 apples cost $2 each, what's the total?"

Hard:    "Count family members with complex relationships"

```

### This Example's Complexity

The potato problem is **highly complex**:

```

┌─────────────────────────────────────────┐

│  Complexity Factors                     │

├─────────────────────────────────────────┤

│  ✓ Multiple entities (15+ people)      │

│  ✓ Relationship reasoning (family tree)│

│  ✓ Conditional logic (if married then..)│

│  ✓ Negative conditions (deceased people)│

│  ✓ Special cases (dietary restrictions)│

│  ✓ Multiple calculations                │

│  ✓ Unit conversions                     │

└─────────────────────────────────────────┘

```

## Limitations of Pure LLM Reasoning

### Why This Approach Has Issues

```

┌────────────────────────────────────┐

│  Problem: No External Tools        │

│                                    │

│  LLM must hold everything in       │

│  "mental" context:                 │

│  • All entity counts               │

│  • Intermediate calculations       │

│  • Conversion factors              │

│  • Final arithmetic                │

│                                    │

│  Result: Prone to errors           │

└────────────────────────────────────┘

```

### Common Failure Modes

**1. Counting Errors:**
```

Problem: "Count 15 people with complex relationships"

LLM: "14" or "16" (off by one)

```

**2. Arithmetic Mistakes:**
```

Problem: "13 adults × 1.5 + 3 kids × 0.5"

LLM: May get intermediate steps wrong

```

**3. Lost Context:**
```

Problem: Multi-step with many facts

LLM: Forgets earlier information

```

## Improving Reasoning: Evolution Path

### Level 1: Pure Prompting (This Example)
```

User → LLM → Answer

       ↑

   System Prompt

```

**Limitations:**
- All reasoning internal to LLM
- No verification
- No tools
- Hidden process

### Level 2: Chain-of-Thought
```

User → LLM → Show Work → Answer

       ↑

   "Explain your reasoning"

```

**Improvements:**
- Visible reasoning steps
- Can catch some errors
- Still no tools

### Level 3: Tool-Augmented (simple-agent)
```

User → LLM ⟷ Tools → Answer

       ↑    (Calculator)

   System Prompt

```

**Improvements:**
- External computation
- Reduced errors
- Verifiable steps

### Level 4: ReAct Pattern (react-agent)
```

User → LLM → Think → Act → Observe

       ↑      ↓      ↓      ↓

   System  Reason  Tool   Result

   Prompt         Use

       ↑           ↓       ↓

       └───────────Iterate──┘

```

**Best approach:**
- Explicit reasoning loop
- Tool use at each step
- Self-correction possible

## System Prompt Design for Reasoning

### Key Elements

**1. Role Definition:**
```

"You are an expert logical and quantitative reasoner"

```
Sets the mental framework.

**2. Task Specification:**
```

"Analyze real-world word problems involving..."

```
Defines the problem domain.

**3. Output Format:**
```

"Return the correct final number as a single value"

```
Controls response structure.

### Design Patterns

**Pattern A: Direct Answer (This Example)**
```

Prompt: [Problem]

Output: [Number]

```
Pros: Concise, fast
Cons: No insight into reasoning

**Pattern B: Show Work**
```

Prompt: [Problem] "Show your steps"

Output: Step 1: ... Step 2: ... Answer: [Number]

```
Pros: Transparent, debuggable
Cons: Longer, may still have errors

**Pattern C: Self-Verification**
```

Prompt: [Problem] "Solve, then verify"

Output: Solution + Verification + Final Answer

```
Pros: More reliable
Cons: Slower, uses more tokens

## Real-World Applications

### Use Cases for Reasoning Agents

**1. Data Analysis:**
```

Input: Dataset summary

Task: Compute statistics, identify trends

Output: Numerical insights

```

**2. Planning:**
```

Input: Goal + constraints

Task: Reason about optimal sequence

Output: Action plan

```

**3. Decision Support:**
```

Input: Options + criteria

Task: Evaluate and compare

Output: Recommended choice

```

**4. Problem Solving:**
```

Input: Complex scenario

Task: Break down and solve

Output: Solution

```

## Comparison: Different Agent Types

```

                  Reasoning  Tools  Memory  Multi-turn

                  ─────────  ─────  ──────  ──────────

intro.js              ✗        ✗      ✗        ✗

translation.js        ~        ✗      ✗        ✗

think.js (here)       ✓        ✗      ✗        ✗

simple-agent.js       ✓        ✓      ✗        ~

memory-agent.js       ✓        ✓      ✓        ✓

react-agent.js        ✓✓       ✓      ~        ✓

```

Legend:
- ✗ = Not present
- ~ = Limited/implicit
- ✓ = Present
- ✓✓ = Advanced/explicit

## Key Takeaways

1. **System prompts enable reasoning**: Proper configuration transforms an LLM into a reasoning agent
2. **Limitations exist**: Pure LLM reasoning is prone to errors on complex problems
3. **Tools help**: External computation (calculators, etc.) improves accuracy
4. **Iteration matters**: Multi-step reasoning patterns (like ReAct) work better
5. **Transparency is valuable**: Seeing the reasoning process helps debug and verify

## Next Steps

After understanding basic reasoning:
- **Add tools**: Let the agent use calculators, databases, APIs
- **Implement verification**: Check answers, retry on errors
- **Use chain-of-thought**: Make reasoning explicit
- **Apply ReAct pattern**: Combine reasoning and tool use systematically

This example is the foundation for more sophisticated agent architectures that combine reasoning with external capabilities.