haive.games.debate.agent¶

Debate Agent implementation for structured debate facilitation.

This module provides a comprehensive debate agent that facilitates various types of structured debates including parliamentary, Oxford-style, and Lincoln-Douglas formats. The agent manages participant turns, phase transitions, moderation, and evaluation throughout the debate process.

The DebateAgent uses a multi-phase workflow system with configurable timing, participant roles, and debate formats. It supports AI-powered participants, human participants, and hybrid debates with sophisticated state management.

Examples

Creating a basic debate agent:

config = DebateAgentConfig(
    debate_format="parliamentary",
    max_statements=20,
    time_limit=1800,
    participant_roles={"player_1": "pro", "player_2": "con"},
    moderator_role=True
)
agent = DebateAgent(config)

Running a debate:

initial_state = {
    "topic": {
        "title": "AI Should Be Regulated by Government",
        "description": "Debate whether AI development requires regulation"
    },
    "participants": ["debater_1", "debater_2", "moderator"]
}
result = await agent.run(initial_state)

Configuring for Oxford-style debate:

config = DebateAgentConfig(
    debate_format="oxford",
    allow_interruptions=True,
    visualize=True,
    participant_roles={
        "pro_1": "pro", "pro_2": "pro",
        "con_1": "con", "con_2": "con",
        "moderator": "moderator"
    }
)

Note

The agent requires properly configured engines for different participant roles (debater, moderator, judge) and uses the DebateStateManager for all state transitions and rule enforcement.

Classes¶

DebateAgent

Intelligent agent for facilitating structured debates and discussions.

Module Contents¶

class haive.games.debate.agent.DebateAgent(config)[source]¶

Bases: haive.games.framework.multi_player.MultiPlayerGameAgent[haive.games.debate.config.DebateAgentConfig]

Intelligent agent for facilitating structured debates and discussions.

The DebateAgent orchestrates multi-participant debates with sophisticated phase management, role-based interaction, and configurable formats. It handles participant turn management, moderator functions, voting systems, and comprehensive state tracking throughout the debate lifecycle.

This agent supports various debate formats including parliamentary, Oxford-style, Lincoln-Douglas, and trial simulations. It can manage AI participants, human participants, or hybrid groups with appropriate context preparation and response extraction for each role.

state_manager¶

Manages all debate state transitions and rule enforcement throughout the debate process.

Type:: DebateStateManager

config¶

Configuration object containing debate format, timing, participant roles, and other behavioral settings.

Type:: DebateAgentConfig

Examples

Creating and configuring a debate agent:

config = DebateAgentConfig(
    debate_format="parliamentary",
    max_statements=15,
    time_limit=1200,
    allow_interruptions=False,
    moderator_role=True,
    participant_roles={
        "debater_1": "pro",
        "debater_2": "con",
        "moderator": "moderator"
    }
)
agent = DebateAgent(config)

Running a debate with custom topic:

debate_state = {
    "topic": {
        "title": "This House Believes Climate Action Should Prioritize Economy",
        "description": "Debate the balance between environmental protection and economic growth",
        "keywords": ["climate change", "economy", "environmental policy"]
    },
    "participants": ["pro_debater", "con_debater", "judge"]
}
result = await agent.arun(debate_state)

Handling trial format:

config = DebateAgentConfig(
    debate_format="trial",
    participant_roles={
        "prosecutor": "prosecutor",
        "defense": "defense",
        "judge": "judge",
        "witness_1": "witness"
    }
)
trial_agent = DebateAgent(config)

Note

The agent requires appropriate engines to be configured for different participant roles. Each role (debater, moderator, judge, etc.) should have corresponding engine configurations in the agent setup.

Initialize the debate agent with configuration.

Parameters:: config (DebateAgentConfig) – Configuration object containing debate format, timing rules, participant roles, and behavioral settings.

Note

The state_manager is set as a class reference and will be used to create instances for state management operations.

debate_setup(state)[source]¶

Handle the initial debate setup and configuration phase.

Configures participant roles, assigns moderator if specified, and advances the debate to the first active phase. This method applies configuration-based role assignments and sets up special roles like moderators before beginning the actual debate proceedings.

Parameters:: state (Dict[str, Any]) – Current state dictionary or DebateState object containing initialized participants and topic information.
Returns:: LangGraph command to transition to participant turn handling with updated state including role assignments and phase advancement.
Return type:: Command

Examples

Setting up debate with configured roles:

# With config.participant_roles = {
#     "player_1": "pro", "player_2": "con", "player_3": "moderator"
# }
command = agent.debate_setup(state)
# Results in participants assigned their configured roles

