promt and scheme eng

examples/ai_testing/generate_prompts_from_state.py

@@ -0,0 +1,285 @@
+"""
+Generate AI Prompts from Current Game State
+--------------------------------------------
+Reads the current optimized game state and generates a complete JSON prompt
+for each player in the exact format to send to LLM, including response schema.
+
+Run this script DURING a game to see what prompts each AI would receive.
+"""
+
+import sys
+import json
+from pathlib import Path
+from datetime import datetime
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from pycatan.ai.prompt_manager import PromptManager
+from pycatan.ai.config import AIConfig
+from pycatan.ai.prompt_templates import get_response_schema
+
+
+def load_current_state():
+    """Load the current optimized game state."""
+    state_file = Path('examples/ai_testing/my_games/current_state_optimized.txt')
+    
+    if not state_file.exists():
+        print("❌ No current game state found!")
+        print(f"   Expected: {state_file}")
+        print("\n💡 Start a game first:")
+        print("   python examples/ai_testing/play_and_capture.py")
+        return None
+    
+    with open(state_file, 'r', encoding='utf-8') as f:
+        content = f.read()
+    
+    # Find JSON after "JSON:" marker
+    json_marker = content.find('JSON:')
+    if json_marker != -1:
+        json_start = content.find('{', json_marker)
+    else:
+        json_start = content.find('{')
+    
+    if json_start == -1:
+        print("❌ Could not find JSON in state file!")
+        return None
+    
+    json_str = content[json_start:].strip()
+    
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError as e:
+        print(f"❌ JSON parsing error: {e}")
+        return None
+
+
+def get_player_colors():
+    """Get color mappings for players (hardcoded for now)."""
+    return {
+        "a": "Red",
+        "b": "Blue", 
+        "c": "White",
+        "d": "Orange"
+    }
+
+
+def generate_prompt_for_player(player_name, game_state, prompt_manager):
+    """
+    Generate a complete prompt for a specific player.
+    
+    Args:
+        player_name: Name of the player (e.g., "a", "b", "c")
+        game_state: Current game state (optimized format)
+        prompt_manager: PromptManager instance
+        
+    Returns:
+        Complete prompt dictionary
+    """
+    colors = get_player_colors()
+    player_color = colors.get(player_name, "Unknown")
+    
+    # Get player index (0-based)
+    players = game_state.get("players", {})
+    player_names = list(players.keys())
+    player_num = player_names.index(player_name) if player_name in player_names else 0
+    
+    # Get current phase and determine what action is needed
+    meta = game_state.get("meta", {})
+    phase = meta.get("phase", "UNKNOWN")
+    current_player = meta.get("curr")
+    
+    # Determine what happened and what to do
+    if phase == "SETUP_FIRST_ROUND":
+        if current_player == player_name:
+            what_happened = "It's your turn in the setup phase. Place your first settlement."
+            available_actions = [
+                {
+                    "action": "place_settlement",
+                    "description": "Place your starting settlement on an available node",
+                    "example_parameters": {
+                        "location": "20"
+                    }
+                }
+            ]
+        else:
+            what_happened = f"It's {current_player}'s turn to place their first settlement."
+            available_actions = None
+    elif phase == "SETUP_SECOND_ROUND":
+        if current_player == player_name:
+            what_happened = "It's your turn in the second setup round. Place your second settlement."
+            available_actions = [
+                {
+                    "action": "place_settlement",
+                    "description": "Place your second starting settlement",
+                    "example_parameters": {
+                        "location": "25"
+                    }
+                }
+            ]
+        else:
+            what_happened = f"It's {current_player}'s turn to place their second settlement."
+            available_actions = None
+    else:
+        if current_player == player_name:
+            what_happened = "It's your turn. Roll the dice to begin."
+            available_actions = [
+                {
+                    "action": "roll_dice",
+                    "description": "Roll the dice to produce resources",
+                    "example_parameters": {}
+                },
+                {
+                    "action": "build_road",
+                    "description": "Build a road on a specific edge",
+                    "example_parameters": {"location": "12"}
+                },
+                {
+                    "action": "build_settlement",
+                    "description": "Build a settlement on a specific node",
+                    "example_parameters": {"location": "45"}
+                },
+                {
+                    "action": "buy_development_card",
+                    "description": "Buy a development card if you have resources",
+                    "example_parameters": {}
+                },
+                {
+                    "action": "wait_for_response",
+                    "description": "Do nothing on the board, just chat or wait for trade responses",
+                    "example_parameters": {}
+                },
+                {
+                    "action": "end_turn",
+                    "description": "End your turn when done",
+                    "example_parameters": {}
+                }
+            ]
+        else:
+            what_happened = f"It's {current_player}'s turn."
+            available_actions = None
+    
+    # Generate the prompt
+    prompt = prompt_manager.create_prompt(
+        player_num=player_num,
+        player_name=player_name,
+        player_color=player_color,
+        game_state=game_state,
+        what_happened=what_happened,
+        available_actions=available_actions,
+        custom_instructions=f"You are player '{player_name}' ({player_color}). Play strategically to win."
+    )
+    
+    return prompt
+
+
+def save_prompt_to_file(player_name, prompt, output_dir):
+    """
+    Save a prompt as JSON file with response schema header.
+    
+    Args:
+        player_name: Name of the player
+        prompt: Complete prompt dictionary
+        output_dir: Directory to save to
+    """
+    output_file = output_dir / f"prompt_player_{player_name}.json"
+    
+    # Create complete LLM request with schema + prompt
+    llm_request = {
+        "response_schema": get_response_schema(),
+        "system_instruction": "You are an expert Settlers of Catan player. Analyze the game state carefully and respond with your chosen action in the exact JSON format specified in response_schema.",
+        "prompt": prompt
+    }
+    
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(llm_request, f, indent=2, ensure_ascii=False)
+    
+    # Also create a human-readable version
+    txt_file = output_dir / f"prompt_player_{player_name}.txt"
+    with open(txt_file, 'w', encoding='utf-8') as f:
+        f.write("="*80 + "\n")
+        f.write(f"AI AGENT PROMPT - PLAYER {player_name.upper()}\n")
+        f.write(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+        f.write("="*80 + "\n\n")
+        
+        f.write("📋 RESPONSE SCHEMA (Expected LLM Output Format)\n")
+        f.write("-" * 80 + "\n")
+        f.write(json.dumps(llm_request["response_schema"], indent=2, ensure_ascii=False))
+        f.write("\n\n")
+        
+        f.write("="*80 + "\n")
+        f.write("📨 PROMPT TO SEND TO LLM\n")
+        f.write("="*80 + "\n\n")
+        
+        f.write(json.dumps(prompt, indent=2, ensure_ascii=False))
+        f.write("\n\n")
+        
+        f.write("="*80 + "\n")
+        f.write("END OF PROMPT\n")
+        f.write("="*80 + "\n")
+
+
+def main():
+    """Main entry point - generate prompts for all players."""
+    print("\n" + "="*80)
+    print("🎮 AI PROMPT GENERATOR - Real Game State")
+    print("="*80 + "\n")
+    
+    # Load current game state
+    print("📖 Loading current game state...")
+    game_state = load_current_state()
+    
+    if not game_state:
+        return
+    
+    # Show basic info
+    meta = game_state.get("meta", {})
+    players = game_state.get("players", {})
+    
+    print(f"✓ Loaded game state")
+    print(f"  Phase: {meta.get('phase')}")
+    print(f"  Current Player: {meta.get('curr')}")
+    print(f"  Players: {', '.join(players.keys())}")
+    print()
+    
+    # Create prompt manager
+    config = AIConfig()
+    prompt_manager = PromptManager(config)
+    
+    # Create output directory
+    output_dir = Path('examples/ai_testing/my_games/prompts')
+    output_dir.mkdir(exist_ok=True, parents=True)
+    
+    print("📝 Generating prompts for each player...\n")
+    
+    # Generate prompt for each player
+    for player_name in players.keys():
+        print(f"  ⚙️  Generating prompt for player '{player_name}'...")
+        
+        try:
+            prompt = generate_prompt_for_player(player_name, game_state, prompt_manager)
+            save_prompt_to_file(player_name, prompt, output_dir)
+            
+            json_file = output_dir / f"prompt_player_{player_name}.json"
+            txt_file = output_dir / f"prompt_player_{player_name}.txt"
+            print(f"     ✓ JSON: {json_file}")
+            print(f"     ✓ TXT:  {txt_file}")
+            
+        except Exception as e:
+            print(f"     ❌ Error: {e}")
+            import traceback
+            traceback.print_exc()
+    
+    print("\n" + "="*80)
+    print("✅ DONE! Prompts generated successfully")
+    print("="*80)
+    print(f"\n📁 Output location: {output_dir.absolute()}")
+    print(f"\n💡 Files created per player:")
+    print(f"   - prompt_player_X.json (Send this to LLM)")
+    print(f"   - prompt_player_X.txt  (Human-readable)")
+    
+    print("\n" + "="*80 + "\n")
+
+
+if __name__ == '__main__':
+    main()

examples/ai_testing/my_games/current_state.json

@@ -0,0 +1,891 @@
+{
+  "timestamp": "2026-01-03T20:37:22.532273",
+  "state_number": 3,
+  "state": {
+    "hexes": [
+      {
+        "id": 1,
+        "type": "wood",
+        "number": 12,
+        "has_robber": false
+      },
+      {
+        "id": 2,
+        "type": "sheep",
+        "number": 5,
+        "has_robber": false
+      },
+      {
+        "id": 3,
+        "type": "wood",
+        "number": 4,
+        "has_robber": false
+      },
+      {
+        "id": 4,
+        "type": "sheep",
+        "number": 8,
+        "has_robber": false
+      },
+      {
+        "id": 5,
+        "type": "brick",
+        "number": 6,
+        "has_robber": false
+      },
+      {
+        "id": 6,
+        "type": "wood",
+        "number": 3,
+        "has_robber": false
+      },
+      {
+        "id": 7,
+        "type": "wheat",
+        "number": 8,
+        "has_robber": false
+      },
+      {
+        "id": 8,
+        "type": "brick",
+        "number": 10,
+        "has_robber": false
+      },
+      {
+        "id": 9,
+        "type": "wood",
+        "number": 11,
+        "has_robber": false
+      },
+      {
+        "id": 10,
+        "type": "desert",
+        "number": null,
+        "has_robber": true
+      },
+      {
+        "id": 11,
+        "type": "ore",
+        "number": 3,
+        "has_robber": false
+      },
+      {
+        "id": 12,
+        "type": "sheep",
+        "number": 4,
+        "has_robber": false
+      },
+      {
+        "id": 13,
+        "type": "brick",
+        "number": 10,
+        "has_robber": false
+      },
+      {
+        "id": 14,
+        "type": "wheat",
+        "number": 9,
+        "has_robber": false
+      },
+      {
+        "id": 15,
+        "type": "wheat",
+        "number": 6,
+        "has_robber": false
+      },
+      {
+        "id": 16,
+        "type": "sheep",
+        "number": 11,
+        "has_robber": false
+      },
+      {
+        "id": 17,
+        "type": "ore",
+        "number": 5,
+        "has_robber": false
+      },
+      {
+        "id": 18,
+        "type": "wheat",
+        "number": 9,
+        "has_robber": false
+      },
+      {
+        "id": 19,
+        "type": "ore",
+        "number": 2,
+        "has_robber": false
+      }
+    ],
+    "settlements": [
+      {
+        "id": "b_20",
+        "vertex": 20,
+        "player": 1
+      }
+    ],
+    "cities": [],
+    "roads": [],
+    "harbors": [
+      {
+        "id": 1,
+        "type": "any",
+        "ratio": 3,
+        "point_one": 9,
+        "point_two": 8
+      },
+      {
+        "id": 2,
+        "type": "sheep",
+        "ratio": 2,
+        "point_one": 17,
+        "point_two": 28
+      },
+      {
+        "id": 3,
+        "type": "wood",
+        "ratio": 2,
+        "point_one": 40,
+        "point_two": 48
+      },
+      {
+        "id": 4,
+        "type": "any",
+        "ratio": 3,
+        "point_one": 50,
+        "point_two": 51
+      },
+      {
+        "id": 5,
+        "type": "any",
+        "ratio": 3,
+        "point_one": 53,
+        "point_two": 54
+      },
+      {
+        "id": 6,
+        "type": "any",
+        "ratio": 3,
+        "point_one": 37,
+        "point_two": 38
+      },
+      {
+        "id": 7,
+        "type": "ore",
+        "ratio": 2,
+        "point_one": 26,
+        "point_two": 16
+      },
+      {
+        "id": 8,
+        "type": "brick",
+        "ratio": 2,
+        "point_one": 7,
+        "point_two": 6
+      },
+      {
+        "id": 9,
+        "type": "wheat",
+        "ratio": 2,
+        "point_one": 3,
+        "point_two": 2
+      }
+    ],
+    "players": [
+      {
+        "id": 0,
+        "name": "a",
+        "victory_points": 1,
+        "total_cards": 0,
+        "cards_list": [],
+        "dev_cards_list": [],
+        "settlements": 1,
+        "cities": 0,
+        "roads": 0,
+        "longest_road": 0,
+        "has_longest_road": false,
+        "knights": 0,
+        "knights_played": 0,
+        "has_largest_army": false
+      },
+      {
+        "id": 1,
+        "name": "b",
+        "victory_points": 0,
+        "total_cards": 0,
+        "cards_list": [],
+        "dev_cards_list": [],
+        "settlements": 0,
+        "cities": 0,
+        "roads": 0,
+        "longest_road": 0,
+        "has_longest_road": false,
+        "knights": 0,
+        "knights_played": 0,
+        "has_largest_army": false
+      },
+      {
+        "id": 2,
+        "name": "c",
+        "victory_points": 0,
+        "total_cards": 0,
+        "cards_list": [],
+        "dev_cards_list": [],
+        "settlements": 0,
+        "cities": 0,
+        "roads": 0,
+        "longest_road": 0,
+        "has_longest_road": false,
+        "knights": 0,
+        "knights_played": 0,
+        "has_largest_army": false
+      }
+    ],
+    "current_player": 0,
+    "current_phase": "SETUP_FIRST_ROUND",
+    "robber_position": [
+      2,
+      2
+    ],
+    "dice_result": null,
+    "points": [
+      {
+        "point_id": 1,
+        "adjacent_points": [
+          2,
+          9
+        ],
+        "adjacent_hexes": [
+          1
+        ]
+      },
+      {
+        "point_id": 2,
+        "adjacent_points": [
+          1,
+          3
+        ],
+        "adjacent_hexes": [
+          1
+        ]
+      },
+      {
+        "point_id": 3,
+        "adjacent_points": [
+          2,
+          4,
+          11
+        ],
+        "adjacent_hexes": [
+          2,
+          1
+        ]
+      },
+      {
+        "point_id": 4,
+        "adjacent_points": [
+          3,
+          5
+        ],
+        "adjacent_hexes": [
+          2
+        ]
+      },
+      {
+        "point_id": 5,
+        "adjacent_points": [
+          4,
+          6,
+          13
+        ],
+        "adjacent_hexes": [
+          3,
+          2
+        ]
+      },
+      {
+        "point_id": 6,
+        "adjacent_points": [
+          5,
+          7
+        ],
+        "adjacent_hexes": [
+          3
+        ]
+      },
+      {
+        "point_id": 7,
+        "adjacent_points": [
+          6,
+          15
+        ],
+        "adjacent_hexes": [
+          3
+        ]
+      },
+      {
+        "point_id": 8,
+        "adjacent_points": [
+          9,
+          18
+        ],
+        "adjacent_hexes": [
+          4
+        ]
+      },
+      {
+        "point_id": 9,
+        "adjacent_points": [
+          8,
+          10,
+          1
+        ],
+        "adjacent_hexes": [
+          4,
+          1
+        ]
+      },
+      {
+        "point_id": 10,
+        "adjacent_points": [
+          9,
+          11,
+          20
+        ],
+        "adjacent_hexes": [
+          5,
+          4,
+          1
+        ]
+      },
+      {
+        "point_id": 11,
+        "adjacent_points": [
+          10,
+          12,
+          3
+        ],
+        "adjacent_hexes": [
+          5,
+          2,
+          1
+        ]
+      },
+      {
+        "point_id": 12,
+        "adjacent_points": [
+          11,
+          13,
+          22
+        ],
+        "adjacent_hexes": [
+          6,
+          5,
+          2
+        ]
+      },
+      {
+        "point_id": 13,
+        "adjacent_points": [
+          12,
+          14,
+          5
+        ],
+        "adjacent_hexes": [
+          6,
+          3,
+          2
+        ]
+      },
+      {
+        "point_id": 14,
+        "adjacent_points": [
+          13,
+          15,
+          24
+        ],
+        "adjacent_hexes": [
+          7,
+          6,
+          3
+        ]
+      },
+      {
+        "point_id": 15,
+        "adjacent_points": [
+          14,
+          16,
+          7
+        ],
+        "adjacent_hexes": [
+          7,
+          3
+        ]
+      },
+      {
+        "point_id": 16,
+        "adjacent_points": [
+          15,
+          26
+        ],
+        "adjacent_hexes": [
+          7
+        ]
+      },
+      {
+        "point_id": 17,
+        "adjacent_points": [
+          18,
+          28
+        ],
+        "adjacent_hexes": [
+          8
+        ]
+      },
+      {
+        "point_id": 18,
+        "adjacent_points": [
+          17,
+          19,
+          8
+        ],
+        "adjacent_hexes": [
+          8,
+          4
+        ]
+      },
+      {
+        "point_id": 19,
+        "adjacent_points": [
+          18,
+          20,
+          30
+        ],
+        "adjacent_hexes": [
+          9,
+          8,
+          4
+        ]
+      },
+      {
+        "point_id": 20,
+        "adjacent_points": [
+          19,
+          21,
+          10
+        ],
+        "adjacent_hexes": [
+          9,
+          5,
+          4
+        ]
+      },
+      {
+        "point_id": 21,
+        "adjacent_points": [
+          20,
+          22,
+          32
+        ],
+        "adjacent_hexes": [
+          10,
+          9,
+          5
+        ]
+      },
+      {
+        "point_id": 22,
+        "adjacent_points": [
+          21,
+          23,
+          12
+        ],
+        "adjacent_hexes": [
+          10,
+          6,
+          5
+        ]
+      },
+      {
+        "point_id": 23,
+        "adjacent_points": [
+          22,
+          24,
+          34
+        ],
+        "adjacent_hexes": [
+          11,
+          10,
+          6
+        ]
+      },
+      {
+        "point_id": 24,
+        "adjacent_points": [
+          23,
+          25,
+          14
+        ],
+        "adjacent_hexes": [
+          11,
+          7,
+          6
+        ]
+      },
+      {
+        "point_id": 25,
+        "adjacent_points": [
+          24,
+          26,
+          36
+        ],
+        "adjacent_hexes": [
+          12,
+          11,
+          7
+        ]
+      },
+      {
+        "point_id": 26,
+        "adjacent_points": [
+          25,
+          27,
+          16
+        ],
+        "adjacent_hexes": [
+          12,
+          7
+        ]
+      },
+      {
+        "point_id": 27,
+        "adjacent_points": [
+          26,
+          38
+        ],
+        "adjacent_hexes": [
+          12
+        ]
+      },
+      {
+        "point_id": 28,
+        "adjacent_points": [
+          29,
+          17
+        ],
+        "adjacent_hexes": [
+          8
+        ]
+      },
+      {
+        "point_id": 29,
+        "adjacent_points": [
+          28,
+          30,
+          39
+        ],
+        "adjacent_hexes": [
+          13,
+          8
+        ]
+      },
+      {
+        "point_id": 30,
+        "adjacent_points": [
+          29,
+          31,
+          19
+        ],
+        "adjacent_hexes": [
+          13,
+          9,
+          8
+        ]
+      },
+      {
+        "point_id": 31,
+        "adjacent_points": [
+          30,
+          32,
+          41
+        ],
+        "adjacent_hexes": [
+          14,
+          13,
+          9
+        ]
+      },
+      {
+        "point_id": 32,
+        "adjacent_points": [
+          31,
+          33,
+          21
+        ],
+        "adjacent_hexes": [
+          14,
+          10,
+          9
+        ]
+      },
+      {
+        "point_id": 33,
+        "adjacent_points": [
+          32,
+          34,
+          43
+        ],
+        "adjacent_hexes": [
+          15,
+          14,
+          10
+        ]
+      },
+      {
+        "point_id": 34,
+        "adjacent_points": [
+          33,
+          35,
+          23
+        ],
+        "adjacent_hexes": [
+          15,
+          11,
+          10
+        ]
+      },
+      {
+        "point_id": 35,
+        "adjacent_points": [
+          34,
+          36,
+          45
+        ],
+        "adjacent_hexes": [
+          16,
+          15,
+          11
+        ]
+      },
+      {
+        "point_id": 36,
+        "adjacent_points": [
+          35,
+          37,
+          25
+        ],
+        "adjacent_hexes": [
+          16,
+          12,
+          11
+        ]
+      },
+      {
+        "point_id": 37,
+        "adjacent_points": [
+          36,
+          38,
+          47
+        ],
+        "adjacent_hexes": [
+          16,
+          12
+        ]
+      },
+      {
+        "point_id": 38,
+        "adjacent_points": [
+          37,
+          27
+        ],
+        "adjacent_hexes": [
+          12
+        ]
+      },
+      {
+        "point_id": 39,
+        "adjacent_points": [
+          40,
+          29
+        ],
+        "adjacent_hexes": [
+          13
+        ]
+      },
+      {
+        "point_id": 40,
+        "adjacent_points": [
+          39,
+          41,
+          48
+        ],
+        "adjacent_hexes": [
+          17,
+          13
+        ]
+      },
+      {
+        "point_id": 41,
+        "adjacent_points": [
+          40,
+          42,
+          31
+        ],
+        "adjacent_hexes": [
+          17,
+          14,
+          13
+        ]
+      },
+      {
+        "point_id": 42,
+        "adjacent_points": [
+          41,
+          43,
+          50
+        ],
+        "adjacent_hexes": [
+          18,
+          17,
+          14
+        ]
+      },
+      {
+        "point_id": 43,
+        "adjacent_points": [
+          42,
+          44,
+          33
+        ],
+        "adjacent_hexes": [
+          18,
+          15,
+          14
+        ]
+      },
+      {
+        "point_id": 44,
+        "adjacent_points": [
+          43,
+          45,
+          52
+        ],
+        "adjacent_hexes": [
+          19,
+          18,
+          15
+        ]
+      },
+      {
+        "point_id": 45,
+        "adjacent_points": [
+          44,
+          46,
+          35
+        ],
+        "adjacent_hexes": [
+          19,
+          16,
+          15
+        ]
+      },
+      {
+        "point_id": 46,
+        "adjacent_points": [
+          45,
+          47,
+          54
+        ],
+        "adjacent_hexes": [
+          19,
+          16
+        ]
+      },
+      {
+        "point_id": 47,
+        "adjacent_points": [
+          46,
+          37
+        ],
+        "adjacent_hexes": [
+          16
+        ]
+      },
+      {
+        "point_id": 48,
+        "adjacent_points": [
+          49,
+          40
+        ],
+        "adjacent_hexes": [
+          17
+        ]
+      },
+      {
+        "point_id": 49,
+        "adjacent_points": [
+          48,
+          50
+        ],
+        "adjacent_hexes": [
+          17
+        ]
+      },
+      {
+        "point_id": 50,
+        "adjacent_points": [
+          49,
+          51,
+          42
+        ],
+        "adjacent_hexes": [
+          18,
+          17
+        ]
+      },
+      {
+        "point_id": 51,
+        "adjacent_points": [
+          50,
+          52
+        ],
+        "adjacent_hexes": [
+          18
+        ]
+      },
+      {
+        "point_id": 52,
+        "adjacent_points": [
+          51,
+          53,
+          44
+        ],
+        "adjacent_hexes": [
+          19,
+          18
+        ]
+      },
+      {
+        "point_id": 53,
+        "adjacent_points": [
+          52,
+          54
+        ],
+        "adjacent_hexes": [
+          19
+        ]
+      },
+      {
+        "point_id": 54,
+        "adjacent_points": [
+          53,
+          46
+        ],
+        "adjacent_hexes": [
+          19
+        ]
+      }
+    ]
+  }
+}

examples/ai_testing/my_games/current_state_optimized.txt

@@ -0,0 +1,25 @@
+1. LOOKUP TABLES:
+   • "H" (Hexes): Array where Index = HexID. Value = Resource+Num.
+     Example: H[1]="W12" -> Hex 1 is Wood 12.
+   • "N" (Nodes): Array where Index = NodeID.
+     Format: [ [Neighbors], [HexIDs], Port? ]
+     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].
+
+2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.
+          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.
+
+3. STATE: "bld"=[NodeID, Owner, Type], "rds"=[[From,To], Owner].
+
+4. PLAYERS: "res"={Resource:Count}, "dev"={"h":[Hidden Cards], "r":[Revealed] (K=Knight)}, 
+            "stat"=["LR" (Longest Road), "LA" (Largest Army)].
+
+5. ROBBER: Located at HexID specified in "meta.robber". H[id] is blocked.
+
+JSON:
+{
+  "meta":{"curr":"a","phase":"SETUP_FIRST_ROUND","robber":10,"dice":null},
+  "H":["","W12","S5","W4","S8","B6","W3","Wh8","B10","W11","D","O3","S4","B10","Wh9","Wh6","S11","O5","Wh9","O2"],
+  "N":[null,[[2,9],[1]],[[1,3],[1],"Wh2"],[[2,4,11],[2,1],"Wh2"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],"B2"],[[6,15],[3],"B2"],[[9,18],[4],"?3"],[[8,10,1],[4,1],"?3"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],"O2"],[[18,28],[8],"S2"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],"O2"],[[26,38],[12]],[[29,17],[8],"S2"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],"?3"],[[37,27],[12],"?3"],[[40,29],[13]],[[39,41,48],[17,13],"W2"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],"W2"],[[48,50],[17]],[[49,51,42],[18,17],"?3"],[[50,52],[18],"?3"],[[51,53,44],[19,18]],[[52,54],[19],"?3"],[[53,46],[19],"?3"]],
+  "state":{"bld":[[20,"a","S"]],"rds":[]},
+  "players":{"a":{"vp":1,"res":{}},"b":{"vp":0,"res":{}},"c":{"vp":0,"res":{}}}
+}

