feat: add frontend controls for similarity temperature and difficulty weight

- Add AdvancedSettings component with parameter sliders
- Add API support for parameter overrides in puzzle generation
- Pass advanced params through service layers to ThematicWordService
- Include presets for common parameter combinations (Default, Focused, Varied, Challenging)
- Restore original parameter values after generation to prevent side effects

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

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

@@ -23,6 +23,8 @@ class GeneratePuzzleRequest(BaseModel):
     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)")
+    similarityTemperature: Optional[float] = Field(default=None, description="Override similarity temperature for word selection randomness (0.1-2.0)")
+    difficultyWeight: Optional[float] = Field(default=None, description="Override difficulty weight for similarity vs frequency balance (0.0-1.0)")
 
 class WordInfo(BaseModel):
     word: str
@@ -130,13 +132,20 @@ async def generate_puzzle(
                 detail="Word count must be between 8 and 15"
             )
         
-        # Generate puzzle
+        # Generate puzzle with optional parameter overrides
+        advanced_params = {}
+        if request.similarityTemperature is not None:
+            advanced_params['similarity_temperature'] = request.similarityTemperature
+        if request.difficultyWeight is not None:
+            advanced_params['difficulty_weight'] = request.difficultyWeight
+        
         puzzle_data = await crossword_gen.generate_puzzle(
             topics=request.topics,
             difficulty=request.difficulty,
             custom_sentence=request.customSentence,
             multi_theme=request.multiTheme,
-            requested_words=request.wordCount
+            requested_words=request.wordCount,
+            advanced_params=advanced_params
         )
         
         if not puzzle_data:

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

@@ -18,7 +18,7 @@ class CrosswordGenerator:
         self.min_words = 6
         self.thematic_service = thematic_service
 
-    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]]:
+    async def generate_puzzle(self, topics: List[str], difficulty: str = "medium", custom_sentence: str = None, multi_theme: bool = True, requested_words: int = 10, advanced_params: Dict[str, Any] = None) -> Optional[Dict[str, Any]]:
         """
         Generate a complete crossword puzzle.
         """
@@ -27,7 +27,7 @@ class CrosswordGenerator:
             logger.info(f"🎯 Generating puzzle for topics: {topics}, difficulty: {difficulty}{sentence_info}, requested words: {requested_words}")
             
             # Get words from thematic AI service
-            words, debug_data = await self._select_words(topics, difficulty, custom_sentence, multi_theme, requested_words)
+            words, debug_data = await self._select_words(topics, difficulty, custom_sentence, multi_theme, requested_words, advanced_params)
             
             if len(words) < self.min_words:
                 logger.error(f"❌ Not enough words: {len(words)} < {self.min_words}")
@@ -66,7 +66,7 @@ class CrosswordGenerator:
             logger.error(f"❌ Error generating puzzle: {e}")
             raise
     
-    async def _select_words(self, topics: List[str], difficulty: str, custom_sentence: str = None, multi_theme: bool = True, requested_words: int = 10) -> Tuple[List[Dict[str, Any]], Optional[Dict[str, Any]]]:
+    async def _select_words(self, topics: List[str], difficulty: str, custom_sentence: str = None, multi_theme: bool = True, requested_words: int = 10, advanced_params: Dict[str, Any] = None) -> Tuple[List[Dict[str, Any]], Optional[Dict[str, Any]]]:
         """Select words for the crossword using thematic AI service.
         
         Returns:
@@ -78,7 +78,7 @@ class CrosswordGenerator:
         logger.info(f"🎯 Using thematic AI service for word generation with {requested_words} requested words")
         
         # Use the dedicated crossword method for better word selection
-        result = await self.thematic_service.find_words_for_crossword(topics, difficulty, requested_words, custom_sentence, multi_theme)
+        result = await self.thematic_service.find_words_for_crossword(topics, difficulty, requested_words, custom_sentence, multi_theme, advanced_params)
         
         # Extract words and debug data from new format
         words = result["words"]

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

@@ -23,7 +23,8 @@ class CrosswordGenerator:
         difficulty: str = "medium",
         custom_sentence: str = None,
         multi_theme: bool = True,
-        requested_words: int = 10
+        requested_words: int = 10,
+        advanced_params: Dict[str, Any] = None
     ) -> Dict[str, Any]:
         """
         Generate a complete crossword puzzle using the fixed generator.
@@ -34,6 +35,7 @@ class CrosswordGenerator:
             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
