first commiiiiiiiiit

.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# macOS
+.DS_Store
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+log.json

README.md

@@ -1,13 +1,73 @@
----
-title: Codenames
-emoji: 🐨
-colorFrom: purple
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.6.0
-app_file: app.py
-pinned: false
-short_description: Playing codenames with LLMs
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Codenames LLM Challenge
+
+A Python framework for students to implement guesser bots for Codenames. The LLM acts as spymaster using embeddings.
+
+## Game Rules
+
+**Challenge Mode (Single Team):**
+- Goal: Guess all RED words in minimum rounds
+- Board: 25 words total (9 RED, 8 BLUE, 8 ASSASSIN)
+- Each round: LLM spymaster gives a clue + number
+- Guesser makes up to (number + 1) guesses
+- Round ends if: BLUE word revealed, max guesses reached, or guesser stops
+- Game ends: WIN if all RED found, LOSE if ASSASSIN revealed
+
+## Setup
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+
+**Dictionary:** Fixed list of 420 Codenames words. Clues and board words must be from this dictionary (case-insensitive).
+
+**Pre-build Embedding Cache (Recommended):**
+
+```bash
+python -m codenames.cli init-cache
+```
+
+Downloads the embedding model and computes vectors for all 420 words (~30 seconds). Cached for reuse.
+
+## Test Your Guesser
+
+Create a Python file with a `guesser` function:
+
+```python
+# my_guesser.py
+def guesser(clue: str, board_state: list[str]) -> str | None:
+    """
+    Args:
+        clue: The spymaster's one-word clue (from dictionary)
+        board_state: List of unrevealed words on the board
+    
+    Returns:
+        A word to guess from board_state, or None to stop the round
+    """
+    # Your embedding-based or heuristic logic here
+    return board_state[0]  # Simple example: always guess first word
+```
+
+Run against LLM spymaster:
+
+```bash
+python -m codenames.cli challenge my_guesser.py --seed 42 --output log.json
+```
+
+**Options:**
+- `--seed`: Random seed for reproducible boards
+- `--model`: Embedding model (default: `sentence-transformers/all-MiniLM-L6-v2`)
+- `--max-rounds`: Maximum rounds before timeout (default: 10)
+- `--output`: Save JSON log with board state, clues, guesses, and result
+
+## Log Format
+
+The JSON output contains:
+- `seed`: Random seed used
+- `board_words`: All 25 words on the board
+- `board_roles`: Role for each word (RED/BLUE/ASSASSIN)
+- `rounds`: Array of rounds with clue, number, and guesses
+- `final_state`: Win/loss status and rounds taken
+
+Use this data to analyze performance or train ML models.

app.py

