refactor: restructure project into modular src architecture and implement database store layer

config.py

@@ -0,0 +1,36 @@
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+ENV_PATH = Path(__file__).resolve().parents[1] / "config.env"
+load_dotenv(ENV_PATH)
+
+
+class Settings:
+    openrouter_api_key: str = os.getenv("OPENROUTER_API_KEY", "")
+    openrouter_base_url: str = os.getenv(
+        "OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"
+    )
+    supabase_url: str = os.getenv("SUPABASE_URL", "")
+    supabase_key: str = os.getenv("SUPABASE_KEY", "")
+    supabase_anon_key: str = os.getenv("SUPABASE_ANON_KEY", "")
+    model_name: str = os.getenv("MODEL_NAME", "openai/gpt-oss-120b")
+    transformers_no_tf: str = os.getenv("TRANSFORMERS_NO_TF", "1")
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    s = Settings()
+    if s.openrouter_api_key:
+        os.environ["OPENROUTER_API_KEY"] = s.openrouter_api_key
+    if s.openrouter_base_url:
+        os.environ["OPENROUTER_BASE_URL"] = s.openrouter_base_url
+    if "TRANSFORMERS_NO_TF" not in os.environ and s.transformers_no_tf:
+        os.environ["TRANSFORMERS_NO_TF"] = s.transformers_no_tf
+    return s
+
+
+settings = get_settings()

database.py

@@ -0,0 +1,11 @@
+from functools import lru_cache
+from typing import Optional
+from supabase import Client, create_client
+from src.config import settings
+
+
+@lru_cache()
+def get_supabase() -> Optional[Client]:
+    if not settings.supabase_url or not settings.supabase_key:
+        return None
+    return create_client(settings.supabase_url, settings.supabase_key)

dependencies.py

@@ -0,0 +1,10 @@
+from fastapi import Header, HTTPException
+from typing import Optional
+
+DEV_USER_ID = "00000000-0000-0000-0000-000000000001"
+
+
+async def get_current_user_id(x_user_id: Optional[str] = Header(None)) -> str:
+    if x_user_id:
+        return x_user_id
+    return DEV_USER_ID

main.py

