Add backend FastAPI code

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.13.0
+
+WORKDIR /code
+
+# Install Poetry
+RUN pip install poetry
+
+# Copy your project files
+COPY pyproject.toml poetry.lock ./
+
+# Install project dependencies
+RUN poetry install --no-interaction --no-ansi
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["poetry", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

app/__init__.py

@@ -0,0 +1,6 @@
+"""Math Agent FastAPI application package."""
+
+from .main import create_app
+
+__all__ = ["create_app"]
+

app/config.py

@@ -0,0 +1,104 @@
+"""Application configuration using Pydantic settings."""
+
+from functools import lru_cache
+import os
+from typing import List
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Resolve .env path robustly so it works whether .env is at repo root or backend/.env
+# This file is at backend/app/config.py → repo root is two levels up
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_BACKEND_DIR = _REPO_ROOT / "backend"
+_ENV_CANDIDATES = [
+    _REPO_ROOT / ".env",           # D:/ai_planet/.env
+    _BACKEND_DIR / ".env",         # D:/ai_planet/backend/.env
+    Path.cwd() / ".env",           # fallback to CWD
+]
+_ENV_FILE = next((p for p in _ENV_CANDIDATES if p.exists()), _REPO_ROOT / ".env")
+
+
+class Settings(BaseSettings):
+    """Runtime configuration loaded from environment or .env file."""
+
+    model_config = SettingsConfigDict(env_file=str(_ENV_FILE), env_file_encoding="utf-8", extra="allow")
+
+    app_name: str = "Math Agentic RAG"
+    environment: str = "local"
+    debug: bool = True
+
+    # Vector store configuration (Weaviate)
+    weaviate_url: str | None = None
+    weaviate_api_key: str | None = None
+    weaviate_collection: str = "mathvectors"  # Collection name in Weaviate cloud
+    embedding_model_name: str = "sentence-transformers/all-MiniLM-L6-v2"
+    top_k: int = 4
+    similarity_threshold: float = 0.80
+
+    # Guardrail keywords for allow-listing math topics
+    allowed_subjects: List[str] = [
+        "algebra",
+        "geometry",
+        "calculus",
+        "probability",
+        "statistics",
+        "number theory",
+        "trigonometry",
+        "combinatorics",
+        "math",
+    ]
+
+    blocked_keywords: List[str] = [
+        "violence",
+        "weapon",
+        "politics",
+        "hate",
+        "self-harm",
+        "explicit",
+    ]
+
+    # External service credentials
+    tavily_api_key: str | None = None
+    mcp_tavily_url: str | None = None  # e.g., https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-...
+    gemini_api_key: str | None = None
+    groq_api_key: str | None = None
+
+    # Model configuration
+    gemini_model: str = "gemini-2.5-flash"  # Fast model for search grounding and vision
+    dspy_model: str = "gemini-2.5-flash"    # For DSPy pipeline
+    whisper_model: str = "whisper-large-v3-turbo"  # For audio transcription
+    dspy_max_tokens: int = 2048
+
+    # Feedback storage
+    feedback_store_path: str = "backend/data/feedback_db.json"
+
+    # Gateway / guardrails toggles
+    enforce_input_guardrails: bool = True
+    enforce_output_guardrails: bool = True
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return a cached Settings instance."""
+    settings = Settings()
+
+    # Allow alternate env var aliases for KB similarity threshold
+    # Priority: KB_SIMILARITY_THRESHOLD -> KB_THRESHOLD -> existing value
+    kb_thresh_env = (
+        os.getenv("KB_SIMILARITY_THRESHOLD")
+        or os.getenv("KB_THRESHOLD")
+    )
+    if kb_thresh_env:
+        try:
+            settings.similarity_threshold = float(kb_thresh_env)
+        except ValueError:
+            # Ignore invalid values and keep existing
+            pass
+
+    return settings
+
+
+settings = get_settings()
+
+

app/guardrails.py

@@ -0,0 +1,100 @@
+"""Guardrail functions for input/output moderation."""
+
+from __future__ import annotations
+
+import re
+from typing import Tuple
+
+from .config import settings
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class GuardrailViolation(Exception):
+    """Raised when a guardrail condition is violated."""
+
+    def __init__(self, message: str, code: str = "guardrail_violation") -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+SANITIZE_REGEX = re.compile(r"[^\x20-\x7E]+")
+PII_REGEX = re.compile(r"\b(\d{3}-?\d{2}-?\d{4}|\d{16}|[A-Z]{5}[0-9]{4}[A-Z]{1})\b")
+
+
+def sanitize_text(text: str) -> str:
+    """Remove non-ascii characters and collapse whitespace."""
+
+    cleaned = SANITIZE_REGEX.sub("", text)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    return cleaned
+
+
+def run_input_guardrails(user_text: str) -> str:
+    """Validate and sanitize user input before routing.
+    
+    Note: Since Gemini is used to validate math questions, we're very permissive here.
+    Only block obvious non-math content and security issues.
+    """
+
+    logger.debug("guardrails.input.start", text=user_text)
+
+    text = sanitize_text(user_text)
+
+    # Only block PII - this is a security issue
+    if PII_REGEX.search(text):
+        logger.warning("guardrails.input.blocked", reason="pii_match")
+        raise GuardrailViolation("The request may contain sensitive information. Please remove it and try again.")
+
+    lower = text.lower()
+
+    # Block only obvious non-educational content - let Gemini decide if it's math
+    if any(keyword in lower for keyword in settings.blocked_keywords):
+        logger.warning("guardrails.input.blocked", reason="blocked_keyword")
+        raise GuardrailViolation("I can only help with mathematics-related educational questions.")
+
+    # Very permissive - allow anything that could be math-related
+    # Gemini will be the final validator, so we just do basic sanity checks
+    # Allow anything with math-like patterns, or let it through and let Gemini decide
+    
+    logger.debug("guardrails.input.pass")
+    return text
+
+
+def run_output_guardrails(response_text: str) -> Tuple[str, list[str]]:
+    """Apply output guardrails - very permissive since Gemini validates math content.
+    
+    Only blocks obvious non-math content. Most validation is done by Gemini.
+    """
+
+    logger.debug("guardrails.output.start")
+    text = sanitize_text(response_text)
+
+    citations: list[str] = []
+    
+    # Only block PII - security issue
+    if PII_REGEX.search(text):
+        logger.warning("guardrails.output.flag", reason="pii_detected")
+        text = re.sub(PII_REGEX, "[redacted]", text)
+
+    # Extract URLs as citations
+    if "http" in text.lower():
+        citations = re.findall(r"(https?://\S+)", text)
+
+    # Very permissive - allow almost everything
+    # Since Gemini generates the responses, it should be math-related
+    # Only block if it's clearly and obviously non-math (e.g., contains blocked keywords)
+    lower = text.lower()
+    
+    # Only block if it contains obviously inappropriate content
+    if any(keyword in lower for keyword in settings.blocked_keywords):
+        logger.warning("guardrails.output.blocked", reason="blocked_keyword", preview=text[:100])
+        raise GuardrailViolation("The generated response contains inappropriate content.")
+
+    # Everything else passes - let Gemini handle math validation
+    logger.debug("guardrails.output.pass", citations=len(citations))
+    return text, citations
+
+

app/logger.py

@@ -0,0 +1,37 @@
+"""Structured logging helpers."""
+
+import logging
+from typing import Any
+
+import structlog
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Configure structlog for the application."""
+
+    timestamper = structlog.processors.TimeStamper(fmt="iso")
+
+    structlog.configure(
+        processors=[
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            timestamper,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.dev.ConsoleRenderer() if level <= logging.DEBUG else structlog.processors.JSONRenderer(),
+        ],
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    logging.basicConfig(level=level, format="%(message)s")
+
+
+def get_logger(*args: Any, **kwargs: Any) -> structlog.stdlib.BoundLogger:
+    """Return a configured structlog logger."""
+
+    return structlog.get_logger(*args, **kwargs)
+
+

app/main.py

@@ -0,0 +1,156 @@
+"""FastAPI entrypoint for the math agent backend."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import AsyncIterator
+
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from .config import settings
+from .guardrails import GuardrailViolation
+from .logger import configure_logging, get_logger
+from .schemas import AgentResponse, ChatRequest, FeedbackRequest
+from .services.retrieval import MathAgent
+from .services.vector_store import (
+    load_vector_store,
+    save_feedback_to_queue,
+)
+from .services.kb_updater import update_knowledge_base
+from .tools.audio import transcribe_audio
+from .tools.validator import validate_user_solution
+from .tools.vision import extract_text_from_image
+
+logger = get_logger(__name__)
+
+
+def create_app() -> FastAPI:
+    configure_logging()
+
+    app = FastAPI(title=settings.app_name, version="0.1.0")
+
+    # Configure CORS. Accept a single FRONTEND_URL or a comma-separated
+    # FRONTEND_URLS env var. Default to common dev ports (5173 and 3000).
+    frontend_env = os.getenv("FRONTEND_URL", os.getenv("FRONTEND_URLS", "http://localhost:5173,http://localhost:3000"))
+    # split and strip any whitespace
+    allowed_origins = [o.strip() for o in frontend_env.split(",") if o.strip()]
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allowed_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        # Startup
+        logger.info("app.startup")
+        app.state.vector_store = await asyncio.to_thread(load_vector_store)
+        
+        yield  # Server is running
+        
+        # Shutdown
+        logger.info("app.shutdown")
+        # Clean up any resources if needed
+
+    app.router.lifespan_context = lifespan
+
+    def get_agent() -> MathAgent:
+        vector_store = getattr(app.state, "vector_store", None)
+        if vector_store is None:
+            vector_store = load_vector_store()
+            app.state.vector_store = vector_store
+        return MathAgent(vector_store=vector_store)
+
+    @app.middleware("http")
+    async def add_process_time_header(request: Request, call_next):  # type: ignore[override]
+        response = await call_next(request)
+        response.headers["X-App-Env"] = settings.environment
+        return response
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "ok", "environment": settings.environment}
+
+    @app.post("/api/chat", response_model=AgentResponse, responses={400: {"description": "Guardrail failure"}})
+    async def chat_endpoint(payload: ChatRequest, agent: MathAgent = Depends(get_agent)) -> AgentResponse:
+        logger.info("chat.request", modality=payload.modality)
+
+        query = payload.query
+        if payload.modality == "audio" and payload.audio_base64:
+            query = transcribe_audio(payload.audio_base64)
+        elif payload.modality == "image" and payload.image_base64:
+            query = extract_text_from_image(payload.image_base64)
+
+        try:
+            response = await agent.handle_query(query)
+            return response
+        except GuardrailViolation as exc:
+            raise HTTPException(status_code=400, detail=exc.message) from exc
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.exception("chat.error", error=str(exc))
+            raise HTTPException(status_code=500, detail="Unexpected error handling query") from exc
+
+    @app.post("/api/feedback")
+    async def feedback_endpoint(request: FeedbackRequest) -> JSONResponse:
+        """Handle user feedback with optional solution upload."""
+        logger.info(
+            "feedback.received", 
+            message_id=request.message_id,
+            helpful=request.feedback.thumbs_up,
+            issue=request.feedback.primary_issue
+        )
+
+        # Always save the feedback first
+        record = request.model_dump()
+        save_feedback_to_queue(record)
+
+        # If it's negative feedback with a solution
+        if not request.feedback.thumbs_up and request.feedback.has_better_solution:
+            solution = None
+            
+            # Get solution based on type
+            if request.feedback.solution_type == "text":
+                solution = request.feedback.better_solution_text
+            elif request.feedback.solution_type == "pdf":
+                # TODO: Extract text from PDF
+                solution = request.feedback.better_solution_text
+            elif request.feedback.solution_type == "image":
+                # Use vision model to extract solution from image
+                if request.feedback.better_solution_image_base64:
+                    solution = extract_text_from_image(
+                        request.feedback.better_solution_image_base64,
+                        "Extract the mathematical solution from this image."
+                    )
+            
+            if solution:
+                # Validate and update KB
+                success = await update_knowledge_base(request.query, solution)
+                return JSONResponse({
+                    "status": "ok",
+                    "feedback_saved": True,
+                    "kb_updated": success
+                })
+
+        return JSONResponse({
+            "status": "ok",
+            "feedback_saved": True
+        })
+
+    @app.get("/api/vector-store/reload")
+    async def reload_vector_store() -> dict[str, str]:
+        app.state.vector_store = await asyncio.to_thread(load_vector_store, True)
+        return {"status": "reloaded"}
+
+    return app
+
+
+app = create_app()
+
+

app/schemas.py

@@ -0,0 +1,117 @@
+"""Pydantic schemas for API endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Step(BaseModel):
+    """A solution step with title, content and optional LaTeX expression."""
+
+    title: str
+    content: str
+    expression: Optional[str] = None
+
+
+class Citation(BaseModel):
+    """Represents a web citation."""
+
+    title: str
+    url: str
+
+
+class RetrievalContext(BaseModel):
+    """Context snippet from knowledge base."""
+
+    document_id: str
+    question: str
+    answer: str
+    similarity: float
+
+
+class AgentResponse(BaseModel):
+    """Structured agent response."""
+
+    answer: str
+    steps: List[Step]
+    retrieved_from_kb: bool = False
+    knowledge_hits: List[RetrievalContext] = Field(default_factory=list)
+    citations: List[Citation] = Field(default_factory=list)
+    source: str = Field(default="kb")  # kb | tavily | gemini
+    feedback_required: bool = True
+    gateway_trace: List[str] = Field(default_factory=list)
+
+
+class ChatRequest(BaseModel):
+    """Incoming chat message payload."""
+
+    query: str
+    modality: str = Field(default="text", description="text|image|audio")
+    image_base64: Optional[str] = None
+    audio_base64: Optional[str] = None
+
+
+class FeedbackMetadata(BaseModel):
+    """User feedback payload."""
+
+    # Minimal - Always Ask (5 seconds)
+    thumbs_up: bool = Field(description="👍 Helpful / 👎 Not helpful")
+    
+    # If thumbs_down, expand to next level (10 seconds)
+    primary_issue: Optional[str] = Field(
+        None,
+        description="What went wrong?",
+        # These match exactly with the frontend enums
+        enum=["wrong-answer", "unclear", "missing-steps", "wrong-method"]
+    )
+    
+    # Optional user solution upload (30-60 seconds)
+    has_better_solution: bool = False
+    solution_type: Optional[str] = Field(
+        None, 
+        description="Type of solution upload",
+        enum=["text", "pdf", "image"]
+    )
+    better_solution_text: Optional[str] = None
+    better_solution_pdf_base64: Optional[str] = None
+    better_solution_image_base64: Optional[str] = None
+
+
+class FeedbackRequest(BaseModel):
+    """Feedback submission request."""
+
+    message_id: str
+    query: str
+    agent_response: AgentResponse
+    feedback: FeedbackMetadata
+
+
+class BenchmarkResult(BaseModel):
+    """Result for a single benchmark item."""
+
+    question_id: str
+    reference_answer: str
+    agent_answer: str
+    score: float
+    source: str
+
+
+class BenchmarkSummary(BaseModel):
+    """Aggregate benchmark output."""
+
+    dataset: str
+    total_questions: int
+    average_score: float
+    details: List[BenchmarkResult]
+
+
+class ErrorResponse(BaseModel):
+    """Error response envelope."""
+
+    detail: str
+    code: str = Field(default="error")
+    context: Optional[dict[str, Any]] = None
+
+

app/services/kb_updater.py

@@ -0,0 +1,56 @@
+"""Knowledge base update service for validated user solutions."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+from sentence_transformers import SentenceTransformer
+
+from ..config import settings
+from ..logger import get_logger
+from ..tools.validator import validate_user_solution
+from .vector_store import load_vector_store
+
+logger = get_logger(__name__)
+
+
+async def update_knowledge_base(question: str, solution: str, source: str = "user-feedback") -> bool:
+    """Validate and add a new solution to the knowledge base."""
+    
+    try:
+        # First validate the solution
+        is_valid = await asyncio.to_thread(validate_user_solution, question, solution)
+        
+        if not is_valid:
+            logger.warning("kb_update.validation_failed", question=question)
+            return False
+            
+        # Load vector store
+        vector_store = load_vector_store()
+        encoder = SentenceTransformer(settings.embedding_model_name)
+        
+        # Generate embedding
+        text = question + "\n" + solution
+        embedding = encoder.encode(text)
+        
+        # Add to Weaviate
+        data_object = {
+            "question": question,
+            "answer": solution,
+            "source": source
+        }
+        
+        # Add with vector
+        vector_store.client.data_object.create(
+            data_object=data_object,
+            class_name=settings.weaviate_class_name,
+            vector=embedding.tolist()
+        )
+        
+        logger.info("kb_update.success", question=question, source=source)
+        return True
+        
+    except Exception as exc:
+        logger.error("kb_update.failed", error=str(exc), question=question)
+        return False

app/services/retrieval.py

@@ -0,0 +1,109 @@
+"""Retrieval and routing logic for the math agent."""
+
+from __future__ import annotations
+
+from ..guardrails import GuardrailViolation
+from ..logger import get_logger
+from ..schemas import AgentResponse, Step
+from ..workflows.langgraph_pipeline import build_math_agent_graph
+from .vector_store import VectorStore, load_vector_store
+
+logger = get_logger(__name__)
+
+
+class MathAgent:
+    """High-level orchestration for handling a math query."""
+
+    def __init__(self, vector_store: VectorStore | None = None) -> None:
+        self.vector_store = vector_store or load_vector_store()
+        self.graph = build_math_agent_graph(self.vector_store)
+
+    async def handle_query(self, query: str) -> AgentResponse:
+        """Run the query through guardrails, routing, and generation."""
+
+        try:
+            result_state = await self.graph.ainvoke({"query": query, "gateway_trace": []})
+        except GuardrailViolation:
+            raise
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.exception("math_agent.graph_failure", error=str(exc))
+            raise
+
+        steps_raw = result_state.get("steps", []) or []
+        
+        # Get KB hits and web hits separately, then combine for display
+        kb_hits = result_state.get("kb_hits", []) or []
+        web_hits = result_state.get("web_hits", []) or []
+        # Combine for knowledge_hits display (show both KB and web)
+        knowledge_hits = list(kb_hits) + list(web_hits)
+        # If no separate hits, fall back to combined knowledge_hits
+        if not knowledge_hits:
+            knowledge_hits = result_state.get("knowledge_hits", []) or []
+        
+        citations = result_state.get("citations", []) or []
+        answer_text = result_state.get("answer", "") or ""
+        
+        # If answer is too short (just overview), try to enhance it with steps
+        if len(answer_text.strip()) < 50 and steps_raw:
+            # Answer might be incomplete - use steps to build a better answer
+            step_texts = []
+            for step in steps_raw:
+                if isinstance(step, dict):
+                    step_texts.append(step.get("content", "") or step.get("explanation", ""))
+                elif isinstance(step, (list, tuple)) and len(step) > 1:
+                    step_texts.append(step[1])
+            
+            if step_texts:
+                # Find the last step that looks like a conclusion
+                for step_text in reversed(step_texts):
+                    if any(word in step_text.lower() for word in ["therefore", "answer", "result", "thus", "hence"]):
+                        answer_text = step_text
+                        break
+                
+                # If still no good answer, use the last step
+                if len(answer_text.strip()) < 50:
+                    answer_text = step_texts[-1] if step_texts else answer_text
+        
+        retrieved_from_kb = result_state.get("retrieved_from_kb", False)
+        source = result_state.get("source", "kb+web" if (kb_hits and web_hits) else ("kb" if retrieved_from_kb else "gemini"))
+        gateway_trace = result_state.get("gateway_trace", [])
+
+        # Convert steps to new format with content and optional expressions
+        formatted_steps = []
+        for step in steps_raw:
+            # steps_raw is now a list of dicts with title/content/expression
+            if isinstance(step, dict):
+                formatted_steps.append(Step(
+                    title=step.get("title", ""),
+                    content=step.get("content", ""),
+                    expression=step.get("expression")
+                ))
+            else:
+                # Handle legacy tuple format for backward compatibility
+                title, explanation = step
+                formatted_steps.append(Step(
+                    title=title,
+                    content=explanation
+                ))
+
+        response = AgentResponse(
+            answer=answer_text,
+            steps=formatted_steps,
+            retrieved_from_kb=retrieved_from_kb,
+            knowledge_hits=knowledge_hits,
+            citations=citations,
+            source=source,
+            gateway_trace=gateway_trace,
+        )
+
+        logger.info(
+            "math_agent.completed",
+            source=response.source,
+            retrieved=retrieved_from_kb,
+            kb_hits=len(knowledge_hits),
+            trace=gateway_trace,
+        )
+
+        return response
+
+

app/services/vector_store.py

@@ -0,0 +1,348 @@
+"""Vector store utilities using Weaviate cloud for knowledge base retrieval."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List, Dict, Any
+
+import numpy as np
+import weaviate
+from sentence_transformers import SentenceTransformer
+from weaviate.collections.classes.config import DataType
+
+from ..config import settings
+from ..logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class VectorStore:
+    """Wrapper around Weaviate vector store."""
+
+    def __init__(self, client: weaviate.WeaviateClient, encoder: SentenceTransformer) -> None:
+        self.client = client
+        self.encoder = encoder
+        self.collection = self._ensure_collection()
+        self._property_map = self._detect_property_names()
+
+    def _ensure_collection(self) -> weaviate.collections.Collection:
+        """Create collection if it doesn't exist."""
+        collection_name = settings.weaviate_collection
+        collections = self.client.collections.list_all()
+
+        # Check for exact or case-insensitive match to avoid 422 when class
+        # already exists with different casing (e.g. 'Mathvectors').
+        lower_names = [n.lower() for n in collections]
+        if collection_name not in collections and collection_name.lower() not in lower_names:
+            try:
+                collection = self.client.collections.create(
+                    name=collection_name,
+                    vectorizer_config=weaviate.classes.config.Configure.Vectorizer.none(),
+                    vector_index_config=weaviate.classes.config.Configure.VectorIndex.hnsw(),
+                    properties=[
+                        {"name": "question", "data_type": DataType.TEXT},
+                        {"name": "answer", "data_type": DataType.TEXT},
+                        {"name": "source", "data_type": DataType.TEXT},
+                    ]
+                )
+                logger.info("vector_store.collection.created", name=collection_name)
+            except weaviate.exceptions.UnexpectedStatusCodeError as e:
+                # If the create failed because the class already exists (422),
+                # recover by locating the existing class name (case-insensitive)
+                msg = str(e)
+                if "already exists" in msg or "class name" in msg:
+                    logger.warning("vector_store.collection.create_conflict", msg=msg)
+                    # refresh list and try to find the existing class name
+                    collections = self.client.collections.list_all()
+                    existing = None
+                    for n in collections:
+                        if n.lower() == collection_name.lower():
+                            existing = n
+                            break
+                    if existing:
+                        collection = self.client.collections.get(existing)
+                        logger.info("vector_store.collection.exists", name=existing)
+                    else:
+                        # re-raise if we can't resolve the conflict
+                        raise
+                else:
+                    raise
+        else:
+            # exact or case-insensitive match found — pick the actual existing name
+            if collection_name in collections:
+                existing_name = collection_name
+            else:
+                existing_name = next(n for n in collections if n.lower() == collection_name.lower())
+            collection = self.client.collections.get(existing_name)
+            logger.info("vector_store.collection.exists", name=existing_name)
+
+        return collection
+
+    def _detect_property_names(self) -> Dict[str, str]:
+        """Detect the actual property names in the collection schema.
+        
+        Returns a mapping from logical names (question, answer, source) to actual property names.
+        """
+        property_map = {}
+        prop_names = []
+        
+        try:
+            # Get the collection configuration to see what properties exist
+            config = self.collection.config.get()
+            
+            # Try different ways to access properties depending on Weaviate v4 structure
+            if hasattr(config, 'properties'):
+                props = config.properties
+                if props:
+                    # Properties might be a list or iterable
+                    if isinstance(props, (list, tuple)):
+                        prop_names = [prop.name if hasattr(prop, 'name') else str(prop) for prop in props]
+                    elif hasattr(props, '__iter__') and not isinstance(props, (str, bytes)):
+                        prop_names = [prop.name if hasattr(prop, 'name') else str(prop) for prop in props]
+            
+            # Also try accessing as attributes
+            if not prop_names and hasattr(config, 'properties'):
+                try:
+                    props_dict = config.properties.__dict__ if hasattr(config.properties, '__dict__') else {}
+                    prop_names = list(props_dict.keys()) if props_dict else []
+                except:
+                    pass
+            
+        except Exception as exc:
+            logger.warning("vector_store.schema.detection_error", error=str(exc))
+        
+        # Try to map to our expected names
+        # Check for new schema (question, answer, source) first
+        if prop_names:
+            if "question" in prop_names:
+                property_map["question"] = "question"
+            elif "input" in prop_names:
+                property_map["question"] = "input"
+            
+            if "answer" in prop_names:
+                property_map["answer"] = "answer"
+            elif "label" in prop_names:
+                property_map["answer"] = "label"
+            
+            if "source" in prop_names:
+                property_map["source"] = "source"
+            elif "source_file" in prop_names:
+                property_map["source"] = "source_file"
+        else:
+            # No properties detected - use fallback (old schema)
+            logger.warning("vector_store.schema.detection_failed", msg="Could not detect properties, using fallback")
+            property_map = {"question": "input", "answer": "label", "source": "source_file"}
+        
+        # If detection partially failed, fill in missing mappings
+        if "question" not in property_map:
+            property_map["question"] = "input"
+        if "answer" not in property_map:
+            property_map["answer"] = "label"
+        if "source" not in property_map:
+            property_map["source"] = "source_file"
+        
+        logger.info("vector_store.schema.detected", mapping=property_map, found_properties=prop_names)
+        return property_map
+
+    def search(self, query: str, top_k: int | None = None) -> List[Dict[str, Any]]:
+        """Search for similar questions and return contexts."""
+        if top_k is None:
+            top_k = settings.top_k
+
+        # Generate embedding for query
+        embedding = self.encoder.encode(query)
+        embedding = embedding / np.linalg.norm(embedding)  # Normalize
+
+        try:
+            # Get the actual property names from the detected schema
+            question_prop = self._property_map.get("question", "input")
+            answer_prop = self._property_map.get("answer", "label")
+            source_prop = self._property_map.get("source", "source_file")
+            
+            # Build Weaviate v4 query with near_vector using actual property names
+            response = self.collection.query.near_vector(
+                near_vector=embedding.tolist(),
+                certainty=settings.similarity_threshold,
+                limit=top_k,
+                return_metadata=["certainty"],
+                return_properties=[question_prop, answer_prop, source_prop]
+            )
+        except Exception as exc:  # pragma: no cover - defensive
+            # If query failed, try with old schema as fallback
+            error_msg = str(exc).lower()
+            if "no such prop" in error_msg or "property" in error_msg:
+                logger.warning("vector_store.search.schema_mismatch", error=str(exc), trying="old_schema")
+                try:
+                    # Fallback to old schema property names
+                    response = self.collection.query.near_vector(
+                        near_vector=embedding.tolist(),
+                        certainty=settings.similarity_threshold,
+                        limit=top_k,
+                        return_metadata=["certainty"],
+                        return_properties=["input", "label", "source_file"]
+                    )
+                    # Update property map for this query
+                    self._property_map = {"question": "input", "answer": "label", "source": "source_file"}
+                    question_prop = "input"
+                    answer_prop = "label"
+                    source_prop = "source_file"
+                except Exception as fallback_exc:
+                    logger.exception("vector_store.search.fallback_failed", error=str(fallback_exc))
+                    return []
+            else:
+                logger.exception("vector_store.search.error", error=str(exc))
+                return []
+
+        results = []
+        # Use the property names that were successfully used in the query
+        # (either from detection or from fallback)
+        question_prop = self._property_map.get("question", "input")
+        answer_prop = self._property_map.get("answer", "label")
+        source_prop = self._property_map.get("source", "source_file")
+        
+        # Weaviate v4 returns a QueryReturn with an objects attribute
+        for obj in response.objects:
+            
+            question = ""
+            answer = ""
+            source = ""
+            
+            if isinstance(obj.properties, dict):
+                question = obj.properties.get(question_prop, "")
+                answer = obj.properties.get(answer_prop, "")
+                source = obj.properties.get(source_prop, "")
+            else:
+                # Try attribute access
+                question = getattr(obj.properties, question_prop, "")
+                answer = getattr(obj.properties, answer_prop, "")
+                source = getattr(obj.properties, source_prop, "")
+            
+            # For old schema where answer might be a label (integer), convert to string
+            if answer_prop == "label" and isinstance(answer, (int, float)):
+                answer = str(answer)
+            
+            # Extract similarity - use certainty if available, otherwise distance (inverted), default to 0.0
+            similarity = 0.0
+            if obj.metadata:
+                if hasattr(obj.metadata, 'certainty') and obj.metadata.certainty is not None:
+                    similarity = float(obj.metadata.certainty)
+                elif hasattr(obj.metadata, 'distance') and obj.metadata.distance is not None:
+                    # Convert distance to similarity (distance is lower for more similar items)
+                    # For normalized vectors, distance = 1 - certainty approximately
+                    similarity = max(0.0, 1.0 - float(obj.metadata.distance))
+            
+            results.append({
+                "document_id": str(obj.uuid),
+                "question": question,
+                "answer": answer,
+                "source": source,
+                "similarity": similarity,
+            })
+            
+        return results
+
+    def add_entry(self, question: str, answer: str, source: str = "kb") -> str:
+        """Add a new entry to the vector store."""
+        # Generate embedding
+        text = question + "\n" + answer
+        embedding = self.encoder.encode(text)
+        embedding = embedding / np.linalg.norm(embedding)
+
+        # Add to Weaviate
+        result = self.collection.data.insert(
+            properties={
+                "question": question,
+                "answer": answer,
+                "source": source,
+            },
+            vector=embedding.tolist()
+        )
+
+        return result.uuid
+
+
+_vector_store: VectorStore | None = None
+
+
+class _NullVectorStore:
+    """Fallback vector store used when Weaviate is unavailable at startup.
+    Provides the minimal API consumed by the workflow.
+    """
+
+    def search(self, query: str, top_k: int | None = None) -> List[Dict[str, Any]]:  # type: ignore[override]
+        return []
+
+    def add_entry(self, question: str, answer: str, source: str = "kb") -> str:  # pragma: no cover
+        logger.warning("vector_store.null.add_entry_ignored")
+        return ""
+
+
+def load_vector_store(force_reload: bool = False) -> VectorStore:
+    """Lazy-load the Weaviate vector store."""
+    global _vector_store
+    if _vector_store is not None and not force_reload:
+        return _vector_store
+
+    if not settings.weaviate_url or not settings.weaviate_api_key:
+        logger.warning("vector_store.config.missing", msg="Starting without KB; searches will return empty.")
+        _vector_store = _NullVectorStore()  # type: ignore[assignment]
+        return _vector_store  # type: ignore[return-value]
+
+    logger.info("vector_store.load.start", url=settings.weaviate_url)
+
+    # Use the v4 helper to connect to Weaviate Cloud. The older v3-style
+    # `weaviate.Client(url=..., auth_client_secret=...)` constructor is not
+    # supported by the installed weaviate client and raises a TypeError.
+    # connect_to_weaviate_cloud will construct the correct ConnectionParams
+    # for cloud deployments (http + grpc hosts) and return a connected client.
+    # pass the API key string directly — the helper will parse it into the
+    # proper AuthCredentials object. Accessing `weaviate.Auth` at module
+    # level can raise AttributeError in some installs; passing a string is
+    # supported and avoids that problem.
+    try:
+        client = weaviate.connect_to_weaviate_cloud(
+            cluster_url=settings.weaviate_url,
+            auth_credentials=settings.weaviate_api_key,
+            skip_init_checks=True,
+        )
+
+        encoder = SentenceTransformer(settings.embedding_model_name)
+        _vector_store = VectorStore(client=client, encoder=encoder)
+        logger.info("vector_store.load.success")
+        return _vector_store
+    except Exception as exc:  # pragma: no cover
+        logger.warning(
+            "vector_store.load.failed_starting_without_kb",
+            error=str(exc),
+        )
+        _vector_store = _NullVectorStore()  # type: ignore[assignment]
+        return _vector_store  # type: ignore[return-value]
+
+
+def save_feedback_to_queue(feedback_record: dict) -> None:
+    """Append feedback to feedback database."""
+
+    feedback_path = Path(settings.feedback_store_path)
+    feedback_path.parent.mkdir(parents=True, exist_ok=True)
+    if feedback_path.exists():
+        data = json.loads(feedback_path.read_text(encoding="utf-8"))
+    else:
+        data = []
+    data.append(feedback_record)
+    feedback_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def queue_candidate_kb_entry(question: str, solution: str, source: str) -> None:
+    """Save a candidate knowledge base entry for human approval."""
+
+    queue_path = Path("backend/data/kb_candidate_queue.json")
+    queue_path.parent.mkdir(parents=True, exist_ok=True)
+    if queue_path.exists():
+        queue = json.loads(queue_path.read_text(encoding="utf-8"))
+    else:
+        queue = []
+    queue.append({"question": question, "answer": solution, "source": source})
+    queue_path.write_text(json.dumps(queue, ensure_ascii=False, indent=2), encoding="utf-8")
+
+

app/tools/__init__.py

@@ -0,0 +1,2 @@
+"""Tooling helpers for math agent."""
+

app/tools/audio.py

@@ -0,0 +1,41 @@
+"""Audio transcription using Groq Whisper models."""
+
+from __future__ import annotations
+
+import base64
+import io
+
+from groq import Groq
+
+from ..config import settings
+
+
+def _strip_data_url(data: str) -> str:
+    if "," in data and data.startswith("data:"):
+        return data.split(",", 1)[1]
+    return data
+
+
+def transcribe_audio(audio_base64: str, language: str = "en") -> str:
+    """Transcribe base64 encoded audio using Groq Whisper."""
+
+    if not settings.groq_api_key:
+        raise RuntimeError("GROQ_API_KEY not configured for speech transcription")
+
+    client = Groq(api_key=settings.groq_api_key)
+    clean_base64 = _strip_data_url(audio_base64)
+    audio_bytes = base64.b64decode(clean_base64)
+    audio_buffer = io.BytesIO(audio_bytes)
+    audio_buffer.name = "input.wav"
+
+    transcription = client.audio.transcriptions.create(
+        model="whisper-large-v3-turbo", file=audio_buffer, response_format="text", language=language
+    )
+
+    if hasattr(transcription, "text"):
+        return transcription.text
+    if isinstance(transcription, str):
+        return transcription
+    raise RuntimeError("Unexpected response format from Groq Whisper API")
+
+

app/tools/dspy_pipeline.py

@@ -0,0 +1,476 @@
+"""DSPy powered reasoning pipeline for math explanations."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from dataclasses import dataclass
+from typing import Iterable, List, Sequence
+
+# Normalization helpers to convert LaTeX-like math to readable text (module-wide)
+_LATEX_SIMPLE_REPLACEMENTS = [
+    (r"\\cdot", "·"),
+    (r"\\times", "×"),
+    (r"\\to", "→"),
+    (r"\\leq", "≤"),
+    (r"\\geq", "≥"),
+    (r"\\neq", "≠"),
+    (r"\\pm", "±"),
+    (r"\\approx", "≈"),
+    (r"\\infty", "∞"),
+    (r"\\Rightarrow", "⇒"),
+    (r"\\Leftarrow", "⇐"),
+    (r"\\sin", "sin"),
+    (r"\\cos", "cos"),
+    (r"\\tan", "tan"),
+    (r"\\ln", "ln"),
+    (r"\\log", "log"),
+    (r"\\lim", "lim"),
+    (r"\\mathbb\{R\}", "R"),
+    (r"\\mathbb\{R\}\^3", "R^3"),
+    (r"\\mathbb\{Z\}", "Z"),
+    (r"\\mathbb\{Q\}", "Q"),
+    (r"\\sqrt", "√"),
+    (r"\\pi", "π"),
+    (r"\\theta", "θ"),
+    (r"\\alpha", "α"),
+    (r"\\beta", "β"),
+    (r"\\gamma", "γ"),
+    (r"\\Delta", "Δ"),
+]
+
+_FRAC_PATTERN = re.compile(r"\\frac\{([^}]+)\}\{([^}]+)\}")
+
+def _normalize_math(text: str) -> str:
+    if not text:
+        return text
+    # Remove inline/display math delimiters
+    text = (
+        text.replace("$$", "")
+            .replace("$", "")
+            .replace("\\[", "")
+            .replace("\\]", "")
+            .replace("\\(", "")
+            .replace("\\)", "")
+    )
+    # Strip common markdown artifacts (bold/headers/backticks)
+    text = text.replace("**", "").replace("`", "")
+    text = re.sub(r"^\s*#{1,6}\s*", "", text, flags=re.MULTILINE)
+    # Drop sizing/spacing commands
+    text = re.sub(r"\\(left|right|big|Big|quad|qquad)\\?", "", text)
+    # Replace \frac{a}{b} with (a)/(b)
+    def _frac_sub(match: re.Match) -> str:
+        return f"({match.group(1)})/({match.group(2)})"
+    text = _FRAC_PATTERN.sub(_frac_sub, text)
+    # Apply simple replacements
+    for pattern, repl in _LATEX_SIMPLE_REPLACEMENTS:
+        text = re.sub(pattern, repl, text)
+    # Normalize powers and tidy operators spacing
+    text = re.sub(r"\^2", "²", text)
+    text = re.sub(r"\^3", "³", text)
+    text = re.sub(r"\s*([=+\-×·*/])\s*", r" \1 ", text)
+    # Collapse excessive spaces
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+try:
+    import dspy  # type: ignore
+    import google.generativeai as genai  # type: ignore
+
+    from ..config import settings
+    from ..logger import get_logger
+
+    logger = get_logger(__name__)
+
+    class GeminiLM(dspy.LM):
+        """Minimal DSPy LM wrapper around Gemini API."""
+
+        def __init__(self, model: str, api_key: str, max_output_tokens: int = 2048) -> None:
+            super().__init__(model=model, max_output_tokens=max_output_tokens)
+            genai.configure(api_key=api_key)
+            self._model = genai.GenerativeModel(model)
+
+        def __call__(self, prompt: str, **kwargs) -> dspy.Completion:
+            response = self._model.generate_content(prompt)
+            text = response.text or ""
+            return dspy.Completion(text=text)
+
+        def loglikelihood(self, prompt: str, continuation: str) -> float:
+            raise NotImplementedError("GeminiLM.loglikelihood is not supported")
+
+
+    class MathTutorSignature(dspy.Signature):
+        """DSPy signature describing the desired behavior."""
+
+        query = dspy.InputField(desc="Student's mathematics question - MUST solve completely")
+        context = dspy.InputField(desc="Knowledge snippets retrieved from KB or web")
+        requirements = dspy.InputField(desc="JSON encoded requirements for the explanation")
+        solution = dspy.OutputField(desc="Structured JSON with COMPLETE solution including all steps, all parts answered, and explicit final answer. Must be a complete solution, not just an overview.")
+
+
+    def _ensure_dspy_configured() -> None:
+        if settings.gemini_api_key is None:
+            raise RuntimeError("Gemini API key missing. Set GEMINI_API_KEY in environment.")
+
+        lm = GeminiLM(model=settings.dspy_model, api_key=settings.gemini_api_key, max_output_tokens=settings.dspy_max_tokens)
+        dspy.settings.configure(lm=lm)
+
+
+    @dataclass
+    class WebDocument:
+        id: str
+        title: str
+        url: str
+        snippet: str
+        score: float
+
+
+    @dataclass
+    class SearchResult:
+        query: str
+        source: str
+        documents: Sequence[WebDocument]
+
+
+    async def generate_solution_with_cot(
+        query: str,
+        contexts: Iterable,
+        search_metadata: SearchResult | None = None,
+    ) -> tuple[list[tuple[str, str]], str]:
+        """Return (steps, final_answer) produced by Gemini via DSPy."""
+
+        _ensure_dspy_configured()
+
+        context_blocks: List[str] = []
+        for ctx in contexts:
+            block = json.dumps({
+                "document_id": getattr(ctx, "document_id", ""),
+                "question": getattr(ctx, "question", ""),
+                "answer": getattr(ctx, "answer", ""),
+                "similarity": getattr(ctx, "similarity", 0.0),
+            }, ensure_ascii=False)
+            context_blocks.append(block)
+
+        if search_metadata:
+            citations = [doc.__dict__ for doc in search_metadata.documents]
+        else:
+            citations = []
+
+        requirements = {
+            "style": "Explain as a friendly mathematics professor using numbered steps.",
+            "must_include": [
+                "Start the response with a single line: 'Answer: <final value or statement>'",
+                "You MUST solve the ENTIRE problem completely - do not stop with just an overview",
+                "List each algebraic manipulation explicitly",
+                "Show ALL intermediate steps - do not skip any calculations",
+                "Conclude with a clear final numeric or symbolic answer",
+                "If the problem has multiple parts, answer ALL parts and label them (a), (b), etc.",
+                "Avoid LaTeX markers like $...$ or \\frac{}{}; prefer natural language and simple unicode math",
+                "State units or interpretation when relevant (probability, geometry, word problems, etc.)",
+            ],
+            "citations": citations,
+        }
+
+        # Build comprehensive context prompt
+        context_prompt = ""
+        if context_blocks:
+            context_prompt = "\n\nCONTEXT FROM KNOWLEDGE BASE AND WEB SEARCH:\n" + "\n".join(context_blocks)
+        
+        enhanced_query = (
+            f"{query}\n\n"
+            "IMPORTANT: Solve this problem COMPLETELY. Provide all steps and the final answer. "
+            "Do not just give an overview - actually solve the entire problem." + context_prompt
+        )
+
+        predictor = dspy.Predict(MathTutorSignature)
+
+        async def _run_predict() -> dspy.Prediction:
+            return await asyncio.to_thread(
+                predictor,
+                query=enhanced_query,
+                context="\n".join(context_blocks) if context_blocks else "No additional context available.",
+                requirements=json.dumps(requirements, ensure_ascii=False),
+            )
+
+        prediction = await _run_predict()
+
+        try:
+            structured = json.loads(prediction.solution)
+        except json.JSONDecodeError:
+            logger.warning("dspy.solution.parse_failed", solution_preview=prediction.solution[:200] if prediction.solution else "")
+            # Try to extract solution from non-JSON response
+            solution_text = _normalize_math(prediction.solution or "")
+            # If it's not JSON, treat it as a natural language response and parse it
+            structured = {
+                "steps": [
+                    {
+                        "title": "Complete Solution",
+                        "explanation": solution_text,
+                    }
+                ],
+                "final_answer": solution_text.split("\n")[-1] if "\n" in solution_text else solution_text,
+            }
+
+        steps_raw = structured.get("steps", [])
+        
+        # Convert to dict format if it's tuple format
+        steps = []
+        for idx, step in enumerate(steps_raw):
+            if isinstance(step, dict):
+                steps.append({
+                    "title": step.get("title", f"Step {idx+1}"),
+                    "content": _normalize_math(step.get("explanation", step.get("content", ""))),
+                    "expression": _normalize_math(step.get("expression")) if step.get("expression") else None
+                })
+            elif isinstance(step, (list, tuple)) and len(step) >= 2:
+                steps.append({
+                    "title": step[0],
+                    "content": _normalize_math(step[1]),
+                    "expression": _normalize_math(step[2]) if len(step) > 2 and step[2] else None
+                })
+            else:
+                steps.append({
+                    "title": f"Step {idx+1}",
+                    "content": _normalize_math(str(step)),
+                    "expression": None
+                })
+        
+        final_answer = _normalize_math(structured.get("final_answer", ""))
+        
+        # Ensure final_answer is not empty
+        if not final_answer and steps:
+            # Try to extract from last step
+            last_content = steps[-1].get("content", "")
+            if last_content:
+                # Look for answer patterns
+                for line in reversed(last_content.split("\n")):
+                    if any(word in line.lower() for word in ["answer", "therefore", "thus", "hence", "result"]):
+                        final_answer = _normalize_math(line)
+                        break
+                if not final_answer:
+                    final_answer = last_content.split("\n")[-1] if "\n" in last_content else last_content
+        
+        # Ultimate fallback
+        if not final_answer:
+            final_answer = "Please see the steps above for the complete solution."
+
+        # Prepend a single-line explicit answer for UI readability
+        if not final_answer.lower().startswith("answer:"):
+            final_answer = f"Answer: {final_answer}"
+
+        return steps, final_answer
+except Exception:  # pragma: no cover - fallback when dspy isn't installed
+    # Provide a lightweight fallback so the application can start even if
+    # `dspy` is not installed. This fallback uses the Gemini client directly
+    # to generate a JSON-structured explanation.
+    import google.generativeai as genai  # type: ignore
+
+    from ..config import settings
+    from ..logger import get_logger
+
+    logger = get_logger(__name__)
+
+
+    @dataclass
+    class WebDocument:
+        id: str
+        title: str
+        url: str
+        snippet: str
+        score: float
+
+
+    @dataclass
+    class SearchResult:
+        query: str
+        source: str
+        documents: Sequence[WebDocument]
+
+
+    async def generate_solution_with_cot(
+        query: str,
+        contexts: Iterable,
+        search_metadata: SearchResult | None = None,
+    ) -> tuple[list[dict[str, str]], str]:
+        """Fallback: use Gemini directly to produce a JSON with `steps` and `final_answer`.
+
+        This is intentionally simple: it asks the model to return a JSON object. If parsing
+        fails, we return the raw text as a single reasoning step.
+        """
+
+        if settings.gemini_api_key is None:
+            raise RuntimeError("Gemini API key missing. Set GEMINI_API_KEY in environment.")
+
+        genai.configure(api_key=settings.gemini_api_key)
+        model = genai.GenerativeModel(settings.dspy_model)
+
+        context_text = []
+        for ctx in contexts:
+            context_text.append(json.dumps({
+                "document_id": getattr(ctx, "document_id", ""),
+                "question": getattr(ctx, "question", ""),
+                "answer": getattr(ctx, "answer", ""),
+                "similarity": getattr(ctx, "similarity", 0.0),
+            }, ensure_ascii=False))
+
+        context_section = ""
+        if context_text:
+            context_section = "\n\nCONTEXT FROM KNOWLEDGE BASE AND WEB SEARCH:\n" + "\n".join(context_text) + "\n"
+        
+        prompt = (
+            "You are an expert mathematics tutor across ALL math domains (arithmetic, algebra, geometry, trigonometry, calculus, linear algebra, probability, statistics, number theory, optimization, etc.). Provide clear, human-friendly solutions.\n\n"
+            "CRITICAL REQUIREMENTS - YOU MUST FOLLOW THESE:\n"
+            "1. Start your response with a single line: 'Answer: <final value or statement>'.\n"
+            "2. Solve the ENTIRE problem - do NOT just give an overview or stop midway.\n"
+            "3. Show EVERY step of your work - no skipped calculations.\n"
+            "4. If there are multiple parts, answer ALL parts, labeled (a), (b), etc.\n"
+            "5. Provide a clear, explicit FINAL ANSWER at the very end as well.\n"
+            "6. Avoid LaTeX markers like $...$ or \\frac{}{}; write math in natural language or simple unicode (e.g., 1/2, ·, ×, →).\n"
+            "7. Use concise, readable sentences; keep symbols understandable to non-experts.\n\n"
+            "RESPONSE STRUCTURE:\n"
+            "1. Brief Overview (1-2 sentences about the goal)\n"
+            "2. Step-by-Step Solution (numbered) with clear titles and calculations\n"
+            "3. Final Answer Section (repeat the answer clearly)\n\n"
+            "STUDENT'S QUESTION:\n" + query + context_section +
+            "\n\nNOW SOLVE THIS PROBLEM COMPLETELY.\n"
+        )
+
+        # Generate with more tokens to ensure complete answers
+        from google.generativeai.types import GenerationConfig
+        
+        generation_config = GenerationConfig(
+            temperature=0.3,  # Lower temperature for more focused responses
+            max_output_tokens=8192,  # Increased for complete solutions
+            top_p=0.95,
+        )
+        
+        resp = model.generate_content(prompt, generation_config=generation_config)
+        text = (resp.text or "").strip()
+        text = _normalize_math(text)
+        
+        if not text:
+            logger.warning("dspy.fallback.empty_response", query=query)
+            text = "I apologize, but I couldn't generate a response. Please try rephrasing your question."
+
+        try:
+            # Parse the natural language response into structured steps
+            lines = text.strip().split("\n")
+            steps = []
+            current_step = None
+            final_answer = ""
+            buffer = []
+            overview_added = False
+
+            for line in lines:
+                line = line.strip()
+                if not line:
+                    if current_step and buffer:
+                        current_step["content"] = "\n".join(buffer)
+                        buffer = []
+                    continue
+
+                # Detect step headers (more flexible patterns)
+                step_match = False
+                if line.lower().startswith("step ") or re.match(r"^\d+[\.\)]\s+", line, re.IGNORECASE):
+                    step_match = True
+                    if current_step:
+                        current_step["content"] = "\n".join(buffer)
+                        steps.append(current_step)
+                        buffer = []
+                    # Extract step number and title
+                    step_parts = re.split(r"[:\.]", line, 1)
+                    step_title = step_parts[1].strip() if len(step_parts) > 1 else line
+                    current_step = {
+                        "title": step_title if step_title else f"Step {len(steps) + 1}",
+                        "content": "",
+                        "expression": None
+                    }
+                # Detect final answer section
+                elif any(word in line.lower() for word in ["therefore", "thus", "finally", "hence", "answer:", "the answer is", "final answer"]):
+                    if current_step:
+                        current_step["content"] = "\n".join(buffer)
+                        steps.append(current_step)
+                        buffer = []
+                        current_step = None
+                    # Extract final answer
+                    for word in ["therefore", "thus", "finally", "hence", "answer:", "the answer is", "final answer"]:
+                        if word in line.lower():
+                            final_answer = line.split(":", 1)[1].strip() if ":" in line else line
+                            break
+                    if not final_answer:
+                        final_answer = line
+                # Handle equations (lines with = or mathematical operators)
+                elif current_step and ("=" in line or any(s in line for s in "+-*/^√∫∑∈ℝ")):
+                    if buffer:  # Save accumulated explanation first
+                        current_step["content"] = "\n".join(buffer)
+                        buffer = []
+                    if not current_step["expression"]:
+                        current_step["expression"] = _normalize_math(line)
+                    else:
+                        current_step["expression"] += "\n" + _normalize_math(line)
+                # Add to current step's content
+                elif current_step:
+                    buffer.append(line)
+                # Handle text before first step (overview)
+                elif not overview_added and not step_match:
+                    steps.append({
+                        "title": "Overview",
+                        "content": line,
+                        "expression": None
+                    })
+                    overview_added = True
+
+            # Don't forget the last step
+            if current_step:
+                if buffer:
+                    current_step["content"] = "\n".join(buffer)
+                steps.append(current_step)
+
+            # If no steps were parsed, create steps from the text
+            if not steps:
+                # Split by paragraphs or double newlines
+                paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
+                for idx, para in enumerate(paragraphs):
+                    if idx == 0:
+                        steps.append({
+                            "title": "Solution",
+                            "content": _normalize_math(para),
+                            "expression": None
+                        })
+                    else:
+                        steps.append({
+                            "title": f"Step {idx}",
+                            "content": _normalize_math(para),
+                            "expression": None
+                        })
+
+            # Extract final answer if not found
+            if not final_answer:
+                # Look for answer patterns in the last few lines
+                for line in reversed(lines[-10:]):
+                    line_lower = line.lower()
+                    if any(word in line_lower for word in ["answer", "therefore", "thus", "hence", "result"]):
+                        final_answer = line
+                        break
+                
+                # If still no answer, use the last meaningful line or paragraph
+                if not final_answer and steps:
+                    last_content = steps[-1].get("content", "")
+                    if last_content:
+                        final_answer = last_content.split("\n")[-1] if "\n" in last_content else last_content
+                
+                # Ultimate fallback
+                if not final_answer:
+                    final_answer = "Please refer to the steps above for the complete solution."
+
+            return steps, final_answer
+        except Exception:
+            logger.warning("dspy.fallback.parse_failed")
+            # Even for plain text, maintain consistent structure
+            return [{
+                "title": "Solution",
+                "content": text
+            }], text
+
+

app/tools/validator.py

@@ -0,0 +1,28 @@
+"""Validation helpers for user-provided solutions."""
+
+from __future__ import annotations
+
+import google.generativeai as genai
+
+from ..config import settings
+
+
+def validate_user_solution(question: str, proposed_solution: str) -> bool:
+    """Use Gemini to validate a user-uploaded solution."""
+
+    if not settings.gemini_api_key:
+        raise RuntimeError("Gemini API key required for solution validation")
+
+    genai.configure(api_key=settings.gemini_api_key)
+    model = genai.GenerativeModel(settings.gemini_model)
+    prompt = (
+        "You are an expert mathematics professor. Validate the student's solution. "
+        "Return ONLY 'VALID' if the reasoning is mathematically correct. "
+        "Return ONLY 'INVALID' otherwise.\n\n"
+        f"Question: {question}\nStudent solution:\n{proposed_solution}"
+    )
+    response = model.generate_content(prompt)
+    text = (response.text or "").strip().lower()
+    return text.startswith("valid")
+
+

app/tools/vision.py

@@ -0,0 +1,33 @@
+"""Image understanding helpers using Gemini multimodal models."""
+
+from __future__ import annotations
+
+import base64
+
+import google.generativeai as genai
+
+from ..config import settings
+
+
+def _strip_data_url(data: str) -> str:
+    if "," in data and data.startswith("data:"):
+        return data.split(",", 1)[1]
+    return data
+
+
+def extract_text_from_image(image_base64: str, prompt: str = "Extract all mathematics text from this image.") -> str:
+    """Use Gemini to extract math text from base64 encoded image."""
+
+    if not settings.gemini_api_key:
+        raise RuntimeError("Gemini API key not configured for image understanding")
+
+    genai.configure(api_key=settings.gemini_api_key)
+    clean_base64 = _strip_data_url(image_base64)
+    image_bytes = base64.b64decode(clean_base64)
+    model = genai.GenerativeModel(settings.gemini_model)
+    response = model.generate_content(
+        [prompt, {"mime_type": "image/png", "data": image_bytes}]
+    )
+    return response.text or ""
+
+

app/tools/web_search.py

@@ -0,0 +1,395 @@
+"""Web search workflow: MCP → LangChain Tavily → SDK fallback."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+import aiohttp
+
+from ..config import settings
+from ..logger import get_logger
+from .dspy_pipeline import SearchResult, WebDocument
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class MCPDocument:
+    id: str
+    title: str
+    url: str
+    snippet: str
+    score: float
+
+
+async def _parse_tavily_response(result: dict) -> List[MCPDocument]:
+    """Parse Tavily API response into MCPDocument objects."""
+    documents: List[MCPDocument] = []
+    
+    # Handle both direct results and nested results
+    results_list = result.get("results", [])
+    if not results_list and isinstance(result, list):
+        results_list = result
+    
+    for idx, item in enumerate(results_list):
+        documents.append(
+            MCPDocument(
+                id=item.get("id", str(idx)),
+                title=item.get("title", "Untitled"),
+                url=item.get("url", ""),
+                snippet=item.get("content", ""),
+                score=item.get("score", 0.0),
+            )
+        )
+    return documents
+
+
+async def _invoke_mcp_tavily(query: str, max_results: int = 5) -> List[MCPDocument]:
+    """Invoke Tavily via MCP server with multiple payload format attempts."""
+    mcp_url = settings.mcp_tavily_url or os.getenv("MCP_TAVILY_URL")
+    
+    if not mcp_url:
+        logger.debug("web_search.mcp_not_configured")
+        raise RuntimeError("MCP URL not configured")
+    
+    # Try different payload formats that MCP servers commonly use
+    payload_formats = [
+        # Format 1: MCP protocol with tools/call
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+                "name": "tavily_search",
+                "arguments": {
+                    "query": query,
+                    "max_results": max_results
+                }
+            }
+        },
+        # Format 2: Direct tavily_search method
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tavily_search",
+            "params": {
+                "query": query,
+                "max_results": max_results
+            }
+        },
+        # Format 3: Call tool method
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "call_tool",
+            "params": {
+                "name": "tavily_search",
+                "arguments": {
+                    "query": query,
+                    "max_results": max_results
+                }
+            }
+        },
+    ]
+    
+    last_error = None
+    
+    async with aiohttp.ClientSession() as session:
+        # Quick health check
+        try:
+            async with session.head(mcp_url, timeout=10) as health_resp:
+                if health_resp.status not in (200, 405):  # 405 = Method Not Allowed for HEAD
+                    logger.warning("web_search.mcp_health_check_failed", 
+                                 status=health_resp.status)
+        except Exception as health_exc:
+            logger.warning("web_search.mcp_unreachable", 
+                         error=str(health_exc),
+                         url=mcp_url)
+            raise RuntimeError(f"MCP server unreachable: {health_exc}")
+        
+        # Try each payload format
+        for idx, payload in enumerate(payload_formats, 1):
+            try:
+                logger.debug("web_search.mcp_attempting_format", 
+                           format_number=idx,
+                           method=payload.get("method"))
+                
+                headers = {
+                    "Accept": "text/event-stream, application/json",
+                    "Content-Type": "application/json",
+                }
+                
+                async with session.post(mcp_url, headers=headers, json=payload, timeout=30) as resp:
+                    ctype = resp.headers.get("Content-Type", "")
+                    status = resp.status
+                    
+                    if status != 200:
+                        response_text = await resp.text()
+                        logger.debug("web_search.mcp_format_failed", 
+                                   format_number=idx,
+                                   status=status,
+                                   response=response_text[:200])
+                        last_error = f"HTTP {status}: {response_text[:100]}"
+                        continue
+                    
+                    # Handle SSE response
+                    if "text/event-stream" in ctype:
+                        last_json = None
+                        async for raw in resp.content:
+                            line = raw.decode("utf-8", errors="ignore").strip()
+                            if line.startswith("data:"):
+                                data_str = line[5:].strip()
+                                if data_str and data_str != "[DONE]":
+                                    last_json = data_str
+                        
+                        if not last_json:
+                            logger.debug("web_search.mcp_empty_sse", format_number=idx)
+                            last_error = "Empty SSE stream"
+                            continue
+                        
+                        data = json.loads(last_json)
+                    else:
+                        # Handle JSON response
+                        data = await resp.json()
+                    
+                    # Check for JSON-RPC error
+                    if "error" in data:
+                        error_detail = data["error"]
+                        logger.debug("web_search.mcp_format_error", 
+                                   format_number=idx,
+                                   error=error_detail)
+                        last_error = f"RPC error: {error_detail}"
+                        continue
+                    
+                    # Extract result
+                    result = data.get("result", {})
+                    
+                    # Handle MCP protocol response format
+                    if "content" in result and isinstance(result["content"], list):
+                        for content_item in result["content"]:
+                            if content_item.get("type") == "text":
+                                text_data = content_item.get("text", "")
+                                try:
+                                    tavily_result = json.loads(text_data)
+                                    documents = await _parse_tavily_response(tavily_result)
+                                    if documents:
+                                        logger.info("web_search.mcp_success", 
+                                                  format_number=idx,
+                                                  document_count=len(documents))
+                                        return documents
+                                except json.JSONDecodeError:
+                                    continue
+                    
+                    # Handle direct Tavily response format
+                    if "results" in result:
+                        documents = await _parse_tavily_response(result)
+                        if documents:
+                            logger.info("web_search.mcp_success", 
+                                      format_number=idx,
+                                      document_count=len(documents))
+                            return documents
+                    
+                    last_error = f"No results in response structure: {list(result.keys())}"
+                    
+            except asyncio.TimeoutError:
+                logger.debug("web_search.mcp_timeout", format_number=idx)
+                last_error = "Request timeout"
+                continue
+            except Exception as exc:
+                logger.debug("web_search.mcp_format_exception", 
+                           format_number=idx,
+                           error=str(exc),
+                           error_type=type(exc).__name__)
+                last_error = str(exc)
+                continue
+    
+    # All formats failed
+    logger.warning("web_search.mcp_all_formats_failed", 
+                  last_error=last_error,
+                  formats_tried=len(payload_formats))
+    raise RuntimeError(f"MCP failed: {last_error}")
+
+
+# LangChain Tavily tool (preferred fallback)
+try:
+    from langchain_tavily import TavilySearch  # type: ignore
+except Exception:
+    TavilySearch = None  # type: ignore
+
+
+async def _run_tavily_langchain(query: str, max_results: int = 5) -> List[MCPDocument]:
+    """Use LangChain Tavily tool - the recommended integration."""
+    if TavilySearch is None:
+        raise RuntimeError("LangChain Tavily not installed. Run: pip install -U langchain-tavily")
+    
+    if not settings.tavily_api_key:
+        raise RuntimeError("TAVILY_API_KEY not configured")
+    
+    # Ensure API key is in environment for LangChain
+    os.environ["TAVILY_API_KEY"] = settings.tavily_api_key
+    
+    try:
+        # Initialize the tool with recommended settings
+        tool = TavilySearch(
+            max_results=max_results,
+            topic="general",
+            search_depth="basic",
+        )
+        
+        # Invoke the tool - it returns a dict with results
+        result = await asyncio.to_thread(tool.invoke, {"query": query})
+        
+        documents: List[MCPDocument] = []
+        results_list = result.get("results", [])
+        
+        for idx, item in enumerate(results_list):
+            documents.append(
+                MCPDocument(
+                    id=item.get("id", str(idx)),
+                    title=item.get("title", "Untitled"),
+                    url=item.get("url", ""),
+                    snippet=item.get("content", ""),
+                    score=item.get("score", 0.0),
+                )
+            )
+        
+        return documents
+        
+    except Exception as exc:
+        logger.error("web_search.langchain_execution_error", 
+                    error=str(exc),
+                    error_type=type(exc).__name__)
+        raise RuntimeError(f"LangChain Tavily failed: {exc}")
+
+
+# Direct Tavily SDK (last resort fallback)
+try:
+    from tavily import TavilyClient  # type: ignore
+except Exception:
+    TavilyClient = None  # type: ignore
+
+
+async def _run_tavily_sdk(query: str, max_results: int = 5) -> List[MCPDocument]:
+    """Direct Tavily SDK as last resort fallback."""
+    if TavilyClient is None:
+        raise RuntimeError("Tavily SDK not installed. Run: pip install tavily-python")
+    
+    if not settings.tavily_api_key:
+        raise RuntimeError("TAVILY_API_KEY not configured")
+    
+    client = TavilyClient(api_key=settings.tavily_api_key)
+    result = await asyncio.to_thread(
+        client.search, 
+        query=query, 
+        max_results=max_results, 
+        include_images=False
+    )
+    
+    documents: List[MCPDocument] = []
+    for idx, item in enumerate(result.get("results", [])):
+        documents.append(
+            MCPDocument(
+                id=item.get("id", str(idx)),
+                title=item.get("title", "Untitled"),
+                url=item.get("url", ""),
+                snippet=item.get("content", ""),
+                score=item.get("score", 0.0),
+            )
+        )
+    return documents
+
+
+async def run_web_search_with_fallback(query: str) -> Optional[SearchResult]:
+    """Run web search with fallback chain: MCP → LangChain Tavily → SDK.
+    
+    Priority order:
+    1. MCP Tavily (if configured) - Remote MCP server integration
+    2. LangChain Tavily - Official LangChain integration (recommended by Tavily)
+    3. Tavily SDK - Direct Python SDK as last resort
+    """
+    
+    all_documents: List[MCPDocument] = []
+    sources_used: List[str] = []
+    
+    # 1) Try MCP Tavily first (if configured)
+    mcp_url = settings.mcp_tavily_url or os.getenv("MCP_TAVILY_URL")
+    if mcp_url:
+        try:
+            tavily_docs = await _invoke_mcp_tavily(query, max_results=5)
+            if tavily_docs:
+                all_documents.extend(tavily_docs[:5])
+                sources_used.append("tavily-mcp")
+                logger.info("web_search.mcp_completed", document_count=len(tavily_docs))
+        except Exception as exc:
+            logger.warning("web_search.mcp_failed", error=str(exc))
+    
+    # 2) Fallback to LangChain Tavily (preferred method)
+    if len(all_documents) < 3:
+        try:
+            lc_docs = await _run_tavily_langchain(query, max_results=5)
+            existing_urls = {doc.url for doc in all_documents if doc.url}
+            
+            added_count = 0
+            for doc in lc_docs:
+                if doc.url not in existing_urls:
+                    all_documents.append(doc)
+                    added_count += 1
+                    if len(all_documents) >= 5:
+                        break
+            
+            if added_count > 0:
+                sources_used.append("tavily-langchain")
+                logger.info("web_search.langchain_completed", 
+                          document_count=added_count,
+                          total_documents=len(all_documents))
+        except Exception as lc_exc:
+            logger.warning("web_search.langchain_failed", error=str(lc_exc))
+    
+    # 3) Last resort: Direct Tavily SDK
+    if len(all_documents) < 3:
+        try:
+            tavily_sdk_docs = await _run_tavily_sdk(query, max_results=5)
+            existing_urls = {doc.url for doc in all_documents if doc.url}
+            
+            added_count = 0
+            for doc in tavily_sdk_docs:
+                if doc.url not in existing_urls:
+                    all_documents.append(doc)
+                    added_count += 1
+                    if len(all_documents) >= 5:
+                        break
+            
+            if added_count > 0:
+                sources_used.append("tavily-sdk")
+                logger.info("web_search.sdk_completed", 
+                          document_count=added_count,
+                          total_documents=len(all_documents))
+        except Exception as sdk_exc:
+            logger.warning("web_search.sdk_failed", error=str(sdk_exc))
+    
+    if not all_documents:
+        logger.error("web_search.all_sources_failed", query=query)
+        return None
+    
+    web_documents = [
+        WebDocument(
+            id=doc.id,
+            title=doc.title,
+            url=doc.url,
+            snippet=doc.snippet,
+            score=doc.score,
+        )
+        for doc in all_documents[:5]
+    ]
+    
+    source = "+".join(sources_used) if sources_used else "unknown"
+    logger.info("web_search.completed", 
+               source=source,
+               total_documents=len(web_documents),
+               query=query)
+    
+    return SearchResult(query=query, source=source, documents=web_documents)

