Hugging Face's logo

Spaces:
Surn
/
wrdler
Running

App Files Community
wrdler / CLAUDE.md
Surn's picture
Surn
0.1.2 Minor updates for challenges
5bc2001
preview code
|
raw
history blame
20.2 kB

Wrdler - Project Context

Project Overview

Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these key differences:

  • 8x6 grid (instead of 12x12)
  • One word per row, horizontal only (no vertical words)
  • No scope/radar visualization
  • 2 free letter guesses at game start (all instances of chosen letters are revealed)

Current Version: 0.1.1 Repository: https://github.com/Oncorporation/Wrdler.git Live Demo: [DEPLOYMENT_URL_HERE]

Recent Changes

v0.1.1 (Current):

  • ✅ Enhanced AI word generation logic with intelligent word saving
  • ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries)
  • ✅1000-word file size limit to prevent dictionary bloat
  • ✅ Better new word detection (separates existing vs. new words before saving)
  • ✅ Improved 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

v0.1.0 (Previous):

  • ✅ Version updated to 0.1.0 across all files
  • ✅ AI word generation functionality added
  • ✅ Word list management enhanced with AI support
  • ✅ Utility modules integrated
  • ✅ Documentation synchronized across all files
  • ✅ Project structure validated and consistent
  • ✅ All Phase 1 requirements complete (7 sprints)
  • ✅ 100% test coverage (25/25 tests passing)
  • Status: Ready for deployment! 🚀

v0.0.2-0.0.3 (Previous):

  • ✅ All 7 sprints complete (12.75 hours development time)
  • ✅ Core data models updated for rectangular 8×6 grid
  • ✅ Generator refactored for horizontal-only, one-per-row placement
  • ✅ Radar/scope visualization removed (~217 lines)
  • ✅ Free letter selection UI with circular green gradient buttons
  • ✅ Grid UI updated for 8×6 display with responsive layout
  • ✅ Comprehensive integration testing suite
  • ✅ Complete documentation (GAMEPLAY_GUIDE.md)
  • ✅ Fixed duplicate rendering call bug
  • ✅ PWA support with service worker and manifest

Core Gameplay

  • 8x6 grid with 6 hidden words (one per row, horizontal only)
  • Word composition: 2 four-letter words, 2 five-letter words, 2 six-letter words
  • No scope/radar visualization
  • Players start by choosing 2 letters; all instances are revealed
  • Players click cells to reveal letters or empty spaces
  • After revealing a letter, players can guess words
  • Scoring: word length + bonus for unrevealed letters
  • Game ends when all words are guessed or all word letters are revealed
  • Incorrect guess history with optional display (enabled by default)
  • 10 incorrect guess limit per game
  • ✅ IMPLEMENTED: Challenge Mode with game sharing via short URLs
  • ✅ IMPLEMENTED: Remote storage via Hugging Face datasets
  • ✅ IMPLEMENTED: PWA install support (v0.2.28+)
  • PLANNED: Local persistent storage for game results and high scores (v0.3.0)

Scoring Tiers

  • Fantastic: 42+ points
  • Great: 38-41 points
  • Good: 34-37 points
  • Keep practicing: < 34 points

Technical Architecture

Technology Stack

  • Framework: Streamlit 1.51.0
  • Language: Python 3.12.8 (requires >=3.12, <3.13)
  • Visualization: Matplotlib (>=3.8)
  • HTTP Requests: requests (>=2.31.0)
  • Remote Storage: huggingface_hub (>=0.20.0)
  • Environment: python-dotenv (>=1.0.0)
  • AI Generation: transformers, gradio_client
  • Testing: Pytest
  • Package Manager: UV or pip

Project Structure 