@@ -0,0 +1,31 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from src.materials.routes import router as materials_router
+from src.summary_generator.routes import router as summary_router
+from src.rag.routes import router as tutor_router
+from src.quiz_generator.routes import router as quiz_router
+
+app = FastAPI(
+    title="AI Tutor API",
+    description="Backend API for the AI Tutor for Students application",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(materials_router)
+app.include_router(summary_router)
+app.include_router(tutor_router)
+app.include_router(quiz_router)
+
+
+@app.get("/api/health")
+async def health_check():
+    return {"status": "ok", "service": "AI Tutor API"}

materials/routes.py

@@ -0,0 +1,86 @@
+import time
+import validators
+from fastapi import APIRouter, UploadFile, File, HTTPException, Depends
+from pydantic import BaseModel
+
+from src.materials.text_utils import text_from_pdf, chunk_text, scrap_website
+from src.rag.rag import store_embeddings
+from src.store import create_material, update_material_status, save_chunks
+from src.dependencies import get_current_user_id
+
+router = APIRouter(prefix="/api/materials", tags=["Materials"])
+
+
+class URLInput(BaseModel):
+    url: str
+
+
+@router.post("/upload-pdf")
+async def upload_pdf(
+    file: UploadFile = File(...),
+    user_id: str = Depends(get_current_user_id),
+):
+    if not file.filename or not file.filename.endswith(".pdf"):
+        raise HTTPException(400, "Only PDF files are accepted")
+
+    try:
+        material = create_material(
+            user_id=user_id,
+            source_type="pdf",
+            title=file.filename,
+        )
+        material_id = material["id"]
+
+        raw = text_from_pdf(file.file)
+        chunks = chunk_text(raw)
+        chunk_ids = save_chunks(material_id, chunks)
+
+        update_material_status(material_id, "processing")
+        store_embeddings(material_id, chunk_ids, chunks)
+        update_material_status(material_id, "ready")
+
+        return {
+            "material_id": material_id,
+            "title": file.filename,
+            "chunks_count": len(chunks),
+        }
+    except Exception as e:
+        if material_id:
+            update_material_status(material_id, "failed", str(e))
+        raise HTTPException(500, f"Failed to process PDF: {e}")
+
+
+@router.post("/scrape-url")
+async def scrape_url(
+    input: URLInput,
+    user_id: str = Depends(get_current_user_id),
+):
+    if not validators.url(input.url):
+        raise HTTPException(400, "Invalid URL provided")
+
+    try:
+        material = create_material(
+            user_id=user_id,
+            source_type="url",
+            title=input.url,
+            url=input.url,
+        )
+        material_id = material["id"]
+
+        raw = scrap_website(input.url)
+        chunks = chunk_text(raw, chunk_size=600, chunk_overlap=100)
+        chunk_ids = save_chunks(material_id, chunks)
+
+        update_material_status(material_id, "processing")
+        store_embeddings(material_id, chunk_ids, chunks)
+        update_material_status(material_id, "ready")
+
+        return {
+            "material_id": material_id,
+            "title": input.url,
+            "chunks_count": len(chunks),
+        }
+    except Exception as e:
+        if material_id:
+            update_material_status(material_id, "failed", str(e))
+        raise HTTPException(500, f"Failed to scrape URL: {e}")

materials/text_utils.py

@@ -0,0 +1,24 @@
+import PyPDF2
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_community.document_loaders import UnstructuredURLLoader
+
+
+def text_from_pdf(pdf_file) -> str:
+    reader = PyPDF2.PdfReader(pdf_file)
+    text = ""
+    for page in reader.pages:
+        text += page.extract_text()
+    return text
+
+
+def chunk_text(text: str, chunk_size: int = 800, chunk_overlap: int = 150):
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=chunk_size, chunk_overlap=chunk_overlap
+    )
+    return splitter.split_text(text)
+
+
+def scrap_website(url: str) -> str:
+    loader = UnstructuredURLLoader(urls=[url], ssl_verify=True)
+    data = loader.load()
+    return data[0].page_content

quiz_generator/quiz.py

