Local-first IDE tutoring loop

Vybe Tutor

AI can generate explanations, but assessment and progression should stay deterministic, validated, and local.

Vybe Tutor is a VS Code extension that helps students learn from AI-assisted coding. A student selects code, Gemini generates an explanation and quiz, and the extension grades answers locally while adjusting difficulty, XP, levels, and streaks.

The architecture separates probabilistic generation from deterministic learning state. Zod contracts validate AI and message payloads, while pure TypeScript functions own grading, adaptation, and gamification.

VS Code extension demoZod-validated AI outputslocal adaptive engine

View source repo Resume context

This project appears under Projects on my resume.

Demo loop: selected code becomes an explanation, quiz, feedback, and progress update.

System flow

Learning loop

01select code
02Gemini response
03Zod validation
04local grading
05adaptive feedback

Project artifacts

Evidence you can see.

Real project media appears where available, with placeholder cards only where sanitized screenshots are still needed.

Project identity for the VS Code tutoring extension.

Vybe Tutor sidebar showing correct-answer feedback — Correct-answer sidebar state shows local grading and immediate feedback.

Vybe Tutor sidebar showing wrong-answer recovery feedback — Wrong-answer state demonstrates recovery feedback instead of simply marking failure.

Vybe Tutor example showing a correct quiz answer — Correct quiz example connects generated explanation to a comprehension check.

Vybe Tutor example showing an incorrect quiz answer — Incorrect quiz example shows how the tutor explains the missed concept.

Vybe Tutor hover context inside VS Code — Hover context keeps the learning surface inside the editor workflow.

Code snippet used for a Vybe Tutor wrong-answer example — Code snippet evidence shows the exact kind of selected code the tutor responds to.

Vybe Tutor team working on the project — Hackathon build context: implementing the extension and webview loop.

Vybe Tutor team photo — Team context for the KiroHacks prototype.

Technical deep dives

The model can write JSON, but the extension still has to prove it.

Contracts around AI output

Tutor responses, quiz questions, doc references, and host/webview messages are all validated with strict Zod schemas. Gemini output is parsed as JSON, then accepted only if it matches the TutorResponse contract.

The Gemini request asks for application/json output.
Invalid JSON and schema mismatch fail before rendering.
The same contract family validates messages crossing the webview boundary.

Source sectionGemini service Source sectionZod contracts

The learner's progress should not depend on another AI call.

Local deterministic adaptation

The adaptive engine uses pure functions to grade answers, update mastery, choose next difficulty, and decide whether to show hints. Incorrect answers lower difficulty and enter recovery; stable correct answers can step difficulty up.

Grading is a case-insensitive selected-vs-correct comparison.
Mastery is clamped between 0 and 1.
A rolling recent-answer window controls difficulty increases.

Source sectionAdaptive engine Demo/videoDemo video

Official docs improve explanations, but failure should not break tutoring.

Documentation enrichment as a side channel

The doc enricher maps model-identified concepts to Python documentation topics, fetches unique topics in parallel, and attaches quotes as references. If docs fail, the tutor response still renders.

Concepts are deduplicated by documentation topic.
Promise.allSettled keeps one failed fetch from failing the whole enrichment step.
Doc enrichment is best-effort and caught separately from the main Gemini response.

Source sectionDoc enricher Demo/videoTutor demo video

Animated artifact

AI generation is boxed in by local contracts

The learning loop separates Gemini output from deterministic grading, state updates, and adaptive feedback.

selected codeGeminiZodlocal gradeadapt

Code evidence

Short excerpts that show the design choices.

Snippets are trimmed for readability and paired with the source file they came from.

const parsedJson = JSON.parse(rawText);
const validated = TutorResponseSchema.parse(parsedJson);

return handleGuardrails(validated);

The extension treats Gemini as an untrusted generator. The response must parse and satisfy the schema before it enters the UI.

Source sectionOpen Gemini service

if (!isCorrect) {
  return {
    ...state,
    currentDifficulty: clampDifficulty(d - 1),
    recoveryState: "recovering",
    needsReview: true,
  };
}

Progression is deterministic and local: a missed question lowers difficulty and marks the concept for review without asking AI to decide.

Source sectionOpen adaptive engine Demo/videoWatch demo

Outcome and reflection

What this project proves.

Built a clearer story around privacy, validation, and learning-state ownership.
Showed how AI can be useful without making the whole product nondeterministic.
Connected product principle, code contracts, and tests into one case-study narrative.

Vybe Tutor shows the kind of AI engineering I want to demonstrate: use the model where it is strong, but put contracts, deterministic state, and user trust around it.