Spaces:
Running
Running
| title: Wrdler | |
| emoji: 🎲 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 5.50.0 | |
| python_version: 3.12.8 | |
| app_port: 7860 | |
| app_file: app.py | |
| suggested_hardware: cpu-basic | |
| pinned: false | |
| tags: | |
| - game | |
| - vocabulary | |
| - gradio | |
| - education | |
| - ai | |
| - mcp | |
| - mcp-server | |
| short_description: Fast paced word game with AI-generated word lists & MCP | |
| thumbnail: >- | |
| https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/6rWS4AIaozoNMCbx9F5Rv.png | |
| # Wrdler - MCP Hackathon Edition 🎉 | |
| > **This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.** | |
| > **🏆 MCP Hackathon Entry:** This Gradio version includes full MCP (Model Context Protocol) server support for AI word generation! See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for details. | |
| Wrdler is a vocabulary learning game with a simplified grid and strategic letter guessing. The objective is to discover hidden words on a grid by making smart guesses before all letters are revealed. | |
| **🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/MCP-1st-Birthday/wrdler) | |
| **🔧 MCP Server:** This version exposes AI word generation as an MCP tool for LLM integration! | |
| ## Key Differences from BattleWords | |
| - **8x6 grid** (instead of 12x12) with **6 words total** (one per row) | |
| - **Horizontal words only** (no vertical placement) | |
| - **No scope/radar visualization** | |
| - **2 free letter guesses** at the start - choose letters to reveal all instances in the grid | |
| ## Features | |
| ### Core Gameplay | |
| - 8x6 grid with six hidden words (one per row, all horizontal) | |
| - **Word composition:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words | |
| - Game starts with 2 free letter guesses; all instances of chosen letters are revealed | |
| - Reveal grid cells and guess words for points | |
| - Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+) | |
| - Game ends when all words are guessed or all word letters are revealed | |
| - Incorrect guess history with tooltip and optional display (enabled by default) | |
| - 10 incorrect guess limit per game | |
| - Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal) | |
| ### Audio & Visuals | |
| - Ocean-themed gradient background with wave animations | |
| - Background music system (toggleable with volume control) | |
| - Sound effects for hits, misses, correct/incorrect guesses | |
| - Responsive UI built with Streamlit | |
| ### AI Word Generation | |
| - **Topic-based word lists**: Generate custom word lists using AI for any theme | |
| - **Intelligent word expansion**: New AI-generated words automatically saved to local files | |
| - Smart detection separates existing dictionary words from new AI words | |
| - Only saves new words to prevent duplicates | |
| - Automatic retry mechanism (up to 3 attempts) for insufficient word counts | |
| - 1000-word file size limit prevents bloat | |
| - Auto-sorted by length then alphabetically | |
| - **Dual generation modes**: | |
| - **HF Space API** (primary): Uses Hugging Face Space when `USE_HF_WORDS=true` | |
| - **Local transformers** (fallback): Falls back to local models if HF unavailable | |
| - **Fallback support**: Gracefully uses dictionary words if AI generation fails | |
| - **Guaranteed distribution**: Ensures exactly 25 words each of lengths 4, 5, and 6 | |
| - **MCP Integration**: Expose AI word generation as MCP tool when running locally | |
| - See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for setup and usage | |
| ### Customization | |
| - Multiple word lists (classic, fourth_grade, wordlist) | |
| - Wordlist sidebar controls (picker + one-click sort) | |
| - Audio volume controls (music and effects separate) | |
| ### ✅ Challenge Mode | |
| - **Shareable challenge links** via short URLs (`?game_id=<sid>`) | |
| - **Multi-user leaderboards** sorted by score and time | |
| - **Remote storage** via Hugging Face datasets | |
| - **Word list difficulty calculation** and display | |
| - **Submit results** to existing challenges or create new ones | |
| - **Top 5 leaderboard** display in Challenge Mode banner | |
| - **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility | |
| - Each player gets different random words from the same wordlist | |
| ### Deployment & Technical | |
| - **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms | |
| - **Dual UI frameworks**: | |
| - **Streamlit 1.51.0** (default) - Feature-rich, session-state based | |
| - **Gradio 5.50+** (alternative) - Modern, reactive components | |
| - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide) | |
| - **Environment variables** for Challenge Mode (HF_API_TOKEN, HF_REPO_ID, SPACE_NAME) | |
| - Works offline without HF credentials (Challenge Mode features disabled gracefully) | |
| - Compatible with both local development and cloud deployment | |
| ### Progressive Web App (PWA) | |
| - Installable on desktop and mobile from your browser | |
| - Includes `service worker` and `manifest.json` with basic offline caching of static assets | |
| - See `INSTALL_GUIDE.md` for platform-specific steps | |
| ### Planned | |
| - Local persistent storage for personal game history | |
| - Personal high scores sidebar (offline-capable) | |
| - Player statistics tracking | |
| - Deterministic seed UI for custom puzzles | |
| ## Challenge Mode & Leaderboard | |
| When playing a shared challenge (via a `game_id` link), the leaderboard displays all submitted results for that challenge. The leaderboard is **sorted by highest score (descending), then by fastest time (ascending)**. This means players with the most points appear at the top, and ties are broken by the shortest completion time. | |
| ## Installation | |
| 1. Clone the repository: | |
| ``` | |
| git clone https://github.com/Oncorporation/Wrdler.git | |
| cd wrdler | |
| ``` | |
| 2. (Optional) Create and activate a virtual environment: | |
| ``` | |
| python -m venv venv | |
| source venv/bin/activate # On Windows use `venv\Scripts\activate` | |
| ``` | |
| 3. Install dependencies: ( add --system if not using a virutal environment) | |
| ``` | |
| uv pip install -r requirements.txt --link-mode=copy | |
| ``` | |
| ## Running Wrdler | |
| You can run the app locally using either [uv](https://github.com/astral-sh/uv) or Streamlit directly: | |
| **Streamlit UI (default):** | |
| ```bash | |
| uv run streamlit run app.py | |
| # or | |
| streamlit run app.py | |
| ``` | |
| **Gradio UI (MCP-enabled for hackathon):** | |
| ```bash | |
| python gradio_app.py | |
| # or | |
| python -m wrdler.gradio_ui | |
| # MCP server will be enabled automatically when USE_HF_WORDS=false | |
| ``` | |
| Both interfaces provide the same gameplay experience with slightly different UI frameworks. **The Gradio version includes MCP server support for AI tool integration.** | |
| ### Dockerfile Deployment (Hugging Face Spaces and more) | |
| Wrdler supports containerized deployment using a `Dockerfile`. This is the recommended method for deploying to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker) or any Docker-compatible environment. | |
| To deploy on Hugging Face Spaces: | |
| 1. Add a `Dockerfile` to your repository root (see [Spaces Dockerfile guide](https://huggingface.co/docs/hub/spaces-sdks-docker)). | |
| 2. Push your code to your Hugging Face Space. | |
| 3. The platform will build and run your app automatically. | |
| For local Docker runs: | |
| ```sh | |
| docker build -t wrdler . | |
| docker run -p8501:8501 wrdler | |
| ``` | |
| ### Environment Variables (for Challenge Mode) | |
| Challenge Mode requires a `.env` file in the project root with HuggingFace Hub credentials: | |
| ```bash | |
| # Required for Challenge Mode | |
| HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx # or HF_TOKEN | |
| HF_REPO_ID=YourUsername/YourRepo # Target HF dataset repo | |
| SPACE_NAME=YourUsername/Wrdler # Your HF Space name | |
| # Optional | |
| CRYPTO_PK= # Reserved for future signing | |
| ``` | |
| **How to get your HF_API_TOKEN:** | |
| 1. Go to https://huggingface.co/settings/tokens | |
| 2. Create a new token with `write` access | |
| 3. Add to `.env` file as `HF_API_TOKEN=hf_...` | |
| **Note:** The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled. | |
| ## Folder Structure | |
| - `app.py` – Streamlit entry point | |
| - `wrdler/` – Python package | |
| - `models.py` – data models and types | |
| - `word_loader.py` – word list loading and validation | |
| - `word_loader_ai.py` – AI word generation with HF Space API and local transformers | |
| - `generator.py` – word placement logic (8x6, horizontal only) | |
| - `logic.py` – game mechanics (reveal, guess, scoring, free letters) | |
| - `ui.py` – Streamlit UI composition | |
| - `gradio_ui.py` – Gradio UI implementation (alternative interface) | |
| - `game_storage.py` – Hugging Face remote storage integration and challenge sharing | |
| - `local_storage.py` – local JSON storage for results and high scores | |
| - `storage.py` – (legacy) local storage and high scores | |
| - `modules/` – shared utility modules (storage, constants, file_utils) | |
| - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt, AI-generated) | |
| - `style_wrdler.css` – Custom CSS styling for Gradio interface | |
| - `specs/` – documentation (`specs.md`, `requirements.md`) | |
| - `tests/` – unit tests | |
| ## Test File Location | |
| All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests. | |
| ## How to Play | |
| 1. **Start with 2 free letter guesses** - choose two letters to reveal all their instances in the grid. | |
| 2. Click grid squares to reveal letters or empty spaces. | |
| 3. After revealing a letter, enter a guess for a word in the text box. | |
| 4. Earn points for correct guesses and bonus points for unrevealed letters. | |
| 5. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.** | |
| 6. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.** | |
| ## Changelog | |
| ### v0.1.2 (Current - MCP Hackathon Edition) | |
| - ✅ **MCP Server Integration** - Expose AI word generation as MCP tool 🏆 | |
| - `@gr.mcp_server_function` decorator for `generate_ai_words` | |
| - Conditional registration based on `USE_HF_WORDS` flag | |
| - Full schema documentation for inputs/outputs | |
| - See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for setup | |
| - ✅ **Gradio UI Topic Display** - Prominent neon-styled badge at top of game area | |
| - Glassmorphism background with glowing cyan border | |
| - Pulsing neon animation effect | |
| - Editable - type new topic and press Enter to generate/switch word lists | |
| - ✅ **Settings Persistence** - Enable Free Letters and Show Challenge Links persist across new games | |
| - ✅ **Timer Implementation** - Real-time game timer using gr.Timer component | |
| - ✅ **AI Topic Generation UI** - Added to Settings tab with Generate button | |
| - ✅ **Streamlit Cache Fix** - Conditional caching to avoid warnings in Gradio mode | |
| - ✅ **Enhanced CSS Styling** - Improved grid container, topic display, and responsive design | |
| ### v0.1.1 | |
| - ✅ Enhanced AI word generation with intelligent word saving | |
| - ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries) | |
| - ✅ 1000-word file size limit to prevent dictionary bloat | |
| - ✅ Improved new word detection (separates existing vs. new words before saving) | |
| - ✅ Better HF Space API integration with graceful fallback to local models | |
| - ✅ Additional word generation when initial pass doesn't meet MIN_REQUIRED threshold | |
| - ✅ Enhanced logging for word generation pipeline visibility | |
| - ✅ **Gradio UI implementation** (gradio>=5.50) as alternative to Streamlit | |
| - ✅ Custom CSS styling for Gradio interface (style_wrdler.css) | |
| - ✅ Dual UI framework support - choose between Streamlit or Gradio | |
| ### v0.1.0 | |
| - ✅ AI word generation functionality added | |
| - ✅ Topic-based custom word list creation | |
| - ✅ Dual generation modes (HF Space API + local transformers) | |
| - ✅ Utility modules integration (storage, file_utils, constants) | |
| - ✅ Documentation synchronized across all files | |
| ### v0.0.8 | |
| - remove background animation | |
| - add "easy" mode (single guess per reveal) | |
| ### v0.0.7 | |
| - fix guess bug - allowing guesses only after word guessed or letter revealed | |
| ### v0.0.2 (Current - All Sprints Complete) 🎉 | |
| - **Sprint 1-3:** Core data models, generator refactor, radar removal | |
| - **Sprint 4:** Implemented free letter selection UI with circular green gradient buttons | |
| - **Sprint 5:** Updated grid UI rendering for 8×6 display | |
| - **Sprint 6:** Comprehensive integration testing (7/7 tests passing) | |
| - **Sprint 7:** Complete documentation update | |
| - Sound effects integration for free letter selection | |
| - Mobile-responsive free letter grid | |
| - Fixed duplicate rendering call bug | |
| - **All core Wrdler features complete and tested** | |
| ### v0.0.1 (Initial Wrdler Release) | |
| - Project renamed from BattleWords to Wrdler | |
| - Grid resized from 12x12 to 8x6 | |
| - Changed to one word per row (6 total), horizontal only | |
| - Removed vertical word placement | |
| - Removed scope/radar visualization | |
| - Core data models updated for rectangular grid | |
| - Generator refactored for horizontal-only placement | |
| Note | |
| - `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper is provided as `game_storage.py` for remote challenge mode. | |
| ## Known Issues / TODO | |
| - Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection to ensure the chosen file is correctly used by the generator. | |
| ## Development Phases | |
| - **Proof of Concept (0.1.0):** No overlaps, basic UI, single session. | |
| - **Beta (0.5.0):** Overlaps allowed on shared letters, responsive layout, keyboard support, deterministic seed. | |
| - **Full (1.0.0):** Enhanced UX, persistence, leaderboards, daily/practice modes, advanced features. | |
| See `specs/requirements.md` and `specs/specs.md` for full details and roadmap. | |
| ## License | |
| Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner. | |
| ## Hugging Face Spaces Configuration | |
| Wrdler is deployable as a Hugging Face Space with **dual UI support**: Streamlit (default) and Gradio (>=5.50). You can use either the YAML config block or a Dockerfile for advanced/custom deployments. | |
| To configure your Space with the YAML block, add it at the top of your `README.md`: | |
| **Streamlit Configuration (default):** | |
| ```yaml | |
| --- | |
| title: Wrdler | |
| emoji: 🎲 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: streamlit | |
| sdk_version: 1.51.0 | |
| python_version: 3.12.8 | |
| app_file: app.py | |
| suggested_hardware: cpu-basic | |
| tags: | |
| - game | |
| - vocabulary | |
| - streamlit | |
| - education | |
| - ai | |
| --- | |
| ``` | |
| **Gradio Configuration (alternative):** | |
| ```yaml | |
| --- | |
| title: Wrdler Gradio | |
| emoji: 🎲 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 5.50 | |
| python_version: 3.12.8 | |
| app_file: wrdler/gradio_ui.py | |
| suggested_hardware: cpu-basic | |
| tags: | |
| - game | |
| - vocabulary | |
| - gradio | |
| - education | |
| - ai | |
| --- | |
| ``` | |
| **Key parameters:** | |
| - `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space. | |
| - `sdk`: Use `streamlit` or `gradio` depending on your preferred UI framework. | |
| - `sdk_version`: Latest supported version (Streamlit 1.51.0 or Gradio 5.50+). | |
| - `python_version`: Python version (3.12.8 recommended). | |
| - `app_file`: Entry point for your app (`app.py` for Streamlit, `wrdler/gradio_ui.py` for Gradio). | |
| - `suggested_hardware`: Recommended hardware tier (cpu-basic is sufficient). | |
| - `tags`: List of descriptive tags. | |
| **Gradio Implementation Notes:** | |
| - Uses modern Gradio 5.50+ API (compatible with upcoming Gradio 6) | |
| - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide) | |
| - Custom styling via `style_wrdler.css` | |
| - State management with `gr.State` and deep copy updates | |
| - Event handlers use `.click()`, `.change()`, `.submit()` methods | |
| - Modal dialogs with `gr.Modal(visible=False)` pattern |