Get expert strategic guidance for EU5 using GPT-5-mini with a comprehensive knowledge base covering all 8 main game panels.

• GPT-5-mini Powered - Fast, cost-effective AI-driven strategy advice
• Comprehensive Knowledge Base - 13 curated files covering all 8 EU5 game panels
• Web Search Fallback - Automatically searches for missing content (prioritizes eu5.paradoxwikis.com)
• Beautiful CLI - Rich terminal formatting with markdown rendering
• In-memory caching - Lightweight LRU caches for knowledge and search to reduce repeated file I/O and queries (use --cache-stats to view stats)
• Flexible Configuration - Environment variables, .env files, or direct parameters
• Fast Responses - 2-3 second response times

From Source:

git clone https://github.com/eggressive/eu5-strategy-agent.git
cd eu5-strategy-agent
pip install -r requirements.txt

1. Copy the example configuration:

   cp .env.example .env

2. Edit .env and add your API key:

   OPENAI_API_KEY=your-api-key-here
   OPENAI_MODEL=gpt-5-mini

3. Get an API key from platform.openai.com/api-keys

• Does NOT support temperature parameter (uses default=1.0)
• Uses max_completion_tokens instead of max_tokens
• The agent handles these differences automatically

The agent works with OpenAI models and OpenAI-compatible providers:

Simply change OPENAI_MODEL in your .env file.

Use free OpenAI-compatible providers by changing OPENAI_BASE_URL:

Groq (14,400 free requests/day, ultra-fast):

OPENAI_API_KEY=your-groq-api-key
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_MODEL=llama-3.1-8b-instant

Google AI Studio (1M free tokens/minute):

OPENAI_API_KEY=your-google-api-key
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
OPENAI_MODEL=gemini-2.5-flash

OpenRouter (300+ models, some free):

OPENAI_API_KEY=your-openrouter-api-key
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=meta-llama/llama-3.3-70b-instruct

Requirements: All providers must support function calling (most modern models do).

See docs/CONFIGURATION.md for detailed setup instructions.

The agent can use Tavily API for web search when knowledge base doesn't have the answer. This is completely optional - the agent works perfectly with just the local knowledge base.

1. Get FREE Tavily API key (1000 searches/month): tavily.com

2. Add to .env file:

   TAVILY_API_KEY=your-tavily-api-key-here

• AI-optimized search results (clean text, no HTML parsing)
• Prioritizes eu5.paradoxwikis.com domain
• 1000 free searches per month
• Falls back gracefully when not configured

Without Tavily: Agent works perfectly for all content in knowledge base, just can't search the web for content outside the local files.

Interactive Mode:

python run_agent.py

Single Query:

python run_agent.py --query "How do estates work in EU5?"

With Verbose Output:

python run_agent.py --query "What are the best opening moves for England?" --verbose

Programmatic Use:

from eu5_agent import EU5Agent

agent = EU5Agent()
response = agent.chat("How does the market system work?")
print(response)

If you want to run the CLI directly from the repository or make the console script available, use one of these approaches:

• Run from the repository root (recommended):

# Module invocation
python -m eu5_agent.cli --cache-stats
python -m eu5_agent.cli --query "How do estates work in EU5?"

• If you're inside the eu5_agent/ directory or have PYTHONPATH conflicts, explicitly set PYTHONPATH to the repo root so Python can discover packages correctly:

# If you're in the `eu5_agent/` subdirectory, set PYTHONPATH to the parent
# directory (repo root) so Python can discover the package correctly.
PYTHONPATH=.. python -m eu5_agent.cli --cache-stats

• Install an editable package (recommended for local development) to enable the console script eu5-agent:

pip install -e .
eu5-agent --cache-stats
eu5-agent --query "How do estates work?"

Note: Using pip install -e . will install the console script eu5-agent defined in pyproject.toml so you can run the CLI without python -m.

When running python -m eu5_agent.cli, Python interprets the module path relative to the working directory. If you execute python -m eu5_agent.cli from within the eu5_agent/ directory itself (or other subdirectory where the package name duplicates a file/directory), Python's import machinery may not find the correct package root, causing a ModuleNotFoundError.

