update response parser

.github/instructions/WORK_PLAN.md

@@ -1,8 +1,8 @@
 # 🗺️ AI Agent Development Work Plan
 
 **Date:** January 3, 2026  
-**Status:** ✅ Phase 1 - Foundation & Infrastructure (90% Complete)
-**Current Task:** Response Parser (1.3) - **NEXT**
+**Status:** ✅ Phase 1 - Foundation & Infrastructure (100% Complete)
+**Current Task:** Phase 3 - Core AI Agent (3.1) - **NEXT**
 
 ## 🎯 Project Goal
 
@@ -90,16 +90,24 @@ Build a fully functional LLM-based AI agent that can play Settlers of Catan auto
 
 ---
 
-#### 1.3 Response Parser
-- [ ] Define structured response format (JSON schema)
-- [ ] Build response parser and validator
-- [ ] Implement error handling for malformed responses
-- [ ] Create fallback mechanisms for parsing failures
-- [ ] Add response logging for debugging
+#### 1.3 Response Parser ✅ **COMPLETED**
+- [x] Define structured response format (JSON schema)
+- [x] Build response parser and validator
+- [x] Implement error handling for malformed responses
+- [x] Create fallback mechanisms for parsing failures
+- [x] Add response logging for debugging
 
-**Files to create:**
-- `pycatan/ai/response_parser.py` - Parse and validate LLM responses
-- `pycatan/ai/schemas.py` - JSON schemas for requests/responses
+**Files created:**
+- ✅ `pycatan/ai/response_parser.py` - Parse and validate LLM responses
+- ✅ `pycatan/ai/schemas.py` - JSON schemas for requests/responses
+
+**Key features:**
+- 🎯 Dual schema support: Active turn (with action) & Observing (no action)
+- 🛡️ Error handling: Invalid JSON, missing fields, type validation
+- 🔧 Fallback mechanisms: JSON repair, structure repair, default values
+- 📊 Parse statistics tracking
+- 🔍 Flexible parsing: Handles markdown code blocks, extra text
+- ✅ Action parameter validation against expected schemas
 
 ---
 

examples/ai_testing/my_games/current_state.json

