math_tutor_rag

MathMaster Edu is an intelligent mistake management platform for students and teachers. Its core workflow is photo entry of mistakes, AI structured parsing, mathematical verification, vector archiving, mastery assessment, and adaptive review. The project uses a Streamlit frontend and FastAPI gateway, while the backend uses SQLAlchemy to manage SQLite/MySQL/PostgreSQL data, and ChromaDB provides vector retrieval capabilities. Main features include: AI photo question entry, which uses a visual large model to recognize handwritten questions and output exam points, step-by-step explanations, answers, difficulty, common mistake reasons, and variant questions; a multi-model provider abstraction that can switch between SiliconFlow, Tongyi Qianwen, Zhipu GLM, DeepSeek, OpenAI, Ollama, or Gemini, and automatically enters demo mode when no key is available; RAG vector retrieval supports similar question recall and semantic search, and degrades to keyword retrieval when the vector database fails; a built-in SM-2 spaced repetition algorithm for flashcard-style review; a mastery engine that combines review logs to generate ability profiles and daily plans; each mistake supports multiple rounds of follow-up question explanations; a learning dashboard displays knowledge point distribution, weak knowledge points, and entry trends; one-click export of Word review papers; teacher-side student overview and mistake annotations; a learning calendar displays heatmaps, accuracy trends, and consecutive check-ins; a knowledge graph presents mastery status as a tag co-occurrence network. In terms of engineering, the project includes 287 pytest cases, Playwright E2E tests, ruff static checks, GitHub Actions CI (multi-Python version matrix, startup smoke tests, Docker builds), Alembic database migrations, one-click Docker Compose deployment, as well as offline evaluation of RAG retrieval and LLM-as-judge evaluation of AI Tutor. The project also provides an MCP Server, which can be connected to Claude Desktop or Cursor for natural language operations. Deployment methods support local running, Docker Compose, and an independent FastAPI gateway. The seed account admin/admin123 is the teacher role, and demo/demo123 is the student role. Known limitations include login rate limiting and asynchronous queues by default only supporting a single instance, and images being stored on local disk.