TutorTrace AI

Inspiration

Students studying chapters and slides need to know where an explanation came from and what to revise next. Fluent AI output and unexplained mastery scores can hide mistakes. We built a local workflow that keeps the original material accessible and makes the evidence, grading rules and learner estimates visible.

What it does

TutorTrace AI is a working local prototype for Track D (Personalized Tutoring & Adaptive Learning):

• Ingestion: upload PDF chapters and PowerPoint decks. Original bytes are preserved, text is extracted by physical page or slide, duplicate uploads are detected, and PDF page labels are retained.
• Evidence retrieval: SQLite FTS5 search returns passages with exact page/slide citations, inspectable chunk IDs and text offsets, PDF page previews and original downloads. Optional local embeddings complement keyword search.
• Source-grounded AI tutor: a local Qwen3 4B model (via Ollama) answers using only selected passages. Every statement must cite a request-specific source ID and an exact supporting quote, which the app validates; otherwise it shows an abstention or an explicit error.
• Diagnostic assessments: source-derived multiple-choice, exact-wording short-answer and numerical value-recall questions. Answer keys are reconstructed from the source text, never from the language model, and grading uses no AI inference.
• Answer review: every graded answer shows the verified key, the supporting statement and its page/slide citation.
• Learner progress: local profiles persist attempts across restarts. A transparent recall estimate (1 + correct) / (2 + correct + incorrect) adapts the next practice level (easy/medium/hard scaffolding) and records a progress history.
• Personalized revision: topics are ranked by the estimate with source-backed excerpts, and "Revise with AI tutor" hands the topic, level and document scope to the tutor.

How we built it

Python 3.11 and Streamlit provide the interface. PyMuPDF and python-pptx extract page/slide text (PDF parsing runs in an isolated worker process with a timeout). SQLite stores original files, source units and the FTS5 index; a separate SQLite database stores learners, questions, sessions, attempts and estimates. Deterministic content-derived identifiers and transactional updates preserve provenance and history. The provider-independent tutor uses local Ollama Qwen3 4B with bounded context; an OpenAI-compatible remote adapter is implemented but only contract-tested.

PDF / PPTX -> page/slide extraction -> source SQLite + FTS5 -> verified evidence
                                                 |                    |
                                     AI tutor (Qwen3 4B)      cloze quiz generator
                                                 |                    |
                                 source-ID + quote checks       exact grading
                                                 |                    |
                                     Streamlit UI  <----  learner SQLite
                                                                |
                                         recall estimates, revision priorities

Challenges we ran into

Preserving source identity across extraction upgrades, rejecting invented citations without pretending to prove semantic correctness, and making learner updates atomic. Limited RAM and CPU-only inference also required bounded model requests and model-free grading so the learning loop keeps working when the model is slow.

Accomplishments that we're proud of

• 216 automated tests pass (re-run before recording the demo; zero failures).
• Ingestion, exact page/slide citation, quiz grading and separate-process persistence smoke checks pass.
• A recorded real Qwen3 4B revision request returned 3 claims with 3 provenance- and quote-validated support references (70.5 s CPU inference). The demo video shows a separate live answer.
• An earlier 13-case self-authored tutor diagnostic recovered 14/14 labelled source units.
• Three scripted learner profiles completed 27/27 sessions and 81/81 answers with zero repeated facts and 3/3 restart checks.

These are small self-authored sets and prescribed simulations, not general accuracy scores or evidence of real-student learning gains.

What we learned

Reliable educational assistance needs explicit boundaries. Exact citations make answers auditable but cannot prove reasoning correct. A small, understandable learner model is easier to inspect than an unsupported claim of precise mastery. Deterministic recall practice keeps the full learning loop usable even when a local model is slow or unavailable.

Limitations and what's next

This release reasons over extracted text only: video ingestion, OCR and diagram understanding are not implemented. Practice tests source recall, not broad conceptual understanding or novel arithmetic. Paraphrased short answers are marked "needs review"; there is no semantic grading. The recall estimate and difficulty levels are uncalibrated. Profiles have no authentication. Next steps: lecture-video transcription with timestamp citations, diagram extraction, teacher-reviewed question quality, and evaluation with real learners before claiming educational impact.

AI assistance disclosure

Solo developer: Akhilesh Selvan. OpenAI Codex assisted with implementation, tests, self-authored synthetic fixtures and documentation. Claude Code (Anthropic) performed an independent Milestone 1 code audit and prepared the demo-video automation and this submission text from the repository's verified documentation. The demo narration uses the built-in Windows text-to-speech voice. Runtime tutor answers come from the configured local model; mocks are used only in deterministic tests. Demo materials are self-authored and contain no private student data.

Code: https://github.com/AkhileshSelvan/tutortrace-ai

Built With

• fts5
• ollama
• pymupdf
• pytest
• python
• python-pptx
• qwen3
• sqlite
• streamlit