@@ -0,0 +1,177 @@
+import json
+import random
+import re
+from typing import Optional
+from langchain.prompts import PromptTemplate
+from langchain.chains import LLMChain
+from langchain.agents import create_openai_tools_agent, AgentExecutor
+from langchain_core.tools import create_retriever_tool
+
+from src.rag.rag import get_llm, web_search_tools, SupabaseRetriever
+
+
+def _quiz_prompt():
+    template = """
+You are an expert quiz generator specialized in creating educational and accurate quizzes.
+
+**SOURCE PRIORITY:**
+1. If a retriever tool is available, use it to access the material.
+2. If a text summary or chunks are provided, rely on that context.
+3. If no material is available, use the topic to search online.
+
+**TASK:**
+Create a {difficulty}-level quiz based on the provided material or topic.
+Include exactly:
+- {mcq_count} multiple choice questions
+- {tf_count} true/false questions
+
+**QUESTION REQUIREMENTS:**
+- Each MCQ must have 4 plausible options (A, B, C, D).
+- Answers must reference the labeled option (e.g., "answer": "A) 12.5 cm").
+- All questions must be factually correct.
+- Include concise explanations referencing material or credible sources.
+
+**OUTPUT FORMAT (MUST BE VALID JSON):**
+{{
+    "quiz_type": "{source_type}",
+    "difficulty": "{difficulty}",
+    "mcq_count": {mcq_count},
+    "tf_count": {tf_count},
+    "mcq": [
+        {{
+            "question": "Question text",
+            "options": ["A) Option 1", "B) Option 2", "C) Option 3", "D) Option 4"],
+            "answer": "A) Option A",
+            "explanation": "Brief factual explanation"
+        }}
+    ],
+    "tf": [
+        {{
+            "question": "True/False question text",
+            "answer": "True",
+            "explanation": "Brief factual explanation"
+        }}
+    ]
+}}
+
+**AVAILABLE CONTEXT:**
+{context}
+
+**THOUGHTS (optional):**
+{agent_scratchpad}
+"""
+    return PromptTemplate(
+        input_variables=[
+            "difficulty", "mcq_count", "tf_count",
+            "source_type", "context", "agent_scratchpad",
+        ],
+        template=template,
+    )
+
+
+def smart_quiz_generator(
+    difficulty,
+    mcq_count,
+    tf_count,
+    topic_title=None,
+    material_id=None,
+    summary=None,
+    chunks=None,
+):
+    random_chunks = None
+    if chunks:
+        sampled = random.sample(chunks, min(10, len(chunks) - 2)) + [chunks[0], chunks[-1]]
+        random.shuffle(sampled)
+        random_chunks = "\n".join(sampled)
+
+    if material_id:
+        return _contextual_quiz(difficulty, mcq_count, tf_count, random_chunks, material_id)
+    elif summary:
+        return _summary_quiz(difficulty, mcq_count, tf_count, summary)
+    elif chunks:
+        return _summary_quiz(difficulty, mcq_count, tf_count, random_chunks)
+    elif topic_title:
+        return _web_quiz(difficulty, mcq_count, tf_count, topic_title)
+    else:
+        raise ValueError("No data or topic provided for quiz generation.")
+
+
+def _summary_quiz(difficulty, mcq_count, tf_count, context_text):
+    prompt = _quiz_prompt()
+    llm = get_llm()
+    chain = LLMChain(llm=llm, prompt=prompt)
+    response = chain.run(
+        difficulty=difficulty,
+        mcq_count=mcq_count,
+        tf_count=tf_count,
+        source_type="summary",
+        context=context_text,
+        agent_scratchpad="",
+    )
+    return _parse_quiz({"output": response})
+
+
+def _contextual_quiz(difficulty, mcq_count, tf_count, context, material_id):
+    prompt = _quiz_prompt()
+    llm = get_llm()
+
+    retriever = SupabaseRetriever(material_id=material_id, k=5)
+    retriever_tool = create_retriever_tool(
+        retriever,
+        name="quiz_material_retriever",
+        description="Retrieves relevant content from uploaded materials for quiz generation.",
+    )
+
+    agent = create_openai_tools_agent(llm, [retriever_tool], prompt)
+    executor = AgentExecutor(
+        agent=agent,
+        tools=[retriever_tool],
+        verbose=False,
+        return_intermediate_steps=False,
+        handle_parsing_errors=True,
+    )
+
+    response = executor.invoke({
+        "difficulty": difficulty,
+        "source_type": "Document Embeddings",
+        "mcq_count": mcq_count,
+        "tf_count": tf_count,
+        "agent_scratchpad": "",
+        "context": context,
+    })
+    return _parse_quiz(response)
+
+
+def _web_quiz(difficulty, mcq_count, tf_count, topic_title):
+    prompt = _quiz_prompt()
+    llm = get_llm()
+    tools = web_search_tools()
+    agent = create_openai_tools_agent(llm, tools, prompt)
+
+    executor = AgentExecutor(
+        agent=agent,
+        tools=tools,
+        verbose=False,
+        return_intermediate_steps=False,
+        handle_parsing_errors=True,
+    )
+
+    response = executor.invoke({
+        "context": topic_title,
+        "difficulty": difficulty,
+        "mcq_count": mcq_count,
+        "tf_count": tf_count,
+        "source_type": "Web Search",
+        "agent_scratchpad": "",
+    })
+    return _parse_quiz(response)
+
+
+def _parse_quiz(response):
+    output = response["output"] if isinstance(response, dict) else str(response)
+    cleaned = re.sub(r"```(?:json)?\n?", "", output)
+    cleaned = cleaned.replace("```", "").strip()
+    match = re.search(r"(\{[\s\S]*\})", cleaned)
+    if match:
+        cleaned = match.group(1)
+    return json.loads(cleaned)

