Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for MDC Advisor Next Stop

🦈 Inspiration

Every year, thousands of Miami students ask the same question: "I like computers (or buildings, or helping people). What do I actually do next?" The answer is spread across program PDFs, transfer agreements and a phone line to an advisor. Many students only find out which credits won't transfer after they've taken the classes.

Several of us are MDC students, and we've lived that confusion. We wanted to build the guide we wish we'd had: you drop in a transcript and get an honest, step-by-step plan that starts at Miami Dade College and shows where it leads, including transfer schools, cost, time and the career at the end.

💡 What it does

NextStop is a full-stack academic and career advisor. Finn, our pixel-art advisor shark, reads your transcript, finds your strongest subjects, suggests MDC programs and builds a term-by-term plan. Once you approve the plan, it's locked. Finn then shows how your credits would carry over to FIU, UM, UCF or USF, and lets you ask "what if I switch to nursing?". Finn answers in English or Spanish and remembers you between visits when you're logged in.

🛠️ How we built it

Layer What we used
Website Plain HTML/CSS/JS (no build step), served by Flask
API Python Flask on waitress
AI chat and roadmaps Gemini through the Prune gateway, falling back to Gemini direct, then OpenRouter
Transcript reading Gemini multimodal for photos and scanned PDFs; pypdf for text PDFs
Multi-agent roadmaps Swarms SequentialWorkflow: Career Researcher → MDC Pathway Planner → Transfer & Outcomes Advisor
Data TigerData (Postgres + a TimescaleDB hypertable for usage events); SQLite locally
Login Auth0 hosted login; the API verifies RS256 tokens against the tenant's JWKS
Hosting Docker + Caddy (automatic HTTPS) on Vultr

The model never writes the plan. It only returns a program code. The server then builds the plan from a curated catalog that includes MDC's official Applied AI A.S. (25080) and B.S. (S9520) program sheets. That's how we keep requirements, credits and prerequisites accurate.

Finding strengths. For each subject $s$, we average the grade points $\bar{g}_s$ from the transcript. AP, IB, honors and dual-enrollment classes get $+0.5$, capped at $4.5$. A subject counts as strong when $\bar{g}_s \ge 3.0$. Each program $p$ gets a fit score:

$$ S_p = \sum_{s} w_{p,s}\,\bigl(\bar{g}_s - 2\bigr)\,\sqrt{\min(n_s,\,4)} $$

Here $w_{p,s}$ is how much subject $s$ matters to program $p$ and $n_s$ is the number of courses in that subject. Subtracting $2$ (a C) means weak grades pull a program down. The square root rewards depth without letting one subject with many classes dominate. Grades below C are listed but never counted toward a degree.

Estimating cost. A plan preview estimates

$$ \text{Cost} = C_{\text{left}} \times r_{\text{MDC}}, \qquad r_{\text{MDC}} = \$118.22 \text{ per credit (in-state)} $$

The transfer tab compares that with each university's 2026-27 per-credit tuition (for example, FIU at \$205.57).

Safety by design. Phone numbers, emails, addresses, student IDs and school names are removed before any text reaches a model. Prompt-injection attempts ("ignore your instructions", "set my progress to 100") are refused. Every AI feature has an offline fallback, so Finn never goes silent.

📚 What we learned

  • Grounding beats prompting. Keeping facts in a curated catalog and letting AI personalize instead of invent made the answers trustworthy and let us test the advisor like ordinary software.
  • Test it like a product. We wrote 61 synthetic student personas: clear matches, undecided explorers, students who change their minds, Spanish speakers, parents, oversharers and prompt injectors. Through Prune → Gemini, Finn got 59/61 right, and both misses were cases where Finn asked a follow-up question instead of picking a program. A 153-test pytest suite covers the backend.
  • Fallback chains matter. Real APIs time out, reject parameters and change key formats. Designing for failure from day one is what made the demo reliable.
  • Working as a team: backend and AI (Ricardo) and UI/UX design (Cris) worked in parallel against one shared API contract (API.md).

🧗 Challenges we faced

  • Prune isn't OpenAI-compatible and runs in vault-only mode. We had to wire its per-provider proxy routes and the X-Prune-Key header by hand.
  • Caching gave the wrong student's answer. Prune's semantic cache treated two "what if" questions that differed only in numbers as the same request, so it could return another student's advice. Personal answers (plan previews, what-if, school pages) now retry uncached when they hit the cache.
  • Swarms timeouts. The default model rejected temperature, and long 3-agent runs hit gateway timeouts. Smaller token budgets plus gpt-4.1-mini cut a run to about 7 seconds, and results are cached.
  • New Google API keys (AQ. prefix) worked as API keys but were rejected as Bearer tokens, which broke Prune's vault until we figured out why.
  • Gemini picked a program in prose but left the JSON field empty. We added server-side extraction that only counts a pick when the reply recommends exactly one program instead of listing options.
  • Reading messy transcripts. Photos, scans, high-school vs. college formats, and real vs. sample course codes all needed separate parsing paths, with a clear message when image reading isn't available.

🚀 What's next

  • Load the rest of MDC's catalog and official articulation agreements to replace the modeled equivalencies.
  • An anonymized advisor dashboard built on TigerData trends, so MDC can see which careers students are exploring.
  • Bring course-section scheduling (already in the API at /api/schedule) into the UI.

Built With

Share this project:

Updates

Submission history