feat: complete Phase 11 & 12, finalize Hackathon submission with ADK, LangGraph, and React

Dockerfile

@@ -1,24 +1,30 @@
-FROM python:3.11-slim
+# Build stage
+FROM python:3.11-slim as builder
 
 WORKDIR /app
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
 
-# 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/*
+# Run stage
+FROM python:3.11-slim
 
-# Install Python dependencies
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+WORKDIR /app
+
+# Copy dependencies from builder
+COPY --from=builder /root/.local /root/.local
+ENV PATH=/root/.local/bin:$PATH
 
 # Copy application code
-COPY src/ ./src/
-COPY ../knowledge_base.py ./knowledge_base.py
+COPY src /app/backend/src
+
+# Set environment variables
+ENV PYTHONPATH=/app
+ENV ENVIRONMENT=production
 
-# Non-root user for security
-RUN useradd --create-home appuser && chown -R appuser /app
-USER appuser
+# Cloud Run injects PORT, but default to 8080
+ENV PORT=8080
 
-EXPOSE 8080
+EXPOSE $PORT
 
-CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8080"]
+# Start FastAPI application
+CMD ["sh", "-c", "uvicorn backend.src.main:app --host 0.0.0.0 --port ${PORT}"]

requirements.txt

@@ -7,10 +7,14 @@ langchain-groq>=0.1.0
 langchain-huggingface>=0.0.3
 langchain-google-genai>=1.0.6
 google-generativeai>=0.5.4
+google-adk==0.1.0
+langgraph>=0.0.26
+langsmith>=0.1.0
 
 # Vector DB
-chromadb>=0.4.0
-faiss-cpu>=1.7.4
+qdrant-client>=1.7.0
+fastembed>=0.1.3
+langchain-qdrant>=0.1.0
 
 # Embeddings — pinned for meta-tensor safety on Python 3.11 / CPU
 sentence-transformers==2.7.0
@@ -24,9 +28,8 @@ accelerate>=0.29.0
 unstructured>=0.10.0
 pypdf>=3.0.0
 
-# Database (memory)
-pymongo>=4.0.0
-motor>=3.0.0
+# Database (Firebase)
+firebase-admin>=6.5.0
 
 # Math
 sympy>=1.12
@@ -52,3 +55,8 @@ plotly>=5.0.0
 pytest>=7.0.0
 pytest-cov>=4.0.0
 httpx>=0.27.0
+google-cloud-logging>=3.10.0
+slowapi>=0.1.9
+RestrictedPython>=6.2
+matplotlib>=3.8.0
+PyPDF2>=3.0.1

src/agents/formatter.py

@@ -0,0 +1,58 @@
+"""
+Formatter Agent (Google ADK)
+
+Formats the final verified solution according to the SYSTEM_TEMPLATE constraints
+(e.g., emojis, teacher reactions, LaTeX math mode).
+"""
+
+import logging
+from backend.src.services.llm_service import _get_llm
+from backend.src.config import SYSTEM_TEMPLATE
+
+try:
+    from google_adk.agent import Agent
+except ImportError:
+    class Agent:
+        def __init__(self, name, description, instructions, llm=None):
+            self.name = name
+            self.description = description
+            self.instructions = instructions
+            self.llm = llm
+
+logger = logging.getLogger("math_assistant.agents.formatter")
+
+class FormatterAgent(Agent):
+    """Formats the solution."""
+    
+    def __init__(self):
+        super().__init__(
+            name="FormatterAgent",
+            description="Formats the mathematical solution based on strict system templates.",
+            instructions=(
+                f"{SYSTEM_TEMPLATE}\n\n"
+                "Your task is to take the provided raw mathematical solution and rewrite it "
+                "to strictly adhere to the above formatting rules, including LaTeX math mode, "
+                "teacher reactions, and class-level appropriate depth."
+            )
+        )
+        self.llm = _get_llm()
+
+    def format(self, query: str, raw_solution: str, class_level: int) -> str:
+        """Format the solution."""
+        try:
+            prompt = (
+                f"{self.instructions}\n\n"
+                f"Target Class Level: {class_level}\n\n"
+                f"Original Query: {query}\n\n"
+                f"Raw Solution to Format:\n{raw_solution}"
+            )
+            
+            if hasattr(self.llm, "invoke"):
+                response = self.llm.invoke(prompt)
+                return response.content
+            else:
+                return self.llm(prompt)
+                
+        except Exception as e:
+            logger.error(f"Formatter failed: {e}")
+            return raw_solution

src/agents/mcp_registry.py

@@ -0,0 +1,65 @@
+import os
+import json
+import asyncio
+from typing import List
+from langchain.tools import Tool
+from backend.src.config import settings
+
+def get_mcp_tools() -> List[Tool]:
+    """Dynamically discover and return MCP tools."""
+    tools = []
+    
+    if not getattr(settings, "USE_MCP", True):
+        # Fallback to direct SymPy calls
+        import sympy as sp
+        from sympy.parsing.sympy_parser import parse_expr
+        
+        def fallback_differentiate(expr: str) -> str:
+            return str(sp.diff(parse_expr(expr), sp.Symbol('x')))
+            
+        tools.append(Tool(
+            name="differentiate",
+            description="Calculate the derivative of a mathematical expression.",
+            func=fallback_differentiate
+        ))
+        return tools
+
+    # In a full production setup, this would use mcp.client.stdio.stdio_client to connect
+    # to the 6 subprocesses. For latency and simplicity in this sandbox, we'll import
+    # the server tool functions directly but wrap them as LangChain tools, simulating
+    # an MCP Tool discovery registry.
+    
+    import sys
+    import importlib.util
+    base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../mcp-servers'))
+    
+    def load_module_from_path(module_name, file_path):
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+        
+    try:
+        sympy_mcp = load_module_from_path("sympy_mcp", os.path.join(base_dir, "sympy-mcp", "server.py"))
+        calc_mcp = load_module_from_path("calculator_mcp", os.path.join(base_dir, "calculator-mcp", "server.py"))
+        graph_mcp = load_module_from_path("graph_plotter_mcp", os.path.join(base_dir, "graph-plotter-mcp", "server.py"))
+        pdf_mcp = load_module_from_path("pdf_reader_mcp", os.path.join(base_dir, "pdf-reader-mcp", "server.py"))
+        exec_mcp = load_module_from_path("python_executor_mcp", os.path.join(base_dir, "python-executor-mcp", "server.py"))
+        img_mcp = load_module_from_path("image_solver_mcp", os.path.join(base_dir, "image-solver-mcp", "server.py"))
+        
+        tools.extend([
+            Tool(name="differentiate", description="Calculate derivative of expr in terms of x", func=lambda x: str(sympy_mcp.differentiate(x))),
+            Tool(name="integrate", description="Calculate integral of expr in terms of x", func=lambda x: str(sympy_mcp.integrate(x))),
+            Tool(name="simplify", description="Simplify mathematical expression", func=lambda x: str(sympy_mcp.simplify(x))),
+            Tool(name="solve", description="Solve algebraic equation equal to 0", func=lambda x: str(sympy_mcp.solve(x))),
+            Tool(name="execute_python", description="Execute sandboxed python code. Returns stdout.", func=exec_mcp.execute_python),
+            Tool(name="plot_function", description="Plot a math function string into SVG", func=graph_mcp.plot_function),
+            Tool(name="read_pdf", description="Read base64 PDF", func=pdf_mcp.read_pdf),
+            Tool(name="extract_and_solve_image", description="Extract and solve math from base64 image", func=lambda x: str(img_mcp.extract_and_solve_image(x)))
+        ])
+    except Exception as e:
+        import logging
+        logging.getLogger(__name__).error(f"Failed to load MCP tools: {e}")
+        
+    return tools

src/agents/memory.py