quiz_generator/routes.py

@@ -0,0 +1,87 @@
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from typing import Optional
+
+from src.quiz_generator.quiz import smart_quiz_generator
+from src.store import get_material, get_chunks, get_summary, save_quiz
+from src.dependencies import get_current_user_id
+from src.config import settings
+
+router = APIRouter(prefix="/api/quiz", tags=["Quiz"])
+
+
+class QuizRequest(BaseModel):
+    difficulty: str = "Medium"
+    mcq_count: int = 4
+    tf_count: int = 3
+    source_type: str = "web"
+    material_id: Optional[str] = None
+    topic: Optional[str] = None
+
+
+class QuizResponse(BaseModel):
+    quiz: dict
+    quiz_id: str
+
+
+@router.post("/generate", response_model=QuizResponse)
+async def generate_quiz(
+    body: QuizRequest,
+    user_id: str = Depends(get_current_user_id),
+):
+    if body.mcq_count < 1 or body.mcq_count > 20:
+        raise HTTPException(400, "MCQ count must be between 1 and 20")
+    if body.tf_count < 1 or body.tf_count > 20:
+        raise HTTPException(400, "True/False count must be between 1 and 20")
+
+    try:
+        quiz = None
+        material_id = body.material_id if body.source_type in ("pdf", "url") else None
+
+        if body.source_type == "web":
+            if not body.topic:
+                raise HTTPException(400, "Topic is required for web-based quiz")
+            quiz = smart_quiz_generator(
+                difficulty=body.difficulty,
+                mcq_count=body.mcq_count,
+                tf_count=body.tf_count,
+                topic_title=body.topic,
+            )
+
+        elif body.source_type in ("pdf", "url"):
+            mat = get_material(body.material_id) if body.material_id else None
+            if not mat:
+                raise HTTPException(400, f"No {body.source_type} material found")
+
+            chunks_list = get_chunks(body.material_id)
+            chunks_texts = [c["content"] for c in chunks_list] if chunks_list else []
+            summary_record = get_summary(body.material_id)
+            summary_text = summary_record["summary"] if summary_record else None
+
+            quiz = smart_quiz_generator(
+                difficulty=body.difficulty,
+                mcq_count=body.mcq_count,
+                tf_count=body.tf_count,
+                material_id=body.material_id if mat.get("status") == "ready" else None,
+                summary=summary_text,
+                chunks=chunks_texts,
+            )
+        else:
+            raise HTTPException(400, f"Unknown source_type: {body.source_type}")
+
+        saved = save_quiz(
+            user_id=user_id,
+            material_id=material_id,
+            source_type=body.source_type,
+            difficulty=body.difficulty,
+            mcq_count=body.mcq_count,
+            tf_count=body.tf_count,
+            quiz_data=quiz,
+            model_name=settings.model_name,
+        )
+
+        return QuizResponse(quiz=quiz, quiz_id=saved["id"])
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+    except Exception as e:
+        raise HTTPException(500, f"Quiz generation failed: {e}")

rag/rag.py