app/workflows/__init__.py

@@ -0,0 +1,3 @@
+"""Workflow graphs for the math agent."""
+
+

app/workflows/langgraph_pipeline.py

@@ -0,0 +1,251 @@
+"""LangGraph implementation of the math agent workflow."""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+from langgraph.graph import END, StateGraph
+
+from ..config import settings
+from ..guardrails import run_input_guardrails, run_output_guardrails
+from ..logger import get_logger
+from ..schemas import Citation, RetrievalContext
+from ..services.vector_store import VectorStore
+from ..tools.dspy_pipeline import SearchResult, generate_solution_with_cot
+from ..tools.web_search import run_web_search_with_fallback
+
+logger = get_logger(__name__)
+
+
+class AgentGraphState(TypedDict, total=False):
+    query: str
+    sanitized_query: str
+    gateway_trace: list[str]
+    knowledge_hits: list[RetrievalContext]  # Combined KB + web for generation
+    kb_hits: list[RetrievalContext]  # KB hits only (for UI)
+    web_hits: list[RetrievalContext]  # Web hits only (for UI)
+    search_result: SearchResult | None
+    steps: list[tuple[str, str]]
+    answer: str
+    source: str
+    citations: list[Citation]
+    retrieved_from_kb: bool
+
+
+def build_math_agent_graph(vector_store: VectorStore) -> StateGraph:
+    """Compile the LangGraph workflow for the math agent."""
+
+    graph = StateGraph(AgentGraphState)
+
+    async def input_guardrails_node(state: AgentGraphState) -> AgentGraphState:
+        sanitized = run_input_guardrails(state["query"]) if settings.enforce_input_guardrails else state["query"]
+        trace = state.get("gateway_trace", []) + ["input_guardrails_pass"]
+        return {"sanitized_query": sanitized, "gateway_trace": trace}
+
+    async def retrieve_kb_node(state: AgentGraphState) -> AgentGraphState:
+        query = state["sanitized_query"]
+        kb_results = vector_store.search(query)
+        kb_contexts: list[RetrievalContext] = []
+        for result in kb_results:
+            # kb_results is a list of dicts with: document_id, question, answer, source, similarity
+            kb_contexts.append(
+                RetrievalContext(
+                    document_id=result.get("document_id", ""),
+                    question=result.get("question", ""),
+                    answer=result.get("answer", ""),
+                    similarity=result.get("similarity", 0.0) or 0.0,
+                )
+            )
+        trace = state.get("gateway_trace", []) + ["kb_search_complete"]
+        # Store KB contexts separately so we can combine them later
+        return {
+            "knowledge_hits": kb_contexts, 
+            "kb_hits": kb_contexts,  # Keep KB hits separate
+            "gateway_trace": trace
+        }
+
+    def route_after_retrieval(state: AgentGraphState) -> Literal["kb", "search"]:
+        # Always proceed to both KB and web search, then generate with Gemini
+        # This ensures we always get comprehensive results
+        contexts = state.get("knowledge_hits", []) or []
+        if contexts and len(contexts) > 0:
+            top_similarity = contexts[0].similarity if contexts[0].similarity is not None else 0.0
+            if top_similarity >= settings.similarity_threshold:
+                logger.info("router.has_good_kb_match", similarity=top_similarity, threshold=settings.similarity_threshold)
+                # Still go to web search to enhance with additional context
+                return "search"
+            logger.info("router.kb_below_threshold", top_similarity=top_similarity, threshold=settings.similarity_threshold)
+        else:
+            logger.info("router.no_kb_results")
+        # Always proceed to web search to get additional context
+        return "search"
+
+    async def kb_generation_node(state: AgentGraphState) -> AgentGraphState:
+        # This node is deprecated - we now always go through web search then generation
+        # But keep it for backward compatibility in case routing changes
+        contexts = state.get("knowledge_hits", [])
+        # Also fetch web search to combine with KB
+        query = state["sanitized_query"]
+        search_result = await run_web_search_with_fallback(query)
+        web_contexts = []
+        if search_result:
+            web_contexts = [
+                RetrievalContext(
+                    document_id=document.id,
+                    question=document.title,
+                    answer=document.snippet,
+                    similarity=document.score or 0.0,
+                )
+                for document in search_result.documents
+            ]
+        
+        # Combine KB and web contexts
+        all_contexts = contexts + web_contexts
+        steps, answer_text = await generate_solution_with_cot(state["sanitized_query"], all_contexts, search_metadata=search_result)
+        trace = state.get("gateway_trace", []) + ["router->kb+web"]
+        return {
+            "steps": steps,
+            "answer": answer_text,
+            "source": "kb+web",
+            "retrieved_from_kb": True,
+            "citations": state.get("citations", []),
+            "gateway_trace": trace,
+            "search_result": search_result,
+        }
+
+    async def web_search_node(state: AgentGraphState) -> AgentGraphState:
+        query = state["sanitized_query"]
+        # Get KB contexts from previous node (preserve them separately)
+        kb_contexts = state.get("kb_hits", []) or state.get("knowledge_hits", [])
+        
+        # Always attempt web search
+        search_result = await run_web_search_with_fallback(query)
+        
+        # Combine KB contexts with web search contexts for Gemini generation
+        all_contexts = list(kb_contexts) if kb_contexts else []
+        web_contexts = []
+        
+        if search_result and search_result.documents:
+            web_contexts = [
+                RetrievalContext(
+                    document_id=document.id,
+                    question=document.title,
+                    answer=document.snippet,
+                    similarity=document.score or 0.0,
+                )
+                for document in search_result.documents
+            ]
+            all_contexts.extend(web_contexts)
+            
+            citations = [
+                Citation(title=document.title, url=document.url)
+                for document in search_result.documents
+                if document.url
+            ]
+            source = search_result.source
+        else:
+            logger.warning("web_search.no_results", query=query)
+            citations = []
+            source = "kb-only" if kb_contexts else "direct"
+        
+        trace = state.get("gateway_trace", []) + ["web_search_complete", f"source={source}"]
+        return {
+            "search_result": search_result,
+            "knowledge_hits": all_contexts,  # Combined KB + web contexts for generation
+            "kb_hits": kb_contexts,  # Keep KB hits separate for UI
+            "web_hits": web_contexts,  # Keep web hits separate for UI
+            "citations": citations,
+            "retrieved_from_kb": len(kb_contexts) > 0,
+            "source": source,
+            "gateway_trace": trace,
+        }
+
+    async def search_generation_node(state: AgentGraphState) -> AgentGraphState:
+        # Always use Gemini to generate comprehensive answer from all available contexts
+        contexts = state.get("knowledge_hits", [])  # Already combined KB + web contexts
+        search_metadata = state.get("search_result")
+        
+        logger.info("generation.starting", contexts_count=len(contexts), has_search_metadata=search_metadata is not None)
+        
+        try:
+            # Always generate with Gemini using all available context
+            steps, answer_text = await generate_solution_with_cot(
+                state["sanitized_query"], 
+                contexts, 
+                search_metadata=search_metadata
+            )
+            
+            # Ensure answer is comprehensive and not empty
+            if not answer_text or not answer_text.strip():
+                logger.warning("generation.empty_response", query=state["sanitized_query"])
+                # Try to construct answer from steps if available
+                if steps:
+                    # Get the last step or combine all step content
+                    if isinstance(steps[-1], dict):
+                        answer_text = steps[-1].get("content", "") or steps[-1].get("explanation", "")
+                    elif isinstance(steps[-1], (list, tuple)) and len(steps[-1]) > 1:
+                        answer_text = steps[-1][1]
+                    else:
+                        answer_text = str(steps[-1])
+                    
+                    if not answer_text:
+                        # Combine all step contents
+                        answer_parts = []
+                        for step in steps:
+                            if isinstance(step, dict):
+                                content = step.get("content", "") or step.get("explanation", "")
+                                if content:
+                                    answer_parts.append(content)
+                            elif isinstance(step, (list, tuple)) and len(step) > 1:
+                                answer_parts.append(step[1])
+                        answer_text = "\n\n".join(answer_parts) if answer_parts else "Please see the steps above for the solution."
+                else:
+                    answer_text = "I apologize, but I couldn't generate a response. Please try rephrasing your question."
+                    steps = [{"title": "Error", "content": "Unable to generate solution with available context."}]
+            
+            # Log the response length to debug
+            logger.info("generation.completed", answer_length=len(answer_text), steps_count=len(steps))
+        except Exception as exc:
+            logger.exception("generation.failed", error=str(exc))
+            answer_text = "I encountered an error while processing your question. Please try again."
+            steps = [{"title": "Error", "content": str(exc)}]
+        
+        # Always return with all context information - let UI decide what to show
+        return {
+            "steps": steps, 
+            "answer": answer_text,
+            # Keep all context for UI display
+        }
+
+    async def output_guardrails_node(state: AgentGraphState) -> AgentGraphState:
+        if not settings.enforce_output_guardrails:
+            return {}
+        filtered_answer, urls = run_output_guardrails(state["answer"])
+        citations = list(state.get("citations", []))
+        for url in urls:
+            if not any(citation.url == url for citation in citations):
+                citations.append(Citation(title="Source", url=url))
+        
+        current_trace = state.get("gateway_trace", [])
+        trace = current_trace + ["output_guardrails_pass"]
+        
+        return {"answer": filtered_answer, "citations": citations, "gateway_trace": trace}
+
+    graph.add_node("input_guardrails", input_guardrails_node)
+    graph.add_node("retrieve_kb", retrieve_kb_node)
+    graph.add_node("kb_generate", kb_generation_node)
+    graph.add_node("web_search", web_search_node)
+    graph.add_node("search_generate", search_generation_node)
+    graph.add_node("output_guardrails", output_guardrails_node)
+
+    graph.set_entry_point("input_guardrails")
+    graph.add_edge("input_guardrails", "retrieve_kb")
+    graph.add_conditional_edges("retrieve_kb", route_after_retrieval, {"kb": "kb_generate", "search": "web_search"})
+    graph.add_edge("kb_generate", "output_guardrails")
+    graph.add_edge("web_search", "search_generate")
+    graph.add_edge("search_generate", "output_guardrails")
+    graph.add_edge("output_guardrails", END)
+
+    return graph.compile()
+
+

