make state smallet

.github/instructions/WORK_PLAN.md

@@ -1,7 +1,8 @@
 # 🗺️ AI Agent Development Work Plan
 
 **Date:** January 3, 2026  
-**Status:** 📋 Planning Phase
+**Status:** ✅ Phase 1 - Foundation & Infrastructure (90% Complete)
+**Current Task:** Response Parser (1.3) - **NEXT**
 
 ## 🎯 Project Goal
 
@@ -17,45 +18,75 @@ Build a fully functional LLM-based AI agent that can play Settlers of Catan auto
 ### Phase 1: Foundation & Infrastructure 🏗️
 **Goal:** Build the core infrastructure needed to support AI agents
 
-#### 1.1 Configuration Management
-- [ ] Create centralized configuration system
-  - [ ] LLM settings (model, temperature, max_tokens, etc.)
-  - [ ] API credentials management
-  - [ ] Agent parameters (personality, risk tolerance, etc.)
-  - [ ] Performance settings (timeouts, retries, caching)
-- [ ] Create config file format (YAML/JSON)
-- [ ] Build configuration loader and validator
-- [ ] Add environment variable support for sensitive data
-
-**Files to create:**
-- `pycatan/ai/config.py` - Configuration management
-- `pycatan/ai/config_example.yaml` - Example configuration file
+#### 1.1 Configuration Management ✅ **COMPLETED**
+- [x] Create centralized configuration system
+  - [x] LLM settings (model, temperature, max_tokens, etc.)
+  - [x] API credentials management
+  - [x] Agent parameters (custom instructions only)
+  - [x] Performance settings (timeouts, retries, caching)
+- [x] Create config file format (YAML)
+- [x] Build configuration loader and validator
+- [x] Add environment variable support for sensitive data
+
+**Files created:**
+- ✅ `pycatan/ai/config.py` - Configuration management
+- ✅ `pycatan/ai/config_example.yaml` - Example configuration file
+- ✅ `pycatan/ai/config_dev.yaml` - Default dev configuration
+- ✅ `.env.example` - Environment variables template
 
 ---
 
-#### 1.2 Prompt Management Layer
-- [ ] Design prompt processing pipeline
-- [ ] Implement game state filtering
-  - [ ] Hide opponent's private information
-  - [ ] Filter development cards
-  - [ ] Remove non-visible game elements
-- [ ] Build perspective transformation
-  - [ ] Convert game state to agent's viewpoint
-  - [ ] Format resources and points
-  - [ ] Present relative positioning
-- [ ] Create prompt template system
-  - [ ] Meta data section
-  - [ ] Task context section
-  - [ ] Game state section
-  - [ ] Social context section
-  - [ ] Memory section
-  - [ ] Constraints section
-- [ ] Build custom instruction injection per agent
+#### 1.2 Prompt Management Layer ✅ **COMPLETED**
+- [x] Design prompt processing pipeline
+- [x] Implement game state filtering
+  - [x] Hide opponent's private information
+  - [x] Filter development cards
+  - [x] Remove non-visible game elements
+- [x] Build perspective transformation
+  - [x] Convert game state to agent's viewpoint
+  - [x] Format resources and points
+  - [x] Present relative positioning
+- [x] Create prompt template system
+  - [x] Meta data section
+  - [x] Task context section
+  - [x] Game state section
+  - [x] Social context section
+  - [x] Memory section
+  - [x] Constraints section
+- [x] Build custom instruction injection per agent
+
+**Files created:**
+- ✅ `pycatan/ai/prompt_manager.py` - Main prompt processing
+- ✅ `pycatan/ai/state_filter.py` - Game state filtering logic
+- ✅ `pycatan/ai/prompt_templates.py` - Template definitions
 
-**Files to create:**
-- `pycatan/ai/prompt_manager.py` - Main prompt processing
-- `pycatan/ai/state_filter.py` - Game state filtering logic
-- `pycatan/ai/prompt_templates.py` - Template definitions
+---
+
+#### 1.2.5 Game State Optimization ✅ **COMPLETED**
+**Goal:** Optimize the game state capture and representation for better LLM consumption
+
+- [x] Review current game state structure from `play_and_capture.py`
+- [x] Design improved game state format
+  - [x] Compress player information structure
+  - [x] Improve board representation (lookup tables H & N)
+  - [x] Add resource/harbor code mappings
+  - [x] Reduce redundancy and token usage (removed pixel_coords, board_graph)
+  - [x] Add status flags (Longest Road, Largest Army)
+- [x] Create optimized state format with legend
+- [x] Update game state capture to save both formats (.json + .txt)
+- [x] Fix timing: capture state at turn START (not just after actions)
+- [x] Test with real game scenarios
+
+**Files modified:**
+- ✅ `examples/ai_testing/play_and_capture.py` - Optimized state capture
+- ✅ `pycatan/management/game_manager.py` - Added state capture at turn start
+
+**Key achievements:**
+- 🎯 State representation optimized by ~60% (removed redundant fields)
+- 📊 Compressed format with lookup tables (H=hexes, N=nodes)
+- 🔄 Real-time state updates at `current_state_optimized.txt`
+- 📝 Clear legend/documentation included in output
+- ✅ Captures state at decision point (turn start)
 
 ---
 

examples/ai_testing/my_games/current_state.json

