Justin dev

.claude/project-context.md

@@ -11,7 +11,7 @@ Quick reference for Claude Code sessions.
 
 ## Tech Stack
 - **Godot 4.5**: C++ GDExtension module for simulation
-- **Python 3.11+**: Agent runtime, LLM backends, tools
+- **Python 3.11**: Agent runtime, LLM backends, tools (3.11 required - many ML packages don't support 3.14 yet)
 - **Visual Studio 2022**: C++ compilation (MSVC)
 - **CMake 3.20+**: Build system
 - **License**: Apache 2.0
@@ -36,8 +36,10 @@ c:\Projects\Agent Arena\
 │   ├── memory/              # Memory systems (RAG, episodes)
 │   └── evals/               # Evaluation harness
 ├── configs/                 # Hydra configs
-├── scenes/                  # Godot benchmark scenes
-│   └── test_arena.tscn      # Test scene with SimulationManager & Agent
+├── scenes/                  # Godot benchmark scenes (.tscn files)
+├── scripts/                 # GDScript files
+│   ├── tests/               # Test scripts (test_extension.gd, ipc_test.gd)
+│   └── test_arena.gd        # Main test arena script
 ├── tests/                   # Python unit tests
 └── docs/                    # Documentation
 ```
@@ -58,9 +60,10 @@ c:\Projects\Agent Arena\
 - ✅ Extension tested and working in Godot 4.5.1
 - ✅ Test scene created with working controls
 - ✅ Core classes verified: SimulationManager, Agent, EventBus, ToolRegistry
-- ⏳ Next: Implement IPC between Godot and Python
+- ✅ IPC system implemented (Godot ↔ Python via HTTP/FastAPI)
 - ⏳ Next: Create actual benchmark scenes (foraging, crafting_chain, team_capture)
 - ⏳ Next: Set up Python environment and agent runtime
+- ⏳ Next: Integrate LLM backends with agent decision-making
 
 ## Development Commands
 
@@ -101,6 +104,20 @@ cd tests
 pytest -v
 ```
 
+### Run IPC Server (Godot ↔ Python Communication)
+```bash
+# Start Python IPC server
+cd python
+venv\Scripts\activate
+python run_ipc_server.py
+
+# With custom options
+python run_ipc_server.py --host 127.0.0.1 --port 5000 --workers 4 --debug
+
+# Test IPC in Godot
+# Open scenes/ipc_test.gd in Godot editor and run it
+```
+
 ## Common Tasks
 
 ### Adding a New Tool
@@ -146,11 +163,17 @@ pytest -v
 - Tool management system for agent actions
 - Methods: `register_tool()`, `unregister_tool()`, `get_tool_schema()`, `execute_tool()`
 
+### IPCClient (Node)
+- HTTP client for Godot ↔ Python communication
+- Methods: `connect_to_server()`, `send_tick_request()`, `get_tick_response()`, `has_response()`
+- Properties: `server_url`
+- Signals: `response_received`, `connection_failed`
+
 ## Known Issues
-- IPC layer not yet implemented (Godot ↔ Python communication)
-- Benchmark scenes are empty placeholders
-- Python environment not yet set up
-- Tool execution currently returns stub responses
+- Benchmark scenes are empty placeholders (need to create actual game worlds)
+- Python environment needs initial setup (venv + pip install)
+- LLM backends not yet connected to agent decision-making
+- Tool execution in Godot currently returns stub responses
 
 ## References
 - Godot docs: https://docs.godotengine.org/

.claude/settings.local.json

@@ -20,7 +20,20 @@
       "Bash(git add:*)",
       "Bash(git commit:*)",
       "Bash(git push:*)",
-      "Bash(gh pr create:*)"
+      "Bash(gh pr create:*)",
+      "Bash(if [ -d .vscode ])",
+      "Bash(then echo \"exists\")",
+      "Bash(else echo \"not exists\")",
+      "Bash(fi)",
+      "Bash(py --list:*)",
+      "Bash(if exist \"c:\\Projects\\Agent Arena\\.godot\" echo \".godot folder exists\" else echo \".godot folder not found\")",
+      "Bash(test:*)",
+      "Bash(\"C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\IDE\\CommonExtensions\\Microsoft\\CMake\\CMake\\bin\\cmake.exe\" --build . --config Debug --target agent_arena)",
+      "Bash(\"C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\IDE\\CommonExtensions\\Microsoft\\CMake\\CMake\\bin\\cmake.exe\" --build . --config Debug --clean-first)",
+      "Bash(del /F /Q agent_arena.*)",
+      "Bash(del /F /Q CMakeFilesagent_arena.dir* 2)",
+      "Bash(nul)",
+      "Bash(ls -la \"C:\\Projects\\Agent Arena\\bin\\windows\"\" 2>nul || echo \"Directory does not exist \")"
     ],
     "deny": [],
     "ask": []

