create plan and config

.env.example

@@ -0,0 +1,65 @@
+# ============================================================================
+# Environment Variables Template for PyCatan AI
+# ============================================================================
+# This file is a TEMPLATE - it will be committed to Git.
+# Copy this file to .env and fill in your actual API keys.
+#
+# SETUP INSTRUCTIONS:
+# 1. Copy this file: cp .env.example .env
+# 2. Edit .env and paste your actual API keys
+# 3. NEVER commit the .env file to Git!
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# LLM API Keys
+# ----------------------------------------------------------------------------
+# Get your API keys from:
+# - Gemini: https://aistudio.google.com/app/apikey
+# - OpenAI: https://platform.openai.com/api-keys
+# - Anthropic: https://console.anthropic.com/settings/keys
+
+# Google Gemini API Key (recommended for development)
+GEMINI_API_KEY=
+
+# OpenAI API Key (optional)
+OPENAI_API_KEY=
+
+# Anthropic Claude API Key (optional)
+ANTHROPIC_API_KEY=
+
+# Azure OpenAI (optional)
+AZURE_OPENAI_KEY=
+AZURE_OPENAI_ENDPOINT=
+
+# ----------------------------------------------------------------------------
+# Optional: LLM Configuration Overrides
+# ----------------------------------------------------------------------------
+# You can override default settings via environment variables
+
+# Default LLM provider (gemini, openai, anthropic, azure)
+# DEFAULT_LLM_PROVIDER=gemini
+
+# Default model name
+# DEFAULT_MODEL_NAME=gemini-2.0-flash-exp
+
+# Default temperature (0.0 to 2.0)
+# DEFAULT_TEMPERATURE=0.7
+
+# ----------------------------------------------------------------------------
+# Development Settings
+# ----------------------------------------------------------------------------
+
+# Enable debug mode for detailed logging
+# DEBUG_MODE=false
+
+# Log directory
+# LOG_DIRECTORY=logs/ai_agents
+
+# ----------------------------------------------------------------------------
+# Notes
+# ----------------------------------------------------------------------------
+# - The .env file is ignored by Git (see .gitignore)
+# - Never share your .env file or commit it to version control
+# - Keep your API keys secret and rotate them regularly
+# - Each developer should have their own .env file with their own keys
+# ============================================================================

.github/instructions/AI_AGENT_PRINCIPLES.md

@@ -0,0 +1,210 @@
+# 🎮 AI Agent Design Principles
+
+**Date:** January 3, 2026  
+**Status:** 📋 In Planning
+
+## 🎯 Core Philosophy: "Give Tools and Let Go"
+
+The AI agent architecture follows a **tool-based autonomy approach** where we provide the agent with:
+- Rich game state context
+- Available tools and actions
+- Clear constraints and rules
+- Memory management capabilities
+
+Then we **let the agent play** - making its own decisions based on the context and available options.
+
+---
+
+## 🏗️ Architecture Principles
+
+### 1️⃣ Event-Driven LLM Invocation
+
+The agent calls the LLM under specific scenarios:
+- **Game Events**: Something happened in the game that affects the agent
+- **Action Required**: The agent must make a decision (build, trade, play card, etc.)
+- **Social Interaction**: Another player sent a message or made an offer
+- **Turn Changes**: Beginning or end of turn phases
+
+The agent doesn't continuously "think" - it responds to events and prompts.
+
+### 2️⃣ Self-Managed Memory
+
+The agent maintains its own memory in a simple, accessible format:
+- **Short-term memory**: Recent events and observations
+- **Strategic notes**: Things to remember for future decisions
+- **Social tracking**: Observations about other players' behavior
+- **Game insights**: Patterns noticed during play
+
+The memory structure is minimal but effective, allowing the agent to maintain context across turns.
+
+### 3️⃣ Generic and Configurable Design
+
+The agent implementation should be:
+- **Modular**: Easy to swap components or strategies
+- **Configurable**: Support different play styles and behaviors
+- **Extensible**: Simple to add new capabilities or tools
+- **Reusable**: Same base agent class for different AI personalities
+
+This allows experimentation with different AI approaches without rewriting core logic.
+
+### 4️⃣ Centralized Configuration
+
+All critical parameters are managed in one place:
+- **LLM Configuration**: Model selection, temperature, max tokens
+- **API Credentials**: Keys and endpoints for LLM services
+- **Agent Parameters**: Personality traits, risk tolerance, strategy preferences
+- **Performance Settings**: Timeout limits, retry policies, caching options
+
+This centralization simplifies tuning and experimentation.
+
+---
+
+## 📨 Prompt Processing Pipeline
+
+### Context Filtering and Preparation
+
+Before sending prompts to the agent, game state undergoes processing:
+
+1. **Information Hiding**: Remove data the player shouldn't know
+   - Other players' cards and resources (unless revealed)
+   - Hidden development cards
+   - Future planned moves by other players
+
+2. **Perspective Adaptation**: Present information from agent's viewpoint
+   - "You received 1 Wood" instead of "Player Blue received 1 Wood"
+   - "Your resources" vs "Player resources"
+   - Relative positioning and strategic context
+
+3. **Custom Instructions**: Tailor prompts per agent instance
+   - Different personality instructions
+   - Unique strategic guidance
+   - Role-specific context
+
+4. **Context Enrichment**: Add relevant computed information
+   - Tile probabilities (based on dice numbers)
+   - Resource scarcity analysis
+   - Build opportunity assessment
+
+### Management Layer
+
+A **prompt management layer** sits between GameManager and AI agents to:
+- Transform raw game state into agent-specific context
+- Filter and format information appropriately
+- Handle simultaneous different messages to different agents
+- Manage conversation history and memory updates
+
+---
+
+## 📋 Prompt Structure Principles
+
+Based on the format in `promt_format.text`, prompts follow this structure:
+
+### Core Components:
+
+1. **Meta Data**: Agent identity and role
+   - Agent name/identifier
+   - Player color
+   - Personality or role description
+
+2. **Task Context**: Current situation
+   - What just happened in the game
+   - What action is now required
+   - Instructions for decision-making
+
+3. **Game State**: World information from agent perspective
+   - Agent's private information (resources, cards, points)
+   - Visible board state
+   - Other players' public information
+
+4. **Social Context**: Communication and relationships
+   - Recent chat messages
+   - Trade offers and negotiations
+   - Historical summaries of interactions
+
+5. **Memory**: Agent's self-maintained notes
+   - Strategic observations
+   - Plans and intentions
+   - Social dynamics tracking
+
+6. **Constraints**: Available actions and rules
+   - List of allowed actions at this moment
+   - Parameter structure for each action
+   - Usage instructions and examples
+
+### Flexibility Note:
+While this structure provides a solid foundation, it should remain **adaptable**. Specific fields and formats may evolve as we test and refine the agent's performance.
+
+---
+
+## 🔄 Structured Response Format
+
+The LLM response is **strictly structured** to enable programmatic processing:
+
+### Response Components:
+
+1. **Reasoning**: Agent's thought process (for debugging/logging)
+   - Current situation analysis
+   - Strategic considerations
+   - Decision rationale
+
+2. **Selected Action**: The chosen action with parameters
+   - Action type (BUILD_ROAD, OFFER_TRADE, etc.)
+   - Required parameters for that action
+   - Validation-ready format
+
+3. **Communication**: Optional message to other players
+   - Chat message content
+   - Target audience (all or specific player)
+
+4. **Memory Update**: What to remember for next time
+   - New notes to add
+   - Observations to store
+   - Strategy adjustments
+
+### Example Response Structure:
+```json
+{
+  "reasoning": "I have enough resources for a settlement and node 23 gives me access to wheat...",
+  "action": {
+    "type": "BUILD_SETTLEMENT",
+    "parameters": {
+      "node_id": 23
+    }
+  },
+  "chat_message": "Building near the wheat fields!",
+  "memory_update": {
+    "add_note": "Focused on wheat production for development cards"
+  }
+}
+```
+
+This structured format allows the game loop to:
+- Parse and validate the agent's decision
+- Execute the action through GameManager
+- Update agent memory automatically
+- Continue the game flow seamlessly
+
+---
+
+## 🔧 Tool Integration
+
+Agents have access to computational tools for enhanced decision-making:
+
+- **Probability Calculator**: Dice roll probabilities for tiles
+- **Resource Tracker**: Historical resource generation analysis  
+- **Path Finder**: Optimal road placement calculations
+- **Trade Evaluator**: Fair trade assessment
+
+**Tool Usage Limits**: To prevent excessive computation, agents are limited in tool calls per decision (e.g., maximum 3 tool executions).
+
+---
+
+## 🎭 Multi-Agent Considerations
+
+When multiple AI agents play simultaneously:
+- Each receives their own filtered game state
+- Agents can negotiate with each other
+- Social dynamics emerge naturally from LLM interactions
+- No direct agent-to-agent communication (all goes through game system)
+
+This creates emergent gameplay where AI strategies adapt to each other's behavior.

.github/instructions/WORK_PLAN.md