wrdler/
├── app.py                    # Streamlit entry point
├── wrdler/                   # Main package
│   ├── __init__.py          # Version: 0.1.0
│   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
│   ├── generator.py         # Puzzle generation with deterministic seeding
│   ├── logic.py             # Game mechanics (reveal, guess, scoring)
│   ├── ui.py                # Streamlit UI
│   ├── word_loader.py       # Word list management
│   ├── audio.py             # Background music system
│   ├── sounds.py            # Sound effects management
│   ├── generate_sounds.py   # Sound generation utilities
│   ├── game_storage.py      # HF game storage wrapper
│   ├── version_info.py      # Version display
│   ├── modules/             # Shared utility modules (from OpenBadge)
│   │   ├── __init__.py      # Module exports
│   │   ├── storage.py       # HuggingFace storage & URL shortener
│   │   ├── storage.md       # Storage module documentation
│   │   ├── constants.py     # Storage-related constants (trimmed)
│   │   └── file_utils.py    # File utility functions
│   └── words/               # Word list files
│       ├── classic.txt      # Default word list
│       ├── fourth_grade.txt # Elementary word list
│       └── wordlist.txt     # Full word list
├── tests/                   # Unit tests
│   └── test_sprint6_integration.py  # Comprehensive integration tests
├── specs/                   # Documentation
│   ├── specs.md             # Game specifications
│   ├── requirements.md      # Implementation requirements
│   └── wrdler_implementation_plan.md  # Sprint planning summary
├── static/                  # PWA assets
│   ├── manifest.json        # PWA manifest
│   ├── service-worker.js    # Service worker for offline caching
│   └── icons/               # App icons
├── .env                     # Environment variables (HF credentials)
├── pyproject.toml          # Project metadata
├── requirements.txt        # Dependencies
├── uv.lock                 # UV lock file
├── Dockerfile              # Container deployment
├── README.md               # User-facing documentation
├── CLAUDE.md               # This file - project context for Claude
├── GAMEPLAY_GUIDE.md       # User guide with tips and strategies
└── RELEASE_NOTES_v0.1.0.md # Complete release documentation

Key Features

Game Modes

  1. Classic Mode: Allows consecutive guessing after correct answers
  2. Too Easy Mode: Single guess per reveal

Audio & Visual Effects

  • Background Music: Toggleable ocean-themed background music with volume control
  • Sound Effects: Hit/miss/correct/incorrect guess sounds with volume control
  • Ocean Theme: Gradient animated background with wave effects
  • Incorrect Guess History: Visual display of wrong guesses (toggleable in settings)

✅ Challenge Mode & Remote Storage (v0.2.20+)

  • Game ID System: Short URL-based challenge sharing
    • Format: ?game_id=<sid> in URL (shortened URL reference)
    • Each player gets different random words from the same wordlist
    • Enables fair challenges between players
    • Stored in Hugging Face dataset repository
  • Remote Storage via HuggingFace Hub:
    • Per-game settings JSON in games/{uid}/settings.json
    • Shortened URL mapping in shortener.json
    • Multi-user leaderboards with score, time, and difficulty tracking
    • Results sorted by: highest score → fastest time → highest difficulty
  • Challenge Features:
    • Submit results to existing challenges
    • Create new challenges from any completed game
    • Top 5 leaderboard display in Challenge Mode banner
    • Optional player names (defaults to "Anonymous")
    • Word list difficulty calculation and display (v0.2.29)
    • "Show Challenge Share Links" toggle (default OFF) to control URL visibility (v0.2.27)

✅ Progressive Web App (PWA) Support (v0.2.28+)

  • PWA Installation: App is installable as a Progressive Web App on desktop and mobile
    • Service worker for basic offline caching of static assets
    • Manifest.json with app metadata and icons
    • Platform-specific installation instructions in INSTALL_GUIDE.md
    • No gameplay logic changes required
    • Works offline for basic functionality

✅ AI Word Generation (v0.1.0+)

  • AI-Powered Word Lists: Generate custom word lists using Hugging Face Spaces or local transformers
  • Topic-Based Generation: Create words related to specific themes (e.g., "Ocean Life", "Space")
  • Automatic Word Expansion: New AI-generated words are saved to local files for future use
    • Intelligent word detection: separates existing dictionary words from new AI-generated words
    • Only new words are saved to prevent duplicates
    • Automatic retry mechanism (up to 3 attempts) if insufficient words generated
    • 1000-word file size limit prevents dictionary bloat
    • Files auto-sorted by length then alphabetically
  • Fallback Support: Gracefully falls back to dictionary words if AI is unavailable
  • Word Distribution: Ensures exactly 25 words each of lengths 4, 5, and 6 per topic
  • Dual Generation Modes:
    • HF Space API (primary): Uses Hugging Face Space for word generation when USE_HF_WORDS=true
    • Local Models (fallback): Falls back to local transformers models if HF Space unavailable
  • Enhanced Logging: Detailed pipeline visibility for debugging and monitoring

PLANNED: Local Player Storage (v0.3.0)

  • Local Storage:
    • Location: ~/.wrdler/data/
    • Files: game_results.json, highscores.json
    • Privacy-first: no cloud dependency, offline-capable
  • Personal High Scores:
    • Top 100 scores tracked automatically on local machine
    • Filterable by wordlist and game mode
    • High score sidebar expander display
  • Player Statistics:
    • Games played, average score, best score
    • Fastest completion time
    • Per-player history on local device