examples/ai_testing/my_games/prompts/a

@@ -0,0 +1,106 @@
+================================================================================
+AI AGENT PROMPT - PLAYER A
+Generated: 2026-01-03 20:17:07
+================================================================================
+
+📋 RESPONSE SCHEMA (Expected LLM Output Format)
+--------------------------------------------------------------------------------
+{
+  "type": "object",
+  "required": [
+    "internal_thinking",
+    "action"
+  ],
+  "properties": {
+    "internal_thinking": {
+      "type": "string",
+      "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+      "minLength": 50
+    },
+    "note_to_self": {
+      "type": "string",
+      "description": "A note to remember for next turn. What are you waiting for? What's your plan?",
+      "examples": [
+        "Waiting for Red's response on trade",
+        "Focus on building toward ore port next",
+        "Watch Blue's progress on longest road"
+      ]
+    },
+    "say_outloud": {
+      "type": "string",
+      "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk.",
+      "examples": [
+        "Anyone want to trade sheep for wood?",
+        "Red, can you give me 1 Brick for 2 Sheep?",
+        "I'm so behind, don't steal from me!"
+      ]
+    },
+    "action": {
+      "type": "object",
+      "required": [
+        "type",
+        "parameters"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "The action type (must match one from allowed_actions in constraints)",
+          "examples": [
+            "BUILD_SETTLEMENT",
+            "BUILD_ROAD",
+            "OFFER_TRADE",
+            "WAIT_FOR_RESPONSE",
+            "END_TURN"
+          ]
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Action-specific parameters (structure matches allowed_actions examples)"
+        }
+      }
+    }
+  },
+  "example": {
+    "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": {}
+    }
+  }
+}
+
+================================================================================
+📨 PROMPT TO SEND TO LLM
+================================================================================
+
+{
+  "meta_data": {
+    "agent_name": "a",
+    "my_color": "Red",
+    "role": "You are player 'a' (Red). Play strategically to win."
+  },
+  "task_context": {
+    "what_just_happened": "It's your turn in the setup phase. Place your first settlement.",
+    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Only one action is currently available."
+  },
+  "game_state": "\nFORMAT GUIDE:\n• H array: Index=HexID, Value=Resource+Number (W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert)\n• N array: Index=NodeID, Value=[[Neighbors], [HexIDs], Port?] where Port: ?3=Any(3:1), X2=Specific(2:1)\n• bld: [NodeID, Owner, Type] where Type: S=Settlement, C=City\n• rds: [[From, To], Owner]\n• Players res: {ResourceCode: Count}\n• Players dev: {\"h\": [Hidden], \"r\": [Revealed]} - Cards: K=Knight, M=Monopoly, Y=Year of Plenty, R=Road Building, V=Victory Point\n• Players stat: [\"LR\"=Longest Road, \"LA\"=Largest Army]\n\nGAME STATE:\n{\n  \"meta\": {\n    \"curr\": \"a\",\n    \"phase\": \"SETUP_FIRST_ROUND\",\n    \"robber\": 10,\n    \"dice\": null\n  },\n  \"H\": [\n    \"\",\n    \"W12\",\n    \"S5\",\n    \"W4\",\n    \"S8\",\n    \"B6\",\n    \"W3\",\n    \"Wh8\",\n    \"B10\",\n    \"W11\",\n    \"D\",\n    \"O3\",\n    \"S4\",\n    \"B10\",\n    \"Wh9\",\n    \"Wh6\",\n    \"S11\",\n    \"O5\",\n    \"Wh9\",\n    \"O2\"\n  ],\n  \"N\": [\n    null,\n    [\n      [\n        2,\n        9\n      ],\n      [\n        1\n      ]\n    ],\n    [\n      [\n        1,\n        3\n      ],\n      [\n        1\n      ],\n      \"Wh2\"\n    ],\n    [\n      [\n        2,\n        4,\n        11\n      ],\n      [\n        2,\n        1\n      ],\n      \"Wh2\"\n    ],\n    [\n      [\n        3,\n        5\n      ],\n      [\n        2\n      ]\n    ],\n    [\n      [\n        4,\n        6,\n        13\n      ],\n      [\n        3,\n        2\n      ]\n    ],\n    [\n      [\n        5,\n        7\n      ],\n      [\n        3\n      ],\n      \"B2\"\n    ],\n    [\n      [\n        6,\n        15\n      ],\n      [\n        3\n      ],\n      \"B2\"\n    ],\n    [\n      [\n        9,\n        18\n      ],\n      [\n        4\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        8,\n        10,\n        1\n      ],\n      [\n        4,\n        1\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        9,\n        11,\n        20\n      ],\n      [\n        5,\n        4,\n        1\n      ]\n    ],\n    [\n      [\n        10,\n        12,\n        3\n      ],\n      [\n        5,\n        2,\n        1\n      ]\n    ],\n    [\n      [\n        11,\n        13,\n        22\n      ],\n      [\n        6,\n        5,\n        2\n      ]\n    ],\n    [\n      [\n        12,\n        14,\n        5\n      ],\n      [\n        6,\n        3,\n        2\n      ]\n    ],\n    [\n      [\n        13,\n        15,\n        24\n      ],\n      [\n        7,\n        6,\n        3\n      ]\n    ],\n    [\n      [\n        14,\n        16,\n        7\n      ],\n      [\n        7,\n        3\n      ]\n    ],\n    [\n      [\n        15,\n        26\n      ],\n      [\n        7\n      ],\n      \"O2\"\n    ],\n    [\n      [\n        18,\n        28\n      ],\n      [\n        8\n      ],\n      \"S2\"\n    ],\n    [\n      [\n        17,\n        19,\n        8\n      ],\n      [\n        8,\n        4\n      ]\n    ],\n    [\n      [\n        18,\n        20,\n        30\n      ],\n      [\n        9,\n        8,\n        4\n      ]\n    ],\n    [\n      [\n        19,\n        21,\n        10\n      ],\n      [\n        9,\n        5,\n        4\n      ]\n    ],\n    [\n      [\n        20,\n        22,\n        32\n      ],\n      [\n        10,\n        9,\n        5\n      ]\n    ],\n    [\n      [\n        21,\n        23,\n        12\n      ],\n      [\n        10,\n        6,\n        5\n      ]\n    ],\n    [\n      [\n        22,\n        24,\n        34\n      ],\n      [\n        11,\n        10,\n        6\n      ]\n    ],\n    [\n      [\n        23,\n        25,\n        14\n      ],\n      [\n        11,\n        7,\n        6\n      ]\n    ],\n    [\n      [\n        24,\n        26,\n        36\n      ],\n      [\n        12,\n        11,\n        7\n      ]\n    ],\n    [\n      [\n        25,\n        27,\n        16\n      ],\n      [\n        12,\n        7\n      ],\n      \"O2\"\n    ],\n    [\n      [\n        26,\n        38\n      ],\n      [\n        12\n      ]\n    ],\n    [\n      [\n        29,\n        17\n      ],\n      [\n        8\n      ],\n      \"S2\"\n    ],\n    [\n      [\n        28,\n        30,\n        39\n      ],\n      [\n        13,\n        8\n      ]\n    ],\n    [\n      [\n        29,\n        31,\n        19\n      ],\n      [\n        13,\n        9,\n        8\n      ]\n    ],\n    [\n      [\n        30,\n        32,\n        41\n      ],\n      [\n        14,\n        13,\n        9\n      ]\n    ],\n    [\n      [\n        31,\n        33,\n        21\n      ],\n      [\n        14,\n        10,\n        9\n      ]\n    ],\n    [\n      [\n        32,\n        34,\n        43\n      ],\n      [\n        15,\n        14,\n        10\n      ]\n    ],\n    [\n      [\n        33,\n        35,\n        23\n      ],\n      [\n        15,\n        11,\n        10\n      ]\n    ],\n    [\n      [\n        34,\n        36,\n        45\n      ],\n      [\n        16,\n        15,\n        11\n      ]\n    ],\n    [\n      [\n        35,\n        37,\n        25\n      ],\n      [\n        16,\n        12,\n        11\n      ]\n    ],\n    [\n      [\n        36,\n        38,\n        47\n      ],\n      [\n        16,\n        12\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        37,\n        27\n      ],\n      [\n        12\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        40,\n        29\n      ],\n      [\n        13\n      ]\n    ],\n    [\n      [\n        39,\n        41,\n        48\n      ],\n      [\n        17,\n        13\n      ],\n      \"W2\"\n    ],\n    [\n      [\n        40,\n        42,\n        31\n      ],\n      [\n        17,\n        14,\n        13\n      ]\n    ],\n    [\n      [\n        41,\n        43,\n        50\n      ],\n      [\n        18,\n        17,\n        14\n      ]\n    ],\n    [\n      [\n        42,\n        44,\n        33\n      ],\n      [\n        18,\n        15,\n        14\n      ]\n    ],\n    [\n      [\n        43,\n        45,\n        52\n      ],\n      [\n        19,\n        18,\n        15\n      ]\n    ],\n    [\n      [\n        44,\n        46,\n        35\n      ],\n      [\n        19,\n        16,\n        15\n      ]\n    ],\n    [\n      [\n        45,\n        47,\n        54\n      ],\n      [\n        19,\n        16\n      ]\n    ],\n    [\n      [\n        46,\n        37\n      ],\n      [\n        16\n      ]\n    ],\n    [\n      [\n        49,\n        40\n      ],\n      [\n        17\n      ],\n      \"W2\"\n    ],\n    [\n      [\n        48,\n        50\n      ],\n      [\n        17\n      ]\n    ],\n    [\n      [\n        49,\n        51,\n        42\n      ],\n      [\n        18,\n        17\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        50,\n        52\n      ],\n      [\n        18\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        51,\n        53,\n        44\n      ],\n      [\n        19,\n        18\n      ]\n    ],\n    [\n      [\n        52,\n        54\n      ],\n      [\n        19\n      ],\n      \"?3\"\n    ],\n    [\n      [\n        53,\n        46\n      ],\n      [\n        19\n      ],\n      \"?3\"\n    ]\n  ],\n  \"state\": {\n    \"bld\": [],\n    \"rds\": []\n  },\n  \"players\": {\n    \"a\": {\n      \"vp\": 0,\n      \"res\": {}\n    },\n    \"b\": {\n      \"vp\": 0,\n      \"res\": {}\n    },\n    \"c\": {\n      \"vp\": 0,\n      \"res\": {}\n    }\n  }\n}",
+  "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": [
+      {
+        "action": "place_settlement",
+        "description": "Place your starting settlement on an available node",
+        "example_parameters": {
+          "node_id": 20,
+          "reasoning": "Good resource diversity and probability"
+        }
+      }
+    ]
+  }
+}
+
+================================================================================
+END OF PROMPT
+================================================================================

