🌍 Nation-Sim: AI-Powered Geopolitical Simulation

A sophisticated, max-realism seven-nation simulator featuring AI-driven governance, real-time decision-making, and comprehensive economic, social, and political modeling.

✨ Features

🤖 AI-Powered Nations

• 7 unique nations with distinct AI leaders and decision-making styles
• LLM-enhanced reasoning for realistic policy decisions
• Reinforcement learning integration for adaptive governance
• Real-time AI decision logging with full rationale

📊 Comprehensive Simulation

• Economic modeling: GDP, unemployment, inflation, trade, debt
• Social dynamics: Legitimacy, unrest, rights, press freedom
• Infrastructure: Grid health, technology, healthcare, education
• International relations: Diplomacy, alliances, conflicts
• Environmental factors: Climate, resources, sustainability

🖥️ Multiple Interfaces

• Desktop GUI: Native tkinter application with matplotlib charts
• Web Dashboard: Real-time browser-based interface with D3.js visualizations
• Command Line: Batch processing and automation tools

⚡ Real-Time Operation

• Live simulation: 1 real day = 1 simulated year (52 weeks)
• WebSocket updates: Real-time data streaming
• Persistent state: Save/load simulation progress
• Background processing: Non-blocking simulation execution

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• pip package manager

Installation

git clone https://github.com/yourusername/nation-sim.git
cd nation-sim
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Running the Simulation

🖥️ Desktop GUI (Recommended)

python run_gui.py

• Native desktop application
• Real-time charts and data
• Full simulation control
• No web server required

🌐 Web Dashboard

python webapp/app.py

Then open http://localhost:5001 in your browser

💻 Command Line

python run_loop.py          # Basic simulation loop
python run_persistent.py    # Persistent real-time simulation
python run_ai_loop.py       # AI-focused simulation

📁 Project Structure

nation-sim/
├── 📊 docs/                   # General documentation
├── 🧮 mathematics/            # Mathematical models and algorithms
│   ├── algorithms/            # RL agents and training algorithms
│   │   ├── rl_agents.py      # Deep Q-Network implementations
│   │   ├── rl_integration.py # RL integration with simulation
│   │   └── train_rl_agents.py # RL training procedures
│   ├── models/               # AI agent models and reasoning
│   │   ├── ai_agents.py      # AI decision-making systems
│   │   └── llm_reasoning.py  # LLM-enhanced reasoning
│   ├── documentation/        # Mathematical frameworks
│   │   ├── mathematical_framework.md
│   │   ├── policy_mathematics.md
│   │   ├── reinforcement_learning_algorithms.md
│   │   └── simulation_dynamics.md
│   └── README.md             # Mathematics package documentation
├── 🧠 nationsim/           # Core simulation engine
│   ├── world.py            # Main world simulation
│   ├── nation.py           # Nation state management
│   ├── ai_agent.py         # AI decision-making
│   ├── modules/            # Specialized simulation modules
│   └── ...
├── 🖥️ gui_app.py           # Desktop GUI application
├── 🌐 webapp/              # Web interface
│   ├── app.py              # Flask web server
│   ├── templates/          # HTML templates
│   └── static/             # CSS, JS, images
├── 📈 visualize_nations.py # Data visualization tools
├── 🤖 train_rl_agents.py   # Reinforcement learning training
└── 📋 requirements.txt     # Python dependencies

🎮 Usage Examples

Start a Real-Time Simulation

from nationsim.world import World

# Initialize world
world = World("data/nations.yaml", "data/relations.yaml")

# Run simulation steps
for week in range(52):  # One year
    world.step(1)
    print(f"Week {week}: {len(world.state.nations)} nations active")

Access Nation Data

# Get nation statistics
for nation_id, nation in world.state.nations.items():
    print(f"{nation.name}: GDP=${nation.gdp/1e12:.1f}T, Pop={nation.population/1e6:.1f}M")

AI Decision Monitoring

# View recent AI decisions
from nationsim.decision_journal import get_recent_decisions
decisions = get_recent_decisions(limit=10)
for decision in decisions:
    print(f"{decision['nation_id']}: {decision['action']} - {decision['rationale']}")

🔧 Configuration

Nation Customization

Edit data/nations.yaml to modify:

• Initial population, GDP, and economic indicators
• Political systems and governance styles
• Geographic and resource characteristics
• AI personality traits and decision preferences

Simulation Parameters

Modify simulation constants in nationsim/world.py:

• Time scaling (real-time to simulation-time ratio)
• Economic growth rates and volatility
• Political stability factors
• International relationship dynamics

📊 Visualization

Built-in Charts

• Economic indicators: GDP, unemployment, inflation trends
• Social metrics: Legitimacy, unrest, rights scores
• International relations: Alliance networks, trade flows
• Policy impacts: Decision effectiveness over time

Export Options

• PNG/SVG chart exports
• CSV data dumps
• JSON state snapshots
• Real-time data streaming

🤖 AI System

Decision-Making Architecture

• Policy evaluation: Multi-criteria analysis of available actions
• Risk assessment: Probabilistic outcome modeling
• Learning adaptation: RL-based strategy refinement
• Reasoning transparency: Full decision rationale logging

Supported AI Models

• Local LLM integration: Ollama, GPT4All compatibility
• Cloud APIs: OpenAI GPT, Anthropic Claude support
• Hybrid approaches: LLM reasoning + RL optimization

🛠️ Development

Running Tests

python -m pytest tests/

Code Style

pip install black flake8
black .
flake8 .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📈 Performance

Benchmarks

• Simulation speed: ~100 weeks/second (7 nations)
• Memory usage: ~50MB base + ~10MB per saved state
• Web interface: <100ms response time for data queries
• GUI refresh rate: 60fps chart updates

Scaling

• Supports up to 20 nations with linear performance degradation
• Configurable simulation complexity for performance tuning
• Distributed processing support for large-scale scenarios

🔍 Troubleshooting

Common Issues

Import errors with pydantic/typing_extensions

pip install --upgrade typing_extensions pydantic

GUI not starting

# Ensure tkinter is available
python -c "import tkinter; print('✅ tkinter available')"

Web dashboard not loading

pip install flask-socketio
python webapp/app.py

📚 Documentation

• API Reference: See docs/api.md
• Architecture Guide: See docs/architecture.md
• Tutorial: See docs/tutorial.md
• Examples: See examples/ directory

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas for Contribution

• New simulation modules (climate, technology, culture)
• AI agent improvements and new strategies
• Visualization enhancements
• Performance optimizations
• Documentation and examples

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by real-world geopolitical modeling systems
• Built with modern Python ecosystem tools
• Community feedback and contributions welcomed

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: your.email@example.com

---

Nation-Sim - Bringing AI-powered geopolitical simulation to everyone 🌍