haive.games.risk.agent

Advanced Risk agent implementation for strategic world domination gameplay.

This module provides a sophisticated RiskAgent class that uses AI-powered strategic reasoning to play the classic Risk board game. The agent analyzes territorial control, army positioning, continental bonuses, and diplomatic opportunities to make optimal decisions in complex multi-player scenarios.

The agent supports different strategic approaches (aggressive expansion, defensive fortification, balanced gameplay) and maintains detailed analysis history for learning and adaptation. It integrates with the broader Haive framework for LLM-powered decision making and strategic evaluation.

Examples

Creating a basic Risk agent:

agent = RiskAgent(
    name="General_Patton",
    strategy="aggressive",
    risk_tolerance=0.8
)

Setting up an agent with game state:

agent = RiskAgent(
    name="Strategic_AI",
    state=current_risk_state,
    strategy="balanced",
    risk_tolerance=0.6,
    diplomatic_stance="neutral"
)

Getting strategic analysis:

analysis = agent.analyze_position()
print(f"Territory control: {analysis.controlled_territories}")
print(f"Recommended move: {analysis.recommended_move.move_type}")

Making moves:

move = agent.get_move()
if move.move_type == MoveType.ATTACK:
    print(f"Attacking {move.to_territory} from {move.from_territory}")
elif move.move_type == MoveType.PLACE_ARMIES:
    print(f"Placing {move.armies} armies in {move.to_territory}")

Note

The agent maintains detailed analysis history for learning and strategic adaptation. Full LLM integration enables sophisticated reasoning about territorial strategy, army management, and diplomatic considerations.

Classes

RiskAgent

Advanced AI agent for strategic Risk gameplay with sophisticated decision-making.

Module Contents

class haive.games.risk.agent.RiskAgent(/, **data)

Bases: pydantic.BaseModel

Advanced AI agent for strategic Risk gameplay with sophisticated decision-making.

This agent employs multi-layered strategic analysis to excel at the classic Risk board game, combining territorial evaluation, military logistics, continental strategy, and diplomatic considerations. It adapts its approach based on game state, opponent behavior, and strategic objectives.

The agent supports various strategic personalities and maintains comprehensive analysis history for learning and adaptation. It integrates with LLM systems for complex reasoning about world domination strategy, resource allocation, and tactical decision-making.

Parameters:

data (Any)

name

Unique identifier and display name for the agent. Used for game tracking and strategic identification.

Type:

str

state

Current game state containing board position, army distributions, territorial control, and game phase information.

Type:

Optional[RiskState]

strategy

Strategic approach determining decision-making priorities. Options: “aggressive” (expansion-focused), “defensive” (consolidation), “balanced” (opportunistic), “diplomatic” (alliance-building).

Type:

str

risk_tolerance

Willingness to take risks in attacks and expansion. Range 0.0-1.0, where higher values favor bold moves over safe plays.

Type:

float

diplomatic_stance

Approach to other players and alliance-building. Options: “aggressive” (hostile), “neutral” (independent), “cooperative”.

Type:

str

analysis_history

Complete history of strategic analyses. Used for learning, pattern recognition, and strategic adaptation.

Type:

List[RiskAnalysis]

preferred_continents

Priority continents for expansion focus. Agent will prioritize gaining control of these continents for bonuses.

Type:

List[str]

minimum_armies_threshold

Minimum armies to maintain in territories. Defensive parameter to avoid leaving territories vulnerable.

Type:

int

Examples

Creating an aggressive expansion agent:

agent = RiskAgent(
    name="Conqueror_Alpha",
    strategy="aggressive",
    risk_tolerance=0.9,
    diplomatic_stance="aggressive",
    preferred_continents=["Asia", "Europe"],
    minimum_armies_threshold=2
)

Creating a defensive consolidation agent:

agent = RiskAgent(
    name="Fortress_Beta",
    strategy="defensive",
    risk_tolerance=0.3,
    diplomatic_stance="neutral",
    preferred_continents=["Australia", "South America"],
    minimum_armies_threshold=4
)

Setting up agent with game state:

agent = RiskAgent(
    name="Strategic_Gamma",
    state=current_game_state,
    strategy="balanced"
)

# Agent immediately begins analyzing position
analysis = agent.analyze_position()

Managing strategic adaptation:

# Agent learns from previous analyses
for analysis in agent.analysis_history[-5:]:
    if analysis.position_evaluation == "losing":
        agent.strategy = "defensive"  # Adapt to defensive play
        agent.risk_tolerance = max(0.2, agent.risk_tolerance - 0.1)

