Class_generator/SMART_PREVIEW_SPECS.md

# Smart Preview System - Technical Specifications

## 🎯 System Overview

**Smart Preview** is an intelligent course preparation system that provides systematic content review with LLM-powered validation. Students can preview and validate their understanding of entire chapter content through adaptive exercises with prerequisite-based progression.

## 🏗️ Dynamic Modular Architecture

### Orchestrator + Semi-Independent Modules

**Core Philosophy**: Dynamic class system with an orchestrator that pilots semi-independent exercise modules. Each module can be loaded, unloaded, and controlled dynamically.

#### **SmartPreviewOrchestrator.js** - Main Controller
- Extends Module base class
- Manages dynamic loading/unloading of exercise modules
- Handles exercise sequencing and variation patterns
- Coordinates shared services (LLM, Prerequisites)
- Tracks overall progress and session state

#### **Semi-Independent Exercise Modules**
1. **VocabularyModule.js** - Vocabulary exercises (groups of 5)
2. **VocabExamModule.js** - AI-verified comprehensive vocabulary exam system
3. **PhraseModule.js** - Individual phrase comprehension
4. **TextModule.js** - Sentence-by-sentence text processing
5. **AudioModule.js** - Audio comprehension exercises
6. **ImageModule.js** - Image description exercises
7. **GrammarModule.js** - Grammar construction and validation

#### **Shared Service Modules**
- **LLMValidator.js** - LLM integration for all exercise types
- **PrerequisiteEngine.js** - Dependency tracking and content filtering
- **ContextMemory.js** - Progressive context building across exercises

### Module Interface Standard
```javascript
// All exercise modules must implement this interface
class ExerciseModuleInterface {
    // Check if module can run with current prerequisites
    canRun(prerequisites, chapterContent): boolean;

    // Present exercise UI and content
    present(container, exerciseData): Promise<void>;

    // Validate user input with LLM
    validate(userInput, context): Promise<ValidationResult>;

    // Get current progress data
    getProgress(): ProgressData;

    // Clean up and prepare for unloading
    cleanup(): void;
}
```

### Dynamic Loading System
```javascript
// Orchestrator can dynamically control modules
orchestrator.loadModule('vocabulary');
orchestrator.switchTo('phrase', prerequisites);
orchestrator.unloadModule('text');
orchestrator.getAvailableModules(currentPrerequisites);

// Module lifecycle management
module.canRun(prereqs) → module.present() → module.validate() → module.cleanup()
```

### Module Dependencies
```javascript
// Orchestrator dependencies
dependencies: ['eventBus', 'contentLoader']

// Each exercise module receives shared services via injection
constructor(orchestrator, llmValidator, prerequisiteEngine, contextMemory)
```

## 📋 Functional Requirements

### 1. Systematic Review by Content Type

#### Vocabulary Review (Groups of 5)
- Display 5 vocabulary words with translations
- Test recognition/translation with LLM validation
- Must achieve mastery (80%+) before next group
- Track learned vocabulary for prerequisite system

#### Vocabulary Exam System (AI-Verified Comprehensive Assessment)
- **Batch Testing Approach**: Present 15-20 vocabulary questions in sequence, collect all answers, then send complete batch to AI for evaluation
- **Multiple Question Types**:
  - Translation (L1→L2 and L2→L1)
  - Definition matching and explanation
  - Context usage (fill-in-the-blank with sentences)
  - Synonym/antonym identification
  - Audio recognition (if audio available)
- **AI-Powered Batch Evaluation**:
  - Single API call evaluates entire batch for efficiency
  - Cross-question consistency checking within batch
  - Semantic understanding over exact word matching
  - Context-aware validation for multiple correct answers
  - Partial credit for near-correct responses
  - Intelligent feedback for incorrect answers
- **Batch Processing Benefits**:
  - Reduced API costs and latency
  - Consistent evaluation across question set
  - Better pattern recognition for student strengths/weaknesses
- **Adaptive Difficulty**: Next batch adapts based on previous batch performance
- **Mastery Certification**: Must achieve 85%+ overall score to pass
- **Spaced Repetition Integration**: Failed words automatically added to review queue
- **Progress Analytics**: Detailed breakdown by word, question type, and difficulty level

#### Phrase Comprehension (Individual)
- Present single phrases for translation/comprehension
- LLM evaluation for semantic accuracy (not exact matching)
- Context-aware validation considering multiple correct answers