@@ -0,0 +1,139 @@
+import gradio as gr
+
+INTRO_MD = """
+# 🕵️ Codenames LLM Challenge
+
+Welcome! This is a coding challenge where you build a **guesser bot** for the board game
+[Codenames](https://en.wikipedia.org/wiki/Codenames_(board_game)).
+
+An LLM-powered **spymaster** will give you one-word clues. Your job is to write the
+**guesser** that picks the right words on the board.
+
+---
+
+## How the game works
+
+The board has **25 words** split into hidden roles:
+
+| Role | Count | Meaning |
+|------|-------|---------|
+| 🟥 RED | 9 | Your team's words — guess these! |
+| 🟦 BLUE | 8 | Opponent words — avoid these |
+| 💀 ASSASSIN | 8 | Instant loss if revealed |
+
+Each round:
+1. The **spymaster** gives a one-word clue + a number (e.g. `"ocean 3"`)
+2. Your **guesser** can make up to `number + 1` guesses
+3. A round ends when you reveal a BLUE word, reach the max guesses, or return `None`
+4. The game ends when **all RED words are found** (win) or the **assassin is revealed** (loss)
+
+Your score is based on the number of rounds needed — fewer is better.
+
+---
+
+## Two steps to participate
+"""
+
+STEP1_MD = """
+## Step 1 — Clone the repository
+
+Open a terminal and run:
+
+```bash
+git clone https://huggingface.co/spaces/LLM-course/codenames
+cd codenames
+```
+
+Then set up the Python environment:
+
+```bash
+uv venv
+source .venv/bin/activate        # on Windows: .venv\\Scripts\\activate
+uv pip install -r requirements.txt
+```
+
+*(Optional but recommended)* Pre-build the embedding cache so runs are faster:
+
+```bash
+python -m codenames.cli init-cache
+```
+"""
+
+STEP2_MD = """
+## Step 2 — Implement `my_guesser.py`
+
+Open `my_guesser.py` and fill in the `guesser` function:
+
+```python
+# my_guesser.py
+from codenames.embedder import EmbeddingIndex
+from codenames.dictionary import load_dictionary
+
+_dictionary = load_dictionary()
+_index = EmbeddingIndex(_dictionary)
+
+def guesser(clue: str, board_state: list[str]) -> str | None:
+    \"\"\"
+    Args:
+        clue:        The spymaster's one-word clue (always from the 420-word dictionary)
+        board_state: List of unrevealed words currently on the board
+
+    Returns:
+        A word from board_state to guess, or None to stop guessing this round.
+    \"\"\"
+    # TODO: replace this with your smart logic!
+    return board_state[0]
+```
+
+### Tips
+- Use **embedding similarity** between the clue and board words — `_index.vector(word)`
+  returns a numpy vector for any dictionary word.
+- Return `None` when you're not confident: it's safer than hitting a BLUE or ASSASSIN word.
+- The clue is always a word from the shared 420-word dictionary (case-insensitive).
+
+### Test your guesser
+
+```bash
+python -m codenames.cli challenge my_guesser.py --seed 42 --output log.json
+```
+
+Options:
+- `--seed` — fix the board for reproducibility
+- `--max-rounds` — limit rounds (default 10)
+- `--output` — save a detailed JSON log with clues, guesses and the final result
+
+The JSON log is useful for inspecting mistakes and improving your strategy.
+"""
+
+RULES_MD = """
+## Full rules summary
+
+- Board: 25 words, 9 RED / 8 BLUE / 8 ASSASSIN (challenge / single-team mode)
+- Clue + number are given each round by the LLM spymaster
+- Guesser may guess up to `number + 1` times per round
+- Revealing a BLUE word ends the round immediately
+- Revealing the ASSASSIN ends the game immediately (loss)
+- **Goal:** reveal all 9 RED words in as few rounds as possible
+
+## Dictionary
+
+All clue words and board words are drawn from a **fixed list of 420 Codenames words**
+(see `codenames/data/codenames_dict.txt`). Your guesser receives words from this list
+and must return a word from the current `board_state`.
+"""
+
+with gr.Blocks(title="Codenames LLM Challenge") as demo:
+    gr.Markdown(INTRO_MD)
+
+    with gr.Tabs():
+        with gr.TabItem("🛠️ Step 1 — Clone"):
+            gr.Markdown(STEP1_MD)
+
+        with gr.TabItem("💡 Step 2 — Implement"):
+            gr.Markdown(STEP2_MD)
+
+        with gr.TabItem("📋 Full Rules"):
+            gr.Markdown(RULES_MD)
+
+if __name__ == "__main__":
+    demo.launch()

baseline.json

@@ -0,0 +1,169 @@
+{
+  "seed": 42,
+  "board_words": [
+    "Snowman",
+    "Carrot",
+    "Atlantis",
+    "Tube",
+    "France",
+    "Fan",
+    "Dwarf",
+    "Chocolate",
+    "Trip",
+    "Canada",
+    "Stock",
+    "Pool",
+    "Bridge",
+    "Row",
+    "Mercury",
+    "Ball",
+    "Back",
+    "Buffalo",
+    "Drill",
+    "England",
+    "Penguin",
+    "Scientist",
+    "Australia",
+    "Pyramid",
+    "Degree"
+  ],
+  "board_roles": [
+    "ASSASSIN",
+    "ASSASSIN",
+    "ASSASSIN",
+    "BLUE",
+    "ASSASSIN",
+    "BLUE",
+    "BLUE",
+    "RED",
+    "BLUE",
+    "RED",
+    "RED",
+    "RED",
+    "BLUE",
+    "RED",
+    "BLUE",
+    "RED",
+    "RED",
+    "RED",
+    "BLUE",
+    "RED",
+    "BLUE",
+    "ASSASSIN",
+    "ASSASSIN",
+    "ASSASSIN",
+    "ASSASSIN"
+  ],
+  "rounds": [
+    {
+      "round": 1,
+      "clue": "bat",
+      "number": 3,
+      "guesses": [
+        {
+          "word": "Ball",
+          "role": "RED"
+        },
+        {
+          "word": "Pool",
+          "role": "RED"
+        },
+        {
+          "word": "Drill",
+          "role": "BLUE"
+        }
+      ]
+    },
+    {
+      "round": 2,
+      "clue": "bark",
+      "number": 3,
+      "guesses": [
+        {
+          "word": "Buffalo",
+          "role": "RED"
+        },
+        {
+          "word": "Chocolate",
+          "role": "RED"
+        },
+        {
+          "word": "Back",
+          "role": "RED"
+        },
+        {
+          "word": "Bridge",
+          "role": "BLUE"
+        }
+      ]
+    },
+    {
+      "round": 3,
+      "clue": "mail",
+      "number": 1,
+      "guesses": [
+        {
+          "word": "Stock",
+          "role": "RED"
+        },
+        {
+          "word": "Canada",
+          "role": "RED"
+        }
+      ]
+    },
+    {
+      "round": 4,
+      "clue": "jam",
+      "number": 1,
+      "guesses": [
+        {
+          "word": "Row",
+          "role": "RED"
+        },
+        {
+          "word": "Trip",
+          "role": "BLUE"
+        }
+      ]
+    },
+    {
+      "round": 5,
+      "clue": "well",
+      "number": 1,
+      "guesses": [
+        {
+          "word": "Fan",
+          "role": "BLUE"
+        }
+      ]
+    },
+    {
+      "round": 6,
+      "clue": "boot",
+      "number": 1,
+      "guesses": [
+        {
+          "word": "Tube",
+          "role": "BLUE"
+        }
+      ]
+    },
+    {
+      "round": 7,
+      "clue": "boot",
+      "number": 1,
+      "guesses": [
+        {
+          "word": "Scientist",
+          "role": "ASSASSIN"
+        }
+      ]
+    }
+  ],
+  "final_state": {
+    "won": false,
+    "lost": true,
+    "rounds_taken": 7
+  }
+}