Puzzle Generation

  • Horizontal-only word placement (one per row in 8×6 grid)
  • Word length distribution: Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
  • Deterministic seeding support for reproducible puzzles
  • No word spacing configuration (fixed one word per row)
  • Validation ensures no overlaps, proper bounds, correct word distribution

UI Components (v0.0.2 - Implemented)

  • Game Grid: Interactive 8×6 button grid (48 cells) with responsive layout
  • Free Letter Selection: Circular green gradient buttons (2 at game start)
  • Score Panel: Real-time scoring with client-side JavaScript timer
  • Settings Sidebar:
    • Word list picker (classic, fourth_grade, wordlist, AI Generated)
    • Game mode selector (Classic, Too Easy)
    • Audio volume controls (music and effects separate)
    • Toggle for incorrect guess history display
    • Player name input
    • "Show Challenge Share Links" toggle (default OFF)
    • Enable/disable sound effects checkbox
    • Enable/disable background music checkbox
  • Theme System: Ocean gradient background with CSS animations
  • Game Over Dialog: Final score display with tier ranking
  • Incorrect Guess Display: Shows history of wrong guesses with count
  • Challenge Mode UI:
    • Challenge Mode banner with leaderboard (top 5 players)
    • Share challenge button in game over dialog
    • Submit result or create new challenge options
    • Word list difficulty display
  • PLANNED (v0.3.0): Local high scores expander and personal statistics display

Development Status

Current Version: 0.1.1 (Complete)

  • ✅ All 7 sprints complete
  • ✅ 100% test coverage (25/25 tests)
  • ✅ AI word generation implemented
  • ✅ Ready for production deployment
  • ✅ PWA support implemented
  • ✅ Challenge Mode fully functional
  • 📊 Development time: ~12.75 hours (sprints 1-7)
  • 📚 Complete documentation

Next Version: v0.3.0 (Planned)

  • 📋 Local storage module (wrdler/local_storage.py)
  • 📋 Personal high score tracking (local JSON files)
  • 📋 High score sidebar UI display
  • 📋 Player statistics tracking and display

Data Models

Core Classes 

@dataclass
class Coord:
    x: int  # row, 0-based
    y: int  # col, 0-based

@dataclass
class Word:
    text: str
    start: Coord
    direction: Direction  # "H" or "V"
    cells: List[Coord]

@dataclass
class Puzzle:
    words: List[Word]
    radar: List[Coord]
    may_overlap: bool
    spacer: int
    uid: str  # Unique identifier for caching

@dataclass
class GameState:
    grid_size: int
    puzzle: Puzzle
    revealed: Set[Coord]
    guessed: Set[str]
    score: int
    last_action: str
    can_guess: bool
    game_mode: str
    points_by_word: Dict[str, int]
    start_time: Optional[datetime]
    end_time: Optional[datetime]

Development Workflow

Running Locally 

# Install dependencies
uv pip install -r requirements.txt --link-mode=copy

# Run app
uv run streamlit run app.py
# or
streamlit run app.py

Docker Deployment 

docker build -t wrdler .
docker run -p 8501:8501 wrdler

Testing 

pytest tests/

Environment Variables

Wrdler uses environment variables for optional features. Create a .env file in the project root:

# ============================================
# Challenge Mode (Remote Storage)
# ============================================
# Required for Challenge Mode features (game sharing, leaderboards)
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN - HuggingFace API token with write access
HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo for challenge storage
SPACE_NAME=YourUsername/Wrdler         # Your HF Space name (for deployment)

# Optional
CRYPTO_PK=                             # Reserved for future challenge signing features

# ============================================
# AI Word Generation
# ============================================
# Controls AI-powered word list generation
USE_HF_WORDS=false                     # Enable HF Space API for word generation
                                       # - true: Use Hugging Face Space API (primary)
                                       # - false: Use local transformers models (fallback)

HF_WORD_LIST_REPO_ID=YourUsername/WordRepo  # HF dataset repo for AI-generated word lists
                                            # (Required if USE_HF_WORDS=true)

IS_LOCAL=                              # Override environment detection
                                       # - true: Force local development mode
                                       # - false: Force production mode
                                       # - (empty): Auto-detect based on environment

Getting 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_...

HF_REPO_ID Structure (Challenge Mode)

The dataset repository will contain:

  • shortener.json - Short URL mappings
  • games/{uid}/settings.json - Per-game challenge data
  • games/{uid}/result.json - Optional detailed results

HF_WORD_LIST_REPO_ID Structure (AI Word Generation)

The dataset repository will contain:

  • words/{topic}.txt - AI-generated word lists by topic
  • Auto-managed by word_loader_ai.py
  • Maximum 1000 words per file
  • Sorted by length then alphabetically

