v2

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies for sentence-transformers and OCR
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY src/ ./src/
+COPY ../knowledge_base.py ./knowledge_base.py
+
+# Non-root user for security
+RUN useradd --create-home appuser && chown -R appuser /app
+USER appuser
+
+EXPOSE 8080
+
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080"]

__init__.py

@@ -0,0 +1 @@
+# Backend package

requirements.txt

@@ -0,0 +1,54 @@
+# Core LangChain
+langchain>=0.2.0,<0.3.0
+langchain-community>=0.2.0,<0.3.0
+langchain-core>=0.2.0,<0.3.0
+langchain-text-splitters>=0.2.0,<0.3.0
+langchain-groq>=0.1.0
+langchain-huggingface>=0.0.3
+langchain-google-genai>=1.0.6
+google-generativeai>=0.5.4
+
+# Vector DB
+chromadb>=0.4.0
+faiss-cpu>=1.7.4
+
+# Embeddings — pinned for meta-tensor safety on Python 3.11 / CPU
+sentence-transformers==2.7.0
+transformers==4.40.2
+torch==2.2.2
+tokenizers>=0.19.0,<0.20.0
+huggingface-hub>=0.23.0,<0.24.0
+accelerate>=0.29.0
+
+# Data processing
+unstructured>=0.10.0
+pypdf>=3.0.0
+
+# Database (memory)
+pymongo>=4.0.0
+motor>=3.0.0
+
+# Math
+sympy>=1.12
+numpy>=1.24.0,<2.0.0
+matplotlib>=3.7.0
+scipy>=1.11.0
+
+# API Framework
+fastapi>=0.111.0
+uvicorn>=0.29.0
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+
+# Utilities
+python-dotenv>=1.0.0
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+pillow>=10.0.0
+pytesseract>=0.3.10
+plotly>=5.0.0
+
+# Testing (dev)
+pytest>=7.0.0
+pytest-cov>=4.0.0
+httpx>=0.27.0

src/__init__.py

@@ -0,0 +1 @@
+# Backend source package

src/api/__init__.py

@@ -0,0 +1 @@
+# API package

src/api/v1/__init__.py

@@ -0,0 +1 @@
+# API v1 package

src/api/v1/chat.py

