LearnMate-AI: LearnMate AI: The Two-Round Tutor That Decides What You Should Learn Next

A FastAPI and React assessment engine that generates questions, grades answers, avoids repetition, and turns a score into a 30-day roadmap.

8 to 10 min read • View on GitHub • More from prithvi-pratap-GL

A student stands before a machine with two doors, one for Round 1 and one for Round 2. A gauge marked at 50 percent decides whether the learner advances into a richer roadmap path or loops back into review, showing the repo’s thresholded progression model. — LearnMate AI’s core trick is not just generating questions. It uses one round to decide whether the next round should exist at all.

Key Takeaways

LearnMate AI’s defining move is a two-round gate that turns assessment into controlled progression instead of one-size-fits-all quizzing.
The repo treats prompts, schemas, and fallback responses like infrastructure, which makes the LLM workflow readable and resilient.
Model choice is used as product design, with cheaper generation and stronger grading separated into different jobs.
The project stands out by being narrow on purpose, which makes its learning logic easier to inspect than broader AI tutoring platforms.

A Quiz That Promotes You

Most AI tutors try to be conversational first. LearnMate AI starts with a different question: is the learner ready to move up? That is why the repo’s two-round flow matters so much. Round 1 is not just a warm-up. It is a gate.

If the learner clears the threshold, the system opens Round 2 and shifts into a harder path. If not, it stops early and returns something more appropriate. That small decision gives the whole product its shape.

The core product is a state machine, not a flat quiz. The threshold decides whether the learner advances, while fallback logic keeps the flow usable when model calls fail.

Why This Is More Than a Static Assessment

The product promise is simple but useful. LearnMate AI generates topic-specific questions, evaluates responses, and turns the result into a roadmap. That means the learner gets more than a score. They get a next step.

This is where the repo feels more deliberate than many AI tutoring demos. It does not just ask questions. It tries to infer readiness, avoid repetition, and keep the session coherent from start to finish.

A close-up pipeline turns sanitized input into a prompt, then into a model response, then into a strict schema frame. A backup drawer labeled mock responses sits underneath, showing how the system stays functional when live model calls fail. — The interesting part is not the model call itself. It is the set of rules around it that keep the output structured, safe, and recoverable.

The Orchestration Layer

`backend/app/routes/learning.py` is not a thin API wrapper. It is the control center. The route layer decides when a learner advances, when questions should be filtered for repetition, and when the system should stop and return results.

def sanitize_input(text: str) -> str:
    sanitized = re.sub(r'[^a-zA-Z0-9\s]', '', text)
    return sanitized.strip()


@app.post("/submit_round_1")
async def submit_round_1(payload: Round1Submission):
    if payload.score >= 50:
        return {"status": "proceed_to_round_2"}
    return {"status": "complete_assessment"}

That thresholded logic is the point. A learner does not simply finish a quiz and see a number. The system uses the number to decide the next experience.

The same file also handles duplicate-question checks. That matters because adaptive systems can look smart while repeating themselves. Here, the repository tries to keep the learning path moving instead of looping.

Prompting as Infrastructure

The prompt layer in `backend/app/utils/prompts.py` treats output as a contract. The prompts insist on JSON-only responses, which is a practical way to make LLM behavior predictable enough for downstream code.

QUESTION_GENERATION_PROMPT = """
Return ONLY valid JSON array.
Generate {count} unique questions for the topic.
Do not include any explanation, markdown, or extra text.
"""

EVALUATION_PROMPT = """
Reason step-by-step internally.
Return ONLY valid JSON with score and feedback.
"""

That internal reasoning instruction is important. The model can think more freely during evaluation, but only structured output leaves the boundary. It is a neat compromise between flexibility and enforceability.

This is the repo’s quietest strength. It does not trust the model to behave like a clean API. It builds a wrapper that makes messy outputs usable anyway.

The Reliability Stack

The backend service layer adds the kind of resilience a demo usually lacks. If the Hugging Face call fails, the app can fall back to mock responses and topic-specific datasets. That keeps the system alive even when the network is not.

Capability	Live model path	Fallback path
Question generation	Model-driven, topic-specific, structured	Prebuilt topic datasets and mock questions
Answer evaluation	LLM scoring and feedback	Deterministic or simplified substitute responses
Demo reliability	Depends on remote inference	Works offline or during API failure
Developer experience	Realistic output and variability	Stable tests and repeatable demos

For a small educational tool, that is a serious design choice. It means the repo is not just trying to impress in a happy-path demo. It is trying to remain legible and usable when the happy path breaks.

Why the Model Split Matters

The repo separates generation from grading, and that separation matters. Faster, cheaper models can draft questions. Stronger models can judge answers. That turns model choice into product design instead of a one-model-fits-all reflex.

Task	Preferred model posture	Why it fits
Question generation	Fast and economical	Creative output matters more than deep judgment
Answer grading	Stronger and slower	Evaluation benefits from a higher-quality judge
Roadmap synthesis	Structured and reliable	The output needs consistency more than flair

This is the kind of trade-off that makes small AI products durable. It avoids wasting expensive inference everywhere, while reserving the best model for the step where correctness matters most.

What the Frontend Has to Make Legible

The React, TypeScript, and Tailwind frontend has one job: make a multi-stage assessment feel simple. That means the UI has to present progression, scoring, and roadmap output without turning the experience into a dashboard maze.

In this project, the frontend is less about visual novelty and more about comprehension. It packages the backend’s branching logic into something a learner can move through without friction.

Where LearnMate AI Fits in the Crowd

Compared with static quizzes, LearnMate AI is more adaptive. Compared with generic chat tutors, it is more structured. Compared with broader adaptive platforms, it is narrower and easier to inspect.

Approach	Adaptivity	Transparency	Self-hosting	Roadmap output
Static quizzes	Low	High	High	Usually none
Generic AI chat tutors	Medium	Low	Medium	Inconsistent
Broader adaptive platforms	High	Low to medium	Low to medium	Sometimes
LearnMate AI	High for a narrow flow	High	High	Built in

That narrowness is not a weakness here. It is what gives the repo shape. You can see the rules, inspect the prompts, and understand how a score turns into a next step.

What This Repo Suggests About Small-Team AI Products

LearnMate AI shows how far a single developer can push a learning product when the goal is controlled progression, not generic chat. The repo combines routing, prompting, fallback design, and lightweight assessment logic into one coherent system.

That is the real lesson. A small AI product does not need to be broad to be useful. It needs a clear state machine, strict boundaries, and enough resilience to survive real-world failures.