Adaptive Analogy

Inspiration

I've always been the kind of student who could ace a concept once someone explained it the right way, but textbooks only ever explain things one way. As a Data Science student who started out pre-med, I've sat through more "one-size-fits-all" explanations than I can count, and I know I'm not the only one who's felt dumb over a concept that was never actually hard, just badly explained.

That frustration is what led to Adaptive Analogy: an AI tool that doesn't just explain a concept, but explains it your way, mapped to something you already understand, and keeps adapting until it actually clicks.

What it does

Adaptive Analogy takes any concept a learner is stuck on, along with one personal interest they choose (cooking, sports, gaming, music, nature), and generates a custom analogy that maps each piece of the real concept onto something from that world. It then quizzes the learner, not on trivia, but on whether they actually understood the mapping itself.

If they get a question wrong, the AI doesn't just repeat the same explanation louder. It identifies the exact concept part that caused the confusion and generates a completely new analogy from a different angle, an adaptive retry loop that's the core differentiator of the project.

How I built it

• Frontend: Next.js (App Router) and TypeScript, styled with Tailwind CSS in a custom claymorphic design system: soft, rounded, tactile UI in a warm earthy palette.
• Backend: Next.js API routes handling a two-step LLM pipeline. One call generates the analogy mapping, a second generates a targeted quiz based on that mapping.
• AI: Google's Gemini API, chosen after early experiments with other providers ran into cost and quota constraints typical of a student hackathon budget.
• Adaptive logic: A custom retry mechanism that feeds the specific misunderstood concept part back into the generation pipeline, instructing the model to produce a genuinely different comparison rather than a rephrased one.

Challenges I ran into

This project taught me as much about infrastructure as it did about prompt design:

• Model deprecations mid-build. I hit 404 errors from three separate Gemini model versions being retired within the same week, and had to keep adapting the codebase to track whichever model generation was actually current.
• Free-tier quota quirks. I learned the hard way that a limit: 0 error doesn't always mean "used up." It can mean a model's free-tier allocation was zeroed out entirely.
• A misconfigured Git repository. At one point my local repo was accidentally rooted at my entire Windows user folder instead of the project directory, which took real debugging to trace and fix without losing work.
• OneDrive file locking. Building inside a synced folder caused repeated build failures until I identified that OneDrive was locking files Next.js needed to write during development.

Working through each of these taught me a lot about debugging systematically instead of guessing, and about how much of "AI engineering" in 2026 is actually just plain software engineering with an LLM API sitting in the middle.

What I learned

• How to design a two-step LLM pipeline where the second call depends structurally on the first, rather than treating an LLM as a single black-box call.
• That prompt design for structured JSON output matters as much as the underlying idea. A good analogy engine is only as good as the schema constraining it.
• A lot more about API lifecycle management than I expected going in: versioning, deprecation cycles, and building error handling that degrades gracefully instead of crashing.
• That the "boring" infrastructure work (git, environments, build tooling) often eats more time than the actual feature work in a real project, and that's worth planning for.

What's next for Adaptive Analogy

• Expanding the interest categories beyond the current set, and letting learners describe their own interests in free text rather than picking from a fixed list.
• Adding a lightweight "concept history" so returning learners can revisit past analogies.
• Exploring multi-turn conversations where a learner can ask follow-up questions about the analogy itself, rather than only interacting through the quiz.

Built With

• gemini
• next.js
• tailwind
• typescript