simplify ui language and integrate dual gemma models

- use gemma-3-27b for hints, gemma-3-12b for word selection
- simplify score display and progression messages
- add passage tracking (1/2, 2/2) in header
- clarify "2 passages per round, 2 rounds per level" system

LEADERBOARD_ROADMAP.md

@@ -1,171 +0,0 @@
-# Cloze Reader Leaderboard Implementation Roadmap
-
-## Overview
-This document outlines the implementation plan for adding a competitive leaderboard system to the Cloze Reader game, where players can submit their scores using 3-letter acronyms.
-
-## Phase 1: Core Infrastructure (Week 1-2)
-
-### 1.1 Database Schema
-- Create leaderboard table structure:
-  ```sql
-  leaderboard {
-    id: UUID
-    acronym: VARCHAR(3)
-    score: INTEGER
-    level_reached: INTEGER
-    total_time: INTEGER (seconds)
-    created_at: TIMESTAMP
-    ip_hash: VARCHAR(64) // For rate limiting
-  }
-  ```
-
-### 1.2 API Endpoints
-- `POST /api/leaderboard/submit` - Submit new score
-- `GET /api/leaderboard/top/{period}` - Get top scores (daily/weekly/all-time)
-- `GET /api/leaderboard/check-acronym/{acronym}` - Validate acronym availability
-
-### 1.3 Score Calculation
-- Base score = (correct_answers * 100) * level_multiplier
-- Time bonus = max(0, 1000 - seconds_per_round)
-- Streak bonus = consecutive_correct * 50
-
-## Phase 2: Frontend Integration (Week 2-3)
-
-### 2.1 UI Components
-- **Leaderboard Modal** (`leaderboardModal.js`)
-  - Top 10 display with rank, acronym, score, level
-  - Period toggle (Today/Week/All-Time)
-  - Personal best highlight
-
-### 2.2 Score Submission Flow
-- End-of-game prompt for acronym entry
-- 3-letter validation (A-Z only)
-- Profanity filter implementation
-- Success/error feedback
-
-### 2.3 Visual Elements
-- Trophy icons for top 3 positions
-- Animated score counter
-- Level badges display
-
-## Phase 3: Security & Performance (Week 3-4)
-
-### 3.1 Anti-Cheat Measures
-- Server-side score validation
-- Rate limiting (1 submission per 5 minutes per IP)
-- Score feasibility checks (max possible score per level)
-- Request signing with session tokens
-
-### 3.2 Caching Strategy
-- Redis cache for top 100 scores
-- 5-minute TTL for leaderboard queries
-- Real-time updates for top 10 changes
-
-### 3.3 Data Persistence
-- PostgreSQL for primary storage
-- Daily backups of leaderboard data
-- Archived monthly snapshots
-
-## Phase 4: Advanced Features (Week 4-5)
-
-### 4.1 Achievement System
-- "First Timer" - First leaderboard entry
-- "Vocabulary Master" - 10+ correct in a row
-- "Speed Reader" - Complete round < 30 seconds
-- "Persistent Scholar" - Play 7 days straight
-
-### 4.2 Social Features
-- Share score to social media
-- Challenge link generation
-- Friend acronym tracking
-
-### 4.3 Analytics Dashboard
-- Player retention metrics
-- Popular acronym analysis
-- Score distribution graphs
-
-## Technical Implementation Details
-
-### Backend Changes Required
-
-1. **FastAPI Endpoints** (`app.py`):
-   ```python
-   @app.post("/api/leaderboard/submit")
-   async def submit_score(score_data: ScoreSubmission)
-   
-   @app.get("/api/leaderboard/top/{period}")
-   async def get_leaderboard(period: str, limit: int = 10)
-   ```
-
-2. **Database Models** (`models.py` - new file):
-   ```python
-   class LeaderboardEntry(Base):
-       __tablename__ = "leaderboard"
-       # Schema implementation
-   ```
-
-3. **Validation Service** (`validation.py` - new file):
-   - Acronym format validation
-   - Profanity checking
-   - Score feasibility verification
-
-### Frontend Changes Required
-
-1. **Game Engine Integration** (`clozeGameEngine.js`):
-   - Track game metrics for scoring
-   - Call submission API on game end
-   - Store session data for validation
-
-2. **UI Updates** (`app.js`):
-   - Add leaderboard button to main menu
-   - Integrate submission modal
-   - Handle API responses
-
-3. **New Modules**:
-   - `leaderboardService.js` - API communication
-   - `scoreCalculator.js` - Client-side scoring logic
-   - `leaderboardUI.js` - UI component management
-
-## Deployment Considerations
-
-### Infrastructure Requirements
-- Database: PostgreSQL 14+
-- Cache: Redis 6+
-- API rate limiting: nginx or API Gateway
-- SSL certificate for secure submissions
-
-### Environment Variables
-```
-DATABASE_URL=postgresql://...
-REDIS_URL=redis://...
-LEADERBOARD_SECRET=... # For request signing
-PROFANITY_API_KEY=... # Optional external service
-```
-
-### Migration Strategy
-1. Deploy database schema
-2. Enable API endpoints (feature flagged)
-3. Gradual UI rollout (A/B testing)
-4. Full launch with announcement
-
-## Success Metrics
-
-- **Engagement**: 30% of players submit scores
-- **Retention**: 15% return to beat their score
-- **Performance**: <100ms leaderboard load time
-- **Security**: Zero validated cheating incidents
-
-## Timeline Summary
-
-- **Week 1-2**: Backend infrastructure
-- **Week 2-3**: Frontend integration
-- **Week 3-4**: Security hardening
-- **Week 4-5**: Advanced features
-- **Week 6**: Testing & deployment
-
-## Open Questions
-
-1. Should we allow Unicode characters in acronyms?
-2. Reset frequency for periodic leaderboards?
-3. Maximum entries per player per day?
-4. Prize/reward system for top performers?

README-testing-framework.md

@@ -0,0 +1,217 @@
+# Cloze Reader Model Testing Framework
+
+A comprehensive testing system for evaluating AI models across all tasks in the Cloze Reader application, including both OpenRouter and local LLM (LM Studio) models.
+
+## Features
+
+### 🎯 Comprehensive Testing
+- **Word Selection Testing**: Evaluates vocabulary selection accuracy, difficulty matching, and response quality
+- **Contextualization Testing**: Tests historical and literary context generation for books and authors
+- **Chat Hints Testing**: Assesses all 4 question types (part of speech, sentence role, word category, synonym)
+- **Performance Monitoring**: Tracks response times, success rates, and error patterns
+- **User Satisfaction Ratings**: Collect user feedback on model performance after each round
+
+### 🏠 Local LLM Support
+- **LM Studio Integration**: Auto-detects models running on port 1234
+- **Real-time Status**: Shows connection status and available models
+- **Response Cleaning**: Handles local LLM output artifacts automatically
+- **Fallback Testing**: Graceful handling when local server is unavailable
+
+### 📊 Advanced Analytics
+- **Multi-format Reports**: JSON, CSV, and Markdown outputs
+- **Performance Comparisons**: Side-by-side model analysis
+- **Quality Scoring**: Detailed evaluation metrics for each task
+- **Interactive Game Testing**: Real-time performance monitoring during gameplay
+- **User Ranking Integration**: 5-star ratings for word selection, passage quality, hint helpfulness, and overall experience
+
+## Quick Start
+
+### 1. Start the Testing Interface
+```bash
+# Start development server
+make dev
+# or
+python local-server.py 8000
+
+# Open testing interface
+open http://localhost:8000/model-testing.html
+```
+
+### 2. Setup Local LLM (Optional)
+```bash
+# Start LM Studio server on port 1234
+# Load your preferred model (e.g., Gemma-3-12b, Llama-3.1-8b)
+# The framework will auto-detect available models
+```
+
+### 3. Run Tests
+1. Select models to test (OpenRouter and/or local models)
+2. Click "Start Comprehensive Test" for full evaluation
+3. Or click "Test Selected Model in Game" for interactive testing
+4. Results are automatically saved to the `/output` folder
+
+## Test Results
+
+### CSV Output Format
+Results are saved as timestamped CSV files with columns for:
+- Model performance metrics (overall score, success rates)
+- Response time analytics (average, min, max)
+- Task-specific scores (word selection, contextualization, chat hints)
+- Error rates and reliability metrics
+- User satisfaction ratings (1-5 stars per category)
+- User comments and feedback count
+
+### Game Testing Output
+Interactive game sessions generate JSON reports with:
+- Real-time AI interaction logs
+- User performance analytics
+- Response time breakdowns
+- Error tracking and categorization
+- User satisfaction ratings per round
+- Qualitative feedback and comments
+
+## Model Categories
+
+### OpenRouter Models
+- GPT-4o, GPT-4o Mini
+- Claude 3.5 Sonnet, Claude 3 Haiku
+- Gemini Pro 1.5
+- Llama 3.1 (8B, 70B)
+- Mistral 7B, Phi-3 Medium, Qwen 2 7B
+
+### Local LLM Models (LM Studio)
+- Auto-detected from running server
+- Supports any OpenAI-compatible model
+- Common options: Gemma-3-12b, Llama-3.1-8b, Mistral-7b
+
+## Testing Methodology
+
+### Word Selection Evaluation
+- **Accuracy**: Words exist in source passage
+- **Difficulty Matching**: Length and complexity appropriate for level
+- **Quality Scoring**: Avoids overly common words at higher difficulties
+- **Performance**: Response time and success rate tracking
+- **User Rating**: 5-star scale for vocabulary appropriateness
+
+### Contextualization Assessment
+- **Relevance**: Mentions book title, author, historical context
+- **Educational Value**: Appropriate for language learners
+- **Completeness**: Balanced length (100-500 characters)
+- **Literary Terms**: Uses appropriate academic vocabulary
+- **User Rating**: Passage quality and educational value scoring
+
+### Chat Hints Analysis
+- **Question Type Coverage**: All 4 hint categories tested
+- **Educational Appropriateness**: Helps without revealing answers
+- **Response Quality**: Clear, concise, and helpful explanations
+- **Consistency**: Performance across different question types
+- **User Rating**: Helpfulness and clarity of AI hints
+
+### User Experience Rating
+After each round, users can rate:
+- **Word Selection Quality** (1-5 stars)
+- **Passage Selection** (1-5 stars)
+- **Hint Helpfulness** (1-5 stars)
+- **Overall Experience** (1-5 stars)
+- **Optional Comments** for detailed feedback
+
+## Architecture
+
+### Core Components
+- **ModelTestingFramework**: Main testing orchestrator
+- **TestAIService**: Performance-tracking AI service wrapper
+- **TestGameRunner**: Real-time game session monitoring
+- **TestReportGenerator**: Multi-format report generation
+
+### File Structure
+```
+src/
+├── modelTestingFramework.js    # Main testing logic
+├── testAIService.js           # AI service wrapper
+├── testGameRunner.js          # Game monitoring
+└── testReportGenerator.js     # Report generation
+
+model-testing.html             # Testing interface UI
+output/                        # Test results folder
+```
+
+## Usage Examples
+
+### Automated Testing
+```javascript
+import { ModelTestingFramework } from './src/modelTestingFramework.js';
+
+const framework = new ModelTestingFramework();
+const results = await framework.runComprehensiveTest();
+console.log('Results saved to output folder');
+```
+
+### Custom Model Testing
+```javascript
+const customModel = {
+    id: 'my-local-model',
+    name: 'Custom Local Model',
+    provider: 'local'
+};
+
+const result = await framework.testModel(customModel);
+```
+
+### Report Generation
+```javascript
+import { TestReportGenerator } from './src/testReportGenerator.js';
+
+const generator = new TestReportGenerator();
+const reports = await generator.generateAllReports(testResults);
+// Generates JSON, CSV, and Markdown reports
+```
+
+## Integration with Existing Codebase
+
+The testing framework integrates seamlessly with the existing Cloze Reader architecture:
+
+- **aiService.js**: Framework uses the same AI service patterns
+- **conversationManager.js**: Chat hint testing leverages existing conversation logic
+- **clozeGameEngine.js**: Game testing monitors actual game interactions
+- **bookDataService.js**: Uses same book data and quality filtering
+
+## Troubleshooting
+
+### Local LLM Issues
+- Ensure LM Studio is running on port 1234
+- Check that a model is loaded and ready
+- Verify CORS is enabled in LM Studio settings
+
+### API Key Issues
+- OpenRouter API key must be set via environment variable or meta tag
+- Local models don't require API keys
+
+### Performance Issues
+- Large model testing can take 10-30 minutes
+- Consider testing fewer models or specific categories
+- Monitor network connectivity for OpenRouter models
+
+## Contributing
+
+The testing framework is designed to be extensible:
+
+1. Add new model providers in `ModelTestingFramework.constructor()`
+2. Extend evaluation metrics in the respective `evaluate*` methods
+3. Add new report formats in `TestReportGenerator`
+4. Enhance UI components in `model-testing.html`
+
+## Results Interpretation
+
+### Overall Scores
+- **90-100**: Excellent performance across all tasks
+- **80-89**: Very good with minor weaknesses
+- **70-79**: Good performance with some limitations
+- **60-69**: Adequate but needs improvement
+- **Below 60**: Poor performance, not recommended
+
+### Success Rate Thresholds
+- **Word Selection**: >80% for production use
+- **Contextualization**: >90% for educational content
+- **Chat Hints**: >85% for effective tutoring
+
+Use these benchmarks to select the best model for your specific needs and performance requirements.

index.html

@@ -62,5 +62,13 @@
     </div>
     
     <script src="./src/app.js" type="module"></script>
+    <script type="module">
+        // Load test runner and ranking interface only in test mode
+        const urlParams = new URLSearchParams(window.location.search);
+        if (urlParams.get('testMode') === 'true') {
+            import('./src/testGameRunner.js');
+            import('./src/userRankingInterface.js');
+        }
+    </script>
 </body>
 </html>

model-testing.html