examples/ai_testing/my_games/prompts/prompt_player_a.json

@@ -0,0 +1,81 @@
+{
+  "response_schema": {
+    "type": "object",
+    "required": [
+      "internal_thinking",
+      "action"
+    ],
+    "properties": {
+      "internal_thinking": {
+        "type": "string",
+        "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+        "minLength": 50
+      },
+      "note_to_self": {
+        "type": "string",
+        "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+      },
+      "say_outloud": {
+        "type": "string",
+        "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+      },
+      "action": {
+        "type": "object",
+        "required": [
+          "type",
+          "parameters"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "The action type (must match one from allowed_actions in constraints)"
+          },
+          "parameters": {
+            "type": "object",
+            "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+            "properties": {
+              "target": {
+                "type": "string",
+                "description": "The target of the action (if applicable)"
+              },
+              "amount": {
+                "type": "number",
+                "description": "The amount (if applicable)"
+              },
+              "location": {
+                "type": "string",
+                "description": "The location (if applicable)"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "system_instruction": "You are an expert Settlers of Catan player. Analyze the game state carefully and respond with your chosen action in the exact JSON format specified in response_schema.",
+  "prompt": {
+    "meta_data": {
+      "agent_name": "a",
+      "my_color": "Red",
+      "role": "You are player 'a' (Red). Play strategically to win."
+    },
+    "task_context": {
+      "what_just_happened": "It's your turn in the setup phase. Place your first settlement.",
+      "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Only one action is currently available."
+    },
+    "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}",
+    "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": [
+        {
+          "action": "place_settlement",
+          "description": "Place your starting settlement on an available node",
+          "example_parameters": {
+            "node_id": 20,
+            "reasoning": "Good resource diversity and probability"
+          }
+        }
+      ]
+    }
+  }
+}

examples/ai_testing/my_games/prompts/prompt_player_a.txt

@@ -0,0 +1,94 @@
+================================================================================
+AI AGENT PROMPT - PLAYER A
+Generated: 2026-01-03 20:37:23
+================================================================================
+
+📋 RESPONSE SCHEMA (Expected LLM Output Format)
+--------------------------------------------------------------------------------
+{
+  "type": "object",
+  "required": [
+    "internal_thinking",
+    "action"
+  ],
+  "properties": {
+    "internal_thinking": {
+      "type": "string",
+      "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+      "minLength": 50
+    },
+    "note_to_self": {
+      "type": "string",
+      "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+    },
+    "say_outloud": {
+      "type": "string",
+      "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+    },
+    "action": {
+      "type": "object",
+      "required": [
+        "type",
+        "parameters"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "The action type (must match one from allowed_actions in constraints)"
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+          "properties": {
+            "target": {
+              "type": "string",
+              "description": "The target of the action (if applicable)"
+            },
+            "amount": {
+              "type": "number",
+              "description": "The amount (if applicable)"
+            },
+            "location": {
+              "type": "string",
+              "description": "The location (if applicable)"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+================================================================================
+📨 PROMPT TO SEND TO LLM
+================================================================================
+
+{
+  "meta_data": {
+    "agent_name": "a",
+    "my_color": "Red",
+    "role": "You are player 'a' (Red). Play strategically to win."
+  },
+  "task_context": {
+    "what_just_happened": "It's your turn in the setup phase. Place your first settlement.",
+    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Only one action is currently available."
+  },
+  "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}",
+  "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": [
+      {
+        "action": "place_settlement",
+        "description": "Place your starting settlement on an available node",
+        "example_parameters": {
+          "node_id": 20,
+          "reasoning": "Good resource diversity and probability"
+        }
+      }
+    ]
+  }
+}
+
+================================================================================
+END OF PROMPT
+================================================================================

examples/ai_testing/my_games/prompts/prompt_player_b.json

@@ -0,0 +1,68 @@
+{
+  "response_schema": {
+    "type": "object",
+    "required": [
+      "internal_thinking",
+      "action"
+    ],
+    "properties": {
+      "internal_thinking": {
+        "type": "string",
+        "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+        "minLength": 50
+      },
+      "note_to_self": {
+        "type": "string",
+        "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+      },
+      "say_outloud": {
+        "type": "string",
+        "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+      },
+      "action": {
+        "type": "object",
+        "required": [
+          "type",
+          "parameters"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "The action type (must match one from allowed_actions in constraints)"
+          },
+          "parameters": {
+            "type": "object",
+            "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+            "properties": {
+              "target": {
+                "type": "string",
+                "description": "The target of the action (if applicable)"
+              },
+              "amount": {
+                "type": "number",
+                "description": "The amount (if applicable)"
+              },
+              "location": {
+                "type": "string",
+                "description": "The location (if applicable)"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "system_instruction": "You are an expert Settlers of Catan player. Analyze the game state carefully and respond with your chosen action in the exact JSON format specified in response_schema.",
+  "prompt": {
+    "meta_data": {
+      "agent_name": "b",
+      "my_color": "Blue",
+      "role": "You are player 'b' (Blue). Play strategically to win."
+    },
+    "task_context": {
+      "what_just_happened": "It's a's turn to place their first settlement.",
+      "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Consider all strategic implications before deciding."
+    },
+    "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+  }
+}

examples/ai_testing/my_games/prompts/prompt_player_b.txt

@@ -0,0 +1,81 @@
+================================================================================
+AI AGENT PROMPT - PLAYER B
+Generated: 2026-01-03 20:37:23
+================================================================================
+
+📋 RESPONSE SCHEMA (Expected LLM Output Format)
+--------------------------------------------------------------------------------
+{
+  "type": "object",
+  "required": [
+    "internal_thinking",
+    "action"
+  ],
+  "properties": {
+    "internal_thinking": {
+      "type": "string",
+      "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+      "minLength": 50
+    },
+    "note_to_self": {
+      "type": "string",
+      "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+    },
+    "say_outloud": {
+      "type": "string",
+      "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+    },
+    "action": {
+      "type": "object",
+      "required": [
+        "type",
+        "parameters"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "The action type (must match one from allowed_actions in constraints)"
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+          "properties": {
+            "target": {
+              "type": "string",
+              "description": "The target of the action (if applicable)"
+            },
+            "amount": {
+              "type": "number",
+              "description": "The amount (if applicable)"
+            },
+            "location": {
+              "type": "string",
+              "description": "The location (if applicable)"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+================================================================================
+📨 PROMPT TO SEND TO LLM
+================================================================================
+
+{
+  "meta_data": {
+    "agent_name": "b",
+    "my_color": "Blue",
+    "role": "You are player 'b' (Blue). Play strategically to win."
+  },
+  "task_context": {
+    "what_just_happened": "It's a's turn to place their first settlement.",
+    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Consider all strategic implications before deciding."
+  },
+  "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+}
+
+================================================================================
+END OF PROMPT
+================================================================================

examples/ai_testing/my_games/prompts/prompt_player_c.json

@@ -0,0 +1,68 @@
+{
+  "response_schema": {
+    "type": "object",
+    "required": [
+      "internal_thinking",
+      "action"
+    ],
+    "properties": {
+      "internal_thinking": {
+        "type": "string",
+        "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+        "minLength": 50
+      },
+      "note_to_self": {
+        "type": "string",
+        "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+      },
+      "say_outloud": {
+        "type": "string",
+        "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+      },
+      "action": {
+        "type": "object",
+        "required": [
+          "type",
+          "parameters"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "The action type (must match one from allowed_actions in constraints)"
+          },
+          "parameters": {
+            "type": "object",
+            "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+            "properties": {
+              "target": {
+                "type": "string",
+                "description": "The target of the action (if applicable)"
+              },
+              "amount": {
+                "type": "number",
+                "description": "The amount (if applicable)"
+              },
+              "location": {
+                "type": "string",
+                "description": "The location (if applicable)"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "system_instruction": "You are an expert Settlers of Catan player. Analyze the game state carefully and respond with your chosen action in the exact JSON format specified in response_schema.",
+  "prompt": {
+    "meta_data": {
+      "agent_name": "c",
+      "my_color": "White",
+      "role": "You are player 'c' (White). Play strategically to win."
+    },
+    "task_context": {
+      "what_just_happened": "It's a's turn to place their first settlement.",
+      "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Consider all strategic implications before deciding."
+    },
+    "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+  }
+}

examples/ai_testing/my_games/prompts/prompt_player_c.txt

@@ -0,0 +1,81 @@
+================================================================================
+AI AGENT PROMPT - PLAYER C
+Generated: 2026-01-03 20:37:23
+================================================================================
+
+📋 RESPONSE SCHEMA (Expected LLM Output Format)
+--------------------------------------------------------------------------------
+{
+  "type": "object",
+  "required": [
+    "internal_thinking",
+    "action"
+  ],
+  "properties": {
+    "internal_thinking": {
+      "type": "string",
+      "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+      "minLength": 50
+    },
+    "note_to_self": {
+      "type": "string",
+      "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+    },
+    "say_outloud": {
+      "type": "string",
+      "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+    },
+    "action": {
+      "type": "object",
+      "required": [
+        "type",
+        "parameters"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "The action type (must match one from allowed_actions in constraints)"
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+          "properties": {
+            "target": {
+              "type": "string",
+              "description": "The target of the action (if applicable)"
+            },
+            "amount": {
+              "type": "number",
+              "description": "The amount (if applicable)"
+            },
+            "location": {
+              "type": "string",
+              "description": "The location (if applicable)"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+================================================================================
+📨 PROMPT TO SEND TO LLM
+================================================================================
+
+{
+  "meta_data": {
+    "agent_name": "c",
+    "my_color": "White",
+    "role": "You are player 'c' (White). Play strategically to win."
+  },
+  "task_context": {
+    "what_just_happened": "It's a's turn to place their first settlement.",
+    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Consider all strategic implications before deciding."
+  },
+  "game_state": "\n  1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" -> Hex 1 is Wood 12.\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [ [Neighbors], [HexIDs], Port? ]\n     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].\n\n2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.\n          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.\n\n3. STATE: \"bld\"=[NodeID, Owner, Type], \"rds\"=[[From,To], Owner].\n\n4. PLAYERS: \"res\"={Resource:Count}, \"dev\"={\"h\":[Hidden Cards], \"r\":[Revealed] (K=Knight)}, \n            \"stat\"=[\"LR\" (Longest Road), \"LA\" (Largest Army)].\n\n5. ROBBER: Located at HexID specified in \"meta.robber\". H[id] is blocked.\n\nJSON:\n{\"meta\":{\"curr\":\"a\",\"phase\":\"SETUP_FIRST_ROUND\",\"robber\":10,\"dice\":null},\"H\":[\"\",\"W12\",\"S5\",\"W4\",\"S8\",\"B6\",\"W3\",\"Wh8\",\"B10\",\"W11\",\"D\",\"O3\",\"S4\",\"B10\",\"Wh9\",\"Wh6\",\"S11\",\"O5\",\"Wh9\",\"O2\"],\"N\":[null,[[2,9],[1]],[[1,3],[1],\"Wh2\"],[[2,4,11],[2,1],\"Wh2\"],[[3,5],[2]],[[4,6,13],[3,2]],[[5,7],[3],\"B2\"],[[6,15],[3],\"B2\"],[[9,18],[4],\"?3\"],[[8,10,1],[4,1],\"?3\"],[[9,11,20],[5,4,1]],[[10,12,3],[5,2,1]],[[11,13,22],[6,5,2]],[[12,14,5],[6,3,2]],[[13,15,24],[7,6,3]],[[14,16,7],[7,3]],[[15,26],[7],\"O2\"],[[18,28],[8],\"S2\"],[[17,19,8],[8,4]],[[18,20,30],[9,8,4]],[[19,21,10],[9,5,4]],[[20,22,32],[10,9,5]],[[21,23,12],[10,6,5]],[[22,24,34],[11,10,6]],[[23,25,14],[11,7,6]],[[24,26,36],[12,11,7]],[[25,27,16],[12,7],\"O2\"],[[26,38],[12]],[[29,17],[8],\"S2\"],[[28,30,39],[13,8]],[[29,31,19],[13,9,8]],[[30,32,41],[14,13,9]],[[31,33,21],[14,10,9]],[[32,34,43],[15,14,10]],[[33,35,23],[15,11,10]],[[34,36,45],[16,15,11]],[[35,37,25],[16,12,11]],[[36,38,47],[16,12],\"?3\"],[[37,27],[12],\"?3\"],[[40,29],[13]],[[39,41,48],[17,13],\"W2\"],[[40,42,31],[17,14,13]],[[41,43,50],[18,17,14]],[[42,44,33],[18,15,14]],[[43,45,52],[19,18,15]],[[44,46,35],[19,16,15]],[[45,47,54],[19,16]],[[46,37],[16]],[[49,40],[17],\"W2\"],[[48,50],[17]],[[49,51,42],[18,17],\"?3\"],[[50,52],[18],\"?3\"],[[51,53,44],[19,18]],[[52,54],[19],\"?3\"],[[53,46],[19],\"?3\"]],\"state\":{\"bld\":[[20,\"a\",\"S\"]],\"rds\":[]},\"players\":{\"a\":{\"vp\":1,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+}
+
+================================================================================
+END OF PROMPT
+================================================================================

examples/ai_testing/my_games/test_prompt_format.json

@@ -0,0 +1,111 @@
+{
+  "response_schema": {
+    "type": "object",
+    "required": [
+      "internal_thinking",
+      "action"
+    ],
+    "properties": {
+      "internal_thinking": {
+        "type": "string",
+        "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+        "minLength": 50
+      },
+      "note_to_self": {
+        "type": "string",
+        "description": "A note to remember for next turn. What are you waiting for? What's your plan?",
+        "examples": [
+          "Waiting for Red's response on trade",
+          "Focus on building toward ore port next",
+          "Watch Blue's progress on longest road"
+        ]
+      },
+      "say_outloud": {
+        "type": "string",
+        "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk.",
+        "examples": [
+          "Anyone want to trade sheep for wood?",
+          "Red, can you give me 1 Brick for 2 Sheep?",
+          "I'm so behind, don't steal from me!"
+        ]
+      },
+      "action": {
+        "type": "object",
+        "required": [
+          "type",
+          "parameters"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "The action type (must match one from allowed_actions in constraints)",
+            "examples": [
+              "BUILD_SETTLEMENT",
+              "BUILD_ROAD",
+              "OFFER_TRADE",
+              "WAIT_FOR_RESPONSE",
+              "END_TURN"
+            ]
+          },
+          "parameters": {
+            "type": "object",
+            "description": "Action-specific parameters (structure matches allowed_actions examples)"
+          }
+        }
+      }
+    },
+    "example": {
+      "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": {}
+      }
+    }
+  },
+  "system_instruction": "You are an expert Settlers of Catan player. Respond in JSON format.",
+  "prompt": {
+    "meta_data": {
+      "agent_name": "a",
+      "my_color": "Red",
+      "role": "You are player 'a' (Red). Play strategically to win."
+    },
+    "task_context": {
+      "what_just_happened": "You rolled an 8. You received 2 wood.",
+      "instructions": "Choose your action from 'allowed_actions'."
+    },
+    "game_state": "\nFORMAT GUIDE:\n• H array: Index=HexID, Value=Resource+Number (W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert)\n• N array: Index=NodeID, Value=[[Neighbors], [HexIDs], Port?] where Port: ?3=Any(3:1), X2=Specific(2:1)\n• bld: [NodeID, Owner, Type] where Type: S=Settlement, C=City\n• rds: [[From, To], Owner]\n• Players res: {ResourceCode: Count}\n• Players dev: {\"h\": [Hidden], \"r\": [Revealed]} - Cards: K=Knight, M=Monopoly, Y=Year of Plenty, R=Road Building, V=Victory Point\n• Players stat: [\"LR\"=Longest Road, \"LA\"=Largest Army]\n\nGAME STATE:\n{\n  \"H\": [\n    \"\",\n    \"W12\",\n    \"S5\",\n    \"W4\",\n    \"S8\",\n    \"B6\"\n  ],\n  \"N\": [\n    [],\n    [\n      [\n        2,\n        5\n      ],\n      [\n        1,\n        2\n      ],\n      null\n    ],\n    [\n      [\n        1,\n        3\n      ],\n      [\n        1,\n        3\n      ],\n      \"W2\"\n    ]\n  ],\n  \"players\": {\n    \"a\": {\n      \"vp\": 2,\n      \"res\": {\n        \"W\": 3,\n        \"B\": 1\n      },\n      \"dev\": {\n        \"h\": [\n          \"K\"\n        ],\n        \"r\": []\n      },\n      \"stat\": []\n    },\n    \"b\": {\n      \"vp\": 1,\n      \"res\": {\n        \"S\": 2\n      },\n      \"dev\": {\n        \"h\": [],\n        \"r\": []\n      },\n      \"stat\": []\n    }\n  },\n  \"bld\": [\n    [\n      20,\n      \"a\",\n      \"S\"\n    ],\n    [\n      25,\n      \"b\",\n      \"S\"\n    ]\n  ],\n  \"rds\": [\n    [\n      [\n        20,\n        21\n      ],\n      \"a\"\n    ],\n    [\n      [\n        25,\n        26\n      ],\n      \"b\"\n    ]\n  ],\n  \"meta\": {\n    \"robber\": 10,\n    \"phase\": \"MAIN_GAME\",\n    \"curr\": \"a\",\n    \"dice\": 8\n  }\n}",
+    "social_context": {
+      "recent_chat": [
+        {
+          "sender": "b",
+          "content": "Anyone need sheep?"
+        }
+      ]
+    },
+    "memory": {
+      "notes_for_myself": [
+        "b needs ore, I should trade",
+        "Focus on longest road"
+      ]
+    },
+    "constraints": {
+      "usage_instructions": "Choose one action. Use exact parameter structure.",
+      "allowed_actions": [
+        {
+          "action": "build_road",
+          "description": "Build a road on an edge",
+          "example_parameters": {
+            "edge_id": 15
+          }
+        },
+        {
+          "action": "end_turn",
+          "description": "End your turn",
+          "example_parameters": {}
+        }
+      ]
+    }
+  }
+}

examples/ai_testing/my_games/test_prompt_output.json

@@ -1,792 +0,0 @@
-{
-  "meta_data": {
-    "agent_name": "a",
-    "my_color": "Blue",
-    "role": "You are a strategic Catan player."
-  },
-  "task_context": {
-    "what_just_happened": "Game started. It's your turn to place your first settlement.",
-    "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. Only one action is currently available."
-  },
-  "game_state_legend": "OPTIMIZED STATE FORMAT GUIDE:\n        \n1. LOOKUP TABLES:\n   • \"H\" (Hexes): Array where Index = HexID. Value = Resource+Num.\n     Example: H[1]=\"W12\" → Hex 1 is Wood with number 12\n   • \"N\" (Nodes): Array where Index = NodeID.\n     Format: [[Neighbors], [HexIDs], Port?]\n     To find yield: Check N[node_id], get HexIDs, look up in H array\n\n2. RESOURCE CODES:\n   W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert\n   Ports: ?3=Any(3:1), X2=Specific(2:1) where X is resource\n\n3. GAME STATE:\n   \"bld\": [NodeID, Owner, Type] where Type: S=Settlement, C=City\n   \"rds\": [[From, To], Owner]\n\n4. PLAYERS:\n   \"res\": {ResourceCode: Count}\n   \"dev\": {\"h\": [HiddenCards], \"r\": [RevealedCards]}\n   \"stat\": [\"LR\"=Longest Road, \"LA\"=Largest Army]\n\n5. META:\n   \"robber\": HexID where robber is located (blocks that hex)\n   \"phase\": Current game phase\n   \"curr\": Current player's turn\n",
-  "game_state": {
-    "my_private_info": {
-      "resources": {},
-      "development_cards": {
-        "hidden": [],
-        "revealed": []
-      },
-      "victory_points": 1,
-      "has_longest_road": false,
-      "has_largest_army": false
-    },
-    "board_state": {
-      "H": [
-        "",
-        "W12",
-        "S5",
-        "W4",
-        "S8",
-        "B6",
-        "W3",
-        "Wh8",
-        "B10",
-        "W11",
-        "D",
-        "O3",
-        "S4",
-        "B10",
-        "Wh9",
-        "Wh6",
-        "S11",
-        "O5",
-        "Wh9",
-        "O2"
-      ],
-      "N": [
-        null,
-        [
-          [
-            2,
-            9
-          ],
-          [
-            1
-          ]
-        ],
-        [
-          [
-            1,
-            3
-          ],
-          [
-            1
-          ],
-          "Wh2"
-        ],
-        [
-          [
-            2,
-            4,
-            11
-          ],
-          [
-            2,
-            1
-          ],
-          "Wh2"
-        ],
-        [
-          [
-            3,
-            5
-          ],
-          [
-            2
-          ]
-        ],
-        [
-          [
-            4,
-            6,
-            13
-          ],
-          [
-            3,
-            2
-          ]
-        ],
-        [
-          [
-            5,
-            7
-          ],
-          [
-            3
-          ],
-          "B2"
-        ],
-        [
-          [
-            6,
-            15
-          ],
-          [
-            3
-          ],
-          "B2"
-        ],
-        [
-          [
-            9,
-            18
-          ],
-          [
-            4
-          ],
-          "?3"
-        ],
-        [
-          [
-            8,
-            10,
-            1
-          ],
-          [
-            4,
-            1
-          ],
-          "?3"
-        ],
-        [
-          [
-            9,
-            11,
-            20
-          ],
-          [
-            5,
-            4,
-            1
-          ]
-        ],
-        [
-          [
-            10,
-            12,
-            3
-          ],
-          [
-            5,
-            2,
-            1
-          ]
-        ],
-        [
-          [
-            11,
-            13,
-            22
-          ],
-          [
-            6,
-            5,
-            2
-          ]
-        ],
-        [
-          [
-            12,
-            14,
-            5
-          ],
-          [
-            6,
-            3,
-            2
-          ]
-        ],
-        [
-          [
-            13,
-            15,
-            24
-          ],
-          [
-            7,
-            6,
-            3
-          ]
-        ],
-        [
-          [
-            14,
-            16,
-            7
-          ],
-          [
-            7,
-            3
-          ]
-        ],
-        [
-          [
-            15,
-            26
-          ],
-          [
-            7
-          ],
-          "O2"
-        ],
-        [
-          [
-            18,
-            28
-          ],
-          [
-            8
-          ],
-          "S2"
-        ],
-        [
-          [
-            17,
-            19,
-            8
-          ],
-          [
-            8,
-            4
-          ]
-        ],
-        [
-          [
-            18,
-            20,
-            30
-          ],
-          [
-            9,
-            8,
-            4
-          ]
-        ],
-        [
-          [
-            19,
-            21,
-            10
-          ],
-          [
-            9,
-            5,
-            4
-          ]
-        ],
-        [
-          [
-            20,
-            22,
-            32
-          ],
-          [
-            10,
-            9,
-            5
-          ]
-        ],
-        [
-          [
-            21,
-            23,
-            12
-          ],
-          [
-            10,
-            6,
-            5
-          ]
-        ],
-        [
-          [
-            22,
-            24,
-            34
-          ],
-          [
-            11,
-            10,
-            6
-          ]
-        ],
-        [
-          [
-            23,
-            25,
-            14
-          ],
-          [
-            11,
-            7,
-            6
-          ]
-        ],
-        [
-          [
-            24,
-            26,
-            36
-          ],
-          [
-            12,
-            11,
-            7
-          ]
-        ],
-        [
-          [
-            25,
-            27,
-            16
-          ],
-          [
-            12,
-            7
-          ],
-          "O2"
-        ],
-        [
-          [
-            26,
-            38
-          ],
-          [
-            12
-          ]
-        ],
-        [
-          [
-            29,
-            17
-          ],
-          [
-            8
-          ],
-          "S2"
-        ],
-        [
-          [
-            28,
-            30,
-            39
-          ],
-          [
-            13,
-            8
-          ]
-        ],
-        [
-          [
-            29,
-            31,
-            19
-          ],
-          [
-            13,
-            9,
-            8
-          ]
-        ],
-        [
-          [
-            30,
-            32,
-            41
-          ],
-          [
-            14,
-            13,
-            9
-          ]
-        ],
-        [
-          [
-            31,
-            33,
-            21
-          ],
-          [
-            14,
-            10,
-            9
-          ]
-        ],
-        [
-          [
-            32,
-            34,
-            43
-          ],
-          [
-            15,
-            14,
-            10
-          ]
-        ],
-        [
-          [
-            33,
-            35,
-            23
-          ],
-          [
-            15,
-            11,
-            10
-          ]
-        ],
-        [
-          [
-            34,
-            36,
-            45
-          ],
-          [
-            16,
-            15,
-            11
-          ]
-        ],
-        [
-          [
-            35,
-            37,
-            25
-          ],
-          [
-            16,
-            12,
-            11
-          ]
-        ],
-        [
-          [
-            36,
-            38,
-            47
-          ],
-          [
-            16,
-            12
-          ],
-          "?3"
-        ],
-        [
-          [
-            37,
-            27
-          ],
-          [
-            12
-          ],
-          "?3"
-        ],
-        [
-          [
-            40,
-            29
-          ],
-          [
-            13
-          ]
-        ],
-        [
-          [
-            39,
-            41,
-            48
-          ],
-          [
-            17,
-            13
-          ],
-          "W2"
-        ],
-        [
-          [
-            40,
-            42,
-            31
-          ],
-          [
-            17,
-            14,
-            13
-          ]
-        ],
-        [
-          [
-            41,
-            43,
-            50
-          ],
-          [
-            18,
-            17,
-            14
-          ]
-        ],
-        [
-          [
-            42,
-            44,
-            33
-          ],
-          [
-            18,
-            15,
-            14
-          ]
-        ],
-        [
-          [
-            43,
-            45,
-            52
-          ],
-          [
-            19,
-            18,
-            15
-          ]
-        ],
-        [
-          [
-            44,
-            46,
-            35
-          ],
-          [
-            19,
-            16,
-            15
-          ]
-        ],
-        [
-          [
-            45,
-            47,
-            54
-          ],
-          [
-            19,
-            16
-          ]
-        ],
-        [
-          [
-            46,
-            37
-          ],
-          [
-            16
-          ]
-        ],
-        [
-          [
-            49,
-            40
-          ],
-          [
-            17
-          ],
-          "W2"
-        ],
-        [
-          [
-            48,
-            50
-          ],
-          [
-            17
-          ]
-        ],
-        [
-          [
-            49,
-            51,
-            42
-          ],
-          [
-            18,
-            17
-          ],
-          "?3"
-        ],
-        [
-          [
-            50,
-            52
-          ],
-          [
-            18
-          ],
-          "?3"
-        ],
-        [
-          [
-            51,
-            53,
-            44
-          ],
-          [
-            19,
-            18
-          ]
-        ],
-        [
-          [
-            52,
-            54
-          ],
-          [
-            19
-          ],
-          "?3"
-        ],
-        [
-          [
-            53,
-            46
-          ],
-          [
-            19
-          ],
-          "?3"
-        ]
-      ],
-      "buildings": [
-        {
-          "node": 20,
-          "owner": "me",
-          "type": "settlement"
-        }
-      ],
-      "roads": [
-        {
-          "from": 20,
-          "to": 10,
-          "owner": "me"
-        }
-      ],
-      "robber_hex": 10,
-      "current_phase": "SETUP_FIRST_ROUND",
-      "dice_result": null
-    },
-    "other_players": [
-      {
-        "name": "b",
-        "victory_points": 0,
-        "resource_count": 0,
-        "development_card_count": 0,
-        "knights_played": 0,
-        "has_longest_road": false,
-        "has_largest_army": false
-      },
-      {
-        "name": "c",
-        "victory_points": 0,
-        "resource_count": 0,
-        "development_card_count": 0,
-        "knights_played": 0,
-        "has_longest_road": false,
-        "has_largest_army": false
-      }
-    ],
-    "strategic_context": {
-      "hex_analysis": [
-        {
-          "hex_id": 1,
-          "resource": "W",
-          "number": 12,
-          "probability": "2.8%"
-        },
-        {
-          "hex_id": 2,
-          "resource": "S",
-          "number": 5,
-          "probability": "11.1%"
-        },
-        {
-          "hex_id": 3,
-          "resource": "W",
-          "number": 4,
-          "probability": "8.3%"
-        },
-        {
-          "hex_id": 4,
-          "resource": "S",
-          "number": 8,
-          "probability": "13.9%"
-        },
-        {
-          "hex_id": 5,
-          "resource": "B",
-          "number": 6,
-          "probability": "13.9%"
-        },
-        {
-          "hex_id": 6,
-          "resource": "W",
-          "number": 3,
-          "probability": "5.6%"
-        },
-        {
-          "hex_id": 8,
-          "resource": "B",
-          "number": 10,
-          "probability": "8.3%"
-        },
-        {
-          "hex_id": 9,
-          "resource": "W",
-          "number": 11,
-          "probability": "5.6%"
-        },
-        {
-          "hex_id": 11,
-          "resource": "O",
-          "number": 3,
-          "probability": "5.6%"
-        },
-        {
-          "hex_id": 12,
-          "resource": "S",
-          "number": 4,
-          "probability": "8.3%"
-        },
-        {
-          "hex_id": 13,
-          "resource": "B",
-          "number": 10,
-          "probability": "8.3%"
-        },
-        {
-          "hex_id": 16,
-          "resource": "S",
-          "number": 11,
-          "probability": "5.6%"
-        },
-        {
-          "hex_id": 17,
-          "resource": "O",
-          "number": 5,
-          "probability": "11.1%"
-        },
-        {
-          "hex_id": 19,
-          "resource": "O",
-          "number": 2,
-          "probability": "2.8%"
-        }
-      ],
-      "leading_player": "a",
-      "current_player": "b",
-      "game_phase": "SETUP_FIRST_ROUND",
-      "robber_location": 10
-    }
-  },
-  "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": [
-      {
-        "action": "place_settlement",
-        "description": "Place your starting settlement",
-        "example_parameters": {
-          "node_id": 20
-        }
-      }
-    ]
-  }
-}

examples/ai_testing/play_and_capture.py

@@ -417,6 +417,26 @@ def main():
     try:
         # Start game
         game = RealGame()
+        
+        # 🎯 CRITICAL: Install turn start callback BEFORE running game
+        # This ensures state is saved at the BEGINNING of each turn
+        def on_turn_start(game_state):
+            """Called at the start of each turn, before showing to user."""
+            # Convert GameState object to dict
+            from pycatan.visualizations.web_visualization import WebVisualization
+            web_viz = WebVisualization()
+            web_viz.update_full_state(game_state)
+            
+            if hasattr(web_viz, 'current_game_state') and web_viz.current_game_state:
+                state_copy = json.loads(json.dumps(web_viz.current_game_state))
+                captured_states.append(state_copy)
+                print(f"[🎯 Turn Start - Captured state #{len(captured_states)}]", flush=True)
+                save_current_state(state_copy)
+        
+        # Install the callback
+        if hasattr(game, 'game_manager'):
+            game.game_manager._on_turn_start_callback = on_turn_start
+        
         game.run()
         
     except KeyboardInterrupt:

examples/ai_testing/play_with_prompts.py

@@ -0,0 +1,105 @@
+"""
+Play Catan with Auto-Generated Prompts
+---------------------------------------
+This version generates AI prompts for each player at the START of every turn.
+
+During the game, you'll see:
+- Game proceeds normally
+- At each turn start, prompts are automatically generated for all players
+- Prompts are saved to: examples/ai_testing/my_games/prompts/
+
+This lets you see exactly what each AI agent would receive as input.
+"""
+
+import sys
+from pathlib import Path
+import subprocess
+import time
+import threading
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+# Import the original capture script's functionality
+from examples.ai_testing import play_and_capture
+
+# Import prompt generator
+from examples.ai_testing.generate_prompts_from_state import main as generate_prompts
+
+
+def prompt_generator_thread():
+    """
+    Background thread that watches for state changes and generates prompts.
+    """
+    state_file = Path('examples/ai_testing/my_games/current_state_optimized.txt')
+    last_modified = 0
+    
+    print("\n[🤖 Prompt Generator Active - will generate prompts on state changes]")
+    
+    while True:
+        try:
+            if state_file.exists():
+                current_modified = state_file.stat().st_mtime
+                
+                # If file was modified, generate prompts
+                if current_modified > last_modified:
+                    last_modified = current_modified
+                    
+                    # Wait a tiny bit to ensure file is fully written
+                    time.sleep(0.1)
+                    
+                    print("\n" + "🔄 " + "-"*70)
+                    print("🔄 State changed - generating AI prompts for all players...")
+                    print("🔄 " + "-"*70)
+                    
+                    try:
+                        # Generate prompts
+                        generate_prompts()
+                        print("🔄 " + "-"*70)
+                        print("✅ Prompts generated! Check examples/ai_testing/my_games/prompts/")
+                        print("🔄 " + "-"*70 + "\n")
+                    except Exception as e:
+                        print(f"⚠️ Error generating prompts: {e}\n")
+            
+            # Check every 0.5 seconds
+            time.sleep(0.5)
+            
+        except KeyboardInterrupt:
+            break
+        except Exception as e:
+            # Ignore errors silently
+            time.sleep(1)
+
+
+def main():
+    """Main entry point."""
+    print("="*80)
+    print("🎮 CATAN WITH AUTO-GENERATED AI PROMPTS")
+    print("="*80)
+    print("\n📝 This version automatically generates AI prompts for each player!")
+    print("📁 Prompts saved to: examples/ai_testing/my_games/prompts/")
+    print("⏱️  Prompts generated at the START of each turn")
+    print("\n" + "="*80 + "\n")
+    
+    # Start prompt generator thread
+    generator = threading.Thread(target=prompt_generator_thread, daemon=True)
+    generator.start()
+    
+    # Give thread time to start
+    time.sleep(0.5)
+    
+    # Run the game (this will block)
+    try:
+        play_and_capture.main()
+    except KeyboardInterrupt:
+        print("\n\n✅ Game stopped")
+    except EOFError:
+        print("\n\n✅ Game completed")
+    except Exception as e:
+        print(f"\n\n❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == '__main__':
+    main()

examples/ai_testing/test_json_format.py

@@ -0,0 +1,192 @@
+"""
+Test JSON Prompt Format
+-----------------------
+Quick test to verify the new JSON format matches promt_format.text structure.
+"""
+
+import sys
+import json
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from pycatan.ai.prompt_templates import PromptBuilder, get_response_schema
+from pycatan.ai.config import AIConfig
+
+
+def test_prompt_structure():
+    """Test that generated prompts match expected structure."""
+    print("\n" + "="*80)
+    print("🧪 TESTING JSON PROMPT FORMAT")
+    print("="*80 + "\n")
+    
+    # Create sample optimized game state
+    sample_state = {
+        "H": ["", "W12", "S5", "W4", "S8", "B6"],
+        "N": [
+            [],  # 0 - empty
+            [[2, 5], [1, 2], None],  # Node 1
+            [[1, 3], [1, 3], "W2"],  # Node 2 with wood port
+        ],
+        "players": {
+            "a": {
+                "vp": 2,
+                "res": {"W": 3, "B": 1},
+                "dev": {"h": ["K"], "r": []},
+                "stat": []
+            },
+            "b": {
+                "vp": 1,
+                "res": {"S": 2},
+                "dev": {"h": [], "r": []},
+                "stat": []
+            }
+        },
+        "bld": [
+            [20, "a", "S"],
+            [25, "b", "S"]
+        ],
+        "rds": [
+            [[20, 21], "a"],
+            [[25, 26], "b"]
+        ],
+        "meta": {
+            "robber": 10,
+            "phase": "MAIN_GAME",
+            "curr": "a",
+            "dice": 8
+        }
+    }
+    
+    # Build prompt
+    builder = PromptBuilder()
+    
+    prompt = builder.build_prompt(
+        meta_data={
+            "agent_name": "a",
+            "my_color": "Red",
+            "role": "You are player 'a' (Red). Play strategically to win."
+        },
+        task_context={
+            "what_just_happened": "You rolled an 8. You received 2 wood.",
+            "instructions": "Choose your action from 'allowed_actions'."
+        },
+        game_state=sample_state,
+        social_context={
+            "recent_chat": [
+                {"sender": "b", "content": "Anyone need sheep?"}
+            ]
+        },
+        memory=[
+            "b needs ore, I should trade",
+            "Focus on longest road"
+        ],
+        constraints={
+            "usage_instructions": "Choose one action. Use exact parameter structure.",
+            "allowed_actions": [
+                {
+                    "action": "build_road",
+                    "description": "Build a road on an edge",
+                    "example_parameters": {"edge_id": 15}
+                },
+                {
+                    "action": "end_turn",
+                    "description": "End your turn",
+                    "example_parameters": {}
+                }
+            ]
+        }
+    )
+    
+    # Verify structure matches promt_format.text
+    print("✅ Testing prompt structure...\n")
+    
+    required_sections = ["meta_data", "task_context", "game_state", 
+                        "social_context", "memory", "constraints"]
+    
+    for section in required_sections:
+        if section in prompt:
+            print(f"  ✓ {section}")
+        else:
+            print(f"  ❌ Missing: {section}")
+    
+    print("\n📋 Meta Data:")
+    print(f"  • agent_name: {prompt['meta_data'].get('agent_name')}")
+    print(f"  • my_color: {prompt['meta_data'].get('my_color')}")
+    print(f"  • role: {prompt['meta_data'].get('role')[:50]}...")
+    
+    print("\n📋 Task Context:")
+    print(f"  • what_just_happened: {prompt['task_context'].get('what_just_happened')}")
+    
+    print("\n📋 Game State:")
+    game_state = prompt.get('game_state', '')
+    if isinstance(game_state, str):
+        lines = game_state.split('\n')
+        print(f"  • Type: String with embedded JSON")
+        print(f"  • Lines: {len(lines)}")
+        print(f"  • Has legend: {'FORMAT GUIDE' in game_state}")
+        print(f"  • Has H array: {'\"H\":' in game_state}")
+        print(f"  • First 100 chars: {game_state[:100]}...")
+    
+    print("\n📋 Social Context:")
+    print(f"  • recent_chat: {len(prompt['social_context'].get('recent_chat', []))} messages")
+    
+    print("\n📋 Memory:")
+    print(f"  • notes_for_myself: {len(prompt['memory'].get('notes_for_myself', []))} notes")
+    
+    print("\n📋 Constraints:")
+    print(f"  • allowed_actions: {len(prompt['constraints'].get('allowed_actions', []))} actions")
+    
+    # Test response schema
+    print("\n" + "="*80)
+    print("📝 Response Schema:")
+    print("="*80)
+    schema = get_response_schema()
+    print(json.dumps(schema, indent=2))
+    
+    # Create full LLM request
+    print("\n" + "="*80)
+    print("📤 Complete LLM Request Structure:")
+    print("="*80)
+    
+    llm_request = {
+        "response_schema": schema,
+        "system_instruction": "You are an expert Settlers of Catan player. Respond in JSON format.",
+        "prompt": prompt
+    }
+    
+    # Save to file
+    output_file = Path('examples/ai_testing/my_games/test_prompt_format.json')
+    output_file.parent.mkdir(exist_ok=True, parents=True)
+    
+    with open(output_file, 'w', encoding='utf-8') as f:
+        json.dump(llm_request, f, indent=2, ensure_ascii=False)
+    
+    print(f"\n✅ Saved complete request to: {output_file}")
+    print(f"📏 File size: {output_file.stat().st_size:,} bytes")
+    
+    # Estimate tokens (rough)
+    json_str = json.dumps(llm_request, ensure_ascii=False)
+    estimated_tokens = len(json_str) // 4
+    print(f"📊 Estimated tokens: ~{estimated_tokens:,}")
+    
+    print("\n" + "="*80)
+    print("✅ ALL TESTS PASSED!")
+    print("="*80)
+    print("\n💡 The prompt format matches promt_format.text structure:")
+    print("   • meta_data ✓")
+    print("   • task_context ✓")
+    print("   • game_state (with legend) ✓")
+    print("   • social_context ✓")
+    print("   • memory ✓")
+    print("   • constraints ✓")
+    print("\n💡 Complete LLM request includes:")
+    print("   • response_schema (tells LLM how to respond)")
+    print("   • system_instruction")
+    print("   • prompt (the actual game state)")
+    print("\n" + "="*80 + "\n")
+
+
+if __name__ == '__main__':
+    test_prompt_structure()

promt_format.text

@@ -11,12 +11,9 @@
     "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
-    },....
+  "game_state": " ENTER HERE THE OPTIMEZED TEXT + JSON
+  
+  "
   },
 
   "social_context": {

pycatan/ai/prompt_manager.py

@@ -273,14 +273,19 @@ class PromptManager:
             "Analyze the game state and select the optimal move from 'allowed_actions'. "
         )
         
+        wait_info = (
+            "Note: 'wait_for_response' is always available if you want to chat, "
+            "negotiate trades, or observe before taking action."
+        )
+        
         if available_actions:
             num_actions = len(available_actions)
             if num_actions == 1:
                 return base_instructions + "Only one action is currently available."
             else:
-                return base_instructions + f"You have {num_actions} possible actions to choose from."
+                return base_instructions + f"You have {num_actions} possible actions. " + wait_info
         
-        return base_instructions + "Consider all strategic implications before deciding."
+        return base_instructions + wait_info
     
     def clear_cache(self):
         """Clear the filter cache. Useful when starting a new game."""

pycatan/ai/prompt_templates.py

@@ -91,7 +91,7 @@ class PromptBuilder:
         """
         prompt = {}
         
-        # Build each section
+        # Build each section according to promt_format.text structure
         if self.template.include_meta_data:
             prompt["meta_data"] = self._build_meta_data(meta_data, custom_instructions)
         
@@ -99,9 +99,8 @@ class PromptBuilder:
             prompt["task_context"] = self._build_task_context(task_context)
         
         if self.template.include_game_state:
-            # Add legend before game state for optimized format
-            prompt["game_state_legend"] = self._build_legend()
-            prompt["game_state"] = game_state
+            # Include optimized game state with legend embedded
+            prompt["game_state"] = self._build_game_state_section(game_state)
         
         if self.template.include_social_context and social_context:
             prompt["social_context"] = self._build_social_context(social_context)
@@ -114,40 +113,40 @@ class PromptBuilder:
         
         return prompt
     
-    def _build_legend(self) -> str:
+    def _build_game_state_section(self, game_state: Dict[str, Any]) -> str:
         """
-        Build legend for optimized game state format.
+        Build game state section with compact legend and single-line JSON.
         
+        Args:
+            game_state: Optimized game state
+            
         Returns:
-            Legend explaining the compact format
+            Complete game state as formatted string with legend
         """
-        return """OPTIMIZED STATE FORMAT GUIDE:
-        
-1. LOOKUP TABLES:
+        legend = """
+  1. LOOKUP TABLES:
    • "H" (Hexes): Array where Index = HexID. Value = Resource+Num.
-     Example: H[1]="W12" → Hex 1 is Wood with number 12
+     Example: H[1]="W12" -> Hex 1 is Wood 12.
    • "N" (Nodes): Array where Index = NodeID.
-     Format: [[Neighbors], [HexIDs], Port?]
-     To find yield: Check N[node_id], get HexIDs, look up in H array
+     Format: [ [Neighbors], [HexIDs], Port? ]
+     Logic: To find yield of Node 10, check N[10]. Get HexIDs (e.g. [1,5]). Look up H[1] and H[5].
 
-2. RESOURCE CODES:
-   W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert
-   Ports: ?3=Any(3:1), X2=Specific(2:1) where X is resource
+2. CODES: W=Wood, B=Brick, S=Sheep, Wh=Wheat, O=Ore, D=Desert.
+          ?3=Any 3:1 port, X2=Specific Resource 2:1 port.
 
-3. GAME STATE:
-   "bld": [NodeID, Owner, Type] where Type: S=Settlement, C=City
-   "rds": [[From, To], Owner]
+3. STATE: "bld"=[NodeID, Owner, Type], "rds"=[[From,To], Owner].
 
-4. PLAYERS:
-   "res": {ResourceCode: Count}
-   "dev": {"h": [HiddenCards], "r": [RevealedCards]}
-   "stat": ["LR"=Longest Road, "LA"=Largest Army]
+4. PLAYERS: "res"={Resource:Count}, "dev"={"h":[Hidden Cards], "r":[Revealed] (K=Knight)}, 
+            "stat"=["LR" (Longest Road), "LA" (Largest Army)].
 
-5. META:
-   "robber": HexID where robber is located (blocks that hex)
-   "phase": Current game phase
-   "curr": Current player's turn
+5. ROBBER: Located at HexID specified in "meta.robber". H[id] is blocked.
+
+JSON:
 """
+        # Convert game state to compact single-line JSON
+        import json
+        compact_json = json.dumps(game_state, ensure_ascii=False, separators=(',', ':'))
+        return legend + compact_json
     
     def _build_meta_data(
         self, 
@@ -226,24 +225,36 @@ class PromptBuilder:
         Build memory section with agent's notes.
         
         Args:
-            memory: Agent's observations and plans
+            memory: Agent's observations and plans (can be list or dict)
             
         Returns:
             Formatted memory
         """
+        # Support both dict format and list format
+        if isinstance(memory, list):
+            notes = memory
+        elif isinstance(memory, dict):
+            notes = memory.get("notes", [])
+        else:
+            notes = []
+            
         return {
-            "notes_for_myself": memory.get("notes", []),
-            "strategic_observations": memory.get("observations", []),
-            "player_tracking": memory.get("player_tracking", {})
+            "notes_for_myself": notes
         }
     
     def _build_constraints(self, constraints: Dict[str, Any]) -> Dict[str, Any]:
         """
         Build constraints section with available actions.
-        
-        Args:
-            constraints: Available actions and rules
+        # Support both dict format and list format
+        if isinstance(memory, dict):
+            notes = memory.get("notes", [])
+        elif isinstance(memory, list):
+            notes = memory
+        else:
+            notes = []
             
+        return {
+            "notes_for_myself": notes
         Returns:
             Formatted constraints
         """
@@ -413,6 +424,55 @@ class ActionTemplates:
         return affordable
 
 
+def get_response_schema() -> Dict[str, Any]:
+    """
+    Get the expected response schema for LLM output.
+    Based on example_answer.md structure.
+    OpenAPI-compliant (no 'examples' inside properties).
+    
+    Returns:
+        JSON schema defining expected response format
+    """
+    return {
+        "type": "object",
+        "required": ["internal_thinking", "action"],
+        "properties": {
+            "internal_thinking": {
+                "type": "string",
+                "description": "Your private reasoning about the situation, strategy, and decision-making process. This is for you only.",
+                "minLength": 50
+            },
+            "note_to_self": {
+                "type": "string",
+                "description": "A note to remember for next turn. What are you waiting for? What's your plan?"
+            },
+            "say_outloud": {
+                "type": "string",
+                "description": "What you want to say to other players (chat message). Use this for negotiation, threats, or table talk."
+            },
+            "action": {
+                "type": "object",
+                "required": ["type", "parameters"],
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "description": "The action type (must match one from allowed_actions in constraints)"
+                    },
+                    "parameters": {
+                        "type": "object",
+                        "description": "Action-specific parameters. If no parameters are needed, provide an empty object.",
+                        "properties": {
+                            "target": {"type": "string", "description": "The target of the action (if applicable)"},
+                            "amount": {"type": "number", "description": "The amount (if applicable)"},
+                            "location": {"type": "string", "description": "The location (if applicable)"}
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+
 def create_default_prompt_builder() -> PromptBuilder:
     """
     Create a prompt builder with default settings.

pycatan/ai/state_filter.py

@@ -48,29 +48,20 @@ class StateFilter:
     
     def filter_game_state(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
         """
-        Main filtering method - converts raw game state to agent view.
+        Main filtering method - returns optimized compact state AS-IS.
+        
+        The state is already in compact format (H, N, players, bld, rds, meta).
+        This filter just returns it directly - the compactness IS the optimization.
         
         Args:
-            raw_state: Complete game state from the game engine
+            raw_state: Optimized game state (already compact)
             
         Returns:
-            Filtered game state from agent's perspective
+            The same compact state (H, N arrays, etc.)
         """
-        filtered = {}
-        
-        # 1. Extract and format my private information
-        filtered["my_private_info"] = self._extract_my_info(raw_state)
-        
-        # 2. Get visible board state
-        filtered["board_state"] = self._filter_board_state(raw_state)
-        
-        # 3. Get other players' public information
-        filtered["other_players"] = self._filter_other_players(raw_state)
-        
-        # 4. Add computed/helpful context
-        filtered["strategic_context"] = self._add_strategic_context(raw_state)
-        
-        return filtered
+        # The optimized state is already perfect for LLM consumption
+        # Just return it as-is
+        return raw_state
     
     def _extract_my_info(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
         """

pycatan/management/game_manager.py

@@ -1735,8 +1735,15 @@ class GameManager:
             player_name = self.users[player_id].name if hasattr(self.users[player_id], 'name') else f"Player {player_id + 1}"
             self.visualization_manager.display_turn_start(player_name, self._current_game_state.turn_number)
             
-            # Display full game state at start of turn (CRITICAL FOR AI!)
+            # 🎯 CRITICAL: Get state BEFORE displaying to user
+            # This ensures AI prompts are generated with correct turn state
             current_state = self.get_full_state()
+            
+            # Trigger state capture for AI prompt generation (if hook is installed)
+            if hasattr(self, '_on_turn_start_callback'):
+                self._on_turn_start_callback(current_state)
+            
+            # Display full game state at start of turn
             self.visualization_manager.display_game_state(current_state)
     
     def _handle_game_end(self) -> None:

temp_viz_console.py

@@ -0,0 +1,31 @@
+
+# -*- coding: utf-8 -*-
+import sys
+import time
+import os
+
+log_file = r"c:\GIT_new\PyCatan_AI\logs\game_viz.log"
+
+print("PyCatan - Game Visualization Console")
+print("=" * 50)
+print("This window shows real-time game state updates.")
+print("Keep this window open while playing!")
+print("=" * 50)
+print(f"Reading from: {log_file}")
+
+# Wait for file to exist
+while not os.path.exists(log_file):
+    time.sleep(0.1)
+
+# Tail the file
+with open(log_file, 'r', encoding='utf-8') as f:
+    # Go to the end of file
+    # f.seek(0, 2) 
+    # Actually start from beginning since we just created it
+    
+    while True:
+        line = f.readline()
+        if line:
+            print(line, end='')
+        else:
+            time.sleep(0.1)