Upload 23 files

backend/main.py

@@ -0,0 +1,117 @@
+"""
+FastAPI backend for Math Agentic RAG system.
+"""
+import sys
+import os
+from pathlib import Path
+
+# Add the parent directory to Python path to import database module
+parent_dir = Path(__file__).parent.parent
+sys.path.append(str(parent_dir))
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+import logging
+import structlog
+from dotenv import load_dotenv
+
+# Import routes
+from routes.search import router as search_router
+from routes.feedback import router as feedback_router
+
+# Load environment variables
+load_dotenv()
+
+# Configure structured logging
+structlog.configure(
+    processors=[
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.UnicodeDecoder(),
+        structlog.processors.JSONRenderer()
+    ],
+    context_class=dict,
+    logger_factory=structlog.stdlib.LoggerFactory(),
+    cache_logger_on_first_use=True,
+)
+
+logger = structlog.get_logger()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    logger.info("Starting Math Agentic RAG Backend...")
+    
+    # Startup
+    try:
+        # Initialize services here if needed
+        logger.info("Backend services initialized successfully")
+        yield
+    except Exception as e:
+        logger.error("Failed to initialize backend services", error=str(e))
+        raise
+    finally:
+        # Cleanup
+        logger.info("Shutting down Math Agentic RAG Backend...")
+
+# Create FastAPI application
+app = FastAPI(
+    title="Math Agentic RAG API",
+    description="Backend API for Math-focused Agentic RAG system with knowledge base and web search capabilities",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure this properly for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(search_router, prefix="/api", tags=["search"])
+app.include_router(feedback_router, prefix="/api", tags=["feedback"])
+
+@app.get("/")
+async def root():
+    """Root endpoint for health check."""
+    return {
+        "message": "Math Agentic RAG Backend API",
+        "status": "running",
+        "version": "1.0.0",
+        "docs": "/docs"
+    }
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "timestamp": structlog.processors.TimeStamper(fmt="iso")._stamper(),
+        "services": {
+            "api": "running",
+            "database": "connected",  # Will be updated with actual checks
+            "mcp": "available"        # Will be updated with actual checks
+        }
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        log_level="info"
+    )

backend/models/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file to make this a Python package

backend/models/schemas.py