@@ -1,6 +1,6 @@
 {
-  "timestamp": "2026-01-03T22:25:16.620950",
-  "state_number": 2,
+  "timestamp": "2026-01-03T22:34:02.690022",
+  "state_number": 3,
   "state": {
     "hexes": [
       {
@@ -118,7 +118,13 @@
         "has_robber": false
       }
     ],
-    "settlements": [],
+    "settlements": [
+      {
+        "id": "b_20",
+        "vertex": 20,
+        "player": 1
+      }
+    ],
     "cities": [],
     "roads": [],
     "harbors": [
@@ -190,11 +196,11 @@
       {
         "id": 0,
         "name": "a",
-        "victory_points": 0,
+        "victory_points": 1,
         "total_cards": 0,
         "cards_list": [],
         "dev_cards_list": [],
-        "settlements": 0,
+        "settlements": 1,
         "cities": 0,
         "roads": 0,
         "longest_road": 0,
@@ -244,7 +250,7 @@
     ],
     "dice_result": null,
     "allowed_actions": [
-      "PLACE_STARTING_SETTLEMENT"
+      "PLACE_STARTING_ROAD"
     ],
     "points": [
       {

examples/ai_testing/my_games/current_state_optimized.txt

@@ -20,6 +20,6 @@ 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":[],"rds":[]},
-  "players":{"a":{"vp":0,"res":{}},"b":{"vp":0,"res":{}},"c":{"vp":0,"res":{}}}
+  "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_a.json

@@ -76,18 +76,19 @@
       "role": "You are player 'a'. Play strategically to win."
     },
     "task_context": {
-      "what_just_happened": "It's your turn in the setup phase. Place your first settlement on a strategic location.",
+      "what_just_happened": "You placed your first settlement at node 20. Now place a road connecting to it.",
       "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. You have 2 possible actions. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
     },
-    "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}",
+    "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",
+          "action": "build_road",
+          "description": "Place your starting road connecting to your settlement",
           "example_parameters": {
-            "location": "20"
+            "from": "20",
+            "to": "21"
           }
         },
         {

examples/ai_testing/my_games/prompts/prompt_player_a.txt

@@ -1,6 +1,6 @@
 ================================================================================
 AI AGENT PROMPT - PLAYER A
-Generated: 2026-01-03 22:25:23
+Generated: 2026-01-03 22:34:03
 ================================================================================
 
 📋 RESPONSE SCHEMA (Expected LLM Output Format)
@@ -86,18 +86,19 @@ Generated: 2026-01-03 22:25:23
     "role": "You are player 'a'. Play strategically to win."
   },
   "task_context": {
-    "what_just_happened": "It's your turn in the setup phase. Place your first settlement on a strategic location.",
+    "what_just_happened": "You placed your first settlement at node 20. Now place a road connecting to it.",
     "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. You have 2 possible actions. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
   },
-  "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}",
+  "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",
+        "action": "build_road",
+        "description": "Place your starting road connecting to your settlement",
         "example_parameters": {
-          "location": "20"
+          "from": "20",
+          "to": "21"
         }
       },
       {

examples/ai_testing/my_games/prompts/prompt_player_b.json

@@ -34,9 +34,9 @@
       "role": "You are player 'b'. Play strategically to win."
     },
     "task_context": {
-      "what_just_happened": "Player a is placing their first settlement.",
+      "what_just_happened": "Player a placed their first settlement at node 20 and is now choosing where to place their starting road.",
       "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
     },
-    "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+    "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

@@ -1,6 +1,6 @@
 ================================================================================
 AI AGENT PROMPT - PLAYER B
-Generated: 2026-01-03 22:25:23
+Generated: 2026-01-03 22:34:03
 ================================================================================
 
 📋 RESPONSE SCHEMA (Expected LLM Output Format)
@@ -44,10 +44,10 @@ Generated: 2026-01-03 22:25:23
     "role": "You are player 'b'. Play strategically to win."
   },
   "task_context": {
-    "what_just_happened": "Player a is placing their first settlement.",
+    "what_just_happened": "Player a placed their first settlement at node 20 and is now choosing where to place their starting road.",
     "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
   },
-  "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+  "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.json

@@ -34,9 +34,9 @@
       "role": "You are player 'c'. Play strategically to win."
     },
     "task_context": {
-      "what_just_happened": "Player a is placing their first settlement.",
+      "what_just_happened": "Player a placed their first settlement at node 20 and is now choosing where to place their starting road.",
       "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
     },
-    "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+    "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

@@ -1,6 +1,6 @@
 ================================================================================
 AI AGENT PROMPT - PLAYER C
-Generated: 2026-01-03 22:25:23
+Generated: 2026-01-03 22:34:03
 ================================================================================
 
 📋 RESPONSE SCHEMA (Expected LLM Output Format)
@@ -44,10 +44,10 @@ Generated: 2026-01-03 22:25:23
     "role": "You are player 'c'. Play strategically to win."
   },
   "task_context": {
-    "what_just_happened": "Player a is placing their first settlement.",
+    "what_just_happened": "Player a placed their first settlement at node 20 and is now choosing where to place their starting road.",
     "instructions": "Analyze the game state and select the optimal move from 'allowed_actions'. If you wish to negotiate or wait for other players, select the 'wait_for_response' action."
   },
-  "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\":[],\"rds\":[]},\"players\":{\"a\":{\"vp\":0,\"res\":{}},\"b\":{\"vp\":0,\"res\":{}},\"c\":{\"vp\":0,\"res\":{}}}}"
+  "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\":{}}}}"
 }
 
 ================================================================================

pycatan/ai/response_parser.py

