README.md

---
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