import logging import random from dataclasses import dataclass, field from json import JSONDecodeError from typing import Any from uuid import uuid4 from fastapi import FastAPI, WebSocket, WebSocketDisconnect logging.basicConfig( level=logging.INFO, format="%(asctime)s %(levelname)s [%(name)s] %(message)s", ) logger = logging.getLogger("wordle-space") EASY_WORDS = [ "ABOUT", "AFTER", "AGAIN", "BELOW", "COULD", "EVERY", "FIRST", "FOUND", "GREAT", "HOUSE", ] MEDIUM_WORDS = [ "ABOUT", "AFTER", "AGAIN", "ALONG", "AMONG", "BELOW", "COULD", "EVERY", "FIRST", "FOUND", "GREAT", "HOUSE", "LARGE", "MIGHT", "NEVER", "OTHER", "PLACE", "POINT", "POWER", "RIGHT", "SMALL", "SOUND", "STILL", "THEIR", "THERE", "THESE", "THINK", "UNDER", "WATER", "WHERE", "WHICH", "WORLD", "WOULD", "WRITE", "YOUNG", ] HARD_WORDS = sorted( set( MEDIUM_WORDS + [ "ALERT", "ALIEN", "ALIVE", "ANGLE", "ANGRY", "APPLY", "ARISE", "ARRAY", "ARROW", "AUDIO", "AWAKE", "AWARD", "AWARE", "BEACH", "BEARD", "BEAST", "BENCH", "BIRTH", "BLACK", "BLAME", "BLEND", "BLOCK", "BRAIN", "BRAVE", "BREAD", "BREAK", "BRICK", "BRING", "BROAD", "BROWN", "BUILD", "CARRY", "CAUSE", "CHAIN", "CHAIR", "CHEAP", "CHECK", "CHEST", "CHIEF", "CHILD", "CHOSE", "CIVIL", "CLASS", "CLEAN", "CLEAR", "CLIMB", "CLOCK", "CLOSE", "COACH", "COAST", "COURT", "COVER", "CRAZY", "CROWD", "CROWN", "DAILY", "DANCE", "DEALT", "DEATH", "DEPTH", "DOING", "DOUBT", "DOZEN", "DRAFT", "DRAMA", "DRAWN", "DREAM", "DRESS", "DRIVE", "EARTH", "ENJOY", "ENTER", "EQUAL", "ERROR", "EVENT", "FAITH", "FALSE", "FIELD", "FIGHT", "FINAL", "FLOOR", "FOCUS", "FORCE", "FRAME", "FRESH", "FRONT", "FRUIT", "GLASS", "GRACE", "GRADE", "GRAND", "GRANT", "GRASS", "GREEN", "GROUP", "GUARD", "GUIDE", "HAPPY", "HEART", "HORSE", "HOTEL", "HUMAN", "IDEAL", "IMAGE", "INDEX", "INNER", "ISSUE", "JOINT", "JUDGE", "KNIFE", "KNOCK", "KNOWN", "LABEL", "LASER", "LATER", "LAYER", "LEARN", "LIGHT", "LIMIT", "LOCAL", "LUCKY", "MAGIC", "MAJOR", "MATCH", "MAYBE", "METAL", "MODEL", "MONEY", "MOTOR", "MOUTH", "MUSIC", "NIGHT", "NORTH", "NOVEL", "NURSE", "OCEAN", "OFFER", "ORDER", "ORGAN", "PAINT", "PANEL", "PAPER", "PARTY", "PEACE", "PHONE", "PHOTO", "PIECE", "PILOT", "PITCH", "PLANE", "PLANT", "PRESS", "PRICE", "PRIDE", "PRIME", "PRINT", "PRIOR", "PRIZE", "PROOF", "PROUD", "QUEEN", "QUICK", "QUIET", "RADIO", "RAISE", "RANGE", "RAPID", "REACH", "READY", "REFER", "RELAX", "REPLY", "RIVER", "ROBIN", "ROUND", "ROUTE", "ROYAL", "RURAL", "SCALE", "SCENE", "SCOPE", "SCORE", "SENSE", "SERVE", "SHADE", "SHAKE", "SHAPE", "SHARE", "SHIFT", "SHINE", "SHOCK", "SHOOT", "SHORT", "SHOWN", "SIGHT", "SKILL", "SLEEP", "SLIDE", "SMART", "SMILE", "SMOKE", "SOLID", "SOLVE", "SORRY", "SOUTH", "SPACE", "SPARE", "SPEAK", "SPEED", "SPEND", "SPITE", "SPORT", "STAFF", "STAGE", "STAKE", "STAND", "START", "STATE", "STEAM", "STEEL", "STOCK", "STONE", "STORE", "STORM", "STORY", "STRIP", "STUDY", "STYLE", "SUGAR", "SUPER", "TABLE", "TEACH", "THANK", "THEME", "THING", "THOSE", "THREE", "TIGER", "TITLE", "TODAY", "TOPIC", "TOTAL", "TOUCH", "TOUGH", "TOWER", "TRACK", "TRADE", "TRAIN", "TREND", "TRIAL", "TRUST", "TRUTH", "UNION", "UNITY", "VALUE", "VIDEO", "VISIT", "VOICE", "WASTE", "WATCH", "WEIGH", "WHEEL", "WHOLE", "WOMAN", "WORTH", "YOUTH", ] ) ) TASKS = { "easy": EASY_WORDS, "medium": MEDIUM_WORDS, "hard": HARD_WORDS, } MAX_ATTEMPTS = 6 def build_valid_action_mask(words: list[str], guesses: list[str]) -> list[int]: guessed = set(guesses) return [0 if word in guessed else 1 for word in words] def compute_feedback(guess: str, secret: str) -> list[str]: feedback = ["absent"] * len(secret) secret_used = [False] * len(secret) for index, letter in enumerate(guess): if letter == secret[index]: feedback[index] = "correct" secret_used[index] = True for guess_index, letter in enumerate(guess): if feedback[guess_index] != "absent": continue for secret_index, secret_letter in enumerate(secret): if not secret_used[secret_index] and letter == secret_letter: feedback[guess_index] = "present" secret_used[secret_index] = True break return feedback @dataclass class WordleSession: episode_id: str = field(default_factory=lambda: str(uuid4())) task_name: str = "medium" seed: int | None = None evaluation_mode: bool = False secret_word: str | None = None step_count: int = 0 guesses: list[str] = field(default_factory=list) feedback: list[list[str]] = field(default_factory=list) remaining_attempts: int = MAX_ATTEMPTS episode_reward_total: float = 0.0 done: bool = False known_positions: list[str | None] = field(default_factory=lambda: [None] * 5) present_letters: list[str] = field(default_factory=list) absent_letters: list[str] = field(default_factory=list) @property def words(self) -> list[str]: return TASKS[self.task_name] def reset( self, task_name: str = "medium", seed: int | None = None, evaluation_mode: bool = False, ) -> dict[str, Any]: if task_name not in TASKS: raise ValueError(f"Unknown task '{task_name}'. Available tasks: {sorted(TASKS)}") self.task_name = task_name self.seed = seed self.evaluation_mode = evaluation_mode self.episode_id = str(uuid4()) self.step_count = 0 self.guesses = [] self.feedback = [] self.remaining_attempts = MAX_ATTEMPTS self.episode_reward_total = 0.0 self.done = False self.known_positions = [None] * 5 self.present_letters = [] self.absent_letters = [] rng = random.Random(seed) self.secret_word = rng.choice(self.words) return { "observation": self.observation(), "reward": 0.0, "done": False, } def step(self, guess: str) -> dict[str, Any]: if self.secret_word is None: raise ValueError("Environment not initialized. Send a reset message first.") if self.done: raise ValueError("Episode is finished. Send a reset message to start a new game.") normalized_guess = guess.strip().upper() if len(normalized_guess) != 5 or not normalized_guess.isalpha(): raise ValueError("Guess must be a 5-letter alphabetic string.") self.step_count += 1 if normalized_guess not in self.words: self.remaining_attempts -= 1 reward = -1.0 self.episode_reward_total += reward self.done = self.remaining_attempts <= 0 return { "observation": self.observation(), "reward": reward, "done": self.done, "info": { "guess": normalized_guess, "is_valid_word": False, "episode_reward_total": self.episode_reward_total, "steps_taken": self.step_count, }, } feedback = compute_feedback(normalized_guess, self.secret_word) self.guesses.append(normalized_guess) self.feedback.append(feedback) self.remaining_attempts -= 1 self.update_constraints(normalized_guess, feedback) solved = normalized_guess == self.secret_word self.done = solved or self.remaining_attempts <= 0 reward = 1.0 if solved else -0.1 self.episode_reward_total += reward return { "observation": self.observation(), "reward": reward, "done": self.done, "info": { "guess": normalized_guess, "is_valid_word": True, "solved": solved, "episode_reward_total": self.episode_reward_total, "steps_taken": self.step_count, }, } def update_constraints(self, guess: str, feedback: list[str]) -> None: for index, (letter, marker) in enumerate(zip(guess, feedback)): if marker == "correct": self.known_positions[index] = letter elif marker == "present": if letter not in self.present_letters: self.present_letters.append(letter) elif marker == "absent": if ( letter not in self.absent_letters and letter not in self.present_letters and letter not in self.known_positions ): self.absent_letters.append(letter) def observation(self) -> dict[str, Any]: return { "task_name": self.task_name, "guesses": self.guesses, "feedback": self.feedback, "remaining_attempts": self.remaining_attempts, "known_positions": self.known_positions, "present_letters": self.present_letters, "absent_letters": self.absent_letters, "valid_action_mask": build_valid_action_mask(self.words, self.guesses), "word_list_size": len(self.words), "secret_word": self.secret_word if self.evaluation_mode else None, } def state(self) -> dict[str, Any]: return { "episode_id": self.episode_id, "task_name": self.task_name, "step_count": self.step_count, "remaining_attempts": self.remaining_attempts, "done": self.done, "episode_reward_total": self.episode_reward_total, } app = FastAPI() @app.get("/") async def healthcheck() -> dict[str, Any]: return { "status": "running", "environment": "wordle", "tasks": sorted(TASKS), } def error_response(message: str, code: str) -> dict[str, str]: return {"error": message, "code": code} @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket) -> None: await websocket.accept() session = WordleSession() client = websocket.client client_label = f"{client.host}:{client.port}" if client else "unknown" logger.info("WebSocket connected: %s", client_label) try: while True: try: payload = await websocket.receive_json() except JSONDecodeError: await websocket.send_json( error_response("Request body must be valid JSON.", "invalid_json") ) continue if not isinstance(payload, dict): await websocket.send_json( error_response("Request payload must be a JSON object.", "invalid_payload") ) continue message_type = payload.get("type") try: if message_type == "reset": response = session.reset( task_name=str(payload.get("task_name", "medium")).lower(), seed=payload.get("seed"), evaluation_mode=bool(payload.get("evaluation_mode", False)), ) await websocket.send_json(response) continue if message_type == "step": response = session.step(str(payload.get("guess", ""))) await websocket.send_json(response) continue if message_type == "state": await websocket.send_json(session.state()) continue await websocket.send_json( error_response( "Unsupported message type. Expected 'reset', 'step', or 'state'.", "unsupported_type", ) ) except ValueError as exc: await websocket.send_json(error_response(str(exc), "invalid_request")) except WebSocketDisconnect: logger.info("WebSocket disconnected: %s", client_label)