@gonzih/exam-prep-mcp 0.1.0

package/dist/readiness.d.ts

@@ -0,0 +1,15 @@
+export interface ReadinessReport {
+    score: number;
+    strongTopics: TopicScore[];
+    weakTopics: TopicScore[];
+    coveragePercent: number;
+    trend: 'improving' | 'declining' | 'stable';
+    recommendation: string;
+    estimatedGrade: string;
+}
+export interface TopicScore {
+    topic: string;
+    accuracy: number;
+    attempts: number;
+}
+export declare function calculateReadiness(profileId: string, examType: string, examDate: string): ReadinessReport;

package/dist/readiness.js

@@ -0,0 +1,272 @@
+import { getTopicStats, getRecentSessions } from './db.js';
+import { EXAM_TOPICS } from './study-plan.js';
+import { QUESTION_BANK } from './questions.js';
+// Grade mapping for different exam types
+const GRADE_MAPPINGS = {
+    AP_Biology: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    AP_Chemistry: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    AP_US_History: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    AP_World_History: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    AP_Physics: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    AP_Calculus: (s) => {
+        if (s >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (s >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (s >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (s >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    },
+    SAT_Math: (s) => {
+        if (s >= 90)
+            return 'SAT Math Score: 750-800';
+        if (s >= 80)
+            return 'SAT Math Score: 680-750';
+        if (s >= 70)
+            return 'SAT Math Score: 600-680';
+        if (s >= 60)
+            return 'SAT Math Score: 520-600';
+        if (s >= 50)
+            return 'SAT Math Score: 440-520';
+        return 'SAT Math Score: Below 440';
+    },
+    SAT_Reading: (s) => {
+        if (s >= 90)
+            return 'SAT Reading Score: 35-40';
+        if (s >= 80)
+            return 'SAT Reading Score: 30-35';
+        if (s >= 70)
+            return 'SAT Reading Score: 25-30';
+        if (s >= 60)
+            return 'SAT Reading Score: 20-25';
+        return 'SAT Reading Score: Below 20';
+    },
+    MCAT: (s) => {
+        if (s >= 90)
+            return 'MCAT Score: 517-528 (97th+ percentile)';
+        if (s >= 80)
+            return 'MCAT Score: 511-516 (80th-96th percentile)';
+        if (s >= 70)
+            return 'MCAT Score: 505-510 (60th-79th percentile)';
+        if (s >= 60)
+            return 'MCAT Score: 499-504 (40th-59th percentile)';
+        return 'MCAT Score: Below 499';
+    },
+    LSAT: (s) => {
+        if (s >= 90)
+            return 'LSAT Score: 170-180 (97th+ percentile)';
+        if (s >= 80)
+            return 'LSAT Score: 163-169 (88th-96th percentile)';
+        if (s >= 70)
+            return 'LSAT Score: 156-162 (70th-87th percentile)';
+        if (s >= 60)
+            return 'LSAT Score: 149-155 (42nd-69th percentile)';
+        return 'LSAT Score: Below 149';
+    },
+    GRE: (s) => {
+        if (s >= 90)
+            return 'GRE Score: 165-170 Verbal, 165-170 Quant';
+        if (s >= 80)
+            return 'GRE Score: 158-164 Verbal, 158-164 Quant';
+        if (s >= 70)
+            return 'GRE Score: 152-157 Verbal, 152-157 Quant';
+        if (s >= 60)
+            return 'GRE Score: 145-151 Verbal, 145-151 Quant';
+        return 'GRE Score: Below 145';
+    },
+};
+function getGradeEstimate(examType, score) {
+    const mapper = GRADE_MAPPINGS[examType];
+    if (mapper)
+        return mapper(score);
+    // Generic AP mapping for unmapped types
+    if (examType.startsWith('AP_')) {
+        if (score >= 85)
+            return 'AP Score: 5/5 (Extremely Well Qualified)';
+        if (score >= 70)
+            return 'AP Score: 4/5 (Well Qualified)';
+        if (score >= 55)
+            return 'AP Score: 3/5 (Qualified)';
+        if (score >= 40)
+            return 'AP Score: 2/5 (Possibly Qualified)';
+        return 'AP Score: 1/5 (No Recommendation)';
+    }
+    return `Estimated score: ${Math.round(score)}%`;
+}
+function generateRecommendation(score, weakTopics, coveragePercent, trend, daysRemaining) {
+    const parts = [];
+    if (score >= 85) {
+        parts.push('Excellent preparation! You are performing at a high level.');
+    }
+    else if (score >= 70) {
+        parts.push('Good progress! You have a solid foundation.');
+    }
+    else if (score >= 55) {
+        parts.push('Moderate preparation. More focused study will improve your score.');
+    }
+    else {
+        parts.push('More intensive study is needed. Focus on building fundamentals.');
+    }
+    if (weakTopics.length > 0) {
+        const topWeak = weakTopics.slice(0, 3).map(t => t.topic).join(', ');
+        parts.push(`Prioritize these weak areas: ${topWeak}.`);
+    }
+    if (coveragePercent < 60) {
+        parts.push(`You have only covered ${Math.round(coveragePercent)}% of topics — work through more areas.`);
+    }
+    if (trend === 'improving') {
+        parts.push('Your performance is improving — keep up the momentum!');
+    }
+    else if (trend === 'declining') {
+        parts.push('Your recent scores are declining. Consider reviewing earlier material.');
+    }
+    if (daysRemaining > 14) {
+        parts.push('You have time to make significant improvements with consistent daily practice.');
+    }
+    else if (daysRemaining > 7) {
+        parts.push('Focus on weak areas and complete at least one full mock exam.');
+    }
+    else {
+        parts.push('Final stretch: review key concepts, rest well, and trust your preparation.');
+    }
+    return parts.join(' ');
+}
+export function calculateReadiness(profileId, examType, examDate) {
+    const allTopicStats = getTopicStats(profileId);
+    const examTopics = EXAM_TOPICS[examType] || [];
+    // Get exam weight data from questions
+    const topicWeights = {};
+    for (const q of QUESTION_BANK) {
+        if (q.subject === examType) {
+            if (!topicWeights[q.topic] || q.examWeight > topicWeights[q.topic]) {
+                topicWeights[q.topic] = q.examWeight;
+            }
+        }
+    }
+    // Calculate per-topic accuracy
+    const topicScores = [];
+    let weightedScore = 0;
+    let totalWeight = 0;
+    for (const stats of allTopicStats) {
+        if (stats.total_attempts === 0)
+            continue;
+        const accuracy = (stats.correct_attempts / stats.total_attempts) * 100;
+        const weight = topicWeights[stats.topic] || 0.5;
+        topicScores.push({
+            topic: stats.topic,
+            accuracy,
+            attempts: stats.total_attempts
+        });
+        weightedScore += accuracy * weight;
+        totalWeight += weight;
+    }
+    const baseScore = totalWeight > 0 ? weightedScore / totalWeight : 0;
+    // Coverage bonus
+    const practicedTopics = new Set(allTopicStats.filter(s => s.total_attempts > 0).map(s => s.topic));
+    const examSpecificTopics = examTopics.length > 0 ? examTopics : [...practicedTopics];
+    const coveragePercent = examSpecificTopics.length > 0
+        ? (practicedTopics.size / examSpecificTopics.length) * 100
+        : 0;
+    let coverageBonus = 0;
+    if (coveragePercent >= 80)
+        coverageBonus = 20;
+    else if (coveragePercent >= 60)
+        coverageBonus = 10;
+    // Trend calculation from recent sessions
+    const recentSessions = getRecentSessions(profileId, 20);
+    let trend = 'stable';
+    let trendModifier = 0;
+    if (recentSessions.length >= 6) {
+        const recent5 = recentSessions.slice(0, 5);
+        const prev5 = recentSessions.slice(5, 10);
+        const recentAccuracy = recent5.reduce((sum, s) => sum + (s.questions_answered > 0 ? s.correct / s.questions_answered : 0), 0) / recent5.length;
+        const prevAccuracy = prev5.reduce((sum, s) => sum + (s.questions_answered > 0 ? s.correct / s.questions_answered : 0), 0) / prev5.length;
+        const diff = recentAccuracy - prevAccuracy;
+        if (diff > 0.05) {
+            trend = 'improving';
+            trendModifier = 5;
+        }
+        else if (diff < -0.05) {
+            trend = 'declining';
+            trendModifier = -5;
+        }
+    }
+    // Time modifier
+    const now = new Date();
+    const examDateObj = new Date(examDate);
+    const daysRemaining = Math.max(0, Math.ceil((examDateObj.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)));
+    const timeModifier = daysRemaining > 30 ? 3 : daysRemaining > 14 ? 1 : 0;
+    // Final score (clamped 0-100)
+    const rawScore = baseScore + (coverageBonus * 0.3) + trendModifier + timeModifier;
+    const score = Math.max(0, Math.min(100, rawScore));
+    // Identify strong and weak topics
+    const strongTopics = topicScores
+        .filter(t => t.accuracy >= 80)
+        .sort((a, b) => b.accuracy - a.accuracy);
+    const weakTopics = topicScores
+        .filter(t => t.accuracy < 60)
+        .sort((a, b) => a.accuracy - b.accuracy);
+    const recommendation = generateRecommendation(score, weakTopics, coveragePercent, trend, daysRemaining);
+    const estimatedGrade = getGradeEstimate(examType, score);
+    return {
+        score: Math.round(score),
+        strongTopics,
+        weakTopics,
+        coveragePercent: Math.round(coveragePercent),
+        trend,
+        recommendation,
+        estimatedGrade
+    };
+}

package/dist/study-plan.d.ts

@@ -0,0 +1,25 @@
+export interface StudyPlan {
+    examType: string;
+    examDate: string;
+    daysRemaining: number;
+    dailySchedule: DayPlan[];
+    topicsIdentified: string[];
+    weeklyGoals: string[];
+}
+export interface DayPlan {
+    date: string;
+    dayNumber: number;
+    activities: Activity[];
+    estimatedMinutes: number;
+    isMockExam: boolean;
+}
+export interface Activity {
+    topic: string;
+    type: 'study' | 'practice' | 'review' | 'mock_exam';
+    durationMinutes: number;
+    description: string;
+}
+export declare const EXAM_TOPICS: Record<string, string[]>;
+export declare const EXAM_TIME_LIMITS: Record<string, number>;
+export declare const MOCK_EXAM_QUESTIONS: Record<string, number>;
+export declare function generateStudyPlan(examType: string, examDate: string, currentLevel: 'beginner' | 'intermediate' | 'advanced', weakTopics?: string[]): StudyPlan;

package/dist/study-plan.js

@@ -0,0 +1,313 @@
+// Topic lists per exam type
+export const EXAM_TOPICS = {
+    AP_Biology: [
+        'Cell Structure',
+        'DNA Replication',
+        'Transcription and Translation',
+        'Cell Division',
+        'Mendelian Genetics',
+        'Evolution and Natural Selection',
+        'Ecology',
+        'Photosynthesis',
+        'Cellular Respiration',
+        'Plant Systems',
+        'Animal Systems',
+        'Genetics',
+    ],
+    AP_Chemistry: [
+        'Atomic Structure',
+        'Chemical Bonding',
+        'Stoichiometry',
+        'Gas Laws',
+        'Thermodynamics',
+        'Chemical Equilibrium',
+        'Acids and Bases',
+        'Electrochemistry',
+        'Kinetics',
+        'Nuclear Chemistry',
+    ],
+    AP_US_History: [
+        'Colonial Period',
+        'American Revolution',
+        'Constitutional Convention',
+        'Early Republic',
+        'Antebellum and Civil War',
+        'Reconstruction Era',
+        'Gilded Age',
+        'Progressive Era',
+        'World War I',
+        'World War II',
+        'Cold War',
+        'Civil Rights Movement',
+        'Modern America',
+    ],
+    AP_World_History: [
+        'Ancient Civilizations',
+        'Classical Period',
+        'Post-Classical Period',
+        'Renaissance and Reformation',
+        'Early Modern Period',
+        'Industrialization',
+        'Imperialism',
+        'World War I',
+        'World War II',
+        'Cold War',
+        'Globalization',
+    ],
+    AP_Physics: [
+        'Kinematics',
+        'Newton\'s Laws',
+        'Energy and Work',
+        'Momentum',
+        'Circular Motion',
+        'Gravity',
+        'Electricity',
+        'Magnetism',
+        'Waves and Optics',
+        'Thermodynamics',
+    ],
+    AP_Calculus: [
+        'Limits and Continuity',
+        'Derivatives',
+        'Applications of Derivatives',
+        'Integration',
+        'Applications of Integration',
+        'Differential Equations',
+        'Sequences and Series',
+    ],
+    AP_Statistics: [
+        'Exploratory Data Analysis',
+        'Sampling and Experiments',
+        'Probability',
+        'Probability Distributions',
+        'Sampling Distributions',
+        'Confidence Intervals',
+        'Hypothesis Testing',
+        'Regression',
+    ],
+    AP_English: [
+        'Rhetorical Analysis',
+        'Argument and Evidence',
+        'Synthesis Essays',
+        'Literary Analysis',
+        'Close Reading',
+        'Grammar and Style',
+    ],
+    AP_Economics: [
+        'Supply and Demand',
+        'Elasticity',
+        'Consumer Theory',
+        'Production and Costs',
+        'Market Structures',
+        'GDP and Macroeconomics',
+        'Money and Banking',
+        'Monetary Policy',
+        'Fiscal Policy',
+        'International Trade',
+    ],
+    SAT_Math: [
+        'Linear Equations',
+        'Linear Inequalities',
+        'Systems of Equations',
+        'Quadratic Equations',
+        'Percentages and Proportions',
+        'Statistics and Probability',
+        'Geometry',
+        'Word Problems',
+        'Functions',
+        'Data Analysis',
+    ],
+    SAT_Reading: [
+        'Main Idea and Purpose',
+        'Evidence and Support',
+        'Vocabulary in Context',
+        'Inference Questions',
+        'Passage Structure',
+        'Comparing Passages',
+        'Data Interpretation',
+    ],
+    SAT_Writing: [
+        'Grammar Rules',
+        'Sentence Structure',
+        'Punctuation',
+        'Word Choice',
+        'Organization and Transitions',
+        'Evidence and Clarity',
+    ],
+    MCAT: [
+        'Biology and Biochemistry',
+        'Chemistry and Physics',
+        'Psychology and Sociology',
+        'Critical Analysis',
+        'Research Methods',
+        'Statistics',
+    ],
+    LSAT: [
+        'Logical Reasoning',
+        'Analytical Reasoning (Logic Games)',
+        'Reading Comprehension',
+        'Argument Structure',
+        'Formal Logic',
+    ],
+    GRE: [
+        'Verbal Reasoning',
+        'Quantitative Reasoning',
+        'Analytical Writing',
+        'Algebra',
+        'Geometry',
+        'Data Analysis',
+        'Reading Comprehension',
+    ],
+};
+// Exam time limits in minutes
+export const EXAM_TIME_LIMITS = {
+    AP_Biology: 170,
+    AP_Chemistry: 190,
+    AP_US_History: 205,
+    AP_World_History: 205,
+    AP_Physics: 180,
+    AP_Calculus: 195,
+    AP_Statistics: 180,
+    AP_English: 215,
+    AP_Economics: 130,
+    SAT_Math: 70,
+    SAT_Reading: 65,
+    SAT_Writing: 35,
+    MCAT: 375,
+    LSAT: 175,
+    GRE: 225,
+};
+export const MOCK_EXAM_QUESTIONS = {
+    AP_Biology: 60,
+    AP_Chemistry: 60,
+    AP_US_History: 55,
+    AP_World_History: 55,
+    AP_Physics: 50,
+    AP_Calculus: 45,
+    AP_Statistics: 40,
+    AP_English: 45,
+    AP_Economics: 60,
+    SAT_Math: 44,
+    SAT_Reading: 52,
+    SAT_Writing: 44,
+    MCAT: 230,
+    LSAT: 100,
+    GRE: 80,
+};
+export function generateStudyPlan(examType, examDate, currentLevel, weakTopics) {
+    const now = new Date();
+    const examDateObj = new Date(examDate);
+    const msPerDay = 1000 * 60 * 60 * 24;
+    const daysRemaining = Math.max(1, Math.ceil((examDateObj.getTime() - now.getTime()) / msPerDay));
+    const allTopics = EXAM_TOPICS[examType] || ['General Study'];
+    const topicsIdentified = [...allTopics];
+    // Level-based settings
+    const minutesPerTopic = currentLevel === 'beginner' ? 60 : currentLevel === 'intermediate' ? 45 : 30;
+    const topicsPerDay = currentLevel === 'beginner' ? 1 : currentLevel === 'intermediate' ? 2 : 3;
+    // Build topic schedule with weak areas weighted 2x
+    const weightedTopics = [];
+    for (const topic of allTopics) {
+        const isWeak = weakTopics && weakTopics.includes(topic);
+        weightedTopics.push(topic);
+        if (isWeak) {
+            weightedTopics.push(topic); // Add again for 2x weight
+        }
+    }
+    // Build daily schedule
+    const dailySchedule = [];
+    let topicIndex = 0;
+    const weeklyGoals = [];
+    for (let day = 0; day < Math.min(daysRemaining, 90); day++) {
+        const date = new Date(now);
+        date.setDate(date.getDate() + day);
+        const dateStr = date.toISOString().split('T')[0];
+        const dayNumber = day + 1;
+        // Mock exams at 7 and 3 days before exam
+        const daysBeforeExam = daysRemaining - day;
+        const isMockExam = daysBeforeExam === 7 || daysBeforeExam === 3;
+        const activities = [];
+        let estimatedMinutes = 0;
+        if (isMockExam) {
+            const timeLimitMins = EXAM_TIME_LIMITS[examType] || 120;
+            activities.push({
+                topic: 'Full Mock Exam',
+                type: 'mock_exam',
+                durationMinutes: timeLimitMins + 30,
+                description: `Full-length ${examType} practice exam simulating real conditions. Review all answers afterward.`
+            });
+            estimatedMinutes = timeLimitMins + 30;
+        }
+        else if (daysBeforeExam === 1) {
+            // Day before: light review
+            activities.push({
+                topic: 'Final Review',
+                type: 'review',
+                durationMinutes: 30,
+                description: 'Light review of key formulas and concepts. Rest and prepare for exam day.'
+            });
+            estimatedMinutes = 30;
+        }
+        else {
+            // Regular study day
+            const dayTopics = weightedTopics.slice(topicIndex % weightedTopics.length, (topicIndex % weightedTopics.length) + topicsPerDay);
+            topicIndex += topicsPerDay;
+            // Deduplicate topics for this day
+            const uniqueDayTopics = [...new Set(dayTopics)];
+            for (const topic of uniqueDayTopics) {
+                const isWeak = weakTopics && weakTopics.includes(topic);
+                activities.push({
+                    topic,
+                    type: 'study',
+                    durationMinutes: minutesPerTopic,
+                    description: `Study ${topic} — ${isWeak ? 'focus area (weak topic)' : 'core concepts and examples'}`
+                });
+                estimatedMinutes += minutesPerTopic;
+                // Add practice component
+                activities.push({
+                    topic,
+                    type: 'practice',
+                    durationMinutes: 15,
+                    description: `Practice questions for ${topic}`
+                });
+                estimatedMinutes += 15;
+            }
+            // Weekly review on Sundays
+            if (date.getDay() === 0) {
+                activities.push({
+                    topic: 'Weekly Review',
+                    type: 'review',
+                    durationMinutes: 30,
+                    description: 'Review all topics covered this week. Identify areas needing more attention.'
+                });
+                estimatedMinutes += 30;
+            }
+        }
+        dailySchedule.push({
+            date: dateStr,
+            dayNumber,
+            activities,
+            estimatedMinutes,
+            isMockExam
+        });
+    }
+    // Generate weekly goals
+    const weeksRemaining = Math.ceil(daysRemaining / 7);
+    const topicsPerWeek = Math.ceil(allTopics.length / Math.max(weeksRemaining, 1));
+    for (let week = 0; week < Math.min(weeksRemaining, 6); week++) {
+        const weekTopics = allTopics.slice(week * topicsPerWeek, (week + 1) * topicsPerWeek);
+        if (weekTopics.length > 0) {
+            weeklyGoals.push(`Week ${week + 1}: Master ${weekTopics.join(', ')}`);
+        }
+    }
+    if (weeksRemaining > 0) {
+        weeklyGoals.push(`Final week: Full mock exams and comprehensive review`);
+    }
+    return {
+        examType,
+        examDate,
+        daysRemaining,
+        dailySchedule,
+        topicsIdentified,
+        weeklyGoals
+    };
+}