backend/data/feedback_db.json

@@ -0,0 +1,176 @@
+[
+  {
+    "message_id": "assistant-1762103842320",
+    "query": "Find the derivative of the function f(x)=x^3sin(x^2) and simplify your answer.",
+    "agent_response": {
+      "answer": "```json{ \"overview\": \"To find the derivative of the given function, we apply the product rule and the chain rule.\", \"steps\": [ { \"title\": \"Step 1: Identify the Rules for Differentiation\", \"content\": \"The function $f(x) = x^3 \\sin(x^2)$ is a product of two functions, $u(x) = x^3$ and $v(x) = \\sin(x^2)$. Therefore, we will use the product rule for differentiation, which states that if $f(x) = u(x)v(x)$, then $f'(x) = u'(x)v(x) + u(x)v'(x)$.\\n\\nAdditionally, to find the derivative of $v(x) = \\sin(x^2)$, we will need to apply the chain rule, which states that if $y = g(h(x))$, then $y' = g'(h(x))h'(x)$.\", \"expression\": \"f'(x) = u'(x)v(x) + u(x)v'(x)\" }, { \"title\": \"Step 2: Differentiate Each Part\", \"content\": \"First, let's find the derivative of $u(x) = x^3$:\\n$u'(x) = \\\\frac{d}{dx}(x^3) = 3x^2$\\n\\nNext, let's find the derivative of $v(x) = \\\\sin(x^2)$ using the chain rule. Let $w = x^2$, so $v(x) = \\\\sin(w)$.\\n$\\\\frac{dv}{dw} = \\\\cos(w)$\\n$\\\\frac{dw}{dx} = \\\\frac{d}{dx}(x^2) = 2x$\\n\\nApplying the chain rule, $v'(x) = \\\\frac{dv}{dw} \\\\cdot \\\\frac{dw}{dx} = \\\\cos(x^2) \\\\cdot 2x = 2x \\\\cos(x^2)$.\", \"expression\": \"u'(x) = 3x^2 \\\\quad \\\\text{and} \\\\quad v'(x) = 2x \\\\cos(x^2)\" }, { \"title\": \"Step 3: Apply the Product Rule\", \"content\": \"Now, we substitute $u(x)$, $u'(x)$, $v(x)$, and $v'(x)$ into the product rule formula:\\n$f'(x) = u'(x)v(x) + u(x)v'(x)$\\n$f'(x) = (3x^2)(\\\\sin(x^2)) + (x^3)(2x \\\\cos(x^2))$\\n$f'(x) = 3x^2 \\\\sin(x^2) + 2x^4 \\\\cos(x^2)$\", \"expression\": \"f'(x) = 3x^2 \\\\sin(x^2) + 2x^4 \\\\cos(x^2)\" }, { \"title\": \"Step 4: Simplify the Answer\", \"content\": \"We can simplify the expression by factoring out the common term $x^2$ from both terms:\\n$f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))$\", \"expression\": \"f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))\" } ], \"final_answer\": \"$f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))$\"}```",
+      "steps": [
+        {
+          "title": "Solution",
+          "content": "```json\n{\n  \"overview\": \"To find the derivative of the given function, we apply the product rule and the chain rule.\",\n  \"steps\": [\n    {\n      \"title\": \"Step 1: Identify the Rules for Differentiation\",\n      \"content\": \"The function $f(x) = x^3 \\sin(x^2)$ is a product of two functions, $u(x) = x^3$ and $v(x) = \\sin(x^2)$. Therefore, we will use the product rule for differentiation, which states that if $f(x) = u(x)v(x)$, then $f'(x) = u'(x)v(x) + u(x)v'(x)$.\\n\\nAdditionally, to find the derivative of $v(x) = \\sin(x^2)$, we will need to apply the chain rule, which states that if $y = g(h(x))$, then $y' = g'(h(x))h'(x)$.\",\n      \"expression\": \"f'(x) = u'(x)v(x) + u(x)v'(x)\"\n    },\n    {\n      \"title\": \"Step 2: Differentiate Each Part\",\n      \"content\": \"First, let's find the derivative of $u(x) = x^3$:\\n$u'(x) = \\\\frac{d}{dx}(x^3) = 3x^2$\\n\\nNext, let's find the derivative of $v(x) = \\\\sin(x^2)$ using the chain rule. Let $w = x^2$, so $v(x) = \\\\sin(w)$.\\n$\\\\frac{dv}{dw} = \\\\cos(w)$\\n$\\\\frac{dw}{dx} = \\\\frac{d}{dx}(x^2) = 2x$\\n\\nApplying the chain rule, $v'(x) = \\\\frac{dv}{dw} \\\\cdot \\\\frac{dw}{dx} = \\\\cos(x^2) \\\\cdot 2x = 2x \\\\cos(x^2)$.\",\n      \"expression\": \"u'(x) = 3x^2 \\\\quad \\\\text{and} \\\\quad v'(x) = 2x \\\\cos(x^2)\"\n    },\n    {\n      \"title\": \"Step 3: Apply the Product Rule\",\n      \"content\": \"Now, we substitute $u(x)$, $u'(x)$, $v(x)$, and $v'(x)$ into the product rule formula:\\n$f'(x) = u'(x)v(x) + u(x)v'(x)$\\n$f'(x) = (3x^2)(\\\\sin(x^2)) + (x^3)(2x \\\\cos(x^2))$\\n$f'(x) = 3x^2 \\\\sin(x^2) + 2x^4 \\\\cos(x^2)$\",\n      \"expression\": \"f'(x) = 3x^2 \\\\sin(x^2) + 2x^4 \\\\cos(x^2)\"\n    },\n    {\n      \"title\": \"Step 4: Simplify the Answer\",\n      \"content\": \"We can simplify the expression by factoring out the common term $x^2$ from both terms:\\n$f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))$\",\n      \"expression\": \"f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))\"\n    }\n  ],\n  \"final_answer\": \"$f'(x) = x^2 (3 \\\\sin(x^2) + 2x^2 \\\\cos(x^2))$\"\n}\n```",
+          "expression": null
+        }
+      ],
+      "retrieved_from_kb": false,
+      "knowledge_hits": [
+        {
+          "document_id": "0",
+          "question": "Find the derivative of f(x)=x^3 sin(x) - MyTutor",
+          "answer": "The derivative of f(x)=x^3 sin(x) is x^2(3 sin(x) + x cos(x)), using the product rule.",
+          "similarity": 0.79119295
+        },
+        {
+          "document_id": "1",
+          "question": "Solved The derivative of f(x) can be expressed in the form",
+          "answer": "The derivative of f(x) can be expressed in the form f'(x)=g(x)(3sinx+2)2, where g(x) is some function of x. Find g(x).Answer: g(x)=(b",
+          "similarity": 0.78512776
+        },
+        {
+          "document_id": "2",
+          "question": "What is the first derivative of the function f(x) =x^3sinx?",
+          "answer": "The first derivative is: u'v+uv'= 3x^2 sin x + x^3 cos x, or, x^2 (3 sin x + x cos x). However, if you mean x^(3 sin x),",
+          "similarity": 0.7173491
+        },
+        {
+          "document_id": "3",
+          "question": "The derivative of the function f is f'(x)=x-3sin x^2. Which ...",
+          "answer": "The derivative of the function f is f'(x)=x-3sin x^2. Which interval contains the greatest number of relative minimums of f? A. (-2,2) B. (-3,1) C. (-4",
+          "similarity": 0.6929958
+        },
+        {
+          "document_id": "4",
+          "question": "Larson Calculus 2.3 #44: Differentiate f(x) = sin(x)/x^3 ...",
+          "answer": "Let me show you how I find the derivative with the quotient rule.",
+          "similarity": 0.63452125
+        }
+      ],
+      "citations": [
+        {
+          "title": "Find the derivative of f(x)=x^3 sin(x) - MyTutor",
+          "url": "https://www.mytutor.co.uk/answers/17399/A-Level/Maths/Find-the-derivative-of-f-x-x-3-sin-x/"
+        },
+        {
+          "title": "Solved The derivative of f(x) can be expressed in the form",
+          "url": "https://www.chegg.com/homework-help/questions-and-answers/derivative-f-x-expressed-form-f-x-g-x-3sinx-2-2-g-x-function-x-find-g-x--answer-g-x-b-let--q147428016"
+        },
+        {
+          "title": "What is the first derivative of the function f(x) =x^3sinx?",
+          "url": "https://www.quora.com/What-is-the-first-derivative-of-the-function-f-x-x-3sinx"
+        },
+        {
+          "title": "The derivative of the function f is f'(x)=x-3sin x^2. Which ...",
+          "url": "https://www.gauthmath.com/solution/1813181098343573/116-Multiple-Choice-The-derivative-of-the-function-is-f-x-x-3sin-x2-Which-interv"
+        },
+        {
+          "title": "Larson Calculus 2.3 #44: Differentiate f(x) = sin(x)/x^3 ...",
+          "url": "https://www.youtube.com/watch?v=9qbaO_Jihzg"
+        }
+      ],
+      "source": "tavily-sdk",
+      "feedback_required": true,
+      "gateway_trace": [
+        "input_guardrails_pass",
+        "router.inspect",
+        "router->search",
+        "search.source=tavily-sdk",
+        "output_guardrails_pass"
+      ]
+    },
+    "feedback": {
+      "thumbs_up": true,
+      "primary_issue": null,
+      "has_better_solution": false,
+      "solution_type": null,
+      "better_solution_text": null,
+      "better_solution_pdf_base64": null,
+      "better_solution_image_base64": null
+    }
+  },
+  {
+    "message_id": "assistant-1762145260594",
+    "query": "Find the derivative of the function: f(x)=3x^4−5x^2+2squareroot(x)−7/x^3",
+    "agent_response": {
+      "answer": "Thus, the function can be rewritten as:",
+      "steps": [
+        {
+          "title": "Overview",
+          "content": "Let's find the derivative of the function $f(x)$ step by step.",
+          "expression": null
+        }
+      ],
+      "retrieved_from_kb": false,
+      "knowledge_hits": [
+        {
+          "document_id": "0",
+          "question": "Derivative Calculator - Mathway",
+          "answer": "Upgrade Calculators Help Sign In Sign Up # Derivative Calculator **Step 1:** Enter the function you want to find the derivative of in the editor. > The Derivative Calculator supports solving first, second...., fourth derivatives, as well as implicit differentiation and finding the zeros/roots. You can also get a better visual and understanding of the function by using our graphing tool. > Chain Rule: ddx[f(g(x))]=f'(g(x))g'(x) **Step 2:** Click the blue arrow to submit. Choose  **\"Find the Derivative\"**  from the topic selector and click to see the result! (2x−9)10 using Amazon.Auth.AccessControlPolicy; Mathway requires javascript and a modern browser. Please ensure that your password is at least 8 characters and contains each of the following: * a special character: @$#!%\\*?&",
+          "similarity": 0.98579
+        },
+        {
+          "document_id": "1",
+          "question": "Derivative Calculator - Math Portal",
+          "answer": "* Calculators Math Calculators, Lessons and Formulas * Calculators * Calculators * Derivative Calculator # Derivative calculator * Fraction Calculator * Percentage Calculator Polynomials * Factoring Polynomials * Simplify Polynomials * Multiplication / Division Solving Equations * Polynomial Equations * Square Calculator * Rectangle Calculator * Circle Calculator * Hexagon Calculator * Rhombus Calculator * Trapezoid Calculator * Distance calculator * Midpoint Calculator * Triangle Calculator * Division * Determinant Calculator Calculus Calculators * Limit Calculator * Derivative Calculator * Integral Calculator Equations * Probability Calculator * T-Test Calculator Financial Calculators * Amortization Calculator * Annuity Calculator Other Calculators Related calculators Limit calculator Integral calculator Derivative calculator – Widget Code **Widget preview:** Derivative calculator Online Math Calculators",
+          "similarity": 0.98278
+        },
+        {
+          "document_id": "2",
+          "question": "Derivative Calculator - Symbolab",
+          "answer": "*Example* : Find the derivative of $f\\left(x\\right)=\\frac{1}{x}$. scientific calculator inverse calculator simplify calculator distance calculator fractions calculator interval notation calculator cross product calculator probability calculator derivative calculator series calculator ratios calculator statistics calculator integral calculator inverse laplace transform calculator rounding calculator gcf calculator algebra calculator tangent line calculator trigonometry calculator log calculator standard deviation calculator linear equation calculator antiderivative calculator laplace transform calculator quadratic equation calculator domain calculator decimals calculator limit calculator equation solver definite integral calculator matrix inverse calculator matrix calculator system of equations calculator calculus calculator slope calculator long division calculator factors calculator polynomial calculator square root calculator implicit differentiation calculator word problem solver differential equation calculator average calculator synthetic division calculator",
+          "similarity": 0.97997
+        },
+        {
+          "document_id": "3",
+          "question": "Calculus - How to find the derivative of a function using the power rule",
+          "answer": "Calculus - How to find the derivative of a function using the power rule\nMySecretMathTutor\n241000 subscribers\n6381 likes\n582542 views\n5 Sep 2013\nThis video shows how to find the derivative of a function using the power rule.  Remember that this rule only works on functions of the form x^n where n is not equal to zero.  For more videos please visit http://www.mysecretmathtutor.com\n189 comments\n",
+          "similarity": 0.97435
+        },
+        {
+          "document_id": "4",
+          "question": "Finding the Derivative of a Square Root Function Using Definition of ...",
+          "answer": "Finding the Derivative of a Square Root Function Using Definition of a Derivative\nPatrick J\n1400000 subscribers\n1825 likes\n268324 views\n11 Dec 2011\nIn this video we compute the derivative of a square root function, namely f(x) = sqrt (2x + 1) by using the definition of a derivative.  We could use the power rule along with the chain rule as well of course, but this what one is often asked in the beginning of a calculus course.\nNote that to help simplify the expression for the derivative, we will make use of the conjugate, a common technique to help simplify these types of expressions with square roots.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#math, #algebra, #khanacademy, #khan, #geometry, #education, #montessori, #calculus, #homeschooling, #functions, #notation, #organicchemistry, #organicchemistrytutor, #calculus, #derivative, #powerrule, #limits,  #limit, #graph, #graphing, #conjugate, #infinity, #patrickjmt, #rational, #shortcut, #trick, #commondenominator, #fraction, #university, #admissions, #test #continuity #onesided #infinite #absolutevalue #tangents #tangentsandnormals #tangentline #definition #hindi #india\n126 comments\n",
+          "similarity": 0.96945
+        }
+      ],
+      "citations": [
+        {
+          "title": "Derivative Calculator - Mathway",
+          "url": "https://www.mathway.com/Calculator/derivative-calculator"
+        },
+        {
+          "title": "Derivative Calculator - Math Portal",
+          "url": "https://www.mathportal.org/calculators/calculus/derivative-calculator.php"
+        },
+        {
+          "title": "Derivative Calculator - Symbolab",
+          "url": "https://www.symbolab.com/solver/derivative-calculator"
+        },
+        {
+          "title": "Calculus - How to find the derivative of a function using the power rule",
+          "url": "https://www.youtube.com/watch?v=pBc4Udqw330"
+        },
+        {
+          "title": "Finding the Derivative of a Square Root Function Using Definition of ...",
+          "url": "https://www.youtube.com/watch?v=3bmw9UQxbRI"
+        }
+      ],
+      "source": "tavily-sdk",
+      "feedback_required": true,
+      "gateway_trace": [
+        "input_guardrails_pass",
+        "router.inspect",
+        "router->search",
+        "search.source=tavily-sdk",
+        "output_guardrails_pass"
+      ]
+    },
+    "feedback": {
+      "thumbs_up": false,
+      "primary_issue": "unclear",
+      "has_better_solution": false,
+      "solution_type": null,
+      "better_solution_text": null,
+      "better_solution_pdf_base64": null,
+      "better_solution_image_base64": null
+    }
+  }
+]