@@ -0,0 +1,64 @@
+"""
+Memory Agent (Google ADK)
+
+Retrieves chat history and analyzes weak topics from the user's profile.
+"""
+
+import logging
+from typing import Dict, Any
+
+from backend.src.services.memory_service import FirestoreChatMemory
+from backend.src.services.firebase_service import get_firestore_client
+from backend.src.config import settings
+
+try:
+    from google_adk.agent import Agent
+except ImportError:
+    class Agent:
+        def __init__(self, name, description, instructions, llm=None):
+            self.name = name
+            self.description = description
+            self.instructions = instructions
+            self.llm = llm
+
+logger = logging.getLogger("math_assistant.agents.memory")
+
+class MemoryAgent(Agent):
+    """Retrieves user memory and weak topics."""
+    
+    def __init__(self):
+        super().__init__(
+            name="MemoryAgent",
+            description="Retrieves past conversation context and user weak topics.",
+            instructions="Fetch user memory context."
+        )
+
+    def retrieve(self, uid: str, session_id: str) -> Dict[str, Any]:
+        """Fetch history and weak topics."""
+        # 1. Get Chat History
+        memory_svc = FirestoreChatMemory(uid=uid, session_id=session_id)
+        history = memory_svc.get_history(limit=5)
+        
+        formatted_history = []
+        for msg in history:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            formatted_history.append(f"{role.capitalize()}: {content}")
+            
+        history_text = "\n".join(formatted_history) if formatted_history else "No previous conversation."
+
+        # 2. Get Weak Topics
+        weak_topics = []
+        db = get_firestore_client()
+        if db:
+            try:
+                doc = db.collection("users").document(uid).collection("profile").document("topics").get()
+                if doc.exists:
+                    weak_topics = doc.to_dict().get("weak_topics", [])
+            except Exception as e:
+                logger.error(f"Failed to fetch weak topics: {e}")
+                
+        return {
+            "history": history_text,
+            "weak_topics": weak_topics
+        }

src/agents/orchestrator.py

@@ -0,0 +1,74 @@
+"""
+ADK Orchestrator
+
+Chains the 5 agents together (Planner -> Memory -> Solver -> Verifier -> Formatter).
+Replaces the monolithic MathAIEngine.
+"""
+
+import logging
+from typing import Dict, Any
+
+from backend.src.agents.planner import PlannerAgent
+from backend.src.agents.memory import MemoryAgent
+from backend.src.agents.solver import SolverAgent
+from backend.src.agents.verifier import VerifierAgent
+from backend.src.agents.formatter import FormatterAgent
+
+logger = logging.getLogger("math_assistant.agents.orchestrator")
+
+class ADKOrchestrator:
+    """Orchestrates the multi-agent ADK pipeline."""
+    
+    def __init__(self, uid: str, session_id: str):
+        self.uid = uid
+        self.session_id = session_id
+        
+        self.planner = PlannerAgent()
+        self.memory = MemoryAgent()
+        self.solver = SolverAgent()
+        self.verifier = VerifierAgent()
+        self.formatter = FormatterAgent()
+        
+    def query(self, user_query: str) -> Dict[str, Any]:
+        """Execute the full agent pipeline."""
+        logger.info(f"Starting ADK Orchestrator for session {self.session_id}")
+        
+        # 1. Plan
+        plan = self.planner.plan(user_query)
+        logger.info(f"Plan: {plan}")
+        class_level = plan.get("class", 10)
+        
+        # 2. Memory Retrieval
+        mem_context = self.memory.retrieve(self.uid, self.session_id)
+        
+        # 3. Solver + RAG
+        rag_context = self.solver.retrieve_context(user_query)
+        raw_solution = self.solver.solve(user_query, rag_context, mem_context["history"])
+        
+        # 4. Verify
+        # We allow up to 2 retries on verification failure
+        verification = self.verifier.verify(user_query, raw_solution)
+        retries = 0
+        while not verification.get("is_correct", True) and retries < 2:
+            logger.warning(f"Verification failed: {verification.get('feedback')}. Retrying...")
+            feedback = verification.get("feedback")
+            # Inject feedback into prompt
+            refined_query = f"{user_query}\nNote: Your previous attempt had an error: {feedback}. Please fix it."
+            raw_solution = self.solver.solve(refined_query, rag_context, mem_context["history"])
+            verification = self.verifier.verify(user_query, raw_solution)
+            retries += 1
+            
+        # 5. Format
+        final_answer = self.formatter.format(user_query, raw_solution, class_level)
+        
+        # Save to memory (Memory agent handles retrieval, but we use memory service directly for saving)
+        from backend.src.services.memory_service import FirestoreChatMemory
+        mem_svc = FirestoreChatMemory(uid=self.uid, session_id=self.session_id)
+        mem_svc.add_message("human", user_query)
+        mem_svc.add_message("assistant", final_answer)
+        
+        return {
+            "answer": final_answer,
+            "session_id": self.session_id,
+            "is_adk": True
+        }

src/agents/planner.py

@@ -0,0 +1,67 @@
+"""
+Planner Agent (Google ADK)
+
+Responsible for classifying the incoming query into a problem type and 
+target educational class.
+"""
+
+import logging
+from typing import Dict, Any
+
+from backend.src.services.llm_service import _get_llm
+from backend.src.config import settings
+
+try:
+    from google_adk.agent import Agent
+except ImportError:
+    # Mock fallback for test environment if ADK is missing
+    class Agent:
+        def __init__(self, name, description, instructions, llm=None):
+            self.name = name
+            self.description = description
+            self.instructions = instructions
+            self.llm = llm
+            
+logger = logging.getLogger("math_assistant.agents.planner")
+
+class PlannerAgent(Agent):
+    """Classifies math problems into type and class level."""
+    
+    def __init__(self):
+        super().__init__(
+            name="PlannerAgent",
+            description="Analyzes mathematical queries to classify them by type and class level.",
+            instructions=(
+                "You are an expert curriculum analyzer. Your job is to classify the given "
+                "mathematical query.\n"
+                "Return ONLY a valid JSON object with two keys:\n"
+                "- 'type': A string representing the question type (e.g., 'ncert_exercise', 'concept_explanation', 'jee_advanced').\n"
+                "- 'class': An integer representing the target class level (e.g., 6, 8, 10, 11, 12). If unknown, use 10.\n"
+                "Example output: {\"type\": \"ncert_exercise\", \"class\": 10}"
+            )
+        )
+        self.llm = _get_llm()
+
+    def plan(self, query: str) -> Dict[str, Any]:
+        """Classify the query."""
+        try:
+            # Simple invocation of LLM for the agent
+            if hasattr(self.llm, "invoke"):
+                response = self.llm.invoke(f"{self.instructions}\n\nQuery: {query}")
+                content = response.content
+            else:
+                content = self.llm(f"{self.instructions}\n\nQuery: {query}")
+            
+            import json
+            import re
+            
+            # Extract JSON from response
+            match = re.search(r'\{.*\}', content, re.DOTALL)
+            if match:
+                return json.loads(match.group(0))
+            
+            return {"type": "unknown", "class": 10}
+            
+        except Exception as e:
+            logger.error(f"Planner failed: {e}")
+            return {"type": "unknown", "class": 10}

src/agents/solver.py

@@ -0,0 +1,101 @@
+"""
+Solver Agent (Google ADK)
+
+Uses RAG context and LLM to solve the math problem.
+"""
+
+import logging
+from typing import Dict, Any, List
+
+from backend.src.services.llm_service import _get_llm
+from backend.src.services.vector_service import build_pipeline
+from backend.src.config import settings
+
+try:
+    from google_adk.agent import Agent
+except ImportError:
+    class Agent:
+        def __init__(self, name, description, instructions, llm=None):
+            self.name = name
+            self.description = description
+            self.instructions = instructions
+            self.llm = llm
+
+logger = logging.getLogger("math_assistant.agents.solver")
+
+class SolverAgent(Agent):
+    """Core mathematical engine."""
+    
+    def __init__(self):
+        super().__init__(
+            name="SolverAgent",
+            description="Solves mathematical problems step-by-step using RAG context.",
+            instructions="Solve the math problem accurately."
+        )
+        self.llm = _get_llm()
+        self.vector_store = build_pipeline()
+        
+        from backend.src.agents.mcp_registry import get_mcp_tools
+        self.tools = get_mcp_tools()
+        
+        try:
+            from langchain.agents import create_tool_calling_agent, AgentExecutor
+            from langchain_core.prompts import ChatPromptTemplate
+            
+            prompt = ChatPromptTemplate.from_messages([
+                ("system", "You are an advanced mathematical solver. Provide a clear, step-by-step solution. You MUST use the provided tools for differentiation, integration, arithmetic, python code execution, etc. whenever a complex calculation is needed. Do not guess complex answers."),
+                ("human", "Question: {query}\n\nRelevant Knowledge Base Context:\n{context}\n\nPrevious Chat Context:\n{history}\n\nSolution:")
+            ])
+            
+            # If the LLM doesn't support bind_tools, this will fail or we can catch it
+            if getattr(settings, "USE_MCP", True) and hasattr(self.llm, "bind_tools") and self.tools:
+                agent = create_tool_calling_agent(self.llm, self.tools, prompt)
+                self.executor = AgentExecutor(agent=agent, tools=self.tools, verbose=True, handle_parsing_errors=True)
+            else:
+                self.executor = None
+        except ImportError:
+            self.executor = None
+
+    def solve(self, query: str, context: str, history: str) -> str:
+        """Generate a solution based on query, RAG context, and history."""
+        if getattr(self, 'executor', None):
+            try:
+                response = self.executor.invoke({
+                    "query": query,
+                    "context": context,
+                    "history": history
+                })
+                return response.get("output", "")
+            except Exception as e:
+                logger.error(f"Solver AgentExecutor failed: {e}")
+                return "I encountered an error while trying to solve this problem with tools."
+        
+        prompt = (
+            f"You are a mathematical solver. Provide a clear, step-by-step solution.\n\n"
+            f"Question: {query}\n\n"
+            f"Relevant Knowledge Base Context:\n{context}\n\n"
+            f"Previous Chat Context:\n{history}\n\n"
+            f"Solution:"
+        )
+        
+        try:
+            if hasattr(self.llm, "invoke"):
+                response = self.llm.invoke(prompt)
+                return response.content
+            else:
+                return self.llm(prompt)
+        except Exception as e:
+            logger.error(f"Solver failed: {e}")
+            return "I encountered an error while trying to solve this problem."
+
+    def retrieve_context(self, query: str) -> str:
+        """Retrieve RAG context for the query."""
+        try:
+            retriever = self.vector_store.as_retriever(search_kwargs={"k": 3})
+            docs = retriever.invoke(query)
+            if not docs:
+                return "No relevant context found."
+            return "\n\n".join([doc.page_content for doc in docs])
+        except Exception as e:
+            logger.warning(f"RAG retrieval failed in Solver: {e}")
+            return "No relevant context found."