To avoid this:

• Run the module from the repository root (where setup.py/pyproject.toml lives):

cd /path/to/eu5-strategy-agent
python -m eu5_agent.cli --query "How do estates work?"

• Or run with an explicit PYTHONPATH that includes the repo root:

cd /path/to/eu5-strategy-agent/eu5_agent
# Set PYTHONPATH to parent dir (repo root) when executing from inside the package folder
PYTHONPATH=.. python -m eu5_agent.cli --query "How do estates work?"

• For a better developer experience, install the package in editable mode so you can run eu5-agent directly and avoid module discovery issues:

pip install -e .[dev]
eu5-agent --query "How do estates work?"

This is a common Python packaging pitfall. Using one of the approaches above ensures Python can find the package root and run the module correctly.

The agent includes comprehensive knowledge covering:

• Economy - Trade, markets, taxation, income
• Government - Laws, institutions, cabinets, reforms
• Production - Buildings, goods, development
• Society - Estates, population classes, privileges
• Diplomacy - Relations, alliances, vassals, wars
• Military - Units, armies, commanders, morale
• Warfare - Combat, sieges, terrain, tactics
• Geopolitics - Regions, power projection, subjects
• Advances - Technology, ideas, innovations

• Beginner Route - Learning path for new players
• Common Mistakes - Pitfalls to avoid

• England - Opening strategy with 50-year checklist

• External Wikis - Community resources and links

# Game Mechanics
python run_agent.py --query "How does the market system work?"

# Beginner Guidance
python run_agent.py --query "I'm new to EU5. Which nation should I start with?"

# Nation-Specific Strategy
python run_agent.py --query "What are the best opening moves for England?"

# Advanced Topics
python run_agent.py --query "What are common beginner mistakes to avoid?"

The agent supports three configuration methods:

1. Environment Variables
2. .env File (Recommended for development)
3. Direct Parameters (Programmatic use)

See docs/CONFIGURATION.md for complete configuration guide.

• Python 3.11+
• OpenAI API key
• Dependencies (5 packages):
  • openai >= 1.0.0
  • pydantic >= 2.0.0
  • rich >= 13.0.0
  • tavily-python >= 0.3.0 (optional - for web search)
  • python-dotenv >= 1.0.0

• Configuration Guide - Complete configuration reference

This is a standalone agent independent of any framework:

• Direct File Loading - No vector database complexity
• Simple OpenAI Integration - Direct API calls with function calling
• Minimal Dependencies - Only 5 packages required
• Fast Startup - < 1 second initialization

The agent uses:

1. Local knowledge base (primary) - Direct markdown file loading
2. Web search - Tavily API for AI-optimized search
   • Prioritizes eu5.paradoxwikis.com
3. GPT-5-mini - OpenAI's latest efficient model

Run the full test suite (excludes integration tests by default):

pytest

Run only unit tests (explicitly exclude integration tests):

pytest -m "not openai_integration"

• The repository includes optional integration tests that make real OpenAI API calls. These tests:

• Are gated behind the openai_integration pytest marker

• Skip automatically when OPENAI_API_KEY is not set

• Keep costs low (max_completion_tokens ≤ 50, single-turn interactions)

• Verify actual OpenAI API functionality

Run integration tests:

# Set your API key first
export OPENAI_API_KEY=your-api-key-here

# Optional: customize model and base URL
export OPENAI_MODEL=gpt-5-mini
export OPENAI_BASE_URL=https://api.openai.com/v1

# Run integration tests only
pytest -m openai_integration

# Run all tests (unit + integration)
pytest

Note: Integration tests will incur minimal API costs (typically < $0.01 per run).

Test your API key and model configuration:

python tests/test_openai_api.py

Contributions are welcome! See TODO.md for a complete list of planned enhancements and areas where contributions are needed.

Pull requests, issue reports, and feedback are all appreciated.

MIT License - see LICENSE file for details.

• Built with OpenAI API
• Uses Rich for beautiful terminal output
• Knowledge sourced from EU5 Wiki

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for the EU5 community