@@ -0,0 +1,484 @@
+# 🗺️ AI Agent Development Work Plan
+
+**Date:** January 3, 2026  
+**Status:** 📋 Planning Phase
+
+## 🎯 Project Goal
+
+Build a fully functional LLM-based AI agent that can play Settlers of Catan autonomously, making intelligent strategic decisions and interacting naturally with other players.
+
+---
+
+## 📊 Development Phases
+
+> **Note:** Phase 4 (Monitoring & Debugging) should be developed **early and in parallel** with Phase 3.  
+> The web dashboard and logging are **critical** for observing agent behavior during development!
+
+### Phase 1: Foundation & Infrastructure 🏗️
+**Goal:** Build the core infrastructure needed to support AI agents
+
+#### 1.1 Configuration Management
+- [ ] Create centralized configuration system
+  - [ ] LLM settings (model, temperature, max_tokens, etc.)
+  - [ ] API credentials management
+  - [ ] Agent parameters (personality, risk tolerance, etc.)
+  - [ ] Performance settings (timeouts, retries, caching)
+- [ ] Create config file format (YAML/JSON)
+- [ ] Build configuration loader and validator
+- [ ] Add environment variable support for sensitive data
+
+**Files to create:**
+- `pycatan/ai/config.py` - Configuration management
+- `pycatan/ai/config_example.yaml` - Example configuration file
+
+---
+
+#### 1.2 Prompt Management Layer
+- [ ] Design prompt processing pipeline
+- [ ] Implement game state filtering
+  - [ ] Hide opponent's private information
+  - [ ] Filter development cards
+  - [ ] Remove non-visible game elements
+- [ ] Build perspective transformation
+  - [ ] Convert game state to agent's viewpoint
+  - [ ] Format resources and points
+  - [ ] Present relative positioning
+- [ ] Create prompt template system
+  - [ ] Meta data section
+  - [ ] Task context section
+  - [ ] Game state section
+  - [ ] Social context section
+  - [ ] Memory section
+  - [ ] Constraints section
+- [ ] Build custom instruction injection per agent
+
+**Files to create:**
+- `pycatan/ai/prompt_manager.py` - Main prompt processing
+- `pycatan/ai/state_filter.py` - Game state filtering logic
+- `pycatan/ai/prompt_templates.py` - Template definitions
+
+---
+
+#### 1.3 Response Parser
+- [ ] Define structured response format (JSON schema)
+- [ ] Build response parser and validator
+- [ ] Implement error handling for malformed responses
+- [ ] Create fallback mechanisms for parsing failures
+- [ ] Add response logging for debugging
+
+**Files to create:**
+- `pycatan/ai/response_parser.py` - Parse and validate LLM responses
+- `pycatan/ai/schemas.py` - JSON schemas for requests/responses
+
+---
+
+### Phase 2: Memory System 🧠
+**Goal:** Enable agents to maintain context and learning across turns
+
+#### 2.1 Memory Structure
+- [ ] Design memory data model
+  - [ ] Short-term observations (last N turns)
+  - [ ] Strategic notes (persistent)
+  - [ ] Social tracking (player relationships)
+  - [ ] Game insights (patterns observed)
+- [ ] Implement memory storage (in-memory for now)
+- [ ] Build memory retrieval and formatting
+
+**Files to create:**
+- `pycatan/ai/memory.py` - Memory management system
+
+---
+
+#### 2.2 Memory Operations
+- [ ] Add note creation and updates
+- [ ] Implement memory pruning (keep relevant, remove old)
+- [ ] Build memory summarization for context limits
+- [ ] Create memory persistence (save/load between games)
+
+---
+
+#### 2.3 Chat History Summarization ⚡
+- [ ] Implement automatic chat summarization
+  - [ ] Configure separate smaller LLM for summarization (cost-effective)
+  - [ ] Monitor chat history length (e.g., last 10 messages)
+  - [ ] Trigger summarization when threshold reached
+  - [ ] Create summarization prompt template
+- [ ] Build chat memory management
+  - [ ] Keep only most recent message after summarization
+  - [ ] Store summary in agent's memory
+  - [ ] Maintain summary history for context
+- [ ] Add configuration for summarization settings
+  - [ ] Summarization model selection
+  - [ ] Message threshold for triggering
+  - [ ] Summary format and length
+
+**Files to update:**
+- `pycatan/ai/memory.py` - Add chat summarization logic
+- `pycatan/ai/config.py` - Add summarization configuration
+- `pycatan/ai/llm_client.py` - Support multiple models (main + summarization)
+
+---
+
+### Phase 3: Core AI Agent 🤖
+**Goal:** Implement the main AI agent class
+
+#### 3.1 Base Agent Implementation
+- [ ] Create `AIAgent` class inheriting from `User`
+- [ ] Implement required User interface methods
+  - [ ] `get_choice()` for decision-making
+  - [ ] Other interaction methods as needed
+- [ ] Integrate with prompt manager
+- [ ] Integrate with memory system
+- [ ] Add agent state management
+
+**Files to create:**
+- `pycatan/players/ai_agent.py` - Main AI agent implementation (update existing stub)
+
+---
+
+#### 3.2 LLM Integration
+- [ ] Create LLM client abstraction
+  - [ ] Support for OpenAI API
+  - [ ] Support for Anthropic Claude
+  - [ ] Support for other providers (Azure, etc.)
+- [ ] Implement API call handling
+  - [ ] Request formatting
+  - [ ] Response parsing
+  - [ ] Error handling and retries
+  - [ ] Rate limiting
+- [ ] Add logging for all LLM interactions
+- [ ] Implement cost tracking
+
+**Files to create:**
+- `pycatan/ai/llm_client.py` - LLM API abstraction
+- `pycatan/ai/providers/` - Provider-specific implementations
+  - `openai_provider.py`
+  - `anthropic_provider.py`
+
+---
+
+#### 3.3 Decision Pipeline
+- [ ] Build event-to-prompt conversion
+- [ ] Implement action extraction from responses
+- [ ] Create action validation before execution
+- [ ] Add decision logging and debugging
+- [ ] Implement decision timeout handling
+
+---
+
+### Phase 4: Monitoring & Debugging Infrastructure 🔍
+**Goal:** Build essential tools for observing and debugging agent behavior
+
+**⚠️ CRITICAL: These tools are essential for development and must be built early!**
+
+---
+
+#### 4.1 Web Dashboard for Real-Time Monitoring 🌐
+**Priority: HIGH - Required before agent testing**
+
+- [ ] Design web dashboard UI
+  - [ ] Multi-agent view (tabs or split screen per agent)
+  - [ ] Live prompt display with syntax highlighting
+  - [ ] Agent reasoning/thinking display
+  - [ ] Action selection visualization
+  - [ ] Chat window with all messages
+  - [ ] Game state summary panel
+- [ ] Build backend API for dashboard
+  - [ ] WebSocket connection for live updates
+  - [ ] Endpoints for prompt/response history
+  - [ ] Agent state endpoints
+  - [ ] Chat history endpoint
+- [ ] Implement prompt logging and streaming
+  - [ ] Capture all prompts sent to LLM
+  - [ ] Capture all responses from LLM
+  - [ ] Stream to dashboard in real-time
+  - [ ] Format for readability
+- [ ] Build agent reasoning viewer
+  - [ ] Display internal_thinking/reasoning
+  - [ ] Show action selection process
+  - [ ] Highlight tool usage
+  - [ ] Show memory updates
+
+**Files to create:**
+- `pycatan/monitoring/` - NEW monitoring package
+  - `dashboard_server.py` - Flask/FastAPI server for dashboard
+  - `event_logger.py` - Captures and broadcasts events
+  - `prompt_tracker.py` - Tracks all LLM interactions
+- `pycatan/monitoring/web/` - Dashboard frontend
+  - `index.html` - Main dashboard page
+  - `dashboard.js` - Dashboard functionality
+  - `dashboard.css` - Dashboard styling
+
+---
+
+#### 4.2 Local Documentation & Logging 📁
+**Priority: HIGH - Required for debugging**
+
+- [ ] Design local documentation structure
+  - [ ] One folder per game session
+  - [ ] One file per agent with structured log
+  - [ ] Timestamp-based organization
+- [ ] Implement per-agent documentation
+  - [ ] Agent configuration snapshot
+  - [ ] All prompts sent (formatted)
+  - [ ] All responses received (formatted)
+  - [ ] Decision timeline with reasoning
+  - [ ] Memory state snapshots
+  - [ ] Tool usage log
+  - [ ] Errors and warnings
+- [ ] Build structured logging format
+  - [ ] JSON-based for easy parsing
+  - [ ] Markdown reports for human reading
+  - [ ] Searchable and filterable
+- [ ] Add game session documentation
+  - [ ] Game state at each turn
+  - [ ] All chat messages with timestamps
+  - [ ] Final game results and statistics
+
+**Files to create:**
+- `pycatan/monitoring/local_logger.py` - Local file logging
+- `pycatan/monitoring/session_recorder.py` - Game session recording
+- `pycatan/monitoring/report_generator.py` - Generate readable reports
+
+**Output structure:**
+```
+logs/
+└── game_sessions/
+    └── 2026-01-03_15-30-45/
+        ├── game_summary.json
+        ├── chat_log.txt
+        ├── agent_blue/
+        │   ├── config.json
+        │   ├── prompts.log
+        │   ├── decisions.log
+        │   └── memory_snapshots.json
+        ├── agent_red/
+        │   └── ...
+        └── agent_white/
+            └── ...
+```
+
+---
+
+#### 4.3 Chat Management System 💬
+**Priority: HIGH - Core game feature**
+
+- [ ] Design chat system architecture
+  - [ ] Centralized chat manager
+  - [ ] Message routing between players
+  - [ ] Chat history per game
+  - [ ] Public vs private messages
+- [ ] Implement chat manager component
+  - [ ] Message queue/buffer
+  - [ ] Broadcast to all players
+  - [ ] Direct messages between players
+  - [ ] Integration with GameManager
+- [ ] Build chat observation interface
+  - [ ] Real-time chat display in web dashboard
+  - [ ] Chat log export
+  - [ ] Filter by sender/time
+- [ ] Define chat protocol
+  - [ ] Message format (sender, content, timestamp, type)
+  - [ ] Chat commands (if any)
+  - [ ] Trade negotiation messages
+
+**Files to create:**
+- `pycatan/management/chat_manager.py` - Central chat management
+- `pycatan/management/message.py` - Message data structure
+
+**Integration points:**
+- GameManager receives messages from players
+- ChatManager distributes to other players and dashboard
+- AI agents see messages in their prompt context
+- Web dashboard shows live chat
+- Local logs record all messages
+
+---
+
+### Phase 5: Tool System 🔧
+**Goal:** Provide computational tools for agent decision-making
+
+#### 5.1 Core Tools
+- [ ] **Probability Calculator**
+  - [ ] Dice roll probabilities for tiles
+  - [ ] Expected resource generation rates
+  - [ ] Statistical analysis helpers
+- [ ] **Resource Tracker**
+  - [ ] Historical resource generation
+  - [ ] Resource scarcity analysis
+  - [ ] Production trend analysis
+- [ ] **Path Finder**
+  - [ ] Optimal road placement
+  - [ ] Longest road calculation
+  - [ ] Connectivity analysis
+- [ ] **Trade Evaluator**
+  - [ ] Fair trade assessment
+  - [ ] Trade benefit calculation
+  - [ ] Market value estimation
+
+**Files to create:**
+- `pycatan/ai/tools/` - Tool implementations
+  - `probability_tool.py`
+  - `resource_tool.py`
+  - `pathfinding_tool.py`
+  - `trade_tool.py`
+  - `tool_manager.py` - Tool orchestration
+
+---
+
+#### 5.2 Tool Integration
+- [ ] Define tool interface/protocol
+- [ ] Implement tool calling from prompts
+- [ ] Add tool usage limits per decision
+- [ ] Create tool result formatting
+- [ ] Build tool usage logging
+
+---
+
+### Phase 6: Testing & Validation ✅
+**Goal:** Ensure agent works correctly and plays reasonably
+
+#### 6.1 Unit Tests
+- [ ] Test prompt manager filtering
+- [ ] Test response parser with various inputs
+- [ ] Test memory operations
+- [ ] Test each tool independently
+- [ ] Test configuration loading
+
+**Files to create:**
+- `tests/unit/test_ai_agent.py`
+- `tests/unit/test_prompt_manager.py`
+- `tests/unit/test_memory.py`
+- `tests/unit/test_tools.py`
+
+---
+
+#### 6.2 Integration Tests
+- [ ] Test agent in complete game loop
+- [ ] Test agent vs human player
+- [ ] Test multiple AI agents playing together
+- [ ] Test edge cases and error scenarios
+- [ ] Test long-running games (memory management)
+
+**Files to create:**
+- `tests/integration/test_ai_gameplay.py`
+- `tests/integration/test_multi_agent.py`
+
+---
+
+#### 6.3 Gameplay Validation
+- [ ] Verify legal moves only
+- [ ] Check strategic decision quality
+- [ ] Evaluate social interaction naturalness
+- [ ] Monitor LLM costs and performance
+- [ ] Collect agent behavior metrics
+
+---
+
+### Phase 7: Optimization & Enhancement 🚀
+**Goal:** Improve agent performance and capabilities
+
+#### 7.1 Performance Optimization
+- [ ] Reduce prompt token usage
+- [ ] Implement response caching for similar situations
+- [ ] Optimize tool execution
+- [ ] Improve decision speed
+
+---
+
+#### 7.2 Strategy Enhancement
+- [ ] Tune agent personalities
+- [ ] Improve opening game strategy
+- [ ] Enhance mid-game adaptation
+- [ ] Refine end-game tactics
+- [ ] Better negotiation and trading
+
+---
+
+#### 7.3 Advanced Features
+- [ ] Multi-turn planning capability
+- [ ] Opponent modeling
+- [ ] Meta-strategy learning
+- [ ] Tournament play support
+- [ ] Statistical performance tracking
+
+---
+
+## 📁 Project Structure (Proposed)
+
+```
+pycatan/
+├── ai/                          # NEW: AI agent infrastructure
+│   ├── __init__.py
+│   ├── config.py                # Configuration management
+│   ├── prompt_manager.py        # Prompt processing pipeline
+│   ├── state_filter.py          # Game state filtering
+│   ├── prompt_templates.py      # Prompt templates
+│   ├── response_parser.py       # Response parsing
+│   ├── schemas.py               # JSON schemas
+│   ├── memory.py                # Memory system + chat summarization
+│   ├── llm_client.py            # LLM abstraction (multi-model)
+│   ├── providers/               # LLM provider implementations
+│   │   ├── __init__.py
+│   │   ├── openai_provider.py
+│   │   └── anthropic_provider.py
+│   └── tools/                   # Agent tools
+│       ├── __init__.py
+│       ├── tool_manager.py
+│       ├── probability_tool.py
+│       ├── resource_tool.py
+│       ├── pathfinding_tool.py
+│       └── trade_tool.py
+├── monitoring/                  # NEW: Monitoring & debugging
+│   ├── __init__.py
+│   ├── dashboard_server.py      # Web dashboard backend
+│   ├── event_logger.py          # Event capture and broadcast
+│   ├── prompt_tracker.py        # LLM interaction tracking
+│   ├── local_logger.py          # Local file logging
+│   ├── session_recorder.py      # Game session recording
+│   ├── report_generator.py      # Report generation
+│   └── web/                     # Dashboard frontend
+│       ├── index.html
+│       ├── dashboard.js
+│       └── dashboard.css
+├── management/
+│   ├── actions.py               # Existing
+│   ├── game_manager.py          # Existing
+│   ├── log_events.py            # Existing
+│   ├── chat_manager.py          # NEW: Chat management
+│   └── message.py               # NEW: Message data structure
+├── players/
+│   ├── ai_agent.py              # UPDATE: Full AI agent implementation
+│   ├── human_user.py            # Existing
+│   └── user.py                  # Existing
+└── ...                          # Existing structure
+
+logs/                            # NEW: Local documentation
+└── game_sessions/
+    └── YYYY-MM-DD_HH-MM-SS/
+        ├── game_summary.json
+        ├── chat_log.txt
+        └── agent_<color>/
+            ├── config.json
+            ├── prompts.log
+            ├── decisions.log
+            └── memory_snapshots.json
+
+examples/
+├── ai_testing/
+│   ├── config_example.yaml      # NEW: Example configuration
+│   ├── test_single_agent.py     # NEW: Test script
+│   └── test_multi_agent.py      # NEW: Multi-agent test
+└── ...
+
+tests/
+├── unit/
+│   ├── test_ai_agent.py         # NEW
+│   ├── test_prompt_manager.py   # NEW
+│   ├── test_memory.py           # NEW
+│   └── test_tools.py            # NEW
+├── integration/
+│   ├── test_ai_gameplay.py      # NEW
+│   └── test_multi_agent.py      # NEW
+└── ...
+```