src/agents/verifier.py

@@ -0,0 +1,65 @@
+"""
+Verifier Agent (Google ADK)
+
+Checks the solver's output for mathematical or logical errors.
+"""
+
+import logging
+from typing import Dict, Any
+
+from backend.src.services.llm_service import _get_llm
+
+try:
+    from google_adk.agent import Agent
+except ImportError:
+    class Agent:
+        def __init__(self, name, description, instructions, llm=None):
+            self.name = name
+            self.description = description
+            self.instructions = instructions
+            self.llm = llm
+
+logger = logging.getLogger("math_assistant.agents.verifier")
+
+class VerifierAgent(Agent):
+    """Verifies mathematical solutions."""
+    
+    def __init__(self):
+        super().__init__(
+            name="VerifierAgent",
+            description="Verifies the step-by-step solution for mathematical errors.",
+            instructions=(
+                "You are a strict math reviewer. Review the provided solution for the given query.\n"
+                "Are there any mathematical errors, calculation mistakes, or logical leaps?\n"
+                "For example, check for basic arithmetic errors like 4+4=9.\n"
+                "Return ONLY a valid JSON object with two keys:\n"
+                "- 'is_correct': A boolean (true/false).\n"
+                "- 'feedback': A string explaining the error if is_correct is false, or 'Looks good.' if true.\n"
+            )
+        )
+        self.llm = _get_llm()
+
+    def verify(self, query: str, solution: str) -> Dict[str, Any]:
+        """Verify the solution."""
+        try:
+            prompt = f"{self.instructions}\n\nQuery: {query}\n\nSolution:\n{solution}"
+            
+            if hasattr(self.llm, "invoke"):
+                response = self.llm.invoke(prompt)
+                content = response.content
+            else:
+                content = self.llm(prompt)
+                
+            import json
+            import re
+            
+            # Extract JSON from response
+            match = re.search(r'\{.*\}', content, re.DOTALL)
+            if match:
+                return json.loads(match.group(0))
+            
+            return {"is_correct": True, "feedback": "Could not parse verification."}
+            
+        except Exception as e:
+            logger.error(f"Verifier failed: {e}")
+            return {"is_correct": True, "feedback": "Verification failed."}

src/api/limiter.py

@@ -0,0 +1,6 @@
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+# Global rate limiter using the remote address as the key.
+limiter = Limiter(key_func=get_remote_address)

src/api/middleware/auth.py

@@ -0,0 +1,60 @@
+"""
+Firebase Authentication Middleware.
+
+Validates Firebase ID tokens passed in the Authorization header.
+Used as a FastAPI dependency for protected routes.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+from backend.src.services.firebase_service import get_auth
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.auth")
+security = HTTPBearer(auto_error=False)
+
+def verify_firebase_token(credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)) -> str:
+    """Verify the Firebase ID token and return the user's UID.
+
+    If USE_FIREBASE=false or no token is provided, returns 'anonymous'.
+    If a token is provided but invalid, raises HTTP 401.
+    """
+    if not settings.use_firebase:
+        return "anonymous"
+
+    auth = get_auth()
+    if not auth:
+        # Firebase not initialized properly
+        return "anonymous"
+
+    if not credentials:
+        # Require authentication when Firebase is enabled
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    token = credentials.credentials
+
+    # For testing: accept a dummy token
+    if token == "test-token":
+        return "test-user-uid"
+
+    try:
+        decoded_token = auth.verify_id_token(token)
+        uid = decoded_token.get("uid")
+        if not uid:
+            raise ValueError("Token does not contain a UID")
+        return uid
+    except Exception as e:
+        logger.warning(f"Firebase token verification failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid authentication token: {e}",
+            headers={"WWW-Authenticate": "Bearer"},
+        )

src/api/v1/chat.py

@@ -8,7 +8,7 @@ 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 import APIRouter, HTTPException, UploadFile, File, Form, Depends, Request
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel, Field
 
@@ -16,6 +16,10 @@ 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
+from backend.src.api.middleware.auth import verify_firebase_token
+from backend.src.api.limiter import limiter
+from backend.src.agents.orchestrator import ADKOrchestrator
+from backend.src.graph.math_graph import math_graph
 
 logger = logging.getLogger("math_assistant.api.chat")
 
@@ -55,7 +59,8 @@ class VisionResponse(BaseModel):
 # ── Endpoints ──────────────────────────────────────────────────────────
 
 @router.post("/chat", response_model=ChatResponse)
-async def chat(request: ChatRequest):
+@limiter.limit("20/minute")
+async def chat(request: Request, payload: ChatRequest, uid: str = Depends(verify_firebase_token)):
     """Process a math question and return a step-by-step solution.
 
     The query flows through:
@@ -65,17 +70,40 @@ async def chat(request: ChatRequest):
     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)
+        if getattr(settings, "use_langgraph", False):
+            # Phase 5: LangGraph Path
+            initial_state = {
+                "user_query": payload.query,
+                "uid": uid,
+                "session_id": payload.session_id,
+                "retries": 0
+            }
+            final_state = math_graph.invoke(initial_state)
+            return ChatResponse(
+                answer=final_state.get("final_answer", "Error generating response."),
+                session_id=payload.session_id,
+                is_adk=True
+            )
+        elif settings.use_adk:
+            # Phase 4: ADK Orchestrator Path
+            orchestrator = ADKOrchestrator(uid=uid, session_id=payload.session_id)
+            result = orchestrator.query(payload.query)
+            return ChatResponse(**result)
+        else:
+            # Legacy Phase 2/3 path
+            store = build_pipeline()
+            engine = MathAIEngine(vector_store=store, session_id=payload.session_id)
+            engine.memory.uid = uid
+            result = engine.query(payload.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):
+@limiter.limit("20/minute")
+async def chat_stream(request: Request, payload: ChatRequest, uid: str = Depends(verify_firebase_token)):
     """Stream a math solution token-by-token using SSE.
     
     Requires USE_GEMINI=true to function correctly.
@@ -89,19 +117,20 @@ async def chat_stream(request: ChatRequest):
     try:
         # We manually orchestrate the context retrieval for streaming
         store = build_pipeline()
-        engine = MathAIEngine(vector_store=store, session_id=request.session_id)
+        engine = MathAIEngine(vector_store=store, session_id=payload.session_id)
+        engine.memory.uid = uid
         
         # 1. Get context and history
-        source_docs, context = engine._retrieve_context(request.query)
+        source_docs, context = engine._retrieve_context(payload.query)
         chat_history = engine.memory.get_langchain_messages(limit=4)
-        engine.memory.add_message("human", request.query)
+        engine.memory.add_message("human", payload.query)
 
         gemini = GeminiService()
 
         async def generate():
             full_response = ""
             try:
-                async for chunk in gemini.stream(request.query, context=context, chat_history=chat_history):
+                async for chunk in gemini.stream(payload.query, context=context, chat_history=chat_history):
                     full_response += chunk
                     # Format as SSE
                     yield f"data: {chunk}\n\n"
@@ -122,7 +151,8 @@ async def chat_stream(request: ChatRequest):
 
 
 @router.post("/vision/extract", response_model=VisionResponse)
-async def extract_math_from_image(file: UploadFile = File(...), solve: bool = Form(False)):
+@limiter.limit("20/minute")
+async def extract_math_from_image(request: Request, file: UploadFile = File(...), solve: bool = Form(False), uid: str = Depends(verify_firebase_token)):
     """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.")
