Initial commit: DocsQA app

.env.example

@@ -0,0 +1,15 @@
+GROQ_API_KEY=your-groq-api-key
+SECRET_KEY=replace-me-with-a-long-random-string
+DATABASE_URL=postgresql+psycopg://postgres.your-project-ref:your-password@aws-0-region.pooler.supabase.com:6543/postgres
+UPLOAD_DIRECTORY=./uploads
+STORAGE_BACKEND=local
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+SUPABASE_STORAGE_BUCKET=documents
+SUPABASE_STORAGE_PREFIX=docsqa
+ACCESS_TOKEN_EXPIRE_MINUTES=720
+MODEL_NAME=llama-3.1-8b-instant
+EMBEDDING_MODEL=mixedbread-ai/mxbai-embed-large-v1
+EMBEDDING_DIMENSIONS=1024
+WEB_SEARCH_PROVIDER=duckduckgo
+TAVILY_API_KEY=

.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+docsqa_langgraph_assignment.egg-info/
+uploads/
+.idea/
+.vscode/

README.md

@@ -0,0 +1,139 @@
+# DocsQA LangGraph Assignment
+
+RAG-powered research assistant with:
+
+- Auth (register/login/logout) using HTTP-only cookie sessions
+- Multi-file PDF upload (up to 5 files/request, max 10 pages/file)
+- Duplicate detection by SHA-256 hash with cross-user document reuse
+- Vector indexing in Supabase Postgres + `pgvector`
+- LangGraph agent with document retrieval + web search fallback
+- Session conversation memory for follow-up questions
+- Source citations in answers for both document and web evidence
+- Chat-style UI with markdown rendering
+
+## Architecture
+
+- Backend: FastAPI + SQLAlchemy
+- Agent: LangGraph ReAct agent
+- LLM: Groq chat model
+- Vector store: Supabase Postgres with `pgvector`
+- Search fallback: Tavily (preferred) or DuckDuckGo when available
+
+## Chunking Strategy
+
+- Splitter: recursive character splitter (`chunk_size=1200`, `chunk_overlap=200`)
+- Why:
+  - 1200 keeps enough local context for legal/business clauses
+  - 200 overlap reduces boundary loss between adjacent chunks
+  - good balance for retrieval accuracy vs. embedding cost
+- Indexing is page-aware: each stored chunk carries `page_number` metadata.
+
+## Retrieval Approach
+
+- Retrieval method: cosine similarity search in `pgvector`
+- Pipeline:
+  - determine relevant user-owned document hashes
+  - embed query
+  - retrieve top-k chunks across selected docs
+- Returned evidence includes:
+  - document filename
+  - page number
+  - excerpt text
+- Final assistant answer is instructed to cite these in a human-friendly source section.
+
+## Agent Routing Logic
+
+- Default behavior: prefer `vector_search` for questions answerable from uploaded docs.
+- If document evidence is insufficient, agent can call `web_search` tool.
+- Web search output is normalized to citation-friendly rows (title, URL, snippet).
+- Prompt requires:
+  - vector citations: document + page + excerpt
+  - web citations: website title + URL
+
+## Bonus Feature
+
+**Implemented bonus:** User-scoped retrieval with automatic document dedup reuse.
+
+- If two users upload the same file, processing/indexing is reused by file hash.
+- Ownership is still enforced via `user_documents` mapping, so retrieval stays user-scoped.
+- Why chosen: materially improves performance/cost while preserving access boundaries.
+
+## Problems Faced and Fixes
+
+- Dependency mismatch (`transformers`/`sentence-transformers`/`torch`) causing startup errors.
+  - Added robust local fallback embedding path to keep app functional.
+- Optional web-search dependency (`ddgs`) missing.
+  - Added graceful web tool fallback and Tavily direct tool support.
+- Passlib bcrypt backend issues.
+  - Switched new password hashing to `pbkdf2_sha256` while retaining bcrypt verify compatibility.
+- Template/render and response UX issues.
+  - Reworked frontend into a stable chat-style UI with clean result handling.
+
+## If I Had More Time
+
+- Add proper migration tooling (Alembic) instead of startup `ALTER TABLE`.
+- Add reranking for higher retrieval precision on long multi-document queries.
+- Add persistent server-side conversation storage (Redis/Postgres) for multi-worker deployments.
+- Add automated evaluation suite for citation faithfulness and retrieval quality.
+
+## Environment Setup
+
+```bash
+cp .env.example .env
+```
+
+Required:
+
+- `GROQ_API_KEY`
+- `SECRET_KEY`
+- `DATABASE_URL` (Supabase transaction pooler recommended)
+
+Optional:
+
+- `TAVILY_API_KEY` (for Tavily web search)
+
+Storage (optional, recommended for deployment):
+
+- `STORAGE_BACKEND=local` or `supabase`
+- `SUPABASE_URL`
+- `SUPABASE_SERVICE_ROLE_KEY`
+- `SUPABASE_STORAGE_BUCKET` (default: `documents`)
+- `SUPABASE_STORAGE_PREFIX` (default: `docsqa`)
+
+Recommended `DATABASE_URL` format:
+
+`postgresql+psycopg://<user>:<password>@<pooler-host>:6543/postgres?sslmode=require`
+
+## Install and Run
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+uvicorn app.main:app --reload
+```
+
+Open: `http://127.0.0.1:8000`
+
+## File Storage Mode
+
+- Local dev default: `STORAGE_BACKEND=local` (writes under `UPLOAD_DIRECTORY`).
+- Deployment recommendation: `STORAGE_BACKEND=supabase` to store PDFs in Supabase Storage instead of local disk.
+
+## API Endpoints
+
+- `POST /register`
+- `POST /login`
+- `POST /logout`
+- `POST /upload`
+- `GET /documents`
+- `POST /ask`
+
+## test_documents
+
+Sample PDFs used during development are in `test_documents/`.
+
+## Deployment and Loom
+
+- Live deployed URL: _add your deployed link here_
+- Loom walkthrough (<5 min): _add your Loom link here_

app/__init__.py

@@ -0,0 +1 @@
+# Package marker.

app/config.py

@@ -0,0 +1,35 @@
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    app_name: str = "DocsQA Assignment"
+    secret_key: str = "change-me"
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 720
+    database_url: str = "postgresql+psycopg://postgres:postgres@localhost:5432/postgres"
+    upload_directory: str = "./uploads"
+    storage_backend: str = "local"
+    supabase_url: str | None = None
+    supabase_service_role_key: str | None = None
+    supabase_storage_bucket: str = "documents"
+    supabase_storage_prefix: str = "docsqa"
+    model_name: str = "llama-3.1-8b-instant"
+    embedding_model: str = "mixedbread-ai/mxbai-embed-large-v1"
+    embedding_dimensions: int = 1024
+    groq_api_key: str | None = None
+    web_search_provider: str = "duckduckgo"
+    tavily_api_key: str | None = None
+
+    @property
+    def upload_path(self) -> Path:
+        return Path(self.upload_directory)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/database.py

@@ -0,0 +1,41 @@
+from collections.abc import Generator
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import make_url
+from sqlalchemy.exc import OperationalError
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from app.config import get_settings
+
+
+settings = get_settings()
+
+engine = create_engine(settings.database_url, pool_pre_ping=True)
+SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, expire_on_commit=False)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def init_db() -> None:
+    try:
+        with engine.begin() as connection:
+            connection.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
+            connection.execute(text("ALTER TABLE IF EXISTS document_chunks ADD COLUMN IF NOT EXISTS page_number INTEGER"))
+        Base.metadata.create_all(bind=engine)
+    except OperationalError as exc:
+        host = make_url(settings.database_url).host or "<unknown>"
+        raise RuntimeError(
+            "Database connection failed for host "
+            f"'{host}'. If you are using Supabase, use the Transaction Pooler URL "
+            "(port 6543) from the Supabase dashboard with sslmode=require."
+        ) from exc
+
+
+def get_db() -> Generator[Session, None, None]:
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/main.py

