A comprehensive, secure, and highly optimized math tutoring application built with React + Vite. Features hybrid AI integration (Azure OpenAI + Ollama), multimodal agents for image-based math problem solving, persistent chat sessions, robust security guardrails, and industry-grade latency optimizations.

• Toggle seamlessly between online (Azure OpenAI) and local (Ollama) AI models with streaming responses.
• Multimodal capabilities:
  • MiniCPM: Advanced multimodal vision model designed for parsing handwritten math problems, graphs, and diagram analysis.
  • DeepSeekR1: Specialized reasoning model for chain-of-thought mathematical explanations and complex proofs.

Our system leverages a collaborative agentic architecture:

• TutorAgent: The core conversational orchestrator that guides learning and manages interaction contexts.
• GraderAgent: Automatically evaluates student answers, assessing correctness and identifying partial understanding.
• ProactivePlanner: Dynamically plans out curriculums, generating quizzes and determining the next learning steps based on student mastery.
• KnowledgeGraph: Maps interconnected math topics (Algebra, Geometry, Calculus, etc.) and tracks prerequisite dependencies.
• StudentReportGenerator: Synthesizes learning data into actionable progress reports and mistake analyses.
• VisionModule: Handles image uploads, extracts text, formulas, and visual context allowing the main agent to "see" math problems.

• Math Workspace: Dynamic chat interface supporting LaTeX rendering and syntax highlighting.
• Knowledge Topic Map: Node-link semantic visualization of mathematical topics and student progression.
• Gamification Engine: Engaging leveling system, XP badges, interactive quizzes, and structured lesson plans.
• Student Dashboard: Visual tracking of reports, past mistakes, and performance metrics over time.

• IndexedDB: Persistent local chat sessions and state management.
• Optional Encryption: Securely store student notes and chat state using client-side AES encryption.

Our latest benchmark updates reduced extreme inference latency by up to 60%, bringing responses from ~22s down to 8-12s, with warm requests achieving <10ms speeds.

• Response Caching (LRU): Frequently asked questions hit cache instantly, dropping response times from ~22s down to sub-10ms logic. Query normalization handles fuzzy prompt matches.
• Inference Profiles: Dynamic parsing auto-selects execution strategies (Fast, Balanced, Thorough) adjusting temperature, top_p, top_k, and max token bounds based on query complexity.
• System Prompt Tuning: Precision-focused, concise system commands that significantly reduce the token processing footprint (40% faster).
• Graceful Timeout Management: 25s timeouts with 504 responses eliminate UX hanging during heavy chain-of-thought processes.
• Model Quantization: Support for Q4_0 and Q5_0 quantized variants to drop VRAM requirements (from 16GB to 8-10GB) and boost speed by 15-20% without losing reasoning ability.
• Frontend Optimization: Vite bundles sit at ~1.41 MB delivering sub-100ms initial load speeds. Health API p99 latency guarantees ~2.35ms passthrough responsiveness.

Built with student safety and enterprise-grade security as first-class citizens.

• Zero Client-Side API Keys: All interactions are securely routed through our server/proxy.js backend proxy.
• Prompt Injection Filters: Strict middleware blocks attempts to manipulate instructions or jailbreak AI boundaries.
• Content Safety Categories Filter: Proactive scanning ensures outputs stay clean, blocking inputs & outputs flagged for violence, self-harm, hate speech, cyberbullying, or sexual content.
• Strict Mode Toggle: Granular control setting to enforce intense content moderation policies on both Azure and Ollama streaming.
• Retention Policies: Configurable automated data-deletion workflows respect student privacy metrics after specified days.
• Data Subject Rights: Out-of-the-box UI controls to export, review, and hard-delete all student data in compliance with standard privacy laws.

• Node.js 18+
• (Optional) Ollama installed and running for fully local AI inference mode.
  • Recommended models: minicpm-v and deepseek-r1:7b

npm install

1. Copy .env.example to .env
2. Apply your targeted keys (AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_KEY, etc.)
3. For split deployments, set:

• VITE_API_BASE_URL=https://YOUR_BACKEND_DOMAIN
• CORS_ORIGIN=https://YOUR_GITHUB_USERNAME.github.io

4. Add VITE_LOCAL_VAULT_KEY if you wish to enforce client-side UI encryption.

npm run dev:full

Spins up Vite Frontend (localhost:5173) and Node Proxy Backend (localhost:8787).

Backend only:

npm run dev:backend

Web only:

npm run dev:web

The web app can run independently as long as VITE_API_BASE_URL points to a reachable backend.

npm run build
npm run preview

Deploy the dist/ directory directly to GitHub Pages, Vercel, or any standard static infrastructure.

1. Deploy backend (server/proxy.js) to a Node host (Render/Railway/Azure/etc.) with your server-side env vars.
2. Set backend CORS to your Pages domain:

• CORS_ORIGIN=https://YOUR_GITHUB_USERNAME.github.io

3. In GitHub repository settings, add secret:

• VITE_API_BASE_URL=https://YOUR_BACKEND_DOMAIN

4. Build for Pages locally (optional verification):

npm run build:pages

5. Push to main. The included workflow at .github/workflows/deploy-pages.yml publishes frontend to GitHub Pages.

Incorporate massive course materials and PDF textbooks by leveraging RAG capabilities. Setup AZURE_SEARCH_ENDPOINT & indices in your .env. When active, top vector matches inject into prompts granting the TutorAgent textbook recall without hallucinatory derivations.