@@ -0,0 +1,192 @@
+import os
+from functools import lru_cache
+from typing import Optional
+
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain.prompts import PromptTemplate
+from langchain.memory import ConversationBufferMemory
+from langchain.agents import create_openai_tools_agent, AgentExecutor
+from langchain_community.tools import ArxivQueryRun, WikipediaQueryRun, DuckDuckGoSearchResults
+from langchain_core.tools.retriever import create_retriever_tool
+from langchain_core.retrievers import BaseRetriever
+from langchain_core.documents import Document
+from langchain_community.utilities import ArxivAPIWrapper, WikipediaAPIWrapper
+from langchain_openai import ChatOpenAI
+
+from src.config import settings
+from src.database import get_supabase
+
+
+# ── Embeddings ─────────────────────────────────────────
+
+EMBEDDING_DIM = 384
+
+@lru_cache
+def get_embedder():
+    return HuggingFaceEmbeddings(
+        model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+        model_kwargs={"device": "cpu"},
+        encode_kwargs={"normalize_embeddings": True},
+    )
+
+
+def store_embeddings(material_id: str, chunk_ids: list[str], chunks: list[str]):
+    embedder = get_embedder()
+    embeddings = embedder.embed_documents(chunks)
+
+    records = [
+        {"chunk_id": cid, "material_id": material_id, "embedding": emb}
+        for cid, emb in zip(chunk_ids, embeddings)
+    ]
+
+    db = get_supabase()
+    for i in range(0, len(records), 50):
+        db.table("material_embeddings").insert(records[i:i + 50]).execute()
+
+
+def similarity_search(query: str, material_id: str, k: int = 5) -> list[dict]:
+    embedder = get_embedder()
+    query_embedding = embedder.embed_query(query)
+
+    db = get_supabase()
+    result = db.rpc(
+        "match_material_chunks",
+        {
+            "query_embedding": query_embedding,
+            "match_material_id": material_id,
+            "match_threshold": 0.7,
+            "match_count": k,
+        },
+    ).execute()
+
+    return result.data
+
+
+# ── LLM ────────────────────────────────────────────────
+
+def get_llm():
+    if not os.environ.get("OPENROUTER_API_KEY"):
+        raise ValueError("OPENROUTER_API_KEY not found. Please set it in config.env.")
+    return ChatOpenAI(
+        model=settings.model_name,
+        base_url=settings.openrouter_base_url,
+        api_key=settings.openrouter_api_key,
+    )
+
+
+# ── Web Search Tools ───────────────────────────────────
+
+def web_search_tools():
+    wikipedia = WikipediaQueryRun(
+        api_wrapper=WikipediaAPIWrapper(top_k_results=3, doc_content_chars_max=7000)
+    )
+    arxiv = ArxivQueryRun(
+        api_wrapper=ArxivAPIWrapper(top_k_results=2, doc_content_chars_max=8000)
+    )
+    duck = DuckDuckGoSearchResults()
+    return [wikipedia, arxiv, duck]
+
+
+# ── Supabase Retriever (replaces FAISS) ────────────────
+
+class SupabaseRetriever(BaseRetriever):
+    material_id: str
+    k: int = 4
+
+    def _get_relevant_documents(self, query: str) -> list[Document]:
+        results = similarity_search(query, self.material_id, self.k)
+        return [
+            Document(page_content=r["content"], metadata={
+                "similarity": r.get("similarity"),
+                "chunk_id": r.get("chunk_id"),
+            })
+            for r in results
+        ]
+
+
+# ── RAG Prompt ─────────────────────────────────────────
+
+def _rag_prompt():
+    return PromptTemplate(
+        input_variables=["chat_history", "input", "agent_scratchpad"],
+        template="""
+You are an advanced AI research assistant specializing in accurate, well-reasoned, and context-aware responses.
+You have access to multiple external tools including:
+
+- **Wikipedia Retriever** for general knowledge and conceptual explanations,
+- **Arxiv Retriever** for academic and scientific research information,
+- **DuckDuckGo Retriever** for the latest web-based insights,
+- **Knowledge Retriever:** for local learning materials, which may include:
+    - Embedding-based vector databases (most precise and semantic),
+    - Summaries (concise overviews of key material),
+    - Raw text chunks (unedited extracted text, less refined but detailed).
+
+## Role and Objectives:
+- Provide clear, factual, and logically organized answers.
+- Integrate information from available tools when relevant.
+- Maintain a professional and instructive tone.
+- Respect previous chat context to ensure continuity.
+
+## Reasoning Guidelines:
+1. Use retrievers only when they can enhance or verify your response.
+2. Combine retrieved facts with your own reasoning.
+3. When multiple tools return information, synthesize a unified explanation.
+4. If information is insufficient, acknowledge the limitation.
+5. Always focus on clarity, structure, and factual accuracy.
+
+## Response Format:
+- **1. Informed Answer:** Provide a detailed, structured explanation.
+- **2. Final Insight:** Conclude with a short, relevant takeaway.
+
+---
+### Chat History:
+{chat_history}
+
+### User Query:
+{input}
+
+### Agent Scratchpad:
+{agent_scratchpad}
+""",
+    )
+
+
+# ── RAG Answer ─────────────────────────────────────────
+
+def rag_answer(
+    query: str,
+    material_id: Optional[str] = None,
+    chunks: Optional[list[str]] = None,
+    summaries: str = "",
+    memory: ConversationBufferMemory = None,
+):
+    if memory is None:
+        memory = ConversationBufferMemory(
+            input_key="input", memory_key="chat_history", return_messages=True
+        )
+
+    prompt = _rag_prompt()
+    tools = web_search_tools()
+    llm = get_llm()
+
+    if material_id:
+        retriever = SupabaseRetriever(material_id=material_id, k=4)
+        retriever_tool = create_retriever_tool(
+            retriever,
+            name="knowledge_retriever",
+            description="Retrieves relevant educational material, notes, and explanations from the knowledge base.",
+        )
+        tools.append(retriever_tool)
+
+    agent = create_openai_tools_agent(llm, tools, prompt)
+    executor = AgentExecutor(
+        agent=agent,
+        tools=tools,
+        memory=memory,
+        verbose=False,
+        return_intermediate_steps=False,
+        handle_parsing_errors=True,
+    )
+
+    response = executor.invoke({"input": query})
+    return response["output"], memory