+            advanced_params: Optional dict with parameter overrides (similarity_temperature, difficulty_weight)
             
         Returns:
             Dictionary containing grid, clues, and metadata
@@ -45,7 +47,7 @@ class CrosswordGenerator:
             from .crossword_generator import CrosswordGenerator as ActualGenerator
             actual_generator = ActualGenerator(thematic_service=self.thematic_service)
             
-            puzzle = await actual_generator.generate_puzzle(topics, difficulty, custom_sentence, multi_theme, requested_words)
+            puzzle = await actual_generator.generate_puzzle(topics, difficulty, custom_sentence, multi_theme, requested_words, advanced_params)
             
             logger.info(f"✅ Generated crossword with fixed algorithm")
             return puzzle

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

@@ -428,15 +428,74 @@ class ThematicWordService:
         # Load or create frequency tiers
         self.frequency_tiers = self._create_frequency_tiers()
         
-        # Load model
+        # Load model with comprehensive diagnostics
         logger.info(f"🤖 Loading embedding model: {self.model_name}")
+        logger.info(f"📂 Cache directory: {self.cache_dir}")
+        logger.info(f"📂 Cache dir exists: {os.path.exists(self.cache_dir)}")
+        if os.path.exists(self.cache_dir):
+            logger.info(f"📂 Cache dir writable: {os.access(self.cache_dir, os.W_OK)}")
+            
+            # Check what's in cache
+            try:
+                cache_contents = os.listdir(self.cache_dir)
+                logger.info(f"📂 Cache contents ({len(cache_contents)} items): {cache_contents[:5]}...")  # First 5 items
+            except Exception as e:
+                logger.error(f"❌ Cannot list cache directory: {e}")
+        
+        # Log the exact model path being constructed
+        model_path = f'sentence-transformers/{self.model_name}'
+        logger.info(f"🔍 Full model path to load: {model_path}")
+        logger.info(f"🔍 Model name from env THEMATIC_MODEL_NAME: {os.getenv('THEMATIC_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")
+        
+        try:
+            self.model = SentenceTransformer(
+                model_path,
+                cache_folder=str(self.cache_dir)
+            )
+            model_time = time.time() - model_start
+            logger.info(f"✅ Model loaded successfully in {model_time:.2f}s")
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to load SentenceTransformer model: {e}")
+            logger.error(f"🔍 Error type: {type(e).__name__}")
+            logger.error(f"🔍 Model name used: {self.model_name}")
+            logger.error(f"🔍 Constructed path: {model_path}")
+            logger.error(f"🔍 Cache folder: {self.cache_dir}")
+            
+            # Check if model files exist in cache
+            model_cache_path = self.cache_dir / "models--sentence-transformers--all-mpnet-base-v2"
+            logger.error(f"🔍 Checking model cache path: {model_cache_path}")
+            
+            if model_cache_path.exists():
+                logger.error(f"📂 Model cache directory exists")
+                try:
+                    # List files in model cache
+                    for root, dirs, files in os.walk(model_cache_path):
+                        rel_path = os.path.relpath(root, model_cache_path)
+                        if rel_path == ".":
+                            rel_path = "root"
+                        logger.error(f"  📁 {rel_path}: {len(files)} files - {files[:3]}...")
+                        if len(dirs) > 0:
+                            logger.error(f"    📂 subdirs: {dirs}")
+                        # Stop after a reasonable number of entries
+                        if len(files) > 10:
+                            break
+                except Exception as walk_e:
+                    logger.error(f"❌ Cannot walk model cache: {walk_e}")
+            else:
+                logger.error(f"📂 Model cache directory does not exist")
+                
+                # Check for any sentence-transformers related folders
+                try:
+                    all_items = os.listdir(self.cache_dir)
+                    st_items = [item for item in all_items if 'sentence' in item.lower() or 'transform' in item.lower()]
+                    logger.error(f"📂 SentenceTransformer-related items in cache: {st_items}")
+                except Exception as list_e:
+                    logger.error(f"❌ Cannot check for related items: {list_e}")
+            
+            raise
         
         # Load or create embeddings
         self.vocab_embeddings = self._load_or_create_embeddings()
@@ -1440,7 +1499,7 @@ class ThematicWordService:
         
         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) -> Dict[str, Any]:
