docs/USAGE.md

Usage Guide

This guide explains how to run UN motion simulations with AI agents.

Prerequisites

1. Python 3.12+ installed
2. Virtual environment set up
3. API key (for cloud provider) OR Ollama (for local provider)

Setup

1. Install Dependencies

# Using uv (recommended)
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt

2. Configure Environment

# Copy the example configuration
cp .env.example .env

# Edit .env with your preferred editor
nano .env  # or vim, code, etc.

For Cloud API (OpenAI/GPT):

OPENAI_API_KEY=sk-your-key-here
MODEL_NAME=gpt-4

For Cloud API (Anthropic/Claude):

ANTHROPIC_API_KEY=sk-ant-your-key-here
MODEL_NAME=claude-3-opus-20240229

For Local Models (Ollama):

# No API key needed!
# Install Ollama from https://ollama.ai
# Pull a model: ollama pull llama3
LOCAL_MODEL_NAME=llama3

Running Simulations

Basic Usage

# Run a motion with cloud API (default)
python scripts/run_motion.py 01_gaza_ceasefire_resolution

# Run with local model
python scripts/run_motion.py 01_gaza_ceasefire_resolution --provider local

# Run with specific model
python scripts/run_motion.py 01_gaza_ceasefire_resolution --model gpt-4-turbo

# Test with sample (only 5 countries)
python scripts/run_motion.py 01_gaza_ceasefire_resolution --sample 5

Command-Line Options

python scripts/run_motion.py <motion_id> [options]

Required:
  motion_id              ID of the motion (e.g., 01_gaza_ceasefire_resolution)

Options:
  --provider {cloud,local}   AI provider (default: cloud)
  --model MODEL_NAME         Specific model to use (optional)
  --sample N                 Only query N countries for testing (optional)
  -h, --help                 Show help message

Example Output

============================================================
Running Motion: 01_gaza_ceasefire_resolution
Provider: cloud | Model: gpt-4
============================================================

✓ Loaded motion from /home/user/AI-Agent-UN/tasks/motions/01_gaza_ceasefire_resolution.md

📊 Querying 193 countries

[1/193] Querying Afghanistan... ✅ YES
[2/193] Querying Albania... ✅ YES
[3/193] Querying Algeria... ✅ YES
[4/193] Querying Andorra... ✅ YES
[5/193] Querying Angola... ✅ YES
...

============================================================
Vote Summary:
  YES:     156 (80.8%)
  NO:       25 (13.0%)
  ABSTAIN:  12 ( 6.2%)
============================================================

✓ Results saved to: tasks/reactions/01_gaza_ceasefire_resolution_20251009_143022.json
✓ Latest results: tasks/reactions/01_gaza_ceasefire_resolution_latest.json

✓ Motion simulation complete!

Understanding Results

Results are saved as JSON files in tasks/reactions/:

File Structure

{
  "motion_id": "01_gaza_ceasefire_resolution",
  "motion_path": "tasks/motions/01_gaza_ceasefire_resolution.md",
  "timestamp": "2025-10-09T14:30:22.123456Z",
  "provider": "cloud",
  "model": "gpt-4",
  "total_votes": 193,
  "vote_summary": {
    "yes": 156,
    "no": 25,
    "abstain": 12
  },
  "votes": [
    {
      "country": "United States",
      "country_slug": "united-states",
      "vote": "yes",
      "statement": "The United States supports this ceasefire agreement as it represents a critical step toward de-escalation and humanitarian relief. We emphasize the importance of protecting civilians and ensuring accountability for violations of international law.",
      "error": null
    },
    {
      "country": "Russia",
      "country_slug": "russia",
      "vote": "yes",
      "statement": "Russia welcomes this ceasefire and calls for immediate humanitarian access. We emphasize the need for a comprehensive political settlement based on international law and UN resolutions.",
      "error": null
    }
  ]
}

Analyzing Results

You can analyze results programmatically:

import json

# Load results
with open('tasks/reactions/01_gaza_ceasefire_resolution_latest.json') as f:
    results = json.load(f)

# Print vote breakdown
print(f"Total votes: {results['total_votes']}")
print(f"YES: {results['vote_summary']['yes']}")
print(f"NO: {results['vote_summary']['no']}")
print(f"ABSTAIN: {results['vote_summary']['abstain']}")

# Find all NO votes
no_votes = [v for v in results['votes'] if v['vote'] == 'no']
for vote in no_votes:
    print(f"{vote['country']}: {vote['statement']}")

Tips and Best Practices

1. Testing with Samples

When developing or testing, use --sample to query only a few countries:

# Test with 5 countries first
python scripts/run_motion.py 01_gaza_ceasefire_resolution --sample 5

2. Cost Management (Cloud API)

• Start with small samples to estimate costs
• A full run (193 countries) typically uses ~200-300 API calls
• Use cheaper models (gpt-3.5-turbo) for testing
• Consider local models (Ollama) for cost-free experimentation

3. Local Models

Pros:

• No API costs
• Complete privacy
• Unlimited usage

Cons:

• Requires local compute resources
• May have lower quality responses
• Slower than cloud APIs

4. Troubleshooting

Error: "api_key client option must be set"

• Make sure .env file exists
• Check that OPENAI_API_KEY is set correctly
• Verify the key is valid

Error: "Motion not found"

• Check that the motion ID matches the filename (without .md)
• Motion files must be in tasks/motions/

Error: "openai package not installed"

• Install dependencies: uv pip install -r requirements.txt

Error: Connection refused (local model)

• Make sure Ollama is running: ollama serve
• Check that the model is pulled: ollama pull llama3

Advanced Usage

Using Alternative APIs

You can use any OpenAI-compatible API by setting API_BASE_URL:

# OpenRouter
API_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=your-openrouter-key

# Local OpenAI-compatible server
API_BASE_URL=http://localhost:11434/v1

Creating New Motions

1. Create a new markdown file in tasks/motions/
2. Use the format from existing motions
3. Run: python scripts/run_motion.py your_new_motion_id

Analyzing Patterns

Compare different runs:

# Run with different models
python scripts/run_motion.py 01_gaza_ceasefire_resolution --model gpt-4
python scripts/run_motion.py 01_gaza_ceasefire_resolution --model gpt-3.5-turbo
python scripts/run_motion.py 01_gaza_ceasefire_resolution --provider local --model llama3

# Compare results
diff tasks/reactions/01_gaza_ceasefire_resolution_20251009_143022.json \
     tasks/reactions/01_gaza_ceasefire_resolution_20251009_144533.json

Next Steps

• Create additional motions in tasks/motions/
• Analyze voting patterns across different issues
• Compare how different AI models vote
• Export results to visualization tools
• Build analysis scripts to identify voting blocs