Agent Architecture

from agents.base import HintGiver, HintResponse
from game import Team
from typing import List

class HintGiver(ABC):
    def __init__(self, team: Team):
        self.team = team
    
    @abstractmethod
    def give_hint(
        self,
        my_words: List[str],          # Your team's unrevealed words
        opponent_words: List[str],     # Opponent's unrevealed words
        neutral_words: List[str],      # Neutral unrevealed words
        bomb_words: List[str],         # Bomb words (AVOID!)
        revealed_words: List[str],     # Already guessed words
        board_words: List[str]         # All words on board
    ) -> HintResponse:                 # Returns (word, count)
        pass

@dataclass
class HintResponse:
    word: str   # Single word hint (no spaces)
    count: int  # How many words it relates to (1-9)
    
    def validate(self) -> Tuple[bool, str]:
        # Validates hint format and constraints
        pass

from agents.base import Guesser
from game import Team, CardColor
from typing import List

class Guesser(ABC):
    def __init__(self, team: Team):
        self.team = team
    
    @abstractmethod
    def make_guesses(
        self,
        hint_word: str,               # The hint word
        hint_count: int,              # How many words it relates to
        board_words: List[str],       # All words on board
        revealed_words: List[str]     # Already revealed words
    ) -> List[str]:                   # Words to guess (ordered)
        pass
    
    def process_result(self, guessed_word: str, was_correct: bool, color: CardColor):
        # Optional: receive feedback after each guess
        pass
    
    def reset(self):
        # Optional: clear state between games
        pass

from agents.llm import BAMLHintGiver, BAMLGuesser, BAMLModel
from game import Team

# Create agents with specific models
hint_giver = BAMLHintGiver(Team.BLUE, model=BAMLModel.GPT4O_MINI)
guesser = BAMLGuesser(Team.RED, model=BAMLModel.CLAUDE_SONNET_45)

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

hint_giver = RandomHintGiver(Team.BLUE)
guesser = RandomGuesser(Team.BLUE)

from agents.llm import create_hint_giver, create_guesser
from game import Team

# Create by provider name
hint_giver = create_hint_giver("openai", "gpt-4o", Team.BLUE)
guesser = create_guesser("anthropic", team=Team.RED)  # Uses default model

# Provider/model mapping
hint_giver = create_hint_giver("google", "gemini-2.5-flash", Team.BLUE)

function GiveHint(
  team: string,
  my_words: string[],
  opponent_words: string[],
  neutral_words: string[],
  bomb_words: string[],
  revealed_words: string[]
) -> HintResponse {
  client GPT4oMini

  prompt #"
    You are playing Codenames as the {{ team | upper }} team's spymaster.

    YOUR GOAL: Give a one-word hint and a number to help your teammate.

    YOUR TEAM'S WORDS:
    {{ my_words | join(', ') }}

    OPPONENT'S WORDS (avoid):
    {{ opponent_words | join(', ') }}

    BOMB WORD(S) (NEVER hint at these):
    {{ bomb_words | join(', ') }}

    // Add your custom strategy instructions here
    STRATEGY:
    - Look for semantic clusters
    - Balance safety vs. aggressiveness
    - Avoid risky hints near the bomb

    {{ ctx.output_format }}
  "#
}

def process_result(self, guessed_word: str, was_correct: bool, color: CardColor):
    """Track guess results for analysis."""
    self.guess_history.append({
        'word': guessed_word,
        'correct': was_correct,
        'color': color.value
    })

def get_model_name(self) -> str:
    """Return the model identifier (e.g., 'GPT4oMini', 'ClaudeSonnet45')."""
    return self.model.value  # For BAML agents