math_tutor_rag

MathMaster Edu é uma plataforma inteligente de gestão de erros voltada para alunos e professores, cujo fluxo central consiste em registrar questões erradas por foto, análise estruturada por IA, verificação matemática, arquivamento vetorial, avaliação de domínio e revisão adaptativa. O projeto adota frontend em Streamlit e gateway FastAPI, com backend usando SQLAlchemy para gerenciar dados em SQLite/MySQL/PostgreSQL, e ChromaDB fornecendo capacidade de recuperação vetorial. As principais funcionalidades incluem: registro de questões por foto com IA, que reconhece questões manuscritas por meio de modelo visual de grande escala e gera pontos de exame, explicação passo a passo, resposta, dificuldade, motivos de erro e questões variantes; abstração de múltiplos provedores de modelo, permitindo alternar entre SiliconFlow, Qwen, Zhipu GLM, DeepSeek, OpenAI, Ollama ou Gemini, com entrada automática em modo de demonstração quando não há chave; recuperação vetorial RAG com suporte a recall de questões similares e busca semântica, com degradação para busca por palavras-chave em caso de falha do banco vetorial; algoritmo de repetição espaçada SM-2 integrado para revisão em estilo flashcard; motor de domínio que combina registros de revisão para gerar perfil de habilidades e plano diário; suporte a múltiplas rodadas de perguntas e explicações para cada questão errada; painel de aprendizado que exibe distribuição de pontos de conhecimento, pontos fracos e tendências de registro; exportação em um clique de folhas de revisão em Word; visão geral de alunos e anotações de questões erradas para professores; calendário de estudos com mapa de calor, tendência de taxa de acerto e sequência de check-ins; grafo de conhecimento apresentando o estado de domínio como rede de coocorrência de tags. Em termos de engenharia, o projeto inclui 287 casos de teste pytest, testes E2E com Playwright, verificação estática com ruff, CI no GitHub Actions (matriz de múltiplas versões do Python, smoke test de inicialização, build Docker), migrações de banco de dados com Alembic, implantação com um clique via Docker Compose, além de avaliação offline de recuperação RAG e avaliação LLM-as-judge do AI Tutor. O projeto também oferece um MCP Server, que pode ser integrado ao Claude Desktop ou Cursor para operações em linguagem natural. Os modos de implantação incluem execução local, Docker Compose e gateway FastAPI independente. As contas semente admin/admin123 têm papel de professor, e demo/demo123 têm papel de aluno. As limitações conhecidas incluem limitação de taxa de login e fila assíncrona com suporte padrão apenas para instância única, armazenamento de imagens em disco local, entre outras.