File size: 3,827 Bytes
0dc7706 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 |
# Adaptive Threshold Fix for Hugging Face Spaces
## Problem
The crossword generator was failing on Hugging Face Spaces with error:
```
❌ Not enough words: 3 < 6
❌ Error generating puzzle: Not enough words generated: 3 < 6
```
## Root Cause
The fixed similarity threshold of `WORD_SIMILARITY_THRESHOLD=0.65` was too strict, only allowing 3 words to pass the semantic similarity filter instead of the required minimum of 6.
## Solution: Adaptive Threshold Strategy
### 1. Adaptive Threshold Logic
Instead of a single fixed threshold, the system now tries multiple thresholds in descending order:
```python
thresholds_to_try = [
0.55, # High quality words (default base threshold)
0.50, # Good quality fallback
0.45, # Acceptable quality (minimum threshold)
0.45 # Never go below this
]
```
The system:
- Starts with high-quality threshold (0.55)
- Falls back to lower thresholds if insufficient words found
- Never goes below 0.45 to maintain semantic relevance
- Stops as soon as enough words are found
### 2. Enhanced Quality Filters
#### Topic Relevance Validation
Prevents cross-topic contamination:
```python
# Example: Animals topic rejects tech words
if topic == "Animals" and "computer" in word:
reject_word() # Prevents "COMPUTER" in animal crosswords
# Example: Technology topic rejects animal words
if topic == "Technology" and "elephant" in word:
reject_word() # Prevents "ELEPHANT" in tech crosswords
```
#### Quality Filters
- Rejects overly generic words ("word", "thing", "stuff")
- Filters out meta-terms and abstract concepts
- Maintains crossword-appropriate word lengths
### 3. Environment Configuration
#### Current HF Spaces Settings
```env
EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
WORD_SIMILARITY_THRESHOLD=0.65 # This can stay - adaptive system handles it
USE_AI_WORDS=true
FALLBACK_TO_STATIC=true
```
#### Recommended Additional Settings (Optional)
```env
SEARCH_RANDOMNESS=0.02 # Adds variety to search results
MAX_CACHED_WORDS=150 # Increase cache size
```
## Results Analysis
### Before Fix (Fixed Threshold 0.65)
- 120 FAISS search results
- Only 3 words above threshold
- **FAILURE**: Insufficient words for crossword
### After Fix (Adaptive Threshold)
- 120 FAISS search results
- Threshold 0.55: ~6 words (acceptable)
- Threshold 0.50: ~7 words (sufficient)
- **SUCCESS**: Generates 6+ relevant words
### Semantic Quality Maintained
- Threshold never goes below 0.45
- Topic relevance filters prevent unrelated words
- No risk of "mobile phone" words in "animals" crosswords
## Implementation Files Modified
1. **`src/services/vector_search.py`**
- Added adaptive threshold logic
- Enhanced topic relevance validation
- Improved fallback mechanisms
- Added debugging logs
2. **Environment Variables**
- `WORD_SIMILARITY_THRESHOLD` now sets the base threshold (default 0.55)
- System automatically adapts if insufficient words found
## Deployment Instructions
### For Hugging Face Spaces
**Option 1: Keep existing settings**
- Current `WORD_SIMILARITY_THRESHOLD=0.65` will work
- Adaptive system will fall back to 0.55, then 0.50, then 0.45 as needed
**Option 2: Optimize for performance**
- Change `WORD_SIMILARITY_THRESHOLD=0.55`
- Will find sufficient words faster on first try
### Testing
The fix has been validated with:
- ✅ Crossword generation tests pass
- ✅ Adaptive threshold logic verified
- ✅ Topic relevance validation confirmed
- ✅ Core algorithm integrity maintained
## Expected Outcome
- **Hugging Face Spaces**: Should now generate 6+ words successfully
- **Local Environment**: Continues to work as before
- **Quality**: Maintains semantic relevance while ensuring sufficient words
- **Performance**: Finds words faster by starting with optimal thresholds |