data/knowledge_base.jsonl

@@ -0,0 +1,6 @@
+{"id": "gsm8k-001", "question": "Solve for x: 2x + 5 = 17.", "answer": "x = 6", "step_by_step": ["Subtract 5 from both sides: 2x = 12", "Divide both sides by 2: x = 6"]}
+{"id": "gsm8k-002", "question": "A rectangle has a length of 12 cm and width 5 cm. What is its perimeter?", "answer": "Perimeter = 34 cm", "step_by_step": ["Perimeter of rectangle = 2*(length + width)", "Compute length + width: 12 + 5 = 17", "Multiply by 2: 2*17 = 34 cm"]}
+{"id": "gsm8k-003", "question": "If 3/4 of a number is 18, what is the number?", "answer": "The number is 24", "step_by_step": ["Let the number be n", "3/4 * n = 18", "Multiply both sides by 4/3: n = 18 * 4/3", "Compute: 18 * 4 = 72", "Divide by 3: 72 / 3 = 24"]}
+{"id": "gsm8k-004", "question": "Simplify: (x^2 - 9)/(x - 3)", "answer": "x + 3", "step_by_step": ["Factor numerator: x^2 - 9 = (x - 3)(x + 3)", "Cancel common factor (x - 3)", "Result: x + 3, for x ≠ 3"]}
+{"id": "gsm8k-005", "question": "Evaluate the derivative d/dx of f(x) = 3x^3 - 4x^2 + x - 7.", "answer": "f'(x) = 9x^2 - 8x + 1", "step_by_step": ["Apply power rule to each term", "Derivative of 3x^3 is 9x^2", "Derivative of -4x^2 is -8x", "Derivative of x is 1", "Derivative of constant -7 is 0", "Combine terms: 9x^2 - 8x + 1"]}
+

