TerpOracle

Instantly analyze your UMD schedule's workload, professor quality, and balance! Upload an image or enter courses manually to get AI-powered insights using Gemini, Testudo, and PlanetTerp data.

Comment 2

Inspiration

Choosing the right courses and balancing a schedule at UMD can be overwhelming. Students often rely on scattered information from Testudo, PlanetTerp, and word-of-mouth. I wanted to create a centralized tool that not only gathers this data but also uses the power of generative AI to provide a holistic, insightful analysis of a student's potential semester schedule, helping them make more informed decisions.

What it does

TerpOracle analyzes a University of Maryland (UMD) student's class schedule to provide comprehensive feedback and scores across several key categories. Users can either:

  1. Upload an image of their schedule (e.g., a screenshot from Testudo).
  2. Manually enter their Course IDs (e.g., CMSC430) and Section numbers (e.g., 0201).

The application then:

  • Extracts course information (if using image upload) using the Google Gemini Vision model.
  • Fetches official course details (professor, time, title) by scraping the UMD Testudo website.
  • Gathers professor ratings and reviews using the PlanetTerp API.
  • Sends the combined course, professor, and review data to the Google Gemini (2.0 Flash) model for analysis.
  • Generates concurrent AI analyses for each individual course using asyncio, covering aspects like Teaching Quality, Difficulty, Workload, Grading Fairness, etc.
  • Produces a final overall schedule analysis, synthesizing the individual course feedback and assigning scores for Overall Workload, Professor Quality, Schedule Balance, Subject Synergy, Difficulty Management, and an Overall Schedule Grade.
  • Displays the results in a clean web interface, including the overall grade and detailed breakdowns for each course with basic Markdown rendering.

How I built it

  • Frontend: Built with HTML, CSS, and vanilla JavaScript. The interface is clean and intuitive, inspired by Apple's aesthetic. It supports both image upload and manual entry, and uses the Fetch API for backend communication.
  • Backend: A lightweight Flask server in Python handles routing, input parsing, and orchestrates the schedule analysis pipeline.
  • Core Analysis Script (enhanced_schedule_analyzer.py):
    • Integrates the Google Gemini API via the google-generativeai library for both vision and text analysis.
    • Scrapes Testudo data using requests and BeautifulSoup4.
    • Retrieves professor data from the PlanetTerp API.
    • Uses asyncio to parallelize Gemini calls for each course, improving speed.
    • Supports both image input and structured JSON input via argparse.

Data Flow:

  1. User submits input (image or JSON + API key + term).
  2. JavaScript sends this data to the Flask backend.
  3. Flask calls the analyzer script with the appropriate arguments.
  4. The script fetches and analyzes course/professor data.
  5. Results are saved to schedule_data.json.
  6. Flask returns the JSON to the frontend.
  7. JavaScript dynamically renders the schedule analysis results.

Challenges I ran into

  • Testudo Scraping: HTML inconsistencies made parsing challenging.
  • Data Integration: Merging scraped HTML, JSON API data, and image OCR.
  • Prompt Engineering: Fine-tuning prompts for accurate, structured Gemini output.
  • Concurrency: Managing asyncio workflows and debugging edge cases.
  • Input Flexibility: Supporting both image and manual text input cleanly.
  • Frontend Formatting: Handling display formatting and Markdown rendering in vanilla JS.

Accomplishments that I'm proud of

  • Successfully integrated vision and text AI with traditional scraping and APIs.
  • Achieved real-time, concurrent Gemini-based analysis.
  • Built an intuitive, multi-input interface with clean UI/UX.
  • Delivered a product that directly helps UMD students make better schedule decisions.

What I learned

  • Real-world application of large language models via APIs.
  • Robust web scraping with requests and BeautifulSoup.
  • Flask API design and dynamic frontend-backend integration.
  • Asynchronous programming with asyncio.
  • Effective UI design and iterative debugging based on feedback.

What's next for TerpOracle

  • Improve Scraping Robustness: Adapt to layout changes on Testudo.
  • Deeper Analysis: Consider commute time, course prerequisites, and topic diversity.
  • Support More Schools: Generalize scraping logic to support other universities.
  • Add User Accounts: Save analysis history and API keys for frequent users.
  • Improve Markdown Rendering: Provide richer formatting support.
  • Refine Prompts: Tune Gemini input for greater consistency and reliability.
Share this project:

Updates