codenames/__init__.py

@@ -0,0 +1,8 @@
+__all__ = [
+    "models",
+    "dictionary",
+    "embedder",
+    "master",
+    "challenge",
+    "challenge_runner",
+]

codenames/challenge.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .models import Role, Card
+
+
+@dataclass
+class ChallengeBoard:
+    """Single-team challenge: RED team vs (BLUE + ASSASSIN). No neutrals."""
+
+    cards: List[Card] = field(default_factory=list)
+    index_by_word: dict = field(default_factory=dict)
+
+    @staticmethod
+    def create(words: List[str], rng: random.Random) -> "ChallengeBoard":
+        """Create a board with RED, BLUE, ASSASSIN roles (no NEUTRAL)."""
+        if len(words) != 25:
+            raise ValueError("Challenge board must have exactly 25 words")
+        
+        # 8 RED, 8 BLUE, 1 ASSASSIN (9 remaining would need adjustment)
+        # Standard: 9 RED, 8 BLUE, 8 ASSASSIN? Let's use 9 RED, 8 BLUE, 8 ASSASSIN
+        roles = [Role.RED] * 9 + [Role.BLUE] * 8 + [Role.ASSASSIN] * 8
+        rng.shuffle(roles)
+        
+        cards = [Card(word=w, role=roles[i]) for i, w in enumerate(words)]
+        board = ChallengeBoard(cards=cards)
+        board.index_by_word = {c.word.lower(): i for i, c in enumerate(cards)}
+        return board
+
+    def get_card(self, word: str) -> Optional[Card]:
+        idx = self.index_by_word.get(word.lower())
+        return self.cards[idx] if idx is not None else None
+
+    def reveal(self, word: str) -> Optional[Role]:
+        card = self.get_card(word)
+        if card is None or card.revealed:
+            return None
+        card.revealed = True
+        return card.role
+
+    def red_remaining(self) -> int:
+        return sum(1 for c in self.cards if c.role == Role.RED and not c.revealed)
+
+    def all_red_revealed(self) -> bool:
+        return all(c.revealed for c in self.cards if c.role == Role.RED)
+
+    def as_grid(self) -> List[List[Card]]:
+        return [self.cards[i : i + 5] for i in range(0, 25, 5)]
+
+    def board_view(self, show_key: bool = False) -> List[List[str]]:
+        grid = []
+        for row in self.as_grid():
+            display_row = []
+            for c in row:
+                label = c.word
+                if c.revealed:
+                    label = f"[{label}]"
+                elif show_key:
+                    label = f"{label}:{c.role.value}"
+                display_row.append(label)
+            grid.append(display_row)
+        return grid
+
+
+@dataclass
+class ChallengeGame:
+    """Single-team challenge: guess all RED words while avoiding BLUE and ASSASSIN."""
+
+    dictionary: List[str]
+    seed: Optional[int] = None
+    rng: random.Random = field(init=False)
+    board: ChallengeBoard = field(init=False)
+    dictionary_set: set = field(init=False)
+
+    # Turn state
+    clue_word: Optional[str] = None
+    clue_number: Optional[int] = None
+    guesses_made: int = 0
+    max_guesses_this_turn: int = 0
+    round_number: int = 1
+
+    # Outcome
+    won: bool = False
+    lost: bool = False
+
+    def __post_init__(self):
+        self.rng = random.Random(self.seed)
+        self.dictionary_set = {w.lower() for w in self.dictionary}
+        if len(self.dictionary) < 25:
+            raise ValueError("Dictionary must contain at least 25 words")
+        words = self.rng.sample(self.dictionary, 25)
+        self.board = ChallengeBoard.create(words, self.rng)
+
+    def give_clue(self, clue_word: str, number: int):
+        if self.won or self.lost:
+            raise RuntimeError("Game already over")
+        if number < 0:
+            raise ValueError("Number must be non-negative")
+        if clue_word.lower() not in self.dictionary_set:
+            raise ValueError("Clue must be a word from the dictionary")
+        if clue_word.lower() in self.board.index_by_word:
+            raise ValueError("Clue cannot be a word that is on the board")
+        
+        self.clue_word = clue_word
+        self.clue_number = number
+        self.max_guesses_this_turn = number + 1
+        self.guesses_made = 0
+
+    def guess(self, word: str) -> tuple[Optional[Role], str]:
+        if self.won or self.lost:
+            return None, "Game over"
+        if self.clue_word is None:
+            return None, "No clue given yet"
+        
+        card = self.board.get_card(word)
+        if card is None:
+            return None, f"Word '{word}' is not on the board. Try again."
+        if card.revealed:
+            return None, f"Word '{word}' is already revealed. Try again."
+
+        role = self.board.reveal(word)
+        self.guesses_made += 1
+
+        # Check outcomes
+        if role == Role.ASSASSIN:
+            self.lost = True
+            return role, "Revealed ASSASSIN. You lose."
+
+        if role == Role.BLUE:
+            self.end_round()
+            return role, "Revealed BLUE. Round ends."
+
+        # Revealed RED
+        if self.board.all_red_revealed():
+            self.won = True
+            return role, f"Revealed RED. All RED words found! You win in {self.round_number} round(s)."
+
+        # Can continue if guesses remain
+        if self.guesses_made >= self.max_guesses_this_turn:
+            self.end_round()
+            return role, f"Revealed RED. Max guesses reached. Round ends."
+
+        return role, f"Revealed RED. You may guess again or 'stop'."
+
+    def end_round(self):
+        self.clue_word = None
+        self.clue_number = None
+        self.guesses_made = 0
+        self.max_guesses_this_turn = 0
+        self.round_number += 1
+
+    def status_text(self) -> str:
+        if self.won:
+            return f"🏆 YOU WIN in {self.round_number} round(s)! 🏆"
+        if self.lost:
+            return "💀 YOU LOSE - Assassin revealed. 💀"
+
+        lines = [
+            f"🎯 SPYMASTER (Round {self.round_number})",
+            f"RED remaining: {self.board.red_remaining()}",
+        ]
+
+        if self.clue_word is not None:
+            lines.append(f"Clue: {self.clue_word.upper()} ({self.clue_number})")
+            lines.append(f"{self.max_guesses_this_turn - self.guesses_made} guesses left")
+        
+        return "\n".join(lines)