Setting up with automatic moderator:

# With config.moderator_role = True
command = agent.debate_setup(state)
# First player becomes moderator automatically

Note

Role assignment from config takes precedence over default assignments. If moderator_role is enabled, the first player becomes moderator. Always advances to opening statements phase after setup.

determine_next_step(state)[source]¶

Determine the next step in the debate workflow.

Analyzes the current debate state to decide whether to continue with participant turns, transition to the next phase, or end the debate. Uses phase-specific completion criteria to ensure proper debate flow and timing.

Parameters:: state (DebateState) – Current debate state including phase information, participant data, statements, and votes.
Returns:: Next workflow step identifier: - END: Debate has concluded or game status is not ongoing - “handle_phase_transition”: Current phase is complete, advance - “handle_participant_turn”: Continue with next participant
Return type:: str

Examples

Checking phase completion:

next_step = agent.determine_next_step(state)
if next_step == "handle_phase_transition":
    # All participants have given opening statements
elif next_step == "handle_participant_turn":
    # Continue with next speaker
elif next_step == END:
    # Debate has concluded

Note

Phase completion criteria: - Opening/Closing: All participants have made statements - Voting: All participants have cast votes - Other phases: Use turn-based progression

extract_move(response, role)[source]¶

Extract and structure move data from engine response.

Processes responses from AI engines or other participants, converting them into standardized move dictionaries that can be applied to the debate state. Handles different response types based on participant role and response format.

Parameters:

response (Any) – Raw response from the participant’s engine. Can be a Statement object, dictionary with structured data, or raw text.
role (str) – Role of the participant (affects response interpretation). Roles like “moderator” have special handling for actions.

Returns:

Structured move dictionary with standardized format.

For statements:

type: “statement”
content: Text content of the statement
statement_type: Category (opening, rebuttal, etc.)
target_id: Optional target participant
references: Supporting evidence or citations

For votes:

type: “vote”
vote_value: The vote decision
target_id: What/who is being voted on
reason: Explanation for the vote

For moderation:

type: “moderation”
action: Moderator action to take
note: Additional context or explanation

Return type:

Dict[str, Any]

Examples

Extracting statement from structured response:

statement = Statement(
    content="I believe regulation is necessary",
    statement_type="opening",
    speaker_id="debater_1"
)
move = agent.extract_move(statement, "debater")
# Returns: {
#     "type": "statement",
#     "content": "I believe regulation is necessary",
#     "statement_type": "opening"
# }

Extracting vote from dictionary:

response = {
    "vote_value": "pro",
    "target_id": "main_topic",
    "reason": "Stronger arguments"
}
move = agent.extract_move(response, "judge")
# Returns: {
#     "type": "vote",
#     "vote_value": "pro",
#     "target_id": "main_topic",
#     "reason": "Stronger arguments"
# }

Note

Fallback behavior treats any unrecognized response as a general statement to ensure debate flow continues even with unexpected responses.

get_player_role(state, player_id)[source]¶

Get the role of a specific player in the debate.

Retrieves the assigned role for a participant from the debate state. Roles determine how participants interact with the debate, what context they receive, and how their responses are processed.

Parameters:

state (DebateState) – Current debate state containing participant data.
player_id (str) – Unique identifier of the participant.

Returns:

The participant’s role (e.g., “debater”, “moderator”, “judge”, “prosecutor”, “defense”, “witness”). Returns “debater” if participant not found or no role assigned.

Return type:

str

Examples

Getting participant roles:

role = agent.get_player_role(state, "participant_1")
if role == "moderator":
    # Handle moderator-specific logic
elif role == "judge":
    # Handle judge-specific logic

Note

Default role is “debater” for unknown participants to ensure graceful handling of edge cases during debate flow.

handle_moderator_turn(state)[source]¶

Handle special processing for moderator participant turns.

Processes moderator-specific actions including debate guidance, phase advancement, time management, and procedural interventions. Moderators have special privileges and different context preparation compared to regular debaters.

Parameters:: state (DebateState) – Current debate state with moderator information and designated moderator ID.
Returns:: Updated state after moderator action, with potential phase changes, turn order adjustments, or procedural updates.
Return type:: DebateState

Examples

Moderator managing debate flow:

# Moderator might receive context about phase completion
# and decide to advance to next phase
updated_state = agent.handle_moderator_turn(state)

Moderator providing guidance:

# Moderator might add guidance statement and continue
# current phase with normal turn progression
updated_state = agent.handle_moderator_turn(state)

Note