@@ -147,10 +177,11 @@ async def extract_math_from_image(file: UploadFile = File(...), solve: bool = Fo
 
 
 @router.get("/history/{session_id}", response_model=HistoryResponse)
-async def get_history(session_id: str):
+async def get_history(session_id: str, uid: str = Depends(verify_firebase_token)):
     """Get chat history for a given session."""
     try:
         engine = MathAIEngine(session_id=session_id)
+        engine.memory.uid = uid
         history = engine.get_history()
         # Convert MongoDB ObjectId to string for JSON serialization
         messages = []
@@ -167,10 +198,11 @@ async def get_history(session_id: str):
 
 
 @router.delete("/history/{session_id}")
-async def clear_history(session_id: str):
+async def clear_history(session_id: str, uid: str = Depends(verify_firebase_token)):
     """Clear chat history for a given session."""
     try:
         engine = MathAIEngine(session_id=session_id)
+        engine.memory.uid = uid
         engine.clear_memory()
         return {"status": "ok", "message": f"History cleared for session {session_id}"}
     except Exception as e:

src/api/v1/progress.py

@@ -0,0 +1,116 @@
+"""
+Progress Tracking API — /api/v1/progress endpoints.
+
+Handles daily streak calculations and total problems solved per user.
+Backed by Firestore.
+"""
+
+import logging
+from datetime import datetime, timezone
+from pydantic import BaseModel
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from backend.src.api.middleware.auth import verify_firebase_token
+from backend.src.services.firebase_service import get_firestore_client
+
+logger = logging.getLogger("math_assistant.api.progress")
+
+router = APIRouter(prefix="/api/v1/progress", tags=["progress"])
+
+class ProgressResponse(BaseModel):
+    streak: int
+    total_solved: int
+    last_solved_date: str
+
+@router.get("", response_model=ProgressResponse)
+async def get_progress(uid: str = Depends(verify_firebase_token)):
+    """Get the user's current progress and streak."""
+    db = get_firestore_client()
+    if not db:
+        # Fallback if Firebase is disabled
+        return ProgressResponse(streak=0, total_solved=0, last_solved_date="")
+        
+    try:
+        doc_ref = db.collection("users").document(uid).collection("profile").document("stats")
+        doc = doc_ref.get()
+        
+        if doc.exists:
+            data = doc.to_dict()
+            return ProgressResponse(
+                streak=data.get("streak", 0),
+                total_solved=data.get("total_solved", 0),
+                last_solved_date=data.get("last_solved_date", "")
+            )
+        else:
+            return ProgressResponse(streak=0, total_solved=0, last_solved_date="")
+    except Exception as e:
+        logger.error(f"Error getting progress for {uid}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/increment", response_model=ProgressResponse)
+async def increment_progress(uid: str = Depends(verify_firebase_token)):
+    """Increment the user's total solved count and update their streak."""
+    db = get_firestore_client()
+    if not db:
+        return ProgressResponse(streak=1, total_solved=1, last_solved_date=datetime.now(timezone.utc).date().isoformat())
+
+    try:
+        doc_ref = db.collection("users").document(uid).collection("profile").document("stats")
+        today_str = datetime.now(timezone.utc).date().isoformat()
+        
+        # We need a transaction to safely update the streak
+        @from_firestore_transaction(db)
+        def update_in_transaction(transaction, ref, today):
+            snapshot = ref.get(transaction=transaction)
+            
+            if not snapshot.exists:
+                data = {
+                    "streak": 1,
+                    "total_solved": 1,
+                    "last_solved_date": today
+                }
+                transaction.set(ref, data)
+                return data
+                
+            current_data = snapshot.to_dict()
+            last_date = current_data.get("last_solved_date", "")
+            streak = current_data.get("streak", 0)
+            total = current_data.get("total_solved", 0) + 1
+            
+            if last_date == today:
+                # Already solved a problem today, just increment total
+                pass
+            else:
+                # Need to check if it was yesterday
+                try:
+                    last_date_obj = datetime.fromisoformat(last_date).date()
+                    today_obj = datetime.fromisoformat(today).date()
+                    delta = (today_obj - last_date_obj).days
+                    
+                    if delta == 1:
+                        streak += 1
+                    else:
+                        streak = 1
+                except ValueError:
+                    streak = 1
+                    
+            data = {
+                "streak": streak,
+                "total_solved": total,
+                "last_solved_date": today
+            }
+            transaction.update(ref, data)
+            return data
+            
+        new_stats = update_in_transaction(db.transaction(), doc_ref, today_str)
+        return ProgressResponse(**new_stats)
+        
+    except Exception as e:
+        logger.error(f"Error incrementing progress for {uid}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+def from_firestore_transaction(db):
+    """Helper decorator for Firestore transactions."""
+    from firebase_admin import firestore
+    return firestore.transactional

src/config.py

@@ -55,10 +55,22 @@ class Settings(BaseSettings):
     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"
+    # ── Firebase ───────────────────────────────────────────────────────
+    use_firebase: bool = True
+    firebase_credentials_path: str = ""
+
+    # ── ADK Multi-Agent ────────────────────────────────────────────────
+    use_adk: bool = True
+
+    # ── LangGraph ──────────────────────────────────────────────────────
+    use_langgraph: bool = True
+    langchain_api_key: str = ""
+
+    # ── Vector DB ──────────────────────────────────────────────────────
+    vector_db: str = "qdrant"
+    qdrant_url: str = ":memory:"
+    qdrant_api_key: str = ""
+
 
     # ── Server ─────────────────────────────────────────────────────────
     host: str = "0.0.0.0"
@@ -70,6 +82,34 @@ class Settings(BaseSettings):
 # Singleton settings instance
 settings = Settings()
 
+def setup_logging():
+    import logging
+    import os
+    
+    # Check if running in a GCP environment (Cloud Run, App Engine) or has ADC setup
+    use_cloud_logging = os.getenv("GOOGLE_APPLICATION_CREDENTIALS") or os.getenv("GOOGLE_CLOUD_PROJECT")
+    
+    if use_cloud_logging:
+        try:
+            import google.cloud.logging
+            client = google.cloud.logging.Client()
+            client.setup_logging()
+            logging.info("Google Cloud Logging integrated successfully.")
+            return
+        except ImportError:
+            logging.warning("google-cloud-logging not installed. Falling back to standard logging.")
+        except Exception as e:
+            logging.warning(f"Failed to initialize Cloud Logging: {e}. Falling back to standard logging.")
+            
+    # Standard local logging fallback
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    )
+
+# Initialize logging when config is imported
+setup_logging()
+
 
 # ── System Prompt Template ─────────────────────────────────────────────
 # Extracted from main.py L404-L522. This is the master prompt template

src/graph/math_graph.py

@@ -0,0 +1,74 @@
+"""
+MathGraph Definition
+
+Builds the StateGraph and connects nodes with conditional routing.
+"""
+
+import logging
+from langgraph.graph import StateGraph, START, END
+
+from backend.src.graph.state import MathAgentState
+from backend.src.graph.nodes.nodes import (
+    classify_node,
+    retrieve_rag_node,
+    retrieve_memory_node,
+    solve_node,
+    verify_node,
+    format_node
+)
+
+logger = logging.getLogger("math_assistant.graph.math_graph")
+
+def should_retry(state: MathAgentState):
+    """Conditional edge logic after verification."""
+    if state["is_correct"]:
+        return "format"
+    elif state["retries"] >= 2:
+        logger.warning(f"Max retries reached. Forcing format. Feedback: {state.get('verification_feedback')}")
+        return "format"
+    else:
+        logger.info(f"Verification failed. Retrying solve... (Retry {state['retries']})")
+        return "solve"
+
+# 1. Initialize StateGraph
+graph_builder = StateGraph(MathAgentState)
+
+# 2. Add Nodes
+graph_builder.add_node("classify", classify_node)
+graph_builder.add_node("retrieve_rag", retrieve_rag_node)
+graph_builder.add_node("retrieve_memory", retrieve_memory_node)
+graph_builder.add_node("solve", solve_node)
+graph_builder.add_node("verify", verify_node)
+graph_builder.add_node("format", format_node)
+
+# 3. Add Edges
+# Start -> Classify
+graph_builder.add_edge(START, "classify")
+
+# Classify -> Parallel Retrievals
+graph_builder.add_edge("classify", "retrieve_rag")
+graph_builder.add_edge("classify", "retrieve_memory")
+
+# Parallel Retrievals -> Solve
+# LangGraph waits for all incoming edges to complete before firing 'solve'
+graph_builder.add_edge("retrieve_rag", "solve")
+graph_builder.add_edge("retrieve_memory", "solve")
+
+# Solve -> Verify
+graph_builder.add_edge("solve", "verify")
+
+# Verify -> Conditional Routing
+graph_builder.add_conditional_edges(
+    "verify",
+    should_retry,
+    {
+        "format": "format",
+        "solve": "solve"
+    }
+)
+
+# Format -> End
+graph_builder.add_edge("format", END)
+
+# 4. Compile Graph
+math_graph = graph_builder.compile()

src/graph/nodes/nodes.py

@@ -0,0 +1,87 @@
+"""
+LangGraph Nodes
+
+Wraps the ADK agents into functional nodes that mutate the MathAgentState.
+"""
+
+import logging
+from backend.src.graph.state import MathAgentState
+from backend.src.agents.planner import PlannerAgent
+from backend.src.agents.memory import MemoryAgent
+from backend.src.agents.solver import SolverAgent
+from backend.src.agents.verifier import VerifierAgent
+from backend.src.agents.formatter import FormatterAgent
+from backend.src.services.memory_service import FirestoreChatMemory
+
+logger = logging.getLogger("math_assistant.graph.nodes")
+
+# Lazy initialization of agents
+_agents = {}
+
+def _get_agent(agent_class, name):
+    if name not in _agents:
+        _agents[name] = agent_class()
+    return _agents[name]
+
+def classify_node(state: MathAgentState) -> dict:
+    """Classify the user query."""
+    planner = _get_agent(PlannerAgent, "planner")
+    plan = planner.plan(state["user_query"])
+    return {
+        "question_type": plan.get("type", "unknown"),
+        "class_level": plan.get("class", 10),
+        "retries": 0  # initialize retries
+    }
+
+def retrieve_rag_node(state: MathAgentState) -> dict:
+    """Fetch RAG context from the vector store."""
+    solver = _get_agent(SolverAgent, "solver")
+    context = solver.retrieve_context(state["user_query"])
+    return {"rag_context": context}
+
+def retrieve_memory_node(state: MathAgentState) -> dict:
+    """Fetch history and weak topics from Firestore."""
+    memory = _get_agent(MemoryAgent, "memory")
+    mem = memory.retrieve(state["uid"], state["session_id"])
+    return {
+        "history": mem.get("history", ""),
+        "weak_topics": mem.get("weak_topics", [])
+    }
+
+def solve_node(state: MathAgentState) -> dict:
+    """Generate a solution based on current state context."""
+    query = state["user_query"]
+    solver = _get_agent(SolverAgent, "solver")
+    
+    # If this is a retry, append the verifier's feedback
+    if state.get("retries", 0) > 0 and state.get("verification_feedback"):
+        query = f"{query}\nNote: Your previous attempt failed validation: {state['verification_feedback']}. Fix it."
+        
+    solution = solver.solve(query, state.get("rag_context", ""), state.get("history", ""))
+    return {"raw_solution": solution}
+
+def verify_node(state: MathAgentState) -> dict:
+    """Verify the generated solution."""
+    verifier = _get_agent(VerifierAgent, "verifier")
+    verification = verifier.verify(state["user_query"], state["raw_solution"])
+    return {
+        "is_correct": verification.get("is_correct", True),
+        "verification_feedback": verification.get("feedback", ""),
+        "retries": state.get("retries", 0) + 1
+    }
+
+def format_node(state: MathAgentState) -> dict:
+    """Format the final output and save it to chat history."""
+    formatter = _get_agent(FormatterAgent, "formatter")
+    final_answer = formatter.format(
+        state["user_query"], 
+        state["raw_solution"], 
+        state.get("class_level", 10)
+    )
+    
+    # Side effect: Save the conversation turn
+    mem_svc = FirestoreChatMemory(uid=state["uid"], session_id=state["session_id"])
+    mem_svc.add_message("human", state["user_query"])
+    mem_svc.add_message("assistant", final_answer)
+    
+    return {"final_answer": final_answer}

src/graph/state.py

@@ -0,0 +1,33 @@
+"""
+LangGraph State Definition
+"""
+
+from typing import TypedDict, Annotated, List
+
+class MathAgentState(TypedDict):
+    """Represents the state of the math orchestration pipeline."""
+    
+    # Input
+    user_query: str
+    uid: str
+    session_id: str
+    
+    # Planner output
+    question_type: str
+    class_level: int
+    
+    # Retrievals (Running in parallel)
+    rag_context: str
+    history: str
+    weak_topics: List[str]
+    
+    # Solver Output
+    raw_solution: str
+    
+    # Verifier Feedback
+    is_correct: bool
+    verification_feedback: str
+    retries: int
+    
+    # Formatter Output
+    final_answer: str

src/main.py

@@ -13,7 +13,9 @@ 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
+from backend.src.services.firebase_service import init_firebase
+from backend.src.api.v1 import chat
+from backend.src.api.v1 import progress
 
 # ── Logging Setup ──────────────────────────────────────────────────────
 logging.basicConfig(
@@ -32,6 +34,9 @@ async def lifespan(app: FastAPI):
     logger.info(f"   LLM Model: {settings.llm_model}")
     logger.info(f"   Vector DB: {settings.vector_db_type}")
 
+    # Initialize Firebase Admin SDK
+    init_firebase()
+
     # 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
@@ -53,6 +58,11 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+from backend.src.api.limiter import limiter, _rate_limit_exceeded_handler, RateLimitExceeded
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+
 # ── CORS Middleware ────────────────────────────────────────────────────
 app.add_middleware(
     CORSMiddleware,
@@ -67,7 +77,8 @@ app.add_middleware(
 )
 
 # ── Routes ─────────────────────────────────────────────────────────────
-app.include_router(chat_router)
+app.include_router(chat.router)
+app.include_router(progress.router)
 
 
 @app.get("/health")

src/math/knowledge_indexer.py

@@ -1,290 +1,80 @@
 """
-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
+Knowledge Base Indexing Pipeline — Markdown loading, preprocessing, and chunking for Qdrant.
 """
 
-import re
-import hashlib
+import os
+import glob
 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 {}
+from typing import List
 
+from langchain_core.documents import Document
 
-class MathDataLoader:
-    """Load NCERT math knowledge base from hardcoded knowledge_base.py."""
+from backend.src.services.qdrant_service import QdrantService
+from backend.src.config import settings
 
-    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)
+logger = logging.getLogger("math_assistant.indexer")
 
-        from knowledge_base import MATH_KNOWLEDGE_BASE, CLASS_EXAMPLES
+class KnowledgeIndexer:
+    """Parses local markdown files and indexes them into the Qdrant vector store."""
+    
+    def __init__(self, kb_dir: str = "knowledge-base"):
+        self.kb_dir = kb_dir
+        self.qdrant = QdrantService()
+
+    def parse_frontmatter(self, text: str) -> tuple[dict, str]:
+        """Extract metadata from markdown frontmatter."""
+        metadata = {}
+        content = text
+        if text.startswith("---\n"):
+            parts = text.split("---\n", 2)
+            if len(parts) == 3:
+                frontmatter = parts[1]
+                content = parts[2]
+                for line in frontmatter.strip().split('\n'):
+                    if ':' in line:
+                        key, val = line.split(':', 1)
+                        metadata[key.strip()] = val.strip()
+        return metadata, content.strip()
+
+    def load_markdown_files(self) -> List[Document]:
+        """Load all markdown files from the knowledge base directory."""
         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:
+        search_pattern = os.path.join(self.kb_dir, "**", "*.md")
+        filepaths = glob.glob(search_pattern, recursive=True)
+        
+        logger.info(f"Found {len(filepaths)} markdown files in {self.kb_dir}")
+        
+        for filepath in filepaths:
             try:
-                loader = WebBaseLoader(url)
-                loader.requests_kwargs = {"timeout": 15}
-                docs.extend(loader.load())
-                logger.info(f"Loaded: {url}")
+                with open(filepath, 'r', encoding='utf-8') as f:
+                    text = f.read()
+                    
+                metadata, content = self.parse_frontmatter(text)
+                metadata["source_file"] = filepath
+                
+                doc = Document(page_content=content, metadata=metadata)
+                documents.append(doc)
             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
+                logger.error(f"Failed to process {filepath}: {e}")
+                
+        return documents
 
-    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
+    def index_all(self):
+        """Load all files, split, and index into Qdrant."""
+        logger.info("Starting Knowledge Base indexing...")
+        docs = self.load_markdown_files()
+        if not docs:
+            logger.warning("No documents found to index.")
+            return
+
+        from langchain.text_splitter import RecursiveCharacterTextSplitter
+        splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=100)
+        chunks = splitter.split_documents(docs)
+            
+        logger.info(f"Created {len(chunks)} chunks. Pushing to Qdrant...")
+        self.qdrant.add_documents(chunks)
+        logger.info(f"Indexing complete. Total vectors: {self.qdrant.get_document_count()}")
+
+if __name__ == "__main__":
+    indexer = KnowledgeIndexer()
+    indexer.index_all()

src/services/embedding_service.py

@@ -0,0 +1,32 @@
+"""
+Embedding Service — Manages dense and sparse embedding models.
+"""
+
+import logging
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.embeddings")
+
+_DENSE_EMBEDDINGS_CACHE = None
+
+def get_dense_embeddings():
+    """Get or create the singleton dense embedding model (text-embedding-004)."""
+    global _DENSE_EMBEDDINGS_CACHE
+    if _DENSE_EMBEDDINGS_CACHE is None:
+        try:
+            # First try new gemini integration
+            from langchain_google_genai import GoogleGenerativeAIEmbeddings
+            logger.info("Loading dense embedding model: text-embedding-004")
+            _DENSE_EMBEDDINGS_CACHE = GoogleGenerativeAIEmbeddings(
+                model="models/text-embedding-004",
+                task_type="retrieval_document"
+            )
+        except Exception as e:
+            logger.warning(f"Failed to load Google embeddings ({e}), falling back to HuggingFace")
+            from langchain_huggingface import HuggingFaceEmbeddings
+            _DENSE_EMBEDDINGS_CACHE = HuggingFaceEmbeddings(
+                model_name=settings.embedding_model,
+                model_kwargs={"device": "cpu"},
+                encode_kwargs={"normalize_embeddings": True},
+            )
+    return _DENSE_EMBEDDINGS_CACHE

src/services/evaluation_service.py

@@ -0,0 +1,101 @@
+"""
+Evaluation Service — Offline LLM-as-judge pipeline for answering quality.
+"""
+
+import logging
+from typing import Dict, List, Any
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.eval")
+
+class EvaluationService:
+    """Uses LLM-as-judge to evaluate generated math answers against reference solutions."""
+    
+    def __init__(self, judge_model: str = "gemini-2.5-flash"):
+        self.judge_model = judge_model
+        
+    def evaluate_answer(self, question: str, generated_answer: str, reference_answer: str) -> Dict[str, Any]:
+        """Ask the judge model to score the generated answer from 1 to 5."""
+        from google import genai
+        from google.genai import types
+        
+        api_key = settings.gemini_api_key
+        if not api_key:
+            return {"score": 0, "reasoning": "Missing API Key for evaluation"}
+            
+        client = genai.Client(api_key=api_key)
+        
+        prompt = f"""You are an expert mathematics teacher grading a student's answer.
+        
+        Question: {question}
+        
+        Reference/Correct Answer:
+        {reference_answer}
+        
+        Student's Answer to evaluate:
+        {generated_answer}
+        
+        Grade the student's answer from 1 to 5 based on:
+        1. Accuracy: Is the final answer correct?
+        2. Steps: Are the steps logical and mathematically sound?
+        
+        Format your response EXACTLY as follows:
+        SCORE: [1-5]
+        REASONING: [1-2 sentences explaining why]
+        """
+        
+        config = types.GenerateContentConfig(
+            temperature=0.1,
+            max_output_tokens=150,
+        )
+        
+        try:
+            response = client.models.generate_content(
+                model=self.judge_model,
+                contents=prompt,
+                config=config
+            )
+            
+            text = response.text.strip()
+            score = 0
+            reasoning = text
+            
+            for line in text.split('\n'):
+                if line.startswith("SCORE:"):
+                    try:
+                        score = int(line.replace("SCORE:", "").strip())
+                    except:
+                        pass
+                elif line.startswith("REASONING:"):
+                    reasoning = line.replace("REASONING:", "").strip()
+                    
+            return {"score": score, "reasoning": reasoning}
+            
+        except Exception as e:
+            logger.error(f"Evaluation failed: {e}")
+            return {"score": 0, "reasoning": f"Evaluation error: {e}"}
+            
+    def run_eval_pipeline(self, test_cases: List[Dict[str, str]]) -> Dict[str, Any]:
+        """Run evaluation on a batch of test cases."""
+        results = []
+        total_score = 0
+        
+        for case in test_cases:
+            res = self.evaluate_answer(
+                question=case['question'],
+                generated_answer=case['generated_answer'],
+                reference_answer=case['reference_answer']
+            )
+            total_score += res['score']
+            results.append({
+                "question": case['question'],
+                "score": res['score'],
+                "reasoning": res['reasoning']
+            })
+            
+        avg_score = total_score / len(test_cases) if test_cases else 0
+        return {
+            "average_score": avg_score,
+            "total_evaluated": len(test_cases),
+            "results": results
+        }

src/services/firebase_service.py

@@ -0,0 +1,81 @@
+"""
+Firebase Service — Initializes Firebase Admin SDK and provides database access.
+
+This replaces MongoDB for database persistence in Phase 3.
+"""
+
+import os
+import logging
+from typing import Optional
+
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.firebase")
+
+_FIREBASE_APP = None
+_FIRESTORE_CLIENT = None
+
+def init_firebase():
+    """Initialize the Firebase Admin SDK."""
+    global _FIREBASE_APP, _FIRESTORE_CLIENT
+    
+    if not settings.use_firebase:
+        logger.info("Firebase integration disabled in config.")
+        return
+
+    if _FIREBASE_APP is not None:
+        return
+
+    import firebase_admin
+    from firebase_admin import credentials
+    from firebase_admin import firestore
+
+    cred_path = settings.firebase_credentials_path
+    if not cred_path or not os.path.exists(cred_path):
+        logger.warning(
+            f"Firebase credentials not found at {cred_path}. "
+            "Running in unauthenticated/memory-fallback mode."
+        )
+        return
+
+    try:
+        cred = credentials.Certificate(cred_path)
+        _FIREBASE_APP = firebase_admin.initialize_app(cred)
+        _FIRESTORE_CLIENT = firestore.client()
+        logger.info("Firebase Admin SDK initialized successfully.")
+    except Exception as e:
+        logger.error(f"Failed to initialize Firebase Admin SDK: {e}")
+
+def get_firestore_client():
+    """Get the initialized Firestore client."""
+    return _FIRESTORE_CLIENT
+
+def get_auth():
+    """Get the Firebase Auth module."""
+    if _FIREBASE_APP is None:
+        return None
+    from firebase_admin import auth
+    return auth
+
+def save_user_feedback(uid: str, session_id: str, message_id: str, is_positive: bool, comments: str = ""):
+    """Save explicit human feedback to Firestore."""
+    db = get_firestore_client()
+    if not db:
+        logger.warning("Cannot save feedback: Firebase is disabled or not initialized.")
+        return
+        
+    try:
+        from datetime import datetime, timezone
+        
+        feedback_data = {
+            "session_id": session_id,
+            "message_id": message_id,
+            "is_positive": is_positive,
+            "comments": comments,
+            "timestamp": datetime.now(timezone.utc)
+        }
+        
+        db.collection("users").document(uid).collection("feedback").add(feedback_data)
+        logger.info(f"Feedback saved for user {uid}")
+    except Exception as e:
+        logger.error(f"Failed to save user feedback: {e}")

src/services/gemini_service.py

@@ -7,47 +7,54 @@ Provides:
 - 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).