.github/instructions/updated.instructions.md

@@ -0,0 +1,30 @@
+---
+applyTo: '**'
+---
+
+# PyCatan AI Project Instructions
+
+## 📋 Project Overview
+
+**PyCatan_AI** is a Python implementation of the Settlers of Catan board game with a focus on AI agent development. The project consists of:
+
+- **Core Game Engine**: Complete implementation of Catan game rules, board management, and resource mechanics
+- **Game Management**: Turn-based coordination, action validation, and game state management
+- **Player Types**: Support for both human players (CLI) and AI agents
+- **Visualization**: Console and web-based game state visualization
+- **AI Development**: Framework for building and testing LLM-based AI agents to play Catan
+
+The primary goal is to create intelligent AI agents that can play Settlers of Catan autonomously, making strategic decisions about resource management, building placement, trading, and overall game strategy.
+
+## 📚 Related Documentation
+
+For detailed information about specific aspects of the project, refer to:
+
+- **[AI_ARCHITECTURE.md](.github/instructions/AI_ARCHITECTURE.md)** - Architecture and design of the AI agent system
+- **[AI_AGENT_PRINCIPLES.md](.github/instructions/AI_AGENT_PRINCIPLES.md)** - Core design principles and philosophy for AI agent implementation
+- **[WORK_PLAN.md](.github/instructions/WORK_PLAN.md)** - Detailed development work plan and roadmap
+- *(Additional documentation files will be referenced here as they are created)*
+
+## 🎯 Project Context
+
+This instruction file provides general coding guidelines and project context that AI assistants should follow when generating code, answering questions, or reviewing changes across the entire codebase.

.gitignore

@@ -70,8 +70,38 @@ pip-selfcheck.json
 
 # Log files
 *.log
+logs/
 
 # Temporary files
 *.tmp
 *.bak
 *~