If no moderator is designated or no moderator engine is available, the turn is skipped and normal turn progression continues. Moderator “advance_phase” actions trigger immediate phase transitions.

handle_participant_turn(state)[source]¶

Handle individual participant turns within the debate.

Manages the core debate loop by processing each participant’s turn, including context preparation, engine invocation, move extraction, and state updates. Handles special cases for different participant roles and manages error recovery to maintain debate flow.

Parameters:: state (Dict[str, Any]) – Current debate state containing participant information, statements, phase data, and turn order.
Returns:: LangGraph command for next step in debate flow. Can be: - END: If debate has concluded or game status is not ongoing - handle_participant_turn: Continue with next participant - handle_phase_transition: Advance to next debate phase
Return type:: Command

Examples

Normal participant turn flow:

command = agent.handle_participant_turn(state)
# Processes current speaker's turn, updates state,
# returns command for next participant or phase transition

Handling moderator turn:

# If current speaker is moderator, special handling applies
command = agent.handle_participant_turn(state)
# Moderator actions may advance phases or manage debate flow

Note

Automatically handles error recovery by skipping problematic turns. Engine selection is based on participant role and position. State visualization occurs if configured in agent settings.

handle_phase_transition(state)[source]¶

Handle transition between debate phases.

Parameters:: state (dict[str, Any])
Return type:: langgraph.types.Command

initialize_game(state)[source]¶

Initialize the debate with topic, participants, and configuration.

Sets up the initial debate state including topic validation, participant registration, role assignment, and format-specific configuration. This method handles both structured topic objects and simple string topics, creating a fully configured debate state ready for the setup phase.

Parameters:: state (Dict[str, Any]) – Initial state containing debate setup data. Expected keys: - topic (Union[str, Dict]): Debate topic as string or structured data - participants (Union[List[str], Dict]): List of participant IDs
Returns:: LangGraph command to transition to debate_setup phase with initialized state data.
Return type:: Command

Examples

Basic initialization with string topic:

state = {
    "topic": "Should AI be regulated?",
    "participants": ["debater_1", "debater_2"]
}
command = agent.initialize_game(state)

Initialization with structured topic:

state = {
    "topic": {
        "title": "This House Believes AI Needs Regulation",
        "description": "Comprehensive debate on AI governance",
        "keywords": ["artificial intelligence", "regulation", "policy"]
    },
    "participants": ["pro_debater", "con_debater", "moderator"]
}
command = agent.initialize_game(state)

Note

If no topic is provided, defaults to “AI Ethics in Society”. If no participants are provided, creates 4 default participants. Participant roles are assigned during the setup phase based on config.

prepare_move_context(state, player_id)[source]¶

Prepare contextual information for a participant’s move.

Generates role-specific context that provides participants with relevant information for making their next move. Context varies significantly based on participant role (debater, moderator, judge, etc.) and current debate phase, ensuring each participant receives appropriate information.

Parameters:

state (DebateState) – Current debate state with all participants, statements, votes, and phase information.
player_id (str) – Unique identifier of the participant whose turn it is.

Returns:

Role-specific context dictionary containing relevant information for the participant’s decision-making. Contents vary by role:

For debaters:

topic: Debate topic and description
debate_phase: Current phase of debate
position: Participant’s stance (pro/con/neutral)
recent_statements: Last 5 statements from all participants
your_statements: Participant’s previous statements
statement_type: Expected type for current phase

For moderators:

topic: Debate topic and description
debate_phase: Current phase of debate
participants: List of all participants with roles
recent_statements: Recent debate activity
current_speaker: Who is currently speaking
action_prompt: Suggested moderator action

For judges:

topic: Debate topic and description
debate_phase: Current phase of debate
all_statements: Complete statement history
key_arguments: Extracted pro/con arguments
action_prompt: Evaluation guidance

Return type:

Dict[str, Any]

Examples

Preparing context for debater:

context = agent.prepare_move_context(state, "debater_1")
# Returns: {
#     "topic": "AI Regulation Topic",
#     "position": "pro",
#     "recent_statements": "...",
#     "statement_type": "opening statement"
# }

Preparing context for moderator:

context = agent.prepare_move_context(state, "moderator")
# Returns: {
#     "topic": "AI Regulation Topic",
#     "participants": "...",
#     "action_prompt": "provide guidance..."
# }

Note

Returns empty dict if participant not found in state. Context is optimized for AI engines but human-readable for hybrid debates.

setup_workflow()[source]¶

Setup the debate workflow.

Return type:: None

visualize_state(state)[source]¶

Visualize the current debate state.

Parameters:: state (dict[str, Any])
Return type:: None