mcp_servers/tavily_server.py

@@ -0,0 +1,65 @@
+"""Minimal MCP-compatible stdio server wrapping Tavily search."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from tavily import TavilyClient
+
+
+def _respond(response: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(response) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> None:
+    client = TavilyClient()
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        method = request.get("method")
+        req_id = request.get("id")
+
+        if method == "initialize":
+            _respond({
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "serverInfo": {"name": "tavily-mcp", "version": "0.1.0"},
+                    "capabilities": {"tools": True},
+                },
+            })
+            continue
+
+        if method == "shutdown":
+            _respond({"jsonrpc": "2.0", "id": req_id, "result": None})
+            break
+
+        if method == "tavily_search":
+            params = request.get("params", {})
+            query = params.get("query", "")
+            max_results = params.get("max_results", 5)
+            include_images = params.get("include_images", False)
+            try:
+                result = client.search(query=query, max_results=max_results, include_images=include_images)
+                _respond({"jsonrpc": "2.0", "id": req_id, "result": result})
+            except Exception as exc:  # pragma: no cover
+                _respond({"jsonrpc": "2.0", "id": req_id, "error": {"code": -32000, "message": str(exc)}})
+            continue
+
+        _respond({"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": "Unknown method"}})
+
+
+if __name__ == "__main__":
+    main()
+
+

pyproject.toml

@@ -0,0 +1,44 @@
+ [tool.poetry]
+ name = "math-agent-backend"
+ version = "0.1.0"
+ description = "Agentic RAG math tutoring backend with guardrails, MCP search, and feedback loop"
+ authors = ["AI Assistant <assistant@example.com>"]
+ packages = [{ include = "app" }]
+
+ [tool.poetry.dependencies]
+python = "^3.13"
+fastapi = "*"
+uvicorn = { extras = ["standard"], version = "*" }
+pydantic = "*"
+pydantic-settings = "*"
+numpy = "*"
+pandas = "*"
+weaviate-client = "*"
+sentence-transformers = "*"
+scikit-learn = "*"
+httpx = "*"
+aiohttp = "*"
+tavily = "*"
+python-dotenv = "*"
+google-generativeai = "*"
+groq = "*"
+# dspy-ai removed from core dependencies to avoid complex transitive
+# dependency conflicts (fastapi/litellm). If you need DSPy features,
+# add it to an optional extras group after verifying compatibility.
+# dspy-ai = { version = "^2.6.0", python = "*" }
+structlog = "*"
+tenacity = "*"
+langgraph = "*"
+
+ [tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-asyncio = "*"
+pytest-cov = "*"
+ruff = "*"
+black = "*"
+mypy = "*"
+
+ [build-system]
+ requires = ["poetry-core>=1.0.0"]
+ build-backend = "poetry.core.masonry.api"
+

render.yaml

@@ -0,0 +1,30 @@
+services:
+  - type: web
+    name: math-agent-backend
+    env: python
+    region: oregon
+    plan: free
+    buildCommand: |
+      pip install poetry
+      poetry install --no-interaction --no-ansi --no-root
+    startCommand: |
+      poetry run uvicorn app.main:app --host 0.0.0.0 --port $PORT
+    autoDeploy: true
+    envVars:
+      - key: WEAVIATE_URL
+        sync: false
+      - key: WEAVIATE_API_KEY
+        sync: false
+      - key: TAVILY_API_KEY
+        sync: false
+      - key: MCP_TAVILY_URL
+        sync: false
+      - key: GEMINI_API_KEY
+        sync: false
+      - key: SIMILARITY_THRESHOLD
+        value: "0.80"
+      - key: ENFORCE_INPUT_GUARDRAILS
+        value: "true"
+      - key: ENFORCE_OUTPUT_GUARDRAILS
+        value: "true"
+

scripts/build_kb.py

@@ -0,0 +1,62 @@
+"""Script to build FAISS vector store from knowledge base dataset."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import faiss
+import numpy as np
+import pandas as pd
+from sentence_transformers import SentenceTransformer
+
+from app.config import settings
+
+
+def load_dataset(path: Path) -> list[dict]:
+    data: list[dict] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            data.append(json.loads(line))
+    return data
+
+
+def build_index(records: list[dict]) -> tuple[faiss.Index, np.ndarray]:
+    encoder = SentenceTransformer(settings.embedding_model_name)
+    corpus = [record["question"] + "\n" + record.get("answer", "") for record in records]
+    embeddings = encoder.encode(corpus, show_progress_bar=True)
+    embeddings = np.array(embeddings).astype("float32")
+    dimension = embeddings.shape[1]
+    index = faiss.IndexFlatIP(dimension)
+    faiss.normalize_L2(embeddings)
+    index.add(embeddings)
+    return index, embeddings
+
+
+def main(dataset_path: Path, output_index: Path, output_metadata: Path) -> None:
+    records = load_dataset(dataset_path)
+    index, _ = build_index(records)
+
+    output_index.parent.mkdir(parents=True, exist_ok=True)
+    output_metadata.parent.mkdir(parents=True, exist_ok=True)
+
+    faiss.write_index(index, str(output_index))
+
+    metadata = pd.DataFrame(records)
+    metadata.to_parquet(output_metadata, index=False)
+
+    print(f"Vector store written to {output_index}")
+    print(f"Metadata written to {output_metadata}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Build FAISS vector store for math agent")
+    parser.add_argument("--dataset", type=Path, default=Path("backend/data/knowledge_base.jsonl"))
+    parser.add_argument("--index", type=Path, default=Path(settings.vector_store_path))
+    parser.add_argument("--metadata", type=Path, default=Path(settings.vector_store_metadata_path))
+    args = parser.parse_args()
+
+    main(args.dataset, args.index, args.metadata)
+
+

