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

// 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

// 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

// 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

// 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

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

// 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