Socratic AI Tutor

Turning AI into a teacher, not an answer machine.

Comment

TL;DR: Most AI homework tools give students the final answer. Socratic AI Tutor is built so it structurally can't—the model is restricted in code, not just prompted, from revealing a solution until the student has reasoned through it. Photo in, textbook-grounded hints out, answer only once earned.

Inspiration

A student photographs a physics question, pastes it into an AI app, and has the final number before they've finished re-reading the problem. No struggle, no reasoning, no learning—just an answer copied into a homework slot.

Most AI homework tools solve the immediate problem: they give students the answer. It's convenient—but it also encourages students to bypass the reasoning that learning depends on.

We wanted to build something closer to a great human tutor: one who knows the answer but deliberately guides students toward discovering it themselves.

Why not simply use ChatGPT or Gemini? They can certainly be prompted to act Socratically, but only as long as the conversation follows that instruction. A student can always ask, "Just tell me the answer," and the model usually will. They also rely primarily on general knowledge unless textbook content is manually provided.

We designed Socratic AI Tutor differently. Instead of asking the model to avoid giving answers, we built the tutoring workflow so that direct answers are system-level restricted until the student has demonstrated sufficient understanding. That distinction—enforced in code, not requested in a prompt—is the actual innovation here. The objective isn't to replace AI assistants; it is to change how students learn with them.

That led to one guiding question:

Can an AI system understand a photographed homework question, retrieve the exact textbook content behind it, and guide a student toward the solution step by step—without revealing the final answer until genuine understanding has been demonstrated?

What it does

Socratic AI Tutor transforms a single homework photo into an interactive learning session through four stages.

1. OCR

Students upload a photo of a homework question—even if it is tilted, handwritten around the edges, or cluttered with notes. The OCR pipeline extracts only the relevant question, including equations, numbers, units, and multiple-choice options.

2. Textbook Retrieval

The extracted question is converted into embeddings and matched against a vector database built from the SNC Punjab curriculum (Physics, Chemistry, and Biology). Instead of relying solely on an LLM's general knowledge, every tutoring response is grounded in the same textbook the student is studying.

3. Socratic Tutoring

This is the core innovation.

Rather than generating complete solutions, the tutor follows a controlled reasoning loop. Every response is validated using structured output (isFinalAnswer) enforced by backend logic—not merely requested through prompt engineering.

If a student's reasoning is incomplete, the tutor provides exactly one guiding question or one small hint.

Only after the student demonstrates a correct and complete understanding does the tutor confirm the solution and conclude the conversation.

For example, instead of solving a stoichiometry problem outright, the tutor first asks:

"How many moles of aluminium are present in 2.7 g?"

The student performs each reasoning step independently instead of receiving the final calculation immediately.

The tutor reasons through equations such as

$$ \mathrm{Al + 3HCl \rightarrow AlCl_3 + \frac{3}{2}H_2} $$

using relationships like

$$ n_{\mathrm{AlCl_3}} : n_{\mathrm{Al}} = 1 : 1 $$

and

$$ m = n \times M $$

without revealing the final answer.

4. Adaptive Progress

Every interaction records:

  • Correctness
  • Hints used
  • Topic mastery The current prototype adjusts difficulty using rule-based progression.

How we built it

The system combines multiple AI components into a single tutoring pipeline.

  • Vision-based OCR and Socratic reasoning are powered through Groq-hosted language models using an OpenAI-compatible API.
  • Textbook retrieval uses Sentence Transformers with Qdrant vector search.
  • FastAPI orchestrates the complete workflow through four dedicated endpoints: /ocr /retrieve /socratic-reply /score-update

One engineering decision proved especially valuable: we froze the API contract before writing any AI logic.

Each teammate owned a separate component—OCR, retrieval, backend integration, frontend, or textbook indexing—and developed independently using mocked responses. This reduced integration issues and allowed parallel development throughout the project.

Current limitation: We have not yet benchmarked end-to-end latency. Measuring response time under realistic tutoring workloads is one of our next engineering priorities.

Challenges we ran into

Conversation structure bug

One of the hardest bugs appeared to be an AI reasoning failure.

Even when students submitted correct answers, the tutor continued asking opening questions instead of recognising completion.

The root cause turned out to be architectural rather than prompt-related. Two consecutive conversation turns shared the same role, causing the provider to merge them internally. As a result, the model never evaluated the student's response as an independent turn.

Moving textbook context into the system prompt restored the expected conversation flow and resolved the issue completely.

Reasoning token budget

Our initial provider counted internal reasoning against the same output budget used for visible responses.

For OCR, long homework questions occasionally became truncated because reasoning consumed the available tokens before extraction completed.

The solution was simple but important:

  • Disable reasoning for OCR.

- Keep reasoning enabled for the Socratic tutoring stage.

Model changes

Several models were deprecated during development.

Rather than depending on fixed model names, we redesigned configuration so providers could be replaced with minimal code changes.

Image download restrictions

Certain image hosts rejected automated requests with HTTP 403 responses.

Adding browser-style request headers resolved the issue reliably.

Accomplishments

  • Built a tutoring engine that distinguishes genuine understanding from partially correct reasoning instead of matching keywords.
  • Grounded every tutoring response in curriculum-specific textbook content rather than relying solely on general LLM knowledge.
  • Successfully coordinated four independent development streams through a shared API contract.
  • Created an OCR pipeline capable of handling realistic classroom photographs while refusing uncertain inputs instead of guessing. ### Current validation status

The prototype demonstrates the complete pipeline:

Homework Photo
      ↓
OCR
      ↓
Textbook Retrieval
      ↓
Socratic Tutoring
      ↓
Adaptive Progress Tracking

Formal evaluation—including OCR accuracy, tutoring effectiveness, and classroom testing with real students—is planned as the next validation milestone.

What we learned

  • Reasoning is a resource, not a universal improvement. Different AI tasks require different reasoning strategies.
  • Multi-turn AI failures are often architectural rather than prompt-related.
  • Reliable tutoring requires grounding responses in trusted learning material instead of relying only on general-purpose language models.

- Stable software architecture and clear API contracts matter just as much as model quality when building collaborative AI systems.

What's next

  • Replace rule-based progression with a data-driven mastery model.
  • Benchmark OCR accuracy, tutoring quality, and response latency using real photographed homework questions.
  • Expand curriculum coverage beyond the initial SNC Punjab textbooks.
  • Support complete worksheet sessions with continuous mastery tracking.
  • Build teacher and parent dashboards that surface how students reason through problems, not simply whether they answered correctly. The student from the first line still gets an answer eventually just one they arrived at themselves.

Built With

  • cloudinary
  • fastapi
  • groq
  • langchain
  • nest.js
  • next.js
  • parisma
  • pdfplumber
  • postragesql
  • python
  • qudrant
  • sentence-transfomer
  • swagger
Share this project:

Updates