AI StudyOS 🎓

The Unified, AI-Powered Student Dashboard & Revision Hub.

AI StudyOS is a highly optimized, premium study dashboard designed to centralize textbook materials, automate active-recall study tasks, and schedule exam preparation timelines.

It pairs a structured course hierarchy (Dashboard → Semester → Subject → Chapter) with on-device text parsing, local similarity vector searches (RAG), spaced-repetition algorithms, and generative AI APIs (Gemini & Groq).

---

✨ Core Features

• 📁 Structured Course Manager: Inline creation and deletion trees for semesters, subjects, and topics—persisted directly on navigation.
• 📄 CORS-Resilient PDF Parsing: On-device, client-side PDF text extraction using a Same-Origin local Web Worker bundle (pdfjs-dist).
• 📸 WASM-Based Scan OCR: Pure-JS character recognition of hand-written note snapshots or whiteboards using tesseract.js web workers.
• 🧠 Spaced Repetition (SM-2): Recall master decks utilizing the SuperMemo-2 (SM-2) algorithm to calculate next-review intervals and ease factors based on recall difficulty ratings (Forgot, Hard, Good, Easy).
• 📝 AI Summaries & Notes: Generates structured markdown notes, definitions, formulas, and bulleted takeaways.
• 🎯 Challenge Quizzes: Dynamic multiple-choice questions with plausible distractor options, immediate correctness scoring, and rationale explanations.
• 💬 Client-Side RAG Chat: Ask questions directly referencing your files. Runs local TF-IDF tokenization and Cosine Similarity vector matching to rank and retrieve context chunks, feeding them to the AI models.
• 📅 Monthly Revision Planner: Color-coded calendar events separating exams (red), homework assignments (orange), and spaced-repetition reviews (blue), complete with manual event creation forms.
• 🌓 HSL-Based Dark/Light Themes: Responsive, glassmorphic layout system with anti-flicker blocker scripts to detect and paint theme preferences instantly.

---

🔌 Resilient Dual-Mode Execution

AI StudyOS is engineered with a zero-dependency fallback layer to allow immediate testing without requiring API keys or cloud databases:

1. 🔑 API Mode (Live AI & Cloud): When GEMINI_API_KEY or GROQ_API_KEY is present in .env.local, the serverless routes invoke Gemini 2.5 Flash (or Llama 3 on Groq) to generate summaries, quizzes, and chat responses. Data can also sync to Supabase.
2. 📴 Fallback Heuristic Mode (Free & Offline): If API keys are missing, the system activates custom client-side NLP regex parsers. It analyzes your PDF text, extracts sentences matching definition patterns (e.g. is, are, refers to, occurs when), and automatically compiles them into formatted study guides, active recall card decks, and distractors. Database data falls back to localStorage.

---

🛠️ Technology Stack

• Frontend: Next.js (App Router, TypeScript, React 19)
• Styling: Vanilla CSS (HSL Custom Properties, Glassmorphism, CSS 3D Transforms)
• Icons: Lucide React
• PDF Extraction: PDF.js (v4.10.38 with locally hosted worker script)
• Scan OCR: Tesseract.js (WASM)
• AI Orchestration: Google Generative AI SDK (gemini-2.5-flash), Groq SDK (llama3-8b-8192)
• Database Fallback: LocalStorage (seeded with sample curriculum data) / Supabase

---

🚀 Getting Started

1. Prerequisites

Make sure you have Node.js (v18.0 or higher) and npm installed.

2. Installation

Clone the repository and install the dependencies:

git clone https://github.com/YOUR_USERNAME/AI_StudyOS.git
cd AI_StudyOS
npm install

3. Environment Variables Setup

Copy the environment variables template and add your API keys:

# Rename the placeholder configuration file
copy .env.local.example .env.local

Open .env.local and paste your Google AI Studio or Groq developer keys:

GEMINI_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here

4. Run the Application

Start the Next.js development server:

npm run dev

Open http://localhost:3000 in your browser.

5. Production Build

Compile the application for production hosting:

npm run build
npm run start