@@ -1,885 +0,0 @@
-{
-  "timestamp": "2025-12-26T16:21:38.408731",
-  "state_number": 1,
-  "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": [],
-    "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": 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": 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/test_prompt_output.json

@@ -0,0 +1,792 @@
+{
+  "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

@@ -24,6 +24,163 @@ original_update_state = None
 # Output directory for states
 OUTPUT_DIR = Path('examples/ai_testing/my_games')
 CURRENT_STATE_FILE = OUTPUT_DIR / 'current_state.json'
+OPTIMIZED_STATE_FILE = OUTPUT_DIR / 'current_state_optimized.txt'
+
+
+def optimize_state_for_ai(input_data):
+    """
+    ממיר את מצב המשחק למבנה אופטימלי עבור AI.
+    מדחס את המידע ומסיר דופליקציות.
+    """
+    # טיפול בעטיפה אם קיימת
+    data = input_data['state'] if 'state' in input_data else input_data
+    
+    # מילוני קיצור
+    RES_MAP = {"wood": "W", "brick": "B", "sheep": "S", "wheat": "Wh", "ore": "O", "desert": "D"}
+    TYPE_MAP = {"settlement": "S", "city": "C"}
+    
+    # 1. יצירת מערך הקסים (H)
+    max_hex_id = max([h['id'] for h in data.get('hexes', [])], default=0)
+    hex_array = [""] * (max_hex_id + 1)
+    
+    robber_hex = None
+    for h in data.get('hexes', []):
+        if h.get('has_robber'): 
+            robber_hex = h['id']
+        t = RES_MAP.get(h['type'], "?")
+        # אם יש מספר מוסיפים אותו, אחרת (מדבר) רק את הסוג
+        val = f"{t}{h['number']}" if h['number'] else t
+        hex_array[h['id']] = val
+
+    # 2. מיפוי נמלים
+    port_map = {}
+    for p in data.get('harbors', []):
+        t = RES_MAP.get(p['type'], "Any") if p['type'] != "any" else "?"
+        code = f"{t}{p['ratio']}"
+        port_map[p['point_one']] = code
+        port_map[p['point_two']] = code
+
+    # 3. יצירת מערך צמתים (N)
+    max_point_id = max([p['point_id'] for p in data.get('points', [])], default=0)
+    nodes_array = [None] * (max_point_id + 1)
+    
+    for p in data.get('points', []):
+        # המבנה: [ [שכנים], [הקסים], נמל? ]
+        val = [p['adjacent_points'], p['adjacent_hexes']]
+        if p['point_id'] in port_map:
+            val.append(port_map[p['point_id']])
+        nodes_array[p['point_id']] = val
+
+    # 4. עיבוד שחקנים
+    players = {}
+    pid_to_name = {}
+    for pl in data.get('players', []):
+        name = pl['name']
+        pid_to_name[pl['id']] = name
+        
+        # ספירת משאבים
+        res_list = pl.get('cards_list', [])
+        res_compact = {}
+        if res_list:
+            for r in set(res_list):
+                r_key = RES_MAP.get(r.lower(), r)
+                res_compact[r_key] = res_list.count(r)
+        
+        p_obj = {"vp": pl['victory_points'], "res": res_compact}
+        
+        # קלפי פיתוח
+        knights = pl.get('knights_played', 0)
+        hidden = pl.get('dev_cards_list', [])
+        if knights > 0 or hidden:
+            p_obj["dev"] = {}
+            if hidden: 
+                p_obj["dev"]["h"] = hidden
+            if knights: 
+                p_obj["dev"]["r"] = ["K"] * knights
+        
+        # דגלים מיוחדים (LR / LA)
+        flags = []
+        if pl.get('has_longest_road'):
+            flags.append("LR")  # Longest Road
+        if pl.get('has_largest_army'):
+            flags.append("LA")  # Largest Army
+        
+        if flags:
+            p_obj["stat"] = flags
+            
+        players[name] = p_obj
+
+    # 5. מצב הלוח (בניינים ודרכים)
+    bld = []
+    for b in data.get('settlements', []):
+        owner_id = b.get('player', 1) - 1  # המרה מ-1-based ל-0-based
+        owner = pid_to_name.get(owner_id, "?")
+        bld.append([b['vertex'], owner, "S"])
+    
+    for b in data.get('cities', []):
+        owner_id = b.get('player', 1) - 1  # המרה מ-1-based ל-0-based
+        owner = pid_to_name.get(owner_id, "?")
+        bld.append([b['vertex'], owner, "C"])
+
+    rds = []
+    for r in data.get('roads', []):
+        owner_id = r.get('player', 1) - 1  # המרה מ-1-based ל-0-based
+        owner = pid_to_name.get(owner_id, "?")
+        rds.append([[r['from'], r['to']], owner])
+    
+    # המרת ID של השחקן הנוכחי לשם
+    curr_id = data.get('current_player')
+    curr_name = pid_to_name.get(curr_id, str(curr_id))
+
+    # החזרת המילון המעובד
+    return {
+        "meta": {
+            "curr": curr_name, 
+            "phase": data.get('current_phase'), 
+            "robber": robber_hex,
+            "dice": data.get('dice_result')
+        },
+        "H": hex_array,
+        "N": nodes_array,
+        "state": {"bld": bld, "rds": rds},
+        "players": players
+    }
+
+
+def format_hybrid_json(data):
+    """יצירת מחרוזת JSON היברידית עם מקרא למעלה"""
+    
+    # המקרא
+    legend = """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:
+"""
+    
+    sections = [
+        f'"meta":{json.dumps(data["meta"], separators=(",", ":"))}',
+        f'"H":{json.dumps(data["H"], separators=(",", ":"))}',
+        f'"N":{json.dumps(data["N"], separators=(",", ":"))}',
+        f'"state":{json.dumps(data["state"], separators=(",", ":"))}',
+        f'"players":{json.dumps(data["players"], separators=(",", ":"))}'
+    ]
+    json_content = "{\n  " + ",\n  ".join(sections) + "\n}"
+    
+    return legend + json_content
 
 
 def save_current_state(state):
@@ -31,12 +188,24 @@ def save_current_state(state):
     try:
         OUTPUT_DIR.mkdir(exist_ok=True)
         cleaned = clean_state_for_llm(state)
+        
+        # שמירת הגרסה המקורית
         with open(CURRENT_STATE_FILE, 'w', encoding='utf-8') as f:
             json.dump({
                 'timestamp': datetime.now().isoformat(),
                 'state_number': len(captured_states),
                 'state': cleaned
             }, f, indent=2, ensure_ascii=False)
+        
+        # שמירת הגרסה האופטימלית
+        try:
+            optimized = optimize_state_for_ai(cleaned)
+            optimized_output = format_hybrid_json(optimized)
+            with open(OPTIMIZED_STATE_FILE, 'w', encoding='utf-8') as f:
+                f.write(optimized_output)
+        except Exception as opt_err:
+            print(f"[⚠️ Failed to save optimized state: {opt_err}]", flush=True)
+            
     except Exception as e:
         print(f"[⚠️ Failed to save current state: {e}]", flush=True)
 
@@ -123,21 +292,56 @@ def save_all_states():
     with open(final_file, 'w', encoding='utf-8') as f:
         json.dump(cleaned_states[-1], f, indent=2, ensure_ascii=False)
     
+    # Save optimized final state
+    optimized_final_file = output_dir / f'game_{timestamp}_final_optimized.txt'
+    try:
+        optimized_final = optimize_state_for_ai(cleaned_states[-1])
+        with open(optimized_final_file, 'w', encoding='utf-8') as f:
+            f.write(format_hybrid_json(optimized_final))
+    except Exception as e:
+        print(f"[⚠️ Failed to save optimized final state: {e}]")
+    
+    # Save optimized full history
+    optimized_history_file = output_dir / f'game_{timestamp}_full_optimized.txt'
+    try:
+        optimized_states = [optimize_state_for_ai(state) for state in cleaned_states]
+        with open(optimized_history_file, 'w', encoding='utf-8') as f:
+            json.dump({
+                'total_states': len(optimized_states),
+                'timestamp': timestamp,
+                'states': optimized_states
+            }, f, indent=2, ensure_ascii=False)
+    except Exception as e:
+        print(f"[⚠️ Failed to save optimized history: {e}]")
+    
     # Also save to standard location (cleaned)
     sample_file = Path('examples/ai_testing/sample_states/captured_game.json')
     sample_file.parent.mkdir(exist_ok=True)
     with open(sample_file, 'w', encoding='utf-8') as f:
         json.dump(cleaned_states[-1], f, indent=2, ensure_ascii=False)
     
+    # Save optimized to standard location
+    sample_optimized_file = Path('examples/ai_testing/sample_states/captured_game_optimized.txt')
+    try:
+        optimized_sample = optimize_state_for_ai(cleaned_states[-1])
+        with open(sample_optimized_file, 'w', encoding='utf-8') as f:
+            f.write(format_hybrid_json(optimized_sample))
+    except Exception as e:
+        print(f"[⚠️ Failed to save optimized sample: {e}]")
+    
     print("\n" + "="*80)
     print("✅ GAME SAVED SUCCESSFULLY!")
     print("="*80)
     print(f"\nTotal states captured: {len(captured_states)}")
     print(f"\nSaved to:")
-    print(f"  📁 Full history: {history_file}")
-    print(f"  📄 Final state:  {final_file}")
-    print(f"  📌 Quick access: {sample_file}")
-    print(f"  🔄 Real-time:    {CURRENT_STATE_FILE} (updated during game)")
+    print(f"  📁 Full history:          {history_file}")
+    print(f"  📁 Full history (opt):    {optimized_history_file}")
+    print(f"  📄 Final state:           {final_file}")
+    print(f"  📄 Final state (opt):     {optimized_final_file}")
+    print(f"  📌 Quick access:          {sample_file}")
+    print(f"  📌 Quick access (opt):    {sample_optimized_file}")
+    print(f"  🔄 Real-time:             {CURRENT_STATE_FILE}")
+    print(f"  🔄 Real-time (opt):       {OPTIMIZED_STATE_FILE}")
     print("\n" + "="*80)
     
     # Print summary

examples/ai_testing/sample_states/captured_game.json

@@ -117,72 +117,17 @@
   ],
   "settlements": [
     {
-      "id": "b_10",
-      "vertex": 10,
+      "id": "b_20",
+      "vertex": 20,
       "player": 1
-    },
-    {
-      "id": "b_14",
-      "vertex": 14,
-      "player": 2
-    },
-    {
-      "id": "b_31",
-      "vertex": 31,
-      "player": 3
-    },
-    {
-      "id": "b_36",
-      "vertex": 36,
-      "player": 2
-    },
-    {
-      "id": "b_40",
-      "vertex": 40,
-      "player": 1
-    },
-    {
-      "id": "b_44",
-      "vertex": 44,
-      "player": 3
     }
   ],
   "cities": [],
   "roads": [
     {
       "id": 1,
-      "from": 10,
-      "to": 11,
-      "player": 1
-    },
-    {
-      "id": 2,
-      "from": 14,
-      "to": 13,
-      "player": 2
-    },
-    {
-      "id": 3,
-      "from": 31,
-      "to": 30,
-      "player": 3
-    },
-    {
-      "id": 4,
-      "from": 44,
-      "to": 43,
-      "player": 3
-    },
-    {
-      "id": 5,
-      "from": 36,
-      "to": 35,
-      "player": 2
-    },
-    {
-      "id": 6,
-      "from": 40,
-      "to": 41,
+      "from": 20,
+      "to": 10,
       "player": 1
     }
   ],
@@ -255,17 +200,13 @@
     {
       "id": 0,
       "name": "a",
-      "victory_points": 2,
-      "total_cards": 3,
-      "cards_list": [
-        "ore",
-        "brick",
-        "sheep"
-      ],
+      "victory_points": 1,
+      "total_cards": 0,
+      "cards_list": [],
       "dev_cards_list": [],
-      "settlements": 2,
+      "settlements": 1,
       "cities": 0,
-      "roads": 2,
+      "roads": 1,
       "longest_road": 1,
       "has_longest_road": false,
       "knights": 0,
@@ -275,19 +216,14 @@
     {
       "id": 1,
       "name": "b",
-      "victory_points": 2,
-      "total_cards": 4,
-      "cards_list": [
-        "sheep",
-        "sheep",
-        "ore",
-        "wheat"
-      ],
+      "victory_points": 0,
+      "total_cards": 0,
+      "cards_list": [],
       "dev_cards_list": [],
-      "settlements": 2,
+      "settlements": 0,
       "cities": 0,
-      "roads": 2,
-      "longest_road": 1,
+      "roads": 0,
+      "longest_road": 0,
       "has_longest_road": false,
       "knights": 0,
       "knights_played": 0,
@@ -296,18 +232,14 @@
     {
       "id": 2,
       "name": "c",
-      "victory_points": 2,
-      "total_cards": 3,
-      "cards_list": [
-        "ore",
-        "wheat",
-        "wheat"
-      ],
+      "victory_points": 0,
+      "total_cards": 0,
+      "cards_list": [],
       "dev_cards_list": [],
-      "settlements": 2,
+      "settlements": 0,
       "cities": 0,
-      "roads": 2,
-      "longest_road": 1,
+      "roads": 0,
+      "longest_road": 0,
       "has_longest_road": false,
       "knights": 0,
       "knights_played": 0,
@@ -315,7 +247,7 @@
     }
   ],
   "current_player": 1,
-  "current_phase": "NORMAL_PLAY",
+  "current_phase": "SETUP_FIRST_ROUND",
   "robber_position": [
     2,
     2

examples/ai_testing/sample_states/captured_game_optimized.json

@@ -0,0 +1,7 @@
+{
+  "meta":{"curr":"b","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":[[[20,21],"a"]]},
+  "players":{"a":{"vp":1,"res":{}},"b":{"vp":0,"res":{}},"c":{"vp":0,"res":{}}}
+}

examples/ai_testing/sample_states/captured_game_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":"b","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":[[[20,10],"a"]]},
+  "players":{"a":{"vp":1,"res":{}},"b":{"vp":0,"res":{}},"c":{"vp":0,"res":{}}}
+}

examples/ai_testing/test_optimized_prompts.py

@@ -0,0 +1,215 @@
+"""
+Test Script for Optimized Prompt System
+-----------------------------------------
+Verifies that the updated prompt system works with the new optimized state format.
+"""
+
+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.state_filter import StateFilter, PlayerPerspective
+from pycatan.ai.prompt_manager import PromptManager
+
+def load_optimized_state():
+    """Load the optimized state from file."""
+    state_file = Path('examples/ai_testing/my_games/current_state_optimized.txt')
+    
+    if not state_file.exists():
+        # Try sample states folder
+        state_file = Path('examples/ai_testing/sample_states/captured_game_optimized.txt')
+        
+    if not state_file.exists():
+        print("❌ Optimized state file not found!")
+        print(f"   Expected: {state_file}")
+        return None
+    
+    with open(state_file, 'r', encoding='utf-8') as f:
+        content = f.read()
+        
+    # Find "JSON:" marker and extract JSON after it
+    json_marker = content.find('JSON:')
+    if json_marker != -1:
+        json_start = content.find('{', json_marker)
+    else:
+        # No marker, just find first {
+        json_start = content.find('{')
+        
+    if json_start == -1:
+        print("❌ Could not find JSON in 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}")
+        print(f"   First 200 chars: {json_str[:200]}")
+        return None
+
+
+def test_state_filter():
+    """Test the state filter with optimized format."""
+    print("\n" + "="*80)
+    print("TEST 1: State Filter with Optimized Format")
+    print("="*80)
+    
+    # Load optimized state
+    raw_state = load_optimized_state()
+    if not raw_state:
+        return False
+    
+    print("\n✓ Loaded optimized state")
+    print(f"  Players: {list(raw_state.get('players', {}).keys())}")
+    print(f"  Phase: {raw_state.get('meta', {}).get('phase')}")
+    
+    # Create filter for player 'a'
+    perspective = PlayerPerspective(
+        player_num=0,
+        player_name="a",
+        player_color="Blue"
+    )
+    state_filter = StateFilter(perspective)
+    
+    print("\n✓ Created state filter for player 'a'")
+    
+    # Filter the state
+    try:
+        filtered = state_filter.filter_game_state(raw_state)
+        print("\n✓ Successfully filtered state!")
+        
+        # Show what we got
+        print(f"\nFiltered sections:")
+        for key in filtered.keys():
+            print(f"  - {key}")
+        
+        # Show my info
+        my_info = filtered.get("my_private_info", {})
+        print(f"\nMy private info:")
+        print(f"  Victory Points: {my_info.get('victory_points')}")
+        print(f"  Resources: {my_info.get('resources')}")
+        print(f"  Has Longest Road: {my_info.get('has_longest_road')}")
+        
+        # Show other players
+        others = filtered.get("other_players", [])
+        print(f"\nOther players: {len(others)}")
+        for player in others:
+            print(f"  - {player.get('name')}: {player.get('victory_points')} VP, {player.get('resource_count')} cards")
+        
+        return True
+        
+    except Exception as e:
+        print(f"\n❌ Error filtering state: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def test_prompt_generation():
+    """Test full prompt generation."""
+    print("\n" + "="*80)
+    print("TEST 2: Full Prompt Generation")
+    print("="*80)
+    
+    # Load optimized state
+    raw_state = load_optimized_state()
+    if not raw_state:
+        return False
+    
+    # Create prompt manager
+    prompt_manager = PromptManager()
+    
+    print("\n✓ Created prompt manager")
+    
+    # Generate prompt
+    try:
+        prompt = prompt_manager.create_prompt(
+            player_num=0,
+            player_name="a",
+            player_color="Blue",
+            game_state=raw_state,
+            what_happened="Game started. It's your turn to place your first settlement.",
+            available_actions=[
+                {
+                    "action": "place_settlement",
+                    "description": "Place your starting settlement",
+                    "example_parameters": {"node_id": 20}
+                }
+            ],
+            custom_instructions="You are a strategic Catan player."
+        )
+        
+        print("\n✓ Successfully generated prompt!")
+        
+        # Show prompt structure
+        print(f"\nPrompt sections:")
+        for key in prompt.keys():
+            print(f"  - {key}")
+        
+        # Show legend
+        if "game_state_legend" in prompt:
+            print("\n✓ Legend included in prompt")
+            legend = prompt["game_state_legend"]
+            print(f"  Legend length: {len(legend)} characters")
+        
+        # Show game state keys
+        game_state = prompt.get("game_state", {})
+        print(f"\nGame state sections:")
+        for key in game_state.keys():
+            print(f"  - {key}")
+        
+        # Check board state
+        board = game_state.get("board_state", {})
+        print(f"\nBoard state:")
+        print(f"  H array length: {len(board.get('H', []))}")
+        print(f"  N array length: {len(board.get('N', []))}")
+        print(f"  Buildings: {len(board.get('buildings', []))}")
+        print(f"  Roads: {len(board.get('roads', []))}")
+        
+        # Save prompt for inspection
+        output_file = Path('examples/ai_testing/my_games/test_prompt_output.json')
+        with open(output_file, 'w', encoding='utf-8') as f:
+            json.dump(prompt, f, indent=2, ensure_ascii=False)
+        
+        print(f"\n✓ Saved full prompt to: {output_file}")
+        
+        return True
+        
+    except Exception as e:
+        print(f"\n❌ Error generating prompt: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def main():
+    """Run all tests."""
+    print("\n" + "="*80)
+    print("TESTING OPTIMIZED PROMPT SYSTEM")
+    print("="*80)
+    
+    # Run tests
+    test1_passed = test_state_filter()
+    test2_passed = test_prompt_generation()
+    
+    # Summary
+    print("\n" + "="*80)
+    print("TEST SUMMARY")
+    print("="*80)
+    print(f"State Filter:     {'✓ PASS' if test1_passed else '❌ FAIL'}")
+    print(f"Prompt Generation: {'✓ PASS' if test2_passed else '❌ FAIL'}")
+    
+    if test1_passed and test2_passed:
+        print("\n🎉 ALL TESTS PASSED! The optimized prompt system is working!")
+    else:
+        print("\n⚠️ Some tests failed. Check the output above for details.")
+    
+    print("="*80 + "\n")
+
+
+if __name__ == '__main__':
+    main()

examples/test_ai_config.py

@@ -48,9 +48,9 @@ def test_save_and_load():
     # Create custom config
     config = AIConfig()
     config.agent_name = "Test Agent"
-    config.agent.personality = "aggressive"
-    config.agent.risk_tolerance = 0.8
+    config.agent.custom_instructions = "Focus on settlements"
     config.llm.temperature = 0.9
+    config.memory.short_term_turns = 3
     
     # Save to file
     test_file = "test_config.yaml"
@@ -63,9 +63,9 @@ def test_save_and_load():
     
     # Verify values
     assert loaded_config.agent_name == "Test Agent", "Agent name mismatch"
-    assert loaded_config.agent.personality == "aggressive", "Personality mismatch"
-    assert loaded_config.agent.risk_tolerance == 0.8, "Risk tolerance mismatch"
+    assert loaded_config.agent.custom_instructions == "Focus on settlements", "Custom instructions mismatch"
     assert loaded_config.llm.temperature == 0.9, "Temperature mismatch"
+    assert loaded_config.memory.short_term_turns == 3, "Memory setting mismatch"
     
     print("✓ All values match correctly")
     
@@ -77,50 +77,27 @@ def test_save_and_load():
 
 
 def test_personalities():
-    """Test creating configs with different personalities."""
+    """Test creating configs with different custom instructions."""
     print("\n" + "="*80)
-    print("TEST 3: Different Personalities")
+    print("TEST 3: Different Agent Configurations")
     print("="*80)
     
-    personalities = {
-        "aggressive": {
-            "personality": "aggressive",
-            "risk_tolerance": 0.8,
-            "trade_willingness": 0.7,
-            "focus_on_settlements": 0.8
-        },
-        "defensive": {
-            "personality": "defensive",
-            "risk_tolerance": 0.3,
-            "trade_willingness": 0.3,
-            "focus_on_cities": 0.9
-        },
-        "balanced": {
-            "personality": "balanced",
-            "risk_tolerance": 0.5,
-            "trade_willingness": 0.5
-        },
-        "trading": {
-            "personality": "trading",
-            "risk_tolerance": 0.6,
-            "trade_willingness": 0.9,
-            "chat_frequency": 0.7
-        }
+    agents = {
+        "aggressive": "Play aggressively and take risks. Expand quickly.",
+        "defensive": "Play defensively and focus on building cities.",
+        "balanced": "Play a balanced strategy.",
+        "trading": "Focus on trading and negotiations."
     }
     
-    for name, settings in personalities.items():
+    for name, instructions in agents.items():
         config = AIConfig()
         config.agent_name = f"{name.capitalize()} Agent"
-        
-        # Apply settings
-        for key, value in settings.items():
-            setattr(config.agent, key, value)
+        config.agent.custom_instructions = instructions
         
         # Validate
         config.validate()
-        print(f"✓ Created and validated '{name}' personality")
-        print(f"  - Risk tolerance: {config.agent.risk_tolerance}")
-        print(f"  - Trade willingness: {config.agent.trade_willingness}")
+        print(f"✓ Created and validated '{name}' agent")
+        print(f"  - Instructions: {instructions[:50]}...")
     
     return True
 
@@ -142,16 +119,16 @@ def test_validation():
     except ValueError as e:
         print(f"✓ Correctly caught invalid temperature: {e}")
     
-    # Test invalid risk tolerance
+    # Test invalid max_tokens
     config = AIConfig()
-    config.agent.risk_tolerance = 1.5  # Invalid (> 1.0)
+    config.llm.max_tokens = 50  # Invalid (< 100)
     
     try:
         config.validate()
-        print("✗ Should have caught invalid risk_tolerance")
+        print("✗ Should have caught invalid max_tokens")
         return False
     except ValueError as e:
-        print(f"✓ Correctly caught invalid risk_tolerance: {e}")
+        print(f"✓ Correctly caught invalid max_tokens: {e}")
     
     # Test valid config
     config = AIConfig()
@@ -170,8 +147,9 @@ def test_to_dict_and_back():
     # Create config
     config = AIConfig()
     config.agent_name = "Dict Test Agent"
-    config.agent.personality = "trading"
+    config.agent.custom_instructions = "Test instructions"
     config.llm.temperature = 0.8
+    config.memory.short_term_turns = 7
     
     # Convert to dict
     config_dict = config.to_dict()
@@ -183,8 +161,9 @@ def test_to_dict_and_back():
     
     # Verify values
     assert new_config.agent_name == config.agent_name
-    assert new_config.agent.personality == config.agent.personality
+    assert new_config.agent.custom_instructions == config.agent.custom_instructions
     assert new_config.llm.temperature == config.llm.temperature
+    assert new_config.memory.short_term_turns == config.memory.short_term_turns
     print("✓ All values preserved correctly")
     
     return True
@@ -199,7 +178,7 @@ def main():
     tests = [
         ("Default Configuration", test_default_config),
         ("Save and Load", test_save_and_load),
-        ("Different Personalities", test_personalities),
+        ("Different Agent Configurations", test_personalities),
         ("Validation", test_validation),
         ("Dictionary Conversion", test_to_dict_and_back)
     ]

examples/test_prompt_manager.py

@@ -0,0 +1,332 @@
+"""
+Test Prompt Management System
+
+This script tests the prompt generation pipeline:
+1. Load a sample game state
+2. Create a prompt manager
+3. Generate prompts for different scenarios
+4. Verify the output structure
+"""
+
+import json
+import sys
+from pathlib import Path
+from pprint import pprint
+
+# Add project root to path
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from pycatan.ai.config import AIConfig
+from pycatan.ai.prompt_manager import PromptManager
+from pycatan.ai.prompt_templates import ActionTemplates
+
+
+def load_sample_game_state():
+    """Load the sample captured game state."""
+    sample_path = project_root / "examples" / "ai_testing" / "sample_states" / "captured_game.json"
+    
+    if not sample_path.exists():
+        print(f"✗ Sample game state not found: {sample_path}")
+        return None
+    
+    with open(sample_path, 'r') as f:
+        return json.load(f)
+
+
+def test_basic_prompt_generation():
+    """Test 1: Generate a basic prompt."""
+    print("\n" + "="*80)
+    print("TEST 1: Basic Prompt Generation")
+    print("="*80)
+    
+    # Create prompt manager
+    config = AIConfig()
+    manager = PromptManager(config)
+    
+    # Load game state
+    game_state = load_sample_game_state()
+    if not game_state:
+        return False
+    
+    print(f"✓ Loaded game state with {len(game_state.get('hexes', []))} hexes")
+    
+    # Create a simple prompt
+    prompt = manager.create_prompt(
+        player_num=1,
+        player_name="Test Agent",
+        player_color="Blue",
+        game_state=game_state,
+        what_happened="The game has started. Place your starting settlement.",
+        available_actions=ActionTemplates.get_actions_for_phase("setup")
+    )
+    
+    print("\n✓ Generated prompt with sections:")
+    for section in prompt.keys():
+        print(f"  - {section}")
+    
+    # Verify structure
+    assert "meta_data" in prompt, "Missing meta_data section"
+    assert "task_context" in prompt, "Missing task_context section"
+    assert "game_state" in prompt, "Missing game_state section"
+    assert "constraints" in prompt, "Missing constraints section"
+    
+    print("\n✓ Prompt structure is valid")
+    
+    return True
+
+
+def test_filtered_game_state():
+    """Test 2: Verify game state filtering."""
+    print("\n" + "="*80)
+    print("TEST 2: Game State Filtering")
+    print("="*80)
+    
+    config = AIConfig()
+    manager = PromptManager(config)
+    
+    game_state = load_sample_game_state()
+    if not game_state:
+        return False
+    
+    # Generate prompt
+    prompt = manager.create_prompt(
+        player_num=1,
+        player_name="Test Agent",
+        player_color="Blue",
+        game_state=game_state,
+        what_happened="Your turn to play."
+    )
+    
+    # Check filtered state structure
+    filtered_state = prompt["game_state"]
+    
+    print("\n✓ Filtered game state contains:")
+    for key in filtered_state.keys():
+        print(f"  - {key}")
+    
+    # Verify key sections exist
+    assert "my_private_info" in filtered_state, "Missing my_private_info"
+    assert "board_state" in filtered_state, "Missing board_state"
+    assert "other_players" in filtered_state, "Missing other_players"
+    assert "strategic_context" in filtered_state, "Missing strategic_context"
+    
+    print("\n✓ My private info:")
+    pprint(filtered_state["my_private_info"], width=100, compact=True)
+    
+    print("\n✓ Strategic context:")
+    pprint(filtered_state["strategic_context"], width=100, compact=True)
+    
+    return True
+
+
+def test_action_filtering():
+    """Test 3: Filter actions by resources."""
+    print("\n" + "="*80)
+    print("TEST 3: Action Filtering by Resources")
+    print("="*80)
+    
+    manager = PromptManager()
+    
+    # Get all actions
+    all_actions = ActionTemplates.get_all_actions()
+    print(f"\n✓ Total available actions: {len(all_actions)}")
+    
+    # Test with different resource scenarios
+    scenarios = [
+        {
+            "name": "Poor (no resources)",
+            "resources": {"wood": 0, "brick": 0, "sheep": 0, "wheat": 0, "ore": 0}
+        },
+        {
+            "name": "Can build road",
+            "resources": {"wood": 1, "brick": 1, "sheep": 0, "wheat": 0, "ore": 0}
+        },
+        {
+            "name": "Can build settlement",
+            "resources": {"wood": 1, "brick": 1, "sheep": 1, "wheat": 1, "ore": 0}
+        },
+        {
+            "name": "Rich (can do anything)",
+            "resources": {"wood": 5, "brick": 5, "sheep": 5, "wheat": 5, "ore": 5}
+        }
+    ]
+    
+    for scenario in scenarios:
+        affordable = manager.filter_actions_by_resources(all_actions, scenario["resources"])
+        print(f"\n{scenario['name']}: {len(affordable)} affordable actions")
+        for action in affordable:
+            if action["type"] in ["BUILD_ROAD", "BUILD_SETTLEMENT", "BUILD_CITY", "BUY_DEV_CARD"]:
+                print(f"  - {action['type']}")
+    
+    return True
+
+
+def test_chat_context():
+    """Test 4: Include chat history in prompt."""
+    print("\n" + "="*80)
+    print("TEST 4: Chat History Integration")
+    print("="*80)
+    
+    manager = PromptManager()
+    game_state = load_sample_game_state()
+    
+    if not game_state:
+        return False
+    
+    # Add chat history
+    chat_history = [
+        {"sender": "Red", "content": "I need wood desperately!"},
+        {"sender": "Green", "content": "I'll trade you wood for ore."},
+        {"sender": "Red", "content": "Deal! I'll give you 2 ore for 2 wood."}
+    ]
+    
+    prompt = manager.create_prompt(
+        player_num=1,
+        player_name="Test Agent",
+        player_color="Blue",
+        game_state=game_state,
+        what_happened="Red and Green are negotiating a trade.",
+        chat_history=chat_history
+    )
+    
+    # Check social context
+    assert "social_context" in prompt, "Missing social_context"
+    
+    print("\n✓ Social context included:")
+    pprint(prompt["social_context"], width=100)
+    
+    return True
+
+
+def test_custom_instructions():
+    """Test 5: Custom instructions per agent."""
+    print("\n" + "="*80)
+    print("TEST 5: Custom Agent Instructions")
+    print("="*80)
+    
+    config = AIConfig()
+    config.agent.custom_instructions = "You are an aggressive trader. Always seek to maximize trades."
+    
+    manager = PromptManager(config)
+    game_state = load_sample_game_state()
+    
+    if not game_state:
+        return False
+    
+    prompt = manager.create_prompt(
+        player_num=1,
+        player_name="Aggressive Trader",
+        player_color="Blue",
+        game_state=game_state,
+        what_happened="Your turn."
+    )
+    
+    print("\n✓ Meta data with custom instructions:")
+    pprint(prompt["meta_data"], width=100)
+    
+    assert "aggressive trader" in prompt["meta_data"]["role"].lower()
+    print("\n✓ Custom instructions applied successfully")
+    
+    return True
+
+
+def test_prompt_json_serialization():
+    """Test 6: Ensure prompt can be serialized to JSON."""
+    print("\n" + "="*80)
+    print("TEST 6: JSON Serialization")
+    print("="*80)
+    
+    manager = PromptManager()
+    game_state = load_sample_game_state()
+    
+    if not game_state:
+        return False
+    
+    prompt = manager.create_prompt(
+        player_num=1,
+        player_name="Test Agent",
+        player_color="Blue",
+        game_state=game_state,
+        what_happened="Test event.",
+        available_actions=ActionTemplates.get_all_actions()
+    )
+    
+    try:
+        # Try to serialize to JSON
+        json_str = json.dumps(prompt, indent=2)
+        print(f"\n✓ Prompt serialized successfully ({len(json_str)} characters)")
+        
+        # Try to deserialize
+        reconstructed = json.loads(json_str)
+        print("✓ Prompt deserialized successfully")
+        
+        # Save to file for inspection
+        output_path = project_root / "logs" / "sample_prompt.json"
+        output_path.parent.mkdir(exist_ok=True)
+        
+        with open(output_path, 'w') as f:
+            f.write(json_str)
+        
+        print(f"✓ Saved sample prompt to: {output_path}")
+        
+    except Exception as e:
+        print(f"✗ Serialization failed: {e}")
+        return False
+    
+    return True
+
+
+def main():
+    """Run all tests."""
+    print("\n" + "="*80)
+    print("🧪 PROMPT MANAGEMENT SYSTEM - TEST SUITE")
+    print("="*80)
+    
+    tests = [
+        ("Basic Prompt Generation", test_basic_prompt_generation),
+        ("Game State Filtering", test_filtered_game_state),
+        ("Action Filtering", test_action_filtering),
+        ("Chat History Integration", test_chat_context),
+        ("Custom Instructions", test_custom_instructions),
+        ("JSON Serialization", test_prompt_json_serialization)
+    ]
+    
+    results = []
+    for name, test_func in tests:
+        try:
+            result = test_func()
+            results.append((name, result))
+        except Exception as e:
+            print(f"\n✗ Test '{name}' failed with exception: {e}")
+            import traceback
+            traceback.print_exc()
+            results.append((name, False))
+    
+    # Summary
+    print("\n" + "="*80)
+    print("TEST SUMMARY")
+    print("="*80)
+    
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for name, result in results:
+        status = "✓ PASS" if result else "✗ FAIL"
+        print(f"{status}: {name}")
+    
+    print(f"\nTotal: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print("\n🎉 All tests passed!")
+        print("\n📋 Next Steps:")
+        print("  - Check logs/sample_prompt.json to see generated prompt")
+        print("  - Ready to proceed to Response Parser (Phase 1.3)")
+        return 0
+    else:
+        print(f"\n❌ {total - passed} test(s) failed")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pycatan/ai/__init__.py

@@ -7,9 +7,11 @@ that can play Settlers of Catan autonomously.
 Components:
 - config: Configuration management for AI agents
 - prompt_manager: Prompt construction and game state filtering
-- response_parser: LLM response parsing and validation
-- memory: Agent memory and learning systems
-- llm_client: LLM API abstraction and client
+- state_filter: Game state filtering and perspective transformation
+- prompt_templates: Prompt structure and action templates
+- response_parser: LLM response parsing and validation (TODO)
+- memory: Agent memory and learning systems (TODO)
+- llm_client: LLM API abstraction and client (TODO)
 
 Architecture Overview:
 ┌─────────────────────────────────────────────────────────┐
@@ -21,14 +23,17 @@ Architecture Overview:
 │  │   Config     │  │    Prompt    │  │   Response   │ │
 │  │  Management  │  │   Manager    │  │    Parser    │ │
 │  └──────────────┘  └──────────────┘  └──────────────┘ │
+│         ✅               ✅                  🚧        │
 │                                                         │
 │  ┌──────────────┐  ┌──────────────┐                   │
 │  │    Memory    │  │  LLM Client  │                   │
 │  │    System    │  │ (Multi-API)  │                   │
 │  └──────────────┘  └──────────────┘                   │
-│                                                         │
+│         🚧               🚧                            │
 └─────────────────────────────────────────────────────────┘
+
+Status: ✅ Complete | 🚧 In Development | ❌ Not Started
 """
 
 __version__ = "0.1.0"
-__all__ = ["config"]
+__all__ = ["config", "prompt_manager", "state_filter", "prompt_templates"]

pycatan/ai/config.py

@@ -63,30 +63,9 @@ class LLMConfig:
 
 @dataclass
 class AgentConfig:
-    """Configuration for agent personality and behavior."""
-    
-    # Agent identity
-    personality: str = "balanced"  # "aggressive", "defensive", "balanced", "trading"
-    risk_tolerance: float = 0.5  # 0.0 (conservative) to 1.0 (risky)
-    
-    # Strategic preferences
-    focus_on_settlements: float = 0.6  # Relative priority
-    focus_on_cities: float = 0.7
-    focus_on_roads: float = 0.5
-    focus_on_dev_cards: float = 0.6
-    
-    # Trading behavior
-    trade_willingness: float = 0.5  # 0.0 (never trades) to 1.0 (trades often)
-    trade_fairness: float = 0.7  # How fair are trade offers
-    
-    # Social behavior
-    chat_frequency: float = 0.3  # How often to send chat messages
-    use_emojis: bool = True
-    chattiness: str = "medium"  # "quiet", "medium", "chatty"
-    
-    # Custom instructions
-    custom_instructions: Optional[str] = None  # Additional instructions for this agent
-
+    """Agent configuration - reserved for future use."""
+    # Custom instructions for the agent (optional)
+    custom_instructions: Optional[str] = None
 
 @dataclass
 class MemoryConfig:
@@ -291,10 +270,6 @@ class AIConfig:
         if self.llm.max_tokens < 100:
             raise ValueError(f"max_tokens must be at least 100, got {self.llm.max_tokens}")
         
-        # Validate risk tolerance
-        if not 0.0 <= self.agent.risk_tolerance <= 1.0:
-            raise ValueError(f"risk_tolerance must be between 0.0 and 1.0, got {self.agent.risk_tolerance}")
-        
         # Validate timeouts
         if self.llm.timeout_seconds < 1:
             raise ValueError(f"timeout_seconds must be at least 1, got {self.llm.timeout_seconds}")
@@ -318,7 +293,6 @@ class AIConfig:
             f"  agent_name='{self.agent_name}',\n"
             f"  provider='{self.llm.provider}',\n"
             f"  model='{self.llm.model_name}',\n"
-            f"  personality='{self.agent.personality}',\n"
             f"  debug={self.debug.debug_mode}\n"
             f")"
         )

pycatan/ai/prompt_manager.py

@@ -0,0 +1,301 @@
+"""
+Prompt Management Layer
+
+This module orchestrates the entire prompt processing pipeline:
+1. Receives raw game state from GameManager
+2. Filters state for specific agent's perspective
+3. Builds structured prompt with all context
+4. Returns prompt ready for LLM
+
+This is the main interface between the game and the AI agents.
+
+Usage:
+    from pycatan.ai.prompt_manager import PromptManager
+    
+    manager = PromptManager(config)
+    prompt = manager.create_prompt(
+        player_num=1,
+        game_state=raw_state,
+        what_happened="Player Red rolled a 6",
+        available_actions=actions
+    )
+"""
+
+from typing import Dict, Any, List, Optional
+from pycatan.ai.config import AIConfig
+from pycatan.ai.state_filter import StateFilter, PlayerPerspective
+from pycatan.ai.prompt_templates import PromptBuilder, ActionTemplates
+
+
+class PromptManager:
+    """
+    Main prompt management orchestrator.
+    
+    Coordinates filtering, template application, and prompt generation
+    for AI agents. Ensures each agent gets appropriate context in the
+    right format.
+    """
+    
+    def __init__(self, config: Optional[AIConfig] = None):
+        """
+        Initialize prompt manager.
+        
+        Args:
+            config: AI configuration (uses default if None)
+        """
+        self.config = config or AIConfig()
+        self.prompt_builder = PromptBuilder()
+        
+        # Cache filters for each player to avoid recreation
+        self._filter_cache: Dict[int, StateFilter] = {}
+    
+    def create_prompt(
+        self,
+        player_num: int,
+        player_name: str,
+        player_color: str,
+        game_state: Dict[str, Any],
+        what_happened: str,
+        available_actions: Optional[List[Dict[str, Any]]] = None,
+        chat_history: Optional[List[Dict[str, str]]] = None,
+        agent_memory: Optional[Dict[str, Any]] = None,
+        custom_instructions: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a complete prompt for an AI agent.
+        
+        This is the main entry point for prompt creation.
+        
+        Args:
+            player_num: Player number (1-4)
+            player_name: Player's name
+            player_color: Player's color
+            game_state: Raw game state from game engine
+            what_happened: Description of what just occurred
+            available_actions: Actions agent can take (optional)
+            chat_history: Recent chat messages (optional)
+            agent_memory: Agent's memory/notes (optional)
+            custom_instructions: Custom instructions for this agent
+            
+        Returns:
+            Complete structured prompt ready for LLM
+        """
+        # Get or create state filter for this player
+        state_filter = self._get_filter(player_num, player_name, player_color)
+        
+        # Filter game state for this agent's perspective
+        filtered_state = state_filter.filter_game_state(game_state)
+        
+        # Build meta data section
+        meta_data = {
+            "agent_name": player_name,
+            "my_color": player_color,
+            "role": custom_instructions or self.config.agent.custom_instructions
+        }
+        
+        # Build task context section
+        task_context = {
+            "what_just_happened": what_happened,
+            "instructions": self._get_instructions(available_actions)
+        }
+        
+        # Build social context section
+        social_context = None
+        if chat_history:
+            social_context = {
+                "recent_chat": chat_history[-self.config.memory.chat_history_size:]
+            }
+        
+        # Build memory section
+        memory = agent_memory if agent_memory else None
+        
+        # Build constraints section (available actions)
+        constraints = None
+        if available_actions:
+            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": available_actions
+            }
+        
+        # Build complete prompt
+        prompt = self.prompt_builder.build_prompt(
+            meta_data=meta_data,
+            task_context=task_context,
+            game_state=filtered_state,
+            social_context=social_context,
+            memory=memory,
+            constraints=constraints,
+            custom_instructions=custom_instructions
+        )
+        
+        return prompt
+    
+    def create_action_prompt(
+        self,
+        player_num: int,
+        player_name: str,
+        player_color: str,
+        game_state: Dict[str, Any],
+        action_type: str,
+        context: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a prompt for a specific action type.
+        
+        This is used when GameManager asks "What settlement do you want to build?"
+        rather than "What do you want to do?"
+        
+        Args:
+            player_num: Player number
+            player_name: Player name
+            player_color: Player color
+            game_state: Current game state
+            action_type: Specific action being requested (e.g., "BUILD_SETTLEMENT")
+            context: Additional context about this action
+            
+        Returns:
+            Structured prompt for this specific action
+        """
+        # Get state filter
+        state_filter = self._get_filter(player_num, player_name, player_color)
+        filtered_state = state_filter.filter_game_state(game_state)
+        
+        # Find the specific action template
+        all_actions = ActionTemplates.get_all_actions()
+        action_template = next(
+            (a for a in all_actions if a["type"] == action_type),
+            None
+        )
+        
+        # Build task context
+        what_happened = context or f"You need to make a decision: {action_type}"
+        task_context = {
+            "what_just_happened": what_happened,
+            "instructions": f"Decide on the best {action_type} action based on the current game state."
+        }
+        
+        # Build meta data
+        meta_data = {
+            "agent_name": player_name,
+            "my_color": player_color,
+            "role": self.config.agent.custom_instructions or "You are a Catan player."
+        }
+        
+        # Constraints with just this action
+        constraints = None
+        if action_template:
+            constraints = {
+                "usage_instructions": f"Perform the {action_type} action.",
+                "allowed_actions": [action_template]
+            }
+        
+        # Build prompt
+        return self.prompt_builder.build_prompt(
+            meta_data=meta_data,
+            task_context=task_context,
+            game_state=filtered_state,
+            constraints=constraints
+        )
+    
+    def filter_actions_by_resources(
+        self,
+        actions: List[Dict[str, Any]],
+        player_resources: Dict[str, int]
+    ) -> List[Dict[str, Any]]:
+        """
+        Filter available actions based on player's resources.
+        
+        Args:
+            actions: List of all possible actions
+            player_resources: Player's current resources
+            
+        Returns:
+            Actions the player can actually afford
+        """
+        return ActionTemplates.filter_by_resources(actions, player_resources)
+    
+    def get_actions_for_phase(self, phase: str) -> List[Dict[str, Any]]:
+        """
+        Get available actions for a specific game phase.
+        
+        Args:
+            phase: Game phase name
+            
+        Returns:
+            Actions available in this phase
+        """
+        return ActionTemplates.get_actions_for_phase(phase)
+    
+    def _get_filter(
+        self, 
+        player_num: int, 
+        player_name: str, 
+        player_color: str
+    ) -> StateFilter:
+        """
+        Get or create state filter for a player.
+        
+        Uses caching to avoid recreating filters.
+        
+        Args:
+            player_num: Player number
+            player_name: Player name
+            player_color: Player color
+            
+        Returns:
+            StateFilter for this player
+        """
+        if player_num not in self._filter_cache:
+            perspective = PlayerPerspective(
+                player_num=player_num,
+                player_name=player_name,
+                player_color=player_color
+            )
+            self._filter_cache[player_num] = StateFilter(perspective)
+        
+        return self._filter_cache[player_num]
+    
+    def _get_instructions(self, available_actions: Optional[List[Dict]]) -> str:
+        """
+        Generate instructions based on available actions.
+        
+        Args:
+            available_actions: Actions available to agent
+            
+        Returns:
+            Instruction text
+        """
+        base_instructions = (
+            "Analyze the game state and select the optimal move from 'allowed_actions'. "
+        )
+        
+        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 + "Consider all strategic implications before deciding."
+    
+    def clear_cache(self):
+        """Clear the filter cache. Useful when starting a new game."""
+        self._filter_cache.clear()
+
+
+# Convenience function
+def create_prompt_manager(config: Optional[AIConfig] = None) -> PromptManager:
+    """
+    Create a prompt manager with optional configuration.
+    
+    Args:
+        config: AI configuration (uses default if None)
+        
+    Returns:
+        Configured PromptManager instance
+    """
+    return PromptManager(config)

pycatan/ai/prompt_templates.py

@@ -0,0 +1,423 @@
+"""
+Prompt Templates for AI Agents
+
+This module defines the structure and templates for prompts sent to LLM agents.
+Based on the format defined in promt_format.text, prompts consist of:
+
+1. Meta Data - Agent identity and role
+2. Task Context - Current situation and instructions
+3. Game State - World information from agent's perspective
+4. Social Context - Chat messages and relationships
+5. Memory - Agent's notes and observations
+6. Constraints - Available actions and usage rules
+
+The templates are flexible and can be customized per agent.
+"""
+
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PromptTemplate:
+    """
+    Base template structure for agent prompts.
+    
+    Each section can be customized and sections can be optionally included.
+    """
+    
+    # Section templates
+    meta_data_template: str = ""
+    task_context_template: str = ""
+    game_state_template: str = ""
+    social_context_template: str = ""
+    memory_template: str = ""
+    constraints_template: str = ""
+    
+    # Which sections to include
+    include_meta_data: bool = True
+    include_task_context: bool = True
+    include_game_state: bool = True
+    include_social_context: bool = True
+    include_memory: bool = True
+    include_constraints: bool = True
+
+
+class PromptBuilder:
+    """
+    Builds structured prompts for AI agents.
+    
+    Takes filtered game state and context, applies templates,
+    and produces a complete prompt ready for LLM.
+    """
+    
+    def __init__(self, template: Optional[PromptTemplate] = None):
+        """
+        Initialize prompt builder with a template.
+        
+        Args:
+            template: Custom template (uses default if None)
+        """
+        self.template = template or self._create_default_template()
+    
+    def _create_default_template(self) -> PromptTemplate:
+        """Create the default prompt template."""
+        return PromptTemplate()
+    
+    def build_prompt(
+        self,
+        meta_data: Dict[str, Any],
+        task_context: Dict[str, Any],
+        game_state: Dict[str, Any],
+        social_context: Optional[Dict[str, Any]] = None,
+        memory: Optional[Dict[str, Any]] = None,
+        constraints: Optional[Dict[str, Any]] = None,
+        custom_instructions: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Build a complete structured prompt with optimized game state.
+        
+        Args:
+            meta_data: Agent identity and role
+            task_context: What just happened and what to do
+            game_state: Filtered game state (optimized format)
+            social_context: Chat and relationships (optional)
+            memory: Agent's notes (optional)
+            constraints: Available actions (optional)
+            custom_instructions: Additional instructions for this agent
+            
+        Returns:
+            Complete structured prompt as dictionary
+        """
+        prompt = {}
+        
+        # Build each section
+        if self.template.include_meta_data:
+            prompt["meta_data"] = self._build_meta_data(meta_data, custom_instructions)
+        
+        if self.template.include_task_context:
+            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
+        
+        if self.template.include_social_context and social_context:
+            prompt["social_context"] = self._build_social_context(social_context)
+        
+        if self.template.include_memory and memory:
+            prompt["memory"] = self._build_memory(memory)
+        
+        if self.template.include_constraints and constraints:
+            prompt["constraints"] = self._build_constraints(constraints)
+        
+        return prompt
+    
+    def _build_legend(self) -> str:
+        """
+        Build legend for optimized game state format.
+        
+        Returns:
+            Legend explaining the compact format
+        """
+        return """OPTIMIZED STATE FORMAT GUIDE:
+        
+1. LOOKUP TABLES:
+   • "H" (Hexes): Array where Index = HexID. Value = Resource+Num.
+     Example: H[1]="W12" → Hex 1 is Wood with number 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
+
+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
+
+3. GAME STATE:
+   "bld": [NodeID, Owner, Type] where Type: S=Settlement, C=City
+   "rds": [[From, To], Owner]
+
+4. PLAYERS:
+   "res": {ResourceCode: Count}
+   "dev": {"h": [HiddenCards], "r": [RevealedCards]}
+   "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
+"""
+    
+    def _build_meta_data(
+        self, 
+        meta_data: Dict[str, Any],
+        custom_instructions: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Build meta data section.
+        
+        Args:
+            meta_data: Basic agent info
+            custom_instructions: Custom role/instructions
+            
+        Returns:
+            Formatted meta data
+        """
+        result = {
+            "agent_name": meta_data.get("agent_name", "AI Agent"),
+            "my_color": meta_data.get("my_color", "Unknown"),
+        }
+        
+        # Add role/instructions
+        if custom_instructions:
+            result["role"] = custom_instructions
+        else:
+            result["role"] = meta_data.get("role", "You are a Catan player.")
+        
+        return result
+    
+    def _build_task_context(self, task_context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build task context section.
+        
+        Args:
+            task_context: What happened and what to do
+            
+        Returns:
+            Formatted task context
+        """
+        return {
+            "what_just_happened": task_context.get("what_just_happened", ""),
+            "instructions": task_context.get(
+                "instructions",
+                "Analyze the game state and select the optimal move from 'allowed_actions'."
+            )
+        }
+    
+    def _build_social_context(self, social_context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build social context section with chat history.
+        
+        Args:
+            social_context: Chat messages and summaries
+            
+        Returns:
+            Formatted social context
+        """
+        result = {}
+        
+        # Recent chat messages
+        if "recent_chat" in social_context:
+            result["recent_chat"] = social_context["recent_chat"]
+        
+        # Chat summaries (if using summarization)
+        if "last_summaries" in social_context:
+            result["last_summaries"] = social_context["last_summaries"]
+        
+        # Trade offers/negotiations
+        if "pending_trades" in social_context:
+            result["pending_trades"] = social_context["pending_trades"]
+        
+        return result
+    
+    def _build_memory(self, memory: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build memory section with agent's notes.
+        
+        Args:
+            memory: Agent's observations and plans
+            
+        Returns:
+            Formatted memory
+        """
+        return {
+            "notes_for_myself": memory.get("notes", []),
+            "strategic_observations": memory.get("observations", []),
+            "player_tracking": memory.get("player_tracking", {})
+        }
+    
+    def _build_constraints(self, constraints: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build constraints section with available actions.
+        
+        Args:
+            constraints: Available actions and rules
+            
+        Returns:
+            Formatted constraints
+        """
+        return {
+            "usage_instructions": constraints.get(
+                "usage_instructions",
+                "Choose one action type from the list below. "
+                "Populate the 'parameters' field according to the example structure."
+            ),
+            "allowed_actions": constraints.get("allowed_actions", [])
+        }
+
+
+class ActionTemplates:
+    """
+    Templates for different game actions.
+    
+    Provides structured definitions of all possible actions
+    an agent can take, with examples and parameter structures.
+    """
+    
+    @staticmethod
+    def get_all_actions() -> List[Dict[str, Any]]:
+        """
+        Get all possible action templates.
+        
+        Returns:
+            List of action definitions with examples
+        """
+        return [
+            {
+                "type": "BUILD_ROAD",
+                "description": "Build a road on a specific edge ID.",
+                "example_parameters": {"edge_id": 12}
+            },
+            {
+                "type": "BUILD_SETTLEMENT",
+                "description": "Build a settlement on a specific node ID.",
+                "example_parameters": {"node_id": 45}
+            },
+            {
+                "type": "BUILD_CITY",
+                "description": "Upgrade an existing settlement to a city.",
+                "example_parameters": {"node_id": 45}
+            },
+            {
+                "type": "BUY_DEV_CARD",
+                "description": "Purchase a development card.",
+                "example_parameters": {}
+            },
+            {
+                "type": "OFFER_TRADE",
+                "description": "Propose a trade to all players or a specific one.",
+                "example_parameters": {
+                    "give": {"wood": 1, "sheep": 1},
+                    "receive": {"ore": 1},
+                    "target_player_color": "Red"  # Optional
+                }
+            },
+            {
+                "type": "ACCEPT_TRADE",
+                "description": "Accept a trade offer from another player.",
+                "example_parameters": {"trade_id": "trade_123"}
+            },
+            {
+                "type": "DECLINE_TRADE",
+                "description": "Decline a trade offer.",
+                "example_parameters": {"trade_id": "trade_123"}
+            },
+            {
+                "type": "PLAY_DEV_CARD",
+                "description": "Play a development card. Specific params depend on the card.",
+                "example_parameters": [
+                    {"card": "KNIGHT", "robber_hex": 7, "target_victim": "Red"},
+                    {"card": "MONOPOLY", "resource": "sheep"},
+                    {"card": "YEAR_OF_PLENTY", "resources": ["wood", "brick"]},
+                    {"card": "ROAD_BUILDING", "edges": [12, 13]}
+                ]
+            },
+            {
+                "type": "SEND_CHAT",
+                "description": "Send a message to all players.",
+                "example_parameters": {"message": "Anyone want to trade sheep for wheat?"}
+            },
+            {
+                "type": "WAIT_FOR_RESPONSE",
+                "description": "Do nothing on the board, just wait or chat.",
+                "example_parameters": {}
+            },
+            {
+                "type": "END_TURN",
+                "description": "Pass the dice to the next player.",
+                "example_parameters": {}
+            }
+        ]
+    
+    @staticmethod
+    def get_actions_for_phase(phase: str) -> List[Dict[str, Any]]:
+        """
+        Get actions available in a specific game phase.
+        
+        Args:
+            phase: Game phase (e.g., "setup", "main_turn", "robber")
+            
+        Returns:
+            List of actions available in this phase
+        """
+        all_actions = ActionTemplates.get_all_actions()
+        
+        if phase == "setup":
+            # During setup, only build settlements and roads
+            return [a for a in all_actions if a["type"] in ["BUILD_SETTLEMENT", "BUILD_ROAD"]]
+        
+        elif phase == "robber":
+            # When 7 is rolled and robber must be moved
+            return [a for a in all_actions if a["type"] == "PLAY_DEV_CARD"]
+        
+        elif phase == "main_turn":
+            # Normal turn - all actions except setup-specific
+            return all_actions
+        
+        else:
+            return all_actions
+    
+    @staticmethod
+    def filter_by_resources(
+        actions: List[Dict[str, Any]], 
+        available_resources: Dict[str, int]
+    ) -> List[Dict[str, Any]]:
+        """
+        Filter actions based on available resources.
+        
+        Args:
+            actions: List of possible actions
+            available_resources: Agent's current resources
+            
+        Returns:
+            Actions the agent can afford
+        """
+        # Resource costs
+        costs = {
+            "BUILD_ROAD": {"wood": 1, "brick": 1},
+            "BUILD_SETTLEMENT": {"wood": 1, "brick": 1, "sheep": 1, "wheat": 1},
+            "BUILD_CITY": {"wheat": 2, "ore": 3},
+            "BUY_DEV_CARD": {"sheep": 1, "wheat": 1, "ore": 1}
+        }
+        
+        affordable = []
+        for action in actions:
+            action_type = action["type"]
+            
+            # Actions that don't require resources
+            if action_type not in costs:
+                affordable.append(action)
+                continue
+            
+            # Check if agent can afford this action
+            required = costs[action_type]
+            can_afford = all(
+                available_resources.get(resource, 0) >= amount
+                for resource, amount in required.items()
+            )
+            
+            if can_afford:
+                affordable.append(action)
+        
+        return affordable
+
+
+def create_default_prompt_builder() -> PromptBuilder:
+    """
+    Create a prompt builder with default settings.
+    
+    Returns:
+        Configured PromptBuilder instance
+    """
+    return PromptBuilder()

pycatan/ai/state_filter.py

@@ -0,0 +1,336 @@
+"""
+Game State Filtering and Perspective Transformation
+
+This module handles filtering and transforming raw game state data
+into an agent-specific view. It ensures that:
+1. Agents only see information they should know
+2. Information is presented from the agent's perspective
+3. Complex game state is simplified for LLM consumption
+
+Key principles:
+- Hide opponent's private information (cards, exact resources)
+- Transform "Player X did Y" → "You did Y" / "Red did Y"
+- Add helpful computed data (probabilities, scarcity)
+- Keep prompts concise but complete
+"""
+
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class PlayerPerspective:
+    """Represents which player's perspective we're filtering for."""
+    player_num: int  # Player number (1, 2, 3, 4)
+    player_name: str  # Player's display name
+    player_color: str  # Player's color (Blue, Red, Green, Orange)
+
+
+class StateFilter:
+    """
+    Filters and transforms game state for a specific agent's perspective.
+    
+    This class takes raw game state and produces a filtered, agent-centric
+    view that:
+    - Hides information the agent shouldn't know
+    - Presents data from the agent's viewpoint
+    - Adds computed context (probabilities, strategic info)
+    """
+    
+    def __init__(self, perspective: PlayerPerspective):
+        """
+        Initialize state filter for a specific player.
+        
+        Args:
+            perspective: Which player's perspective to use
+        """
+        self.perspective = perspective
+    
+    def filter_game_state(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Main filtering method - converts raw game state to agent view.
+        
+        Args:
+            raw_state: Complete game state from the game engine
+            
+        Returns:
+            Filtered game state from agent's perspective
+        """
+        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
+    
+    def _extract_my_info(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract this agent's private information.
+        Works with optimized state format where players is a dict keyed by name.
+        
+        Returns:
+            Dictionary with agent's resources, cards, and points
+        """
+        players = raw_state.get("players", {})
+        
+        # In optimized format, players is a dict with player names as keys
+        my_player = players.get(self.perspective.player_name)
+        
+        if not my_player:
+            return {
+                "resources": {},
+                "development_cards": {"hidden": [], "revealed": []},
+                "victory_points": 0,
+                "has_longest_road": False,
+                "has_largest_army": False,
+            }
+        
+        # Extract dev cards
+        dev = my_player.get("dev", {})
+        
+        return {
+            "resources": my_player.get("res", {}),
+            "development_cards": {
+                "hidden": dev.get("h", []),
+                "revealed": dev.get("r", [])
+            },
+            "victory_points": my_player.get("vp", 0),
+            "has_longest_road": "LR" in my_player.get("stat", []),
+            "has_largest_army": "LA" in my_player.get("stat", []),
+        }
+    
+    def _filter_board_state(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Filter board information using optimized format.
+        Returns the compact H/N arrays plus current state.
+        """
+        meta = raw_state.get("meta", {})
+        state = raw_state.get("state", {})
+        
+        return {
+            "H": raw_state.get("H", []),  # Hex lookup table
+            "N": raw_state.get("N", []),  # Node lookup table  
+            "buildings": self._annotate_buildings(state.get("bld", [])),
+            "roads": self._annotate_roads(state.get("rds", [])),
+            "robber_hex": meta.get("robber"),
+            "current_phase": meta.get("phase"),
+            "dice_result": meta.get("dice")
+        }
+    
+    def _annotate_buildings(self, buildings: List) -> List[Dict]:
+        """
+        Annotate buildings with ownership info (mine vs others).
+        Optimized format: [NodeID, Owner, Type]
+        
+        Args:
+            buildings: List of building data [node, owner, type]
+            
+        Returns:
+            Annotated building list
+        """
+        annotated = []
+        for bld in buildings:
+            if len(bld) < 3:
+                continue
+                
+            node_id, owner, bld_type = bld[0], bld[1], bld[2]
+            
+            annotated.append({
+                "node": node_id,
+                "owner": "me" if owner == self.perspective.player_name else owner,
+                "type": "settlement" if bld_type == "S" else "city"
+            })
+        
+        return annotated
+    
+    def _annotate_roads(self, roads: List) -> List[Dict]:
+        """
+        Annotate roads with ownership info.
+        Optimized format: [[From, To], Owner]
+        
+        Args:
+            roads: List of road data [[from, to], owner]
+            
+        Returns:
+            Annotated road list
+        """
+        annotated = []
+        for road in roads:
+            if len(road) < 2:
+                continue
+                
+            nodes, owner = road[0], road[1]
+            
+            annotated.append({
+                "from": nodes[0],
+                "to": nodes[1],
+                "owner": "me" if owner == self.perspective.player_name else owner
+            })
+        
+        return annotated
+    
+    def _filter_other_players(self, raw_state: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """
+        Get public information about other players.
+        Works with optimized format where players is a dict.
+        
+        This hides:
+        - Exact resource counts (only show total)
+        - Hidden development cards
+        - Other private information
+        """
+        players = raw_state.get("players", {})
+        other_players = []
+        
+        for player_name, player_data in players.items():
+            # Skip myself
+            if player_name == self.perspective.player_name:
+                continue
+            
+            # Calculate totals from optimized format
+            resources = player_data.get("res", {})
+            dev_cards = player_data.get("dev", {})
+            stats = player_data.get("stat", [])
+            
+            # Public information only
+            other_players.append({
+                "name": player_name,
+                "victory_points": player_data.get("vp", 0),
+                "resource_count": sum(resources.values()),  # Total only
+                "development_card_count": len(dev_cards.get("h", [])) + len(dev_cards.get("r", [])),
+                "knights_played": len([c for c in dev_cards.get("r", []) if c == "K"]),
+                "has_longest_road": "LR" in stats,
+                "has_largest_army": "LA" in stats
+            })
+        
+        return other_players
+    
+    def _add_strategic_context(self, raw_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Add computed strategic information using optimized format.
+        
+        This includes:
+        - Dice roll probabilities for each hex (from H array)
+        - Leading player information
+        - Current turn info
+        """
+        H = raw_state.get("H", [])
+        players = raw_state.get("players", {})
+        meta = raw_state.get("meta", {})
+        
+        # Dice probabilities
+        dice_probs = {
+            2: "2.8%", 3: "5.6%", 4: "8.3%", 5: "11.1%", 6: "13.9%",
+            8: "13.9%", 9: "11.1%", 10: "8.3%", 11: "5.6%", 12: "2.8%"
+        }
+        
+        # Parse hex array for strategic info
+        hex_analysis = []
+        for hex_id, hex_str in enumerate(H):
+            if not hex_str or hex_id == 0:
+                continue
+                
+            # Parse format like "W12", "B6", "D"
+            if hex_str == "D":
+                continue  # Skip desert
+                
+            # Extract resource and number
+            resource = hex_str[0] if len(hex_str) > 0 else ""
+            if len(hex_str) > 1:
+                try:
+                    number = int(hex_str[1:])
+                    hex_analysis.append({
+                        "hex_id": hex_id,
+                        "resource": resource,
+                        "number": number,
+                        "probability": dice_probs.get(number, "0%")
+                    })
+                except:
+                    pass
+        
+        # Find who's winning
+        leading_player = None
+        max_points = 0
+        for name, data in players.items():
+            vp = data.get("vp", 0)
+            if vp > max_points:
+                max_points = vp
+                leading_player = name
+        
+        return {
+            "hex_analysis": hex_analysis,
+            "leading_player": leading_player,
+            "current_player": meta.get("curr"),
+            "game_phase": meta.get("phase"),
+            "robber_location": meta.get("robber")
+        }
+    
+    def hide_private_info(self, game_state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Remove all private information from game state.
+        Works with optimized format.
+        
+        Args:
+            game_state: Full game state
+            
+        Returns:
+            Game state with private info removed
+        """
+        filtered = game_state.copy()
+        
+        # Remove opponent development cards and exact resources
+        if "players" in filtered:
+            players_copy = {}
+            for name, data in filtered["players"].items():
+                if name != self.perspective.player_name:
+                    # Hide exact resources - only show count
+                    res = data.get("res", {})
+                    total_res = sum(res.values())
+                    
+                    # Hide hidden dev cards
+                    dev = data.get("dev", {})
+                    hidden_count = len(dev.get("h", []))
+                    revealed = dev.get("r", [])
+                    
+                    players_copy[name] = {
+                        "vp": data.get("vp", 0),
+                        "res": {"total": total_res},  # Only total
+                        "dev": {"hidden_count": hidden_count, "r": revealed},  # Hide specific cards
+                        "stat": data.get("stat", [])
+                    }
+                else:
+                    # Keep my full info
+                    players_copy[name] = data.copy()
+            
+            filtered["players"] = players_copy
+        
+        return filtered
+
+
+def create_filter_for_player(player_num: int, player_name: str, player_color: str) -> StateFilter:
+    """
+    Convenience function to create a state filter for a specific player.
+    
+    Args:
+        player_num: Player number (1-4)
+        player_name: Player's name
+        player_color: Player's color
+        
+    Returns:
+        Configured StateFilter instance
+    """
+    perspective = PlayerPerspective(
+        player_num=player_num,
+        player_name=player_name,
+        player_color=player_color
+    )
+    return StateFilter(perspective)

pycatan/management/game_manager.py

@@ -1734,6 +1734,10 @@ class GameManager:
             player_id = self._current_game_state.current_player
             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!)
+            current_state = self.get_full_state()
+            self.visualization_manager.display_game_state(current_state)
     
     def _handle_game_end(self) -> None:
         """

temp_viz_console.py

@@ -1,31 +0,0 @@
-
-# -*- 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)