| # Debug Tab Feature Documentation | |
| ## Overview | |
| The debug tab feature provides detailed insights into the thematic word generation process when enabled via environment variable. This feature is designed for developers to understand how the ML-based word selection algorithm works internally. | |
| ## Environment Variable | |
| ```bash | |
| ENABLE_DEBUG_TAB=true # Enable debug data collection and return | |
| ENABLE_DEBUG_TAB=false # Disable debug data (default) | |
| ``` | |
| ## When Debug Data is Collected | |
| Debug data is collected during the thematic word generation process in `find_words_for_crossword()` when: | |
| 1. `ENABLE_DEBUG_TAB=true` environment variable is set | |
| 2. The thematic word service is properly initialized | |
| 3. Any API endpoint that generates crossword puzzles is called | |
| ## API Response Structure | |
| ### Without Debug (Default) | |
| ```json | |
| { | |
| "grid": [...], | |
| "clues": {...}, | |
| "metadata": {...} | |
| } | |
| ``` | |
| ### With Debug Enabled | |
| ```json | |
| { | |
| "grid": [...], | |
| "clues": {...}, | |
| "metadata": {...}, | |
| "debug": { | |
| "enabled": true, | |
| "generation_params": { | |
| "topics": ["animals"], | |
| "difficulty": "easy", | |
| "requested_words": 10, | |
| "custom_sentence": null, | |
| "multi_theme": true, | |
| "thematic_pool_size": 150, | |
| "min_similarity": 0.25 | |
| }, | |
| "thematic_pool": [ | |
| { | |
| "word": "CAT", | |
| "similarity": 0.834, | |
| "tier": "tier_5_common", | |
| "percentile": 0.952, | |
| "tier_description": "Common (Top 8%)" | |
| } | |
| ], | |
| "candidate_words": [ | |
| { | |
| "word": "CAT", | |
| "similarity": 0.834, | |
| "tier": "tier_5_common", | |
| "percentile": 0.952, | |
| "clue": "Feline pet", | |
| "semantic_neighbors": ["dog", "kitten", "feline", "pet", "animal"] | |
| } | |
| ], | |
| "selection_method": "softmax", | |
| "selection_params": { | |
| "use_softmax_selection": true, | |
| "similarity_temperature": 0.2, | |
| "difficulty_weight": 0.5 | |
| }, | |
| "selected_words": [ | |
| { | |
| "word": "CAT", | |
| "similarity": 0.834, | |
| "tier": "tier_5_common", | |
| "percentile": 0.952, | |
| "clue": "Feline pet" | |
| } | |
| ] | |
| } | |
| } | |
| ``` | |
| ## Debug Data Structure | |
| ### `generation_params` | |
| - **topics**: Input topics provided by user | |
| - **difficulty**: Selected difficulty level | |
| - **requested_words**: Number of words requested | |
| - **custom_sentence**: Custom sentence input (if any) | |
| - **multi_theme**: Whether multi-theme processing was used | |
| - **thematic_pool_size**: Size of initial thematic pool generated | |
| - **min_similarity**: Minimum similarity threshold used | |
| ### `thematic_pool` | |
| Array of all words generated thematically (typically 150 words): | |
| - **word**: The word in uppercase | |
| - **similarity**: Cosine similarity score to theme (0.0-1.0) | |
| - **tier**: Frequency tier (tier_1_ultra_common to tier_10_very_rare) | |
| - **percentile**: Word frequency percentile (0.0-1.0, higher = more common) | |
| - **tier_description**: Human-readable tier description | |
| ### `candidate_words` | |
| Array of words that passed filtering and got clues generated: | |
| - All fields from `thematic_pool` plus: | |
| - **clue**: Generated crossword clue | |
| - **semantic_neighbors**: List of semantically similar words from embeddings | |
| ### `selection_method` | |
| - `"softmax"`: Uses ML-based probabilistic selection | |
| - `"random"`: Uses traditional random selection | |
| ### `selection_params` | |
| Current algorithm parameters: | |
| - **use_softmax_selection**: Whether softmax selection is enabled | |
| - **similarity_temperature**: Temperature for softmax (lower = more deterministic) | |
| - **difficulty_weight**: Balance between similarity and frequency (0.0-1.0) | |
| ### `selected_words` | |
| Final words chosen for crossword generation with their scores and metadata. | |
| ## Use Cases for Debug Data | |
| ### 1. Algorithm Performance Analysis | |
| - Compare similarity scores across difficulty levels | |
| - Analyze frequency distribution in selections | |
| - Understand why certain words were selected/rejected | |
| ### 2. Difficulty Tuning | |
| - Verify easy mode selects common words (high percentiles) | |
| - Verify hard mode selects rare words (low percentiles) | |
| - Check if composite scoring is working as expected | |
| ### 3. Clue Quality Assessment | |
| - Review generated clues for accuracy | |
| - Analyze semantic neighbors for clue generation | |
| - Identify words that need manual clue overrides | |
| ### 4. Theme Relevance Debugging | |
| - Check similarity scores for theme matching | |
| - Identify words that don't match intended theme | |
| - Analyze multi-theme vs single-theme behavior | |
| ## Frontend Integration | |
| The debug data can be displayed in a separate "Debug" or "Peek-in" tab that shows: | |
| 1. **Generation Overview**: Parameters and summary statistics | |
| 2. **Thematic Pool**: Sortable table of all 150 generated words | |
| 3. **Selection Process**: Visualization of softmax probabilities | |
| 4. **Semantic Analysis**: Word neighbors and clue generation details | |
| 5. **Performance Metrics**: Timing and efficiency data | |
| ## Performance Impact | |
| - **Disabled** (default): No performance impact | |
| - **Enabled**: Minimal impact (~5-10ms additional processing) | |
| - Semantic neighbor computation: ~1-2ms per word | |
| - Debug data structure creation: ~3-5ms total | |
| - JSON serialization: Negligible | |
| ## Security Considerations | |
| - Debug data exposes internal ML model behavior | |
| - Should only be enabled in development/staging environments | |
| - No sensitive user data is exposed | |
| - All data is derived from public word frequencies and embeddings | |
| ## Testing | |
| ```bash | |
| # Test debug disabled | |
| python test_debug_feature.py | |
| # Test with full model loading (takes time) | |
| ENABLE_DEBUG_TAB=true python -c "import asyncio; from test_debug_feature import full_integration_test; asyncio.run(full_integration_test())" | |
| # Test API endpoint with debug enabled | |
| ENABLE_DEBUG_TAB=true uvicorn app:app --host 0.0.0.0 --port 7860 | |
| curl -X POST http://localhost:7860/api/generate -H "Content-Type: application/json" -d '{"topics": ["animals"], "difficulty": "easy", "wordCount": 8}' | |
| ``` | |
| ## Implementation Details | |
| ### Files Modified | |
| - `src/services/thematic_word_service.py`: Debug data collection | |
| - `src/services/crossword_generator.py`: Debug data pass-through | |
| - `src/routes/api.py`: Debug data inclusion in responses | |
| ### Key Functions | |
| - `ThematicWordService.find_words_for_crossword()`: Now returns `{"words": [...], "debug": {...}}` | |
| - `CrosswordGenerator._select_words()`: Now returns `(words, debug_data)` tuple | |
| - `CrosswordGenerator.generate_puzzle()`: Includes debug data in response | |
| ### Environment Variable Parsing | |
| ```python | |
| self.enable_debug_tab = os.getenv("ENABLE_DEBUG_TAB", "false").lower() == "true" | |
| ``` | |
| ## Future Enhancements | |
| 1. **Performance Metrics**: Add timing data for each processing stage | |
| 2. **Grid Placement Debug**: Include grid placement algorithm details | |
| 3. **Clue Generation Debug**: Detailed clue generation process insights | |
| 4. **Statistical Analysis**: Word distribution charts and analytics | |
| 5. **Export Functionality**: Export debug data as CSV/JSON for analysis | |
| --- | |
| *This feature was implemented in August 2025 as part of the crossword generation optimization project.* |