+Uses Google AI Studio free tier via the google-genai SDK.
 """
 
-import re
 import time
 import logging
-import base64
 from typing import Dict, Any, Optional, AsyncGenerator
 
-from backend.src.config import settings, SYSTEM_TEMPLATE
+from backend.src.config import settings
+from backend.src.services.prompt_service import PromptService
 
 logger = logging.getLogger("math_assistant.gemini")
 
-_GEMINI_CACHE = {}
+_GEMINI_CLIENT = None
 
-
-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:
+def _get_gemini_client():
+    global _GEMINI_CLIENT
+    if _GEMINI_CLIENT is None:
+        from google import genai
         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]
+        _GEMINI_CLIENT = genai.Client(api_key=api_key)
+        logger.info("Initialized google-genai Client")
+    return _GEMINI_CLIENT
+
+def _get_safety_settings():
+    from google.genai import types
+    return [
+        types.SafetySetting(
+            category=types.HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+            threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+        ),
+        types.SafetySetting(
+            category=types.HarmCategory.HARM_CATEGORY_HARASSMENT,
+            threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+        ),
+        types.SafetySetting(
+            category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+            threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+        ),
+        types.SafetySetting(
+            category=types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+            threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
+        ),
+    ]
 
 
 class GeminiService:
@@ -56,19 +63,14 @@ class GeminiService:
     def __init__(self):
         self.primary_model = settings.gemini_primary_model
         self.fallback_model = settings.gemini_fallback_model
+        self.prompt_service = PromptService()
 
     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 "")
+        """Send a math query to Gemini and return the response."""
+        from google.genai import types
+        
+        system_template = self.prompt_service.get_system_prompt()
+        system_text = system_template.replace("{context}", context or "")
 
         # Build conversation parts
         parts = [system_text + "\n\n"]
@@ -82,15 +84,24 @@ class GeminiService:
 
         prompt = "".join(parts)
 
-        # Try primary model, then fallback
         models_to_try = [self.primary_model, self.fallback_model]
         last_error = None
+        client = _get_gemini_client()
+
+        config = types.GenerateContentConfig(
+            temperature=settings.gemini_temperature,
+            max_output_tokens=settings.gemini_max_tokens,
+            safety_settings=_get_safety_settings()
+        )
 
         for model_name in models_to_try:
-            model = _get_gemini_model(model_name)
             for attempt in range(2):
                 try:
-                    response = model.generate_content(prompt)
+                    response = client.models.generate_content(
+                        model=model_name,
+                        contents=prompt,
+                        config=config
+                    )
 
                     if response.text:
                         answer = response.text.strip()
@@ -98,10 +109,7 @@ class GeminiService:
                             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")
+                        raise Exception("Empty response or content blocked by safety filters.")
 
                 except Exception as e:
                     last_error = e
@@ -118,16 +126,16 @@ class GeminiService:
                     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 "")
+        """Stream a response token by token for SSE delivery."""
+        from google.genai import types
+        
+        system_template = self.prompt_service.get_system_prompt()
+        system_text = system_template.replace("{context}", context or "")
+        
         parts = [system_text + "\n\n"]
         if chat_history:
             for msg in chat_history:
@@ -138,10 +146,20 @@ class GeminiService:
         parts.append(f"Student: {user_input}\nTeacher: ")
         prompt = "".join(parts)
 
-        model = _get_gemini_model(self.primary_model)
+        client = _get_gemini_client()
+        config = types.GenerateContentConfig(
+            temperature=settings.gemini_temperature,
+            max_output_tokens=settings.gemini_max_tokens,
+            safety_settings=_get_safety_settings()
+        )
+
         try:
-            response = model.generate_content(prompt, stream=True)
-            for chunk in response:
+            response_stream = client.models.generate_content_stream(
+                model=self.primary_model,
+                contents=prompt,
+                config=config
+            )
+            for chunk in response_stream:
                 if chunk.text:
                     yield chunk.text
         except Exception as e:
@@ -150,24 +168,14 @@ class GeminiService:
 
 
 class GeminiVisionService:
-    """Gemini Vision for extracting math from images (replaces Tesseract OCR)."""
+    """Gemini Vision for extracting math from images."""
 
     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)
+        from google.genai import types
+        client = _get_gemini_client()
 
         prompt = (
             "You are a math OCR expert. Extract ALL mathematical content from this image.\n\n"
@@ -180,11 +188,16 @@ class GeminiVisionService:
             "6. Return ONLY the extracted math — no commentary.\n"
         )
 
+        config = types.GenerateContentConfig(safety_settings=_get_safety_settings())
         try:
-            response = model.generate_content([
-                prompt,
-                {"mime_type": mime_type, "data": image_bytes},
-            ])
+            response = client.models.generate_content(
+                model=self.model_name,
+                contents=[
+                    prompt,
+                    types.Part.from_bytes(data=image_bytes, mime_type=mime_type)
+                ],
+                config=config
+            )
             if response.text:
                 return response.text.strip()
             return "Could not extract math from image."
@@ -193,13 +206,8 @@ class GeminiVisionService:
             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)
+        from google.genai import types
+        client = _get_gemini_client()
 
         prompt = (
             "You are an Indian math teacher. Look at this image.\n\n"
@@ -211,14 +219,18 @@ class GeminiVisionService:
             "SOLUTION:\n[step-by-step solution]\n"
         )
 
+        config = types.GenerateContentConfig(safety_settings=_get_safety_settings())
         try:
-            response = model.generate_content([
-                prompt,
-                {"mime_type": mime_type, "data": image_bytes},
-            ])
+            response = client.models.generate_content(
+                model=self.model_name,
+                contents=[
+                    prompt,
+                    types.Part.from_bytes(data=image_bytes, mime_type=mime_type)
+                ],
+                config=config
+            )
             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()

src/services/memory_service.py

@@ -1,8 +1,9 @@
 """
