# Word Hunt Environment This Atropos environment is designed to train language models to play **Word Hunt**, a game where the goal is to trace through a 4x4 grid of letters to create as many words as possible within the time limit. Word Hunt combines multiple cognitive challenges: spatial reasoning (tracing paths through the grid), vocabulary knowledge (recognizing valid words), and strategic optimization (prioritizing longer, higher-scoring words within token output constraints). ## Game Rules and Sample Prompt The model receives a 4x4 grid of letters and must find valid English words by tracing through adjacent letters (including diagonally). The key rules are: - Words must be **at least 3 letters long** - Letters must be **adjacent** (horizontally, vertically, or diagonally) - Each letter can only be **used once per word** - The board **does not wrap around** (edges are not connected) - Only **valid English words** count toward the score - **Duplicate words** don't count for extra points **Sample Prompt:** ``` Find English words on this 4x4 letter grid to maximize your score. Longer words are worth more points. You must adhere to the following rules: • Words must be AT LEAST 3 letters long and have to be formed by connecting adjacent letters on the board (including diagonally). • The board does not wrap around; letters on opposite edges are not considered adjacent. • The whole word must have an adjacent path through it • Each letter can only be used once per word. • The word must be a valid word in the English language • Making the same word in multiple ways does not count for extra points - each unique word only counts once. Provide your answer as a comma-separated list, like this: WORD, ANOTHER, EXAMPLE Scoring: 3-letter: 100pts, 4-letter: 400pts, 5-letter: 800pts Board: G O E L M I I E N G M C B S D T Found words: ``` ## Features - **High-Performance Solver:** Uses a Trie-based recursive backtracking algorithm to efficiently find all possible words on any given board. This allows us to measure model performance against the optimal solution and provide accurate scoring. - **Scoring:** Points are awarded based on word length following the official Word Hunt scoring system: - 3-letter words: 100 points - 4-letter words: 400 points - 5-letter words: 800 points - 6+ letter words: 1400 + (400 × (length - 6)) points - These scoring rules are based on the version of Word Hunt in GamePigeon, the iOS app The default maximum output tokens a response will produce is 100 tokens, which simulates the time pressure and encourages strategic resource allocation. - **Reward Signal:** The environment provides normalized rewards (0-1 range) based on the model's score divided by the maximum possible score on each board, ensuring consistent training signals across different board difficulties. ## Setup and Dependencies The environment relies on a dictionary file to validate words. You'll need to download the dictionary file before running the environment: 1. **Download the dictionary file:** Manually download `Dictionary.txt` from: https://github.com/Aboozle1/wordhuntsolver/blob/main/Dictionary.txt 2. **Place it in the correct location:** Save the file as: `environments/community/word_hunt/Dictionary.txt` If you wish to use a different dictionary, you can change the `dictionary_path` in `word_hunt_config.py`. ## How to Run You can run the environment and generate a small sample of rollouts using the `process` command. This is a quick way to test that the environment is working correctly. The results will be saved to a `.jsonl` file and a corresponding `.html` report for easy viewing. ```bash python environments/community/word_hunt/word_hunt_env.py process \ --env.total_steps 2 \ --env.data_path_to_save_groups word_hunt_sample_rollouts.jsonl \ --env.use_wandb false ``` This command will: - Run the model for **2 steps** (i.e., process 2 groups of boards). - Save the results to `word_hunt_sample_rollouts.jsonl` and `word_hunt_sample_rollouts.html`. You can also override other parameters, like the model endpoint: ```bash python environments/community/word_hunt/word_hunt_env.py process \ --openai.base_url \ --openai.api_key \ --openai.model_name \ --env.total_steps 2 \ --env.use_wandb false ``` ### Full Example with Model Configuration Here is a complete, real-world example that specifies the model endpoint and API key. This is useful when you want to target a specific model that is not set as your default. ```bash python3 environments/community/word_hunt/word_hunt_env.py process \ --openai.base_url https://inference-api.nousresearch.com/v1 \ --openai.api_key \ --openai.model_name DeepHermes-3-Llama-3-8B-Preview \ --env.data_path_to_save_groups word_hunt_rollouts.jsonl \ --env.use_wandb false \ --env.total_steps 2 ``` ## Configuration The primary configuration for this environment is handled in `environments/community/word_hunt/word_hunt_config.py`. Key options include: - `prompt_style`: How the board is presented to the model. Can be `grid_visual`, `text_description`, or `both`. - `include_instructions`: Whether to include the game rules in the prompt. - `include_scoring_info`: Whether to show the scoring system in the prompt. - `board_size`: The dimensions of the game board (default is 4). - `dictionary_path`: The file path to the dictionary used for word validation. - `letter_frequencies`: The probability distribution used for generating the letter grid. - `scoring_system`: A dictionary mapping word lengths to point values. - `max_tokens_per_game`: The maximum number of tokens the model is allowed to generate for its response. This simulates a "time limit" and can be adjusted to make the task easier or harder (default: 100).