EduTrace — AI-Powered Adaptive Learning Path Agent

Type a topic. Get a personalized roadmap. Learn with an AI agent that adapts to you detecting confusion, switching teaching styles, and quizzing you as you progress.

Comment

Inspiration

Most learning resources treat every learner the same. You search for "learn React" and get the same roadmap whether you're a complete beginner or someone who already knows Vue. And when you get stuck midway, there's nothing to help you through it so you quit.

I wanted to build something that actually adapts: starts where you are, teaches the way you learn, and supports you when you're confused not just a static PDF with a chatbot bolted on.

What it does

EduTrace is a multi-phase adaptive learning system that conducts a short 3-turn diagnostic conversation to infer your knowledge level, then generates a personalized week-by-week roadmap grounded in real roadmap.sh content via RAG starting exactly where you are, not at week 1 for everyone.

As you learn, it tracks your state turn-by-turn: what you've understood, where you're stuck, how you like to learn. You control the teaching style (Analogy, Socratic, Code Examples) and pace (Relaxed, Normal, Accelerated) from the sidebar. At the end of each week, a built-in quiz tests your understanding with MCQs, short answers, and code challenges before you move on.

Features shipped:

  • 3-turn adaptive diagnostic conversation
  • RAG-grounded personalized roadmap generation (60+ topics)
  • Persistent world state with full session history injection every turn
  • Stuck detection with 3 response modes (re-explain / simplify / resource)
  • Teaching modes: Analogy, Socratic, Code Examples
  • Learning pace: Relaxed, Normal, Accelerated
  • End-of-week quizzes: MCQ, short answer, code challenge
  • PDF roadmap export + YouTube resource embeds
  • Week-by-week progress page
  • Firebase Auth + Firestore session persistence and resume

How I built it

Backend: FastAPI (Python) with Firebase Auth token verification on every request, slowapi rate limiting, and bleach input sanitization. Sessions and full conversation history persisted to Firestore per user.

Frontend: React + Vite with a cyberpunk dark theme (JetBrains Mono, cyan/magenta accent system). Three-column chat layout with live world state display, roadmap panel, and teaching mode controls.

RAG layer: 60+ roadmap.sh topic JSONs as static grounding files, injected into Gemini during roadmap generation, truncated to 1800 tokens per request.

Deployment: Vercel (frontend) + Render (backend) + Firebase (auth + database).

How the Gemini API Was Used

EduTrace uses the Gemini API in 4 distinct ways not as a single chat endpoint, but as a multi-role reasoning engine across the entire learning pipeline.

1. Level Inference (Diagnostic Phase)

After the user completes a 3-turn diagnostic conversation, Gemini reads all three answers together and classifies the user as beginner, intermediate, or advanced. It returns structured JSON with the inferred level and a brief rationale. This classification determines where the roadmap starts.

2. RAG-Grounded Roadmap Generation

Once the level is inferred, Gemini receives the user's topic along with structured roadmap.sh content injected as grounding context node graph data and content markdown for 60+ technical topics. Gemini sequences this into a personalized week-by-week curriculum tailored to the user's level, including YouTube resources for each week. Non-tech topics fall back to pure Gemini generation with a warning badge.

3. Persistent Adaptive Conversation (Main Chat Loop)

Every turn in the main chat loop injects the full world state into Gemini current topic, level, week, concepts understood, concepts stuck on, teaching mode, learning pace, and the last 20 turns of conversation history. Every response is conditioned on the full session history, not just the last message. Gemini returns both a response and a state delta, which the backend uses to update the session in Firestore.

4. Stuck Mode Reasoning

When the user sends a short frustrated reply or explicitly says they're stuck, a separate Gemini call reads the stuck concept, the attempt count, and the conversation history to select the right intervention: re-explain from a different angle, simplify into micro-steps, or surface a specific resource link. The mode is selected by Gemini, not hardcoded.

Uses 2 and 3 in combination are the core differentiator Gemini functions as a persistent reasoning engine grounded in real external data across the full session lifetime, not just a single-turn responder.

Models Used

  • Primary: gemini-3.1-flash-lite (high RPD, cost-efficient for high-frequency chat turns)
  • Fallback: gemini-3-flash → gemini-3.5-flash (on quota exhaustion)

Additional Implementation Details

  • Two Gemini SDK instances coexist intentionally: roadmap generation uses a direct call (no search grounding, optimized for speed), while chat uses the full SDK with conversation history injection
  • max_output_tokens=1500 on all calls to control cost
  • RAG context truncated to 1800 tokens per request
  • Gemini fallback chain triggered automatically on 429 responses

Challenges I ran into

  • Managing two Gemini SDK instances intentionally (one for roadmap speed, one for persistent adaptive chat) without consolidating them
  • Building a world state injection system that keeps Gemini context under token limits while preserving enough history to be useful
  • Handling Render cold starts gracefully on the free tier (~30s spin-up) with retries and user feedback
  • Staying within free-tier Gemini RPD limits during development by building a model fallback chain

Accomplishments that I am proud of

  • The system genuinely adapts stuck detection and teaching mode switching work in practice, not just in theory
  • Full security hardening: token verification, rate limiting, input sanitization, Firestore rules, no API keys in frontend
  • Shipped significantly beyond the original scope: teaching modes, learning pace, quizzes, PDF export, progress page, and a full cyberpunk UI overhaul all added during the build

What I learned

  • Persistent adaptive system design is fundamentally different from single-turn prompting world state management is the hard part
  • RAG grounding dramatically improves roadmap quality and specificity compared to pure generation
  • Free-tier quota management requires building fallback chains from day one, not as an afterthought

What's next for EduTrace

  • Monaco in-browser code editor with execution for code challenge quizzes
  • Spaced repetition flashcard system built from concepts the user has covered
  • Gamification: streaks, achievement badges, weekly goals
  • Mobile-responsive polish

Built With

Share this project:

Updates

Submission history