codenames/challenge_runner.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .challenge import ChallengeGame
+from .master import MasterPlayer
+
+
+def play_challenge(
+    guesser_fn: Callable,
+    dictionary: list[str],
+    seed: Optional[int] = None,
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    max_rounds: int = 10,
+    verbose: bool = True,
+) -> dict:
+    """
+    Play a challenge game with LLM spymaster and student guesser code.
+    
+    The guesser_fn should have signature:
+        guesser_fn(clue: str, board_state: list[str]) -> Optional[str]
+    where board_state is a list of unrevealed word strings.
+    """
+    game = ChallengeGame(dictionary=dictionary, seed=seed)
+    master = MasterPlayer(dictionary, model_name=model_name)
+
+    log = {
+        "seed": seed,
+        "board_words": [c.word for c in game.board.cards],
+        "board_roles": [c.role.value for c in game.board.cards],
+        "rounds": [],
+    }
+
+    while not game.won and not game.lost and game.round_number <= max_rounds:
+        if verbose:
+            print(f"\n{game.status_text()}")
+
+        # Spymaster suggests clue
+        suggestion = master.suggest_clue(game)
+        if suggestion is None:
+            if verbose:
+                print("No clue available.")
+            break
+
+        game.give_clue(suggestion.clue, suggestion.number)
+        if verbose:
+            print(f"Clue: {suggestion.clue} ({suggestion.number})")
+
+        round_log = {
+            "round": game.round_number,
+            "clue": suggestion.clue,
+            "number": suggestion.number,
+            "guesses": [],
+        }
+
+        # Guesser phase with student code
+        while not game.won and not game.lost and game.clue_word is not None:
+            unrevealed = [c.word for c in game.board.cards if not c.revealed]
+            try:
+                guess_word = guesser_fn(game.clue_word, unrevealed)
+            except Exception as e:
+                if verbose:
+                    print(f"Guesser error: {e}")
+                break
+
+            if guess_word is None:
+                break
+
+            role, msg = game.guess(guess_word)
+            if verbose:
+                print(f"  Guess: {guess_word} -> {msg}")
+
+            if role is not None:
+                round_log["guesses"].append({"word": guess_word, "role": role.value})
+
+        log["rounds"].append(round_log)
+
+    log["final_state"] = {
+        "won": game.won,
+        "lost": game.lost,
+        "rounds_taken": game.round_number - 1 if game.won else game.round_number,
+    }
+
+    if verbose:
+        print(f"\nFinal: {game.status_text()}")
+
+    return log

