TerpAdvisor

Inspiration

Every registration season, we found ourselves overwhelmed — scrolling through endless course options, stressed about what to take next, and unsure whether our choices actually fit our major and pathway. UMD offers nearly 5,000 courses, but no smart, personalized way to figure out what you should take. Advisors do their best, but they can’t scale to hundreds of students. So we built the advisor we always needed: one that understands your academic journey and can map out your next steps instantly.

What It Does

TerpAdvisor is an AI-powered academic planning platform built specifically for University of Maryland students. You upload your degree audit PDF and the app automatically parses your major, GPA, every course you've completed, and everything still required. From there, a Claude-powered advisor chat lets you ask natural questions — "What should I take next semester?", "Which GenEd is the easiest double-dipper?", "Build me a four-year plan that keeps Fridays free" — and get real, personalized answers backed by actual UMD data. The platform includes a drag-and-drop semester planner with prerequisite validation, a GenEd Explorer with an "Easy Picks" mode that sorts courses by historical GPA, a full course browser across all 4,876 UMD courses with sub-5ms search, ML-predicted difficulty and workload scores, professor quality ratings, and an Insights dashboard pulling real earnings data, career pathways, and UMD graduation statistics.

How we built it

The frontend is Next.js 14 with Tailwind and React Query. The backend is a FastAPI Python service handling auth, course data, AI advisor streaming, and plan generation. A separate ML microservice runs four scikit-learn and VADER-powered models for difficulty prediction, workload estimation, professor quality scoring, and course recommendations. Course data (all 4,876 UMD courses) is seeded from api.umd.io and enriched with PlanetTerp grade distributions, then stored in Supabase PostgreSQL with a GIN full-text index for fast search. Redis handles caching with 24-hour TTLs. The AI advisor uses Claude with tool use and server-sent event streaming so responses feel live and natural. PDF parsing uses a three-stage waterfall: pdfplumber for fast local extraction, Gemini 1.5 Flash for vision enrichment when confidence is low, and Claude vision as the final fallback.

Challenges we ran into

The hardest part of the entire project was building the ML difficulty model from scratch. There's no dataset that just tells you how hard a UMD course is — we had to construct that signal ourselves. We pulled grade distributions and student reviews from PlanetTerp for hundreds of courses and engineered a feature set that could capture difficulty from multiple angles: historical average GPA, VADER sentiment analysis on student review text, keyword density for workload language ("midterm," "weekly," "project"), struggle language ("brutal," "weed-out," "impossible"), and ease language ("GPA booster," "chill," "free A"). The challenge was that none of these features alone tells the full story — a course with a low GPA might just have a harsh grader, not brutal content. Getting the weighted formula right so that the 0–10 difficulty scores actually felt meaningful and matched students' lived experience took a lot of iteration and testing across very different course types.

Then, we had to take those difficulty scores and make them useful inside the planner — which meant solving a second hard problem: figuring out whether a proposed schedule is actually feasible. A semester with five "Hard" courses back-to-back isn't just a difficulty issue, it's a prerequisite issue, a credit load issue, and a cognitive load issue all at once. We built validation logic that checks prerequisite chains (with full AND/OR logic up to five levels deep), flags credit overloads, catches duplicate courses across semesters, and uses the aggregate difficulty rating of the whole semester to warn users when they're biting off more than is reasonable. Getting all of those constraints to work together (and getting Claude to respect all of them when generating a four-year plan automatically) was genuinely the most complex engineering challenge of the project.

Accomplishments that we're proud of

We're proud of the end-to-end experience feeling genuinely polished and useful. The four-year plan generator respects graduation requirements, AND/OR prerequisite chains, preferred class days, credit limits, and difficulty tolerance all at once — and produces a structured forecast with semester milestones and career narrative. The GenEd Explorer with Easy Picks mode is something we genuinely wish had existed when we were picking classes. Getting course search from ~300ms (live API) down to under 5ms by seeding the full catalog into Postgres with a GIN index felt like a real win. And building the entire PDF parsing pipeline (pdfplumber to Gemini to Claude vision) so that any degree audit PDF just works, regardless of format, took a lot of careful engineering.

What we learned

Building a real AI-powered product means designing for failure at every layer. We learned how to structure Claude tool use for multi-step reasoning, how to stream SSE responses for a natural conversational feel, and how to balance AI cost with speed using model waterfalls (cheap-and-fast first, powerful-and-expensive as fallback). On the data side, we learned how much work goes into making external data clean and queryable; normalizing prerequisite strings from free text into structured AND/OR logic across 4,876 courses was extremely difficult. We also got a lot more comfortable with ML feature engineering and building models that degrade gracefully rather than failing silently.

What's next for TerpAdvisor

The collaborative filter recommender is built but not yet surfaced in the UI — a "Recommended for You" tab in Insights is the immediate next step. We also want to add section-aware scheduling: right now the planner knows which courses to take, but not which section fits your actual schedule. Integrating live section data from api.umd.io so the AI can recommend morning vs. evening sections, avoid conflicts, and prefer your preferred days would make the planner dramatically more practical. Longer term, we'd love to expand beyond CS to serve all UMD majors, and potentially open the platform up to other universities that have similar public course APIs.

Built With

• anthropic-claude
• api.umd.io
• college-scorecard-api
• fastapi
• gemini1.5-flash
• next.js
• pandas
• pdfplumber
• planetterp-api
• postgresql
• railway
• react-query
• redis
• scikit-learn
• tailwind
• vader-sentiment
• vercel