How goodstartlabs/ai_diplomacy works
Project Type and Purpose
• This is a full-stack, AI-powered extension of a turn-based board game (“Diplomacy”) combining:
• A Python core game engine (diplomacy package)
• An AI layer of stateful agents powered by LLMs (ai_diplomacy package + CLI orchestrators)
• Analysis pipelines (analysis/, experiment_runner/analysis/)
• Interactive visualizations:
– 3D animation front-end (ai_animation/ with Vite/TypeScript)
– React web UI (diplomacy/web/)
• Deployment support via Docker and docker-compose
File Structure
• Top-level Python modules and CLI scripts:
• diplomacy/ – core engine, network client, server, maps, utils, web backend
• ai_diplomacy/ – AI agent implementation, LLM client abstractions, prompt templates
• Orchestrators: lm_game.py, experiment_runner.py, plus analysis/, experiments/
• Front-end:
• diplomacy/web/ – React app for human play and visualization of games
• ai_animation/ – standalone 3D playback UI
• Config/deployment:
• .env.example, docker-compose.yaml, Dockerfiles in subdirs
• Data:
• results/ directories written at runtime (JSON, CSV, logs)
• Analysis notebooks and scripts reading those results
Extract Key Insights from README
• Core engine is a Python library managing game state, map logic, server/client APIs
• ai_diplomacy agents wrap the engine, track memory, build LLM prompts, call LLMs for decisions
• CLI tools (lm_game.py, experiment_runner.py) orchestrate game loops, batch experiments, and launch analysis modules
• Data flow: engine + agents → LLM calls → orders & messages → engine processes next phase → logs & results written → post-game analysis and visualization
Main Components & Interactions
a. Components
• Core Game Engine (diplomacy package)
• AI Agent Layer (ai_diplomacy modules)
• Orchestrators (lm_game.py, experiment_runner.py)
• External LLM Services (OpenAI, Claude, Gemini, etc.)
• Data Store (results directory, JSON/CSV files)
• Analysis Pipelines (analysis/, experiment_runner/analysis/)
• 3D Animation Front-end (ai_animation/)
• Web UI & Server (diplomacy/web/ + diplomacy.server)
• Deployment & CI (Docker, GitHub workflows)
b. Relationships & Data Flow
1. Orchestrator (lm_game)
– Invokes Core Engine to initialize game state
– Instantiates one DiplomacyAgent per power (ai_diplomacy.agent)
– In each phase:
• Gathers game state from Core Engine
• Agent builds prompt via PromptConstructor → calls LLM Client → receives decision
• Submits orders/messages back to engine → engine processes phase
• Writes phase summary & agent state to Results (JSON, logs, llm_responses.csv)
2. Experiment Runner
– Launches multiple lm_game instances in parallel
– Aggregates runs under an experiment directory
– Triggers Analysis Pipelines upon completion
3. Analysis Pipelines
– Read Result files → generate RL JSON → statistical reports, lie detection, moment analysis
4. Visualization & Web UI
– 3D Animation reads saved game JSON → interactive playback
– React Web UI connects via WebSocket/HTTP to diplomacy.server → real-time game view & human players
5. External LLM Services
– ai_diplomacy/clients call third-party APIs → return structured replies → Agent updates memory
c. Architectural Patterns & Design Principles
– Modular layered design:
• Engine layer (core game logic)
• AI layer (agents, prompt templates)
• Orchestration/CLI layer
• Data analysis layer
• Presentation/UI layers
– Separation of concerns: engine is independent of AI, which is independent of UI
– Plugin-style LLM client abstraction (supports multiple providers)
– Batch orchestration via ExperimentRunner using process pools
– File-based persistence for reproducibility
d. Technologies & Frameworks
– Python 3.10+ with uv for env management
– LLM APIs (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter)
– TypeScript + Vite for 3D animation
– React for web UI
– Docker & docker-compose for containerization
– Playwright & Vitest for testing front-ends
– Sphinx for API docs