Skip to main content

​
Overview

The random agents module provides basic implementations that make random decisions. These are primarily used for testing the game flow and validating game mechanics.
Random agents are for testing purposes only. They do not implement any strategic logic and will not perform well in actual games.

​
RandomHintGiver

Gives random hints for testing.

​
Constructor

​
team
Team
required
The team this agent represents (Team.RED or Team.BLUE)
from game import Team
from agents.random_agents import RandomHintGiver

hint_giver = RandomHintGiver(team=Team.BLUE)

​
Methods

​
give_hint()

Generate a random hint.
​
my_words
List[str]
required
List of unrevealed words belonging to this agent’s team
​
opponent_words
List[str]
required
List of unrevealed opponent words
​
neutral_words
List[str]
required
List of unrevealed neutral words
​
bomb_words
List[str]
required
List of bomb words (if not revealed)
​
revealed_words
List[str]
required
List of already revealed words
​
board_words
List[str]
required
All words on the board (for reference)
Returns: HintResponse - Contains random hint word and count Behavior:
  • If no team words remain, returns HintResponse(word="pass", count=1)
  • Otherwise, generates a hint word in format hint_{random_number} where random_number is 1-100
  • Count is random between 1 and min(3, number of team words remaining)
response = hint_giver.give_hint(
    my_words=["whale", "dolphin", "shark"],
    opponent_words=["cat", "dog"],
    neutral_words=["table", "chair"],
    bomb_words=["explosion"],
    revealed_words=[],
    board_words=["whale", "dolphin", "shark", "cat", "dog",
                 "table", "chair", "explosion"]
)
# Example output: HintResponse(word="hint_42", count=2)

​
RandomGuesser

Makes random guesses for testing.

​
Constructor

​
team
Team
required
The team this agent represents (Team.RED or Team.BLUE)
from game import Team
from agents.random_agents import RandomGuesser

guesser = RandomGuesser(team=Team.BLUE)

​
Methods

​
make_guesses()

Make random guesses.
​
hint_word
str
required
The hint word given by the hint giver
​
hint_count
int
required
Number of words the hint relates to
​
board_words
List[str]
required
All words on the board
​
revealed_words
List[str]
required
List of already revealed words
Returns: List[str] - List of randomly selected words to guess Behavior:
  • Filters out revealed words to get unrevealed words
  • If no unrevealed words remain, returns empty list
  • Otherwise, randomly samples up to hint_count words from unrevealed words
  • Does not consider the hint word or any strategy
guesses = guesser.make_guesses(
    hint_word="ocean",
    hint_count=3,
    board_words=["whale", "dolphin", "shark", "cat", "dog",
                 "table", "chair", "explosion"],
    revealed_words=["cat"]
)
# Example output: ["table", "whale", "dolphin"]
# (random selection, ignores hint word)

​
process_result()

Process guess results. Random agent does not learn from results.
​
guessed_word
str
required
The word that was guessed
​
was_correct
bool
required
Whether it was the team’s word
​
color
CardColor
required
The actual color of the word
Behavior: Does nothing (empty implementation) 
from game import CardColor

guesser.process_result(
    guessed_word="whale",
    was_correct=False,
    color=CardColor.NEUTRAL
)
# No action taken

​
Example: Testing Game Flow

from game import Game, Team
from agents.random_agents import RandomHintGiver, RandomGuesser

# Create random agents for both teams
blue_hint_giver = RandomHintGiver(team=Team.BLUE)
blue_guesser = RandomGuesser(team=Team.BLUE)
red_hint_giver = RandomHintGiver(team=Team.RED)
red_guesser = RandomGuesser(team=Team.RED)

# Create and play game
game = Game(
    blue_hint_giver=blue_hint_giver,
    blue_guesser=blue_guesser,
    red_hint_giver=red_hint_giver,
    red_guesser=red_guesser
)

result = game.play()
print(f"Winner: {result.winner.value}")
print(f"Turns: {result.num_turns}")
print(f"Reason: {result.end_reason}")

​
Example: Mixed Agent Testing

from game import Game, Team
from agents.random_agents import RandomHintGiver, RandomGuesser
from agents.llm.baml_agents import BAMLHintGiver, BAMLGuesser, BAMLModel

# Test LLM guesser with random hint giver
blue_hint_giver = RandomHintGiver(team=Team.BLUE)
blue_guesser = BAMLGuesser(team=Team.BLUE, model=BAMLModel.GPT4O_MINI)

red_hint_giver = RandomHintGiver(team=Team.RED)
red_guesser = RandomGuesser(team=Team.RED)

game = Game(
    blue_hint_giver=blue_hint_giver,
    blue_guesser=blue_guesser,
    red_hint_giver=red_hint_giver,
    red_guesser=red_guesser
)

result = game.play()
print(f"Testing LLM guesser with random hints")
print(f"Result: {result.winner.value} wins")

​
Use Cases

Game Flow Testing

Validate that the game engine correctly handles turns, reveals, and win conditions

Baseline Performance

Establish a baseline for comparing intelligent agent performance

Component Testing

Test individual components (hint giver or guesser) in isolation

Integration Testing

Verify that different agent types can work together correctly

​
Implementation Notes

The random agents use Python’s random module:
  • random.randint(1, 100) for hint word generation
  • random.randint(1, 3) for hint count
  • random.sample() for selecting guesses
Random agents have no memory or learning capability:
  • process_result() is a no-op
  • No state is maintained between calls
  • No reset() method needed (inherited default is sufficient)

Build docs developers (and LLMs) love

Get started for freeTalk to us