#### Text Processing (Sentence by Sentence)
- Break texts into individual sentences
- Progressive context building (sentence 1 → sentence 1+2 → sentence 1+2+3)
- Each sentence validated with accumulated context
- Prerequisites: only texts containing learned vocabulary words

#### Audio Comprehension
- Play audio segments with transcription for LLM reference
- User provides comprehension in their own words
- LLM evaluates understanding against transcription

#### Image Description
- Present images for description exercises
- LLM evaluates vocabulary usage and accuracy of description
- No exact matching required - intelligent semantic evaluation

#### Grammar Exercises
- Present grammar-focused exercises (sentence construction, tense usage, etc.)
- LLM evaluates grammar correctness and natural language flow
- Context-aware grammar validation considering multiple correct structures
- Track grammar concept mastery (present tense, articles, sentence structure, etc.)

### 2. Prerequisite Dependency System

#### Smart Filtering
```javascript
// Only chapter vocabulary words are prerequisites
chapterVocab = ['shirt', 'coat', 'blue', 'work', 'wear'];

// Basic words assumed known
assumedKnown = ['the', 'is', 'a', 'to', 'in', 'on', 'at', ...];

// Dependency extraction
function getPrerequisites(content, chapterVocabulary) {
    const words = extractWords(content);
    return words.filter(word =>
        chapterVocabulary.includes(word) ||
        chapterVocabulary.includes(getBaseForm(word))
    );
}
```

#### Progressive Unlocking
- Vocabulary groups unlock based on completion of previous groups
- Phrases unlock when ALL required chapter words are learned
- Text sentences unlock progressively with vocabulary mastery
- Real-time content availability updates

### 3. Exercise Variation Engine

#### Dynamic Pattern Generation
```javascript
const exercisePattern = [
    'vocabulary-5',           // First 5 vocab words
    'single-phrase',          // Available phrase with learned words
    'vocabulary-5',           // Next 5 vocab words
    'text-sentence-1',        // First sentence of available text
    'vocabulary-5',           // Continue vocabulary
    'vocab-exam-checkpoint',  // Comprehensive exam after 15-20 learned words
    'text-sentence-2-ctx',    // Second sentence with context from first
    'image-description',      // Image exercise
    'audio-comprehension',    // Audio exercise
    'vocab-exam-final',       // Final comprehensive exam at chapter end
    // Pattern continues...
];

// Vocabulary Exam Trigger Logic
const examTriggers = {
    checkpoint: {
        condition: 'wordsLearned >= 15 && wordsLearned % 15 === 0',
        examType: 'checkpoint',
        wordsToTest: 'last15Learned',
        passingScore: 80
    },
    final: {
        condition: 'chapterComplete',
        examType: 'comprehensive',
        wordsToTest: 'allChapterWords',
        passingScore: 85
    },
    remedial: {
        condition: 'examFailed',
        examType: 'focused',
        wordsToTest: 'failedWords',
        passingScore: 75
    }
};
```

#### Context Memory System
- Store user responses for progressive exercises
- Build context for text comprehension exercises
- Pass accumulated context to LLM for evaluation
- Reset context appropriately between different texts/topics

### 4. LLM Integration

#### Evaluation Prompts
```javascript
// Translation Validation
const translationPrompt = `
Evaluate this language learning translation:
- Original (English): "${originalText}"
- Student translation (Chinese/French): "${userAnswer}"
- Context: ${exerciseType} exercise
- Previous context: ${contextHistory}

Evaluate if the translation captures the essential meaning, even if not word-for-word exact.
Return JSON: {
    score: 0-100,
    correct: boolean,
    feedback: "constructive feedback in user's language",
    keyPoints: ["important vocabulary/grammar noted"]
}
`;

// Vocabulary Exam Batch Validation
const vocabExamBatchPrompt = `
Evaluate this vocabulary exam batch (15-20 questions):
- Language level: ${languageLevel}
- Total questions in batch: ${batchSize}

Questions and responses:
${questionsArray.map((q, i) => `
${i+1}. Question type: ${q.type} | Target word: "${q.targetWord}"
   Expected: "${q.expectedAnswer}"
   Student answer: "${q.userAnswer}"
   Context: "${q.contextSentence || 'N/A'}"
`).join('')}

For different question types:
- Translation: Accept semantic equivalents, consider cultural variations
- Definition: Accept paraphrasing that captures core meaning
- Context usage: Evaluate grammatical correctness and semantic appropriateness
- Synonyms: Accept close semantic relationships, not just exact synonyms

Evaluate ALL questions in the batch and look for consistency patterns.