codenames/cli.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import argparse
+from typing import Optional
+
+from .dictionary import load_dictionary
+
+
+
+
+
+def cmd_init_cache(args):
+    """Pre-build embedding cache for the dictionary."""
+    from .embedder import load_or_build_embeddings
+    words = load_dictionary()
+    print(f"Pre-building cache for {len(words)} words with model: {args.model}")
+    cache = load_or_build_embeddings(words, model_name=args.model, rebuild=args.rebuild)
+    print(f"✓ Cache ready: {cache.vectors.shape}")
+
+
+
+
+
+def cmd_challenge(args):
+    """Play challenge mode with LLM spymaster and student guesser code."""
+    words = load_dictionary()
+    
+    # Import student code
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("student_guesser", args.guesser_code)
+    if spec is None or spec.loader is None:
+        print(f"Could not load {args.guesser_code}")
+        return
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    
+    if not hasattr(module, "guesser"):
+        print("Student code must define a 'guesser' function with signature: guesser(clue: str, board_state: list[str]) -> Optional[str]")
+        return
+    
+    from .challenge_runner import play_challenge
+    log = play_challenge(
+        module.guesser,
+        words,
+        seed=args.seed,
+        model_name=args.model,
+        max_rounds=args.max_rounds,
+        verbose=True,
+    )
+    
+    if args.output:
+        import json
+        with open(args.output, "w") as f:
+            json.dump(log, f, indent=2)
+        print(f"\nLog saved to {args.output}")
+
+
+def main(argv: Optional[list] = None):
+    parser = argparse.ArgumentParser(description="Codenames Challenge CLI")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_cache = sub.add_parser("init-cache", help="Pre-build embedding cache for dictionary")
+    p_cache.add_argument(
+        "--model",
+        type=str,
+        default="sentence-transformers/all-MiniLM-L6-v2",
+        help="SentenceTransformers model name",
+    )
+    p_cache.add_argument("--rebuild", action="store_true", help="Force rebuild cache even if it exists")
+    p_cache.set_defaults(func=cmd_init_cache)
+
+    p_challenge = sub.add_parser("challenge", help="Challenge mode: LLM spymaster + student guesser")
+    p_challenge.add_argument("guesser_code", help="Path to Python file with guesser() function")
+    p_challenge.add_argument("--seed", type=int, default=None, help="Random seed")
+    p_challenge.add_argument(
+        "--model",
+        type=str,
+        default="sentence-transformers/all-MiniLM-L6-v2",
+        help="SentenceTransformers model name",
+    )
+    p_challenge.add_argument("--max-rounds", type=int, default=10, help="Maximum rounds")
+    p_challenge.add_argument("--output", type=str, default=None, help="Save log to JSON file")
+    p_challenge.set_defaults(func=cmd_challenge)
+
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

codenames/data/codenames_dict.txt