rag/routes.py

@@ -0,0 +1,74 @@
+import time
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+
+from src.rag.rag import rag_answer
+from src.store import get_material, get_chunks, get_summary, get_or_create_memory
+
+router = APIRouter(prefix="/api/tutor", tags=["Tutor"])
+
+
+class TutorQuery(BaseModel):
+    query: str
+    source_type: str = "web"
+    material_id: Optional[str] = None
+    memory_id: Optional[str] = None
+
+
+class TutorResponse(BaseModel):
+    answer: str
+    source: str
+    time_taken: float
+    memory_id: str
+
+
+@router.post("/ask", response_model=TutorResponse)
+async def ask_tutor(body: TutorQuery):
+    if not body.query.strip():
+        raise HTTPException(400, "Query cannot be empty")
+
+    memory, memory_id = get_or_create_memory(body.memory_id)
+    start = time.time()
+
+    try:
+        if body.source_type in ("pdf", "url"):
+            mat = get_material(body.material_id) if body.material_id else None
+            if not mat:
+                raise HTTPException(400, f"No {body.source_type} material found. Upload one first.")
+
+            material_id = body.material_id
+            chunks_list = get_chunks(material_id)
+            chunks_texts = [c["content"] for c in chunks_list] if chunks_list else []
+            summary_record = get_summary(material_id)
+            summary_text = summary_record["summary"] if summary_record else ""
+            status = mat.get("status")
+
+            if status == "ready":
+                answer, memory = rag_answer(
+                    query=body.query, material_id=material_id, memory=memory
+                )
+                source = f"{body.source_type.upper()} (embeddings)"
+            elif summary_text:
+                answer, memory = rag_answer(
+                    query=body.query, summaries=summary_text, memory=memory
+                )
+                source = f"{body.source_type.upper()} (summary)"
+            elif chunks_texts:
+                answer, memory = rag_answer(
+                    query=body.query, chunks=chunks_texts, memory=memory
+                )
+                source = f"{body.source_type.upper()} (chunks)"
+            else:
+                answer, memory = rag_answer(query=body.query, memory=memory)
+                source = "Web Search (no material data)"
+
+        else:
+            answer, memory = rag_answer(query=body.query, memory=memory)
+            source = "Web Search"
+
+    except Exception as e:
+        raise HTTPException(500, f"Error generating answer: {e}")
+
+    elapsed = time.time() - start
+    return TutorResponse(answer=answer, source=source, time_taken=elapsed, memory_id=memory_id)