@@ -0,0 +1,374 @@
+import re
+from typing import Any
+
+from fastapi import Cookie, Depends, FastAPI, File, Form, HTTPException, Request, UploadFile, status
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.responses import StreamingResponse
+from langchain_core.messages import HumanMessage, ToolMessage
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from sqlalchemy.exc import OperationalError
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.database import get_db, init_db
+from app.models import Document, User, UserDocument
+from app.schemas import AskRequest, AskResponse, UserCreate, UserLogin
+from app.security import create_access_token, decode_access_token, hash_password, verify_password
+from app.services.agent import build_agent
+from app.services.document_service import DocumentService
+from app.services.pdf_utils import count_pdf_pages_from_bytes
+from app.services.storage_service import StorageService
+
+
+init_db()
+
+app = FastAPI(title="DocsQA Assignment")
+app.mount("/static", StaticFiles(directory="app/static"), name="static")
+templates = Jinja2Templates(directory="app/templates")
+document_service = DocumentService()
+storage_service = StorageService()
+MAX_UPLOAD_FILES = 5
+MAX_PDF_PAGES = 10
+
+
+def _message_content_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        chunks: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                text_value = item.get("text")
+                if isinstance(text_value, str):
+                    chunks.append(text_value)
+            else:
+                chunks.append(str(item))
+        return "\n".join(chunks)
+    return str(content)
+
+
+def _parse_vector_sources(tool_output: str) -> list[dict[str, str]]:
+    lines = tool_output.splitlines()
+    sources: list[dict[str, str]] = []
+    current_document_id = ""
+    current_doc = ""
+    current_page = ""
+
+    for line in lines:
+        match = re.match(r"^\s*\d+\.\s+document_id=(.*?)\s+\|\s+document=(.*?)\s+\|\s+page=(.*?)\s+\|\s+distance=", line)
+        if match:
+            current_document_id = match.group(1).strip()
+            current_doc = match.group(2).strip()
+            current_page = match.group(3).strip()
+            continue
+        excerpt_match = re.match(r"^\s*excerpt:\s*(.*)$", line)
+        if excerpt_match and current_doc:
+            excerpt = excerpt_match.group(1).strip()
+            sources.append(
+                {
+                    "document_id": current_document_id,
+                    "document": current_doc,
+                    "page": current_page or "unknown",
+                    "excerpt": excerpt,
+                }
+            )
+            current_document_id = ""
+            current_doc = ""
+            current_page = ""
+    return sources
+
+
+def _parse_web_sources(tool_output: str) -> list[dict[str, str]]:
+    lines = tool_output.splitlines()
+    sources: list[dict[str, str]] = []
+    current_title = ""
+    current_url = ""
+
+    for line in lines:
+        title_match = re.match(r"^\s*\d+\.\s+title:\s*(.*)$", line)
+        if title_match:
+            current_title = title_match.group(1).strip()
+            current_url = ""
+            continue
+        url_match = re.match(r"^\s*url:\s*(.*)$", line)
+        if url_match and current_title:
+            current_url = url_match.group(1).strip()
+            sources.append({"title": current_title, "url": current_url})
+            current_title = ""
+            current_url = ""
+    return sources
+
+
+def _extract_current_turn_tool_messages(messages: list[Any]) -> list[ToolMessage]:
+    turn_tools_reversed: list[ToolMessage] = []
+    for message in reversed(messages):
+        if isinstance(message, HumanMessage):
+            break
+        if isinstance(message, ToolMessage):
+            turn_tools_reversed.append(message)
+    return list(reversed(turn_tools_reversed))
+
+
+def _extract_sources_from_messages(messages: list[Any]) -> dict[str, list[dict[str, str]]]:
+    vector_sources: list[dict[str, str]] = []
+    web_sources: list[dict[str, str]] = []
+
+    for message in _extract_current_turn_tool_messages(messages):
+        tool_name = (message.name or "").strip()
+        text = _message_content_to_text(message.content)
+        if tool_name == "vector_search":
+            vector_sources.extend(_parse_vector_sources(text))
+        elif tool_name == "web_search":
+            web_sources.extend(_parse_web_sources(text))
+
+    seen_vector: set[tuple[str, str, str]] = set()
+    deduped_vector: list[dict[str, str]] = []
+    for item in vector_sources:
+        key = (item.get("document", ""), item.get("page", ""), item.get("excerpt", ""))
+        if key in seen_vector:
+            continue
+        seen_vector.add(key)
+        deduped_vector.append(item)
+
+    seen_web: set[tuple[str, str]] = set()
+    deduped_web: list[dict[str, str]] = []
+    for item in web_sources:
+        key = (item.get("title", ""), item.get("url", ""))
+        if key in seen_web:
+            continue
+        seen_web.add(key)
+        deduped_web.append(item)
+
+    return {"vector": deduped_vector, "web": deduped_web}
+
+
+def _strip_sources_from_answer(answer: str) -> str:
+    # Remove any trailing "Sources" section and source-status lines from model text.
+    cleaned = re.sub(r"(?is)\n+\s*(?:#+\s*)?sources\s*:?\s*\n.*$", "", answer).strip()
+    lines = cleaned.splitlines()
+    filtered = []
+    for line in lines:
+        if re.match(r"^\s*source(s)?\s*:", line, flags=re.IGNORECASE):
+            continue
+        if re.match(r"^\s*no sources were used for this response\.?\s*$", line, flags=re.IGNORECASE):
+            continue
+        if re.match(r"^\s*no citations available for this turn\.?\s*$", line, flags=re.IGNORECASE):
+            continue
+        filtered.append(line)
+    return "\n".join(filtered).strip()
+
+
+def get_current_user(
+    access_token: str | None = Cookie(default=None),
+    db: Session = Depends(get_db),
+) -> User:
+    if not access_token:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    user_id = decode_access_token(access_token)
+    if not user_id:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+    try:
+        user = db.get(User, int(user_id))
+    except OperationalError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Database is temporarily unavailable. Please try again in a moment.",
+        ) from exc
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found")
+    return user
+
+
+@app.get("/", response_class=HTMLResponse)
+def home(request: Request, access_token: str | None = Cookie(default=None), db: Session = Depends(get_db)):
+    user = None
+    documents = []
+    db_unavailable = False
+    if access_token:
+        user_id = decode_access_token(access_token)
+        if user_id:
+            try:
+                user = db.get(User, int(user_id))
+                if user:
+                    documents = document_service.list_user_documents(db, user)
+            except OperationalError:
+                # Keep homepage responsive during transient DNS/DB outages.
+                db_unavailable = True
+                user = None
+                documents = []
+    return templates.TemplateResponse(
+        request=request,
+        name="index.html",
+        context={"request": request, "user": user, "documents": documents, "db_unavailable": db_unavailable},
+    )
+
+
+@app.post("/register")
+def register(email: str = Form(...), password: str = Form(...), db: Session = Depends(get_db)):
+    payload = UserCreate(email=email, password=password)
+    existing = db.scalar(select(User).where(User.email == payload.email))
+    if existing:
+        raise HTTPException(status_code=400, detail="Email already registered")
+    user = User(email=payload.email, password_hash=hash_password(payload.password))
+    db.add(user)
+    db.commit()
+    token = create_access_token(str(user.id))
+    response = JSONResponse(
+        status_code=status.HTTP_201_CREATED,
+        content={"message": "Registered successfully", "email": user.email},
+    )
+    response.set_cookie("access_token", token, httponly=True, samesite="lax", path="/")
+    return response
+
+
+@app.post("/login")
+def login(email: str = Form(...), password: str = Form(...), db: Session = Depends(get_db)):
+    payload = UserLogin(email=email, password=password)
+    user = db.scalar(select(User).where(User.email == payload.email))
+    if not user or not verify_password(payload.password, user.password_hash):
+        raise HTTPException(status_code=400, detail="Invalid credentials")
+    token = create_access_token(str(user.id))
+    response = JSONResponse(content={"message": "Login successful", "email": user.email})
+    response.set_cookie("access_token", token, httponly=True, samesite="lax", path="/")
+    return response
+
+
+@app.post("/logout")
+def logout(access_token: str | None = Cookie(default=None)):
+    response = JSONResponse(content={"message": "Logged out successfully"})
+    response.delete_cookie("access_token", path="/")
+    return response
+
+
+@app.post("/upload")
+async def upload_document(
+    files: list[UploadFile] = File(..., alias="file"),
+    db: Session = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    if not files:
+        raise HTTPException(status_code=400, detail="At least one PDF file is required")
+    if len(files) > MAX_UPLOAD_FILES:
+        raise HTTPException(status_code=400, detail=f"Upload supports up to {MAX_UPLOAD_FILES} files at a time")
+
+    results = []
+    for file in files:
+        filename = file.filename or ""
+        if not filename.lower().endswith(".pdf"):
+            raise HTTPException(status_code=400, detail=f"Only PDF files are supported: {filename or '<unnamed file>'}")
+
+        content, file_hash = await document_service.save_upload(file)
+        page_count = count_pdf_pages_from_bytes(content)
+        if page_count > MAX_PDF_PAGES:
+            raise HTTPException(
+                status_code=400,
+                detail=f"{filename} has {page_count} pages. Maximum allowed is {MAX_PDF_PAGES} pages per file.",
+            )
+
+        document, created, processed = document_service.get_or_create_document(
+            db=db,
+            user=user,
+            upload=file,
+            content=content,
+            file_hash=file_hash,
+        )
+        results.append(
+            {
+                "filename": document.filename,
+                "created": created,
+                "processed": processed,
+                "page_count": document.page_count,
+            }
+        )
+
+    db.commit()
+    return {
+        "message": "Upload handled successfully",
+        "count": len(results),
+        "documents": results,
+    }
+
+
+@app.get("/documents")
+def list_documents(db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    documents = document_service.list_user_documents(db, user)
+    return [
+        {
+            "id": document.id,
+            "filename": document.filename,
+            "file_hash": document.file_hash,
+            "page_count": document.page_count,
+            "summary": document.summary,
+        }
+        for document in documents
+    ]
+
+
+@app.get("/documents/{document_id}/pdf")
+def get_document_pdf(document_id: int, db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    link = db.scalar(
+        select(UserDocument.id).where(UserDocument.document_id == document_id, UserDocument.user_id == user.id)
+    )
+    if not link:
+        raise HTTPException(status_code=404, detail="Document not found for this user.")
+
+    document = db.get(Document, document_id)
+    if document is None:
+        raise HTTPException(status_code=404, detail="Document not found.")
+
+    try:
+        content = storage_service.read_file_bytes(file_path=document.file_path)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail="Unable to load document content.") from exc
+
+    headers = {"Content-Disposition": f'inline; filename="{document.filename}"'}
+    return StreamingResponse(iter([content]), media_type="application/pdf", headers=headers)
+
+
+@app.delete("/documents/{document_id}")
+def delete_document(document_id: int, db: Session = Depends(get_db), user: User = Depends(get_current_user)):
+    try:
+        result = document_service.delete_user_document(db, user=user, document_id=document_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    db.commit()
+    return {
+        "message": f"Removed {result['filename']} from your account.",
+        "deleted_shared_document": result["deleted_shared_document"],
+    }
+
+
+@app.post("/ask", response_model=AskResponse)
+def ask_question(
+    payload: AskRequest,
+    db: Session = Depends(get_db),
+    user: User = Depends(get_current_user),
+    access_token: str | None = Cookie(default=None),
+):
+    document_service.ensure_page_metadata_for_user(db=db, user=user)
+    agent = build_agent(db=db, user=user)
+    session_key = access_token or f"user:{user.id}"
+    config = {"configurable": {"thread_id": session_key}}
+    previous_messages: list[Any] = []
+    try:
+        state = agent.get_state(config)
+        values = getattr(state, "values", {}) or {}
+        maybe_messages = values.get("messages", [])
+        if isinstance(maybe_messages, list):
+            previous_messages = maybe_messages
+    except Exception:
+        # If state read fails, continue safely and parse from result fallback.
+        previous_messages = []
+
+    result = agent.invoke({"messages": [("user", payload.query)]}, config=config)
+    final_message = result["messages"][-1].content
+    answer = final_message if isinstance(final_message, str) else str(final_message)
+    answer = _strip_sources_from_answer(answer)
+    all_messages = result.get("messages", [])
+    if isinstance(all_messages, list) and len(all_messages) >= len(previous_messages):
+        current_turn_messages = all_messages[len(previous_messages):]
+    else:
+        current_turn_messages = all_messages if isinstance(all_messages, list) else []
+    sources = _extract_sources_from_messages(current_turn_messages)
+    return AskResponse(answer=answer, sources=sources)

app/models.py

@@ -0,0 +1,69 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from pgvector.sqlalchemy import Vector
+
+from app.config import get_settings
+
+from app.database import Base
+
+settings = get_settings()
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    documents: Mapped[list["UserDocument"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+
+
+class Document(Base):
+    __tablename__ = "documents"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    filename: Mapped[str] = mapped_column(String(512), nullable=False)
+    file_hash: Mapped[str] = mapped_column(String(64), unique=True, nullable=False, index=True)
+    file_path: Mapped[str] = mapped_column(String(1024), nullable=False)
+    page_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    summary: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    extracted_preview: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    processing_status: Mapped[str] = mapped_column(String(32), default="completed", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    users: Mapped[list["UserDocument"]] = relationship(back_populates="document", cascade="all, delete-orphan")
+    chunks: Mapped[list["DocumentChunk"]] = relationship(back_populates="document", cascade="all, delete-orphan")
+
+
+class UserDocument(Base):
+    __tablename__ = "user_documents"
+    __table_args__ = (UniqueConstraint("user_id", "document_id", name="uq_user_document"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False, index=True)
+    document_id: Mapped[int] = mapped_column(ForeignKey("documents.id"), nullable=False, index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    user: Mapped["User"] = relationship(back_populates="documents")
+    document: Mapped["Document"] = relationship(back_populates="users")
+
+
+class DocumentChunk(Base):
+    __tablename__ = "document_chunks"
+    __table_args__ = (UniqueConstraint("document_id", "chunk_index", name="uq_document_chunk"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    document_id: Mapped[int] = mapped_column(ForeignKey("documents.id"), nullable=False, index=True)
+    file_hash: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    filename: Mapped[str] = mapped_column(String(512), nullable=False)
+    chunk_index: Mapped[int] = mapped_column(Integer, nullable=False)
+    page_number: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+    embedding: Mapped[list[float]] = mapped_column(Vector(settings.embedding_dimensions), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    document: Mapped["Document"] = relationship(back_populates="chunks")

app/schemas.py

@@ -0,0 +1,35 @@
+from pydantic import BaseModel, EmailStr, Field
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class TokenPayload(BaseModel):
+    sub: str
+
+
+class AskRequest(BaseModel):
+    query: str
+
+
+class AskResponse(BaseModel):
+    answer: str
+    sources: dict[str, list[dict[str, str]]] = Field(default_factory=lambda: {"vector": [], "web": []})
+
+
+class DocumentResponse(BaseModel):
+    id: int
+    filename: str
+    file_hash: str
+    summary: str
+    page_count: int
+
+    class Config:
+        from_attributes = True

app/security.py

@@ -0,0 +1,39 @@
+from datetime import datetime, timedelta, timezone
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from app.config import get_settings
+
+
+# Use PBKDF2 for new hashes to avoid bcrypt backend/version issues and
+# bcrypt's 72-byte password input limit. Keep bcrypt for legacy verification.
+pwd_context = CryptContext(
+    schemes=["pbkdf2_sha256", "bcrypt"],
+    deprecated="auto",
+)
+settings = get_settings()
+
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    return pwd_context.verify(password, password_hash)
+
+
+def create_access_token(subject: str) -> str:
+    expires_delta = timedelta(minutes=settings.access_token_expire_minutes)
+    expire = datetime.now(timezone.utc) + expires_delta
+    payload = {"sub": subject, "exp": expire}
+    return jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm)
+
+
+def decode_access_token(token: str) -> str | None:
+    try:
+        payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+        subject = payload.get("sub")
+        return str(subject) if subject is not None else None
+    except JWTError:
+        return None

app/services/agent.py

@@ -0,0 +1,104 @@
+from typing import Literal
+
+from langchain_core.messages import AIMessage, SystemMessage
+from langchain_core.tools import StructuredTool
+from langchain_groq import ChatGroq
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.prebuilt import ToolNode
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from app.config import get_settings
+from app.models import User
+from app.services.document_service import DocumentService
+from app.services.vector_store import VectorStoreService
+from app.services.web_search import build_web_search_tool
+
+
+class VectorSearchInput(BaseModel):
+    query: str = Field(..., description="The user question to answer from uploaded documents.")
+    file_hashes: list[str] | None = Field(
+        default=None,
+        description="Optional document hashes to filter search. Leave empty to auto-resolve relevant documents for the current user.",
+    )
+
+
+LANGGRAPH_CHECKPOINTER = MemorySaver()
+
+
+def _route_tools(state: MessagesState) -> Literal["tools", "__end__"]:
+    last = state["messages"][-1]
+    if isinstance(last, AIMessage) and last.tool_calls:
+        return "tools"
+    return "__end__"
+
+
+def build_agent(*, db: Session, user: User):
+    settings = get_settings()
+    if not settings.groq_api_key:
+        raise RuntimeError("GROQ_API_KEY is required for agent responses.")
+    llm = ChatGroq(api_key=settings.groq_api_key, model=settings.model_name, temperature=0)
+    document_service = DocumentService()
+    vector_store = VectorStoreService()
+    web_search_tool = build_web_search_tool()
+
+    def vector_search(query: str, file_hashes: list[str] | None = None) -> str:
+        resolved_hashes = file_hashes or document_service.resolve_relevant_document_hashes(db, user=user, query=query)
+        if not resolved_hashes:
+            return "No uploaded documents are available for this user."
+        matches = vector_store.similarity_search(db=db, query=query, file_hashes=resolved_hashes, k=4)
+        if not matches:
+            return f"No vector matches found for hashes: {resolved_hashes}"
+        lines = ["Vector evidence (cite document + page + excerpt in final answer):"]
+        for index, match in enumerate(matches, start=1):
+            page_number = match["metadata"].get("page_number")
+            page_label = str(page_number) if page_number is not None else "unknown"
+            document_id = match["metadata"].get("document_id")
+            lines.append(
+                f"{index}. document_id={document_id} | document={match['metadata']['filename']} | page={page_label} | distance={match['distance']:.4f}"
+            )
+            lines.append(f"   excerpt: {match['content'][:900].replace(chr(10), ' ')}")
+        return "\n\n".join(lines)
+
+    vector_tool = StructuredTool.from_function(
+        func=vector_search,
+        name="vector_search",
+        description=(
+            "Searches the current user's uploaded documents. "
+            "If file hashes are omitted, the tool first finds the most relevant document hashes from stored metadata and summary, "
+            "then applies those hashes as a vector-search filter."
+        ),
+        args_schema=VectorSearchInput,
+    )
+
+    tools = [vector_tool]
+    prompt = (
+        "You are a document QA agent. Prefer vector_search for questions about the user's uploaded documents. "
+        "Do NOT include any 'Sources' section, citation list, footnotes, chunk ids, or hashes in the final answer text. "
+        "Only provide the concise user-facing answer. "
+        "Citation metadata is handled separately by the application. "
+        "Do not claim evidence that is not present in tool outputs."
+    )
+    if web_search_tool is not None:
+        tools.append(web_search_tool)
+        prompt += " Use web search only when the answer depends on external or current information."
+    else:
+        prompt += " Web search is currently unavailable in this environment."
+
+    llm_with_tools = llm.bind_tools(tools)
+    tool_node = ToolNode(tools)
+    system_prompt = SystemMessage(content=prompt)
+
+    def agent_node(state: MessagesState):
+        response = llm_with_tools.invoke([system_prompt, *state["messages"]])
+        return {"messages": [response]}
+
+    graph = StateGraph(MessagesState)
+    graph.add_node("agent", agent_node)
+    graph.add_node("tools", tool_node)
+    graph.add_edge(START, "agent")
+    graph.add_conditional_edges("agent", _route_tools, {"tools": "tools", "__end__": END})
+    graph.add_edge("tools", "agent")
+
+    return graph.compile(checkpointer=LANGGRAPH_CHECKPOINTER)

app/services/document_service.py

@@ -0,0 +1,212 @@
+import hashlib
+
+from fastapi import UploadFile
+from langchain_groq import ChatGroq
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.config import get_settings
+from app.models import Document, DocumentChunk, User, UserDocument
+from app.services.pdf_utils import extract_pdf_pages_from_bytes, extract_pdf_text_from_bytes
+from app.services.storage_service import StorageService
+from app.services.vector_store import VectorStoreService
+
+
+class DocumentService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self.storage = StorageService()
+        self.vector_store = VectorStoreService()
+        self.summarizer = None
+
+    async def save_upload(self, upload: UploadFile) -> tuple[bytes, str]:
+        content = await upload.read()
+        file_hash = hashlib.sha256(content).hexdigest()
+        return content, file_hash
+
+    def get_or_create_document(self, *, db: Session, user: User, upload: UploadFile, content: bytes, file_hash: str) -> tuple[Document, bool, bool]:
+        existing_document = db.scalar(select(Document).where(Document.file_hash == file_hash))
+        created = False
+        processed = False
+
+        if existing_document is None:
+            file_path = self.storage.save_pdf(
+                file_hash=file_hash,
+                filename=upload.filename or "document.pdf",
+                content=content,
+            )
+            preview_text, page_count = extract_pdf_text_from_bytes(content, max_pages=10)
+            full_pages, _ = extract_pdf_pages_from_bytes(content)
+            summary = self._summarize_preview(preview_text, upload.filename or "document.pdf")
+            existing_document = Document(
+                filename=upload.filename or "document.pdf",
+                file_hash=file_hash,
+                file_path=file_path,
+                page_count=page_count,
+                summary=summary,
+                extracted_preview=preview_text[:8000],
+                processing_status="completed",
+            )
+            db.add(existing_document)
+            db.flush()
+            self.vector_store.add_document(
+                db=db,
+                document_id=existing_document.id,
+                file_hash=file_hash,
+                filename=existing_document.filename,
+                pages=full_pages,
+            )
+            created = True
+            processed = True
+        else:
+            needs_page_reindex = db.scalar(
+                select(DocumentChunk.id)
+                .where(DocumentChunk.document_id == existing_document.id, DocumentChunk.page_number.is_(None))
+                .limit(1)
+            )
+            if needs_page_reindex:
+                content_bytes = self.storage.read_file_bytes(file_path=existing_document.file_path)
+                full_pages, _ = extract_pdf_pages_from_bytes(content_bytes)
+                self.vector_store.add_document(
+                    db=db,
+                    document_id=existing_document.id,
+                    file_hash=existing_document.file_hash,
+                    filename=existing_document.filename,
+                    pages=full_pages,
+                )
+                processed = True
+
+        link = db.scalar(
+            select(UserDocument).where(
+                UserDocument.user_id == user.id,
+                UserDocument.document_id == existing_document.id,
+            )
+        )
+        if link is None:
+            db.add(UserDocument(user_id=user.id, document_id=existing_document.id))
+            db.flush()
+
+        return existing_document, created, processed
+
+    def list_user_documents(self, db: Session, user: User) -> list[Document]:
+        stmt = (
+            select(Document)
+            .join(UserDocument, UserDocument.document_id == Document.id)
+            .where(UserDocument.user_id == user.id)
+            .order_by(Document.created_at.desc())
+        )
+        return list(db.scalars(stmt))
+
+    def delete_user_document(self, db: Session, *, user: User, document_id: int) -> dict[str, str | bool]:
+        link = db.scalar(
+            select(UserDocument).where(
+                UserDocument.user_id == user.id,
+                UserDocument.document_id == document_id,
+            )
+        )
+        if link is None:
+            raise ValueError("Document not found for this user.")
+
+        document = db.get(Document, document_id)
+        if document is None:
+            raise ValueError("Document does not exist.")
+
+        db.delete(link)
+        db.flush()
+
+        remaining_links = db.scalar(select(func.count()).select_from(UserDocument).where(UserDocument.document_id == document_id)) or 0
+        deleted_shared_document = False
+
+        if remaining_links == 0:
+            db.delete(document)
+            db.flush()
+            self.storage.delete_file(file_path=document.file_path)
+            deleted_shared_document = True
+
+        return {
+            "filename": document.filename,
+            "deleted_shared_document": deleted_shared_document,
+        }
+
+    def resolve_relevant_document_hashes(self, db: Session, *, user: User, query: str, limit: int = 5) -> list[str]:
+        stopwords = {
+            "the",
+            "and",
+            "for",
+            "with",
+            "from",
+            "that",
+            "this",
+            "what",
+            "who",
+            "how",
+            "are",
+            "was",
+            "were",
+            "is",
+            "of",
+            "about",
+            "tell",
+            "more",
+            "please",
+            "can",
+            "you",
+            "your",
+        }
+        terms = [term.strip() for term in query.lower().split() if len(term.strip()) > 2 and term.strip() not in stopwords]
+        docs = self.list_user_documents(db, user)
+        scored: list[tuple[int, str]] = []
+        for doc in docs:
+            haystack = f"{doc.filename} {doc.summary} {doc.extracted_preview}".lower()
+            filename_score = sum(3 for term in terms if term in (doc.filename or "").lower())
+            body_score = sum(1 for term in terms if term in haystack)
+            score = filename_score + body_score
+            if score > 0:
+                scored.append((score, doc.file_hash))
+        scored.sort(reverse=True)
+        hashes = [file_hash for _, file_hash in scored[:limit]]
+        if hashes:
+            return hashes
+        return [doc.file_hash for doc in docs[:limit]]
+
+    def ensure_page_metadata_for_user(self, *, db: Session, user: User) -> None:
+        docs = self.list_user_documents(db, user)
+        changed = False
+        for doc in docs:
+            needs_page_reindex = db.scalar(
+                select(DocumentChunk.id)
+                .where(DocumentChunk.document_id == doc.id, DocumentChunk.page_number.is_(None))
+                .limit(1)
+            )
+            if not needs_page_reindex:
+                continue
+            try:
+                content_bytes = self.storage.read_file_bytes(file_path=doc.file_path)
+            except Exception:
+                continue
+            full_pages, _ = extract_pdf_pages_from_bytes(content_bytes)
+            self.vector_store.add_document(
+                db=db,
+                document_id=doc.id,
+                file_hash=doc.file_hash,
+                filename=doc.filename,
+                pages=full_pages,
+            )
+            changed = True
+        if changed:
+            db.commit()
+
+    def _summarize_preview(self, preview_text: str, filename: str) -> str:
+        if not preview_text.strip():
+            return f"No text could be extracted from the first pages of {filename}."
+        if not self.settings.groq_api_key:
+            return preview_text[:1200]
+        if self.summarizer is None:
+            self.summarizer = ChatGroq(api_key=self.settings.groq_api_key, model=self.settings.model_name, temperature=0)
+        prompt = (
+            "Summarize the following document preview in 6-8 concise bullet-style sentences. "
+            "Focus on purpose, key topics, and likely use cases.\n\n"
+            f"Filename: {filename}\n\nPreview:\n{preview_text[:16000]}"
+        )
+        response = self.summarizer.invoke(prompt)
+        return response.content if isinstance(response.content, str) else str(response.content)

app/services/pdf_utils.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+from io import BytesIO
+
+from pypdf import PdfReader
+
+
+def extract_pdf_pages(file_path: Path, max_pages: int | None = None) -> tuple[list[tuple[int, str]], int]:
+    reader = PdfReader(str(file_path))
+    total_pages = len(reader.pages)
+    page_limit = min(total_pages, max_pages) if max_pages else total_pages
+    pages: list[tuple[int, str]] = []
+    for index, page in enumerate(reader.pages[:page_limit], start=1):
+        pages.append((index, (page.extract_text() or "").strip()))
+    return pages, total_pages
+
+
+def extract_pdf_text(file_path: Path, max_pages: int | None = None) -> tuple[str, int]:
+    pages, total_pages = extract_pdf_pages(file_path, max_pages=max_pages)
+    text = "\n\n".join(page_text for _, page_text in pages).strip()
+    return text, total_pages
+
+
+def extract_pdf_pages_from_bytes(content: bytes, max_pages: int | None = None) -> tuple[list[tuple[int, str]], int]:
+    reader = PdfReader(BytesIO(content))
+    total_pages = len(reader.pages)
+    page_limit = min(total_pages, max_pages) if max_pages else total_pages
+    pages: list[tuple[int, str]] = []
+    for index, page in enumerate(reader.pages[:page_limit], start=1):
+        pages.append((index, (page.extract_text() or "").strip()))
+    return pages, total_pages
+
+
+def extract_pdf_text_from_bytes(content: bytes, max_pages: int | None = None) -> tuple[str, int]:
+    pages, total_pages = extract_pdf_pages_from_bytes(content, max_pages=max_pages)
+    text = "\n\n".join(page_text for _, page_text in pages).strip()
+    return text, total_pages
+
+
+def count_pdf_pages_from_bytes(content: bytes) -> int:
+    reader = PdfReader(BytesIO(content))
+    return len(reader.pages)

app/services/storage_service.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+
+from app.config import get_settings
+
+
+class StorageService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self.backend = self.settings.storage_backend.lower().strip()
+        self._client = None
+        self.settings.upload_path.mkdir(parents=True, exist_ok=True)
+
+    def save_pdf(self, *, file_hash: str, filename: str, content: bytes) -> str:
+        if self._use_supabase():
+            key = self._build_supabase_key(file_hash=file_hash, filename=filename)
+            self._supabase().storage.from_(self.settings.supabase_storage_bucket).upload(
+                path=key,
+                file=content,
+                file_options={"content-type": "application/pdf", "upsert": "true"},
+            )
+            return f"supabase://{self.settings.supabase_storage_bucket}/{key}"
+
+        suffix = Path(filename).suffix or ".pdf"
+        target = self.settings.upload_path / f"{file_hash}{suffix}"
+        if not target.exists():
+            target.write_bytes(content)
+        return str(target)
+
+    def read_file_bytes(self, *, file_path: str) -> bytes:
+        if file_path.startswith("supabase://"):
+            bucket, key = self._parse_supabase_path(file_path)
+            result = self._supabase().storage.from_(bucket).download(key)
+            if isinstance(result, bytes):
+                return result
+            return bytes(result)
+        return Path(file_path).read_bytes()
+
+    def delete_file(self, *, file_path: str) -> None:
+        if file_path.startswith("supabase://"):
+            bucket, key = self._parse_supabase_path(file_path)
+            try:
+                self._supabase().storage.from_(bucket).remove([key])
+            except Exception:
+                pass
+            return
+        local_path = Path(file_path)
+        if local_path.exists():
+            try:
+                local_path.unlink()
+            except OSError:
+                pass
+
+    def _use_supabase(self) -> bool:
+        return (
+            self.backend == "supabase"
+            and bool(self.settings.supabase_url)
+            and bool(self.settings.supabase_service_role_key)
+        )
+
+    def _supabase(self):
+        if self._client is None:
+            from supabase import create_client
+
+            self._client = create_client(self.settings.supabase_url, self.settings.supabase_service_role_key)
+        return self._client
+
+    def _build_supabase_key(self, *, file_hash: str, filename: str) -> str:
+        suffix = Path(filename).suffix or ".pdf"
+        base_prefix = self.settings.supabase_storage_prefix.strip("/ ")
+        if base_prefix:
+            return f"{base_prefix}/{file_hash}{suffix}"
+        return f"{file_hash}{suffix}"
+
+    def _parse_supabase_path(self, file_path: str) -> tuple[str, str]:
+        without_scheme = file_path.removeprefix("supabase://")
+        parts = without_scheme.split("/", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid supabase path: {file_path}")
+        return parts[0], parts[1]

app/services/vector_store.py

@@ -0,0 +1,151 @@
+import hashlib
+import math
+import re
+from typing import Any
+
+from sqlalchemy import delete, select
+from sqlalchemy.orm import Session
+
+from app.config import get_settings
+from app.models import DocumentChunk
+
+
+class SimpleTextSplitter:
+    def __init__(self, *, chunk_size: int, chunk_overlap: int) -> None:
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+
+    def split_text(self, text: str) -> list[str]:
+        normalized = text.strip()
+        if not normalized:
+            return []
+        if len(normalized) <= self.chunk_size:
+            return [normalized]
+
+        chunks: list[str] = []
+        start = 0
+        step = max(1, self.chunk_size - self.chunk_overlap)
+        text_length = len(normalized)
+        while start < text_length:
+            end = min(text_length, start + self.chunk_size)
+            chunk = normalized[start:end].strip()
+            if chunk:
+                chunks.append(chunk)
+            if end >= text_length:
+                break
+            start += step
+        return chunks
+
+
+class LocalHashEmbeddings:
+    def __init__(self, dimensions: int) -> None:
+        self.dimensions = dimensions
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        return [self._embed_text(text) for text in texts]
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._embed_text(text)
+
+    def _embed_text(self, text: str) -> list[float]:
+        vector = [0.0] * self.dimensions
+        tokens = re.findall(r"\w+", text.lower())
+        if not tokens:
+            return vector
+
+        for token in tokens:
+            digest = hashlib.sha256(token.encode("utf-8")).digest()
+            bucket = int.from_bytes(digest[:4], "big") % self.dimensions
+            sign = 1.0 if digest[4] % 2 == 0 else -1.0
+            vector[bucket] += sign
+
+        norm = math.sqrt(sum(value * value for value in vector))
+        if norm == 0:
+            return vector
+        return [value / norm for value in vector]
+
+
+class VectorStoreService:
+    def __init__(self) -> None:
+        self.splitter = SimpleTextSplitter(chunk_size=1200, chunk_overlap=200)
+        self.embeddings = None
+
+    def _get_embeddings(self) -> Any:
+        settings = get_settings()
+        if self.embeddings is None:
+            try:
+                from langchain_huggingface import HuggingFaceEmbeddings
+
+                self.embeddings = HuggingFaceEmbeddings(
+                    model_name=settings.embedding_model,
+                    model_kwargs={"device": "cpu"},
+                    encode_kwargs={"normalize_embeddings": True},
+                )
+            except Exception:
+                # Keep the app usable when transformer/torch dependencies are unavailable.
+                self.embeddings = LocalHashEmbeddings(settings.embedding_dimensions)
+        return self.embeddings
+
+    def add_document(self, *, db: Session, document_id: int, file_hash: str, filename: str, pages: list[tuple[int, str]]) -> None:
+        chunk_rows: list[tuple[int | None, str]] = []
+        for page_number, page_text in pages:
+            if not page_text.strip():
+                continue
+            page_chunks = self.splitter.split_text(page_text)
+            chunk_rows.extend((page_number, chunk) for chunk in page_chunks if chunk.strip())
+        chunks = [chunk for _, chunk in chunk_rows]
+        if not chunks:
+            return
+        embeddings_client = self._get_embeddings()
+        embeddings = embeddings_client.embed_documents(chunks)
+        db.execute(delete(DocumentChunk).where(DocumentChunk.document_id == document_id))
+        rows = [
+            DocumentChunk(
+                document_id=document_id,
+                file_hash=file_hash,
+                filename=filename,
+                chunk_index=index,
+                page_number=page_number,
+                content=chunk,
+                embedding=embedding,
+            )
+            for index, ((page_number, chunk), embedding) in enumerate(zip(chunk_rows, embeddings, strict=False))
+        ]
+        db.add_all(rows)
+        db.flush()
+
+    def similarity_search(self, *, db: Session, query: str, file_hashes: list[str], k: int = 4) -> list[dict[str, Any]]:
+        if not file_hashes:
+            return []
+        query_embedding = self._get_embeddings().embed_query(query)
+        stmt = (
+            select(
+                DocumentChunk.document_id,
+                DocumentChunk.content,
+                DocumentChunk.filename,
+                DocumentChunk.file_hash,
+                DocumentChunk.chunk_index,
+                DocumentChunk.page_number,
+                DocumentChunk.embedding.cosine_distance(query_embedding).label("distance"),
+            )
+            .where(DocumentChunk.file_hash.in_(file_hashes))
+            .order_by(DocumentChunk.embedding.cosine_distance(query_embedding))
+            .limit(k)
+        )
+        results = db.execute(stmt).all()
+        matches: list[dict[str, Any]] = []
+        for row in results:
+            matches.append(
+                {
+                    "content": row.content,
+                    "metadata": {
+                        "document_id": row.document_id,
+                        "filename": row.filename,
+                        "file_hash": row.file_hash,
+                        "chunk_index": row.chunk_index,
+                        "page_number": row.page_number,
+                    },
+                    "distance": row.distance,
+                }
+            )
+        return matches

app/services/web_search.py

@@ -0,0 +1,72 @@
+import json
+
+from langchain_community.tools import DuckDuckGoSearchResults
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.config import get_settings
+
+
+class WebSearchInput(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    query: str = Field(default="", description="Search query for external/current information.")
+    cursor: int | None = Field(default=None, description="Optional cursor from model/tool planning. Ignored.")
+    id: str | int | None = Field(default=None, description="Optional id from model/tool planning. Ignored.")
+
+
+def _build_tavily_tool(api_key: str):
+    try:
+        from tavily import TavilyClient
+    except Exception:
+        return None
+
+    client = TavilyClient(api_key=api_key)
+
+    def tavily_search(query: str = "", cursor: int | None = None, id: str | int | None = None, **kwargs) -> str:
+        query_text = query.strip()
+        _ = (cursor, id, kwargs)
+        if not query_text:
+            return "Web search was requested without a query."
+        try:
+            result = client.search(query=query_text, search_depth="advanced")
+        except Exception as exc:
+            return f"Tavily search failed: {exc}"
+        rows = result.get("results", []) if isinstance(result, dict) else []
+        if not rows:
+            return "No web results found."
+
+        lines = ["Web search results (cite website URLs used):"]
+        for index, row in enumerate(rows[:5], start=1):
+            title = str(row.get("title") or "Untitled result")
+            url = str(row.get("url") or "").strip()
+            snippet = str(row.get("content") or "").strip().replace("\n", " ")
+            snippet = snippet[:500]
+            lines.append(f"{index}. title: {title}")
+            lines.append(f"   url: {url or 'N/A'}")
+            if snippet:
+                lines.append(f"   snippet: {snippet}")
+        lines.append("\nRaw response:")
+        lines.append(json.dumps(result, ensure_ascii=True))
+        return "\n".join(lines)
+
+    return StructuredTool.from_function(
+        func=tavily_search,
+        name="web_search",
+        description="Search the web for current/external information using Tavily.",
+        args_schema=WebSearchInput,
+    )
+
+
+def build_web_search_tool():
+    settings = get_settings()
+    provider = settings.web_search_provider.lower()
+
+    if provider == "tavily":
+        if not settings.tavily_api_key:
+            return None
+        return _build_tavily_tool(settings.tavily_api_key)
+
+    try:
+        return DuckDuckGoSearchResults(num_results=5)
+    except Exception:
+        return None

app/static/style.css

@@ -0,0 +1,680 @@
+:root {
+  --bg-1: #fff7eb;
+  --bg-2: #f8e7cf;
+  --ink-1: #1f1b16;
+  --ink-2: #554b40;
+  --card: rgba(255, 252, 247, 0.84);
+  --card-strong: rgba(255, 252, 247, 0.95);
+  --line: rgba(100, 77, 45, 0.18);
+  --line-strong: rgba(100, 77, 45, 0.34);
+  --brand-1: #b24a00;
+  --brand-2: #ff7b00;
+  --brand-3: #ffd8a8;
+  --ok-bg: #f0fdf4;
+  --ok-line: #86efac;
+  --error-bg: #fef2f2;
+  --error-line: #fca5a5;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  color: var(--ink-1);
+  font-family: "Space Grotesk", "Helvetica Neue", sans-serif;
+  background:
+    linear-gradient(180deg, var(--bg-1), var(--bg-2)),
+    radial-gradient(circle at 10% 10%, rgba(255, 179, 71, 0.32), transparent 45%);
+  position: relative;
+}
+
+.bg-orb {
+  position: fixed;
+  border-radius: 999px;
+  filter: blur(70px);
+  pointer-events: none;
+  z-index: 0;
+  opacity: 0.65;
+}
+
+.orb-one {
+  width: 420px;
+  height: 420px;
+  left: -100px;
+  top: -110px;
+  background: rgba(255, 133, 28, 0.42);
+}
+
+.orb-two {
+  width: 360px;
+  height: 360px;
+  right: -100px;
+  top: 220px;
+  background: rgba(255, 208, 143, 0.6);
+}
+
+.shell {
+  position: relative;
+  z-index: 1;
+  width: min(1460px, calc(100% - 2.5rem));
+  margin: 0 auto;
+  padding: 1.6rem 0 3.4rem;
+}
+
+.hero {
+  margin-bottom: 1rem;
+}
+
+.workspace-strip {
+  margin-bottom: 0.95rem;
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 1rem;
+}
+
+.workspace-strip h1 {
+  font-size: clamp(1.65rem, 3.5vw, 2.2rem);
+  margin-top: 0.35rem;
+}
+
+.hero-topline {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.eyebrow {
+  margin: 0;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.72rem;
+  color: var(--brand-1);
+  font-weight: 700;
+}
+
+h1,
+h2,
+h3 {
+  margin: 0;
+  letter-spacing: -0.02em;
+}
+
+h1 {
+  font-size: clamp(1.8rem, 4vw, 2.7rem);
+  margin-top: 0.65rem;
+}
+
+h2 {
+  font-size: 1.25rem;
+}
+
+h3 {
+  font-size: 1rem;
+}
+
+.lede,
+p,
+label,
+textarea,
+input,
+button {
+  font-size: 0.98rem;
+  line-height: 1.5;
+}
+
+.lede {
+  margin-top: 0.75rem;
+  color: var(--ink-2);
+  max-width: 72ch;
+}
+
+.db-warning {
+  margin-top: 0.75rem;
+  border: 1px solid var(--error-line);
+  background: var(--error-bg);
+  color: #991b1b;
+  border-radius: 10px;
+  padding: 0.55rem 0.7rem;
+}
+
+.muted {
+  color: var(--ink-2);
+  margin: 0.35rem 0 0;
+}
+
+.grid {
+  display: grid;
+  gap: 1rem;
+}
+
+.grid.two {
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+}
+
+.card {
+  border: 1px solid var(--line);
+  border-radius: 20px;
+  background: var(--card);
+  backdrop-filter: blur(10px);
+  box-shadow:
+    0 8px 22px rgba(70, 50, 20, 0.08),
+    0 28px 60px rgba(70, 50, 20, 0.07);
+  padding: 1.45rem;
+  animation: fade-up 0.4s ease both;
+}
+
+.panel {
+  display: grid;
+  gap: 0.9rem;
+}
+
+.panel-head p {
+  margin: 0.25rem 0 0;
+  color: var(--ink-2);
+}
+
+.panel-head-inline {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 0.8rem;
+}
+
+.badge {
+  border: 1px solid rgba(178, 74, 0, 0.22);
+  background: linear-gradient(135deg, rgba(255, 187, 107, 0.24), rgba(255, 123, 0, 0.12));
+  color: #8d3600;
+  padding: 0.3rem 0.7rem;
+  border-radius: 999px;
+  font-size: 0.78rem;
+  white-space: nowrap;
+}
+
+.toolbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+  margin-bottom: 1rem;
+}
+
+.app-layout {
+  display: grid;
+  grid-template-columns: minmax(360px, 430px) 1fr;
+  gap: 1.2rem;
+  align-items: start;
+}
+
+.sidebar-panel {
+  position: sticky;
+  top: 1rem;
+  max-height: calc(100vh - 2rem);
+  overflow: auto;
+  gap: 1rem;
+  padding: 1.55rem;
+}
+
+.sidebar-docs {
+  max-height: 52vh;
+  overflow: auto;
+  padding-right: 0.25rem;
+}
+
+.user-email {
+  overflow-wrap: anywhere;
+}
+
+label,
+input,
+textarea,
+button {
+  display: block;
+  width: 100%;
+}
+
+label {
+  color: #453d34;
+  font-weight: 500;
+}
+
+input,
+textarea {
+  margin-top: 0.38rem;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--card-strong);
+  padding: 0.75rem 0.85rem;
+  color: var(--ink-1);
+  transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+input:focus,
+textarea:focus {
+  outline: none;
+  border-color: var(--brand-2);
+  box-shadow: 0 0 0 3px rgba(255, 123, 0, 0.2);
+}
+
+textarea {
+  min-height: 146px;
+  resize: vertical;
+}
+
+button {
+  border: none;
+  border-radius: 12px;
+  padding: 0.8rem 1rem;
+  color: #fff;
+  cursor: pointer;
+  font-weight: 700;
+  background: linear-gradient(135deg, var(--brand-1), var(--brand-2));
+  transition: transform 0.12s ease, filter 0.2s ease;
+}
+
+button:hover {
+  filter: brightness(1.06);
+}
+
+button:active {
+  transform: translateY(1px);
+}
+
+button:disabled {
+  opacity: 0.76;
+  cursor: wait;
+}
+
+button.secondary {
+  background: linear-gradient(135deg, #2f2f2f, #151515);
+}
+
+button.danger {
+  background: linear-gradient(135deg, #b42318, #e11d48);
+}
+
+.result {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  border-radius: 12px;
+  border: 1px solid var(--ok-line);
+  background: var(--ok-bg);
+  color: #0f5132;
+  font-family: "IBM Plex Mono", monospace;
+  font-size: 0.85rem;
+  padding: 0.8rem;
+  min-height: 76px;
+}
+
+.hidden {
+  display: none;
+}
+
+.result:empty {
+  display: none;
+}
+
+.result.error {
+  background: var(--error-bg);
+  border-color: var(--error-line);
+  color: #991b1b;
+}
+
+.docs {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.chat-shell {
+  gap: 0.75rem;
+}
+
+.chat-panel {
+  min-height: 78vh;
+  padding: 1.55rem;
+}
+
+.chat-thread {
+  border: 1px solid var(--line);
+  background: rgba(255, 250, 243, 0.7);
+  border-radius: 14px;
+  padding: 0.9rem;
+  min-height: 56vh;
+  max-height: 68vh;
+  overflow-y: auto;
+  display: grid;
+  gap: 0.65rem;
+  align-content: start;
+  grid-auto-rows: max-content;
+}
+
+.chat-msg {
+  display: flex;
+}
+
+.chat-msg.user {
+  justify-content: flex-end;
+}
+
+.chat-msg.assistant {
+  justify-content: flex-start;
+}
+
+.chat-bubble {
+  border-radius: 14px;
+  padding: 0.6rem 0.75rem;
+  max-width: min(92%, 900px);
+  overflow-wrap: anywhere;
+  border: 1px solid var(--line);
+}
+
+.chat-bubble-user {
+  background: linear-gradient(135deg, var(--brand-1), var(--brand-2));
+  color: #fff;
+  border-color: transparent;
+}
+
+.chat-bubble-assistant {
+  background: var(--card-strong);
+  color: var(--ink-1);
+}
+
+.chat-pending {
+  opacity: 0.8;
+  font-style: italic;
+}
+
+.chat-error {
+  border-color: var(--error-line);
+  background: var(--error-bg);
+  color: #991b1b;
+}
+
+.chat-composer {
+  display: grid;
+  gap: 0.6rem;
+  padding-top: 0.35rem;
+  border-top: 1px solid var(--line);
+  background: linear-gradient(180deg, rgba(255, 252, 247, 0), rgba(255, 252, 247, 0.92) 35%);
+}
+
+.chat-composer textarea {
+  min-height: 118px;
+  font-size: 1rem;
+}
+
+.chat-markdown p,
+.chat-markdown ul,
+.chat-markdown ol {
+  margin: 0.3rem 0;
+}
+
+.chat-markdown p:first-child {
+  margin-top: 0;
+}
+
+.chat-markdown p:last-child {
+  margin-bottom: 0;
+}
+
+.chat-markdown pre,
+.chat-markdown code {
+  font-family: "IBM Plex Mono", monospace;
+}
+
+.chat-markdown pre {
+  background: #f6ead8;
+  border: 1px solid #e8ccb0;
+  border-radius: 10px;
+  padding: 0.65rem;
+  overflow-x: auto;
+}
+
+.chat-markdown table {
+  border-collapse: collapse;
+  width: 100%;
+  display: block;
+  overflow-x: auto;
+  margin: 0.5rem 0;
+}
+
+.chat-markdown th,
+.chat-markdown td {
+  border: 1px solid var(--line-strong);
+  padding: 0.5rem;
+  text-align: left;
+  vertical-align: top;
+  min-width: 120px;
+}
+
+.message-panel {
+  margin-top: 0.1rem;
+  min-height: auto;
+}
+
+.source-dropdown {
+  margin-top: 0.5rem;
+  border-top: 1px solid var(--line);
+  padding-top: 0.45rem;
+}
+
+.source-dropdown summary {
+  cursor: pointer;
+  font-weight: 700;
+  color: #6d3d13;
+  list-style: none;
+}
+
+.source-dropdown summary::-webkit-details-marker {
+  display: none;
+}
+
+.source-dropdown summary::before {
+  content: "▸";
+  display: inline-block;
+  margin-right: 0.35rem;
+  transition: transform 0.15s ease;
+}
+
+.source-dropdown[open] summary::before {
+  transform: rotate(90deg);
+}
+
+.chat-bubble .panel,
+.chat-bubble .card,
+.chat-bubble .result {
+  min-height: 0;
+}
+
+.sources-panel {
+  display: grid;
+  gap: 0.7rem;
+  margin-top: 0.55rem;
+}
+
+.sources-panel h4 {
+  margin: 0.2rem 0 0.45rem;
+  font-size: 0.9rem;
+  color: #6d3d13;
+}
+
+.source-list {
+  display: grid;
+  gap: 0.55rem;
+}
+
+.source-card {
+  border: 1px solid var(--line);
+  background: #fff8ef;
+  border-radius: 10px;
+  padding: 0.65rem;
+}
+
+.source-meta {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 0.6rem;
+  margin-bottom: 0.35rem;
+}
+
+.source-doc {
+  font-weight: 700;
+  font-size: 0.86rem;
+}
+
+.source-page {
+  font-size: 0.78rem;
+  color: #6d3d13;
+}
+
+.source-excerpt {
+  margin: 0;
+  font-size: 0.9rem;
+  line-height: 1.48;
+}
+
+.source-excerpt mark {
+  background: #ffe29d;
+  color: #402100;
+  border-radius: 3px;
+  padding: 0 2px;
+}
+
+.source-actions {
+  margin-top: 0.5rem;
+}
+
+.source-link {
+  display: inline-block;
+  text-decoration: none;
+  font-size: 0.82rem;
+  font-weight: 700;
+  padding: 0.35rem 0.58rem;
+  border: 1px solid #ddbb97;
+  border-radius: 8px;
+  color: #6d3d13;
+  background: #fdf2e4;
+}
+
+.source-web-list {
+  margin: 0;
+  padding-left: 1.1rem;
+}
+
+.doc {
+  display: grid;
+  border: 1px solid var(--line);
+  border-radius: 14px;
+  padding: 1.1rem;
+  background: var(--card-strong);
+  gap: 0.75rem;
+}
+
+.doc-actions {
+  margin-top: 0.75rem;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.doc-actions button {
+  width: 100%;
+  padding: 0.55rem 0.9rem;
+  font-size: 0.82rem;
+}
+
+.doc-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 0.8rem;
+}
+
+.doc-pages {
+  color: #684b29;
+  font-size: 0.8rem;
+  padding: 0.2rem 0.55rem;
+  border-radius: 999px;
+  border: 1px solid rgba(178, 74, 0, 0.24);
+  background: rgba(255, 206, 140, 0.3);
+}
+
+.hash {
+  margin: 0.55rem 0 0.3rem;
+  color: #5d5247;
+}
+
+code {
+  font-family: "IBM Plex Mono", monospace;
+  font-size: 0.76rem;
+}
+
+.summary {
+  margin: 0;
+  color: #2d251d;
+}
+
+@keyframes fade-up {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (max-width: 720px) {
+  .shell {
+    width: min(1120px, calc(100% - 1rem));
+    padding-top: 0.95rem;
+  }
+
+  .toolbar {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .hero-topline,
+  .panel-head-inline,
+  .doc-head {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .app-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .workspace-strip {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .sidebar-panel {
+    position: static;
+    max-height: none;
+  }
+
+  .sidebar-docs {
+    max-height: none;
+  }
+
+  .chat-panel {
+    min-height: 68vh;
+  }
+
+  .chat-thread {
+    min-height: 46vh;
+    max-height: 56vh;
+  }
+}

app/templates/index.html

@@ -0,0 +1,577 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>DocsQA Assignment</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+    <link rel="stylesheet" href="/static/style.css" />
+  </head>
+  <body>
+    <div class="bg-orb orb-one"></div>
+    <div class="bg-orb orb-two"></div>
+    <main class="shell">
+      {% if not user %}
+      <section class="hero card">
+        <div class="hero-topline">
+          <p class="eyebrow">LangGraph Assignment</p>
+          <span class="badge">FastAPI + Supabase + PGVector</span>
+        </div>
+        <h1>DocsQA Workspace</h1>
+        <p class="lede">
+          Upload PDFs, avoid duplicate reprocessing by file hash, and ask an agent that uses user-scoped document retrieval with optional web search.
+        </p>
+        {% if db_unavailable %}
+        <p class="db-warning">
+          Database connection is temporarily unavailable. This is usually a transient DNS/network issue with the Supabase host. Please retry shortly.
+        </p>
+        {% endif %}
+      </section>
+      {% else %}
+      <section class="workspace-strip card">
+        <div>
+          <p class="eyebrow">LangGraph Assignment</p>
+          <h1>DocsQA Workspace</h1>
+          <p class="muted">Private document chat with structured sources.</p>
+        </div>
+        <span class="badge">FastAPI + Supabase + PGVector</span>
+      </section>
+      {% endif %}
+
+      {% if not user %}
+      <section class="grid two auth-grid">
+        <form class="card panel" id="register-form" method="post" action="/register">
+          <div class="panel-head">
+            <h2>Create account</h2>
+            <p>Start by creating your personal docs workspace.</p>
+          </div>
+          <label>Email <input type="email" name="email" required /></label>
+          <label>Password <input type="password" name="password" required /></label>
+          <button type="submit">Register</button>
+          <pre class="result ok" id="register-result"></pre>
+        </form>
+
+        <form class="card panel" id="login-form" method="post" action="/login">
+          <div class="panel-head">
+            <h2>Sign in</h2>
+            <p>Continue with your existing account.</p>
+          </div>
+          <label>Email <input type="email" name="email" required /></label>
+          <label>Password <input type="password" name="password" required /></label>
+          <button type="submit">Login</button>
+          <pre class="result ok" id="login-result"></pre>
+        </form>
+      </section>
+      {% else %}
+      <section class="app-layout">
+        <aside class="card panel sidebar-panel">
+          <div class="panel-head">
+            <h2 class="user-email">{{ user.email }}</h2>
+            <p class="muted">Your uploaded docs are private to this account.</p>
+          </div>
+
+          <form id="upload-form" class="panel">
+            <label class="muted">Upload PDFs (max 5 files, 10 pages each)</label>
+            <input type="file" id="file" name="file" accept="application/pdf" multiple required />
+            <button type="submit">Upload</button>
+          </form>
+          <pre class="result" id="upload-result"></pre>
+
+          <div class="panel-head panel-head-inline">
+            <h3>Your documents</h3>
+            <span class="badge">{{ documents|length }}</span>
+          </div>
+          <div class="docs sidebar-docs">
+            {% for document in documents %}
+            <article class="doc">
+              <header class="doc-head">
+                <h3>{{ document.filename }}</h3>
+                <span class="doc-pages">{{ document.page_count }} pages</span>
+              </header>
+              <div class="doc-actions">
+                <button
+                  type="button"
+                  class="danger doc-delete-btn"
+                  data-document-id="{{ document.id }}"
+                  data-document-name="{{ document.filename }}"
+                >
+                  Delete
+                </button>
+              </div>
+            </article>
+            {% else %}
+            <p class="muted">No documents uploaded yet.</p>
+            {% endfor %}
+          </div>
+
+          <form method="post" action="/logout" id="logout-form">
+            <button type="submit" class="secondary">Sign out</button>
+          </form>
+        </aside>
+
+        <section class="card panel chat-shell chat-panel">
+          <div class="panel-head panel-head-inline">
+            <h2>DocsQA Chat</h2>
+            <span class="badge">Markdown enabled</span>
+          </div>
+          <div id="chat-thread" class="chat-thread">
+            <article class="chat-msg assistant">
+              <div class="chat-bubble chat-bubble-assistant chat-markdown">
+                <p>Ask anything about your uploaded PDFs and I will answer with citations from retrieved chunks.</p>
+              </div>
+            </article>
+          </div>
+          <form id="ask-form" class="chat-composer">
+            <textarea
+              id="query"
+              rows="3"
+              placeholder="Message DocsQA..."
+              required
+            ></textarea>
+            <button type="submit">Send</button>
+          </form>
+        </section>
+      </section>
+      {% endif %}
+    </main>
+
+    <script>
+      const registerForm = document.getElementById("register-form");
+      const loginForm = document.getElementById("login-form");
+      const logoutForm = document.getElementById("logout-form");
+      const registerResult = document.getElementById("register-result");
+      const loginResult = document.getElementById("login-result");
+      const uploadForm = document.getElementById("upload-form");
+      const askForm = document.getElementById("ask-form");
+      const uploadResult = document.getElementById("upload-result");
+      const chatThread = document.getElementById("chat-thread");
+      const queryInput = document.getElementById("query");
+      const docDeleteButtons = document.querySelectorAll(".doc-delete-btn");
+
+      const safeJson = async (response) => {
+        try {
+          return await response.json();
+        } catch {
+          return { detail: "Unexpected non-JSON response" };
+        }
+      };
+
+      const prettyError = (body) => {
+        if (!body) return "Request failed.";
+        if (typeof body.detail === "string") return body.detail;
+        if (typeof body.message === "string") return body.message;
+        return "Request failed.";
+      };
+
+      const setBusy = (form, busy) => {
+        if (!form) return;
+        const button = form.querySelector("button[type='submit']");
+        if (!button) return;
+        button.disabled = busy;
+        if (busy) {
+          button.dataset.originalText = button.textContent;
+          button.textContent = "Please wait...";
+        } else if (button.dataset.originalText) {
+          button.textContent = button.dataset.originalText;
+        }
+      };
+
+      const escapeHtml = (value) =>
+        value
+          .replaceAll("&", "&amp;")
+          .replaceAll("<", "&lt;")
+          .replaceAll(">", "&gt;");
+
+      const normalizeTabularAnswer = (text) => {
+        const lines = text.split("\n");
+        const out = [];
+        let i = 0;
+
+        while (i < lines.length) {
+          const line = lines[i];
+          if (!line.includes("\t")) {
+            out.push(line);
+            i += 1;
+            continue;
+          }
+
+          const rows = [];
+          while (i < lines.length && lines[i].includes("\t")) {
+            rows.push(lines[i].split("\t").map((cell) => cell.trim()));
+            i += 1;
+          }
+
+          if (rows.length < 2) {
+            out.push(...rows.map((row) => row.join(" ")));
+            continue;
+          }
+
+          const columnCount = Math.max(...rows.map((row) => row.length));
+          const paddedRows = rows.map((row) => {
+            const copy = [...row];
+            while (copy.length < columnCount) copy.push("");
+            return copy.map((cell) => cell.replaceAll("|", "\\|").replaceAll("\n", "<br>"));
+          });
+
+          out.push(`| ${paddedRows[0].join(" | ")} |`);
+          out.push(`| ${Array(columnCount).fill("---").join(" | ")} |`);
+          for (const row of paddedRows.slice(1)) {
+            out.push(`| ${row.join(" | ")} |`);
+          }
+        }
+
+        return out.join("\n");
+      };
+
+      const sanitizeHtml = (html) => {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, "text/html");
+        doc.querySelectorAll("script,style,iframe,object,embed").forEach((node) => node.remove());
+        for (const el of doc.querySelectorAll("*")) {
+          for (const attr of [...el.attributes]) {
+            const name = attr.name.toLowerCase();
+            const value = attr.value.toLowerCase();
+            if (name.startsWith("on")) {
+              el.removeAttribute(attr.name);
+            }
+            if ((name === "href" || name === "src") && value.startsWith("javascript:")) {
+              el.removeAttribute(attr.name);
+            }
+          }
+        }
+        return doc.body.innerHTML;
+      };
+
+      const renderMarkdown = (text) => {
+        const normalized = normalizeTabularAnswer(text || "");
+        if (window.marked?.parse) {
+          const html = window.marked.parse(normalized, { gfm: true, breaks: true });
+          return sanitizeHtml(html);
+        }
+        return `<pre>${escapeHtml(normalized)}</pre>`;
+      };
+
+      const stripSourceStatusLines = (text) => {
+        if (!text) return "";
+        const withoutSourcesSection = text.replace(/\n+\s*(?:#+\s*)?sources\s*:?\s*\n[\s\S]*$/i, "").trim();
+        return withoutSourcesSection
+          .split("\n")
+          .filter((line) => !/^\s*no sources were used for this response\.?\s*$/i.test(line.trim()))
+          .filter((line) => !/^\s*no citations available for this turn\.?\s*$/i.test(line.trim()))
+          .join("\n")
+          .trim();
+      };
+
+      const buildSourcesMarkdown = (sources) => {
+        const vectorSources = Array.isArray(sources?.vector) ? sources.vector : [];
+        const webSources = Array.isArray(sources?.web) ? sources.web : [];
+        const lines = [];
+
+        if (vectorSources.length) {
+          lines.push("### Document Sources");
+          for (const src of vectorSources) {
+            const doc = src.document || "Unknown document";
+            const page = src.page || "unknown";
+            const excerpt = src.excerpt || "";
+            lines.push(`- **${doc}**, page **${page}**`);
+            if (excerpt) {
+              lines.push(`  - "${excerpt}"`);
+            }
+          }
+        }
+
+        if (webSources.length) {
+          if (lines.length) lines.push("");
+          lines.push("### Web Sources");
+          for (const src of webSources) {
+            const title = src.title || "Untitled source";
+            const url = src.url || "";
+            if (url && url !== "N/A") {
+              lines.push(`- [${title}](${url})`);
+            } else {
+              lines.push(`- ${title}`);
+            }
+          }
+        }
+
+        if (lines.length) return lines.join("\n");
+        return "_No citations available for this turn._";
+      };
+
+      const sourceStopwords = new Set([
+        "the", "and", "for", "with", "from", "that", "this", "what", "who", "how", "are", "was", "were", "is",
+        "of", "about", "tell", "more", "please", "can", "you", "your", "according", "resume"
+      ]);
+
+      const extractQueryTerms = (queryText) => {
+        const raw = (queryText || "").toLowerCase().match(/[a-z0-9_]+/g) || [];
+        const deduped = [];
+        const seen = new Set();
+        for (const term of raw) {
+          if (term.length < 3 || sourceStopwords.has(term) || seen.has(term)) continue;
+          seen.add(term);
+          deduped.push(term);
+        }
+        return deduped;
+      };
+
+      const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+      const highlightMatches = (text, terms) => {
+        const plain = text || "";
+        if (!terms.length) return escapeHtml(plain);
+        const pattern = new RegExp(`\\b(${terms.map(escapeRegex).join("|")})\\b`, "gi");
+        return escapeHtml(plain).replace(pattern, "<mark>$1</mark>");
+      };
+
+      const renderSourcesHtml = (sources, queryText = "") => {
+        const vectorSources = Array.isArray(sources?.vector) ? sources.vector : [];
+        const webSources = Array.isArray(sources?.web) ? sources.web : [];
+        const terms = extractQueryTerms(queryText);
+
+        const sections = [];
+
+        if (vectorSources.length) {
+          const vectorCards = vectorSources
+            .map((src) => {
+              const documentId = (src.document_id || "").toString().trim();
+              const doc = escapeHtml(src.document || "Unknown document");
+              const page = escapeHtml(src.page || "unknown");
+              const excerptHtml = highlightMatches(src.excerpt || "", terms);
+              const pageNumber = Number.parseInt(src.page || "", 10);
+              const pageAnchor = Number.isFinite(pageNumber) && pageNumber > 0 ? `#page=${pageNumber}` : "";
+              const pdfUrl = documentId ? `/documents/${encodeURIComponent(documentId)}/pdf${pageAnchor}` : "";
+              return `
+                <article class="source-card">
+                  <div class="source-meta">
+                    <span class="source-doc">${doc}</span>
+                    <span class="source-page">Page ${page}</span>
+                  </div>
+                  <p class="source-excerpt">${excerptHtml || "No excerpt available."}</p>
+                  ${
+                    pdfUrl
+                      ? `<div class="source-actions"><a class="source-link" href="${pdfUrl}" target="_blank" rel="noopener noreferrer">Open PDF</a></div>`
+                      : ""
+                  }
+                </article>
+              `;
+            })
+            .join("");
+          sections.push(`<section><h4>Document Sources</h4><div class="source-list">${vectorCards}</div></section>`);
+        }
+
+        if (webSources.length) {
+          const webItems = webSources
+            .map((src) => {
+              const title = escapeHtml(src.title || "Untitled source");
+              const url = src.url || "";
+              if (url && url !== "N/A") {
+                return `<li><a href="${escapeHtml(url)}" target="_blank" rel="noopener noreferrer">${title}</a></li>`;
+              }
+              return `<li>${title}</li>`;
+            })
+            .join("");
+          sections.push(`<section><h4>Web Sources</h4><ul class="source-web-list">${webItems}</ul></section>`);
+        }
+
+        if (!sections.length) {
+          return `<p class="muted">No citations available for this turn.</p>`;
+        }
+        return sections.join("");
+      };
+
+      const renderAssistantResponse = (container, fullAnswerText, sourceDict = null, queryText = "") => {
+        if (!container) return;
+        const answerContent = stripSourceStatusLines(fullAnswerText) || "Response received.";
+        const sourcesContent = renderSourcesHtml(sourceDict, queryText);
+
+        container.innerHTML = "";
+
+        const answerPanel = document.createElement("div");
+        answerPanel.className = "message-panel";
+        answerPanel.innerHTML = renderMarkdown(answerContent);
+
+        container.appendChild(answerPanel);
+
+        const details = document.createElement("details");
+        details.className = "source-dropdown";
+        const summary = document.createElement("summary");
+        summary.textContent = "Sources";
+        const body = document.createElement("div");
+        body.className = "sources-panel";
+        body.innerHTML = sourcesContent;
+        details.appendChild(summary);
+        details.appendChild(body);
+        container.appendChild(details);
+      };
+
+      const appendMessage = ({ role, text, markdown = false, pending = false, isError = false }) => {
+        if (!chatThread) return null;
+        const row = document.createElement("article");
+        row.className = `chat-msg ${role}`;
+
+        const bubble = document.createElement("div");
+        bubble.className = `chat-bubble ${role === "user" ? "chat-bubble-user" : "chat-bubble-assistant"}`;
+        if (markdown) bubble.classList.add("chat-markdown");
+        if (pending) bubble.classList.add("chat-pending");
+        if (isError) bubble.classList.add("chat-error");
+
+        if (markdown) {
+          bubble.innerHTML = renderMarkdown(text);
+        } else {
+          bubble.textContent = text;
+        }
+
+        row.appendChild(bubble);
+        chatThread.appendChild(row);
+        chatThread.scrollTop = chatThread.scrollHeight;
+        return bubble;
+      };
+
+      registerForm?.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        setBusy(registerForm, true);
+        const formData = new FormData(registerForm);
+        const response = await fetch("/register", { method: "POST", body: formData });
+        const body = await safeJson(response);
+        registerResult.textContent = response.ok
+          ? "Registration successful. Redirecting to your workspace..."
+          : prettyError(body);
+        registerResult.classList.toggle("error", !response.ok);
+        setBusy(registerForm, false);
+        if (response.ok) {
+          window.location.reload();
+        }
+      });
+
+      loginForm?.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        setBusy(loginForm, true);
+        const formData = new FormData(loginForm);
+        const response = await fetch("/login", { method: "POST", body: formData });
+        const body = await safeJson(response);
+        loginResult.textContent = response.ok
+          ? "Login successful. Redirecting..."
+          : prettyError(body);
+        loginResult.classList.toggle("error", !response.ok);
+        setBusy(loginForm, false);
+        if (response.ok) {
+          window.location.reload();
+        }
+      });
+
+      logoutForm?.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        const response = await fetch("/logout", { method: "POST" });
+        if (response.ok) {
+          window.location.reload();
+        }
+      });
+
+      uploadForm?.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        setBusy(uploadForm, true);
+        const formData = new FormData();
+        const fileInput = document.getElementById("file");
+        const files = Array.from(fileInput?.files || []);
+        if (!files.length) {
+          uploadResult.textContent = "Please choose at least one PDF.";
+          uploadResult.classList.add("error");
+          setBusy(uploadForm, false);
+          return;
+        }
+        for (const file of files) {
+          formData.append("file", file);
+        }
+        const response = await fetch("/upload", { method: "POST", body: formData });
+        const body = await safeJson(response);
+        if (response.ok) {
+          const createdCount = (body.documents || []).filter((doc) => doc.created).length;
+          const reusedCount = (body.documents || []).length - createdCount;
+          uploadResult.textContent =
+            `Uploaded ${body.count} file(s). ${createdCount} indexed, ${reusedCount} reused.\n` +
+            (body.documents || [])
+              .map((doc) => `- ${doc.filename} (${doc.page_count} pages)`)
+              .join("\n");
+        } else {
+          uploadResult.textContent = prettyError(body);
+        }
+        uploadResult.classList.toggle("error", !response.ok);
+        setBusy(uploadForm, false);
+        if (response.ok) {
+          window.location.reload();
+        }
+      });
+
+      docDeleteButtons.forEach((button) => {
+        button.addEventListener("click", async () => {
+          const documentId = button.dataset.documentId;
+          const documentName = button.dataset.documentName || "this document";
+          if (!documentId) return;
+          const confirmed = window.confirm(`Delete ${documentName} from your documents?`);
+          if (!confirmed) return;
+
+          button.disabled = true;
+          const response = await fetch(`/documents/${documentId}`, { method: "DELETE" });
+          const body = await safeJson(response);
+          if (!response.ok) {
+            button.disabled = false;
+            uploadResult.textContent = prettyError(body);
+            uploadResult.classList.add("error");
+            return;
+          }
+          window.location.reload();
+        });
+      });
+
+      askForm?.addEventListener("submit", async (event) => {
+        event.preventDefault();
+        const query = queryInput?.value?.trim() || "";
+        if (!query) return;
+
+        appendMessage({ role: "user", text: query });
+        if (queryInput) queryInput.value = "";
+        setBusy(askForm, true);
+        const pendingBubble = appendMessage({ role: "assistant", text: "Thinking...", markdown: false, pending: true });
+
+        const response = await fetch("/ask", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ query }),
+        });
+        const body = await safeJson(response);
+        const target = pendingBubble || appendMessage({ role: "assistant", text: "", markdown: false });
+        if (!target) {
+          setBusy(askForm, false);
+          return;
+        }
+        target.classList.remove("chat-pending");
+
+        if (response.ok) {
+          const answerText = body.answer || "Response received.";
+          target.classList.add("chat-markdown");
+          renderAssistantResponse(target, answerText, body.sources || null, query);
+        } else {
+          const message = prettyError(body);
+          target.classList.add("chat-error");
+          target.textContent = message;
+        }
+        chatThread.scrollTop = chatThread.scrollHeight;
+        setBusy(askForm, false);
+      });
+
+      queryInput?.addEventListener("keydown", (event) => {
+        if (event.key === "Enter" && !event.shiftKey) {
+          event.preventDefault();
+          askForm?.requestSubmit();
+        }
+      });
+    </script>
+  </body>
+</html>

pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "docsqa-langgraph-assignment"
+version = "0.1.0"
+description = "LangGraph-powered document QA assignment app with login, upload deduplication, vector search, and web search."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.115.0",
+  "jinja2>=3.1.4",
+  "langchain-community>=0.3.0",
+  "langchain-groq>=0.2.0",
+  "langchain-huggingface>=0.1.0",
+  "langchain-text-splitters>=0.3.0",
+  "langgraph>=0.2.35",
+  "passlib[bcrypt]>=1.7.4",
+  "pgvector>=0.3.6",
+  "psycopg[binary]>=3.2.1",
+  "pydantic-settings>=2.5.2",
+  "pypdf>=5.0.1",
+  "python-jose[cryptography]>=3.3.0",
+  "python-multipart>=0.0.9",
+  "sqlalchemy>=2.0.35",
+  "sentence-transformers>=3.0.1",
+  "uvicorn[standard]>=0.30.6",
+  "email-validator>=2.2.0",
+  "tavily-python==0.7.23",
+  "supabase>=2.7.4",
+]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["app*"]