Return JSON: {
    batchScore: 0-100,
    totalCorrect: number,
    totalPartialCredit: number,
    overallFeedback: "general performance summary",
    questions: [
        {
            questionId: number,
            score: 0-100,
            correct: boolean,
            partialCredit: boolean,
            feedback: "specific feedback for this question",
            correctAlternatives: ["alternative answers if applicable"],
            learningTip: "helpful tip for this word/concept"
        }
        // ... for each question in batch
    ],
    strengthAreas: ["areas where student performed well"],
    weaknessAreas: ["areas needing improvement"],
    recommendedActions: ["specific next steps for improvement"]
}
`;

// Audio Comprehension Validation
const audioPrompt = `
Evaluate audio comprehension:
- Audio transcription: "${transcription}"
- Student comprehension: "${userAnswer}"
- Language level: beginner/intermediate

Did the student understand the main meaning? Accept paraphrasing and different expressions.
Return JSON: {score: 0-100, correct: boolean, feedback: "..."}
`;

// Image Description Validation
const imagePrompt = `
Evaluate image description:
- Student description: "${userAnswer}"
- Target vocabulary from chapter: ${chapterVocab}
- Exercise type: free description

Evaluate vocabulary usage, accuracy of description, and language naturalness.
Return JSON: {score: 0-100, correct: boolean, feedback: "...", vocabularyUsed: []}
`;

// Grammar Exercise Validation
const grammarPrompt = `
Evaluate grammar usage:
- Exercise type: ${grammarType} (sentence construction, tense usage, etc.)
- Student response: "${userAnswer}"
- Target grammar concepts: ${grammarConcepts}
- Language level: ${languageLevel}

Evaluate grammatical correctness, naturalness, and appropriate usage of target concepts.
Accept multiple correct variations but identify errors clearly.
Return JSON: {
    score: 0-100,
    correct: boolean,
    feedback: "constructive grammar feedback",
    grammarErrors: ["specific errors identified"],
    grammarStrengths: ["correct usage noted"],
    suggestion: "alternative correct formulation if needed"
}
`;
```

#### API Configuration
- Support multiple LLM providers (OpenAI, Claude, local Ollama)
- Fallback mechanisms for API failures
- Rate limiting and error handling
- Configurable temperature and model parameters

### 5. Progress Tracking

#### Mastery Validation
- Individual word mastery tracking (attempts, success rate, last reviewed)
- Phrase/sentence comprehension scores
- Grammar concept mastery tracking (tenses, sentence structure, etc.)
- **Vocabulary Exam Performance**:
  - Checkpoint exam scores (every 15 words)
  - Comprehensive exam certification status
  - Question-type specific performance (translation, definition, context, etc.)
  - Remedial exam tracking for failed words
- Overall chapter progress percentage
- Difficulty adaptation based on performance

#### Visual Progress Indicators
- Progress bar showing overall completion
- Section-based progress (vocabulary: 45/60, phrases: 8/12, texts: 2/5, grammar: 6/8)
- Mastery indicators (✅ learned, 🟡 reviewing, ❌ needs work)
- Grammar concept tracking (present tense: ✅, articles: 🟡, word order: ❌)
- Time estimates for completion

## 🎮 User Experience Flow

### Session Start
1. Load chapter content and analyze prerequisites
2. Display progress overview and available exercises
3. Present first available exercise based on mastery state

### Exercise Flow
1. **Present Content** - Show vocabulary/phrase/text/image/audio/grammar exercise
2. **User Interaction** - Input translation/description/comprehension/grammar construction
3. **LLM Validation** - Intelligent evaluation with feedback (including grammar analysis)
4. **Progress Update** - Update mastery tracking (vocabulary, grammar concepts, etc.)
5. **Next Exercise** - Dynamic selection based on progress and variation pattern

### Adaptive Progression
- If user struggles (< 60% score): additional practice exercises
- If user excels (> 90% score): accelerated progression
- Smart retry system for failed exercises
- Prerequisite re-evaluation after each mastery update

### Session End
- Progress summary with achievements
- Recommendations for next session
- Mastery gaps identified for focused review

## 🔧 Technical Implementation