+
+# ============================================================================
+# AI Agent - Security and Privacy
+# ============================================================================
+
+# Environment variables with API keys (CRITICAL - NEVER COMMIT!)
+.env
+.env.local
+.env.*.local
+
+# AI Configuration files with sensitive data
+# Note: *_example.yaml files WILL be committed as templates
+pycatan/ai/*.yaml
+!pycatan/ai/*_example.yaml
+!pycatan/ai/*_example.yml
+config.yaml
+config.yml
+*_config.yaml
+*_config.yml
+
+# AI Agent memory and game state files (may contain private data)
+agent_memory.json
+pycatan/ai/memory/*.json
+logs/ai_agents/
+logs/game_states/
+
+# Test configuration files
+test_config.yaml
+test_*.yaml

QUICKSTART_API.md

@@ -0,0 +1,31 @@
+# Quick Start - API Key Setup
+
+## 🚀 Fast Setup (2 minutes)
+
+### 1. Copy the template:
+```bash
+copy .env.example .env
+```
+
+### 2. Get your Gemini API key:
+- Go to: https://aistudio.google.com/app/apikey
+- Click "Create API Key"
+- Copy the key
+
+### 3. Edit `.env` file and paste your key:
+```
+GEMINI_API_KEY=AIzaSyC_paste_your_key_here
+```
+
+### 4. Test it works:
+```bash
+python examples/test_ai_config.py
+```
+
+## 📚 Full Documentation
+See [docs/AI_SETUP.md](docs/AI_SETUP.md) for complete setup guide.
+
+## ✅ Security
+- `.env` is NOT committed to Git (safe!)
+- Only `.env.example` (template) is in Git
+- Your API keys stay on your machine only

docs/AI_SETUP.md

@@ -0,0 +1,367 @@
+# 🤖 AI Agent Setup Guide
+
+This guide explains how to set up and configure AI agents for PyCatan.
+
+## 📋 Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [API Key Setup](#api-key-setup)
+3. [Configuration System](#configuration-system)
+4. [Security Best Practices](#security-best-practices)
+5. [Development Workflow](#development-workflow)
+
+---
+
+## 🚀 Quick Start
+
+### Step 1: Get an API Key
+
+You need an API key from an LLM provider. We recommend **Google Gemini** for development:
+
+1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. Click "Create API Key"
+3. Copy your API key
+
+**Other providers:**
+- OpenAI: https://platform.openai.com/api-keys
+- Anthropic: https://console.anthropic.com/settings/keys
+
+### Step 2: Setup Environment Variables
+
+```bash
+# Copy the template file
+cp .env.example .env
+
+# Edit .env and paste your API key
+# (Use any text editor)
+```
+
+Example `.env` file:
+```bash
+GEMINI_API_KEY=AIzaSyC_your_actual_api_key_here
+```
+
+### Step 3: Install Dependencies
+
+```bash
+pip install pyyaml
+```
+
+### Step 4: Test the Configuration
+
+```bash
+python examples/test_ai_config.py
+```
+
+You should see:
+```
+🎉 All tests passed!
+```
+
+---
+
+## 🔑 API Key Setup
+
+### Where API Keys Are Stored
+
+**API keys are stored in the `.env` file**, which is:
+- ✅ **NOT** committed to Git (protected by `.gitignore`)
+- ✅ Stored locally on your machine only
+- ✅ Easy to update without changing code
+
+### `.env` File Structure
+
+```bash
+# .env - YOUR PRIVATE FILE (never commit this!)
+GEMINI_API_KEY=your_actual_key_here
+OPENAI_API_KEY=your_openai_key_here      # Optional
+ANTHROPIC_API_KEY=your_anthropic_key      # Optional
+```
+
+### `.env.example` File
+
+The **`.env.example`** file is a template that:
+- ✅ **IS** committed to Git
+- ✅ Shows what variables are needed
+- ✅ Contains NO actual secrets
+- ✅ Helps other developers know what to set up
+
+**Never put real API keys in `.env.example`!**
+
+---
+
+## ⚙️ Configuration System
+
+### Overview
+
+PyCatan uses a **two-file configuration system**:
+
+```
+📁 Project Root
+├── .env                          # ❌ NOT in Git - API keys
+├── .env.example                  # ✅ IN Git - Template
+├── pycatan/ai/
+│   ├── config_example.yaml       # ✅ IN Git - Documentation
+│   ├── config_dev.yaml           # ✅ IN Git - Dev defaults
+│   └── my_agent_config.yaml      # ❌ NOT in Git - Your custom config
+```
+
+### File Types Explained
+
+#### 1. `.env` - Environment Variables (API Keys)
+- **Purpose:** Store sensitive API keys
+- **Git:** ❌ **NEVER** committed
+- **Contains:** `GEMINI_API_KEY=actual_secret_key`
+- **Who creates it:** Each developer on their machine
+
+#### 2. `.env.example` - Environment Template
+- **Purpose:** Template showing what variables are needed
+- **Git:** ✅ Committed to Git
+- **Contains:** `GEMINI_API_KEY=` (empty)
+- **Who creates it:** Already created in the project
+
+#### 3. `config_dev.yaml` - Development Defaults
+- **Purpose:** Default configuration for development
+- **Git:** ✅ Committed to Git
+- **Contains:** All settings EXCEPT API keys
+- **Who uses it:** Everyone, automatically
+
+#### 4. `config_example.yaml` - Configuration Documentation
+- **Purpose:** Complete documentation of all options
+- **Git:** ✅ Committed to Git
+- **Contains:** All possible settings with explanations
+- **Who uses it:** Reference when creating custom configs
+
+#### 5. Your Custom Config (e.g., `my_agent_config.yaml`)
+- **Purpose:** Your personal agent configuration
+- **Git:** ❌ NOT committed (optional)
+- **Contains:** Custom personality, strategies, etc.
+- **Who uses it:** You, when you want special behavior
+
+---
+
+## 🔒 Security Best Practices
+
+### ✅ DO:
+- Keep your `.env` file local only
+- Use different API keys for development and production
+- Rotate your API keys regularly
+- Review `.gitignore` to ensure `.env` is excluded
+- Use `.env.example` as a template for team members
+
+### ❌ DON'T:
+- Never commit `.env` to Git
+- Never put API keys in configuration YAML files
+- Never share your `.env` file
+- Never hardcode API keys in Python code
+- Never put API keys in commit messages or PR descriptions
+
+### Checking Security
+
+```bash
+# Make sure .env is ignored by Git
+git status
+
+# .env should NOT appear in the list
+# If it does, remove it:
+git rm --cached .env
+```
+
+---
+
+## 🛠️ Development Workflow
+
+### Using the Default Development Config
+
+The simplest way - just use `config_dev.yaml`:
+
+```python
+from pycatan.ai.config import AIConfig
+
+# Loads config_dev.yaml by default
+config = AIConfig.from_file('pycatan/ai/config_dev.yaml')
+
+# API key is automatically loaded from .env
+api_key = config.get_api_key()  # Reads GEMINI_API_KEY from .env
+```
+
+### Creating a Custom Agent
+
+1. **Copy the example config:**
+```bash
+cp pycatan/ai/config_example.yaml my_aggressive_agent.yaml
+```
+
+2. **Edit your config:**
+```yaml
+agent_name: "Aggressive Trader"
+agent:
+  personality: "aggressive"
+  risk_tolerance: 0.8
+  trade_willingness: 0.9
+```
+
+3. **Use it in your code:**
+```python
+config = AIConfig.from_file('my_aggressive_agent.yaml')
+```
+
+4. **The API key is still loaded from `.env`** - you don't need to specify it!
+
+### Multiple Agents with Different Personalities
+
+```python
+# Agent 1: Aggressive
+config1 = AIConfig.from_file('configs/aggressive.yaml')
+
+# Agent 2: Defensive
+config2 = AIConfig.from_file('configs/defensive.yaml')
+
+# Agent 3: Balanced (default)
+config3 = AIConfig.from_file('pycatan/ai/config_dev.yaml')
+
+# All three use the same API key from .env
+```
+
+---
+
+## 📝 Configuration Options
+
+### LLM Settings
+
+```yaml
+llm:
+  provider: "gemini"              # or "openai", "anthropic"
+  model_name: "gemini-2.0-flash-exp"
+  temperature: 0.7                # 0.0 = deterministic, 1.0 = creative
+  max_tokens: 4096
+```
+
+### Agent Personality
+
+```yaml
+agent:
+  personality: "balanced"         # aggressive, defensive, balanced, trading
+  risk_tolerance: 0.5            # 0.0 = safe, 1.0 = risky
+  
+  # Strategic focus (0.0 to 1.0)
+  focus_on_settlements: 0.6
+  focus_on_cities: 0.7
+  focus_on_roads: 0.5
+  focus_on_dev_cards: 0.6
+  
+  # Trading behavior
+  trade_willingness: 0.5         # 0.0 = never, 1.0 = always
+  trade_fairness: 0.7            # How fair are trades
+```
+
+### Debug Settings
+
+```yaml
+debug:
+  debug_mode: true               # Enable detailed logging
+  log_prompts: true              # Log prompts sent to LLM
+  log_responses: true            # Log LLM responses
+  save_game_states: true         # Save states for analysis
+```
+
+---
+
+## 🧪 Testing Your Setup
+
+### Test 1: Check API Key
+
+```python
+from pycatan.ai.config import AIConfig
+
+config = AIConfig()
+try:
+    api_key = config.get_api_key()
+    print("✓ API key loaded successfully")
+except ValueError as e:
+    print(f"✗ Error: {e}")
+```
+
+### Test 2: Load Configuration
+
+```python
+config = AIConfig.from_file('pycatan/ai/config_dev.yaml')
+print(f"✓ Loaded config for: {config.agent_name}")
+print(f"  Provider: {config.llm.provider}")
+print(f"  Model: {config.llm.model_name}")
+```
+
+### Test 3: Run Full Test Suite
+
+```bash
+python examples/test_ai_config.py
+```
+
+---
+
+## 🎯 Common Scenarios
+
+### Scenario 1: "I just cloned the repo"
+
+1. Create `.env`: `cp .env.example .env`
+2. Add your API key to `.env`
+3. Run tests: `python examples/test_ai_config.py`
+
+### Scenario 2: "I want to test different personalities"
+
+Use the existing configs:
+- `config_dev.yaml` - Balanced agent
+- Or create custom configs based on `config_example.yaml`
+
+### Scenario 3: "I want to switch LLM providers"
+
+Edit your config file:
+```yaml
+llm:
+  provider: "openai"
+  model_name: "gpt-4-turbo-preview"
+  api_key_env_var: "OPENAI_API_KEY"
+```
+
+Add the key to `.env`:
+```bash
+OPENAI_API_KEY=sk-your-key-here
+```
+
+### Scenario 4: "My API key changed"
+
+Just edit `.env` - no code changes needed!
+
+---
+
+## 📚 Next Steps
+
+- Read [AI_ARCHITECTURE.md](AI_ARCHITECTURE.md) for system design
+- Read [WORK_PLAN.md](WORK_PLAN.md) for development roadmap
+- See [config_example.yaml](../pycatan/ai/config_example.yaml) for all options
+
+---
+
+## 🆘 Troubleshooting
+
+### "ModuleNotFoundError: No module named 'yaml'"
+```bash
+pip install pyyaml
+```
+
+### "API key not found"
+1. Check `.env` exists in project root
+2. Check the API key variable name matches
+3. Try: `cat .env` to verify content
+
+### "Configuration file not found"
+- Use absolute paths or run from project root
+- Check file extension (`.yaml` not `.yml`)
+
+### "Still stuck?"
+- Check [GitHub Issues](your-repo-url/issues)
+- Review the test output: `python examples/test_ai_config.py`
+
+---
+
+**Last Updated:** January 3, 2026

example_answer.md

@@ -0,0 +1,12 @@
+{
+  "internal_thinking": "I have 3 Sheep and 2 Wheat. I need Wood and Brick to build. I see Red asked for Sheep in the chat. My note says to trade with Red. I will offer him a deal verbally first to see if he accepts, before committing to a formal trade action. I won't pass turn yet.",
+  
+  "note_to_self": "Waiting for Red's response. If he says yes, I will use OFFER_TRADE action next.",
+  
+  "say_outloud": "Red, I have plenty of sheep. Can you give me 1 Wood and 1 Brick for 2 Sheep?",
+  
+  "action": {
+    "type": "WAIT_FOR_RESPONSE", 
+    "parameters": {}
+  }
+}

examples/demo_ai_config.py

@@ -0,0 +1,222 @@
+"""
+Quick demo showing how the AI configuration system works.
+
+This script demonstrates:
+1. How API keys are loaded from environment variables
+2. How to use config files
+3. The difference between config_example.yaml and config_dev.yaml
+4. How to create custom agent configurations
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add project root to path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from pycatan.ai.config import AIConfig, load_config
+
+
+def demo_api_key_loading():
+    """Demo 1: How API keys are loaded from environment variables."""
+    print("\n" + "="*80)
+    print("DEMO 1: API Key Loading from Environment")
+    print("="*80)
+    
+    print("\n1. API keys are stored in the .env file (NOT in Git)")
+    print("   Example .env file:")
+    print("   ┌─────────────────────────────────────┐")
+    print("   │ GEMINI_API_KEY=AIzaSyC...your_key  │")
+    print("   │ OPENAI_API_KEY=sk-...your_key      │")
+    print("   └─────────────────────────────────────┘")
+    
+    print("\n2. The config system reads from environment variables:")
+    config = AIConfig()
+    
+    print(f"   Provider: {config.llm.provider}")
+    print(f"   Env var name: {config.llm.api_key_env_var}")
+    
+    # Try to get API key
+    try:
+        api_key = config.get_api_key()
+        # Hide most of the key for security
+        masked_key = api_key[:10] + "..." + api_key[-4:] if len(api_key) > 14 else "***"
+        print(f"   ✓ API key loaded: {masked_key}")
+        print(f"   ✓ Full length: {len(api_key)} characters")
+    except ValueError as e:
+        print(f"   ✗ No API key found: {e}")
+        print("\n   👉 To fix this:")
+        print("      1. Copy .env.example to .env")
+        print("      2. Add your API key to .env")
+        print("      3. The .env file will NOT be committed to Git")
+
+
+def demo_config_files():
+    """Demo 2: Different types of config files."""
+    print("\n" + "="*80)
+    print("DEMO 2: Configuration Files Explained")
+    print("="*80)
+    
+    print("\n📁 THREE types of config files:")
+    
+    print("\n1️⃣  config_example.yaml - DOCUMENTATION")
+    print("   ├─ Purpose: Shows ALL possible settings with explanations")
+    print("   ├─ Git: ✅ Committed (it's documentation)")
+    print("   ├─ Usage: Read it to understand options")
+    print("   └─ Don't use directly - copy and customize it")
+    
+    print("\n2️⃣  config_dev.yaml - DEFAULT FOR DEVELOPMENT")
+    print("   ├─ Purpose: Ready-to-use config for development")
+    print("   ├─ Git: ✅ Committed (team shares same defaults)")
+    print("   ├─ Usage: Just load it and start coding!")
+    print("   └─ Example: AIConfig.from_file('pycatan/ai/config_dev.yaml')")
+    
+    print("\n3️⃣  your_custom_config.yaml - YOUR PERSONAL AGENT")
+    print("   ├─ Purpose: Your custom agent configuration")
+    print("   ├─ Git: ❌ NOT committed (optional)")
+    print("   ├─ Usage: Create when you want custom behavior")
+    print("   └─ Example: Copy config_example.yaml and modify")
+    
+    print("\n💡 WORKFLOW:")
+    print("   • During development: Use config_dev.yaml")
+    print("   • Want custom agent: Copy config_example.yaml → my_agent.yaml")
+    print("   • API keys: Always in .env (never in YAML files)")
+
+
+def demo_default_config():
+    """Demo 3: Using the default development config."""
+    print("\n" + "="*80)
+    print("DEMO 3: Using the Default Development Config")
+    print("="*80)
+    
+    print("\n▶ Loading config_dev.yaml...")
+    config_path = project_root / "pycatan" / "ai" / "config_dev.yaml"
+    
+    if config_path.exists():
+        config = AIConfig.from_file(str(config_path))
+        
+        print(f"\n✓ Loaded successfully!")
+        print(f"\n📋 Configuration Details:")
+        print(f"   Agent Name: {config.agent_name}")
+        print(f"   Provider: {config.llm.provider}")
+        print(f"   Model: {config.llm.model_name}")
+        print(f"   Temperature: {config.llm.temperature}")
+        print(f"   Personality: {config.agent.personality}")
+        print(f"   Risk Tolerance: {config.agent.risk_tolerance}")
+        print(f"   Debug Mode: {config.debug.debug_mode}")
+        
+        print(f"\n⚙️ Strategic Focus:")
+        print(f"   Settlements: {config.agent.focus_on_settlements}")
+        print(f"   Cities: {config.agent.focus_on_cities}")
+        print(f"   Roads: {config.agent.focus_on_roads}")
+        print(f"   Dev Cards: {config.agent.focus_on_dev_cards}")
+        
+        print(f"\n💬 Social Behavior:")
+        print(f"   Trade Willingness: {config.agent.trade_willingness}")
+        print(f"   Chat Frequency: {config.agent.chat_frequency}")
+        print(f"   Chattiness: {config.agent.chattiness}")
+    else:
+        print(f"✗ Config file not found: {config_path}")
+
+
+def demo_custom_config():
+    """Demo 4: Creating a custom agent configuration."""
+    print("\n" + "="*80)
+    print("DEMO 4: Creating Custom Agent Configuration")
+    print("="*80)
+    
+    print("\n▶ Creating an 'Aggressive Trader' agent...")
+    
+    # Start with default config
+    config = AIConfig()
+    
+    # Customize for aggressive trading
+    config.agent_name = "Aggressive Trader"
+    config.agent.personality = "trading"
+    config.agent.risk_tolerance = 0.8  # High risk
+    config.agent.trade_willingness = 0.9  # Trades a lot
+    config.agent.trade_fairness = 0.6  # Slightly unfair trades
+    config.agent.focus_on_settlements = 0.8  # Expand quickly
+    config.agent.chat_frequency = 0.7  # Very chatty
+    config.agent.chattiness = "chatty"
+    config.llm.temperature = 0.8  # More creative
+    
+    print("\n✓ Custom config created!")
+    print(f"\n📋 Agent Profile:")
+    print(f"   Name: {config.agent_name}")
+    print(f"   Personality: {config.agent.personality}")
+    print(f"   Risk Tolerance: {config.agent.risk_tolerance} (HIGH)")
+    print(f"   Trade Willingness: {config.agent.trade_willingness} (VERY HIGH)")
+    print(f"   Trade Fairness: {config.agent.trade_fairness} (Slightly unfair)")
+    print(f"   Chattiness: {config.agent.chattiness}")
+    print(f"   Temperature: {config.llm.temperature} (Creative)")
+    
+    # Save to file
+    custom_file = project_root / "aggressive_trader_config.yaml"
+    config.to_file(str(custom_file))
+    print(f"\n💾 Saved to: {custom_file.name}")
+    print("   (This file will NOT be committed to Git)")
+    
+    # Clean up
+    custom_file.unlink()
+    print("   (Cleaned up demo file)")
+
+
+def demo_security():
+    """Demo 5: Security features."""
+    print("\n" + "="*80)
+    print("DEMO 5: Security Features")
+    print("="*80)
+    
+    print("\n🔒 What's Protected:")
+    print("   ✅ .env file → NOT in Git")
+    print("   ✅ Your custom *.yaml configs → NOT in Git")
+    print("   ✅ Agent memory files → NOT in Git")
+    print("   ✅ Game state logs → NOT in Git")
+    
+    print("\n📤 What's Committed:")
+    print("   ✅ .env.example → Template (no secrets)")
+    print("   ✅ config_example.yaml → Documentation")
+    print("   ✅ config_dev.yaml → Default settings")
+    print("   ✅ Python code → No secrets in code")
+    
+    print("\n⚠️ Remember:")
+    print("   • NEVER commit your .env file")
+    print("   • NEVER put API keys in YAML files")
+    print("   • NEVER hardcode API keys in Python code")
+    print("   • Each developer has their own .env file")
+
+
+def main():
+    """Run all demos."""
+    print("\n" + "="*80)
+    print("🎓 AI CONFIGURATION SYSTEM - INTERACTIVE DEMO")
+    print("="*80)
+    print("\nThis demo explains how the configuration system works")
+    print("and shows you the difference between the config files.")
+    
+    demo_api_key_loading()
+    demo_config_files()
+    demo_default_config()
+    demo_custom_config()
+    demo_security()
+    
+    print("\n" + "="*80)
+    print("✅ DEMO COMPLETE!")
+    print("="*80)
+    print("\n📚 Next Steps:")
+    print("   1. Read: docs/AI_SETUP.md (complete setup guide)")
+    print("   2. Read: QUICKSTART_API.md (2-minute setup)")
+    print("   3. Look at: pycatan/ai/config_example.yaml (all options)")
+    print("   4. Use: pycatan/ai/config_dev.yaml (start coding!)")
+    print("\n💡 Quick Start:")
+    print("   from pycatan.ai.config import AIConfig")
+    print("   config = AIConfig.from_file('pycatan/ai/config_dev.yaml')")
+    print("   api_key = config.get_api_key()  # From .env file")
+    print("\n" + "="*80)
+
+
+if __name__ == "__main__":
+    main()

examples/test_ai_config.py

@@ -0,0 +1,241 @@
+"""
+Test script for AI Configuration System
+
+This script tests the configuration management functionality:
+1. Create default configuration
+2. Save to file
+3. Load from file
+4. Validate configuration
+5. Test different personalities
+"""
+
+import sys
+from pathlib import Path
+
+# Add project root to path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from pycatan.ai.config import AIConfig, load_config
+
+
+def test_default_config():
+    """Test creating and using default configuration."""
+    print("\n" + "="*80)
+    print("TEST 1: Default Configuration")
+    print("="*80)
+    
+    config = AIConfig()
+    print(f"\n✓ Created default config:\n{config}")
+    
+    # Validate
+    try:
+        config.validate()
+        print("✓ Configuration is valid")
+    except ValueError as e:
+        print(f"✗ Validation failed: {e}")
+        return False
+    
+    return True
+
+
+def test_save_and_load():
+    """Test saving and loading configuration."""
+    print("\n" + "="*80)
+    print("TEST 2: Save and Load Configuration")
+    print("="*80)
+    
+    # Create custom config
+    config = AIConfig()
+    config.agent_name = "Test Agent"
+    config.agent.personality = "aggressive"
+    config.agent.risk_tolerance = 0.8
+    config.llm.temperature = 0.9
+    
+    # Save to file
+    test_file = "test_config.yaml"
+    config.to_file(test_file)
+    print(f"✓ Saved configuration to {test_file}")
+    
+    # Load from file
+    loaded_config = AIConfig.from_file(test_file)
+    print(f"✓ Loaded configuration from {test_file}")
+    
+    # Verify values
+    assert loaded_config.agent_name == "Test Agent", "Agent name mismatch"
+    assert loaded_config.agent.personality == "aggressive", "Personality mismatch"
+    assert loaded_config.agent.risk_tolerance == 0.8, "Risk tolerance mismatch"
+    assert loaded_config.llm.temperature == 0.9, "Temperature mismatch"
+    
+    print("✓ All values match correctly")
+    
+    # Clean up
+    Path(test_file).unlink()
+    print(f"✓ Cleaned up {test_file}")
+    
+    return True
+
+
+def test_personalities():
+    """Test creating configs with different personalities."""
+    print("\n" + "="*80)
+    print("TEST 3: Different Personalities")
+    print("="*80)
+    
+    personalities = {
+        "aggressive": {
+            "personality": "aggressive",
+            "risk_tolerance": 0.8,
+            "trade_willingness": 0.7,
+            "focus_on_settlements": 0.8
+        },
+        "defensive": {
+            "personality": "defensive",
+            "risk_tolerance": 0.3,
+            "trade_willingness": 0.3,
+            "focus_on_cities": 0.9
+        },
+        "balanced": {
+            "personality": "balanced",
+            "risk_tolerance": 0.5,
+            "trade_willingness": 0.5
+        },
+        "trading": {
+            "personality": "trading",
+            "risk_tolerance": 0.6,
+            "trade_willingness": 0.9,
+            "chat_frequency": 0.7
+        }
+    }
+    
+    for name, settings in personalities.items():
+        config = AIConfig()
+        config.agent_name = f"{name.capitalize()} Agent"
+        
+        # Apply settings
+        for key, value in settings.items():
+            setattr(config.agent, key, value)
+        
+        # Validate
+        config.validate()
+        print(f"✓ Created and validated '{name}' personality")
+        print(f"  - Risk tolerance: {config.agent.risk_tolerance}")
+        print(f"  - Trade willingness: {config.agent.trade_willingness}")
+    
+    return True
+
+
+def test_validation():
+    """Test configuration validation."""
+    print("\n" + "="*80)
+    print("TEST 4: Configuration Validation")
+    print("="*80)
+    
+    # Test invalid temperature
+    config = AIConfig()
+    config.llm.temperature = 3.0  # Invalid (> 2.0)
+    
+    try:
+        config.validate()
+        print("✗ Should have caught invalid temperature")
+        return False
+    except ValueError as e:
+        print(f"✓ Correctly caught invalid temperature: {e}")
+    
+    # Test invalid risk tolerance
+    config = AIConfig()
+    config.agent.risk_tolerance = 1.5  # Invalid (> 1.0)
+    
+    try:
+        config.validate()
+        print("✗ Should have caught invalid risk_tolerance")
+        return False
+    except ValueError as e:
+        print(f"✓ Correctly caught invalid risk_tolerance: {e}")
+    
+    # Test valid config
+    config = AIConfig()
+    config.validate()
+    print("✓ Valid configuration passes validation")
+    
+    return True
+
+
+def test_to_dict_and_back():
+    """Test dictionary conversion."""
+    print("\n" + "="*80)
+    print("TEST 5: Dictionary Conversion")
+    print("="*80)
+    
+    # Create config
+    config = AIConfig()
+    config.agent_name = "Dict Test Agent"
+    config.agent.personality = "trading"
+    config.llm.temperature = 0.8
+    
+    # Convert to dict
+    config_dict = config.to_dict()
+    print("✓ Converted config to dictionary")
+    
+    # Create from dict
+    new_config = AIConfig.from_dict(config_dict)
+    print("✓ Created config from dictionary")
+    
+    # Verify values
+    assert new_config.agent_name == config.agent_name
+    assert new_config.agent.personality == config.agent.personality
+    assert new_config.llm.temperature == config.llm.temperature
+    print("✓ All values preserved correctly")
+    
+    return True
+
+
+def main():
+    """Run all tests."""
+    print("\n" + "="*80)
+    print("AI CONFIGURATION SYSTEM - TEST SUITE")
+    print("="*80)
+    
+    tests = [
+        ("Default Configuration", test_default_config),
+        ("Save and Load", test_save_and_load),
+        ("Different Personalities", test_personalities),
+        ("Validation", test_validation),
+        ("Dictionary Conversion", test_to_dict_and_back)
+    ]
+    
+    results = []
+    for name, test_func in tests:
+        try:
+            result = test_func()
+            results.append((name, result))
+        except Exception as e:
+            print(f"\n✗ Test '{name}' failed with exception: {e}")
+            import traceback
+            traceback.print_exc()
+            results.append((name, False))
+    
+    # Summary
+    print("\n" + "="*80)
+    print("TEST SUMMARY")
+    print("="*80)
+    
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for name, result in results:
+        status = "✓ PASS" if result else "✗ FAIL"
+        print(f"{status}: {name}")
+    
+    print(f"\nTotal: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print("\n🎉 All tests passed!")
+        return 0
+    else:
+        print(f"\n❌ {total - passed} test(s) failed")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

promt_format.text

@@ -0,0 +1,86 @@
+{
+    // מידע על זהות השחקן
+  "meta_data": {
+    "agent_name": "Dani",
+    "my_color": "Blue",
+    "role": "You are a pro Catan player.",
+  },
+    // מידע על מה קרה עכשיו בעולם
+  "task_context": {
+    "what_just_happened": "Player 'Red' rolled a 6. You received 1 Wood.",
+    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. You may use the provided tools to gather more data (e.g., calculate probabilities), but limit yourself to a maximum of 3 tool executions per decision. If you wish to negotiate or wait for other players, select the 'WAIT_FOR_RESPONSE' action.",
+  },
+    // קונטקסט על הSTATE של העולם מותאם לנקודת המבט של השחקן
+  "game_state": {
+    "my_private_info": {
+      "resources": {"wood": 0, "brick": 0, "sheep": 3, "wheat": 1, "ore": 0},
+      "development_cards": [],
+      "victory_points": 2
+    },....
+  },
+
+  "social_context": {
+    // ההודעות האחרונות בצאט
+    "recent_chat": [
+      {"sender": "Red", "content": "I need sheep desperately."}
+    ],
+
+    "last_summaries": [1: "Dana is off to a quick start with a lucky roll and a trade with Alex to build toward the wood port. I’ve warned the table about her strategy, but she’s already trying to downplay her early advantage.",2: "I’m frustrated by the lack of 8s and Dana’s blatant betrayal after she snubbed my brick trade for a secret deal with Alex. It seems those two are continuing to work together to dominate the game despite my warnings to the table."]
+  },
+
+  "memory": {
+    // דברים שאני רוצה לזכור להמשך
+    "notes_for_myself": [1 : "My plan is to trade Sheep for Wood with Red to build a settlement." , 2: "shani been an ashole to me"]
+  },
+
+"constraints": {
+    "usage_instructions": "Choose one action type from the list below. Populate the 'parameters' field in your response strictly according to the 'example_parameters' structure provided.",
+    
+    "allowed_actions": [
+      {
+        "type": "BUILD_ROAD",
+        "description": "Build a road on a specific edge ID.",
+        "example_parameters": { "edge_id": 12 }
+      },
+      {
+        "type": "BUILD_SETTLEMENT",
+        "description": "Build a settlement on a specific node ID.",
+        "example_parameters": { "node_id": 45 }
+      },
+      {
+        "type": "BUILD_CITY",
+        "description": "Upgrade an existing settlement to a city.",
+        "example_parameters": { "node_id": 45 }
+      },
+      {
+        "type": "OFFER_TRADE",
+        "description": "Propose a trade to all players or a specific one.",
+        "example_parameters": { 
+            "give": {"wood": 1, "sheep": 1}, 
+            "receive": {"ore": 1},
+            "target_player_color": "Red" // Optional, remove key for public offer
+        }
+      },
+      {
+        "type": "PLAY_DEV_CARD",
+        "description": "Play a development card. Specific params depend on the card.",
+        "example_parameters": [
+            { "card": "KNIGHT", "robber_hex": 7, "target_victim": "Red" },
+            { "card": "MONOPOLY", "resource": "sheep" },
+            { "card": "YEAR_OF_PLENTY", "resources": ["wood", "brick"] },
+            { "card": "ROAD_BUILDING", "edges": [12, 13] }
+        ]
+      },
+      {
+        "type": "WAIT_FOR_RESPONSE",
+        "description": "Do nothing on the board, just chat or wait.",
+        "example_parameters": {} 
+      },
+      {
+        "type": "END_TURN",
+        "description": "Pass the dice to the next player.",
+        "example_parameters": {} 
+      }
+    ]
+  }
+}

pycatan/ai/__init__.py

@@ -0,0 +1,34 @@
+"""
+AI Agent Infrastructure for PyCatan
+
+This package contains the infrastructure for building LLM-based AI agents
+that can play Settlers of Catan autonomously.
+
+Components:
+- config: Configuration management for AI agents
+- prompt_manager: Prompt construction and game state filtering
+- response_parser: LLM response parsing and validation
+- memory: Agent memory and learning systems
+- llm_client: LLM API abstraction and client
+
+Architecture Overview:
+┌─────────────────────────────────────────────────────────┐
+│                      AIAgent                            │
+│           (Main AI player implementation)               │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │   Config     │  │    Prompt    │  │   Response   │ │
+│  │  Management  │  │   Manager    │  │    Parser    │ │
+│  └──────────────┘  └──────────────┘  └──────────────┘ │
+│                                                         │
+│  ┌──────────────┐  ┌──────────────┐                   │
+│  │    Memory    │  │  LLM Client  │                   │
+│  │    System    │  │ (Multi-API)  │                   │
+│  └──────────────┘  └──────────────┘                   │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+"""
+
+__version__ = "0.1.0"
+__all__ = ["config"]

pycatan/ai/config.py

@@ -0,0 +1,341 @@
+"""
+Configuration Management for AI Agents
+
+This module provides centralized configuration management for AI agents,
+including LLM settings, API credentials, agent parameters, and performance settings.
+
+Features:
+- Load configuration from YAML files
+- Environment variable support for sensitive data
+- Configuration validation
+- Default values with override capability
+- Multiple LLM provider support
+
+Usage:
+    from pycatan.ai.config import AIConfig
+    
+    # Load from file
+    config = AIConfig.from_file('my_agent_config.yaml')
+    
+    # Or create with defaults
+    config = AIConfig()
+    
+    # Access settings
+    model = config.llm.model_name
+    temperature = config.llm.temperature
+    api_key = config.get_api_key()
+"""
+
+import os
+import yaml
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+
+@dataclass
+class LLMConfig:
+    """Configuration for LLM provider and model settings."""
+    
+    # Provider settings
+    provider: str = "gemini"  # "gemini", "openai", "anthropic", "azure"
+    model_name: str = "gemini-2.0-flash-exp"
+    
+    # Generation parameters
+    temperature: float = 0.7
+    max_tokens: int = 4096
+    top_p: float = 0.95
+    top_k: int = 40
+    
+    # API settings
+    api_key_env_var: str = "GEMINI_API_KEY"  # Environment variable name
+    api_base_url: Optional[str] = None  # For custom endpoints
+    
+    # Performance
+    timeout_seconds: int = 30
+    max_retries: int = 3
+    retry_delay_seconds: float = 1.0
+    
+    # Cost tracking
+    track_usage: bool = True
+    log_requests: bool = True
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for agent personality and behavior."""
+    
+    # Agent identity
+    personality: str = "balanced"  # "aggressive", "defensive", "balanced", "trading"
+    risk_tolerance: float = 0.5  # 0.0 (conservative) to 1.0 (risky)
+    
+    # Strategic preferences
+    focus_on_settlements: float = 0.6  # Relative priority
+    focus_on_cities: float = 0.7
+    focus_on_roads: float = 0.5
+    focus_on_dev_cards: float = 0.6
+    
+    # Trading behavior
+    trade_willingness: float = 0.5  # 0.0 (never trades) to 1.0 (trades often)
+    trade_fairness: float = 0.7  # How fair are trade offers
+    
+    # Social behavior
+    chat_frequency: float = 0.3  # How often to send chat messages
+    use_emojis: bool = True
+    chattiness: str = "medium"  # "quiet", "medium", "chatty"
+    
+    # Custom instructions
+    custom_instructions: Optional[str] = None  # Additional instructions for this agent
+
+
+@dataclass
+class MemoryConfig:
+    """Configuration for agent memory system."""
+    
+    # Short-term memory
+    short_term_turns: int = 5  # Remember last N turns
+    
+    # Chat history
+    chat_history_size: int = 10  # Keep last N messages
+    enable_chat_summarization: bool = True
+    chat_summary_threshold: int = 10  # Summarize when reaching N messages
+    
+    # Summarization settings
+    summarization_provider: str = "gemini"
+    summarization_model: str = "gemini-2.0-flash-exp"
+    summarization_max_tokens: int = 500
+    
+    # Memory persistence
+    save_memory_to_file: bool = True
+    memory_file_path: str = "agent_memory.json"
+    
+    # Memory limits
+    max_strategic_notes: int = 20
+    max_observations: int = 50
+
+
+@dataclass
+class DebugConfig:
+    """Configuration for debugging and logging."""
+    
+    # Logging levels
+    debug_mode: bool = False
+    log_prompts: bool = True
+    log_responses: bool = True
+    log_decisions: bool = True
+    
+    # Log file settings
+    log_to_file: bool = True
+    log_directory: str = "logs/ai_agents"
+    log_format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    
+    # Performance monitoring
+    track_decision_time: bool = True
+    track_token_usage: bool = True
+    
+    # Development helpers
+    save_game_states: bool = False  # Save game states for analysis
+    game_states_directory: str = "logs/game_states"
+
+
+@dataclass
+class AIConfig:
+    """
+    Main configuration class for AI agents.
+    
+    This class aggregates all configuration sections and provides
+    methods for loading, saving, and accessing configuration values.
+    """
+    
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    agent: AgentConfig = field(default_factory=AgentConfig)
+    memory: MemoryConfig = field(default_factory=MemoryConfig)
+    debug: DebugConfig = field(default_factory=DebugConfig)
+    
+    # Metadata
+    config_version: str = "1.0"
+    agent_name: str = "AI Agent"
+    
+    @classmethod
+    def from_file(cls, file_path: str) -> "AIConfig":
+        """
+        Load configuration from a YAML file.
+        
+        Args:
+            file_path: Path to the YAML configuration file
+            
+        Returns:
+            AIConfig instance with loaded settings
+            
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            yaml.YAMLError: If config file is invalid
+        """
+        config_path = Path(file_path)
+        
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {file_path}")
+        
+        with open(config_path, 'r', encoding='utf-8') as f:
+            data = yaml.safe_load(f)
+        
+        return cls.from_dict(data)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AIConfig":
+        """
+        Create configuration from a dictionary.
+        
+        Args:
+            data: Dictionary with configuration values
+            
+        Returns:
+            AIConfig instance
+        """
+        # Extract nested configs
+        llm_data = data.get('llm', {})
+        agent_data = data.get('agent', {})
+        memory_data = data.get('memory', {})
+        debug_data = data.get('debug', {})
+        
+        return cls(
+            llm=LLMConfig(**llm_data),
+            agent=AgentConfig(**agent_data),
+            memory=MemoryConfig(**memory_data),
+            debug=DebugConfig(**debug_data),
+            config_version=data.get('config_version', '1.0'),
+            agent_name=data.get('agent_name', 'AI Agent')
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert configuration to dictionary.
+        
+        Returns:
+            Dictionary representation of configuration
+        """
+        return {
+            'config_version': self.config_version,
+            'agent_name': self.agent_name,
+            'llm': asdict(self.llm),
+            'agent': asdict(self.agent),
+            'memory': asdict(self.memory),
+            'debug': asdict(self.debug)
+        }
+    
+    def to_file(self, file_path: str):
+        """
+        Save configuration to a YAML file.
+        
+        Args:
+            file_path: Path where to save the configuration
+        """
+        config_path = Path(file_path)
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(config_path, 'w', encoding='utf-8') as f:
+            yaml.dump(self.to_dict(), f, default_flow_style=False, sort_keys=False)
+    
+    def get_api_key(self, provider: Optional[str] = None) -> str:
+        """
+        Get API key from environment variable.
+        
+        Args:
+            provider: Provider name (uses llm.provider if None)
+            
+        Returns:
+            API key string
+            
+        Raises:
+            ValueError: If API key environment variable is not set
+        """
+        if provider is None:
+            provider = self.llm.provider
+        
+        # Determine environment variable name
+        if provider == "gemini":
+            env_var = self.llm.api_key_env_var or "GEMINI_API_KEY"
+        elif provider == "openai":
+            env_var = "OPENAI_API_KEY"
+        elif provider == "anthropic":
+            env_var = "ANTHROPIC_API_KEY"
+        elif provider == "azure":
+            env_var = "AZURE_OPENAI_KEY"
+        else:
+            env_var = self.llm.api_key_env_var or f"{provider.upper()}_API_KEY"
+        
+        api_key = os.getenv(env_var)
+        
+        if not api_key:
+            raise ValueError(
+                f"API key not found. Please set the {env_var} environment variable."
+            )
+        
+        return api_key
+    
+    def validate(self) -> bool:
+        """
+        Validate configuration values.
+        
+        Returns:
+            True if configuration is valid
+            
+        Raises:
+            ValueError: If configuration contains invalid values
+        """
+        # Validate temperature
+        if not 0.0 <= self.llm.temperature <= 2.0:
+            raise ValueError(f"Temperature must be between 0.0 and 2.0, got {self.llm.temperature}")
+        
+        # Validate token limits
+        if self.llm.max_tokens < 100:
+            raise ValueError(f"max_tokens must be at least 100, got {self.llm.max_tokens}")
+        
+        # Validate risk tolerance
+        if not 0.0 <= self.agent.risk_tolerance <= 1.0:
+            raise ValueError(f"risk_tolerance must be between 0.0 and 1.0, got {self.agent.risk_tolerance}")
+        
+        # Validate timeouts
+        if self.llm.timeout_seconds < 1:
+            raise ValueError(f"timeout_seconds must be at least 1, got {self.llm.timeout_seconds}")
+        
+        # Validate memory settings
+        if self.memory.short_term_turns < 1:
+            raise ValueError(f"short_term_turns must be at least 1, got {self.memory.short_term_turns}")
+        
+        # Check API key is available (warning, not error)
+        try:
+            self.get_api_key()
+        except ValueError as e:
+            print(f"Warning: {e}")
+        
+        return True
+    
+    def __repr__(self) -> str:
+        """String representation of configuration."""
+        return (
+            f"AIConfig(\n"
+            f"  agent_name='{self.agent_name}',\n"
+            f"  provider='{self.llm.provider}',\n"
+            f"  model='{self.llm.model_name}',\n"
+            f"  personality='{self.agent.personality}',\n"
+            f"  debug={self.debug.debug_mode}\n"
+            f")"
+        )
+
+
+# Convenience function for quick config loading
+def load_config(file_path: Optional[str] = None) -> AIConfig:
+    """
+    Load AI configuration from file or create default.
+    
+    Args:
+        file_path: Path to config file (optional)
+        
+    Returns:
+        AIConfig instance
+    """
+    if file_path and Path(file_path).exists():
+        return AIConfig.from_file(file_path)
+    else:
+        return AIConfig()

pycatan/ai/config_example.yaml

@@ -0,0 +1,164 @@
+# ============================================================================
+# AI Agent Configuration Example
+# ============================================================================
+# This is an example configuration file for PyCatan AI agents.
+# Copy this file and customize it for your agent.
+#
+# Usage:
+#   from pycatan.ai.config import AIConfig
+#   config = AIConfig.from_file('my_agent_config.yaml')
+# ============================================================================
+
+config_version: "1.0"
+agent_name: "AI Agent"  # Name of your agent
+
+# ============================================================================
+# LLM Configuration
+# ============================================================================
+llm:
+  # Provider selection
+  # Options: "gemini", "openai", "anthropic", "azure"
+  provider: "gemini"
+  
+  # Model name
+  # Gemini: "gemini-2.0-flash-exp", "gemini-1.5-pro", "gemini-1.5-flash"
+  # OpenAI: "gpt-4-turbo-preview", "gpt-4", "gpt-3.5-turbo"
+  # Anthropic: "claude-3-opus-20240229", "claude-3-sonnet-20240229"
+  model_name: "gemini-2.0-flash-exp"
+  
+  # Generation parameters
+  temperature: 0.7          # 0.0 (deterministic) to 2.0 (creative)
+  max_tokens: 4096          # Maximum tokens in response
+  top_p: 0.95              # Nucleus sampling threshold
+  top_k: 40                # Top-k sampling (for supported models)
+  
+  # API settings
+  # The API key is read from environment variables for security
+  # Set GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY
+  api_key_env_var: "GEMINI_API_KEY"
+  api_base_url: null       # Custom endpoint (if needed)
+  
+  # Performance settings
+  timeout_seconds: 30      # Request timeout
+  max_retries: 3           # Number of retry attempts
+  retry_delay_seconds: 1.0 # Delay between retries
+  
+  # Tracking
+  track_usage: true        # Track token usage and costs
+  log_requests: true       # Log all API requests
+
+# ============================================================================
+# Agent Configuration
+# ============================================================================
+agent:
+  # Personality types affect decision-making style
+  # Options: "aggressive", "defensive", "balanced", "trading"
+  personality: "balanced"
+  
+  # Risk tolerance: 0.0 (conservative) to 1.0 (risky)
+  risk_tolerance: 0.5
+  
+  # Strategic priorities (0.0 to 1.0)
+  # Higher values mean higher priority
+  focus_on_settlements: 0.6
+  focus_on_cities: 0.7
+  focus_on_roads: 0.5
+  focus_on_dev_cards: 0.6
+  
+  # Trading behavior
+  trade_willingness: 0.5   # 0.0 (never) to 1.0 (always)
+  trade_fairness: 0.7      # How fair are trade offers
+  
+  # Social behavior
+  chat_frequency: 0.3      # How often to chat (0.0 to 1.0)
+  use_emojis: true        # Use emojis in chat
+  chattiness: "medium"     # Options: "quiet", "medium", "chatty"
+  
+  # Custom instructions (optional)
+  # Add any additional instructions for this specific agent
+  custom_instructions: null
+  # Example:
+  # custom_instructions: "Focus on building settlements near wheat and ore tiles."
+
+# ============================================================================
+# Memory Configuration
+# ============================================================================
+memory:
+  # Short-term memory
+  short_term_turns: 5      # Remember last N turns
+  
+  # Chat history management
+  chat_history_size: 10              # Keep last N messages
+  enable_chat_summarization: true    # Auto-summarize old chats
+  chat_summary_threshold: 10         # Summarize after N messages
+  
+  # Summarization settings
+  # Use a smaller/cheaper model for summarization
+  summarization_provider: "gemini"
+  summarization_model: "gemini-2.0-flash-exp"
+  summarization_max_tokens: 500
+  
+  # Memory persistence
+  save_memory_to_file: true
+  memory_file_path: "agent_memory.json"
+  
+  # Memory limits
+  max_strategic_notes: 20  # Maximum strategic notes to keep
+  max_observations: 50     # Maximum observations to keep
+
+# ============================================================================
+# Debug Configuration
+# ============================================================================
+debug:
+  # Debug mode - shows detailed information
+  debug_mode: false
+  
+  # Logging options
+  log_prompts: true        # Log prompts sent to LLM
+  log_responses: true      # Log LLM responses
+  log_decisions: true      # Log decision-making process
+  
+  # Log file settings
+  log_to_file: true
+  log_directory: "logs/ai_agents"
+  log_format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  
+  # Performance tracking
+  track_decision_time: true  # Track how long decisions take
+  track_token_usage: true    # Track token consumption
+  
+  # Development helpers
+  save_game_states: false              # Save game states for analysis
+  game_states_directory: "logs/game_states"
+
+# ============================================================================
+# Example Configurations for Different Personalities
+# ============================================================================
+#
+# AGGRESSIVE TRADER:
+# ------------------
+# agent:
+#   personality: "trading"
+#   risk_tolerance: 0.8
+#   trade_willingness: 0.9
+#   focus_on_settlements: 0.8
+#   chat_frequency: 0.6
+#
+# DEFENSIVE BUILDER:
+# ------------------
+# agent:
+#   personality: "defensive"
+#   risk_tolerance: 0.3
+#   trade_willingness: 0.3
+#   focus_on_cities: 0.9
+#   focus_on_roads: 0.7
+#
+# DEVELOPMENT CARD SPECIALIST:
+# ----------------------------
+# agent:
+#   personality: "balanced"
+#   risk_tolerance: 0.6
+#   focus_on_dev_cards: 0.9
+#   trade_willingness: 0.6
+#
+# ============================================================================