docs/THINKING_MODE_SETUP.md

🧠 Thinking Mode Setup Guide

Overview

Gemini 2.0 Flash introduces thinking mode - the model explicitly "thinks" through problems before responding. This generates higher quality responses for complex tasks like game strategy.

---

🚀 Quick Start

1. Switch to Thinking Model

Option A: Edit config.yaml (Recommended)

llm:
  model_name: "gemini-2.0-flash-thinking-exp"
  enable_thinking: true
  thinking_budget: 16000  # Max tokens for thinking (8k-32k)

Option B: Edit config.py (For default settings)

@dataclass
class LLMConfig:
    model_name: str = "gemini-2.0-flash-thinking-exp"
    enable_thinking: bool = True
    thinking_budget: int = 16000

2. Run Your Game

python play_catan.py

The AI will now use thinking mode automatically!

---

📊 How to Monitor Thinking

In Console Logs

Look for thinking token counts:

✅ Response received: 450 tokens (+1200 thinking), 3.5s

In Log Files

JSON logs (examples/ai_testing/my_games/AI_Agent_1/prompt_1.json):

{
  "tokens": {
    "prompt": 1523,
    "completion": 450,
    "thinking": 1200,
    "total": 3173
  }
}

TXT logs (examples/ai_testing/my_games/AI_Agent_1/prompt_1.txt):

Tokens: prompt=1523, completion=450, thinking=1200, total=3173

In Web Viewer

Visit: http://localhost:5001

The viewer will show:

• 📊 Token breakdown including thinking tokens
• 💰 Cost calculation (thinking tokens = input cost)
• 📈 Thinking usage trends

---

⚙️ Configuration Options

Model Selection

Model	Thinking	Speed	Quality
gemini-2.0-flash-exp	❌	⚡ Fast	Good
gemini-2.0-flash-thinking-exp	✅	🐢 Slower	Better

Thinking Budget

Controls max tokens the model can use for thinking:

thinking_budget: 16000  # Recommended: 8000-32000

• Lower (8k): Faster, less thorough
• Medium (16k): Balanced (default)
• Higher (32k): Slower, more thorough

Enable/Disable

enable_thinking: true   # Turn on thinking mode
enable_thinking: false  # Turn off (faster, cheaper)

---

💰 Cost Impact

Thinking tokens are charged as input tokens:

Example (16k thinking budget):

• Standard mode: ~450 output tokens = $0.000034
• Thinking mode: ~1200 thinking + 450 output = $0.000056

~1.6x cost increase for better decisions 🎯

---

🔍 Viewing the Schema

The response schema is logged in TXT files for debugging:

=== Prompt #1 (Active Turn) ===

--- Response Schema ---
{
  "type": "object",
  "properties": {
    "internal_thinking": {
      "type": "string",
      "description": "Your reasoning process...",
      "minLength": 200
    },
    ...
  }
}

--- Prompt Content ---
{
  "meta_data": { ... }
}

Location: examples/ai_testing/my_games/AI_Agent_1/prompt_N.txt

---

✅ Testing Thinking Mode

Quick Test

1. Edit pycatan/ai/config.py:

   model_name: str = "gemini-2.0-flash-thinking-exp"
   enable_thinking: bool = True
   

2. Run a game:

   python play_catan.py
   

3. Check console output for thinking tokens:

   ✅ Response received: 450 tokens (+1200 thinking), 3.5s
   

4. View logs:

   # Check TXT file
   cat examples/ai_testing/my_games/AI_Agent_1/prompt_1.txt
   
   # Or JSON
   cat examples/ai_testing/my_games/AI_Agent_1/prompt_1.json
   

Web Viewer

cd examples/ai_testing
python web_viewer.py

Visit http://localhost:5001 to see:

• Token breakdowns with thinking
• Cost calculations
• Response quality metrics

---

🐛 Troubleshooting

Not Seeing Thinking Tokens?

1. Check model name: Must be gemini-2.0-flash-thinking-exp
2. Check enable_thinking: Must be true in config
3. Check logs: Look for "enable_thinking" in debug output

Error: "thinking_config not supported"

• Your model doesn't support thinking mode
• Switch to: gemini-2.0-flash-thinking-exp

High Costs?

• Reduce thinking_budget (e.g., 8000)
• Or disable thinking: enable_thinking: false

---

📚 Configuration Files

Location

• Active config: pycatan/ai/config_dev.yaml
• Example: pycatan/ai/config_example.yaml
• Defaults: pycatan/ai/config.py

Priority

1. Config YAML file (if exists)
2. Default values in config.py

---

🎯 Summary

To enable thinking mode:

1. Set model_name: "gemini-2.0-flash-thinking-exp"
2. Set enable_thinking: true
3. Set thinking_budget: 16000 (optional)
4. Run your game
5. Check logs for thinking token counts

Benefits:

• ✅ Better strategic decisions
• ✅ More thorough reasoning
• ✅ Higher quality play

Trade-offs:

• ⏱️ Slower responses (~2-5s)
• 💰 Higher costs (~1.5-2x)