store.py

@@ -0,0 +1,131 @@
+from typing import Optional
+from langchain.memory import ConversationBufferMemory
+from src.database import get_supabase
+
+
+def _db():
+    client = get_supabase()
+    if client is None:
+        raise RuntimeError(
+            "Supabase not configured. Set SUPABASE_URL and SUPABASE_KEY in config.env."
+        )
+    return client
+
+
+# ── Materials ──────────────────────────────────────────
+
+def create_material(user_id: str, source_type: str, title: str,
+                    file_path: Optional[str] = None,
+                    url: Optional[str] = None) -> dict:
+    data = {
+        "user_id": user_id,
+        "source_type": source_type,
+        "title": title,
+        "status": "pending",
+    }
+    if file_path:
+        data["file_path"] = file_path
+    if url:
+        data["url"] = url
+    result = _db().table("materials").insert(data).execute()
+    return result.data[0]
+
+
+def update_material_status(material_id: str, status: str,
+                           error_message: Optional[str] = None):
+    data = {"status": status}
+    if error_message:
+        data["error_message"] = error_message
+    _db().table("materials").update(data).eq("id", material_id).execute()
+
+
+def get_material(material_id: str) -> Optional[dict]:
+    result = _db().table("materials").select("*").eq("id", material_id).execute()
+    return result.data[0] if result.data else None
+
+
+# ── Material Chunks ────────────────────────────────────
+
+def save_chunks(material_id: str, chunks: list[str]) -> list[str]:
+    records = [
+        {"material_id": material_id, "chunk_index": i, "content": c}
+        for i, c in enumerate(chunks)
+    ]
+    result = _db().table("material_chunks").insert(records).execute()
+    return [r["id"] for r in result.data]
+
+
+def get_chunks(material_id: str) -> list[dict]:
+    result = (
+        _db().table("material_chunks")
+        .select("*")
+        .eq("material_id", material_id)
+        .order("chunk_index")
+        .execute()
+    )
+    return result.data
+
+
+# ── Summaries ──────────────────────────────────────────
+
+def save_summary(material_id: str, user_id: str, summary: str,
+                 time_taken: float, model_name: str = ""):
+    data = {
+        "material_id": material_id,
+        "user_id": user_id,
+        "summary": summary,
+        "status": "completed",
+        "time_taken": time_taken,
+        "model_name": model_name,
+    }
+    _db().table("summaries").upsert(data, on_conflict=["material_id"]).execute()
+
+
+def get_summary(material_id: str) -> Optional[dict]:
+    result = (
+        _db().table("summaries")
+        .select("*")
+        .eq("material_id", material_id)
+        .maybe_single()
+        .execute()
+    )
+    return result.data if result.data else None
+
+
+# ── Quizzes ────────────────────────────────────────────
+
+def save_quiz(user_id: str, material_id: Optional[str], source_type: str,
+              difficulty: str, mcq_count: int, tf_count: int,
+              quiz_data: dict, model_name: str = "") -> dict:
+    data = {
+        "user_id": user_id,
+        "source_type": source_type,
+        "difficulty": difficulty,
+        "mcq_count": mcq_count,
+        "tf_count": tf_count,
+        "quiz_data": quiz_data,
+        "status": "completed",
+        "model_name": model_name,
+    }
+    if material_id:
+        data["material_id"] = material_id
+    result = _db().table("quizzes").insert(data).execute()
+    return result.data[0]
+
+
+# ── Conversation Memory (in-memory, ephemeral) ─────────
+
+import uuid as _uuid
+
+_memories: dict[str, ConversationBufferMemory] = {}
+
+
+def get_or_create_memory(memory_id: Optional[str] = None):
+    if memory_id and memory_id in _memories:
+        return _memories[memory_id], memory_id
+    mid = memory_id or str(_uuid.uuid4())
+    mem = ConversationBufferMemory(
+        input_key="input", memory_key="chat_history", return_messages=True
+    )
+    _memories[mid] = mem
+    return mem, mid

