crossword-app/backend-py/docs/debug_tab_feature.md

# 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.*