@@ -0,0 +1,349 @@
+"""
+Response parser for AI agent LLM responses.
+
+This module handles:
+1. Parsing JSON responses from LLM
+2. Validating response structure against schemas
+3. Error handling and recovery
+4. Fallback mechanisms for malformed responses
+5. Logging all parsing attempts
+"""
+
+import json
+import logging
+import re
+from typing import Dict, Any, Optional, Tuple
+from dataclasses import dataclass
+from enum import Enum
+
+from pycatan.ai.schemas import (
+    ResponseType,
+    get_schema_for_response_type,
+    validate_action_parameters,
+    ACTIVE_TURN_RESPONSE_SCHEMA,
+    OBSERVING_RESPONSE_SCHEMA
+)
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+class ParseError(Enum):
+    """Types of parsing errors."""
+    INVALID_JSON = "invalid_json"
+    MISSING_REQUIRED_FIELD = "missing_required_field"
+    INVALID_FIELD_TYPE = "invalid_field_type"
+    INVALID_ACTION = "invalid_action"
+    VALIDATION_ERROR = "validation_error"
+
+
+@dataclass
+class ParseResult:
+    """Result of parsing an LLM response."""
+    success: bool
+    data: Optional[Dict[str, Any]] = None
+    error_type: Optional[ParseError] = None
+    error_message: Optional[str] = None
+    raw_response: Optional[str] = None
+    fallback_used: bool = False
+
+
+class ResponseParser:
+    """
+    Parser for AI agent LLM responses with error handling and fallback mechanisms.
+    """
+    
+    def __init__(self, enable_fallbacks: bool = True, strict_mode: bool = False):
+        """
+        Initialize the response parser.
+        
+        Args:
+            enable_fallbacks: Whether to use fallback mechanisms for parsing errors
+            strict_mode: If True, fail on any validation error. If False, be lenient.
+        """
+        self.enable_fallbacks = enable_fallbacks
+        self.strict_mode = strict_mode
+        self.parse_attempts = 0
+        self.successful_parses = 0
+        self.failed_parses = 0
+    
+    def parse(self, 
+              raw_response: str, 
+              response_type: ResponseType,
+              allowed_actions: Optional[list] = None) -> ParseResult:
+        """
+        Parse and validate an LLM response.
+        
+        Args:
+            raw_response: Raw string response from LLM
+            response_type: Expected response type (active turn or observing)
+            allowed_actions: List of allowed action types (for validation)
+            
+        Returns:
+            ParseResult with success status and parsed data or error info
+        """
+        self.parse_attempts += 1
+        
+        logger.info(f"Parsing response (attempt #{self.parse_attempts})")
+        logger.debug(f"Raw response: {raw_response[:200]}...")
+        
+        # Step 1: Extract JSON from response
+        json_str = self._extract_json(raw_response)
+        if json_str is None:
+            self.failed_parses += 1
+            return ParseResult(
+                success=False,
+                error_type=ParseError.INVALID_JSON,
+                error_message="Could not find valid JSON in response",
+                raw_response=raw_response
+            )
+        
+        # Step 2: Parse JSON
+        try:
+            data = json.loads(json_str)
+        except json.JSONDecodeError as e:
+            logger.error(f"JSON decode error: {e}")
+            
+            if self.enable_fallbacks:
+                # Try to fix common JSON errors
+                fixed_data = self._try_fix_json(json_str)
+                if fixed_data is not None:
+                    logger.warning("Used fallback JSON repair mechanism")
+                    data = fixed_data
+                else:
+                    self.failed_parses += 1
+                    return ParseResult(
+                        success=False,
+                        error_type=ParseError.INVALID_JSON,
+                        error_message=f"JSON parse error: {str(e)}",
+                        raw_response=raw_response
+                    )
+            else:
+                self.failed_parses += 1
+                return ParseResult(
+                    success=False,
+                    error_type=ParseError.INVALID_JSON,
+                    error_message=f"JSON parse error: {str(e)}",
+                    raw_response=raw_response
+                )
+        
+        # Step 3: Validate structure
+        validation_result = self._validate_structure(data, response_type)
+        if not validation_result[0]:
+            if self.enable_fallbacks and not self.strict_mode:
+                # Try to repair structure
+                data = self._try_repair_structure(data, response_type)
+                if data is None:
+                    self.failed_parses += 1
+                    return ParseResult(
+                        success=False,
+                        error_type=ParseError.VALIDATION_ERROR,
+                        error_message=validation_result[1],
+                        raw_response=raw_response,
+                        data=data
+                    )
+                logger.warning("Used fallback structure repair mechanism")
+            else:
+                self.failed_parses += 1
+                return ParseResult(
+                    success=False,
+                    error_type=ParseError.VALIDATION_ERROR,
+                    error_message=validation_result[1],
+                    raw_response=raw_response,
+                    data=data
+                )
+        
+        # Step 4: Validate action if present
+        if response_type == ResponseType.ACTIVE_TURN and "action" in data:
+            action_validation = self._validate_action(data["action"], allowed_actions)
+            if not action_validation[0]:
+                if self.strict_mode:
+                    self.failed_parses += 1
+                    return ParseResult(
+                        success=False,
+                        error_type=ParseError.INVALID_ACTION,
+                        error_message=action_validation[1],
+                        raw_response=raw_response,
+                        data=data
+                    )
+                else:
+                    logger.warning(f"Action validation warning: {action_validation[1]}")
+        
+        # Success!
+        self.successful_parses += 1
+        logger.info("Successfully parsed and validated response")
+        
+        return ParseResult(
+            success=True,
+            data=data,
+            raw_response=raw_response
+        )
+    
+    def _extract_json(self, text: str) -> Optional[str]:
+        """
+        Extract JSON from text that may contain additional content.
+        
+        Handles cases where LLM returns JSON wrapped in markdown code blocks
+        or with additional text before/after.
+        """
+        # Try to find JSON in code blocks first
+        code_block_pattern = r'```(?:json)?\s*(\{.*?\})\s*```'
+        matches = re.findall(code_block_pattern, text, re.DOTALL)
+        if matches:
+            return matches[0]
+        
+        # Try to find raw JSON object
+        json_pattern = r'\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}'
+        matches = re.findall(json_pattern, text, re.DOTALL)
+        if matches:
+            # Return the longest match (most likely to be complete)
+            return max(matches, key=len)
+        
+        # If text looks like pure JSON, return as is
+        stripped = text.strip()
+        if stripped.startswith('{') and stripped.endswith('}'):
+            return stripped
+        
+        return None
+    
+    def _try_fix_json(self, json_str: str) -> Optional[Dict[str, Any]]:
+        """
+        Attempt to fix common JSON errors.
+        
+        Common issues:
+        - Missing closing quotes
+        - Trailing commas
+        - Single quotes instead of double quotes
+        """
+        fixes = [
+            # Replace single quotes with double quotes (careful with apostrophes)
+            lambda s: s.replace("'", '"'),
+            # Remove trailing commas
+            lambda s: re.sub(r',\s*}', '}', s),
+            lambda s: re.sub(r',\s*]', ']', s),
+        ]
+        
+        for fix in fixes:
+            try:
+                fixed = fix(json_str)
+                return json.loads(fixed)
+            except (json.JSONDecodeError, Exception):
+                continue
+        
+        return None
+    
+    def _validate_structure(self, data: Dict[str, Any], response_type: ResponseType) -> Tuple[bool, Optional[str]]:
+        """
+        Validate response structure against schema.
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        schema = get_schema_for_response_type(response_type)
+        
+        # Check required fields
+        for field in schema.get("required", []):
+            if field not in data:
+                return False, f"Missing required field: '{field}'"
+        
+        # Validate field types and constraints
+        for field, value in data.items():
+            if field in schema["properties"]:
+                field_schema = schema["properties"][field]
+                
+                # Check type
+                expected_type = field_schema.get("type")
+                if expected_type == "string" and not isinstance(value, str):
+                    return False, f"Field '{field}' must be a string"
+                elif expected_type == "object" and not isinstance(value, dict):
+                    return False, f"Field '{field}' must be an object"
+                
+                # Check string constraints
+                if isinstance(value, str):
+                    min_length = field_schema.get("minLength")
+                    max_length = field_schema.get("maxLength")
+                    if min_length and len(value) < min_length:
+                        return False, f"Field '{field}' must be at least {min_length} characters"
+                    if max_length and len(value) > max_length:
+                        return False, f"Field '{field}' must be at most {max_length} characters"
+        
+        return True, None
+    
+    def _validate_action(self, action: Dict[str, Any], allowed_actions: Optional[list]) -> Tuple[bool, Optional[str]]:
+        """
+        Validate action structure and parameters.
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not isinstance(action, dict):
+            return False, "Action must be an object"
+        
+        if "type" not in action:
+            return False, "Action missing 'type' field"
+        
+        if "parameters" not in action:
+            return False, "Action missing 'parameters' field"
+        
+        action_type = action["type"]
+        
+        # Check if action is in allowed list
+        if allowed_actions:
+            if action_type not in allowed_actions:
+                return False, f"Action type '{action_type}' not in allowed actions: {allowed_actions}"
+        
+        # Validate parameters
+        parameters = action["parameters"]
+        if not isinstance(parameters, dict):
+            return False, "Action parameters must be an object"
+        
+        # Validate parameter schema
+        param_valid, param_error = validate_action_parameters(action_type, parameters)
+        if not param_valid:
+            return False, param_error
+        
+        return True, None
+    
+    def _try_repair_structure(self, data: Dict[str, Any], response_type: ResponseType) -> Optional[Dict[str, Any]]:
+        """
+        Attempt to repair missing or invalid fields.
+        
+        Strategies:
+        - Add default values for missing optional fields
+        - Convert types if possible
+        - Use empty objects/strings as fallbacks
+        """
+        schema = get_schema_for_response_type(response_type)
+        repaired = data.copy()
+        
+        # Add missing required fields with defaults
+        for field in schema.get("required", []):
+            if field not in repaired:
+                if field == "internal_thinking":
+                    repaired[field] = "[No reasoning provided]"
+                elif field == "action":
+                    repaired[field] = {"type": "wait_for_response", "parameters": {}}
+                else:
+                    return None  # Can't repair
+        
+        # Try to fix internal_thinking if too short
+        if "internal_thinking" in repaired:
+            min_length = schema["properties"]["internal_thinking"].get("minLength", 0)
+            if len(repaired["internal_thinking"]) < min_length:
+                repaired["internal_thinking"] += " [Response was too brief]"
+        
+        return repaired
+    
+    def get_statistics(self) -> Dict[str, Any]:
+        """Get parser statistics."""
+        return {
+            "total_attempts": self.parse_attempts,
+            "successful": self.successful_parses,
+            "failed": self.failed_parses,
+            "success_rate": (
+                self.successful_parses / self.parse_attempts 
+                if self.parse_attempts > 0 
+                else 0.0
+            )
+        }