### Dynamic Modular File Structure
```
src/games/smart-preview/
├── SmartPreviewOrchestrator.js     # Main orchestrator module
├── exercise-modules/               # Semi-independent exercise modules
│   ├── VocabularyModule.js         # Vocabulary exercises (groups of 5)
│   ├── VocabExamModule.js          # AI-verified batch vocabulary exams
│   ├── PhraseModule.js             # Individual phrase comprehension
│   ├── TextModule.js               # Sentence-by-sentence processing
│   ├── AudioModule.js              # Audio comprehension
│   ├── ImageModule.js              # Image description
│   └── GrammarModule.js            # Grammar construction
├── services/                       # Shared service modules
│   ├── LLMValidator.js             # LLM integration for all modules
│   ├── PrerequisiteEngine.js       # Dependency tracking
│   └── ContextMemory.js            # Progressive context building
├── interfaces/
│   └── ExerciseModuleInterface.js  # Standard interface for all modules
└── templates/
    ├── orchestrator.html           # Main UI template
    └── modules/                    # Module-specific templates
        ├── vocabulary.html
        ├── vocab-exam.html         # Batch exam interface
        ├── phrase.html
        ├── text.html
        ├── audio.html
        ├── image.html
        └── grammar.html
```

### Dynamic Module Data Flow
```
1. Orchestrator Initialization
   └── Load shared services (LLM, Prerequisites, Context)
   └── Analyze chapter content and prerequisites
   └── Determine available exercise modules

2. Module Loading & Sequencing
   └── orchestrator.getAvailableModules(prerequisites)
   └── orchestrator.loadModule(selectedType)
   └── module.canRun(prerequisites) → boolean

3. Exercise Execution
   └── module.present(container, exerciseData)
   └── user interaction & input capture
   └── module.validate(userInput, context) → ValidationResult

4. Dynamic Adaptation
   └── Update mastery tracking
   └── prerequisiteEngine.reevaluate(newMastery)
   └── orchestrator.selectNextModule(progress, variation)
   └── module.cleanup() → orchestrator.unloadModule()

5. Module Lifecycle
   canRun() → present() → validate() → cleanup() → unload/switch
```

### Integration Points

#### With Existing System
- Extends Module base class architecture
- Uses EventBus for communication
- Integrates with existing content loading system
- Compatible with current routing system

#### Content Requirements
- Chapter vocabulary lists with base forms
- Phrase/sentence collections with difficulty indicators
- Audio files with transcriptions
- Images with contextual information
- Text passages segmented by sentences

### Performance Considerations
- Lazy loading of exercises and content
- LLM request caching for repeated validations
- Efficient prerequisite checking algorithms
- Minimal DOM manipulation for smooth UX

## 🚀 Dynamic Implementation Strategy

### **MVP Phase 1: Orchestrator + Vocabulary Module (Week 1)**
```
1. SmartPreviewOrchestrator.js - Core controller
   └── Module loading/unloading system
   └── Basic exercise sequencing
   └── Progress tracking foundation

2. VocabularyModule.js - First exercise module
   └── Groups of 5 vocabulary system
   └── Basic LLM mock validation
   └── Standard interface implementation

3. Services Foundation
   └── LLMValidator.js (mock responses initially)
   └── PrerequisiteEngine.js (chapter vocab filtering)
   └── ExerciseModuleInterface.js (standard contract)
```

### **Phase 2: Add Core Modules (Week 2)**
```
4. PhraseModule.js - Individual phrase comprehension
5. TextModule.js - Sentence-by-sentence processing
6. Basic ContextMemory.js - Progressive context building
7. Real LLM integration (replace mocks)
```

### **Phase 3: Complete Module Set (Week 3)**
```
8. AudioModule.js - Audio comprehension
9. ImageModule.js - Image description
10. GrammarModule.js - Grammar construction
11. Advanced prerequisite logic
12. Exercise variation patterns
```

### **Phase 4: Intelligence & Polish (Week 4)**
```
13. Adaptive difficulty system
14. Advanced context memory
15. Performance optimization
16. Error handling and fallbacks
17. UI/UX refinements
```

### **Development Approach**
- **Modular Testing**: Each module independently testable
- **Progressive Enhancement**: Add modules incrementally
- **Interface-Driven**: All modules follow standard contract
- **Service Injection**: Shared services injected into modules
- **Dynamic Loading**: Modules loaded only when needed

## 📊 Success Metrics

### Learning Effectiveness
- User completion rates per session
- Average time to vocabulary mastery
- Retention rates in follow-up sessions
- User satisfaction scores

### Technical Performance
- LLM response times (< 2 seconds)
- Exercise loading times (< 500ms)
- System uptime and error rates
- Content coverage completeness

### Adaptive Accuracy
- Prerequisite system accuracy (avoiding impossible exercises)
- LLM validation consistency with human evaluation
- Progression appropriateness for user level