@@ -0,0 +1,629 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Cloze Reader - Model Testing Framework</title>
+    <style>
+        body {
+            font-family: 'Georgia', serif;
+            background: linear-gradient(135deg, #f5f3f0 0%, #e8e4df 100%);
+            margin: 0;
+            padding: 20px;
+            min-height: 100vh;
+        }
+
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+            background: rgba(255, 255, 255, 0.95);
+            border-radius: 15px;
+            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
+            padding: 40px;
+        }
+
+        h1 {
+            text-align: center;
+            color: #2c3e50;
+            font-size: 2.5rem;
+            margin-bottom: 10px;
+            text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.1);
+        }
+
+        .subtitle {
+            text-align: center;
+            color: #7f8c8d;
+            font-size: 1.2rem;
+            margin-bottom: 40px;
+        }
+
+        .model-selection {
+            background: #f8f9fa;
+            border-radius: 10px;
+            padding: 30px;
+            margin-bottom: 30px;
+            border: 2px solid #e9ecef;
+        }
+
+        .model-selection h2 {
+            color: #2c3e50;
+            margin-bottom: 20px;
+            font-size: 1.5rem;
+        }
+
+        .model-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 15px;
+            margin-bottom: 20px;
+        }
+
+        .model-option {
+            background: white;
+            border: 2px solid #dee2e6;
+            border-radius: 8px;
+            padding: 15px;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            position: relative;
+        }
+
+        .model-option:hover {
+            border-color: #007bff;
+            box-shadow: 0 4px 8px rgba(0, 123, 255, 0.2);
+        }
+
+        .model-option.selected {
+            border-color: #28a745;
+            background: #f8fff9;
+        }
+
+        .model-option input[type="checkbox"] {
+            position: absolute;
+            top: 10px;
+            right: 10px;
+            transform: scale(1.2);
+        }
+
+        .model-name {
+            font-weight: bold;
+            color: #2c3e50;
+            margin-bottom: 5px;
+        }
+
+        .model-provider {
+            color: #6c757d;
+            font-size: 0.9rem;
+            margin-bottom: 5px;
+        }
+
+        .model-id {
+            color: #495057;
+            font-size: 0.8rem;
+            font-family: monospace;
+            background: #f1f3f4;
+            padding: 2px 6px;
+            border-radius: 4px;
+        }
+
+        .controls {
+            display: flex;
+            gap: 15px;
+            align-items: center;
+            flex-wrap: wrap;
+        }
+
+        .btn {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            border: none;
+            padding: 12px 24px;
+            border-radius: 8px;
+            font-size: 1rem;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            font-weight: 500;
+        }
+
+        .btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 6px 20px rgba(102, 126, 234, 0.4);
+        }
+
+        .btn:disabled {
+            background: #6c757d;
+            cursor: not-allowed;
+            transform: none;
+            box-shadow: none;
+        }
+
+        .btn-secondary {
+            background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+        }
+
+        .btn-success {
+            background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);
+        }
+
+        .progress-section {
+            margin-top: 30px;
+            padding: 20px;
+            background: #f8f9fa;
+            border-radius: 10px;
+            display: none;
+        }
+
+        .progress-section.active {
+            display: block;
+        }
+
+        .progress-bar {
+            width: 100%;
+            height: 8px;
+            background: #e9ecef;
+            border-radius: 4px;
+            overflow: hidden;
+            margin-bottom: 10px;
+        }
+
+        .progress-fill {
+            height: 100%;
+            background: linear-gradient(90deg, #667eea, #764ba2);
+            width: 0%;
+            transition: width 0.3s ease;
+        }
+
+        .status-message {
+            color: #495057;
+            font-size: 1rem;
+            margin-bottom: 10px;
+        }
+
+        .test-log {
+            background: #2d3748;
+            color: #e2e8f0;
+            padding: 15px;
+            border-radius: 8px;
+            font-family: 'Courier New', monospace;
+            font-size: 0.9rem;
+            max-height: 300px;
+            overflow-y: auto;
+            white-space: pre-wrap;
+        }
+
+        .results-section {
+            margin-top: 30px;
+            padding: 20px;
+            background: #f8f9fa;
+            border-radius: 10px;
+            display: none;
+        }
+
+        .results-section.active {
+            display: block;
+        }
+
+        .results-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 20px;
+            margin-top: 20px;
+        }
+
+        .result-card {
+            background: white;
+            border-radius: 8px;
+            padding: 20px;
+            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+        }
+
+        .result-card h3 {
+            color: #2c3e50;
+            margin-bottom: 15px;
+            font-size: 1.2rem;
+        }
+
+        .metric {
+            display: flex;
+            justify-content: space-between;
+            margin-bottom: 10px;
+            padding-bottom: 8px;
+            border-bottom: 1px solid #e9ecef;
+        }
+
+        .metric:last-child {
+            border-bottom: none;
+            margin-bottom: 0;
+        }
+
+        .metric-label {
+            color: #6c757d;
+            font-weight: 500;
+        }
+
+        .metric-value {
+            color: #2c3e50;
+            font-weight: bold;
+        }
+
+        .score-high { color: #28a745; }
+        .score-medium { color: #ffc107; }
+        .score-low { color: #dc3545; }
+
+        .game-section {
+            margin-top: 30px;
+            padding: 20px;
+            background: #f8f9fa;
+            border-radius: 10px;
+            display: none;
+        }
+
+        .game-section.active {
+            display: block;
+        }
+
+        .game-frame {
+            width: 100%;
+            height: 600px;
+            border: none;
+            border-radius: 8px;
+            background: white;
+        }
+
+        @media (max-width: 768px) {
+            .container {
+                padding: 20px;
+            }
+            
+            .model-grid {
+                grid-template-columns: 1fr;
+            }
+            
+            .controls {
+                flex-direction: column;
+                align-items: stretch;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Model Testing Framework</h1>
+        <p class="subtitle">Comprehensive evaluation of AI models for the Cloze Reader application</p>
+
+        <div class="model-selection">
+            <h2>Select Models to Test</h2>
+            <div id="modelGrid" class="model-grid">
+                <!-- Models will be populated by JavaScript -->
+            </div>
+            
+            <div class="controls">
+                <button id="selectAllBtn" class="btn btn-secondary">Select All</button>
+                <button id="clearAllBtn" class="btn btn-secondary">Clear All</button>
+                <button id="startTestBtn" class="btn">Start Comprehensive Test</button>
+                <button id="testGameBtn" class="btn btn-success">Test Selected Model in Game</button>
+            </div>
+        </div>
+
+        <div id="progressSection" class="progress-section">
+            <h2>Testing Progress</h2>
+            <div class="progress-bar">
+                <div id="progressFill" class="progress-fill"></div>
+            </div>
+            <div id="statusMessage" class="status-message">Initializing tests...</div>
+            <div id="testLog" class="test-log"></div>
+        </div>
+
+        <div id="resultsSection" class="results-section">
+            <h2>Test Results</h2>
+            <p>Results have been saved to the output folder as CSV files.</p>
+            <div id="resultsGrid" class="results-grid">
+                <!-- Results will be populated by JavaScript -->
+            </div>
+        </div>
+
+        <div id="gameSection" class="game-section">
+            <h2>Interactive Game Testing</h2>
+            <p>Test the selected model by playing the game. Performance will be logged for analysis.</p>
+            <iframe id="gameFrame" class="game-frame" src="about:blank"></iframe>
+        </div>
+    </div>
+
+    <script type="module">
+        import { ModelTestingFramework } from './src/modelTestingFramework.js';
+
+        class ModelTestingUI {
+            constructor() {
+                this.framework = new ModelTestingFramework();
+                this.selectedModels = new Set();
+                this.isTestingInProgress = false;
+                this.localServerStatus = null;
+                
+                this.initializeUI();
+                this.setupEventListeners();
+            }
+
+            async initializeUI() {
+                await this.checkLocalServer();
+                await this.populateModelGrid();
+            }
+
+            async checkLocalServer() {
+                this.localServerStatus = await this.framework.testLocalServerConnection();
+                if (this.localServerStatus.connected) {
+                    console.log('Local LM Studio server detected:', this.localServerStatus.models.length, 'models available');
+                    await this.framework.detectLocalModels();
+                } else {
+                    console.log('Local LM Studio server not available:', this.localServerStatus.error);
+                }
+            }
+
+            populateModelGrid() {
+                const grid = document.getElementById('modelGrid');
+                grid.innerHTML = '';
+
+                // Add local server status indicator
+                if (this.localServerStatus) {
+                    const statusDiv = document.createElement('div');
+                    statusDiv.className = 'server-status';
+                    statusDiv.style.cssText = `
+                        grid-column: 1 / -1;
+                        padding: 15px;
+                        margin-bottom: 15px;
+                        border-radius: 8px;
+                        font-weight: bold;
+                        text-align: center;
+                        ${this.localServerStatus.connected 
+                            ? 'background: #d4edda; color: #155724; border: 1px solid #c3e6cb;'
+                            : 'background: #f8d7da; color: #721c24; border: 1px solid #f5c6cb;'
+                        }
+                    `;
+                    
+                    if (this.localServerStatus.connected) {
+                        statusDiv.innerHTML = `
+                            ✓ Local LM Studio Server Connected (Port 1234)<br>
+                            <small>${this.localServerStatus.models.length} model(s) available</small>
+                        `;
+                    } else {
+                        statusDiv.innerHTML = `
+                            ✗ Local LM Studio Server Not Available<br>
+                            <small>Start LM Studio on port 1234 to test local models</small>
+                        `;
+                    }
+                    
+                    grid.appendChild(statusDiv);
+                }
+
+                this.framework.models.forEach(model => {
+                    const modelDiv = document.createElement('div');
+                    modelDiv.className = 'model-option';
+                    modelDiv.dataset.modelId = model.id;
+                    
+                    // Disable local models if server is not connected
+                    const isDisabled = model.provider === 'local' && !this.localServerStatus?.connected;
+                    if (isDisabled) {
+                        modelDiv.classList.add('disabled');
+                        modelDiv.style.opacity = '0.5';
+                        modelDiv.style.cursor = 'not-allowed';
+                    }
+                    
+                    const providerLabel = model.provider === 'local' 
+                        ? `LOCAL ${this.localServerStatus?.connected ? '(✓)' : '(✗)'}`
+                        : model.provider.toUpperCase();
+                    
+                    modelDiv.innerHTML = `
+                        <input type="checkbox" id="model-${model.id}" ${isDisabled ? 'disabled' : ''} />
+                        <div class="model-name">${model.name}</div>
+                        <div class="model-provider">${providerLabel}</div>
+                        <div class="model-id">${model.id}</div>
+                    `;
+                    
+                    const checkbox = modelDiv.querySelector('input');
+                    checkbox.addEventListener('change', (e) => {
+                        if (e.target.checked) {
+                            this.selectedModels.add(model);
+                            modelDiv.classList.add('selected');
+                        } else {
+                            this.selectedModels.delete(model);
+                            modelDiv.classList.remove('selected');
+                        }
+                        this.updateControlsState();
+                    });
+                    
+                    if (!isDisabled) {
+                        modelDiv.addEventListener('click', (e) => {
+                            if (e.target !== checkbox) {
+                                checkbox.click();
+                            }
+                        });
+                    }
+                    
+                    grid.appendChild(modelDiv);
+                });
+            }
+
+            setupEventListeners() {
+                document.getElementById('selectAllBtn').addEventListener('click', () => {
+                    this.selectAllModels();
+                });
+
+                document.getElementById('clearAllBtn').addEventListener('click', () => {
+                    this.clearAllModels();
+                });
+
+                document.getElementById('startTestBtn').addEventListener('click', () => {
+                    this.startComprehensiveTest();
+                });
+
+                document.getElementById('testGameBtn').addEventListener('click', () => {
+                    this.startGameTest();
+                });
+            }
+
+            selectAllModels() {
+                this.framework.models.forEach(model => {
+                    this.selectedModels.add(model);
+                    const modelDiv = document.querySelector(`[data-model-id="${model.id}"]`);
+                    const checkbox = modelDiv.querySelector('input');
+                    checkbox.checked = true;
+                    modelDiv.classList.add('selected');
+                });
+                this.updateControlsState();
+            }
+
+            clearAllModels() {
+                this.selectedModels.clear();
+                document.querySelectorAll('.model-option').forEach(div => {
+                    div.classList.remove('selected');
+                    div.querySelector('input').checked = false;
+                });
+                this.updateControlsState();
+            }
+
+            updateControlsState() {
+                const hasSelection = this.selectedModels.size > 0;
+                document.getElementById('startTestBtn').disabled = !hasSelection || this.isTestingInProgress;
+                document.getElementById('testGameBtn').disabled = this.selectedModels.size !== 1 || this.isTestingInProgress;
+            }
+
+            async startComprehensiveTest() {
+                if (this.selectedModels.size === 0) {
+                    alert('Please select at least one model to test.');
+                    return;
+                }
+
+                this.isTestingInProgress = true;
+                this.updateControlsState();
+                
+                const progressSection = document.getElementById('progressSection');
+                const progressFill = document.getElementById('progressFill');
+                const statusMessage = document.getElementById('statusMessage');
+                const testLog = document.getElementById('testLog');
+                
+                progressSection.classList.add('active');
+                testLog.textContent = '';
+                
+                const modelsArray = Array.from(this.selectedModels);
+                let completedTests = 0;
+                
+                try {
+                    for (let i = 0; i < modelsArray.length; i++) {
+                        const model = modelsArray[i];
+                        const progress = (i / modelsArray.length) * 100;
+                        
+                        progressFill.style.width = `${progress}%`;
+                        statusMessage.textContent = `Testing ${model.name} (${i + 1}/${modelsArray.length})...`;
+                        
+                        this.log(`Starting test for ${model.name}...`);
+                        
+                        try {
+                            const result = await this.framework.testModel(model);
+                            this.log(`✓ ${model.name} completed - Score: ${result.overallScore.toFixed(1)}`);
+                            completedTests++;
+                        } catch (error) {
+                            this.log(`✗ ${model.name} failed: ${error.message}`);
+                        }
+                        
+                        progressFill.style.width = `${((i + 1) / modelsArray.length) * 100}%`;
+                    }
+                    
+                    statusMessage.textContent = `Testing completed! ${completedTests}/${modelsArray.length} models tested successfully.`;
+                    this.log(`\\nTesting completed! Results saved to output folder.`);
+                    
+                    // Show results
+                    this.displayResults();
+                    
+                } catch (error) {
+                    this.log(`\\nTesting failed: ${error.message}`);
+                    statusMessage.textContent = 'Testing failed. Check the log for details.';
+                } finally {
+                    this.isTestingInProgress = false;
+                    this.updateControlsState();
+                }
+            }
+
+            startGameTest() {
+                if (this.selectedModels.size !== 1) {
+                    alert('Please select exactly one model for game testing.');
+                    return;
+                }
+
+                const selectedModel = Array.from(this.selectedModels)[0];
+                const gameSection = document.getElementById('gameSection');
+                const gameFrame = document.getElementById('gameFrame');
+                
+                // Construct URL with model parameter
+                const gameUrl = `index.html?testModel=${encodeURIComponent(selectedModel.id)}&testMode=true`;
+                if (selectedModel.provider === 'local') {
+                    gameUrl += '&local=true';
+                }
+                
+                gameFrame.src = gameUrl;
+                gameSection.classList.add('active');
+                
+                this.log(`Starting game test with ${selectedModel.name}...`);
+            }
+
+            displayResults() {
+                const resultsSection = document.getElementById('resultsSection');
+                const resultsGrid = document.getElementById('resultsGrid');
+                
+                resultsGrid.innerHTML = '';
+                
+                this.framework.testResults.tests.forEach(result => {
+                    const card = document.createElement('div');
+                    card.className = 'result-card';
+                    
+                    const overallScoreClass = this.getScoreClass(result.overallScore);
+                    
+                    card.innerHTML = `
+                        <h3>${result.modelName}</h3>
+                        <div class="metric">
+                            <span class="metric-label">Overall Score</span>
+                            <span class="metric-value ${overallScoreClass}">${result.overallScore?.toFixed(1) || 'N/A'}</span>
+                        </div>
+                        <div class="metric">
+                            <span class="metric-label">Word Selection Success</span>
+                            <span class="metric-value">${(result.wordSelection?.successRate * 100)?.toFixed(1) || 'N/A'}%</span>
+                        </div>
+                        <div class="metric">
+                            <span class="metric-label">Contextualization Success</span>
+                            <span class="metric-value">${(result.contextualization?.successRate * 100)?.toFixed(1) || 'N/A'}%</span>
+                        </div>
+                        <div class="metric">
+                            <span class="metric-label">Chat Hints Success</span>
+                            <span class="metric-value">${(result.chatHints?.successRate * 100)?.toFixed(1) || 'N/A'}%</span>
+                        </div>
+                        <div class="metric">
+                            <span class="metric-label">Average Response Time</span>
+                            <span class="metric-value">${result.wordSelection?.averageTime?.toFixed(0) || 'N/A'}ms</span>
+                        </div>
+                    `;
+                    
+                    resultsGrid.appendChild(card);
+                });
+                
+                resultsSection.classList.add('active');
+            }
+
+            getScoreClass(score) {
+                if (score >= 80) return 'score-high';
+                if (score >= 60) return 'score-medium';
+                return 'score-low';
+            }
+
+            log(message) {
+                const testLog = document.getElementById('testLog');
+                const timestamp = new Date().toLocaleTimeString();
+                testLog.textContent += `[${timestamp}] ${message}\\n`;
+                testLog.scrollTop = testLog.scrollHeight;
+            }
+        }
+
+        // Initialize the testing UI when the page loads
+        window.addEventListener('DOMContentLoaded', () => {
+            new ModelTestingUI();
+        });
+    </script>
+</body>
+</html>

src/aiService.js

@@ -4,12 +4,17 @@ class OpenRouterService {
     this.isLocalMode = this.checkLocalMode();
     this.apiUrl = this.isLocalMode ? 'http://localhost:1234/v1/chat/completions' : 'https://openrouter.ai/api/v1/chat/completions';
     this.apiKey = this.getApiKey();
-    this.model = this.isLocalMode ? 'gemma-3-12b' : 'google/gemma-3-27b-it:free';
+    
+    // Dual model configuration: Gemma-3-27b for hints/query-answering, Gemma-3-12b for everything else
+    this.hintModel = this.isLocalMode ? 'gemma-3-12b' : 'google/gemma-3-27b-it';
+    this.primaryModel = this.isLocalMode ? 'gemma-3-12b' : 'google/gemma-3-12b-it';
+    this.model = this.primaryModel; // Default model for backward compatibility
     
     console.log('AI Service initialized:', {
       mode: this.isLocalMode ? 'Local LLM' : 'OpenRouter',
       url: this.apiUrl,
-      model: this.model
+      primaryModel: this.primaryModel,
+      hintModel: this.hintModel
     });
   }
   
@@ -86,15 +91,18 @@ class OpenRouterService {
         method: 'POST',
         headers,
         body: JSON.stringify({
-          model: this.model,
+          model: this.hintModel,  // Use Gemma-3-27b for hints
           messages: [{
+            role: 'system',
+            content: 'You are a helpful assistant that provides hints for word puzzles. Never reveal the answer word directly.'
+          }, {
             role: 'user',
-            content: `You provide clues for word puzzles. You will be told the target word that players need to guess, but you must NEVER mention, spell, or reveal that word in your response. Follow the EXACT format requested. Be concise and direct about the target word without revealing it. Use plain text only - no bold, italics, asterisks, or markdown formatting. Stick to word limits.
-
-${prompt}`
+            content: prompt
           }],
-          max_tokens: 50,
-          temperature: 0.6
+          max_tokens: 150,
+          temperature: 0.7,
+          // Try to disable reasoning mode for hints
+          response_format: { type: "text" }
         })
       });
 
@@ -104,19 +112,73 @@ ${prompt}`
 
       const data = await response.json();
       
+      console.log('Hint API response:', JSON.stringify(data, null, 2));
+      
       // Check if data and choices exist before accessing
       if (!data || !data.choices || data.choices.length === 0) {
         console.error('Invalid API response structure:', data);
         return 'Unable to generate hint at this time';
       }
       
-      // Check if message content exists
-      if (!data.choices[0].message || !data.choices[0].message.content) {
-        console.error('No content in API response');
+      // Check if message exists
+      if (!data.choices[0].message) {
+        console.error('No message in API response');
         return 'Unable to generate hint at this time';
       }
       
-      let content = data.choices[0].message.content.trim();
+      // OSS-20B model returns content in 'reasoning' field when using reasoning mode
+      let content = data.choices[0].message.content || '';
+      
+      // If content is empty, check for reasoning field
+      if (!content && data.choices[0].message.reasoning) {
+        content = data.choices[0].message.reasoning;
+      }
+      
+      // Still no content? Check reasoning_details
+      if (!content && data.choices[0].message.reasoning_details?.length > 0) {
+        content = data.choices[0].message.reasoning_details[0].text;
+      }
+      
+      if (!content) {
+        console.error('No content found in hint response');
+        // Provide a generic hint based on the prompt type
+        if (prompt.toLowerCase().includes('synonym')) {
+          return 'Think of a word that means something similar';
+        } else if (prompt.toLowerCase().includes('definition')) {
+          return 'Consider what this word means in context';
+        } else if (prompt.toLowerCase().includes('category')) {
+          return 'Think about what type or category this word belongs to';
+        } else {
+          return 'Consider the context around the blank';
+        }
+      }
+      
+      content = content.trim();
+      
+      // For OSS-20B, extract hint from reasoning text if needed
+      if (content.includes('The user') || content.includes('We need to')) {
+        // This looks like reasoning text, try to extract the actual hint
+        // Look for text about synonyms, definitions, or clues
+        const hintPatterns = [
+          /synonym[s]?.*?(?:is|are|include[s]?|would be)\s+([^.]+)/i,
+          /means?\s+([^.]+)/i,
+          /refers? to\s+([^.]+)/i,
+          /describes?\s+([^.]+)/i,
+        ];
+        
+        for (const pattern of hintPatterns) {
+          const match = content.match(pattern);
+          if (match) {
+            content = match[1];
+            break;
+          }
+        }
+        
+        // If still has reasoning markers, just return a fallback
+        if (content.includes('The user') || content.includes('We need to')) {
+          return 'Think about words that mean something similar';
+        }
+      }
       
       // Clean up AI response artifacts  
       content = content
@@ -176,35 +238,20 @@ ${prompt}`
             'X-Title': 'Cloze Reader'
           },
           body: JSON.stringify({
-            model: this.model,
+            model: this.primaryModel,  // Use Gemma-3-12b for word selection
             messages: [{
+              role: 'system',
+              content: 'Select words for a cloze exercise. Return ONLY a JSON array of words, nothing else.'
+            }, {
               role: 'user',
-              content: `You are a cluemaster vocabulary selector for educational cloze exercises. Select exactly ${count} words from this passage for a cloze exercise.
-
-DIFFICULTY LEVEL ${level}:
-${difficultyGuidance}
-
-CLOZE DELETION PRINCIPLES:
-- Select words that require understanding context and vocabulary to identify
-- Choose words essential for comprehension that test language ability
-- Target words where deletion creates meaningful cognitive gaps
-
-REQUIREMENTS:
-- Choose clear, properly-spelled words (no OCR errors like "andsatires")
-- Select meaningful nouns, verbs, or adjectives (${wordLengthConstraint})
-- Words must appear EXACTLY as written in the passage
-- Avoid: capitalized words, ALL-CAPS words, function words, archaic terms, proper nouns, technical jargon
-- Skip any words that look malformed or concatenated
-- Avoid dated or potentially offensive terms
-- PREFER words from the middle portions of the passage when possible
-- If struggling to find ${count} perfect words, prioritize returning SOMETHING over returning nothing
-
-Return ONLY a JSON array of the selected words.
+              content: `Select ${count} ${level <= 2 ? 'easy' : level <= 4 ? 'medium' : 'challenging'} words (${wordLengthConstraint}) from this passage. Choose meaningful nouns, verbs, or adjectives. Avoid capitalized words and proper nouns.
 
 Passage: "${passage}"`
             }],
-            max_tokens: 100,
-            temperature: 0.3
+            max_tokens: 200,
+            temperature: 0.5,
+            // Try to disable reasoning mode for word selection
+            response_format: { type: "text" }
           })
         });
 
@@ -220,13 +267,35 @@ Passage: "${passage}"`
           throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
         }
         
+        // Log the full response to debug structure
+        console.log('Full API response:', JSON.stringify(data, null, 2));
+        
         // Check if response has expected structure
-        if (!data.choices || !data.choices[0] || !data.choices[0].message || !data.choices[0].message.content) {
+        if (!data.choices || !data.choices[0] || !data.choices[0].message) {
           console.error('Invalid word selection API response structure:', data);
-          throw new Error('API response missing expected content');
+          console.error('Choices[0]:', data.choices?.[0]);
+          throw new Error('API response missing expected structure');
         }
         
-        let content = data.choices[0].message.content.trim();
+        // OSS-20B model returns content in 'reasoning' field when using reasoning mode
+        let content = data.choices[0].message.content || '';
+        
+        // If content is empty, check for reasoning field
+        if (!content && data.choices[0].message.reasoning) {
+          content = data.choices[0].message.reasoning;
+        }
+        
+        // Still no content? Check reasoning_details
+        if (!content && data.choices[0].message.reasoning_details?.length > 0) {
+          content = data.choices[0].message.reasoning_details[0].text;
+        }
+        
+        if (!content) {
+          console.error('No content found in API response');
+          throw new Error('API response missing content');
+        }
+        
+        content = content.trim();
         
         // Clean up local LLM artifacts
         if (this.isLocalMode) {
@@ -237,33 +306,55 @@ Passage: "${passage}"`
         try {
           let words;
           
-          // For local LLM, try different parsing strategies
-          if (this.isLocalMode) {
-            // Try JSON parse first
-            try {
+          // Try to parse JSON first
+          try {
+            // Check if content contains JSON array anywhere in it
+            const jsonMatch = content.match(/\[[\s\S]*?\]/);
+            if (jsonMatch) {
+              words = JSON.parse(jsonMatch[0]);
+            } else {
               words = JSON.parse(content);
-            } catch {
-              // If not JSON, try comma-separated
+            }
+          } catch {
+            // If not JSON, check if this is reasoning text from OSS-20B
+            if (content.includes('pick') || content.includes('Let\'s')) {
+              // Extract words from reasoning text
+              // Look for quoted words or words after "pick"
+              const quotedWords = content.match(/"([^"]+)"/g);
+              if (quotedWords) {
+                words = quotedWords.map(w => w.replace(/"/g, ''));
+              } else {
+                // Look for pattern like "Let's pick 'word'" or "pick word"
+                const pickMatch = content.match(/pick\s+['"]?(\w+)['"]?/i);
+                if (pickMatch) {
+                  words = [pickMatch[1]];
+                } else {
+                  // For local LLM, try comma-separated
+                  if (this.isLocalMode && content.includes(',')) {
+                    words = content.split(',').map(w => w.trim());
+                  } else {
+                    // Single word
+                    words = [content.trim()];
+                  }
+                }
+              }
+            } else if (this.isLocalMode) {
+              // For local LLM, try comma-separated
               if (content.includes(',')) {
                 words = content.split(',').map(w => w.trim());
               } else {
                 // Single word
                 words = [content.trim()];
               }
+            } else {
+              throw new Error('Could not parse words from response');
             }
-          } else {
-            words = JSON.parse(content);
           }
           
           if (Array.isArray(words)) {
-            // Filter problematic words and validate word lengths based on level
-            const problematicWords = ['negro', 'retard', 'retarded', 'nigger', 'chinaman', 'jap', 'gypsy', 'savage', 'primitive', 'heathen'];
+            // Validate word lengths based on level
             const validWords = words.filter(word => {
               const cleanWord = word.replace(/[^a-zA-Z]/g, '');
-              const lowerWord = cleanWord.toLowerCase();
-              
-              // Skip problematic words
-              if (problematicWords.includes(lowerWord)) return false;
               
               // Check length constraints
               if (level <= 2) {
@@ -288,14 +379,9 @@ Passage: "${passage}"`
           const matches = content.match(/"([^"]+)"/g);
           if (matches) {
             const words = matches.map(m => m.replace(/"/g, ''));
-            // Filter problematic words and validate word lengths
-            const problematicWords = ['negro', 'retard', 'retarded', 'nigger', 'chinaman', 'jap', 'gypsy', 'savage', 'primitive', 'heathen'];
+            // Validate word lengths
             const validWords = words.filter(word => {
               const cleanWord = word.replace(/[^a-zA-Z]/g, '');
-              const lowerWord = cleanWord.toLowerCase();
-              
-              // Skip problematic words
-              if (problematicWords.includes(lowerWord)) return false;
               
               // Check length constraints
               if (level <= 2) {
@@ -368,45 +454,25 @@ Passage: "${passage}"`
         headers,
         signal: controller.signal,
         body: JSON.stringify({
-          model: this.model,
+          model: this.primaryModel,  // Use Gemma-3-12b for batch processing
           messages: [{
+            role: 'system',
+            content: 'Process passages for cloze exercises. Return ONLY a JSON object.'
+          }, {
             role: 'user',
-            content: `You process passages for cloze reading exercises. For each passage: 1) Select words for blanks, 2) Generate a contextual introduction. Return a JSON object with both passages' data.
+            content: `Select ${blanksPerPassage} ${level <= 2 ? 'easy' : level <= 4 ? 'medium' : 'challenging'} words (${wordLengthConstraint}) from each passage.
 
-DIFFICULTY LEVEL ${level}:
-${difficultyGuidance}
+Passage 1 ("${book1.title}" by ${book1.author}):
+${passage1}
 
-Process these two passages for cloze exercises:
+Passage 2 ("${book2.title}" by ${book2.author}):
+${passage2}
 
-PASSAGE 1:
-Title: "${book1.title}" by ${book1.author}
-Text: "${passage1}"
-Select ${blanksPerPassage} words for blanks.
-
-PASSAGE 2:
-Title: "${book2.title}" by ${book2.author}
-Text: "${passage2}"
-Select ${blanksPerPassage} words for blanks.
-
-SELECTION RULES:
-- Select EXACTLY ${blanksPerPassage} word${blanksPerPassage > 1 ? 's' : ''} per passage, no more, no less
-- Choose meaningful nouns, verbs, or adjectives (${wordLengthConstraint})
-- Avoid capitalized words, ALL-CAPS words, and table of contents entries
-- Avoid dated or potentially offensive terms
-- NEVER select words from the first or last sentence/clause of each passage
-- Choose words from the middle portions for better context dependency
-- Words must appear EXACTLY as written in the passage
-
-For each passage return:
-- "words": array of EXACTLY ${blanksPerPassage} selected word${blanksPerPassage > 1 ? 's' : ''} (exactly as they appear in the text)
-- "context": one-sentence intro about the book/author
-
-CRITICAL: The "words" array must contain exactly ${blanksPerPassage} element${blanksPerPassage > 1 ? 's' : ''} for each passage.
-
-Return as JSON: {"passage1": {...}, "passage2": {...}}`
+Return JSON: {"passage1": {"words": [${blanksPerPassage} words], "context": "one sentence about book"}, "passage2": {"words": [${blanksPerPassage} words], "context": "one sentence about book"}}`
           }],
           max_tokens: 800,
-          temperature: 0.5
+          temperature: 0.5,
+          response_format: { type: "text" }
         })
       });
 
@@ -425,13 +491,34 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
         throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
       }
       
+      console.log('Batch API response:', JSON.stringify(data, null, 2));
+      
       // Check if response has expected structure
-      if (!data.choices || !data.choices[0] || !data.choices[0].message || !data.choices[0].message.content) {
+      if (!data.choices || !data.choices[0] || !data.choices[0].message) {
         console.error('Invalid batch API response structure:', data);
-        throw new Error('API response missing expected content');
+        console.error('Choices[0]:', data.choices?.[0]);
+        throw new Error('API response missing expected structure');
+      }
+      
+      // OSS-20B model returns content in 'reasoning' field when using reasoning mode
+      let content = data.choices[0].message.content || '';
+      
+      // If content is empty, check for reasoning field
+      if (!content && data.choices[0].message.reasoning) {
+        content = data.choices[0].message.reasoning;
+      }
+      
+      // Still no content? Check reasoning_details
+      if (!content && data.choices[0].message.reasoning_details?.length > 0) {
+        content = data.choices[0].message.reasoning_details[0].text;
       }
       
-      const content = data.choices[0].message.content.trim();
+      if (!content) {
+        console.error('No content found in batch API response');
+        throw new Error('API response missing content');
+      }
+      
+      content = content.trim();
       
       try {
         // Try to extract JSON from the response
@@ -491,15 +578,10 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
         parsed.passage1.words = parsed.passage1.words.filter(word => word && word.trim() !== '');
         parsed.passage2.words = parsed.passage2.words.filter(word => word && word.trim() !== '');
         
-        // Filter problematic words and validate word lengths based on level
+        // Validate word lengths based on level
         const validateWords = (words, passageText) => {
-          const problematicWords = ['negro', 'retard', 'retarded', 'nigger', 'chinaman', 'jap', 'gypsy', 'savage', 'primitive', 'heathen'];
           return words.filter(word => {
             const cleanWord = word.replace(/[^a-zA-Z]/g, '');
-            const lowerWord = cleanWord.toLowerCase();
-            
-            // Skip problematic words
-            if (problematicWords.includes(lowerWord)) return false;
             
             // Check if word appears in all caps in the passage (like "VOLUME")
             if (passageText.includes(word.toUpperCase()) && word === word.toUpperCase()) {
@@ -609,13 +691,17 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
             'X-Title': 'Cloze Reader'
           },
           body: JSON.stringify({
-            model: this.model,
+            model: this.primaryModel,  // Use Gemma-3-12b for contextualization
             messages: [{
+              role: 'system',
+              content: 'Write one factual sentence about the given literary work.'
+            }, {
               role: 'user',
-              content: `You are a historical and literary expert of public domain entries in Project Gutenberg. Write one factual sentence about "${title}" by ${author}. Focus on what type of work it is, when it was written, or its historical significance. Be accurate and concise.`
+              content: `"${title}" by ${author}`
             }],
-            max_tokens: 80,
-            temperature: 0.2
+            max_tokens: 150,
+            temperature: 0.5,
+            response_format: { type: "text" }
           })
         });
 
@@ -633,13 +719,34 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
           throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
         }
         
+        console.log('Context API response:', JSON.stringify(data, null, 2));
+        
         // Check if response has expected structure
-        if (!data.choices || !data.choices[0] || !data.choices[0].message || !data.choices[0].message.content) {
+        if (!data.choices || !data.choices[0] || !data.choices[0].message) {
           console.error('Invalid contextualization API response structure:', data);
-          throw new Error('API response missing expected content');
+          console.error('Choices[0]:', data.choices?.[0]);
+          throw new Error('API response missing expected structure');
+        }
+        
+        // OSS-20B model returns content in 'reasoning' field when using reasoning mode
+        let content = data.choices[0].message.content || '';
+        
+        // If content is empty, check for reasoning field
+        if (!content && data.choices[0].message.reasoning) {
+          content = data.choices[0].message.reasoning;
+        }
+        
+        // Still no content? Check reasoning_details
+        if (!content && data.choices[0].message.reasoning_details?.length > 0) {
+          content = data.choices[0].message.reasoning_details[0].text;
+        }
+        
+        if (!content) {
+          console.error('No content found in context API response');
+          throw new Error('API response missing content');
         }
         
-        let content = data.choices[0].message.content.trim();
+        content = content.trim();
         
         // Clean up AI response artifacts
         content = content

src/app.js

@@ -72,7 +72,8 @@ class App {
 
     // Show level information
     const blanksCount = roundData.blanks.length;
-    const levelInfo = `Level ${this.game.currentLevel} • ${blanksCount} blank${blanksCount > 1 ? 's' : ''}`;
+    const passageNumber = this.game.currentPassageIndex + 1;
+    const levelInfo = `Level ${this.game.currentLevel} • Passage ${passageNumber}/2 • ${blanksCount} blank${blanksCount > 1 ? 's' : ''}`;
     
     this.elements.roundInfo.innerHTML = levelInfo;
 
@@ -155,22 +156,19 @@ class App {
   }
 
   displayResults(results) {
-    let message = `Score: ${results.correct}/${results.total} (${results.percentage}%)`;
-    
-    // Show "Required" information at all levels for consistency
-    message += ` - Required: ${results.requiredCorrect}/${results.total}`;
+    let message = `Score: ${results.correct}/${results.total}`;
     
     if (results.passed) {
       // Check if this completes the requirements for level advancement
       const roundsCompleted = this.game.roundsPassedAtCurrentLevel + 1; // +1 for this round
       if (roundsCompleted >= 2) {
-        message += ` - Excellent! Advancing to Level ${this.game.currentLevel + 1}! 🎉`;
+        message += ` ✓ Level ${this.game.currentLevel + 1} unlocked!`;
       } else {
-        message += ` - Great job! ${roundsCompleted}/2 rounds completed for Level ${this.game.currentLevel}`;
+        message += ` ✓ Passed (1 more round needed for next level)`;
       }
       this.elements.result.className = 'mt-4 text-center font-semibold text-green-600';
     } else {
-      message += ` - Need ${results.requiredCorrect} correct to advance. Keep practicing! 💪`;
+      message += ` - Try again (need ${results.requiredCorrect}/${results.total})`;
       this.elements.result.className = 'mt-4 text-center font-semibold text-red-600';
     }
     

src/clozeGameEngine.js

@@ -885,17 +885,17 @@ class ClozeGame {
     // Track successful rounds and advance level after 2 successful rounds
     if (roundPassed) {
       this.roundsPassedAtCurrentLevel++;
-      console.log(`Round passed! Total rounds passed at level ${this.currentLevel}: ${this.roundsPassedAtCurrentLevel}`);
+      console.log(`Round passed at level ${this.currentLevel}`);
       
       // Advance level after 2 successful rounds
       if (this.roundsPassedAtCurrentLevel >= 2) {
         this.currentLevel++;
         this.roundsPassedAtCurrentLevel = 0; // Reset counter for new level
-        console.log(`Advancing to level ${this.currentLevel} after 2 successful rounds`);
+        console.log(`Advanced to level ${this.currentLevel}`);
       }
     } else {
       // Failed round - do not reset the counter, user must accumulate 2 passes
-      console.log(`Round failed. Still need ${2 - this.roundsPassedAtCurrentLevel} more passed round(s) to advance from level ${this.currentLevel}`);
+      console.log(`Round not passed. Need ${2 - this.roundsPassedAtCurrentLevel} more round(s) to advance`);
     }
     
     // Clear chat conversations for new round

src/modelTestingFramework.js

@@ -0,0 +1,703 @@
+/**
+ * Comprehensive Model Testing Framework for Cloze Reader
+ * Tests all AI-powered features across different models
+ */
+
+class ModelTestingFramework {
+    constructor() {
+        this.models = [
+            // OpenRouter Models
+            { id: 'openai/gpt-4o', name: 'GPT-4o', provider: 'openrouter' },
+            { id: 'openai/gpt-4o-mini', name: 'GPT-4o Mini', provider: 'openrouter' },
+            { id: 'anthropic/claude-3.5-sonnet', name: 'Claude 3.5 Sonnet', provider: 'openrouter' },
+            { id: 'anthropic/claude-3-haiku', name: 'Claude 3 Haiku', provider: 'openrouter' },
+            { id: 'google/gemini-pro-1.5', name: 'Gemini Pro 1.5', provider: 'openrouter' },
+            { id: 'meta-llama/llama-3.1-8b-instruct', name: 'Llama 3.1 8B', provider: 'openrouter' },
+            { id: 'meta-llama/llama-3.1-70b-instruct', name: 'Llama 3.1 70B', provider: 'openrouter' },
+            { id: 'mistralai/mistral-7b-instruct', name: 'Mistral 7B', provider: 'openrouter' },
+            { id: 'microsoft/phi-3-medium-4k-instruct', name: 'Phi-3 Medium', provider: 'openrouter' },
+            { id: 'qwen/qwen-2-7b-instruct', name: 'Qwen 2 7B', provider: 'openrouter' },
+            
+            // Local LLM Models (LM Studio compatible)
+            { id: 'local-llm', name: 'Local LLM (Auto-detect)', provider: 'local' },
+            { id: 'gemma-3-12b', name: 'Gemma 3 12B (Local)', provider: 'local' },
+            { id: 'llama-3.1-8b', name: 'Llama 3.1 8B (Local)', provider: 'local' },
+            { id: 'mistral-7b', name: 'Mistral 7B (Local)', provider: 'local' },
+            { id: 'qwen-2-7b', name: 'Qwen 2 7B (Local)', provider: 'local' },
+            { id: 'phi-3-medium', name: 'Phi-3 Medium (Local)', provider: 'local' },
+            { id: 'custom-local', name: 'Custom Local Model', provider: 'local' }
+        ];
+        
+        this.testResults = {
+            timestamp: new Date().toISOString(),
+            tests: []
+        };
+        
+        this.testPassages = [
+            {
+                text: "The old man sat by the fireplace, reading his favorite book. The flames danced in the hearth, casting shadows on the walls. He turned each page carefully, savoring every word of the ancient tale.",
+                difficulty: 3,
+                expectedWords: ['favorite', 'flames', 'shadows', 'carefully', 'ancient']
+            },
+            {
+                text: "In the garden, colorful flowers bloomed under the warm sunshine. Bees buzzed from blossom to blossom, collecting nectar for their hive. The gardener watched with satisfaction as his hard work flourished.",
+                difficulty: 2,
+                expectedWords: ['colorful', 'warm', 'buzzed', 'collecting', 'satisfaction']
+            },
+            {
+                text: "The protagonist's journey through the labyrinthine corridors revealed the edifice's architectural complexity. Each ornate chamber contained mysterious artifacts that suggested an ancient civilization's sophisticated understanding of mathematics and astronomy.",
+                difficulty: 8,
+                expectedWords: ['labyrinthine', 'edifice', 'architectural', 'ornate', 'artifacts', 'civilization', 'sophisticated']
+            }
+        ];
+        
+        this.chatQuestions = [
+            { type: 'part_of_speech', prompt: 'What part of speech is this word?' },
+            { type: 'sentence_role', prompt: 'What role does this word play in the sentence?' },
+            { type: 'word_category', prompt: 'What category or type of word is this?' },
+            { type: 'synonym', prompt: 'Can you suggest a synonym for this word?' }
+        ];
+    }
+
+    async runComprehensiveTest(selectedModels = null) {
+        const modelsToTest = selectedModels || this.models;
+        console.log(`Starting comprehensive test of ${modelsToTest.length} models...`);
+        
+        for (const model of modelsToTest) {
+            console.log(`\nTesting model: ${model.name}`);
+            const modelResults = await this.testModel(model);
+            this.testResults.tests.push(modelResults);
+            
+            // Save intermediate results
+            await this.saveResults();
+        }
+        
+        console.log('\nAll tests completed!');
+        return this.testResults;
+    }
+
+    async testModel(model) {
+        const startTime = Date.now();
+        const results = {
+            modelId: model.id,
+            modelName: model.name,
+            provider: model.provider,
+            timestamp: new Date().toISOString(),
+            totalTime: 0,
+            wordSelection: {},
+            contextualization: {},
+            chatHints: {},
+            errorRates: {},
+            overallScore: 0
+        };
+
+        try {
+            // Test word selection across different difficulty levels
+            results.wordSelection = await this.testWordSelection(model);
+            
+            // Test contextualization
+            results.contextualization = await this.testContextualization(model);
+            
+            // Test chat hint generation
+            results.chatHints = await this.testChatHints(model);
+            
+            // Calculate overall metrics
+            results.totalTime = Date.now() - startTime;
+            results.overallScore = this.calculateOverallScore(results);
+            
+        } catch (error) {
+            console.error(`Error testing model ${model.name}:`, error);
+            results.error = error.message;
+            results.overallScore = 0;
+        }
+
+        return results;
+    }
+
+    async testWordSelection(model) {
+        const results = {
+            tests: [],
+            averageTime: 0,
+            successRate: 0,
+            qualityScore: 0,
+            difficultyAccuracy: 0
+        };
+
+        let totalTime = 0;
+        let successCount = 0;
+        let qualitySum = 0;
+        let difficultySum = 0;
+
+        for (const passage of this.testPassages) {
+            const testStart = Date.now();
+            
+            try {
+                const words = await this.performWordSelection(model, passage);
+                const testTime = Date.now() - testStart;
+                totalTime += testTime;
+                
+                const test = {
+                    passageLength: passage.text.length,
+                    targetDifficulty: passage.difficulty,
+                    responseTime: testTime,
+                    selectedWords: words,
+                    wordCount: words.length,
+                    success: words.length > 0,
+                    qualityScore: this.evaluateWordQuality(words, passage),
+                    difficultyScore: this.evaluateDifficultyMatch(words, passage.difficulty)
+                };
+                
+                results.tests.push(test);
+                
+                if (test.success) {
+                    successCount++;
+                    qualitySum += test.qualityScore;
+                    difficultySum += test.difficultyScore;
+                }
+                
+            } catch (error) {
+                results.tests.push({
+                    passageLength: passage.text.length,
+                    targetDifficulty: passage.difficulty,
+                    responseTime: Date.now() - testStart,
+                    error: error.message,
+                    success: false
+                });
+            }
+            
+            // Brief pause between tests
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+
+        results.averageTime = totalTime / this.testPassages.length;
+        results.successRate = successCount / this.testPassages.length;
+        results.qualityScore = successCount > 0 ? qualitySum / successCount : 0;
+        results.difficultyAccuracy = successCount > 0 ? difficultySum / successCount : 0;
+
+        return results;
+    }
+
+    async testContextualization(model) {
+        const results = {
+            tests: [],
+            averageTime: 0,
+            successRate: 0,
+            relevanceScore: 0
+        };
+
+        const testBooks = [
+            { title: 'Pride and Prejudice', author: 'Jane Austen' },
+            { title: 'The Adventures of Tom Sawyer', author: 'Mark Twain' },
+            { title: 'Moby Dick', author: 'Herman Melville' }
+        ];
+
+        let totalTime = 0;
+        let successCount = 0;
+        let relevanceSum = 0;
+
+        for (const book of testBooks) {
+            const testStart = Date.now();
+            
+            try {
+                const context = await this.performContextualization(model, book);
+                const testTime = Date.now() - testStart;
+                totalTime += testTime;
+                
+                const test = {
+                    bookTitle: book.title,
+                    author: book.author,
+                    responseTime: testTime,
+                    contextLength: context.length,
+                    success: context.length > 0,
+                    relevanceScore: this.evaluateContextRelevance(context, book)
+                };
+                
+                results.tests.push(test);
+                
+                if (test.success) {
+                    successCount++;
+                    relevanceSum += test.relevanceScore;
+                }
+                
+            } catch (error) {
+                results.tests.push({
+                    bookTitle: book.title,
+                    author: book.author,
+                    responseTime: Date.now() - testStart,
+                    error: error.message,
+                    success: false
+                });
+            }
+            
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+
+        results.averageTime = totalTime / testBooks.length;
+        results.successRate = successCount / testBooks.length;
+        results.relevanceScore = successCount > 0 ? relevanceSum / successCount : 0;
+
+        return results;
+    }
+
+    async testChatHints(model) {
+        const results = {
+            tests: [],
+            averageTime: 0,
+            successRate: 0,
+            helpfulnessScore: 0,
+            questionTypePerformance: {}
+        };
+
+        const testWords = [
+            { word: 'magnificent', sentence: 'The cathedral was truly magnificent.', difficulty: 5 },
+            { word: 'whispered', sentence: 'She whispered the secret to her friend.', difficulty: 3 },
+            { word: 'extraordinary', sentence: 'His performance was extraordinary.', difficulty: 7 }
+        ];
+
+        let totalTime = 0;
+        let successCount = 0;
+        let helpfulnessSum = 0;
+
+        // Initialize question type tracking
+        this.chatQuestions.forEach(q => {
+            results.questionTypePerformance[q.type] = {
+                tests: 0,
+                successes: 0,
+                averageScore: 0
+            };
+        });
+
+        for (const testWord of testWords) {
+            for (const question of this.chatQuestions) {
+                const testStart = Date.now();
+                
+                try {
+                    const hint = await this.performChatHint(model, testWord, question);
+                    const testTime = Date.now() - testStart;
+                    totalTime += testTime;
+                    
+                    const helpfulnessScore = this.evaluateHintHelpfulness(hint, testWord, question);
+                    
+                    const test = {
+                        word: testWord.word,
+                        questionType: question.type,
+                        difficulty: testWord.difficulty,
+                        responseTime: testTime,
+                        hintLength: hint.length,
+                        success: hint.length > 10, // Minimum meaningful response
+                        helpfulnessScore: helpfulnessScore
+                    };
+                    
+                    results.tests.push(test);
+                    
+                    // Update question type performance
+                    const qtPerf = results.questionTypePerformance[question.type];
+                    qtPerf.tests++;
+                    
+                    if (test.success) {
+                        successCount++;
+                        helpfulnessSum += helpfulnessScore;
+                        qtPerf.successes++;
+                        qtPerf.averageScore += helpfulnessScore;
+                    }
+                    
+                } catch (error) {
+                    results.tests.push({
+                        word: testWord.word,
+                        questionType: question.type,
+                        difficulty: testWord.difficulty,
+                        responseTime: Date.now() - testStart,
+                        error: error.message,
+                        success: false
+                    });
+                    
+                    results.questionTypePerformance[question.type].tests++;
+                }
+                
+                await new Promise(resolve => setTimeout(resolve, 500));
+            }
+        }
+
+        // Calculate averages for question types
+        Object.keys(results.questionTypePerformance).forEach(type => {
+            const perf = results.questionTypePerformance[type];
+            perf.successRate = perf.tests > 0 ? perf.successes / perf.tests : 0;
+            perf.averageScore = perf.successes > 0 ? perf.averageScore / perf.successes : 0;
+        });
+
+        const totalTests = testWords.length * this.chatQuestions.length;
+        results.averageTime = totalTime / totalTests;
+        results.successRate = successCount / totalTests;
+        results.helpfulnessScore = successCount > 0 ? helpfulnessSum / successCount : 0;
+
+        return results;
+    }
+
+    async performWordSelection(model, passage) {
+        // Create a temporary AI service instance for this model
+        const aiService = await this.createModelAIService(model);
+        
+        const prompt = `Select ${Math.min(3, Math.floor(passage.difficulty / 2) + 1)} appropriate words to remove from this passage for a cloze exercise at difficulty level ${passage.difficulty}:
+
+"${passage.text}"
+
+Return only a JSON array of words, like: ["word1", "word2", "word3"]`;
+
+        const response = await aiService.makeAIRequest(prompt);
+        
+        try {
+            return JSON.parse(response);
+        } catch {
+            // Try to extract words from non-JSON response
+            const matches = response.match(/\[.*?\]/);
+            if (matches) {
+                return JSON.parse(matches[0]);
+            }
+            return [];
+        }
+    }
+
+    async performContextualization(model, book) {
+        const aiService = await this.createModelAIService(model);
+        
+        const prompt = `Provide a brief historical and literary context for "${book.title}" by ${book.author}. Keep it concise and educational, suitable for language learners.`;
+
+        return await aiService.makeAIRequest(prompt);
+    }
+
+    async performChatHint(model, testWord, question) {
+        const aiService = await this.createModelAIService(model);
+        
+        const prompt = `You are helping a student understand a word in context. The word is "${testWord.word}" in the sentence: "${testWord.sentence}"
+
+${question.prompt}
+
+Provide a helpful hint without revealing the word directly. Keep your response concise and educational.`;
+
+        return await aiService.makeAIRequest(prompt);
+    }
+
+    async createModelAIService(model) {
+        // Use the testing AI service for better performance tracking
+        const { TestAIService } = await import('./testAIService.js');
+        
+        const config = {
+            modelId: model.id,
+            provider: model.provider,
+            isLocal: model.provider === 'local'
+        };
+        
+        return new TestAIService(config);
+    }
+
+    async detectLocalModels() {
+        // Attempt to detect available local models from LM Studio
+        try {
+            const response = await fetch('http://localhost:1234/v1/models');
+            if (response.ok) {
+                const data = await response.json();
+                const detectedModels = data.data.map(model => ({
+                    id: model.id,
+                    name: `${model.id} (Local)`,
+                    provider: 'local'
+                }));
+                
+                // Update the local models list
+                this.models = this.models.filter(m => m.provider !== 'local');
+                this.models.push(...detectedModels);
+                
+                return detectedModels;
+            }
+        } catch (error) {
+            console.log('No local LM Studio server detected on port 1234');
+        }
+        
+        // Return default local models if detection fails
+        return this.models.filter(m => m.provider === 'local');
+    }
+
+    async testLocalServerConnection() {
+        try {
+            const response = await fetch('http://localhost:1234/v1/models', {
+                method: 'GET',
+                headers: {
+                    'Content-Type': 'application/json'
+                }
+            });
+            
+            if (response.ok) {
+                const data = await response.json();
+                return {
+                    connected: true,
+                    models: data.data || [],
+                    serverInfo: data
+                };
+            } else {
+                return {
+                    connected: false,
+                    error: `HTTP ${response.status}: ${response.statusText}`
+                };
+            }
+        } catch (error) {
+            return {
+                connected: false,
+                error: error.message
+            };
+        }
+    }
+
+    evaluateWordQuality(words, passage) {
+        if (!words || words.length === 0) return 0;
+        
+        let score = 0;
+        const text = passage.text.toLowerCase();
+        
+        for (const word of words) {
+            const wordLower = word.toLowerCase();
+            
+            // Check if word exists in passage
+            if (text.includes(wordLower)) score += 20;
+            
+            // Check word length appropriateness
+            const expectedMinLength = Math.max(4, passage.difficulty);
+            const expectedMaxLength = Math.min(12, passage.difficulty + 6);
+            
+            if (word.length >= expectedMinLength && word.length <= expectedMaxLength) {
+                score += 15;
+            }
+            
+            // Avoid overly common words for higher difficulties
+            const commonWords = ['the', 'and', 'but', 'for', 'are', 'was', 'his', 'her'];
+            if (passage.difficulty > 5 && !commonWords.includes(wordLower)) {
+                score += 10;
+            }
+        }
+        
+        return Math.min(100, score / words.length);
+    }
+
+    evaluateDifficultyMatch(words, targetDifficulty) {
+        if (!words || words.length === 0) return 0;
+        
+        let score = 0;
+        
+        for (const word of words) {
+            const wordLength = word.length;
+            const expectedMin = Math.max(4, targetDifficulty);
+            const expectedMax = Math.min(14, targetDifficulty + 6);
+            
+            if (wordLength >= expectedMin && wordLength <= expectedMax) {
+                score += 100;
+            } else {
+                // Partial credit for close matches
+                const distance = Math.min(
+                    Math.abs(wordLength - expectedMin),
+                    Math.abs(wordLength - expectedMax)
+                );
+                score += Math.max(0, 100 - (distance * 20));
+            }
+        }
+        
+        return score / words.length;
+    }
+
+    evaluateContextRelevance(context, book) {
+        if (!context || context.length < 20) return 0;
+        
+        let score = 0;
+        const contextLower = context.toLowerCase();
+        
+        // Check for book title mention
+        if (contextLower.includes(book.title.toLowerCase())) score += 25;
+        
+        // Check for author mention
+        if (contextLower.includes(book.author.toLowerCase().split(' ').pop())) score += 25;
+        
+        // Check for literary/historical terms
+        const literaryTerms = ['novel', 'literature', 'author', 'published', 'century', 'period', 'style', 'theme'];
+        const foundTerms = literaryTerms.filter(term => contextLower.includes(term));
+        score += Math.min(30, foundTerms.length * 5);
+        
+        // Length appropriateness (100-500 chars is good)
+        if (context.length >= 100 && context.length <= 500) score += 20;
+        
+        return Math.min(100, score);
+    }
+
+    evaluateHintHelpfulness(hint, testWord, question) {
+        if (!hint || hint.length < 10) return 0;
+        
+        let score = 0;
+        const hintLower = hint.toLowerCase();
+        const wordLower = testWord.word.toLowerCase();
+        
+        // Penalize if the word is revealed directly
+        if (hintLower.includes(wordLower)) {
+            score -= 50;
+        }
+        
+        // Check for question-appropriate responses
+        switch (question.type) {
+            case 'part_of_speech':
+                const posTerms = ['noun', 'verb', 'adjective', 'adverb', 'pronoun'];
+                if (posTerms.some(term => hintLower.includes(term))) score += 40;
+                break;
+                
+            case 'sentence_role':
+                const roleTerms = ['subject', 'object', 'predicate', 'modifier', 'describes'];
+                if (roleTerms.some(term => hintLower.includes(term))) score += 40;
+                break;
+                
+            case 'word_category':
+                const categoryTerms = ['type', 'kind', 'category', 'group', 'family'];
+                if (categoryTerms.some(term => hintLower.includes(term))) score += 40;
+                break;
+                
+            case 'synonym':
+                const synonymTerms = ['similar', 'means', 'like', 'same as', 'equivalent'];
+                if (synonymTerms.some(term => hintLower.includes(term))) score += 40;
+                break;
+        }
+        
+        // Length appropriateness
+        if (hint.length >= 20 && hint.length <= 200) score += 30;
+        
+        // Educational tone
+        const educationalTerms = ['this word', 'in this context', 'here', 'sentence'];
+        if (educationalTerms.some(term => hintLower.includes(term))) score += 20;
+        
+        return Math.max(0, Math.min(100, score));
+    }
+
+    calculateOverallScore(results) {
+        const weights = {
+            wordSelection: 0.4,
+            contextualization: 0.3,
+            chatHints: 0.3
+        };
+        
+        let totalScore = 0;
+        
+        if (results.wordSelection.successRate !== undefined) {
+            totalScore += results.wordSelection.successRate * 40 * weights.wordSelection;
+        }
+        
+        if (results.contextualization.successRate !== undefined) {
+            totalScore += results.contextualization.successRate * 50 * weights.contextualization;
+        }
+        
+        if (results.chatHints.successRate !== undefined) {
+            totalScore += results.chatHints.successRate * 60 * weights.chatHints;
+        }
+        
+        // Bonus for consistent performance across all areas
+        const allAreas = [results.wordSelection, results.contextualization, results.chatHints];
+        const minSuccess = Math.min(...allAreas.map(area => area.successRate || 0));
+        if (minSuccess > 0.8) totalScore += 10;
+        
+        return Math.min(100, totalScore);
+    }
+
+    async saveResults() {
+        const csvContent = this.generateCSV();
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filename = `model_test_results_${timestamp}.csv`;
+        
+        // Browser environment - download file
+        this.downloadCSV(csvContent, filename);
+        
+        console.log(`Results saved as ${filename}`);
+        return filename;
+    }
+
+    downloadCSV(content, filename) {
+        const blob = new Blob([content], { type: 'text/csv' });
+        const url = URL.createObjectURL(blob);
+        
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }
+
+    generateCSV() {
+        const headers = [
+            'Model Name',
+            'Model ID', 
+            'Provider',
+            'Timestamp',
+            'Total Time (ms)',
+            'Overall Score',
+            'Word Selection Success Rate',
+            'Word Selection Avg Time (ms)',
+            'Word Selection Quality Score',
+            'Word Selection Difficulty Accuracy',
+            'Contextualization Success Rate',
+            'Contextualization Avg Time (ms)',
+            'Contextualization Relevance Score',
+            'Chat Hints Success Rate',
+            'Chat Hints Avg Time (ms)',
+            'Chat Hints Helpfulness Score',
+            'Part of Speech Success Rate',
+            'Sentence Role Success Rate',
+            'Word Category Success Rate',
+            'Synonym Success Rate',
+            'User Satisfaction Score',
+            'Word Selection User Rating',
+            'Passage Quality User Rating',
+            'Hint Helpfulness User Rating',
+            'Overall Experience User Rating',
+            'User Comments Count',
+            'Error Message'
+        ];
+
+        const rows = [headers.join(',')];
+
+        for (const test of this.testResults.tests) {
+            // Get user ranking data if available
+            const userRankings = test.userRankings || {};
+            const userSatisfaction = userRankings.overallUserSatisfaction || 0;
+            const avgRatings = userRankings.averageRatings || {};
+            const commentsCount = userRankings.comments?.length || 0;
+            
+            const row = [
+                `"${test.modelName}"`,
+                `"${test.modelId}"`,
+                `"${test.provider}"`,
+                `"${test.timestamp}"`,
+                test.totalTime || 0,
+                test.overallScore || 0,
+                test.wordSelection?.successRate || 0,
+                test.wordSelection?.averageTime || 0,
+                test.wordSelection?.qualityScore || 0,
+                test.wordSelection?.difficultyAccuracy || 0,
+                test.contextualization?.successRate || 0,
+                test.contextualization?.averageTime || 0,
+                test.contextualization?.relevanceScore || 0,
+                test.chatHints?.successRate || 0,
+                test.chatHints?.averageTime || 0,
+                test.chatHints?.helpfulnessScore || 0,
+                test.chatHints?.questionTypePerformance?.part_of_speech?.successRate || 0,
+                test.chatHints?.questionTypePerformance?.sentence_role?.successRate || 0,
+                test.chatHints?.questionTypePerformance?.word_category?.successRate || 0,
+                test.chatHints?.questionTypePerformance?.synonym?.successRate || 0,
+                userSatisfaction.toFixed(2),
+                avgRatings.word_selection?.toFixed(2) || 0,
+                avgRatings.passage_quality?.toFixed(2) || 0,
+                avgRatings.hint_helpfulness?.toFixed(2) || 0,
+                avgRatings.overall_experience?.toFixed(2) || 0,
+                commentsCount,
+                `"${test.error || ''}"`
+            ];
+            
+            rows.push(row.join(','));
+        }
+
+        return rows.join('\n');
+    }
+}
+
+export { ModelTestingFramework };

src/testAIService.js

@@ -0,0 +1,154 @@
+/**
+ * Testing-specific AI Service wrapper
+ * Extends the main AI service with testing capabilities
+ */
+
+class TestAIService {
+    constructor(config) {
+        this.modelId = config.modelId;
+        this.provider = config.provider;
+        this.isLocal = config.isLocal || config.provider === 'local';
+        this.baseUrl = this.isLocal ? 'http://localhost:1234' : 'https://openrouter.ai/api/v1';
+        this.apiKey = this.isLocal ? 'test-key' : this.getApiKey();
+        
+        // Performance tracking
+        this.requestCount = 0;
+        this.totalResponseTime = 0;
+        this.errorCount = 0;
+        this.lastError = null;
+    }
+
+    getApiKey() {
+        // Try to get API key from meta tag (injected by server)
+        const metaTag = document.querySelector('meta[name="openrouter-api-key"]');
+        if (metaTag) {
+            return metaTag.content;
+        }
+        
+        // Fallback to environment variable (for Node.js testing)
+        if (typeof process !== 'undefined' && process.env) {
+            return process.env.OPENROUTER_API_KEY;
+        }
+        
+        return null;
+    }
+
+    async makeAIRequest(prompt, options = {}) {
+        const startTime = Date.now();
+        this.requestCount++;
+        
+        try {
+            const response = await this.performRequest(prompt, options);
+            this.totalResponseTime += Date.now() - startTime;
+            return response;
+        } catch (error) {
+            this.errorCount++;
+            this.lastError = error;
+            this.totalResponseTime += Date.now() - startTime;
+            throw error;
+        }
+    }
+
+    async performRequest(prompt, options = {}) {
+        const requestBody = {
+            model: this.modelId,
+            messages: [
+                {
+                    role: "user",
+                    content: prompt
+                }
+            ],
+            max_tokens: options.maxTokens || 500,
+            temperature: options.temperature || 0.7,
+            top_p: options.topP || 0.9
+        };
+
+        const headers = {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`
+        };
+
+        if (!this.isLocal) {
+            headers['HTTP-Referer'] = window.location.origin;
+        }
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 second timeout
+
+        try {
+            const response = await fetch(`${this.baseUrl}/chat/completions`, {
+                method: 'POST',
+                headers: headers,
+                body: JSON.stringify(requestBody),
+                signal: controller.signal
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+
+            const data = await response.json();
+            
+            if (!data.choices || data.choices.length === 0) {
+                throw new Error('No response from AI service');
+            }
+
+            let content = data.choices[0].message.content;
+            
+            // Clean up local LLM response artifacts
+            if (this.isLocal) {
+                content = this.cleanLocalLLMResponse(content);
+            }
+
+            return content;
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') {
+                throw new Error('Request timeout');
+            }
+            throw error;
+        }
+    }
+
+    cleanLocalLLMResponse(content) {
+        // Remove common local LLM artifacts
+        content = content.replace(/^\[.*?\]\s*/, ''); // Remove leading brackets
+        content = content.replace(/\s*\[.*?\]$/, ''); // Remove trailing brackets
+        content = content.replace(/^"(.*)"$/, '$1'); // Remove surrounding quotes
+        content = content.replace(/\\n/g, '\n'); // Fix escaped newlines
+        content = content.replace(/\\"/g, '"'); // Fix escaped quotes
+        
+        return content.trim();
+    }
+
+    // Performance metrics
+    getAverageResponseTime() {
+        return this.requestCount > 0 ? this.totalResponseTime / this.requestCount : 0;
+    }
+
+    getErrorRate() {
+        return this.requestCount > 0 ? this.errorCount / this.requestCount : 0;
+    }
+
+    getPerformanceStats() {
+        return {
+            requestCount: this.requestCount,
+            totalResponseTime: this.totalResponseTime,
+            averageResponseTime: this.getAverageResponseTime(),
+            errorCount: this.errorCount,
+            errorRate: this.getErrorRate(),
+            lastError: this.lastError?.message || null
+        };
+    }
+
+    reset() {
+        this.requestCount = 0;
+        this.totalResponseTime = 0;
+        this.errorCount = 0;
+        this.lastError = null;
+    }
+}
+
+export { TestAIService };

src/testGameRunner.js

@@ -0,0 +1,473 @@
+/**
+ * Test Game Runner - Monitors and logs performance during game testing
+ */
+
+class TestGameRunner {
+    constructor(modelConfig) {
+        this.modelConfig = modelConfig;
+        this.sessionData = {
+            modelId: modelConfig.modelId,
+            modelName: modelConfig.modelName,
+            provider: modelConfig.provider,
+            startTime: Date.now(),
+            rounds: [],
+            interactions: [],
+            userRankings: [],
+            performance: {
+                wordSelectionRequests: 0,
+                wordSelectionSuccess: 0,
+                wordSelectionTime: 0,
+                contextualizationRequests: 0,
+                contextualizationSuccess: 0,
+                contextualizationTime: 0,
+                chatHintRequests: 0,
+                chatHintSuccess: 0,
+                chatHintTime: 0,
+                errors: []
+            }
+        };
+        
+        this.originalAIService = null;
+        this.setupInterception();
+    }
+
+    setupInterception() {
+        // Intercept AI service calls to track performance
+        if (window.aiService) {
+            this.originalAIService = window.aiService;
+            this.wrapAIService();
+        }
+        
+        // Monitor for game events
+        this.setupGameEventListeners();
+    }
+
+    wrapAIService() {
+        const testRunner = this;
+        
+        // Wrap the makeAIRequest method
+        const originalMakeAIRequest = this.originalAIService.makeAIRequest.bind(this.originalAIService);
+        
+        window.aiService.makeAIRequest = async function(prompt, options = {}) {
+            const startTime = Date.now();
+            const requestType = testRunner.classifyRequest(prompt);
+            
+            testRunner.logInteraction({
+                type: 'ai_request_start',
+                requestType: requestType,
+                prompt: prompt.substring(0, 200) + '...',
+                timestamp: Date.now()
+            });
+            
+            try {
+                const result = await originalMakeAIRequest(prompt, options);
+                const responseTime = Date.now() - startTime;
+                
+                testRunner.updatePerformanceMetrics(requestType, true, responseTime);
+                testRunner.logInteraction({
+                    type: 'ai_request_success',
+                    requestType: requestType,
+                    responseTime: responseTime,
+                    responseLength: result.length,
+                    timestamp: Date.now()
+                });
+                
+                return result;
+            } catch (error) {
+                const responseTime = Date.now() - startTime;
+                
+                testRunner.updatePerformanceMetrics(requestType, false, responseTime);
+                testRunner.logInteraction({
+                    type: 'ai_request_error',
+                    requestType: requestType,
+                    error: error.message,
+                    responseTime: responseTime,
+                    timestamp: Date.now()
+                });
+                
+                testRunner.sessionData.performance.errors.push({
+                    type: requestType,
+                    error: error.message,
+                    timestamp: Date.now()
+                });
+                
+                throw error;
+            }
+        };
+    }
+
+    classifyRequest(prompt) {
+        const promptLower = prompt.toLowerCase();
+        
+        if (promptLower.includes('select') && promptLower.includes('word')) {
+            return 'word_selection';
+        } else if (promptLower.includes('context') || promptLower.includes('background')) {
+            return 'contextualization';
+        } else if (promptLower.includes('hint') || promptLower.includes('help') || promptLower.includes('clue')) {
+            return 'chat_hint';
+        } else {
+            return 'other';
+        }
+    }
+
+    updatePerformanceMetrics(requestType, success, responseTime) {
+        const perf = this.sessionData.performance;
+        
+        switch (requestType) {
+            case 'word_selection':
+                perf.wordSelectionRequests++;
+                if (success) {
+                    perf.wordSelectionSuccess++;
+                    perf.wordSelectionTime += responseTime;
+                }
+                break;
+                
+            case 'contextualization':
+                perf.contextualizationRequests++;
+                if (success) {
+                    perf.contextualizationSuccess++;
+                    perf.contextualizationTime += responseTime;
+                }
+                break;
+                
+            case 'chat_hint':
+                perf.chatHintRequests++;
+                if (success) {
+                    perf.chatHintSuccess++;
+                    perf.chatHintTime += responseTime;
+                }
+                break;
+        }
+    }
+
+    setupGameEventListeners() {
+        // Listen for game-specific events
+        document.addEventListener('gameRoundStart', (event) => {
+            this.logInteraction({
+                type: 'round_start',
+                level: event.detail.level,
+                round: event.detail.round,
+                timestamp: Date.now()
+            });
+        });
+
+        document.addEventListener('gameRoundComplete', (event) => {
+            const roundData = {
+                level: event.detail.level,
+                round: event.detail.round,
+                score: event.detail.score,
+                correctAnswers: event.detail.correctAnswers,
+                totalBlanks: event.detail.totalBlanks,
+                timeSpent: event.detail.timeSpent,
+                timestamp: Date.now()
+            };
+            
+            this.sessionData.rounds.push(roundData);
+            
+            // Store the current round index for user ranking association
+            this.currentRoundIndex = this.sessionData.rounds.length - 1;
+            
+            this.logInteraction({
+                type: 'round_complete',
+                level: event.detail.level,
+                round: event.detail.round,
+                score: event.detail.score,
+                timestamp: Date.now()
+            });
+        });
+
+        document.addEventListener('userAnswer', (event) => {
+            this.logInteraction({
+                type: 'user_answer',
+                word: event.detail.targetWord,
+                userAnswer: event.detail.userAnswer,
+                correct: event.detail.correct,
+                timestamp: Date.now()
+            });
+        });
+
+        document.addEventListener('chatInteraction', (event) => {
+            this.logInteraction({
+                type: 'chat_interaction',
+                questionType: event.detail.questionType,
+                word: event.detail.word,
+                timestamp: Date.now()
+            });
+        });
+
+        // Listen for user ranking events
+        document.addEventListener('userRanking', (event) => {
+            const rankingData = {
+                ...event.detail,
+                roundIndex: this.currentRoundIndex,
+                roundDetails: this.sessionData.rounds[this.currentRoundIndex]
+            };
+            
+            this.sessionData.userRankings.push(rankingData);
+            
+            this.logInteraction({
+                type: 'user_ranking',
+                averageRating: event.detail.averageRating,
+                ratings: event.detail.ratings,
+                timestamp: Date.now()
+            });
+        });
+    }
+
+    logInteraction(interaction) {
+        this.sessionData.interactions.push(interaction);
+        
+        // Log to console for real-time monitoring
+        console.log(`[TestRunner] ${interaction.type}:`, interaction);
+    }
+
+    generateReport() {
+        const endTime = Date.now();
+        const totalTime = endTime - this.sessionData.startTime;
+        const perf = this.sessionData.performance;
+        
+        // Calculate user ranking summary
+        const userRankingSummary = this.calculateUserRankingSummary();
+        
+        const report = {
+            ...this.sessionData,
+            endTime: endTime,
+            totalSessionTime: totalTime,
+            summary: {
+                totalRounds: this.sessionData.rounds.length,
+                averageScore: this.sessionData.rounds.length > 0 
+                    ? this.sessionData.rounds.reduce((sum, round) => sum + round.score, 0) / this.sessionData.rounds.length 
+                    : 0,
+                wordSelectionSuccessRate: perf.wordSelectionRequests > 0 
+                    ? perf.wordSelectionSuccess / perf.wordSelectionRequests 
+                    : 0,
+                wordSelectionAvgTime: perf.wordSelectionSuccess > 0 
+                    ? perf.wordSelectionTime / perf.wordSelectionSuccess 
+                    : 0,
+                contextualizationSuccessRate: perf.contextualizationRequests > 0 
+                    ? perf.contextualizationSuccess / perf.contextualizationRequests 
+                    : 0,
+                contextualizationAvgTime: perf.contextualizationSuccess > 0 
+                    ? perf.contextualizationTime / perf.contextualizationSuccess 
+                    : 0,
+                chatHintSuccessRate: perf.chatHintRequests > 0 
+                    ? perf.chatHintSuccess / perf.chatHintRequests 
+                    : 0,
+                chatHintAvgTime: perf.chatHintSuccess > 0 
+                    ? perf.chatHintTime / perf.chatHintSuccess 
+                    : 0,
+                totalErrors: perf.errors.length,
+                userRankingSummary: userRankingSummary
+            }
+        };
+        
+        return report;
+    }
+
+    calculateUserRankingSummary() {
+        if (this.sessionData.userRankings.length === 0) {
+            return null;
+        }
+
+        const categories = ['word_selection', 'passage_quality', 'hint_helpfulness', 'overall_experience'];
+        const summary = {
+            totalRankings: this.sessionData.userRankings.length,
+            averageRatings: {},
+            categoryBreakdown: {},
+            comments: [],
+            overallUserSatisfaction: 0
+        };
+
+        // Calculate average ratings per category
+        categories.forEach(category => {
+            const ratings = this.sessionData.userRankings
+                .map(r => r.ratings[category])
+                .filter(r => r !== undefined);
+            
+            if (ratings.length > 0) {
+                summary.averageRatings[category] = 
+                    ratings.reduce((a, b) => a + b, 0) / ratings.length;
+                
+                // Distribution of ratings
+                summary.categoryBreakdown[category] = {
+                    1: ratings.filter(r => r === 1).length,
+                    2: ratings.filter(r => r === 2).length,
+                    3: ratings.filter(r => r === 3).length,
+                    4: ratings.filter(r => r === 4).length,
+                    5: ratings.filter(r => r === 5).length
+                };
+            }
+        });
+
+        // Calculate overall satisfaction
+        const allRatings = this.sessionData.userRankings
+            .map(r => r.averageRating)
+            .filter(r => r !== undefined);
+        
+        if (allRatings.length > 0) {
+            summary.overallUserSatisfaction = 
+                allRatings.reduce((a, b) => a + b, 0) / allRatings.length;
+        }
+
+        // Collect comments with context
+        summary.comments = this.sessionData.userRankings
+            .filter(r => r.comments)
+            .map(r => ({
+                timestamp: r.timestamp,
+                comment: r.comments,
+                averageRating: r.averageRating,
+                roundLevel: r.roundDetails?.level,
+                roundScore: r.roundDetails?.score
+            }));
+
+        return summary;
+    }
+
+    async saveReport() {
+        const report = this.generateReport();
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filename = `game_test_${this.modelConfig.modelId.replace(/[\/\\:]/g, '_')}_${timestamp}.json`;
+        
+        try {
+            // Try to save via browser download
+            this.downloadReport(report, filename);
+            
+            // Also try to save to output folder if possible (server-side)
+            await this.saveToServer(report, filename);
+            
+            console.log(`Test report saved: ${filename}`);
+            return filename;
+        } catch (error) {
+            console.error('Error saving test report:', error);
+            return null;
+        }
+    }
+
+    downloadReport(report, filename) {
+        const jsonString = JSON.stringify(report, null, 2);
+        const blob = new Blob([jsonString], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }
+
+    async saveToServer(report, filename) {
+        try {
+            const response = await fetch('/api/save-test-report', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    filename: filename,
+                    data: report
+                })
+            });
+            
+            if (!response.ok) {
+                throw new Error(`Server save failed: ${response.status}`);
+            }
+        } catch (error) {
+            console.log('Server save not available, using browser download only');
+        }
+    }
+
+    // Utility methods for analysis
+    getWordSelectionAnalytics() {
+        const wordSelectionInteractions = this.sessionData.interactions.filter(
+            i => i.type === 'ai_request_success' && i.requestType === 'word_selection'
+        );
+        
+        return {
+            count: wordSelectionInteractions.length,
+            averageResponseTime: wordSelectionInteractions.length > 0 
+                ? wordSelectionInteractions.reduce((sum, i) => sum + i.responseTime, 0) / wordSelectionInteractions.length 
+                : 0,
+            averageResponseLength: wordSelectionInteractions.length > 0 
+                ? wordSelectionInteractions.reduce((sum, i) => sum + i.responseLength, 0) / wordSelectionInteractions.length 
+                : 0
+        };
+    }
+
+    getChatHintAnalytics() {
+        const chatHintInteractions = this.sessionData.interactions.filter(
+            i => i.type === 'chat_interaction'
+        );
+        
+        const questionTypes = {};
+        chatHintInteractions.forEach(interaction => {
+            const type = interaction.questionType || 'unknown';
+            questionTypes[type] = (questionTypes[type] || 0) + 1;
+        });
+        
+        return {
+            totalHints: chatHintInteractions.length,
+            questionTypeBreakdown: questionTypes
+        };
+    }
+
+    getUserPerformanceAnalytics() {
+        const answerInteractions = this.sessionData.interactions.filter(
+            i => i.type === 'user_answer'
+        );
+        
+        const correctAnswers = answerInteractions.filter(i => i.correct).length;
+        
+        return {
+            totalAnswers: answerInteractions.length,
+            correctAnswers: correctAnswers,
+            accuracy: answerInteractions.length > 0 ? correctAnswers / answerInteractions.length : 0
+        };
+    }
+}
+
+// Initialize test runner if in test mode
+window.addEventListener('DOMContentLoaded', () => {
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.get('testMode') === 'true') {
+        const modelId = urlParams.get('testModel');
+        const isLocal = urlParams.get('local') === 'true';
+        
+        if (modelId) {
+            window.testGameRunner = new TestGameRunner({
+                modelId: modelId,
+                modelName: modelId,
+                provider: isLocal ? 'local' : 'openrouter'
+            });
+            
+            console.log('Test Game Runner initialized for model:', modelId);
+            
+            // Add end session button
+            const endButton = document.createElement('button');
+            endButton.textContent = 'End Test Session';
+            endButton.style.cssText = `
+                position: fixed;
+                top: 10px;
+                right: 10px;
+                z-index: 1000;
+                padding: 10px 15px;
+                background: #dc3545;
+                color: white;
+                border: none;
+                border-radius: 5px;
+                cursor: pointer;
+            `;
+            
+            endButton.addEventListener('click', async () => {
+                const filename = await window.testGameRunner.saveReport();
+                alert(`Test session ended. Report saved as: ${filename}`);
+                window.close();
+            });
+            
+            document.body.appendChild(endButton);
+        }
+    }
+});
+
+export { TestGameRunner };

src/testReportGenerator.js

@@ -0,0 +1,453 @@
+/**
+ * Comprehensive Test Report Generator
+ * Analyzes test results and generates detailed reports
+ */
+
+class TestReportGenerator {
+    constructor() {
+        this.reportTemplates = {
+            summary: this.generateSummaryReport.bind(this),
+            detailed: this.generateDetailedReport.bind(this),
+            comparison: this.generateComparisonReport.bind(this),
+            performance: this.generatePerformanceReport.bind(this),
+            markdown: this.generateMarkdownReport.bind(this)
+        };
+    }
+
+    async generateAllReports(testResults, outputFormat = 'all') {
+        const reports = {};
+        
+        if (outputFormat === 'all' || outputFormat === 'summary') {
+            reports.summary = this.generateSummaryReport(testResults);
+        }
+        
+        if (outputFormat === 'all' || outputFormat === 'detailed') {
+            reports.detailed = this.generateDetailedReport(testResults);
+        }
+        
+        if (outputFormat === 'all' || outputFormat === 'comparison') {
+            reports.comparison = this.generateComparisonReport(testResults);
+        }
+        
+        if (outputFormat === 'all' || outputFormat === 'performance') {
+            reports.performance = this.generatePerformanceReport(testResults);
+        }
+        
+        if (outputFormat === 'all' || outputFormat === 'markdown') {
+            reports.markdown = this.generateMarkdownReport(testResults);
+        }
+        
+        return reports;
+    }
+
+    generateSummaryReport(testResults) {
+        const summary = {
+            testOverview: {
+                timestamp: testResults.timestamp,
+                totalModels: testResults.tests.length,
+                testDuration: this.calculateTotalTestDuration(testResults.tests),
+                successfulTests: testResults.tests.filter(t => !t.error).length
+            },
+            topPerformers: this.getTopPerformers(testResults.tests),
+            categoryAverages: this.calculateCategoryAverages(testResults.tests),
+            recommendations: this.generateRecommendations(testResults.tests)
+        };
+        
+        return summary;
+    }
+
+    generateDetailedReport(testResults) {
+        const detailed = {
+            testMetadata: {
+                timestamp: testResults.timestamp,
+                totalModels: testResults.tests.length,
+                testFrameworkVersion: '1.0.0'
+            },
+            modelResults: testResults.tests.map(test => ({
+                modelInfo: {
+                    id: test.modelId,
+                    name: test.modelName,
+                    provider: test.provider
+                },
+                overallPerformance: {
+                    score: test.overallScore,
+                    totalTime: test.totalTime,
+                    rank: this.calculateRank(test, testResults.tests)
+                },
+                wordSelection: this.analyzeWordSelection(test.wordSelection),
+                contextualization: this.analyzeContextualization(test.contextualization),
+                chatHints: this.analyzeChatHints(test.chatHints),
+                errorAnalysis: this.analyzeErrors(test)
+            }))
+        };
+        
+        return detailed;
+    }
+
+    generateComparisonReport(testResults) {
+        const validTests = testResults.tests.filter(t => !t.error);
+        
+        const comparison = {
+            modelComparison: this.createModelComparisonMatrix(validTests),
+            providerAnalysis: this.analyzeByProvider(validTests),
+            performanceMetrics: {
+                wordSelection: this.compareWordSelectionMetrics(validTests),
+                contextualization: this.compareContextualizationMetrics(validTests),
+                chatHints: this.compareChatHintMetrics(validTests),
+                responseTime: this.compareResponseTimes(validTests)
+            },
+            recommendations: {
+                bestOverall: this.getBestOverallModel(validTests),
+                bestForWordSelection: this.getBestForTask(validTests, 'wordSelection'),
+                bestForContextualization: this.getBestForTask(validTests, 'contextualization'),
+                bestForChatHints: this.getBestForTask(validTests, 'chatHints'),
+                fastestResponse: this.getFastestModel(validTests),
+                mostReliable: this.getMostReliableModel(validTests)
+            }
+        };
+        
+        return comparison;
+    }
+
+    generatePerformanceReport(testResults) {
+        const performance = {
+            responseTimeAnalysis: this.analyzeResponseTimes(testResults.tests),
+            successRateAnalysis: this.analyzeSuccessRates(testResults.tests),
+            qualityMetrics: this.analyzeQualityMetrics(testResults.tests),
+            scalabilityInsights: this.analyzeScalability(testResults.tests),
+            reliabilityMetrics: this.analyzeReliability(testResults.tests)
+        };
+        
+        return performance;
+    }
+
+    generateMarkdownReport(testResults) {
+        const summary = this.generateSummaryReport(testResults);
+        const comparison = this.generateComparisonReport(testResults);
+        
+        let markdown = `# Cloze Reader Model Testing Report\n\n`;
+        markdown += `**Generated:** ${new Date().toLocaleString()}\n`;
+        markdown += `**Test Timestamp:** ${testResults.timestamp}\n`;
+        markdown += `**Models Tested:** ${testResults.tests.length}\n\n`;
+        
+        // Executive Summary
+        markdown += `## Executive Summary\n\n`;
+        markdown += `- **Successful Tests:** ${summary.testOverview.successfulTests}/${summary.testOverview.totalModels}\n`;
+        markdown += `- **Best Overall Model:** ${comparison.recommendations.bestOverall.name} (${comparison.recommendations.bestOverall.score.toFixed(1)}/100)\n`;
+        markdown += `- **Average Response Time:** ${this.formatTime(this.calculateAverageResponseTime(testResults.tests))}\n\n`;
+        
+        // Top Performers
+        markdown += `## Top Performers\n\n`;
+        markdown += `| Rank | Model | Score | Provider |\n`;
+        markdown += `|------|-------|-------|----------|\n`;
+        summary.topPerformers.forEach((model, index) => {
+            markdown += `| ${index + 1} | ${model.name} | ${model.score.toFixed(1)} | ${model.provider} |\n`;
+        });
+        markdown += `\n`;
+        
+        // Performance by Category
+        markdown += `## Performance by Category\n\n`;
+        markdown += `### Word Selection\n`;
+        markdown += `- **Best:** ${comparison.recommendations.bestForWordSelection.name} (${(comparison.recommendations.bestForWordSelection.successRate * 100).toFixed(1)}% success rate)\n`;
+        markdown += `- **Average Success Rate:** ${(summary.categoryAverages.wordSelection.successRate * 100).toFixed(1)}%\n`;
+        markdown += `- **Average Response Time:** ${this.formatTime(summary.categoryAverages.wordSelection.averageTime)}\n\n`;
+        
+        markdown += `### Contextualization\n`;
+        markdown += `- **Best:** ${comparison.recommendations.bestForContextualization.name} (${(comparison.recommendations.bestForContextualization.successRate * 100).toFixed(1)}% success rate)\n`;
+        markdown += `- **Average Success Rate:** ${(summary.categoryAverages.contextualization.successRate * 100).toFixed(1)}%\n`;
+        markdown += `- **Average Response Time:** ${this.formatTime(summary.categoryAverages.contextualization.averageTime)}\n\n`;
+        
+        markdown += `### Chat Hints\n`;
+        markdown += `- **Best:** ${comparison.recommendations.bestForChatHints.name} (${(comparison.recommendations.bestForChatHints.successRate * 100).toFixed(1)}% success rate)\n`;
+        markdown += `- **Average Success Rate:** ${(summary.categoryAverages.chatHints.successRate * 100).toFixed(1)}%\n`;
+        markdown += `- **Average Response Time:** ${this.formatTime(summary.categoryAverages.chatHints.averageTime)}\n\n`;
+        
+        // Add user rankings section if available
+        const hasUserRankings = testResults.tests.some(t => t.userRankings?.totalRankings > 0);
+        if (hasUserRankings) {
+            markdown += `## User Satisfaction Ratings\n\n`;
+            markdown += `| Model | Overall Satisfaction | Word Selection | Passage Quality | Hint Helpfulness | Overall Experience |\n`;
+            markdown += `|-------|---------------------|----------------|-----------------|------------------|--------------------|\n`;
+            
+            testResults.tests.forEach(test => {
+                if (test.userRankings?.totalRankings > 0) {
+                    const ur = test.userRankings;
+                    const avg = ur.averageRatings || {};
+                    markdown += `| ${test.modelName} | ${ur.overallUserSatisfaction.toFixed(1)}/5 | ${(avg.word_selection || 0).toFixed(1)} | ${(avg.passage_quality || 0).toFixed(1)} | ${(avg.hint_helpfulness || 0).toFixed(1)} | ${(avg.overall_experience || 0).toFixed(1)} |\n`;
+                }
+            });
+            markdown += `\n`;
+            
+            // Add user comments if any
+            const allComments = testResults.tests
+                .filter(t => t.userRankings?.comments?.length > 0)
+                .flatMap(t => t.userRankings.comments.map(c => ({ ...c, model: t.modelName })));
+            
+            if (allComments.length > 0) {
+                markdown += `### User Comments\n\n`;
+                allComments.forEach(comment => {
+                    markdown += `- **${comment.model}** (Rating: ${comment.averageRating.toFixed(1)}): "${comment.comment}"\n`;
+                });
+                markdown += `\n`;
+            }
+        }
+        
+        // Detailed Results
+        markdown += `## Detailed Results\n\n`;
+        testResults.tests.forEach(test => {
+            if (!test.error) {
+                markdown += `### ${test.modelName}\n`;
+                markdown += `- **Provider:** ${test.provider}\n`;
+                markdown += `- **Overall Score:** ${test.overallScore.toFixed(1)}/100\n`;
+                markdown += `- **Total Time:** ${this.formatTime(test.totalTime)}\n`;
+                markdown += `- **Word Selection:** ${(test.wordSelection?.successRate * 100 || 0).toFixed(1)}% success\n`;
+                markdown += `- **Contextualization:** ${(test.contextualization?.successRate * 100 || 0).toFixed(1)}% success\n`;
+                markdown += `- **Chat Hints:** ${(test.chatHints?.successRate * 100 || 0).toFixed(1)}% success\n\n`;
+            }
+        });
+        
+        // Recommendations
+        markdown += `## Recommendations\n\n`;
+        summary.recommendations.forEach(rec => {
+            markdown += `- ${rec}\n`;
+        });
+        
+        return markdown;
+    }
+
+    // Helper methods for analysis
+    calculateTotalTestDuration(tests) {
+        return tests.reduce((total, test) => total + (test.totalTime || 0), 0);
+    }
+
+    getTopPerformers(tests, limit = 5) {
+        return tests
+            .filter(t => !t.error && t.overallScore)
+            .sort((a, b) => b.overallScore - a.overallScore)
+            .slice(0, limit)
+            .map(test => ({
+                name: test.modelName,
+                score: test.overallScore,
+                provider: test.provider
+            }));
+    }
+
+    calculateCategoryAverages(tests) {
+        const validTests = tests.filter(t => !t.error);
+        
+        return {
+            wordSelection: this.calculateCategoryAverage(validTests, 'wordSelection'),
+            contextualization: this.calculateCategoryAverage(validTests, 'contextualization'),
+            chatHints: this.calculateCategoryAverage(validTests, 'chatHints')
+        };
+    }
+
+    calculateCategoryAverage(tests, category) {
+        const validCategoryTests = tests.filter(t => t[category]);
+        
+        if (validCategoryTests.length === 0) {
+            return { successRate: 0, averageTime: 0, qualityScore: 0 };
+        }
+        
+        return {
+            successRate: validCategoryTests.reduce((sum, t) => sum + (t[category].successRate || 0), 0) / validCategoryTests.length,
+            averageTime: validCategoryTests.reduce((sum, t) => sum + (t[category].averageTime || 0), 0) / validCategoryTests.length,
+            qualityScore: validCategoryTests.reduce((sum, t) => sum + (t[category].qualityScore || t[category].relevanceScore || t[category].helpfulnessScore || 0), 0) / validCategoryTests.length
+        };
+    }
+
+    generateRecommendations(tests) {
+        const recommendations = [];
+        const validTests = tests.filter(t => !t.error);
+        
+        if (validTests.length === 0) {
+            return ['No successful tests to generate recommendations.'];
+        }
+        
+        const bestOverall = validTests.reduce((best, test) => 
+            test.overallScore > best.overallScore ? test : best
+        );
+        
+        recommendations.push(`For overall best performance, use ${bestOverall.modelName} (${bestOverall.provider})`);
+        
+        // Provider-specific recommendations
+        const providerPerformance = this.analyzeByProvider(validTests);
+        const bestProvider = Object.keys(providerPerformance)
+            .reduce((best, provider) => 
+                providerPerformance[provider].averageScore > providerPerformance[best]?.averageScore ? provider : best
+            );
+        
+        recommendations.push(`${bestProvider} models show the best average performance`);
+        
+        // Speed vs quality trade-offs
+        const fastestGoodModel = validTests
+            .filter(t => t.overallScore > 70)
+            .sort((a, b) => a.totalTime - b.totalTime)[0];
+        
+        if (fastestGoodModel) {
+            recommendations.push(`For fastest good performance, consider ${fastestGoodModel.modelName}`);
+        }
+        
+        return recommendations;
+    }
+
+    analyzeByProvider(tests) {
+        const providerGroups = {};
+        
+        tests.forEach(test => {
+            if (!providerGroups[test.provider]) {
+                providerGroups[test.provider] = [];
+            }
+            providerGroups[test.provider].push(test);
+        });
+        
+        const analysis = {};
+        Object.keys(providerGroups).forEach(provider => {
+            const providerTests = providerGroups[provider];
+            analysis[provider] = {
+                count: providerTests.length,
+                averageScore: providerTests.reduce((sum, t) => sum + t.overallScore, 0) / providerTests.length,
+                averageTime: providerTests.reduce((sum, t) => sum + t.totalTime, 0) / providerTests.length,
+                successRate: providerTests.filter(t => !t.error).length / providerTests.length
+            };
+        });
+        
+        return analysis;
+    }
+
+    getBestOverallModel(tests) {
+        return tests.reduce((best, test) => 
+            test.overallScore > best.overallScore ? {
+                name: test.modelName,
+                score: test.overallScore,
+                provider: test.provider
+            } : best
+        , { name: '', score: 0, provider: '' });
+    }
+
+    getBestForTask(tests, taskName) {
+        const validTests = tests.filter(t => t[taskName] && t[taskName].successRate !== undefined);
+        
+        if (validTests.length === 0) {
+            return { name: 'N/A', successRate: 0, provider: '' };
+        }
+        
+        return validTests.reduce((best, test) => 
+            test[taskName].successRate > best.successRate ? {
+                name: test.modelName,
+                successRate: test[taskName].successRate,
+                provider: test.provider
+            } : best
+        , { name: '', successRate: 0, provider: '' });
+    }
+
+    getFastestModel(tests) {
+        return tests.reduce((fastest, test) => 
+            test.totalTime < fastest.time ? {
+                name: test.modelName,
+                time: test.totalTime,
+                provider: test.provider
+            } : fastest
+        , { name: '', time: Infinity, provider: '' });
+    }
+
+    getMostReliableModel(tests) {
+        // Model with fewest errors and highest success rates across all tasks
+        const reliability = tests.map(test => {
+            const wordSelectionReliability = test.wordSelection?.successRate || 0;
+            const contextualizationReliability = test.contextualization?.successRate || 0;
+            const chatHintReliability = test.chatHints?.successRate || 0;
+            
+            const overallReliability = (wordSelectionReliability + contextualizationReliability + chatHintReliability) / 3;
+            
+            return {
+                name: test.modelName,
+                reliability: overallReliability,
+                provider: test.provider
+            };
+        });
+        
+        return reliability.reduce((most, test) => 
+            test.reliability > most.reliability ? test : most
+        , { name: '', reliability: 0, provider: '' });
+    }
+
+    calculateAverageResponseTime(tests) {
+        const validTests = tests.filter(t => t.totalTime);
+        return validTests.reduce((sum, t) => sum + t.totalTime, 0) / validTests.length;
+    }
+
+    formatTime(milliseconds) {
+        if (milliseconds < 1000) {
+            return `${milliseconds.toFixed(0)}ms`;
+        } else if (milliseconds < 60000) {
+            return `${(milliseconds / 1000).toFixed(1)}s`;
+        } else {
+            return `${(milliseconds / 60000).toFixed(1)}m`;
+        }
+    }
+
+    async saveReports(reports, baseFilename) {
+        const savedFiles = [];
+        
+        for (const [type, content] of Object.entries(reports)) {
+            const filename = `${baseFilename}_${type}`;
+            let fileContent, extension;
+            
+            if (type === 'markdown') {
+                fileContent = content;
+                extension = '.md';
+            } else {
+                fileContent = JSON.stringify(content, null, 2);
+                extension = '.json';
+            }
+            
+            try {
+                await this.saveFile(`${filename}${extension}`, fileContent);
+                savedFiles.push(`${filename}${extension}`);
+            } catch (error) {
+                console.error(`Error saving ${filename}:`, error);
+            }
+        }
+        
+        return savedFiles;
+    }
+
+    async saveFile(filename, content) {
+        // Try to save via browser download
+        const blob = new Blob([content], { 
+            type: filename.endsWith('.md') ? 'text/markdown' : 'application/json' 
+        });
+        const url = URL.createObjectURL(blob);
+        
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }
+
+    // Stub methods for detailed analysis (implement as needed)
+    analyzeWordSelection(data) { return data; }
+    analyzeContextualization(data) { return data; }
+    analyzeChatHints(data) { return data; }
+    analyzeErrors(test) { return test.error ? [test.error] : []; }
+    calculateRank(test, allTests) { 
+        const sorted = allTests.filter(t => !t.error).sort((a, b) => b.overallScore - a.overallScore);
+        return sorted.findIndex(t => t.modelId === test.modelId) + 1;
+    }
+    createModelComparisonMatrix(tests) { return {}; }
+    compareWordSelectionMetrics(tests) { return {}; }
+    compareContextualizationMetrics(tests) { return {}; }
+    compareChatHintMetrics(tests) { return {}; }
+    compareResponseTimes(tests) { return {}; }
+    analyzeResponseTimes(tests) { return {}; }
+    analyzeSuccessRates(tests) { return {}; }
+    analyzeQualityMetrics(tests) { return {}; }
+    analyzeScalability(tests) { return {}; }
+    analyzeReliability(tests) { return {}; }
+}
+
+export { TestReportGenerator };

src/userRankingInterface.js

@@ -0,0 +1,650 @@
+/**
+ * User Ranking Interface for Model Testing
+ * Allows users to rate model performance on each task during gameplay
+ */
+
+class UserRankingInterface {
+    constructor() {
+        this.rankings = {
+            rounds: [],
+            currentRound: null
+        };
+        
+        this.rankingCategories = [
+            {
+                id: 'word_selection',
+                name: 'Word Selection Quality',
+                description: 'How appropriate were the selected words for this difficulty level?',
+                criteria: [
+                    'Words match the difficulty level',
+                    'Vocabulary is challenging but fair',
+                    'Selected words are meaningful in context'
+                ]
+            },
+            {
+                id: 'passage_quality',
+                name: 'Passage Selection',
+                description: 'How suitable was this passage for language learning?',
+                criteria: [
+                    'Text is engaging and appropriate',
+                    'Content is educational',
+                    'Difficulty matches the level'
+                ]
+            },
+            {
+                id: 'hint_helpfulness',
+                name: 'Hint Quality',
+                description: 'How helpful were the AI-generated hints?',
+                criteria: [
+                    'Hints guide without revealing answers',
+                    'Explanations are clear and educational',
+                    'Responses are contextually appropriate'
+                ]
+            },
+            {
+                id: 'overall_experience',
+                name: 'Overall Round Experience',
+                description: 'How was the overall quality of this round?',
+                criteria: [
+                    'Smooth gameplay experience',
+                    'AI responses were timely',
+                    'Educational value was high'
+                ]
+            }
+        ];
+        
+        this.createRankingUI();
+        this.setupEventListeners();
+    }
+
+    createRankingUI() {
+        // Create ranking modal
+        const modal = document.createElement('div');
+        modal.id = 'ranking-modal';
+        modal.className = 'ranking-modal';
+        modal.innerHTML = `
+            <div class="ranking-modal-content">
+                <h2>Rate This Round</h2>
+                <p class="ranking-subtitle">Help us improve by rating the AI's performance</p>
+                
+                <div id="ranking-categories" class="ranking-categories">
+                    <!-- Categories will be populated dynamically -->
+                </div>
+                
+                <div class="ranking-comments">
+                    <label for="ranking-comments-input">Additional Comments (Optional):</label>
+                    <textarea id="ranking-comments-input" rows="3" placeholder="Any specific feedback about this round..."></textarea>
+                </div>
+                
+                <div class="ranking-actions">
+                    <button id="skip-ranking-btn" class="btn-secondary">Skip</button>
+                    <button id="submit-ranking-btn" class="btn-primary" disabled>Submit Rating</button>
+                </div>
+            </div>
+        `;
+        
+        // Create ranking trigger button
+        const triggerButton = document.createElement('button');
+        triggerButton.id = 'ranking-trigger-btn';
+        triggerButton.className = 'ranking-trigger-btn';
+        triggerButton.innerHTML = '⭐ Rate Round';
+        triggerButton.style.cssText = `
+            position: fixed;
+            bottom: 20px;
+            left: 20px;
+            z-index: 999;
+            padding: 10px 20px;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            border: none;
+            border-radius: 25px;
+            cursor: pointer;
+            font-size: 14px;
+            font-weight: bold;
+            box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
+            transition: all 0.3s ease;
+            display: none;
+        `;
+        
+        // Add styles
+        const styles = document.createElement('style');
+        styles.textContent = `
+            .ranking-modal {
+                display: none;
+                position: fixed;
+                top: 0;
+                left: 0;
+                width: 100%;
+                height: 100%;
+                background: rgba(0, 0, 0, 0.5);
+                z-index: 1000;
+                backdrop-filter: blur(5px);
+            }
+            
+            .ranking-modal.active {
+                display: flex;
+                align-items: center;
+                justify-content: center;
+            }
+            
+            .ranking-modal-content {
+                background: white;
+                border-radius: 15px;
+                padding: 30px;
+                max-width: 600px;
+                width: 90%;
+                max-height: 80vh;
+                overflow-y: auto;
+                box-shadow: 0 10px 40px rgba(0, 0, 0, 0.3);
+            }
+            
+            .ranking-modal-content h2 {
+                color: #2c3e50;
+                margin-bottom: 10px;
+                text-align: center;
+            }
+            
+            .ranking-subtitle {
+                color: #7f8c8d;
+                text-align: center;
+                margin-bottom: 30px;
+            }
+            
+            .ranking-category {
+                margin-bottom: 25px;
+                padding: 20px;
+                background: #f8f9fa;
+                border-radius: 10px;
+                border: 2px solid #e9ecef;
+            }
+            
+            .ranking-category h3 {
+                color: #2c3e50;
+                margin-bottom: 8px;
+                font-size: 1.1rem;
+            }
+            
+            .ranking-category-description {
+                color: #6c757d;
+                font-size: 0.9rem;
+                margin-bottom: 15px;
+            }
+            
+            .ranking-criteria {
+                font-size: 0.85rem;
+                color: #6c757d;
+                margin-bottom: 15px;
+                padding-left: 20px;
+            }
+            
+            .ranking-criteria li {
+                margin-bottom: 5px;
+            }
+            
+            .ranking-stars {
+                display: flex;
+                gap: 10px;
+                justify-content: center;
+                margin-top: 10px;
+            }
+            
+            .ranking-star {
+                font-size: 30px;
+                color: #ddd;
+                cursor: pointer;
+                transition: all 0.2s ease;
+            }
+            
+            .ranking-star:hover,
+            .ranking-star.hover {
+                color: #ffd700;
+                transform: scale(1.1);
+            }
+            
+            .ranking-star.selected {
+                color: #ffd700;
+            }
+            
+            .ranking-comments {
+                margin: 20px 0;
+            }
+            
+            .ranking-comments label {
+                display: block;
+                color: #2c3e50;
+                margin-bottom: 8px;
+                font-weight: 500;
+            }
+            
+            .ranking-comments textarea {
+                width: 100%;
+                padding: 10px;
+                border: 2px solid #e9ecef;
+                border-radius: 8px;
+                font-family: inherit;
+                resize: vertical;
+            }
+            
+            .ranking-actions {
+                display: flex;
+                gap: 15px;
+                justify-content: flex-end;
+                margin-top: 20px;
+            }
+            
+            .btn-primary, .btn-secondary {
+                padding: 10px 24px;
+                border: none;
+                border-radius: 8px;
+                font-size: 1rem;
+                cursor: pointer;
+                transition: all 0.3s ease;
+                font-weight: 500;
+            }
+            
+            .btn-primary {
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                color: white;
+            }
+            
+            .btn-primary:hover:not(:disabled) {
+                transform: translateY(-2px);
+                box-shadow: 0 6px 20px rgba(102, 126, 234, 0.4);
+            }
+            
+            .btn-primary:disabled {
+                background: #6c757d;
+                cursor: not-allowed;
+            }
+            
+            .btn-secondary {
+                background: #e9ecef;
+                color: #495057;
+            }
+            
+            .btn-secondary:hover {
+                background: #dee2e6;
+            }
+            
+            .ranking-trigger-btn:hover {
+                transform: translateY(-2px) scale(1.05);
+                box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);
+            }
+            
+            @media (max-width: 600px) {
+                .ranking-modal-content {
+                    padding: 20px;
+                }
+                
+                .ranking-star {
+                    font-size: 24px;
+                }
+                
+                .ranking-trigger-btn {
+                    bottom: 70px;
+                    padding: 8px 16px;
+                    font-size: 12px;
+                }
+            }
+        `;
+        
+        document.head.appendChild(styles);
+        document.body.appendChild(modal);
+        document.body.appendChild(triggerButton);
+        
+        this.populateCategories();
+    }
+
+    populateCategories() {
+        const container = document.getElementById('ranking-categories');
+        container.innerHTML = '';
+        
+        this.rankingCategories.forEach(category => {
+            const categoryDiv = document.createElement('div');
+            categoryDiv.className = 'ranking-category';
+            categoryDiv.dataset.categoryId = category.id;
+            
+            const criteriaHtml = category.criteria.map(c => `<li>${c}</li>`).join('');
+            
+            categoryDiv.innerHTML = `
+                <h3>${category.name}</h3>
+                <p class="ranking-category-description">${category.description}</p>
+                <ul class="ranking-criteria">${criteriaHtml}</ul>
+                <div class="ranking-stars" data-category="${category.id}">
+                    ${[1, 2, 3, 4, 5].map(i => 
+                        `<span class="ranking-star" data-rating="${i}">★</span>`
+                    ).join('')}
+                </div>
+            `;
+            
+            container.appendChild(categoryDiv);
+        });
+        
+        // Setup star interactions
+        this.setupStarInteractions();
+    }
+
+    setupStarInteractions() {
+        const starContainers = document.querySelectorAll('.ranking-stars');
+        
+        starContainers.forEach(container => {
+            const stars = container.querySelectorAll('.ranking-star');
+            const categoryId = container.dataset.category;
+            
+            stars.forEach((star, index) => {
+                star.addEventListener('mouseenter', () => {
+                    this.highlightStars(stars, index + 1);
+                });
+                
+                star.addEventListener('click', () => {
+                    this.selectRating(categoryId, index + 1);
+                    this.markStarsAsSelected(stars, index + 1);
+                    this.updateSubmitButton();
+                });
+            });
+            
+            container.addEventListener('mouseleave', () => {
+                const currentRating = this.getCurrentRating(categoryId);
+                if (currentRating > 0) {
+                    this.markStarsAsSelected(stars, currentRating);
+                } else {
+                    this.highlightStars(stars, 0);
+                }
+            });
+        });
+    }
+
+    highlightStars(stars, count) {
+        stars.forEach((star, index) => {
+            if (index < count) {
+                star.classList.add('hover');
+            } else {
+                star.classList.remove('hover');
+            }
+        });
+    }
+
+    markStarsAsSelected(stars, count) {
+        stars.forEach((star, index) => {
+            if (index < count) {
+                star.classList.add('selected');
+                star.classList.remove('hover');
+            } else {
+                star.classList.remove('selected');
+                star.classList.remove('hover');
+            }
+        });
+    }
+
+    selectRating(categoryId, rating) {
+        if (!this.currentRound) {
+            this.currentRound = {
+                timestamp: Date.now(),
+                ratings: {},
+                comments: ''
+            };
+        }
+        
+        this.currentRound.ratings[categoryId] = rating;
+    }
+
+    getCurrentRating(categoryId) {
+        return this.currentRound?.ratings[categoryId] || 0;
+    }
+
+    setupEventListeners() {
+        const modal = document.getElementById('ranking-modal');
+        const triggerBtn = document.getElementById('ranking-trigger-btn');
+        const skipBtn = document.getElementById('skip-ranking-btn');
+        const submitBtn = document.getElementById('submit-ranking-btn');
+        const commentsInput = document.getElementById('ranking-comments-input');
+        
+        // Show modal
+        triggerBtn.addEventListener('click', () => {
+            this.showRankingModal();
+        });
+        
+        // Skip ranking
+        skipBtn.addEventListener('click', () => {
+            this.hideRankingModal();
+            this.currentRound = null;
+        });
+        
+        // Submit ranking
+        submitBtn.addEventListener('click', () => {
+            this.submitRanking();
+        });
+        
+        // Update comments
+        commentsInput.addEventListener('input', (e) => {
+            if (this.currentRound) {
+                this.currentRound.comments = e.target.value;
+            }
+        });
+        
+        // Close modal on background click
+        modal.addEventListener('click', (e) => {
+            if (e.target === modal) {
+                this.hideRankingModal();
+            }
+        });
+        
+        // Listen for round completion events
+        document.addEventListener('gameRoundComplete', (event) => {
+            this.onRoundComplete(event.detail);
+        });
+    }
+
+    updateSubmitButton() {
+        const submitBtn = document.getElementById('submit-ranking-btn');
+        const allRated = this.rankingCategories.every(category => 
+            this.getCurrentRating(category.id) > 0
+        );
+        
+        submitBtn.disabled = !allRated;
+    }
+
+    showRankingModal() {
+        const modal = document.getElementById('ranking-modal');
+        modal.classList.add('active');
+        
+        // Reset current round if needed
+        if (!this.currentRound) {
+            this.currentRound = {
+                timestamp: Date.now(),
+                ratings: {},
+                comments: ''
+            };
+        }
+        
+        // Clear previous selections
+        this.resetUI();
+    }
+
+    hideRankingModal() {
+        const modal = document.getElementById('ranking-modal');
+        modal.classList.remove('active');
+    }
+
+    resetUI() {
+        // Clear all star selections
+        document.querySelectorAll('.ranking-star').forEach(star => {
+            star.classList.remove('selected', 'hover');
+        });
+        
+        // Clear comments
+        document.getElementById('ranking-comments-input').value = '';
+        
+        // Disable submit button
+        document.getElementById('submit-ranking-btn').disabled = true;
+    }
+
+    submitRanking() {
+        if (!this.currentRound) return;
+        
+        // Add metadata
+        this.currentRound.submittedAt = Date.now();
+        this.currentRound.modelId = window.testGameRunner?.modelConfig?.modelId || 'unknown';
+        
+        // Calculate average rating
+        const ratings = Object.values(this.currentRound.ratings);
+        this.currentRound.averageRating = ratings.reduce((a, b) => a + b, 0) / ratings.length;
+        
+        // Save ranking
+        this.rankings.rounds.push(this.currentRound);
+        
+        // Dispatch event for test runner
+        document.dispatchEvent(new CustomEvent('userRanking', {
+            detail: this.currentRound
+        }));
+        
+        // Show confirmation
+        this.showConfirmation();
+        
+        // Reset
+        this.hideRankingModal();
+        this.currentRound = null;
+        
+        console.log('Ranking submitted:', this.rankings);
+    }
+
+    showConfirmation() {
+        const confirmation = document.createElement('div');
+        confirmation.style.cssText = `
+            position: fixed;
+            bottom: 100px;
+            left: 50%;
+            transform: translateX(-50%);
+            background: #28a745;
+            color: white;
+            padding: 15px 30px;
+            border-radius: 8px;
+            box-shadow: 0 4px 15px rgba(40, 167, 69, 0.4);
+            z-index: 1001;
+            animation: slideInUp 0.3s ease;
+        `;
+        confirmation.textContent = '✓ Thank you for your feedback!';
+        
+        document.body.appendChild(confirmation);
+        
+        setTimeout(() => {
+            confirmation.style.animation = 'slideOutDown 0.3s ease';
+            setTimeout(() => confirmation.remove(), 300);
+        }, 2000);
+    }
+
+    onRoundComplete(roundDetails) {
+        // Store round details for context
+        if (!this.currentRound) {
+            this.currentRound = {
+                timestamp: Date.now(),
+                ratings: {},
+                comments: '',
+                roundDetails: roundDetails
+            };
+        } else {
+            this.currentRound.roundDetails = roundDetails;
+        }
+        
+        // Show ranking trigger button
+        const triggerBtn = document.getElementById('ranking-trigger-btn');
+        triggerBtn.style.display = 'block';
+        
+        // Auto-show modal after a short delay (optional)
+        if (window.testGameRunner?.modelConfig?.autoShowRanking) {
+            setTimeout(() => this.showRankingModal(), 1500);
+        }
+    }
+
+    exportRankings() {
+        const exportData = {
+            ...this.rankings,
+            exportedAt: new Date().toISOString(),
+            modelId: window.testGameRunner?.modelConfig?.modelId || 'unknown'
+        };
+        
+        return exportData;
+    }
+
+    getRankingSummary() {
+        if (this.rankings.rounds.length === 0) {
+            return null;
+        }
+        
+        const summary = {
+            totalRounds: this.rankings.rounds.length,
+            averageRatings: {},
+            categoryBreakdown: {},
+            comments: []
+        };
+        
+        // Calculate average ratings per category
+        this.rankingCategories.forEach(category => {
+            const ratings = this.rankings.rounds
+                .map(r => r.ratings[category.id])
+                .filter(r => r !== undefined);
+            
+            if (ratings.length > 0) {
+                summary.averageRatings[category.id] = 
+                    ratings.reduce((a, b) => a + b, 0) / ratings.length;
+                
+                // Distribution of ratings
+                summary.categoryBreakdown[category.id] = {
+                    1: ratings.filter(r => r === 1).length,
+                    2: ratings.filter(r => r === 2).length,
+                    3: ratings.filter(r => r === 3).length,
+                    4: ratings.filter(r => r === 4).length,
+                    5: ratings.filter(r => r === 5).length
+                };
+            }
+        });
+        
+        // Collect all comments
+        summary.comments = this.rankings.rounds
+            .filter(r => r.comments)
+            .map(r => ({
+                timestamp: r.timestamp,
+                comment: r.comments,
+                averageRating: r.averageRating
+            }));
+        
+        return summary;
+    }
+}
+
+// Initialize when in test mode
+window.addEventListener('DOMContentLoaded', () => {
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.get('testMode') === 'true') {
+        window.userRankingInterface = new UserRankingInterface();
+        
+        // Add CSS animation keyframes
+        const animationStyles = document.createElement('style');
+        animationStyles.textContent = `
+            @keyframes slideInUp {
+                from {
+                    transform: translate(-50%, 100%);
+                    opacity: 0;
+                }
+                to {
+                    transform: translate(-50%, 0);
+                    opacity: 1;
+                }
+            }
+            
+            @keyframes slideOutDown {
+                from {
+                    transform: translate(-50%, 0);
+                    opacity: 1;
+                }
+                to {
+                    transform: translate(-50%, 100%);
+                    opacity: 0;
+                }
+            }
+        `;
+        document.head.appendChild(animationStyles);
+    }
+});
+
+export { UserRankingInterface };

src/welcomeOverlay.js

@@ -43,7 +43,7 @@ class WelcomeOverlay {
       
       <div class="welcome-content">
         <p>
-          <strong>How to play:</strong> Read the passage, fill in the blanks, and use hints or chat help (💬) if needed. Progress through levels as you improve.
+          <strong>How to play:</strong> Fill in the blanks in each passage. Complete 2 passages per round. Pass 2 rounds to advance to the next level.
         </p>
         
         <p>
@@ -51,7 +51,7 @@ class WelcomeOverlay {
         </p>
         
         <p style="margin-bottom: 0;">
-          <strong>AI assistance:</strong> Powered by Google's Gemma 3 model via OpenRouter for intelligent word selection and contextual hints.
+          <strong>AI assistance:</strong> Powered by Google's Gemma models via OpenRouter - Gemma-3-27b for contextual hints and Gemma-3-12b for word selection and processing.
         </p>
       </div>
 

test-prompts-lm-studio.md

@@ -1,262 +0,0 @@
-# Gemma-3-27b Model Integration Guide for Cloze Reader
-
-## Part 1: Step-by-Step API Request Processing
-
-### 1. Initial Request Reception
-When the Cloze Reader application makes an API request through OpenRouter:
-
-1. **Authentication**: Verify Bearer token from `Authorization` header
-2. **Request Type Detection**: Identify the operation type based on prompt content
-3. **Parameter Extraction**: Parse temperature, max_tokens, and message content
-4. **Rate Limiting Check**: Ensure request complies with free tier limits
-
-### 2. Word Selection Request Processing
-
-**When Temperature = 0.3 and prompt contains "CLOZE DELETION PRINCIPLES":**
-
-1. **Parse Passage**: Extract the text passage from the system message
-2. **Identify Difficulty Level**: 
-   - Level 1-2: Target 4-7 letter words (easy vocabulary)
-   - Level 3-4: Target 4-10 letter words (medium difficulty)
-   - Level 5+: Target 5-14 letter words (challenging vocabulary)
-3. **Select Words**:
-   - Identify significant vocabulary words (nouns, verbs, adjectives, adverbs)
-   - Avoid proper nouns, numbers, articles, and function words
-   - Ensure words are contextually important for comprehension
-4. **Format Response**: Return JSON array of selected words
-5. **Validate**: Ensure all words exist in the original passage
-
-### 3. Batch Processing Request
-
-**When Temperature = 0.5 and prompt contains two passages:**
-
-1. **Parse Both Passages**: Extract passage1 and passage2 from the prompt
-2. **Process Each Passage**:
-   - Apply word selection logic for each based on difficulty level
-   - Generate one-sentence contextualization for each book
-3. **Format Response**: Return structured JSON with both passages' data
-4. **Ensure Consistency**: Words must match exactly as they appear in passages
-
-### 4. Contextualization Request
-
-**When Temperature = 0.2 and prompt asks for book context:**
-
-1. **Extract Book Information**: Parse title and author from prompt
-2. **Generate Context**: Create one factual sentence about:
-   - Type of work (novel, short story, essay)
-   - Historical period when written
-   - Literary significance or genre
-3. **Keep Concise**: Limit to 80 tokens maximum
-4. **Avoid Speculation**: Only include verifiable information
-
-### 5. Chat Hint Request
-
-**When Temperature = 0.6 and prompt includes "word puzzles":**
-
-1. **Identify Question Type**:
-   - `part_of_speech`: Grammar category identification
-   - `sentence_role`: Function in the sentence
-   - `word_category`: Abstract/concrete classification
-   - `synonym`: Alternative word suggestion
-2. **Parse Target Word**: Extract the hidden word (NEVER reveal it)
-3. **Generate Appropriate Hint**:
-   - Follow exact format requested
-   - Stay within 50 token limit
-   - Use plain text only, no formatting
-4. **Validate**: Ensure hint doesn't contain or spell out the target word
-
-### 6. Response Formatting Rules
-
-1. **JSON Responses**: 
-   - Word selection: Clean array format `["word1", "word2"]`
-   - Batch processing: Nested object structure
-   - No markdown code blocks unless specifically requested
-
-2. **Text Responses**:
-   - Contextualization: Single sentence, no formatting
-   - Chat hints: Plain text, follows exact format requested
-
-3. **Error Handling**:
-   - Invalid requests: Return graceful error messages
-   - Missing parameters: Use sensible defaults
-   - Malformed input: Attempt to parse intent
-
-## Part 2: LM Studio Testing Configuration
-
-### System Prompt
-```
-You are a specialized AI assistant for the Cloze Reader educational application. You help create vocabulary exercises by selecting appropriate words from text passages and providing contextual hints without revealing answers. Always respond in the exact format requested, using plain JSON or text as specified. Never use markdown formatting unless explicitly requested.
-```
-
-### Temperature Settings
-- **Word Selection**: 0.3
-- **Batch Processing**: 0.5
-- **Contextualization**: 0.2
-- **Chat Hints**: 0.6
-
-### Response Length Limits
-- **Word Selection**: 100 tokens
-- **Batch Processing**: 800 tokens
-- **Contextualization**: 80 tokens
-- **Chat Hints**: 50 tokens
-
-### Test Prompts
-
-#### 1. Word Selection Test (Level 1-2 Easy)
-```json
-{
-  "messages": [
-    {
-      "role": "system",
-      "content": "CLOZE DELETION PRINCIPLES:\n- Select words that require understanding context and vocabulary to identify\n- Choose words essential for comprehension that test language ability\n- Target words where deletion creates meaningful cognitive gaps\n\nFrom the following passage, select exactly 1 word that is important for reading comprehension.\n\nDifficulty level 1-2: Focus on easier vocabulary (4-7 letters) like common nouns, simple verbs, and basic adjectives.\n\nRETURN ONLY A JSON ARRAY OF YOUR SELECTED WORDS. Select words that appear EXACTLY as written in the passage.\n\nPassage:\nThe old woman lived in a small cottage by the forest. Every morning, she would walk to the village market to buy fresh bread."
-    }
-  ],
-  "temperature": 0.3,
-  "max_tokens": 100
-}
-```
-
-**Expected Output Schema:**
-```json
-{
-  "type": "array",
-  "items": {
-    "type": "string",
-    "minLength": 4,
-    "maxLength": 7
-  },
-  "minItems": 1,
-  "maxItems": 1
-}
-```
-
-#### 2. Batch Processing Test (Level 3-4 Medium)
-```json
-{
-  "messages": [
-    {
-      "role": "system",
-      "content": "Process these two passages for a cloze reading exercise:\n\nPASSAGE 1 (Pride and Prejudice by Jane Austen):\nIt is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife.\n\nPASSAGE 2 (A Tale of Two Cities by Charles Dickens):\nIt was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness.\n\nFor each passage:\n1. Select 1 word for difficulty level 3-4 (medium vocabulary, 4-10 letters)\n2. Write ONE sentence about the book/author\n\nReturn a JSON object with this structure:\n{\n  \"passage1\": {\n    \"words\": [selected words],\n    \"context\": \"One sentence about the book\"\n  },\n  \"passage2\": {\n    \"words\": [selected words],\n    \"context\": \"One sentence about the book\"\n  }\n}"
-    }
-  ],
-  "temperature": 0.5,
-  "max_tokens": 800
-}
-```
-
-**Expected Output Schema:**
-```json
-{
-  "type": "object",
-  "properties": {
-    "passage1": {
-      "type": "object",
-      "properties": {
-        "words": {
-          "type": "array",
-          "items": { "type": "string" },
-          "minItems": 1,
-          "maxItems": 1
-        },
-        "context": {
-          "type": "string",
-          "maxLength": 150
-        }
-      },
-      "required": ["words", "context"]
-    },
-    "passage2": {
-      "type": "object",
-      "properties": {
-        "words": {
-          "type": "array",
-          "items": { "type": "string" },
-          "minItems": 1,
-          "maxItems": 1
-        },
-        "context": {
-          "type": "string",
-          "maxLength": 150
-        }
-      },
-      "required": ["words", "context"]
-    }
-  },
-  "required": ["passage1", "passage2"]
-}
-```
-
-#### 3. Contextualization Test
-```json
-{
-  "messages": [
-    {
-      "role": "user",
-      "content": "Write one factual sentence about 'The Adventures of Sherlock Holmes' by Arthur Conan Doyle. Focus on what type of work it is, when it was written, or its historical significance. Keep it under 20 words and conversational."
-    }
-  ],
-  "temperature": 0.2,
-  "max_tokens": 80
-}
-```
-
-**Expected Output:** Plain text string, no JSON structure required.
-
-#### 4. Chat Hint Test (Part of Speech)
-```json
-{
-  "messages": [
-    {
-      "role": "system",
-      "content": "You provide clues for word puzzles. You will be told the target word that players need to guess, but you must NEVER mention, spell, or reveal that word in your response. Follow the EXACT format requested. Be concise and direct about the target word without revealing it. Use plain text only - no bold, italics, asterisks, or markdown formatting. Stick to word limits."
-    },
-    {
-      "role": "user",
-      "content": "The target word is 'walked'. The sentence is: 'Every morning, she would _____ to the village market to buy fresh bread.'\n\nQuestion type: part_of_speech\n\nIdentify what part of speech fits in this blank. Answer in 2-5 words. Format: 'It's a/an [part of speech]'"
-    }
-  ],
-  "temperature": 0.6,
-  "max_tokens": 50
-}
-```
-
-**Expected Output:** Plain text following format "It's a/an [part of speech]"
-
-#### 5. Chat Hint Test (Synonym)
-```json
-{
-  "messages": [
-    {
-      "role": "system",
-      "content": "You provide clues for word puzzles. You will be told the target word that players need to guess, but you must NEVER mention, spell, or reveal that word in your response. Follow the EXACT format requested. Be concise and direct about the target word without revealing it. Use plain text only - no bold, italics, asterisks, or markdown formatting. Stick to word limits."
-    },
-    {
-      "role": "user",
-      "content": "The target word is 'cottage'. The sentence is: 'The old woman lived in a small _____ by the forest.'\n\nQuestion type: synonym\n\nSuggest a different word that could replace the blank. Answer in 1-3 words only."
-    }
-  ],
-  "temperature": 0.6,
-  "max_tokens": 50
-}
-```
-
-**Expected Output:** Plain text with 1-3 word synonym
-
-### LM Studio Configuration
-
-1. **Model Selection**: Load gemma-3-27b or equivalent model
-2. **Context Length**: Set to at least 4096 tokens
-3. **GPU Layers**: Maximize based on available VRAM
-4. **Batch Size**: 512 for optimal performance
-5. **Prompt Format**: Use ChatML or model's native format
-
-### Testing Checklist
-
-- [ ] Verify JSON responses are clean (no markdown blocks)
-- [ ] Check word selections match passage exactly
-- [ ] Ensure hints never reveal target words
-- [ ] Validate response stays within token limits
-- [ ] Test difficulty level word length constraints
-- [ ] Confirm batch processing handles both passages
-- [ ] Verify contextualization produces factual content
-- [ ] Test all four hint question types