Note

The agent maintains state independence, allowing multiple agents to operate on different game states simultaneously. Strategic parameters can be adjusted dynamically for adaptive gameplay and experimental strategies.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

analyze_position()

Perform comprehensive strategic analysis of current game position.

Conducts multi-layered analysis of the game state including territorial control evaluation, army distribution assessment, continental bonus analysis, threat identification, and opportunity recognition. Generates strategic recommendations based on agent’s personality and current situation.

Returns:

Comprehensive analysis object containing: - Territory control metrics and army distribution - Continental bonus evaluation and expansion opportunities - Threat assessment and defensive priorities - Strategic recommendations with detailed reasoning - Position evaluation (winning/neutral/losing)

Return type:

RiskAnalysis

Raises:

ValueError – If agent doesn’t have a game state assigned for analysis.

Examples

Basic position analysis:

agent.state = current_game_state
analysis = agent.analyze_position()

print(f"Controlled territories: {analysis.controlled_territories}")
print(f"Total armies: {analysis.total_armies}")
print(f"Position: {analysis.position_evaluation}")

Strategic decision making:

analysis = agent.analyze_position()

if analysis.position_evaluation == "winning":
    # Aggressive expansion
    move = analysis.recommended_move
elif analysis.position_evaluation == "losing":
    # Defensive consolidation
    agent.strategy = "defensive"

Historical analysis tracking:

analysis = agent.analyze_position()
agent.analysis_history.append(analysis)

# Analyze trend over last 3 turns
recent_analyses = agent.analysis_history[-3:]
position_trend = [a.position_evaluation for a in recent_analyses]

Note

Analysis complexity scales with game state complexity. Full LLM integration provides sophisticated reasoning about strategic priorities, diplomatic considerations, and tactical execution.

get_move()

Determine optimal next move through strategic analysis and decision- making.

Performs comprehensive position analysis and selects the best move based on current game state, agent strategy, risk tolerance, and historical performance. Automatically stores analysis in history for learning and adaptation.

Returns:

Optimized move decision containing: - Move type (attack, place armies, fortify, end turn) - Source and target territories (if applicable) - Army quantities and strategic reasoning - Risk assessment and expected outcomes

Return type:

RiskMove

Raises:

ValueError – If agent doesn’t have a game state assigned.

Examples

Basic move generation:

agent.state = current_game_state
move = agent.get_move()

if move.move_type == MoveType.ATTACK:
    print(f"Attacking {move.to_territory} from {move.from_territory}")
    print(f"Using {move.attack_dice} dice against {move.defend_dice}")
elif move.move_type == MoveType.PLACE_ARMIES:
    print(f"Placing {move.armies} armies in {move.to_territory}")

Strategic adaptation:

move = agent.get_move()

# Adapt strategy based on move success
if move.move_type == MoveType.ATTACK and move.success_probability < 0.4:
    agent.risk_tolerance = max(0.1, agent.risk_tolerance - 0.1)

Decision tracking:

move = agent.get_move()

# Analysis automatically stored in history
latest_analysis = agent.analysis_history[-1]
print(f"Decision reasoning: {latest_analysis.explanation}")

Note

Move selection considers multiple factors including territorial security, expansion opportunities, continental bonuses, threat mitigation, and long-term strategic positioning.

classmethod validate_diplomatic_stance(v)

Validate diplomatic stance is supported.

Parameters:

v (str) – Diplomatic stance to validate.

Returns:

Validated diplomatic stance string.

Return type:

str

Raises:

ValueError – If diplomatic stance is not supported.

classmethod validate_strategy(v)

Validate strategic approach is supported.

Parameters:

v (str) – Strategy to validate.

Returns:

Validated strategy string.

Return type:

str

Raises:

ValueError – If strategy is not supported.

property analysis_summary: dict[str, int | float | str]

Get summary statistics from analysis history.

Returns:

Summary containing: - total_analyses: Number of analyses performed - avg_territories: Average territories controlled - avg_armies: Average total armies - most_common_evaluation: Most frequent position evaluation - strategic_trend: Overall strategic effectiveness trend

Return type:

Dict[str, Union[int, float, str]]

property strategic_effectiveness: float

Calculate strategic effectiveness based on analysis history.

Returns:

Effectiveness score from 0.0 to 1.0 based on position improvements.

Return type:

float

Examples

Tracking agent performance:

effectiveness = agent.strategic_effectiveness
if effectiveness > 0.7:
    print("Agent performing well")
elif effectiveness < 0.3:
    print("Agent may need strategy adjustment")