pycatan/ai/schemas.py

@@ -0,0 +1,233 @@
+"""
+JSON Schema definitions for AI agent requests and responses.
+
+This module contains all schema definitions used for:
+1. Validating LLM responses
+2. Generating prompts with schema documentation
+3. Type checking and validation
+"""
+
+from typing import Dict, Any, List, Optional
+from enum import Enum
+
+
+class ResponseType(Enum):
+    """Types of responses expected from AI agents."""
+    ACTIVE_TURN = "active_turn"  # When it's the agent's turn to act
+    OBSERVING = "observing"       # When agent is observing other players
+
+
+# Schema for when it's the agent's turn (must take action)
+ACTIVE_TURN_RESPONSE_SCHEMA = {
+    "type": "object",
+    "required": ["internal_thinking", "action"],
+    "properties": {
+        "internal_thinking": {
+            "type": "string",
+            "description": "Private strategy. What's your plan and why?",
+            "minLength": 50
+        },
+        "note_to_self": {
+            "type": "string",
+            "description": "Important facts for when it's your turn. Use only if essential for clarity or direct user query. Omit otherwise.",
+            "maxLength": 100
+        },
+        "say_outloud": {
+            "type": "string",
+            "description": "A short message to other players (max 100 chars). Use for negotiation, threats, or table talk. Keep in mind you pay for speak outload.",
+            "maxLength": 100
+        },
+        "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.",
+                    "additionalProperties": True  # Allow flexible parameters based on action
+                }
+            }
+        }
+    },
+    "propertyOrdering": [
+        "internal_thinking",
+        "note_to_self", 
+        "say_outloud",
+        "action"
+    ]
+}
+
+
+# Schema for when agent is observing (not their turn)
+OBSERVING_RESPONSE_SCHEMA = {
+    "type": "object",
+    "required": ["internal_thinking"],
+    "properties": {
+        "internal_thinking": {
+            "type": "string",
+            "description": "Track what's happening. What are opponents doing? What's your strategy for next turn?",
+            "minLength": 30
+        },
+        "note_to_self": {
+            "type": "string",
+            "description": "Important facts for when it's your turn. Use only if essential for clarity or direct user query. Omit otherwise.",
+            "maxLength": 100
+        },
+        "say_outloud": {
+            "type": "string",
+            "description": "Optional message to other players (max 100 chars). Propose trades or negotiate. You pay for this.",
+            "maxLength": 100
+        }
+    },
+    "propertyOrdering": [
+        "internal_thinking",
+        "note_to_self",
+        "say_outloud"
+    ]
+}
+
+
+def get_schema_for_response_type(response_type: ResponseType) -> Dict[str, Any]:
+    """
+    Get the appropriate schema based on response type.
+    
+    Args:
+        response_type: Type of response expected (active turn or observing)
+        
+    Returns:
+        JSON schema dictionary
+    """
+    if response_type == ResponseType.ACTIVE_TURN:
+        return ACTIVE_TURN_RESPONSE_SCHEMA
+    elif response_type == ResponseType.OBSERVING:
+        return OBSERVING_RESPONSE_SCHEMA
+    else:
+        raise ValueError(f"Unknown response type: {response_type}")
+
+
+def get_schema_description(response_type: ResponseType) -> str:
+    """
+    Get a human-readable description of what the schema expects.
+    
+    Args:
+        response_type: Type of response expected
+        
+    Returns:
+        Description string
+    """
+    if response_type == ResponseType.ACTIVE_TURN:
+        return (
+            "Response must include:\n"
+            "- internal_thinking: Your strategy (min 50 chars)\n"
+            "- action: {type: action_name, parameters: {...}}\n"
+            "Optional:\n"
+            "- note_to_self: Important reminder (max 100 chars)\n"
+            "- say_outloud: Message to other players (max 100 chars)"
+        )
+    elif response_type == ResponseType.OBSERVING:
+        return (
+            "Response must include:\n"
+            "- internal_thinking: What you observed (min 30 chars)\n"
+            "Optional:\n"
+            "- note_to_self: Important reminder (max 100 chars)\n"
+            "- say_outloud: Message to other players (max 100 chars)"
+        )
+    else:
+        return "Unknown response type"
+
+
+# Common action parameter schemas for validation
+ACTION_PARAMETER_SCHEMAS = {
+    "build_road": {
+        "required": ["from", "to"],
+        "properties": {
+            "from": {"type": "string", "description": "Starting node ID"},
+            "to": {"type": "string", "description": "Ending node ID"}
+        }
+    },
+    "build_settlement": {
+        "required": ["node"],
+        "properties": {
+            "node": {"type": "string", "description": "Node ID where to build"}
+        }
+    },
+    "build_city": {
+        "required": ["node"],
+        "properties": {
+            "node": {"type": "string", "description": "Node ID where settlement exists"}
+        }
+    },
+    "buy_dev_card": {
+        "required": [],
+        "properties": {}
+    },
+    "play_knight": {
+        "required": ["hex", "victim"],
+        "properties": {
+            "hex": {"type": "string", "description": "Hex ID to move robber"},
+            "victim": {"type": "string", "description": "Player to steal from (or 'none')"}
+        }
+    },
+    "trade_with_bank": {
+        "required": ["give", "receive"],
+        "properties": {
+            "give": {"type": "string", "description": "Resource to give"},
+            "receive": {"type": "string", "description": "Resource to receive"}
+        }
+    },
+    "propose_trade": {
+        "required": ["offer", "request"],
+        "properties": {
+            "offer": {"type": "object", "description": "Resources offered"},
+            "request": {"type": "object", "description": "Resources requested"}
+        }
+    },
+    "wait_for_response": {
+        "required": [],
+        "properties": {}
+    },
+    "end_turn": {
+        "required": [],
+        "properties": {}
+    }
+}
+
+
+def validate_action_parameters(action_type: str, parameters: Dict[str, Any]) -> tuple[bool, Optional[str]]:
+    """
+    Validate that action parameters match expected schema.
+    
+    Args:
+        action_type: Type of action (e.g., "build_road")
+        parameters: Parameters provided by the agent
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if action_type not in ACTION_PARAMETER_SCHEMAS:
+        # Unknown action type - let game manager handle validation
+        return True, None
+    
+    schema = ACTION_PARAMETER_SCHEMAS[action_type]
+    
+    # Check required parameters
+    for required_param in schema["required"]:
+        if required_param not in parameters:
+            return False, f"Missing required parameter '{required_param}' for action '{action_type}'"
+    
+    # Check parameter types if defined
+    for param_name, param_value in parameters.items():
+        if param_name in schema["properties"]:
+            expected_type = schema["properties"][param_name].get("type")
+            if expected_type == "string" and not isinstance(param_value, str):
+                return False, f"Parameter '{param_name}' should be a string"
+            elif expected_type == "number" and not isinstance(param_value, (int, float)):
+                return False, f"Parameter '{param_name}' should be a number"
+            elif expected_type == "object" and not isinstance(param_value, dict):
+                return False, f"Parameter '{param_name}' should be an object"
+    
+    return True, None