-Chat Memory Service — MongoDB-backed persistent chat history.
+Chat Memory Service — Firestore-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.
+Provides per-session chat history with Firestore persistence and
+in-memory fallback when Firestore is unavailable.
+Replaces the MongoDB implementation from Phase 1.
 """
 
 import logging
@@ -10,6 +11,7 @@ from datetime import datetime, timezone
 from typing import List, Dict
 
 from backend.src.config import settings
+from backend.src.services.firebase_service import get_firestore_client
 
 try:
     from langchain_core.messages import HumanMessage, AIMessage
@@ -19,56 +21,59 @@ except ImportError:
 logger = logging.getLogger("math_assistant.memory")
 
 
-class MongoDBChatMemory:
-    """Per-session chat memory with MongoDB persistence and in-memory fallback."""
+class FirestoreChatMemory:
+    """Per-session chat memory with Firestore persistence and in-memory fallback."""
 
-    def __init__(self, session_id: str = "default"):
+    def __init__(self, uid: str = "anonymous", session_id: str = "default"):
+        self.uid = uid
         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")
+        self.db = get_firestore_client()
+
+    def _get_collection_ref(self):
+        """Get a reference to the session's messages subcollection."""
+        if not self.db:
+            return None
+        return self.db.collection("users").document(self.uid).collection("sessions").document(self.session_id).collection("messages")
 
     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:
+        
+        col_ref = self._get_collection_ref()
+        if col_ref is not None:
             try:
-                self.collection.insert_one(msg)
+                col_ref.add(msg)
                 return
-            except Exception:
-                pass
+            except Exception as e:
+                logger.error(f"Failed to add message to Firestore: {e}")
+
+        # Fallback to in-memory
+        msg["session_id"] = self.session_id
         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:
+        col_ref = self._get_collection_ref()
+        if col_ref is not None:
             try:
-                msgs = list(
-                    self.collection.find({"session_id": self.session_id})
-                    .sort("timestamp", -1)
+                from firebase_admin import firestore
+                docs = (
+                    col_ref.order_by("timestamp", direction=firestore.Query.DESCENDING)
                     .limit(limit)
+                    .stream()
                 )
+                msgs = [doc.to_dict() for doc in docs]
                 msgs.reverse()
                 return msgs
-            except Exception:
-                pass
+            except Exception as e:
+                logger.error(f"Failed to get history from Firestore: {e}")
+
+        # Fallback to in-memory
         return self._memory[-limit:]
 
     def get_langchain_messages(self, limit: int = 10):
@@ -76,17 +81,29 @@ class MongoDBChatMemory:
         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"]))
+            if msg.get("role") == "human":
+                result.append(HumanMessage(content=msg.get("content", "")))
+            elif msg.get("role") == "assistant":
+                result.append(AIMessage(content=msg.get("content", "")))
         return result
 
     def clear_history(self):
         """Clear all messages for this session."""
-        if self.collection is not None:
+        col_ref = self._get_collection_ref()
+        if col_ref is not None:
             try:
-                self.collection.delete_many({"session_id": self.session_id})
-            except Exception:
-                pass
+                docs = col_ref.limit(500).stream()
+                batch = self.db.batch()
+                count = 0
+                for doc in docs:
+                    batch.delete(doc.reference)
+                    count += 1
+                if count > 0:
+                    batch.commit()
+            except Exception as e:
+                logger.error(f"Failed to clear history in Firestore: {e}")
+
         self._memory.clear()
+
+# Maintain backward compatibility name for the MathAIEngine import during transition
+MongoDBChatMemory = FirestoreChatMemory

src/services/prompt_service.py

@@ -0,0 +1,164 @@
+import logging
+from google.cloud import firestore
+from backend.src.config import settings
+
+logger = logging.getLogger("math_assistant.prompt")
+
+DEFAULT_SYSTEM_PROMPT = """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 strictly for all math: `$...$` for inline, `$$...$$` for block.
+→ Hindi/Hinglish question → answer in same language
+
+Context from knowledge base:
+{context}
+"""
+
+class PromptService:
+    def __init__(self):
+        self.db = None
+        if settings.use_firebase:
+            try:
+                self.db = firestore.Client()
+            except Exception as e:
+                logger.warning(f"Could not initialize Firestore client for prompts: {e}")
+
+    def get_system_prompt(self, version: str = "latest", ab_test_group: str = None) -> str:
+        """Fetch the system prompt from Firestore with optional A/B testing variations."""
+        if not self.db:
+            return DEFAULT_SYSTEM_PROMPT
+            
+        try:
+            # For A/B testing, fetch from the "prompts" collection
+            # Using document ID "system_prompt_A" or "system_prompt_B" based on group
+            doc_id = f"system_prompt_{ab_test_group}" if ab_test_group else "system_prompt"
+            doc_ref = self.db.collection("prompts").document(doc_id)
+            doc = doc_ref.get()
+            
+            if doc.exists:
+                data = doc.to_dict()
+                # Check if specific version requested, otherwise use 'latest' or 'active' pointer
+                target_version = version
+                if target_version == "latest":
+                    target_version = data.get("active_version", "v1")
+                
+                template = data.get("versions", {}).get(target_version)
+                if template:
+                    return template
+                else:
+                    logger.warning(f"Version {target_version} not found in Firestore. Using fallback.")
+            else:
+                logger.warning(f"Prompt document {doc_id} not found in Firestore. Using fallback.")
+                
+        except Exception as e:
+            logger.error(f"Error fetching prompt from Firestore: {e}. Using fallback.")
+            
+        return DEFAULT_SYSTEM_PROMPT

src/services/qdrant_service.py

@@ -0,0 +1,145 @@
+"""
+Qdrant Vector Service — Hybrid Search (Dense + Sparse).
+"""
+
+import logging
+from typing import List, Dict, Any, Optional
+
+from qdrant_client import QdrantClient
+from langchain_qdrant import QdrantVectorStore, RetrievalMode, FastEmbedSparse
+
+from backend.src.config import settings
+from backend.src.services.embedding_service import get_dense_embeddings
+
+logger = logging.getLogger("math_assistant.qdrant")
+
+class QdrantService:
+    """Manages the Qdrant Cloud or local vector store with Hybrid Search."""
+
+    def __init__(self):
+        self.collection_name = settings.collection_name
+        self.url = getattr(settings, "qdrant_url", ":memory:")
+        self.api_key = getattr(settings, "qdrant_api_key", "")
+        
+        logger.info(f"Initializing Qdrant at {self.url}")
+        
+        # 1. Initialize Client
+        if self.url == ":memory:":
+            self.client = QdrantClient(location=":memory:")
+        else:
+            self.client = QdrantClient(
+                url=self.url,
+                api_key=self.api_key if self.api_key else None
+            )
+            
+        # 2. Get dense embeddings
+        self.dense_embeddings = get_dense_embeddings()
+        
+        # 3. Setup sparse embeddings for hybrid search
+        self.sparse_embeddings = FastEmbedSparse(model_name="Qdrant/bm25")
+        
+        # 4. Create collection if not exists
+        if not self.client.collection_exists(self.collection_name):
+            from qdrant_client.http import models as rest
+            
+            # Since we are using Hybrid search (dense + sparse), we need to configure vectors properly.
+            # But langchain_qdrant handles the schema if we use `from_texts`/`from_documents`.
+            # A safer way to initialize an empty hybrid store is to let langchain_qdrant handle it:
+            # We can just skip manual creation and let `add_documents` handle it, but `QdrantVectorStore` 
+            # init requires the collection to exist if we pass `client`.
+            
+            # Let's create it with the correct dimensions for HuggingFace (384) or Gemini (768).
+            # But wait, QdrantVectorStore.from_texts() creates everything automatically.
+            pass  # We will defer instantiation if it doesn't exist, or just use from_documents later.
+            
+        # Actually, LangChain's QdrantVectorStore has a parameter `force_recreate=True/False` or we can just 
+        # let `from_texts` do the heavy lifting in `add_documents`.
+        # For simplicity, we just initialize it:
+        try:
+            self.vectorstore = QdrantVectorStore(
+                client=self.client,
+                collection_name=self.collection_name,
+                embedding=self.dense_embeddings,
+                sparse_embedding=self.sparse_embeddings,
+                retrieval_mode=RetrievalMode.HYBRID
+            )
+        except ValueError as e:
+            if "not found" in str(e):
+                logger.warning(f"Collection {self.collection_name} not found. It will be created upon first insertion.")
+                self.vectorstore = None
+            else:
+                raise e
+
+    def add_documents(self, documents: List[Any]):
+        """Index documents into Qdrant."""
+        logger.info(f"Indexing {len(documents)} documents into Qdrant...")
+        if self.vectorstore is None:
+            self.vectorstore = QdrantVectorStore.from_documents(
+                documents,
+                embedding=self.dense_embeddings,
+                sparse_embedding=self.sparse_embeddings,
+                location=self.url if self.url == ":memory:" else None,
+                url=self.url if self.url != ":memory:" else None,
+                api_key=self.api_key if self.api_key and self.url != ":memory:" else None,
+                collection_name=self.collection_name,
+                retrieval_mode=RetrievalMode.HYBRID
+            )
+        else:
+            self.vectorstore.add_documents(documents)
+        logger.info("Indexing complete.")
+
+    def similarity_search(
+        self, 
+        query: str, 
+        k: int = 5, 
+        filter_topic: Optional[str] = None,
+        filter_class: Optional[str] = None,
+        filter_chapter: Optional[str] = None
+    ) -> List[Any]:
+        """Hybrid search with metadata filtering."""
+        
+        from qdrant_client.http import models as rest
+        
+        filter_conditions = []
+        if filter_topic:
+            filter_conditions.append(rest.FieldCondition(key="topic", match=rest.MatchValue(value=filter_topic)))
+        if filter_class:
+            filter_conditions.append(rest.FieldCondition(key="class_level", match=rest.MatchValue(value=filter_class)))
+        if filter_chapter:
+            filter_conditions.append(rest.FieldCondition(key="chapter", match=rest.MatchValue(value=filter_chapter)))
+            
+        qdrant_filter = rest.Filter(must=filter_conditions) if filter_conditions else None
+        
+        try:
+            return self.vectorstore.similarity_search(
+                query=query, 
+                k=k, 
+                filter=qdrant_filter
+            )
+        except Exception as e:
+            logger.error(f"Qdrant search failed: {e}")
+            return []
+
+    def as_retriever(self, k: int = 5, metadata_filters: Dict[str, Any] = None):
+        """Return a LangChain retriever interface with dynamic filters."""
+        from qdrant_client.http import models as rest
+        
+        qdrant_filter = None
+        if metadata_filters:
+            conditions = []
+            for key, val in metadata_filters.items():
+                conditions.append(rest.FieldCondition(key=key, match=rest.MatchValue(value=val)))
+            qdrant_filter = rest.Filter(must=conditions)
+            
+        search_kwargs = {"k": k}
+        if qdrant_filter:
+            search_kwargs["filter"] = qdrant_filter
+            
+        return self.vectorstore.as_retriever(search_kwargs=search_kwargs)
+
+    def get_document_count(self) -> int:
+        """Count total documents in collection."""
+        try:
+            return self.client.count(self.collection_name).count
+        except Exception:
+            return 0

src/services/vector_service.py

@@ -137,21 +137,28 @@ class MathVectorStore:
 
 _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
-
+def build_pipeline(force_rebuild=False):
+    """Build or load the knowledge base pipeline."""
+    from backend.src.config import settings
+    
     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).")
+        
+    if getattr(settings, "vector_db", "qdrant") == "qdrant":
+        from backend.src.services.qdrant_service import QdrantService
+        store = QdrantService()
+        if store.get_document_count() == 0 or force_rebuild:
+            from backend.src.math.knowledge_indexer import KnowledgeIndexer
+            indexer = KnowledgeIndexer()
+            indexer.index_all()
+        _PIPELINE_CACHE["store"] = store
+        return store
+    else:
+        # Fallback to Chroma (legacy)
+        store = MathVectorStore()
+        if store.is_ready() and not force_rebuild:
+            logger.info(f"Knowledge base already built ({store.get_document_count()} docs).")
+        else:
+            logger.warning("Chroma build from scratch is deprecated. Please use Qdrant.")
         _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