Spaces:
Configuration error
Configuration error
| # 🤖 AI Agent Setup Guide | |
| This guide explains how to set up and configure AI agents for PyCatan. | |
| ## 📋 Table of Contents | |
| 1. [Quick Start](#quick-start) | |
| 2. [API Key Setup](#api-key-setup) | |
| 3. [Configuration System](#configuration-system) | |
| 4. [Security Best Practices](#security-best-practices) | |
| 5. [Development Workflow](#development-workflow) | |
| --- | |
| ## 🚀 Quick Start | |
| ### Step 1: Get an API Key | |
| You need an API key from an LLM provider. We recommend **Google Gemini** for development: | |
| 1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey) | |
| 2. Click "Create API Key" | |
| 3. Copy your API key | |
| **Other providers:** | |
| - OpenAI: https://platform.openai.com/api-keys | |
| - Anthropic: https://console.anthropic.com/settings/keys | |
| ### Step 2: Setup Environment Variables | |
| ```bash | |
| # Copy the template file | |
| cp .env.example .env | |
| # Edit .env and paste your API key | |
| # (Use any text editor) | |
| ``` | |
| Example `.env` file: | |
| ```bash | |
| GEMINI_API_KEY=AIzaSyC_your_actual_api_key_here | |
| ``` | |
| ### Step 3: Install Dependencies | |
| ```bash | |
| pip install pyyaml | |
| ``` | |
| ### Step 4: Test the Configuration | |
| ```bash | |
| python examples/test_ai_config.py | |
| ``` | |
| You should see: | |
| ``` | |
| 🎉 All tests passed! | |
| ``` | |
| --- | |
| ## 🔑 API Key Setup | |
| ### Where API Keys Are Stored | |
| **API keys are stored in the `.env` file**, which is: | |
| - ✅ **NOT** committed to Git (protected by `.gitignore`) | |
| - ✅ Stored locally on your machine only | |
| - ✅ Easy to update without changing code | |
| ### `.env` File Structure | |
| ```bash | |
| # .env - YOUR PRIVATE FILE (never commit this!) | |
| GEMINI_API_KEY=your_actual_key_here | |
| OPENAI_API_KEY=your_openai_key_here # Optional | |
| ANTHROPIC_API_KEY=your_anthropic_key # Optional | |
| ``` | |
| ### `.env.example` File | |
| The **`.env.example`** file is a template that: | |
| - ✅ **IS** committed to Git | |
| - ✅ Shows what variables are needed | |
| - ✅ Contains NO actual secrets | |
| - ✅ Helps other developers know what to set up | |
| **Never put real API keys in `.env.example`!** | |
| --- | |
| ## ⚙️ Configuration System | |
| ### Overview | |
| PyCatan uses a **two-file configuration system**: | |
| ``` | |
| 📁 Project Root | |
| ├── .env # ❌ NOT in Git - API keys | |
| ├── .env.example # ✅ IN Git - Template | |
| ├── pycatan/ai/ | |
| │ ├── config_example.yaml # ✅ IN Git - Documentation | |
| │ ├── config_dev.yaml # ✅ IN Git - Dev defaults | |
| │ └── my_agent_config.yaml # ❌ NOT in Git - Your custom config | |
| ``` | |
| ### File Types Explained | |
| #### 1. `.env` - Environment Variables (API Keys) | |
| - **Purpose:** Store sensitive API keys | |
| - **Git:** ❌ **NEVER** committed | |
| - **Contains:** `GEMINI_API_KEY=actual_secret_key` | |
| - **Who creates it:** Each developer on their machine | |
| #### 2. `.env.example` - Environment Template | |
| - **Purpose:** Template showing what variables are needed | |
| - **Git:** ✅ Committed to Git | |
| - **Contains:** `GEMINI_API_KEY=` (empty) | |
| - **Who creates it:** Already created in the project | |
| #### 3. `config_dev.yaml` - Development Defaults | |
| - **Purpose:** Default configuration for development | |
| - **Git:** ✅ Committed to Git | |
| - **Contains:** All settings EXCEPT API keys | |
| - **Who uses it:** Everyone, automatically | |
| #### 4. `config_example.yaml` - Configuration Documentation | |
| - **Purpose:** Complete documentation of all options | |
| - **Git:** ✅ Committed to Git | |
| - **Contains:** All possible settings with explanations | |
| - **Who uses it:** Reference when creating custom configs | |
| #### 5. Your Custom Config (e.g., `my_agent_config.yaml`) | |
| - **Purpose:** Your personal agent configuration | |
| - **Git:** ❌ NOT committed (optional) | |
| - **Contains:** Custom personality, strategies, etc. | |
| - **Who uses it:** You, when you want special behavior | |
| --- | |
| ## 🔒 Security Best Practices | |
| ### ✅ DO: | |
| - Keep your `.env` file local only | |
| - Use different API keys for development and production | |
| - Rotate your API keys regularly | |
| - Review `.gitignore` to ensure `.env` is excluded | |
| - Use `.env.example` as a template for team members | |
| ### ❌ DON'T: | |
| - Never commit `.env` to Git | |
| - Never put API keys in configuration YAML files | |
| - Never share your `.env` file | |
| - Never hardcode API keys in Python code | |
| - Never put API keys in commit messages or PR descriptions | |
| ### Checking Security | |
| ```bash | |
| # Make sure .env is ignored by Git | |
| git status | |
| # .env should NOT appear in the list | |
| # If it does, remove it: | |
| git rm --cached .env | |
| ``` | |
| --- | |
| ## 🛠️ Development Workflow | |
| ### Using the Default Development Config | |
| The simplest way - just use `config_dev.yaml`: | |
| ```python | |
| from pycatan.ai.config import AIConfig | |
| # Loads config_dev.yaml by default | |
| config = AIConfig.from_file('pycatan/ai/config_dev.yaml') | |
| # API key is automatically loaded from .env | |
| api_key = config.get_api_key() # Reads GEMINI_API_KEY from .env | |
| ``` | |
| ### Creating a Custom Agent | |
| 1. **Copy the example config:** | |
| ```bash | |
| cp pycatan/ai/config_example.yaml my_aggressive_agent.yaml | |
| ``` | |
| 2. **Edit your config:** | |
| ```yaml | |
| agent_name: "Aggressive Trader" | |
| agent: | |
| personality: "aggressive" | |
| risk_tolerance: 0.8 | |
| trade_willingness: 0.9 | |
| ``` | |
| 3. **Use it in your code:** | |
| ```python | |
| config = AIConfig.from_file('my_aggressive_agent.yaml') | |
| ``` | |
| 4. **The API key is still loaded from `.env`** - you don't need to specify it! | |
| ### Multiple Agents with Different Personalities | |
| ```python | |
| # Agent 1: Aggressive | |
| config1 = AIConfig.from_file('configs/aggressive.yaml') | |
| # Agent 2: Defensive | |
| config2 = AIConfig.from_file('configs/defensive.yaml') | |
| # Agent 3: Balanced (default) | |
| config3 = AIConfig.from_file('pycatan/ai/config_dev.yaml') | |
| # All three use the same API key from .env | |
| ``` | |
| --- | |
| ## 📝 Configuration Options | |
| ### LLM Settings | |
| ```yaml | |
| llm: | |
| provider: "gemini" # or "openai", "anthropic" | |
| model_name: "gemini-2.0-flash-exp" | |
| temperature: 0.7 # 0.0 = deterministic, 1.0 = creative | |
| max_tokens: 4096 | |
| ``` | |
| ### Agent Personality | |
| ```yaml | |
| agent: | |
| personality: "balanced" # aggressive, defensive, balanced, trading | |
| risk_tolerance: 0.5 # 0.0 = safe, 1.0 = risky | |
| # Strategic focus (0.0 to 1.0) | |
| focus_on_settlements: 0.6 | |
| focus_on_cities: 0.7 | |
| focus_on_roads: 0.5 | |
| focus_on_dev_cards: 0.6 | |
| # Trading behavior | |
| trade_willingness: 0.5 # 0.0 = never, 1.0 = always | |
| trade_fairness: 0.7 # How fair are trades | |
| ``` | |
| ### Debug Settings | |
| ```yaml | |
| debug: | |
| debug_mode: true # Enable detailed logging | |
| log_prompts: true # Log prompts sent to LLM | |
| log_responses: true # Log LLM responses | |
| save_game_states: true # Save states for analysis | |
| ``` | |
| --- | |
| ## 🧪 Testing Your Setup | |
| ### Test 1: Check API Key | |
| ```python | |
| from pycatan.ai.config import AIConfig | |
| config = AIConfig() | |
| try: | |
| api_key = config.get_api_key() | |
| print("✓ API key loaded successfully") | |
| except ValueError as e: | |
| print(f"✗ Error: {e}") | |
| ``` | |
| ### Test 2: Load Configuration | |
| ```python | |
| config = AIConfig.from_file('pycatan/ai/config_dev.yaml') | |
| print(f"✓ Loaded config for: {config.agent_name}") | |
| print(f" Provider: {config.llm.provider}") | |
| print(f" Model: {config.llm.model_name}") | |
| ``` | |
| ### Test 3: Run Full Test Suite | |
| ```bash | |
| python examples/test_ai_config.py | |
| ``` | |
| --- | |
| ## 🎯 Common Scenarios | |
| ### Scenario 1: "I just cloned the repo" | |
| 1. Create `.env`: `cp .env.example .env` | |
| 2. Add your API key to `.env` | |
| 3. Run tests: `python examples/test_ai_config.py` | |
| ### Scenario 2: "I want to test different personalities" | |
| Use the existing configs: | |
| - `config_dev.yaml` - Balanced agent | |
| - Or create custom configs based on `config_example.yaml` | |
| ### Scenario 3: "I want to switch LLM providers" | |
| Edit your config file: | |
| ```yaml | |
| llm: | |
| provider: "openai" | |
| model_name: "gpt-4-turbo-preview" | |
| api_key_env_var: "OPENAI_API_KEY" | |
| ``` | |
| Add the key to `.env`: | |
| ```bash | |
| OPENAI_API_KEY=sk-your-key-here | |
| ``` | |
| ### Scenario 4: "My API key changed" | |
| Just edit `.env` - no code changes needed! | |
| --- | |
| ## 📚 Next Steps | |
| - Read [AI_ARCHITECTURE.md](AI_ARCHITECTURE.md) for system design | |
| - Read [WORK_PLAN.md](WORK_PLAN.md) for development roadmap | |
| - See [config_example.yaml](../pycatan/ai/config_example.yaml) for all options | |
| --- | |
| ## 🆘 Troubleshooting | |
| ### "ModuleNotFoundError: No module named 'yaml'" | |
| ```bash | |
| pip install pyyaml | |
| ``` | |
| ### "API key not found" | |
| 1. Check `.env` exists in project root | |
| 2. Check the API key variable name matches | |
| 3. Try: `cat .env` to verify content | |
| ### "Configuration file not found" | |
| - Use absolute paths or run from project root | |
| - Check file extension (`.yaml` not `.yml`) | |
| ### "Still stuck?" | |
| - Check [GitHub Issues](your-repo-url/issues) | |
| - Review the test output: `python examples/test_ai_config.py` | |
| --- | |
| **Last Updated:** January 3, 2026 | |