@@ -0,0 +1,420 @@
+Africa
+Agent
+Air
+Alien
+Alps
+Amazon
+Ambulance
+America
+Angel
+Antarctica
+Apple
+Arm
+Atlantis
+Australia
+Aztec
+Back
+Ball
+Band
+Bank
+Bar
+Bark
+Bat
+Battery
+Beach
+Bear
+Beat
+Bed
+Beijing
+Bell
+Belt
+Berlin
+Bermuda
+Berry
+Bill
+Block
+Board
+Bolt
+Bomb
+Bond
+Boom
+Boot
+Bottle
+Bow
+Box
+Bridge
+Brush
+Buck
+Buffalo
+Bug
+Bugle
+Button
+Calf
+Canada
+Cap
+Capital
+Car
+Card
+Carrot
+Casino
+Cast
+Cat
+Cell
+Centaur
+Center
+Chair
+Change
+Charge
+Check
+Chest
+Chick
+China
+Chocolate
+Church
+Circle
+Cliff
+Cloak
+Club
+Code
+Cold
+Comic
+Compound
+Concert
+Conductor
+Contract
+Cook
+Copper
+Cotton
+Court
+Cover
+Crane
+Crash
+Cricket
+Cross
+Crown
+Cycle
+Czech
+Dance
+Date
+Day
+Death
+Deck
+Degree
+Diamond
+Dice
+Dinosaur
+Disease
+Doctor
+Dog
+Draft
+Dragon
+Dress
+Drill
+Drop
+Duck
+Dwarf
+Eagle
+Egypt
+Embassy
+Engine
+England
+Europe
+Eye
+Face
+Fair
+Fall
+Fan
+Fence
+Field
+Fighter
+Figure
+File
+Film
+Fire
+Fish
+Flute
+Fly
+Foot
+Force
+Forest
+Fork
+France
+Game
+Gas
+Genius
+Germany
+Ghost
+Giant
+Glass
+Glove
+Gold
+Grace
+Grass
+Greece
+Green
+Ground
+Ham
+Hand
+Hawk
+Head
+Heart
+Helicopter
+Himalayas
+Hole
+Hollywood
+Honey
+Hood
+Hook
+Horn
+Horse
+Horseshoe
+Hospital
+Hotel
+Ice
+Ice Cream
+India
+Iron
+Ivory
+Jack
+Jam
+Jet
+Jupiter
+Kangaroo
+Ketchup
+Key
+Kid
+King
+Kiwi
+Knife
+Knight
+Lab
+Lap
+Laser
+Lawyer
+Lead
+Leather
+Lemon
+Leprechaun
+Life
+Light
+Limousine
+Line
+Link
+Lion
+Litter
+Loch Ness
+Lock
+Log
+London
+Luck
+Mail
+Mammoth
+Maple
+Marble
+March
+Mass
+Match
+Mercury
+Mexico
+Microscope
+Millionaire
+Mine
+Mint
+Missile
+Model
+Mole
+Moon
+Moscow
+Mount
+Mouse
+Mouth
+Mug
+Nail
+Needle
+Net
+New York
+Night
+Ninja
+Note
+Novel
+Nurse
+Nut
+Octopus
+Oil
+Olive
+Olympus
+Opera
+Orange
+Organ
+Pain
+Palm
+Pan
+Pants
+Paper
+Parachute
+Park
+Part
+Pass
+Paste
+Penguin
+Phoenix
+Piano
+Pie
+Pilot
+Pin
+Pipe
+Pirate
+Pistol
+Pit
+Pitch
+Plane
+Plastic
+Plate
+Platypus
+Play
+Plot
+Point
+Poison
+Pole
+Police
+Pool
+Port
+Post
+Pound
+Press
+Princess
+Pumpkin
+Pupil
+Pyramid
+Queen
+Rabbit
+Racket
+Ray
+Revolution
+Ring
+Robin
+Robot
+Rock
+Rome
+Root
+Rose
+Roulette
+Round
+Row
+Ruler
+Satellite
+Saturn
+Scale
+School
+Scientist
+Scorpion
+Screen
+Scuba Diver
+Seal
+Server
+Shadow
+Shakespeare
+Shark
+Ship
+Shoe
+Shop
+Shot
+Sink
+Skyscraper
+Slip
+Slug
+Smuggler
+Snow
+Snowman
+Sock
+Soldier
+Soul
+Sound
+Space
+Spell
+Spider
+Spike
+Spine
+Spot
+Spring
+Spy
+Square
+Stadium
+Staff
+Star
+State
+Stick
+Stock
+Straw
+Stream
+Strike
+String
+Sub
+Suit
+Superhero
+Swing
+Switch
+Table
+Tablet
+Tag
+Tail
+Tap
+Teacher
+Telescope
+Temple
+Theater
+Thief
+Thumb
+Tick
+Tie
+Time
+Tokyo
+Tooth
+Torch
+Tower
+Track
+Train
+Triangle
+Trip
+Trunk
+Tube
+Turkey
+Undertaker
+Unicorn
+Vacuum
+Van
+Vet
+Wake
+Wall
+War
+Washer
+Washington
+Watch
+Water
+Wave
+Web
+Well
+Whale
+Whip
+Wind
+Witch
+Worm
+Yard
+Beard
+Pleasure
+Orgasm
+Volcano
+Eruption
+Burger
+Hot Dog
+Pizza
+Sausage
+Hands
+Cherry
+Tomato
+Pickle
+Sexy
+Cave
+Volley
+Mold
+Mould