@@ -0,0 +1,61 @@
+"""
+Pydantic models for API request/response schemas.
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+from datetime import datetime
+import uuid
+
+# Request Models
+class SearchRequest(BaseModel):
+    """Request model for search endpoint."""
+    question: str = Field(..., description="Math question to search for", max_length=200)
+
+class FeedbackRequest(BaseModel):
+    """Request model for feedback endpoint."""
+    question: str = Field(..., description="Original question")
+    response_id: str = Field(..., description="UUID of the response")
+    correctness_rating: int = Field(..., ge=1, le=5, description="Rating from 1-5")
+    comment: str = Field("", description="Optional feedback comment")
+
+# Response Models
+class SearchResult(BaseModel):
+    """Individual search result."""
+    problem: str = Field(..., description="Math problem statement")
+    solution: str = Field(..., description="Solution to the problem")
+    score: float = Field(..., description="Similarity score")
+
+class SearchResponse(BaseModel):
+    """Response model for search endpoint."""
+    response_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    final_answer: str = Field(..., description="The main answer to the question")
+    source: Literal["KB", "MCP", "Gemini"] = Field(..., description="Source of the answer")
+    explanation: Optional[str] = Field(None, description="Optional explanation")
+    results: List[SearchResult] = Field(default_factory=list, description="Detailed search results")
+    metadata: dict = Field(default_factory=dict, description="Additional metadata")
+    response_time_ms: Optional[float] = Field(None, description="Response time in milliseconds")
+
+class FeedbackResponse(BaseModel):
+    """Response model for feedback endpoint."""
+    message: str = Field(..., description="Confirmation message")
+    feedback_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+
+# Internal Models
+class APILogEntry(BaseModel):
+    """Model for logging API requests and responses."""
+    request_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    endpoint: str = Field(..., description="API endpoint called")
+    method: str = Field(..., description="HTTP method")
+    request_data: dict = Field(..., description="Request payload")
+    response_data: dict = Field(..., description="Response payload")
+    response_time_ms: float = Field(..., description="Response time in milliseconds")
+    source: Literal["KB", "MCP", "Gemini"] = Field(..., description="Source of the answer")
+    feedback_received: bool = Field(default=False, description="Whether feedback was received")
+    status_code: int = Field(..., description="HTTP status code")
+
+class ErrorResponse(BaseModel):
+    """Standard error response model."""
+    error: str = Field(..., description="Error message")
+    detail: Optional[str] = Field(None, description="Detailed error information")
+    request_id: Optional[str] = Field(None, description="Request ID for tracking")

backend/requirements.txt

@@ -0,0 +1,44 @@
+# FastAPI and web server
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+
+# HTTP client for MCP calls
+httpx==0.25.2
+
+# Qdrant vector database
+qdrant-client==1.8.0
+
+# AI Guardrails
+guardrails-ai==0.4.5
+
+# Google Generative AI (Gemini)
+google-generativeai==0.8.3
+
+# Environment management
+python-dotenv==1.0.0
+
+# Structured logging
+structlog==23.2.0
+
+# Data processing and embeddings (reusing from database module)
+sentence-transformers==2.2.2
+datasets==2.18.0
+pandas==2.1.4
+
+# MCP client (for web search integration)
+fastmcp==0.3.0
+
+# Logging and monitoring
+structlog==23.2.0
+
+# Data validation
+pydantic==2.5.0
+
+# Async support
+asyncio==3.4.3
+
+# UUID generation (built-in, but listed for clarity)
+# uuid (built-in)
+
+# JSON handling
+orjson==3.9.10

backend/routes/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file to make this a Python package

backend/routes/feedback.py

@@ -0,0 +1,91 @@
+"""
+Feedback endpoint for the Math Agentic RAG system.
+"""
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+import structlog
+import time
+from typing import Dict, Any
+
+from models.schemas import FeedbackRequest, FeedbackResponse, ErrorResponse
+
+router = APIRouter()
+logger = structlog.get_logger()
+
+@router.post("/feedback", response_model=FeedbackResponse)
+async def submit_feedback(
+    feedback: FeedbackRequest,
+    background_tasks: BackgroundTasks
+) -> FeedbackResponse:
+    """
+    Submit user feedback for search results.
+    
+    Args:
+        feedback: Feedback data including response_id, rating, and comments
+        background_tasks: Background tasks for processing
+        
+    Returns:
+        FeedbackResponse confirming feedback receipt
+    """
+    start_time = time.time()
+    
+    try:
+        logger.info("Processing feedback submission",
+                   response_id=feedback.response_id,
+                   rating=feedback.rating,
+                   has_comments=bool(feedback.comments))
+        
+        # Process feedback in background
+        background_tasks.add_task(
+            process_feedback,
+            feedback.dict()
+        )
+        
+        response_time_ms = (time.time() - start_time) * 1000
+        
+        response = FeedbackResponse(
+            message="Feedback received successfully",
+            feedback_id=feedback.response_id,  # Using response_id as feedback_id for traceability
+            status="received"
+        )
+        
+        logger.info("Feedback submission completed",
+                   response_id=feedback.response_id,
+                   response_time_ms=response_time_ms)
+        
+        return response
+        
+    except Exception as e:
+        logger.error("Feedback submission failed",
+                    response_id=feedback.response_id,
+                    error=str(e))
+        
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to process feedback: {str(e)}"
+        )
+
+async def process_feedback(feedback_data: Dict[str, Any]):
+    """
+    Process feedback data in the background.
+    
+    This function will:
+    1. Store feedback in Qdrant for analysis
+    2. Update system metrics
+    3. Trigger retraining if needed (future enhancement)
+    """
+    try:
+        logger.info("Processing feedback in background",
+                   response_id=feedback_data.get("response_id"))
+        
+        # TODO: Implement feedback storage in Qdrant
+        # TODO: Update system performance metrics
+        # TODO: Implement feedback-based model improvements
+        
+        # For now, just log the feedback
+        logger.info("Feedback processed successfully",
+                   feedback_data=feedback_data)
+                   
+    except Exception as e:
+        logger.error("Background feedback processing failed",
+                    error=str(e),
+                    feedback_data=feedback_data)

backend/routes/search.py

@@ -0,0 +1,452 @@
+"""
+Search endpoint for the Math Agentic RAG system.
+"""
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+import sys
+from pathlib import Path
+import structlog
+import time
+import uuid
+
+# Add parent directory to import database module
+parent_dir = Path(__file__).parent.parent.parent
+sys.path.append(str(parent_dir))
+
+from models.schemas import SearchRequest, SearchResponse, ErrorResponse, SearchResult
+from services.qdrant_service import QdrantService
+from services.mcp_service import MCPService
+from services.guardrails_service import GuardrailsService
+from services.gemini_service import GeminiService
+
+router = APIRouter()
+logger = structlog.get_logger()
+
+# Initialize services (will be properly initialized when packages are installed)
+qdrant_service = None
+mcp_service = None
+guardrails_service = None
+gemini_service = None
+
+def initialize_services():
+    """Initialize services on first request."""
+    global qdrant_service, mcp_service, guardrails_service, gemini_service
+    
+    if qdrant_service is None:
+        qdrant_service = QdrantService()
+        mcp_service = MCPService()
+        guardrails_service = GuardrailsService()
+        gemini_service = GeminiService()
+
+@router.post("/search", response_model=SearchResponse)
+async def search_math_problems(
+    request: SearchRequest,
+    background_tasks: BackgroundTasks
+) -> SearchResponse:
+    """
+    Search for math problems in knowledge base or web.
+    
+    Args:
+        request: Search request containing the math question
+        background_tasks: Background tasks for logging
+        
+    Returns:
+        SearchResponse with results and metadata
+    """
+    start_time = time.time()
+    response_id = str(uuid.uuid4())
+    
+    try:
+        # Initialize services if not already done
+        initialize_services()
+        
+        logger.info("Processing search request", 
+                   request_id=response_id, 
+                   question=request.question)
+        
+        # Step 1: Validate input with guardrails
+        validated_question = guardrails_service.validate_input(request.question)
+        
+        # Step 2: Search knowledge base (Qdrant)
+        kb_results = await qdrant_service.search_similar(validated_question)
+        
+        # Step 3: Determine if we need web search fallback with enhanced logic
+        confidence_threshold = 0.8  # Increased from 0.5 to 0.8 for higher confidence requirement
+        best_score = kb_results[0].score if kb_results else 0.0
+        
+        logger.info("Evaluating search results",
+                   kb_results_found=len(kb_results) if kb_results else 0,
+                   best_score=best_score,
+                   threshold=confidence_threshold)
+        
+        if best_score >= confidence_threshold:
+            # Use knowledge base results - high confidence match found
+            source = "KB"
+            final_answer = kb_results[0].solution if kb_results else "No solution found"
+            explanation = f"High confidence match found (score: {best_score:.3f} ≥ {confidence_threshold})"
+            results = kb_results[:3]  # Return top 3 results
+            
+            logger.info("Using knowledge base results",
+                       confidence_score=best_score,
+                       results_returned=len(results))
+            
+        else:
+            # First fallback: Web search via MCP
+            logger.info("Low confidence KB results, trying web search fallback",
+                       best_score=best_score, 
+                       threshold=confidence_threshold)
+            
+            try:
+                web_results = await mcp_service.search_web(validated_question)
+                mcp_answer = web_results.get("answer", "")
+                mcp_confidence = web_results.get("confidence", 0.6)  # Default MCP confidence
+                
+                logger.info("MCP web search completed",
+                           answer_length=len(mcp_answer),
+                           mcp_confidence=mcp_confidence)
+                
+                # Check if MCP results meet confidence threshold
+                if mcp_confidence >= confidence_threshold and mcp_answer:
+                    # Use MCP results - sufficient confidence
+                    source = "MCP"
+                    final_answer = mcp_answer
+                    explanation = f"KB confidence too low ({best_score:.3f} < {confidence_threshold}), used web search (confidence: {mcp_confidence:.3f})"
+                    
+                    results = [SearchResult(
+                        problem=validated_question,
+                        solution=final_answer,
+                        score=mcp_confidence
+                    )]
+                    
+                    logger.info("Using MCP web search results",
+                               mcp_confidence=mcp_confidence)
+                
+                else:
+                    # Second fallback: Gemini LLM when both KB and MCP have low confidence
+                    logger.info("Both KB and MCP have low confidence, falling back to Gemini LLM",
+                               kb_score=best_score,
+                               mcp_confidence=mcp_confidence,
+                               threshold=confidence_threshold)
+                    
+                    try:
+                        if gemini_service and gemini_service.is_available():
+                            gemini_result = await gemini_service.solve_math_problem(validated_question)
+                            
+                            source = "Gemini"
+                            final_answer = gemini_result.get("answer", "No solution generated")
+                            gemini_confidence = gemini_result.get("confidence", 0.75)
+                            explanation = f"Both KB ({best_score:.3f}) and MCP ({mcp_confidence:.3f}) below threshold ({confidence_threshold}), used Gemini LLM"
+                            
+                            results = [SearchResult(
+                                problem=validated_question,
+                                solution=final_answer,
+                                score=gemini_confidence
+                            )]
+                            
+                            logger.info("Gemini LLM response generated successfully",
+                                       answer_length=len(final_answer),
+                                       gemini_confidence=gemini_confidence)
+                        
+                        else:
+                            # Ultimate fallback: Use best available result
+                            logger.warning("Gemini service unavailable, using best available result")
+                            
+                            if mcp_answer and len(mcp_answer) > 20:  # Prefer MCP if it has substantial content
+                                source = "MCP"
+                                final_answer = mcp_answer
+                                explanation = f"All services below threshold, using MCP result (confidence: {mcp_confidence:.3f})"
+                                results = [SearchResult(problem=validated_question, solution=final_answer, score=mcp_confidence)]
+                            else:
+                                source = "KB"
+                                final_answer = kb_results[0].solution if kb_results else "No solution available"
+                                explanation = f"All services below threshold, using best KB result (score: {best_score:.3f})"
+                                results = kb_results[:1] if kb_results else []
+                    
+                    except Exception as gemini_error:
+                        logger.error("Gemini LLM failed, using MCP results", error=str(gemini_error))
+                        source = "MCP"
+                        final_answer = mcp_answer if mcp_answer else "No solution available"
+                        explanation = f"Gemini failed, used MCP result (confidence: {mcp_confidence:.3f})"
+                        results = [SearchResult(problem=validated_question, solution=final_answer, score=mcp_confidence)] if mcp_answer else []
+                
+            except Exception as mcp_error:
+                logger.error("MCP web search failed, trying Gemini fallback", error=str(mcp_error))
+                
+                # If MCP fails, try Gemini directly
+                try:
+                    if gemini_service and gemini_service.is_available():
+                        gemini_result = await gemini_service.solve_math_problem(validated_question)
+                        
+                        source = "Gemini"
+                        final_answer = gemini_result.get("answer", "No solution generated")
+                        gemini_confidence = gemini_result.get("confidence", 0.75)
+                        explanation = f"KB confidence low ({best_score:.3f}), MCP failed, used Gemini LLM"
+                        
+                        results = [SearchResult(
+                            problem=validated_question,
+                            solution=final_answer,
+                            score=gemini_confidence
+                        )]
+                        
+                        logger.info("Gemini LLM used after MCP failure",
+                                   answer_length=len(final_answer))
+                    
+                    else:
+                        # Final fallback to KB results
+                        logger.warning("Both MCP and Gemini failed, using KB results")
+                        source = "KB"
+                        final_answer = kb_results[0].solution if kb_results else "No solution available"
+                        explanation = f"MCP and Gemini failed, using best KB result (score: {best_score:.3f})"
+                        results = kb_results[:1] if kb_results else []
+                
+                except Exception as final_error:
+                    logger.error("All fallbacks failed, using KB results", error=str(final_error))
+                    source = "KB"
+                    final_answer = kb_results[0].solution if kb_results else "No solution available"
+                    explanation = f"All services failed, using best KB result (score: {best_score:.3f})"
+                    results = kb_results[:1] if kb_results else []
+        
+        
+        # Step 4: Validate output with guardrails and create comprehensive response
+        logger.info("Validating final answer with guardrails",
+                   answer_length=len(final_answer),
+                   source=source)
+        
+        try:
+            validated_response = guardrails_service.validate_output(final_answer)
+            
+            # Check if validation changed the response
+            if validated_response != final_answer:
+                logger.warning("Guardrails modified the response",
+                             original_length=len(final_answer),
+                             validated_length=len(validated_response))
+            
+        except Exception as e:
+            logger.error("Guardrails validation failed, using original response", error=str(e))
+            validated_response = final_answer
+        
+        # Calculate response time
+        response_time_ms = (time.time() - start_time) * 1000
+        
+        # Create comprehensive response with enhanced metadata
+        response = SearchResponse(
+            response_id=response_id,
+            final_answer=validated_response,
+            source=source,
+            explanation=explanation,
+            results=results,
+            metadata={
+                "confidence_score": best_score,
+                "threshold_used": confidence_threshold,
+                "kb_results_count": len(kb_results) if kb_results else 0,
+                "search_strategy": "semantic_similarity" if source == "KB" else "web_search",
+                "guardrails_applied": validated_response != final_answer,
+                "processing_time_ms": response_time_ms
+            },
+            response_time_ms=response_time_ms
+        )
+        
+        logger.info("Response created successfully",
+                   response_id=response_id,
+                   final_answer_length=len(validated_response),
+                   results_count=len(results),
+                   metadata_fields=len(response.metadata))
+        
+        # Step 5: Post-processing, analytics, and optimization
+        logger.info("Starting post-processing and analytics",
+                   response_id=response_id,
+                   source=source)
+        
+        try:
+            # 5.1: Performance optimization - cache high-confidence results
+            if source == "KB" and best_score >= 0.9:
+                logger.info("High confidence result detected for potential caching",
+                           confidence_score=best_score,
+                           question_hash=hash(validated_question))
+            
+            # 5.2: Quality assessment
+            response_quality = assess_response_quality(
+                question=validated_question,
+                answer=validated_response,
+                source=source,
+                confidence=best_score
+            )
+            
+            # 5.3: Add quality metrics to metadata
+            response.metadata.update({
+                "response_quality": response_quality,
+                "optimization_applied": best_score >= 0.9,
+                "search_efficiency": calculate_search_efficiency(
+                    kb_results_count=len(kb_results) if kb_results else 0,
+                    source=source,
+                    response_time_ms=response_time_ms
+                )
+            })
+            
+            # 5.4: Trigger analytics and learning
+            background_tasks.add_task(
+                update_analytics,
+                question=validated_question,
+                response_data=response.dict(),
+                performance_metrics={
+                    "kb_hit": source == "KB",
+                    "confidence_score": best_score,
+                    "response_time_ms": response_time_ms,
+                    "quality_score": response_quality
+                }
+            )
+            
+            logger.info("Post-processing completed successfully",
+                       response_id=response_id,
+                       quality_score=response_quality,
+                       total_metadata_fields=len(response.metadata))
+            
+        except Exception as e:
+            logger.warning("Post-processing failed, but response is still valid", 
+                          error=str(e), response_id=response_id)
+        
+        # Log API call in background for analytics
+        background_tasks.add_task(
+            log_api_call,
+            request=request.dict(),
+            response=response.dict(),
+            response_time_ms=response_time_ms,
+            source=source
+        )
+        
+        # Final completion log with comprehensive metrics
+        logger.info("Search request completed successfully",
+                   request_id=response_id,
+                   source=source,
+                   confidence_score=best_score,
+                   threshold_used=confidence_threshold,
+                   kb_results_count=len(kb_results) if kb_results else 0,
+                   final_results_count=len(results),
+                   response_time_ms=response_time_ms,
+                   guardrails_applied=response.metadata.get("guardrails_applied", False))
+        
+        return response
+        
+    except Exception as e:
+        logger.error("Search request failed", 
+                    request_id=response_id, 
+                    error=str(e))
+        
+        raise HTTPException(
+            status_code=500,
+            detail=f"Internal server error: {str(e)}"
+        )
+
+async def log_api_call(
+    request: dict,
+    response: dict,
+    response_time_ms: float,
+    source: str
+):
+    """Log API call to Qdrant for analytics."""
+    try:
+        if qdrant_service:
+            await qdrant_service.log_api_call(
+                endpoint="/search",
+                method="POST",
+                request_data=request,
+                response_data=response,
+                response_time_ms=response_time_ms,
+                source=source
+            )
+    except Exception as e:
+        logger.warning("Failed to log API call", error=str(e))
+
+def assess_response_quality(question: str, answer: str, source: str, confidence: float) -> float:
+    """
+    Assess the quality of the response based on multiple factors.
+    
+    Returns:
+        Quality score between 0.0 and 1.0
+    """
+    try:
+        quality_score = 0.0
+        
+        # Factor 1: Answer length (not too short, not too long)
+        answer_length = len(answer.strip())
+        if 50 <= answer_length <= 2000:
+            quality_score += 0.3
+        elif answer_length > 20:
+            quality_score += 0.1
+        
+        # Factor 2: Source reliability
+        if source == "KB":
+            quality_score += 0.4 * confidence  # Scale by confidence
+        else:
+            quality_score += 0.3  # Web search baseline
+        
+        # Factor 3: Mathematical content indicators
+        math_indicators = ['=', '+', '-', '*', '/', '^', '√', '∫', '∑', 'x', 'y', 'equation']
+        math_content = sum(1 for indicator in math_indicators if indicator in answer.lower())
+        quality_score += min(0.3, math_content * 0.05)
+        
+        return min(1.0, quality_score)
+        
+    except Exception as e:
+        logger.warning("Quality assessment failed", error=str(e))
+        return 0.5  # Default neutral score
+
+def calculate_search_efficiency(kb_results_count: int, source: str, response_time_ms: float) -> float:
+    """
+    Calculate search efficiency based on results and performance.
+    
+    Returns:
+        Efficiency score between 0.0 and 1.0
+    """
+    try:
+        efficiency = 0.0
+        
+        # Factor 1: Speed (faster is better)
+        if response_time_ms < 1000:
+            efficiency += 0.5
+        elif response_time_ms < 3000:
+            efficiency += 0.3
+        else:
+            efficiency += 0.1
+        
+        # Factor 2: Result availability
+        if kb_results_count > 0:
+            efficiency += 0.3
+        
+        # Factor 3: Source efficiency (KB is more efficient)
+        if source == "KB":
+            efficiency += 0.2
+        
+        return min(1.0, efficiency)
+        
+    except Exception as e:
+        logger.warning("Efficiency calculation failed", error=str(e))
+        return 0.5
+
+async def update_analytics(question: str, response_data: dict, performance_metrics: dict):
+    """
+    Update analytics and learning systems with search data.
+    """
+    try:
+        logger.info("Updating analytics",
+                   kb_hit=performance_metrics.get("kb_hit", False),
+                   confidence=performance_metrics.get("confidence_score", 0),
+                   quality=performance_metrics.get("quality_score", 0))
+        
+        # Future: Could integrate with ML systems for:
+        # - Query pattern analysis
+        # - Response quality improvement
+        # - Automatic threshold adjustment
+        # - Usage pattern detection
+        
+        # For now, just comprehensive logging
+        analytics_data = {
+            "question_length": len(question),
+            "question_hash": hash(question),
+            "timestamp": time.time(),
+            **performance_metrics
+        }
+        
+        logger.info("Analytics updated", **analytics_data)
+        
+    except Exception as e:
+        logger.warning("Analytics update failed", error=str(e))

backend/services/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file to make this a Python package

backend/services/gemini_service.py

@@ -0,0 +1,219 @@
+"""
+Gemini LLM service for final fallback when both KB and MCP have low confidence.
+"""
+import os
+import re
+import structlog
+import google.generativeai as genai
+from typing import Dict, Optional
+
+logger = structlog.get_logger()
+
+
+class GeminiService:
+    """Service for interacting with Google Gemini 2.5 Pro."""
+    
+    def __init__(self):
+        """Initialize Gemini service."""
+        self.api_key = os.getenv("GEMINI_API_KEY")
+        if not self.api_key:
+            logger.warning("GEMINI_API_KEY not found in environment variables")
+            self.client = None
+            return
+            
+        try:
+            genai.configure(api_key=self.api_key)
+            self.model = genai.GenerativeModel('gemini-2.0-flash-exp')
+            logger.info("Gemini service initialized successfully")
+        except Exception as e:
+            logger.error("Failed to initialize Gemini service", error=str(e))
+            self.client = None
+    
+    async def solve_math_problem(self, question: str) -> Dict[str, any]:
+        """
+        Solve a math problem using Gemini 2.5 Pro.
+        
+        Args:
+            question: The math question to solve
+            
+        Returns:
+            Dict containing the solution and metadata
+        """
+        if not self.model:
+            raise Exception("Gemini service not properly initialized")
+        
+        try:
+            # Create a comprehensive prompt for math problem solving
+            prompt = self._create_math_prompt(question)
+            
+            logger.info("Sending request to Gemini", question_length=len(question))
+            
+            # Generate response
+            response = await self._generate_response(prompt)
+            
+            # Parse and validate the response
+            result = self._parse_response(response, question)
+            
+            logger.info("Gemini response generated successfully", 
+                       answer_length=len(result.get("answer", "")))
+            
+            return result
+            
+        except Exception as e:
+            logger.error("Error in Gemini math problem solving", error=str(e))
+            raise
+    
+    def _create_math_prompt(self, question: str) -> str:
+        """Create a comprehensive prompt for math problem solving."""
+        return f"""You are an expert mathematics tutor. Solve this math problem with precision and clarity.
+
+QUESTION: {question}
+
+CRITICAL FORMATTING REQUIREMENT - THIS IS MANDATORY:
+You MUST wrap every single mathematical expression in dollar signs ($). No exceptions.
+
+RESPONSE FORMAT:
+Solution Steps:
+[Provide numbered steps with clear explanations]
+
+Final Answer:
+[State the final answer clearly and concisely]
+
+Verification (if applicable):
+[Show verification using an alternative method or substitution]
+
+MANDATORY MATH FORMATTING EXAMPLES - COPY THIS STYLE EXACTLY:
+- Write: "For the term $3x^2$, we have $a = 3$ and $n = 2$"
+- Write: "The function $f(x) = 3x^2 + 2x - 1$"
+- Write: "The derivative is $f'(x) = 6x + 2$"
+- Write: "Apply the power rule: if $f(x) = ax^n$, then $f'(x) = nax^{{n-1}}$"
+
+NEVER WRITE MATH WITHOUT DOLLAR SIGNS:
+- WRONG: "For the term 3x^2, we have a = 3 and n = 2"
+- WRONG: "The function f(x) = 3x^2 + 2x - 1"
+- WRONG: "The derivative is f'(x) = 6x + 2"
+
+EVERYTHING mathematical must have $ around it: variables, numbers in math context, equations, expressions.
+
+Begin your solution now, remembering to wrap ALL math in $ signs:"""
+    
+    async def _generate_response(self, prompt: str) -> str:
+        """Generate response from Gemini."""
+        try:
+            # Generate content using the configured model
+            response = self.model.generate_content(prompt)
+            
+            if not response.text:
+                raise Exception("Empty response from Gemini")
+            
+            return response.text
+            
+        except Exception as e:
+            logger.error("Error generating Gemini response", error=str(e))
+            raise
+    
+    def _parse_response(self, response: str, original_question: str) -> Dict[str, any]:
+        """Parse Gemini response into structured format."""
+        try:
+            # Clean up the response
+            cleaned_response = self._clean_response(response)
+            
+            return {
+                "answer": cleaned_response,
+                "confidence": 0.85,  # Increased confidence for better structured responses
+                "source": "Gemini",
+                "original_question": original_question,
+                "response_length": len(cleaned_response),
+                "model": "gemini-2.0-flash-exp"
+            }
+            
+        except Exception as e:
+            logger.error("Error parsing Gemini response", error=str(e))
+            return {
+                "answer": response.strip(),
+                "confidence": 0.6,
+                "source": "Gemini",
+                "original_question": original_question,
+                "error": "Failed to parse response properly"
+            }
+    
+    def _clean_response(self, response: str) -> str:
+        """Clean and format the Gemini response."""
+        try:
+            # Remove excessive introductory phrases
+            response = response.strip()
+            
+            # Remove common verbose openings
+            verbose_openings = [
+                "Okay, let's",
+                "Alright, let's", 
+                "Sure, let's",
+                "Let's solve",
+                "I'll solve",
+                "Here's how to"
+            ]
+            
+            for opening in verbose_openings:
+                if response.lower().startswith(opening.lower()):
+                    # Find the first period or newline and start from there
+                    first_break = min(
+                        response.find('.') + 1 if response.find('.') != -1 else len(response),
+                        response.find('\n') if response.find('\n') != -1 else len(response)
+                    )
+                    response = response[first_break:].strip()
+                    break
+            
+            # Convert LaTeX delimiters to standard format for frontend
+            response = response.replace('\\(', '$').replace('\\)', '$')
+            response = response.replace('\\[', '$$').replace('\\]', '$$')
+            
+            # Remove markdown formatting
+            response = response.replace("**Final Answer:**", "Final Answer:")
+            response = response.replace("**Final Answer**", "Final Answer:")
+            response = response.replace("## Final Answer", "Final Answer:")
+            response = response.replace("## Solution Steps", "Solution Steps:")
+            response = response.replace("## Verification", "Verification:")
+            
+            # Clean up excessive asterisks and markdown formatting
+            response = re.sub(r'\*{2,}', '', response)  # Remove all ** formatting
+            response = re.sub(r'#{2,}\s*', '', response)  # Remove ## headers
+            
+            # Improve section formatting
+            response = re.sub(r'^(\d+\.\s)', r'\n\1', response, flags=re.MULTILINE)  # Add newlines before numbered steps
+            response = re.sub(r'\n\s*\n\s*\n', '\n\n', response)  # Remove excessive line breaks
+            
+            return response.strip()
+            
+        except Exception as e:
+            logger.warning("Failed to clean response, returning original", error=str(e))
+            return response.strip()
+    
+    def is_available(self) -> bool:
+        """Check if Gemini service is available."""
+        return self.model is not None
+    
+    async def health_check(self) -> Dict[str, any]:
+        """Perform a health check on the Gemini service."""
+        if not self.model:
+            return {
+                "status": "unhealthy",
+                "error": "Gemini service not initialized"
+            }
+        
+        try:
+            # Test with a simple math problem
+            test_response = await self.solve_math_problem("What is 2 + 2?")
+            
+            return {
+                "status": "healthy",
+                "model": "gemini-2.0-flash-exp",
+                "test_response_length": len(test_response.get("answer", "")),
+                "api_key_configured": bool(self.api_key)
+            }
+            
+        except Exception as e:
+            return {
+                "status": "unhealthy",
+                "error": str(e),
+                "api_key_configured": bool(self.api_key)
+            }

backend/services/guardrails_service.py

@@ -0,0 +1,155 @@
+"""
+Guardrails service for input/output validation and safety.
+"""
+import re
+import structlog
+from typing import Dict, List, Any, Optional
+
+logger = structlog.get_logger()
+
+class GuardrailsService:
+    """Service for input/output validation using guardrails-ai."""
+    
+    def __init__(self):
+        """Initialize Guardrails service."""
+        self.initialized = False
+        self._setup_validation_rules()
+        logger.info("Guardrails service initialized")
+    
+    def _setup_validation_rules(self):
+        """Setup validation rules for math content."""
+        # TODO: Implement actual guardrails-ai integration
+        # For now, implement basic validation rules
+        
+        # Prohibited content patterns
+        self.prohibited_patterns = [
+            r'(?i)\b(hack|exploit|malicious|virus|attack)\b',
+            r'(?i)\b(personal|private|confidential|secret)\b',
+            r'(?i)\b(password|credit|social.*security)\b'
+        ]
+        
+        # Math-related positive patterns
+        self.math_patterns = [
+            r'\b\d+\b',  # Numbers
+            r'[+\-*/=()]',  # Math operators
+            r'(?i)\b(solve|equation|function|derivative|integral|limit|sum|product)\b',
+            r'(?i)\b(algebra|geometry|calculus|trigonometry|statistics|probability)\b',
+            r'(?i)\b(theorem|proof|formula|solution|answer)\b'
+        ]
+        
+        self.initialized = True
+    
+    def validate_input(self, question: str) -> str:
+        """
+        Validate and sanitize input question.
+        
+        Args:
+            question: Input question to validate
+            
+        Returns:
+            Validated and sanitized question
+            
+        Raises:
+            ValueError: If input is invalid or unsafe
+        """
+        try:
+            if not question or not question.strip():
+                raise ValueError("Question cannot be empty")
+            
+            # Check length limits
+            if len(question) > 2000:
+                raise ValueError("Question too long (max 2000 characters)")
+            
+            if len(question) < 5:
+                raise ValueError("Question too short (min 5 characters)")
+            
+            # Check for prohibited content
+            for pattern in self.prohibited_patterns:
+                if re.search(pattern, question):
+                    logger.warning("Prohibited content detected in input",
+                                 pattern=pattern)
+                    raise ValueError("Input contains prohibited content")
+            
+            # Basic sanitization
+            sanitized = question.strip()
+            
+            # Remove potential script injections
+            sanitized = re.sub(r'<script.*?</script>', '', sanitized, flags=re.IGNORECASE | re.DOTALL)
+            sanitized = re.sub(r'javascript:', '', sanitized, flags=re.IGNORECASE)
+            
+            # Check if it looks like a math question
+            has_math_content = any(re.search(pattern, sanitized) for pattern in self.math_patterns)
+            
+            if not has_math_content:
+                logger.info("Non-math content detected, proceeding with caution")
+            
+            logger.info("Input validation successful",
+                       original_length=len(question),
+                       sanitized_length=len(sanitized),
+                       has_math_content=has_math_content)
+            
+            return sanitized
+            
+        except ValueError:
+            raise
+        except Exception as e:
+            logger.error("Input validation failed", error=str(e))
+            raise ValueError(f"Input validation error: {str(e)}")
+    
+    def validate_output(self, response: str) -> str:
+        """
+        Validate and sanitize output response.
+        
+        Args:
+            response: Output response to validate
+            
+        Returns:
+            Validated and sanitized response
+            
+        Raises:
+            ValueError: If output is invalid or unsafe
+        """
+        try:
+            if not response or not response.strip():
+                return "No response generated"
+            
+            # Check length limits
+            if len(response) > 10000:
+                logger.warning("Response too long, truncating")
+                response = response[:10000] + "... [truncated]"
+            
+            # Basic sanitization
+            sanitized = response.strip()
+            
+            # Remove potential harmful content
+            sanitized = re.sub(r'<script.*?</script>', '', sanitized, flags=re.IGNORECASE | re.DOTALL)
+            sanitized = re.sub(r'javascript:', '', sanitized, flags=re.IGNORECASE)
+            
+            # Check for prohibited content in output
+            for pattern in self.prohibited_patterns:
+                if re.search(pattern, sanitized):
+                    logger.warning("Prohibited content detected in output",
+                                 pattern=pattern)
+                    sanitized = re.sub(pattern, '[FILTERED]', sanitized, flags=re.IGNORECASE)
+            
+            logger.info("Output validation successful",
+                       original_length=len(response),
+                       sanitized_length=len(sanitized))
+            
+            return sanitized
+            
+        except Exception as e:
+            logger.error("Output validation failed", error=str(e))
+            return "Response validation failed - please try again"
+    
+    def is_math_related(self, text: str) -> bool:
+        """
+        Check if text is math-related.
+        
+        Args:
+            text: Text to analyze
+            
+        Returns:
+            True if text appears to be math-related
+        """
+        return any(re.search(pattern, text) for pattern in self.math_patterns)

backend/services/mcp_service.py

@@ -0,0 +1,103 @@
+"""
+MCP (Model Context Protocol) service for web search fallback.
+"""
+import asyncio
+import structlog
+from typing import Dict, Any, Optional
+import json
+
+logger = structlog.get_logger()
+
+class MCPService:
+    """Service for MCP web search integration."""
+    
+    def __init__(self):
+        """Initialize MCP service."""
+        self.mcp_server_path = "pranavms13/web-search-mcp"
+        self.initialized = False
+        logger.info("MCP service initialized")
+    
+    async def search_web(self, question: str) -> Dict[str, Any]:
+        """
+        Search the web for math-related information using MCP.
+        
+        Args:
+            question: The math question to search for
+            
+        Returns:
+            Dictionary containing web search results
+        """
+        try:
+            logger.info("Starting web search via MCP", question_length=len(question))
+            
+            # TODO: Implement actual MCP integration
+            # For now, return a placeholder response
+            
+            # Simulate web search delay
+            await asyncio.sleep(0.5)
+            
+            # Mock response based on question type with realistic confidence scoring
+            confidence_score = 0.6  # Default confidence
+            
+            if any(keyword in question.lower() for keyword in ['derivative', 'integral', 'calculus']):
+                answer = f"Based on web search: This appears to be a calculus problem. {question} involves applying standard calculus techniques. Consider using the fundamental theorem of calculus or integration by parts."
+                confidence_score = 0.75  # Higher confidence for calculus
+            elif any(keyword in question.lower() for keyword in ['algebra', 'equation', 'solve']):
+                answer = f"Based on web search: This is an algebraic problem. {question} can be solved using algebraic manipulation and equation solving techniques."
+                confidence_score = 0.7  # Good confidence for algebra
+            elif any(keyword in question.lower() for keyword in ['geometry', 'triangle', 'circle']):
+                answer = f"Based on web search: This is a geometry problem. {question} involves geometric principles and may require knowledge of shapes, areas, or angles."
+                confidence_score = 0.65  # Moderate confidence for geometry
+            elif any(keyword in question.lower() for keyword in ['statistics', 'probability', 'mean', 'standard deviation']):
+                answer = f"Based on web search: This is a statistics/probability problem. {question} requires understanding of statistical concepts and may involve data analysis."
+                confidence_score = 0.72  # Good confidence for stats
+            else:
+                answer = f"Based on web search: {question} is a mathematical problem that may require breaking down into smaller steps and applying relevant mathematical concepts."
+                confidence_score = 0.55  # Lower confidence for unknown types
+            
+            # Adjust confidence based on question length and complexity
+            if len(question) > 100:
+                confidence_score += 0.05  # Slightly higher for detailed questions
+            if '=' in question and any(op in question for op in ['+', '-', '*', '/', '^']):
+                confidence_score += 0.1   # Higher for equations with operators
+            
+            # Cap confidence to ensure it's below KB threshold for testing fallback
+            confidence_score = min(confidence_score, 0.79)  # Always below 0.8 threshold
+            
+            result = {
+                "answer": answer,
+                "source": "web_search",
+                "confidence": confidence_score,
+                "search_query": question,
+                "results_count": 1
+            }
+            
+            logger.info("Web search completed via MCP",
+                       answer_length=len(answer),
+                       confidence=result["confidence"])
+            
+            return result
+            
+        except Exception as e:
+            logger.error("Web search via MCP failed", error=str(e))
+            raise Exception(f"MCP web search failed: {str(e)}")
+    
+    async def initialize_mcp_connection(self):
+        """Initialize connection to MCP server."""
+        try:
+            # TODO: Implement actual MCP server connection
+            # This would involve:
+            # 1. Spawning the MCP server process
+            # 2. Establishing JSON-RPC communication
+            # 3. Calling available tools like web_search
+            
+            self.initialized = True
+            logger.info("MCP connection initialized successfully")
+            
+        except Exception as e:
+            logger.error("Failed to initialize MCP connection", error=str(e))
+            raise
+    
+    def is_available(self) -> bool:
+        """Check if MCP service is available."""
+        return self.initialized

backend/services/qdrant_service.py

@@ -0,0 +1,160 @@
+"""
+Qdrant service for vector database operations.
+"""
+import sys
+from pathlib import Path
+import structlog
+from typing import List, Dict, Any, Optional
+
+# Add parent directory to import database module
+parent_dir = Path(__file__).parent.parent.parent
+sys.path.append(str(parent_dir))
+
+try:
+    from database.qdrant_manager import QdrantManager
+    from database.utils import EmbeddingGenerator
+    from models.schemas import SearchResult, APILogEntry
+except ImportError as e:
+    # Services will be initialized when packages are available
+    pass
+
+logger = structlog.get_logger()
+
+class QdrantService:
+    """Service layer for Qdrant vector database operations."""
+    
+    def __init__(self):
+        """Initialize Qdrant service."""
+        self.qdrant_manager = None
+        self.embedding_generator = None
+        self._initialize()
+    
+    def _initialize(self):
+        """Initialize Qdrant manager and embedding generator."""
+        try:
+            import os
+            from dotenv import load_dotenv
+            
+            # Load .env from project root (3 levels up from services)
+            env_path = Path(__file__).parent.parent.parent / '.env'
+            load_dotenv(env_path)
+            
+            # Qdrant configuration from environment variables
+            qdrant_config = {
+                'url': os.getenv('QDRANT_URL'),
+                'api_key': os.getenv('QDRANT_API_KEY'),
+                'collection_name': os.getenv('QDRANT_COLLECTION', 'nuinamath')
+            }
+            
+            if not qdrant_config['url'] or not qdrant_config['api_key']:
+                raise ValueError("QDRANT_URL and QDRANT_API_KEY must be set in environment variables")
+            
+            self.qdrant_manager = QdrantManager(
+                url=qdrant_config['url'],
+                api_key=qdrant_config['api_key']
+            )
+            
+            self.embedding_generator = EmbeddingGenerator()
+            
+            logger.info("Qdrant service initialized successfully")
+            
+        except Exception as e:
+            logger.error("Failed to initialize Qdrant service", error=str(e))
+            # Service will work in degraded mode
+    
+    async def search_similar(self, question: str, limit: int = 5) -> List[SearchResult]:
+        """
+        Search for similar math problems in the knowledge base.
+        
+        Args:
+            question: The math question to search for
+            limit: Maximum number of results to return
+            
+        Returns:
+            List of SearchResult objects
+        """
+        if not self.qdrant_manager or not self.embedding_generator:
+            logger.warning("Qdrant service not properly initialized")
+            return []
+        
+        try:
+            import os
+            # Generate embedding for the question
+            query_embedding = self.embedding_generator.embed_text(question)
+            
+            # Search in Qdrant
+            collection_name = os.getenv('QDRANT_COLLECTION', 'nuinamath')
+            results = self.qdrant_manager.search_similar(
+                collection_name=collection_name,
+                query_vector=query_embedding,
+                limit=limit
+            )
+            
+            # Convert to SearchResult objects
+            search_results = []
+            for result in results:
+                payload = result.payload
+                search_result = SearchResult(
+                    problem=payload.get('problem', ''),
+                    solution=payload.get('solution', ''),
+                    score=result.score
+                )
+                search_results.append(search_result)
+            
+            logger.info("Knowledge base search completed",
+                       question_length=len(question),
+                       results_count=len(search_results),
+                       best_score=search_results[0].score if search_results else 0)
+            
+            return search_results
+            
+        except Exception as e:
+            logger.error("Knowledge base search failed", error=str(e))
+            return []
+    
+    async def log_api_call(
+        self,
+        endpoint: str,
+        method: str,
+        request_data: Dict[str, Any],
+        response_data: Dict[str, Any],
+        response_time_ms: float,
+        source: str
+    ):
+        """
+        Log API call to Qdrant for analytics.
+        
+        Args:
+            endpoint: API endpoint called
+            method: HTTP method
+            request_data: Request payload
+            response_data: Response payload
+            response_time_ms: Response time in milliseconds
+            source: Source of the response (KB/MCP)
+        """
+        if not self.qdrant_manager or not self.embedding_generator:
+            logger.warning("Cannot log API call - Qdrant service not initialized")
+            return
+        
+        try:
+            # Create log entry
+            log_entry = APILogEntry(
+                endpoint=endpoint,
+                method=method,
+                request_data=request_data,
+                response_data=response_data,
+                response_time_ms=response_time_ms,
+                source=source,
+                status_code=200  # Default to 200 for successful responses
+            )
+            
+            # TODO: Store log entry in Qdrant analytics collection
+            # For now, just log to stdout
+            logger.info("API call logged",
+                       endpoint=endpoint,
+                       method=method,
+                       response_time_ms=response_time_ms,
+                       source=source)
+            
+        except Exception as e:
+            logger.warning("Failed to log API call", error=str(e))