.github/instructions/AI_ARCHITECTURE.md

🤖 AI Agent Architecture

Date: December 23, 2025
Status: 📋 In Planning

🎯 Goal

Build an LLM-based AI agent that can play Settlers of Catan autonomously and intelligently.

🏗️ Overall Architecture

┌─────────────────────────────────────────────────────────────┐
│                        GameManager                          │
│                (Game coordination & decisions)               │
├─────────────────────────────────────────────────────────────┤
│  • game_loop() - Main game loop                             │
│  • handle_turn_rules() - Turn management                    │
│  • coordinate_interactions() - Player coordination          │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │  Game   │  │  Users  │  │  Viz    │
   │ (Core)  │  │(Players)│  │(Display)│
   └─────────┘  └────┬────┘  └─────────┘
                     │
              ┌──────┴──────┐
              │             │
              ▼             ▼
        ┌──────────┐  ┌──────────┐
        │  Human   │  │ AI Agent │ ← NEW!
        │   User   │  │   (LLM)  │
        └──────────┘  └──────────┘
             ✅            🚧

📦 Existing Components

1️⃣ Core - The Game (game.py)

What exists:

• Complete and tested game rules
• Board, player, and resource management
• Action validation

Status: ✅ Ready and stable

2️⃣ GameManager - Game Manager (management/game_manager.py)

What exists:

• Turn and phase management
• Player coordination
• Rule enforcement

Status: ✅ Ready and stable

3️⃣ Actions - Action System (management/actions.py)

What exists:

• Definition of all possible game actions
• Unified data structure for each action
• Validation and permissions

Example:

class Action:
    def __init__(self, action_type, player_num, **kwargs):
        self.action_type = action_type  # BUILD_SETTLEMENT, BUILD_ROAD, etc.
        self.player_num = player_num
        self.details = kwargs  # point, edge, resources, etc.

Status: ✅ Ready and stable

4️⃣ HumanUser - Human User (players/human_user.py)

What exists:

• CLI interaction
• Getting decisions from user
• Executing actions through GameManager

Status: ✅ Ready and tested