+    async def find_words_for_crossword(self, topics: List[str], difficulty: str, requested_words: int = 10, custom_sentence: str = None, multi_theme: bool = True, advanced_params: Dict[str, Any] = None) -> Dict[str, Any]:
         """
         Crossword-specific word finding method with 50% overgeneration and clue quality filtering.
         
@@ -1450,6 +1509,7 @@ class ThematicWordService:
             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)
+            advanced_params: Optional dict with parameter overrides (similarity_temperature, difficulty_weight)
             
         Returns:
             Dictionary with words and optional debug data:
@@ -1484,6 +1544,18 @@ class ThematicWordService:
         thematic_pool = min(self.thematic_pool_size, max(generation_target * 5, 50))
         logger.info(f"🚀 Optimized thematic pool size: {thematic_pool} (was 400) - {((400-thematic_pool)/400*100):.1f}% reduction")
         
+        # Handle advanced parameter overrides
+        original_temp = self.similarity_temperature
+        original_weight = self.difficulty_weight
+        
+        if advanced_params:
+            if 'similarity_temperature' in advanced_params:
+                self.similarity_temperature = advanced_params['similarity_temperature']
+                logger.info(f"🎛️ Overriding similarity temperature: {original_temp} → {self.similarity_temperature}")
+            if 'difficulty_weight' in advanced_params:
+                self.difficulty_weight = advanced_params['difficulty_weight']
+                logger.info(f"🎛️ Overriding difficulty weight: {original_weight} → {self.difficulty_weight}")
+        
         # a result is a tuple of  (word, similarity, word_tier)
         raw_results = self.generate_thematic_words(
             input_list,
@@ -1642,6 +1714,15 @@ class ThematicWordService:
             result["debug"] = debug_data
             logger.info(f"🐛 Debug data collected: {len(debug_data['thematic_pool'])} thematic words, {len(debug_data['candidate_words'])} candidates, {len(debug_data['selected_words'])} selected")
         
+        # Restore original parameter values if they were overridden
+        if advanced_params:
+            self.similarity_temperature = original_temp
+            self.difficulty_weight = original_weight
+            if 'similarity_temperature' in advanced_params:
+                logger.info(f"🔄 Restored similarity temperature: {self.similarity_temperature}")
+            if 'difficulty_weight' in advanced_params:
+                logger.info(f"🔄 Restored difficulty weight: {self.difficulty_weight}")
+        
         return result
 
     def _matches_crossword_difficulty(self, word: str, difficulty: str) -> bool:

crossword-app/frontend/src/App.jsx

@@ -3,6 +3,7 @@ import TopicSelector from './components/TopicSelector';
 import PuzzleGrid from './components/PuzzleGrid';
 import ClueList from './components/ClueList';
 import DebugTab from './components/DebugTab';
+import AdvancedSettings from './components/AdvancedSettings';
 import LoadingSpinner from './components/LoadingSpinner';
 import useCrossword from './hooks/useCrossword';
 import './styles/puzzle.css';
@@ -16,6 +17,10 @@ function App() {
   const [multiTheme, setMultiTheme] = useState(true);
   const [activeTab, setActiveTab] = useState('puzzle');
   
+  // Advanced settings state
+  const [similarityTemperature, setSimilarityTemperature] = useState(0.2);
+  const [difficultyWeight, setDifficultyWeight] = useState(0.5);
+  
   const {
     puzzle,
     loading,
@@ -40,7 +45,10 @@ function App() {
     }
     
     setShowSolution(false);
-    await generatePuzzle(allTopics, difficulty, false, customSentence, multiTheme);
+    await generatePuzzle(allTopics, difficulty, false, customSentence, multiTheme, {
+      similarityTemperature,
+      difficultyWeight
+    });
   };
 
   const handleTopicsChange = (topics) => {
@@ -69,6 +77,8 @@ function App() {
     setCustomSentence('');
     setMultiTheme(true);
     setActiveTab('puzzle');
+    setSimilarityTemperature(0.2);
+    setDifficultyWeight(0.5);
   };
 
   const handleRevealSolution = () => {
@@ -94,6 +104,13 @@ function App() {
         onMultiThemeChange={handleMultiThemeChange}
       />
 
+      <AdvancedSettings 
+        similarityTemperature={similarityTemperature}
+        onTemperatureChange={setSimilarityTemperature}
+        difficultyWeight={difficultyWeight}
+        onWeightChange={setDifficultyWeight}
+      />
+
       <div className="puzzle-controls">
         <select 
           value={difficulty} 

crossword-app/frontend/src/components/AdvancedSettings.jsx

@@ -0,0 +1,155 @@
+import React, { useState } from 'react';
+
+const AdvancedSettings = ({ 
+  similarityTemperature, 
+  onTemperatureChange, 
+  difficultyWeight, 
+  onWeightChange 
+}) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  const presets = [
+    { 
+      name: 'Default', 
+      temp: 0.2, 
+      weight: 0.5, 
+      description: 'Balanced settings (recommended)' 
+    },
+    { 
+      name: 'Focused', 
+      temp: 0.1, 
+      weight: 0.3, 
+      description: 'Deterministic, similarity-based' 
+    },
+    { 
+      name: 'Varied', 
+      temp: 0.7, 
+      weight: 0.5, 
+      description: 'More randomness and variety' 
+    },
+    { 
+      name: 'Challenging', 
+      temp: 0.5, 
+      weight: 0.7, 
+      description: 'Respects difficulty levels more' 
+    }
+  ];
+
+  const applyPreset = (preset) => {
+    onTemperatureChange(preset.temp);
+    onWeightChange(preset.weight);
+  };
+
+  const getTemperatureDescription = (value) => {
+    if (value <= 0.3) return 'Deterministic (top similar words)';
+    if (value <= 0.6) return 'Balanced (good variety)';
+    if (value <= 1.0) return 'Random (surprising choices)';
+    return 'Very random (unpredictable)';
+  };
+
+  const getWeightDescription = (value) => {
+    if (value <= 0.2) return 'Similarity-focused';
+    if (value <= 0.4) return 'Slightly similarity-focused';
+    if (value <= 0.6) return 'Balanced';
+    if (value <= 0.8) return 'Slightly frequency-focused';
+    return 'Frequency-focused';
+  };
+
+  return (
+    <div className="advanced-settings">
+      <div 
+        className="advanced-settings-header" 
+        onClick={() => setIsExpanded(!isExpanded)}
+      >
+        <span className="settings-icon">⚙️</span>
+        <span className="settings-title">Advanced Settings</span>
+        <span className="expand-icon">{isExpanded ? '▼' : '▶'}</span>
+      </div>
+      
+      {isExpanded && (
+        <div className="advanced-settings-content">
+          <div className="setting-group">
+            <label className="setting-label">
+              Word Selection Randomness
+              <span className="setting-value">{similarityTemperature.toFixed(1)}</span>
+            </label>
+            <div className="slider-container">
+              <input
+                type="range"
+                min="0.1"
+                max="2.0"
+                step="0.1"
+                value={similarityTemperature}
+                onChange={(e) => onTemperatureChange(parseFloat(e.target.value))}
+                className="slider"
+              />
+              <div className="slider-labels">
+                <span>More focused</span>
+                <span>More variety</span>
+              </div>
+            </div>
+            <div className="setting-description">
+              {getTemperatureDescription(similarityTemperature)}
+            </div>
+          </div>
+
+          <div className="setting-group">
+            <label className="setting-label">
+              Difficulty Balance
+              <span className="setting-value">{difficultyWeight.toFixed(1)}</span>
+            </label>
+            <div className="slider-container">
+              <input
+                type="range"
+                min="0.0"
+                max="1.0"
+                step="0.1"
+                value={difficultyWeight}
+                onChange={(e) => onWeightChange(parseFloat(e.target.value))}
+                className="slider"
+              />
+              <div className="slider-labels">
+                <span>Similarity</span>
+                <span>Frequency</span>
+              </div>
+            </div>
+            <div className="setting-description">
+              {getWeightDescription(difficultyWeight)}
+            </div>
+          </div>
+
+          <div className="presets-section">
+            <div className="presets-label">Quick Presets:</div>
+            <div className="presets-container">
+              {presets.map((preset, index) => (
+                <button
+                  key={index}
+                  onClick={() => applyPreset(preset)}
+                  className={`preset-button ${
+                    similarityTemperature === preset.temp && difficultyWeight === preset.weight
+                      ? 'active'
+                      : ''
+                  }`}
+                  title={preset.description}
+                >
+                  {preset.name}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          <div className="settings-info">
+            <div className="info-item">
+              <strong>Temperature:</strong> Controls how random word selection is. Lower values pick the most similar words, higher values add variety.
+            </div>
+            <div className="info-item">
+              <strong>Weight:</strong> Balances similarity vs word frequency. Lower focuses on semantic similarity, higher respects difficulty levels.
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default AdvancedSettings;

crossword-app/frontend/src/hooks/useCrossword.js

@@ -22,7 +22,7 @@ const useCrossword = () => {
     }
   }, [API_BASE_URL]);
 
-  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium', useAI = false, customSentence = '', multiTheme = true) => {
+  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium', useAI = false, customSentence = '', multiTheme = true, advancedParams = {}) => {
     try {
       setLoading(true);
       setError(null);
@@ -37,7 +37,13 @@ const useCrossword = () => {
           difficulty,
           useAI,
           ...(customSentence && { customSentence }),
-          multiTheme
+          multiTheme,
+          ...(advancedParams.similarityTemperature !== undefined && { 
+            similarityTemperature: advancedParams.similarityTemperature 
+          }),
+          ...(advancedParams.difficultyWeight !== undefined && { 
+            difficultyWeight: advancedParams.difficultyWeight 
+          })
         })
       });
 

crossword-app/frontend/src/styles/puzzle.css

@@ -1,5 +1,184 @@
 /* Crossword Puzzle Styles */
 
+/* Advanced Settings Styles */
+.advanced-settings {
+  background: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 8px;
+  margin-bottom: 20px;
+  overflow: hidden;
+}
+
+.advanced-settings-header {
+  display: flex;
+  align-items: center;
+  padding: 12px 16px;
+  background: #e9ecef;
+  cursor: pointer;
+  user-select: none;
+  transition: background-color 0.2s ease;
+}
+
+.advanced-settings-header:hover {
+  background: #dee2e6;
+}
+
+.settings-icon {
+  margin-right: 8px;
+  font-size: 1.1rem;
+}
+
+.settings-title {
+  flex: 1;
+  font-weight: 600;
+  color: #2c3e50;
+}
+
+.expand-icon {
+  color: #6c757d;
+  font-size: 0.9rem;
+}
+
+.advanced-settings-content {
+  padding: 20px;
+}
+
+.setting-group {
+  margin-bottom: 24px;
+}
+
+.setting-group:last-child {
+  margin-bottom: 0;
+}
+
+.setting-label {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  font-weight: 600;
+  color: #2c3e50;
+  margin-bottom: 8px;
+}
+
+.setting-value {
+  background: #e9ecef;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 0.9rem;
+  color: #495057;
+}
+
+.slider-container {
+  margin-bottom: 8px;
+}
+
+.slider {
+  width: 100%;
+  height: 6px;
+  border-radius: 3px;
+  background: #dee2e6;
+  outline: none;
+  -webkit-appearance: none;
+  cursor: pointer;
+}
+
+.slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: #3498db;
+  cursor: pointer;
+  transition: transform 0.2s ease;
+}
+
+.slider::-webkit-slider-thumb:hover {
+  transform: scale(1.1);
+}
+
+.slider::-moz-range-thumb {
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: #3498db;
+  cursor: pointer;
+  border: none;
+}
+
+.slider-labels {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 4px;
+  font-size: 0.85rem;
+  color: #6c757d;
+}
+
+.setting-description {
+  font-size: 0.9rem;
+  color: #6c757d;
+  font-style: italic;
+}
+
+.presets-section {
+  margin-top: 20px;
+  padding-top: 20px;
+  border-top: 1px solid #dee2e6;
+}
+
+.presets-label {
+  font-weight: 600;
+  color: #2c3e50;
+  margin-bottom: 10px;
+}
+
+.presets-container {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.preset-button {
+  padding: 6px 12px;
+  border: 2px solid #6c757d;
+  background: white;
+  color: #6c757d;
+  border-radius: 16px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  font-size: 0.85rem;
+  font-weight: 500;
+}
+
+.preset-button:hover {
+  border-color: #3498db;
+  color: #3498db;
+}
+
+.preset-button.active {
+  border-color: #3498db;
+  background: #3498db;
+  color: white;
+}
+
+.settings-info {
+  margin-top: 16px;
+  padding: 12px;
+  background: #e3f2fd;
+  border-radius: 6px;
+  border-left: 4px solid #2196f3;
+}
+
+.info-item {
+  margin-bottom: 8px;
+  font-size: 0.85rem;
+  color: #1976d2;
+}
+
+.info-item:last-child {
+  margin-bottom: 0;
+}
+
 .crossword-app {
   max-width: 1200px;
   margin: 0 auto;