feat(crossword): generated crosswords with clues

Signed-off-by: Vimal Kumar <vimal78@gmail.com>

.gitignore

@@ -49,7 +49,24 @@ pids
 ehthumbs.db
 Thumbs.db
 
-hack
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# hack
 issues/
 samples/
 venv/
+crossword-app/backend-py/src/services/model_cache/
+hack/model_cache/
+cache-dir/
+.KARO.md
+CLAUDE.md
+crossword-app/backend-py/faiss_cache/

CLAUDE.md

@@ -214,4 +214,6 @@ DATABASE_URL=postgresql://user:pass@host:port/db  # Optional
 - Docker build time: ~5-10 minutes (includes frontend build + Python deps)
 - Container size: ~1.5GB (includes ML models and dependencies)
 - Hugging Face Spaces deployment: Automatic on git push
-- run unit tests after fixing a bug
+- run unit tests after fixing a bug
+- do not use any static files for any word generation or clue gebneration.
+- we do not prefer inference api based solution

Dockerfile

@@ -1,6 +1,6 @@
 # Multi-stage build to optimize performance and security
 # Stage 1: Builder - Install dependencies and build as root
-FROM python:3.11-slim as builder
+FROM python:3.11-slim AS builder
 
 # Set working directory
 WORKDIR /app
@@ -43,7 +43,7 @@ RUN mkdir -p backend-py/public && cp -r frontend/dist/* backend-py/public/
 RUN cd backend-py && ln -sf ../backend/data data
 
 # Stage 2: Runtime - Copy only necessary files as non-root user
-FROM python:3.11-slim as runtime
+FROM python:3.11-slim AS runtime
 
 # Copy Python packages from builder stage
 COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
@@ -78,8 +78,8 @@ ENV PYTHONUNBUFFERED=1
 ENV PIP_NO_CACHE_DIR=1
 
 # Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
-    CMD curl -f http://localhost:7860/health || exit 1
+# HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+#     CMD curl -f http://localhost:7860/health || exit 1
 
 # Start the Python backend server with uvicorn for better production performance
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

VOCABULARY_OPTIMIZATION.md

@@ -0,0 +1,164 @@
+# Vocabulary Optimization & Unification
+
+## Problem Solved
+
+Previously, the crossword system had **vocabulary redundancy** with 3 separate sources:
+- **SentenceTransformer Model Vocabulary**: ~30K tokens → ~8-12K actual words after filtering
+- **NLTK Words Corpus**: 41,998 words for embeddings in thematic generator  
+- **WordFreq Database**: 319,938 words for frequency data
+
+This created inconsistencies, memory waste, and limited vocabulary coverage.
+
+## Solution: Unified Architecture
+
+### New Design
+- **Single Vocabulary Source**: WordFreq database (319,938 words)
+- **Single Embedding Model**: all-mpnet-base-v2 (generates embeddings for any text)
+- **Unified Filtering**: Consistent crossword-suitable word filtering
+- **Shared Caching**: Single vocabulary + embeddings + frequency cache
+
+### Key Components
+
+#### 1. VocabularyManager (`hack/thematic_word_generator.py`)
+- Loads and filters WordFreq vocabulary
+- Applies crossword-suitable filtering (3-12 chars, alphabetic, excludes boring words)
+- Generates frequency data with 10-tier classification
+- Handles caching for performance
+
+#### 2. UnifiedThematicWordGenerator (`hack/thematic_word_generator.py`) 
+- Uses WordFreq vocabulary instead of NLTK words
+- Generates all-mpnet-base-v2 embeddings for WordFreq words
+- Maintains 10-tier frequency classification system
+- Provides both hack tool API and backend-compatible API
+
+#### 3. UnifiedWordService (`crossword-app/backend-py/src/services/unified_word_service.py`)
+- Bridge adapter for backend integration
+- Compatible with existing VectorSearchService interface
+- Uses comprehensive WordFreq vocabulary instead of limited model vocabulary
+
+## Usage
+
+### For Hack Tools
+```python
+from thematic_word_generator import UnifiedThematicWordGenerator
+
+# Initialize with desired vocabulary size
+generator = UnifiedThematicWordGenerator(vocab_size_limit=100000)
+generator.initialize()
+
+# Generate thematic words with tier info
+results = generator.generate_thematic_words(
+    topic="science", 
+    num_words=10,
+    difficulty_tier="tier_5_common"  # Optional tier filtering
+)
+
+for word, similarity, tier in results:
+    print(f"{word}: {similarity:.3f} ({tier})")
+```
+
+### For Backend Integration
+
+#### Option 1: Replace VectorSearchService
+```python
+# In crossword_generator.py
+from .unified_word_service import create_unified_word_service
+
+# Initialize
+vector_service = await create_unified_word_service(vocab_size_limit=100000)
+crossword_gen = CrosswordGenerator(vector_service=vector_service)
+```
+
+#### Option 2: Direct Usage
+```python
+from .unified_word_service import UnifiedWordService
+
+service = UnifiedWordService(vocab_size_limit=100000)
+await service.initialize()
+
+# Compatible with existing interface
+words = await service.find_similar_words("animal", "medium", max_words=15)
+```
+
+## Performance Improvements
+
+### Memory Usage
+- **Before**: 3 separate vocabularies + embeddings (~500MB+)
+- **After**: Single vocabulary + embeddings (~200MB)
+- **Reduction**: ~60% memory usage reduction
+
+### Vocabulary Coverage  
+- **Before**: Limited to ~8-12K words from model tokenizer
+- **After**: Up to 100K+ filtered words from WordFreq database
+- **Improvement**: 10x+ vocabulary coverage
+
+### Consistency
+- **Before**: Different words available in hack tools vs backend
+- **After**: Same comprehensive vocabulary across all components
+- **Benefit**: Consistent word quality and availability
+
+## Configuration
+
+### Environment Variables
+- `MAX_VOCABULARY_SIZE`: Maximum vocabulary size (default: 100000)
+- `EMBEDDING_MODEL`: Model name (default: all-mpnet-base-v2)
+- `WORD_SIMILARITY_THRESHOLD`: Minimum similarity (default: 0.3)
+
+### Vocabulary Size Options
+- **Small (10K)**: Fast initialization, basic vocabulary
+- **Medium (50K)**: Balanced performance and coverage  
+- **Large (100K)**: Comprehensive coverage, slower initialization
+- **Full (319K)**: Complete WordFreq database, longest initialization
+
+## Migration Guide
+
+### For Existing Hack Tools
+1. Update imports: `from thematic_word_generator import UnifiedThematicWordGenerator`
+2. Replace `ThematicWordGenerator` with `UnifiedThematicWordGenerator`
+3. API remains compatible, but now uses comprehensive WordFreq vocabulary
+
+### For Backend Services
+1. Import: `from .unified_word_service import UnifiedWordService`
+2. Replace `VectorSearchService` initialization with `UnifiedWordService`
+3. All existing methods remain compatible
+4. Benefits: Better vocabulary coverage, consistent frequency data
+
+### Backwards Compatibility
+- All existing APIs maintained
+- Same method signatures and return formats
+- Gradual migration possible - can run both systems in parallel
+
+## Benefits Summary
+
+✅ **Eliminates Redundancy**: Single vocabulary source instead of 3 separate ones  
+✅ **Improves Coverage**: 100K+ words vs previous 8-12K words  
+✅ **Reduces Memory**: ~60% reduction in memory usage  
+✅ **Ensures Consistency**: Same vocabulary across hack tools and backend  
+✅ **Maintains Performance**: Smart caching and batch processing  
+✅ **Preserves Features**: 10-tier frequency classification, difficulty filtering  
+✅ **Enables Growth**: Easy to add new features with unified architecture  
+
+## Cache Management
+
+### Cache Locations
+- **Hack tools**: `hack/model_cache/`
+- **Backend**: `crossword-app/backend-py/cache/unified_generator/`
+
+### Cache Files
+- `unified_vocabulary_<size>.pkl`: Filtered vocabulary
+- `unified_frequencies_<size>.pkl`: Frequency data  
+- `unified_embeddings_<model>_<size>.npy`: Pre-computed embeddings
+
+### Cache Invalidation
+Caches are automatically rebuilt if:
+- Vocabulary size limit changes
+- Embedding model changes
+- WordFreq database updates (rare)
+
+## Future Enhancements
+
+1. **Semantic Clustering**: Group words by semantic similarity
+2. **Dynamic Difficulty**: Real-time difficulty adjustment based on user performance  
+3. **Topic Expansion**: Automatic topic discovery and expansion
+4. **Multilingual Support**: Extend to other languages using WordFreq
+5. **Custom Vocabularies**: Allow domain-specific vocabulary additions

crossword-app/backend-py/CROSSWORD_GENERATION_WALKTHROUGH.md

@@ -0,0 +1,434 @@
+# Crossword Generation Code Walkthrough
+
+This document provides a detailed, line-by-line walkthrough of how crossword puzzle generation works in the Python backend, tracing the complete flow from API request to finalized words and clues.
+
+## Overview
+
+The Python backend implements AI-powered crossword generation using:
+- **FastAPI** for web framework and API endpoints
+- **Vector similarity search** with sentence-transformers and FAISS for intelligent word discovery
+- **Backtracking algorithm** for word placement in the crossword grid
+- **Multi-layer caching system** for performance and fallback mechanisms
+
+## 1. Application Startup (`app.py`)
+
+### Entry Point and Service Initialization
+
+```python
+# Lines 66-95: Async lifespan context manager
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global vector_service
+    
+    # Startup initialization
+    vector_service = VectorSearchService()
+    await vector_service.initialize()
+    app.state.vector_service = vector_service
+```
+
+**Flow:**
+1. FastAPI application starts with lifespan context manager
+2. Creates global `VectorSearchService` instance (line 79)
+3. Calls `vector_service.initialize()` (line 82) which:
+   - Loads sentence-transformer model (~30-60 seconds)
+   - Builds or loads cached FAISS index for word embeddings
+   - Initializes word cache manager for fallbacks
+4. Makes vector service available to all API routes via `app.state`
+
+## 2. API Request Handling (`src/routes/api.py`)
+
+### Crossword Generation Endpoint
+
+```python
+# Lines 77-118: Main crossword generation endpoint
+@router.post("/generate", response_model=PuzzleResponse)
+async def generate_puzzle(
+    request: GeneratePuzzleRequest,
+    crossword_gen: CrosswordGenerator = Depends(get_crossword_generator)
+):
+```
+
+**Flow:**
+1. Client POST request to `/api/generate` with JSON body:
+   ```json
+   {
+     "topics": ["animals", "science"], 
+     "difficulty": "medium",
+        }
+   ```
+
+2. FastAPI validates request against `GeneratePuzzleRequest` model (lines 20-23)
+
+3. Dependency injection calls `get_crossword_generator()` (lines 57-63):
+   ```python
+   def get_crossword_generator(request: Request) -> CrosswordGenerator:
+       global generator
+       if generator is None:
+           vector_service = getattr(request.app.state, 'vector_service', None)
+           generator = CrosswordGenerator(vector_service)
+       return generator
+   ```
+
+4. Creates or reuses `CrosswordGenerator` wrapper with vector service reference
+
+## 3. Crossword Generation Wrapper (`src/services/crossword_generator_wrapper.py`)
+
+### Simple Delegation Layer
+
+```python
+# Lines 20-51: Generate puzzle method
+async def generate_puzzle(
+    self, 
+    topics: List[str], 
+    difficulty: str = "medium", 
+    ) -> Dict[str, Any]:
+```
+
+**Flow:**
+1. Wrapper receives request from API route
+2. **Line 41**: Imports actual generator to avoid circular imports:
+   ```python
+   from .crossword_generator import CrosswordGenerator as ActualGenerator
+   ```
+3. **Line 42**: Creates actual generator instance with vector service
+4. **Line 44**: Delegates to actual generator's `generate_puzzle()` method
+
+## 4. Core Crossword Generation (`src/services/crossword_generator.py`)
+
+### 4.1 Main Generation Method
+
+```python
+# Lines 22-66: Core puzzle generation
+async def generate_puzzle(self, topics: List[str], difficulty: str = "medium",  = False):
+```
+
+**Key steps:**
+
+1. **Line 37**: Select words using AI or static sources:
+   ```python
+   words = await self._select_words(topics, difficulty, use_ai)
+   ```
+
+2. **Line 44**: Create crossword grid from selected words:
+   ```python
+   grid_result = self._create_grid(words)
+   ```
+
+3. **Lines 52-62**: Return structured response with grid, clues, and metadata
+
+### 4.2 Word Selection Process
+
+```python
+# Lines 68-97: Word selection logic
+async def _select_words(self, topics: List[str], difficulty: str, ):
+```
+
+**Flow branches based on `use_ai` parameter:**
+
+#### AI-Powered Word Selection (Lines 72-83):
+```python
+if use_ai and self.vector_service:
+    for topic in topics:
+        ai_words = await self.vector_service.find_similar_words(
+            topic, difficulty, self.max_words // len(topics)
+        )
+        all_words.extend(ai_words)
+```
+
+#### Fallback to Cached Words (Lines 86-91):
+```python
+if self.vector_service:
+    for topic in topics:
+        cached_words = await self.vector_service._get_cached_fallback(
+            topic, difficulty, self.max_words // len(topics)
+        )
+```
+
+#### Final Fallback to Static JSON Files (Lines 93-95):
+```python
+else:
+    all_words = await self._get_static_words(topics, difficulty)
+```
+
+### 4.3 Word Sorting for Crossword Viability
+
+```python
+# Lines 129-168: Sort words by crossword suitability
+def _sort_words_for_crossword(self, words: List[Dict[str, Any]]):
+```
+
+**Scoring algorithm:**
+- **Lines 138-147**: Length-based scoring (shorter words preferred)
+- **Lines 150-153**: Common letter bonus (E, A, R, I, O, T, N, S)
+- **Lines 156-158**: Vowel distribution bonus
+- **Lines 161-162**: Penalty for very long words
+
+## 5. AI Word Discovery (`src/services/vector_search.py`)
+
+### 5.1 Vector Search Initialization
+
+```python
+# Lines 71-143: Service initialization
+async def initialize(self):
+```
+
+**Initialization flow:**
+1. **Lines 90-92**: Load sentence-transformer model
+2. **Lines 95-119**: Build or load cached FAISS index
+3. **Lines 124-134**: Initialize word cache manager
+
+### 5.2 Core Word Finding Algorithm
+
+```python
+# Lines 279-374: Main word discovery method
+async def find_similar_words(
+    self, 
+    topic: str, 
+    difficulty: str = "medium", 
+    max_words: int = 15
+):
+```
+
+**Search strategy branches:**
+
+#### Hierarchical Search (Lines 296-325):
+```python
+if self.use_hierarchical_search:
+    all_candidates = await self._hierarchical_search(topic, difficulty, max_words)
+    combined_results = self._combine_hierarchical_results(all_candidates, max_words * 2)
+```
+
+#### Traditional Single Search (Lines 328-337):
+```python
+else:
+    traditional_results = await self._traditional_single_search(topic, difficulty, max_words * 2)
+```
+
+### 5.3 Hierarchical Search Process
+
+```python
+# Lines 639-748: Multi-phase hierarchical search
+async def _hierarchical_search(self, topic: str, difficulty: str, max_words: int):
+```
+
+**Three-phase approach:**
+
+#### Phase 1: Topic Variations (Lines 652-694)
+```python
+topic_variations = self._expand_topic_variations(topic)  # "Animal" → ["Animal", "Animals"]
+
+for variation in topic_variations:
+    topic_embedding = self.model.encode([variation], convert_to_numpy=True)
+    scores, indices = self.faiss_index.search(topic_embedding, search_size)
+    variation_candidates = self._collect_candidates_with_threshold(scores, indices, threshold, variation, difficulty)
+```
+
+#### Phase 2: Subcategory Identification (Lines 697-700)
+```python
+subcategories = self._identify_subcategories(main_topic_candidates, topic)
+```
+
+#### Phase 3: Subcategory Search (Lines 703-733)
+```python
+for subcategory in subcategories:
+    subcat_embedding = self.model.encode([subcategory], convert_to_numpy=True)
+    sub_scores, sub_indices = self.faiss_index.search(subcat_embedding, sub_search_size)
+```
+
+### 5.4 Word Quality Filtering
+
+```python
+# Lines 1164-1215: Candidate collection with filtering
+def _collect_candidates_with_threshold(self, scores, indices, threshold, topic, difficulty):
+```
+
+**Multi-stage filtering:**
+1. **Line 1176**: Similarity threshold check
+2. **Line 1183**: Difficulty matching (word length)
+3. **Line 1185**: Interest and topic relevance check:
+   ```python
+   if self._is_interesting_word(word, topic) and self._is_topic_relevant(word, topic):
+   ```
+
+## 6. Grid Creation and Word Placement
+
+### 6.1 Grid Generation Entry Point
+
+```python
+# Lines 170-243: Main grid creation method
+def _create_grid(self, words: List[Dict[str, Any]]):
+```
+
+**Flow:**
+1. **Lines 184-203**: Process and sort words by length (longest first)
+2. **Lines 209-213**: Calculate appropriate grid size
+3. **Lines 212-237**: Multiple placement attempts with increasing grid size
+4. **Lines 240-241**: Fallback to simple two-word cross
+
+### 6.2 Word Placement Algorithm
+
+```python
+# Lines 259-295: Backtracking word placement
+def _place_words_in_grid(self, word_list: List[str], word_objs: List[Dict[str, Any]], size: int):
+```
+
+**Setup:**
+- **Line 263**: Initialize empty grid with dots
+- **Line 270**: Call recursive backtracking algorithm
+- **Lines 272-287**: Generate clues and assign crossword numbers
+
+### 6.3 Backtracking Algorithm
+
+```python
+# Lines 297-357: Recursive backtracking placement
+def _backtrack_placement(self, grid, word_list, word_objs, word_index, placed_words, start_time, timeout):
+```
+
+**Algorithm flow:**
+
+#### Base Cases:
+- **Lines 302-303**: Timeout check every 50 calls
+- **Lines 305-306**: Success when all words placed
+
+#### First Word Placement (Lines 312-332):
+```python
+if word_index == 0:
+    center_row = size // 2
+    center_col = (size - len(word)) // 2
+    
+    if self._can_place_word(grid, word, center_row, center_col, "horizontal"):
+        original_state = self._place_word(grid, word, center_row, center_col, "horizontal")
+```
+
+#### Subsequent Word Placement (Lines 334-356):
+```python
+all_placements = self._find_all_intersection_placements(grid, word, placed_words)
+all_placements.sort(key=lambda p: p["score"], reverse=True)
+
+for placement in all_placements:
+    if self._can_place_word(grid, word, row, col, direction):
+        # Try placement and recurse
+        if self._backtrack_placement(...):
+            return True
+        # Backtrack if failed
+        self._remove_word(grid, original_state)
+```
+
+### 6.4 Word Placement Validation
+
+```python
+# Lines 359-417: Comprehensive placement validation
+def _can_place_word(self, grid: List[List[str]], word: str, row: int, col: int, direction: str):
+```
+
+**Critical validation checks:**
+1. **Lines 364-365**: Boundary checks
+2. **Lines 372-375**: Word boundary enforcement (no adjacent letters)
+3. **Lines 378-390**: Letter-by-letter placement validation
+4. **Lines 388-390**: Perpendicular intersection validation
+
+### 6.5 Intersection Finding
+
+```python
+# Lines 486-505: Find all possible intersections
+def _find_all_intersection_placements(self, grid, word, placed_words):
+```
+
+**Process:**
+1. **Lines 491-502**: For each placed word, find letter intersections
+2. **Lines 496-502**: Calculate placement position for each intersection
+3. **Lines 499-502**: Score placement quality
+
+## 7. Clue Generation and Final Assembly
+
+### 7.1 Grid Trimming and Optimization
+
+```python
+# Lines 589-642: Remove excess empty space
+def _trim_grid(self, grid, placed_words):
+```
+
+**Process:**
+1. **Lines 595-610**: Find bounding box of all placed words
+2. **Lines 612-631**: Create trimmed grid with padding
+3. **Lines 634-641**: Update word positions relative to new grid
+
+### 7.2 Crossword Numbering
+
+```python
+# Lines 698-750: Assign proper crossword numbers and create clues
+def _assign_numbers_and_clues(self, placed_words, clues_data):
+```
+
+**Crossword numbering rules:**
+1. **Lines 710-714**: Group words by starting position
+2. **Lines 716**: Sort by reading order (top-to-bottom, left-to-right)
+3. **Lines 725-749**: Assign shared numbers for words starting at same position
+4. **Lines 738-745**: Create clue objects with proper formatting
+
+### 7.3 Final Response Assembly
+
+**Back in `crossword_generator.py` lines 52-62:**
+```python
+return {
+    "grid": grid_result["grid"],
+    "clues": grid_result["clues"],
+    "metadata": {
+        "topics": topics,
+        "difficulty": difficulty,
+        "wordCount": len(grid_result["placed_words"]),
+        "size": len(grid_result["grid"]),
+        "aiGenerated":     }
+}
+```
+
+## 8. Caching System (`src/services/word_cache.py`)
+
+### 8.1 Cache Initialization
+
+```python
+# Lines 75-113: Load existing cache files
+async def initialize(self):
+```
+
+**Process:**
+1. **Lines 86-108**: Load all `.json` cache files from disk
+2. **Lines 99-102**: Validate cache structure and load into memory
+3. **Lines 110**: Report loaded cache statistics
+
+### 8.2 Word Caching
+
+```python
+# Lines 166-224: Cache successful word discoveries
+async def cache_words(self, topic, difficulty, words, source="vector_search"):
+```
+
+**Storage process:**
+1. **Lines 186-193**: Enhance words with caching metadata
+2. **Lines 196-207**: Create structured cache data with expiration
+3. **Lines 210-213**: Save to disk (if permissions allow)
+4. **Lines 216-217**: Update in-memory cache
+
+## Complete Data Flow Summary
+
+1. **API Request** → `/api/generate` with topics, difficulty, 2. **Route Handler** → Validates request, injects dependencies
+3. **Wrapper** → Delegates to actual generator with vector service
+4. **Word Selection** → AI vector search OR cached words OR static JSON fallback
+5. **Vector Search** (if AI enabled):
+   - Load sentence-transformer model
+   - Perform hierarchical semantic search
+   - Filter by similarity threshold, difficulty, relevance
+   - Apply word exclusions and variety filtering
+6. **Grid Creation**:
+   - Sort words by crossword viability
+   - Calculate appropriate grid size
+   - Use backtracking algorithm to place words
+   - Validate word boundaries and intersections
+7. **Grid Optimization**:
+   - Trim excess empty space
+   - Assign proper crossword numbers
+   - Generate clue objects
+8. **Response Assembly** → Return grid, clues, and metadata
+9. **Caching** → Store successful AI discoveries for future use
+
+The system gracefully degrades from AI → cached words → static words, ensuring crossword generation always succeeds even when AI components fail.

crossword-app/backend-py/README.md

@@ -1,24 +1,25 @@
-# Python Backend with Vector Similarity Search
+# Python Backend with Thematic AI Word Generation
 
-This is the Python implementation of the crossword generator backend, featuring true AI word generation via vector similarity search.
+This is the Python implementation of the crossword generator backend, featuring AI-powered thematic word generation using WordFreq vocabulary and semantic embeddings.
 
 ## 🚀 Features
 
-- **True Vector Search**: Uses sentence-transformers + FAISS for semantic word discovery
-- **30K+ Vocabulary**: Searches through full model vocabulary instead of limited static lists
+- **Thematic Word Generation**: Uses sentence-transformers for semantic word discovery from WordFreq vocabulary
+- **319K+ Word Database**: Comprehensive vocabulary from WordFreq with frequency data
+- **10-Tier Difficulty System**: Smart word selection based on frequency tiers
+- **Environment Variable Configuration**: Flexible cache and model configuration
 - **FastAPI**: Modern, fast Python web framework
 - **Same API**: Compatible with existing React frontend
-- **Hybrid Approach**: AI vector search with static word fallback
 
 ## 🔄 Differences from JavaScript Backend
 
 | Feature | JavaScript Backend | Python Backend |
 |---------|-------------------|----------------|
-| **Word Generation** | Embedding filtering of static lists | True vector similarity search |
-| **Vocabulary Size** | ~100 words per topic | 30K+ words from model |
-| **AI Approach** | Semantic similarity filtering | Nearest neighbor search |
-| **Performance** | Fast but limited | Slower startup, better results |
-| **Dependencies** | Node.js + HuggingFace API | Python + ML libraries |
+| **Word Generation** | Static word lists | Thematic AI word generation from 319K vocabulary |
+| **Vocabulary Size** | ~100 words per topic | Filtered from 319K WordFreq database |
+| **AI Approach** | Basic filtering | Semantic similarity with frequency tiers |
+| **Performance** | Fast but limited | Slower startup, richer word selection |
+| **Dependencies** | Node.js + static files | Python + ML libraries |
 
 ## 🛠️ Setup & Installation
 
@@ -70,10 +71,11 @@ backend-py/
 ├── requirements-dev.txt            # Full development dependencies
 ├── src/
 │   ├── services/
-│   │   ├── vector_search.py        # Core vector similarity search
-│   │   └── crossword_generator.py  # Puzzle generation logic
+│   │   ├── thematic_word_service.py    # Thematic AI word generation
+│   │   ├── crossword_generator.py      # Puzzle generation logic
+│   │   └── crossword_generator_wrapper.py  # Service wrapper
 │   └── routes/
-│       └── api.py                  # API endpoints (matches JS backend)
+│       └── api.py                      # API endpoints (matches JS backend)
 ├── test-unit/                      # Unit tests (pytest framework) - 5 files
 │   ├── test_crossword_generator.py
 │   ├── test_api_routes.py
@@ -90,8 +92,9 @@ backend-py/
 
 ### Core ML Stack
 - `sentence-transformers`: Local model loading and embeddings
-- `faiss-cpu`: Fast vector similarity search
+- `wordfreq`: 319K word vocabulary with frequency data
 - `torch`: PyTorch for model inference
+- `scikit-learn`: Cosine similarity and clustering
 - `numpy`: Vector operations
 
 ### Web Framework
@@ -203,39 +206,56 @@ pytest test-unit/ --cov=src --cov-report=html --ignore=test-unit/test_vector_sea
 
 ## 🔧 Configuration
 
-Environment variables (set in HuggingFace Spaces):
+### Environment Variables
+
+The backend supports flexible configuration via environment variables:
 
 ```bash
-# Core settings
-PORT=7860
-NODE_ENV=production
+# Cache Configuration
+CACHE_DIR=/app/cache                        # Cache directory for all service files
+THEMATIC_VOCAB_SIZE_LIMIT=50000            # Maximum vocabulary size (default: 100000)
+THEMATIC_MODEL_NAME=all-mpnet-base-v2      # Sentence transformer model
 
-# AI Configuration
-EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
-WORD_SIMILARITY_THRESHOLD=0.65
+# Core Application Settings  
+PORT=7860                                  # Server port
+NODE_ENV=production                        # Environment mode
 
 # Optional
-LOG_LEVEL=INFO
+LOG_LEVEL=INFO                            # Logging level
 ```
 
-## 🎯 Vector Search Process
+### Cache Structure
+
+The service creates the following cache files:
+
+```
+{CACHE_DIR}/
+├── vocabulary_{size}.pkl              # Processed vocabulary words
+├── frequencies_{size}.pkl             # Word frequency data
+├── embeddings_{model}_{size}.npy      # Word embeddings
+└── sentence-transformers/             # Hugging Face model cache
+```
+
+## 🎯 Thematic Word Generation Process
 
 1. **Initialization**:
+   - Load WordFreq vocabulary database (319K words)
+   - Filter words for crossword suitability (length, content)  
    - Load sentence-transformers model locally
-   - Extract 30K+ vocabulary from model tokenizer
-   - Pre-compute embeddings for all vocabulary words
-   - Build FAISS index for fast similarity search
+   - Pre-compute embeddings for filtered vocabulary
+   - Create 10-tier frequency classification system
 
 2. **Word Generation**:
    - Get topic embedding: `"Animals" → [768-dim vector]`
-   - Search FAISS index for nearest neighbors
-   - Filter by similarity threshold (0.65+)
-   - Filter by difficulty (word length)
+   - Compute cosine similarity with all vocabulary embeddings
+   - Filter by similarity threshold and difficulty tier
+   - Filter by crossword-specific criteria (length, etc.)
    - Return top matches with generated clues
 
-3. **Fallback**:
-   - If vector search fails → use static word lists
-   - If insufficient AI words → supplement with static words
+3. **Multi-Theme Support**:
+   - Detect multiple themes using clustering
+   - Generate words that relate to combined themes
+   - Balance word selection across different topics
 
 ## 🧪 Testing
 
@@ -248,16 +268,163 @@ python test_local.py
 python app.py
 ```
 
-## 🐳 Docker Deployment
+## 🐳 Container Deployment
+
+### Docker Run with Cache Configuration
+
+```bash
+# Basic deployment
+docker run -e CACHE_DIR=/app/cache \
+           -e THEMATIC_VOCAB_SIZE_LIMIT=50000 \
+           -v /host/cache:/app/cache \
+           -p 7860:7860 \
+           your-crossword-app
+
+# With all configuration options
+docker run -e CACHE_DIR=/app/cache \
+           -e THEMATIC_VOCAB_SIZE_LIMIT=25000 \
+           -e THEMATIC_MODEL_NAME=all-mpnet-base-v2 \
+           -e NODE_ENV=production \
+           -v /host/cache:/app/cache \
+           -p 7860:7860 \
+           your-crossword-app
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  crossword-backend:
+    image: your-crossword-app
+    environment:
+      - CACHE_DIR=/app/cache
+      - THEMATIC_VOCAB_SIZE_LIMIT=50000
+      - THEMATIC_MODEL_NAME=all-mpnet-base-v2
+      - NODE_ENV=production
+    volumes:
+      - ./cache:/app/cache
+    ports:
+      - "7860:7860"
+    restart: unless-stopped
+```
+
+### Pre-built Cache Strategy (Recommended)
+
+For production deployments, pre-build the cache to avoid long startup times:
+
+```bash
+# 1. Build cache locally or in a build container
+export CACHE_DIR=/local/cache
+export THEMATIC_VOCAB_SIZE_LIMIT=50000
+python -c "from src.services.thematic_word_service import ThematicWordService; s=ThematicWordService(); s.initialize()"
+
+# 2. Deploy with pre-built cache (read-only mount)
+docker run -e CACHE_DIR=/app/cache \
+           -v /local/cache:/app/cache:ro \
+           -p 7860:7860 \
+           your-crossword-app
+```
+
+### Debugging Cache Issues
 
-The Dockerfile has been updated to use Python backend:
+If cache files are not being created in your container:
 
-```dockerfile
-FROM python:3.9-slim
-# ... install dependencies
-# ... build frontend (same as before)
-# ... copy to backend-py/public/
-CMD ["python", "app.py"]
+1. **Check Health Endpoints:**
+```bash
+# Basic health check
+curl http://localhost:7860/api/health
+
+# Detailed cache status
+curl http://localhost:7860/api/health/cache
+
+# Force cache re-initialization
+curl -X POST http://localhost:7860/api/health/cache/reinitialize
+```
+
+2. **Check Container Logs:**
+```bash
+docker logs your-container-name
+```
+Look for cache directory permissions and initialization messages.
+
+3. **Test Cache Directory:**
+```bash
+# Run test script to verify cache setup
+docker exec your-container python test_cache_startup.py
+```
+
+4. **Common Issues:**
+   - **Permission denied**: Container user can't write to mounted volume
+   - **Missing dependencies**: ML libraries not installed in container
+   - **Volume not mounted**: Cache directory not properly mounted
+   - **Environment variables**: `CACHE_DIR` not set correctly
+
+5. **Fix Permission Issues:**
+```bash
+# Option 1: Change ownership of host directory
+sudo chown -R 1000:1000 /host/cache
+
+# Option 2: Run container with specific user
+docker run --user 1000:1000 ...
+
+# Option 3: Set permissions in Dockerfile
+RUN mkdir -p /app/cache && chmod 777 /app/cache
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: crossword-config
+data:
+  CACHE_DIR: "/app/cache"
+  THEMATIC_VOCAB_SIZE_LIMIT: "50000"
+  THEMATIC_MODEL_NAME: "all-mpnet-base-v2"
+  NODE_ENV: "production"
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: crossword-cache
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: crossword-backend
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: crossword-backend
+  template:
+    metadata:
+      labels:
+        app: crossword-backend
+    spec:
+      containers:
+      - name: backend
+        image: your-crossword-app
+        envFrom:
+        - configMapRef:
+            name: crossword-config
+        volumeMounts:
+        - name: cache-volume
+          mountPath: /app/cache
+        ports:
+        - containerPort: 7860
+      volumes:
+      - name: cache-volume
+        persistentVolumeClaim:
+          claimName: crossword-cache
 ```
 
 ## 🧪 Testing
@@ -301,19 +468,25 @@ pytest tests/ --cov=src --cov-report=html
 
 **Startup Time**:
 - JavaScript: ~2 seconds
-- Python: ~30-60 seconds (model download + index building)
+- Python: ~30-60 seconds (model download + embedding generation)
+- Python (with cache): ~5-10 seconds
 
 **Word Quality**:
-- JavaScript: Limited by static word lists
-- Python: Access to full model vocabulary with semantic understanding
+- JavaScript: Limited by static word lists (~100 words/topic)
+- Python: Rich thematic generation from 319K word database
 
 **Memory Usage**:
 - JavaScript: ~100MB
-- Python: ~500MB-1GB (model + embeddings + FAISS index)
+- Python: ~500MB-1GB (model + embeddings)
+- Cache Size: ~50-200MB per 50K vocabulary
 
 **API Response Time**:
-- JavaScript: ~100ms (after cache warm-up)
-- Python: ~200-500ms (vector search + filtering)
+- JavaScript: ~100ms (static word lookup)
+- Python: ~200-500ms (semantic similarity computation)
+
+**Cache Performance**:
+- Vocabulary loading: ~1-2 seconds from cache vs 30+ seconds generation
+- Embeddings loading: ~2-5 seconds from cache vs 60+ seconds generation
 
 ## 🔄 Migration Strategy
 
@@ -325,8 +498,10 @@ pytest tests/ --cov=src --cov-report=html
 
 ## 🎯 Next Steps
 
-- [ ] Test vector search with real model
-- [ ] Optimize FAISS index performance
+- [x] Replace vector search with thematic word generation
+- [x] Implement environment variable cache configuration  
+- [x] Add 10-tier difficulty system based on word frequency
+- [ ] Optimize embedding computation performance
 - [ ] Add more sophisticated crossword grid generation
 - [ ] Implement LLM-based clue generation
-- [ ] Add caching for frequently requested topics
+- [ ] Add cache warming strategies for production deployment

crossword-app/backend-py/all-packages.txt

@@ -0,0 +1,69 @@
+annotated-types==0.7.0
+anyio==4.10.0
+certifi==2025.8.3
+charset-normalizer==3.4.3
+click==8.2.1
+exceptiongroup==1.3.0
+faiss-cpu==1.9.0
+fastapi==0.115.0
+filelock==3.19.1
+fsspec==2025.7.0
+h11==0.16.0
+httpcore==1.0.9
+httptools==0.6.4
+httpx==0.28.1
+huggingface-hub==0.26.2
+idna==3.10
+iniconfig==2.1.0
+Jinja2==3.1.6
+joblib==1.5.1
+MarkupSafe==3.0.2
+mpmath==1.3.0
+networkx==3.4.2
+numpy==1.26.4
+nvidia-cublas-cu12==12.4.5.8
+nvidia-cuda-cupti-cu12==12.4.127
+nvidia-cuda-nvrtc-cu12==12.4.127
+nvidia-cuda-runtime-cu12==12.4.127
+nvidia-cudnn-cu12==9.1.0.70
+nvidia-cufft-cu12==11.2.1.3
+nvidia-curand-cu12==10.3.5.147
+nvidia-cusolver-cu12==11.6.1.9
+nvidia-cusparse-cu12==12.3.1.170
+nvidia-nccl-cu12==2.21.5
+nvidia-nvjitlink-cu12==12.4.127
+nvidia-nvtx-cu12==12.4.127
+packaging==25.0
+pillow==11.3.0
+pluggy==1.6.0
+pydantic==2.9.2
+pydantic-settings==2.5.2
+pydantic_core==2.23.4
+pytest==8.3.4
+pytest-asyncio==0.25.0
+python-dotenv==1.0.1
+python-multipart==0.0.12
+PyYAML==6.0.2
+regex==2025.7.34
+requests==2.32.4
+safetensors==0.6.2
+scikit-learn==1.5.2
+scipy==1.15.3
+sentence-transformers==3.3.0
+sniffio==1.3.1
+starlette==0.38.6
+structlog==24.4.0
+sympy==1.13.1
+threadpoolctl==3.6.0
+tokenizers==0.21.4
+tomli==2.2.1
+torch==2.5.1
+tqdm==4.67.1
+transformers==4.47.1
+triton==3.1.0
+typing_extensions==4.14.1
+urllib3==2.5.0
+uvicorn==0.32.1
+uvloop==0.21.0
+watchfiles==1.1.0
+websockets==15.0.1

crossword-app/backend-py/app.py

@@ -17,61 +17,117 @@ import uvicorn
 from dotenv import load_dotenv
 
 from src.routes.api import router as api_router
-from src.services.vector_search import VectorSearchService
+from src.services.thematic_word_service import ThematicWordService
 
 # Load environment variables
 load_dotenv()
 
-# Set up logging
-logging.basicConfig(level=logging.INFO)
+# Set up logging with filename and line numbers
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(filename)s:%(lineno)d - %(levelname)s - %(message)s',
+    datefmt='%H:%M:%S'
+)
 logger = logging.getLogger(__name__)
 
-def log_with_timestamp(message):
-    """Helper to log with precise timestamp."""
-    timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
-    logger.info(f"[{timestamp}] {message}")
+# All services now use standard Python logging with filename/line numbers
 
-# Global vector search service instance
-vector_service = None
+# Global thematic service instance
+thematic_service = None
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Initialize and cleanup application resources."""
-    global vector_service
+    global thematic_service
     
     # Startup
     startup_time = time.time()
-    log_with_timestamp("🚀 Initializing Python backend with vector search...")
+    logger.info("🚀 Initializing Python backend with thematic word service...")
     
-    # Initialize vector search service
+    # Initialize thematic service
     try:
         service_start = time.time()
-        log_with_timestamp("🔧 Creating VectorSearchService instance...")
-        vector_service = VectorSearchService()
+        logger.info("🔧 Creating ThematicWordService instance...")
+        thematic_service = ThematicWordService()
+        
+        # Log cache configuration for debugging
+        cache_status = thematic_service.get_cache_status()
+        logger.info(f"📁 Cache directory: {cache_status['cache_directory']}")
+        logger.info(f"🔍 Cache directory exists: {os.path.exists(cache_status['cache_directory'])}")
+        logger.info(f"✏️ Cache directory writable: {os.access(cache_status['cache_directory'], os.W_OK)}")
+        
+        # Check for existing cache files
+        cache_complete = cache_status['complete']
+        logger.info(f"📦 Existing cache complete: {cache_complete}")
+        if not cache_complete:
+            for cache_type in ['vocabulary_cache', 'frequency_cache', 'embeddings_cache']:
+                cache_info = cache_status[cache_type]
+                logger.info(f"  {cache_type}: exists={cache_info['exists']}, path={cache_info['path']}")
         
-        log_with_timestamp("⚡ Starting vector search initialization...")
-        await vector_service.initialize()
+        # Force eager initialization to create cache files
+        logger.info("⚡ Starting thematic service initialization (creating cache files)...")
+        await thematic_service.initialize_async()
+        
+        # Verify cache files were created
+        cache_status_after = thematic_service.get_cache_status()
+        logger.info(f"✅ Cache status after initialization: complete={cache_status_after['complete']}")
+        for cache_type in ['vocabulary_cache', 'frequency_cache', 'embeddings_cache']:
+            cache_info = cache_status_after[cache_type]
+            if cache_info['exists']:
+                logger.info(f"  ✅ {cache_type}: {cache_info.get('size_mb', 0):.1f}MB")
+            else:
+                logger.warning(f"  ❌ {cache_type}: NOT CREATED")
         
         init_time = time.time() - service_start
-        log_with_timestamp(f"✅ Vector search service initialized in {init_time:.2f}s")
+        logger.info(f"🎉 Thematic service initialized in {init_time:.2f}s")
+        
+        # Initialize WordNet clue generator during startup
+        logger.info("🔧 Initializing WordNet clue generator...")
+        try:
+            wordnet_start = time.time()
+            from src.services.wordnet_clue_generator import WordNetClueGenerator
+            cache_dir = thematic_service.cache_dir if thematic_service else "./cache"
+            wordnet_generator = WordNetClueGenerator(cache_dir=str(cache_dir))
+            wordnet_generator.initialize()
+            
+            # Store in thematic service for later use
+            if thematic_service:
+                thematic_service._wordnet_generator = wordnet_generator
+                
+            wordnet_time = time.time() - wordnet_start
+            logger.info(f"✅ WordNet clue generator initialized in {wordnet_time:.2f}s")
+        except Exception as e:
+            logger.warning(f"⚠️ Failed to initialize WordNet clue generator during startup: {e}")
+            logger.info("📝 WordNet clue generator will be initialized on first use")
+            
+    except ImportError as e:
+        logger.error(f"❌ Missing dependencies for thematic service: {e}")
+        logger.error("💡 Install missing packages: pip install wordfreq sentence-transformers torch scikit-learn")
+        raise  # Fail fast on missing dependencies
+    except PermissionError as e:
+        logger.error(f"❌ Permission error with cache directory: {e}")
+        logger.error(f"💡 Check cache directory permissions: {thematic_service.cache_dir if 'thematic_service' in locals() else 'unknown'}")
+        raise  # Fail fast on permission issues
     except Exception as e:
-        logger.error(f"❌ Failed to initialize vector search service: {e}")
-        # Continue without vector search (will fallback to static words)
+        logger.error(f"❌ Failed to initialize thematic service: {e}")
+        logger.error(f"🔍 Error type: {type(e).__name__}")
+        import traceback
+        logger.error(f"📋 Full traceback: {traceback.format_exc()}")
+        raise  # Fail fast instead of continuing without service
     
-    # Make vector service available to routes
-    app.state.vector_service = vector_service
+    # Make thematic service available to routes
+    app.state.thematic_service = thematic_service
     
     yield
     
     # Shutdown
     logger.info("🛑 Shutting down Python backend...")
-    if vector_service:
-        await vector_service.cleanup()
+    # Thematic service doesn't need cleanup, but we can add it if needed in the future
 
 # Create FastAPI app
 app = FastAPI(
     title="Crossword Puzzle Generator API",
-    description="Python backend with AI-powered vector similarity search",
+    description="Python backend with AI-powered thematic word generation",
     version="2.0.0",
     lifespan=lifespan
 )

crossword-app/backend-py/data/data

@@ -1 +0,0 @@
-../backend/data

crossword-app/backend-py/data/word-lists/animals.json

@@ -1,165 +0,0 @@
-[
-  { "word": "DOG", "clue": "Man's best friend" },
-  { "word": "CAT", "clue": "Feline pet that purrs" },
-  { "word": "ELEPHANT", "clue": "Large mammal with a trunk" },
-  { "word": "TIGER", "clue": "Striped big cat" },
-  { "word": "WHALE", "clue": "Largest marine mammal" },
-  { "word": "BUTTERFLY", "clue": "Colorful flying insect" },
-  { "word": "BIRD", "clue": "Flying creature with feathers" },
-  { "word": "FISH", "clue": "Aquatic animal with gills" },
-  { "word": "LION", "clue": "King of the jungle" },
-  { "word": "BEAR", "clue": "Large mammal that hibernates" },
-  { "word": "RABBIT", "clue": "Hopping mammal with long ears" },
-  { "word": "HORSE", "clue": "Riding animal with hooves" },
-  { "word": "SHEEP", "clue": "Woolly farm animal" },
-  { "word": "GOAT", "clue": "Horned farm animal" },
-  { "word": "DUCK", "clue": "Water bird that quacks" },
-  { "word": "CHICKEN", "clue": "Farm bird that lays eggs" },
-  { "word": "SNAKE", "clue": "Slithering reptile" },
-  { "word": "TURTLE", "clue": "Shelled reptile" },
-  { "word": "FROG", "clue": "Amphibian that croaks" },
-  { "word": "SHARK", "clue": "Predatory ocean fish" },
-  { "word": "DOLPHIN", "clue": "Intelligent marine mammal" },
-  { "word": "PENGUIN", "clue": "Flightless Antarctic bird" },
-  { "word": "MONKEY", "clue": "Primate that swings in trees" },
-  { "word": "ZEBRA", "clue": "Striped African animal" },
-  { "word": "GIRAFFE", "clue": "Tallest land animal" },
-  { "word": "WOLF", "clue": "Wild canine that howls" },
-  { "word": "FOX", "clue": "Cunning red-furred animal" },
-  { "word": "DEER", "clue": "Graceful forest animal with antlers" },
-  { "word": "MOOSE", "clue": "Large antlered animal" },
-  { "word": "SQUIRREL", "clue": "Tree-climbing nut gatherer" },
-  { "word": "RACCOON", "clue": "Masked nocturnal animal" },
-  { "word": "BEAVER", "clue": "Dam-building rodent" },
-  { "word": "OTTER", "clue": "Playful water mammal" },
-  { "word": "SEAL", "clue": "Marine mammal with flippers" },
-  { "word": "WALRUS", "clue": "Tusked Arctic marine mammal" },
-  { "word": "RHINO", "clue": "Horned thick-skinned mammal" },
-  { "word": "HIPPO", "clue": "Large African river mammal" },
-  { "word": "CHEETAH", "clue": "Fastest land animal" },
-  { "word": "LEOPARD", "clue": "Spotted big cat" },
-  { "word": "JAGUAR", "clue": "South American big cat" },
-  { "word": "PUMA", "clue": "Mountain lion" },
-  { "word": "LYNX", "clue": "Wild cat with tufted ears" },
-  { "word": "KANGAROO", "clue": "Hopping Australian marsupial" },
-  { "word": "KOALA", "clue": "Eucalyptus-eating marsupial" },
-  { "word": "PANDA", "clue": "Black and white bamboo eater" },
-  { "word": "SLOTH", "clue": "Slow-moving tree dweller" },
-  { "word": "ARMADILLO", "clue": "Armored mammal" },
-  { "word": "ANTEATER", "clue": "Long-snouted insect eater" },
-  { "word": "PLATYPUS", "clue": "Egg-laying mammal with a bill" },
-  { "word": "BAT", "clue": "Flying mammal" },
-  { "word": "MOLE", "clue": "Underground tunnel digger" },
-  { "word": "HEDGEHOG", "clue": "Spiny small mammal" },
-  { "word": "PORCUPINE", "clue": "Quill-covered rodent" },
-  { "word": "SKUNK", "clue": "Black and white scent-spraying mammal" },
-  { "word": "WEASEL", "clue": "Small carnivorous mammal" },
-  { "word": "BADGER", "clue": "Burrowing black and white mammal" },
-  { "word": "FERRET", "clue": "Domesticated hunting animal" },
-  { "word": "MINK", "clue": "Valuable fur-bearing animal" },
-  { "word": "EAGLE", "clue": "Majestic bird of prey" },
-  { "word": "HAWK", "clue": "Sharp-eyed hunting bird" },
-  { "word": "OWL", "clue": "Nocturnal bird with large eyes" },
-  { "word": "FALCON", "clue": "Fast diving bird of prey" },
-  { "word": "VULTURE", "clue": "Scavenging bird" },
-  { "word": "CROW", "clue": "Black intelligent bird" },
-  { "word": "RAVEN", "clue": "Large black corvid" },
-  { "word": "ROBIN", "clue": "Red-breasted songbird" },
-  { "word": "SPARROW", "clue": "Small brown songbird" },
-  { "word": "CARDINAL", "clue": "Bright red songbird" },
-  { "word": "BLUEJAY", "clue": "Blue crested bird" },
-  { "word": "WOODPECKER", "clue": "Tree-pecking bird" },
-  { "word": "HUMMINGBIRD", "clue": "Tiny fast-flying bird" },
-  { "word": "PELICAN", "clue": "Large-billed water bird" },
-  { "word": "FLAMINGO", "clue": "Pink wading bird" },
-  { "word": "STORK", "clue": "Long-legged wading bird" },
-  { "word": "HERON", "clue": "Tall fishing bird" },
-  { "word": "CRANE", "clue": "Large wading bird" },
-  { "word": "SWAN", "clue": "Elegant white water bird" },
-  { "word": "GOOSE", "clue": "Large waterfowl" },
-  { "word": "TURKEY", "clue": "Large ground bird" },
-  { "word": "PHEASANT", "clue": "Colorful game bird" },
-  { "word": "QUAIL", "clue": "Small ground bird" },
-  { "word": "PEACOCK", "clue": "Bird with spectacular tail feathers" },
-  { "word": "OSTRICH", "clue": "Largest flightless bird" },
-  { "word": "EMU", "clue": "Australian flightless bird" },
-  { "word": "KIWI", "clue": "Small flightless New Zealand bird" },
-  { "word": "PARROT", "clue": "Colorful talking bird" },
-  { "word": "TOUCAN", "clue": "Large-billed tropical bird" },
-  { "word": "MACAW", "clue": "Large colorful parrot" },
-  { "word": "COCKATOO", "clue": "Crested parrot" },
-  { "word": "CANARY", "clue": "Yellow singing bird" },
-  { "word": "FINCH", "clue": "Small seed-eating bird" },
-  { "word": "PIGEON", "clue": "Common city bird" },
-  { "word": "DOVE", "clue": "Symbol of peace" },
-  { "word": "SEAGULL", "clue": "Coastal scavenging bird" },
-  { "word": "ALBATROSS", "clue": "Large ocean bird" },
-  { "word": "PUFFIN", "clue": "Colorful-billed seabird" },
-  { "word": "LIZARD", "clue": "Small scaly reptile" },
-  { "word": "IGUANA", "clue": "Large tropical lizard" },
-  { "word": "GECKO", "clue": "Wall-climbing lizard" },
-  { "word": "CHAMELEON", "clue": "Color-changing reptile" },
-  { "word": "ALLIGATOR", "clue": "Large American crocodilian" },
-  { "word": "CROCODILE", "clue": "Large aquatic reptile" },
-  { "word": "PYTHON", "clue": "Large constricting snake" },
-  { "word": "COBRA", "clue": "Venomous hooded snake" },
-  { "word": "VIPER", "clue": "Poisonous snake" },
-  { "word": "RATTLESNAKE", "clue": "Snake with warning tail" },
-  { "word": "SALAMANDER", "clue": "Amphibian that can regrow limbs" },
-  { "word": "NEWT", "clue": "Small aquatic salamander" },
-  { "word": "TOAD", "clue": "Warty amphibian" },
-  { "word": "TADPOLE", "clue": "Frog larva" },
-  { "word": "SALMON", "clue": "Fish that swims upstream" },
-  { "word": "TROUT", "clue": "Freshwater game fish" },
-  { "word": "BASS", "clue": "Popular sport fish" },
-  { "word": "TUNA", "clue": "Large ocean fish" },
-  { "word": "SWORDFISH", "clue": "Fish with long pointed bill" },
-  { "word": "MARLIN", "clue": "Large billfish" },
-  { "word": "MANTA", "clue": "Large ray fish" },
-  { "word": "STINGRAY", "clue": "Flat fish with barbed tail" },
-  { "word": "EEL", "clue": "Snake-like fish" },
-  { "word": "SEAHORSE", "clue": "Horse-shaped fish" },
-  { "word": "ANGELFISH", "clue": "Colorful tropical fish" },
-  { "word": "GOLDFISH", "clue": "Common pet fish" },
-  { "word": "CLOWNFISH", "clue": "Orange and white anemone fish" },
-  { "word": "JELLYFISH", "clue": "Transparent stinging sea creature" },
-  { "word": "OCTOPUS", "clue": "Eight-armed sea creature" },
-  { "word": "SQUID", "clue": "Ten-armed cephalopod" },
-  { "word": "CRAB", "clue": "Sideways-walking crustacean" },
-  { "word": "LOBSTER", "clue": "Large marine crustacean" },
-  { "word": "SHRIMP", "clue": "Small crustacean" },
-  { "word": "STARFISH", "clue": "Five-armed sea creature" },
-  { "word": "URCHIN", "clue": "Spiny sea creature" },
-  { "word": "CORAL", "clue": "Marine organism that builds reefs" },
-  { "word": "SPONGE", "clue": "Simple marine animal" },
-  { "word": "OYSTER", "clue": "Pearl-producing mollusk" },
-  { "word": "CLAM", "clue": "Burrowing shellfish" },
-  { "word": "MUSSEL", "clue": "Dark-shelled mollusk" },
-  { "word": "SNAIL", "clue": "Spiral-shelled gastropod" },
-  { "word": "SLUG", "clue": "Shell-less gastropod" },
-  { "word": "WORM", "clue": "Segmented invertebrate" },
-  { "word": "SPIDER", "clue": "Eight-legged web spinner" },
-  { "word": "SCORPION", "clue": "Arachnid with stinging tail" },
-  { "word": "ANT", "clue": "Social insect worker" },
-  { "word": "BEE", "clue": "Honey-making insect" },
-  { "word": "WASP", "clue": "Stinging flying insect" },
-  { "word": "HORNET", "clue": "Large aggressive wasp" },
-  { "word": "FLY", "clue": "Common buzzing insect" },
-  { "word": "MOSQUITO", "clue": "Blood-sucking insect" },
-  { "word": "BEETLE", "clue": "Hard-shelled insect" },
-  { "word": "LADYBUG", "clue": "Red spotted beneficial insect" },
-  { "word": "DRAGONFLY", "clue": "Large-winged flying insect" },
-  { "word": "GRASSHOPPER", "clue": "Jumping green insect" },
-  { "word": "CRICKET", "clue": "Chirping insect" },
-  { "word": "MANTIS", "clue": "Praying insect predator" },
-  { "word": "MOTH", "clue": "Nocturnal butterfly relative" },
-  { "word": "CATERPILLAR", "clue": "Butterfly larva" },
-  { "word": "COCOON", "clue": "Insect transformation casing" },
-  { "word": "TERMITE", "clue": "Wood-eating social insect" },
-  { "word": "TICK", "clue": "Blood-sucking parasite" },
-  { "word": "FLEA", "clue": "Jumping parasite" },
-  { "word": "LOUSE", "clue": "Small parasitic insect" },
-  { "word": "APHID", "clue": "Plant-sucking insect" },
-  { "word": "MAGGOT", "clue": "Fly larva" },
-  { "word": "GRUB", "clue": "Beetle larva" }
-]

crossword-app/backend-py/data/word-lists/geography.json

@@ -1,161 +0,0 @@
-[
-  { "word": "MOUNTAIN", "clue": "High elevation landform" },
-  { "word": "OCEAN", "clue": "Large body of salt water" },
-  { "word": "DESERT", "clue": "Dry, arid region" },
-  { "word": "CONTINENT", "clue": "Large landmass" },
-  { "word": "RIVER", "clue": "Flowing body of water" },
-  { "word": "ISLAND", "clue": "Land surrounded by water" },
-  { "word": "FOREST", "clue": "Dense area of trees" },
-  { "word": "VALLEY", "clue": "Low area between hills" },
-  { "word": "LAKE", "clue": "Body of freshwater" },
-  { "word": "BEACH", "clue": "Sandy shore by water" },
-  { "word": "CLIFF", "clue": "Steep rock face" },
-  { "word": "PLATEAU", "clue": "Elevated flat area" },
-  { "word": "CANYON", "clue": "Deep gorge with steep sides" },
-  { "word": "GLACIER", "clue": "Moving mass of ice" },
-  { "word": "VOLCANO", "clue": "Mountain that erupts" },
-  { "word": "PENINSULA", "clue": "Land surrounded by water on three sides" },
-  { "word": "ARCHIPELAGO", "clue": "Group of islands" },
-  { "word": "PRAIRIE", "clue": "Grassland plain" },
-  { "word": "TUNDRA", "clue": "Cold, treeless region" },
-  { "word": "SAVANNA", "clue": "Tropical grassland" },
-  { "word": "EQUATOR", "clue": "Earth's middle line" },
-  { "word": "LATITUDE", "clue": "Distance from equator" },
-  { "word": "LONGITUDE", "clue": "Distance from prime meridian" },
-  { "word": "CLIMATE", "clue": "Long-term weather pattern" },
-  { "word": "MONSOON", "clue": "Seasonal wind pattern" },
-  { "word": "CAPITAL", "clue": "Main city of country" },
-  { "word": "BORDER", "clue": "Boundary between countries" },
-  { "word": "COAST", "clue": "Land meeting the sea" },
-  { "word": "STRAIT", "clue": "Narrow water passage" },
-  { "word": "DELTA", "clue": "River mouth formation" },
-  { "word": "FJORD", "clue": "Narrow inlet between cliffs" },
-  { "word": "ATOLL", "clue": "Ring-shaped coral island" },
-  { "word": "MESA", "clue": "Flat-topped hill" },
-  { "word": "BUTTE", "clue": "Isolated hill with steep sides" },
-  { "word": "GORGE", "clue": "Deep narrow valley" },
-  { "word": "RAVINE", "clue": "Small narrow gorge" },
-  { "word": "RIDGE", "clue": "Long narrow hilltop" },
-  { "word": "PEAK", "clue": "Mountain summit" },
-  { "word": "SUMMIT", "clue": "Highest point" },
-  { "word": "FOOTHILLS", "clue": "Hills at base of mountains" },
-  { "word": "RANGE", "clue": "Chain of mountains" },
-  { "word": "BASIN", "clue": "Low-lying area" },
-  { "word": "WATERSHED", "clue": "Drainage area" },
-  { "word": "ESTUARY", "clue": "Where river meets sea" },
-  { "word": "BAY", "clue": "Curved inlet of water" },
-  { "word": "GULF", "clue": "Large bay" },
-  { "word": "CAPE", "clue": "Point of land into water" },
-  { "word": "HEADLAND", "clue": "High point of land" },
-  { "word": "LAGOON", "clue": "Shallow coastal body of water" },
-  { "word": "REEF", "clue": "Underwater rock formation" },
-  { "word": "SHOAL", "clue": "Shallow area in water" },
-  { "word": "CHANNEL", "clue": "Deep water passage" },
-  { "word": "SOUND", "clue": "Large sea inlet" },
-  { "word": "HARBOR", "clue": "Sheltered port area" },
-  { "word": "INLET", "clue": "Small bay" },
-  { "word": "COVE", "clue": "Small sheltered bay" },
-  { "word": "MARSH", "clue": "Wetland area" },
-  { "word": "SWAMP", "clue": "Forested wetland" },
-  { "word": "BOG", "clue": "Acidic wetland" },
-  { "word": "OASIS", "clue": "Fertile spot in desert" },
-  { "word": "DUNE", "clue": "Sand hill" },
-  { "word": "PLAIN", "clue": "Flat grassland" },
-  { "word": "STEPPE", "clue": "Dry grassland" },
-  { "word": "TAIGA", "clue": "Northern coniferous forest" },
-  { "word": "RAINFOREST", "clue": "Dense tropical forest" },
-  { "word": "JUNGLE", "clue": "Dense tropical vegetation" },
-  { "word": "WOODLAND", "clue": "Area with scattered trees" },
-  { "word": "GROVE", "clue": "Small group of trees" },
-  { "word": "MEADOW", "clue": "Grassy field" },
-  { "word": "PASTURE", "clue": "Grazing land" },
-  { "word": "FIELD", "clue": "Open area of land" },
-  { "word": "MOOR", "clue": "Open uncultivated land" },
-  { "word": "HEATH", "clue": "Shrubland area" },
-  { "word": "ARCTIC", "clue": "Cold northern region" },
-  { "word": "ANTARCTIC", "clue": "Cold southern region" },
-  { "word": "POLAR", "clue": "Of the poles" },
-  { "word": "TROPICAL", "clue": "Hot humid climate zone" },
-  { "word": "TEMPERATE", "clue": "Moderate climate zone" },
-  { "word": "ARID", "clue": "Very dry" },
-  { "word": "HUMID", "clue": "Moist air" },
-  { "word": "ALTITUDE", "clue": "Height above sea level" },
-  { "word": "ELEVATION", "clue": "Height of land" },
-  { "word": "TERRAIN", "clue": "Physical features of land" },
-  { "word": "TOPOGRAPHY", "clue": "Surface features of area" },
-  { "word": "GEOGRAPHY", "clue": "Study of Earth's features" },
-  { "word": "CARTOGRAPHY", "clue": "Map making" },
-  { "word": "MERIDIAN", "clue": "Longitude line" },
-  { "word": "PARALLEL", "clue": "Latitude line" },
-  { "word": "HEMISPHERE", "clue": "Half of Earth" },
-  { "word": "TROPICS", "clue": "Hot climate zone" },
-  { "word": "POLES", "clue": "Earth's endpoints" },
-  { "word": "AXIS", "clue": "Earth's rotation line" },
-  { "word": "ORBIT", "clue": "Path around sun" },
-  { "word": "SEASON", "clue": "Time of year" },
-  { "word": "SOLSTICE", "clue": "Longest or shortest day" },
-  { "word": "EQUINOX", "clue": "Equal day and night" },
-  { "word": "COMPASS", "clue": "Direction-finding tool" },
-  { "word": "NAVIGATION", "clue": "Finding your way" },
-  { "word": "BEARING", "clue": "Direction or course" },
-  { "word": "AZIMUTH", "clue": "Compass direction" },
-  { "word": "SCALE", "clue": "Map size ratio" },
-  { "word": "LEGEND", "clue": "Map symbol key" },
-  { "word": "CONTOUR", "clue": "Elevation line on map" },
-  { "word": "GRID", "clue": "Map reference system" },
-  { "word": "PROJECTION", "clue": "Map flattening method" },
-  { "word": "SURVEY", "clue": "Land measurement" },
-  { "word": "BOUNDARY", "clue": "Dividing line" },
-  { "word": "FRONTIER", "clue": "Border region" },
-  { "word": "TERRITORY", "clue": "Area of land" },
-  { "word": "REGION", "clue": "Geographic area" },
-  { "word": "ZONE", "clue": "Designated area" },
-  { "word": "DISTRICT", "clue": "Administrative area" },
-  { "word": "PROVINCE", "clue": "Political subdivision" },
-  { "word": "STATE", "clue": "Political entity" },
-  { "word": "COUNTY", "clue": "Local government area" },
-  { "word": "CITY", "clue": "Large urban area" },
-  { "word": "TOWN", "clue": "Small urban area" },
-  { "word": "VILLAGE", "clue": "Small rural community" },
-  { "word": "HAMLET", "clue": "Very small village" },
-  { "word": "SUBURB", "clue": "Residential area outside city" },
-  { "word": "URBAN", "clue": "City-like" },
-  { "word": "RURAL", "clue": "Countryside" },
-  { "word": "METROPOLITAN", "clue": "Large city area" },
-  { "word": "POPULATION", "clue": "Number of people" },
-  { "word": "DENSITY", "clue": "Crowdedness" },
-  { "word": "SETTLEMENT", "clue": "Place where people live" },
-  { "word": "COLONY", "clue": "Overseas territory" },
-  { "word": "NATION", "clue": "Country" },
-  { "word": "REPUBLIC", "clue": "Democratic state" },
-  { "word": "KINGDOM", "clue": "Monarchy" },
-  { "word": "EMPIRE", "clue": "Large political entity" },
-  { "word": "FEDERATION", "clue": "Union of states" },
-  { "word": "ALLIANCE", "clue": "Partnership of nations" },
-  { "word": "TREATY", "clue": "International agreement" },
-  { "word": "TRADE", "clue": "Commercial exchange" },
-  { "word": "EXPORT", "clue": "Goods sent abroad" },
-  { "word": "IMPORT", "clue": "Goods brought in" },
-  { "word": "COMMERCE", "clue": "Business activity" },
-  { "word": "INDUSTRY", "clue": "Manufacturing" },
-  { "word": "AGRICULTURE", "clue": "Farming" },
-  { "word": "MINING", "clue": "Extracting minerals" },
-  { "word": "FORESTRY", "clue": "Tree management" },
-  { "word": "FISHING", "clue": "Catching fish" },
-  { "word": "TOURISM", "clue": "Travel industry" },
-  { "word": "TRANSPORTATION", "clue": "Moving people and goods" },
-  { "word": "INFRASTRUCTURE", "clue": "Basic facilities" },
-  { "word": "COMMUNICATION", "clue": "Information exchange" },
-  { "word": "CULTURE", "clue": "Way of life" },
-  { "word": "LANGUAGE", "clue": "Communication system" },
-  { "word": "RELIGION", "clue": "Belief system" },
-  { "word": "ETHNICITY", "clue": "Cultural group" },
-  { "word": "MIGRATION", "clue": "Movement of people" },
-  { "word": "IMMIGRATION", "clue": "Moving into country" },
-  { "word": "EMIGRATION", "clue": "Moving out of country" },
-  { "word": "DIASPORA", "clue": "Scattered population" },
-  { "word": "NOMAD", "clue": "Wandering person" },
-  { "word": "REFUGEE", "clue": "Displaced person" },
-  { "word": "CENSUS", "clue": "Population count" },
-  { "word": "DEMOGRAPHIC", "clue": "Population characteristic" }
-]

crossword-app/backend-py/data/word-lists/science.json

@@ -1,170 +0,0 @@
-[
-  { "word": "ATOM", "clue": "Smallest unit of matter" },
-  { "word": "GRAVITY", "clue": "Force that pulls objects down" },
-  { "word": "MOLECULE", "clue": "Group of atoms bonded together" },
-  { "word": "PHOTON", "clue": "Particle of light" },
-  { "word": "CHEMISTRY", "clue": "Study of matter and reactions" },
-  { "word": "PHYSICS", "clue": "Study of matter and energy" },
-  { "word": "BIOLOGY", "clue": "Study of living organisms" },
-  { "word": "ELEMENT", "clue": "Pure chemical substance" },
-  { "word": "OXYGEN", "clue": "Gas essential for breathing" },
-  { "word": "CARBON", "clue": "Element found in all life" },
-  { "word": "HYDROGEN", "clue": "Lightest chemical element" },
-  { "word": "ENERGY", "clue": "Capacity to do work" },
-  { "word": "FORCE", "clue": "Push or pull on an object" },
-  { "word": "VELOCITY", "clue": "Speed with direction" },
-  { "word": "MASS", "clue": "Amount of matter in object" },
-  { "word": "VOLUME", "clue": "Amount of space occupied" },
-  { "word": "DENSITY", "clue": "Mass per unit volume" },
-  { "word": "PRESSURE", "clue": "Force per unit area" },
-  { "word": "TEMPERATURE", "clue": "Measure of heat" },
-  { "word": "ELECTRON", "clue": "Negatively charged particle" },
-  { "word": "PROTON", "clue": "Positively charged particle" },
-  { "word": "NEUTRON", "clue": "Neutral atomic particle" },
-  { "word": "NUCLEUS", "clue": "Center of an atom" },
-  { "word": "CELL", "clue": "Basic unit of life" },
-  { "word": "DNA", "clue": "Genetic blueprint molecule" },
-  { "word": "PROTEIN", "clue": "Complex biological molecule" },
-  { "word": "ENZYME", "clue": "Biological catalyst" },
-  { "word": "VIRUS", "clue": "Infectious agent" },
-  { "word": "BACTERIA", "clue": "Single-celled organisms" },
-  { "word": "EVOLUTION", "clue": "Change in species over time" },
-  { "word": "ISOTOPE", "clue": "Atom variant with different neutrons" },
-  { "word": "ION", "clue": "Charged atom or molecule" },
-  { "word": "COMPOUND", "clue": "Chemical combination of elements" },
-  { "word": "MIXTURE", "clue": "Combined substances retaining properties" },
-  { "word": "SOLUTION", "clue": "Dissolved mixture" },
-  { "word": "ACID", "clue": "Sour chemical with low pH" },
-  { "word": "BASE", "clue": "Alkaline substance with high pH" },
-  { "word": "SALT", "clue": "Ionic compound from acid-base reaction" },
-  { "word": "CATALYST", "clue": "Substance that speeds reactions" },
-  { "word": "RNA", "clue": "Genetic messenger molecule" },
-  { "word": "GENE", "clue": "Heredity unit on chromosome" },
-  { "word": "CHROMOSOME", "clue": "Gene-carrying structure" },
-  { "word": "TISSUE", "clue": "Group of similar cells" },
-  { "word": "ORGAN", "clue": "Body part with specific function" },
-  { "word": "SYSTEM", "clue": "Group of organs working together" },
-  { "word": "ORGANISM", "clue": "Living individual entity" },
-  { "word": "SPECIES", "clue": "Group of similar organisms" },
-  { "word": "ADAPTATION", "clue": "Survival-enhancing change" },
-  { "word": "MUTATION", "clue": "Genetic change in DNA" },
-  { "word": "HEREDITY", "clue": "Passing traits to offspring" },
-  { "word": "ECOSYSTEM", "clue": "Community and environment" },
-  { "word": "HABITAT", "clue": "Natural living environment" },
-  { "word": "BIODIVERSITY", "clue": "Variety of life forms" },
-  { "word": "PHOTOSYNTHESIS", "clue": "Plant energy-making process" },
-  { "word": "RESPIRATION", "clue": "Cellular breathing process" },
-  { "word": "METABOLISM", "clue": "Chemical processes in body" },
-  { "word": "HOMEOSTASIS", "clue": "Body's internal balance" },
-  { "word": "MITOSIS", "clue": "Cell division for growth" },
-  { "word": "MEIOSIS", "clue": "Cell division for reproduction" },
-  { "word": "EMBRYO", "clue": "Early development stage" },
-  { "word": "FOSSIL", "clue": "Preserved ancient remains" },
-  { "word": "GEOLOGY", "clue": "Study of Earth's structure" },
-  { "word": "MINERAL", "clue": "Natural inorganic crystal" },
-  { "word": "ROCK", "clue": "Solid earth material" },
-  { "word": "SEDIMENT", "clue": "Settled particles" },
-  { "word": "EROSION", "clue": "Gradual wearing away" },
-  { "word": "VOLCANO", "clue": "Earth opening spewing lava" },
-  { "word": "EARTHQUAKE", "clue": "Ground shaking from plate movement" },
-  { "word": "PLATE", "clue": "Earth's crust section" },
-  { "word": "MAGMA", "clue": "Molten rock beneath surface" },
-  { "word": "LAVA", "clue": "Molten rock on surface" },
-  { "word": "CRYSTAL", "clue": "Ordered atomic structure" },
-  { "word": "ATMOSPHERE", "clue": "Layer of gases around Earth" },
-  { "word": "CLIMATE", "clue": "Long-term weather pattern" },
-  { "word": "WEATHER", "clue": "Short-term atmospheric conditions" },
-  { "word": "PRECIPITATION", "clue": "Water falling from clouds" },
-  { "word": "HUMIDITY", "clue": "Moisture in air" },
-  { "word": "WIND", "clue": "Moving air mass" },
-  { "word": "STORM", "clue": "Violent weather event" },
-  { "word": "HURRICANE", "clue": "Powerful tropical cyclone" },
-  { "word": "TORNADO", "clue": "Rotating column of air" },
-  { "word": "LIGHTNING", "clue": "Electrical discharge in sky" },
-  { "word": "THUNDER", "clue": "Sound of lightning" },
-  { "word": "RAINBOW", "clue": "Spectrum of light in sky" },
-  { "word": "ASTRONOMY", "clue": "Study of celestial objects" },
-  { "word": "GALAXY", "clue": "Collection of stars and planets" },
-  { "word": "PLANET", "clue": "Large orbiting celestial body" },
-  { "word": "STAR", "clue": "Self-luminous celestial body" },
-  { "word": "MOON", "clue": "Natural satellite of planet" },
-  { "word": "COMET", "clue": "Icy body with tail" },
-  { "word": "ASTEROID", "clue": "Rocky space object" },
-  { "word": "METEOR", "clue": "Space rock entering atmosphere" },
-  { "word": "ORBIT", "clue": "Curved path around object" },
-  { "word": "LIGHT", "clue": "Electromagnetic radiation" },
-  { "word": "SPECTRUM", "clue": "Range of electromagnetic radiation" },
-  { "word": "WAVELENGTH", "clue": "Distance between wave peaks" },
-  { "word": "FREQUENCY", "clue": "Waves per unit time" },
-  { "word": "AMPLITUDE", "clue": "Wave height or intensity" },
-  { "word": "SOUND", "clue": "Vibrations in air" },
-  { "word": "ECHO", "clue": "Reflected sound" },
-  { "word": "RESONANCE", "clue": "Vibration amplification" },
-  { "word": "DOPPLER", "clue": "Wave frequency shift effect" },
-  { "word": "MOTION", "clue": "Change in position" },
-  { "word": "ACCELERATION", "clue": "Change in velocity" },
-  { "word": "MOMENTUM", "clue": "Mass times velocity" },
-  { "word": "INERTIA", "clue": "Resistance to motion change" },
-  { "word": "FRICTION", "clue": "Resistance to sliding" },
-  { "word": "HEAT", "clue": "Thermal energy transfer" },
-  { "word": "COMBUSTION", "clue": "Burning chemical reaction" },
-  { "word": "OXIDATION", "clue": "Reaction with oxygen" },
-  { "word": "REDUCTION", "clue": "Gain of electrons" },
-  { "word": "ELECTROLYSIS", "clue": "Chemical breakdown by electricity" },
-  { "word": "CONDUCTIVITY", "clue": "Ability to transfer energy" },
-  { "word": "INSULATOR", "clue": "Material blocking energy flow" },
-  { "word": "SEMICONDUCTOR", "clue": "Partial electrical conductor" },
-  { "word": "MAGNETISM", "clue": "Force of magnetic attraction" },
-  { "word": "FIELD", "clue": "Region of force influence" },
-  { "word": "CIRCUIT", "clue": "Closed electrical path" },
-  { "word": "CURRENT", "clue": "Flow of electric charge" },
-  { "word": "VOLTAGE", "clue": "Electric potential difference" },
-  { "word": "RESISTANCE", "clue": "Opposition to current flow" },
-  { "word": "CAPACITOR", "clue": "Device storing electric charge" },
-  { "word": "INDUCTOR", "clue": "Device storing magnetic energy" },
-  { "word": "TRANSISTOR", "clue": "Electronic switching device" },
-  { "word": "LASER", "clue": "Focused beam of light" },
-  { "word": "RADAR", "clue": "Radio detection system" },
-  { "word": "SONAR", "clue": "Sound detection system" },
-  { "word": "TELESCOPE", "clue": "Instrument for viewing distant objects" },
-  { "word": "MICROSCOPE", "clue": "Instrument for viewing small objects" },
-  { "word": "HYPOTHESIS", "clue": "Testable scientific prediction" },
-  { "word": "THEORY", "clue": "Well-tested scientific explanation" },
-  { "word": "LAW", "clue": "Consistently observed scientific rule" },
-  { "word": "EXPERIMENT", "clue": "Controlled scientific test" },
-  { "word": "OBSERVATION", "clue": "Careful scientific watching" },
-  { "word": "MEASUREMENT", "clue": "Quantified observation" },
-  { "word": "ANALYSIS", "clue": "Detailed examination of data" },
-  { "word": "SYNTHESIS", "clue": "Combining elements into whole" },
-  { "word": "VARIABLE", "clue": "Factor that can change" },
-  { "word": "CONTROL", "clue": "Unchanged comparison group" },
-  { "word": "DATA", "clue": "Information collected from tests" },
-  { "word": "STATISTICS", "clue": "Mathematical analysis of data" },
-  { "word": "PROBABILITY", "clue": "Likelihood of occurrence" },
-  { "word": "PRECISION", "clue": "Exactness of measurement" },
-  { "word": "ACCURACY", "clue": "Correctness of measurement" },
-  { "word": "ERROR", "clue": "Difference from true value" },
-  { "word": "UNCERTAINTY", "clue": "Range of doubt in measurement" },
-  { "word": "CALIBRATION", "clue": "Adjusting instrument accuracy" },
-  { "word": "STANDARD", "clue": "Reference for measurement" },
-  { "word": "UNIT", "clue": "Base measure of quantity" },
-  { "word": "METRIC", "clue": "Decimal measurement system" },
-  { "word": "WEIGHT", "clue": "Force of gravity on mass" },
-  { "word": "CONCENTRATION", "clue": "Amount of substance per volume" },
-  { "word": "MOLARITY", "clue": "Moles of solute per liter" },
-  { "word": "EQUILIBRIUM", "clue": "State of balanced forces" },
-  { "word": "STABILITY", "clue": "Resistance to change" },
-  { "word": "DECAY", "clue": "Gradual breakdown process" },
-  { "word": "RADIATION", "clue": "Energy emitted from source" },
-  { "word": "RADIOACTIVE", "clue": "Emitting nuclear radiation" },
-  { "word": "HALFLIFE", "clue": "Time for half to decay" },
-  { "word": "FUSION", "clue": "Nuclear combining reaction" },
-  { "word": "FISSION", "clue": "Nuclear splitting reaction" },
-  { "word": "QUANTUM", "clue": "Discrete packet of energy" },
-  { "word": "PARTICLE", "clue": "Tiny piece of matter" },
-  { "word": "WAVE", "clue": "Energy transfer disturbance" },
-  { "word": "INTERFERENCE", "clue": "Wave interaction effect" },
-  { "word": "DIFFRACTION", "clue": "Wave bending around obstacle" },
-  { "word": "REFLECTION", "clue": "Bouncing back of waves" },
-  { "word": "REFRACTION", "clue": "Bending of waves through medium" }
-]

crossword-app/backend-py/data/word-lists/technology.json

@@ -1,221 +0,0 @@
-[
-  { "word": "COMPUTER", "clue": "Electronic processing device" },
-  { "word": "INTERNET", "clue": "Global computer network" },
-  { "word": "ALGORITHM", "clue": "Set of rules for solving problems" },
-  { "word": "DATABASE", "clue": "Organized collection of data" },
-  { "word": "SOFTWARE", "clue": "Computer programs" },
-  { "word": "HARDWARE", "clue": "Physical computer components" },
-  { "word": "NETWORK", "clue": "Connected system of computers" },
-  { "word": "CODE", "clue": "Programming instructions" },
-  { "word": "ROBOT", "clue": "Automated machine" },
-  { "word": "ARTIFICIAL", "clue": "Made by humans, not natural" },
-  { "word": "DIGITAL", "clue": "Using binary data" },
-  { "word": "BINARY", "clue": "Base-2 number system" },
-  { "word": "PROCESSOR", "clue": "Computer's brain" },
-  { "word": "MEMORY", "clue": "Data storage component" },
-  { "word": "KEYBOARD", "clue": "Input device with keys" },
-  { "word": "MONITOR", "clue": "Computer display screen" },
-  { "word": "MOUSE", "clue": "Pointing input device" },
-  { "word": "PRINTER", "clue": "Device that prints documents" },
-  { "word": "SCANNER", "clue": "Device that digitizes images" },
-  { "word": "CAMERA", "clue": "Device that captures images" },
-  { "word": "SMARTPHONE", "clue": "Portable computing device" },
-  { "word": "TABLET", "clue": "Touchscreen computing device" },
-  { "word": "LAPTOP", "clue": "Portable computer" },
-  { "word": "SERVER", "clue": "Computer that serves data" },
-  { "word": "CLOUD", "clue": "Internet-based computing" },
-  { "word": "WEBSITE", "clue": "Collection of web pages" },
-  { "word": "EMAIL", "clue": "Electronic mail" },
-  { "word": "BROWSER", "clue": "Web navigation software" },
-  { "word": "SEARCH", "clue": "Look for information" },
-  { "word": "DOWNLOAD", "clue": "Transfer data to device" },
-  { "word": "UPLOAD", "clue": "Transfer data from device" },
-  { "word": "BANDWIDTH", "clue": "Data transfer capacity" },
-  { "word": "PROTOCOL", "clue": "Communication rules" },
-  { "word": "FIREWALL", "clue": "Network security barrier" },
-  { "word": "ENCRYPTION", "clue": "Data scrambling for security" },
-  { "word": "PASSWORD", "clue": "Secret access code" },
-  { "word": "SECURITY", "clue": "Protection from threats" },
-  { "word": "VIRUS", "clue": "Malicious computer program" },
-  { "word": "MALWARE", "clue": "Harmful software" },
-  { "word": "ANTIVIRUS", "clue": "Protection software" },
-  { "word": "BACKUP", "clue": "Data safety copy" },
-  { "word": "RECOVERY", "clue": "Data restoration process" },
-  { "word": "STORAGE", "clue": "Data keeping capacity" },
-  { "word": "HARDDRIVE", "clue": "Magnetic storage device" },
-  { "word": "FLASH", "clue": "Solid state storage" },
-  { "word": "RAM", "clue": "Random access memory" },
-  { "word": "ROM", "clue": "Read-only memory" },
-  { "word": "CPU", "clue": "Central processing unit" },
-  { "word": "GPU", "clue": "Graphics processing unit" },
-  { "word": "MOTHERBOARD", "clue": "Main circuit board" },
-  { "word": "CHIP", "clue": "Integrated circuit" },
-  { "word": "CIRCUIT", "clue": "Electronic pathway" },
-  { "word": "TRANSISTOR", "clue": "Electronic switch" },
-  { "word": "SILICON", "clue": "Semiconductor material" },
-  { "word": "NANOTECHNOLOGY", "clue": "Extremely small scale tech" },
-  { "word": "AUTOMATION", "clue": "Self-operating technology" },
-  { "word": "MACHINE", "clue": "Mechanical device" },
-  { "word": "SENSOR", "clue": "Detection device" },
-  { "word": "ACTUATOR", "clue": "Movement device" },
-  { "word": "FEEDBACK", "clue": "System response information" },
-  { "word": "PROGRAMMING", "clue": "Writing computer instructions" },
-  { "word": "FUNCTION", "clue": "Reusable code block" },
-  { "word": "VARIABLE", "clue": "Data storage container" },
-  { "word": "LOOP", "clue": "Repeating code structure" },
-  { "word": "CONDITION", "clue": "Decision-making logic" },
-  { "word": "DEBUG", "clue": "Find and fix errors" },
-  { "word": "COMPILE", "clue": "Convert code to executable" },
-  { "word": "RUNTIME", "clue": "Program execution time" },
-  { "word": "API", "clue": "Application programming interface" },
-  { "word": "FRAMEWORK", "clue": "Code structure foundation" },
-  { "word": "LIBRARY", "clue": "Reusable code collection" },
-  { "word": "MODULE", "clue": "Self-contained code unit" },
-  { "word": "OBJECT", "clue": "Data and methods container" },
-  { "word": "CLASS", "clue": "Object blueprint" },
-  { "word": "INHERITANCE", "clue": "Code reuse mechanism" },
-  { "word": "INTERFACE", "clue": "System interaction boundary" },
-  { "word": "PROTOCOL", "clue": "Communication standard" },
-  { "word": "FORMAT", "clue": "Data structure standard" },
-  { "word": "SYNTAX", "clue": "Language rules" },
-  { "word": "SEMANTIC", "clue": "Meaning in code" },
-  { "word": "PARSING", "clue": "Analyzing code structure" },
-  { "word": "COMPILER", "clue": "Code translation program" },
-  { "word": "INTERPRETER", "clue": "Code execution program" },
-  { "word": "VIRTUAL", "clue": "Simulated environment" },
-  { "word": "SIMULATION", "clue": "Computer modeling" },
-  { "word": "EMULATION", "clue": "System imitation" },
-  { "word": "OPTIMIZATION", "clue": "Performance improvement" },
-  { "word": "EFFICIENCY", "clue": "Resource usage effectiveness" },
-  { "word": "PERFORMANCE", "clue": "System speed and quality" },
-  { "word": "BENCHMARK", "clue": "Performance measurement" },
-  { "word": "TESTING", "clue": "Quality verification process" },
-  { "word": "VALIDATION", "clue": "Correctness checking" },
-  { "word": "VERIFICATION", "clue": "Accuracy confirmation" },
-  { "word": "QUALITY", "clue": "Standard of excellence" },
-  { "word": "MAINTENANCE", "clue": "System upkeep" },
-  { "word": "UPDATE", "clue": "Software improvement" },
-  { "word": "PATCH", "clue": "Software fix" },
-  { "word": "VERSION", "clue": "Software release number" },
-  { "word": "RELEASE", "clue": "Software distribution" },
-  { "word": "DEPLOYMENT", "clue": "Software installation" },
-  { "word": "CONFIGURATION", "clue": "System setup" },
-  { "word": "INSTALLATION", "clue": "Software setup process" },
-  { "word": "MIGRATION", "clue": "System transition" },
-  { "word": "INTEGRATION", "clue": "System combination" },
-  { "word": "COMPATIBILITY", "clue": "System cooperation ability" },
-  { "word": "INTEROPERABILITY", "clue": "Cross-system communication" },
-  { "word": "SCALABILITY", "clue": "Growth accommodation ability" },
-  { "word": "RELIABILITY", "clue": "Consistent performance" },
-  { "word": "AVAILABILITY", "clue": "System accessibility" },
-  { "word": "REDUNDANCY", "clue": "Backup system duplication" },
-  { "word": "FAULT", "clue": "System error condition" },
-  { "word": "TOLERANCE", "clue": "Error handling ability" },
-  { "word": "RECOVERY", "clue": "System restoration" },
-  { "word": "MONITORING", "clue": "System observation" },
-  { "word": "LOGGING", "clue": "Event recording" },
-  { "word": "ANALYTICS", "clue": "Data analysis" },
-  { "word": "METRICS", "clue": "Measurement data" },
-  { "word": "DASHBOARD", "clue": "Information display panel" },
-  { "word": "INTERFACE", "clue": "User interaction design" },
-  { "word": "EXPERIENCE", "clue": "User interaction quality" },
-  { "word": "USABILITY", "clue": "Ease of use" },
-  { "word": "ACCESSIBILITY", "clue": "Universal design principle" },
-  { "word": "RESPONSIVE", "clue": "Adaptive design" },
-  { "word": "MOBILE", "clue": "Portable device category" },
-  { "word": "TOUCHSCREEN", "clue": "Touch-sensitive display" },
-  { "word": "GESTURE", "clue": "Touch movement command" },
-  { "word": "VOICE", "clue": "Speech interaction" },
-  { "word": "RECOGNITION", "clue": "Pattern identification" },
-  { "word": "LEARNING", "clue": "Adaptive improvement" },
-  { "word": "INTELLIGENCE", "clue": "Artificial reasoning" },
-  { "word": "NEURAL", "clue": "Brain-inspired network" },
-  { "word": "DEEP", "clue": "Multi-layered learning" },
-  { "word": "MACHINE", "clue": "Automated learning system" },
-  { "word": "DATA", "clue": "Information collection" },
-  { "word": "BIG", "clue": "Large scale data" },
-  { "word": "MINING", "clue": "Data pattern extraction" },
-  { "word": "ANALYSIS", "clue": "Data examination" },
-  { "word": "VISUALIZATION", "clue": "Data graphic representation" },
-  { "word": "DASHBOARD", "clue": "Data monitoring panel" },
-  { "word": "REPORT", "clue": "Data summary document" },
-  { "word": "QUERY", "clue": "Data search request" },
-  { "word": "INDEX", "clue": "Data location reference" },
-  { "word": "SCHEMA", "clue": "Data structure blueprint" },
-  { "word": "TABLE", "clue": "Data organization structure" },
-  { "word": "RECORD", "clue": "Data entry" },
-  { "word": "FIELD", "clue": "Data element" },
-  { "word": "PRIMARY", "clue": "Main identifier key" },
-  { "word": "FOREIGN", "clue": "Reference relationship key" },
-  { "word": "RELATION", "clue": "Data connection" },
-  { "word": "JOIN", "clue": "Data combination operation" },
-  { "word": "TRANSACTION", "clue": "Data operation sequence" },
-  { "word": "COMMIT", "clue": "Data change confirmation" },
-  { "word": "ROLLBACK", "clue": "Data change reversal" },
-  { "word": "CONCURRENCY", "clue": "Simultaneous access handling" },
-  { "word": "LOCK", "clue": "Data access control" },
-  { "word": "SYNCHRONIZATION", "clue": "Timing coordination" },
-  { "word": "THREAD", "clue": "Execution sequence" },
-  { "word": "PROCESS", "clue": "Running program instance" },
-  { "word": "MULTITASKING", "clue": "Multiple process handling" },
-  { "word": "PARALLEL", "clue": "Simultaneous execution" },
-  { "word": "DISTRIBUTED", "clue": "Spread across multiple systems" },
-  { "word": "CLUSTER", "clue": "Group of connected computers" },
-  { "word": "GRID", "clue": "Distributed computing network" },
-  { "word": "PEER", "clue": "Equal network participant" },
-  { "word": "CLIENT", "clue": "Service requesting system" },
-  { "word": "SERVICE", "clue": "System functionality provider" },
-  { "word": "MICROSERVICE", "clue": "Small independent service" },
-  { "word": "CONTAINER", "clue": "Isolated application environment" },
-  { "word": "DOCKER", "clue": "Containerization platform" },
-  { "word": "KUBERNETES", "clue": "Container orchestration" },
-  { "word": "DEVOPS", "clue": "Development operations practice" },
-  { "word": "AGILE", "clue": "Flexible development method" },
-  { "word": "SCRUM", "clue": "Iterative development framework" },
-  { "word": "SPRINT", "clue": "Short development cycle" },
-  { "word": "KANBAN", "clue": "Visual workflow management" },
-  { "word": "CONTINUOUS", "clue": "Ongoing integration practice" },
-  { "word": "PIPELINE", "clue": "Automated workflow" },
-  { "word": "BUILD", "clue": "Software compilation process" },
-  { "word": "TESTING", "clue": "Quality assurance process" },
-  { "word": "AUTOMATION", "clue": "Manual task elimination" },
-  { "word": "SCRIPT", "clue": "Automated task sequence" },
-  { "word": "BATCH", "clue": "Group processing" },
-  { "word": "STREAMING", "clue": "Continuous data flow" },
-  { "word": "REALTIME", "clue": "Immediate processing" },
-  { "word": "LATENCY", "clue": "Response delay time" },
-  { "word": "THROUGHPUT", "clue": "Processing capacity" },
-  { "word": "BOTTLENECK", "clue": "Performance limitation point" },
-  { "word": "CACHE", "clue": "Fast temporary storage" },
-  { "word": "BUFFER", "clue": "Temporary data holder" },
-  { "word": "QUEUE", "clue": "Ordered waiting line" },
-  { "word": "STACK", "clue": "Last-in-first-out structure" },
-  { "word": "HEAP", "clue": "Dynamic memory area" },
-  { "word": "POINTER", "clue": "Memory address reference" },
-  { "word": "REFERENCE", "clue": "Object location indicator" },
-  { "word": "GARBAGE", "clue": "Unused memory collection" },
-  { "word": "ALLOCATION", "clue": "Memory assignment" },
-  { "word": "DEALLOCATION", "clue": "Memory release" },
-  { "word": "LEAK", "clue": "Memory usage error" },
-  { "word": "OVERFLOW", "clue": "Capacity exceeding error" },
-  { "word": "UNDERFLOW", "clue": "Insufficient data error" },
-  { "word": "EXCEPTION", "clue": "Error handling mechanism" },
-  { "word": "INTERRUPT", "clue": "Process suspension signal" },
-  { "word": "SIGNAL", "clue": "Process communication" },
-  { "word": "EVENT", "clue": "System occurrence" },
-  { "word": "HANDLER", "clue": "Event processing function" },
-  { "word": "CALLBACK", "clue": "Function reference" },
-  { "word": "PROMISE", "clue": "Future value placeholder" },
-  { "word": "ASYNC", "clue": "Non-blocking operation" },
-  { "word": "AWAIT", "clue": "Pause for completion" },
-  { "word": "YIELD", "clue": "Temporary function pause" },
-  { "word": "GENERATOR", "clue": "Value sequence producer" },
-  { "word": "ITERATOR", "clue": "Sequential access pattern" },
-  { "word": "RECURSION", "clue": "Self-calling function" },
-  { "word": "CLOSURE", "clue": "Function scope retention" },
-  { "word": "LAMBDA", "clue": "Anonymous function" },
-  { "word": "FUNCTIONAL", "clue": "Function-based programming" },
-  { "word": "PROCEDURAL", "clue": "Step-by-step programming" },
-  { "word": "DECLARATIVE", "clue": "What-not-how programming" },
-  { "word": "IMPERATIVE", "clue": "Command-based programming" }
-]

crossword-app/backend-py/debug_full_generation.py

@@ -1,316 +0,0 @@
-#!/usr/bin/env python3
-"""
-Debug the complete crossword generation process to identify display/numbering issues.
-"""
-
-import asyncio
-import sys
-import json
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-
-async def debug_complete_generation():
-    """Debug the complete crossword generation process."""
-    
-    print("🔍 Debugging Complete Crossword Generation Process\n")
-    
-    # Create generator with no vector service to use static words
-    generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    # Override the word selection to use controlled test words
-    test_words = [
-        {"word": "MACHINE", "clue": "Device with moving parts"},
-        {"word": "COMPUTER", "clue": "Electronic device"}, 
-        {"word": "EXPERT", "clue": "Person with specialized knowledge"},
-        {"word": "SCIENCE", "clue": "Systematic study"},
-        {"word": "TECHNOLOGY", "clue": "Applied science"},
-        {"word": "RESEARCH", "clue": "Systematic investigation"},
-        {"word": "ANALYSIS", "clue": "Detailed examination"},
-        {"word": "METHOD", "clue": "Systematic approach"}
-    ]
-    
-    # Mock the word selection method
-    async def mock_select_words(topics, difficulty, use_ai):
-        return test_words
-    generator._select_words = mock_select_words
-    
-    print("=" * 70)
-    print("GENERATING COMPLETE CROSSWORD")
-    print("=" * 70)
-    
-    try:
-        result = await generator.generate_puzzle(["technology"], "medium", use_ai=False)
-        
-        if result:
-            print("✅ Crossword generation successful!")
-            
-            # Analyze the complete result
-            analyze_crossword_result(result)
-        else:
-            print("❌ Crossword generation failed - returned None")
-            
-    except Exception as e:
-        print(f"❌ Crossword generation failed with error: {e}")
-        import traceback
-        traceback.print_exc()
-
-def analyze_crossword_result(result):
-    """Analyze the complete crossword result for potential issues."""
-    
-    print("\n" + "=" * 70)
-    print("CROSSWORD RESULT ANALYSIS")
-    print("=" * 70)
-    
-    # Print basic metadata
-    metadata = result.get("metadata", {})
-    print("Metadata:")
-    for key, value in metadata.items():
-        print(f"  {key}: {value}")
-    
-    # Analyze the grid
-    grid = result.get("grid", [])
-    print(f"\nGrid dimensions: {len(grid)}x{len(grid[0]) if grid else 0}")
-    
-    print("\nGrid layout:")
-    print_numbered_grid(grid)
-    
-    # Analyze placed words vs clues
-    clues = result.get("clues", [])
-    print(f"\nNumber of clues generated: {len(clues)}")
-    
-    print("\nClue analysis:")
-    for i, clue in enumerate(clues):
-        print(f"  Clue {i+1}:")
-        print(f"    Number: {clue.get('number', 'MISSING')}")
-        print(f"    Word: {clue.get('word', 'MISSING')}")
-        print(f"    Direction: {clue.get('direction', 'MISSING')}")
-        print(f"    Position: {clue.get('position', 'MISSING')}")
-        print(f"    Text: {clue.get('text', 'MISSING')}")
-    
-    # Check for potential issues
-    print("\n" + "=" * 70)
-    print("ISSUE DETECTION")
-    print("=" * 70)
-    
-    check_word_boundary_consistency(grid, clues)
-    check_numbering_consistency(clues)
-    check_grid_word_alignment(grid, clues)
-
-def print_numbered_grid(grid):
-    """Print grid with coordinates for analysis."""
-    if not grid:
-        print("  Empty grid")
-        return
-    
-    # Print column headers
-    print("    ", end="")
-    for c in range(len(grid[0])):
-        print(f"{c:2d}", end="")
-    print()
-    
-    # Print rows with row numbers
-    for r in range(len(grid)):
-        print(f" {r:2d}: ", end="")
-        for c in range(len(grid[0])):
-            cell = grid[r][c]
-            if cell == ".":
-                print(" .", end="")
-            else:
-                print(f" {cell}", end="")
-        print()
-
-def check_word_boundary_consistency(grid, clues):
-    """Check if words in clues match what's actually in the grid."""
-    
-    print("Checking word boundary consistency:")
-    
-    issues_found = []
-    
-    for clue in clues:
-        word = clue.get("word", "")
-        position = clue.get("position", {})
-        direction = clue.get("direction", "")
-        
-        if not all([word, position, direction]):
-            issues_found.append(f"Incomplete clue data: {clue}")
-            continue
-        
-        row = position.get("row", -1)
-        col = position.get("col", -1)
-        
-        if row < 0 or col < 0:
-            issues_found.append(f"Invalid position for word '{word}': {position}")
-            continue
-        
-        # Extract the actual word from the grid
-        grid_word = extract_word_from_grid(grid, row, col, direction, len(word))
-        
-        if grid_word != word:
-            issues_found.append(f"Mismatch for '{word}' at ({row}, {col}) {direction}: grid shows '{grid_word}'")
-    
-    if issues_found:
-        print("  ❌ Issues found:")
-        for issue in issues_found:
-            print(f"    {issue}")
-    else:
-        print("  ✅ All words match grid positions")
-
-def extract_word_from_grid(grid, row, col, direction, expected_length):
-    """Extract a word from the grid at the given position and direction."""
-    
-    if row >= len(grid) or col >= len(grid[0]):
-        return "OUT_OF_BOUNDS"
-    
-    word = ""
-    
-    if direction == "across":  # horizontal
-        for i in range(expected_length):
-            if col + i >= len(grid[0]):
-                return word + "TRUNCATED"
-            word += grid[row][col + i]
-    
-    elif direction == "down":  # vertical
-        for i in range(expected_length):
-            if row + i >= len(grid):
-                return word + "TRUNCATED"
-            word += grid[row + i][col]
-    
-    return word
-
-def check_numbering_consistency(clues):
-    """Check if clue numbering is consistent and logical."""
-    
-    print("\nChecking numbering consistency:")
-    
-    numbers = [clue.get("number", -1) for clue in clues]
-    issues = []
-    
-    # Check for duplicate numbers
-    if len(numbers) != len(set(numbers)):
-        issues.append("Duplicate clue numbers found")
-    
-    # Check for missing numbers in sequence
-    if numbers:
-        min_num = min(numbers)
-        max_num = max(numbers)
-        expected = set(range(min_num, max_num + 1))
-        actual = set(numbers)
-        
-        if expected != actual:
-            missing = expected - actual
-            extra = actual - expected
-            if missing:
-                issues.append(f"Missing numbers: {sorted(missing)}")
-            if extra:
-                issues.append(f"Extra numbers: {sorted(extra)}")
-    
-    if issues:
-        print("  ❌ Numbering issues:")
-        for issue in issues:
-            print(f"    {issue}")
-    else:
-        print("  ✅ Numbering is consistent")
-
-def check_grid_word_alignment(grid, clues):
-    """Check if all words are properly aligned and don't create unintended extensions."""
-    
-    print("\nChecking grid word alignment:")
-    
-    # Find all letter sequences in the grid
-    horizontal_sequences = find_horizontal_sequences(grid)
-    vertical_sequences = find_vertical_sequences(grid)
-    
-    print(f"  Found {len(horizontal_sequences)} horizontal sequences")
-    print(f"  Found {len(vertical_sequences)} vertical sequences")
-    
-    # Check if each sequence corresponds to a clue
-    clue_words = {}
-    for clue in clues:
-        pos = clue.get("position", {})
-        key = (pos.get("row"), pos.get("col"), clue.get("direction"))
-        clue_words[key] = clue.get("word", "")
-    
-    issues = []
-    
-    # Check horizontal sequences
-    for seq in horizontal_sequences:
-        row, start_col, word = seq
-        key = (row, start_col, "across")
-        if key not in clue_words:
-            issues.append(f"Unaccounted horizontal sequence: '{word}' at ({row}, {start_col})")
-        elif clue_words[key] != word:
-            issues.append(f"Mismatch: clue says '{clue_words[key]}' but grid shows '{word}' at ({row}, {start_col})")
-    
-    # Check vertical sequences
-    for seq in vertical_sequences:
-        col, start_row, word = seq
-        key = (start_row, col, "down")
-        if key not in clue_words:
-            issues.append(f"Unaccounted vertical sequence: '{word}' at ({start_row}, {col})")
-        elif clue_words[key] != word:
-            issues.append(f"Mismatch: clue says '{clue_words[key]}' but grid shows '{word}' at ({start_row}, {col})")
-    
-    if issues:
-        print("  ❌ Alignment issues found:")
-        for issue in issues:
-            print(f"    {issue}")
-    else:
-        print("  ✅ All words are properly aligned")
-
-def find_horizontal_sequences(grid):
-    """Find all horizontal letter sequences of length > 1."""
-    sequences = []
-    
-    for r in range(len(grid)):
-        current_word = ""
-        start_col = None
-        
-        for c in range(len(grid[0])):
-            if grid[r][c] != ".":
-                if start_col is None:
-                    start_col = c
-                current_word += grid[r][c]
-            else:
-                if current_word and len(current_word) > 1:
-                    sequences.append((r, start_col, current_word))
-                current_word = ""
-                start_col = None
-        
-        # Handle word at end of row
-        if current_word and len(current_word) > 1:
-            sequences.append((r, start_col, current_word))
-    
-    return sequences
-
-def find_vertical_sequences(grid):
-    """Find all vertical letter sequences of length > 1."""
-    sequences = []
-    
-    for c in range(len(grid[0])):
-        current_word = ""
-        start_row = None
-        
-        for r in range(len(grid)):
-            if grid[r][c] != ".":
-                if start_row is None:
-                    start_row = r
-                current_word += grid[r][c]
-            else:
-                if current_word and len(current_word) > 1:
-                    sequences.append((c, start_row, current_word))
-                current_word = ""
-                start_row = None
-        
-        # Handle word at end of column
-        if current_word and len(current_word) > 1:
-            sequences.append((c, start_row, current_word))
-    
-    return sequences
-
-if __name__ == "__main__":
-    asyncio.run(debug_complete_generation())

crossword-app/backend-py/debug_grid_direct.py

@@ -1,293 +0,0 @@
-#!/usr/bin/env python3
-"""
-Direct grid generation test to identify word boundary/display issues.
-"""
-
-import sys
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-
-def test_direct_grid_generation():
-    """Test grid generation directly with controlled words."""
-    
-    print("🔍 Direct Grid Generation Test\n")
-    
-    generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    # Test words that might cause the issues seen in the images
-    test_words = [
-        {"word": "MACHINE", "clue": "Device with moving parts"},
-        {"word": "COMPUTER", "clue": "Electronic device"}, 
-        {"word": "EXPERT", "clue": "Person with specialized knowledge"},
-        {"word": "SCIENCE", "clue": "Systematic study"},
-        {"word": "CAMERA", "clue": "Device for taking photos"},
-        {"word": "METHOD", "clue": "Systematic approach"}
-    ]
-    
-    print("=" * 60)
-    print("TEST 1: Direct grid creation")
-    print("=" * 60)
-    
-    # Test the _create_grid method directly
-    result = generator._create_grid(test_words)
-    
-    if result:
-        print("✅ Grid generation successful!")
-        
-        grid = result["grid"]
-        placed_words = result["placed_words"]
-        clues = result["clues"]
-        
-        print(f"Grid size: {len(grid)}x{len(grid[0])}")
-        print(f"Words placed: {len(placed_words)}")
-        print(f"Clues generated: {len(clues)}")
-        
-        # Print the grid
-        print("\nGenerated Grid:")
-        print_grid_with_coordinates(grid)
-        
-        # Print placed words details
-        print("\nPlaced Words:")
-        for i, word_info in enumerate(placed_words):
-            print(f"  {i+1}. {word_info['word']} at ({word_info['row']}, {word_info['col']}) {word_info['direction']}")
-        
-        # Print clues
-        print("\nGenerated Clues:")
-        for clue in clues:
-            print(f"  {clue['number']}. {clue['direction']}: {clue['word']} - {clue['text']}")
-        
-        # Analyze for potential issues
-        print("\n" + "=" * 60)
-        print("ANALYSIS")
-        print("=" * 60)
-        
-        analyze_grid_issues(grid, placed_words, clues)
-    
-    else:
-        print("❌ Grid generation failed")
-    
-    # Test another scenario that might reproduce the image issues
-    print("\n" + "=" * 60)
-    print("TEST 2: Scenario with potential extension words")
-    print("=" * 60)
-    
-    # Words that might create the "MACHINERY" type issue
-    extension_words = [
-        {"word": "MACHINE", "clue": "Device with moving parts"},
-        {"word": "MACHINERY", "clue": "Mechanical equipment"},  # Might cause confusion
-        {"word": "EXPERT", "clue": "Specialist"},
-        {"word": "TECHNOLOGY", "clue": "Applied science"},
-    ]
-    
-    result2 = generator._create_grid(extension_words)
-    
-    if result2:
-        print("✅ Extension test grid generated!")
-        
-        grid2 = result2["grid"]
-        placed_words2 = result2["placed_words"]
-        
-        print("\nExtension Test Grid:")
-        print_grid_with_coordinates(grid2)
-        
-        print("\nPlaced Words:")
-        for i, word_info in enumerate(placed_words2):
-            print(f"  {i+1}. {word_info['word']} at ({word_info['row']}, {word_info['col']}) {word_info['direction']}")
-        
-        # Check specifically for MACHINE vs MACHINERY issues
-        check_machine_machinery_issue(grid2, placed_words2)
-    
-    else:
-        print("❌ Extension test grid generation failed")
-
-def print_grid_with_coordinates(grid):
-    """Print grid with row and column coordinates."""
-    if not grid:
-        print("  Empty grid")
-        return
-    
-    # Print column headers
-    print("     ", end="")
-    for c in range(len(grid[0])):
-        print(f"{c:2d}", end="")
-    print()
-    
-    # Print rows
-    for r in range(len(grid)):
-        print(f" {r:2d}: ", end="")
-        for c in range(len(grid[0])):
-            cell = grid[r][c]
-            if cell == ".":
-                print(" .", end="")
-            else:
-                print(f" {cell}", end="")
-        print()
-
-def analyze_grid_issues(grid, placed_words, clues):
-    """Analyze the grid for potential boundary/display issues."""
-    
-    print("Checking for potential issues...")
-    
-    issues = []
-    
-    # Check 1: Verify each placed word actually exists in the grid
-    for word_info in placed_words:
-        word = word_info["word"]
-        row = word_info["row"]
-        col = word_info["col"]
-        direction = word_info["direction"]
-        
-        grid_word = extract_word_from_grid(grid, row, col, direction, len(word))
-        
-        if grid_word != word:
-            issues.append(f"Word mismatch: '{word}' expected at ({row},{col}) {direction}, but grid shows '{grid_word}'")
-    
-    # Check 2: Look for unintended letter sequences
-    all_sequences = find_all_letter_sequences(grid)
-    intended_words = {(w["row"], w["col"], w["direction"]): w["word"] for w in placed_words}
-    
-    for seq_info in all_sequences:
-        row, col, direction, seq_word = seq_info
-        key = (row, col, direction)
-        
-        if key not in intended_words:
-            if len(seq_word) > 1:  # Only care about multi-letter sequences
-                issues.append(f"Unintended sequence: '{seq_word}' at ({row},{col}) {direction}")
-        elif intended_words[key] != seq_word:
-            issues.append(f"Sequence mismatch: expected '{intended_words[key]}' but found '{seq_word}' at ({row},{col}) {direction}")
-    
-    # Check 3: Verify clue consistency
-    for clue in clues:
-        clue_word = clue["word"]
-        pos = clue["position"]
-        clue_row = pos["row"]
-        clue_col = pos["col"]
-        clue_direction = clue["direction"]
-        
-        # Convert direction format if needed
-        direction_map = {"across": "horizontal", "down": "vertical"}
-        normalized_direction = direction_map.get(clue_direction, clue_direction)
-        
-        grid_word = extract_word_from_grid(grid, clue_row, clue_col, normalized_direction, len(clue_word))
-        
-        if grid_word != clue_word:
-            issues.append(f"Clue mismatch: clue says '{clue_word}' at ({clue_row},{clue_col}) {clue_direction}, but grid shows '{grid_word}'")
-    
-    # Report results
-    if issues:
-        print("❌ Issues found:")
-        for issue in issues:
-            print(f"  {issue}")
-    else:
-        print("✅ No issues detected - grid appears consistent")
-
-def extract_word_from_grid(grid, row, col, direction, expected_length):
-    """Extract word from grid at given position and direction."""
-    if row >= len(grid) or col >= len(grid[0]) or row < 0 or col < 0:
-        return "OUT_OF_BOUNDS"
-    
-    word = ""
-    
-    if direction in ["horizontal", "across"]:
-        for i in range(expected_length):
-            if col + i >= len(grid[0]):
-                return word + "[TRUNCATED]"
-            word += grid[row][col + i]
-    elif direction in ["vertical", "down"]:
-        for i in range(expected_length):
-            if row + i >= len(grid):
-                return word + "[TRUNCATED]"
-            word += grid[row + i][col]
-    
-    return word
-
-def find_all_letter_sequences(grid):
-    """Find all letter sequences (horizontal and vertical) in the grid."""
-    sequences = []
-    
-    # Horizontal sequences
-    for r in range(len(grid)):
-        current_word = ""
-        start_col = None
-        
-        for c in range(len(grid[0])):
-            if grid[r][c] != ".":
-                if start_col is None:
-                    start_col = c
-                current_word += grid[r][c]
-            else:
-                if current_word and len(current_word) > 1:
-                    sequences.append((r, start_col, "horizontal", current_word))
-                current_word = ""
-                start_col = None
-        
-        # Handle end of row
-        if current_word and len(current_word) > 1:
-            sequences.append((r, start_col, "horizontal", current_word))
-    
-    # Vertical sequences
-    for c in range(len(grid[0])):
-        current_word = ""
-        start_row = None
-        
-        for r in range(len(grid)):
-            if grid[r][c] != ".":
-                if start_row is None:
-                    start_row = r
-                current_word += grid[r][c]
-            else:
-                if current_word and len(current_word) > 1:
-                    sequences.append((start_row, c, "vertical", current_word))
-                current_word = ""
-                start_row = None
-        
-        # Handle end of column
-        if current_word and len(current_word) > 1:
-            sequences.append((start_row, c, "vertical", current_word))
-    
-    return sequences
-
-def check_machine_machinery_issue(grid, placed_words):
-    """Specifically check for MACHINE vs MACHINERY confusion."""
-    
-    print("\nChecking for MACHINE/MACHINERY issue:")
-    
-    machine_words = [w for w in placed_words if "MACHINE" in w["word"]]
-    
-    if not machine_words:
-        print("  No MACHINE-related words found")
-        return
-    
-    for word_info in machine_words:
-        word = word_info["word"]
-        row = word_info["row"]
-        col = word_info["col"]
-        direction = word_info["direction"]
-        
-        print(f"  Found: '{word}' at ({row},{col}) {direction}")
-        
-        # Check what's actually in the grid at this location
-        grid_word = extract_word_from_grid(grid, row, col, direction, len(word))
-        print(f"    Grid shows: '{grid_word}'")
-        
-        # Check if there are extra letters that might create confusion
-        if direction == "horizontal":
-            # Check for letters after the word
-            end_col = col + len(word)
-            if end_col < len(grid[0]) and grid[row][end_col] != ".":
-                extra_letters = ""
-                check_col = end_col
-                while check_col < len(grid[0]) and grid[row][check_col] != ".":
-                    extra_letters += grid[row][check_col]
-                    check_col += 1
-                if extra_letters:
-                    print(f"    ⚠️ Extra letters after word: '{extra_letters}'")
-                    print(f"    This might make '{word}' appear as '{word + extra_letters}'")
-
-if __name__ == "__main__":
-    test_direct_grid_generation()

crossword-app/backend-py/debug_index_error.py

@@ -1,307 +0,0 @@
-#!/usr/bin/env python3
-"""
-Debug the recurring index error by adding comprehensive bounds checking.
-"""
-
-import asyncio
-import sys
-import logging
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-from src.services.vector_search import VectorSearchService
-
-# Enable debug logging
-logging.basicConfig(level=logging.DEBUG)
-logger = logging.getLogger(__name__)
-
-class DebugCrosswordGenerator(CrosswordGeneratorFixed):
-    """Debug version with comprehensive bounds checking."""
-    
-    def _can_place_word(self, grid, word, row, col, direction):
-        """Enhanced _can_place_word with comprehensive bounds checking."""
-        try:
-            size = len(grid)
-            logger.debug(f"_can_place_word: word={word}, row={row}, col={col}, direction={direction}, grid_size={size}")
-            
-            # Check initial boundaries
-            if row < 0 or col < 0 or row >= size or col >= size:
-                logger.debug(f"Initial bounds check failed: row={row}, col={col}, size={size}")
-                return False
-            
-            if direction == "horizontal":
-                if col + len(word) > size:
-                    logger.debug(f"Horizontal bounds check failed: col+len(word)={col + len(word)} > size={size}")
-                    return False
-                
-                # Check word boundaries (no adjacent letters) - with bounds check
-                if col > 0:
-                    if row >= size or col - 1 >= size or row < 0 or col - 1 < 0:
-                        logger.debug(f"Horizontal left boundary check failed: row={row}, col-1={col-1}, size={size}")
-                        return False
-                    if grid[row][col - 1] != ".":
-                        logger.debug(f"Horizontal left boundary has adjacent letter")
-                        return False
-                
-                if col + len(word) < size:
-                    if row >= size or col + len(word) >= size or row < 0 or col + len(word) < 0:
-                        logger.debug(f"Horizontal right boundary check failed: row={row}, col+len={col + len(word)}, size={size}")
-                        return False
-                    if grid[row][col + len(word)] != ".":
-                        logger.debug(f"Horizontal right boundary has adjacent letter")
-                        return False
-                
-                # Check each letter position
-                for i, letter in enumerate(word):
-                    check_row = row
-                    check_col = col + i
-                    if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                        logger.debug(f"Horizontal letter position check failed: letter {i}, row={check_row}, col={check_col}, size={size}")
-                        return False
-                    current_cell = grid[check_row][check_col]
-                    if current_cell != "." and current_cell != letter:
-                        logger.debug(f"Horizontal letter conflict: expected {letter}, found {current_cell}")
-                        return False
-            
-            else:  # vertical
-                if row + len(word) > size:
-                    logger.debug(f"Vertical bounds check failed: row+len(word)={row + len(word)} > size={size}")
-                    return False
-                
-                # Check word boundaries - with bounds check
-                if row > 0:
-                    if row - 1 >= size or col >= size or row - 1 < 0 or col < 0:
-                        logger.debug(f"Vertical top boundary check failed: row-1={row-1}, col={col}, size={size}")
-                        return False
-                    if grid[row - 1][col] != ".":
-                        logger.debug(f"Vertical top boundary has adjacent letter")
-                        return False
-                
-                if row + len(word) < size:
-                    if row + len(word) >= size or col >= size or row + len(word) < 0 or col < 0:
-                        logger.debug(f"Vertical bottom boundary check failed: row+len={row + len(word)}, col={col}, size={size}")
-                        return False
-                    if grid[row + len(word)][col] != ".":
-                        logger.debug(f"Vertical bottom boundary has adjacent letter")
-                        return False
-                
-                # Check each letter position
-                for i, letter in enumerate(word):
-                    check_row = row + i
-                    check_col = col
-                    if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                        logger.debug(f"Vertical letter position check failed: letter {i}, row={check_row}, col={check_col}, size={size}")
-                        return False
-                    current_cell = grid[check_row][check_col]
-                    if current_cell != "." and current_cell != letter:
-                        logger.debug(f"Vertical letter conflict: expected {letter}, found {current_cell}")
-                        return False
-            
-            logger.debug(f"_can_place_word: SUCCESS for word={word}")
-            return True
-            
-        except Exception as e:
-            logger.error(f"❌ ERROR in _can_place_word: {e}")
-            logger.error(f"   word={word}, row={row}, col={col}, direction={direction}")
-            logger.error(f"   grid_size={len(grid) if grid else 'None'}")
-            import traceback
-            traceback.print_exc()
-            return False
-    
-    def _place_word(self, grid, word, row, col, direction):
-        """Enhanced _place_word with comprehensive bounds checking."""
-        try:
-            size = len(grid)
-            logger.debug(f"_place_word: word={word}, row={row}, col={col}, direction={direction}, grid_size={size}")
-            
-            original_state = []
-            
-            if direction == "horizontal":
-                for i, letter in enumerate(word):
-                    check_row = row
-                    check_col = col + i
-                    if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                        logger.error(f"❌ _place_word horizontal bounds error: row={check_row}, col={check_col}, size={size}")
-                        raise IndexError(f"Grid index out of range: [{check_row}][{check_col}] in grid of size {size}")
-                    
-                    original_state.append({
-                        "row": check_row,
-                        "col": check_col,
-                        "value": grid[check_row][check_col]
-                    })
-                    grid[check_row][check_col] = letter
-            else:
-                for i, letter in enumerate(word):
-                    check_row = row + i
-                    check_col = col
-                    if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                        logger.error(f"❌ _place_word vertical bounds error: row={check_row}, col={check_col}, size={size}")
-                        raise IndexError(f"Grid index out of range: [{check_row}][{check_col}] in grid of size {size}")
-                    
-                    original_state.append({
-                        "row": check_row,
-                        "col": check_col,
-                        "value": grid[check_row][check_col]
-                    })
-                    grid[check_row][check_col] = letter
-            
-            logger.debug(f"_place_word: SUCCESS for word={word}")
-            return original_state
-            
-        except Exception as e:
-            logger.error(f"❌ ERROR in _place_word: {e}")
-            logger.error(f"   word={word}, row={row}, col={col}, direction={direction}")
-            logger.error(f"   grid_size={len(grid) if grid else 'None'}")
-            import traceback
-            traceback.print_exc()
-            raise
-    
-    def _remove_word(self, grid, original_state):
-        """Enhanced _remove_word with comprehensive bounds checking."""
-        try:
-            size = len(grid)
-            logger.debug(f"_remove_word: restoring {len(original_state)} positions, grid_size={size}")
-            
-            for state in original_state:
-                check_row = state["row"]
-                check_col = state["col"]
-                if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                    logger.error(f"❌ _remove_word bounds error: row={check_row}, col={check_col}, size={size}")
-                    raise IndexError(f"Grid index out of range: [{check_row}][{check_col}] in grid of size {size}")
-                
-                grid[check_row][check_col] = state["value"]
-            
-            logger.debug(f"_remove_word: SUCCESS")
-            
-        except Exception as e:
-            logger.error(f"❌ ERROR in _remove_word: {e}")
-            logger.error(f"   grid_size={len(grid) if grid else 'None'}")
-            logger.error(f"   original_state={original_state}")
-            import traceback
-            traceback.print_exc()
-            raise
-    
-    def _create_simple_cross(self, word_list, word_objs):
-        """Enhanced _create_simple_cross with comprehensive bounds checking."""
-        try:
-            logger.debug(f"_create_simple_cross: words={word_list}")
-            
-            if len(word_list) < 2:
-                logger.debug("Not enough words for simple cross")
-                return None
-            
-            word1, word2 = word_list[0], word_list[1]
-            intersections = self._find_word_intersections(word1, word2)
-            
-            if not intersections:
-                logger.debug("No intersections found")
-                return None
-            
-            # Use first intersection
-            intersection = intersections[0]
-            size = max(len(word1), len(word2)) + 4
-            logger.debug(f"Creating grid of size {size} for simple cross")
-            
-            grid = [["." for _ in range(size)] for _ in range(size)]
-            
-            # Place first word horizontally in center
-            center_row = size // 2
-            center_col = (size - len(word1)) // 2
-            
-            logger.debug(f"Placing word1 '{word1}' at row={center_row}, col={center_col}")
-            
-            for i, letter in enumerate(word1):
-                check_row = center_row
-                check_col = center_col + i
-                if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                    logger.error(f"❌ _create_simple_cross word1 bounds error: row={check_row}, col={check_col}, size={size}")
-                    raise IndexError(f"Grid index out of range: [{check_row}][{check_col}] in grid of size {size}")
-                grid[check_row][check_col] = letter
-            
-            # Place second word vertically at intersection
-            intersection_col = center_col + intersection["word_pos"]
-            word2_start_row = center_row - intersection["placed_pos"]
-            
-            logger.debug(f"Placing word2 '{word2}' at row={word2_start_row}, col={intersection_col}")
-            
-            for i, letter in enumerate(word2):
-                check_row = word2_start_row + i
-                check_col = intersection_col
-                if check_row >= size or check_col >= size or check_row < 0 or check_col < 0:
-                    logger.error(f"❌ _create_simple_cross word2 bounds error: row={check_row}, col={check_col}, size={size}")
-                    raise IndexError(f"Grid index out of range: [{check_row}][{check_col}] in grid of size {size}")
-                grid[check_row][check_col] = letter
-            
-            placed_words = [
-                {"word": word1, "row": center_row, "col": center_col, "direction": "horizontal", "number": 1},
-                {"word": word2, "row": word2_start_row, "col": intersection_col, "direction": "vertical", "number": 2}
-            ]
-            
-            logger.debug(f"_create_simple_cross: SUCCESS")
-            
-            trimmed = self._trim_grid(grid, placed_words)
-            clues = self._generate_clues(word_objs[:2], trimmed["placed_words"])
-            
-            return {
-                "grid": trimmed["grid"],
-                "placed_words": trimmed["placed_words"],
-                "clues": clues
-            }
-            
-        except Exception as e:
-            logger.error(f"❌ ERROR in _create_simple_cross: {e}")
-            import traceback
-            traceback.print_exc()
-            raise
-
-async def test_debug_generator():
-    """Test the debug generator to catch index errors."""
-    try:
-        print("🧪 Testing debug crossword generator...")
-        
-        # Create mock vector service
-        vector_service = VectorSearchService()
-        
-        # Create debug generator
-        generator = DebugCrosswordGenerator(vector_service)
-        
-        # Test with various topics and difficulties
-        test_cases = [
-            (["animals"], "medium"),
-            (["science"], "hard"),
-            (["technology"], "easy"),
-            (["animals", "science"], "medium"),
-        ]
-        
-        for i, (topics, difficulty) in enumerate(test_cases):
-            print(f"\n🔬 Test {i+1}: topics={topics}, difficulty={difficulty}")
-            try:
-                result = await generator.generate_puzzle(topics, difficulty, use_ai=False)
-                if result:
-                    print(f"✅ Test {i+1} succeeded")
-                    grid_size = len(result['grid'])
-                    word_count = len(result['clues'])
-                    print(f"   Grid: {grid_size}x{grid_size}, Words: {word_count}")
-                else:
-                    print(f"⚠️ Test {i+1} returned None")
-            except Exception as e:
-                print(f"❌ Test {i+1} failed: {e}")
-                import traceback
-                traceback.print_exc()
-                return False
-        
-        print(f"\n✅ All debug tests completed!")
-        return True
-        
-    except Exception as e:
-        print(f"❌ Debug test setup failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-if __name__ == "__main__":
-    asyncio.run(test_debug_generator())

crossword-app/backend-py/debug_simple.py

@@ -1,142 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple debug test for crossword generator index errors.
-"""
-
-import asyncio
-import sys
-import logging
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-
-# Enable debug logging
-logging.basicConfig(level=logging.DEBUG)
-logger = logging.getLogger(__name__)
-
-async def test_with_static_words():
-    """Test generator with static word lists."""
-    
-    # Create generator without vector service
-    generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    # Create test words
-    test_words = [
-        {"word": "CAT", "clue": "Feline pet"},
-        {"word": "DOG", "clue": "Man's best friend"}, 
-        {"word": "BIRD", "clue": "Flying animal"},
-        {"word": "FISH", "clue": "Aquatic animal"},
-        {"word": "ELEPHANT", "clue": "Large mammal"},
-        {"word": "TIGER", "clue": "Striped cat"},
-        {"word": "HORSE", "clue": "Riding animal"},
-        {"word": "BEAR", "clue": "Large carnivore"}
-    ]
-    
-    print(f"🧪 Testing crossword generation with {len(test_words)} words...")
-    
-    try:
-        # Test multiple times to catch intermittent errors
-        for attempt in range(10):
-            print(f"\n🔬 Attempt {attempt + 1}/10")
-            
-            # Shuffle words to create different scenarios
-            import random
-            random.shuffle(test_words)
-            
-            # Override the word selection to use our test words
-            generator._select_words = lambda topics, difficulty, use_ai: test_words
-            
-            result = await generator.generate_puzzle(["animals"], "medium", use_ai=False)
-            
-            if result:
-                grid_size = len(result['grid'])
-                word_count = len(result['clues'])
-                print(f"✅ Attempt {attempt + 1} succeeded: {grid_size}x{grid_size} grid, {word_count} words")
-            else:
-                print(f"⚠️ Attempt {attempt + 1} returned None")
-                
-    except IndexError as e:
-        print(f"❌ INDEX ERROR caught on attempt {attempt + 1}: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-    except Exception as e:
-        print(f"❌ Other error on attempt {attempt + 1}: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-    
-    print(f"\n✅ All 10 attempts completed successfully!")
-    return True
-
-async def test_grid_placement_directly():
-    """Test grid placement functions directly with problematic data."""
-    
-    generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    # Test data that might cause issues
-    test_cases = [
-        {
-            "words": ["A", "I"],  # Very short words
-            "description": "Very short words"
-        },
-        {
-            "words": ["VERYLONGWORDTHATMIGHTCAUSEISSUES", "SHORT"],
-            "description": "Very long word with short word"
-        },
-        {
-            "words": ["ABCDEFGHIJKLMNOP", "QRSTUVWXYZ"],  # Long words
-            "description": "Two long words"
-        },
-        {
-            "words": ["TEST", "SETS", "NETS", "PETS"],  # Multiple similar words
-            "description": "Similar words with same endings"
-        }
-    ]
-    
-    for i, test_case in enumerate(test_cases):
-        print(f"\n🔬 Grid test {i+1}: {test_case['description']}")
-        
-        try:
-            word_list = test_case["words"]
-            word_objs = [{"word": w, "clue": f"Clue for {w}"} for w in word_list]
-            
-            result = generator._create_grid(word_objs)
-            
-            if result:
-                grid_size = len(result['grid'])
-                word_count = len(result['placed_words'])
-                print(f"✅ Grid test {i+1} succeeded: {grid_size}x{grid_size} grid, {word_count} words")
-            else:
-                print(f"⚠️ Grid test {i+1} returned None")
-                
-        except IndexError as e:
-            print(f"❌ INDEX ERROR in grid test {i+1}: {e}")
-            import traceback
-            traceback.print_exc()
-            return False
-        except Exception as e:
-            print(f"❌ Other error in grid test {i+1}: {e}")
-            import traceback
-            traceback.print_exc()
-            return False
-    
-    return True
-
-if __name__ == "__main__":
-    print("🧪 Starting debug tests for crossword generator...")
-    
-    async def run_tests():
-        success1 = await test_with_static_words()
-        success2 = await test_grid_placement_directly()
-        
-        if success1 and success2:
-            print("\n🎉 All debug tests passed! No index errors detected.")
-        else:
-            print("\n❌ Some debug tests failed.")
-    
-    asyncio.run(run_tests())

crossword-app/backend-py/public/assets/index-2XJqMaqu.js

@@ -0,0 +1,10 @@
+import{r as p,a as C,R as P}from"./vendor-nf7bT_Uh.js";(function(){const a=document.createElement("link").relList;if(a&&a.supports&&a.supports("modulepreload"))return;for(const t of document.querySelectorAll('link[rel="modulepreload"]'))n(t);new MutationObserver(t=>{for(const r of t)if(r.type==="childList")for(const o of r.addedNodes)o.tagName==="LINK"&&o.rel==="modulepreload"&&n(o)}).observe(document,{childList:!0,subtree:!0});function c(t){const r={};return t.integrity&&(r.integrity=t.integrity),t.referrerPolicy&&(r.referrerPolicy=t.referrerPolicy),t.crossOrigin==="use-credentials"?r.credentials="include":t.crossOrigin==="anonymous"?r.credentials="omit":r.credentials="same-origin",r}function n(t){if(t.ep)return;t.ep=!0;const r=c(t);fetch(t.href,r)}})();var w={exports:{}},z={};/**
+ * @license React
+ * react-jsx-runtime.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */var R=p,_=Symbol.for("react.element"),$=Symbol.for("react.fragment"),E=Object.prototype.hasOwnProperty,O=R.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,k={key:!0,ref:!0,__self:!0,__source:!0};function S(s,a,c){var n,t={},r=null,o=null;c!==void 0&&(r=""+c),a.key!==void 0&&(r=""+a.key),a.ref!==void 0&&(o=a.ref);for(n in a)E.call(a,n)&&!k.hasOwnProperty(n)&&(t[n]=a[n]);if(s&&s.defaultProps)for(n in a=s.defaultProps,a)t[n]===void 0&&(t[n]=a[n]);return{$$typeof:_,type:s,key:r,ref:o,props:t,_owner:O.current}}z.Fragment=$;z.jsx=S;z.jsxs=S;w.exports=z;var e=w.exports,N={},b=C;N.createRoot=b.createRoot,N.hydrateRoot=b.hydrateRoot;const T=({onTopicsChange:s,availableTopics:a=[],selectedTopics:c=[]})=>{const n=t=>{const r=c.includes(t)?c.filter(o=>o!==t):[...c,t];s(r)};return e.jsxs("div",{className:"topic-selector",children:[e.jsx("h3",{children:"Select Topics"}),e.jsx("div",{className:"topic-buttons",children:a.map(t=>e.jsx("button",{className:`topic-btn ${c.includes(t.name)?"selected":""}`,onClick:()=>n(t.name),children:t.name},t.id))}),e.jsxs("p",{className:"selected-count",children:[c.length," topic",c.length!==1?"s":""," selected"]})]})},L=({grid:s,clues:a,showSolution:c,onCellChange:n})=>{const[t,r]=p.useState({}),o=(u,l,i)=>{const d=`${u}-${l}`,h={...t,[d]:i.toUpperCase()};r(h),n&&n(u,l,i)},f=(u,l)=>{if(c&&!m(u,l))return s[u][l];const i=`${u}-${l}`;return t[i]||""},m=(u,l)=>s[u][l]===".",g=(u,l)=>{if(!a)return null;const i=a.find(d=>d.position.row===u&&d.position.col===l);return i?i.number:null};if(!s||s.length===0)return e.jsx("div",{className:"puzzle-grid",children:"No puzzle loaded"});const x=s.length,y=s[0]?s[0].length:0;return e.jsx("div",{className:"puzzle-container",children:e.jsx("div",{className:"puzzle-grid",style:{gridTemplateColumns:`repeat(${y}, 35px)`,gridTemplateRows:`repeat(${x}, 35px)`},children:s.map((u,l)=>u.map((i,d)=>{const h=g(l,d);return m(l,d)?e.jsx("div",{className:"grid-cell empty-cell",style:{visibility:"hidden"}},`${l}-${d}`):e.jsxs("div",{className:"grid-cell white-cell",children:[h&&e.jsx("span",{className:"cell-number",children:h}),e.jsx("input",{type:"text",maxLength:"1",value:f(l,d),onChange:v=>o(l,d,v.target.value),className:`cell-input ${c?"solution-text":""}`,disabled:c})]},`${l}-${d}`)}))})})},A=({clues:s=[]})=>{const a=s.filter(t=>t.direction==="across"),c=s.filter(t=>t.direction==="down"),n=({title:t,clueList:r})=>e.jsxs("div",{className:"clue-section",children:[e.jsx("h4",{children:t}),e.jsx("ol",{children:r.map(o=>e.jsxs("li",{className:"clue-item",children:[e.jsx("span",{className:"clue-number",children:o.number}),e.jsx("span",{className:"clue-text",children:o.text})]},`${o.number}-${o.direction}`))})]});return e.jsxs("div",{className:"clue-list",children:[e.jsx(n,{title:"Across",clueList:a}),e.jsx(n,{title:"Down",clueList:c})]})},D=({message:s="Generating puzzle..."})=>e.jsxs("div",{className:"loading-spinner",children:[e.jsx("div",{className:"spinner"}),e.jsx("p",{className:"loading-message",children:s})]}),F=()=>{const[s,a]=p.useState(null),[c,n]=p.useState(!1),[t,r]=p.useState(null),[o,f]=p.useState([]),m="",g=p.useCallback(async()=>{try{n(!0);const l=await fetch(`${m}/api/topics`);if(!l.ok)throw new Error("Failed to fetch topics");const i=await l.json();f(i)}catch(l){r(l.message)}finally{n(!1)}},[m]),x=p.useCallback(async(l,i="medium",d=!1)=>{try{n(!0),r(null);const h=await fetch(`${m}/api/generate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({topics:l,difficulty:i,useAI:d})});if(!h.ok){const v=await h.json().catch(()=>({}));throw new Error(v.message||"Failed to generate puzzle")}const j=await h.json();return a(j),j}catch(h){return r(h.message),null}finally{n(!1)}},[m]),y=p.useCallback(async l=>{try{const i=await fetch(`${m}/api/validate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({puzzle:s,answers:l})});if(!i.ok)throw new Error("Failed to validate answers");return await i.json()}catch(i){return r(i.message),null}},[m,s]),u=p.useCallback(()=>{a(null),r(null)},[]);return{puzzle:s,loading:c,error:t,topics:o,fetchTopics:g,generatePuzzle:x,validateAnswers:y,resetPuzzle:u}};function G(){const[s,a]=p.useState([]),[c,n]=p.useState("medium"),[t,r]=p.useState(!1),{puzzle:o,loading:f,error:m,topics:g,fetchTopics:x,generatePuzzle:y,resetPuzzle:u}=F();p.useEffect(()=>{x()},[x]);const l=async()=>{if(s.length===0){alert("Please select at least one topic");return}await y(s,c,!1)},i=j=>{a(j)},d=()=>{u(),a([]),r(!1),n("medium")},h=()=>{r(!0)};return e.jsxs("div",{className:"crossword-app",children:[e.jsxs("header",{className:"app-header",children:[e.jsx("h1",{className:"app-title",children:"Crossword Puzzle Generator"}),e.jsx("p",{children:"Select topics and generate your custom crossword puzzle!"})]}),e.jsx(T,{onTopicsChange:i,availableTopics:g,selectedTopics:s}),e.jsxs("div",{className:"puzzle-controls",children:[e.jsxs("select",{value:c,onChange:j=>n(j.target.value),className:"control-btn",children:[e.jsx("option",{value:"easy",children:"Easy"}),e.jsx("option",{value:"medium",children:"Medium"}),e.jsx("option",{value:"hard",children:"Hard"})]}),e.jsx("button",{onClick:l,disabled:f||s.length===0,className:"control-btn generate-btn",children:f?"Generating...":"Generate Puzzle"}),e.jsx("button",{onClick:d,className:"control-btn reset-btn",children:"Reset"}),o&&!t&&e.jsx("button",{onClick:h,className:"control-btn reveal-btn",children:"Reveal Solution"})]}),m&&e.jsxs("div",{className:"error-message",children:["Error: ",m]}),f&&e.jsx(D,{}),o&&!f&&e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"puzzle-info",children:e.jsxs("span",{className:"puzzle-stats",children:[o.metadata.wordCount," words • ",o.metadata.size,"×",o.metadata.size," grid"]})}),e.jsxs("div",{className:"puzzle-layout",children:[e.jsx(L,{grid:o.grid,clues:o.clues,showSolution:t}),e.jsx(A,{clues:o.clues})]})]}),!o&&!f&&!m&&e.jsx("div",{style:{textAlign:"center",padding:"40px",color:"#7f8c8d"},children:'Select topics and click "Generate Puzzle" to start!'})]})}N.createRoot(document.getElementById("root")).render(e.jsx(P.StrictMode,{children:e.jsx(G,{})}));
+//# sourceMappingURL=index-2XJqMaqu.js.map

crossword-app/backend-py/public/assets/index-2XJqMaqu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-2XJqMaqu.js","sources":["../../node_modules/react/cjs/react-jsx-runtime.production.min.js","../../node_modules/react/jsx-runtime.js","../../node_modules/react-dom/client.js","../../src/components/TopicSelector.jsx","../../src/components/PuzzleGrid.jsx","../../src/components/ClueList.jsx","../../src/components/LoadingSpinner.jsx","../../src/hooks/useCrossword.js","../../src/App.jsx","../../src/main.jsx"],"sourcesContent":["/**\n * @license React\n * react-jsx-runtime.production.min.js\n *\n * Copyright (c) Facebook, Inc. and its affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n'use strict';var f=require(\"react\"),k=Symbol.for(\"react.element\"),l=Symbol.for(\"react.fragment\"),m=Object.prototype.hasOwnProperty,n=f.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,p={key:!0,ref:!0,__self:!0,__source:!0};\nfunction q(c,a,g){var b,d={},e=null,h=null;void 0!==g&&(e=\"\"+g);void 0!==a.key&&(e=\"\"+a.key);void 0!==a.ref&&(h=a.ref);for(b in a)m.call(a,b)&&!p.hasOwnProperty(b)&&(d[b]=a[b]);if(c&&c.defaultProps)for(b in a=c.defaultProps,a)void 0===d[b]&&(d[b]=a[b]);return{$$typeof:k,type:c,key:e,ref:h,props:d,_owner:n.current}}exports.Fragment=l;exports.jsx=q;exports.jsxs=q;\n","'use strict';\n\nif (process.env.NODE_ENV === 'production') {\n  module.exports = require('./cjs/react-jsx-runtime.production.min.js');\n} else {\n  module.exports = require('./cjs/react-jsx-runtime.development.js');\n}\n","'use strict';\n\nvar m = require('react-dom');\nif (process.env.NODE_ENV === 'production') {\n  exports.createRoot = m.createRoot;\n  exports.hydrateRoot = m.hydrateRoot;\n} else {\n  var i = m.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;\n  exports.createRoot = function(c, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.createRoot(c, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n  exports.hydrateRoot = function(c, h, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.hydrateRoot(c, h, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n}\n","import React from 'react';\n\nconst TopicSelector = ({ \n  onTopicsChange, \n  availableTopics = [], \n  selectedTopics = []\n}) => {\n  const handleTopicToggle = (topic) => {\n    const newSelectedTopics = selectedTopics.includes(topic)\n      ? selectedTopics.filter(t => t !== topic)\n      : [...selectedTopics, topic];\n    \n    onTopicsChange(newSelectedTopics);\n  };\n\n  return (\n    <div className=\"topic-selector\">\n      <h3>Select Topics</h3>\n      <div className=\"topic-buttons\">\n        {availableTopics.map(topic => (\n          <button\n            key={topic.id}\n            className={`topic-btn ${selectedTopics.includes(topic.name) ? 'selected' : ''}`}\n            onClick={() => handleTopicToggle(topic.name)}\n          >\n            {topic.name}\n          </button>\n        ))}\n      </div>\n      \n      <p className=\"selected-count\">\n        {selectedTopics.length} topic{selectedTopics.length !== 1 ? 's' : ''} selected\n      </p>\n    </div>\n  );\n};\n\nexport default TopicSelector;","import React, { useState } from 'react';\n\nconst PuzzleGrid = ({ grid, clues, showSolution, onCellChange }) => {\n  const [userAnswers, setUserAnswers] = useState({});\n\n  const handleCellInput = (row, col, value) => {\n    const key = `${row}-${col}`;\n    const newAnswers = { ...userAnswers, [key]: value.toUpperCase() };\n    setUserAnswers(newAnswers);\n    onCellChange && onCellChange(row, col, value);\n  };\n\n  const getCellValue = (row, col) => {\n    if (showSolution && !isBlackCell(row, col)) {\n      return grid[row][col];\n    }\n    const key = `${row}-${col}`;\n    return userAnswers[key] || '';\n  };\n\n  const isBlackCell = (row, col) => {\n    return grid[row][col] === '.';\n  };\n\n  const getCellNumber = (row, col) => {\n    if (!clues) return null;\n    const clue = clues.find(c => c.position.row === row && c.position.col === col);\n    return clue ? clue.number : null;\n  };\n\n  if (!grid || grid.length === 0) {\n    return <div className=\"puzzle-grid\">No puzzle loaded</div>;\n  }\n\n  const gridRows = grid.length;\n  const gridCols = grid[0] ? grid[0].length : 0;\n\n  return (\n    <div className=\"puzzle-container\">\n      <div \n        className=\"puzzle-grid\"\n        style={{\n          gridTemplateColumns: `repeat(${gridCols}, 35px)`,\n          gridTemplateRows: `repeat(${gridRows}, 35px)`\n        }}\n      >\n        {grid.map((row, rowIndex) =>\n          row.map((cell, colIndex) => {\n            const cellNumber = getCellNumber(rowIndex, colIndex);\n            const isBlack = isBlackCell(rowIndex, colIndex);\n            \n            // Only render cells that contain letters (not black/unused cells)\n            if (isBlack) {\n              return (\n                <div\n                  key={`${rowIndex}-${colIndex}`}\n                  className=\"grid-cell empty-cell\"\n                  style={{ visibility: 'hidden' }}\n                >\n                </div>\n              );\n            }\n            \n            return (\n              <div\n                key={`${rowIndex}-${colIndex}`}\n                className=\"grid-cell white-cell\"\n              >\n                {cellNumber && <span className=\"cell-number\">{cellNumber}</span>}\n                <input\n                  type=\"text\"\n                  maxLength=\"1\"\n                  value={getCellValue(rowIndex, colIndex)}\n                  onChange={(e) => handleCellInput(rowIndex, colIndex, e.target.value)}\n                  className={`cell-input ${showSolution ? 'solution-text' : ''}`}\n                  disabled={showSolution}\n                />\n              </div>\n            );\n          })\n        )}\n      </div>\n    </div>\n  );\n};\n\nexport default PuzzleGrid;","import React from 'react';\n\nconst ClueList = ({ clues = [] }) => {\n  const acrossClues = clues.filter(clue => clue.direction === 'across');\n  const downClues = clues.filter(clue => clue.direction === 'down');\n\n  const ClueSection = ({ title, clueList }) => (\n    <div className=\"clue-section\">\n      <h4>{title}</h4>\n      <ol>\n        {clueList.map(clue => (\n          <li key={`${clue.number}-${clue.direction}`} className=\"clue-item\">\n            <span className=\"clue-number\">{clue.number}</span>\n            <span className=\"clue-text\">{clue.text}</span>\n          </li>\n        ))}\n      </ol>\n    </div>\n  );\n\n  return (\n    <div className=\"clue-list\">\n      <ClueSection title=\"Across\" clueList={acrossClues} />\n      <ClueSection title=\"Down\" clueList={downClues} />\n    </div>\n  );\n};\n\nexport default ClueList;","import React from 'react';\n\nconst LoadingSpinner = ({ message = \"Generating puzzle...\" }) => {\n  return (\n    <div className=\"loading-spinner\">\n      <div className=\"spinner\"></div>\n      <p className=\"loading-message\">{message}</p>\n    </div>\n  );\n};\n\nexport default LoadingSpinner;","import { useState, useCallback } from 'react';\n\nconst useCrossword = () => {\n  const [puzzle, setPuzzle] = useState(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n  const [topics, setTopics] = useState([]);\n\n  const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || (import.meta.env.PROD ? '' : 'http://localhost:3000');\n\n  const fetchTopics = useCallback(async () => {\n    try {\n      setLoading(true);\n      const response = await fetch(`${API_BASE_URL}/api/topics`);\n      if (!response.ok) throw new Error('Failed to fetch topics');\n      const data = await response.json();\n      setTopics(data);\n    } catch (err) {\n      setError(err.message);\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium', useAI = false) => {\n    try {\n      setLoading(true);\n      setError(null);\n      \n      const response = await fetch(`${API_BASE_URL}/api/generate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          topics: selectedTopics,\n          difficulty,\n          useAI\n        })\n      });\n\n      if (!response.ok) {\n        const errorData = await response.json().catch(() => ({}));\n        throw new Error(errorData.message || 'Failed to generate puzzle');\n      }\n      \n      const puzzleData = await response.json();\n      setPuzzle(puzzleData);\n      return puzzleData;\n    } catch (err) {\n      setError(err.message);\n      return null;\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const validateAnswers = useCallback(async (userAnswers) => {\n    try {\n      const response = await fetch(`${API_BASE_URL}/api/validate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          puzzle: puzzle,\n          answers: userAnswers\n        })\n      });\n\n      if (!response.ok) throw new Error('Failed to validate answers');\n      \n      return await response.json();\n    } catch (err) {\n      setError(err.message);\n      return null;\n    }\n  }, [API_BASE_URL, puzzle]);\n\n  const resetPuzzle = useCallback(() => {\n    setPuzzle(null);\n    setError(null);\n  }, []);\n\n  return {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    validateAnswers,\n    resetPuzzle\n  };\n};\n\nexport default useCrossword;","import React, { useState, useEffect } from 'react';\nimport TopicSelector from './components/TopicSelector';\nimport PuzzleGrid from './components/PuzzleGrid';\nimport ClueList from './components/ClueList';\nimport LoadingSpinner from './components/LoadingSpinner';\nimport useCrossword from './hooks/useCrossword';\nimport './styles/puzzle.css';\n\nfunction App() {\n  const [selectedTopics, setSelectedTopics] = useState([]);\n  const [difficulty, setDifficulty] = useState('medium');\n  const [showSolution, setShowSolution] = useState(false);\n  \n  const {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    resetPuzzle\n  } = useCrossword();\n\n  useEffect(() => {\n    fetchTopics();\n  }, [fetchTopics]);\n\n  const handleGeneratePuzzle = async () => {\n    if (selectedTopics.length === 0) {\n      alert('Please select at least one topic');\n      return;\n    }\n    \n    await generatePuzzle(selectedTopics, difficulty, false);\n  };\n\n  const handleTopicsChange = (topics) => {\n    setSelectedTopics(topics);\n  };\n\n\n  const handleReset = () => {\n    resetPuzzle();\n    setSelectedTopics([]);\n    setShowSolution(false);\n    setDifficulty('medium');\n  };\n\n  const handleRevealSolution = () => {\n    setShowSolution(true);\n  };\n\n  return (\n    <div className=\"crossword-app\">\n      <header className=\"app-header\">\n        <h1 className=\"app-title\">Crossword Puzzle Generator</h1>\n        <p>Select topics and generate your custom crossword puzzle!</p>\n      </header>\n\n      <TopicSelector \n        onTopicsChange={handleTopicsChange}\n        availableTopics={topics}\n        selectedTopics={selectedTopics}\n      />\n\n      <div className=\"puzzle-controls\">\n        <select \n          value={difficulty} \n          onChange={(e) => setDifficulty(e.target.value)}\n          className=\"control-btn\"\n        >\n          <option value=\"easy\">Easy</option>\n          <option value=\"medium\">Medium</option>\n          <option value=\"hard\">Hard</option>\n        </select>\n        \n        <button\n          onClick={handleGeneratePuzzle}\n          disabled={loading || selectedTopics.length === 0}\n          className=\"control-btn generate-btn\"\n        >\n          {loading ? 'Generating...' : 'Generate Puzzle'}\n        </button>\n        \n        <button\n          onClick={handleReset}\n          className=\"control-btn reset-btn\"\n        >\n          Reset\n        </button>\n        \n        {puzzle && !showSolution && (\n          <button\n            onClick={handleRevealSolution}\n            className=\"control-btn reveal-btn\"\n          >\n            Reveal Solution\n          </button>\n        )}\n      </div>\n\n      {error && (\n        <div className=\"error-message\">\n          Error: {error}\n        </div>\n      )}\n\n      {loading && <LoadingSpinner />}\n\n      {puzzle && !loading && (\n        <>\n          <div className=\"puzzle-info\">\n            <span className=\"puzzle-stats\">\n              {puzzle.metadata.wordCount} words • {puzzle.metadata.size}×{puzzle.metadata.size} grid\n            </span>\n          </div>\n          <div className=\"puzzle-layout\">\n            <PuzzleGrid \n              grid={puzzle.grid} \n              clues={puzzle.clues}\n              showSolution={showSolution}\n            />\n            <ClueList clues={puzzle.clues} />\n          </div>\n        </>\n      )}\n\n      {!puzzle && !loading && !error && (\n        <div style={{ textAlign: 'center', padding: '40px', color: '#7f8c8d' }}>\n          Select topics and click \"Generate Puzzle\" to start!\n        </div>\n      )}\n    </div>\n  );\n}\n\nexport default App;","import React from 'react'\nimport ReactDOM from 'react-dom/client'\nimport App from './App.jsx'\n\nReactDOM.createRoot(document.getElementById('root')).render(\n  <React.StrictMode>\n    <App />\n  </React.StrictMode>,\n)"],"names":["f","require$$0","k","l","m","n","p","q","c","g","b","d","e","h","reactJsxRuntime_production_min","jsxRuntimeModule","client","TopicSelector","onTopicsChange","availableTopics","selectedTopics","handleTopicToggle","topic","newSelectedTopics","t","jsxs","jsx","PuzzleGrid","grid","clues","showSolution","onCellChange","userAnswers","setUserAnswers","useState","handleCellInput","row","col","value","key","newAnswers","getCellValue","isBlackCell","getCellNumber","clue","gridRows","gridCols","rowIndex","cell","colIndex","cellNumber","ClueList","acrossClues","downClues","ClueSection","title","clueList","LoadingSpinner","message","useCrossword","puzzle","setPuzzle","loading","setLoading","error","setError","topics","setTopics","API_BASE_URL","fetchTopics","useCallback","response","data","err","generatePuzzle","difficulty","useAI","errorData","puzzleData","validateAnswers","resetPuzzle","App","setSelectedTopics","setDifficulty","setShowSolution","useEffect","handleGeneratePuzzle","handleTopicsChange","handleReset","handleRevealSolution","Fragment","ReactDOM","React"],"mappings":";;;;;;;;GASa,IAAIA,EAAEC,EAAiBC,EAAE,OAAO,IAAI,eAAe,EAAEC,EAAE,OAAO,IAAI,gBAAgB,EAAEC,EAAE,OAAO,UAAU,eAAeC,EAAEL,EAAE,mDAAmD,kBAAkBM,EAAE,CAAC,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,EAAE,EAClP,SAASC,EAAEC,EAAE,EAAEC,EAAE,CAAC,IAAIC,EAAEC,EAAE,GAAGC,EAAE,KAAKC,EAAE,KAAcJ,IAAT,SAAaG,EAAE,GAAGH,GAAY,EAAE,MAAX,SAAiBG,EAAE,GAAG,EAAE,KAAc,EAAE,MAAX,SAAiBC,EAAE,EAAE,KAAK,IAAIH,KAAK,EAAEN,EAAE,KAAK,EAAEM,CAAC,GAAG,CAACJ,EAAE,eAAeI,CAAC,IAAIC,EAAED,CAAC,EAAE,EAAEA,CAAC,GAAG,GAAGF,GAAGA,EAAE,aAAa,IAAIE,KAAK,EAAEF,EAAE,aAAa,EAAWG,EAAED,CAAC,aAAIC,EAAED,CAAC,EAAE,EAAEA,CAAC,GAAG,MAAM,CAAC,SAASR,EAAE,KAAKM,EAAE,IAAII,EAAE,IAAIC,EAAE,MAAMF,EAAE,OAAON,EAAE,OAAO,CAAC,YAAkBF,EAAEW,EAAA,IAAYP,EAAEO,EAAA,KAAaP,ECPxWQ,EAAA,QAAiBd,uBCDfG,EAAIH,EAENe,EAAA,WAAqBZ,EAAE,WACvBY,EAAA,YAAsBZ,EAAE,YCH1B,MAAMa,EAAgB,CAAC,CACrB,eAAAC,EACA,gBAAAC,EAAkB,CAAA,EAClB,eAAAC,EAAiB,CAAA,CACnB,IAAM,CACJ,MAAMC,EAAqBC,GAAU,CACnC,MAAMC,EAAoBH,EAAe,SAASE,CAAK,EACnDF,EAAe,OAAOI,GAAKA,IAAMF,CAAK,EACtC,CAAC,GAAGF,EAAgBE,CAAK,EAE7BJ,EAAeK,CAAiB,CAClC,EAEA,OACEE,EAAAA,KAAC,MAAA,CAAI,UAAU,iBACb,SAAA,CAAAC,EAAAA,IAAC,MAAG,SAAA,eAAA,CAAa,QAChB,MAAA,CAAI,UAAU,gBACZ,SAAAP,EAAgB,IAAIG,GACnBI,EAAAA,IAAC,SAAA,CAEC,UAAW,aAAaN,EAAe,SAASE,EAAM,IAAI,EAAI,WAAa,EAAE,GAC7E,QAAS,IAAMD,EAAkBC,EAAM,IAAI,EAE1C,SAAAA,EAAM,IAAA,EAJFA,EAAM,EAAA,CAMd,EACH,EAEAG,EAAAA,KAAC,IAAA,CAAE,UAAU,iBACV,SAAA,CAAAL,EAAe,OAAO,SAAOA,EAAe,SAAW,EAAI,IAAM,GAAG,WAAA,CAAA,CACvE,CAAA,EACF,CAEJ,ECjCMO,EAAa,CAAC,CAAE,KAAAC,EAAM,MAAAC,EAAO,aAAAC,EAAc,aAAAC,KAAmB,CAClE,KAAM,CAACC,EAAaC,CAAc,EAAIC,EAAAA,SAAS,CAAA,CAAE,EAE3CC,EAAkB,CAACC,EAAKC,EAAKC,IAAU,CAC3C,MAAMC,EAAM,GAAGH,CAAG,IAAIC,CAAG,GACnBG,EAAa,CAAE,GAAGR,EAAa,CAACO,CAAG,EAAGD,EAAM,aAAY,EAC9DL,EAAeO,CAAU,EACzBT,GAAgBA,EAAaK,EAAKC,EAAKC,CAAK,CAC9C,EAEMG,EAAe,CAACL,EAAKC,IAAQ,CACjC,GAAIP,GAAgB,CAACY,EAAYN,EAAKC,CAAG,EACvC,OAAOT,EAAKQ,CAAG,EAAEC,CAAG,EAEtB,MAAME,EAAM,GAAGH,CAAG,IAAIC,CAAG,GACzB,OAAOL,EAAYO,CAAG,GAAK,EAC7B,EAEMG,EAAc,CAACN,EAAKC,IACjBT,EAAKQ,CAAG,EAAEC,CAAG,IAAM,IAGtBM,EAAgB,CAACP,EAAKC,IAAQ,CAClC,GAAI,CAACR,EAAO,OAAO,KACnB,MAAMe,EAAOf,EAAM,KAAKrB,GAAKA,EAAE,SAAS,MAAQ4B,GAAO5B,EAAE,SAAS,MAAQ6B,CAAG,EAC7E,OAAOO,EAAOA,EAAK,OAAS,IAC9B,EAEA,GAAI,CAAChB,GAAQA,EAAK,SAAW,EAC3B,OAAOF,EAAAA,IAAC,MAAA,CAAI,UAAU,cAAc,SAAA,mBAAgB,EAGtD,MAAMmB,EAAWjB,EAAK,OAChBkB,EAAWlB,EAAK,CAAC,EAAIA,EAAK,CAAC,EAAE,OAAS,EAE5C,OACEF,EAAAA,IAAC,MAAA,CAAI,UAAU,mBACb,SAAAA,EAAAA,IAAC,MAAA,CACC,UAAU,cACV,MAAO,CACL,oBAAqB,UAAUoB,CAAQ,UACvC,iBAAkB,UAAUD,CAAQ,SAAA,EAGrC,SAAAjB,EAAK,IAAI,CAACQ,EAAKW,IACdX,EAAI,IAAI,CAACY,EAAMC,IAAa,CAC1B,MAAMC,EAAaP,EAAcI,EAAUE,CAAQ,EAInD,OAHgBP,EAAYK,EAAUE,CAAQ,EAK1CvB,EAAAA,IAAC,MAAA,CAEC,UAAU,uBACV,MAAO,CAAE,WAAY,QAAA,CAAS,EAFzB,GAAGqB,CAAQ,IAAIE,CAAQ,EAAA,EAShCxB,EAAAA,KAAC,MAAA,CAEC,UAAU,uBAET,SAAA,CAAAyB,GAAcxB,EAAAA,IAAC,OAAA,CAAK,UAAU,cAAe,SAAAwB,EAAW,EACzDxB,EAAAA,IAAC,QAAA,CACC,KAAK,OACL,UAAU,IACV,MAAOe,EAAaM,EAAUE,CAAQ,EACtC,SAAWrC,GAAMuB,EAAgBY,EAAUE,EAAUrC,EAAE,OAAO,KAAK,EACnE,UAAW,cAAckB,EAAe,gBAAkB,EAAE,GAC5D,SAAUA,CAAA,CAAA,CACZ,CAAA,EAXK,GAAGiB,CAAQ,IAAIE,CAAQ,EAAA,CAclC,CAAC,CAAA,CACH,CAAA,EAEJ,CAEJ,EClFME,EAAW,CAAC,CAAE,MAAAtB,EAAQ,CAAA,KAAS,CACnC,MAAMuB,EAAcvB,EAAM,OAAOe,GAAQA,EAAK,YAAc,QAAQ,EAC9DS,EAAYxB,EAAM,OAAOe,GAAQA,EAAK,YAAc,MAAM,EAE1DU,EAAc,CAAC,CAAE,MAAAC,EAAO,SAAAC,KAC5B/B,OAAC,MAAA,CAAI,UAAU,eACb,SAAA,CAAAC,EAAAA,IAAC,MAAI,SAAA6B,CAAA,CAAM,EACX7B,EAAAA,IAAC,MACE,SAAA8B,EAAS,OACR/B,EAAAA,KAAC,KAAA,CAA4C,UAAU,YACrD,SAAA,CAAAC,EAAAA,IAAC,OAAA,CAAK,UAAU,cAAe,SAAAkB,EAAK,OAAO,EAC3ClB,EAAAA,IAAC,OAAA,CAAK,UAAU,YAAa,WAAK,IAAA,CAAK,CAAA,GAFhC,GAAGkB,EAAK,MAAM,IAAIA,EAAK,SAAS,EAGzC,CACD,CAAA,CACH,CAAA,EACF,EAGF,OACEnB,EAAAA,KAAC,MAAA,CAAI,UAAU,YACb,SAAA,CAAAC,EAAAA,IAAC4B,EAAA,CAAY,MAAM,SAAS,SAAUF,EAAa,EACnD1B,EAAAA,IAAC4B,EAAA,CAAY,MAAM,OAAO,SAAUD,CAAA,CAAW,CAAA,EACjD,CAEJ,ECxBMI,EAAiB,CAAC,CAAE,QAAAC,EAAU,0BAEhCjC,EAAAA,KAAC,MAAA,CAAI,UAAU,kBACb,SAAA,CAAAC,EAAAA,IAAC,MAAA,CAAI,UAAU,SAAA,CAAU,EACzBA,EAAAA,IAAC,IAAA,CAAE,UAAU,kBAAmB,SAAAgC,CAAA,CAAQ,CAAA,EAC1C,ECLEC,EAAe,IAAM,CACzB,KAAM,CAACC,EAAQC,CAAS,EAAI3B,EAAAA,SAAS,IAAI,EACnC,CAAC4B,EAASC,CAAU,EAAI7B,EAAAA,SAAS,EAAK,EACtC,CAAC8B,EAAOC,CAAQ,EAAI/B,EAAAA,SAAS,IAAI,EACjC,CAACgC,EAAQC,CAAS,EAAIjC,EAAAA,SAAS,CAAA,CAAE,EAEjCkC,EAA4E,GAE5EC,EAAcC,EAAAA,YAAY,SAAY,CAC1C,GAAI,CACFP,EAAW,EAAI,EACf,MAAMQ,EAAW,MAAM,MAAM,GAAGH,CAAY,aAAa,EACzD,GAAI,CAACG,EAAS,GAAI,MAAM,IAAI,MAAM,wBAAwB,EAC1D,MAAMC,EAAO,MAAMD,EAAS,KAAA,EAC5BJ,EAAUK,CAAI,CAChB,OAASC,EAAK,CACZR,EAASQ,EAAI,OAAO,CACtB,QAAA,CACEV,EAAW,EAAK,CAClB,CACF,EAAG,CAACK,CAAY,CAAC,EAEXM,EAAiBJ,EAAAA,YAAY,MAAOlD,EAAgBuD,EAAa,SAAUC,EAAQ,KAAU,CACjG,GAAI,CACFb,EAAW,EAAI,EACfE,EAAS,IAAI,EAEb,MAAMM,EAAW,MAAM,MAAM,GAAGH,CAAY,gBAAiB,CAC3D,OAAQ,OACR,QAAS,CACP,eAAgB,kBAAA,EAElB,KAAM,KAAK,UAAU,CACnB,OAAQhD,EACR,WAAAuD,EACA,MAAAC,CAAA,CACD,CAAA,CACF,EAED,GAAI,CAACL,EAAS,GAAI,CAChB,MAAMM,EAAY,MAAMN,EAAS,KAAA,EAAO,MAAM,KAAO,CAAA,EAAG,EACxD,MAAM,IAAI,MAAMM,EAAU,SAAW,2BAA2B,CAClE,CAEA,MAAMC,EAAa,MAAMP,EAAS,KAAA,EAClC,OAAAV,EAAUiB,CAAU,EACbA,CACT,OAASL,EAAK,CACZ,OAAAR,EAASQ,EAAI,OAAO,EACb,IACT,QAAA,CACEV,EAAW,EAAK,CAClB,CACF,EAAG,CAACK,CAAY,CAAC,EAEXW,EAAkBT,cAAY,MAAOtC,GAAgB,CACzD,GAAI,CACF,MAAMuC,EAAW,MAAM,MAAM,GAAGH,CAAY,gBAAiB,CAC3D,OAAQ,OACR,QAAS,CACP,eAAgB,kBAAA,EAElB,KAAM,KAAK,UAAU,CACnB,OAAAR,EACA,QAAS5B,CAAA,CACV,CAAA,CACF,EAED,GAAI,CAACuC,EAAS,GAAI,MAAM,IAAI,MAAM,4BAA4B,EAE9D,OAAO,MAAMA,EAAS,KAAA,CACxB,OAASE,EAAK,CACZ,OAAAR,EAASQ,EAAI,OAAO,EACb,IACT,CACF,EAAG,CAACL,EAAcR,CAAM,CAAC,EAEnBoB,EAAcV,EAAAA,YAAY,IAAM,CACpCT,EAAU,IAAI,EACdI,EAAS,IAAI,CACf,EAAG,CAAA,CAAE,EAEL,MAAO,CACL,OAAAL,EACA,QAAAE,EACA,MAAAE,EACA,OAAAE,EACA,YAAAG,EACA,eAAAK,EACA,gBAAAK,EACA,YAAAC,CAAA,CAEJ,ECtFA,SAASC,GAAM,CACb,KAAM,CAAC7D,EAAgB8D,CAAiB,EAAIhD,EAAAA,SAAS,CAAA,CAAE,EACjD,CAACyC,EAAYQ,CAAa,EAAIjD,EAAAA,SAAS,QAAQ,EAC/C,CAACJ,EAAcsD,CAAe,EAAIlD,EAAAA,SAAS,EAAK,EAEhD,CACJ,OAAA0B,EACA,QAAAE,EACA,MAAAE,EACA,OAAAE,EACA,YAAAG,EACA,eAAAK,EACA,YAAAM,CAAA,EACErB,EAAA,EAEJ0B,EAAAA,UAAU,IAAM,CACdhB,EAAA,CACF,EAAG,CAACA,CAAW,CAAC,EAEhB,MAAMiB,EAAuB,SAAY,CACvC,GAAIlE,EAAe,SAAW,EAAG,CAC/B,MAAM,kCAAkC,EACxC,MACF,CAEA,MAAMsD,EAAetD,EAAgBuD,EAAY,EAAK,CACxD,EAEMY,EAAsBrB,GAAW,CACrCgB,EAAkBhB,CAAM,CAC1B,EAGMsB,EAAc,IAAM,CACxBR,EAAA,EACAE,EAAkB,CAAA,CAAE,EACpBE,EAAgB,EAAK,EACrBD,EAAc,QAAQ,CACxB,EAEMM,EAAuB,IAAM,CACjCL,EAAgB,EAAI,CACtB,EAEA,OACE3D,EAAAA,KAAC,MAAA,CAAI,UAAU,gBACb,SAAA,CAAAA,EAAAA,KAAC,SAAA,CAAO,UAAU,aAChB,SAAA,CAAAC,EAAAA,IAAC,KAAA,CAAG,UAAU,YAAY,SAAA,6BAA0B,EACpDA,EAAAA,IAAC,KAAE,SAAA,0DAAA,CAAwD,CAAA,EAC7D,EAEAA,EAAAA,IAACT,EAAA,CACC,eAAgBsE,EAChB,gBAAiBrB,EACjB,eAAA9C,CAAA,CAAA,EAGFK,EAAAA,KAAC,MAAA,CAAI,UAAU,kBACb,SAAA,CAAAA,EAAAA,KAAC,SAAA,CACC,MAAOkD,EACP,SAAW/D,GAAMuE,EAAcvE,EAAE,OAAO,KAAK,EAC7C,UAAU,cAEV,SAAA,CAAAc,EAAAA,IAAC,SAAA,CAAO,MAAM,OAAO,SAAA,OAAI,EACzBA,EAAAA,IAAC,SAAA,CAAO,MAAM,SAAS,SAAA,SAAM,EAC7BA,EAAAA,IAAC,SAAA,CAAO,MAAM,OAAO,SAAA,MAAA,CAAI,CAAA,CAAA,CAAA,EAG3BA,EAAAA,IAAC,SAAA,CACC,QAAS4D,EACT,SAAUxB,GAAW1C,EAAe,SAAW,EAC/C,UAAU,2BAET,WAAU,gBAAkB,iBAAA,CAAA,EAG/BM,EAAAA,IAAC,SAAA,CACC,QAAS8D,EACT,UAAU,wBACX,SAAA,OAAA,CAAA,EAIA5B,GAAU,CAAC9B,GACVJ,EAAAA,IAAC,SAAA,CACC,QAAS+D,EACT,UAAU,yBACX,SAAA,iBAAA,CAAA,CAED,EAEJ,EAECzB,GACCvC,EAAAA,KAAC,MAAA,CAAI,UAAU,gBAAgB,SAAA,CAAA,UACrBuC,CAAA,EACV,EAGDF,SAAYL,EAAA,EAAe,EAE3BG,GAAU,CAACE,GACVrC,EAAAA,KAAAiE,EAAAA,SAAA,CACE,SAAA,CAAAhE,EAAAA,IAAC,OAAI,UAAU,cACb,SAAAD,EAAAA,KAAC,OAAA,CAAK,UAAU,eACb,SAAA,CAAAmC,EAAO,SAAS,UAAU,YAAUA,EAAO,SAAS,KAAK,IAAEA,EAAO,SAAS,KAAK,OAAA,CAAA,CACnF,CAAA,CACF,EACAnC,EAAAA,KAAC,MAAA,CAAI,UAAU,gBACb,SAAA,CAAAC,EAAAA,IAACC,EAAA,CACC,KAAMiC,EAAO,KACb,MAAOA,EAAO,MACd,aAAA9B,CAAA,CAAA,EAEFJ,EAAAA,IAACyB,EAAA,CAAS,MAAOS,EAAO,KAAA,CAAO,CAAA,CAAA,CACjC,CAAA,EACF,EAGD,CAACA,GAAU,CAACE,GAAW,CAACE,GACvBtC,EAAAA,IAAC,MAAA,CAAI,MAAO,CAAE,UAAW,SAAU,QAAS,OAAQ,MAAO,SAAA,EAAa,SAAA,qDAAA,CAExE,CAAA,EAEJ,CAEJ,CClIAiE,EAAS,WAAW,SAAS,eAAe,MAAM,CAAC,EAAE,aAClDC,EAAM,WAAN,CACC,SAAAlE,MAACuD,IAAI,CAAA,CACP,CACF","x_google_ignoreList":[0,1,2]}

crossword-app/backend-py/public/assets/index-7dkEH9uQ.js

@@ -0,0 +1,10 @@
+import{r as m,a as R,R as E}from"./vendor-nf7bT_Uh.js";(function(){const c=document.createElement("link").relList;if(c&&c.supports&&c.supports("modulepreload"))return;for(const t of document.querySelectorAll('link[rel="modulepreload"]'))n(t);new MutationObserver(t=>{for(const r of t)if(r.type==="childList")for(const l of r.addedNodes)l.tagName==="LINK"&&l.rel==="modulepreload"&&n(l)}).observe(document,{childList:!0,subtree:!0});function o(t){const r={};return t.integrity&&(r.integrity=t.integrity),t.referrerPolicy&&(r.referrerPolicy=t.referrerPolicy),t.crossOrigin==="use-credentials"?r.credentials="include":t.crossOrigin==="anonymous"?r.credentials="omit":r.credentials="same-origin",r}function n(t){if(t.ep)return;t.ep=!0;const r=o(t);fetch(t.href,r)}})();var S={exports:{}},N={};/**
+ * @license React
+ * react-jsx-runtime.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */var _=m,$=Symbol.for("react.element"),k=Symbol.for("react.fragment"),O=Object.prototype.hasOwnProperty,T=_.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,L={key:!0,ref:!0,__self:!0,__source:!0};function P(s,c,o){var n,t={},r=null,l=null;o!==void 0&&(r=""+o),c.key!==void 0&&(r=""+c.key),c.ref!==void 0&&(l=c.ref);for(n in c)O.call(c,n)&&!L.hasOwnProperty(n)&&(t[n]=c[n]);if(s&&s.defaultProps)for(n in c=s.defaultProps,c)t[n]===void 0&&(t[n]=c[n]);return{$$typeof:$,type:s,key:r,ref:l,props:t,_owner:T.current}}N.Fragment=k;N.jsx=P;N.jsxs=P;S.exports=N;var e=S.exports,w={},C=R;w.createRoot=C.createRoot,w.hydrateRoot=C.hydrateRoot;const A=({onTopicsChange:s,availableTopics:c=[],selectedTopics:o=[],customSentence:n="",onSentenceChange:t})=>{const r=l=>{const x=o.includes(l)?o.filter(i=>i!==l):[...o,l];s(x)};return e.jsxs("div",{className:"topic-selector",children:[e.jsx("h3",{children:"Select Topics"}),e.jsx("div",{className:"topic-buttons",children:c.map(l=>e.jsx("button",{className:`topic-btn ${o.includes(l.name)?"selected":""}`,onClick:()=>r(l.name),children:l.name},l.id))}),e.jsxs("div",{className:"sentence-input-container",children:[e.jsx("label",{htmlFor:"custom-sentence",className:"sentence-label",children:"Custom Sentence (optional)"}),e.jsx("textarea",{id:"custom-sentence",className:"sentence-input",value:n,onChange:l=>t&&t(l.target.value),placeholder:"Enter a sentence to influence word selection...",rows:"3",maxLength:"200"}),e.jsxs("div",{className:"sentence-info",children:[e.jsxs("span",{className:"char-count",children:[n.length,"/200 characters"]}),n&&e.jsx("button",{type:"button",className:"clear-sentence-btn",onClick:()=>t&&t(""),title:"Clear sentence",children:"Clear"})]})]}),e.jsxs("p",{className:"selected-count",children:[o.length," topic",o.length!==1?"s":""," selected"]})]})},F=({grid:s,clues:c,showSolution:o,onCellChange:n})=>{const[t,r]=m.useState({}),l=(d,a,u)=>{const p=`${d}-${a}`,f={...t,[p]:u.toUpperCase()};r(f),n&&n(d,a,u)},x=(d,a)=>{if(o&&!i(d,a))return s[d][a];const u=`${d}-${a}`;return t[u]||""},i=(d,a)=>s[d][a]===".",h=(d,a)=>{if(!c)return null;const u=c.find(p=>p.position.row===d&&p.position.col===a);return u?u.number:null};if(!s||s.length===0)return e.jsx("div",{className:"puzzle-grid",children:"No puzzle loaded"});const g=s.length,z=s[0]?s[0].length:0;return e.jsx("div",{className:"puzzle-container",children:e.jsx("div",{className:"puzzle-grid",style:{gridTemplateColumns:`repeat(${z}, 35px)`,gridTemplateRows:`repeat(${g}, 35px)`},children:s.map((d,a)=>d.map((u,p)=>{const f=h(a,p);return i(a,p)?e.jsx("div",{className:"grid-cell empty-cell",style:{visibility:"hidden"}},`${a}-${p}`):e.jsxs("div",{className:"grid-cell white-cell",children:[f&&e.jsx("span",{className:"cell-number",children:f}),e.jsx("input",{type:"text",maxLength:"1",value:x(a,p),onChange:y=>l(a,p,y.target.value),className:`cell-input ${o?"solution-text":""}`,disabled:o})]},`${a}-${p}`)}))})})},D=({clues:s=[]})=>{const c=s.filter(t=>t.direction==="across"),o=s.filter(t=>t.direction==="down"),n=({title:t,clueList:r})=>e.jsxs("div",{className:"clue-section",children:[e.jsx("h4",{children:t}),e.jsx("ol",{children:r.map(l=>e.jsxs("li",{className:"clue-item",children:[e.jsx("span",{className:"clue-number",children:l.number}),e.jsx("span",{className:"clue-text",children:l.text})]},`${l.number}-${l.direction}`))})]});return e.jsxs("div",{className:"clue-list",children:[e.jsx(n,{title:"Across",clueList:c}),e.jsx(n,{title:"Down",clueList:o})]})},G=({message:s="Generating puzzle..."})=>e.jsxs("div",{className:"loading-spinner",children:[e.jsx("div",{className:"spinner"}),e.jsx("p",{className:"loading-message",children:s})]}),B=()=>{const[s,c]=m.useState(null),[o,n]=m.useState(!1),[t,r]=m.useState(null),[l,x]=m.useState([]),i="",h=m.useCallback(async()=>{try{n(!0);const a=await fetch(`${i}/api/topics`);if(!a.ok)throw new Error("Failed to fetch topics");const u=await a.json();x(u)}catch(a){r(a.message)}finally{n(!1)}},[i]),g=m.useCallback(async(a,u="medium",p=!1,f="")=>{try{n(!0),r(null);const j=await fetch(`${i}/api/generate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({topics:a,difficulty:u,useAI:p,...f&&{customSentence:f}})});if(!j.ok){const b=await j.json().catch(()=>({}));throw new Error(b.message||"Failed to generate puzzle")}const y=await j.json();return c(y),y}catch(j){return r(j.message),null}finally{n(!1)}},[i]),z=m.useCallback(async a=>{try{const u=await fetch(`${i}/api/validate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({puzzle:s,answers:a})});if(!u.ok)throw new Error("Failed to validate answers");return await u.json()}catch(u){return r(u.message),null}},[i,s]),d=m.useCallback(()=>{c(null),r(null)},[]);return{puzzle:s,loading:o,error:t,topics:l,fetchTopics:h,generatePuzzle:g,validateAnswers:z,resetPuzzle:d}};function U(){const[s,c]=m.useState([]),[o,n]=m.useState("medium"),[t,r]=m.useState(!1),[l,x]=m.useState(""),{puzzle:i,loading:h,error:g,topics:z,fetchTopics:d,generatePuzzle:a,resetPuzzle:u}=B();m.useEffect(()=>{d()},[d]);const p=async()=>{if(s.length===0){alert("Please select at least one topic");return}await a(s,o,!1,l)},f=v=>{c(v)},j=v=>{x(v)},y=()=>{u(),c([]),r(!1),n("medium"),x("")},b=()=>{r(!0)};return e.jsxs("div",{className:"crossword-app",children:[e.jsxs("header",{className:"app-header",children:[e.jsx("h1",{className:"app-title",children:"Crossword Puzzle Generator"}),e.jsx("p",{children:"Select topics and generate your custom crossword puzzle!"})]}),e.jsx(A,{onTopicsChange:f,availableTopics:z,selectedTopics:s,customSentence:l,onSentenceChange:j}),e.jsxs("div",{className:"puzzle-controls",children:[e.jsxs("select",{value:o,onChange:v=>n(v.target.value),className:"control-btn",children:[e.jsx("option",{value:"easy",children:"Easy"}),e.jsx("option",{value:"medium",children:"Medium"}),e.jsx("option",{value:"hard",children:"Hard"})]}),e.jsx("button",{onClick:p,disabled:h||s.length===0,className:"control-btn generate-btn",children:h?"Generating...":"Generate Puzzle"}),e.jsx("button",{onClick:y,className:"control-btn reset-btn",children:"Reset"}),i&&!t&&e.jsx("button",{onClick:b,className:"control-btn reveal-btn",children:"Reveal Solution"})]}),g&&e.jsxs("div",{className:"error-message",children:["Error: ",g]}),h&&e.jsx(G,{}),i&&!h&&e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"puzzle-info",children:e.jsxs("span",{className:"puzzle-stats",children:[i.metadata.wordCount," words • ",i.metadata.size,"×",i.metadata.size," grid"]})}),e.jsxs("div",{className:"puzzle-layout",children:[e.jsx(F,{grid:i.grid,clues:i.clues,showSolution:t}),e.jsx(D,{clues:i.clues})]})]}),!i&&!h&&!g&&e.jsx("div",{style:{textAlign:"center",padding:"40px",color:"#7f8c8d"},children:'Select topics and click "Generate Puzzle" to start!'})]})}w.createRoot(document.getElementById("root")).render(e.jsx(E.StrictMode,{children:e.jsx(U,{})}));
+//# sourceMappingURL=index-7dkEH9uQ.js.map

crossword-app/backend-py/public/assets/index-7dkEH9uQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-7dkEH9uQ.js","sources":["../../node_modules/react/cjs/react-jsx-runtime.production.min.js","../../node_modules/react/jsx-runtime.js","../../node_modules/react-dom/client.js","../../src/components/TopicSelector.jsx","../../src/components/PuzzleGrid.jsx","../../src/components/ClueList.jsx","../../src/components/LoadingSpinner.jsx","../../src/hooks/useCrossword.js","../../src/App.jsx","../../src/main.jsx"],"sourcesContent":["/**\n * @license React\n * react-jsx-runtime.production.min.js\n *\n * Copyright (c) Facebook, Inc. and its affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n'use strict';var f=require(\"react\"),k=Symbol.for(\"react.element\"),l=Symbol.for(\"react.fragment\"),m=Object.prototype.hasOwnProperty,n=f.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,p={key:!0,ref:!0,__self:!0,__source:!0};\nfunction q(c,a,g){var b,d={},e=null,h=null;void 0!==g&&(e=\"\"+g);void 0!==a.key&&(e=\"\"+a.key);void 0!==a.ref&&(h=a.ref);for(b in a)m.call(a,b)&&!p.hasOwnProperty(b)&&(d[b]=a[b]);if(c&&c.defaultProps)for(b in a=c.defaultProps,a)void 0===d[b]&&(d[b]=a[b]);return{$$typeof:k,type:c,key:e,ref:h,props:d,_owner:n.current}}exports.Fragment=l;exports.jsx=q;exports.jsxs=q;\n","'use strict';\n\nif (process.env.NODE_ENV === 'production') {\n  module.exports = require('./cjs/react-jsx-runtime.production.min.js');\n} else {\n  module.exports = require('./cjs/react-jsx-runtime.development.js');\n}\n","'use strict';\n\nvar m = require('react-dom');\nif (process.env.NODE_ENV === 'production') {\n  exports.createRoot = m.createRoot;\n  exports.hydrateRoot = m.hydrateRoot;\n} else {\n  var i = m.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;\n  exports.createRoot = function(c, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.createRoot(c, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n  exports.hydrateRoot = function(c, h, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.hydrateRoot(c, h, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n}\n","import React from 'react';\n\nconst TopicSelector = ({ \n  onTopicsChange, \n  availableTopics = [], \n  selectedTopics = [],\n  customSentence = '',\n  onSentenceChange\n}) => {\n  const handleTopicToggle = (topic) => {\n    const newSelectedTopics = selectedTopics.includes(topic)\n      ? selectedTopics.filter(t => t !== topic)\n      : [...selectedTopics, topic];\n    \n    onTopicsChange(newSelectedTopics);\n  };\n\n  return (\n    <div className=\"topic-selector\">\n      <h3>Select Topics</h3>\n      <div className=\"topic-buttons\">\n        {availableTopics.map(topic => (\n          <button\n            key={topic.id}\n            className={`topic-btn ${selectedTopics.includes(topic.name) ? 'selected' : ''}`}\n            onClick={() => handleTopicToggle(topic.name)}\n          >\n            {topic.name}\n          </button>\n        ))}\n      </div>\n      \n      <div className=\"sentence-input-container\">\n        <label htmlFor=\"custom-sentence\" className=\"sentence-label\">\n          Custom Sentence (optional)\n        </label>\n        <textarea\n          id=\"custom-sentence\"\n          className=\"sentence-input\"\n          value={customSentence}\n          onChange={(e) => onSentenceChange && onSentenceChange(e.target.value)}\n          placeholder=\"Enter a sentence to influence word selection...\"\n          rows=\"3\"\n          maxLength=\"200\"\n        />\n        <div className=\"sentence-info\">\n          <span className=\"char-count\">{customSentence.length}/200 characters</span>\n          {customSentence && (\n            <button \n              type=\"button\"\n              className=\"clear-sentence-btn\"\n              onClick={() => onSentenceChange && onSentenceChange('')}\n              title=\"Clear sentence\"\n            >\n              Clear\n            </button>\n          )}\n        </div>\n      </div>\n      \n      <p className=\"selected-count\">\n        {selectedTopics.length} topic{selectedTopics.length !== 1 ? 's' : ''} selected\n      </p>\n    </div>\n  );\n};\n\nexport default TopicSelector;","import React, { useState } from 'react';\n\nconst PuzzleGrid = ({ grid, clues, showSolution, onCellChange }) => {\n  const [userAnswers, setUserAnswers] = useState({});\n\n  const handleCellInput = (row, col, value) => {\n    const key = `${row}-${col}`;\n    const newAnswers = { ...userAnswers, [key]: value.toUpperCase() };\n    setUserAnswers(newAnswers);\n    onCellChange && onCellChange(row, col, value);\n  };\n\n  const getCellValue = (row, col) => {\n    if (showSolution && !isBlackCell(row, col)) {\n      return grid[row][col];\n    }\n    const key = `${row}-${col}`;\n    return userAnswers[key] || '';\n  };\n\n  const isBlackCell = (row, col) => {\n    return grid[row][col] === '.';\n  };\n\n  const getCellNumber = (row, col) => {\n    if (!clues) return null;\n    const clue = clues.find(c => c.position.row === row && c.position.col === col);\n    return clue ? clue.number : null;\n  };\n\n  if (!grid || grid.length === 0) {\n    return <div className=\"puzzle-grid\">No puzzle loaded</div>;\n  }\n\n  const gridRows = grid.length;\n  const gridCols = grid[0] ? grid[0].length : 0;\n\n  return (\n    <div className=\"puzzle-container\">\n      <div \n        className=\"puzzle-grid\"\n        style={{\n          gridTemplateColumns: `repeat(${gridCols}, 35px)`,\n          gridTemplateRows: `repeat(${gridRows}, 35px)`\n        }}\n      >\n        {grid.map((row, rowIndex) =>\n          row.map((cell, colIndex) => {\n            const cellNumber = getCellNumber(rowIndex, colIndex);\n            const isBlack = isBlackCell(rowIndex, colIndex);\n            \n            // Only render cells that contain letters (not black/unused cells)\n            if (isBlack) {\n              return (\n                <div\n                  key={`${rowIndex}-${colIndex}`}\n                  className=\"grid-cell empty-cell\"\n                  style={{ visibility: 'hidden' }}\n                >\n                </div>\n              );\n            }\n            \n            return (\n              <div\n                key={`${rowIndex}-${colIndex}`}\n                className=\"grid-cell white-cell\"\n              >\n                {cellNumber && <span className=\"cell-number\">{cellNumber}</span>}\n                <input\n                  type=\"text\"\n                  maxLength=\"1\"\n                  value={getCellValue(rowIndex, colIndex)}\n                  onChange={(e) => handleCellInput(rowIndex, colIndex, e.target.value)}\n                  className={`cell-input ${showSolution ? 'solution-text' : ''}`}\n                  disabled={showSolution}\n                />\n              </div>\n            );\n          })\n        )}\n      </div>\n    </div>\n  );\n};\n\nexport default PuzzleGrid;","import React from 'react';\n\nconst ClueList = ({ clues = [] }) => {\n  const acrossClues = clues.filter(clue => clue.direction === 'across');\n  const downClues = clues.filter(clue => clue.direction === 'down');\n\n  const ClueSection = ({ title, clueList }) => (\n    <div className=\"clue-section\">\n      <h4>{title}</h4>\n      <ol>\n        {clueList.map(clue => (\n          <li key={`${clue.number}-${clue.direction}`} className=\"clue-item\">\n            <span className=\"clue-number\">{clue.number}</span>\n            <span className=\"clue-text\">{clue.text}</span>\n          </li>\n        ))}\n      </ol>\n    </div>\n  );\n\n  return (\n    <div className=\"clue-list\">\n      <ClueSection title=\"Across\" clueList={acrossClues} />\n      <ClueSection title=\"Down\" clueList={downClues} />\n    </div>\n  );\n};\n\nexport default ClueList;","import React from 'react';\n\nconst LoadingSpinner = ({ message = \"Generating puzzle...\" }) => {\n  return (\n    <div className=\"loading-spinner\">\n      <div className=\"spinner\"></div>\n      <p className=\"loading-message\">{message}</p>\n    </div>\n  );\n};\n\nexport default LoadingSpinner;","import { useState, useCallback } from 'react';\n\nconst useCrossword = () => {\n  const [puzzle, setPuzzle] = useState(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n  const [topics, setTopics] = useState([]);\n\n  const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || (import.meta.env.PROD ? '' : 'http://localhost:3000');\n\n  const fetchTopics = useCallback(async () => {\n    try {\n      setLoading(true);\n      const response = await fetch(`${API_BASE_URL}/api/topics`);\n      if (!response.ok) throw new Error('Failed to fetch topics');\n      const data = await response.json();\n      setTopics(data);\n    } catch (err) {\n      setError(err.message);\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium', useAI = false, customSentence = '') => {\n    try {\n      setLoading(true);\n      setError(null);\n      \n      const response = await fetch(`${API_BASE_URL}/api/generate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          topics: selectedTopics,\n          difficulty,\n          useAI,\n          ...(customSentence && { customSentence })\n        })\n      });\n\n      if (!response.ok) {\n        const errorData = await response.json().catch(() => ({}));\n        throw new Error(errorData.message || 'Failed to generate puzzle');\n      }\n      \n      const puzzleData = await response.json();\n      setPuzzle(puzzleData);\n      return puzzleData;\n    } catch (err) {\n      setError(err.message);\n      return null;\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const validateAnswers = useCallback(async (userAnswers) => {\n    try {\n      const response = await fetch(`${API_BASE_URL}/api/validate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          puzzle: puzzle,\n          answers: userAnswers\n        })\n      });\n\n      if (!response.ok) throw new Error('Failed to validate answers');\n      \n      return await response.json();\n    } catch (err) {\n      setError(err.message);\n      return null;\n    }\n  }, [API_BASE_URL, puzzle]);\n\n  const resetPuzzle = useCallback(() => {\n    setPuzzle(null);\n    setError(null);\n  }, []);\n\n  return {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    validateAnswers,\n    resetPuzzle\n  };\n};\n\nexport default useCrossword;","import React, { useState, useEffect } from 'react';\nimport TopicSelector from './components/TopicSelector';\nimport PuzzleGrid from './components/PuzzleGrid';\nimport ClueList from './components/ClueList';\nimport LoadingSpinner from './components/LoadingSpinner';\nimport useCrossword from './hooks/useCrossword';\nimport './styles/puzzle.css';\n\nfunction App() {\n  const [selectedTopics, setSelectedTopics] = useState([]);\n  const [difficulty, setDifficulty] = useState('medium');\n  const [showSolution, setShowSolution] = useState(false);\n  const [customSentence, setCustomSentence] = useState('');\n  \n  const {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    resetPuzzle\n  } = useCrossword();\n\n  useEffect(() => {\n    fetchTopics();\n  }, [fetchTopics]);\n\n  const handleGeneratePuzzle = async () => {\n    if (selectedTopics.length === 0) {\n      alert('Please select at least one topic');\n      return;\n    }\n    \n    await generatePuzzle(selectedTopics, difficulty, false, customSentence);\n  };\n\n  const handleTopicsChange = (topics) => {\n    setSelectedTopics(topics);\n  };\n\n  const handleSentenceChange = (sentence) => {\n    setCustomSentence(sentence);\n  };\n\n\n  const handleReset = () => {\n    resetPuzzle();\n    setSelectedTopics([]);\n    setShowSolution(false);\n    setDifficulty('medium');\n    setCustomSentence('');\n  };\n\n  const handleRevealSolution = () => {\n    setShowSolution(true);\n  };\n\n  return (\n    <div className=\"crossword-app\">\n      <header className=\"app-header\">\n        <h1 className=\"app-title\">Crossword Puzzle Generator</h1>\n        <p>Select topics and generate your custom crossword puzzle!</p>\n      </header>\n\n      <TopicSelector \n        onTopicsChange={handleTopicsChange}\n        availableTopics={topics}\n        selectedTopics={selectedTopics}\n        customSentence={customSentence}\n        onSentenceChange={handleSentenceChange}\n      />\n\n      <div className=\"puzzle-controls\">\n        <select \n          value={difficulty} \n          onChange={(e) => setDifficulty(e.target.value)}\n          className=\"control-btn\"\n        >\n          <option value=\"easy\">Easy</option>\n          <option value=\"medium\">Medium</option>\n          <option value=\"hard\">Hard</option>\n        </select>\n        \n        <button\n          onClick={handleGeneratePuzzle}\n          disabled={loading || selectedTopics.length === 0}\n          className=\"control-btn generate-btn\"\n        >\n          {loading ? 'Generating...' : 'Generate Puzzle'}\n        </button>\n        \n        <button\n          onClick={handleReset}\n          className=\"control-btn reset-btn\"\n        >\n          Reset\n        </button>\n        \n        {puzzle && !showSolution && (\n          <button\n            onClick={handleRevealSolution}\n            className=\"control-btn reveal-btn\"\n          >\n            Reveal Solution\n          </button>\n        )}\n      </div>\n\n      {error && (\n        <div className=\"error-message\">\n          Error: {error}\n        </div>\n      )}\n\n      {loading && <LoadingSpinner />}\n\n      {puzzle && !loading && (\n        <>\n          <div className=\"puzzle-info\">\n            <span className=\"puzzle-stats\">\n              {puzzle.metadata.wordCount} words • {puzzle.metadata.size}×{puzzle.metadata.size} grid\n            </span>\n          </div>\n          <div className=\"puzzle-layout\">\n            <PuzzleGrid \n              grid={puzzle.grid} \n              clues={puzzle.clues}\n              showSolution={showSolution}\n            />\n            <ClueList clues={puzzle.clues} />\n          </div>\n        </>\n      )}\n\n      {!puzzle && !loading && !error && (\n        <div style={{ textAlign: 'center', padding: '40px', color: '#7f8c8d' }}>\n          Select topics and click \"Generate Puzzle\" to start!\n        </div>\n      )}\n    </div>\n  );\n}\n\nexport default App;","import React from 'react'\nimport ReactDOM from 'react-dom/client'\nimport App from './App.jsx'\n\nReactDOM.createRoot(document.getElementById('root')).render(\n  <React.StrictMode>\n    <App />\n  </React.StrictMode>,\n)"],"names":["f","require$$0","k","l","m","n","p","q","c","a","g","b","d","e","h","reactJsxRuntime_production_min","jsxRuntimeModule","client","TopicSelector","onTopicsChange","availableTopics","selectedTopics","customSentence","onSentenceChange","handleTopicToggle","topic","newSelectedTopics","t","jsxs","jsx","PuzzleGrid","grid","clues","showSolution","onCellChange","userAnswers","setUserAnswers","useState","handleCellInput","row","col","value","key","newAnswers","getCellValue","isBlackCell","getCellNumber","clue","gridRows","gridCols","rowIndex","cell","colIndex","cellNumber","ClueList","acrossClues","downClues","ClueSection","title","clueList","LoadingSpinner","message","useCrossword","puzzle","setPuzzle","loading","setLoading","error","setError","topics","setTopics","API_BASE_URL","fetchTopics","useCallback","response","data","err","generatePuzzle","difficulty","useAI","errorData","puzzleData","validateAnswers","resetPuzzle","App","setSelectedTopics","setDifficulty","setShowSolution","setCustomSentence","useEffect","handleGeneratePuzzle","handleTopicsChange","handleSentenceChange","sentence","handleReset","handleRevealSolution","Fragment","ReactDOM","React"],"mappings":"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","x_google_ignoreList":[0,1,2]}

crossword-app/backend-py/public/assets/index-CWqdoNhy.css

@@ -0,0 +1 @@
+.crossword-app{max-width:1200px;margin:0 auto;padding:20px;font-family:Segoe UI,Tahoma,Geneva,Verdana,sans-serif}.app-header{text-align:center;margin-bottom:30px}.app-title{color:#2c3e50;font-size:2.5rem;margin-bottom:10px}.topic-selector{background:#f8f9fa;padding:20px;border-radius:8px;margin-bottom:20px}.topic-selector h3{margin-top:0;color:#2c3e50}.topic-buttons{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:15px}.topic-btn{padding:8px 16px;border:2px solid #3498db;background:#fff;color:#3498db;border-radius:20px;cursor:pointer;transition:all .3s ease;font-weight:500}.topic-btn:hover,.topic-btn.selected{background:#3498db;color:#fff}.selected-count{color:#7f8c8d;font-size:.9rem;margin:0}.sentence-input-container{margin-top:20px;margin-bottom:15px}.sentence-label{display:block;margin-bottom:8px;color:#2c3e50;font-weight:500;font-size:.95rem}.sentence-input{width:100%;padding:12px;border:2px solid #e1e8ed;border-radius:8px;font-family:inherit;font-size:.9rem;line-height:1.4;resize:vertical;min-height:80px;background:#fff;transition:border-color .3s ease,box-shadow .3s ease;box-sizing:border-box}.sentence-input:focus{outline:none;border-color:#3498db;box-shadow:0 0 0 3px #3498db1a}.sentence-input::placeholder{color:#95a5a6;font-style:italic}.sentence-info{display:flex;justify-content:space-between;align-items:center;margin-top:6px;font-size:.8rem}.char-count{color:#7f8c8d}.clear-sentence-btn{background:#e74c3c;color:#fff;border:none;padding:4px 8px;border-radius:4px;cursor:pointer;font-size:.75rem;transition:background-color .2s ease}.clear-sentence-btn:hover{background:#c0392b}.clear-sentence-btn:active{background:#a93226}.ai-toggle-container{margin:20px 0;padding:15px;background:#f8f9fa;border-radius:8px;border:2px solid #e9ecef;transition:all .3s ease}.ai-toggle-container:has(.ai-checkbox:checked){background:linear-gradient(135deg,#e3f2fd,#f3e5f5);border-color:#3498db}.ai-toggle{display:flex;align-items:center;cursor:pointer;font-weight:500;margin-bottom:8px}.ai-checkbox{width:20px;height:20px;margin-right:12px;cursor:pointer;accent-color:#3498db}.ai-label{font-size:1rem;color:#2c3e50;-webkit-user-select:none;user-select:none}.ai-status{color:#27ae60;font-weight:600;font-size:.9rem}.ai-description{margin:0;font-size:.85rem;color:#6c757d;line-height:1.4;padding-left:32px}.puzzle-controls{display:flex;gap:15px;margin-bottom:20px;justify-content:center}.control-btn{padding:10px 20px;border:none;border-radius:5px;cursor:pointer;font-weight:600;transition:background-color .3s ease}.control-btn:disabled{background:#bdc3c7!important;color:#7f8c8d!important;cursor:not-allowed;opacity:.7}.generate-btn{background:#27ae60;color:#fff}.generate-btn:hover{background:#229954}.generate-btn:disabled{background:#bdc3c7;cursor:not-allowed}.reset-btn{background:#e74c3c;color:#fff}.reset-btn:hover{background:#c0392b}.reveal-btn{background:#f39c12;color:#fff}.reveal-btn:hover{background:#e67e22}.loading-spinner{display:flex;flex-direction:column;align-items:center;padding:40px}.spinner{width:40px;height:40px;border:4px solid #f3f3f3;border-top:4px solid #3498db;border-radius:50%;animation:spin 1s linear infinite;margin-bottom:15px}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.loading-message{color:#7f8c8d;font-size:1.1rem}.puzzle-info{display:flex;justify-content:space-between;align-items:center;margin:20px 0 10px;padding:10px 15px;background:#f8f9fa;border-radius:6px;border-left:4px solid #3498db}.puzzle-stats{font-size:.9rem;color:#6c757d;font-weight:500}.ai-generated-badge{background:linear-gradient(135deg,#667eea,#764ba2);color:#fff;padding:4px 12px;border-radius:15px;font-size:.8rem;font-weight:600;text-shadow:0 1px 2px rgba(0,0,0,.2);box-shadow:0 2px 4px #0000001a}.puzzle-layout{display:grid;grid-template-columns:1fr 300px;gap:30px;margin-top:20px}@media (max-width: 768px){.puzzle-layout{grid-template-columns:1fr;gap:20px}.puzzle-info{flex-direction:column;gap:8px;text-align:center}.ai-toggle-container{padding:12px}.ai-description{padding-left:0;text-align:center}}.puzzle-container{display:flex;justify-content:center}.puzzle-grid{display:grid;gap:0;margin:0 auto;width:fit-content;height:fit-content}.grid-cell{width:35px;height:35px;position:relative;display:flex;align-items:center;justify-content:center;box-sizing:border-box;background:#fff}.grid-cell:before{content:"";position:absolute;top:0;left:0;right:-1px;bottom:-1px;border:1px solid #2c3e50;pointer-events:none;z-index:10}.black-cell{background:#f0f0f0}.black-cell:before{background:#f0f0f0;border:1px solid #2c3e50}.white-cell{background:#fff}.empty-cell{background:transparent;border:none;visibility:hidden}.empty-cell:before{display:none}.cell-input{width:100%;height:100%;border:none!important;text-align:center;font-size:16px;font-weight:700;background:transparent;outline:none;text-transform:uppercase;position:relative;z-index:5}.cell-input:focus{background:#e8f4fd;box-shadow:inset 0 0 0 2px #3498db}.cell-number{position:absolute;top:1px;left:2px;font-size:10px;font-weight:700;color:#2c3e50;line-height:1;z-index:15;pointer-events:none}.solution-text{color:#2c3e50!important;font-weight:700!important;background:#fff!important}.solution-text:disabled{opacity:1!important;cursor:default}.grid-cell .solution-text{border:none!important;background:#fff!important}.clue-list{background:#f8f9fa;padding:20px;border-radius:8px;max-height:600px;overflow-y:auto}.clue-section{margin-bottom:25px}.clue-section h4{color:#2c3e50;margin-bottom:15px;font-size:1.2rem;border-bottom:2px solid #3498db;padding-bottom:5px}.clue-section ol{padding-left:0;list-style:none}.clue-item{display:flex;margin-bottom:8px;padding:8px;border-radius:4px;cursor:pointer;transition:background-color .2s ease}.clue-item:hover{background:#e9ecef}.clue-number{font-weight:700;color:#3498db;margin-right:10px;min-width:25px}.clue-text{flex:1;color:#2c3e50}.error-message{background:#f8d7da;color:#721c24;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #f5c6cb}.success-message{background:#d4edda;color:#155724;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #c3e6cb;text-align:center;font-weight:600}

crossword-app/backend-py/public/assets/index-DyT-gQda.css

@@ -0,0 +1 @@
+.crossword-app{max-width:1200px;margin:0 auto;padding:20px;font-family:Segoe UI,Tahoma,Geneva,Verdana,sans-serif}.app-header{text-align:center;margin-bottom:30px}.app-title{color:#2c3e50;font-size:2.5rem;margin-bottom:10px}.topic-selector{background:#f8f9fa;padding:20px;border-radius:8px;margin-bottom:20px}.topic-selector h3{margin-top:0;color:#2c3e50}.topic-buttons{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:15px}.topic-btn{padding:8px 16px;border:2px solid #3498db;background:#fff;color:#3498db;border-radius:20px;cursor:pointer;transition:all .3s ease;font-weight:500}.topic-btn:hover,.topic-btn.selected{background:#3498db;color:#fff}.selected-count{color:#7f8c8d;font-size:.9rem;margin:0}.sentence-input-container{margin-top:20px;margin-bottom:15px}.sentence-label{display:block;margin-bottom:8px;color:#2c3e50;font-weight:500;font-size:.95rem}.sentence-input{width:100%;padding:12px;border:2px solid #e1e8ed;border-radius:8px;font-family:inherit;font-size:.9rem;line-height:1.4;resize:vertical;min-height:80px;background:#fff;transition:border-color .3s ease,box-shadow .3s ease;box-sizing:border-box}.sentence-input:focus{outline:none;border-color:#3498db;box-shadow:0 0 0 3px #3498db1a}.sentence-input::placeholder{color:#95a5a6;font-style:italic}.sentence-info{display:flex;justify-content:space-between;align-items:center;margin-top:6px;font-size:.8rem}.char-count{color:#7f8c8d}.clear-sentence-btn{background:#e74c3c;color:#fff;border:none;padding:4px 8px;border-radius:4px;cursor:pointer;font-size:.75rem;transition:background-color .2s ease}.clear-sentence-btn:hover{background:#c0392b}.clear-sentence-btn:active{background:#a93226}.multi-theme-toggle-container{margin-top:20px;margin-bottom:15px;padding:15px;background:#f0f4f8;border:1px solid #e1e8ed;border-radius:8px}.multi-theme-toggle{display:flex;align-items:center;cursor:pointer;margin-bottom:8px}.multi-theme-checkbox{width:18px;height:18px;margin-right:10px;cursor:pointer;accent-color:#3498db}.multi-theme-label{font-weight:500;color:#2c3e50;font-size:.95rem;-webkit-user-select:none;user-select:none}.multi-theme-description{margin:0;font-size:.85rem;color:#5a6c7d;line-height:1.4;font-style:italic;padding-left:28px}.ai-toggle-container{margin:20px 0;padding:15px;background:#f8f9fa;border-radius:8px;border:2px solid #e9ecef;transition:all .3s ease}.ai-toggle-container:has(.ai-checkbox:checked){background:linear-gradient(135deg,#e3f2fd,#f3e5f5);border-color:#3498db}.ai-toggle{display:flex;align-items:center;cursor:pointer;font-weight:500;margin-bottom:8px}.ai-checkbox{width:20px;height:20px;margin-right:12px;cursor:pointer;accent-color:#3498db}.ai-label{font-size:1rem;color:#2c3e50;-webkit-user-select:none;user-select:none}.ai-status{color:#27ae60;font-weight:600;font-size:.9rem}.ai-description{margin:0;font-size:.85rem;color:#6c757d;line-height:1.4;padding-left:32px}.puzzle-controls{display:flex;gap:15px;margin-bottom:20px;justify-content:center}.control-btn{padding:10px 20px;border:none;border-radius:5px;cursor:pointer;font-weight:600;transition:background-color .3s ease}.control-btn:disabled{background:#bdc3c7!important;color:#7f8c8d!important;cursor:not-allowed;opacity:.7}.generate-btn{background:#27ae60;color:#fff}.generate-btn:hover{background:#229954}.generate-btn:disabled{background:#bdc3c7;cursor:not-allowed}.reset-btn{background:#e74c3c;color:#fff}.reset-btn:hover{background:#c0392b}.reveal-btn{background:#f39c12;color:#fff}.reveal-btn:hover{background:#e67e22}.loading-spinner{display:flex;flex-direction:column;align-items:center;padding:40px}.spinner{width:40px;height:40px;border:4px solid #f3f3f3;border-top:4px solid #3498db;border-radius:50%;animation:spin 1s linear infinite;margin-bottom:15px}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.loading-message{color:#7f8c8d;font-size:1.1rem}.puzzle-info{display:flex;justify-content:space-between;align-items:center;margin:20px 0 10px;padding:10px 15px;background:#f8f9fa;border-radius:6px;border-left:4px solid #3498db}.puzzle-stats{font-size:.9rem;color:#6c757d;font-weight:500}.ai-generated-badge{background:linear-gradient(135deg,#667eea,#764ba2);color:#fff;padding:4px 12px;border-radius:15px;font-size:.8rem;font-weight:600;text-shadow:0 1px 2px rgba(0,0,0,.2);box-shadow:0 2px 4px #0000001a}.puzzle-layout{display:grid;grid-template-columns:1fr 300px;gap:30px;margin-top:20px}@media (max-width: 768px){.puzzle-layout{grid-template-columns:1fr;gap:20px}.puzzle-info{flex-direction:column;gap:8px;text-align:center}.ai-toggle-container{padding:12px}.ai-description{padding-left:0;text-align:center}}.puzzle-container{display:flex;justify-content:center}.puzzle-grid{display:grid;gap:0;margin:0 auto;width:fit-content;height:fit-content}.grid-cell{width:35px;height:35px;position:relative;display:flex;align-items:center;justify-content:center;box-sizing:border-box;background:#fff}.grid-cell:before{content:"";position:absolute;top:0;left:0;right:-1px;bottom:-1px;border:1px solid #2c3e50;pointer-events:none;z-index:10}.black-cell{background:#f0f0f0}.black-cell:before{background:#f0f0f0;border:1px solid #2c3e50}.white-cell{background:#fff}.empty-cell{background:transparent;border:none;visibility:hidden}.empty-cell:before{display:none}.cell-input{width:100%;height:100%;border:none!important;text-align:center;font-size:16px;font-weight:700;background:transparent;outline:none;text-transform:uppercase;position:relative;z-index:5}.cell-input:focus{background:#e8f4fd;box-shadow:inset 0 0 0 2px #3498db}.cell-number{position:absolute;top:1px;left:2px;font-size:10px;font-weight:700;color:#2c3e50;line-height:1;z-index:15;pointer-events:none}.solution-text{color:#2c3e50!important;font-weight:700!important;background:#fff!important}.solution-text:disabled{opacity:1!important;cursor:default}.grid-cell .solution-text{border:none!important;background:#fff!important}.clue-list{background:#f8f9fa;padding:20px;border-radius:8px;max-height:600px;overflow-y:auto}.clue-section{margin-bottom:25px}.clue-section h4{color:#2c3e50;margin-bottom:15px;font-size:1.2rem;border-bottom:2px solid #3498db;padding-bottom:5px}.clue-section ol{padding-left:0;list-style:none}.clue-item{display:flex;margin-bottom:8px;padding:8px;border-radius:4px;cursor:pointer;transition:background-color .2s ease}.clue-item:hover{background:#e9ecef}.clue-number{font-weight:700;color:#3498db;margin-right:10px;min-width:25px}.clue-text{flex:1;color:#2c3e50}.error-message{background:#f8d7da;color:#721c24;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #f5c6cb}.success-message{background:#d4edda;color:#155724;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #c3e6cb;text-align:center;font-weight:600}

crossword-app/backend-py/public/assets/index-V4v18wFW.css

@@ -0,0 +1 @@
+.crossword-app{max-width:1200px;margin:0 auto;padding:20px;font-family:Segoe UI,Tahoma,Geneva,Verdana,sans-serif}.app-header{text-align:center;margin-bottom:30px}.app-title{color:#2c3e50;font-size:2.5rem;margin-bottom:10px}.topic-selector{background:#f8f9fa;padding:20px;border-radius:8px;margin-bottom:20px}.topic-selector h3{margin-top:0;color:#2c3e50}.topic-buttons{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:15px}.topic-btn{padding:8px 16px;border:2px solid #3498db;background:#fff;color:#3498db;border-radius:20px;cursor:pointer;transition:all .3s ease;font-weight:500}.topic-btn:hover,.topic-btn.selected{background:#3498db;color:#fff}.selected-count{color:#7f8c8d;font-size:.9rem;margin:0}.ai-toggle-container{margin:20px 0;padding:15px;background:#f8f9fa;border-radius:8px;border:2px solid #e9ecef;transition:all .3s ease}.ai-toggle-container:has(.ai-checkbox:checked){background:linear-gradient(135deg,#e3f2fd,#f3e5f5);border-color:#3498db}.ai-toggle{display:flex;align-items:center;cursor:pointer;font-weight:500;margin-bottom:8px}.ai-checkbox{width:20px;height:20px;margin-right:12px;cursor:pointer;accent-color:#3498db}.ai-label{font-size:1rem;color:#2c3e50;-webkit-user-select:none;user-select:none}.ai-status{color:#27ae60;font-weight:600;font-size:.9rem}.ai-description{margin:0;font-size:.85rem;color:#6c757d;line-height:1.4;padding-left:32px}.puzzle-controls{display:flex;gap:15px;margin-bottom:20px;justify-content:center}.control-btn{padding:10px 20px;border:none;border-radius:5px;cursor:pointer;font-weight:600;transition:background-color .3s ease}.control-btn:disabled{background:#bdc3c7!important;color:#7f8c8d!important;cursor:not-allowed;opacity:.7}.generate-btn{background:#27ae60;color:#fff}.generate-btn:hover{background:#229954}.generate-btn:disabled{background:#bdc3c7;cursor:not-allowed}.reset-btn{background:#e74c3c;color:#fff}.reset-btn:hover{background:#c0392b}.reveal-btn{background:#f39c12;color:#fff}.reveal-btn:hover{background:#e67e22}.loading-spinner{display:flex;flex-direction:column;align-items:center;padding:40px}.spinner{width:40px;height:40px;border:4px solid #f3f3f3;border-top:4px solid #3498db;border-radius:50%;animation:spin 1s linear infinite;margin-bottom:15px}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}.loading-message{color:#7f8c8d;font-size:1.1rem}.puzzle-info{display:flex;justify-content:space-between;align-items:center;margin:20px 0 10px;padding:10px 15px;background:#f8f9fa;border-radius:6px;border-left:4px solid #3498db}.puzzle-stats{font-size:.9rem;color:#6c757d;font-weight:500}.ai-generated-badge{background:linear-gradient(135deg,#667eea,#764ba2);color:#fff;padding:4px 12px;border-radius:15px;font-size:.8rem;font-weight:600;text-shadow:0 1px 2px rgba(0,0,0,.2);box-shadow:0 2px 4px #0000001a}.puzzle-layout{display:grid;grid-template-columns:1fr 300px;gap:30px;margin-top:20px}@media (max-width: 768px){.puzzle-layout{grid-template-columns:1fr;gap:20px}.puzzle-info{flex-direction:column;gap:8px;text-align:center}.ai-toggle-container{padding:12px}.ai-description{padding-left:0;text-align:center}}.puzzle-container{display:flex;justify-content:center}.puzzle-grid{display:grid;gap:0;margin:0 auto;width:fit-content;height:fit-content}.grid-cell{width:35px;height:35px;position:relative;display:flex;align-items:center;justify-content:center;box-sizing:border-box;background:#fff}.grid-cell:before{content:"";position:absolute;top:0;left:0;right:-1px;bottom:-1px;border:1px solid #2c3e50;pointer-events:none;z-index:10}.black-cell{background:#f0f0f0}.black-cell:before{background:#f0f0f0;border:1px solid #2c3e50}.white-cell{background:#fff}.empty-cell{background:transparent;border:none;visibility:hidden}.empty-cell:before{display:none}.cell-input{width:100%;height:100%;border:none!important;text-align:center;font-size:16px;font-weight:700;background:transparent;outline:none;text-transform:uppercase;position:relative;z-index:5}.cell-input:focus{background:#e8f4fd;box-shadow:inset 0 0 0 2px #3498db}.cell-number{position:absolute;top:1px;left:2px;font-size:10px;font-weight:700;color:#2c3e50;line-height:1;z-index:15;pointer-events:none}.solution-text{color:#2c3e50!important;font-weight:700!important;background:#fff!important}.solution-text:disabled{opacity:1!important;cursor:default}.grid-cell .solution-text{border:none!important;background:#fff!important}.clue-list{background:#f8f9fa;padding:20px;border-radius:8px;max-height:600px;overflow-y:auto}.clue-section{margin-bottom:25px}.clue-section h4{color:#2c3e50;margin-bottom:15px;font-size:1.2rem;border-bottom:2px solid #3498db;padding-bottom:5px}.clue-section ol{padding-left:0;list-style:none}.clue-item{display:flex;margin-bottom:8px;padding:8px;border-radius:4px;cursor:pointer;transition:background-color .2s ease}.clue-item:hover{background:#e9ecef}.clue-number{font-weight:700;color:#3498db;margin-right:10px;min-width:25px}.clue-text{flex:1;color:#2c3e50}.error-message{background:#f8d7da;color:#721c24;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #f5c6cb}.success-message{background:#d4edda;color:#155724;padding:15px;border-radius:5px;margin:20px 0;border:1px solid #c3e6cb;text-align:center;font-weight:600}

crossword-app/backend-py/public/assets/index-uK3VdD5a.js

@@ -0,0 +1,10 @@
+import{r as m,a as T,R as _}from"./vendor-nf7bT_Uh.js";(function(){const a=document.createElement("link").relList;if(a&&a.supports&&a.supports("modulepreload"))return;for(const t of document.querySelectorAll('link[rel="modulepreload"]'))l(t);new MutationObserver(t=>{for(const s of t)if(s.type==="childList")for(const i of s.addedNodes)i.tagName==="LINK"&&i.rel==="modulepreload"&&l(i)}).observe(document,{childList:!0,subtree:!0});function o(t){const s={};return t.integrity&&(s.integrity=t.integrity),t.referrerPolicy&&(s.referrerPolicy=t.referrerPolicy),t.crossOrigin==="use-credentials"?s.credentials="include":t.crossOrigin==="anonymous"?s.credentials="omit":s.credentials="same-origin",s}function l(t){if(t.ep)return;t.ep=!0;const s=o(t);fetch(t.href,s)}})();var P={exports:{}},b={};/**
+ * @license React
+ * react-jsx-runtime.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */var $=m,O=Symbol.for("react.element"),L=Symbol.for("react.fragment"),A=Object.prototype.hasOwnProperty,F=$.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,D={key:!0,ref:!0,__self:!0,__source:!0};function k(n,a,o){var l,t={},s=null,i=null;o!==void 0&&(s=""+o),a.key!==void 0&&(s=""+a.key),a.ref!==void 0&&(i=a.ref);for(l in a)A.call(a,l)&&!D.hasOwnProperty(l)&&(t[l]=a[l]);if(n&&n.defaultProps)for(l in a=n.defaultProps,a)t[l]===void 0&&(t[l]=a[l]);return{$$typeof:O,type:n,key:s,ref:i,props:t,_owner:F.current}}b.Fragment=L;b.jsx=k;b.jsxs=k;P.exports=b;var e=P.exports,C={},S=T;C.createRoot=S.createRoot,C.hydrateRoot=S.hydrateRoot;const G=({onTopicsChange:n,availableTopics:a=[],selectedTopics:o=[],customSentence:l="",onSentenceChange:t,multiTheme:s=!0,onMultiThemeChange:i})=>{const g=c=>{const y=o.includes(c)?o.filter(p=>p!==c):[...o,c];n(y)};return e.jsxs("div",{className:"topic-selector",children:[e.jsx("h3",{children:"Select Topics"}),e.jsx("div",{className:"topic-buttons",children:a.map(c=>e.jsx("button",{className:`topic-btn ${o.includes(c.name)?"selected":""}`,onClick:()=>g(c.name),children:c.name},c.id))}),e.jsxs("div",{className:"sentence-input-container",children:[e.jsx("label",{htmlFor:"custom-sentence",className:"sentence-label",children:"Custom Sentence (optional)"}),e.jsx("textarea",{id:"custom-sentence",className:"sentence-input",value:l,onChange:c=>t&&t(c.target.value),placeholder:"Enter a sentence to influence word selection...",rows:"3",maxLength:"200"}),e.jsxs("div",{className:"sentence-info",children:[e.jsxs("span",{className:"char-count",children:[l.length,"/200 characters"]}),l&&e.jsx("button",{type:"button",className:"clear-sentence-btn",onClick:()=>t&&t(""),title:"Clear sentence",children:"Clear"})]})]}),e.jsxs("div",{className:"multi-theme-toggle-container",children:[e.jsxs("label",{className:"multi-theme-toggle",children:[e.jsx("input",{type:"checkbox",checked:s,onChange:c=>i&&i(c.target.checked),className:"multi-theme-checkbox"}),e.jsx("span",{className:"multi-theme-label",children:"🎯 Use Multi-Theme Processing"})]}),e.jsx("p",{className:"multi-theme-description",children:s?"AI will process each theme separately and balance results":"AI will blend all themes into a single concept"})]}),e.jsxs("p",{className:"selected-count",children:[o.length," topic",o.length!==1?"s":""," selected"]})]})},B=({grid:n,clues:a,showSolution:o,onCellChange:l})=>{const[t,s]=m.useState({}),i=(d,r,u)=>{const h=`${d}-${r}`,x={...t,[h]:u.toUpperCase()};s(x),l&&l(d,r,u)},g=(d,r)=>{if(o&&!c(d,r))return n[d][r];const u=`${d}-${r}`;return t[u]||""},c=(d,r)=>n[d][r]===".",y=(d,r)=>{if(!a)return null;const u=a.find(h=>h.position.row===d&&h.position.col===r);return u?u.number:null};if(!n||n.length===0)return e.jsx("div",{className:"puzzle-grid",children:"No puzzle loaded"});const p=n.length,f=n[0]?n[0].length:0;return e.jsx("div",{className:"puzzle-container",children:e.jsx("div",{className:"puzzle-grid",style:{gridTemplateColumns:`repeat(${f}, 35px)`,gridTemplateRows:`repeat(${p}, 35px)`},children:n.map((d,r)=>d.map((u,h)=>{const x=y(r,h);return c(r,h)?e.jsx("div",{className:"grid-cell empty-cell",style:{visibility:"hidden"}},`${r}-${h}`):e.jsxs("div",{className:"grid-cell white-cell",children:[x&&e.jsx("span",{className:"cell-number",children:x}),e.jsx("input",{type:"text",maxLength:"1",value:g(r,h),onChange:j=>i(r,h,j.target.value),className:`cell-input ${o?"solution-text":""}`,disabled:o})]},`${r}-${h}`)}))})})},M=({clues:n=[]})=>{const a=n.filter(t=>t.direction==="across"),o=n.filter(t=>t.direction==="down"),l=({title:t,clueList:s})=>e.jsxs("div",{className:"clue-section",children:[e.jsx("h4",{children:t}),e.jsx("ol",{children:s.map(i=>e.jsxs("li",{className:"clue-item",children:[e.jsx("span",{className:"clue-number",children:i.number}),e.jsx("span",{className:"clue-text",children:i.text})]},`${i.number}-${i.direction}`))})]});return e.jsxs("div",{className:"clue-list",children:[e.jsx(l,{title:"Across",clueList:a}),e.jsx(l,{title:"Down",clueList:o})]})},U=({message:n="Generating puzzle..."})=>e.jsxs("div",{className:"loading-spinner",children:[e.jsx("div",{className:"spinner"}),e.jsx("p",{className:"loading-message",children:n})]}),J=()=>{const[n,a]=m.useState(null),[o,l]=m.useState(!1),[t,s]=m.useState(null),[i,g]=m.useState([]),c="",y=m.useCallback(async()=>{try{l(!0);const r=await fetch(`${c}/api/topics`);if(!r.ok)throw new Error("Failed to fetch topics");const u=await r.json();g(u)}catch(r){s(r.message)}finally{l(!1)}},[c]),p=m.useCallback(async(r,u="medium",h=!1,x="",z=!0)=>{try{l(!0),s(null);const j=await fetch(`${c}/api/generate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({topics:r,difficulty:u,useAI:h,...x&&{customSentence:x},multiTheme:z})});if(!j.ok){const w=await j.json().catch(()=>({}));throw new Error(w.message||"Failed to generate puzzle")}const v=await j.json();return a(v),v}catch(j){return s(j.message),null}finally{l(!1)}},[c]),f=m.useCallback(async r=>{try{const u=await fetch(`${c}/api/validate`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({puzzle:n,answers:r})});if(!u.ok)throw new Error("Failed to validate answers");return await u.json()}catch(u){return s(u.message),null}},[c,n]),d=m.useCallback(()=>{a(null),s(null)},[]);return{puzzle:n,loading:o,error:t,topics:i,fetchTopics:y,generatePuzzle:p,validateAnswers:f,resetPuzzle:d}};function q(){const[n,a]=m.useState([]),[o,l]=m.useState("medium"),[t,s]=m.useState(!1),[i,g]=m.useState(""),[c,y]=m.useState(!0),{puzzle:p,loading:f,error:d,topics:r,fetchTopics:u,generatePuzzle:h,resetPuzzle:x}=J();m.useEffect(()=>{u()},[u]);const z=async()=>{if(n.length===0){alert("Please select at least one topic");return}await h(n,o,!1,i,c)},j=N=>{a(N)},v=N=>{g(N)},w=N=>{y(N)},R=()=>{x(),a([]),s(!1),l("medium"),g(""),y(!0)},E=()=>{s(!0)};return e.jsxs("div",{className:"crossword-app",children:[e.jsxs("header",{className:"app-header",children:[e.jsx("h1",{className:"app-title",children:"Crossword Puzzle Generator"}),e.jsx("p",{children:"Select topics and generate your custom crossword puzzle!"})]}),e.jsx(G,{onTopicsChange:j,availableTopics:r,selectedTopics:n,customSentence:i,onSentenceChange:v,multiTheme:c,onMultiThemeChange:w}),e.jsxs("div",{className:"puzzle-controls",children:[e.jsxs("select",{value:o,onChange:N=>l(N.target.value),className:"control-btn",children:[e.jsx("option",{value:"easy",children:"Easy"}),e.jsx("option",{value:"medium",children:"Medium"}),e.jsx("option",{value:"hard",children:"Hard"})]}),e.jsx("button",{onClick:z,disabled:f||n.length===0,className:"control-btn generate-btn",children:f?"Generating...":"Generate Puzzle"}),e.jsx("button",{onClick:R,className:"control-btn reset-btn",children:"Reset"}),p&&!t&&e.jsx("button",{onClick:E,className:"control-btn reveal-btn",children:"Reveal Solution"})]}),d&&e.jsxs("div",{className:"error-message",children:["Error: ",d]}),f&&e.jsx(U,{}),p&&!f&&e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"puzzle-info",children:e.jsxs("span",{className:"puzzle-stats",children:[p.metadata.wordCount," words • ",p.metadata.size,"×",p.metadata.size," grid"]})}),e.jsxs("div",{className:"puzzle-layout",children:[e.jsx(B,{grid:p.grid,clues:p.clues,showSolution:t}),e.jsx(M,{clues:p.clues})]})]}),!p&&!f&&!d&&e.jsx("div",{style:{textAlign:"center",padding:"40px",color:"#7f8c8d"},children:'Select topics and click "Generate Puzzle" to start!'})]})}C.createRoot(document.getElementById("root")).render(e.jsx(_.StrictMode,{children:e.jsx(q,{})}));
+//# sourceMappingURL=index-uK3VdD5a.js.map

crossword-app/backend-py/public/assets/index-uK3VdD5a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-uK3VdD5a.js","sources":["../../node_modules/react/cjs/react-jsx-runtime.production.min.js","../../node_modules/react/jsx-runtime.js","../../node_modules/react-dom/client.js","../../src/components/TopicSelector.jsx","../../src/components/PuzzleGrid.jsx","../../src/components/ClueList.jsx","../../src/components/LoadingSpinner.jsx","../../src/hooks/useCrossword.js","../../src/App.jsx","../../src/main.jsx"],"sourcesContent":["/**\n * @license React\n * react-jsx-runtime.production.min.js\n *\n * Copyright (c) Facebook, Inc. and its affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n'use strict';var f=require(\"react\"),k=Symbol.for(\"react.element\"),l=Symbol.for(\"react.fragment\"),m=Object.prototype.hasOwnProperty,n=f.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,p={key:!0,ref:!0,__self:!0,__source:!0};\nfunction q(c,a,g){var b,d={},e=null,h=null;void 0!==g&&(e=\"\"+g);void 0!==a.key&&(e=\"\"+a.key);void 0!==a.ref&&(h=a.ref);for(b in a)m.call(a,b)&&!p.hasOwnProperty(b)&&(d[b]=a[b]);if(c&&c.defaultProps)for(b in a=c.defaultProps,a)void 0===d[b]&&(d[b]=a[b]);return{$$typeof:k,type:c,key:e,ref:h,props:d,_owner:n.current}}exports.Fragment=l;exports.jsx=q;exports.jsxs=q;\n","'use strict';\n\nif (process.env.NODE_ENV === 'production') {\n  module.exports = require('./cjs/react-jsx-runtime.production.min.js');\n} else {\n  module.exports = require('./cjs/react-jsx-runtime.development.js');\n}\n","'use strict';\n\nvar m = require('react-dom');\nif (process.env.NODE_ENV === 'production') {\n  exports.createRoot = m.createRoot;\n  exports.hydrateRoot = m.hydrateRoot;\n} else {\n  var i = m.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;\n  exports.createRoot = function(c, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.createRoot(c, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n  exports.hydrateRoot = function(c, h, o) {\n    i.usingClientEntryPoint = true;\n    try {\n      return m.hydrateRoot(c, h, o);\n    } finally {\n      i.usingClientEntryPoint = false;\n    }\n  };\n}\n","import React from 'react';\n\nconst TopicSelector = ({ \n  onTopicsChange, \n  availableTopics = [], \n  selectedTopics = [],\n  customSentence = '',\n  onSentenceChange,\n  multiTheme = true,\n  onMultiThemeChange\n}) => {\n  const handleTopicToggle = (topic) => {\n    const newSelectedTopics = selectedTopics.includes(topic)\n      ? selectedTopics.filter(t => t !== topic)\n      : [...selectedTopics, topic];\n    \n    onTopicsChange(newSelectedTopics);\n  };\n\n  return (\n    <div className=\"topic-selector\">\n      <h3>Select Topics</h3>\n      <div className=\"topic-buttons\">\n        {availableTopics.map(topic => (\n          <button\n            key={topic.id}\n            className={`topic-btn ${selectedTopics.includes(topic.name) ? 'selected' : ''}`}\n            onClick={() => handleTopicToggle(topic.name)}\n          >\n            {topic.name}\n          </button>\n        ))}\n      </div>\n      \n      <div className=\"sentence-input-container\">\n        <label htmlFor=\"custom-sentence\" className=\"sentence-label\">\n          Custom Sentence (optional)\n        </label>\n        <textarea\n          id=\"custom-sentence\"\n          className=\"sentence-input\"\n          value={customSentence}\n          onChange={(e) => onSentenceChange && onSentenceChange(e.target.value)}\n          placeholder=\"Enter a sentence to influence word selection...\"\n          rows=\"3\"\n          maxLength=\"200\"\n        />\n        <div className=\"sentence-info\">\n          <span className=\"char-count\">{customSentence.length}/200 characters</span>\n          {customSentence && (\n            <button \n              type=\"button\"\n              className=\"clear-sentence-btn\"\n              onClick={() => onSentenceChange && onSentenceChange('')}\n              title=\"Clear sentence\"\n            >\n              Clear\n            </button>\n          )}\n        </div>\n      </div>\n      \n      <div className=\"multi-theme-toggle-container\">\n        <label className=\"multi-theme-toggle\">\n          <input\n            type=\"checkbox\"\n            checked={multiTheme}\n            onChange={(e) => onMultiThemeChange && onMultiThemeChange(e.target.checked)}\n            className=\"multi-theme-checkbox\"\n          />\n          <span className=\"multi-theme-label\">\n            🎯 Use Multi-Theme Processing\n          </span>\n        </label>\n        <p className=\"multi-theme-description\">\n          {multiTheme \n            ? \"AI will process each theme separately and balance results\" \n            : \"AI will blend all themes into a single concept\"\n          }\n        </p>\n      </div>\n      \n      <p className=\"selected-count\">\n        {selectedTopics.length} topic{selectedTopics.length !== 1 ? 's' : ''} selected\n      </p>\n    </div>\n  );\n};\n\nexport default TopicSelector;","import React, { useState } from 'react';\n\nconst PuzzleGrid = ({ grid, clues, showSolution, onCellChange }) => {\n  const [userAnswers, setUserAnswers] = useState({});\n\n  const handleCellInput = (row, col, value) => {\n    const key = `${row}-${col}`;\n    const newAnswers = { ...userAnswers, [key]: value.toUpperCase() };\n    setUserAnswers(newAnswers);\n    onCellChange && onCellChange(row, col, value);\n  };\n\n  const getCellValue = (row, col) => {\n    if (showSolution && !isBlackCell(row, col)) {\n      return grid[row][col];\n    }\n    const key = `${row}-${col}`;\n    return userAnswers[key] || '';\n  };\n\n  const isBlackCell = (row, col) => {\n    return grid[row][col] === '.';\n  };\n\n  const getCellNumber = (row, col) => {\n    if (!clues) return null;\n    const clue = clues.find(c => c.position.row === row && c.position.col === col);\n    return clue ? clue.number : null;\n  };\n\n  if (!grid || grid.length === 0) {\n    return <div className=\"puzzle-grid\">No puzzle loaded</div>;\n  }\n\n  const gridRows = grid.length;\n  const gridCols = grid[0] ? grid[0].length : 0;\n\n  return (\n    <div className=\"puzzle-container\">\n      <div \n        className=\"puzzle-grid\"\n        style={{\n          gridTemplateColumns: `repeat(${gridCols}, 35px)`,\n          gridTemplateRows: `repeat(${gridRows}, 35px)`\n        }}\n      >\n        {grid.map((row, rowIndex) =>\n          row.map((cell, colIndex) => {\n            const cellNumber = getCellNumber(rowIndex, colIndex);\n            const isBlack = isBlackCell(rowIndex, colIndex);\n            \n            // Only render cells that contain letters (not black/unused cells)\n            if (isBlack) {\n              return (\n                <div\n                  key={`${rowIndex}-${colIndex}`}\n                  className=\"grid-cell empty-cell\"\n                  style={{ visibility: 'hidden' }}\n                >\n                </div>\n              );\n            }\n            \n            return (\n              <div\n                key={`${rowIndex}-${colIndex}`}\n                className=\"grid-cell white-cell\"\n              >\n                {cellNumber && <span className=\"cell-number\">{cellNumber}</span>}\n                <input\n                  type=\"text\"\n                  maxLength=\"1\"\n                  value={getCellValue(rowIndex, colIndex)}\n                  onChange={(e) => handleCellInput(rowIndex, colIndex, e.target.value)}\n                  className={`cell-input ${showSolution ? 'solution-text' : ''}`}\n                  disabled={showSolution}\n                />\n              </div>\n            );\n          })\n        )}\n      </div>\n    </div>\n  );\n};\n\nexport default PuzzleGrid;","import React from 'react';\n\nconst ClueList = ({ clues = [] }) => {\n  const acrossClues = clues.filter(clue => clue.direction === 'across');\n  const downClues = clues.filter(clue => clue.direction === 'down');\n\n  const ClueSection = ({ title, clueList }) => (\n    <div className=\"clue-section\">\n      <h4>{title}</h4>\n      <ol>\n        {clueList.map(clue => (\n          <li key={`${clue.number}-${clue.direction}`} className=\"clue-item\">\n            <span className=\"clue-number\">{clue.number}</span>\n            <span className=\"clue-text\">{clue.text}</span>\n          </li>\n        ))}\n      </ol>\n    </div>\n  );\n\n  return (\n    <div className=\"clue-list\">\n      <ClueSection title=\"Across\" clueList={acrossClues} />\n      <ClueSection title=\"Down\" clueList={downClues} />\n    </div>\n  );\n};\n\nexport default ClueList;","import React from 'react';\n\nconst LoadingSpinner = ({ message = \"Generating puzzle...\" }) => {\n  return (\n    <div className=\"loading-spinner\">\n      <div className=\"spinner\"></div>\n      <p className=\"loading-message\">{message}</p>\n    </div>\n  );\n};\n\nexport default LoadingSpinner;","import { useState, useCallback } from 'react';\n\nconst useCrossword = () => {\n  const [puzzle, setPuzzle] = useState(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState(null);\n  const [topics, setTopics] = useState([]);\n\n  const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || (import.meta.env.PROD ? '' : 'http://localhost:3000');\n\n  const fetchTopics = useCallback(async () => {\n    try {\n      setLoading(true);\n      const response = await fetch(`${API_BASE_URL}/api/topics`);\n      if (!response.ok) throw new Error('Failed to fetch topics');\n      const data = await response.json();\n      setTopics(data);\n    } catch (err) {\n      setError(err.message);\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium', useAI = false, customSentence = '', multiTheme = true) => {\n    try {\n      setLoading(true);\n      setError(null);\n      \n      const response = await fetch(`${API_BASE_URL}/api/generate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          topics: selectedTopics,\n          difficulty,\n          useAI,\n          ...(customSentence && { customSentence }),\n          multiTheme\n        })\n      });\n\n      if (!response.ok) {\n        const errorData = await response.json().catch(() => ({}));\n        throw new Error(errorData.message || 'Failed to generate puzzle');\n      }\n      \n      const puzzleData = await response.json();\n      setPuzzle(puzzleData);\n      return puzzleData;\n    } catch (err) {\n      setError(err.message);\n      return null;\n    } finally {\n      setLoading(false);\n    }\n  }, [API_BASE_URL]);\n\n  const validateAnswers = useCallback(async (userAnswers) => {\n    try {\n      const response = await fetch(`${API_BASE_URL}/api/validate`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          puzzle: puzzle,\n          answers: userAnswers\n        })\n      });\n\n      if (!response.ok) throw new Error('Failed to validate answers');\n      \n      return await response.json();\n    } catch (err) {\n      setError(err.message);\n      return null;\n    }\n  }, [API_BASE_URL, puzzle]);\n\n  const resetPuzzle = useCallback(() => {\n    setPuzzle(null);\n    setError(null);\n  }, []);\n\n  return {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    validateAnswers,\n    resetPuzzle\n  };\n};\n\nexport default useCrossword;","import React, { useState, useEffect } from 'react';\nimport TopicSelector from './components/TopicSelector';\nimport PuzzleGrid from './components/PuzzleGrid';\nimport ClueList from './components/ClueList';\nimport LoadingSpinner from './components/LoadingSpinner';\nimport useCrossword from './hooks/useCrossword';\nimport './styles/puzzle.css';\n\nfunction App() {\n  const [selectedTopics, setSelectedTopics] = useState([]);\n  const [difficulty, setDifficulty] = useState('medium');\n  const [showSolution, setShowSolution] = useState(false);\n  const [customSentence, setCustomSentence] = useState('');\n  const [multiTheme, setMultiTheme] = useState(true);\n  \n  const {\n    puzzle,\n    loading,\n    error,\n    topics,\n    fetchTopics,\n    generatePuzzle,\n    resetPuzzle\n  } = useCrossword();\n\n  useEffect(() => {\n    fetchTopics();\n  }, [fetchTopics]);\n\n  const handleGeneratePuzzle = async () => {\n    if (selectedTopics.length === 0) {\n      alert('Please select at least one topic');\n      return;\n    }\n    \n    await generatePuzzle(selectedTopics, difficulty, false, customSentence, multiTheme);\n  };\n\n  const handleTopicsChange = (topics) => {\n    setSelectedTopics(topics);\n  };\n\n  const handleSentenceChange = (sentence) => {\n    setCustomSentence(sentence);\n  };\n\n  const handleMultiThemeChange = (enabled) => {\n    setMultiTheme(enabled);\n  };\n\n\n  const handleReset = () => {\n    resetPuzzle();\n    setSelectedTopics([]);\n    setShowSolution(false);\n    setDifficulty('medium');\n    setCustomSentence('');\n    setMultiTheme(true);\n  };\n\n  const handleRevealSolution = () => {\n    setShowSolution(true);\n  };\n\n  return (\n    <div className=\"crossword-app\">\n      <header className=\"app-header\">\n        <h1 className=\"app-title\">Crossword Puzzle Generator</h1>\n        <p>Select topics and generate your custom crossword puzzle!</p>\n      </header>\n\n      <TopicSelector \n        onTopicsChange={handleTopicsChange}\n        availableTopics={topics}\n        selectedTopics={selectedTopics}\n        customSentence={customSentence}\n        onSentenceChange={handleSentenceChange}\n        multiTheme={multiTheme}\n        onMultiThemeChange={handleMultiThemeChange}\n      />\n\n      <div className=\"puzzle-controls\">\n        <select \n          value={difficulty} \n          onChange={(e) => setDifficulty(e.target.value)}\n          className=\"control-btn\"\n        >\n          <option value=\"easy\">Easy</option>\n          <option value=\"medium\">Medium</option>\n          <option value=\"hard\">Hard</option>\n        </select>\n        \n        <button\n          onClick={handleGeneratePuzzle}\n          disabled={loading || selectedTopics.length === 0}\n          className=\"control-btn generate-btn\"\n        >\n          {loading ? 'Generating...' : 'Generate Puzzle'}\n        </button>\n        \n        <button\n          onClick={handleReset}\n          className=\"control-btn reset-btn\"\n        >\n          Reset\n        </button>\n        \n        {puzzle && !showSolution && (\n          <button\n            onClick={handleRevealSolution}\n            className=\"control-btn reveal-btn\"\n          >\n            Reveal Solution\n          </button>\n        )}\n      </div>\n\n      {error && (\n        <div className=\"error-message\">\n          Error: {error}\n        </div>\n      )}\n\n      {loading && <LoadingSpinner />}\n\n      {puzzle && !loading && (\n        <>\n          <div className=\"puzzle-info\">\n            <span className=\"puzzle-stats\">\n              {puzzle.metadata.wordCount} words • {puzzle.metadata.size}×{puzzle.metadata.size} grid\n            </span>\n          </div>\n          <div className=\"puzzle-layout\">\n            <PuzzleGrid \n              grid={puzzle.grid} \n              clues={puzzle.clues}\n              showSolution={showSolution}\n            />\n            <ClueList clues={puzzle.clues} />\n          </div>\n        </>\n      )}\n\n      {!puzzle && !loading && !error && (\n        <div style={{ textAlign: 'center', padding: '40px', color: '#7f8c8d' }}>\n          Select topics and click \"Generate Puzzle\" to start!\n        </div>\n      )}\n    </div>\n  );\n}\n\nexport default App;","import React from 'react'\nimport ReactDOM from 'react-dom/client'\nimport App from './App.jsx'\n\nReactDOM.createRoot(document.getElementById('root')).render(\n  <React.StrictMode>\n    <App />\n  </React.StrictMode>,\n)"],"names":["f","require$$0","k","l","m","n","p","q","c","g","b","d","e","h","reactJsxRuntime_production_min","jsxRuntimeModule","client","TopicSelector","onTopicsChange","availableTopics","selectedTopics","customSentence","onSentenceChange","multiTheme","onMultiThemeChange","handleTopicToggle","topic","newSelectedTopics","t","jsxs","jsx","PuzzleGrid","grid","clues","showSolution","onCellChange","userAnswers","setUserAnswers","useState","handleCellInput","row","col","value","key","newAnswers","getCellValue","isBlackCell","getCellNumber","clue","gridRows","gridCols","rowIndex","cell","colIndex","cellNumber","ClueList","acrossClues","downClues","ClueSection","title","clueList","LoadingSpinner","message","useCrossword","puzzle","setPuzzle","loading","setLoading","error","setError","topics","setTopics","API_BASE_URL","fetchTopics","useCallback","response","data","err","generatePuzzle","difficulty","useAI","errorData","puzzleData","validateAnswers","resetPuzzle","App","setSelectedTopics","setDifficulty","setShowSolution","setCustomSentence","setMultiTheme","useEffect","handleGeneratePuzzle","handleTopicsChange","handleSentenceChange","sentence","handleMultiThemeChange","enabled","handleReset","handleRevealSolution","Fragment","ReactDOM","React"],"mappings":"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","x_google_ignoreList":[0,1,2]}

crossword-app/backend-py/public/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Generate custom crossword puzzles by selecting topics" />
+    <meta name="keywords" content="crossword, puzzle, word game, brain teaser" />
+    <title>Crossword Puzzle Generator</title>
+    <script type="module" crossorigin src="/assets/index-uK3VdD5a.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/vendor-nf7bT_Uh.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-DyT-gQda.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

crossword-app/backend-py/requirements.txt

@@ -24,7 +24,8 @@ idna==3.10
 numpy==2.3.2
 
 # Logging and monitoring
-structlog==25.4.0
+# (Using standard Python logging with enhanced format)
+
 
 # Development and testing dependencies
 pytest==8.4.1
@@ -34,15 +35,17 @@ packaging==25.0
 pluggy==1.6.0
 pygments==2.19.2
 
-# AI/ML dependencies (optional - install separately if needed)
-# Uncomment these lines if you want AI-powered word generation:
-# sentence-transformers==3.3.0
-# torch==2.5.1
-# transformers==4.47.1
-# scikit-learn==1.5.2
-# huggingface-hub==0.26.2
-# faiss-cpu==1.9.0
+# AI/ML dependencies for thematic word generation
+sentence-transformers==3.3.0
+torch==2.5.1
+transformers==4.47.1
+scikit-learn==1.5.2
+huggingface-hub==0.26.2
+wordfreq==3.1.0
+
+# NLTK dependencies for WordNet clue generation
+nltk==3.8.1
 
 # Additional utility dependencies
 annotated-types==0.7.0
-sniffio==1.3.1
+sniffio==1.3.1

crossword-app/backend-py/src/routes/api.py

@@ -20,7 +20,9 @@ router = APIRouter()
 class GeneratePuzzleRequest(BaseModel):
     topics: List[str] = Field(..., description="List of topics for the puzzle")
     difficulty: str = Field(default="medium", description="Difficulty level: easy, medium, hard")
-    useAI: bool = Field(default=False, description="Use AI vector search for word generation")
+    customSentence: Optional[str] = Field(default=None, description="Optional custom sentence to influence word selection")
+    multiTheme: bool = Field(default=True, description="Whether to use multi-theme processing or single-theme blending")
+    wordCount: Optional[int] = Field(default=10, description="Number of words to include in the crossword (8-15)")
 
 class WordInfo(BaseModel):
     word: str
@@ -55,22 +57,30 @@ class TopicInfo(BaseModel):
 generator = None
 
 def get_crossword_generator(request: Request) -> CrosswordGenerator:
-    """Dependency to get the crossword generator with vector search service."""
+    """Dependency to get the crossword generator with thematic service."""
     global generator
     if generator is None:
-        vector_service = getattr(request.app.state, 'vector_service', None)
-        generator = CrosswordGenerator(vector_service)
+        thematic_service = getattr(request.app.state, 'thematic_service', None)
+        generator = CrosswordGenerator(thematic_service)
     return generator
 
 @router.get("/topics", response_model=List[TopicInfo])
 async def get_topics():
     """Get available topics for puzzle generation."""
-    # Return the same topics as JavaScript backend for consistency
+    # Return expanded topic list for better user variety
     topics = [
         {"id": "animals", "name": "Animals"},
         {"id": "geography", "name": "Geography"},
         {"id": "science", "name": "Science"},
-        {"id": "technology", "name": "Technology"}
+        {"id": "technology", "name": "Technology"},
+        {"id": "sports", "name": "Sports"},
+        {"id": "history", "name": "History"},
+        {"id": "food", "name": "Food"},
+        {"id": "entertainment", "name": "Entertainment"},
+        {"id": "nature", "name": "Nature"},
+        {"id": "transportation", "name": "Transportation"},
+        {"id": "art", "name": "Art"},
+        {"id": "medicine", "name": "Medicine"}
     ]
     return topics
 
@@ -80,16 +90,18 @@ async def generate_puzzle(
     crossword_gen: CrosswordGenerator = Depends(get_crossword_generator)
 ):
     """
-    Generate a crossword puzzle with optional AI vector search.
+    Generate a crossword puzzle with AI thematic word generation.
     
     This endpoint matches the JavaScript API exactly for frontend compatibility.
     """
     try:
-        logger.info(f"🎯 Generating puzzle for topics: {request.topics}, difficulty: {request.difficulty}, useAI: {request.useAI}")
+        sentence_info = f", custom sentence: '{request.customSentence}'" if request.customSentence else ""
+        theme_mode = "multi-theme" if request.multiTheme else "single-theme"
+        logger.info(f"🎯 Generating puzzle for topics: {request.topics}, difficulty: {request.difficulty}{sentence_info}, mode: {theme_mode}")
         
-        # Validate topics
-        if not request.topics:
-            raise HTTPException(status_code=400, detail="At least one topic is required")
+        # Validate topics - require either topics or custom sentence
+        if not request.topics and not (request.customSentence and request.customSentence.strip()):
+            raise HTTPException(status_code=400, detail="At least one topic or a custom sentence is required")
         
         valid_difficulties = ["easy", "medium", "hard"]
         if request.difficulty not in valid_difficulties:
@@ -98,11 +110,20 @@ async def generate_puzzle(
                 detail=f"Invalid difficulty. Must be one of: {valid_difficulties}"
             )
         
+        # Validate word count
+        if request.wordCount and (request.wordCount < 8 or request.wordCount > 15):
+            raise HTTPException(
+                status_code=400,
+                detail="Word count must be between 8 and 15"
+            )
+        
         # Generate puzzle
         puzzle_data = await crossword_gen.generate_puzzle(
             topics=request.topics,
             difficulty=request.difficulty,
-            use_ai=request.useAI
+            custom_sentence=request.customSentence,
+            multi_theme=request.multiTheme,
+            requested_words=request.wordCount
         )
         
         if not puzzle_data:
@@ -130,14 +151,12 @@ async def generate_words(
     try:
         words = await crossword_gen.generate_words_for_topics(
             topics=request.topics,
-            difficulty=request.difficulty,
-            use_ai=request.useAI
+            difficulty=request.difficulty
         )
         
         return {
             "topics": request.topics,
             "difficulty": request.difficulty,
-            "useAI": request.useAI,
             "wordCount": len(words),
             "words": words
         }
@@ -147,31 +166,129 @@ async def generate_words(
         raise HTTPException(status_code=500, detail=str(e))
 
 @router.get("/health")
-async def api_health():
-    """API health check."""
-    return {
+async def api_health(request: Request):
+    """API health check with cache status."""
+    thematic_service = getattr(request.app.state, 'thematic_service', None)
+    
+    health_info = {
         "status": "healthy",
         "timestamp": datetime.utcnow().isoformat(),
         "backend": "python",
-        "version": "2.0.0"
+        "version": "2.0.0",
+        "thematic_service": {
+            "available": thematic_service is not None,
+            "initialized": thematic_service.is_initialized if thematic_service else False
+        }
     }
+    
+    # Add cache status if service is available
+    if thematic_service:
+        try:
+            cache_status = thematic_service.get_cache_status()
+            health_info["cache"] = cache_status
+        except Exception as e:
+            health_info["cache"] = {"error": str(e)}
+    
+    return health_info
+
+@router.get("/health/cache")
+async def cache_health(request: Request):
+    """Detailed cache health check and status."""
+    thematic_service = getattr(request.app.state, 'thematic_service', None)
+    
+    if not thematic_service:
+        return {"error": "Thematic service not available"}
+    
+    try:
+        cache_status = thematic_service.get_cache_status()
+        
+        # Add additional diagnostic information
+        import os
+        cache_dir = cache_status['cache_directory']
+        
+        diagnostics = {
+            "cache_status": cache_status,
+            "diagnostics": {
+                "cache_dir_exists": os.path.exists(cache_dir),
+                "cache_dir_readable": os.access(cache_dir, os.R_OK) if os.path.exists(cache_dir) else False,
+                "cache_dir_writable": os.access(cache_dir, os.W_OK) if os.path.exists(cache_dir) else False,
+                "service_initialized": thematic_service.is_initialized,
+                "vocab_size_limit": thematic_service.vocab_size_limit,
+                "model_name": thematic_service.model_name
+            }
+        }
+        
+        # Add file listing if directory exists
+        if os.path.exists(cache_dir):
+            try:
+                cache_files = []
+                for file in os.listdir(cache_dir):
+                    file_path = os.path.join(cache_dir, file)
+                    if os.path.isfile(file_path):
+                        stat = os.stat(file_path)
+                        cache_files.append({
+                            "name": file,
+                            "size_bytes": stat.st_size,
+                            "size_mb": round(stat.st_size / (1024 * 1024), 2),
+                            "modified": datetime.fromtimestamp(stat.st_mtime).isoformat()
+                        })
+                diagnostics["cache_files"] = cache_files
+            except Exception as e:
+                diagnostics["cache_files_error"] = str(e)
+        
+        return diagnostics
+        
+    except Exception as e:
+        return {"error": f"Failed to get cache status: {e}"}
+
+@router.post("/health/cache/reinitialize")
+async def reinitialize_cache(request: Request):
+    """Force re-initialization of the thematic service and cache creation."""
+    thematic_service = getattr(request.app.state, 'thematic_service', None)
+    
+    if not thematic_service:
+        return {"error": "Thematic service not available"}
+    
+    try:
+        # Reset initialization flag to force re-initialization
+        thematic_service.is_initialized = False
+        
+        # Force re-initialization
+        await thematic_service.initialize_async()
+        
+        # Get updated cache status
+        cache_status = thematic_service.get_cache_status()
+        
+        return {
+            "message": "Cache re-initialization completed",
+            "cache_status": cache_status,
+            "timestamp": datetime.utcnow().isoformat()
+        }
+        
+    except Exception as e:
+        import traceback
+        return {
+            "error": f"Failed to reinitialize cache: {e}",
+            "traceback": traceback.format_exc(),
+            "timestamp": datetime.utcnow().isoformat()
+        }
 
-@router.get("/debug/vector-search")
-async def debug_vector_search(
+@router.get("/debug/thematic-search")
+async def debug_thematic_search(
     topic: str,
     difficulty: str = "medium",
     max_words: int = 10,
     request: Request = None
 ):
     """
-    Debug endpoint to test vector search directly.
+    Debug endpoint to test thematic word generation directly.
     """
     try:
-        vector_service = getattr(request.app.state, 'vector_service', None)
-        if not vector_service or not vector_service.is_initialized:
-            raise HTTPException(status_code=503, detail="Vector search service not available")
+        thematic_service = getattr(request.app.state, 'thematic_service', None)
+        if not thematic_service or not thematic_service.is_initialized:
+            raise HTTPException(status_code=503, detail="Thematic service not available")
         
-        words = await vector_service.find_similar_words(topic, difficulty, max_words)
+        words = await thematic_service.find_words_for_crossword([topic], difficulty, max_words)
         
         return {
             "topic": topic,
@@ -182,5 +299,5 @@ async def debug_vector_search(
         }
         
     except Exception as e:
-        logger.error(f"❌ Vector search debug failed: {e}")
+        logger.error(f"❌ Thematic search debug failed: {e}")
         raise HTTPException(status_code=500, detail=str(e))

crossword-app/backend-py/src/services///

@@ -0,0 +1,12 @@
+# cross-words
+
+- [x] tell claude it is stupid
+- [x] remove use_ai flag. always use AI. that was the plan
+- [ ] in the initialize function of vector search service log all config parameters. some config items are missing
+- [x] add filename line number to logs
+- [ ] make difficulty to tier mapping separate, configurable
+- [x] remove use_ai from frontend
+- [x] add more topics to choose
+- [ ] how to dynamically generate topics
+- [x] enable the difficulty chooser in frontend
+- [ ] let backend return multiple set of words and frontend use it one by one till crossword generation is success

crossword-app/backend-py/src/services/clue_generator.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+
+"""
+WordNet-Based Clue Generator for Crossword Puzzles
+
+Uses NLTK WordNet to generate crossword clues by analyzing word definitions,
+synonyms, hypernyms, and semantic relationships. Integrated with the thematic
+word generator for complete crossword creation without API dependencies.
+
+Features:
+- WordNet-based clue generation using definitions and relationships
+- Integration with UnifiedThematicWordGenerator for word discovery
+- Interactive mode with topic-based generation
+- Multiple clue styles (definition, synonym, category, descriptive)
+- Difficulty-based clue complexity
+- Caching for improved performance
+"""
+
+import os
+import sys
+import re
+import time
+import logging
+from typing import List, Dict, Optional, Tuple, Set, Any
+from pathlib import Path
+from dataclasses import dataclass
+from collections import defaultdict
+import random
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)

crossword-app/backend-py/src/services/crossword_generator.py

@@ -4,37 +4,30 @@ Fixed Crossword Generator - Ported from working JavaScript implementation.
 
 import asyncio
 import json
+import logging
 import random
 import time
 from pathlib import Path
 from typing import Dict, List, Optional, Any, Tuple
-import structlog
 
-logger = structlog.get_logger(__name__)
+logger = logging.getLogger(__name__)
 
 class CrosswordGenerator:
-    def __init__(self, vector_service=None):
+    def __init__(self, thematic_service=None):
         self.max_attempts = 100
         self.min_words = 6
-        self.max_words = 10  # Reduced from 12 to 10 for better success rate
-        self.vector_service = vector_service
+        self.thematic_service = thematic_service
 
-    async def generate_puzzle(self, topics: List[str], difficulty: str = "medium", use_ai: bool = False) -> Optional[Dict[str, Any]]:
+    async def generate_puzzle(self, topics: List[str], difficulty: str = "medium", custom_sentence: str = None, multi_theme: bool = True, requested_words: int = 10) -> Optional[Dict[str, Any]]:
         """
         Generate a complete crossword puzzle.
         """
         try:
-            # Import here to avoid circular imports - with fallback
-            try:
-                from .vector_search import VectorSearchService
-            except ImportError as import_error:
-                logger.warning(f"⚠️ Could not import VectorSearchService: {import_error}. Using static words only.")
-                # Continue without vector service
-            
-            logger.info(f"🎯 Generating puzzle for topics: {topics}, difficulty: {difficulty}, AI: {use_ai}")
+            sentence_info = f", custom sentence: '{custom_sentence}'" if custom_sentence else ""
+            logger.info(f"🎯 Generating puzzle for topics: {topics}, difficulty: {difficulty}{sentence_info}, requested words: {requested_words}")
             
-            # Get words (from AI or static)
-            words = await self._select_words(topics, difficulty, use_ai)
+            # Get words from thematic AI service
+            words = await self._select_words(topics, difficulty, custom_sentence, multi_theme, requested_words)
             
             if len(words) < self.min_words:
                 logger.error(f"❌ Not enough words: {len(words)} < {self.min_words}")
@@ -57,7 +50,7 @@ class CrosswordGenerator:
                     "difficulty": difficulty,
                     "wordCount": len(grid_result["placed_words"]),
                     "size": len(grid_result["grid"]),
-                    "aiGenerated": use_ai
+                    "aiGenerated": True
                 }
             }
             
@@ -65,66 +58,22 @@ class CrosswordGenerator:
             logger.error(f"❌ Error generating puzzle: {e}")
             raise
     
-    async def _select_words(self, topics: List[str], difficulty: str, use_ai: bool) -> List[Dict[str, Any]]:
-        """Select words for the crossword."""
-        all_words = []
-        
-        if use_ai and self.vector_service:
-            # Use the initialized vector service
-            logger.info(f"🤖 Using initialized vector service for AI word generation")
-            for topic in topics:
-                ai_words = await self.vector_service.find_similar_words(topic, difficulty, self.max_words // len(topics))
-                all_words.extend(ai_words)
-            
-            if len(all_words) >= self.min_words:
-                logger.info(f"✅ AI generated {len(all_words)} words")
-                return self._sort_words_for_crossword(all_words[:self.max_words])
-            else:
-                logger.warning(f"⚠️ AI only generated {len(all_words)} words, falling back to static")
-        
-        # Fallback to cached words
-        if self.vector_service:
-            # Use the cached words from the initialized service
-            logger.info(f"📦 Using cached words from initialized vector service")
-            for topic in topics:
-                cached_words = await self.vector_service._get_cached_fallback(topic, difficulty, self.max_words // len(topics))
-                all_words.extend(cached_words)
-        else:
-            # Last resort: load static words directly
-            logger.warning(f"⚠️ No vector service available, loading static words directly")
-            all_words = await self._get_static_words(topics, difficulty)
+    async def _select_words(self, topics: List[str], difficulty: str, custom_sentence: str = None, multi_theme: bool = True, requested_words: int = 10) -> List[Dict[str, Any]]:
+        """Select words for the crossword using thematic AI service."""
+        if not self.thematic_service:
+            raise Exception("Thematic service is required for word generation")
         
-        return self._sort_words_for_crossword(all_words[:self.max_words])
-    
-    async def _get_static_words(self, topics: List[str], difficulty: str) -> List[Dict[str, Any]]:
-        """Get static words from JSON files."""
-        all_words = []
-        
-        for topic in topics:
-            # Try multiple case variations
-            for topic_variation in [topic, topic.capitalize(), topic.lower()]:
-                word_file = Path(__file__).parent.parent.parent / "data" / "word-lists" / f"{topic_variation.lower()}.json"
-                
-                if word_file.exists():
-                    with open(word_file, 'r') as f:
-                        words = json.load(f)
-                        # Filter by difficulty
-                        filtered = self._filter_by_difficulty(words, difficulty)
-                        all_words.extend(filtered)
-                    break
-        
-        return all_words
-    
-    def _filter_by_difficulty(self, words: List[Dict[str, Any]], difficulty: str) -> List[Dict[str, Any]]:
-        """Filter words by difficulty (length)."""
-        difficulty_map = {
-            "easy": {"min_len": 3, "max_len": 8},
-            "medium": {"min_len": 4, "max_len": 10},
-            "hard": {"min_len": 5, "max_len": 15}
-        }
+        logger.info(f"🎯 Using thematic AI service for word generation with {requested_words} requested words")
+        
+        # Use the dedicated crossword method for better word selection
+        words = await self.thematic_service.find_words_for_crossword(topics, difficulty, requested_words, custom_sentence, multi_theme)
         
-        criteria = difficulty_map.get(difficulty, difficulty_map["medium"])
-        return [w for w in words if criteria["min_len"] <= len(w["word"]) <= criteria["max_len"]]
+        if len(words) < self.min_words:
+            raise Exception(f"Thematic service generated insufficient words: {len(words)} < {self.min_words}")
+        
+        logger.info(f"✅ Thematic service generated {len(words)} words")
+        return self._sort_words_for_crossword(words)
+    
     
     def _sort_words_for_crossword(self, words: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """Sort words by crossword suitability."""
@@ -271,11 +220,18 @@ class CrosswordGenerator:
                 logger.info(f"🔧 Backtrack successful, trimming grid...")
                 trimmed = self._trim_grid(grid, placed_words)
                 logger.info(f"🔧 Grid trimmed, generating clues...")
-                clues = self._generate_clues(word_objs, trimmed["placed_words"])
+                
+                # Generate clues first so we can display them with positions
+                clues_data = self._generate_clues_data(word_objs, trimmed["placed_words"])
+                
+                logger.info(f"🔧 Clues generated, assigning proper crossword numbers...")
+                
+                # Fix numbering based on grid position (reading order) and log with clues
+                numbered_words, clues = self._assign_numbers_and_clues(trimmed["placed_words"], clues_data)
                 
                 return {
                     "grid": trimmed["grid"],
-                    "placed_words": trimmed["placed_words"],
+                    "placed_words": numbered_words,
                     "clues": clues
                 }
             else:
@@ -634,6 +590,114 @@ class CrosswordGenerator:
         
         return {"grid": trimmed_grid, "placed_words": updated_words}
     
+    def _assign_crossword_numbers(self, placed_words: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Assign proper crossword numbers based on grid position (reading order).
+        
+        Crossword numbering rules:
+        1. Numbers are assigned to word starting positions
+        2. Reading order: top-to-bottom, then left-to-right  
+        3. A single number can be shared by both across and down words starting at the same cell
+        """
+        if not placed_words:
+            return placed_words
+        
+        # Collect all unique starting positions
+        starting_positions = {}  # (row, col) -> list of words starting at that position
+        
+        for word in placed_words:
+            pos_key = (word["row"], word["col"])
+            if pos_key not in starting_positions:
+                starting_positions[pos_key] = []
+            starting_positions[pos_key].append(word)
+        
+        # Sort positions by reading order (top-to-bottom, left-to-right)
+        sorted_positions = sorted(starting_positions.keys(), key=lambda pos: (pos[0], pos[1]))
+        
+        # Assign numbers
+        numbered_words = []
+        for i, pos in enumerate(sorted_positions):
+            number = i + 1  # Crossword numbers start at 1
+            
+            # Assign this number to all words starting at this position
+            for word in starting_positions[pos]:
+                numbered_word = word.copy()
+                numbered_word["number"] = number
+                numbered_words.append(numbered_word)
+        
+        logger.info(f"🔢 Assigned crossword numbers: {len(sorted_positions)} unique starting positions (legacy function)")
+        
+        return numbered_words
+    
+    def _generate_clues_data(self, word_objs: List[Dict[str, Any]], placed_words: List[Dict[str, Any]]) -> Dict[str, str]:
+        """Generate a mapping of words to their clues."""
+        clues_map = {}
+        
+        for placed_word in placed_words:
+            # Find matching word object
+            word_obj = next((w for w in word_objs if w["word"].upper() == placed_word["word"]), None)
+            
+            if word_obj and "clue" in word_obj:
+                clues_map[placed_word["word"]] = word_obj["clue"]
+            else:
+                clues_map[placed_word["word"]] = f"Clue for {placed_word['word']}"
+        
+        return clues_map
+    
+    def _assign_numbers_and_clues(self, placed_words: List[Dict[str, Any]], clues_data: Dict[str, str]) -> tuple:
+        """
+        Assign proper crossword numbers based on grid position and create clues with enhanced logging.
+        
+        Returns: (numbered_words, clues_list)
+        """
+        if not placed_words:
+            return placed_words, []
+        
+        # Collect all unique starting positions
+        starting_positions = {}  # (row, col) -> list of words starting at that position
+        
+        for word in placed_words:
+            pos_key = (word["row"], word["col"])
+            if pos_key not in starting_positions:
+                starting_positions[pos_key] = []
+            starting_positions[pos_key].append(word)
+        
+        # Sort positions by reading order (top-to-bottom, left-to-right)
+        sorted_positions = sorted(starting_positions.keys(), key=lambda pos: (pos[0], pos[1]))
+        
+        # Assign numbers and create both numbered words and clues
+        numbered_words = []
+        clues = []
+        
+        logger.info(f"🔢 Assigned crossword numbers: {len(sorted_positions)} unique starting positions")
+        
+        for i, pos in enumerate(sorted_positions):
+            number = i + 1  # Crossword numbers start at 1
+            
+            # Process all words starting at this position
+            for word in starting_positions[pos]:
+                numbered_word = word.copy()
+                numbered_word["number"] = number
+                numbered_words.append(numbered_word)
+                
+                # Create clue object
+                clue_text = clues_data.get(word["word"], f"Clue for {word['word']}")
+                direction = "across" if word["direction"] == "horizontal" else "down"
+                
+                clue = {
+                    "number": number,
+                    "word": word["word"],
+                    "text": clue_text,
+                    "direction": direction,
+                    "position": {"row": word["row"], "col": word["col"]}
+                }
+                clues.append(clue)
+                
+                # Enhanced logging with clues
+                logger.info(f"  {number} {direction}: {word['word']} at ({word['row']}, {word['col']}) - \"{clue_text}\"")
+        
+        return numbered_words, clues
+    
     def _create_simple_cross(self, word_list: List[str], word_objs: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
         """Create simple cross with two words."""
         if len(word_list) < 2:
@@ -678,31 +742,29 @@ class CrosswordGenerator:
         ]
         
         trimmed = self._trim_grid(grid, placed_words)
-        clues = self._generate_clues(word_objs[:2], trimmed["placed_words"])
+        
+        # Generate clues first, then assign numbers with enhanced logging
+        clues_data = self._generate_clues_data(word_objs[:2], trimmed["placed_words"])
+        numbered_words, clues = self._assign_numbers_and_clues(trimmed["placed_words"], clues_data)
         
         return {
             "grid": trimmed["grid"],
-            "placed_words": trimmed["placed_words"],
+            "placed_words": numbered_words,
             "clues": clues
         }
     
     def _generate_clues(self, word_objs: List[Dict[str, Any]], placed_words: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """Generate clues for placed words."""
-        logger.info(f"🔧 _generate_clues: word_objs={len(word_objs)}, placed_words={len(placed_words)}")
+        """Generate clues for placed words (legacy function - use _assign_numbers_and_clues for better logging)."""
         clues = []
         
         try:
-            for i, placed_word in enumerate(placed_words):
-                logger.info(f"🔧 Processing placed word {i}: {placed_word.get('word', 'UNKNOWN')}")
-                
+            for placed_word in placed_words:
                 # Find matching word object
                 word_obj = next((w for w in word_objs if w["word"].upper() == placed_word["word"]), None)
                 
-                if word_obj:
-                    logger.info(f"🔧 Found matching word_obj: {word_obj.get('word', 'UNKNOWN')}")
-                    clue_text = word_obj["clue"] if "clue" in word_obj else f"Clue for {placed_word['word']}"
+                if word_obj and "clue" in word_obj:
+                    clue_text = word_obj["clue"]
                 else:
-                    logger.warning(f"⚠️ No matching word_obj found for {placed_word['word']}")
                     clue_text = f"Clue for {placed_word['word']}"
                 
                 clues.append({
@@ -713,7 +775,6 @@ class CrosswordGenerator:
                     "position": {"row": placed_word["row"], "col": placed_word["col"]}
                 })
                 
-            logger.info(f"🔧 Generated {len(clues)} clues")
             return clues
         except Exception as e:
             logger.error(f"❌ Error in _generate_clues: {e}")

crossword-app/backend-py/src/services/crossword_generator_wrapper.py

@@ -12,16 +12,18 @@ class CrosswordGenerator:
     Wrapper that uses the fixed crossword generator implementation.
     """
     
-    def __init__(self, vector_service=None):
-        self.vector_service = vector_service
+    def __init__(self, thematic_service=None):
+        self.thematic_service = thematic_service
         self.min_words = 8
         self.max_words = 15
 
     async def generate_puzzle(
         self, 
         topics: List[str], 
-        difficulty: str = "medium", 
-        use_ai: bool = False
+        difficulty: str = "medium",
+        custom_sentence: str = None,
+        multi_theme: bool = True,
+        requested_words: int = 10
     ) -> Dict[str, Any]:
         """
         Generate a complete crossword puzzle using the fixed generator.
@@ -29,19 +31,21 @@ class CrosswordGenerator:
         Args:
             topics: List of topic strings
             difficulty: "easy", "medium", or "hard"
-            use_ai: Whether to use vector search for word generation
+            custom_sentence: Optional custom sentence to influence word selection
+            multi_theme: Whether to use multi-theme processing (True) or single-theme blending (False)
+            requested_words: Number of words requested by frontend
             
         Returns:
             Dictionary containing grid, clues, and metadata
         """
         try:
-            logger.info(f"🎯 Using fixed crossword generator for topics: {topics}")
+            logger.info(f"🎯 Using fixed crossword generator for topics: {topics}, requested words: {requested_words}")
             
-            # Use the fixed generator implementation with the initialized vector service
+            # Use the fixed generator implementation with the initialized thematic service
             from .crossword_generator import CrosswordGenerator as ActualGenerator
-            actual_generator = ActualGenerator(vector_service=self.vector_service)
+            actual_generator = ActualGenerator(thematic_service=self.thematic_service)
             
-            puzzle = await actual_generator.generate_puzzle(topics, difficulty, use_ai)
+            puzzle = await actual_generator.generate_puzzle(topics, difficulty, custom_sentence, multi_theme, requested_words)
             
             logger.info(f"✅ Generated crossword with fixed algorithm")
             return puzzle
@@ -50,9 +54,9 @@ class CrosswordGenerator:
             logger.error(f"❌ Failed to generate puzzle: {e}")
             raise
 
-    async def generate_words_for_topics(self, topics: List[str], difficulty: str, use_ai: bool) -> List[Dict[str, Any]]:
+    async def generate_words_for_topics(self, topics: List[str], difficulty: str, custom_sentence: str = None) -> List[Dict[str, Any]]:
         """Backward compatibility method."""
         # This method is kept for compatibility but delegates to the fixed generator
         from .crossword_generator import CrosswordGenerator as ActualGenerator
-        actual_generator = ActualGenerator()
-        return await actual_generator._select_words(topics, difficulty, use_ai)
+        actual_generator = ActualGenerator(thematic_service=self.thematic_service)
+        return await actual_generator._select_words(topics, difficulty, custom_sentence)

crossword-app/backend-py/src/services/thematic_word_service.py

@@ -0,0 +1,1057 @@
+#!/usr/bin/env python3
+"""
+Unified Thematic Word Generator using WordFreq + SentenceTransformers
+
+Eliminates vocabulary redundancy by using WordFreq as the single vocabulary source
+for both word lists and frequency data, with all-mpnet-base-v2 for embeddings.
+
+Features:
+- Single vocabulary source (WordFreq 319K words vs previous 3 separate sources)
+- Unified filtering for crossword-suitable words
+- 10-tier frequency classification system
+- Compatible with crossword backend services
+- Comprehensive modern vocabulary with proper frequency data
+- Environment variable configuration for cache paths and settings
+
+Environment Variables:
+- CACHE_DIR: Cache directory for all thematic service files (default: ./model_cache)
+- THEMATIC_VOCAB_SIZE_LIMIT: Maximum vocabulary size (default: 100000)
+- MAX_VOCABULARY_SIZE: Fallback vocab size limit (used if THEMATIC_VOCAB_SIZE_LIMIT not set)
+- THEMATIC_MODEL_NAME: Sentence transformer model to use (default: all-mpnet-base-v2)
+
+Cache Structure:
+- {cache_dir}/vocabulary_{size}.pkl - Processed vocabulary words
+- {cache_dir}/frequencies_{size}.pkl - Word frequency data
+- {cache_dir}/embeddings_{model}_{size}.npy - Word embeddings
+- {cache_dir}/sentence-transformers/ - Hugging Face model cache
+
+Usage:
+  # Use environment variables for production
+  export CACHE_DIR=/app/cache
+  export THEMATIC_VOCAB_SIZE_LIMIT=50000
+  
+  # Or pass directly to constructor for development
+  service = ThematicWordService(cache_dir="/custom/path", vocab_size_limit=25000)
+"""
+
+import os
+import csv
+import pickle
+import numpy as np
+import logging
+import asyncio
+import random
+from typing import List, Tuple, Optional, Dict, Set, Any
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+from sklearn.cluster import KMeans
+from datetime import datetime
+import time
+from collections import Counter
+from pathlib import Path
+
+# WordFreq imports (assumed to be available)
+from wordfreq import word_frequency, zipf_frequency, top_n_list
+
+# Use backend's logging configuration
+logger = logging.getLogger(__name__)
+
+def get_timestamp():
+    return datetime.now().strftime("%H:%M:%S")
+
+def get_datetimestamp():
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+class VocabularyManager:
+    """
+    Centralized vocabulary management using WordFreq as the single source.
+    Handles loading, filtering, caching, and frequency data generation.
+    """
+    
+    def __init__(self, cache_dir: Optional[str] = None, vocab_size_limit: Optional[int] = None):
+        """Initialize vocabulary manager.
+        
+        Args:
+            cache_dir: Directory for caching vocabulary and embeddings
+            vocab_size_limit: Maximum vocabulary size (None for full WordFreq vocabulary)
+        """
+        if cache_dir is None:
+            # Check environment variable for cache directory
+            cache_dir = os.getenv("CACHE_DIR")
+            if cache_dir is None:
+                cache_dir = os.path.join(os.path.dirname(__file__), 'model_cache')
+        
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Vocabulary size configuration
+        self.vocab_size_limit = vocab_size_limit or int(os.getenv("THEMATIC_VOCAB_SIZE_LIMIT", 
+                                                                 os.getenv("MAX_VOCABULARY_SIZE", "100000")))
+        
+        # Cache paths
+        self.vocab_cache_path = self.cache_dir / f"vocabulary_{self.vocab_size_limit}.pkl"
+        self.frequency_cache_path = self.cache_dir / f"frequencies_{self.vocab_size_limit}.pkl"
+        
+        # Loaded data
+        self.vocabulary: List[str] = []
+        self.word_frequencies: Counter = Counter()
+        self.is_loaded = False
+        
+    def load_vocabulary(self) -> Tuple[List[str], Counter]:
+        """Load vocabulary and frequency data, with caching."""
+        if self.is_loaded:
+            return self.vocabulary, self.word_frequencies
+            
+        # Try loading from cache
+        if self._load_from_cache():
+            logger.info(f"✅ Loaded vocabulary from cache: {len(self.vocabulary):,} words")
+            self.is_loaded = True
+            return self.vocabulary, self.word_frequencies
+        
+        # Generate from WordFreq
+        logger.info("🔄 Generating vocabulary from WordFreq...")
+        self._generate_vocabulary_from_wordfreq()
+        
+        # Save to cache
+        self._save_to_cache()
+        
+        self.is_loaded = True
+        return self.vocabulary, self.word_frequencies
+    
+    def _load_from_cache(self) -> bool:
+        """Load vocabulary and frequencies from cache."""
+        try:
+            if self.vocab_cache_path.exists() and self.frequency_cache_path.exists():
+                logger.info(f"📦 Loading vocabulary from cache...")
+                logger.info(f"  Vocab cache: {self.vocab_cache_path}")
+                logger.info(f"  Freq cache: {self.frequency_cache_path}")
+                
+                # Validate cache files are readable
+                if not os.access(self.vocab_cache_path, os.R_OK):
+                    logger.warning(f"⚠️ Vocabulary cache file not readable: {self.vocab_cache_path}")
+                    return False
+                    
+                if not os.access(self.frequency_cache_path, os.R_OK):
+                    logger.warning(f"⚠️ Frequency cache file not readable: {self.frequency_cache_path}")
+                    return False
+                
+                with open(self.vocab_cache_path, 'rb') as f:
+                    self.vocabulary = pickle.load(f)
+                    
+                with open(self.frequency_cache_path, 'rb') as f:
+                    self.word_frequencies = pickle.load(f)
+                
+                # Validate loaded data
+                if not self.vocabulary or not self.word_frequencies:
+                    logger.warning("⚠️ Cache files contain empty data")
+                    return False
+                    
+                logger.info(f"✅ Loaded {len(self.vocabulary):,} words and {len(self.word_frequencies):,} frequencies from cache")
+                return True
+            else:
+                missing = []
+                if not self.vocab_cache_path.exists():
+                    missing.append(f"vocabulary ({self.vocab_cache_path})")
+                if not self.frequency_cache_path.exists():
+                    missing.append(f"frequency ({self.frequency_cache_path})")
+                logger.info(f"📂 Cache files missing: {', '.join(missing)}")
+                return False
+        except Exception as e:
+            logger.warning(f"⚠️ Cache loading failed: {e}")
+            
+        return False
+    
+    def _save_to_cache(self):
+        """Save vocabulary and frequencies to cache."""
+        try:
+            logger.info("💾 Saving vocabulary to cache...")
+            
+            with open(self.vocab_cache_path, 'wb') as f:
+                pickle.dump(self.vocabulary, f)
+                
+            with open(self.frequency_cache_path, 'wb') as f:
+                pickle.dump(self.word_frequencies, f)
+                
+            logger.info("✅ Vocabulary cached successfully")
+        except Exception as e:
+            logger.warning(f"⚠️ Cache saving failed: {e}")
+    
+    def _generate_vocabulary_from_wordfreq(self):
+        """Generate filtered vocabulary from WordFreq database."""
+        logger.info(f"📚 Fetching top {self.vocab_size_limit:,} words from WordFreq...")
+        
+        # Get comprehensive word list from WordFreq
+        raw_words = top_n_list('en', self.vocab_size_limit * 2, wordlist='large')  # Get extra for filtering
+        logger.info(f"📥 Retrieved {len(raw_words):,} raw words from WordFreq")
+        
+        # Apply crossword-suitable filtering
+        filtered_words = []
+        frequency_data = Counter()
+        
+        logger.info("🔍 Applying crossword filtering...")
+        for word in raw_words:
+            if self._is_crossword_suitable(word):
+                filtered_words.append(word.lower())
+                
+                # Get frequency data
+                try:
+                    freq = word_frequency(word, 'en', wordlist='large')
+                    if freq > 0:
+                        # Scale frequency to preserve precision
+                        frequency_data[word.lower()] = int(freq * 1e9)
+                except:
+                    frequency_data[word.lower()] = 1  # Minimal frequency for unknown words
+                
+                if len(filtered_words) >= self.vocab_size_limit:
+                    break
+        
+        # Remove duplicates and sort
+        self.vocabulary = sorted(list(set(filtered_words)))
+        self.word_frequencies = frequency_data
+        
+        logger.info(f"✅ Generated filtered vocabulary: {len(self.vocabulary):,} words")
+        logger.info(f"📊 Frequency data coverage: {len(self.word_frequencies):,} words")
+    
+    def _is_crossword_suitable(self, word: str) -> bool:
+        """Check if word is suitable for crosswords."""
+        word = word.lower().strip()
+        
+        # Length check (3-12 characters for crosswords)
+        if len(word) < 3 or len(word) > 12:
+            return False
+            
+        # Must be alphabetic only
+        if not word.isalpha():
+            return False
+            
+        # Skip boring/common words
+        boring_words = {
+            'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'this', 'that',
+            'with', 'from', 'they', 'were', 'been', 'have', 'their', 'said', 'each',
+            'which', 'what', 'there', 'will', 'more', 'when', 'some', 'like', 'into',
+            'time', 'very', 'only', 'has', 'had', 'who', 'its', 'now', 'find', 'long',
+            'down', 'day', 'did', 'get', 'come', 'made', 'may', 'part'
+        }
+        
+        if word in boring_words:
+            return False
+            
+        # Skip obvious plurals (simple heuristic)
+        if len(word) > 4 and word.endswith('s') and not word.endswith(('ss', 'us', 'is')):
+            return False
+            
+        # Skip words with repeated characters (often not real words)
+        if len(set(word)) < len(word) * 0.6:  # Less than 60% unique characters
+            return False
+            
+        return True
+
+
+class ThematicWordService:
+    """
+    Unified thematic word generator using WordFreq vocabulary and all-mpnet-base-v2 embeddings.
+    
+    Compatible with both hack tools and crossword backend services.
+    Eliminates vocabulary redundancy by using single source for everything.
+    """
+    
+    def __init__(self, cache_dir: Optional[str] = None, model_name: str = 'all-mpnet-base-v2', 
+                 vocab_size_limit: Optional[int] = None):
+        """Initialize the unified thematic word generator.
+        
+        Args:
+            cache_dir: Directory to cache model and embeddings
+            model_name: Sentence transformer model to use
+            vocab_size_limit: Maximum vocabulary size (None for 100K default)
+        """
+        if cache_dir is None:
+            # Check environment variable for cache directory
+            cache_dir = os.getenv("CACHE_DIR")
+            if cache_dir is None:
+                cache_dir = os.path.join(os.path.dirname(__file__), 'model_cache')
+        
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Get model name from environment if not specified
+        self.model_name = os.getenv("THEMATIC_MODEL_NAME", model_name)
+        
+        # Get vocabulary size limit from environment if not specified
+        self.vocab_size_limit = (vocab_size_limit or 
+                                int(os.getenv("THEMATIC_VOCAB_SIZE_LIMIT", 
+                                             os.getenv("MAX_VOCABULARY_SIZE", "100000"))))
+        
+        # Core components
+        self.vocab_manager = VocabularyManager(str(self.cache_dir), self.vocab_size_limit)
+        self.model: Optional[SentenceTransformer] = None
+        
+        # Loaded data
+        self.vocabulary: List[str] = []
+        self.word_frequencies: Counter = Counter()
+        self.vocab_embeddings: Optional[np.ndarray] = None
+        self.frequency_tiers: Dict[str, str] = {}
+        self.tier_descriptions: Dict[str, str] = {}
+        
+        # Cache paths for embeddings
+        vocab_hash = f"{self.model_name.replace('/', '_')}_{self.vocab_size_limit}"
+        self.embeddings_cache_path = self.cache_dir / f"embeddings_{vocab_hash}.npy"
+        
+        self.is_initialized = False
+    
+    def initialize(self):
+        """Initialize the generator (synchronous version)."""
+        if self.is_initialized:
+            return
+            
+        start_time = time.time()
+        logger.info(f"🚀 Initializing Thematic Word Service...")
+        logger.info(f"📁 Cache directory: {self.cache_dir}")
+        logger.info(f"🤖 Model: {self.model_name}")
+        logger.info(f"📊 Vocabulary size limit: {self.vocab_size_limit:,}")
+        
+        # Check if cache directory exists and is accessible
+        if not self.cache_dir.exists():
+            logger.warning(f"⚠️ Cache directory does not exist, creating: {self.cache_dir}")
+            try:
+                self.cache_dir.mkdir(parents=True, exist_ok=True)
+            except Exception as e:
+                logger.error(f"❌ Failed to create cache directory: {e}")
+                raise
+        
+        # Load vocabulary and frequency data
+        vocab_start = time.time()
+        self.vocabulary, self.word_frequencies = self.vocab_manager.load_vocabulary()
+        vocab_time = time.time() - vocab_start
+        logger.info(f"✅ Vocabulary loaded in {vocab_time:.2f}s: {len(self.vocabulary):,} words")
+        
+        # Load or create frequency tiers
+        self.frequency_tiers = self._create_frequency_tiers()
+        
+        # Load model
+        logger.info(f"🤖 Loading embedding model: {self.model_name}")
+        model_start = time.time()
+        self.model = SentenceTransformer(
+            f'sentence-transformers/{self.model_name}',
+            cache_folder=str(self.cache_dir)
+        )
+        model_time = time.time() - model_start
+        logger.info(f"✅ Model loaded in {model_time:.2f}s")
+        
+        # Load or create embeddings
+        self.vocab_embeddings = self._load_or_create_embeddings()
+        
+        self.is_initialized = True
+        total_time = time.time() - start_time
+        logger.info(f"🎉 Unified generator initialized in {total_time:.2f}s")
+        logger.info(f"📊 Vocabulary: {len(self.vocabulary):,} words")
+        logger.info(f"📈 Frequency data: {len(self.word_frequencies):,} words")
+    
+    async def initialize_async(self):
+        """Initialize the generator (async version for backend compatibility)."""
+        return self.initialize()  # For now, same as sync version
+    
+    def _load_or_create_embeddings(self) -> np.ndarray:
+        """Load embeddings from cache or create them."""
+        # Try loading from cache
+        if self.embeddings_cache_path.exists():
+            try:
+                logger.info(f"📦 Loading embeddings from cache: {self.embeddings_cache_path}")
+                
+                # Validate cache file is readable
+                if not os.access(self.embeddings_cache_path, os.R_OK):
+                    logger.warning(f"⚠️ Embeddings cache file not readable: {self.embeddings_cache_path}")
+                    return self._create_embeddings_from_scratch()
+                
+                embeddings = np.load(self.embeddings_cache_path)
+                
+                # Validate embeddings shape matches vocabulary size
+                expected_shape = (len(self.vocabulary), None)  # Second dimension varies by model
+                if embeddings.shape[0] != len(self.vocabulary):
+                    logger.warning(f"⚠️ Embeddings shape mismatch: cache={embeddings.shape[0]}, vocab={len(self.vocabulary)}")
+                    logger.warning("🔄 Vocabulary size changed, recreating embeddings...")
+                    return self._create_embeddings_from_scratch()
+                
+                logger.info(f"✅ Loaded embeddings from cache: {embeddings.shape}")
+                return embeddings
+            except Exception as e:
+                logger.warning(f"⚠️ Embeddings cache loading failed: {e}")
+                return self._create_embeddings_from_scratch()
+        else:
+            logger.info(f"📂 Embeddings cache not found: {self.embeddings_cache_path}")
+            return self._create_embeddings_from_scratch()
+
+    def _create_embeddings_from_scratch(self) -> np.ndarray:
+        
+        # Create embeddings
+        logger.info("🔄 Creating embeddings for vocabulary...")
+        start_time = time.time()
+        
+        # Create embeddings in batches for memory efficiency
+        batch_size = 512
+        all_embeddings = []
+        
+        for i in range(0, len(self.vocabulary), batch_size):
+            batch_words = self.vocabulary[i:i + batch_size]
+            batch_embeddings = self.model.encode(
+                batch_words,
+                convert_to_tensor=False,
+                show_progress_bar=i == 0  # Only show progress for first batch
+            )
+            all_embeddings.append(batch_embeddings)
+            
+            if i % (batch_size * 10) == 0:
+                logger.info(f"📊 Embeddings progress: {i:,}/{len(self.vocabulary):,}")
+        
+        embeddings = np.vstack(all_embeddings)
+        embedding_time = time.time() - start_time
+        logger.info(f"✅ Created embeddings in {embedding_time:.2f}s: {embeddings.shape}")
+        
+        # Save to cache
+        try:
+            np.save(self.embeddings_cache_path, embeddings)
+            logger.info("💾 Embeddings cached successfully")
+        except Exception as e:
+            logger.warning(f"⚠️ Embeddings cache saving failed: {e}")
+        
+        return embeddings
+    
+    def _create_frequency_tiers(self) -> Dict[str, str]:
+        """Create 10-tier frequency classification system."""
+        if not self.word_frequencies:
+            return {}
+        
+        logger.info("📊 Creating frequency tiers...")
+        
+        tiers = {}
+        
+        # Calculate percentile-based thresholds for even distribution
+        all_counts = list(self.word_frequencies.values())
+        all_counts.sort(reverse=True)
+        
+        # Define 10 tiers with percentile-based thresholds
+        tier_definitions = [
+            ("tier_1_ultra_common", 0.999, "Ultra Common (Top 0.1%)"),
+            ("tier_2_extremely_common", 0.995, "Extremely Common (Top 0.5%)"), 
+            ("tier_3_very_common", 0.99, "Very Common (Top 1%)"),
+            ("tier_4_highly_common", 0.97, "Highly Common (Top 3%)"),
+            ("tier_5_common", 0.92, "Common (Top 8%)"),
+            ("tier_6_moderately_common", 0.85, "Moderately Common (Top 15%)"),
+            ("tier_7_somewhat_uncommon", 0.70, "Somewhat Uncommon (Top 30%)"),
+            ("tier_8_uncommon", 0.50, "Uncommon (Top 50%)"),
+            ("tier_9_rare", 0.25, "Rare (Top 75%)"),
+            ("tier_10_very_rare", 0.0, "Very Rare (Bottom 25%)")
+        ]
+        
+        # Calculate actual thresholds
+        thresholds = []
+        for tier_name, percentile, description in tier_definitions:
+            if percentile > 0:
+                idx = int((1 - percentile) * len(all_counts))
+                threshold = all_counts[min(idx, len(all_counts) - 1)]
+            else:
+                threshold = 0
+            thresholds.append((tier_name, threshold, description))
+        
+        # Store descriptions
+        self.tier_descriptions = {name: desc for name, _, desc in thresholds}
+        
+        # Assign tiers
+        for word, count in self.word_frequencies.items():
+            assigned = False
+            for tier_name, threshold, description in thresholds:
+                if count >= threshold:
+                    tiers[word] = tier_name
+                    assigned = True
+                    break
+            
+            if not assigned:
+                tiers[word] = "tier_10_very_rare"
+        
+        # Words not in frequency data are very rare
+        for word in self.vocabulary:
+            if word not in tiers:
+                tiers[word] = "tier_10_very_rare"
+        
+        # Log tier distribution
+        tier_counts = Counter(tiers.values())
+        logger.info(f"✅ Created frequency tiers:")
+        for tier_name, count in sorted(tier_counts.items()):
+            desc = self.tier_descriptions.get(tier_name, tier_name)
+            logger.info(f"   {desc}: {count:,} words")
+        
+        return tiers
+    
+    def generate_thematic_words(self, 
+                              inputs, 
+                              num_words: int = 100, 
+                              min_similarity: float = 0.3,
+                              multi_theme: bool = False,
+                              difficulty_tier: Optional[str] = None) -> List[Tuple[str, float, str]]:
+        """Generate thematically related words from input seeds.
+        
+        Args:
+            inputs: Single string, or list of words/sentences as theme seeds
+            num_words: Number of words to return
+            min_similarity: Minimum similarity threshold
+            multi_theme: Whether to detect and use multiple themes
+            difficulty_tier: Specific tier to filter by (e.g., "tier_5_common")
+            
+        Returns:
+            List of (word, similarity_score, frequency_tier) tuples
+        """
+        if not self.is_initialized:
+            self.initialize()
+        
+        logger.info(f"🎯 Generating {num_words} thematic words")
+        
+        # Handle single string input (convert to list for compatibility)
+        if isinstance(inputs, str):
+            inputs = [inputs]
+        
+        if not inputs:
+            return []
+        
+        # Clean inputs
+        clean_inputs = [inp.strip().lower() for inp in inputs if inp.strip()]
+        if not clean_inputs:
+            return []
+        
+        logger.info(f"📝 Input themes: {clean_inputs}")
+        if difficulty_tier:
+            logger.info(f"📊 Filtering to tier: {self.tier_descriptions.get(difficulty_tier, difficulty_tier)}")
+        
+        # Get theme vector(s) using original logic
+        # Auto-enable multi-theme for 3+ inputs (matching original behavior)
+        auto_multi_theme = len(clean_inputs) > 2
+        final_multi_theme = multi_theme or auto_multi_theme
+        
+        logger.info(f"🔍 Multi-theme detection: {final_multi_theme} (auto: {auto_multi_theme}, manual: {multi_theme})")
+        
+        if final_multi_theme:
+            theme_vectors = self._detect_multiple_themes(clean_inputs)
+            logger.info(f"📊 Detected {len(theme_vectors)} themes")
+        else:
+            theme_vectors = [self._compute_theme_vector(clean_inputs)]
+            logger.info("📊 Using single theme vector")
+
+        # Collect similarities from all themes
+        all_similarities = np.zeros(len(self.vocabulary))
+        
+        for theme_vector in theme_vectors:
+            # Compute similarities with vocabulary
+            similarities = cosine_similarity(theme_vector, self.vocab_embeddings)[0]
+            all_similarities += similarities / len(theme_vectors)  # Average across themes
+        
+        logger.info("✅ Computed semantic similarities")
+        
+        # Get top candidates sorted by similarity
+        # np.argsort() returns indices that would sort array in ascending order
+        # [::-1] reverses to get descending order (highest similarity first)
+        # top_indices[0] contains the vocabulary index of the word most similar to theme vector
+        top_indices = np.argsort(all_similarities)[::-1]
+        
+        # Filter and format results
+        results = []
+        input_words_set = set(clean_inputs)
+        logger.info(f"{clean_inputs=}")
+        
+        # Traverse top_indices from beginning to get most similar words first
+        # Each idx is used to lookup the actual word in self.vocabulary[idx]
+        for idx in top_indices:
+            if len(results) >= num_words * 3:  # Get extra candidates for filtering
+                break
+                
+            similarity_score = all_similarities[idx]
+            word = self.vocabulary[idx]  # Get actual word using vocabulary index
+            
+            # Apply filters - use early termination since top_indices is sorted by similarity
+            if similarity_score < min_similarity:
+                break  # All remaining words will also be below threshold since array is sorted
+                
+            # Skip input words themselves
+            if word.lower() in input_words_set:
+                continue
+            
+            # Get pre-assigned tier for this word
+            # Tiers are computed during initialization using WordFreq data
+            # Based on percentile thresholds: tier_1 (top 0.1%), tier_5 (top 8%), etc.
+            word_tier = self.frequency_tiers.get(word, "tier_10_very_rare")
+            
+            # Filter by difficulty tier if specified
+            # If difficulty_tier is specified, only include words from that exact tier
+            # If no difficulty_tier specified, include all words (subject to similarity threshold)
+            if difficulty_tier and word_tier != difficulty_tier:
+                continue
+            
+            results.append((word, similarity_score, word_tier))
+        
+        # Sort by similarity and return top results
+        results.sort(key=lambda x: x[1], reverse=True)
+        final_results = results[:num_words]
+        
+        logger.info(f"✅ Generated {len(final_results)} thematic words")
+        return final_results
+    
+    def _compute_theme_vector(self, inputs: List[str]) -> np.ndarray:
+        """Compute semantic centroid from input words/sentences."""
+        logger.info(f"🎯 Computing theme vector for {len(inputs)} inputs")
+        
+        # Encode all inputs
+        input_embeddings = self.model.encode(inputs, convert_to_tensor=False, show_progress_bar=False)
+        logger.info(f"✅ Encoded {len(inputs)} inputs")
+        
+        # Simple approach: average all input embeddings
+        theme_vector = np.mean(input_embeddings, axis=0)
+        
+        return theme_vector.reshape(1, -1)
+    
+    def _detect_multiple_themes(self, inputs: List[str], max_themes: int = 3) -> List[np.ndarray]:
+        """Detect multiple themes using clustering."""
+        if len(inputs) < 2:
+            return [self._compute_theme_vector(inputs)]
+        
+        logger.info(f"🔍 Detecting multiple themes from {len(inputs)} inputs")
+        
+        # Encode inputs
+        input_embeddings = self.model.encode(inputs, convert_to_tensor=False, show_progress_bar=False)
+        logger.info("✅ Encoded inputs for clustering")
+        
+        # Determine optimal number of clusters
+        n_clusters = min(max_themes, len(inputs), 3)
+        logger.info(f"📊 Using {n_clusters} clusters for theme detection")
+        
+        if n_clusters == 1:
+            return [np.mean(input_embeddings, axis=0).reshape(1, -1)]
+        
+        # Perform clustering
+        kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
+        kmeans.fit(input_embeddings)
+        
+        logger.info(f"✅ Clustered inputs into {n_clusters} themes")
+        
+        # Return cluster centers as theme vectors
+        return [center.reshape(1, -1) for center in kmeans.cluster_centers_]
+    
+    def get_tier_words(self, tier: str, limit: int = 1000) -> List[str]:
+        """Get all words from a specific frequency tier.
+        
+        Args:
+            tier: Frequency tier name (e.g., "tier_5_common")
+            limit: Maximum number of words to return
+            
+        Returns:
+            List of words in the specified tier
+        """
+        if not self.is_initialized:
+            self.initialize()
+            
+        tier_words = [word for word, word_tier in self.frequency_tiers.items() 
+                     if word_tier == tier]
+        
+        return tier_words[:limit]
+    
+    def get_word_info(self, word: str) -> Dict[str, Any]:
+        """Get comprehensive information about a word.
+        
+        Args:
+            word: Word to get information for
+            
+        Returns:
+            Dictionary with word info including frequency, tier, etc.
+        """
+        if not self.is_initialized:
+            self.initialize()
+            
+        word_lower = word.lower()
+        
+        info = {
+            'word': word,
+            'in_vocabulary': word_lower in self.vocabulary,
+            'frequency': self.word_frequencies.get(word_lower, 0),
+            'tier': self.frequency_tiers.get(word_lower, "tier_10_very_rare"),
+            'tier_description': self.tier_descriptions.get(
+                self.frequency_tiers.get(word_lower, "tier_10_very_rare"),
+                "Unknown"
+            )
+        }
+        
+        return info
+    
+    # Backend compatibility methods
+    async def find_similar_words(self, topic: str, difficulty: str = "medium", max_words: int = 15) -> List[Dict[str, Any]]:
+        """Backend-compatible method for finding similar words.
+        
+        Returns list of word dictionaries compatible with crossword_generator.py
+        Expected format: [{"word": str, "clue": str}, ...]
+        """
+        # Map difficulty to appropriate tier filtering
+        difficulty_tier_map = {
+            "easy": [ "tier_2_extremely_common", "tier_3_very_common", "tier_4_highly_common"],
+            "medium": ["tier_4_highly_common", "tier_5_common", "tier_6_moderately_common", "tier_7_somewhat_uncommon"],
+            "hard": ["tier_7_somewhat_uncommon", "tier_8_uncommon", "tier_9_rare"]
+        }
+        
+        allowed_tiers = difficulty_tier_map.get(difficulty, difficulty_tier_map["medium"])
+        
+        # Get thematic words
+        all_results = self.generate_thematic_words(
+            topic, 
+            num_words=150,  # Get extra for filtering
+            min_similarity=0.3
+        )
+        
+        # Filter by difficulty and format for backend
+        backend_words = []
+        for word, similarity, tier in all_results:
+            # Check difficulty criteria
+            if not self._matches_backend_difficulty(word, difficulty):
+                continue
+                
+            # Optional tier filtering for more precise difficulty control
+            # (Comment out if tier filtering is too restrictive)
+            # if tier not in allowed_tiers:
+            #     continue
+            
+            # Format for backend compatibility
+            backend_word = {
+                "word": word.upper(),  # Backend expects uppercase
+                "clue": self._generate_simple_clue(word, topic),
+                "similarity": similarity,
+                "tier": tier
+            }
+            
+            backend_words.append(backend_word)
+            
+            if len(backend_words) >= max_words:
+                break
+        
+        logger.info(f"🎯 Generated {len(backend_words)} words for topic '{topic}' (difficulty: {difficulty})")
+        return backend_words
+    
+    def _matches_backend_difficulty(self, word: str, difficulty: str) -> bool:
+        """Check if word matches backend difficulty criteria."""
+        difficulty_map = {
+            "easy": {"min_len": 3, "max_len": 8},
+            "medium": {"min_len": 4, "max_len": 10},
+            "hard": {"min_len": 5, "max_len": 15}
+        }
+        
+        criteria = difficulty_map.get(difficulty, difficulty_map["medium"])
+        return criteria["min_len"] <= len(word) <= criteria["max_len"]
+    
+    def _generate_simple_clue(self, word: str, topic: str) -> str:
+        """Generate a simple clue for the word (backend compatibility)."""
+        # Basic clue templates matching backend expectations
+        word_lower = word.lower()
+        topic_lower = topic.lower()
+        
+        # Topic-specific clue templates
+        if "animal" in topic_lower:
+            return f"{word_lower} (animal)"
+        elif "tech" in topic_lower or "computer" in topic_lower:
+            return f"{word_lower} (technology)"
+        elif "science" in topic_lower:
+            return f"{word_lower} (science)"
+        elif "geo" in topic_lower or "place" in topic_lower:
+            return f"{word_lower} (geography)"
+        elif "food" in topic_lower:
+            return f"{word_lower} (food)"
+        else:
+            return f"{word_lower} (related to {topic_lower})"
+    
+    def get_vocabulary_size(self) -> int:
+        """Get the size of the loaded vocabulary."""
+        return len(self.vocabulary)
+    
+    def get_tier_distribution(self) -> Dict[str, int]:
+        """Get distribution of words across frequency tiers."""
+        if not self.frequency_tiers:
+            return {}
+            
+        tier_counts = Counter(self.frequency_tiers.values())
+        return dict(tier_counts)
+
+    def get_cache_status(self) -> Dict[str, Any]:
+        """Get detailed cache status information."""
+        vocab_exists = self.vocab_manager.vocab_cache_path.exists()
+        freq_exists = self.vocab_manager.frequency_cache_path.exists()
+        embeddings_exists = self.embeddings_cache_path.exists()
+        
+        status = {
+            "cache_directory": str(self.cache_dir),
+            "vocabulary_cache": {
+                "path": str(self.vocab_manager.vocab_cache_path),
+                "exists": vocab_exists,
+                "readable": vocab_exists and os.access(self.vocab_manager.vocab_cache_path, os.R_OK)
+            },
+            "frequency_cache": {
+                "path": str(self.vocab_manager.frequency_cache_path),
+                "exists": freq_exists,
+                "readable": freq_exists and os.access(self.vocab_manager.frequency_cache_path, os.R_OK)
+            },
+            "embeddings_cache": {
+                "path": str(self.embeddings_cache_path),
+                "exists": embeddings_exists,
+                "readable": embeddings_exists and os.access(self.embeddings_cache_path, os.R_OK)
+            },
+            "complete": vocab_exists and freq_exists and embeddings_exists
+        }
+        
+        # Add size information if files exist
+        for cache_type in ["vocabulary_cache", "frequency_cache", "embeddings_cache"]:
+            cache_info = status[cache_type]
+            if cache_info["exists"]:
+                try:
+                    file_path = Path(cache_info["path"])
+                    cache_info["size_bytes"] = file_path.stat().st_size
+                    cache_info["size_mb"] = round(cache_info["size_bytes"] / (1024 * 1024), 2)
+                except Exception as e:
+                    cache_info["size_error"] = str(e)
+        
+        return status
+
+    async def find_words_for_crossword(self, topics: List[str], difficulty: str, requested_words: int = 10, custom_sentence: str = None, multi_theme: bool = True) -> List[Dict[str, Any]]:
+        """
+        Crossword-specific word finding method with 50% overgeneration and clue quality filtering.
+        
+        Args:
+            topics: List of topic strings
+            difficulty: "easy", "medium", or "hard"
+            requested_words: Number of words requested by frontend
+            custom_sentence: Optional custom sentence to influence word selection
+            multi_theme: Whether to use multi-theme processing (True) or single-theme blending (False)
+            
+        Returns:
+            List of word dictionaries: [{"word": str, "clue": str, "similarity": float, "source": "thematic", "tier": str}]
+        """
+        if not self.is_initialized:
+            await self.initialize_async()
+        
+        sentence_info = f", custom sentence: '{custom_sentence}'" if custom_sentence else ""
+        theme_mode = "multi-theme" if multi_theme else "single-theme"
+        
+        # Calculate generation target (3x more for quality filtering - need large pool for clue generation)
+        generation_target = int(requested_words * 3)
+        logger.info(f"🎯 Finding words for crossword - topics: {topics}, difficulty: {difficulty}{sentence_info}, mode: {theme_mode}")
+        logger.info(f"📊 Generating {generation_target} candidates to select best {requested_words} words after clue filtering")
+        
+        # Map difficulty to tier preferences
+        difficulty_tier_map = {
+            "easy": ["tier_2_extremely_common", "tier_3_very_common", "tier_4_highly_common"],
+            "medium": ["tier_4_highly_common", "tier_5_common", "tier_6_moderately_common", "tier_7_somewhat_uncommon"],
+            "hard": ["tier_7_somewhat_uncommon", "tier_8_uncommon", "tier_9_rare"]
+        }
+        
+        # Map difficulty to similarity thresholds
+        difficulty_similarity_map = {
+            "easy": 0.4,
+            "medium": 0.3,
+            "hard": 0.25
+        }
+        
+        preferred_tiers = difficulty_tier_map.get(difficulty, difficulty_tier_map["medium"])
+        min_similarity = difficulty_similarity_map.get(difficulty, 0.3)
+        
+        # Build input list for thematic word generation
+        input_list = topics.copy()  # Start with topics: ["Art"]
+        
+        # Add custom sentence as separate input if provided
+        if custom_sentence:
+            input_list.append(custom_sentence)  # Now: ["Art", "i will always love you"]
+        
+        # Determine if multi-theme processing is needed
+        is_multi_theme = len(input_list) > 1
+        
+        # Set topic_input for generate_thematic_words
+        topic_input = input_list if is_multi_theme else input_list[0]
+        
+        # Get thematic words (get extra for filtering)
+        raw_results = self.generate_thematic_words(
+            topic_input,
+            num_words=150,  # Get extra for difficulty filtering
+            min_similarity=min_similarity,
+            multi_theme=multi_theme
+        )
+        
+        # Log generated thematic words sorted by tiers
+        if raw_results:
+            # Group results by tier for sorted display
+            tier_groups = {}
+            for word, similarity, tier in raw_results:
+                if tier not in tier_groups:
+                    tier_groups[tier] = []
+                tier_groups[tier].append((word, similarity))
+            
+            # Sort tiers from most common to least common
+            tier_order = [
+                "tier_1_ultra_common",
+                "tier_2_extremely_common", 
+                "tier_3_very_common",
+                "tier_4_highly_common",
+                "tier_5_common",
+                "tier_6_moderately_common",
+                "tier_7_somewhat_uncommon",
+                "tier_8_uncommon",
+                "tier_9_rare",
+                "tier_10_very_rare"
+            ]
+            
+            # Build single log message with all tier information
+            log_lines = [f"📊 Generated {len(raw_results)} thematic words, grouped by tiers:"]
+            
+            for tier in tier_order:
+                if tier in tier_groups:
+                    tier_desc = self.tier_descriptions.get(tier, tier)
+                    log_lines.append(f"  📊 {tier_desc}:")
+                    # Sort words within tier alphabetically
+                    tier_words = sorted(tier_groups[tier], key=lambda x: x[0])
+                    for word, similarity in tier_words:
+                        log_lines.append(f"    {word:<15} (similarity: {similarity:.3f})")
+            
+            # uncomment this log line if want to print all words returned
+            logger.info("\n".join(log_lines))
+        else:
+            logger.info("📊 No thematic words generated")
+        
+        # Weighted random tier selection for crossword backend
+        # Step 1: Group raw_results by tier and filter by difficulty/length
+        tier_groups_filtered = {}
+        for word, similarity, tier in raw_results:
+            # Only consider words from preferred tiers for this difficulty
+            if tier in preferred_tiers: # and self._matches_crossword_difficulty(word, difficulty):
+                if tier not in tier_groups_filtered:
+                    tier_groups_filtered[tier] = []
+                tier_groups_filtered[tier].append((word, similarity, tier))
+        
+        # Step 2: Calculate word distribution across preferred tiers
+        tier_word_counts = {tier: len(words) for tier, words in tier_groups_filtered.items()}
+        total_available_words = sum(tier_word_counts.values())
+        
+        logger.info(f"📊 Available words by preferred tier: {tier_word_counts}")
+        
+        if total_available_words == 0:
+            logger.info("⚠️ No words found in preferred tiers, returning empty list")
+            return []
+        
+        # Step 3: Generate clues for ALL words in preferred tiers (no pre-selection)
+        candidate_words = []
+        
+        # Generate clues for all available words in preferred tiers
+        # This gives us a large pool to filter by clue quality
+        logger.info(f"📊 Generating clues for all {total_available_words} words in preferred tiers")
+        for tier, words in tier_groups_filtered.items():
+            for word, similarity, tier in words:
+                word_data = {
+                    "word": word.upper(),
+                    "clue": self._generate_crossword_clue(word, topics),
+                    "similarity": float(similarity),
+                    "source": "thematic",
+                    "tier": tier
+                }
+                candidate_words.append(word_data)
+        
+        # Step 5: Filter candidates by clue quality and select best words
+        logger.info(f"📊 Generated {len(candidate_words)} candidate words, filtering for clue quality")
+        
+        # Separate words by clue quality
+        quality_words = []  # Words with proper WordNet-based clues
+        fallback_words = []  # Words with generic fallback clues
+        
+        fallback_patterns = ["Related to", "Crossword answer"]
+        
+        for word_data in candidate_words:
+            clue = word_data["clue"]
+            has_fallback = any(pattern in clue for pattern in fallback_patterns)
+            
+            if has_fallback:
+                fallback_words.append(word_data)
+            else:
+                quality_words.append(word_data)
+        
+        # Prioritize quality words, use fallback only if needed
+        final_words = []
+        
+        # First, add quality words up to requested count
+        if quality_words:
+            random.shuffle(quality_words)  # Randomize selection
+            final_words.extend(quality_words[:requested_words])
+        
+        # If we don't have enough quality words, add some fallback words
+        if len(final_words) < requested_words and fallback_words:
+            needed = requested_words - len(final_words)
+            random.shuffle(fallback_words)
+            final_words.extend(fallback_words[:needed])
+        
+        # Final shuffle to avoid quality-based ordering
+        random.shuffle(final_words)
+        
+        logger.info(f"✅ Selected {len(final_words)} words ({len([w for w in final_words if not any(p in w['clue'] for p in fallback_patterns)])} quality, {len([w for w in final_words if any(p in w['clue'] for p in fallback_patterns)])} fallback)")
+        logger.info(f"📝 Final words: {[w['word'] for w in final_words]}")
+        return final_words
+
+    def _matches_crossword_difficulty(self, word: str, difficulty: str) -> bool:
+        """Check if word matches crossword difficulty criteria."""
+        difficulty_criteria = {
+            "easy": {"min_len": 3, "max_len": 8},
+            "medium": {"min_len": 4, "max_len": 10},
+            "hard": {"min_len": 5, "max_len": 12}
+        }
+        
+        criteria = difficulty_criteria.get(difficulty, difficulty_criteria["medium"])
+        return criteria["min_len"] <= len(word) <= criteria["max_len"]
+
+    def _generate_crossword_clue(self, word: str, topics: List[str]) -> str:
+        """Generate a crossword clue for the word using WordNet."""
+        # Initialize WordNet clue generator if not already done
+        if not hasattr(self, '_wordnet_generator') or self._wordnet_generator is None:
+            try:
+                from .wordnet_clue_generator import WordNetClueGenerator
+                self._wordnet_generator = WordNetClueGenerator(
+                    cache_dir=str(self.cache_dir)
+                )
+                self._wordnet_generator.initialize()
+                logger.info("✅ WordNet clue generator initialized on-demand")
+            except Exception as e:
+                logger.warning(f"⚠️ Failed to initialize WordNet clue generator: {e}")
+                self._wordnet_generator = None
+        
+        # Use WordNet generator if available
+        if self._wordnet_generator:
+            try:
+                primary_topic = topics[0] if topics else "general"
+                clue = self._wordnet_generator.generate_clue(word, primary_topic)
+                if clue and len(clue.strip()) > 0:
+                    return clue
+            except Exception as e:
+                logger.warning(f"⚠️ WordNet clue generation failed for '{word}': {e}")
+        
+        # Fallback to simple templates if WordNet fails
+        word_lower = word.lower()
+        primary_topic = topics[0] if topics else "general"
+        topic_lower = primary_topic.lower()
+        
+        # Topic-specific clue templates as fallback
+        if any(keyword in topic_lower for keyword in ["animal", "pet", "wildlife"]):
+            return f"{word_lower} (animal)"
+        elif any(keyword in topic_lower for keyword in ["tech", "computer", "software", "digital"]):
+            return f"{word_lower} (technology)"
+        elif any(keyword in topic_lower for keyword in ["science", "biology", "chemistry", "physics"]):
+            return f"{word_lower} (science)"
+        elif any(keyword in topic_lower for keyword in ["geo", "place", "city", "country", "location"]):
+            return f"{word_lower} (geography)"
+        elif any(keyword in topic_lower for keyword in ["food", "cooking", "cuisine", "recipe"]):
+            return f"{word_lower} (food)"
+        elif any(keyword in topic_lower for keyword in ["music", "song", "instrument", "audio"]):
+            return f"{word_lower} (music)"
+        elif any(keyword in topic_lower for keyword in ["sport", "game", "athletic", "exercise"]):
+            return f"{word_lower} (sports)"
+        else:
+            return f"{word_lower} (related to {topic_lower})"
+
+
+# Backwards compatibility aliases
+ThematicWordGenerator = ThematicWordService  # For existing code
+UnifiedThematicWordGenerator = ThematicWordService  # For existing code
+
+# Backend service - no interactive demo needed

crossword-app/backend-py/src/services/unified_word_service.py

@@ -0,0 +1,250 @@
+"""
+Integration adapter for Unified Thematic Word Generator
+
+This service provides a bridge between the new unified word generator
+and the existing crossword backend, enabling the backend to use the
+comprehensive WordFreq vocabulary instead of the limited model vocabulary.
+"""
+
+import os
+import sys
+import logging
+from typing import List, Dict, Any, Optional
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+class UnifiedWordService:
+    """
+    Service adapter for integrating UnifiedThematicWordGenerator with the crossword backend.
+    
+    Provides the same interface as VectorSearchService but uses the comprehensive
+    WordFreq vocabulary instead of model-limited vocabulary.
+    """
+    
+    def __init__(self, vocab_size_limit: Optional[int] = None):
+        """Initialize the unified word service.
+        
+        Args:
+            vocab_size_limit: Maximum vocabulary size (None for default 100K)
+        """
+        self.generator = None
+        self.vocab_size_limit = vocab_size_limit or int(os.getenv("MAX_VOCABULARY_SIZE", "100000"))
+        self.is_initialized = False
+        
+        # Import the generator from hack directory
+        self._import_generator()
+    
+    def _import_generator(self):
+        """Import the UnifiedThematicWordGenerator from hack directory."""
+        try:
+            # Add hack directory to path
+            hack_dir = Path(__file__).parent.parent.parent.parent.parent / "hack"
+            if hack_dir.exists():
+                sys.path.insert(0, str(hack_dir))
+                logger.info(f"📁 Added hack directory to path: {hack_dir}")
+            
+            # Import the generator
+            from thematic_word_generator import UnifiedThematicWordGenerator
+            
+            # Initialize with appropriate cache directory
+            cache_dir = os.path.join(os.path.dirname(__file__), '..', '..', 'cache', 'unified_generator')
+            
+            self.generator = UnifiedThematicWordGenerator(
+                cache_dir=cache_dir,
+                vocab_size_limit=self.vocab_size_limit
+            )
+            
+            logger.info(f"✅ Imported UnifiedThematicWordGenerator with vocab limit: {self.vocab_size_limit:,}")
+            
+        except ImportError as e:
+            logger.error(f"❌ Failed to import UnifiedThematicWordGenerator: {e}")
+            logger.error("   Make sure the hack directory contains thematic_word_generator.py")
+            self.generator = None
+        except Exception as e:
+            logger.error(f"❌ Error setting up UnifiedThematicWordGenerator: {e}")
+            self.generator = None
+    
+    async def initialize(self):
+        """Initialize the unified word service."""
+        if not self.generator:
+            logger.error("❌ Cannot initialize: generator not available")
+            return False
+        
+        try:
+            logger.info("🚀 Initializing Unified Word Service...")
+            start_time = time.time()
+            
+            # Initialize the generator (async compatible)
+            await self.generator.initialize_async()
+            
+            self.is_initialized = True
+            init_time = time.time() - start_time
+            
+            logger.info(f"✅ Unified Word Service initialized in {init_time:.2f}s")
+            logger.info(f"📊 Vocabulary size: {self.generator.get_vocabulary_size():,} words")
+            logger.info(f"🎯 Tier distribution: {self.generator.get_tier_distribution()}")
+            
+            return True
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to initialize Unified Word Service: {e}")
+            self.is_initialized = False
+            return False
+    
+    async def find_similar_words(
+        self, 
+        topic: str, 
+        difficulty: str = "medium", 
+        max_words: int = 15
+    ) -> List[Dict[str, Any]]:
+        """
+        Find similar words using the unified generator.
+        
+        Compatible with VectorSearchService interface.
+        
+        Args:
+            topic: Topic to find words for
+            difficulty: Difficulty level (easy/medium/hard)
+            max_words: Maximum number of words to return
+            
+        Returns:
+            List of word dictionaries: [{"word": str, "clue": str}, ...]
+        """
+        if not self.is_initialized or not self.generator:
+            logger.error("❌ Service not initialized or generator not available")
+            return []
+        
+        try:
+            # Use the generator's backend-compatible method
+            results = await self.generator.find_similar_words(topic, difficulty, max_words)
+            
+            logger.info(f"🎯 Generated {len(results)} words for '{topic}' (difficulty: {difficulty})")
+            return results
+            
+        except Exception as e:
+            logger.error(f"❌ Error finding similar words for '{topic}': {e}")
+            return []
+    
+    async def _get_cached_fallback(self, topic: str, difficulty: str, max_words: int) -> List[Dict[str, Any]]:
+        """
+        Fallback method for compatibility with existing backend code.
+        
+        Since our unified generator already has comprehensive vocabulary,
+        this just calls find_similar_words with relaxed criteria.
+        """
+        if not self.is_initialized or not self.generator:
+            return []
+        
+        try:
+            # Try with lower similarity threshold as "fallback"
+            results = self.generator.generate_thematic_words(
+                topic, 
+                num_words=max_words,
+                min_similarity=0.2  # Lower threshold for fallback
+            )
+            
+            # Format for backend compatibility
+            backend_words = []
+            for word, similarity, tier in results:
+                if self.generator._matches_backend_difficulty(word, difficulty):
+                    backend_word = {
+                        "word": word.upper(),
+                        "clue": self.generator._generate_simple_clue(word, topic),
+                        "similarity": similarity,
+                        "tier": tier
+                    }
+                    backend_words.append(backend_word)
+            
+            logger.info(f"📦 Fallback generated {len(backend_words)} words for '{topic}'")
+            return backend_words[:max_words]
+            
+        except Exception as e:
+            logger.error(f"❌ Error in cached fallback for '{topic}': {e}")
+            return []
+    
+    def get_vocabulary_size(self) -> int:
+        """Get the vocabulary size."""
+        if self.generator:
+            return self.generator.get_vocabulary_size()
+        return 0
+    
+    def get_tier_info(self) -> Dict[str, Any]:
+        """Get frequency tier information."""
+        if not self.generator:
+            return {}
+            
+        return {
+            "tier_distribution": self.generator.get_tier_distribution(),
+            "tier_descriptions": getattr(self.generator, 'tier_descriptions', {}),
+            "vocabulary_size": self.generator.get_vocabulary_size()
+        }
+
+
+# Import time for initialization timing
+import time
+
+# Factory function for easy backend integration
+async def create_unified_word_service(vocab_size_limit: Optional[int] = None) -> Optional[UnifiedWordService]:
+    """
+    Factory function to create and initialize a UnifiedWordService.
+    
+    Args:
+        vocab_size_limit: Maximum vocabulary size (None for default)
+        
+    Returns:
+        Initialized UnifiedWordService or None if initialization failed
+    """
+    try:
+        service = UnifiedWordService(vocab_size_limit)
+        
+        if await service.initialize():
+            return service
+        else:
+            logger.error("❌ Failed to initialize UnifiedWordService")
+            return None
+            
+    except Exception as e:
+        logger.error(f"❌ Error creating UnifiedWordService: {e}")
+        return None
+
+
+# Example usage for testing
+async def main():
+    """Test the unified word service."""
+    print("🧪 Testing Unified Word Service")
+    print("=" * 50)
+    
+    # Create and initialize service
+    service = await create_unified_word_service(vocab_size_limit=50000)  # Smaller vocab for testing
+    
+    if not service:
+        print("❌ Failed to create service")
+        return
+    
+    # Test word generation
+    test_topics = ["animal", "science", "technology"]
+    
+    for topic in test_topics:
+        print(f"\n🎯 Testing topic: '{topic}'")
+        print("-" * 30)
+        
+        for difficulty in ["easy", "medium", "hard"]:
+            words = await service.find_similar_words(topic, difficulty, max_words=5)
+            
+            print(f"  {difficulty.capitalize()}: {len(words)} words")
+            for word_data in words:
+                word = word_data['word']
+                tier = word_data.get('tier', 'unknown')
+                print(f"    {word:<12} ({tier})")
+    
+    print(f"\n📊 Service Info:")
+    print(f"   Vocabulary size: {service.get_vocabulary_size():,}")
+    print(f"   Tier info: {service.get_tier_info()}")
+    
+    print("\n✅ Test completed!")
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())

crossword-app/backend-py/src/services/vector_search.py

@@ -3,6 +3,7 @@ Vector similarity search service using sentence-transformers and FAISS.
 This implements true AI word generation via vector space nearest neighbor search.
 """
 
+from math import log
 import os
 import logging
 import asyncio
@@ -21,10 +22,7 @@ from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
-def log_with_timestamp(message):
-    """Helper to log with precise timestamp."""
-    timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
-    logger.info(f"[{timestamp}] {message}")
+# All logging now uses standard logger with filename/line numbers
 
 class VectorSearchService:
     """
@@ -70,29 +68,29 @@ class VectorSearchService:
             start_time = time.time()
             
             # Log environment configuration for debugging
-            log_with_timestamp(f"🔧 Environment Configuration:")
-            log_with_timestamp(f"   📊 Model: {self.model_name}")
-            log_with_timestamp(f"   🎯 Base Similarity Threshold: {self.base_similarity_threshold}")
-            log_with_timestamp(f"   📉 Min Similarity Threshold: {self.min_similarity_threshold}")
-            log_with_timestamp(f"   📈 Max Results: {self.max_results}")
-            log_with_timestamp(f"   🌟 Hierarchical Search: {self.use_hierarchical_search}")
-            log_with_timestamp(f"   🔀 Search Randomness: {os.getenv('SEARCH_RANDOMNESS', '0.02')}")
-            log_with_timestamp(f"   💾 Cache Dir: {os.getenv('WORD_CACHE_DIR', 'auto-detect')}")
+            logger.info(f"🔧 Environment Configuration:")
+            logger.info(f"   📊 Model: {self.model_name}")
+            logger.info(f"   🎯 Base Similarity Threshold: {self.base_similarity_threshold}")
+            logger.info(f"   📉 Min Similarity Threshold: {self.min_similarity_threshold}")
+            logger.info(f"   📈 Max Results: {self.max_results}")
+            logger.info(f"   🌟 Hierarchical Search: {self.use_hierarchical_search}")
+            logger.info(f"   🔀 Search Randomness: {os.getenv('SEARCH_RANDOMNESS', '0.02')}")
+            logger.info(f"   💾 Cache Dir: {os.getenv('WORD_CACHE_DIR', 'auto-detect')}")
             
-            log_with_timestamp(f"🔧 Loading model: {self.model_name}")
+            logger.info(f"🔧 Loading model: {self.model_name}")
             
             # Load sentence transformer model
             model_start = time.time()
             self.model = SentenceTransformer(self.model_name)
             model_time = time.time() - model_start
-            log_with_timestamp(f"✅ Model loaded in {model_time:.2f}s: {self.model_name}")
+            logger.info(f"✅ Model loaded in {model_time:.2f}s: {self.model_name}")
             
             # Try to load from cache first
             if self._load_cached_index():
-                log_with_timestamp("🚀 Using cached FAISS index - startup accelerated!")
+                logger.info("🚀 Using cached FAISS index - startup accelerated!")
             else:
                 # Build from scratch
-                log_with_timestamp("🔨 Building FAISS index from scratch...")
+                logger.info("🔨 Building FAISS index from scratch...")
                 
                 # Get model vocabulary from tokenizer
                 vocab_start = time.time()
@@ -102,36 +100,36 @@ class VectorSearchService:
                 # Filter vocabulary for crossword-suitable words
                 self.vocab = self._filter_vocabulary(vocab_dict)
                 vocab_time = time.time() - vocab_start
-                log_with_timestamp(f"📚 Filtered vocabulary in {vocab_time:.2f}s: {len(self.vocab)} words")
+                logger.info(f"📚 Filtered vocabulary in {vocab_time:.2f}s: {len(self.vocab)} words")
                 
                 # Pre-compute embeddings for all vocabulary words
                 embedding_start = time.time()
-                log_with_timestamp("🔄 Starting embedding generation...")
+                logger.info("🔄 Starting embedding generation...")
                 await self._build_embeddings_index()
                 embedding_time = time.time() - embedding_start
-                log_with_timestamp(f"🔄 Embeddings built in {embedding_time:.2f}s")
+                logger.info(f"🔄 Embeddings built in {embedding_time:.2f}s")
                 
                 # Save to cache for next time
                 self._save_index_to_cache()
             
             # Initialize cache manager
             cache_start = time.time()
-            log_with_timestamp("📦 Initializing word cache manager...")
+            logger.info("📦 Initializing word cache manager...")
             try:
                 from .word_cache import WordCacheManager
                 self.cache_manager = WordCacheManager()
                 await self.cache_manager.initialize()
                 cache_time = time.time() - cache_start
-                log_with_timestamp(f"📦 Cache manager initialized in {cache_time:.2f}s")
+                logger.info(f"📦 Cache manager initialized in {cache_time:.2f}s")
             except Exception as e:
                 cache_time = time.time() - cache_start
-                log_with_timestamp(f"⚠️ Cache manager initialization failed in {cache_time:.2f}s: {e}")
-                log_with_timestamp("📝 Continuing without persistent caching (in-memory only)")
+                logger.info(f"⚠️ Cache manager initialization failed in {cache_time:.2f}s: {e}")
+                logger.info("📝 Continuing without persistent caching (in-memory only)")
                 self.cache_manager = None
             
             self.is_initialized = True
             total_time = time.time() - start_time
-            log_with_timestamp(f"✅ Vector search service fully initialized in {total_time:.2f}s")
+            logger.info(f"✅ Vector search service fully initialized in {total_time:.2f}s")
             
         except Exception as e:
             logger.error(f"❌ Failed to initialize vector search: {e}")
@@ -140,7 +138,7 @@ class VectorSearchService:
     
     def _filter_vocabulary(self, vocab_dict: Dict[str, int]) -> List[str]:
         """Filter vocabulary to keep only crossword-suitable words."""
-        log_with_timestamp(f"📚 Filtering {len(vocab_dict)} vocabulary words...")
+        logger.info(f"📚 Filtering {len(vocab_dict)} vocabulary words...")
         
         # Pre-compile excluded words set for faster lookup
         excluded_words = {
@@ -159,7 +157,7 @@ class VectorSearchService:
             
             # Progress logging for large vocabularies
             if processed % 10000 == 0:
-                log_with_timestamp(f"📊 Vocabulary filtering progress: {processed}/{len(vocab_dict)}")
+                logger.info(f"📊 Vocabulary filtering progress: {processed}/{len(vocab_dict)}")
             
             # Clean word (remove special tokens) - optimized
             if word.startswith('##'):
@@ -191,7 +189,7 @@ class VectorSearchService:
         
         # Remove duplicates efficiently and sort
         unique_filtered = sorted(list(set(filtered)))
-        log_with_timestamp(f"📚 Vocabulary filtered: {len(vocab_dict)} → {len(unique_filtered)} words")
+        logger.info(f"📚 Vocabulary filtered: {len(vocab_dict)} → {len(unique_filtered)} words")
         
         return unique_filtered
     
@@ -225,7 +223,7 @@ class VectorSearchService:
         cpu_count = os.cpu_count() or 1
         # Larger batches for better throughput, smaller for HF Spaces limited memory
         batch_size = min(200 if cpu_count > 2 else 100, len(self.vocab) // 4)
-        log_with_timestamp(f"⚡ Using batch size {batch_size} with {cpu_count} CPUs")
+        logger.info(f"⚡ Using batch size {batch_size} with {cpu_count} CPUs")
         
         embeddings_list = []
         total_batches = (len(self.vocab) + batch_size - 1) // batch_size
@@ -249,24 +247,24 @@ class VectorSearchService:
             # Progress logging - more frequent for slower HF Spaces
             if batch_num % max(1, total_batches // 10) == 0:
                 progress = (batch_num / total_batches) * 100
-                log_with_timestamp(f"📊 Embedding progress: {progress:.1f}% ({i}/{len(self.vocab)} words)")
+                logger.info(f"📊 Embedding progress: {progress:.1f}% ({i}/{len(self.vocab)} words)")
         
         # Combine all embeddings
-        log_with_timestamp("🔗 Combining embeddings...")
+        logger.info("🔗 Combining embeddings...")
         self.word_embeddings = np.vstack(embeddings_list)
         logger.info(f"📈 Generated embeddings shape: {self.word_embeddings.shape}")
         
         # Build FAISS index for fast similarity search
-        log_with_timestamp("🏗️ Building FAISS index...")
+        logger.info("🏗️ Building FAISS index...")
         dimension = self.word_embeddings.shape[1]
         self.faiss_index = faiss.IndexFlatIP(dimension)  # Inner product similarity
         
         # Normalize embeddings for cosine similarity
-        log_with_timestamp("📏 Normalizing embeddings for cosine similarity...")
+        logger.info("📏 Normalizing embeddings for cosine similarity...")
         faiss.normalize_L2(self.word_embeddings)
         
         # Add to FAISS index
-        log_with_timestamp("📥 Adding embeddings to FAISS index...")
+        logger.info("📥 Adding embeddings to FAISS index...")
         self.faiss_index.add(self.word_embeddings)
         
         logger.info(f"🔍 FAISS index built with {self.faiss_index.ntotal} vectors")
@@ -316,7 +314,7 @@ class VectorSearchService:
                     
                     # Track these words to prevent future repetition
                     if similar_words:
-                        self._track_used_words(topic, [word['word'] for word in similar_words])
+                        self._track_used_words(topic, similar_words)
                     
                     # Cache successful results for future use
                     if similar_words:
@@ -338,7 +336,7 @@ class VectorSearchService:
                 
                 # Track these words to prevent future repetition
                 if similar_words:
-                    self._track_used_words(topic, [word['word'] for word in similar_words])
+                    self._track_used_words(topic, similar_words)
             
             # If not enough words found, supplement with cached words (more aggressive)
             if len(similar_words) < max_words * 0.75:  # If less than 75% of target, supplement
@@ -578,7 +576,8 @@ class VectorSearchService:
                          'urban', 'rural', 'geological', 'topographical', 'cartographic']
         }
         
-        for candidate in candidates[:10]:  # Only consider top 10 for performance
+        # for candidate in candidates[:10]:  # Only consider top 10 for performance
+        for candidate in candidates:  # Only consider top 10 for performance
             word = candidate['word'].lower()
             similarity = candidate['similarity']
             
@@ -691,6 +690,8 @@ class VectorSearchService:
                 
             main_topic_candidates.extend(variation_candidates)
             
+        if len(main_topic_candidates) <= 10:
+            logger.info(f"🔍 Main topic search found candidates: {main_topic_candidates}")
         logger.info(f"🔍 Main topic search found {len(main_topic_candidates)} candidates")
         
         # Phase 2: Identify subcategories from best candidates
@@ -919,7 +920,18 @@ class VectorSearchService:
         max_words: int
     ) -> List[Dict[str, Any]]:
         """
-        Ensure diverse representation from different search sources.
+        Balance word selection across different search sources for optimal variety.
+        
+        Allocates selection quotas to ensure representation from main topic searches
+        and subcategory searches, preventing over-concentration from any single source
+        while maintaining quality standards.
+        
+        Args:
+            candidates: Word candidates with search source metadata
+            max_words: Target number of words to select
+            
+        Returns:
+            Balanced selection ensuring source diversity
         """
         if len(candidates) <= max_words:
             return candidates
@@ -1047,38 +1059,38 @@ class VectorSearchService:
         """Load FAISS index from cache if available."""
         try:
             if not self._cache_exists():
-                log_with_timestamp("📁 No cached index found - will build new index")
+                logger.info("📁 No cached index found - will build new index")
                 return False
             
-            log_with_timestamp("📁 Loading cached FAISS index...")
+            logger.info("📁 Loading cached FAISS index...")
             cache_start = time.time()
             
             # Load vocabulary
             with open(self.vocab_cache_path, 'rb') as f:
                 self.vocab = pickle.load(f)
-            log_with_timestamp(f"📚 Loaded {len(self.vocab)} vocabulary words from cache")
+            logger.info(f"📚 Loaded {len(self.vocab)} vocabulary words from cache")
             
             # Load embeddings
             self.word_embeddings = np.load(self.embeddings_cache_path)
-            log_with_timestamp(f"📈 Loaded embeddings shape: {self.word_embeddings.shape}")
+            logger.info(f"📈 Loaded embeddings shape: {self.word_embeddings.shape}")
             
             # Load FAISS index
             self.faiss_index = faiss.read_index(self.faiss_cache_path)
-            log_with_timestamp(f"🔍 Loaded FAISS index with {self.faiss_index.ntotal} vectors")
+            logger.info(f"🔍 Loaded FAISS index with {self.faiss_index.ntotal} vectors")
             
             cache_time = time.time() - cache_start
-            log_with_timestamp(f"✅ Successfully loaded cached index in {cache_time:.2f}s")
+            logger.info(f"✅ Successfully loaded cached index in {cache_time:.2f}s")
             return True
             
         except Exception as e:
-            log_with_timestamp(f"❌ Failed to load cached index: {e}")
-            log_with_timestamp("🔄 Will rebuild index from scratch")
+            logger.info(f"❌ Failed to load cached index: {e}")
+            logger.info("🔄 Will rebuild index from scratch")
             return False
     
     def _save_index_to_cache(self):
         """Save the built FAISS index to cache for future use."""
         try:
-            log_with_timestamp("💾 Saving FAISS index to cache...")
+            logger.info("💾 Saving FAISS index to cache...")
             save_start = time.time()
             
             # Save vocabulary
@@ -1092,12 +1104,12 @@ class VectorSearchService:
             faiss.write_index(self.faiss_index, self.faiss_cache_path)
             
             save_time = time.time() - save_start
-            log_with_timestamp(f"✅ Index cached successfully in {save_time:.2f}s")
-            log_with_timestamp(f"📁 Cache location: {self.index_cache_dir}")
+            logger.info(f"✅ Index cached successfully in {save_time:.2f}s")
+            logger.info(f"📁 Cache location: {self.index_cache_dir}")
             
         except Exception as e:
-            log_with_timestamp(f"⚠️ Failed to cache index: {e}")
-            log_with_timestamp("📝 Continuing without caching (performance will be slower next startup)")
+            logger.info(f"⚠️ Failed to cache index: {e}")
+            logger.info("📝 Continuing without caching (performance will be slower next startup)")
     
     def _is_topic_relevant(self, word: str, topic: str) -> bool:
         """
@@ -1182,16 +1194,16 @@ class VectorSearchService:
             # Filter by difficulty and quality
             if self._matches_difficulty(word, difficulty):
                 difficulty_passed += 1
-                if self._is_interesting_word(word, topic) and self._is_topic_relevant(word, topic):
-                    interesting_passed += 1
-                    candidates.append({
-                        "word": word,
-                        "clue": self._generate_clue(word, topic),
-                        "similarity": float(score),
-                        "source": "vector_search"
-                    })
-                else:
-                    rejected_words.append(f"{word}({score:.3f})")
+                # if self._is_interesting_word(word, topic) and self._is_topic_relevant(word, topic):
+                interesting_passed += 1
+                candidates.append({
+                    "word": word,
+                    "clue": self._generate_clue(word, topic),
+                    "similarity": float(score),
+                    "source": "vector_search"
+                })
+                # else:
+                #     rejected_words.append(f"{word}({score:.3f})")
             else:
                 rejected_words.append(f"{word}({score:.3f})")
         
@@ -1341,58 +1353,49 @@ class VectorSearchService:
             "animals": [
                 {"word": "DOG", "clue": "Man's best friend"},
                 {"word": "CAT", "clue": "Feline pet"},
-                {"word": "ELEPHANT", "clue": "Large mammal with trunk"},
-                {"word": "TIGER", "clue": "Striped big cat"},
-                {"word": "BIRD", "clue": "Flying creature"},
                 {"word": "FISH", "clue": "Aquatic animal"},
-                {"word": "HORSE", "clue": "Riding animal"},
-                {"word": "BEAR", "clue": "Large mammal"},
-                {"word": "WHALE", "clue": "Marine mammal"},
-                {"word": "LION", "clue": "King of jungle"},
-                {"word": "RABBIT", "clue": "Hopping mammal"},
-                {"word": "SNAKE", "clue": "Slithering reptile"}
             ],
             "science": [
-                {"word": "ATOM", "clue": "Basic unit of matter"},
-                {"word": "CELL", "clue": "Basic unit of life"},
-                {"word": "DNA", "clue": "Genetic material"},
-                {"word": "ENERGY", "clue": "Capacity to do work"},
-                {"word": "FORCE", "clue": "Push or pull"},
-                {"word": "GRAVITY", "clue": "Force of attraction"},
-                {"word": "LIGHT", "clue": "Electromagnetic radiation"},
-                {"word": "MATTER", "clue": "Physical substance"},
-                {"word": "MOTION", "clue": "Change in position"},
-                {"word": "OXYGEN", "clue": "Essential gas"},
-                {"word": "PHYSICS", "clue": "Study of matter and energy"},
-                {"word": "THEORY", "clue": "Scientific explanation"}
+                # {"word": "ATOM", "clue": "Basic unit of matter"},
+                # {"word": "CELL", "clue": "Basic unit of life"},
+                # {"word": "DNA", "clue": "Genetic material"},
+                # {"word": "ENERGY", "clue": "Capacity to do work"},
+                # {"word": "FORCE", "clue": "Push or pull"},
+                # {"word": "GRAVITY", "clue": "Force of attraction"},
+                # {"word": "LIGHT", "clue": "Electromagnetic radiation"},
+                # {"word": "MATTER", "clue": "Physical substance"},
+                # {"word": "MOTION", "clue": "Change in position"},
+                # {"word": "OXYGEN", "clue": "Essential gas"},
+                # {"word": "PHYSICS", "clue": "Study of matter and energy"},
+                # {"word": "THEORY", "clue": "Scientific explanation"}
             ],
             "technology": [
-                {"word": "COMPUTER", "clue": "Electronic device"},
-                {"word": "INTERNET", "clue": "Global network"},
-                {"word": "SOFTWARE", "clue": "Computer programs"},
-                {"word": "ROBOT", "clue": "Automated machine"},
-                {"word": "DATA", "clue": "Information"},
-                {"word": "CODE", "clue": "Programming instructions"},
-                {"word": "DIGITAL", "clue": "Electronic format"},
-                {"word": "NETWORK", "clue": "Connected systems"},
-                {"word": "SYSTEM", "clue": "Organized whole"},
-                {"word": "DEVICE", "clue": "Technical apparatus"},
-                {"word": "MOBILE", "clue": "Portable technology"},
-                {"word": "SCREEN", "clue": "Display surface"}
+                # {"word": "COMPUTER", "clue": "Electronic device"},
+                # {"word": "INTERNET", "clue": "Global network"},
+                # {"word": "SOFTWARE", "clue": "Computer programs"},
+                # {"word": "ROBOT", "clue": "Automated machine"},
+                # {"word": "DATA", "clue": "Information"},
+                # {"word": "CODE", "clue": "Programming instructions"},
+                # {"word": "DIGITAL", "clue": "Electronic format"},
+                # {"word": "NETWORK", "clue": "Connected systems"},
+                # {"word": "SYSTEM", "clue": "Organized whole"},
+                # {"word": "DEVICE", "clue": "Technical apparatus"},
+                # {"word": "MOBILE", "clue": "Portable technology"},
+                # {"word": "SCREEN", "clue": "Display surface"}
             ],
             "geography": [
-                {"word": "MOUNTAIN", "clue": "High landform"},
-                {"word": "RIVER", "clue": "Flowing water"},
-                {"word": "OCEAN", "clue": "Large body of water"},
-                {"word": "DESERT", "clue": "Arid region"},
-                {"word": "FOREST", "clue": "Dense trees"},
-                {"word": "ISLAND", "clue": "Land surrounded by water"},
-                {"word": "VALLEY", "clue": "Low area between hills"},
-                {"word": "LAKE", "clue": "Inland water body"},
-                {"word": "COAST", "clue": "Land by the sea"},
-                {"word": "PLAIN", "clue": "Flat land"},
-                {"word": "HILL", "clue": "Small elevation"},
-                {"word": "CLIFF", "clue": "Steep rock face"}
+                # {"word": "MOUNTAIN", "clue": "High landform"},
+                # {"word": "RIVER", "clue": "Flowing water"},
+                # {"word": "OCEAN", "clue": "Large body of water"},
+                # {"word": "DESERT", "clue": "Arid region"},
+                # {"word": "FOREST", "clue": "Dense trees"},
+                # {"word": "ISLAND", "clue": "Land surrounded by water"},
+                # {"word": "VALLEY", "clue": "Low area between hills"},
+                # {"word": "LAKE", "clue": "Inland water body"},
+                # {"word": "COAST", "clue": "Land by the sea"},
+                # {"word": "PLAIN", "clue": "Flat land"},
+                # {"word": "HILL", "clue": "Small elevation"},
+                # {"word": "CLIFF", "clue": "Steep rock face"}
             ]
         }
         
@@ -1441,4 +1444,4 @@ class VectorSearchService:
             del self.faiss_index
         if self.cache_manager:
             await self.cache_manager.cleanup_expired_caches()
-        self.is_initialized = False
+        self.is_initialized = False

crossword-app/backend-py/src/services/wordnet_clue_generator.py

@@ -0,0 +1,640 @@
+#!/usr/bin/env python3
+"""
+WordNet-Based Clue Generator for Crossword Puzzles
+
+Uses NLTK WordNet to generate crossword clues by analyzing word definitions,
+synonyms, hypernyms, and semantic relationships. Integrated with the thematic
+word generator for complete crossword creation without API dependencies.
+
+Features:
+- WordNet-based clue generation using definitions and relationships
+- Integration with UnifiedThematicWordGenerator for word discovery
+- Interactive mode with topic-based generation
+- Multiple clue styles (definition, synonym, category, descriptive)
+- Difficulty-based clue complexity
+- Caching for improved performance
+"""
+
+import os
+import sys
+import re
+import time
+import logging
+from typing import List, Dict, Optional, Tuple, Set, Any
+from pathlib import Path
+from dataclasses import dataclass
+from collections import defaultdict
+import random
+
+# NLTK imports
+try:
+    import nltk
+    from nltk.corpus import wordnet as wn
+    from nltk.stem import WordNetLemmatizer
+    NLTK_AVAILABLE = True
+except ImportError:
+    print("❌ NLTK not available. Install with: pip install nltk")
+    NLTK_AVAILABLE = False
+
+# Add hack directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+try:
+    from .thematic_word_service import ThematicWordService as UnifiedThematicWordGenerator
+    THEMATIC_AVAILABLE = True
+except ImportError as e:
+    print(f"❌ Thematic generator import error: {e}")
+    THEMATIC_AVAILABLE = False
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WordNetClueEntry:
+    """Complete crossword entry with WordNet-generated clue and metadata."""
+    word: str
+    clue: str
+    topic: str
+    similarity_score: float
+    frequency_tier: str
+    tier_description: str
+    clue_type: str  # definition, synonym, hypernym, etc.
+    synset_info: Optional[str] = None
+    definition_source: Optional[str] = None
+
+
+def ensure_nltk_data(nltk_data_dir: Optional[str] = None):
+    """Ensure required NLTK data is downloaded to specified directory.
+    
+    Args:
+        nltk_data_dir: Custom directory for NLTK data. If None, uses default.
+    """
+    if not NLTK_AVAILABLE:
+        return False
+    
+    # Set up custom NLTK data directory
+    if nltk_data_dir:
+        nltk_data_path = Path(nltk_data_dir)
+        nltk_data_path.mkdir(parents=True, exist_ok=True)
+        
+        # Add custom path to NLTK search path (at the beginning for priority)
+        if str(nltk_data_path) not in nltk.data.path:
+            nltk.data.path.insert(0, str(nltk_data_path))
+            logger.info(f"📂 Added NLTK data path: {nltk_data_path}")
+    
+    # Map corpus names to their actual directory paths
+    corpus_paths = {
+        'wordnet': 'corpora/wordnet',
+        'omw-1.4': 'corpora/omw-1.4', 
+        'punkt': 'tokenizers/punkt',
+        'averaged_perceptron_tagger': 'taggers/averaged_perceptron_tagger'
+    }
+    
+    required_corpora = ['wordnet', 'punkt', 'averaged_perceptron_tagger', 'omw-1.4']
+    
+    for corpus in required_corpora:
+        corpus_path = corpus_paths[corpus]
+        
+        try:
+            # Try to find corpus in current search paths
+            found_corpus = nltk.data.find(corpus_path)
+            logger.info(f"✅ Found {corpus} at: {found_corpus}")
+        except LookupError:
+            # Check if it exists in our custom directory
+            if nltk_data_dir:
+                local_corpus_path = Path(nltk_data_dir) / corpus_path
+                if local_corpus_path.exists():
+                    logger.info(f"✅ Found {corpus} locally at: {local_corpus_path}")
+                    continue
+            
+            # Only download if not found anywhere
+            logger.warning(f"❌ {corpus} not found, attempting download...")
+            try:
+                if nltk_data_dir:
+                    # Download to custom directory
+                    logger.info(f"📥 Downloading {corpus} to: {nltk_data_dir}")
+                    nltk.download(corpus, download_dir=nltk_data_dir, quiet=False)
+                    logger.info(f"✅ Downloaded {corpus} to: {nltk_data_dir}")
+                else:
+                    # Download to default directory
+                    logger.info(f"📥 Downloading {corpus} to default location")
+                    nltk.download(corpus, quiet=False)
+                    logger.info(f"✅ Downloaded {corpus} to default location")
+            except Exception as e:
+                logger.warning(f"⚠️ Failed to download {corpus}: {e}")
+                return False
+    
+    return True
+
+
+class WordNetClueGenerator:
+    """
+    WordNet-based clue generator that creates crossword clues using semantic
+    relationships and definitions from the WordNet lexical database.
+    """
+    
+    def __init__(self, cache_dir: Optional[str] = None):
+        """Initialize WordNet clue generator.
+        
+        Args:
+            cache_dir: Directory for caching (used for both model cache and NLTK data)
+        """
+        self.cache_dir = cache_dir or str(Path(__file__).parent / 'model_cache')
+        self.nltk_data_dir = str(Path(self.cache_dir) / 'nltk_data')
+        self.lemmatizer = None
+        self.clue_cache = {}
+        self.is_initialized = False
+        
+        # Simple clue generation using definition concatenation
+        
+        # Words to avoid in clues (common words that don't make good clues)
+        self.avoid_words = {
+            'thing', 'stuff', 'item', 'object', 'entity', 'something', 'anything',
+            'person', 'people', 'someone', 'anyone', 'somebody', 'anybody',
+            'place', 'location', 'somewhere', 'anywhere', 'area', 'spot',
+            'time', 'moment', 'period', 'while', 'when', 'then',
+            'way', 'manner', 'method', 'means', 'how', 'what', 'which'
+        }
+    
+    def initialize(self):
+        """Initialize the WordNet clue generator."""
+        if self.is_initialized:
+            return True
+        
+        if not NLTK_AVAILABLE:
+            logger.error("❌ NLTK not available - cannot initialize WordNet generator")
+            return False
+        
+        logger.info("🚀 Initializing WordNet Clue Generator...")
+        logger.info(f"📂 Using cache directory: {self.cache_dir}")
+        logger.info(f"📂 Using NLTK data directory: {self.nltk_data_dir}")
+        start_time = time.time()
+        
+        # Ensure NLTK data is available in cache directory
+        if not ensure_nltk_data(self.nltk_data_dir):
+            logger.error("❌ Failed to download required NLTK data")
+            return False
+        
+        # Initialize lemmatizer
+        try:
+            self.lemmatizer = WordNetLemmatizer()
+            logger.info("✅ WordNet lemmatizer initialized")
+        except Exception as e:
+            logger.error(f"❌ Failed to initialize lemmatizer: {e}")
+            return False
+        
+        self.is_initialized = True
+        init_time = time.time() - start_time
+        logger.info(f"✅ WordNet clue generator ready in {init_time:.2f}s")
+        
+        return True
+    
+    def generate_clue(self, word: str, topic: str = "", clue_style: str = "auto", 
+                     difficulty: str = "medium") -> str:
+        """Generate a crossword clue using WordNet definitions.
+        
+        Args:
+            word: Target word for clue generation
+            topic: Topic context (for fallback only)
+            clue_style: Ignored - kept for compatibility
+            difficulty: Ignored - kept for compatibility
+            
+        Returns:
+            Generated crossword clue
+        """
+        if not self.is_initialized:
+            if not self.initialize():
+                return f"Related to {topic}" if topic else "Crossword answer"
+        
+        word_clean = word.lower().strip()
+        
+        # Get synsets
+        synsets = wn.synsets(word_clean)
+        if not synsets:
+            return f"Related to {topic}" if topic else "Crossword answer"
+        
+        # Limit to max 3 synsets, randomly select if more than 3
+        if len(synsets) > 3:
+            import random
+            synsets = random.sample(synsets, 3)
+        
+        # Get all definitions and filter out those containing the target word
+        definitions = []
+        word_variants = {
+            word_clean,
+            word_clean + 's',
+            word_clean + 'ing',
+            word_clean + 'ed',
+            word_clean + 'er',
+            word_clean + 'ly'
+        }
+        
+        for syn in synsets:
+            definition = syn.definition()
+            definition_lower = definition.lower()
+            
+            # Check if any variant of the target word appears in the definition
+            contains_target = False
+            for variant in word_variants:
+                if f" {variant} " in f" {definition_lower} " or definition_lower.startswith(variant + " "):
+                    contains_target = True
+                    break
+            
+            # Only include definitions that don't contain the target word
+            if not contains_target:
+                definitions.append(definition)
+        
+        # If no clean definitions found, return fallback
+        if not definitions:
+            return f"Related to {topic}" if topic else "Crossword answer"
+        
+        # Concatenate clean definitions
+        clue = "; ".join(definitions)
+        
+        return clue
+    
+    def _generate_fallback_clue(self, word: str, topic: str) -> str:
+        """Generate fallback clue when WordNet fails."""
+        if topic:
+            return f"Related to {topic}"
+        return "Crossword answer"
+    
+    
+    def get_clue_info(self, word: str) -> Dict[str, Any]:
+        """Get detailed information about WordNet data for a word."""
+        if not self.is_initialized:
+            return {"error": "Generator not initialized"}
+        
+        word_clean = word.lower().strip()
+        synsets = self._get_synsets(word_clean)
+        
+        info = {
+            "word": word,
+            "synsets_count": len(synsets),
+            "synsets": []
+        }
+        
+        for synset in synsets[:3]:  # Top 3 synsets
+            synset_info = {
+                "name": synset.name(),
+                "pos": synset.pos(),
+                "definition": synset.definition(),
+                "examples": synset.examples()[:2],
+                "hypernyms": [h.name() for h in synset.hypernyms()[:2]],
+                "synonyms": [l.name().replace('_', ' ') for l in synset.lemmas()[:3]]
+            }
+            info["synsets"].append(synset_info)
+        
+        return info
+
+
+class IntegratedWordNetCrosswordGenerator:
+    """
+    Complete crossword generation system using WordNet clues and thematic word discovery.
+    """
+    
+    def __init__(self, vocab_size_limit: Optional[int] = None, cache_dir: Optional[str] = None):
+        """Initialize the integrated WordNet crossword generator.
+        
+        Args:
+            vocab_size_limit: Maximum vocabulary size for thematic generator
+            cache_dir: Cache directory for models and data
+        """
+        self.cache_dir = cache_dir or str(Path(__file__).parent / 'model_cache')
+        self.vocab_size_limit = vocab_size_limit or 50000
+        
+        # Initialize components
+        self.thematic_generator = None
+        self.clue_generator = None
+        self.is_initialized = False
+        
+        # Stats
+        self.stats = {
+            'words_discovered': 0,
+            'clues_generated': 0,
+            'cache_hits': 0,
+            'total_time': 0.0
+        }
+    
+    def initialize(self):
+        """Initialize both generators."""
+        if self.is_initialized:
+            return True
+        
+        start_time = time.time()
+        logger.info("🚀 Initializing Integrated WordNet Crossword Generator...")
+        
+        success = True
+        
+        # Initialize WordNet clue generator with consistent cache directory
+        logger.info("🔄 Initializing WordNet clue generator...")
+        self.clue_generator = WordNetClueGenerator(self.cache_dir)
+        if not self.clue_generator.initialize():
+            logger.error("❌ Failed to initialize WordNet clue generator")
+            success = False
+        else:
+            logger.info("✅ WordNet clue generator ready")
+            logger.info(f"📂 NLTK data stored in: {self.clue_generator.nltk_data_dir}")
+        
+        # Initialize thematic word generator
+        if THEMATIC_AVAILABLE:
+            logger.info("🔄 Initializing thematic word generator...")
+            try:
+                self.thematic_generator = UnifiedThematicWordGenerator(
+                    cache_dir=self.cache_dir,
+                    vocab_size_limit=self.vocab_size_limit
+                )
+                self.thematic_generator.initialize()
+                logger.info(f"✅ Thematic generator ready ({self.thematic_generator.get_vocabulary_size():,} words)")
+            except Exception as e:
+                logger.error(f"❌ Failed to initialize thematic generator: {e}")
+                success = False
+        else:
+            logger.warning("⚠️ Thematic generator not available - limited word discovery")
+        
+        self.is_initialized = success
+        init_time = time.time() - start_time
+        logger.info(f"{'✅' if success else '❌'} Initialization {'completed' if success else 'failed'} in {init_time:.2f}s")
+        
+        return success
+    
+    def generate_crossword_entries(self, topic: str, num_words: int = 15, 
+                                 difficulty: str = "medium", clue_style: str = "auto") -> List[WordNetClueEntry]:
+        """Generate complete crossword entries for a topic.
+        
+        Args:
+            topic: Topic for word generation
+            num_words: Number of entries to generate
+            difficulty: Difficulty level ('easy', 'medium', 'hard')
+            clue_style: Clue generation style
+            
+        Returns:
+            List of WordNetClueEntry objects
+        """
+        if not self.is_initialized:
+            if not self.initialize():
+                return []
+        
+        start_time = time.time()
+        logger.info(f"🎯 Generating {num_words} crossword entries for '{topic}' (difficulty: {difficulty})")
+        
+        # Generate thematic words
+        if self.thematic_generator:
+            try:
+                # Get more words than needed for better selection
+                word_results = self.thematic_generator.generate_thematic_words(
+                    inputs=topic,
+                    num_words=num_words * 2,
+                    min_similarity=0.2
+                )
+                self.stats['words_discovered'] += len(word_results)
+            except Exception as e:
+                logger.error(f"❌ Word generation failed: {e}")
+                word_results = []
+        else:
+            # Fallback: use some common words related to topic
+            word_results = [(topic.upper(), 0.9, "tier_5_common")]
+        
+        if not word_results:
+            logger.warning(f"⚠️ No words found for topic '{topic}'")
+            return []
+        
+        # Generate clues for words
+        entries = []
+        for word, similarity, tier in word_results[:num_words]:
+            try:
+                clue = self.clue_generator.generate_clue(
+                    word=word,
+                    topic=topic,
+                    clue_style=clue_style,
+                    difficulty=difficulty
+                )
+                
+                if clue:
+                    tier_desc = self._get_tier_description(tier)
+                    entry = WordNetClueEntry(
+                        word=word.upper(),
+                        clue=clue,
+                        topic=topic,
+                        similarity_score=similarity,
+                        frequency_tier=tier,
+                        tier_description=tier_desc,
+                        clue_type=clue_style
+                    )
+                    entries.append(entry)
+                    self.stats['clues_generated'] += 1
+                
+            except Exception as e:
+                logger.error(f"❌ Failed to generate clue for '{word}': {e}")
+        
+        # Sort by similarity and limit results
+        entries.sort(key=lambda x: x.similarity_score, reverse=True)
+        final_entries = entries[:num_words]
+        
+        total_time = time.time() - start_time
+        self.stats['total_time'] += total_time
+        
+        logger.info(f"✅ Generated {len(final_entries)} entries in {total_time:.2f}s")
+        return final_entries
+    
+    def _get_tier_description(self, tier: str) -> str:
+        """Get tier description from thematic generator or provide default."""
+        if self.thematic_generator and hasattr(self.thematic_generator, 'tier_descriptions'):
+            return self.thematic_generator.tier_descriptions.get(tier, tier)
+        return tier.replace('_', ' ').title()
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get generation statistics."""
+        return {
+            **self.stats,
+            'thematic_available': self.thematic_generator is not None,
+            'wordnet_available': self.clue_generator is not None and self.clue_generator.is_initialized,
+            'vocab_size': self.thematic_generator.get_vocabulary_size() if self.thematic_generator else 0
+        }
+
+
+def main():
+    """Interactive WordNet crossword generator."""
+    if not NLTK_AVAILABLE:
+        print("❌ NLTK not available. Please install with: pip install nltk")
+        return
+    
+    print("🚀 WordNet Crossword Generator")
+    print("=" * 60)
+    print("Using NLTK WordNet for clue generation + thematic word discovery")
+    
+    # Initialize generator
+    cache_dir = str(Path(__file__).parent / 'model_cache')
+    generator = IntegratedWordNetCrosswordGenerator(
+        vocab_size_limit=50000,
+        cache_dir=cache_dir
+    )
+    
+    print("\n🔄 Initializing system...")
+    if not generator.initialize():
+        print("❌ Failed to initialize system")
+        return
+    
+    stats = generator.get_stats()
+    print(f"\n📊 System Status:")
+    print(f"   WordNet clues: {'✅' if stats['wordnet_available'] else '❌'}")
+    print(f"   Thematic words: {'✅' if stats['thematic_available'] else '❌'}")
+    if stats['vocab_size'] > 0:
+        print(f"   Vocabulary: {stats['vocab_size']:,} words")
+    
+    print(f"\n🎮 INTERACTIVE MODE")
+    print("=" * 60)
+    print("Commands:")
+    print("  <topic>                    - Generate words and clues for topic")
+    print("  <topic> <num_words>        - Generate specific number of entries")
+    print("  <topic> <num_words> <diff> - Set difficulty (easy/medium/hard)")
+    print("  <topic> style <style>      - Set clue style (definition/synonym/hypernym/category)")
+    print("  info <word>                - Show WordNet information for word")
+    print("  test <word> <topic>        - Test clue generation for specific word")
+    print("  stats                      - Show generation statistics")
+    print("  help                       - Show this help")
+    print("  quit                       - Exit")
+    print()
+    print("Examples:")
+    print("  animals                    - Generate animal-related crossword entries")
+    print("  technology 10 hard         - 10 hard technology entries")
+    print("  music style synonym        - Music entries with synonym-style clues")
+    print("  info elephant              - WordNet info for 'elephant'")
+    
+    while True:
+        try:
+            user_input = input("\n🎯 Enter command: ").strip()
+            
+            if user_input.lower() in ['quit', 'exit', 'q']:
+                break
+            
+            if not user_input:
+                continue
+            
+            parts = user_input.split()
+            
+            if user_input.lower() == 'help':
+                print("\nCommands:")
+                print("  <topic> [num_words] [difficulty] - Generate crossword entries")
+                print("  <topic> style <clue_style>        - Generate with specific clue style")
+                print("  info <word>                       - Show WordNet info for word")
+                print("  test <word> <topic>               - Test clue generation")
+                print("  stats                             - Show statistics")
+                print("  quit                              - Exit")
+                continue
+            
+            elif user_input.lower() == 'stats':
+                stats = generator.get_stats()
+                print("\n📊 Generation Statistics:")
+                print(f"   Words discovered: {stats['words_discovered']}")
+                print(f"   Clues generated: {stats['clues_generated']}")
+                print(f"   Total time: {stats['total_time']:.2f}s")
+                if stats['clues_generated'] > 0:
+                    avg_time = stats['total_time'] / stats['clues_generated']
+                    print(f"   Avg time per clue: {avg_time:.2f}s")
+                continue
+            
+            elif parts[0].lower() == 'info' and len(parts) > 1:
+                word = parts[1]
+                print(f"\n📝 WordNet Information: '{word}'")
+                info = generator.clue_generator.get_clue_info(word)
+                
+                if 'error' in info:
+                    print(f"   ❌ {info['error']}")
+                else:
+                    print(f"   Synsets found: {info['synsets_count']}")
+                    for i, synset in enumerate(info['synsets'], 1):
+                        print(f"\n   {i}. {synset['name']} ({synset['pos']})")
+                        print(f"      Definition: {synset['definition']}")
+                        if synset['examples']:
+                            print(f"      Examples: {', '.join(synset['examples'])}")
+                        if synset['synonyms']:
+                            print(f"      Synonyms: {', '.join(synset['synonyms'])}")
+                        if synset['hypernyms']:
+                            print(f"      Categories: {', '.join(synset['hypernyms'])}")
+                continue
+            
+            elif parts[0].lower() == 'test' and len(parts) >= 3:
+                word = parts[1]
+                topic = parts[2]
+                print(f"\n🧪 Testing clue generation: '{word}' + '{topic}'")
+                
+                styles = ['definition', 'synonym', 'hypernym', 'category', 'descriptive']
+                for style in styles:
+                    clue = generator.clue_generator.generate_clue(word, topic, style, 'medium')
+                    print(f"   {style:12}: {clue if clue else '(no clue generated)'}")
+                continue
+            
+            # Parse generation command
+            topic = parts[0]
+            num_words = 8
+            difficulty = 'medium'
+            clue_style = 'auto'
+            
+            # Parse additional parameters
+            i = 1
+            while i < len(parts):
+                if parts[i].isdigit():
+                    num_words = int(parts[i])
+                elif parts[i].lower() in ['easy', 'medium', 'hard']:
+                    difficulty = parts[i].lower()
+                elif parts[i].lower() == 'style' and i + 1 < len(parts):
+                    clue_style = parts[i + 1].lower()
+                    i += 1
+                elif parts[i].lower() in ['definition', 'synonym', 'hypernym', 'category', 'descriptive']:
+                    clue_style = parts[i].lower()
+                i += 1
+            
+            print(f"\n🎯 Generating {num_words} {difficulty} entries for '{topic}'" +
+                  (f" (style: {clue_style})" if clue_style != 'auto' else ""))
+            print("-" * 60)
+            
+            try:
+                start_time = time.time()
+                entries = generator.generate_crossword_entries(
+                    topic=topic,
+                    num_words=num_words,
+                    difficulty=difficulty,
+                    clue_style=clue_style
+                )
+                generation_time = time.time() - start_time
+                
+                if entries:
+                    print(f"✅ Generated {len(entries)} entries in {generation_time:.2f}s:")
+                    print()
+                    
+                    for i, entry in enumerate(entries, 1):
+                        tier_short = entry.frequency_tier.split('_')[1] if '_' in entry.frequency_tier else 'unk'
+                        print(f"  {i:2}. {entry.word:<12} | {entry.clue}")
+                        print(f"      Similarity: {entry.similarity_score:.3f} | Tier: {tier_short} | Type: {entry.clue_type}")
+                        print()
+                else:
+                    print("❌ No entries generated. Try a different topic.")
+                
+            except Exception as e:
+                print(f"❌ Error: {e}")
+        
+        except KeyboardInterrupt:
+            print("\n\n👋 Exiting WordNet crossword generator")
+            break
+        except Exception as e:
+            print(f"❌ Error: {e}")
+    
+    # Show final stats
+    final_stats = generator.get_stats()
+    if final_stats['clues_generated'] > 0:
+        print(f"\n📊 Session Summary:")
+        print(f"   Entries generated: {final_stats['clues_generated']}")
+        print(f"   Total time: {final_stats['total_time']:.2f}s")
+        print(f"   Average per entry: {final_stats['total_time']/final_stats['clues_generated']:.2f}s")
+    
+    print("\n✅ Thanks for using WordNet Crossword Generator!")
+
+
+if __name__ == "__main__":
+    main()

crossword-app/backend-py/test-integration/test_boundary_fix.py

@@ -1,147 +0,0 @@
-#!/usr/bin/env python3
-
-import sys
-import asyncio
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent.parent  # Go up from test-integration to backend-py
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator import CrosswordGenerator
-
-async def test_boundary_fix():
-    """Test that the boundary fix works correctly."""
-    
-    # Sample words that are known to cause boundary issues
-    test_words = [
-        {"word": "COMPUTER", "clue": "Electronic device"},
-        {"word": "MACHINE", "clue": "Device with moving parts"},
-        {"word": "SCIENCE", "clue": "Systematic study"},
-        {"word": "EXPERT", "clue": "Specialist"},
-        {"word": "CODE", "clue": "Programming text"},
-        {"word": "DATA", "clue": "Information"}
-    ]
-    
-    generator = CrosswordGenerator()
-    
-    print("🧪 Testing Boundary Fix")
-    print("=" * 50)
-    
-    # Generate a crossword
-    result = generator._create_grid(test_words)
-    
-    if not result:
-        print("❌ Grid generation failed")
-        return False
-    
-    grid = result["grid"]
-    placed_words = result["placed_words"]
-    
-    print(f"✅ Generated grid with {len(placed_words)} words")
-    print(f"Grid size: {len(grid)}x{len(grid[0])}")
-    
-    # Display the grid
-    print("\nGenerated Grid:")
-    for i, row in enumerate(grid):
-        row_str = " ".join(cell if cell != "." else " " for cell in row)
-        print(f"{i:2d} | {row_str}")
-    
-    print(f"\nPlaced Words:")
-    for word in placed_words:
-        print(f"  {word['word']} at ({word['row']},{word['col']}) {word['direction']}")
-    
-    # Analyze for boundary violations
-    print(f"\n🔍 Analyzing for boundary violations...")
-    
-    violations = []
-    
-    # Check horizontal words
-    for r in range(len(grid)):
-        current_word = ""
-        word_start = -1
-        
-        for c in range(len(grid[r])):
-            if grid[r][c] != ".":
-                if current_word == "":
-                    word_start = c
-                current_word += grid[r][c]
-            else:
-                if current_word:
-                    # Word ended - check if it's a valid placed word
-                    is_valid_word = any(
-                        placed['word'] == current_word and 
-                        placed['row'] == r and 
-                        placed['col'] == word_start and 
-                        placed['direction'] == 'horizontal'
-                        for placed in placed_words
-                    )
-                    if not is_valid_word and len(current_word) > 1:
-                        violations.append(f"Invalid horizontal word '{current_word}' at ({r},{word_start})")
-                    current_word = ""
-        
-        # Check word at end of row
-        if current_word:
-            is_valid_word = any(
-                placed['word'] == current_word and 
-                placed['row'] == r and 
-                placed['col'] == word_start and 
-                placed['direction'] == 'horizontal'
-                for placed in placed_words
-            )
-            if not is_valid_word and len(current_word) > 1:
-                violations.append(f"Invalid horizontal word '{current_word}' at ({r},{word_start})")
-    
-    # Check vertical words
-    for c in range(len(grid[0])):
-        current_word = ""
-        word_start = -1
-        
-        for r in range(len(grid)):
-            if grid[r][c] != ".":
-                if current_word == "":
-                    word_start = r
-                current_word += grid[r][c]
-            else:
-                if current_word:
-                    # Word ended - check if it's a valid placed word
-                    is_valid_word = any(
-                        placed['word'] == current_word and 
-                        placed['row'] == word_start and 
-                        placed['col'] == c and 
-                        placed['direction'] == 'vertical'
-                        for placed in placed_words
-                    )
-                    if not is_valid_word and len(current_word) > 1:
-                        violations.append(f"Invalid vertical word '{current_word}' at ({word_start},{c})")
-                    current_word = ""
-        
-        # Check word at end of column
-        if current_word:
-            is_valid_word = any(
-                placed['word'] == current_word and 
-                placed['row'] == word_start and 
-                placed['col'] == c and 
-                placed['direction'] == 'vertical'
-                for placed in placed_words
-            )
-            if not is_valid_word and len(current_word) > 1:
-                violations.append(f"Invalid vertical word '{current_word}' at ({word_start},{c})")
-    
-    # Report results
-    if violations:
-        print(f"❌ Found {len(violations)} boundary violations:")
-        for violation in violations:
-            print(f"  - {violation}")
-        return False
-    else:
-        print(f"✅ No boundary violations found!")
-        print(f"✅ All words in grid are properly placed and bounded")
-        return True
-
-if __name__ == "__main__":
-    success = asyncio.run(test_boundary_fix())
-    if success:
-        print(f"\n🎉 Boundary fix is working correctly!")
-    else:
-        print(f"\n💥 Boundary fix needs more work!")

crossword-app/backend-py/test-integration/test_bounds_comprehensive.py

@@ -1,266 +0,0 @@
-#!/usr/bin/env python3
-"""
-Comprehensive test for bounds checking fixes in crossword generator.
-"""
-
-import asyncio
-import sys
-import pytest
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent.parent  # Go up from test-integration to backend-py
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-
-class TestBoundsChecking:
-    """Test all bounds checking in crossword generator."""
-    
-    def setup_method(self):
-        """Setup test instance."""
-        self.generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    def test_can_place_word_bounds_horizontal(self):
-        """Test _can_place_word bounds checking for horizontal placement."""
-        # Create small grid
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Test cases that should fail bounds checking
-        assert not self.generator._can_place_word(grid, "TOOLONG", 2, 1, "horizontal")  # Word too long
-        assert not self.generator._can_place_word(grid, "TEST", -1, 1, "horizontal")    # Negative row
-        assert not self.generator._can_place_word(grid, "TEST", 1, -1, "horizontal")    # Negative col
-        assert not self.generator._can_place_word(grid, "TEST", 5, 1, "horizontal")     # Row >= size
-        assert not self.generator._can_place_word(grid, "TEST", 1, 5, "horizontal")     # Col >= size
-        assert not self.generator._can_place_word(grid, "TEST", 1, 3, "horizontal")     # Word extends beyond grid
-        
-        # Test cases that should pass
-        assert self.generator._can_place_word(grid, "TEST", 2, 1, "horizontal")         # Valid placement
-        assert self.generator._can_place_word(grid, "A", 0, 0, "horizontal")            # Single letter
-        
-    def test_can_place_word_bounds_vertical(self):
-        """Test _can_place_word bounds checking for vertical placement."""
-        # Create small grid
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Test cases that should fail bounds checking
-        assert not self.generator._can_place_word(grid, "TOOLONG", 1, 2, "vertical")    # Word too long
-        assert not self.generator._can_place_word(grid, "TEST", -1, 1, "vertical")      # Negative row
-        assert not self.generator._can_place_word(grid, "TEST", 1, -1, "vertical")      # Negative col
-        assert not self.generator._can_place_word(grid, "TEST", 5, 1, "vertical")       # Row >= size
-        assert not self.generator._can_place_word(grid, "TEST", 1, 5, "vertical")       # Col >= size
-        assert not self.generator._can_place_word(grid, "TEST", 3, 1, "vertical")       # Word extends beyond grid
-        
-        # Test cases that should pass
-        assert self.generator._can_place_word(grid, "TEST", 1, 2, "vertical")           # Valid placement
-        assert self.generator._can_place_word(grid, "A", 0, 0, "vertical")              # Single letter
-    
-    def test_place_word_bounds_horizontal(self):
-        """Test _place_word bounds checking for horizontal placement."""
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Valid placement should work
-        original_state = self.generator._place_word(grid, "TEST", 2, 1, "horizontal")
-        assert len(original_state) == 4
-        assert grid[2][1] == "T"
-        assert grid[2][4] == "T"
-        
-        # Test out-of-bounds placement should raise IndexError
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TOOLONG", 2, 1, "horizontal")
-        
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", -1, 1, "horizontal")
-        
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", 5, 1, "horizontal")
-            
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", 1, 5, "horizontal")
-    
-    def test_place_word_bounds_vertical(self):
-        """Test _place_word bounds checking for vertical placement."""
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Valid placement should work
-        original_state = self.generator._place_word(grid, "TEST", 1, 2, "vertical")
-        assert len(original_state) == 4
-        assert grid[1][2] == "T"
-        assert grid[4][2] == "T"
-        
-        # Test out-of-bounds placement should raise IndexError
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TOOLONG", 1, 2, "vertical")
-            
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", -1, 2, "vertical")
-            
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", 5, 2, "vertical")
-            
-        with pytest.raises(IndexError):
-            self.generator._place_word(grid, "TEST", 2, 5, "vertical")
-    
-    def test_remove_word_bounds(self):
-        """Test _remove_word bounds checking."""
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Place a word first
-        original_state = self.generator._place_word(grid, "TEST", 2, 1, "horizontal")
-        
-        # Normal removal should work
-        self.generator._remove_word(grid, original_state)
-        assert grid[2][1] == "."
-        
-        # Test invalid original state should raise IndexError
-        bad_state = [{"row": -1, "col": 1, "value": "."}]
-        with pytest.raises(IndexError):
-            self.generator._remove_word(grid, bad_state)
-            
-        bad_state = [{"row": 5, "col": 1, "value": "."}]
-        with pytest.raises(IndexError):
-            self.generator._remove_word(grid, bad_state)
-            
-        bad_state = [{"row": 1, "col": -1, "value": "."}]
-        with pytest.raises(IndexError):
-            self.generator._remove_word(grid, bad_state)
-            
-        bad_state = [{"row": 1, "col": 5, "value": "."}]
-        with pytest.raises(IndexError):
-            self.generator._remove_word(grid, bad_state)
-    
-    def test_create_simple_cross_bounds(self):
-        """Test _create_simple_cross bounds checking."""
-        # Test with words that have intersections
-        word_list = ["CAT", "TOY"]  # 'T' intersection
-        word_objs = [{"word": w, "clue": f"Clue for {w}"} for w in word_list]
-        
-        # This should work without bounds errors
-        result = self.generator._create_simple_cross(word_list, word_objs)
-        assert result is not None
-        assert len(result["placed_words"]) == 2
-        
-        # Test with words that might cause issues
-        word_list = ["A", "A"]  # Same single letter
-        word_objs = [{"word": w, "clue": f"Clue for {w}"} for w in word_list]
-        
-        # This should not crash with bounds errors
-        result = self.generator._create_simple_cross(word_list, word_objs)
-        # May return None due to placement issues, but should not crash
-    
-    def test_trim_grid_bounds(self):
-        """Test _trim_grid bounds checking."""
-        # Create a grid with words placed
-        grid = [["." for _ in range(10)] for _ in range(10)]
-        
-        # Place some letters
-        grid[5][3] = "T"
-        grid[5][4] = "E"
-        grid[5][5] = "S"
-        grid[5][6] = "T"
-        
-        placed_words = [{
-            "word": "TEST",
-            "row": 5,
-            "col": 3,
-            "direction": "horizontal",
-            "number": 1
-        }]
-        
-        # This should work without bounds errors
-        result = self.generator._trim_grid(grid, placed_words)
-        assert result is not None
-        assert "grid" in result
-        assert "placed_words" in result
-        
-        # Test with edge case placements
-        placed_words = [{
-            "word": "A",
-            "row": 0,
-            "col": 0,
-            "direction": "horizontal", 
-            "number": 1
-        }]
-        
-        grid[0][0] = "A"
-        result = self.generator._trim_grid(grid, placed_words)
-        assert result is not None
-    
-    def test_calculation_placement_score_bounds(self):
-        """Test _calculate_placement_score bounds checking."""
-        grid = [["." for _ in range(5)] for _ in range(5)]
-        
-        # Place some letters for intersection testing
-        grid[2][2] = "T"
-        grid[2][3] = "E"
-        
-        placement = {"row": 2, "col": 2, "direction": "horizontal"}
-        placed_words = []
-        
-        # This should work without bounds errors
-        score = self.generator._calculate_placement_score(grid, "TEST", placement, placed_words)
-        assert isinstance(score, int)
-        
-        # Test with out-of-bounds placement (should handle gracefully)
-        placement = {"row": 4, "col": 3, "direction": "horizontal"}  # Would extend beyond grid
-        score = self.generator._calculate_placement_score(grid, "TEST", placement, placed_words)
-        assert isinstance(score, int)
-        
-        # Test with negative placement (should handle gracefully)
-        placement = {"row": -1, "col": 0, "direction": "horizontal"}
-        score = self.generator._calculate_placement_score(grid, "TEST", placement, placed_words)
-        assert isinstance(score, int)
-
-async def test_full_generation_stress():
-    """Stress test full generation to catch index errors."""
-    generator = CrosswordGeneratorFixed(vector_service=None)
-    
-    # Mock word selection to return test words
-    test_words = [
-        {"word": "CAT", "clue": "Feline pet"},
-        {"word": "DOG", "clue": "Man's best friend"}, 
-        {"word": "BIRD", "clue": "Flying animal"},
-        {"word": "FISH", "clue": "Aquatic animal"},
-        {"word": "ELEPHANT", "clue": "Large mammal"},
-        {"word": "TIGER", "clue": "Striped cat"},
-        {"word": "HORSE", "clue": "Riding animal"},
-        {"word": "BEAR", "clue": "Large carnivore"},
-        {"word": "WOLF", "clue": "Pack animal"},
-        {"word": "LION", "clue": "King of jungle"}
-    ]
-    
-    generator._select_words = lambda topics, difficulty, use_ai: test_words
-    
-    # Run multiple generation attempts
-    for i in range(20):
-        try:
-            result = await generator.generate_puzzle(["animals"], "medium", use_ai=False)
-            if result:
-                print(f"✅ Generation {i+1} succeeded")
-            else:
-                print(f"⚠️ Generation {i+1} returned None")
-        except IndexError as e:
-            print(f"❌ Index error in generation {i+1}: {e}")
-            raise
-        except Exception as e:
-            print(f"⚠️ Other error in generation {i+1}: {e}")
-            # Don't raise for other errors, just continue
-    
-    print("✅ All stress test generations completed without index errors!")
-
-if __name__ == "__main__":
-    # Run tests
-    print("🧪 Running comprehensive bounds checking tests...")
-    
-    # Run pytest on this file
-    import subprocess
-    result = subprocess.run([sys.executable, "-m", "pytest", __file__, "-v"], 
-                          capture_output=True, text=True)
-    
-    print("STDOUT:", result.stdout)
-    if result.stderr:
-        print("STDERR:", result.stderr)
-    
-    # Run stress test
-    print("\n🏋️ Running stress test...")
-    asyncio.run(test_full_generation_stress())

crossword-app/backend-py/test-integration/test_bounds_fix.py

@@ -1,90 +0,0 @@
-#!/usr/bin/env python3
-"""
-Quick test to verify the bounds checking fix.
-"""
-
-import sys
-from pathlib import Path
-
-# Add project root to path
-project_root = Path(__file__).parent.parent  # Go up from test-integration to backend-py
-sys.path.insert(0, str(project_root))
-
-from src.services.crossword_generator_fixed import CrosswordGeneratorFixed
-
-def test_bounds_checking():
-    """Test that placement score calculation doesn't crash with out-of-bounds access."""
-    print("🧪 Testing bounds checking fix...")
-    
-    generator = CrosswordGeneratorFixed()
-    
-    # Create a small grid
-    grid = [["." for _ in range(5)] for _ in range(5)]
-    
-    # Test placement that would go out of bounds
-    placement = {
-        "row": 3,       # Starting at row 3
-        "col": 2,       # Starting at col 2  
-        "direction": "vertical"
-    }
-    
-    # Word that would extend beyond grid (3+8=11 > 5)
-    word = "ELEPHANT"  # 8 letters, would go from row 3 to row 10 (out of bounds)
-    
-    try:
-        # This should NOT crash with bounds checking
-        score = generator._calculate_placement_score(grid, word, placement, [])
-        print(f"✅ Success! Placement score calculated: {score}")
-        print("✅ Bounds checking is working correctly")
-        return True
-    except IndexError as e:
-        print(f"❌ IndexError still occurs: {e}")
-        return False
-    except Exception as e:
-        print(f"❌ Other error: {e}")
-        return False
-
-def test_valid_placement():
-    """Test that valid placements still work correctly."""
-    print("\n🧪 Testing valid placement scoring...")
-    
-    generator = CrosswordGeneratorFixed()
-    
-    # Create a grid with some letters
-    grid = [["." for _ in range(8)] for _ in range(8)]
-    grid[2][2] = "A"  # Place an 'A' at position (2,2)
-    
-    # Test placement that intersects properly
-    placement = {
-        "row": 2,
-        "col": 1,
-        "direction": "horizontal"
-    }
-    
-    word = "CAT"  # Should intersect at the 'A'
-    
-    try:
-        score = generator._calculate_placement_score(grid, word, placement, [])
-        print(f"✅ Valid placement score: {score}")
-        
-        # Should have intersection bonus (score > 100)
-        if score > 300:  # Base 100 + intersection 200
-            print("✅ Intersection detection working")
-        else:
-            print(f"⚠️ Expected intersection bonus, got score {score}")
-        
-        return True
-    except Exception as e:
-        print(f"❌ Error with valid placement: {e}")
-        return False
-
-if __name__ == "__main__":
-    print("🔧 Testing crossword generator bounds fix\n")
-    
-    test1_pass = test_bounds_checking()
-    test2_pass = test_valid_placement()
-    
-    if test1_pass and test2_pass:
-        print("\n✅ All tests passed! The bounds checking fix is working.")
-    else:
-        print("\n❌ Some tests failed. More work needed.")