summary_generator/routes.py

@@ -0,0 +1,51 @@
+import time
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+
+from src.summary_generator.summary import summarizer
+from src.store import get_material, get_chunks, save_summary
+from src.dependencies import get_current_user_id
+from src.config import settings
+
+router = APIRouter(prefix="/api/materials", tags=["Summarizer"])
+
+
+class SummarizeRequest(BaseModel):
+    material_id: str
+
+
+class SummarizeResponse(BaseModel):
+    summary: str
+    time_taken: float
+
+
+@router.post("/summarize", response_model=SummarizeResponse)
+async def generate_summary(
+    body: SummarizeRequest,
+    user_id: str = Depends(get_current_user_id),
+):
+    mat = get_material(body.material_id)
+    if not mat:
+        raise HTTPException(404, "Material not found")
+
+    chunks_list = get_chunks(body.material_id)
+    if not chunks_list:
+        raise HTTPException(400, "No text chunks found in this material")
+
+    try:
+        combined = "\n".join(c["content"] for c in chunks_list)
+        start = time.time()
+        summary = summarizer(combined)
+        elapsed = time.time() - start
+
+        save_summary(
+            material_id=body.material_id,
+            user_id=user_id,
+            summary=summary,
+            time_taken=elapsed,
+            model_name=settings.model_name,
+        )
+
+        return SummarizeResponse(summary=summary, time_taken=elapsed)
+    except Exception as e:
+        raise HTTPException(500, f"Summarization failed: {e}")

summary_generator/summary.py

@@ -0,0 +1,43 @@
+from langchain.prompts import PromptTemplate
+from langchain.chains import LLMChain
+from src.rag.rag import get_llm
+
+
+def summarizer_prompt():
+    return PromptTemplate(
+        input_variables=["input"],
+        template="""
+You are an expert academic assistant tasked with creating a comprehensive and well-structured summary of educational material.
+
+**INSTRUCTIONS:**
+1. Analyze the provided text and identify the main topics, key concepts, and important details.
+2. Create a coherent summary that flows logically from introduction to conclusion.
+3. Focus on educational value - highlight definitions, theories, examples, and practical applications.
+4. Maintain academic tone while ensuring clarity and accessibility.
+5. Organize the summary with clear sections and logical progression.
+6. If the content contains a list of facts, make sure the final summary presents them as a numbered list.
+
+**STRUCTURE YOUR SUMMARY AS FOLLOWS:**
+- **Overview**: Begin with a 2-3 sentence high-level overview of the entire content
+- **Key Topics**: List the main topics covered in the material
+- **Detailed Summary**: Provide a comprehensive section-by-section summary covering all important concepts
+- **Key Takeaways**: Highlight the most important points, definitions, and conclusions
+- **Educational Value**: Explain how this material helps in understanding the subject
+
+**CONTENT TO SUMMARIZE:**
+{input}
+
+**REMEMBER:**
+- Be thorough but concise
+- Maintain academic accuracy
+- Use clear, educational language
+- Focus on what would be most helpful for a student studying this material
+""",
+    )
+
+
+def summarizer(text: str) -> str:
+    prompt = summarizer_prompt()
+    llm = get_llm()
+    chain = LLMChain(llm=llm, prompt=prompt, verbose=False)
+    return chain.run(input=text)