scripts/build_weaviate_kb.py

@@ -0,0 +1,102 @@
+"""Script to build Weaviate vector store from knowledge base dataset."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import List, Dict, Any
+
+import numpy as np
+import weaviate
+from sentence_transformers import SentenceTransformer
+from tqdm import tqdm
+
+from app.config import settings
+
+
+def load_dataset(path: Path) -> List[Dict[str, Any]]:
+    data: List[Dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            data.append(json.loads(line))
+    return data
+
+
+def get_weaviate_client() -> weaviate.Client:
+    """Initialize Weaviate client with authentication."""
+    auth_config = weaviate.auth.AuthApiKey(api_key=settings.weaviate_api_key)
+    client = weaviate.Client(
+        url=settings.weaviate_url,
+        auth_client_secret=auth_config,
+    )
+    return client
+
+
+def setup_schema(client: weaviate.Client) -> None:
+    """Create the schema if it doesn't exist."""
+    if not client.schema.exists(settings.weaviate_class_name):
+        class_obj = {
+            "class": settings.weaviate_class_name,
+            "vectorizer": "none",  # We'll provide our own vectors
+            "properties": [
+                {"name": "question", "dataType": ["text"]},
+                {"name": "answer", "dataType": ["text"]},
+                {"name": "source", "dataType": ["text"]},
+            ]
+        }
+        client.schema.create_class(class_obj)
+
+
+def build_index(client: weaviate.Client, records: List[Dict[str, Any]], batch_size: int = 100) -> None:
+    """Build the vector index by importing records in batches."""
+    encoder = SentenceTransformer(settings.embedding_model_name)
+    
+    with client.batch as batch:
+        batch.batch_size = batch_size
+        
+        for record in tqdm(records, desc="Importing records"):
+            # Generate embedding from question and answer
+            text = record["question"] + "\n" + record.get("answer", "")
+            embedding = encoder.encode(text)
+            
+            # Normalize the embedding
+            embedding = embedding / np.linalg.norm(embedding)
+            
+            # Prepare properties
+            properties = {
+                "question": record["question"],
+                "answer": record.get("answer", ""),
+                "source": record.get("source", "")
+            }
+            
+            # Import the object with its vector
+            batch.add_data_object(
+                data_object=properties,
+                class_name=settings.weaviate_class_name,
+                vector=embedding.tolist()
+            )
+
+
+def main(dataset_path: Path) -> None:
+    print(f"Loading dataset from {dataset_path}")
+    records = load_dataset(dataset_path)
+    
+    print("Initializing Weaviate client")
+    client = get_weaviate_client()
+    
+    print("Setting up schema")
+    setup_schema(client)
+    
+    print("Building index")
+    build_index(client, records)
+    
+    print(f"Successfully imported {len(records)} records to Weaviate")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Build Weaviate vector store for math agent")
+    parser.add_argument("--dataset", type=Path, default=Path("backend/data/knowledge_base.jsonl"))
+    args = parser.parse_args()
+
+    main(args.dataset)