Environment Variable Behavior

Without these variables:

  • Challenge Mode features (sharing, leaderboards) will be disabled
  • AI word generation will fall back to local transformers models
  • Core game functionality remains fully operational

With these variables:

  • Challenge Mode enables game sharing via short URLs
  • AI generation can use HF Space API (faster, more reliable)
  • Remote storage for multi-user leaderboards

Git Configuration & Deployment

Current Branch: main Purpose: Wrdler - vocabulary puzzle game with simplified 8x6 grid Main Branch: main

Remotes

Deployment Platforms

  1. Hugging Face Spaces (Primary) - Dockerfile deployment
  2. Local Development - Streamlit run
  3. Docker - Containerized deployment
  4. PWA - Installable web app on any platform

Sprint Summary (v0.0.2 - Complete)

Sprint Description Time Tests Status
Sprint 1 Core Data Models 3h 13/13 ✅ Complete
Sprint 2 Puzzle Generator 3h 5/5 ✅ Complete
Sprint 3 Remove Radar 0.5h N/A Complete
Sprint 4 Free Letters UI 2h Manual ✅ Complete
Sprint 5 Grid UI Updates 1.25h Syntax ✅ Complete
Sprint 6 Integration Testing 2h 7/7 ✅ Complete
Sprint 7 Documentation 1h N/A Complete
Total All Features 12.75h 25/25 Complete ✅

Status: Ready for deployment! 🚀

Post-v0.0.2 Enhancements

v0.1.1 (AI Word Generation Enhancement)

  • 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)
  • Better HF Space API integration with fallback to local models
  • Additional word generation when MIN_REQUIRED threshold not met
  • Enhanced logging for generation pipeline visibility

v0.1.0 (AI Word Generation)

  • AI-powered word list generation using Hugging Face Spaces
  • Topic-based word creation with automatic saving
  • Enhanced word list management with AI fallback
  • Utility modules integration for storage and file handling

v0.2.20-0.2.29 (Challenge Mode & PWA)

  • Remote storage and game sharing via HF datasets
  • Multi-user leaderboards
  • PWA support with offline caching
  • Word list difficulty calculation
  • Privacy controls for challenge sharing
  • Sound effect and music system improvements

Future Roadmap

v0.3.0 (Next Phase)

  • Local persistent storage module (~/.wrdler/data/)
  • High score tracking and display
  • Player statistics tracking
  • Enhanced UI animations

v1.0.0 (Long Term)

  • Multiple difficulty levels
  • Daily puzzle mode
  • Internationalization (i18n)
  • Performance optimizations
  • Advanced word list management

Deployment Targets

  • Hugging Face Spaces: Primary deployment platform (Dockerfile-based)
  • Docker: Containerized deployment for any platform
  • Local: Development and testing
  • PWA: Installable on desktop and mobile devices

Privacy & Data (v0.1.0)

  • Challenge Mode: Optional remote storage via Hugging Face datasets
    • Player names optional (defaults to "Anonymous")
    • Only stores: word lists, scores, times, game modes
    • No PII beyond optional player name
    • User controls URL visibility via "Show Challenge Share Links" toggle
  • Local Storage (v0.3.0 - Planned):
    • Location: ~/.wrdler/data/
    • Privacy-first, offline-capable
    • Easy to delete
    • No cloud dependency

Notes for Claude

Technical Implementation

  • ✅ Project uses modern Python features (3.12.8)
  • ✅ Requires Python >=3.12, <3.13 per pyproject.toml
  • ✅ Heavy use of Streamlit session state for game state management
  • ✅ Client-side JavaScript for timer updates without page refresh
  • ✅ CSS heavily customized for ocean theme aesthetics
  • ✅ All file paths should be absolute when working in WSL environment
  • ✅ Game IDs are deterministic for consistent sharing
  • ✅ 8×6 rectangular grid (grid_rows=6, grid_cols=8)
  • ✅ Horizontal-only word placement (one per row)
  • ✅ Radar/scope visualization removed entirely
  • ✅ Free letter selection UI implemented with circular buttons
  • ✅ PWA injection via Docker build script (inject-pwa-head.sh)
  • ✅ AI word generation via word_loader_ai.py with Hugging Face integration
  • ✅ Utility modules provide reusable functions for storage and file ops
  • ⚠️ IMPORTANT: Use Python syntax (colons :) NOT JavaScript syntax (curly braces {})
    • Python: if condition: followed by indented block
    • NOT: if condition { - this is JavaScript/C-style syntax
    • Python: try: / except Exception: / else:
    • NOT: try { / } catch (Exception) { / } else {