Usage

Installation

To use TheTraitors, first install it using pip:

$ pip install -r requirements.txt

You’ll need to set up API keys for the LLM providers you want to use. Create a .env file in the project root with your API keys:

OPENAI_API_KEY=your_openai_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key
TOGETHER_API_KEY=your_together_api_key
HF_API_TOKEN=your_huggingface_token

Basic Usage

Running a Game

To run a basic game simulation:

from traitors_game import TraitorsGame

# Create a configuration dictionary
config = {
    'game': {
        'agent_count': 10,
        'traitor_count': 3,
        'seed': 42,
        'experiment_name': 'my_experiment'
    },
    'llm': {
        'model': 'gpt-3.5-turbo',
        'client_type': 'openai',
        'provider': 'openai'
    }
}

# Create a game with 10 agents, 3 of which are traitors
game = TraitorsGame(
    config=config,
    agent_count=10,
    traitor_count=3,
    model="gpt-3.5-turbo",
    client_type="openai",
    provider="openai",
    seed=42  # For reproducibility
)

# Run the game
game.run()

# Analyze the results
game.post_game_analysis()

Agent Traits

You can define personality traits for agents in your configuration file:

config = {
    # ...other configuration...
    'agent_configs': [
        {
            'model': 'gpt-3.5-turbo',
            'client_type': 'openai',
            'enforce_role': 'Traitor',  # Optional role enforcement
            'traits': {
                'age': 42,
                'nationality': 'British',
                'profession': 'Detective',
                'ethnicity': 'Caucasian',
                'civil_status': 'Divorced',
                'gender_pronoun': 'He',
                'children': 2
            }
        },
        # More agent configurations...
    ]
}

The traits will be used during the introduction phase to create a richer game experience.

Command Line Interface

You can also run the game using the command line interface:

$ python main.py --config path/to/config.yaml

# Or with direct arguments
$ python main.py --agents 10 --traitors 3 --model gpt-3.5-turbo --client openai --provider openai --seed 42

Configuration with YAML

You can create a YAML configuration file with all game parameters:

game:
  agent_count: 10
  traitor_count: 3
  seed: 42
  experiment_name: experiment_1

llm:
  model: gpt-3.5-turbo
  client_type: openai
  provider: openai

agent_configs:
  - model: gpt-3.5-turbo
    client_type: openai
    enforce_role: Traitor
    traits:
      age: 45
      nationality: American
      profession: Lawyer
      ethnicity: Latino
      civil_status: Married
      gender_pronoun: He
      children: 3

Configuration Options

The TraitorsGame constructor accepts the following parameters:

config: Configuration dictionary with game parameters
agent_count: Number of agents in the game (default: 10)
traitor_count: Number of traitors among the agents (default: 3)
model: Model name to use (default: “deepseek-chat”)
seed: Random seed for reproducibility (default: None)
client_type: Type of client to use (“openai”, “hf”, “mlx”) (default: “openai”)
provider: Provider for the client (default: None)
experiment_name: Optional name for the experiment (default: None)

Supported LLM Providers

TheTraitors supports multiple LLM providers:

OpenAI: Using the OpenAI API (GPT models)
Deepseek: Using Deepseek’s API
Together AI: Using Together AI’s API
Hugging Face: Using Hugging Face’s Inference API
MLX: Using local MLX models for Mac with Apple Silicon

Viewing Results

After running a game, results are saved in the results directory:

history.txt: Complete game transcript
votes.csv: Record of all votes and eliminations
metrics.txt: Game metrics and statistics
config.yaml: Game configuration
Agent-specific logs in subdirectories

The results are organized in a structured way: results/{experiment_name}/{model}/run-{number}/