API Reference

This section provides a detailed reference for the key classes and functions in TheTraitors.

TraitorsGame

The main game engine that manages the simulation.

class TraitorsGame:
    def __init__(
        self,
        config,
        agent_count=10,
        traitor_count=3,
        model="deepseek-chat",
        seed=None,
        client_type="openai",
        provider=None,
        experiment_name=None
    ):
        """
        Initialize the Traitors Game.

        Args:
            config: Configuration dictionary
            agent_count: Default number of total agents in the game
            traitor_count: Default number of traitors among the agents
            model: Default model name to use
            seed: Random seed for reproducibility
            client_type: Default type of client to use ("openai", "hf", "mlx")
            provider: Default provider for the client
            experiment_name: Optional name for the experiment
        """

Key Methods

def create_agents(self, agent_count, traitor_count):
    """
    Initialize agents with unique roles and traits from configuration.
    Returns a list of Agent instances.
    """

def introduction_phase(self):
    """
    Run the introduction phase where agents share their background traits.
    """

def discussion_phase(self):
    """
    Run a discussion phase where agents communicate and discuss who to vote out.
    """

def voting_phase(self):
    """
    Run a voting phase where agents vote to eliminate a suspected traitor.
    """

def traitor_discussion_phase(self):
    """
    Run a private discussion among traitor agents to decide who to eliminate.
    """

def traitor_elimination_phase(self, traitors, active_faithfuls):
    """
    Execute the traitor elimination decision.
    """

def check_win_conditions(self):
    """
    Check if the game has ended and determine the winner.
    Returns the winner ("Faithfuls", "Traitors") or None if game continues.
    """

def run(self):
    """
    Execute the main game loop until win conditions are met.
    """

def post_game_analysis(self):
    """
    Compute and save game metrics after the game has completed.
    """

Agent

The Agent class represents a player in the game.

class Agent:
    def __init__(
        self, agent_id, role, model, results_dir, llm_client=None, traits=None
    ):
        """
        Initialize an Agent.

        Args:
            agent_id: Unique identifier for the agent
            role: Either "Traitor" or "Faithful"
            model: The LLM model to use for this agent
            results_dir: Directory to save agent outputs
            llm_client: The LLM client to use for this agent
            traits: Optional dictionary of agent traits (age, profession, etc.)
        """

Key Methods

def set_llm_client(self, llm_client):
    """
    Set the LLM client for this agent.
    """

def call_llm(self, user_prompt):
    """
    Call the LLM client to generate a response based on system and user prompts.
    """

def set_fellow_traitors(self, traitor_ids):
    """
    Provide a list of fellow traitor IDs to this agent (only for traitors).
    """

def add_to_memory(self, content, section=None):
    """
    Add content to the agent's structured memory system with categorization.
    """

def get_formatted_memory(self):
    """
    Format the structured memory into a string for the LLM prompt.
    """

def is_traitor(self):
    """
    Return True if the agent is a traitor, False otherwise.
    """

def is_faithful(self):
    """
    Return True if the agent is faithful, False otherwise.
    """

def is_active(self):
    """
    Check if the agent is still active in the game.
    """

def is_eliminated(self):
    """
    Return True if the agent has been eliminated, False otherwise.
    """

def eliminate(self):
    """
    Mark the agent as eliminated.
    """

def extract_dialogue(self, full_response):
    """
    Extract dialogue from between triple dashes in the response.
    """

def to_dict(self):
    """
    Convert the agent to a dictionary representation.
    """

@classmethod
def from_dict(cls, data, results_dir, llm_client=None):
    """
    Create an Agent instance from a dictionary.
    """

LLM Clients

The framework includes several LLM client implementations for different providers.

LLMClient Base Class

class LLMClient(ABC):
    def __init__(self, model):
        """
        Initialize the LLM client.

        Args:
            model: The model name to use for API calls
        """

    @abstractmethod
    def call(self, system_message, user_message):
        """
        Call the LLM API with the given messages.

        Args:
            system_message: The system message to send
            user_message: The user message to send

        Returns:
            The LLM's response text
        """

LLMClientFactory

class LLMClientFactory:
    @staticmethod
    def create_client(client_type, model, provider=None):
        """
        Create and return an LLM client based on the specified type.

        Args:
            client_type: Type of client ("openai", "hf", "mlx")
            model: Model name to use
            provider: Provider name (for compatible APIs)

        Returns:
            An instance of an LLMClient implementation
        """

OpenAIClient

class OpenAIClient(LLMClient):
    def __init__(self, model, api_key, base_url=None):
        """
        Initialize an OpenAI-compatible client.

        Args:
            model: Model name to use
            api_key: The API key for authentication
            base_url: Optional base URL for the API (for compatible providers)
        """

    def call(self, system_message, user_message):
        """
        Call the OpenAI-compatible API with the given messages.

        Args:
            system_message: The system message to send
            user_message: The user message to send

        Returns:
            The generated text response
        """

HuggingFaceClient

class HuggingFaceClient(LLMClient):
    def __init__(self, model, provider=None, api_key=None):
        """
        Initialize a Hugging Face Inference API client.

        Args:
            model: The model name to use
            provider: Optional provider name (e.g., 'together')
            api_key: API key for authentication
        """

    def call(self, system_message, user_message):
        """
        Call the Hugging Face API with the given messages.

        Args:
            system_message: The system message to send
            user_message: The user message to send

        Returns:
            The generated text response
        """

MLXClient

class MLXClient(LLMClient):
    def __init__(self, model):
        """
        Initialize an MLX-based client for local model inference.

        Args:
            model: The MLX-compatible model name to load
        """

    def call(self, system_message, user_message):
        """
        Generate a response using a local MLX model.

        Args:
            system_message: The system message to send
            user_message: The user message to send

        Returns:
            The generated text response
        """

PromptManager

class PromptManager:
    @staticmethod
    def get_system_prompt(agent, memory_content):
        """
        Get the system prompt for an agent based on their role and memory.

        Args:
            agent: The agent instance
            memory_content: The formatted memory content

        Returns:
            The constructed system prompt
        """

Utility Functions

TheTraitors includes several utility functions for configuration management and metrics computation.

Configuration

def load_config(config_path):
    """
    Load a YAML configuration file.

    Args:
        config_path: Path to the YAML configuration file

    Returns:
        A dictionary containing the configuration
    """

def merge_config_with_args(config, args):
    """
    Merge command line arguments with a configuration dictionary.

    Args:
        config: The base configuration dictionary
        args: Parsed command line arguments

    Returns:
        The merged configuration dictionary
    """

Metrics

def compute_traitors_game_metrics(csv_file):
    """
    Compute game metrics from a votes CSV file.

    Args:
        csv_file: Path to the votes CSV file

    Returns:
        A dictionary of computed metrics
    """