codenames/dictionary.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+WORDS_DIR = Path(__file__).parent / "data"
+WORDS_FILE = WORDS_DIR / "codenames_dict.txt"
+
+
+def load_dictionary() -> List[str]:
+    if not WORDS_FILE.exists():
+        raise FileNotFoundError(f"Dictionary file not found at {WORDS_FILE}")
+    words: List[str] = []
+    with open(WORDS_FILE, "r", encoding="utf-8") as f:
+        for line in f:
+            w = line.strip()
+            if w:
+                words.append(w)
+    if len(words) < 100:
+        raise ValueError("Dictionary seems too small.")
+    return words

codenames/embedder.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from .dictionary import WORDS_DIR
+
+
+@dataclass
+class EmbeddingCache:
+    words: List[str]
+    vectors: np.ndarray  # shape (N, D), normalized
+
+
+def _cache_path(model_name: str) -> Path:
+    safe = model_name.replace("/", "_")
+    return WORDS_DIR / f"embeddings_{safe}.npz"
+
+
+def load_or_build_embeddings(
+    words: Sequence[str],
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    rebuild: bool = False,
+    batch_size: int = 64,
+) -> EmbeddingCache:
+    WORDS_DIR.mkdir(parents=True, exist_ok=True)
+    cache_file = _cache_path(model_name)
+    lower_words = [w.lower() for w in words]
+
+    if cache_file.exists() and not rebuild:
+        data = np.load(cache_file, allow_pickle=False)
+        cached_words = data["words"].tolist()
+        vectors = data["vectors"].astype(np.float32)
+        norms = np.linalg.norm(vectors, axis=1, keepdims=True)
+        norms = np.where(norms == 0, 1.0, norms)
+        vectors = vectors / norms
+        if cached_words == lower_words:
+            print(f"✓ Loaded cached embeddings for {len(lower_words)} words (model: {model_name})")
+            return EmbeddingCache(words=lower_words, vectors=vectors)
+        else:
+            print(f"⚠ Cache mismatch: expected {len(lower_words)} words, found {len(cached_words)}. Rebuilding...")
+
+    print(f"Building embeddings for {len(lower_words)} words with {model_name}...")
+    model = SentenceTransformer(model_name)
+    vectors = model.encode(
+        lower_words,
+        batch_size=batch_size,
+        normalize_embeddings=True,
+        convert_to_numpy=True,
+    ).astype(np.float32)
+    np.savez(cache_file, words=np.array(lower_words), vectors=vectors)
+    print(f"✓ Cache saved to {cache_file.name}")
+    return EmbeddingCache(words=lower_words, vectors=vectors)
+
+
+class EmbeddingIndex:
+    def __init__(
+        self,
+        words: Sequence[str],
+        model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+        rebuild: bool = False,
+    ) -> None:
+        self.cache = load_or_build_embeddings(words, model_name=model_name, rebuild=rebuild)
+        self.lookup: Dict[str, int] = {w: i for i, w in enumerate(self.cache.words)}
+
+    def vector(self, word: str) -> Optional[np.ndarray]:
+        idx = self.lookup.get(word.lower())
+        if idx is None:
+            return None
+        return self.cache.vectors[idx]
+
+    def vectors_for(self, words: Iterable[str]) -> List[np.ndarray]:
+        out: List[np.ndarray] = []
+        for w in words:
+            v = self.vector(w)
+            if v is not None:
+                out.append(v)
+        return out
+
+    @property
+    def all_words(self) -> List[str]:
+        return list(self.cache.words)

