@gonzih/exam-prep-mcp 0.1.0

package/src/readiness.ts

@@ -0,0 +1,268 @@
+import { getTopicStats, getRecentSessions, TopicStats } from './db.js';
+import { EXAM_TOPICS } from './study-plan.js';
+import { QUESTION_BANK } from './questions.js';
+
+export interface ReadinessReport {
+  score: number; // 0-100
+  strongTopics: TopicScore[];
+  weakTopics: TopicScore[];
+  coveragePercent: number;
+  trend: 'improving' | 'declining' | 'stable';
+  recommendation: string;
+  estimatedGrade: string;
+}
+
+export interface TopicScore {
+  topic: string;
+  accuracy: number; // 0-100
+  attempts: number;
+}
+
+// Grade mapping for different exam types
+const GRADE_MAPPINGS: Record<string, (score: number) => string> = {
+  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: string, score: number): string {
+  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: number,
+  weakTopics: TopicScore[],
+  coveragePercent: number,
+  trend: string,
+  daysRemaining: number
+): string {
+  const parts: string[] = [];
+
+  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: string,
+  examType: string,
+  examDate: string
+): ReadinessReport {
+  const allTopicStats = getTopicStats(profileId);
+  const examTopics = EXAM_TOPICS[examType] || [];
+
+  // Get exam weight data from questions
+  const topicWeights: Record<string, number> = {};
+  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: TopicScore[] = [];
+  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: 'improving' | 'declining' | 'stable' = '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/src/study-plan.ts

@@ -0,0 +1,364 @@
+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;
+}
+
+// Topic lists per exam type
+export const EXAM_TOPICS: Record<string, string[]> = {
+  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: Record<string, number> = {
+  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: Record<string, number> = {
+  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: string,
+  examDate: string,
+  currentLevel: 'beginner' | 'intermediate' | 'advanced',
+  weakTopics?: string[]
+): StudyPlan {
+  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: string[] = [];
+  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: DayPlan[] = [];
+  let topicIndex = 0;
+  const weeklyGoals: string[] = [];
+
+  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: Activity[] = [];
+    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
+  };
+}