@@ -0,0 +1,178 @@
+"""
+Chat API — /api/v1/chat endpoint for math question answering.
+
+Provides a non-streaming POST endpoint that processes math queries
+through the MathAIEngine (RAG + symbolic math + LLM with fallback).
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, UploadFile, File, Form
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from backend.src.services.llm_service import MathAIEngine
+from backend.src.services.vector_service import build_pipeline
+from backend.src.services.gemini_service import GeminiVisionService
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.api.chat")
+
+router = APIRouter(prefix="/api/v1", tags=["chat"])
+
+
+# ── Request / Response Models ──────────────────────────────────────────
+
+class ChatRequest(BaseModel):
+    """Request body for the chat endpoint."""
+    query: str = Field(..., min_length=1, max_length=2000, description="Math question to solve")
+    session_id: str = Field(default="default", description="Session ID for chat history")
+    class_level: Optional[str] = Field(default=None, description="Student class level (e.g., '10', 'JEE')")
+
+
+class ChatResponse(BaseModel):
+    """Response body from the chat endpoint."""
+    answer: str
+    sources: list = []
+    symbolic_hint: Optional[str] = None
+    session_id: str
+    context_docs: int = 0
+
+
+class HistoryResponse(BaseModel):
+    """Response body for chat history endpoint."""
+    session_id: str
+    messages: list
+
+
+class VisionResponse(BaseModel):
+    """Response body for the vision extraction endpoint."""
+    extracted_math: str
+    solution: Optional[str] = None
+
+
+# ── Endpoints ──────────────────────────────────────────────────────────
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """Process a math question and return a step-by-step solution.
+
+    The query flows through:
+    1. Symbolic math verification (SymPy)
+    2. Vector store retrieval (ChromaDB/FAISS)
+    3. Chat history injection
+    4. LLM call with automatic model fallback
+    """
+    try:
+        store = build_pipeline()
+        engine = MathAIEngine(vector_store=store, session_id=request.session_id)
+        result = engine.query(request.query)
+        return ChatResponse(**result)
+    except Exception as e:
+        logger.error(f"Chat endpoint error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/chat/stream")
+async def chat_stream(request: ChatRequest):
+    """Stream a math solution token-by-token using SSE.
+    
+    Requires USE_GEMINI=true to function correctly.
+    """
+    if not settings.use_gemini:
+        raise HTTPException(status_code=400, detail="Streaming requires Gemini API to be enabled.")
+
+    from backend.src.services.gemini_service import GeminiService
+    from backend.src.services.memory_service import MongoDBChatMemory
+
+    try:
+        # We manually orchestrate the context retrieval for streaming
+        store = build_pipeline()
+        engine = MathAIEngine(vector_store=store, session_id=request.session_id)
+        
+        # 1. Get context and history
+        source_docs, context = engine._retrieve_context(request.query)
+        chat_history = engine.memory.get_langchain_messages(limit=4)
+        engine.memory.add_message("human", request.query)
+
+        gemini = GeminiService()
+
+        async def generate():
+            full_response = ""
+            try:
+                async for chunk in gemini.stream(request.query, context=context, chat_history=chat_history):
+                    full_response += chunk
+                    # Format as SSE
+                    yield f"data: {chunk}\n\n"
+                
+                # Save full response to memory after streaming completes
+                engine.memory.add_message("assistant", full_response)
+                yield "data: [DONE]\n\n"
+            except Exception as e:
+                logger.error(f"Streaming error: {e}")
+                yield f"data: ⚠️ Streaming error: {e}\n\n"
+                yield "data: [DONE]\n\n"
+
+        return StreamingResponse(generate(), media_type="text/event-stream")
+
+    except Exception as e:
+        logger.error(f"Chat stream endpoint error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/vision/extract", response_model=VisionResponse)
+async def extract_math_from_image(file: UploadFile = File(...), solve: bool = Form(False)):
+    """Extract math from an uploaded image using Gemini Vision."""
+    if not settings.use_gemini:
+        raise HTTPException(status_code=400, detail="Vision extraction requires Gemini API.")
+
+    try:
+        image_bytes = await file.read()
+        vision_service = GeminiVisionService()
+        
+        if solve:
+            result = vision_service.extract_and_solve(image_bytes, mime_type=file.content_type)
+            return VisionResponse(
+                extracted_math=result["extracted"],
+                solution=result["solution"]
+            )
+        else:
+            extracted = vision_service.extract_math_from_image(image_bytes, mime_type=file.content_type)
+            return VisionResponse(extracted_math=extracted)
+            
+    except Exception as e:
+        logger.error(f"Vision endpoint error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/history/{session_id}", response_model=HistoryResponse)
+async def get_history(session_id: str):
+    """Get chat history for a given session."""
+    try:
+        engine = MathAIEngine(session_id=session_id)
+        history = engine.get_history()
+        # Convert MongoDB ObjectId to string for JSON serialization
+        messages = []
+        for msg in history:
+            messages.append({
+                "role": msg.get("role", "unknown"),
+                "content": msg.get("content", ""),
+                "timestamp": str(msg.get("timestamp", "")),
+            })
+        return HistoryResponse(session_id=session_id, messages=messages)
+    except Exception as e:
+        logger.error(f"History endpoint error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/history/{session_id}")
+async def clear_history(session_id: str):
+    """Clear chat history for a given session."""
+    try:
+        engine = MathAIEngine(session_id=session_id)
+        engine.clear_memory()
+        return {"status": "ok", "message": f"History cleared for session {session_id}"}
+    except Exception as e:
+        logger.error(f"Clear history error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

src/config.py

@@ -0,0 +1,196 @@
+"""
+Application configuration — Pydantic Settings loaded from environment variables.
+
+All configuration values are centralized here. Modules import from this file
+instead of reading os.environ directly. This is the single source of truth
+for all runtime configuration across the backend.
+"""
+
+import os
+from pathlib import Path
+from typing import List
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Ensure .env is loaded for local development
+from dotenv import load_dotenv
+load_dotenv(dotenv_path=Path(__file__).resolve().parent.parent.parent.parent / ".env", override=True)
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables and .env file."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # ── LLM Configuration ──────────────────────────────────────────────
+    groq_api_key: str = ""
+    llm_model: str = "llama-3.3-70b-versatile"
+    groq_model_fallbacks: List[str] = [
+        "llama-3.3-70b-versatile",
+        "llama3-8b-8192",
+        "mixtral-8x7b-32768",
+    ]
+
+    # ── Gemini Configuration ───────────────────────────────────────────
+    gemini_api_key: str = ""
+    use_gemini: bool = True  # Feature flag: True = Gemini primary, False = Groq
+    gemini_primary_model: str = "gemini-2.0-flash"
+    gemini_fallback_model: str = "gemini-1.5-flash"
+    gemini_vision_model: str = "gemini-2.0-flash"
+    gemini_temperature: float = 0.1
+    gemini_max_tokens: int = 2048
+
+    # ── Embeddings ─────────────────────────────────────────────────────
+    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+
+    # ── Vector Database ────────────────────────────────────────────────
+    vector_db_type: str = "chroma"
+    chroma_persist_dir: str = "./chroma_db"
+    faiss_index_path: str = "./faiss_index"
+    top_k_results: int = 5
+    chunk_size: int = 1000
+    chunk_overlap: int = 200
+    collection_name: str = "math_knowledge_base"
+
+    # ── MongoDB (Chat Memory) ──────────────────────────────────────────
+    mongodb_uri: str = ""
+    mongodb_db_name: str = "math_assistant"
+    mongodb_collection: str = "chat_history"
+
+    # ── Server ─────────────────────────────────────────────────────────
+    host: str = "0.0.0.0"
+    port: int = 8080
+    environment: str = "development"
+    log_level: str = "INFO"
+
+
+# Singleton settings instance
+settings = Settings()
+
+
+# ── System Prompt Template ─────────────────────────────────────────────
+# Extracted from main.py L404-L522. This is the master prompt template
+# used by MathAIEngine to instruct the LLM on response format.
+
+SYSTEM_TEMPLATE = """You are an Indian mathematics teacher writing on a whiteboard.
+
+⚠️ NON-MATH QUESTIONS:
+If NOT about mathematics → reply ONLY: "❌ I only teach math! Ask me any math problem."
+Stop immediately. Nothing else.
+
+════════════════════════════════════════
+THE GOLDEN RULE — READ THIS FIRST:
+════════════════════════════════════════
+
+NEVER write paragraphs. NEVER write long sentences explaining theory.
+Write SHORT lines. Like a teacher writing on a board.
+Every line = one idea. One calculation. One small result.
+If a student can't follow in 5 seconds → you wrote too much.
+
+WRONG (too much theory, paragraph style):
+"The Commutative Property of Addition states that when we add numbers,
+the order does not matter. This means that 3+4 gives the same result
+as 4+3, which we can verify by counting on a number line..."
+
+RIGHT (whiteboard style):
+Step 1 — Check: does order matter in addition?
+   3 + 4 = 7
+   4 + 3 = 7  ← same answer!
+   ✓ Yes — order doesn't matter. This is called Commutative Property.
+
+════════════════════════════════════════
+FORMAT — FOLLOW EXACTLY EVERY TIME:
+════════════════════════════════════════
+
+[One short opening — max 1 line. Like reading the problem aloud.]
+"Okay, quadratic equation. Let's use the formula."
+"Right — we need HCF of two numbers."
+"Alright, let's integrate this step by step."
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Question: [restate question clearly]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Step 1 — [title: what and why, max 1 line]
+   [calculation line 1]
+   [calculation line 2]
+   [short teacher note if needed — max 1 line]
+
+Step 2 — [title]
+   [calculation]
+   [result]
+
+[only as many steps as needed — no fake steps]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Answer: [final answer]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[One closing line max — "Key thing: watch the sign here!" or "Make sense?"]
+
+════════════════════════════════════════
+INSIDE EACH STEP — RULES:
+════════════════════════════════════════
+
+✅ DO write like this:
+   a = 2, b = 5, c = -3
+   b² - 4ac = 25 - 4(2)(-3) = 25 + 24 = 49   ← careful: minus×minus = plus!
+   √49 = 7   ← clean number, good sign!
+   x = (-5 ± 7) / 4
+
+✅ DO add ONE short teacher reaction inline:
+   "← careful here"   "← minus × minus = plus!"   "← nice, simplifies!"
+   "← most students miss this"   "← remember this!"
+
+❌ NEVER write:
+   - Paragraphs or long sentences
+   - Theory blocks explaining what a property IS
+   - Repeated explanations of the same idea
+   - More than 1 line of teacher commentary per step
+   - Sentences like "In this case, we can see that..." or "This demonstrates..."
+   - Definitions ("The quadratic formula is used when...")
+   - History or background ("This property was discovered...")
+
+════════════════════════════════════════
+DETECT LEVEL — CHANGE DEPTH NOT STYLE:
+════════════════════════════════════════
+
+Class 1–5:
+→ Ultra simple. Real objects. ("3 apples + 4 apples = 7 apples")
+→ No jargon. Max 3 steps.
+→ Lots of ✓ and encouragement inline.
+
+Class 6–8:
+→ Short friendly lines. Explain WHY in 3-4 words inline.
+→ "← because negative × negative = positive"
+
+Class 9–10:
+→ Full working, every line shown.
+→ One inline note on common exam mistake.
+→ "← board exams always ask this"
+
+Class 11–12:
+→ State theorem/formula name once, then just use it.
+→ Show every substitution clearly.
+
+JEE Advanced:
+→ Full clean solution first.
+→ Then add:
+   💡 Key Insight: [one line — the clever observation]
+   ⏱️ Exam Tip: [one line — what to write quickly]
+
+════════════════════════════════════════
+SYMBOLS — STRICT:
+════════════════════════════════════════
+
+→ USE LaTeX math mode ($...$ for inline, $$...$$ for block) for all mathematical expressions.
+→ Example: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$
+→ Use proper LaTeX symbols (e.g. \sqrt, \pi, \pm, \int)
+→ Hindi/Hinglish question → answer in same language
+
+Context from knowledge base:
+{context}
+"""

src/main.py

@@ -0,0 +1,108 @@
+"""
+FastAPI Application — Advanced Mathematics Assistant Backend.
+
+This is the main entry point for the backend API server.
+Run with: uvicorn backend.src.main:app --host 0.0.0.0 --port 8080
+"""
+
+import logging
+import time
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.src.config import settings
+from backend.src.api.v1.chat import router as chat_router
+
+# ── Logging Setup ──────────────────────────────────────────────────────
+logging.basicConfig(
+    level=getattr(logging, settings.log_level.upper(), logging.INFO),
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger("math_assistant.app")
+
+
+# ── Application Lifespan ──────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup and shutdown events for the FastAPI application."""
+    logger.info("🚀 Starting Advanced Mathematics Assistant API...")
+    logger.info(f"   Environment: {settings.environment}")
+    logger.info(f"   LLM Model: {settings.llm_model}")
+    logger.info(f"   Vector DB: {settings.vector_db_type}")
+
+    # Pre-build knowledge base on startup (optional, lazy by default)
+    # Uncomment the following to eagerly build on startup:
+    # from backend.src.services.vector_service import build_pipeline
+    # build_pipeline()
+
+    yield  # Application is running
+
+    logger.info("🛑 Shutting down Advanced Mathematics Assistant API.")
+
+
+# ── FastAPI App ────────────────────────────────────────────────────────
+app = FastAPI(
+    title="Advanced Mathematics Assistant API",
+    description=(
+        "AI-powered math tutoring API for Indian school students (Class 6-12 + JEE). "
+        "Uses RAG retrieval, SymPy symbolic computation, and LLM-based step-by-step solutions."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# ── CORS Middleware ────────────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:3000",      # React dev server
+        "http://localhost:5173",      # Vite dev server
+        "http://localhost:8501",      # Streamlit
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routes ─────────────────────────────────────────────────────────────
+app.include_router(chat_router)
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint — returns API status and knowledge base info.
+
+    Returns HTTP 200 with:
+    - status: "ok"
+    - environment: current environment
+    - kb_docs: number of indexed knowledge base documents (0 if not yet built)
+    """
+    kb_docs = 0
+    try:
+        from backend.src.services.vector_service import _PIPELINE_CACHE
+        store = _PIPELINE_CACHE.get("store")
+        if store:
+            kb_docs = store.get_document_count()
+    except Exception:
+        pass
+
+    return {
+        "status": "ok",
+        "environment": settings.environment,
+        "version": "1.0.0",
+        "kb_docs": kb_docs,
+        "llm_model": settings.llm_model,
+        "vector_db": settings.vector_db_type,
+    }
+
+
+@app.get("/")
+async def root():
+    """Root endpoint — redirect info."""
+    return {
+        "message": "Advanced Mathematics Assistant API",
+        "docs": "/docs",
+        "health": "/health",
+    }

src/math/__init__.py

@@ -0,0 +1 @@
+# Math modules package

src/math/graph_utils.py

@@ -0,0 +1,115 @@
+"""
+Graph Utilities — Safe expression evaluation and OCR text extraction.
+
+Contains:
+- _safe_evaluate_expression: SymPy-based safe math evaluator (Phase 0 security fix)
+- ocr_extract_text: Tesseract OCR for math image extraction
+
+Extracted from main.py L815-L904 (Phase 0 security-fixed version).
+"""
+
+import re
+import os
+import logging
+from typing import Optional
+
+logger = logging.getLogger("math_assistant.graph")
+
+
+def safe_evaluate_expression(expr_str: str, x_array):
+    """Safely evaluate a mathematical expression string over a numpy array.
+
+    Uses SymPy's sympify() to parse the expression (rejecting arbitrary Python)
+    and lambdify() to convert it to a numpy-callable function. This is safe
+    because sympify() only understands mathematical syntax, not arbitrary code.
+
+    Args:
+        expr_str: Mathematical expression string (e.g., "sin(x)", "x**2 + 1").
+        x_array: numpy array of x values to evaluate the expression over.
+
+    Returns:
+        numpy array of y values.
+
+    Raises:
+        ValueError: If the expression contains disallowed constructs.
+        sympy.SympifyError: If the expression cannot be parsed as math.
+    """
+    import sympy as sp
+    import numpy as np
+
+    # Reject expressions containing dangerous patterns before parsing
+    _BLOCKED_PATTERNS = [
+        "__", "import", "exec", "eval", "compile", "open", "getattr",
+        "setattr", "delattr", "globals", "locals", "vars", "dir",
+        "breakpoint", "exit", "quit", "input", "print", "os.",
+        "sys.", "subprocess", "shutil", "pathlib",
+    ]
+    expr_lower = expr_str.lower().replace(" ", "")
+    for pattern in _BLOCKED_PATTERNS:
+        if pattern in expr_lower:
+            raise ValueError(f"Blocked: expression contains disallowed pattern '{pattern}'")
+
+    # Replace caret with power operator
+    sanitized = re.sub(r'\^', '**', expr_str.strip())
+
+    # Define allowed SymPy symbols and functions for parsing
+    x = sp.Symbol("x")
+    _local_dict = {
+        "x": x, "e": sp.E, "pi": sp.pi,
+        "sin": sp.sin, "cos": sp.cos, "tan": sp.tan,
+        "exp": sp.exp, "log": sp.log, "ln": sp.log,
+        "sqrt": sp.sqrt, "abs": sp.Abs,
+        "arcsin": sp.asin, "arccos": sp.acos, "arctan": sp.atan,
+        "asin": sp.asin, "acos": sp.acos, "atan": sp.atan,
+        "sinh": sp.sinh, "cosh": sp.cosh, "tanh": sp.tanh,
+        "sec": sp.sec, "csc": sp.csc, "cot": sp.cot,
+        "ceiling": sp.ceiling, "floor": sp.floor,
+    }
+
+    # Parse through SymPy — rejects arbitrary Python code
+    sym_expr = sp.sympify(sanitized, locals=_local_dict)
+
+    # Convert to numpy-callable function — safe, no code execution
+    f = sp.lambdify(x, sym_expr, modules=["numpy"])
+    y = f(x_array)
+
+    # Ensure result is array (handles constant expressions like "5" or "pi")
+    if not hasattr(y, "__len__"):
+        y = np.full_like(x_array, float(y))
+
+    return y
+
+
+def ocr_extract_text(image) -> str:
+    """Extract text from an image using Tesseract OCR.
+
+    Args:
+        image: PIL Image object.
+
+    Returns:
+        Extracted text string, or error message if OCR fails.
+    """
+    try:
+        import pytesseract
+        from PIL import ImageEnhance as enhance
+
+        # Set tesseract binary path for common install locations
+        for _tess_path in [
+            "/opt/homebrew/bin/tesseract",   # macOS Apple Silicon (brew)
+            "/usr/local/bin/tesseract",       # macOS Intel (brew)
+            "/usr/bin/tesseract",             # Linux
+        ]:
+            if os.path.exists(_tess_path):
+                pytesseract.pytesseract.tesseract_cmd = _tess_path
+                break
+        gray      = image.convert("L")
+        contrast  = enhance.Contrast(gray).enhance(2.0)
+        sharpened = enhance.Sharpness(contrast).enhance(2.0)
+        text = pytesseract.image_to_string(sharpened, config='--psm 6').strip()
+        text = ' '.join(text.replace('\n', ' ').split())
+        return text
+    except ImportError:
+        return "ERROR_NO_PYTESSERACT"
+    except Exception as e:
+        logger.error(f"OCR error: {e}")
+        return ""

src/math/knowledge_indexer.py

@@ -0,0 +1,290 @@
+"""
+Knowledge Base Indexing Pipeline — Data loading, preprocessing, and chunking.
+
+Extracted from main.py L80-L270. Contains:
+- MathDataLoader: loads NCERT knowledge base from knowledge_base.py
+- MathDataPreprocessor: cleans, deduplicates, detects topics
+- MathTextSplitter: splits documents into chunks for vector indexing
+"""
+
+import re
+import hashlib
+import logging
+from typing import Dict, List
+from pathlib import Path
+
+logger = logging.getLogger("math_assistant.indexer")
+
+try:
+    from langchain_core.documents import Document
+except ImportError:
+    try:
+        from langchain.schema import Document
+    except ImportError:
+        class Document:
+            def __init__(self, page_content: str, metadata: dict = None):
+                self.page_content = page_content
+                self.metadata = metadata or {}
+
+
+class MathDataLoader:
+    """Load NCERT math knowledge base from hardcoded knowledge_base.py."""
+
+    def load_builtin_knowledge(self) -> List[Document]:
+        """Load the hand-curated NCERT knowledge base.
+
+        Returns:
+            List of Document objects with topic metadata.
+        """
+        # Import from the project root knowledge_base.py
+        import sys
+        project_root = str(Path(__file__).resolve().parent.parent.parent.parent)
+        if project_root not in sys.path:
+            sys.path.insert(0, project_root)
+
+        from knowledge_base import MATH_KNOWLEDGE_BASE, CLASS_EXAMPLES
+        documents = []
+
+        # Process topic documents
+        for topic, sections in MATH_KNOWLEDGE_BASE.items():
+            if isinstance(sections, dict):
+                for sub_topic, content in sections.items():
+                    if isinstance(content, str) and len(content.strip()) > 50:
+                        documents.append(Document(
+                            page_content=content,
+                            metadata={"source": "builtin_kb", "topic": topic,
+                                      "sub_topic": sub_topic}
+                        ))
+                    elif isinstance(content, dict):
+                        for k, v in content.items():
+                            if isinstance(v, str) and len(v.strip()) > 50:
+                                documents.append(Document(
+                                    page_content=v,
+                                    metadata={"source": "builtin_kb", "topic": topic,
+                                              "sub_topic": f"{sub_topic}/{k}"}
+                                ))
+            elif isinstance(sections, str) and len(sections.strip()) > 50:
+                documents.append(Document(
+                    page_content=sections,
+                    metadata={"source": "builtin_kb", "topic": topic}
+                ))
+
+        # Process class examples
+        for class_id, chapters in CLASS_EXAMPLES.items():
+            if isinstance(chapters, dict):
+                for chapter, questions in chapters.items():
+                    if isinstance(questions, list):
+                        for q in questions:
+                            if isinstance(q, dict):
+                                text = q.get("question", "") + "\n" + q.get("solution", "")
+                                if len(text.strip()) > 50:
+                                    documents.append(Document(
+                                        page_content=text,
+                                        metadata={"source": "ncert_examples",
+                                                  "class": class_id,
+                                                  "chapter": chapter,
+                                                  "topic": q.get("topic", "general_math")}
+                                    ))
+                    elif isinstance(questions, str) and len(questions.strip()) > 50:
+                        documents.append(Document(
+                            page_content=questions,
+                            metadata={"source": "ncert_examples",
+                                      "class": class_id, "chapter": chapter}
+                        ))
+
+        logger.info(f"Loaded {len(documents)} documents from built-in knowledge base")
+        return documents
+
+    def load_pdf(self, pdf_path: str) -> List[Document]:
+        """Load a single PDF file."""
+        try:
+            from langchain_community.document_loaders import PyPDFLoader
+            docs = PyPDFLoader(pdf_path).load()
+            logger.info(f"Loaded {len(docs)} pages from: {pdf_path}")
+            return docs
+        except Exception as e:
+            logger.error(f"Failed to load PDF {pdf_path}: {e}")
+            return []
+
+    def load_pdfs_from_directory(self, dir_path: str) -> List[Document]:
+        """Load all PDFs from a directory."""
+        try:
+            from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader
+            docs = DirectoryLoader(dir_path, glob="**/*.pdf", loader_cls=PyPDFLoader).load()
+            logger.info(f"Loaded {len(docs)} documents from: {dir_path}")
+            return docs
+        except Exception as e:
+            logger.error(f"Failed to load PDFs from {dir_path}: {e}")
+            return []
+
+    def load_web_pages(self, urls: List[str]) -> List[Document]:
+        """Load content from web URLs."""
+        from langchain_community.document_loaders import WebBaseLoader
+        docs = []
+        for url in urls:
+            try:
+                loader = WebBaseLoader(url)
+                loader.requests_kwargs = {"timeout": 15}
+                docs.extend(loader.load())
+                logger.info(f"Loaded: {url}")
+            except Exception as e:
+                logger.warning(f"Failed URL {url}: {e}")
+        return docs
+
+    def load_text_file(self, file_path: str) -> List[Document]:
+        """Load a text or markdown file."""
+        try:
+            if file_path.endswith(".md"):
+                from langchain_community.document_loaders import UnstructuredMarkdownLoader
+                loader = UnstructuredMarkdownLoader(file_path)
+            else:
+                from langchain_community.document_loaders import TextLoader
+                loader = TextLoader(file_path, encoding="utf-8")
+            docs = loader.load()
+            logger.info(f"Loaded: {file_path}")
+            return docs
+        except Exception as e:
+            logger.error(f"Failed to load {file_path}: {e}")
+            return []
+
+    def load_all(self, pdf_paths=None, urls=None, text_paths=None, pdf_directory=None) -> List[Document]:
+        """Load all data sources: builtin KB + PDFs + URLs + text files."""
+        import os
+        all_docs = self.load_builtin_knowledge()
+        if pdf_paths:
+            for p in pdf_paths:
+                all_docs.extend(self.load_pdf(p))
+        if pdf_directory and os.path.exists(pdf_directory):
+            all_docs.extend(self.load_pdfs_from_directory(pdf_directory))
+        if urls:
+            all_docs.extend(self.load_web_pages(urls))
+        if text_paths:
+            for p in text_paths:
+                all_docs.extend(self.load_text_file(p))
+        logger.info(f"Total documents loaded: {len(all_docs)}")
+        return all_docs
+
+
+class MathDataPreprocessor:
+    """Clean, deduplicate, and enrich math documents with metadata."""
+
+    TOPIC_KEYWORDS: Dict[str, List[str]] = {
+        "calculus":       ["derivative", "integral", "differentiate", "integrate", "limit", "continuity", "taylor"],
+        "linear_algebra": ["matrix", "vector", "eigenvalue", "determinant", "rank", "span", "basis"],
+        "statistics":     ["probability", "distribution", "mean", "variance", "regression", "hypothesis"],
+        "algebra":        ["polynomial", "equation", "quadratic", "factor", "root", "logarithm", "exponent"],
+        "trigonometry":   ["sine", "cosine", "tangent", "angle", "radian", "unit circle", "trig"],
+        "discrete_math":  ["graph", "combinatorics", "permutation", "combination", "modular", "prime"],
+        "geometry":       ["triangle", "circle", "area", "volume", "perimeter", "pythagorean", "coordinate"],
+        "number_theory":  ["prime", "divisor", "gcd", "lcm", "modular", "congruence", "integer"],
+    }
+
+    def __init__(self):
+        self._seen_hashes: set = set()
+
+    def _clean(self, text: str) -> str:
+        text = re.sub(r"\n{3,}", "\n\n", text)
+        text = re.sub(r"[ \t]{2,}", " ", text)
+        text = re.sub(r"Page\s+\d+\s+of\s+\d+", "", text, flags=re.IGNORECASE)
+        text = re.sub(r"https?://\S+", "[URL]", text)
+        text = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", text)
+        replacements = {
+            "\u2019": "'", "\u201c": '"', "\u201d": '"',
+            "\u2013": "-", "\u2014": "--", "\u00a0": " ",
+            "\u03c0": "pi", "\u221e": "infinity",
+            "\u2264": "<=", "\u2265": ">="
+        }
+        for old, new in replacements.items():
+            text = text.replace(old, new)
+        return text.strip()
+
+    def _detect_topic(self, text: str) -> str:
+        tl = text.lower()
+        scores = {t: sum(1 for kw in kws if kw in tl) for t, kws in self.TOPIC_KEYWORDS.items()}
+        scores = {k: v for k, v in scores.items() if v > 0}
+        return max(scores, key=scores.get) if scores else "general_math"
+
+    def _difficulty(self, text: str) -> str:
+        adv = ["eigenvalue", "differential equation", "fourier", "laplace", "manifold", "tensor"]
+        mid = ["derivative", "integral", "matrix", "probability", "polynomial", "logarithm"]
+        tl = text.lower()
+        if sum(1 for t in adv if t in tl) >= 2: return "advanced"
+        if sum(1 for t in mid if t in tl) >= 2: return "intermediate"
+        return "beginner"
+
+    def preprocess_document(self, doc):
+        text = doc.page_content
+        if len(text.strip()) < 50:
+            return None
+        text = self._clean(text)
+        h = hashlib.md5(text.strip().lower().encode()).hexdigest()
+        if h in self._seen_hashes:
+            return None
+        self._seen_hashes.add(h)
+        meta = doc.metadata.copy()
+        meta.update({
+            "topic":        meta.get("topic") or self._detect_topic(text),
+            "difficulty":   self._difficulty(text),
+            "char_count":   len(text),
+            "word_count":   len(text.split()),
+            "content_hash": h,
+        })
+        return Document(page_content=text, metadata=meta)
+
+    def preprocess_documents(self, documents):
+        logger.info(f"Preprocessing {len(documents)} documents...")
+        self._seen_hashes.clear()
+        processed = [r for doc in documents if (r := self.preprocess_document(doc)) is not None]
+        logger.info(f"Done: {len(processed)} kept, {len(documents)-len(processed)} skipped")
+        return processed
+
+
+class MathTextSplitter:
+    """Split documents into overlapping chunks optimized for math content."""
+
+    def __init__(self, chunk_size: int = 1000, chunk_overlap: int = 200):
+        from langchain_text_splitters import RecursiveCharacterTextSplitter, MarkdownHeaderTextSplitter
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self._markdown_splitter = MarkdownHeaderTextSplitter(
+            headers_to_split_on=[("#", "h1"), ("##", "h2"), ("###", "h3")],
+            strip_headers=False,
+        )
+        self._text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=["\n## ", "\n### ", "\n\n", "\n", ". ", " "],
+        )
+
+    def split_document(self, doc) -> list:
+        """Split a single document into chunks with metadata preserved."""
+        try:
+            md_chunks = self._markdown_splitter.split_text(doc.page_content)
+            if len(md_chunks) > 1:
+                chunks = []
+                for mc in md_chunks:
+                    sub_chunks = self._text_splitter.split_text(mc.page_content)
+                    for sc in sub_chunks:
+                        meta = {**doc.metadata, **mc.metadata}
+                        chunks.append(Document(page_content=sc, metadata=meta))
+                final = chunks
+            else:
+                texts = self._text_splitter.split_text(doc.page_content)
+                final = [Document(page_content=t, metadata=doc.metadata.copy()) for t in texts]
+        except Exception:
+            texts = self._text_splitter.split_text(doc.page_content)
+            final = [Document(page_content=t, metadata=doc.metadata.copy()) for t in texts]
+
+        for i, chunk in enumerate(final):
+            chunk.metadata["chunk_index"] = i
+            chunk.metadata["total_chunks"] = len(final)
+
+        return final
+
+    def split_documents(self, documents) -> list:
+        """Split multiple documents and flatten into a single list."""
+        all_chunks = []
+        for doc in documents:
+            all_chunks.extend(self.split_document(doc))
+        logger.info(f"Split {len(documents)} documents into {len(all_chunks)} chunks")
+        return all_chunks

src/math/symbolic_engine.py

@@ -0,0 +1,86 @@
+"""
+Symbolic Mathematics Engine — SymPy-based exact computation.
+
+Extracted from main.py L585-L643. Provides differentiation, integration,
+equation solving, simplification, and matrix operations using SymPy.
+All methods are stateless (static) and safe for concurrent use.
+"""
+
+import re
+import ast
+import logging
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger("math_assistant.symbolic")
+
+
+class SymbolicMathEngine:
+    """SymPy-powered symbolic math solver for exact computation."""
+
+    @staticmethod
+    def differentiate(expression: str, variable: str = "x") -> Optional[str]:
+        """Compute the derivative of an expression with respect to a variable."""
+        try:
+            import sympy as sp
+            var = sp.Symbol(variable)
+            expr = sp.sympify(re.sub(r'\^', '**', expression.strip()))
+            return f"d/d{variable}[{expression}] = {sp.simplify(sp.diff(expr, var))}"
+        except Exception:
+            return None
+
+    @staticmethod
+    def integrate(expression: str, variable: str = "x") -> Optional[str]:
+        """Compute the indefinite integral of an expression."""
+        try:
+            import sympy as sp
+            var = sp.Symbol(variable)
+            expr = sp.sympify(re.sub(r'\^', '**', expression.strip()))
+            return f"integral({expression}) d{variable} = {sp.integrate(expr, var)} + C"
+        except Exception:
+            return None
+
+    @staticmethod
+    def solve_equation(equation: str, variable: str = "x") -> Optional[str]:
+        """Solve an equation for a given variable."""
+        try:
+            import sympy as sp
+            var = sp.Symbol(variable)
+            eq_str = re.sub(r'\^', '**', equation.strip())
+            if "=" in eq_str:
+                lhs, rhs = eq_str.split("=", 1)
+                eq = sp.Eq(sp.sympify(lhs), sp.sympify(rhs))
+            else:
+                eq = sp.sympify(eq_str)
+            return f"Solutions for {variable}: {sp.solve(eq, var)}"
+        except Exception:
+            return None
+
+    @staticmethod
+    def try_solve(expression: str) -> Optional[str]:
+        """Attempt to simplify or solve a general expression."""
+        try:
+            import sympy as sp
+            x, y, z, t = sp.symbols('x y z t')
+            expr_str = re.sub(r'\^', '**', expression.strip())
+            result = sp.simplify(sp.sympify(expr_str, locals={
+                'x': x, 'y': y, 'z': z, 't': t,
+                'sin': sp.sin, 'cos': sp.cos, 'exp': sp.exp,
+                'log': sp.log, 'sqrt': sp.sqrt, 'pi': sp.pi}))
+            return str(result)
+        except Exception:
+            return None
+
+    @staticmethod
+    def matrix_operations(matrix_str: str) -> Optional[Dict[str, Any]]:
+        """Compute determinant, rank, eigenvalues, and trace of a matrix."""
+        try:
+            import sympy as sp
+            M = sp.Matrix(ast.literal_eval(matrix_str))
+            return {
+                "determinant": str(M.det()),
+                "rank": M.rank(),
+                "eigenvalues": str(M.eigenvals()),
+                "trace": str(M.trace()),
+            }
+        except Exception:
+            return None

src/services/__init__.py

@@ -0,0 +1 @@
+# Services package

src/services/gemini_service.py

@@ -0,0 +1,233 @@
+"""
+Gemini Service — Google AI Studio integration for math tutoring.
+
+Provides:
+- GeminiService: Text-based math query processing with Gemini 2.0 Flash
+- GeminiVisionService: Image math extraction using Gemini Vision
+- Streaming support for token-by-token SSE delivery
+- Automatic fallback from Gemini 2.0 Flash → Gemini 1.5 Flash on rate limits
+
+Uses Google AI Studio free tier (google-generativeai SDK).
+"""
+
+import re
+import time
+import logging
+import base64
+from typing import Dict, Any, Optional, AsyncGenerator
+
+from backend.src.config import settings, SYSTEM_TEMPLATE
+
+logger = logging.getLogger("math_assistant.gemini")
+
+_GEMINI_CACHE = {}
+
+
+def _get_gemini_model(model_name: str = None):
+    """Get or create a cached Gemini GenerativeModel instance.
+
+    Uses google-generativeai SDK (Google AI Studio free tier).
+    """
+    import google.generativeai as genai
+
+    model_name = model_name or settings.gemini_primary_model
+    if model_name not in _GEMINI_CACHE:
+        api_key = settings.gemini_api_key
+        if not api_key:
+            raise ValueError(
+                "GEMINI_API_KEY not set. Get a free key at https://aistudio.google.com/apikey "
+                "and add it to your .env file."
+            )
+        genai.configure(api_key=api_key)
+        _GEMINI_CACHE[model_name] = genai.GenerativeModel(
+            model_name=model_name,
+            generation_config=genai.GenerationConfig(
+                temperature=settings.gemini_temperature,
+                max_output_tokens=settings.gemini_max_tokens,
+            ),
+        )
+        logger.info(f"Initialized Gemini model: {model_name}")
+    return _GEMINI_CACHE[model_name]
+
+
+class GeminiService:
+    """Google Gemini text-based math query service with automatic fallback."""
+
+    def __init__(self):
+        self.primary_model = settings.gemini_primary_model
+        self.fallback_model = settings.gemini_fallback_model
+
+    def query(self, user_input: str, context: str = "", chat_history: list = None) -> str:
+        """Send a math query to Gemini and return the response.
+
+        Args:
+            user_input: The student's math question.
+            context: RAG-retrieved knowledge base context.
+            chat_history: List of previous messages for context.
+
+        Returns:
+            The LLM response string.
+        """
+        system_text = SYSTEM_TEMPLATE.replace("{context}", context or "")
+
+        # Build conversation parts
+        parts = [system_text + "\n\n"]
+        if chat_history:
+            for msg in chat_history:
+                role = getattr(msg, "type", "human")
+                content = getattr(msg, "content", str(msg))
+                prefix = "Student: " if role == "human" else "Teacher: "
+                parts.append(f"{prefix}{content}\n")
+        parts.append(f"Student: {user_input}\nTeacher: ")
+
+        prompt = "".join(parts)
+
+        # Try primary model, then fallback
+        models_to_try = [self.primary_model, self.fallback_model]
+        last_error = None
+
+        for model_name in models_to_try:
+            model = _get_gemini_model(model_name)
+            for attempt in range(2):
+                try:
+                    response = model.generate_content(prompt)
+
+                    if response.text:
+                        answer = response.text.strip()
+                        if model_name != self.primary_model:
+                            answer = f"*(Using fallback: {model_name})*\n\n" + answer
+                        return answer
+                    else:
+                        # Check for blocked content
+                        if response.prompt_feedback and response.prompt_feedback.block_reason:
+                            raise Exception(f"Content blocked: {response.prompt_feedback.block_reason}")
+                        raise Exception("Empty response from Gemini")
+
+                except Exception as e:
+                    last_error = e
+                    err_str = str(e).lower()
+                    logger.warning(f"Gemini {model_name} attempt {attempt+1} failed: {e}")
+
+                    if "429" in str(e) or "resource_exhausted" in err_str or "quota" in err_str:
+                        logger.info(f"Rate limit on {model_name}, trying fallback...")
+                        time.sleep(1)
+                        break  # Skip to next model
+                    elif "timeout" in err_str or "deadline" in err_str:
+                        time.sleep(1)
+                        continue
+                    else:
+                        break  # Non-retryable
+
+        # All models failed
+        logger.error(f"All Gemini models failed: {last_error}")
+        return f"⚠️ Gemini API error: {last_error}"
+
+    async def stream(self, user_input: str, context: str = "", chat_history: list = None) -> AsyncGenerator[str, None]:
+        """Stream a response token by token for SSE delivery.
+
+        Yields chunks of text as they arrive from Gemini's streaming API.
+        """
+        system_text = SYSTEM_TEMPLATE.replace("{context}", context or "")
+        parts = [system_text + "\n\n"]
+        if chat_history:
+            for msg in chat_history:
+                role = getattr(msg, "type", "human")
+                content = getattr(msg, "content", str(msg))
+                prefix = "Student: " if role == "human" else "Teacher: "
+                parts.append(f"{prefix}{content}\n")
+        parts.append(f"Student: {user_input}\nTeacher: ")
+        prompt = "".join(parts)
+
+        model = _get_gemini_model(self.primary_model)
+        try:
+            response = model.generate_content(prompt, stream=True)
+            for chunk in response:
+                if chunk.text:
+                    yield chunk.text
+        except Exception as e:
+            logger.error(f"Streaming error: {e}")
+            yield f"\n\n⚠️ Streaming error: {e}"
+
+
+class GeminiVisionService:
+    """Gemini Vision for extracting math from images (replaces Tesseract OCR)."""
+
+    def __init__(self):
+        self.model_name = settings.gemini_vision_model
+
+    def extract_math_from_image(self, image_bytes: bytes, mime_type: str = "image/jpeg") -> str:
+        """Extract mathematical content from an image using Gemini Vision.
+
+        Args:
+            image_bytes: Raw image bytes.
+            mime_type: Image MIME type (image/jpeg, image/png, etc.).
+
+        Returns:
+            Extracted mathematical expression or problem text.
+        """
+        import google.generativeai as genai
+
+        model = _get_gemini_model(self.model_name)
+
+        prompt = (
+            "You are a math OCR expert. Extract ALL mathematical content from this image.\n\n"
+            "Rules:\n"
+            "1. Convert handwritten or printed math into clean text.\n"
+            "2. Use standard notation: x², √, π, ±, ∫, Σ, etc.\n"
+            "3. If it's an equation, write it as: equation\n"
+            "4. If it's a word problem, transcribe it exactly.\n"
+            "5. If there are multiple problems, number them.\n"
+            "6. Return ONLY the extracted math — no commentary.\n"
+        )
+
+        try:
+            response = model.generate_content([
+                prompt,
+                {"mime_type": mime_type, "data": image_bytes},
+            ])
+            if response.text:
+                return response.text.strip()
+            return "Could not extract math from image."
+        except Exception as e:
+            logger.error(f"Vision extraction error: {e}")
+            return f"Vision error: {e}"
+
+    def extract_and_solve(self, image_bytes: bytes, mime_type: str = "image/jpeg") -> Dict[str, str]:
+        """Extract math from image and solve it in one call.
+
+        Returns dict with 'extracted' (the raw math) and 'solution' (step-by-step).
+        """
+        import google.generativeai as genai
+
+        model = _get_gemini_model(self.model_name)
+
+        prompt = (
+            "You are an Indian math teacher. Look at this image.\n\n"
+            "Step 1: Extract the math problem from the image.\n"
+            "Step 2: Solve it step-by-step in whiteboard style.\n\n"
+            "Format your response as:\n"
+            "EXTRACTED: [the math problem]\n"
+            "---\n"
+            "SOLUTION:\n[step-by-step solution]\n"
+        )
+
+        try:
+            response = model.generate_content([
+                prompt,
+                {"mime_type": mime_type, "data": image_bytes},
+            ])
+            text = response.text.strip() if response.text else ""
+
+            # Parse response
+            if "EXTRACTED:" in text and "SOLUTION:" in text:
+                parts = text.split("---", 1)
+                extracted = parts[0].replace("EXTRACTED:", "").strip()
+                solution = parts[1].replace("SOLUTION:", "").strip() if len(parts) > 1 else ""
+            else:
+                extracted = ""
+                solution = text
+
+            return {"extracted": extracted, "solution": solution}
+        except Exception as e:
+            logger.error(f"Extract and solve error: {e}")
+            return {"extracted": "", "solution": f"⚠️ Error: {e}"}

src/services/llm_service.py

@@ -0,0 +1,210 @@
+"""
+LLM Service — Gemini (primary) + Groq (fallback) orchestrator.
+
+Phase 2: Gemini Integration.
+- When USE_GEMINI=true (default), queries go through GeminiService.
+- When USE_GEMINI=false or GEMINI_API_KEY is missing, falls back to Groq.
+- _get_llm: Groq LLM factory (preserved for fallback)
+- MathAIEngine: Orchestrates retrieval, symbolic math, and LLM calls.
+"""
+
+import re
+import time
+import logging
+from typing import Dict, Any, Optional, Tuple
+
+from backend.src.config import settings, SYSTEM_TEMPLATE
+from backend.src.math.symbolic_engine import SymbolicMathEngine
+from backend.src.services.memory_service import MongoDBChatMemory
+
+try:
+    from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+except ImportError:
+    from langchain.schema import HumanMessage, AIMessage, SystemMessage
+
+logger = logging.getLogger("math_assistant.llm")
+
+_LLM_CACHE = {}
+
+
+def _get_llm(model=None):
+    """Get or create a cached Groq LLM instance for a given model name."""
+    key = model or settings.groq_model_fallbacks[0]
+    if key not in _LLM_CACHE:
+        from langchain_groq import ChatGroq
+        api_key = settings.groq_api_key
+        if not api_key:
+            raise ValueError("GROQ_API_KEY not set. Add it to your .env file.")
+        logger.info(f"Initializing Groq LLM: {key}")
+        _LLM_CACHE[key] = ChatGroq(
+            groq_api_key=api_key,
+            model_name=key,
+            temperature=0.1,
+            max_tokens=2048,
+        )
+    return _LLM_CACHE[key]
+
+
+class MathAIEngine:
+    """Orchestrates RAG retrieval, symbolic math, and LLM calls for math tutoring."""
+
+    def __init__(self, vector_store=None, session_id: str = "default"):
+        self.llm          = self._init_llm()
+        self.vector_store = vector_store
+        self.memory       = MongoDBChatMemory(session_id=session_id)
+        self.symbolic     = SymbolicMathEngine()
+        self.session_id   = session_id
+
+    def _init_llm(self):
+        """Initialize the primary LLM model."""
+        return _get_llm(settings.groq_model_fallbacks[0])
+
+    def _retrieve_context(self, query: str) -> Tuple[list, str]:
+        """Retrieve relevant documents from the vector store."""
+        if not self.vector_store or not self.vector_store.is_ready():
+            return [], "No knowledge base available. Using general mathematical knowledge."
+        docs = self.vector_store.similarity_search(query, k=3)
+        if not docs:
+            return [], "No specific context found."
+        parts = [f"[Reference {i+1} - {d.metadata.get('topic','math')}]\n{d.page_content}"
+                 for i, d in enumerate(docs)]
+        return docs, "\n\n---\n\n".join(parts)
+
+    def _symbolic_hint(self, query: str) -> Optional[str]:
+        """Try to get a symbolic verification hint for the query."""
+        ql = query.lower()
+        for pattern, action in [
+            (r"(?:differentiate|derivative of|d/dx)\s+(.+?)(?:\s+with respect|\s*$)", "diff"),
+            (r"(?:integrate|integral of)\s+(.+?)(?:\s+with respect|\s+dx|\s*$)", "int"),
+            (r"solve\s+(.+?)\s+(?:for|=)", "solve"),
+        ]:
+            m = re.search(pattern, ql)
+            if m:
+                expr = m.group(1).strip()
+                result = (self.symbolic.differentiate(expr) if action == "diff"
+                          else self.symbolic.integrate(expr) if action == "int"
+                          else self.symbolic.solve_equation(expr))
+                if result:
+                    return f"[Symbolic verification: {result}]"
+        return None
+
+    def query(self, user_input: str) -> Dict[str, Any]:
+        """Process a user math query through the full RAG pipeline.
+
+        Flow: symbolic hint → vector retrieval → chat history →
+              Gemini (primary) or Groq (fallback) → store response.
+        """
+        hint        = self._symbolic_hint(user_input)
+        source_docs, context = self._retrieve_context(user_input)
+        chat_history = self.memory.get_langchain_messages(limit=4)
+
+        # Store human message BEFORE LLM call so history order is correct
+        self.memory.add_message("human", user_input)
+
+        # ── Try Gemini first (Phase 2) ─────────────────────────────────
+        if settings.use_gemini and settings.gemini_api_key:
+            try:
+                from backend.src.services.gemini_service import GeminiService
+                gemini = GeminiService()
+                answer = gemini.query(user_input, context=context, chat_history=chat_history)
+                if answer and not answer.startswith("⚠️"):
+                    self.memory.add_message("assistant", answer)
+                    sources = [{"topic": d.metadata.get("topic", "unknown"),
+                                "source": d.metadata.get("source", "kb"),
+                                "difficulty": d.metadata.get("difficulty", "unknown")}
+                               for d in source_docs]
+                    return {"answer": answer, "sources": sources, "symbolic_hint": hint,
+                            "session_id": self.session_id, "context_docs": len(source_docs)}
+            except Exception as e:
+                logger.warning(f"Gemini failed, falling back to Groq: {e}")
+
+        # ── Groq Fallback ──────────────────────────────────────────────
+        # Build messages list manually — NEVER pass math content through
+        # LangChain format_messages(), because curly braces in math break templates
+        system_text = SYSTEM_TEMPLATE.replace("{context}", context)
+        llm_messages = [SystemMessage(content=system_text)]
+        for msg in chat_history:
+            llm_messages.append(msg)
+        llm_messages.append(HumanMessage(content=user_input))
+
+        # Auto-retry with model fallback
+        answer      = None
+        last_error  = None
+        used_models = []
+        for model_name in settings.groq_model_fallbacks:
+            if model_name in used_models:
+                continue
+            used_models.append(model_name)
+            llm = _get_llm(model_name)
+            for _attempt in range(2):
+                try:
+                    raw = llm.invoke(llm_messages).content
+                    if raw and not any(p in raw.lower() for p in
+                                       ["rate limit", "too many requests", "service unavailable"]):
+                        answer = raw
+                        if model_name != settings.groq_model_fallbacks[0]:
+                            answer = f"*(Using fallback model: {model_name})*\n\n" + answer
+                        break
+                    else:
+                        raise Exception(raw or "Empty response")
+                except Exception as e:
+                    last_error = e
+                    err = str(e).lower()
+                    full_err = str(e)
+                    logger.warning(f"Model {model_name} attempt {_attempt+1} failed: {e}")
+                    if "per day" in full_err or "tokens per day" in full_err:
+                        logger.info(f"Daily limit on {model_name}, trying next model...")
+                        break
+                    elif "429" in full_err or "rate_limit" in err:
+                        time.sleep(2 ** _attempt)
+                        continue
+                    elif "timeout" in err or "connect" in err or "503" in err:
+                        time.sleep(1)
+                        continue
+                    else:
+                        break
+            if answer:
+                break
+
+        if answer is None:
+            full_err = str(last_error)
+            err      = full_err.lower()
+            logger.error(f"LLM failed: [{type(last_error).__name__}] {full_err}")
+
+            if "401" in full_err or "invalid_api_key" in err:
+                answer = "⚠️ Invalid API key. Check GROQ_API_KEY in your .env file."
+            elif "429" in full_err or "rate_limit_exceeded" in err:
+                retry_match = re.search(r'try again in (.+?)\.', full_err)
+                retry_info  = f" Groq says: try again in **{retry_match.group(1)}**." if retry_match else ""
+                if "per day" in full_err or "tokens per day" in full_err or "TPD" in full_err:
+                    answer = (f"⚠️ **Daily token limit reached** (Groq free tier: 100,000 tokens/day).{retry_info}\n\n"
+                              f"To keep using the app now, change your `.env`:\n```\nLLM_MODEL=llama3-8b-8192\n```\n"
+                              f"Then restart Streamlit. The 8B model has a separate 500k/day quota.")
+                else:
+                    answer = f"⚠️ **Rate limit hit** (too many requests per minute).{retry_info} Wait 20–30 seconds and try again."
+            elif "context_length" in err or ("context" in err and "length" in err):
+                answer = "⚠️ Question + context too long. Try a shorter question."
+            elif "connect" in err or "connection" in err:
+                answer = "⚠️ Cannot reach Groq API. Check your internet connection."
+            elif "timeout" in err:
+                answer = "⚠️ Request timed out. Try again."
+            else:
+                answer = f"⚠️ Error ({type(last_error).__name__}): {full_err}"
+
+        self.memory.add_message("assistant", answer)
+
+        sources = [{"topic":      d.metadata.get("topic", "unknown"),
+                    "source":     d.metadata.get("source", "kb"),
+                    "difficulty": d.metadata.get("difficulty", "unknown")}
+                   for d in source_docs]
+
+        return {"answer": answer, "sources": sources, "symbolic_hint": hint,
+                "session_id": self.session_id, "context_docs": len(source_docs)}
+
+    def clear_memory(self):
+        """Clear chat history for this session."""
+        self.memory.clear_history()
+
+    def get_history(self):
+        """Get full chat history for this session."""
+        return self.memory.get_history(limit=50)

src/services/memory_service.py

@@ -0,0 +1,92 @@
+"""
+Chat Memory Service — MongoDB-backed persistent chat history.
+
+Extracted from main.py L525-L582. Provides per-session chat history
+with MongoDB persistence and in-memory fallback when MongoDB is unavailable.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import List, Dict
+
+from backend.src.config import settings
+
+try:
+    from langchain_core.messages import HumanMessage, AIMessage
+except ImportError:
+    from langchain.schema import HumanMessage, AIMessage
+
+logger = logging.getLogger("math_assistant.memory")
+
+
+class MongoDBChatMemory:
+    """Per-session chat memory with MongoDB persistence and in-memory fallback."""
+
+    def __init__(self, session_id: str = "default"):
+        self.session_id = session_id
+        self.collection = None
+        self._memory: List[Dict] = []
+        self._connect()
+
+    def _connect(self):
+        if not settings.mongodb_uri:
+            return
+        try:
+            from pymongo import MongoClient
+            client = MongoClient(settings.mongodb_uri, serverSelectionTimeoutMS=5000)
+            client.admin.command("ping")
+            self.collection = client[settings.mongodb_db_name][settings.mongodb_collection]
+            logger.info("MongoDB connected")
+        except Exception as e:
+            logger.warning(f"MongoDB unavailable ({e}), using in-memory history")
+
+    def add_message(self, role: str, content: str):
+        """Add a message to chat history."""
+        msg = {
+            "session_id": self.session_id,
+            "role": role,
+            "content": content,
+            "timestamp": datetime.now(timezone.utc),
+        }
+        if self.collection is not None:
+            try:
+                self.collection.insert_one(msg)
+                return
+            except Exception:
+                pass
+        self._memory.append(msg)
+
+    def get_history(self, limit: int = 20) -> List[Dict]:
+        """Retrieve recent chat history for this session."""
+        if self.collection is not None:
+            try:
+                msgs = list(
+                    self.collection.find({"session_id": self.session_id})
+                    .sort("timestamp", -1)
+                    .limit(limit)
+                )
+                msgs.reverse()
+                return msgs
+            except Exception:
+                pass
+        return self._memory[-limit:]
+
+    def get_langchain_messages(self, limit: int = 10):
+        """Convert chat history to LangChain message objects."""
+        history = self.get_history(limit)
+        result = []
+        for msg in history:
+            if msg["role"] == "human":
+                result.append(HumanMessage(content=msg["content"]))
+            elif msg["role"] == "assistant":
+                result.append(AIMessage(content=msg["content"]))
+        return result
+
+    def clear_history(self):
+        """Clear all messages for this session."""
+        if self.collection is not None:
+            try:
+                self.collection.delete_many({"session_id": self.session_id})
+            except Exception:
+                pass
+        self._memory.clear()

src/services/vector_service.py

@@ -0,0 +1,157 @@
+"""
+Vector Store Service — ChromaDB/FAISS vector database operations.
+
+Extracted from main.py L276-L397. Manages embedding model loading,
+vector store creation/loading, similarity search, and the full
+knowledge base build pipeline.
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional, List
+
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.vector")
+
+_EMBEDDINGS_CACHE = {}
+
+
+def get_embeddings():
+    """Get or create the singleton embedding model instance."""
+    if "model" not in _EMBEDDINGS_CACHE:
+        from langchain_huggingface import HuggingFaceEmbeddings
+        logger.info(f"Loading embedding model: {settings.embedding_model}")
+        _EMBEDDINGS_CACHE["model"] = HuggingFaceEmbeddings(
+            model_name=settings.embedding_model,
+            model_kwargs={"device": "cpu"},
+            encode_kwargs={"normalize_embeddings": True},
+        )
+    return _EMBEDDINGS_CACHE["model"]
+
+
+class MathVectorStore:
+    """Vector store abstraction supporting ChromaDB (primary) and FAISS (fallback)."""
+
+    def __init__(self):
+        self.embeddings = get_embeddings()
+        self.vectorstore = None
+        self.db_type = settings.vector_db_type
+        self._load_existing()
+
+    def _load_existing(self):
+        if self.db_type == "chroma":
+            self._try_chroma()
+        else:
+            self._try_faiss()
+
+    def _try_chroma(self, documents=None):
+        try:
+            from langchain_community.vectorstores import Chroma
+            persist_path = Path(settings.chroma_persist_dir)
+            persist_path.mkdir(parents=True, exist_ok=True)
+            if documents:
+                self.vectorstore = Chroma.from_documents(
+                    documents=documents, embedding=self.embeddings,
+                    collection_name=settings.collection_name,
+                    persist_directory=str(persist_path))
+                logger.info("ChromaDB created.")
+            elif list(persist_path.glob("*.sqlite3")):
+                self.vectorstore = Chroma(
+                    collection_name=settings.collection_name,
+                    embedding_function=self.embeddings,
+                    persist_directory=str(persist_path))
+                logger.info(f"ChromaDB loaded ({self.vectorstore._collection.count()} docs)")
+        except Exception as e:
+            logger.warning(f"ChromaDB failed ({type(e).__name__}: {e}), switching to FAISS")
+            self.db_type = "faiss"
+            if documents:
+                self._try_faiss(documents)
+
+    def _try_faiss(self, documents=None):
+        try:
+            from langchain_community.vectorstores import FAISS
+            index_path = Path(settings.faiss_index_path)
+            if documents:
+                self.vectorstore = FAISS.from_documents(documents, self.embeddings)
+                index_path.mkdir(parents=True, exist_ok=True)
+                self.vectorstore.save_local(str(index_path))
+                logger.info(f"FAISS saved to {index_path}")
+            elif index_path.exists() and any(index_path.iterdir()):
+                self.vectorstore = FAISS.load_local(
+                    str(index_path), self.embeddings,
+                    allow_dangerous_deserialization=True)
+                logger.info("FAISS loaded.")
+        except Exception as e:
+            logger.error(f"FAISS failed: {e}")
+
+    def build_knowledge_base(self, documents):
+        """Build the vector index from a list of Document chunks."""
+        logger.info(f"Building knowledge base with {len(documents)} chunks...")
+        if self.db_type == "chroma":
+            self._try_chroma(documents)
+        else:
+            self._try_faiss(documents)
+        logger.info("Knowledge base ready.")
+
+    def add_documents(self, documents):
+        """Add documents to an existing vector store, or create one."""
+        if self.vectorstore is None:
+            self.build_knowledge_base(documents)
+        else:
+            self.vectorstore.add_documents(documents)
+
+    def similarity_search(self, query: str, k: int = None, filter_topic: str = None):
+        """Search for similar documents by query string."""
+        k = k or settings.top_k_results
+        if self.vectorstore is None:
+            return []
+        try:
+            if filter_topic and self.db_type == "chroma":
+                return self.vectorstore.similarity_search(query, k=k, filter={"topic": filter_topic})
+            return self.vectorstore.similarity_search(query, k=k)
+        except Exception as e:
+            logger.error(f"Search failed: {e}")
+            return []
+
+    def as_retriever(self, k: int = None):
+        """Return a LangChain retriever interface."""
+        k = k or settings.top_k_results
+        return self.vectorstore.as_retriever(search_kwargs={"k": k}) if self.vectorstore else None
+
+    def get_document_count(self) -> int:
+        """Get the number of indexed documents."""
+        if self.vectorstore is None:
+            return 0
+        try:
+            return (self.vectorstore._collection.count() if self.db_type == "chroma"
+                    else self.vectorstore.index.ntotal)
+        except Exception as e:
+            logger.error(f"get_document_count failed: {e}")
+            return 0
+
+    def is_ready(self) -> bool:
+        """Check if the vector store is loaded and has documents."""
+        return self.vectorstore is not None and self.get_document_count() > 0
+
+
+_PIPELINE_CACHE = {}
+
+
+def build_pipeline(pdf_paths=None, urls=None, text_paths=None, force_rebuild=False) -> MathVectorStore:
+    """Build or load the full knowledge base pipeline (cached per process)."""
+    from backend.src.math.knowledge_indexer import MathDataLoader, MathDataPreprocessor, MathTextSplitter
+
+    if "store" in _PIPELINE_CACHE and not force_rebuild:
+        return _PIPELINE_CACHE["store"]
+    store = MathVectorStore()
+    if store.is_ready() and not force_rebuild:
+        logger.info(f"Knowledge base already built ({store.get_document_count()} docs).")
+        _PIPELINE_CACHE["store"] = store
+        return store
+    raw_docs   = MathDataLoader().load_all(pdf_paths=pdf_paths or [], urls=urls or [], text_paths=text_paths or [])
+    clean_docs = MathDataPreprocessor().preprocess_documents(raw_docs)
+    chunks     = MathTextSplitter().split_documents(clean_docs)
+    store.build_knowledge_base(chunks)
+    _PIPELINE_CACHE["store"] = store
+    return store