codenames/master.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from .embedder import EmbeddingIndex
+from .challenge import ChallengeGame
+from .models import Role
+
+
+@dataclass
+class ClueSuggestion:
+    clue: str
+    number: int
+    score: float
+    supports: List[Tuple[str, float]]
+    blockers: List[Tuple[str, float]]
+
+
+class MasterPlayer:
+    def __init__(
+        self,
+        dictionary: Sequence[str],
+        model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+        good_top_k: int = 3,
+        good_threshold: float = 0.32,
+        bad_weight: float = 1.2,
+        assassin_weight: float = 3.0,
+    ) -> None:
+        self.index = EmbeddingIndex(dictionary, model_name=model_name)
+        self.dictionary = [w.lower() for w in dictionary]
+        self.good_top_k = good_top_k
+        self.good_threshold = good_threshold
+        self.bad_weight = bad_weight
+        self.assassin_weight = assassin_weight
+
+    def suggest_clue(self, game: ChallengeGame) -> Optional[ClueSuggestion]:
+        good_words = [
+            c.word.lower()
+            for c in game.board.cards
+            if not c.revealed and c.role == Role.RED
+        ]
+        bad_words = [
+            c.word.lower()
+            for c in game.board.cards
+            if not c.revealed and (c.role == Role.BLUE or c.role == Role.ASSASSIN)
+        ]
+        assassin_words = [c.word.lower() for c in game.board.cards if c.role == Role.ASSASSIN and not c.revealed]
+
+        board_words = {c.word.lower() for c in game.board.cards}
+
+        good_vecs = self._vectors_for(good_words)
+        bad_vecs = self._vectors_for(bad_words)
+        assassin_vecs = self._vectors_for(assassin_words)
+
+        if not good_vecs:
+            return None
+
+        good_matrix = np.stack(good_vecs)
+        bad_matrix = np.stack(bad_vecs) if bad_vecs else None
+        assassin_matrix = np.stack(assassin_vecs) if assassin_vecs else None
+
+        best: Optional[ClueSuggestion] = None
+        for clue in self.dictionary:
+            if clue in board_words:
+                continue
+            vec = self.index.vector(clue)
+            if vec is None:
+                continue
+            norm = np.linalg.norm(vec)
+            if norm == 0 or not np.isfinite(norm):
+                continue
+            vec = vec / norm
+
+            with np.errstate(divide="ignore", over="ignore", invalid="ignore"):
+                good_sims = good_matrix @ vec
+                sorted_good_idx = np.argsort(-good_sims)
+                top_idx = sorted_good_idx[: self.good_top_k]
+                top_pairs = [(good_words[i], float(good_sims[i])) for i in top_idx]
+                good_score = float(np.sum([good_sims[i] for i in top_idx]))
+
+                bad_max = 0.0
+                bad_pairs: List[Tuple[str, float]] = []
+                if bad_matrix is not None:
+                    bad_sims = bad_matrix @ vec
+                    max_idx = int(np.argmax(bad_sims)) if bad_sims.size else 0
+                    bad_max = float(bad_sims[max_idx]) if bad_sims.size else 0.0
+                    bad_pairs = [(bad_words[max_idx], float(bad_max))]
+
+                assassin_max = 0.0
+                if assassin_matrix is not None:
+                    ass_sims = assassin_matrix @ vec
+                    assassin_max = float(np.max(ass_sims)) if ass_sims.size else 0.0
+
+            score = good_score - self.bad_weight * bad_max - self.assassin_weight * assassin_max
+
+            guessable = sum(1 for s in good_sims if s >= self.good_threshold)
+            number = max(1, min(self.good_top_k, guessable))
+
+            suggestion = ClueSuggestion(
+                clue=clue,
+                number=number,
+                score=score,
+                supports=top_pairs,
+                blockers=bad_pairs,
+            )
+            if best is None or suggestion.score > best.score:
+                best = suggestion
+        return best
+
+    def _vectors_for(self, words: Iterable[str]) -> List[np.ndarray]:
+        out: List[np.ndarray] = []
+        for w in words:
+            v = self.index.vector(w)
+            if v is not None:
+                out.append(v)
+        return out

codenames/models.py

@@ -0,0 +1,15 @@
+from enum import Enum
+from dataclasses import dataclass
+
+
+class Role(Enum):
+    RED = "RED"
+    BLUE = "BLUE"
+    ASSASSIN = "ASSASSIN"
+
+
+@dataclass
+class Card:
+    word: str
+    role: Role
+    revealed: bool = False

my_guesser.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from codenames.embedder import EmbeddingIndex
+from codenames.dictionary import load_dictionary
+
+_dictionary = load_dictionary()
+_index = EmbeddingIndex(_dictionary)
+
+
+def guesser(clue: str, board_state: list[str]) -> Optional[str]:
+    """
+    Given a clue word and list of unrevealed board words,
+    return a word.
+    """
+    return board_state[0]

requirements.txt

@@ -0,0 +1,4 @@
+wordfreq>=3.0
+numpy>=1.26
+sentence-transformers>=3.0
+colorama>=0.4.6