PYTHON_SETUP.md

@@ -0,0 +1,138 @@
+# Python Environment Setup
+
+## Python Version Requirement
+
+**Agent Arena requires Python 3.11** (specifically tested with 3.11.9)
+
+Many ML/AI packages (llama-cpp-python, torch, faiss, etc.) don't yet have pre-built wheels for Python 3.14. Using Python 3.11 ensures all dependencies install smoothly.
+
+## Installation Steps
+
+### 1. Install Python 3.11
+
+**Download**: [Python 3.11.9 (64-bit)](https://www.python.org/downloads/release/python-3119/)
+
+**During installation**:
+- ✅ Check "Add Python 3.11 to PATH"
+- ✅ Check "Install for all users" (optional)
+
+**Verify installation**:
+```bash
+py -3.11 --version
+# Should output: Python 3.11.9
+```
+
+### 2. Create Virtual Environment
+
+```bash
+cd "c:\Projects\Agent Arena\python"
+
+# Create venv with Python 3.11
+py -3.11 -m venv venv
+
+# Activate venv
+venv\Scripts\activate
+
+# Verify Python version in venv
+python --version
+# Should output: Python 3.11.9
+```
+
+### 3. Install Dependencies
+
+#### Option A: Full Installation (Recommended)
+Installs all dependencies including LLM backends, vector stores, etc.
+
+```bash
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+**Note**: This may take 5-10 minutes as some packages (torch, transformers) are large.
+
+#### Option B: Minimal Installation (For IPC Testing Only)
+If you just want to test the IPC system quickly:
+
+```bash
+pip install --upgrade pip
+pip install -r requirements-minimal.txt
+```
+
+This installs only FastAPI, uvicorn, and essential packages. You'll need the full installation later for LLM functionality.
+
+### 4. Verify Installation
+
+```bash
+# Test imports
+python -c "import fastapi; import uvicorn; print('IPC dependencies OK')"
+
+# Full test (only if you did full installation)
+python -c "import torch; import transformers; import faiss; print('All dependencies OK')"
+```
+
+## Running the IPC Server
+
+```bash
+cd "c:\Projects\Agent Arena\python"
+venv\Scripts\activate
+python run_ipc_server.py
+```
+
+You should see:
+```
+============================================================
+Agent Arena IPC Server
+============================================================
+Host: 127.0.0.1
+Port: 5000
+Max Workers: 4
+============================================================
+INFO:     Started server process
+INFO:     Uvicorn running on http://127.0.0.1:5000
+```
+
+## Troubleshooting
+
+### "Python 3.11 not found"
+- Make sure you installed Python 3.11 from python.org
+- Try `py --list` to see available Python versions
+- If 3.11 doesn't appear, reinstall and check "Add to PATH"
+
+### "No module named 'fastapi'"
+- Make sure venv is activated: `venv\Scripts\activate`
+- Reinstall: `pip install -r requirements.txt`
+
+### "ERROR: Could not build wheels for llama-cpp-python"
+- Requires Visual Studio C++ Build Tools
+- On Windows, install: https://visualstudio.microsoft.com/visual-cpp-build-tools/
+- Select "Desktop development with C++" workload
+
+### "torch" installation is very slow
+- torch is ~2GB, be patient
+- Alternative: Use CPU-only version: `pip install torch --index-url https://download.pytorch.org/whl/cpu`
+
+### Port 5000 already in use
+- Change port: `python run_ipc_server.py --port 5001`
+- Update Godot IPCClient.server_url to match
+
+## Using Different Python Versions
+
+If you need to keep Python 3.14 as default but use 3.11 for this project:
+
+```bash
+# Always use py -3.11 to create the venv
+py -3.11 -m venv venv
+
+# Once activated, the venv uses 3.11 automatically
+venv\Scripts\activate
+python --version  # Shows 3.11.9
+```
+
+## Next Steps
+
+After setup:
+1. Start IPC server: `python run_ipc_server.py`
+2. Open Godot and run [scenes/ipc_test.gd](scenes/ipc_test.gd)
+3. Verify communication in console logs
+
+See [docs/ipc.md](docs/ipc.md) for detailed IPC documentation.

TROUBLESHOOTING_IPC.md

@@ -0,0 +1,140 @@
+# Troubleshooting: IPCClient Not Found
+
+## Error
+```
+ERROR: Could not find type "IPCClient" in the current scope.
+```
+
+## Cause
+Godot cached the old GDExtension DLL before IPCClient was added. It needs to reload the new version.
+
+## Solution
+
+### Method 1: Clear Cache and Restart (Most Reliable)
+
+1. **Close Godot completely** (make sure it's not running in background)
+
+2. **Delete the `.godot` cache folder**:
+   ```bash
+   # Windows PowerShell
+   Remove-Item -Recurse -Force ".godot"
+
+   # Or Windows Command Prompt
+   rmdir /s /q ".godot"
+
+   # Or manually delete the .godot folder in Windows Explorer
+   ```
+
+3. **Restart Godot**:
+   - It will recreate the `.godot` folder
+   - It will reimport all assets and reload the extension
+
+4. **Verify the classes are loaded**:
+   - Open and run `scripts/tests/test_extension.gd`
+   - You should see all 5 classes (including IPCClient) pass
+
+### Method 2: Just Restart Godot
+
+Sometimes simply closing and reopening Godot is enough:
+1. Close Godot completely
+2. Reopen the project
+3. Try running `scripts/tests/test_extension.gd`
+
+### Method 3: Rebuild the Extension
+
+If the above doesn't work, the DLL might not have been built correctly:
+
+```bash
+cd "c:\Projects\Agent Arena\godot\build"
+
+# Clean build
+"C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" --build . --config Debug --clean-first
+
+# Restart Godot after build completes
+```
+
+## Verification Steps
+
+### 1. Check DLL Exists
+```bash
+dir "c:\Projects\Agent Arena\bin\windows\libagent_arena.windows.template_debug.x86_64.dll"
+```
+Should show a file ~3.5 MB in size with recent timestamp.
+
+### 2. Check Extension Configuration
+File `agent_arena.gdextension` should contain:
+```ini
+[configuration]
+entry_symbol = "agent_arena_library_init"
+compatibility_minimum = "4.5"
+
+[libraries]
+windows.debug.x86_64 = "res://bin/windows/libagent_arena.windows.template_debug.x86_64.dll"
+```
+
+### 3. Run Test Script
+Open `scenes/test_extension.gd` and run it (F6). You should see:
+```
+=== Testing GDExtension Classes ===
+  ✓ SimulationManager - OK
+  ✓ EventBus - OK
+  ✓ Agent - OK
+  ✓ ToolRegistry - OK
+  ✓ IPCClient - OK
+=== Test Complete ===
+All classes loaded successfully!
+```
+
+### 4. Check Godot Console on Startup
+When Godot starts, it should print:
+```
+IPCClient initialized with server URL: http://127.0.0.1:5000
+```
+(This appears when you create an IPCClient node)
+
+## Common Issues
+
+### "Still getting IPCClient not found after restart"
+- Make sure you deleted the entire `.godot` folder
+- Make sure Godot was completely closed (check Task Manager)
+- Try rebuilding the extension with `--clean-first`
+
+### "Other classes work but IPCClient doesn't"
+- Check that `godot/src/register_types.cpp` includes:
+  ```cpp
+  ClassDB::register_class<IPCClient>();
+  ```
+- Rebuild the extension
+
+### "DLL file is locked / can't delete"
+- Close Godot first
+- If still locked, restart Windows (Godot may have crashed)
+
+### "Extension loads but crashes"
+- Check Windows Event Viewer for C++ errors
+- Try Debug build instead of Release build
+- Check that all includes are correct in `agent_arena.h`
+
+## Still Not Working?
+
+1. Check the build output for any errors (warnings are OK)
+2. Verify the file `godot/src/agent_arena.cpp` contains the IPCClient implementation
+3. Verify `godot/include/agent_arena.h` contains the IPCClient class definition
+4. Try creating a minimal test:
+   ```gdscript
+   extends Node
+   func _ready():
+       var client = IPCClient.new()
+       print("IPCClient created: ", client)
+       client.free()
+   ```
+
+## Quick Checklist
+
+- [ ] Godot is completely closed
+- [ ] `.godot` folder deleted
+- [ ] DLL exists and is recent (check timestamp)
+- [ ] Extension built successfully (no errors)
+- [ ] `IPCClient` registered in `register_types.cpp`
+- [ ] Godot restarted
+- [ ] Test script runs successfully