Initial commit

.env.example

@@ -0,0 +1,40 @@
+APP_NAME="MedRAG"
+APP_VERSION="1.0.0"
+DEBUG=false
+
+SECRET_KEY=CHANGE_THIS_TO_A_LONG_RANDOM_STRING_IN_PRODUCTION
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+REFRESH_TOKEN_EXPIRE_DAYS=30
+
+QDRANT_HOST=localhost
+QDRANT_PORT=6333
+QDRANT_API_KEY=
+QDRANT_PATH=data/qdrant
+QDRANT_COLLECTION_NAME=medical-knowledge-rag
+QDRANT_NAMESPACE=medical-docs
+QDRANT_VECTOR_SIZE=768
+
+GROQ_API_KEY=your-groq-api-key-here
+LLM_MODEL=meta-llama/llama-4-scout-17b-16e-instruct
+LLM_MAX_TOKENS=1024
+LLM_TEMPERATURE=0.1
+
+EMBEDDING_MODEL=NeuML/pubmedbert-base-embeddings
+SPEECH_MODEL=Qwen/Qwen3-ASR-1.7B
+SPEECH_DEVICE=
+SPEECH_MAX_UPLOAD_MB=25
+TTS_VOICE=af_heart
+TTS_SPEED=1.0
+
+RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
+RERANKER_TOP_K=5
+RERANKER_MAX_CHUNKS_PER_DOC=2
+
+RAG_RETRIEVAL_TOP_K=20
+RAG_CHUNK_SIZE=512
+RAG_CHUNK_OVERLAP=64
+
+DATABASE_URL=sqlite+aiosqlite:///./data/medrag_main.db
+
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

.gitignore

@@ -0,0 +1,45 @@
+# Environments
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Python
+venv/
+.venv/
+ENV/
+env/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node / JS
+node_modules/
+dist/
+build/
+.eslintcache
+.parcel-cache
+.cache/
+.vite/
+
+# Databases
+data/*.db
+data/qdrant/
+*.db
+
+# Logs
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,197 @@
+# 🏥 MedRAG — Medical Knowledge RAG System
+
+A full-stack, production-ready Retrieval-Augmented Generation system for medical knowledge, with a ChatGPT-style interface, per-user chat history, JWT auth, and an admin dashboard.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| **LLM** | Llama 4 Scout 17B via **Groq** |
+| **Embeddings** | `NeuML/pubmedbert-base-embeddings` |
+| **Reranker** | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
+| **Vector Store** | **Qdrant** (local path storage) |
+| **Backend** | **FastAPI** + SQLAlchemy async |
+| **Auth** | **JWT** (access + refresh tokens) |
+| **Chat DB** | Per-user SQLite — each user gets `data/users/<id>/chats.db` |
+| **Frontend** | React + Tailwind + Zustand + Framer Motion |
+
+---
+
+## Project Structure
+
+```
+medical-rag/
+├── app/
+│   ├── main.py                    # FastAPI app, lifespan, routers
+│   ├── core/
+│   │   ├── config.py              # Pydantic settings
+│   │   └── security.py            # JWT helpers
+│   ├── db/
+│   │   ├── database.py            # Shared DB: users + documents
+│   │   └── chat_db.py             # Per-user chat DB (conversations + messages)
+│   ├── schemas/schemas.py         # All Pydantic models
+│   ├── services/
+│   │   ├── embedding_service.py   # PubMedBERT async encoder
+│   │   ├── reranker_service.py    # Cross-encoder reranker
+│   │   ├── qdrant_service.py      # Qdrant CRUD
+│   │   ├── llm_service.py         # Groq → Llama 4 Scout
+│   │   ├── ingestion_service.py   # PDF/DOCX/TXT → chunk → embed → store
+│   │   └── rag_pipeline.py        # Retrieve → Rerank → Generate → Persist
+│   └── api/routes/
+│       ├── auth.py                # /auth/register, /login, /refresh, /me
+│       ├── conversations.py       # /conversations CRUD
+│       ├── query.py               # /query  (RAG endpoint)
+│       ├── documents.py           # /documents upload/list/delete
+│       └── health_admin.py        # /health, /admin/*
+├── frontend/
+│   └── src/
+│       ├── api/client.js          # Axios + auto-refresh interceptor
+│       ├── store/index.js         # Zustand: auth + chat state
+│       ├── pages/
+│       │   ├── AuthPage.jsx       # Login + Register
+│       │   ├── ChatPage.jsx       # Main ChatGPT-style chat
+│       │   └── AdminPage.jsx      # Admin dashboard
+│       └── components/
+│           ├── layout/Sidebar.jsx # Conversation list, search, grouped by date
+│           └── chat/
+│               ├── MessageBubble.jsx  # Markdown, sources, timing
+│               ├── ChatInput.jsx      # Textarea + PDF upload + button
+│               ├── UploadModal.jsx    # Drag & drop upload dialog
+│               └── WelcomeScreen.jsx  # Suggestion cards
+├── scripts/
+│   └── create_admin.py            # First admin user seeder
+└── requirements.txt
+```
+
+---
+
+## Quickstart
+
+### 1. Clone & configure
+
+```bash
+cp .env.example .env
+# Edit .env — fill in GROQ_API_KEY and SECRET_KEY
+```
+
+### 2. Backend (local dev)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+
+# Create first admin user
+python scripts/create_admin.py \
+  --email admin@hospital.com \
+  --password yourpassword \
+  --name "Dr. Admin"
+
+# Start server
+uvicorn app.main:app --reload --port 8000
+```
+
+API docs: http://localhost:8000/docs
+
+### 3. Frontend (local dev)
+
+```bash
+cd frontend
+npm install
+npm run dev
+# → http://localhost:5173
+```
+
+---
+
+## RAG Pipeline
+
+```
+User question
+    │
+    ▼
+[PubMedBERT Embed]  — medical-domain embedding
+    │
+    ▼
+[Qdrant Search]  — top-20 cosine similarity candidates
+    │
+    ▼
+[Cross-Encoder]  — ms-marco-MiniLM-L-6-v2 reranks to top-5
+    │
+    ▼
+[Llama 4 Scout]  — Groq inference, medical system prompt
+    │
+    ▼
+Answer + Sources — saved to user's per-user SQLite chat DB
+```
+
+---
+
+## API Reference
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| POST | `/api/v1/auth/register` | None | Create account |
+| POST | `/api/v1/auth/login` | None | Get JWT tokens |
+| POST | `/api/v1/auth/refresh` | None | Refresh access token |
+| GET | `/api/v1/auth/me` | User | Current user info |
+| GET | `/api/v1/conversations` | User | List user's conversations |
+| POST | `/api/v1/conversations` | User | Create new conversation |
+| GET | `/api/v1/conversations/{id}/messages` | User | Get chat history |
+| PATCH | `/api/v1/conversations/{id}` | User | Rename conversation |
+| DELETE | `/api/v1/conversations/{id}` | User | Delete conversation |
+| POST | `/api/v1/query` | User | RAG query (returns answer + sources) |
+| GET | `/api/v1/documents` | User | List all documents |
+| POST | `/api/v1/documents/upload` | Admin | Upload + ingest document |
+| DELETE | `/api/v1/documents/{id}` | Admin | Delete document + vectors |
+| GET | `/api/v1/admin/stats` | Admin | System statistics |
+| GET | `/api/v1/admin/users` | Admin | All users |
+| PATCH | `/api/v1/admin/users/{id}/role` | Admin | Change user role |
+| PATCH | `/api/v1/admin/users/{id}/toggle` | Admin | Enable/disable user |
+
+---
+
+## Per-User Chat Database
+
+Each user gets a completely isolated SQLite file:
+
+```
+data/
+├── medrag_main.db              # Shared: users + documents registry
+└── users/
+    ├── <user-id-1>/
+    │   └── chats.db            # conversations + messages for user 1
+    ├── <user-id-2>/
+    │   └── chats.db            # completely separate for user 2
+    └── ...
+```
+
+Conversations are auto-titled from the first message and grouped in the UI by Today / Last 7 days / Older.
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `SECRET_KEY` | JWT signing secret (use a long random string) |
+| `GROQ_API_KEY` | Your Groq API key |
+| `LLM_MODEL` | `meta-llama/llama-4-scout-17b-16e-instruct` |
+| `QDRANT_PATH` | `data/qdrant` |
+| `QDRANT_COLLECTION_NAME` | `medical-knowledge-rag` |
+| `QDRANT_NAMESPACE` | `medical-docs` |
+| `EMBEDDING_MODEL` | `NeuML/pubmedbert-base-embeddings` |
+| `RERANKER_MODEL` | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
+| `RAG_RETRIEVAL_TOP_K` | Candidates from Qdrant (default: 20) |
+| `RERANKER_TOP_K` | Final chunks after rerank (default: 5) |
+| `RAG_CHUNK_SIZE` | Tokens per chunk (default: 512) |
+| `RAG_CHUNK_OVERLAP` | Overlap tokens (default: 64) |
+
+---
+
+## Notes
+
+- **Document upload is admin-only** — regular users query but admins manage the knowledge base
+- **No documents = no answers** — ingest PDFs/DOCX first before querying
+- The first model load (PubMedBERT + cross-encoder) takes ~30–60 seconds; subsequent requests are fast
+- For production: swap SQLite for PostgreSQL (`asyncpg` driver) and optionally move Qdrant to a managed/cloud deployment

app/api/routes/audio.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+from pathlib import Path
+
+import soundfile as sf
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from fastapi.responses import StreamingResponse
+from loguru import logger
+
+from app.core.config import get_settings
+from app.core.security import get_current_user_id
+from app.schemas.schemas import SpeechToTextResponse, TextToSpeechRequest
+from app.services.speech_service import get_speech_service, get_tts_service
+
+router = APIRouter(prefix="/audio", tags=["audio"])
+
+ALLOWED_AUDIO_EXTENSIONS = {"wav", "mp3", "m4a", "mp4", "webm", "ogg", "flac", "opus"}
+
+
+def _validate_audio_file(filename: str, size_bytes: int) -> None:
+    settings = get_settings()
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    if ext not in ALLOWED_AUDIO_EXTENSIONS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unsupported audio format. Allowed: {', '.join(sorted(ALLOWED_AUDIO_EXTENSIONS))}",
+        )
+    max_bytes = settings.speech_max_upload_mb * 1024 * 1024
+    if size_bytes > max_bytes:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Audio file is too large. Maximum size is {settings.speech_max_upload_mb} MB.",
+        )
+
+
+@router.post("/transcribe", response_model=SpeechToTextResponse)
+async def transcribe_audio(
+    file: UploadFile = File(...),
+    _: str = Depends(get_current_user_id),
+):
+    filename = file.filename or "recording.wav"
+    raw_bytes = await file.read()
+    if not raw_bytes:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Audio file is empty")
+
+    _validate_audio_file(filename, len(raw_bytes))
+    suffix = Path(filename).suffix or ".wav"
+    temp_path = None
+    try:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as temp_file:
+            temp_file.write(raw_bytes)
+            temp_path = temp_file.name
+        text = get_speech_service().transcribe(temp_path)
+    except Exception as exc:
+        logger.exception("STT transcription failed for {}", filename)
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)) from exc
+    finally:
+        if temp_path and os.path.exists(temp_path):
+            os.unlink(temp_path)
+
+    if not text.strip():
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="No speech was detected in the recording")
+
+    return SpeechToTextResponse(
+        text=text.strip(),
+        language=None,
+        model=get_settings().speech_model,
+        filename=filename,
+    )
+
+
+@router.post("/speak")
+async def speak_text(
+    request: TextToSpeechRequest,
+    _: str = Depends(get_current_user_id),
+):
+    try:
+        audio, sample_rate = get_tts_service().speak(
+            request.text,
+            voice=request.voice or get_settings().tts_voice,
+            speed=request.speed,
+            play=False,
+        )
+    except Exception as exc:
+        logger.exception("TTS generation failed")
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)) from exc
+
+    if audio is None or sample_rate <= 0:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Text-to-speech produced no audio")
+
+    wav_bytes = io.BytesIO()
+    sf.write(wav_bytes, audio, sample_rate, format="WAV")
+    wav_bytes.seek(0)
+    return StreamingResponse(
+        wav_bytes,
+        media_type="audio/wav",
+        headers={"Content-Disposition": "inline; filename=tts.wav"},
+    )

app/api/routes/auth.py

@@ -0,0 +1,71 @@
+import uuid
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+from app.core.security import (
+    hash_password, verify_password,
+    create_access_token, create_refresh_token,
+    decode_token, get_current_user_id,
+)
+from app.db.database import User, get_db
+from app.db.chat_db import ensure_user_db
+from app.schemas.schemas import UserRegister, UserLogin, TokenResponse, RefreshRequest, UserOut
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/register", response_model=UserOut, status_code=201)
+async def register(payload: UserRegister, db: AsyncSession = Depends(get_db)):
+    existing = await db.execute(select(User).where(User.email == payload.email))
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Email already registered")
+
+    user = User(
+        id=str(uuid.uuid4()),
+        email=payload.email,
+        hashed_password=hash_password(payload.password),
+        full_name=payload.full_name,
+        role="user",
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    # Provision per-user chat DB immediately
+    await ensure_user_db(user.id)
+    return user
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(payload: UserLogin, db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(User).where(User.email == payload.email))
+    user = result.scalar_one_or_none()
+    if not user or not verify_password(payload.password, user.hashed_password):
+        raise HTTPException(status_code=401, detail="Incorrect email or password")
+    if not user.is_active:
+        raise HTTPException(status_code=403, detail="Account is disabled")
+    return TokenResponse(
+        access_token=create_access_token(user.id),
+        refresh_token=create_refresh_token(user.id),
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(payload: RefreshRequest):
+    claims = decode_token(payload.refresh_token)
+    if claims.get("kind") != "refresh":
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+    user_id: str = claims["sub"]
+    return TokenResponse(
+        access_token=create_access_token(user_id),
+        refresh_token=create_refresh_token(user_id),
+    )
+
+
+@router.get("/me", response_model=UserOut)
+async def me(user_id: str = Depends(get_current_user_id), db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user

app/api/routes/conversations.py

@@ -0,0 +1,103 @@
+"""
+Conversation management routes — ChatGPT-style sidebar.
+"""
+import json
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.core.security import get_current_user_id
+from app.db import chat_db
+from app.schemas.schemas import (
+    ConversationOut,
+    ConversationCreate,
+    ConversationRename,
+    MessageOut,
+    SourceChunk,
+)
+
+router = APIRouter(prefix="/conversations", tags=["conversations"])
+
+
+def _msg_to_out(msg) -> MessageOut:
+    sources = None
+    meta = None
+    if msg.sources_json:
+        try:
+            raw = json.loads(msg.sources_json)
+            sources = [SourceChunk(**s) for s in raw]
+        except Exception:
+            sources = None
+    if getattr(msg, "meta_json", None):
+        try:
+            meta = json.loads(msg.meta_json)
+        except Exception:
+            meta = None
+    return MessageOut(
+        id=msg.id,
+        conversation_id=msg.conversation_id,
+        role=msg.role,
+        content=msg.content,
+        sources=sources,
+        meta=meta,
+        created_at=msg.created_at,
+    )
+
+
+@router.post("", response_model=ConversationOut, status_code=201)
+async def create_conversation(
+    payload: ConversationCreate,
+    user_id: str = Depends(get_current_user_id),
+):
+    conv = await chat_db.create_conversation(user_id, payload.title)
+    return ConversationOut(
+        id=conv.id,
+        title=conv.title,
+        created_at=conv.created_at,
+        updated_at=conv.updated_at,
+    )
+
+
+@router.get("", response_model=List[ConversationOut])
+async def list_conversations(user_id: str = Depends(get_current_user_id)):
+    convs = await chat_db.list_conversations(user_id)
+    return [
+        ConversationOut(id=c.id, title=c.title, created_at=c.created_at, updated_at=c.updated_at)
+        for c in convs
+    ]
+
+
+@router.get("/{conv_id}/messages", response_model=List[MessageOut])
+async def get_messages(
+    conv_id: str,
+    user_id: str = Depends(get_current_user_id),
+):
+    conv = await chat_db.get_conversation(user_id, conv_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    msgs = await chat_db.get_messages(user_id, conv_id)
+    return [_msg_to_out(m) for m in msgs]
+
+
+@router.patch("/{conv_id}", response_model=ConversationOut)
+async def rename_conversation(
+    conv_id: str,
+    payload: ConversationRename,
+    user_id: str = Depends(get_current_user_id),
+):
+    conv = await chat_db.get_conversation(user_id, conv_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    await chat_db.rename_conversation(user_id, conv_id, payload.title)
+    conv = await chat_db.get_conversation(user_id, conv_id)
+    return ConversationOut(id=conv.id, title=conv.title, created_at=conv.created_at, updated_at=conv.updated_at)
+
+
+@router.delete("/{conv_id}", status_code=204)
+async def delete_conversation(
+    conv_id: str,
+    user_id: str = Depends(get_current_user_id),
+):
+    conv = await chat_db.get_conversation(user_id, conv_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    await chat_db.delete_conversation(user_id, conv_id)

app/api/routes/documents.py

@@ -0,0 +1,151 @@
+from pathlib import Path
+from fastapi import APIRouter, Depends, UploadFile, File, Form, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from typing import List
+
+from app.core.security import get_current_user_id
+from app.db.database import get_db, DocumentRecord, User
+from app.schemas.schemas import BatchIngestResponse, DocumentOut
+from app.services.ingestion_service import (
+    create_document_record,
+    get_conversation_documents,
+    get_all_documents,
+    get_document,
+    schedule_ingestion,
+    validate_medical_document,
+)
+from app.db import chat_db
+from app.services.qdrant_service import get_qdrant_service
+
+router = APIRouter(prefix="/documents", tags=["documents"])
+ALLOWED_EXT = {"pdf", "docx", "txt"}
+
+
+def _check_ext(filename: str) -> None:
+    ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    if ext not in ALLOWED_EXT:
+        raise HTTPException(status_code=400, detail=f"Unsupported file type. Allowed: {', '.join(ALLOWED_EXT)}")
+
+
+async def _require_admin(user_id: str, db: AsyncSession) -> User:
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user or user.role != "admin":
+        raise HTTPException(status_code=403, detail="Admin access required")
+    return user
+
+
+@router.post("/upload", response_model=BatchIngestResponse, status_code=202)
+async def upload_document(
+    files: List[UploadFile] = File(...),
+    conversation_id: str = Form(...),
+    title: str | None = Form(default=None),
+    source: str | None = Form(default=None),
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    """Queue one or more medical documents for ingestion."""
+    conv = await chat_db.get_conversation(user_id, conversation_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    pending_documents: List[tuple[str, bytes, str]] = []
+
+    for file in files:
+        filename = file.filename or "unknown"
+        _check_ext(filename)
+        raw_bytes = await file.read()
+        try:
+            validate_medical_document(filename, raw_bytes)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=f"{filename}: {exc}") from exc
+
+        doc_title = title.strip() if title and len(files) == 1 else Path(filename).stem.replace("-", " ").replace("_", " ")
+        pending_documents.append((filename, raw_bytes, doc_title))
+
+    document_ids: List[str] = []
+    for filename, raw_bytes, doc_title in pending_documents:
+        doc_id = await create_document_record(
+            filename=filename,
+            title=doc_title,
+            source=source,
+            user_id=user_id,
+            conversation_id=conversation_id,
+            db=db,
+        )
+        schedule_ingestion(
+            doc_id=doc_id,
+            filename=filename,
+            title=doc_title,
+            source=source,
+            raw_bytes=raw_bytes,
+        )
+        document_ids.append(doc_id)
+
+    noun = "document" if len(document_ids) == 1 else "documents"
+    return BatchIngestResponse(
+        document_ids=document_ids,
+        message=f"Queued {len(document_ids)} {noun} for ingestion",
+    )
+
+
+@router.get("", response_model=List[DocumentOut])
+async def list_documents(
+    conversation_id: str | None = None,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    if conversation_id:
+        conv = await chat_db.get_conversation(user_id, conversation_id)
+        if not conv:
+            raise HTTPException(status_code=404, detail="Conversation not found")
+        docs = await get_conversation_documents(conversation_id, db)
+    else:
+        docs = await get_all_documents(db)
+    return docs
+
+
+@router.get("/{doc_id}", response_model=DocumentOut)
+async def get_document_detail(
+    doc_id: str,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    doc = await get_document(doc_id, db)
+    if not doc:
+        raise HTTPException(status_code=404, detail="Document not found")
+    return doc
+
+
+@router.delete("/conversation/{conversation_id}", status_code=204)
+async def clear_conversation_documents(
+    conversation_id: str,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    conv = await chat_db.get_conversation(user_id, conversation_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+
+    docs = await get_conversation_documents(conversation_id, db)
+    qdrant = get_qdrant_service()
+    for doc in docs:
+        await qdrant.delete_by_doc_id(doc.id)
+        await db.delete(doc)
+    await db.commit()
+
+
+@router.delete("/{doc_id}", status_code=204)
+async def delete_document(
+    doc_id: str,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    await _require_admin(user_id, db)
+    doc = await get_document(doc_id, db)
+    if not doc:
+        raise HTTPException(status_code=404, detail="Document not found")
+    qdrant = get_qdrant_service()
+    await qdrant.delete_by_doc_id(doc_id)
+    await db.delete(doc)
+    await db.commit()

app/api/routes/health_admin.py

@@ -0,0 +1,103 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from typing import List
+
+from app.core.security import get_current_user_id
+from app.db.database import get_db, User, DocumentRecord
+from app.schemas.schemas import HealthResponse, UserOut
+from app.services.qdrant_service import get_qdrant_service
+from app.services.llm_service import get_llm_service
+from app.core.config import get_settings
+
+settings = get_settings()
+
+health_router = APIRouter(tags=["health"])
+admin_router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+@health_router.get("/health", response_model=HealthResponse)
+async def health():
+    qdrant_status = await get_qdrant_service().health()
+    llm_status = await get_llm_service().health()
+    return HealthResponse(
+        status="ok" if qdrant_status == "ok" and llm_status == "ok" else "degraded",
+        qdrant=qdrant_status,
+        llm=llm_status,
+        version=settings.app_version,
+    )
+
+
+async def _require_admin(user_id: str, db: AsyncSession) -> User:
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user or user.role != "admin":
+        raise HTTPException(status_code=403, detail="Admin access required")
+    return user
+
+
+@admin_router.get("/users", response_model=List[UserOut])
+async def list_users(
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    await _require_admin(user_id, db)
+    result = await db.execute(select(User).order_by(User.created_at.desc()))
+    return result.scalars().all()
+
+
+@admin_router.patch("/users/{target_id}/role")
+async def update_user_role(
+    target_id: str,
+    role: str,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    await _require_admin(user_id, db)
+    if role not in ("user", "admin"):
+        raise HTTPException(status_code=400, detail="Role must be 'user' or 'admin'")
+    result = await db.execute(select(User).where(User.id == target_id))
+    target = result.scalar_one_or_none()
+    if not target:
+        raise HTTPException(status_code=404, detail="User not found")
+    target.role = role
+    await db.commit()
+    return {"id": target_id, "role": role}
+
+
+@admin_router.patch("/users/{target_id}/toggle")
+async def toggle_user_active(
+    target_id: str,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    await _require_admin(user_id, db)
+    result = await db.execute(select(User).where(User.id == target_id))
+    target = result.scalar_one_or_none()
+    if not target:
+        raise HTTPException(status_code=404, detail="User not found")
+    target.is_active = not target.is_active
+    await db.commit()
+    return {"id": target_id, "is_active": target.is_active}
+
+
+@admin_router.get("/stats")
+async def admin_stats(
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    await _require_admin(user_id, db)
+    user_count = await db.scalar(select(func.count()).select_from(User))
+    doc_count = await db.scalar(select(func.count()).select_from(DocumentRecord))
+    ready_docs = await db.scalar(
+        select(func.count()).select_from(DocumentRecord).where(DocumentRecord.status == "ready")
+    )
+    total_chunks = await db.scalar(select(func.sum(DocumentRecord.chunk_count)).select_from(DocumentRecord))
+    qdrant_status = await get_qdrant_service().health()
+    return {
+        "total_users": user_count,
+        "total_documents": doc_count,
+        "ready_documents": ready_docs,
+        "total_chunks_indexed": total_chunks or 0,
+        "qdrant_status": qdrant_status,
+    }

app/api/routes/query.py

@@ -0,0 +1,61 @@
+from fastapi import APIRouter, Depends, HTTPException
+from app.core.security import get_current_user_id
+from app.schemas.schemas import QueryRequest, QueryResponse
+from app.services.rag_pipeline import run_rag_pipeline
+from app.db import chat_db
+from app.db.database import get_db
+from app.services.ingestion_service import get_conversation_ready_document_count
+from sqlalchemy.ext.asyncio import AsyncSession
+from loguru import logger
+
+router = APIRouter(prefix="/query", tags=["rag"])
+
+
+@router.post("", response_model=QueryResponse)
+async def query(
+    request: QueryRequest,
+    user_id: str = Depends(get_current_user_id),
+    db: AsyncSession = Depends(get_db),
+):
+    # Verify conversation belongs to user
+    conv = await chat_db.get_conversation(user_id, request.conversation_id)
+    if not conv:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    ready_docs = await get_conversation_ready_document_count(request.conversation_id, db)
+    if ready_docs == 0:
+        await chat_db.add_message(
+            user_id=user_id,
+            conv_id=request.conversation_id,
+            role="user",
+            content=request.query,
+        )
+        asst_msg = await chat_db.add_message(
+            user_id=user_id,
+            conv_id=request.conversation_id,
+            role="assistant",
+            content="Upload documents to this chat first",
+        )
+        messages = await chat_db.get_messages(user_id, request.conversation_id)
+        if len(messages) <= 2:
+            await chat_db.auto_title_conversation(user_id, request.conversation_id, request.query)
+        return QueryResponse(
+            message_id=asst_msg.id,
+            conversation_id=request.conversation_id,
+            query=request.query,
+            search_query=request.query,
+            answer="Upload documents to this chat first",
+            sources=[],
+            model="none",
+            retrieval_strategy="none",
+            conversation_turns_used=0,
+            retrieval_ms=0,
+            rerank_ms=0,
+            generation_ms=0,
+        )
+
+    logger.info(f"RAG query user={user_id} conv={request.conversation_id}: {request.query[:60]}...")
+    try:
+        return await run_rag_pipeline(request, user_id)
+    except Exception as exc:
+        logger.error(f"RAG pipeline error: {exc}")
+        raise HTTPException(status_code=500, detail=f"RAG pipeline failed: {str(exc)}")

app/core/config.py

@@ -0,0 +1,67 @@
+from functools import lru_cache
+from typing import List
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "MedRAG"
+    app_version: str = "1.0.0"
+    debug: bool = False
+
+    secret_key: str = Field(default="dev-secret-change-in-prod")
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 60
+    refresh_token_expire_days: int = 30
+
+    qdrant_host: str = "localhost"
+    qdrant_port: int = 6333
+    qdrant_api_key: str | None = None
+    qdrant_path: str = "data/qdrant"
+    qdrant_collection_name: str = "medical-knowledge-rag"
+    qdrant_namespace: str = "medical-docs"
+    qdrant_vector_size: int = 768
+
+    groq_api_key: str = Field(default="")
+    google_api_key: str = Field(default="")
+    llm_model: str = "meta-llama/llama-4-scout-17b-16e-instruct"
+    gemini_model: str = "gemini-2.5-flash"
+    llm_max_tokens: int = 1024
+    llm_temperature: float = 0.1
+
+    embedding_model: str = "NeuML/pubmedbert-base-embeddings"
+    speech_model: str = "Qwen/Qwen3-ASR-1.7B"
+    speech_device: str | None = None
+    speech_max_upload_mb: int = 25
+    tts_voice: str = "af_heart"
+    tts_speed: float = 1.0
+
+    reranker_model: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+    reranker_top_k: int = 5
+    reranker_max_chunks_per_doc: int = 2
+    reranker_min_score: float = -1.0
+    reranker_score_window: float = 1.5
+
+    rag_retrieval_top_k: int = 20
+    rag_chunk_size: int = 512
+    rag_chunk_overlap: int = 64
+    rag_conversation_history_turns: int = 6
+    rag_hybrid_rrf_k: int = 60
+
+    database_url: str = "sqlite+aiosqlite:///./data/medrag_main.db"
+    allowed_origins: str = "http://localhost:3000,http://localhost:5173"
+
+    @property
+    def allowed_origins_list(self) -> List[str]:
+        return [origin.strip() for origin in self.allowed_origins.split(",") if origin.strip()]
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()

app/core/security.py

@@ -0,0 +1,56 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+import bcrypt
+from jose import JWTError, jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+from app.core.config import get_settings
+
+settings = get_settings()
+bearer_scheme = HTTPBearer()
+
+
+def hash_password(plain: str) -> str:
+    return bcrypt.hashpw(plain.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return bcrypt.checkpw(plain.encode("utf-8"), hashed.encode("utf-8"))
+
+
+def _create_token(subject: str, kind: str, expires_delta: timedelta) -> str:
+    expire = datetime.now(timezone.utc) + expires_delta
+    payload = {"sub": subject, "kind": kind, "exp": expire, "iat": datetime.now(timezone.utc)}
+    return jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm)
+
+
+def create_access_token(user_id: str) -> str:
+    return _create_token(user_id, "access", timedelta(minutes=settings.access_token_expire_minutes))
+
+
+def create_refresh_token(user_id: str) -> str:
+    return _create_token(user_id, "refresh", timedelta(days=settings.refresh_token_expire_days))
+
+
+def decode_token(token: str) -> dict:
+    try:
+        return jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+    except JWTError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from exc
+
+
+def get_current_user_id(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+) -> str:
+    payload = decode_token(credentials.credentials)
+    if payload.get("kind") != "access":
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token type")
+    user_id: Optional[str] = payload.get("sub")
+    if not user_id:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token payload")
+    return user_id

app/db/chat_db.py

@@ -0,0 +1,182 @@
+"""
+Per-user chat database.
+
+Each user gets their own SQLite file at:
+  ./data/users/<user_id>/chats.db
+
+Schema:
+  conversations  – chat sessions (like ChatGPT sidebar items)
+  messages       – individual messages within a conversation
+"""
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import String, DateTime, Text, ForeignKey, select, update
+from loguru import logger
+
+
+class ChatBase(DeclarativeBase):
+    pass
+
+
+class Conversation(ChatBase):
+    __tablename__ = "conversations"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    title: Mapped[str] = mapped_column(String(512), default="New Chat")
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+
+class Message(ChatBase):
+    __tablename__ = "messages"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    conversation_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("conversations.id"), nullable=False, index=True
+    )
+    role: Mapped[str] = mapped_column(String(20), nullable=False)   # "user" | "assistant"
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+    sources_json: Mapped[str | None] = mapped_column(Text)          # JSON-serialised SourceChunk list
+    meta_json: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+
+# ─── Engine pool per user ─────────────────────────────────────────────────────
+_engines: dict[str, any] = {}
+
+
+def _get_user_engine(user_id: str):
+    if user_id not in _engines:
+        user_dir = f"./data/users/{user_id}"
+        os.makedirs(user_dir, exist_ok=True)
+        db_path = f"{user_dir}/chats.db"
+        engine = create_async_engine(f"sqlite+aiosqlite:///{db_path}", echo=False)
+        _engines[user_id] = engine
+    return _engines[user_id]
+
+
+async def ensure_user_db(user_id: str) -> None:
+    engine = _get_user_engine(user_id)
+    async with engine.begin() as conn:
+        await conn.run_sync(ChatBase.metadata.create_all)
+        columns = await conn.exec_driver_sql("PRAGMA table_info(messages)")
+        column_names = {row[1] for row in columns.fetchall()}
+        if "meta_json" not in column_names:
+            await conn.exec_driver_sql("ALTER TABLE messages ADD COLUMN meta_json TEXT")
+    logger.debug(f"Chat DB ready for user {user_id}")
+
+
+def _session_maker(user_id: str) -> async_sessionmaker:
+    return async_sessionmaker(_get_user_engine(user_id), expire_on_commit=False)
+
+
+# ─── CRUD helpers ─────────────────────────────────────────────────────────────
+
+async def create_conversation(user_id: str, title: str = "New Chat") -> Conversation:
+    await ensure_user_db(user_id)
+    async with _session_maker(user_id)() as db:
+        conv = Conversation(id=str(uuid.uuid4()), title=title)
+        db.add(conv)
+        await db.commit()
+        await db.refresh(conv)
+        return conv
+
+
+async def list_conversations(user_id: str) -> List[Conversation]:
+    await ensure_user_db(user_id)
+    async with _session_maker(user_id)() as db:
+        result = await db.execute(
+            select(Conversation).order_by(Conversation.updated_at.desc())
+        )
+        return result.scalars().all()
+
+
+async def get_conversation(user_id: str, conv_id: str) -> Optional[Conversation]:
+    await ensure_user_db(user_id)
+    async with _session_maker(user_id)() as db:
+        result = await db.execute(
+            select(Conversation).where(Conversation.id == conv_id)
+        )
+        return result.scalar_one_or_none()
+
+
+async def rename_conversation(user_id: str, conv_id: str, new_title: str) -> None:
+    async with _session_maker(user_id)() as db:
+        await db.execute(
+            update(Conversation)
+            .where(Conversation.id == conv_id)
+            .values(title=new_title, updated_at=datetime.now(timezone.utc))
+        )
+        await db.commit()
+
+
+async def delete_conversation(user_id: str, conv_id: str) -> None:
+    async with _session_maker(user_id)() as db:
+        result = await db.execute(select(Conversation).where(Conversation.id == conv_id))
+        conv = result.scalar_one_or_none()
+        if conv:
+            # cascade delete messages first
+            msgs = await db.execute(select(Message).where(Message.conversation_id == conv_id))
+            for msg in msgs.scalars().all():
+                await db.delete(msg)
+            await db.delete(conv)
+            await db.commit()
+
+
+async def add_message(
+    user_id: str,
+    conv_id: str,
+    role: str,
+    content: str,
+    sources_json: str | None = None,
+    meta_json: str | None = None,
+) -> Message:
+    async with _session_maker(user_id)() as db:
+        msg = Message(
+            id=str(uuid.uuid4()),
+            conversation_id=conv_id,
+            role=role,
+            content=content,
+            sources_json=sources_json,
+            meta_json=meta_json,
+        )
+        db.add(msg)
+        # Touch conversation updated_at so it floats to top
+        await db.execute(
+            update(Conversation)
+            .where(Conversation.id == conv_id)
+            .values(updated_at=datetime.now(timezone.utc))
+        )
+        await db.commit()
+        await db.refresh(msg)
+        return msg
+
+
+async def get_messages(user_id: str, conv_id: str) -> List[Message]:
+    await ensure_user_db(user_id)
+    async with _session_maker(user_id)() as db:
+        result = await db.execute(
+            select(Message)
+            .where(Message.conversation_id == conv_id)
+            .order_by(Message.created_at.asc())
+        )
+        return result.scalars().all()
+
+
+async def auto_title_conversation(user_id: str, conv_id: str, first_question: str) -> None:
+    """Set a smart title from the first user message (truncated)."""
+    title = first_question[:60] + ("…" if len(first_question) > 60 else "")
+    await rename_conversation(user_id, conv_id, title)

app/db/database.py

@@ -0,0 +1,72 @@
+"""
+Main application database (shared across all users).
+  - users table
+  - documents table (Qdrant vector registry)
+
+Per-user chat history lives in separate SQLite files:
+  ./data/users/<user_id>/chats.db
+"""
+import os
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import String, Boolean, DateTime, Text, Integer
+from datetime import datetime, timezone
+
+from app.core.config import get_settings
+
+settings = get_settings()
+
+# Ensure data directory exists
+os.makedirs("./data", exist_ok=True)
+
+engine = create_async_engine(settings.database_url, echo=settings.debug)
+AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    full_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[str] = mapped_column(String(50), default="user")
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+
+class DocumentRecord(Base):
+    __tablename__ = "documents"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    filename: Mapped[str] = mapped_column(String(512), nullable=False)
+    title: Mapped[str] = mapped_column(String(512), nullable=False)
+    source: Mapped[str | None] = mapped_column(String(512))
+    chunk_count: Mapped[int] = mapped_column(Integer, default=0)
+    uploaded_by: Mapped[str] = mapped_column(String(36), nullable=False)
+    conversation_id: Mapped[str] = mapped_column(String(36), nullable=False, default="")
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    status: Mapped[str] = mapped_column(String(50), default="processing")
+    error_message: Mapped[str | None] = mapped_column(Text)
+
+
+async def init_db() -> None:
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+        columns = await conn.exec_driver_sql("PRAGMA table_info(documents)")
+        column_names = {row[1] for row in columns.fetchall()}
+        if "conversation_id" not in column_names:
+            await conn.exec_driver_sql("ALTER TABLE documents ADD COLUMN conversation_id VARCHAR(36) NOT NULL DEFAULT ''")
+
+
+async def get_db():  # type: ignore[return]
+    async with AsyncSessionLocal() as session:
+        yield session

app/main.py

@@ -0,0 +1,74 @@
+import os
+import asyncio
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from loguru import logger
+
+from app.core.config import get_settings
+from app.db.database import init_db
+from app.api.routes.auth import router as auth_router
+from app.api.routes.conversations import router as conv_router
+from app.api.routes.query import router as query_router
+from app.api.routes.documents import router as docs_router
+from app.api.routes.audio import router as audio_router
+from app.api.routes.health_admin import health_router, admin_router
+
+settings = get_settings()
+os.makedirs("./data/users", exist_ok=True)
+
+
+from app.services.speech_service import get_speech_service, get_tts_service
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+    await init_db()
+    logger.info("Main database initialised")
+    
+    # Preload STT and TTS models during startup to avoid latency on first request
+    try:
+        logger.info("Preloading Speech-to-Text (STT) model...")
+        await asyncio.to_thread(get_speech_service)
+        logger.info("STT model preloaded successfully")
+        
+        logger.info("Preloading Text-to-Speech (TTS) model...")
+        await asyncio.to_thread(get_tts_service().preload, settings.tts_voice)
+        logger.info("TTS model preloaded successfully")
+    except Exception as e:
+        logger.error(f"Failed to preload speech models during startup: {e}")
+        
+    yield
+    logger.info("Shutting down")
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Medical Knowledge RAG API — Groq · Llama 4 Scout · Qdrant · BioBERT · Cross-Encoder",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ─── Routers ──────────────────────────────────────────────────────────────────
+PREFIX = "/api/v1"
+app.include_router(health_router, prefix=PREFIX)
+app.include_router(auth_router, prefix=PREFIX)
+app.include_router(conv_router, prefix=PREFIX)
+app.include_router(query_router, prefix=PREFIX)
+app.include_router(docs_router, prefix=PREFIX)
+app.include_router(audio_router, prefix=PREFIX)
+app.include_router(admin_router, prefix=PREFIX)
+
+
+@app.get("/")
+async def root():
+    return {"name": settings.app_name, "version": settings.app_version, "docs": "/docs"}

app/schemas/schemas.py

@@ -0,0 +1,147 @@
+from pydantic import BaseModel, EmailStr, Field
+from typing import Optional, List, Any
+from datetime import datetime
+
+
+# ─── Auth ──────────────────────────────────────────────────────────────────────
+
+class UserRegister(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8)
+    full_name: str = Field(min_length=2)
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+class UserOut(BaseModel):
+    id: str
+    email: str
+    full_name: str
+    role: str
+    is_active: bool
+    created_at: datetime
+    model_config = {"from_attributes": True}
+
+
+# ─── Conversations ─────────────────────────────────────────────────────────────
+
+class ConversationOut(BaseModel):
+    id: str
+    title: str
+    created_at: datetime
+    updated_at: datetime
+    model_config = {"from_attributes": True}
+
+
+class ConversationCreate(BaseModel):
+    title: str = "New Chat"
+
+
+class ConversationRename(BaseModel):
+    title: str = Field(min_length=1, max_length=200)
+
+
+# ─── Messages ──────────────────────────────────────────────────────────────────
+
+class SourceChunk(BaseModel):
+    doc_id: str
+    filename: str
+    title: str
+    chunk_index: int
+    page_number: Optional[int] = None
+    text: str
+    score: float
+    retrieval_method: Optional[str] = None
+
+
+class MessageOut(BaseModel):
+    id: str
+    conversation_id: str
+    role: str
+    content: str
+    sources: Optional[List[SourceChunk]] = None
+    meta: Optional[dict[str, Any]] = None
+    created_at: datetime
+    model_config = {"from_attributes": True}
+
+
+# ─── RAG / Query ───────────────────────────────────────────────────────────────
+
+class QueryRequest(BaseModel):
+    query: str = Field(min_length=3, max_length=2000)
+    conversation_id: str          # must exist in user's chat DB
+    top_k: Optional[int] = Field(default=5, ge=1, le=20)
+
+
+class QueryResponse(BaseModel):
+    message_id: str
+    conversation_id: str
+    query: str
+    search_query: str
+    answer: str
+    sources: List[SourceChunk]
+    model: str
+    retrieval_strategy: str
+    conversation_turns_used: int
+    retrieval_ms: float
+    rerank_ms: float
+    generation_ms: float
+
+
+class SpeechToTextResponse(BaseModel):
+    text: str
+    language: Optional[str] = None
+    model: str
+    filename: str
+
+
+class TextToSpeechRequest(BaseModel):
+    text: str = Field(min_length=1, max_length=12000)
+    voice: Optional[str] = None
+    speed: float = Field(default=1.0, ge=0.5, le=2.0)
+
+
+# ─── Documents ─────────────────────────────────────────────────────────────────
+
+class DocumentOut(BaseModel):
+    id: str
+    filename: str
+    title: str
+    source: Optional[str]
+    chunk_count: int
+    status: str
+    created_at: datetime
+    uploaded_by: str
+    model_config = {"from_attributes": True}
+
+
+class IngestResponse(BaseModel):
+    document_id: str
+    message: str
+
+
+class BatchIngestResponse(BaseModel):
+    document_ids: List[str]
+    message: str
+
+
+# ─── Health ────────────────────────────────────────────────────────────────────
+
+class HealthResponse(BaseModel):
+    status: str
+    qdrant: str
+    llm: str
+    version: str

app/services/embedding_service.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+import asyncio
+from functools import lru_cache
+from typing import List
+
+from sentence_transformers import SentenceTransformer
+from loguru import logger
+from app.core.config import get_settings
+
+settings = get_settings()
+
+
+class EmbeddingService:
+    _model: SentenceTransformer | None = None
+
+    def _load(self) -> SentenceTransformer:
+        if self._model is None:
+            logger.info(f"Loading embedding model: {settings.embedding_model}")
+            self._model = SentenceTransformer(settings.embedding_model)
+        return self._model
+
+    async def embed_texts(self, texts: List[str]) -> List[List[float]]:
+        loop = asyncio.get_running_loop()
+        model = self._load()
+        return await loop.run_in_executor(
+            None,
+            lambda: model.encode(texts, normalize_embeddings=True, show_progress_bar=False).tolist()
+        )
+
+    async def embed_query(self, query: str) -> List[float]:
+        vecs = await self.embed_texts([query])
+        return vecs[0]
+
+
+@lru_cache(maxsize=1)
+def get_embedding_service() -> EmbeddingService:
+    return EmbeddingService()

app/services/gemini_service.py

@@ -0,0 +1,41 @@
+import google.generativeai as genai
+from app.core.config import get_settings
+from loguru import logger
+
+settings = get_settings()
+
+class GeminiService:
+    def __init__(self):
+        if not settings.google_api_key:
+            logger.warning("GOOGLE_API_KEY not found in settings")
+        
+        genai.configure(api_key=settings.google_api_key)
+        self.model = genai.GenerativeModel(settings.gemini_model)
+
+    async def generate_response(self, prompt: str, system_instruction: str = None) -> str:
+        """
+        Generates a response from Gemini based on the provided prompt.
+        """
+        try:
+            # Re-initialize model if system_instruction is provided
+            model = self.model
+            if system_instruction:
+                model = genai.GenerativeModel(
+                    settings.gemini_model,
+                    system_instruction=system_instruction
+                )
+            
+            response = await model.generate_content_async(prompt)
+            return response.text
+        except Exception as e:
+            logger.error(f"Error calling Gemini API: {e}")
+            return f"Error: {e}"
+
+# Global instance
+gemini_service = None
+
+def get_gemini_service():
+    global gemini_service
+    if gemini_service is None:
+        gemini_service = GeminiService()
+    return gemini_service

app/services/ingestion_service.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+import asyncio
+import io
+import uuid
+from typing import Any, List
+
+from fastapi import UploadFile
+from loguru import logger
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+from app.core.config import get_settings
+from app.db.database import AsyncSessionLocal, DocumentRecord
+from app.services.embedding_service import get_embedding_service
+from app.services.qdrant_service import get_qdrant_service
+
+settings = get_settings()
+_ingestion_tasks: set[asyncio.Task] = set()
+
+MIN_MEDICAL_TEXT_CHARS = 120
+MIN_MEDICAL_KEYWORD_HITS = 3
+MIN_MEDICAL_KEYWORD_DENSITY = 1.5
+MEDICAL_KEYWORDS = {
+    "acute",
+    "anatomy",
+    "antibiotic",
+    "artery",
+    "blood",
+    "cancer",
+    "cardiac",
+    "cardiology",
+    "care",
+    "cell",
+    "chronic",
+    "clinical",
+    "clinic",
+    "condition",
+    "diagnosis",
+    "diagnostic",
+    "disease",
+    "disorder",
+    "dosage",
+    "dose",
+    "drug",
+    "emergency",
+    "epidemiology",
+    "examination",
+    "guideline",
+    "health",
+    "healthcare",
+    "heart",
+    "hospital",
+    "immune",
+    "infection",
+    "inflammation",
+    "injury",
+    "laboratory",
+    "medical",
+    "medicine",
+    "mortality",
+    "nurse",
+    "oncology",
+    "organ",
+    "pathology",
+    "patient",
+    "pharmacology",
+    "physician",
+    "physiology",
+    "prescription",
+    "prognosis",
+    "radiology",
+    "risk",
+    "screening",
+    "surgery",
+    "surgical",
+    "symptom",
+    "syndrome",
+    "therapy",
+    "tissue",
+    "treatment",
+    "trial",
+    "vaccine",
+}
+
+
+def _extract_pdf(data: bytes) -> List[dict[str, Any]]:
+    import fitz
+    with fitz.open(stream=data, filetype="pdf") as doc:
+        return [
+            {"text": page.get_text("text") or "", "page_number": page.number + 1}
+            for page in doc
+        ]
+
+
+def _extract_docx(data: bytes) -> str:
+    import docx
+    doc = docx.Document(io.BytesIO(data))
+    return "\n\n".join(p.text for p in doc.paragraphs if p.text.strip())
+
+
+def _extract_txt(data: bytes) -> str:
+    return data.decode("utf-8", errors="replace")
+
+
+def extract_segments(filename: str, data: bytes) -> List[dict[str, Any]]:
+    ext = filename.rsplit(".", 1)[-1].lower()
+    if ext == "pdf":
+        return _extract_pdf(data)
+    elif ext in ("docx", "doc"):
+        return [{"text": _extract_docx(data), "page_number": None}]
+    elif ext == "txt":
+        return [{"text": _extract_txt(data), "page_number": None}]
+    raise ValueError(f"Unsupported file type: .{ext}")
+
+
+def chunk_text(text: str) -> List[str]:
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=settings.rag_chunk_size,
+        chunk_overlap=settings.rag_chunk_overlap,
+        separators=["\n\n", "\n", ". ", " ", ""],
+    )
+    return [c for c in splitter.split_text(text) if c.strip()]
+
+
+def chunk_segments(segments: List[dict[str, Any]]) -> List[dict[str, Any]]:
+    chunks: List[dict[str, Any]] = []
+    for segment in segments:
+        text = segment.get("text", "")
+        if not text.strip():
+            continue
+        for chunk in chunk_text(text):
+            chunks.append(
+                {
+                    "text": chunk,
+                    "page_number": segment.get("page_number"),
+                }
+            )
+    return chunks
+
+
+def validate_medical_document(filename: str, data: bytes) -> None:
+    segments = extract_segments(filename, data)
+    text = "\n".join(segment.get("text") or "" for segment in segments).strip()
+    if len(text) < MIN_MEDICAL_TEXT_CHARS:
+        raise ValueError("Not enough readable text found to verify this as a medical document.")
+
+    words = [
+        word.strip(".,;:!?()[]{}\"'").lower()
+        for word in text.split()
+    ]
+    words = [word for word in words if word]
+    if not words:
+        raise ValueError("No readable text found to verify this as a medical document.")
+
+    normalized_words = {
+        word[:-1] if word.endswith("s") else word
+        for word in words
+    }
+    keyword_hits = sum(
+        1 for word in words
+        if word in MEDICAL_KEYWORDS or (word.endswith("s") and word[:-1] in MEDICAL_KEYWORDS)
+    )
+    unique_keyword_hits = len(normalized_words & MEDICAL_KEYWORDS)
+    keyword_density = (keyword_hits / len(words)) * 1000
+
+    if unique_keyword_hits < MIN_MEDICAL_KEYWORD_HITS or keyword_density < MIN_MEDICAL_KEYWORD_DENSITY:
+        raise ValueError(
+            "This does not look like a medical document. Upload clinical notes, reports, "
+            "guidelines, research, or other healthcare material."
+        )
+
+
+async def ingest_document(
+    file: UploadFile,
+    title: str,
+    source: str | None,
+    user_id: str,
+    conversation_id: str,
+    db: AsyncSession,
+) -> str:
+    doc_id = str(uuid.uuid4())
+    filename = file.filename or "unknown"
+
+    record = DocumentRecord(
+        id=doc_id, filename=filename, title=title,
+        source=source, chunk_count=0, uploaded_by=user_id, conversation_id=conversation_id, status="processing",
+    )
+    db.add(record)
+    await db.commit()
+
+    try:
+        raw_bytes = await file.read()
+        logger.info(f"Ingesting '{filename}' ({len(raw_bytes):,} bytes)")
+        segments = extract_segments(filename, raw_bytes)
+        if not any((segment.get("text") or "").strip() for segment in segments):
+            raise ValueError("No extractable text found — file may be image-only.")
+
+        chunks = chunk_segments(segments)
+        logger.info(f"Split '{filename}' into {len(chunks)} chunks")
+
+        emb_svc = get_embedding_service()
+        embeddings = await emb_svc.embed_texts([chunk["text"] for chunk in chunks])
+
+        qdrant = get_qdrant_service()
+        await qdrant.ensure_collection()
+        n = await qdrant.upsert_chunks(
+            doc_id=doc_id, chunks=chunks, embeddings=embeddings,
+            metadata={
+                "filename": filename,
+                "title": title,
+                "source": source or "",
+                "conversation_id": record.conversation_id,
+            },
+        )
+
+        record.chunk_count = n
+        record.status = "ready"
+        await db.commit()
+        logger.success(f"Document {doc_id} ready ({n} chunks)")
+
+    except Exception as exc:
+        record.status = "error"
+        record.error_message = str(exc)
+        await db.commit()
+        logger.error(f"Ingestion failed for {doc_id}: {exc}")
+        raise
+
+    return doc_id
+
+
+async def create_document_record(
+    *,
+    filename: str,
+    title: str,
+    source: str | None,
+    user_id: str,
+    conversation_id: str,
+    db: AsyncSession,
+) -> str:
+    doc_id = str(uuid.uuid4())
+    record = DocumentRecord(
+        id=doc_id,
+        filename=filename,
+        title=title,
+        source=source,
+        chunk_count=0,
+        uploaded_by=user_id,
+        conversation_id=conversation_id,
+        status="processing",
+    )
+    db.add(record)
+    await db.commit()
+    return doc_id
+
+
+async def ingest_document_bytes(
+    *,
+    doc_id: str,
+    filename: str,
+    title: str,
+    source: str | None,
+    raw_bytes: bytes,
+    db: AsyncSession,
+) -> None:
+    record = await db.get(DocumentRecord, doc_id)
+    if not record:
+        raise ValueError(f"Document record not found: {doc_id}")
+
+    try:
+        logger.info(f"Ingesting '{filename}' ({len(raw_bytes):,} bytes)")
+        segments = extract_segments(filename, raw_bytes)
+        if not any((segment.get("text") or "").strip() for segment in segments):
+            raise ValueError("No extractable text found - file may be image-only.")
+
+        chunks = chunk_segments(segments)
+        logger.info(f"Split '{filename}' into {len(chunks)} chunks")
+
+        emb_svc = get_embedding_service()
+        embeddings = await emb_svc.embed_texts([chunk["text"] for chunk in chunks])
+
+        qdrant = get_qdrant_service()
+        await qdrant.ensure_collection()
+        n = await qdrant.upsert_chunks(
+            doc_id=doc_id, chunks=chunks, embeddings=embeddings,
+            metadata={
+                "filename": filename,
+                "title": title,
+                "source": source or "",
+                "conversation_id": record.conversation_id,
+            },
+        )
+
+        record.chunk_count = n
+        record.status = "ready"
+        record.error_message = None
+        await db.commit()
+        logger.success(f"Document {doc_id} ready ({n} chunks)")
+
+    except Exception as exc:
+        record.status = "error"
+        record.error_message = str(exc)
+        await db.commit()
+        logger.error(f"Ingestion failed for {doc_id}: {exc}")
+        raise
+
+
+async def ingest_document_background(
+    *,
+    doc_id: str,
+    filename: str,
+    title: str,
+    source: str | None,
+    raw_bytes: bytes,
+) -> None:
+    async with AsyncSessionLocal() as db:
+        await ingest_document_bytes(
+            doc_id=doc_id,
+            filename=filename,
+            title=title,
+            source=source,
+            raw_bytes=raw_bytes,
+            db=db,
+        )
+
+
+async def _run_ingestion_job(
+    *,
+    doc_id: str,
+    filename: str,
+    title: str,
+    source: str | None,
+    raw_bytes: bytes,
+) -> None:
+    try:
+        await ingest_document_background(
+            doc_id=doc_id,
+            filename=filename,
+            title=title,
+            source=source,
+            raw_bytes=raw_bytes,
+        )
+    except Exception:
+        # Errors are persisted onto the document record inside ingest_document_bytes.
+        logger.exception(f"Background ingestion crashed for doc {doc_id}")
+
+
+def schedule_ingestion(
+    *,
+    doc_id: str,
+    filename: str,
+    title: str,
+    source: str | None,
+    raw_bytes: bytes,
+) -> None:
+    task = asyncio.create_task(
+        _run_ingestion_job(
+            doc_id=doc_id,
+            filename=filename,
+            title=title,
+            source=source,
+            raw_bytes=raw_bytes,
+        )
+    )
+    _ingestion_tasks.add(task)
+    task.add_done_callback(_ingestion_tasks.discard)
+
+
+async def get_all_documents(db: AsyncSession) -> List[DocumentRecord]:
+    result = await db.execute(select(DocumentRecord).order_by(DocumentRecord.created_at.desc()))
+    return result.scalars().all()
+
+
+async def get_conversation_documents(conversation_id: str, db: AsyncSession) -> List[DocumentRecord]:
+    result = await db.execute(
+        select(DocumentRecord)
+        .where(DocumentRecord.conversation_id == conversation_id)
+        .order_by(DocumentRecord.created_at.desc())
+    )
+    return result.scalars().all()
+
+
+async def get_conversation_ready_document_count(conversation_id: str, db: AsyncSession) -> int:
+    result = await db.execute(
+        select(DocumentRecord)
+        .where(
+            DocumentRecord.conversation_id == conversation_id,
+            DocumentRecord.status == "ready",
+        )
+    )
+    return len(result.scalars().all())
+
+
+async def get_document(doc_id: str, db: AsyncSession) -> DocumentRecord | None:
+    result = await db.execute(select(DocumentRecord).where(DocumentRecord.id == doc_id))
+    return result.scalar_one_or_none()

app/services/llm_service.py

@@ -0,0 +1,141 @@
+"""
+LLM service — Groq API with Llama 4 Scout 17B.
+"""
+from __future__ import annotations
+from functools import lru_cache
+from typing import List
+
+from groq import AsyncGroq
+from loguru import logger
+
+from app.core.config import get_settings
+
+settings = get_settings()
+
+SYSTEM_PROMPT = """You are MedRAG, an expert medical knowledge assistant.
+You must answer accurately, conservatively, and only from the provided context.
+
+Rules:
+- Ground every factual claim in the provided sources only.
+- If the context is incomplete or conflicting, say so plainly.
+- Synthesize across multiple sources when possible instead of relying on one excerpt.
+- Prefer clear, clinically useful wording over vague summaries.
+- Keep the answer short by default: 2-4 sentences for ordinary questions.
+- Use bullets only when the user asks for a list or when brevity would be worse.
+- Do not mention internal retrieval labels like "Source 1" or "Source 2" in the answer.
+- Cite source titles inline only when needed for an important claim or ambiguity.
+- Never invent guidelines, dosages, diagnoses, or recommendations not supported by context.
+- Do not add a generic safety disclaimer unless the answer includes urgent-risk advice, diagnosis, treatment guidance, or the context specifically calls for it.
+
+Style:
+- Start with the direct answer immediately.
+- Avoid headings like "Direct answer", "Key details", or "Source-backed notes".
+- Avoid bracketed citations and source-number references in the prose.
+- Avoid padded phrasing and repetition.
+- If the user asks a simple definition, respond in one short paragraph."""
+
+
+class LLMService:
+    def __init__(self) -> None:
+        self._client = AsyncGroq(api_key=settings.groq_api_key)
+
+    def _build_context(self, chunks: List[dict]) -> str:
+        parts = []
+        for i, c in enumerate(chunks, 1):
+            page_label = f" | page {c.get('page_number')}" if c.get("page_number") else ""
+            parts.append(
+                f"[Document {i}: {c['title']} | {c['filename']}{page_label} | chunk {c.get('chunk_index', 0)}]\n"
+                f"{c['text']}"
+            )
+        return "\n\n---\n\n".join(parts)
+
+    async def rewrite_query_for_retrieval(self, query: str, conversation_history: List[dict]) -> str:
+        if not conversation_history:
+            return query
+
+        history_text = "\n".join(
+            f"{item['role']}: {item['content']}" for item in conversation_history if item.get("content")
+        )
+        response = await self._client.chat.completions.create(
+            model=settings.llm_model,
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "Rewrite the user's latest question into a standalone medical search query. "
+                        "Preserve key medical entities, symptoms, conditions, tests, and follow-up references. "
+                        "Return only the rewritten search query."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": f"Conversation:\n{history_text}\n\nLatest user question:\n{query}",
+                },
+            ],
+            max_tokens=96,
+            temperature=0.0,
+        )
+        rewritten = (response.choices[0].message.content or "").strip()
+        return rewritten or query
+
+    async def generate_answer(self, query: str, context_chunks: List[dict]) -> str:
+        context = self._build_context(context_chunks)
+        try:
+            response = await self._client.chat.completions.create(
+                model=settings.llm_model,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {
+                        "role": "user",
+                        "content": (
+                            f"Question:\n{query}\n\n"
+                            f"Retrieved medical context:\n{context}\n\n"
+                            "Answer the question using only the retrieved context. Keep it concise unless the user explicitly asks for more detail."
+                        ),
+                    },
+                ],
+                max_tokens=settings.llm_max_tokens,
+                temperature=settings.llm_temperature,
+            )
+            answer = (response.choices[0].message.content or "").strip()
+            if not answer:
+                raise RuntimeError("LLM returned an empty answer")
+            return answer
+        except Exception as e:
+            logger.error(f"Error generating RAG answer: {e}")
+            raise
+
+    async def generate_simple_response(self, prompt: str, system_prompt: str = SYSTEM_PROMPT) -> str:
+        """
+        Generates a simple response without RAG context.
+        """
+        try:
+            response = await self._client.chat.completions.create(
+                model=settings.llm_model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=settings.llm_max_tokens,
+                temperature=settings.llm_temperature,
+            )
+            return response.choices[0].message.content.strip()
+        except Exception as e:
+            logger.error(f"Error calling Groq API: {e}")
+            return f"Error: {e}"
+
+    async def health(self) -> str:
+        try:
+            r = await self._client.chat.completions.create(
+                model=settings.llm_model,
+                messages=[{"role": "user", "content": "ping"}],
+                max_tokens=5,
+            )
+            return "ok"
+        except Exception as exc:
+            return f"error: {exc}"
+
+
+@lru_cache(maxsize=1)
+def get_llm_service() -> LLMService:
+    return LLMService()

app/services/qdrant_service.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+import math
+import re
+import uuid
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import List, Dict, Any
+
+from qdrant_client import AsyncQdrantClient
+from qdrant_client.models import (
+    Distance, VectorParams, PointStruct,
+    Filter, FieldCondition, MatchValue, ScoredPoint, FilterSelector,
+)
+from loguru import logger
+from app.core.config import get_settings
+
+settings = get_settings()
+TOKEN_RE = re.compile(r"[a-zA-Z0-9]{3,}")
+
+
+@dataclass
+class RetrievedChunk:
+    id: str
+    payload: Dict[str, Any]
+    vector_score: float | None = None
+    lexical_score: float | None = None
+    hybrid_score: float | None = None
+    retrieval_method: str = "vector"
+    score: float = 0.0
+    retrieval_methods: set[str] = field(default_factory=set)
+
+
+def _tokenize(text: str) -> list[str]:
+    return TOKEN_RE.findall((text or "").lower())
+
+
+class QdrantService:
+    def __init__(self) -> None:
+        if settings.qdrant_path:
+            self.client = AsyncQdrantClient(path=settings.qdrant_path)
+        elif settings.qdrant_api_key:
+            self.client = AsyncQdrantClient(url=f"https://{settings.qdrant_host}", api_key=settings.qdrant_api_key)
+        else:
+            self.client = AsyncQdrantClient(host=settings.qdrant_host, port=settings.qdrant_port)
+
+    async def ensure_collection(self) -> None:
+        exists = await self.client.collection_exists(settings.qdrant_collection_name)
+        if not exists:
+            await self.client.create_collection(
+                collection_name=settings.qdrant_collection_name,
+                vectors_config=VectorParams(size=settings.qdrant_vector_size, distance=Distance.COSINE),
+            )
+            logger.info(f"Created collection: {settings.qdrant_collection_name}")
+
+    async def upsert_chunks(self, doc_id: str, chunks: List[Dict[str, Any]], embeddings: List[List[float]], metadata: Dict[str, Any]) -> int:
+        points = [
+            PointStruct(
+                id=str(uuid.uuid4()),
+                vector=emb,
+                payload={
+                    "doc_id": doc_id,
+                    "chunk_index": i,
+                    "text": chunk.get("text", ""),
+                    "page_number": chunk.get("page_number"),
+                    "filename": metadata.get("filename", ""),
+                    "title": metadata.get("title", ""),
+                    "source": metadata.get("source", ""),
+                    "conversation_id": metadata.get("conversation_id", ""),
+                    "namespace": settings.qdrant_namespace,
+                },
+            )
+            for i, (chunk, emb) in enumerate(zip(chunks, embeddings))
+        ]
+        await self.client.upsert(collection_name=settings.qdrant_collection_name, points=points)
+        logger.info(f"Upserted {len(points)} chunks for doc {doc_id}")
+        return len(points)
+
+    def _scope_filter(self, conversation_id: str | None = None) -> Filter:
+        must = [FieldCondition(key="namespace", match=MatchValue(value=settings.qdrant_namespace))]
+        if conversation_id:
+            must.append(FieldCondition(key="conversation_id", match=MatchValue(value=conversation_id)))
+        return Filter(must=must)
+
+    async def search(self, query_vector: List[float], top_k: int = 20, conversation_id: str | None = None) -> List[ScoredPoint]:
+        return await self.client.search(
+            collection_name=settings.qdrant_collection_name,
+            query_vector=query_vector,
+            limit=top_k,
+            with_payload=True,
+            query_filter=self._scope_filter(conversation_id),
+        )
+
+    async def vector_search(self, query_vector: List[float], top_k: int = 20, conversation_id: str | None = None) -> List[RetrievedChunk]:
+        points = await self.search(query_vector=query_vector, top_k=top_k, conversation_id=conversation_id)
+        return [
+            RetrievedChunk(
+                id=str(point.id),
+                payload=dict(point.payload or {}),
+                vector_score=float(point.score),
+                retrieval_method="vector",
+                score=float(point.score),
+                retrieval_methods={"vector"},
+            )
+            for point in points
+        ]
+
+    async def lexical_search(self, query: str, top_k: int = 20, conversation_id: str | None = None) -> List[RetrievedChunk]:
+        query_tokens = _tokenize(query)
+        if not query_tokens:
+            return []
+
+        query_counts: dict[str, int] = {}
+        for token in query_tokens:
+            query_counts[token] = query_counts.get(token, 0) + 1
+
+        scored: list[RetrievedChunk] = []
+        offset = None
+        while True:
+            points, offset = await self.client.scroll(
+                collection_name=settings.qdrant_collection_name,
+                scroll_filter=self._scope_filter(conversation_id),
+                with_payload=True,
+                with_vectors=False,
+                limit=256,
+                offset=offset,
+            )
+            for point in points:
+                payload = dict(point.payload or {})
+                text_tokens = _tokenize(payload.get("text", ""))
+                if not text_tokens:
+                    continue
+                text_counts: dict[str, int] = {}
+                for token in text_tokens:
+                    text_counts[token] = text_counts.get(token, 0) + 1
+
+                overlap = 0.0
+                for token, q_count in query_counts.items():
+                    overlap += min(q_count, text_counts.get(token, 0))
+                if overlap <= 0:
+                    continue
+
+                norm = math.sqrt(len(query_tokens) * len(text_tokens))
+                lexical_score = overlap / norm if norm else 0.0
+                scored.append(
+                    RetrievedChunk(
+                        id=str(point.id),
+                        payload=payload,
+                        lexical_score=lexical_score,
+                        retrieval_method="lexical",
+                        score=lexical_score,
+                        retrieval_methods={"lexical"},
+                    )
+                )
+            if offset is None:
+                break
+
+        scored.sort(key=lambda item: item.lexical_score or 0.0, reverse=True)
+        return scored[:top_k]
+
+    async def delete_by_doc_id(self, doc_id: str) -> None:
+        await self.client.delete(
+            collection_name=settings.qdrant_collection_name,
+            points_selector=FilterSelector(
+                filter=Filter(
+                    must=[
+                        FieldCondition(key="doc_id", match=MatchValue(value=doc_id)),
+                        FieldCondition(key="namespace", match=MatchValue(value=settings.qdrant_namespace)),
+                    ]
+                )
+            ),
+        )
+        logger.info(f"Deleted vectors for doc {doc_id}")
+
+    async def health(self) -> str:
+        try:
+            await self.client.get_collections()
+            return "ok"
+        except Exception as exc:
+            return f"error: {exc}"
+
+
+@lru_cache(maxsize=1)
+def get_qdrant_service() -> QdrantService:
+    return QdrantService()

app/services/rag_pipeline.py

@@ -0,0 +1,226 @@
+"""
+RAG pipeline: conversational rewrite -> hybrid retrieve -> rerank -> generate -> persist.
+"""
+from __future__ import annotations
+from collections import defaultdict
+import json
+import time
+
+from app.core.config import get_settings
+from app.schemas.schemas import QueryRequest, QueryResponse, SourceChunk
+from app.services.embedding_service import get_embedding_service
+from app.services.qdrant_service import RetrievedChunk, get_qdrant_service
+from app.services.reranker_service import get_reranker_service
+from app.services.llm_service import get_llm_service
+from app.db import chat_db
+
+settings = get_settings()
+
+
+def _diversify_ranked_results(ranked: list[tuple], top_k: int) -> list[tuple]:
+    """Keep the final context from being dominated by one document."""
+    per_doc_counts = defaultdict(int)
+    diversified = []
+
+    for point, score in ranked:
+        doc_id = str(point.payload.get("doc_id", ""))
+        if per_doc_counts[doc_id] >= settings.reranker_max_chunks_per_doc:
+            continue
+        diversified.append((point, score))
+        per_doc_counts[doc_id] += 1
+        if len(diversified) >= top_k:
+            break
+
+    return diversified
+
+
+def _filter_ranked_results_by_score(ranked: list[tuple], min_score: float) -> list[tuple]:
+    return [(point, score) for point, score in ranked if float(score) >= min_score]
+
+
+def _filter_ranked_results_by_top_window(ranked: list[tuple], window: float) -> list[tuple]:
+    if not ranked:
+        return []
+    top_score = float(ranked[0][1])
+    min_allowed = top_score - window
+    return [(point, score) for point, score in ranked if float(score) >= min_allowed]
+
+
+def _build_conversation_history(messages: list, max_turns: int) -> list[dict]:
+    recent = messages[-max_turns:] if max_turns > 0 else []
+    return [{"role": msg.role, "content": msg.content} for msg in recent]
+
+
+def _hybrid_merge(vector_hits: list[RetrievedChunk], lexical_hits: list[RetrievedChunk]) -> list[RetrievedChunk]:
+    merged: dict[str, RetrievedChunk] = {}
+    rrf_k = settings.rag_hybrid_rrf_k
+
+    for rank, item in enumerate(vector_hits, start=1):
+        existing = merged.get(item.id)
+        contribution = 1.0 / (rrf_k + rank)
+        if existing is None:
+            item.hybrid_score = contribution
+            item.retrieval_methods = {"vector"}
+            merged[item.id] = item
+        else:
+            existing.vector_score = item.vector_score
+            existing.hybrid_score = (existing.hybrid_score or 0.0) + contribution
+            existing.retrieval_methods.add("vector")
+
+    for rank, item in enumerate(lexical_hits, start=1):
+        existing = merged.get(item.id)
+        contribution = 1.0 / (rrf_k + rank)
+        if existing is None:
+            item.hybrid_score = contribution
+            item.retrieval_methods = {"lexical"}
+            merged[item.id] = item
+        else:
+            existing.lexical_score = item.lexical_score
+            existing.hybrid_score = (existing.hybrid_score or 0.0) + contribution
+            existing.retrieval_methods.add("lexical")
+
+    merged_hits = list(merged.values())
+    for item in merged_hits:
+        item.score = float(item.hybrid_score or 0.0)
+        if item.retrieval_methods == {"vector", "lexical"}:
+            item.retrieval_method = "hybrid"
+        elif "lexical" in item.retrieval_methods:
+            item.retrieval_method = "lexical"
+        else:
+            item.retrieval_method = "vector"
+
+    merged_hits.sort(key=lambda item: item.hybrid_score or 0.0, reverse=True)
+    return merged_hits
+
+
+async def run_rag_pipeline(request: QueryRequest, user_id: str) -> QueryResponse:
+    emb_svc = get_embedding_service()
+    qdrant = get_qdrant_service()
+    reranker = get_reranker_service()
+    llm = get_llm_service()
+
+    history_messages = await chat_db.get_messages(user_id, request.conversation_id)
+    conversation_history = _build_conversation_history(history_messages, settings.rag_conversation_history_turns)
+    search_query = await llm.rewrite_query_for_retrieval(request.query, conversation_history)
+
+    t0 = time.perf_counter()
+    query_vector = await emb_svc.embed_query(search_query)
+    vector_hits = await qdrant.vector_search(
+        query_vector=query_vector,
+        top_k=settings.rag_retrieval_top_k,
+        conversation_id=request.conversation_id,
+    )
+    lexical_hits = await qdrant.lexical_search(
+        query=search_query,
+        top_k=settings.rag_retrieval_top_k,
+        conversation_id=request.conversation_id,
+    )
+    candidates = _hybrid_merge(vector_hits, lexical_hits)
+    t_retrieval = (time.perf_counter() - t0) * 1000
+
+    t1 = time.perf_counter()
+    requested_top_k = request.top_k or settings.reranker_top_k
+    ranked = await reranker.rerank(
+        query=search_query,
+        candidates=candidates,
+        text_fn=lambda c: c.payload.get("text", ""),
+        top_k=max(requested_top_k * 3, settings.reranker_top_k),
+    )
+    ranked = _filter_ranked_results_by_score(ranked, settings.reranker_min_score)
+    ranked = _filter_ranked_results_by_top_window(ranked, settings.reranker_score_window)
+    ranked = _diversify_ranked_results(ranked, requested_top_k)
+    t_rerank = (time.perf_counter() - t1) * 1000
+
+    if ranked:
+        context_chunks = [
+            {
+                "text": point.payload.get("text", ""),
+                "title": point.payload.get("title", ""),
+                "filename": point.payload.get("filename", ""),
+                "doc_id": point.payload.get("doc_id", ""),
+                "chunk_index": point.payload.get("chunk_index", 0),
+                "page_number": point.payload.get("page_number"),
+                "score": float(score),
+                "retrieval_method": getattr(point, "retrieval_method", "hybrid"),
+            }
+            for point, score in ranked
+        ]
+        no_results = False
+    else:
+        context_chunks = []
+        no_results = True
+
+    t2 = time.perf_counter()
+    if no_results:
+        answer = (
+            "I couldn't find relevant information in the knowledge base "
+            "to answer your question. Please ensure relevant medical documents "
+            "have been uploaded, or rephrase your question."
+        )
+    else:
+        answer = await llm.generate_answer(request.query, context_chunks)
+    t_gen = (time.perf_counter() - t2) * 1000
+
+    sources = [
+        SourceChunk(
+            doc_id=c["doc_id"],
+            filename=c["filename"],
+            title=c["title"],
+            chunk_index=c["chunk_index"],
+            page_number=c.get("page_number"),
+            text=c["text"],
+            score=round(c["score"], 4),
+            retrieval_method=c.get("retrieval_method"),
+        )
+        for c in context_chunks
+    ]
+
+    await chat_db.add_message(
+        user_id=user_id,
+        conv_id=request.conversation_id,
+        role="user",
+        content=request.query,
+    )
+
+    sources_json = json.dumps([s.model_dump() for s in sources])
+    meta_json = json.dumps({
+        "model": settings.llm_model,
+        "search_query": search_query,
+        "retrieval_strategy": "conversational-hybrid-rag+rerank",
+        "conversation_turns_used": len(conversation_history),
+        "retrieval_ms": round(t_retrieval, 2),
+        "rerank_ms": round(t_rerank, 2),
+        "generation_ms": round(t_gen, 2),
+        "source_count": len(sources),
+        "vector_candidates": len(vector_hits),
+        "lexical_candidates": len(lexical_hits),
+        "reranker_min_score": settings.reranker_min_score,
+        "reranker_score_window": settings.reranker_score_window,
+    })
+    asst_msg = await chat_db.add_message(
+        user_id=user_id,
+        conv_id=request.conversation_id,
+        role="assistant",
+        content=answer,
+        sources_json=sources_json,
+        meta_json=meta_json,
+    )
+
+    messages = await chat_db.get_messages(user_id, request.conversation_id)
+    if len(messages) <= 2:
+        await chat_db.auto_title_conversation(user_id, request.conversation_id, request.query)
+
+    return QueryResponse(
+        message_id=asst_msg.id,
+        conversation_id=request.conversation_id,
+        query=request.query,
+        search_query=search_query,
+        answer=answer,
+        sources=sources,
+        model=settings.llm_model,
+        retrieval_strategy="conversational-hybrid-rag+rerank",
+        conversation_turns_used=len(conversation_history),
+        retrieval_ms=round(t_retrieval, 2),
+        rerank_ms=round(t_rerank, 2),
+        generation_ms=round(t_gen, 2),
+    )

app/services/reranker_service.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+import asyncio
+from functools import lru_cache
+from typing import List, Tuple, TypeVar, Callable
+
+from sentence_transformers.cross_encoder import CrossEncoder
+from loguru import logger
+from app.core.config import get_settings
+
+settings = get_settings()
+T = TypeVar("T")
+
+
+class RerankerService:
+    _model: CrossEncoder | None = None
+
+    def _load(self) -> CrossEncoder:
+        if self._model is None:
+            logger.info(f"Loading reranker: {settings.reranker_model}")
+            self._model = CrossEncoder(settings.reranker_model, max_length=512)
+        return self._model
+
+    async def rerank(
+        self,
+        query: str,
+        candidates: List[T],
+        text_fn: Callable[[T], str],
+        top_k: int | None = None,
+    ) -> List[Tuple[T, float]]:
+        if not candidates:
+            return []
+        k = top_k or settings.reranker_top_k
+        model = self._load()
+        pairs = [(query, text_fn(c)) for c in candidates]
+        loop = asyncio.get_running_loop()
+        scores: List[float] = await loop.run_in_executor(None, lambda: model.predict(pairs).tolist())
+        ranked = sorted(zip(candidates, scores), key=lambda x: x[1], reverse=True)
+        return ranked[:k]
+
+
+@lru_cache(maxsize=1)
+def get_reranker_service() -> RerankerService:
+    return RerankerService()

app/services/speech_service.py

@@ -0,0 +1,245 @@
+import torch
+from qwen_asr import Qwen3ASRModel
+from loguru import logger
+import os
+from functools import lru_cache
+from app.core.config import get_settings
+
+settings = get_settings()
+
+class SpeechService:
+    def __init__(self, model_name: str = "Qwen/Qwen3-ASR-1.7B", device: str = None):
+        """
+        Initializes the Qwen-ASR model for speech-to-text.
+        """
+        if device is None:
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        else:
+            self.device = device
+            
+        logger.info(f"Initializing SpeechService with model {model_name} on {self.device}")
+        
+        try:
+            # Load the model with bfloat16 for better performance if on CUDA
+            dtype = torch.bfloat16 if self.device == "cuda" else torch.float32
+            
+            self.model = Qwen3ASRModel.from_pretrained(
+                model_name,
+                dtype=dtype,
+                device_map=self.device if self.device == "cuda" else None
+            )
+            logger.success("SpeechService initialized successfully")
+        except Exception as e:
+            logger.error(f"Failed to initialize SpeechService: {e}")
+            raise
+
+    def transcribe(self, audio_data, language: str = None) -> str:
+        """
+        Transcribes audio (file path or numpy array) to text.
+        
+        Args:
+            audio_data: Path to the audio file OR numpy array of audio data.
+            language: Optional language hint.
+        
+        Returns:
+            The transcribed text.
+        """
+        import numpy as np
+        import soundfile as sf
+        import tempfile
+
+        temp_file = None
+        try:
+            if isinstance(audio_data, str):
+                if not os.path.exists(audio_data):
+                    logger.error(f"Audio file not found: {audio_data}")
+                    raise FileNotFoundError(f"Audio file not found: {audio_data}")
+                logger.info(f"Transcribing audio file: {audio_data}")
+                input_audio = [audio_data]
+            elif isinstance(audio_data, np.ndarray):
+                logger.info("Transcribing audio buffer (NumPy array)")
+                # Save to a temporary file as Qwen-ASR expects file paths
+                temp_file = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+                sf.write(temp_file.name, audio_data, 16000)
+                temp_file.close() # Close so the model can read it
+                input_audio = [temp_file.name]
+            else:
+                # If it's already a list or something else, pass it through
+                input_audio = audio_data
+
+            results = self.model.transcribe(
+                audio=input_audio,
+                language=[language] if language else None
+            )
+            
+            if results and len(results) > 0:
+                transcription = results[0].text
+                logger.info(f"Transcription successful: {transcription[:50]}...")
+                return transcription
+            else:
+                logger.warning("No transcription results returned")
+                return ""
+        except Exception as e:
+            logger.error(f"Error during transcription: {e}")
+            raise
+        finally:
+            # Clean up temporary file
+            if temp_file and os.path.exists(temp_file.name):
+                try:
+                    os.unlink(temp_file.name)
+                except Exception as cleanup_err:
+                    logger.warning(f"Failed to delete temp file {temp_file.name}: {cleanup_err}")
+
+    def record_and_transcribe(self, duration: int = 5, sample_rate: int = 16000) -> str:
+        """
+        Records audio from the microphone for a fixed duration and transcribes it.
+        
+        Args:
+            duration: Recording duration in seconds.
+            sample_rate: Sample rate for recording.
+            
+        Returns:
+            The transcribed text.
+        """
+        import sounddevice as sd
+        import numpy as np
+        
+        logger.info(f"Recording for {duration} seconds...")
+        # sd.rec is non-blocking, so we need to wait
+        recording = sd.rec(int(duration * sample_rate), samplerate=sample_rate, channels=1)
+        sd.wait() # Wait until recording is finished
+        
+        audio_data = recording.flatten()
+        return self.transcribe(audio_data)
+
+    def transcribe_stream(self, callback_fn, chunk_duration: int = 5, sample_rate: int = 16000):
+        """
+        Captures audio from the microphone and transcribes it in real-time.
+        
+        Args:
+            callback_fn: Function to call with each transcription result.
+            chunk_duration: Duration of each audio chunk in seconds.
+            sample_rate: Sample rate for recording (default 16000Hz as required by Qwen-ASR).
+        """
+        import sounddevice as sd
+        import numpy as np
+
+        logger.info(f"Starting microphone stream ({chunk_duration}s chunks)...")
+        
+        def sd_callback(indata, frames, time, status):
+            if status:
+                logger.warning(f"Sounddevice status: {status}")
+            
+            audio_chunk = indata.copy().flatten()
+            try:
+                # Transcribe the chunk
+                text = self.transcribe(audio_chunk)
+                if text.strip():
+                    callback_fn(text)
+            except Exception as e:
+                logger.error(f"Error in stream transcription: {e}")
+
+        block_size = int(sample_rate * chunk_duration)
+        
+        try:
+            with sd.InputStream(samplerate=sample_rate, 
+                                channels=1, 
+                                callback=sd_callback, 
+                                blocksize=block_size):
+                logger.info("Microphone is live. Press Ctrl+C to stop.")
+                while True:
+                    sd.sleep(1000)
+        except KeyboardInterrupt:
+            logger.info("Microphone stream stopped by user.")
+        except Exception as e:
+            logger.error(f"Error in microphone stream: {e}")
+            raise
+
+
+class KokoroTTSService:
+    SAMPLE_RATE = 24000
+
+    def __init__(self, device: str = None):
+        if device is None:
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        else:
+            self.device = device
+
+        self._pipelines = {}
+        logger.info(f"Initializing KokoroTTSService on {self.device}")
+
+    def preload(self, voice: str = "af_heart") -> None:
+        """Preloads the TTS model pipeline."""
+        logger.info(f"Preloading Kokoro TTS pipeline for voice: {voice}")
+        self._get_pipeline(voice)
+
+    def _get_pipeline(self, voice: str):
+        lang_code = (voice or "af_heart")[0].lower()
+        pipeline = self._pipelines.get(lang_code)
+        if pipeline is not None:
+            return pipeline
+
+        try:
+            from kokoro import KPipeline
+        except ImportError as exc:
+            logger.error(f"Kokoro TTS dependency is unavailable: {exc}")
+            raise RuntimeError(
+                "Kokoro TTS is not installed. Run pip install -r requirements.txt."
+            ) from exc
+
+        pipeline = KPipeline(lang_code=lang_code, device=self.device)
+        self._pipelines[lang_code] = pipeline
+        return pipeline
+
+    def speak(self, text: str, voice: str = "af_heart", speed: float = 1.0, play: bool = False):
+        import numpy as np
+
+        if not text or not text.strip():
+            raise ValueError("Text-to-speech requires non-empty text")
+
+        pipeline = self._get_pipeline(voice)
+        chunks = []
+        for result in pipeline(text.strip(), voice=voice, speed=speed, split_pattern=r"\n+"):
+            audio = result.audio
+            if audio is None:
+                continue
+            if hasattr(audio, "detach"):
+                audio = audio.detach()
+            if hasattr(audio, "cpu"):
+                audio = audio.cpu()
+            if hasattr(audio, "numpy"):
+                audio = audio.numpy()
+            chunks.append(np.asarray(audio, dtype=np.float32).reshape(-1))
+
+        if not chunks:
+            raise RuntimeError("Text-to-speech produced no audio")
+
+        waveform = np.concatenate(chunks)
+
+        if play:
+            try:
+                import sounddevice as sd
+
+                sd.play(waveform, self.SAMPLE_RATE)
+                sd.wait()
+            except Exception as exc:
+                logger.warning(f"Unable to play generated audio: {exc}")
+
+        return waveform, self.SAMPLE_RATE
+
+# Global instance for easy access
+speech_service = None
+
+def get_speech_service():
+    global speech_service
+    if speech_service is None:
+        speech_service = SpeechService(
+            model_name=settings.speech_model,
+            device=settings.speech_device
+        )
+    return speech_service
+
+
+@lru_cache()
+def get_tts_service():
+    return KokoroTTSService()

app/services/stt_service.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import tempfile
+from functools import lru_cache
+from typing import Any
+
+from fastapi import HTTPException, UploadFile, status
+
+from app.core.config import Settings, get_settings
+
+
+class QwenSTTService:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self._model: Any | None = None
+
+    def _resolve_device(self) -> str:
+        if self.settings.stt_device != "auto":
+            return self.settings.stt_device
+
+        try:
+            import torch
+
+            return "cuda:0" if torch.cuda.is_available() else "cpu"
+        except Exception:
+            return "cpu"
+
+    def _resolve_dtype(self):
+        if self.settings.stt_dtype != "auto":
+            return self.settings.stt_dtype
+
+        try:
+            import torch
+
+            if self._resolve_device().startswith("cuda"):
+                return torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
+            return torch.float32
+        except Exception:
+            return "float32"
+
+    def _load_model(self):
+        if self._model is not None:
+            return self._model
+
+        try:
+            from qwen_asr import Qwen3ASRModel
+        except ImportError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Qwen ASR dependencies are not installed. Run pip install -r requirements.txt.",
+            ) from exc
+
+        self._model = Qwen3ASRModel.from_pretrained(
+            self.settings.stt_model,
+            device_map=self._resolve_device(),
+            dtype=self._resolve_dtype(),
+            max_new_tokens=self.settings.stt_max_new_tokens,
+        )
+        hf_model = getattr(self._model, "model", None)
+        processor = getattr(self._model, "processor", None)
+        tokenizer = getattr(processor, "tokenizer", None)
+
+        if hf_model is not None and hasattr(hf_model, "generation_config"):
+            generation_config = hf_model.generation_config
+            generation_config.max_new_tokens = self.settings.stt_max_new_tokens
+            generation_config.do_sample = False
+            if hasattr(generation_config, "temperature"):
+                generation_config.temperature = None
+            if tokenizer is not None:
+                eos_token_id = getattr(tokenizer, "eos_token_id", None)
+                pad_token_id = getattr(tokenizer, "pad_token_id", None) or eos_token_id
+                if pad_token_id is not None:
+                    generation_config.pad_token_id = pad_token_id
+                    if getattr(tokenizer, "pad_token_id", None) is None:
+                        tokenizer.pad_token_id = pad_token_id
+                if eos_token_id is not None:
+                    generation_config.eos_token_id = eos_token_id
+
+        return self._model
+
+    def _transcribe_sync(self, audio_path: str) -> dict[str, Any]:
+        model = self._load_model()
+        result = model.transcribe(
+            audio=audio_path,
+            context=self.settings.stt_context,
+            language=self.settings.stt_language,
+        )
+
+        if isinstance(result, (list, tuple)) and result:
+            first = result[0]
+            return {
+                "text": str(getattr(first, "text", "")).strip(),
+                "language": getattr(first, "language", None) or self.settings.stt_language,
+                "duration_seconds": getattr(first, "duration_seconds", None),
+            }
+
+        if isinstance(result, str):
+            return {"text": result.strip(), "language": self.settings.stt_language}
+
+        if isinstance(result, dict):
+            text = str(result.get("text", "")).strip()
+            return {
+                "text": text,
+                "language": result.get("language") or self.settings.stt_language,
+                "duration_seconds": result.get("duration_seconds"),
+            }
+
+        if hasattr(result, "text"):
+            return {
+                "text": str(getattr(result, "text", "")).strip(),
+                "language": getattr(result, "language", None) or self.settings.stt_language,
+                "duration_seconds": getattr(result, "duration_seconds", None),
+            }
+
+        text = str(result).strip()
+        return {"text": text, "language": self.settings.stt_language}
+
+    async def transcribe_upload(self, audio_file: UploadFile) -> dict[str, Any]:
+        if not self.settings.stt_enabled:
+            raise HTTPException(status_code=503, detail="Speech-to-text is disabled")
+
+        suffix = os.path.splitext(audio_file.filename or "audio.webm")[1] or ".webm"
+        raw_audio = await audio_file.read()
+        if not raw_audio:
+            raise HTTPException(status_code=400, detail="Uploaded audio file is empty")
+
+        temp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as temp_file:
+                temp_file.write(raw_audio)
+                temp_path = temp_file.name
+
+            transcript = await asyncio.to_thread(self._transcribe_sync, temp_path)
+        except HTTPException:
+            raise
+        except Exception as exc:
+            raise HTTPException(
+                status_code=500,
+                detail=f"Speech transcription failed: {exc}",
+            ) from exc
+        finally:
+            if temp_path and os.path.exists(temp_path):
+                try:
+                    os.remove(temp_path)
+                except OSError:
+                    pass
+
+        if not transcript.get("text"):
+            raise HTTPException(status_code=422, detail="No speech was detected in the audio")
+
+        return transcript
+
+    async def preload(self) -> None:
+        await asyncio.to_thread(self._load_model)
+
+
+@lru_cache()
+def get_stt_service() -> QwenSTTService:
+    return QwenSTTService(get_settings())

frontend/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>MedRAG — Medical Knowledge Assistant</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=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🏥</text></svg>" />
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.jsx"></script>
+</body>
+</html>

frontend/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "medrag-frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "zustand": "^5.0.2",
+    "axios": "^1.7.9",
+    "react-markdown": "^9.0.1",
+    "remark-gfm": "^4.0.0",
+    "lucide-react": "^0.468.0",
+    "clsx": "^2.1.1",
+    "react-hot-toast": "^2.4.1",
+    "framer-motion": "^11.15.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.17",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "vite": "^6.0.5"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,3 @@
+export default {
+  plugins: { tailwindcss: {}, autoprefixer: {} },
+}

frontend/src/App.jsx

@@ -0,0 +1,60 @@
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { Toaster } from 'react-hot-toast'
+import { useEffect } from 'react'
+import { useAuthStore } from './store'
+import { RequireAuth, RequireAdmin } from './components/ui/ProtectedRoute'
+import AuthPage from './pages/AuthPage'
+import ChatPage from './pages/ChatPage'
+import AdminPage from './pages/AdminPage'
+
+function AppInit({ children }) {
+  const { isAuthenticated, loadMe } = useAuthStore()
+  useEffect(() => {
+    if (isAuthenticated) loadMe()
+  }, [])
+  return children
+}
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <AppInit>
+        <Routes>
+          <Route path="/login" element={<AuthPage />} />
+          <Route
+            path="/"
+            element={
+              <RequireAuth>
+                <ChatPage />
+              </RequireAuth>
+            }
+          />
+          <Route
+            path="/admin"
+            element={
+              <RequireAdmin>
+                <AdminPage />
+              </RequireAdmin>
+            }
+          />
+          <Route path="*" element={<Navigate to="/" replace />} />
+        </Routes>
+      </AppInit>
+
+      <Toaster
+        position="top-right"
+        toastOptions={{
+          style: {
+            background: '#18181f',
+            color: '#e8e8f0',
+            border: '1px solid rgba(255,255,255,0.08)',
+            borderRadius: '12px',
+            fontSize: '13px',
+          },
+          success: { iconTheme: { primary: '#00c9a7', secondary: '#18181f' } },
+          error: { iconTheme: { primary: '#f87171', secondary: '#18181f' } },
+        }}
+      />
+    </BrowserRouter>
+  )
+}

frontend/src/api/client.js

@@ -0,0 +1,104 @@
+import axios from 'axios'
+
+const api = axios.create({ baseURL: '/api/v1' })
+const AUTH_PATHS = ['/auth/login', '/auth/register', '/auth/refresh']
+
+// Attach access token to every request
+api.interceptors.request.use((config) => {
+  const token = localStorage.getItem('access_token')
+  if (token) config.headers.Authorization = `Bearer ${token}`
+  return config
+})
+
+// Auto-refresh on 401
+api.interceptors.response.use(
+  (res) => res,
+  async (err) => {
+    const original = err.config || {}
+    const requestUrl = original.url || ''
+    const isAuthRequest = AUTH_PATHS.some((path) => requestUrl.includes(path))
+
+    if (err.response?.status === 401 && !original._retry && !isAuthRequest) {
+      original._retry = true
+      try {
+        const refresh = localStorage.getItem('refresh_token')
+        if (!refresh) throw new Error('Missing refresh token')
+        const { data } = await axios.post('/api/v1/auth/refresh', { refresh_token: refresh })
+        localStorage.setItem('access_token', data.access_token)
+        localStorage.setItem('refresh_token', data.refresh_token)
+        original.headers.Authorization = `Bearer ${data.access_token}`
+        return api(original)
+      } catch {
+        localStorage.clear()
+        window.location.href = '/login'
+      }
+    }
+    return Promise.reject(err)
+  }
+)
+
+export function getApiErrorMessage(err, fallback = 'Something went wrong') {
+  const detail = err?.response?.data?.detail
+  if (typeof detail === 'string' && detail.trim()) return detail
+  if (Array.isArray(detail) && detail.length) {
+    return detail.map((item) => item?.msg || item).filter(Boolean).join(', ')
+  }
+  return fallback
+}
+
+// ─── Auth ──────────────────────────────────────────────────────────────────────
+export const authApi = {
+  register: (d) => api.post('/auth/register', d).then(r => r.data),
+  login: (d) => api.post('/auth/login', d).then(r => r.data),
+  me: () => api.get('/auth/me').then(r => r.data),
+}
+
+// ─── Conversations ─────────────────────────────────────────────────────────────
+export const convApi = {
+  list: () => api.get('/conversations').then(r => r.data),
+  create: (title = 'New Chat') => api.post('/conversations', { title }).then(r => r.data),
+  messages: (id) => api.get(`/conversations/${id}/messages`).then(r => r.data),
+  rename: (id, title) => api.patch(`/conversations/${id}`, { title }).then(r => r.data),
+  delete: (id) => api.delete(`/conversations/${id}`),
+}
+
+// ─── Query ─────────────────────────────────────────────────────────────────────
+export const queryApi = {
+  ask: (payload) => api.post('/query', payload).then(r => r.data),
+}
+
+export const audioApi = {
+  transcribe: (formData) => api.post('/audio/transcribe', formData, {
+    headers: { 'Content-Type': 'multipart/form-data' }
+  }).then(r => r.data),
+  speak: (payload) => api.post('/audio/speak', payload, {
+    responseType: 'blob',
+  }).then(r => r.data),
+}
+
+// ─── Documents ─────────────────────────────────────────────────────────────────
+export const docsApi = {
+  list: (conversationId) => api.get('/documents', {
+    params: conversationId ? { conversation_id: conversationId } : undefined,
+  }).then(r => r.data),
+  upload: (formData) => api.post('/documents/upload', formData, {
+    headers: { 'Content-Type': 'multipart/form-data' }
+  }).then(r => r.data),
+  clearConversation: (conversationId) => api.delete(`/documents/conversation/${conversationId}`),
+  delete: (id) => api.delete(`/documents/${id}`),
+}
+
+// ─── Admin ─────────────────────────────────────────────────────────────────────
+export const adminApi = {
+  stats: () => api.get('/admin/stats').then(r => r.data),
+  users: () => api.get('/admin/users').then(r => r.data),
+  setRole: (id, role) => api.patch(`/admin/users/${id}/role`, null, { params: { role } }).then(r => r.data),
+  toggle: (id) => api.patch(`/admin/users/${id}/toggle`).then(r => r.data),
+}
+
+// ─── Health ────────────────────────────────────────────────────────────────────
+export const healthApi = {
+  check: () => api.get('/health').then(r => r.data),
+}
+
+export default api

frontend/src/components/chat/ChatInput.jsx

@@ -0,0 +1,442 @@
+import { useEffect, useRef, useState } from 'react'
+import { LoaderCircle, Mic, Paperclip, Plus, Send, Square } from 'lucide-react'
+import clsx from 'clsx'
+import toast from 'react-hot-toast'
+
+import { audioApi, getApiErrorMessage } from '../../api/client'
+
+const SAMPLE_RATE = 16000
+const MIN_RECORDING_SECONDS = 0.5
+const TARGET_PEAK = 0.92
+const LOW_INPUT_LEVEL = 0.015
+
+function floatTo16BitPCM(view, offset, input) {
+  for (let i = 0; i < input.length; i += 1) {
+    const sample = Math.max(-1, Math.min(1, input[i]))
+    view.setInt16(offset, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true)
+    offset += 2
+  }
+}
+
+function encodeWav(samples, sampleRate) {
+  const buffer = new ArrayBuffer(44 + samples.length * 2)
+  const view = new DataView(buffer)
+  const writeString = (offset, value) => {
+    for (let i = 0; i < value.length; i += 1) {
+      view.setUint8(offset + i, value.charCodeAt(i))
+    }
+  }
+
+  writeString(0, 'RIFF')
+  view.setUint32(4, 36 + samples.length * 2, true)
+  writeString(8, 'WAVE')
+  writeString(12, 'fmt ')
+  view.setUint32(16, 16, true)
+  view.setUint16(20, 1, true)
+  view.setUint16(22, 1, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, sampleRate * 2, true)
+  view.setUint16(32, 2, true)
+  view.setUint16(34, 16, true)
+  writeString(36, 'data')
+  view.setUint32(40, samples.length * 2, true)
+  floatTo16BitPCM(view, 44, samples)
+  return new Blob([buffer], { type: 'audio/wav' })
+}
+
+function downsampleBuffer(buffer, inputSampleRate, outputSampleRate) {
+  if (outputSampleRate >= inputSampleRate) return buffer
+
+  const sampleRateRatio = inputSampleRate / outputSampleRate
+  const newLength = Math.round(buffer.length / sampleRateRatio)
+  const result = new Float32Array(newLength)
+  let offsetResult = 0
+  let offsetBuffer = 0
+
+  while (offsetResult < result.length) {
+    const nextOffsetBuffer = Math.round((offsetResult + 1) * sampleRateRatio)
+    let accum = 0
+    let count = 0
+    for (let i = offsetBuffer; i < nextOffsetBuffer && i < buffer.length; i += 1) {
+      accum += buffer[i]
+      count += 1
+    }
+    result[offsetResult] = count > 0 ? accum / count : 0
+    offsetResult += 1
+    offsetBuffer = nextOffsetBuffer
+  }
+
+  return result
+}
+
+function normalizeSamples(samples, targetPeak = TARGET_PEAK) {
+  let peak = 0
+  for (let i = 0; i < samples.length; i += 1) {
+    peak = Math.max(peak, Math.abs(samples[i]))
+  }
+  if (peak === 0) return samples
+
+  const gain = Math.min(targetPeak / peak, 8)
+  if (gain <= 1.05) return samples
+
+  const normalized = new Float32Array(samples.length)
+  for (let i = 0; i < samples.length; i += 1) {
+    normalized[i] = Math.max(-1, Math.min(1, samples[i] * gain))
+  }
+  return normalized
+}
+
+function getPeak(samples) {
+  let peak = 0
+  for (let i = 0; i < samples.length; i += 1) {
+    peak = Math.max(peak, Math.abs(samples[i]))
+  }
+  return peak
+}
+
+function mixToMono(audioBuffer) {
+  const channelCount = audioBuffer.numberOfChannels
+  if (channelCount === 1) return new Float32Array(audioBuffer.getChannelData(0))
+
+  const mono = new Float32Array(audioBuffer.length)
+  for (let channel = 0; channel < channelCount; channel += 1) {
+    const data = audioBuffer.getChannelData(channel)
+    for (let i = 0; i < data.length; i += 1) {
+      mono[i] += data[i] / channelCount
+    }
+  }
+  return mono
+}
+
+async function decodeBlobToMonoWav(blob) {
+  const AudioContextClass = window.AudioContext || window.webkitAudioContext
+  const audioContext = new AudioContextClass()
+  try {
+    if (audioContext.state === 'suspended') await audioContext.resume()
+    const arrayBuffer = await blob.arrayBuffer()
+    const audioBuffer = await audioContext.decodeAudioData(arrayBuffer)
+    const mono = mixToMono(audioBuffer)
+    const downsampled = downsampleBuffer(mono, audioBuffer.sampleRate, SAMPLE_RATE)
+    const peakBefore = getPeak(downsampled)
+    const normalized = normalizeSamples(downsampled)
+    return {
+      wavBlob: encodeWav(normalized, SAMPLE_RATE),
+      durationSeconds: normalized.length / SAMPLE_RATE,
+      sampleCount: normalized.length,
+      peakBefore,
+    }
+  } finally {
+    if (audioContext.state !== 'closed') await audioContext.close()
+  }
+}
+
+export default function ChatInput({ onSend, onUploadClick, isLoading, disabled, disabledReason }) {
+  const [text, setText] = useState('')
+  const [isRecording, setIsRecording] = useState(false)
+  const [isTranscribing, setIsTranscribing] = useState(false)
+  const [inputLevel, setInputLevel] = useState(0)
+  const textareaRef = useRef(null)
+  const streamRef = useRef(null)
+  const mediaRecorderRef = useRef(null)
+  const chunksRef = useRef([])
+  const monitorAudioContextRef = useRef(null)
+  const analyserRef = useRef(null)
+  const monitorFrameRef = useRef(null)
+
+  useEffect(() => {
+    const el = textareaRef.current
+    if (!el) return
+    el.style.height = 'auto'
+    el.style.height = Math.min(el.scrollHeight, 200) + 'px'
+  }, [text])
+
+  useEffect(() => () => {
+    if (mediaRecorderRef.current?.state && mediaRecorderRef.current.state !== 'inactive') {
+      mediaRecorderRef.current.stop()
+    }
+    if (monitorFrameRef.current) cancelAnimationFrame(monitorFrameRef.current)
+    if (monitorAudioContextRef.current && monitorAudioContextRef.current.state !== 'closed') {
+      monitorAudioContextRef.current.close().catch(() => {})
+    }
+    if (streamRef.current) {
+      streamRef.current.getTracks().forEach((track) => track.stop())
+    }
+  }, [])
+
+  const submit = () => {
+    const q = text.trim()
+    if (!q || isLoading || disabled || isRecording || isTranscribing) return
+    onSend(q)
+    setText('')
+    if (textareaRef.current) textareaRef.current.style.height = 'auto'
+  }
+
+  const handleKey = (e) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      submit()
+    }
+  }
+
+  const stopInputMonitor = async () => {
+    if (monitorFrameRef.current) {
+      cancelAnimationFrame(monitorFrameRef.current)
+      monitorFrameRef.current = null
+    }
+    analyserRef.current = null
+    if (monitorAudioContextRef.current && monitorAudioContextRef.current.state !== 'closed') {
+      await monitorAudioContextRef.current.close()
+    }
+    monitorAudioContextRef.current = null
+    setInputLevel(0)
+  }
+
+  const stopStream = async () => {
+    await stopInputMonitor()
+    if (!streamRef.current) return
+    streamRef.current.getTracks().forEach((track) => track.stop())
+    streamRef.current = null
+  }
+
+  const startInputMonitor = async (stream) => {
+    const AudioContextClass = window.AudioContext || window.webkitAudioContext
+    const audioContext = new AudioContextClass()
+    if (audioContext.state === 'suspended') await audioContext.resume()
+
+    const source = audioContext.createMediaStreamSource(stream)
+    const analyser = audioContext.createAnalyser()
+    analyser.fftSize = 2048
+    source.connect(analyser)
+
+    monitorAudioContextRef.current = audioContext
+    analyserRef.current = analyser
+
+    const buffer = new Float32Array(analyser.fftSize)
+    const tick = () => {
+      if (!analyserRef.current) return
+      analyserRef.current.getFloatTimeDomainData(buffer)
+      let sumSquares = 0
+      for (let i = 0; i < buffer.length; i += 1) {
+        sumSquares += buffer[i] * buffer[i]
+      }
+      const rms = Math.sqrt(sumSquares / buffer.length)
+      setInputLevel(Math.min(1, rms * 12))
+      monitorFrameRef.current = requestAnimationFrame(tick)
+    }
+    tick()
+  }
+
+  const transcribeWavBlob = async (blob) => {
+    const formData = new FormData()
+    formData.append('file', new File([blob], 'recording.wav', { type: 'audio/wav' }))
+
+    setIsTranscribing(true)
+    try {
+      const result = await audioApi.transcribe(formData)
+      if (!result.text?.trim()) {
+        toast.error('No speech was detected in that recording')
+        return
+      }
+      setText((prev) => [prev.trim(), result.text.trim()].filter(Boolean).join(prev.trim() ? '\n' : ''))
+      toast.success('Transcript added to the message box')
+    } catch (err) {
+      toast.error(getApiErrorMessage(err, 'Failed to transcribe audio'))
+    } finally {
+      setIsTranscribing(false)
+    }
+  }
+
+  const handleRecordedBlob = async (blob) => {
+    try {
+      const { wavBlob, durationSeconds, sampleCount, peakBefore } = await decodeBlobToMonoWav(blob)
+      if (sampleCount === 0) {
+        toast.error('Recording was empty')
+        return
+      }
+      if (durationSeconds < MIN_RECORDING_SECONDS) {
+        toast.error('Recording is too short. Please speak for a bit longer.')
+        return
+      }
+      if (peakBefore < LOW_INPUT_LEVEL) {
+        toast.error('The selected browser microphone is almost silent. Check the browser mic permission and selected input device.')
+        return
+      }
+      await transcribeWavBlob(wavBlob)
+    } catch (err) {
+      toast.error(err?.message || 'Could not process the microphone recording')
+    }
+  }
+
+  const toggleRecording = async () => {
+    if (disabled || isLoading || isTranscribing) return
+
+    if (isRecording) {
+      mediaRecorderRef.current?.stop()
+      setIsRecording(false)
+      return
+    }
+
+    if (!navigator.mediaDevices?.getUserMedia || typeof MediaRecorder === 'undefined') {
+      toast.error('Your browser does not support microphone recording')
+      return
+    }
+
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+      streamRef.current = stream
+      await startInputMonitor(stream)
+
+      const track = stream.getAudioTracks()[0]
+      const label = track?.label?.trim()
+      if (label) {
+        toast.success(`Using microphone: ${label}`)
+      } else {
+        toast.success('Recording started. Press the mic again to stop.')
+      }
+
+      const mimeType = [
+        'audio/webm;codecs=opus',
+        'audio/webm',
+        'audio/ogg;codecs=opus',
+      ].find((type) => MediaRecorder.isTypeSupported(type))
+
+      if (!mimeType) {
+        await stopStream()
+        toast.error('This browser cannot record in a supported audio format')
+        return
+      }
+
+      const recorder = new MediaRecorder(stream, { mimeType })
+      mediaRecorderRef.current = recorder
+      chunksRef.current = []
+
+      recorder.ondataavailable = (event) => {
+        if (event.data?.size) chunksRef.current.push(event.data)
+      }
+      recorder.onerror = async () => {
+        await stopStream()
+        setIsRecording(false)
+        toast.error('Microphone recording failed')
+      }
+      recorder.onstop = async () => {
+        const blob = new Blob(chunksRef.current, { type: recorder.mimeType || mimeType })
+        chunksRef.current = []
+        await stopStream()
+        await handleRecordedBlob(blob)
+      }
+
+      recorder.start()
+      setIsRecording(true)
+    } catch (err) {
+      await stopStream()
+      toast.error(err?.message || 'Could not access the microphone')
+    }
+  }
+
+  return (
+    <div className="border border-white/8 bg-surface-2 rounded-2xl shadow-xl overflow-hidden transition-all duration-150 focus-within:border-accent/30 focus-within:shadow-accent/5">
+      <textarea
+        ref={textareaRef}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        onKeyDown={handleKey}
+        disabled={disabled || isLoading || isTranscribing}
+        placeholder={disabled && disabledReason ? disabledReason : 'Ask a medical question...'}
+        rows={1}
+        className="w-full bg-transparent text-white text-sm placeholder-gray-600 px-4 pt-4 pb-2 resize-none outline-none leading-relaxed disabled:opacity-50"
+      />
+
+      <div className="flex items-center justify-between px-3 pb-3 pt-1">
+        <div className="flex items-center gap-1">
+          <button
+            onClick={onUploadClick}
+            title="Upload PDF / document"
+            className={clsx(
+              'flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg text-xs font-medium transition-all duration-150',
+              'text-gray-400 hover:text-accent hover:bg-accent/10 border border-white/5 hover:border-accent/20'
+            )}
+          >
+            <Plus size={13} />
+            <Paperclip size={12} />
+          </button>
+          <button
+            onClick={toggleRecording}
+            disabled={disabled || isLoading || isTranscribing}
+            title={
+              isTranscribing
+                ? 'Transcribing audio...'
+                : isRecording
+                  ? 'Stop recording'
+                  : 'Record audio for transcription'
+            }
+            className={clsx(
+              'flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg text-xs font-medium transition-all duration-150 border',
+              isRecording
+                ? 'text-red-300 bg-red-500/10 border-red-400/30 hover:bg-red-500/15'
+                : 'text-gray-400 hover:text-accent hover:bg-accent/10 border-white/5 hover:border-accent/20',
+              (disabled || isLoading || isTranscribing) && 'opacity-60 cursor-not-allowed'
+            )}
+          >
+            {isTranscribing
+              ? <LoaderCircle size={13} className="animate-spin" />
+              : <Mic size={13} className={isRecording ? 'animate-pulse' : ''} />
+            }
+          </button>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {(text || isRecording || isTranscribing) && (
+            <span className="text-[10px] text-gray-600 select-none">
+              {isRecording
+                ? 'Recording... press mic to stop'
+                : isTranscribing
+                  ? 'Transcribing audio...'
+                  : 'Enter send | Shift+Enter newline'}
+            </span>
+          )}
+          <button
+            onClick={submit}
+            disabled={!text.trim() || disabled || isRecording || isTranscribing}
+            title={disabled && disabledReason ? disabledReason : (isLoading ? 'Processing...' : 'Send')}
+            className={clsx(
+              'w-8 h-8 rounded-lg flex items-center justify-center transition-all duration-150',
+              text.trim() && !disabled && !isRecording && !isTranscribing
+                ? 'bg-accent hover:bg-accent-hover text-white shadow-md shadow-accent/20 active:scale-95'
+                : 'bg-surface-3 text-gray-600 cursor-not-allowed'
+            )}
+          >
+            {isLoading
+              ? <Square size={12} className="fill-current" />
+              : <Send size={13} className={text.trim() ? '' : 'opacity-40'} />
+            }
+          </button>
+        </div>
+      </div>
+
+      {(isRecording || inputLevel > 0) && (
+        <div className="px-4 pb-3">
+          <div className="flex items-center gap-2">
+            <div className="h-1.5 flex-1 rounded-full bg-surface-3 overflow-hidden">
+              <div
+                className={clsx(
+                  'h-full transition-[width] duration-100',
+                  inputLevel < LOW_INPUT_LEVEL ? 'bg-amber-400/80' : 'bg-emerald-400/90'
+                )}
+                style={{ width: `${Math.max(4, inputLevel * 100)}%` }}
+              />
+            </div>
+            <span className="text-[10px] text-gray-500 w-12 text-right">
+              {inputLevel < LOW_INPUT_LEVEL ? 'Low mic' : 'Mic ok'}
+            </span>
+          </div>
+        </div>
+      )}
+
+      {disabled && disabledReason && (
+        <div className="px-4 pb-3 text-[11px] text-amber-300/80">
+          {disabledReason}
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/components/chat/MessageBubble.jsx

@@ -0,0 +1,177 @@
+import { useRef, useState } from 'react'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import { motion } from 'framer-motion'
+import { ChevronDown, ChevronUp, BookOpen, Hash, LoaderCircle, Volume2, VolumeX } from 'lucide-react'
+import { Stethoscope, User } from 'lucide-react'
+import clsx from 'clsx'
+import toast from 'react-hot-toast'
+
+import { audioApi, getApiErrorMessage } from '../../api/client'
+
+function TypingDots() {
+  return (
+    <div className="flex items-center gap-1 py-1">
+      <span className="typing-dot" />
+      <span className="typing-dot" />
+      <span className="typing-dot" />
+    </div>
+  )
+}
+
+function SourceCard({ source, index }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <div className="border border-white/8 rounded-lg overflow-hidden text-xs">
+      <button
+        onClick={() => setOpen(o => !o)}
+        className="w-full flex items-center gap-2 px-3 py-2 bg-surface-3 hover:bg-surface-4 transition-colors text-left"
+      >
+        <span className="w-5 h-5 rounded-full bg-accent/20 text-accent flex items-center justify-center font-bold text-[10px] shrink-0">{index}</span>
+        <div className="flex-1 min-w-0">
+          <p className="text-white/80 font-medium truncate">{source.title}</p>
+          <p className="text-gray-500 truncate">
+            {source.filename}
+            {source.page_number ? ` | page ${source.page_number}` : ''}
+            {source.retrieval_method ? ` | ${source.retrieval_method}` : ''}
+          </p>
+        </div>
+        <span className="text-gray-500 shrink-0 font-mono">{(source.score * 100).toFixed(0)}%</span>
+        {open ? <ChevronUp size={12} className="text-gray-500 shrink-0" /> : <ChevronDown size={12} className="text-gray-500 shrink-0" />}
+      </button>
+      {open && (
+        <div className="px-3 py-2 bg-surface-2 border-t border-white/5 text-gray-400 leading-relaxed text-[11px] max-h-40 overflow-y-auto">
+          <div className="flex items-center gap-3 text-[10px] text-gray-500 mb-2">
+            <span className="flex items-center gap-1"><Hash size={10} /> chunk {source.chunk_index}</span>
+            {source.page_number ? <span>page {source.page_number}</span> : null}
+            <span className="font-mono">{source.doc_id.slice(0, 8)}</span>
+          </div>
+          {source.text}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default function MessageBubble({ message, isStreaming = false }) {
+  const [showSources, setShowSources] = useState(false)
+  const [isSpeaking, setIsSpeaking] = useState(false)
+  const isUser = message.role === 'user'
+  const sources = message.sources || []
+  const audioRef = useRef(null)
+
+  const handleSpeak = async () => {
+    if (!message.content?.trim()) return
+
+    if (audioRef.current && !audioRef.current.paused) {
+      audioRef.current.pause()
+      audioRef.current.currentTime = 0
+      setIsSpeaking(false)
+      return
+    }
+
+    setIsSpeaking(true)
+    try {
+      const blob = await audioApi.speak({ text: message.content })
+      const url = URL.createObjectURL(blob)
+      const audio = new Audio(url)
+      audioRef.current = audio
+      audio.onended = () => {
+        URL.revokeObjectURL(url)
+        setIsSpeaking(false)
+      }
+      audio.onerror = () => {
+        URL.revokeObjectURL(url)
+        setIsSpeaking(false)
+      }
+      await audio.play()
+    } catch (err) {
+      setIsSpeaking(false)
+      toast.error(getApiErrorMessage(err, 'Failed to generate speech'))
+    }
+  }
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 10 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.2 }}
+      className={clsx('flex gap-3 group', isUser && 'flex-row-reverse')}
+    >
+      <div className={clsx(
+        'w-8 h-8 rounded-xl flex items-center justify-center shrink-0 mt-0.5',
+        isUser ? 'bg-accent/20 border border-accent/30' : 'bg-med-teal/10 border border-med-teal/20'
+      )}>
+        {isUser
+          ? <User size={14} className="text-accent" />
+          : <Stethoscope size={14} className="text-med-teal" />
+        }
+      </div>
+
+      <div className={clsx('flex-1 min-w-0 max-w-2xl', isUser && 'flex flex-col items-end')}>
+        {isUser ? (
+          <div className="bg-accent/10 border border-accent/20 rounded-2xl rounded-tr-sm px-4 py-3 text-sm text-white leading-relaxed">
+            {message.content}
+          </div>
+        ) : (
+          <div className="space-y-3">
+            <div className="bg-surface-2 border border-white/5 rounded-2xl rounded-tl-sm px-4 py-3">
+              {isStreaming ? (
+                <TypingDots />
+              ) : (
+                <div className="space-y-3">
+                  <div className="prose-dark text-sm leading-relaxed">
+                    <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                      {message.content}
+                    </ReactMarkdown>
+                  </div>
+                  <div className="flex items-center justify-end">
+                    <button
+                      onClick={handleSpeak}
+                      className="flex items-center gap-1.5 text-xs text-gray-400 hover:text-white transition-colors"
+                      title={isSpeaking ? 'Stop audio' : 'Play answer audio'}
+                    >
+                      {isSpeaking
+                        ? <LoaderCircle size={12} className="animate-spin" />
+                        : audioRef.current && !audioRef.current.paused
+                          ? <VolumeX size={12} />
+                          : <Volume2 size={12} />
+                      }
+                      {isSpeaking ? 'Speaking...' : 'Speak'}
+                    </button>
+                  </div>
+                </div>
+              )}
+            </div>
+
+            {!isStreaming && sources.length > 0 && (
+              <div className="space-y-2">
+                <button
+                  onClick={() => setShowSources(s => !s)}
+                  className="flex items-center gap-1.5 text-xs text-gray-500 hover:text-gray-300 transition-colors"
+                >
+                  <BookOpen size={11} />
+                  {sources.length} source{sources.length !== 1 ? 's' : ''}
+                  {showSources ? <ChevronUp size={11} /> : <ChevronDown size={11} />}
+                </button>
+
+                {showSources && (
+                  <motion.div
+                    initial={{ opacity: 0, height: 0 }}
+                    animate={{ opacity: 1, height: 'auto' }}
+                    exit={{ opacity: 0, height: 0 }}
+                    className="space-y-1.5"
+                  >
+                    {sources.map((s, i) => (
+                      <SourceCard key={i} source={s} index={i + 1} />
+                    ))}
+                  </motion.div>
+                )}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </motion.div>
+  )
+}

frontend/src/components/chat/UploadModal.jsx

@@ -0,0 +1,198 @@
+import { useRef, useState } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import { X, Upload, FileText, CheckCircle, AlertCircle, Loader } from 'lucide-react'
+import { docsApi } from '../../api/client'
+import toast from 'react-hot-toast'
+
+const ALLOWED_TYPES = [
+  'application/pdf',
+  'text/plain',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+]
+
+export default function UploadModal({ onClose, conversationId }) {
+  const [files, setFiles] = useState([])
+  const [title, setTitle] = useState('')
+  const [source, setSource] = useState('')
+  const [status, setStatus] = useState('idle')
+  const [errorMsg, setErrorMsg] = useState('')
+  const fileRef = useRef()
+  const isSingleFile = files.length === 1
+
+  const selectFiles = (fileList) => {
+    const picked = Array.from(fileList || []).filter((file) => {
+      const ok = ALLOWED_TYPES.includes(file.type) || /\.(pdf|txt|docx)$/i.test(file.name)
+      if (!ok) toast.error(`Unsupported file skipped: ${file.name}`)
+      return ok
+    })
+    if (!picked.length) return
+    setFiles(picked)
+    if (picked.length === 1) {
+      setTitle((prev) => prev || picked[0].name.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' '))
+    } else {
+      setTitle('')
+    }
+  }
+
+  const handleDrop = (e) => {
+    e.preventDefault()
+    selectFiles(e.dataTransfer.files)
+  }
+
+  const submit = async () => {
+    if (!conversationId) {
+      setErrorMsg('Create a conversation before uploading documents')
+      setStatus('error')
+      return
+    }
+    if (!files.length || (isSingleFile && !title.trim())) return
+    setStatus('uploading')
+    setErrorMsg('')
+    try {
+      const fd = new FormData()
+      files.forEach((file) => fd.append('files', file))
+      fd.append('conversation_id', conversationId)
+      if (isSingleFile) fd.append('title', title.trim())
+      if (source.trim()) fd.append('source', source.trim())
+      const result = await docsApi.upload(fd)
+      setStatus('success')
+      toast.success(result.message || 'Documents queued for ingestion')
+      setTimeout(onClose, 1800)
+    } catch (err) {
+      setErrorMsg(err.response?.data?.detail || 'Upload failed')
+      setStatus('error')
+    }
+  }
+
+  const totalSizeMb = (files.reduce((sum, file) => sum + file.size, 0) / 1024 / 1024).toFixed(2)
+
+  return (
+    <AnimatePresence>
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+        className="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center p-4"
+        onClick={(e) => e.target === e.currentTarget && onClose()}
+      >
+        <motion.div
+          initial={{ opacity: 0, scale: 0.95, y: 16 }}
+          animate={{ opacity: 1, scale: 1, y: 0 }}
+          exit={{ opacity: 0, scale: 0.95, y: 16 }}
+          transition={{ duration: 0.2 }}
+          className="bg-surface-2 border border-white/8 rounded-2xl w-full max-w-md p-6 shadow-2xl"
+        >
+          <div className="flex items-center justify-between mb-5">
+            <div>
+              <h2 className="text-white font-semibold">Upload Medical Documents</h2>
+              <p className="text-xs text-gray-500 mt-0.5">PDF, DOCX, or TXT. One or many files.</p>
+            </div>
+            <button onClick={onClose} className="text-gray-500 hover:text-white p-1 rounded-lg hover:bg-white/5">
+              <X size={18} />
+            </button>
+          </div>
+
+          <div
+            onDragOver={(e) => e.preventDefault()}
+            onDrop={handleDrop}
+            onClick={() => fileRef.current?.click()}
+            className={`border-2 border-dashed rounded-xl p-6 text-center cursor-pointer transition-all duration-200 mb-4 ${
+              files.length ? 'border-med-teal/40 bg-med-teal/5' : 'border-white/10 hover:border-accent/40 hover:bg-accent/5'
+            }`}
+          >
+            <input
+              ref={fileRef}
+              type="file"
+              multiple
+              accept=".pdf,.docx,.txt"
+              className="hidden"
+              onChange={(e) => selectFiles(e.target.files)}
+            />
+            {files.length ? (
+              <div className="space-y-3">
+                <div className="flex items-center gap-3 justify-center">
+                  <FileText className="text-med-teal" size={22} />
+                  <div className="text-left">
+                    <p className="text-white text-sm font-medium">
+                      {isSingleFile ? files[0].name : `${files.length} files selected`}
+                    </p>
+                    <p className="text-gray-500 text-xs">{totalSizeMb} MB total</p>
+                  </div>
+                </div>
+                {files.length > 1 && (
+                  <div className="max-h-28 overflow-y-auto text-left text-xs text-gray-400 space-y-1">
+                    {files.map((file) => (
+                      <div key={`${file.name}-${file.size}`} className="truncate">
+                        {file.name}
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </div>
+            ) : (
+              <div>
+                <Upload size={24} className="mx-auto text-gray-500 mb-2" />
+                <p className="text-gray-400 text-sm">Drop files here or <span className="text-accent">browse</span></p>
+              </div>
+            )}
+          </div>
+
+          <div className="space-y-3 mb-5">
+            {isSingleFile && (
+              <div>
+                <label className="block text-xs text-gray-400 mb-1.5 font-medium">Document Title *</label>
+                <input
+                  className="input-field"
+                  placeholder="e.g. Harrison's Principles of Internal Medicine"
+                  value={title}
+                  onChange={(e) => setTitle(e.target.value)}
+                />
+              </div>
+            )}
+            {files.length > 1 && (
+              <div className="text-xs text-gray-500">
+                Titles will be generated automatically from the filenames.
+              </div>
+            )}
+            <div>
+              <label className="block text-xs text-gray-400 mb-1.5 font-medium">Source / Reference <span className="text-gray-600">(optional)</span></label>
+              <input
+                className="input-field"
+                placeholder="e.g. PubMed, WHO Guidelines 2024"
+                value={source}
+                onChange={(e) => setSource(e.target.value)}
+              />
+            </div>
+          </div>
+
+          {status === 'error' && (
+            <div className="flex items-start gap-2 bg-red-500/10 border border-red-500/20 rounded-lg p-3 mb-4 text-xs text-red-400">
+              <AlertCircle size={14} className="shrink-0 mt-0.5" />
+              {errorMsg}
+            </div>
+          )}
+          {status === 'success' && (
+            <div className="flex items-center gap-2 bg-med-teal/10 border border-med-teal/20 rounded-lg p-3 mb-4 text-xs text-med-teal">
+              <CheckCircle size={14} />
+              Upload accepted and queued for background ingestion. Closing...
+            </div>
+          )}
+
+          <div className="flex gap-3">
+            <button onClick={onClose} className="btn-ghost flex-1 text-sm">Cancel</button>
+            <button
+              onClick={submit}
+              disabled={!files.length || (isSingleFile && !title.trim()) || status === 'uploading' || status === 'success'}
+              className="btn-primary flex-1 text-sm flex items-center justify-center gap-2"
+            >
+              {status === 'uploading'
+                ? <><Loader size={14} className="animate-spin" /> Queueing...</>
+                : <><Upload size={14} /> Upload</>
+              }
+            </button>
+          </div>
+        </motion.div>
+      </motion.div>
+    </AnimatePresence>
+  )
+}

frontend/src/components/chat/WelcomeScreen.jsx

@@ -0,0 +1,45 @@
+import { Stethoscope, FileSearch, Brain, BookOpen } from 'lucide-react'
+
+const SUGGESTIONS = [
+  { icon: Stethoscope, text: 'What are the first-line treatments for hypertension?' },
+  { icon: FileSearch, text: 'Explain the pathophysiology of type 2 diabetes.' },
+  { icon: Brain, text: 'What are the diagnostic criteria for major depressive disorder?' },
+  { icon: BookOpen, text: 'Summarize the mechanism of action of beta-blockers.' },
+]
+
+export default function WelcomeScreen({ onSuggest }) {
+  return (
+    <div className="flex flex-col items-center justify-center h-full px-4 pb-16 animate-fade-in">
+      {/* Icon */}
+      <div className="w-16 h-16 rounded-2xl bg-accent/10 border border-accent/20 flex items-center justify-center mb-6">
+        <Stethoscope className="text-accent w-8 h-8" />
+      </div>
+
+      <h2 className="text-2xl font-bold text-white mb-2">MedRAG Assistant</h2>
+      <p className="text-gray-500 text-sm text-center max-w-sm mb-10 leading-relaxed">
+        Ask clinical questions grounded in your uploaded medical knowledge base.
+      </p>
+
+      {/* Suggestion cards */}
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-3 w-full max-w-lg">
+        {SUGGESTIONS.map(({ icon: Icon, text }) => (
+          <button
+            key={text}
+            onClick={() => onSuggest(text)}
+            className="flex items-start gap-3 p-3.5 rounded-xl bg-surface-2 border border-white/5 hover:border-accent/20 hover:bg-surface-3 transition-all duration-150 text-left group"
+          >
+            <div className="w-7 h-7 rounded-lg bg-accent/10 flex items-center justify-center shrink-0 mt-0.5 group-hover:bg-accent/20 transition-colors">
+              <Icon size={13} className="text-accent" />
+            </div>
+            <span className="text-xs text-gray-400 group-hover:text-gray-200 transition-colors leading-relaxed">{text}</span>
+          </button>
+        ))}
+      </div>
+
+      <p className="mt-10 text-[10px] text-gray-700 text-center max-w-xs">
+        Answers are grounded in indexed documents only.
+        Always verify with a licensed healthcare professional.
+      </p>
+    </div>
+  )
+}

frontend/src/components/layout/Sidebar.jsx

@@ -0,0 +1,211 @@
+import { useState, useRef, useEffect } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import { useChatStore, useAuthStore } from '../../store'
+import {
+  Plus, MessageSquare, Trash2, Pencil, Check, X,
+  Stethoscope, LogOut, Shield, ChevronRight, Search
+} from 'lucide-react'
+import { useNavigate } from 'react-router-dom'
+import toast from 'react-hot-toast'
+import clsx from 'clsx'
+
+function ConvItem({ conv, isActive, onSelect, onDelete, onRename }) {
+  const [editing, setEditing] = useState(false)
+  const [title, setTitle] = useState(conv.title)
+  const [showActions, setShowActions] = useState(false)
+  const inputRef = useRef()
+
+  useEffect(() => { if (editing) inputRef.current?.focus() }, [editing])
+
+  const saveRename = async () => {
+    if (title.trim() && title !== conv.title) await onRename(conv.id, title.trim())
+    setEditing(false)
+  }
+
+  const handleKey = (e) => {
+    if (e.key === 'Enter') saveRename()
+    if (e.key === 'Escape') { setTitle(conv.title); setEditing(false) }
+  }
+
+  return (
+    <div
+      className={clsx('sidebar-item relative', isActive && 'active')}
+      onClick={() => !editing && onSelect(conv.id)}
+      onMouseEnter={() => setShowActions(true)}
+      onMouseLeave={() => setShowActions(false)}
+    >
+      <MessageSquare size={14} className="shrink-0 opacity-60" />
+
+      {editing ? (
+        <input
+          ref={inputRef}
+          value={title}
+          onChange={e => setTitle(e.target.value)}
+          onKeyDown={handleKey}
+          onBlur={saveRename}
+          onClick={e => e.stopPropagation()}
+          className="flex-1 bg-surface-4 text-white text-sm px-2 py-0.5 rounded outline-none border border-accent/40 min-w-0"
+        />
+      ) : (
+        <span className="flex-1 truncate text-sm">{conv.title}</span>
+      )}
+
+      <AnimatePresence>
+        {showActions && !editing && (
+          <motion.div
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            className="flex items-center gap-0.5 shrink-0"
+            onClick={e => e.stopPropagation()}
+          >
+            <button
+              onClick={() => setEditing(true)}
+              className="p-1 hover:text-white text-gray-500 rounded hover:bg-white/10"
+            >
+              <Pencil size={12} />
+            </button>
+            <button
+              onClick={() => onDelete(conv.id)}
+              className="p-1 hover:text-red-400 text-gray-500 rounded hover:bg-white/10"
+            >
+              <Trash2 size={12} />
+            </button>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  )
+}
+
+export default function Sidebar({ onClose }) {
+  const { conversations, activeConvId, createConversation, selectConversation, deleteConversation, renameConversation, fetchConversations } = useChatStore()
+  const { user, logout } = useAuthStore()
+  const navigate = useNavigate()
+  const [search, setSearch] = useState('')
+
+  useEffect(() => { fetchConversations() }, [])
+
+  const handleNew = async () => {
+    await createConversation()
+    onClose?.()
+  }
+
+  const handleDelete = async (id) => {
+    if (!confirm('Delete this conversation?')) return
+    try { await deleteConversation(id) }
+    catch { toast.error('Could not delete conversation') }
+  }
+
+  const handleRename = async (id, title) => {
+    try { await renameConversation(id, title) }
+    catch { toast.error('Could not rename') }
+  }
+
+  const filtered = conversations.filter(c =>
+    c.title.toLowerCase().includes(search.toLowerCase())
+  )
+
+  // Group by date
+  const now = new Date()
+  const groups = { Today: [], 'Last 7 days': [], Older: [] }
+  filtered.forEach(c => {
+    const d = new Date(c.updated_at)
+    const diffDays = (now - d) / 86400000
+    if (diffDays < 1) groups['Today'].push(c)
+    else if (diffDays < 7) groups['Last 7 days'].push(c)
+    else groups['Older'].push(c)
+  })
+
+  return (
+    <div className="flex flex-col h-full bg-surface-1 w-64 border-r border-white/5">
+      {/* Logo */}
+      <div className="px-4 pt-5 pb-3 flex items-center gap-2.5">
+        <div className="w-7 h-7 rounded-lg bg-accent/10 border border-accent/20 flex items-center justify-center shrink-0">
+          <Stethoscope size={14} className="text-accent" />
+        </div>
+        <span className="font-bold text-white text-sm tracking-tight">MedRAG</span>
+      </div>
+
+      {/* New Chat button */}
+      <div className="px-3 mb-3">
+        <button
+          onClick={handleNew}
+          className="w-full flex items-center gap-2 px-3 py-2.5 rounded-xl bg-accent/10 hover:bg-accent/20 border border-accent/20 text-accent text-sm font-medium transition-all duration-150 group"
+        >
+          <Plus size={15} className="group-hover:rotate-90 transition-transform duration-200" />
+          New Chat
+        </button>
+      </div>
+
+      {/* Search */}
+      <div className="px-3 mb-2">
+        <div className="flex items-center gap-2 bg-surface-3 rounded-lg px-3 py-2 border border-white/5">
+          <Search size={13} className="text-gray-500 shrink-0" />
+          <input
+            value={search}
+            onChange={e => setSearch(e.target.value)}
+            placeholder="Search chats…"
+            className="bg-transparent text-sm text-white placeholder-gray-600 outline-none flex-1 min-w-0"
+          />
+        </div>
+      </div>
+
+      {/* Conversation list */}
+      <div className="flex-1 overflow-y-auto px-2 pb-2 space-y-4">
+        {Object.entries(groups).map(([label, convs]) =>
+          convs.length > 0 && (
+            <div key={label}>
+              <p className="px-2 py-1 text-[10px] font-semibold text-gray-600 uppercase tracking-wider">{label}</p>
+              {convs.map(c => (
+                <ConvItem
+                  key={c.id}
+                  conv={c}
+                  isActive={c.id === activeConvId}
+                  onSelect={selectConversation}
+                  onDelete={handleDelete}
+                  onRename={handleRename}
+                />
+              ))}
+            </div>
+          )
+        )}
+        {filtered.length === 0 && (
+          <p className="text-center text-gray-600 text-xs py-8">
+            {search ? 'No chats found' : 'No conversations yet'}
+          </p>
+        )}
+      </div>
+
+      {/* Bottom user area */}
+      <div className="border-t border-white/5 p-3 space-y-1">
+        {user?.role === 'admin' && (
+          <button
+            onClick={() => navigate('/admin')}
+            className="sidebar-item w-full text-med-purple"
+          >
+            <Shield size={14} className="shrink-0" />
+            Admin Dashboard
+            <ChevronRight size={12} className="ml-auto" />
+          </button>
+        )}
+        <div className="sidebar-item">
+          <div className="w-6 h-6 rounded-full bg-accent/20 flex items-center justify-center text-accent text-xs font-bold shrink-0">
+            {user?.full_name?.[0]?.toUpperCase() ?? 'U'}
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-xs text-white font-medium truncate">{user?.full_name}</p>
+            <p className="text-[10px] text-gray-500 truncate">{user?.email}</p>
+          </div>
+          <button
+            onClick={logout}
+            className="text-gray-500 hover:text-red-400 p-1 rounded shrink-0"
+            title="Sign out"
+          >
+            <LogOut size={13} />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

frontend/src/components/ui/ProtectedRoute.jsx

@@ -0,0 +1,15 @@
+import { Navigate } from 'react-router-dom'
+import { useAuthStore } from '../../store'
+
+export function RequireAuth({ children }) {
+  const { isAuthenticated } = useAuthStore()
+  if (!isAuthenticated) return <Navigate to="/login" replace />
+  return children
+}
+
+export function RequireAdmin({ children }) {
+  const { isAuthenticated, user } = useAuthStore()
+  if (!isAuthenticated) return <Navigate to="/login" replace />
+  if (user?.role !== 'admin') return <Navigate to="/" replace />
+  return children
+}

frontend/src/index.css

@@ -0,0 +1,97 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * { box-sizing: border-box; }
+
+  html, body, #root {
+    height: 100%;
+    margin: 0;
+    padding: 0;
+    background: #0a0a0f;
+    color: #e8e8f0;
+    font-family: 'Inter', system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  ::-webkit-scrollbar { width: 5px; height: 5px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: #2a2a38; border-radius: 4px; }
+  ::-webkit-scrollbar-thumb:hover { background: #3b3b50; }
+
+  ::selection { background: rgba(59,127,255,0.3); }
+}
+
+@layer components {
+  .btn-primary {
+    @apply bg-accent hover:bg-accent-hover text-white font-medium px-4 py-2 rounded-lg
+           transition-all duration-150 disabled:opacity-40 disabled:cursor-not-allowed
+           active:scale-95;
+  }
+
+  .btn-ghost {
+    @apply text-gray-400 hover:text-white hover:bg-surface-3 px-3 py-2 rounded-lg
+           transition-all duration-150 active:scale-95;
+  }
+
+  .input-field {
+    @apply bg-surface-3 border border-white/10 rounded-xl px-4 py-3 text-white
+           placeholder-gray-500 focus:outline-none focus:border-accent/60 focus:ring-1
+           focus:ring-accent/30 transition-all duration-150 w-full;
+  }
+
+  .sidebar-item {
+    @apply flex items-center gap-2 px-3 py-2 rounded-lg text-sm text-gray-400
+           hover:text-white hover:bg-surface-3 cursor-pointer transition-all duration-150
+           truncate;
+  }
+
+  .sidebar-item.active {
+    @apply bg-surface-3 text-white;
+  }
+
+  .glass-card {
+    @apply bg-surface-2/80 backdrop-blur-sm border border-white/5 rounded-2xl;
+  }
+}
+
+/* Typing animation dots */
+.typing-dot {
+  width: 6px; height: 6px;
+  border-radius: 50%;
+  background: #3b7fff;
+  display: inline-block;
+  animation: pulseDot 1.4s ease-in-out infinite;
+}
+.typing-dot:nth-child(2) { animation-delay: 0.2s; }
+.typing-dot:nth-child(3) { animation-delay: 0.4s; }
+
+@keyframes pulseDot {
+  0%, 80%, 100% { transform: scale(0.4); opacity: 0.4; }
+  40% { transform: scale(1); opacity: 1; }
+}
+
+/* Markdown prose overrides for dark theme */
+.prose-dark { color: #d4d4e8; }
+.prose-dark h1,.prose-dark h2,.prose-dark h3 { color: #fff; }
+.prose-dark strong { color: #fff; }
+.prose-dark code {
+  background: #1f1f28; color: #00c9a7;
+  padding: 2px 6px; border-radius: 4px;
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 0.85em;
+}
+.prose-dark pre {
+  background: #111118; border: 1px solid rgba(255,255,255,0.06);
+  border-radius: 10px; padding: 16px; overflow-x: auto;
+}
+.prose-dark a { color: #3b7fff; }
+.prose-dark ul { list-style: disc; padding-left: 1.4em; }
+.prose-dark ol { list-style: decimal; padding-left: 1.4em; }
+.prose-dark li { margin: 4px 0; }
+.prose-dark blockquote {
+  border-left: 3px solid #3b7fff; padding-left: 12px;
+  color: #9999b8; margin: 12px 0;
+}
+.prose-dark hr { border-color: rgba(255,255,255,0.08); margin: 20px 0; }

frontend/src/main.jsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+)

frontend/src/pages/AdminPage.jsx

@@ -0,0 +1,273 @@
+import { useEffect, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { motion } from 'framer-motion'
+import { adminApi, docsApi } from '../api/client'
+import { useAuthStore } from '../store'
+import {
+  Users, FileText, Database, Activity, ArrowLeft,
+  Shield, ShieldOff, UserCheck, UserX, Trash2,
+  RefreshCw, CheckCircle, XCircle, Clock
+} from 'lucide-react'
+import toast from 'react-hot-toast'
+import clsx from 'clsx'
+
+function StatCard({ label, value, icon: Icon, color = 'accent' }) {
+  const colors = {
+    accent: 'bg-accent/10 text-accent border-accent/20',
+    teal: 'bg-med-teal/10 text-med-teal border-med-teal/20',
+    purple: 'bg-med-purple/10 text-med-purple border-med-purple/20',
+    yellow: 'bg-yellow-500/10 text-yellow-400 border-yellow-500/20',
+  }
+  return (
+    <div className="glass-card p-5 flex items-center gap-4">
+      <div className={clsx('w-10 h-10 rounded-xl flex items-center justify-center border', colors[color])}>
+        <Icon size={18} />
+      </div>
+      <div>
+        <p className="text-2xl font-bold text-white">{value ?? '—'}</p>
+        <p className="text-xs text-gray-500">{label}</p>
+      </div>
+    </div>
+  )
+}
+
+function StatusBadge({ status }) {
+  const map = {
+    ready: { icon: CheckCircle, cls: 'text-med-teal bg-med-teal/10', label: 'Ready' },
+    processing: { icon: Clock, cls: 'text-yellow-400 bg-yellow-500/10', label: 'Processing' },
+    error: { icon: XCircle, cls: 'text-red-400 bg-red-500/10', label: 'Error' },
+  }
+  const { icon: Icon, cls, label } = map[status] || map.error
+  return (
+    <span className={clsx('flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-medium', cls)}>
+      <Icon size={10} />
+      {label}
+    </span>
+  )
+}
+
+export default function AdminPage() {
+  const [stats, setStats] = useState(null)
+  const [users, setUsers] = useState([])
+  const [docs, setDocs] = useState([])
+  const [tab, setTab] = useState('overview')
+  const [loading, setLoading] = useState(true)
+  const { user } = useAuthStore()
+  const navigate = useNavigate()
+
+  const load = async () => {
+    setLoading(true)
+    try {
+      const [s, u, d] = await Promise.all([adminApi.stats(), adminApi.users(), docsApi.list()])
+      setStats(s); setUsers(u); setDocs(d)
+    } catch { toast.error('Failed to load data') }
+    finally { setLoading(false) }
+  }
+
+  useEffect(() => { load() }, [])
+
+  const toggleRole = async (u) => {
+    const newRole = u.role === 'admin' ? 'user' : 'admin'
+    await adminApi.setRole(u.id, newRole)
+    setUsers(prev => prev.map(x => x.id === u.id ? { ...x, role: newRole } : x))
+    toast.success(`${u.full_name} is now ${newRole}`)
+  }
+
+  const toggleActive = async (u) => {
+    await adminApi.toggle(u.id)
+    setUsers(prev => prev.map(x => x.id === u.id ? { ...x, is_active: !x.is_active } : x))
+  }
+
+  const deleteDoc = async (id, title) => {
+    if (!confirm(`Delete "${title}"? This will remove all indexed vectors.`)) return
+    await docsApi.delete(id)
+    setDocs(prev => prev.filter(d => d.id !== id))
+    setStats(s => ({ ...s, total_documents: s.total_documents - 1 }))
+    toast.success('Document deleted')
+  }
+
+  const TABS = ['overview', 'users', 'documents']
+
+  return (
+    <div className="min-h-screen bg-surface-0 text-white">
+      {/* Header */}
+      <div className="border-b border-white/5 bg-surface-1/60 backdrop-blur-sm sticky top-0 z-10">
+        <div className="max-w-6xl mx-auto px-6 py-4 flex items-center gap-4">
+          <button onClick={() => navigate('/')} className="btn-ghost p-2 -ml-2">
+            <ArrowLeft size={16} />
+          </button>
+          <div className="flex items-center gap-2">
+            <Shield size={16} className="text-med-purple" />
+            <h1 className="font-semibold text-white">Admin Dashboard</h1>
+          </div>
+          <div className="flex-1" />
+          <button onClick={load} className="btn-ghost p-2" title="Refresh">
+            <RefreshCw size={14} className={loading ? 'animate-spin' : ''} />
+          </button>
+        </div>
+        {/* Tabs */}
+        <div className="max-w-6xl mx-auto px-6 flex gap-1 pb-0">
+          {TABS.map(t => (
+            <button
+              key={t}
+              onClick={() => setTab(t)}
+              className={clsx(
+                'px-4 py-2 text-sm font-medium capitalize border-b-2 transition-colors',
+                tab === t
+                  ? 'border-accent text-accent'
+                  : 'border-transparent text-gray-500 hover:text-gray-300'
+              )}
+            >
+              {t}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="max-w-6xl mx-auto px-6 py-8">
+        {/* ── Overview tab ── */}
+        {tab === 'overview' && (
+          <motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }} className="space-y-6">
+            <div className="grid grid-cols-2 lg:grid-cols-4 gap-4">
+              <StatCard label="Total Users" value={stats?.total_users} icon={Users} color="accent" />
+              <StatCard label="Documents" value={stats?.total_documents} icon={FileText} color="teal" />
+              <StatCard label="Chunks Indexed" value={stats?.total_chunks_indexed?.toLocaleString()} icon={Database} color="purple" />
+              <StatCard label="Qdrant Status" value={stats?.qdrant_status === 'ok' ? 'Healthy' : 'Error'} icon={Activity} color={stats?.qdrant_status === 'ok' ? 'teal' : 'yellow'} />
+            </div>
+
+            <div className="glass-card p-5">
+              <h3 className="text-sm font-semibold text-white mb-4">System Information</h3>
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-3 text-sm">
+                {[
+                  ['LLM Model', 'Llama 4 Scout 17B (Groq)'],
+                  ['Embedding Model', 'PubMedBERT'],
+                  ['Reranker', 'ms-marco-MiniLM-L-6-v2'],
+                  ['Vector Store', 'Qdrant (local path)'],
+                  ['Chunk Size', '512 tokens / 64 overlap'],
+                  ['Auth', 'JWT (access + refresh)'],
+                ].map(([k, v]) => (
+                  <div key={k} className="flex items-center justify-between py-2 border-b border-white/5">
+                    <span className="text-gray-500">{k}</span>
+                    <span className="text-white font-mono text-xs bg-surface-3 px-2 py-0.5 rounded">{v}</span>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </motion.div>
+        )}
+
+        {/* ── Users tab ── */}
+        {tab === 'users' && (
+          <motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}>
+            <div className="glass-card overflow-hidden">
+              <table className="w-full text-sm">
+                <thead>
+                  <tr className="border-b border-white/5 text-xs text-gray-500 uppercase tracking-wide">
+                    {['Name', 'Email', 'Role', 'Status', 'Joined', 'Actions'].map(h => (
+                      <th key={h} className="text-left px-4 py-3 font-medium">{h}</th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {users.map((u, i) => (
+                    <tr key={u.id} className={clsx('border-b border-white/5 hover:bg-white/2 transition-colors', i === users.length - 1 && 'border-b-0')}>
+                      <td className="px-4 py-3">
+                        <div className="flex items-center gap-2">
+                          <div className="w-7 h-7 rounded-full bg-accent/20 flex items-center justify-center text-accent text-xs font-bold">
+                            {u.full_name[0].toUpperCase()}
+                          </div>
+                          <span className="text-white font-medium truncate max-w-[140px]">{u.full_name}</span>
+                        </div>
+                      </td>
+                      <td className="px-4 py-3 text-gray-400 text-xs">{u.email}</td>
+                      <td className="px-4 py-3">
+                        <span className={clsx('px-2 py-0.5 rounded-full text-xs font-medium',
+                          u.role === 'admin' ? 'bg-med-purple/15 text-med-purple' : 'bg-white/5 text-gray-400'
+                        )}>
+                          {u.role}
+                        </span>
+                      </td>
+                      <td className="px-4 py-3">
+                        <span className={clsx('px-2 py-0.5 rounded-full text-xs',
+                          u.is_active ? 'bg-med-teal/10 text-med-teal' : 'bg-red-500/10 text-red-400'
+                        )}>
+                          {u.is_active ? 'Active' : 'Disabled'}
+                        </span>
+                      </td>
+                      <td className="px-4 py-3 text-gray-500 text-xs">
+                        {new Date(u.created_at).toLocaleDateString()}
+                      </td>
+                      <td className="px-4 py-3">
+                        {u.id !== user?.id && (
+                          <div className="flex items-center gap-1">
+                            <button
+                              onClick={() => toggleRole(u)}
+                              title={u.role === 'admin' ? 'Demote to user' : 'Promote to admin'}
+                              className="p-1.5 hover:bg-white/5 rounded text-gray-500 hover:text-med-purple transition-colors"
+                            >
+                              {u.role === 'admin' ? <ShieldOff size={13} /> : <Shield size={13} />}
+                            </button>
+                            <button
+                              onClick={() => toggleActive(u)}
+                              title={u.is_active ? 'Disable user' : 'Enable user'}
+                              className="p-1.5 hover:bg-white/5 rounded text-gray-500 hover:text-yellow-400 transition-colors"
+                            >
+                              {u.is_active ? <UserX size={13} /> : <UserCheck size={13} />}
+                            </button>
+                          </div>
+                        )}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          </motion.div>
+        )}
+
+        {/* ── Documents tab ── */}
+        {tab === 'documents' && (
+          <motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}>
+            <div className="glass-card overflow-hidden">
+              <table className="w-full text-sm">
+                <thead>
+                  <tr className="border-b border-white/5 text-xs text-gray-500 uppercase tracking-wide">
+                    {['Title', 'File', 'Chunks', 'Status', 'Uploaded', 'Actions'].map(h => (
+                      <th key={h} className="text-left px-4 py-3 font-medium">{h}</th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {docs.length === 0 && (
+                    <tr>
+                      <td colSpan={6} className="text-center text-gray-600 py-12 text-sm">
+                        No documents ingested yet. Upload via the chat interface.
+                      </td>
+                    </tr>
+                  )}
+                  {docs.map((d, i) => (
+                    <tr key={d.id} className={clsx('border-b border-white/5 hover:bg-white/2 transition-colors', i === docs.length - 1 && 'border-b-0')}>
+                      <td className="px-4 py-3 text-white font-medium max-w-[200px] truncate">{d.title}</td>
+                      <td className="px-4 py-3 text-gray-400 text-xs font-mono max-w-[160px] truncate">{d.filename}</td>
+                      <td className="px-4 py-3 text-gray-300">{d.chunk_count.toLocaleString()}</td>
+                      <td className="px-4 py-3"><StatusBadge status={d.status} /></td>
+                      <td className="px-4 py-3 text-gray-500 text-xs">{new Date(d.created_at).toLocaleDateString()}</td>
+                      <td className="px-4 py-3">
+                        <button
+                          onClick={() => deleteDoc(d.id, d.title)}
+                          className="p-1.5 hover:bg-red-500/10 rounded text-gray-500 hover:text-red-400 transition-colors"
+                        >
+                          <Trash2 size={13} />
+                        </button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          </motion.div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/pages/AuthPage.jsx

@@ -0,0 +1,152 @@
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { motion, AnimatePresence } from 'framer-motion'
+import { useAuthStore } from '../store'
+import toast from 'react-hot-toast'
+import { Activity, Eye, EyeOff, Stethoscope } from 'lucide-react'
+import { getApiErrorMessage } from '../api/client'
+
+export default function AuthPage() {
+  const [mode, setMode] = useState('login') // 'login' | 'register'
+  const [form, setForm] = useState({ email: '', password: '', full_name: '' })
+  const [showPw, setShowPw] = useState(false)
+  const [loading, setLoading] = useState(false)
+  const { login, register } = useAuthStore()
+  const navigate = useNavigate()
+
+  const set = (k, v) => setForm(f => ({ ...f, [k]: v }))
+
+  const submit = async (e) => {
+    e.preventDefault()
+    setLoading(true)
+    try {
+      if (mode === 'login') {
+        await login(form.email, form.password)
+      } else {
+        await register(form.email, form.password, form.full_name)
+      }
+      toast.success(mode === 'login' ? 'Welcome back!' : 'Account created!')
+      navigate('/')
+    } catch (err) {
+      toast.error(getApiErrorMessage(err))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="min-h-screen bg-surface-0 flex items-center justify-center p-4 relative overflow-hidden">
+      {/* Background glow */}
+      <div className="absolute inset-0 pointer-events-none">
+        <div className="absolute top-1/4 left-1/2 -translate-x-1/2 w-[600px] h-[600px] bg-accent/5 rounded-full blur-[120px]" />
+        <div className="absolute bottom-0 right-1/4 w-[400px] h-[400px] bg-med-teal/5 rounded-full blur-[100px]" />
+      </div>
+
+      <motion.div
+        initial={{ opacity: 0, y: 24 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4 }}
+        className="w-full max-w-md relative z-10"
+      >
+        {/* Logo */}
+        <div className="text-center mb-8">
+          <div className="inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-accent/10 border border-accent/20 mb-4">
+            <Stethoscope className="w-8 h-8 text-accent" />
+          </div>
+          <h1 className="text-2xl font-bold text-white">MedRAG</h1>
+          <p className="text-gray-500 text-sm mt-1">Medical Knowledge Intelligence</p>
+        </div>
+
+        {/* Card */}
+        <div className="glass-card p-8">
+          {/* Tab switcher */}
+          <div className="flex bg-surface-0 rounded-lg p-1 mb-6">
+            {['login', 'register'].map(m => (
+              <button
+                key={m}
+                onClick={() => setMode(m)}
+                className={`flex-1 py-2 text-sm font-medium rounded-md transition-all duration-200 capitalize ${
+                  mode === m ? 'bg-accent text-white shadow-sm' : 'text-gray-400 hover:text-white'
+                }`}
+              >
+                {m === 'login' ? 'Sign In' : 'Create Account'}
+              </button>
+            ))}
+          </div>
+
+          <form onSubmit={submit} className="space-y-4">
+            <AnimatePresence mode="wait">
+              {mode === 'register' && (
+                <motion.div
+                  key="name"
+                  initial={{ opacity: 0, height: 0 }}
+                  animate={{ opacity: 1, height: 'auto' }}
+                  exit={{ opacity: 0, height: 0 }}
+                  transition={{ duration: 0.2 }}
+                >
+                  <label className="block text-xs text-gray-400 mb-1.5 font-medium">Full Name</label>
+                  <input
+                    className="input-field"
+                    placeholder="Dr. Jane Smith"
+                    value={form.full_name}
+                    onChange={e => set('full_name', e.target.value)}
+                    required={mode === 'register'}
+                  />
+                </motion.div>
+              )}
+            </AnimatePresence>
+
+            <div>
+              <label className="block text-xs text-gray-400 mb-1.5 font-medium">Email</label>
+              <input
+                className="input-field"
+                type="email"
+                placeholder="you@hospital.com"
+                value={form.email}
+                onChange={e => set('email', e.target.value)}
+                required
+              />
+            </div>
+
+            <div>
+              <label className="block text-xs text-gray-400 mb-1.5 font-medium">Password</label>
+              <div className="relative">
+                <input
+                  className="input-field pr-10"
+                  type={showPw ? 'text' : 'password'}
+                  placeholder={mode === 'register' ? 'Min. 8 characters' : '••••••••'}
+                  value={form.password}
+                  onChange={e => set('password', e.target.value)}
+                  required
+                  minLength={mode === 'register' ? 8 : undefined}
+                />
+                <button
+                  type="button"
+                  onClick={() => setShowPw(p => !p)}
+                  className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-500 hover:text-gray-300"
+                >
+                  {showPw ? <EyeOff size={16} /> : <Eye size={16} />}
+                </button>
+              </div>
+            </div>
+
+            <button
+              type="submit"
+              disabled={loading}
+              className="btn-primary w-full mt-2 py-3 text-sm font-semibold"
+            >
+              {loading
+                ? <span className="flex items-center justify-center gap-2"><Activity size={15} className="animate-spin" /> Processing…</span>
+                : mode === 'login' ? 'Sign In' : 'Create Account'
+              }
+            </button>
+          </form>
+        </div>
+
+        <p className="text-center text-xs text-gray-600 mt-6">
+          Medical AI assistant · Not a substitute for professional medical advice
+        </p>
+      </motion.div>
+    </div>
+  )
+}

frontend/src/pages/ChatPage.jsx

@@ -0,0 +1,214 @@
+import { useEffect, useRef, useState } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import { docsApi } from '../api/client'
+import { useChatStore } from '../store'
+import Sidebar from '../components/layout/Sidebar'
+import MessageBubble from '../components/chat/MessageBubble'
+import ChatInput from '../components/chat/ChatInput'
+import WelcomeScreen from '../components/chat/WelcomeScreen'
+import UploadModal from '../components/chat/UploadModal'
+import { Menu, Trash2, X } from 'lucide-react'
+import toast from 'react-hot-toast'
+
+export default function ChatPage() {
+  const {
+    messages, isLoading, isFetchingMsgs,
+    activeConvId, createConversation, sendMessage,
+  } = useChatStore()
+  const [sidebarOpen, setSidebarOpen] = useState(true)
+  const [uploadOpen, setUploadOpen] = useState(false)
+  const [pendingIngestionCount, setPendingIngestionCount] = useState(0)
+  const [readyDocumentCount, setReadyDocumentCount] = useState(0)
+  const bottomRef = useRef()
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
+  }, [messages, isLoading])
+
+  useEffect(() => {
+    let cancelled = false
+    let intervalId = null
+
+    const loadDocumentStatus = async () => {
+      try {
+        if (!activeConvId) {
+          setPendingIngestionCount(0)
+          setReadyDocumentCount(0)
+          return
+        }
+        const docs = await docsApi.list(activeConvId)
+        if (cancelled) return
+        const pending = docs.filter((doc) => doc.status === 'processing').length
+        const ready = docs.filter((doc) => doc.status === 'ready').length
+        setPendingIngestionCount(pending)
+        setReadyDocumentCount(ready)
+      } catch {
+        if (!cancelled) {
+          setPendingIngestionCount(0)
+          setReadyDocumentCount(0)
+        }
+      }
+    }
+
+    loadDocumentStatus()
+    intervalId = window.setInterval(loadDocumentStatus, 3000)
+
+    return () => {
+      cancelled = true
+      if (intervalId) window.clearInterval(intervalId)
+    }
+  }, [activeConvId])
+
+  const handleSend = async (query) => {
+    if (pendingIngestionCount > 0) {
+      toast.error('Please wait until document ingestion and embeddings finish')
+      return
+    }
+    if (activeConvId && readyDocumentCount === 0) {
+      toast.error('Upload documents to this chat first')
+      return
+    }
+
+    let convId = activeConvId
+    if (!convId) {
+      const conv = await createConversation()
+      convId = conv.id
+    }
+    try {
+      await sendMessage(query)
+    } catch (err) {
+      toast.error(err.response?.data?.detail || 'Failed to get a response')
+    }
+  }
+
+  const handleSuggest = async (text) => {
+    if (pendingIngestionCount > 0) return
+    await handleSend(text)
+  }
+
+  const handleUploadOpen = async () => {
+    if (pendingIngestionCount > 0) {
+      toast.error('Wait for the current document ingestion to finish first')
+      return
+    }
+    if (!activeConvId) {
+      const conv = await createConversation()
+      if (!conv?.id) {
+        toast.error('Could not create a conversation for document upload')
+        return
+      }
+    }
+    setUploadOpen(true)
+  }
+
+  const handleClearDocuments = async () => {
+    if (!activeConvId) return
+    if (!window.confirm('Clear all uploaded documents for this chat?')) return
+    try {
+      await docsApi.clearConversation(activeConvId)
+      setPendingIngestionCount(0)
+      setReadyDocumentCount(0)
+      toast.success('Cleared documents for this chat')
+    } catch (err) {
+      toast.error(err.response?.data?.detail || 'Failed to clear chat documents')
+    }
+  }
+
+  return (
+    <div className="flex h-screen bg-surface-0 overflow-hidden">
+      <AnimatePresence initial={false}>
+        {sidebarOpen && (
+          <motion.div
+            initial={{ width: 0, opacity: 0 }}
+            animate={{ width: 256, opacity: 1 }}
+            exit={{ width: 0, opacity: 0 }}
+            transition={{ duration: 0.2, ease: 'easeInOut' }}
+            className="overflow-hidden shrink-0"
+          >
+            <Sidebar onClose={() => setSidebarOpen(false)} />
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      <div className="flex flex-col flex-1 min-w-0">
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-white/5 bg-surface-1/50 backdrop-blur-sm shrink-0">
+          <button
+            onClick={() => setSidebarOpen(s => !s)}
+            className="btn-ghost p-2"
+          >
+            {sidebarOpen ? <X size={16} /> : <Menu size={16} />}
+          </button>
+          <div className="flex-1 min-w-0">
+            <h1 className="text-sm font-medium text-white truncate">
+              {activeConvId
+                ? useChatStore.getState().conversations.find(c => c.id === activeConvId)?.title || 'Chat'
+                : 'MedRAG Assistant'
+              }
+            </h1>
+          </div>
+          {activeConvId && (
+            <button
+              onClick={handleClearDocuments}
+              className="btn-ghost p-2 text-gray-500 hover:text-red-400"
+              title="Clear documents for this chat"
+            >
+              <Trash2 size={14} />
+            </button>
+          )}
+          <div className="text-xs text-gray-600 hidden sm:block">
+            MedRAG by HET SHETA
+          </div>
+        </div>
+
+        <div className="flex-1 overflow-y-auto">
+          {isFetchingMsgs ? (
+            <div className="flex items-center justify-center h-full">
+              <div className="flex gap-1">
+                <span className="typing-dot" />
+                <span className="typing-dot" />
+                <span className="typing-dot" />
+              </div>
+            </div>
+          ) : messages.length === 0 ? (
+            <WelcomeScreen onSuggest={handleSuggest} />
+          ) : (
+            <div className="max-w-3xl mx-auto px-4 py-6 space-y-6">
+              {messages.map((msg) => (
+                <MessageBubble key={msg.id} message={msg} />
+              ))}
+
+              {isLoading && (
+                <MessageBubble
+                  message={{ id: 'loading', role: 'assistant', content: '', sources: null }}
+                  isStreaming
+                />
+              )}
+              <div ref={bottomRef} />
+            </div>
+          )}
+        </div>
+
+        <div className="shrink-0 px-4 pb-4 pt-2 bg-gradient-to-t from-surface-0 via-surface-0/90 to-transparent">
+          <div className="max-w-3xl mx-auto">
+            <ChatInput
+              onSend={handleSend}
+              onUploadClick={handleUploadOpen}
+              isLoading={isLoading}
+              disabled={pendingIngestionCount > 0}
+              disabledReason={
+                pendingIngestionCount > 0
+                  ? `Waiting for ${pendingIngestionCount} uploaded document${pendingIngestionCount !== 1 ? 's' : ''} to finish ingestion and embeddings`
+                  : ''
+              }
+            />
+            <p className="text-center text-[10px] text-gray-700 mt-2">
+              MedRAG can make mistakes. Always verify medical information with a licensed professional.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {uploadOpen && <UploadModal conversationId={activeConvId} onClose={() => setUploadOpen(false)} />}
+    </div>
+  )
+}

frontend/src/store/index.js

@@ -0,0 +1,144 @@
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import { authApi, convApi } from '../api/client'
+
+// ─── Auth store ───────────────────────────────────────────────────────────────
+export const useAuthStore = create(
+  persist(
+    (set, get) => ({
+      user: null,
+      isAuthenticated: false,
+
+      login: async (email, password) => {
+        const tokens = await authApi.login({ email, password })
+        localStorage.setItem('access_token', tokens.access_token)
+        localStorage.setItem('refresh_token', tokens.refresh_token)
+        const user = await authApi.me()
+        set({ user, isAuthenticated: true })
+        return user
+      },
+
+      register: async (email, password, full_name) => {
+        await authApi.register({ email, password, full_name })
+        return get().login(email, password)
+      },
+
+      logout: () => {
+        localStorage.removeItem('access_token')
+        localStorage.removeItem('refresh_token')
+        set({ user: null, isAuthenticated: false })
+      },
+
+      loadMe: async () => {
+        try {
+          const user = await authApi.me()
+          set({ user, isAuthenticated: true })
+        } catch {
+          get().logout()
+        }
+      },
+    }),
+    { name: 'auth-store', partialize: (s) => ({ user: s.user, isAuthenticated: s.isAuthenticated }) }
+  )
+)
+
+// ─── Chat store ───────────────────────────────────────────────────────────────
+export const useChatStore = create((set, get) => ({
+  conversations: [],          // sidebar list
+  activeConvId: null,
+  messages: [],               // messages of active conversation
+  isLoading: false,           // waiting for RAG response
+  isFetchingMsgs: false,
+
+  fetchConversations: async () => {
+    try {
+      const convs = await convApi.list()
+      set({ conversations: convs })
+    } catch {}
+  },
+
+  createConversation: async () => {
+    const conv = await convApi.create('New Chat')
+    set((s) => ({ conversations: [conv, ...s.conversations], activeConvId: conv.id, messages: [] }))
+    return conv
+  },
+
+  selectConversation: async (id) => {
+    if (get().activeConvId === id) return
+    set({ activeConvId: id, messages: [], isFetchingMsgs: true })
+    try {
+      const msgs = await convApi.messages(id)
+      set({ messages: msgs })
+    } finally {
+      set({ isFetchingMsgs: false })
+    }
+  },
+
+  deleteConversation: async (id) => {
+    await convApi.delete(id)
+    const convs = get().conversations.filter(c => c.id !== id)
+    const activeConvId = get().activeConvId === id
+      ? (convs[0]?.id ?? null)
+      : get().activeConvId
+    set({ conversations: convs, activeConvId })
+    if (activeConvId && activeConvId !== get().activeConvId) {
+      await get().selectConversation(activeConvId)
+    } else if (!activeConvId) {
+      set({ messages: [] })
+    }
+  },
+
+  renameConversation: async (id, title) => {
+    const updated = await convApi.rename(id, title)
+    set((s) => ({
+      conversations: s.conversations.map(c => c.id === id ? { ...c, title: updated.title } : c)
+    }))
+  },
+
+  // Optimistically add user message, then add assistant response
+  sendMessage: async (query, topK = 5) => {
+    const { activeConvId } = get()
+    if (!activeConvId) return
+
+    // Optimistic user bubble
+    const tmpUserMsg = { id: `tmp-u-${Date.now()}`, role: 'user', content: query, conversation_id: activeConvId, created_at: new Date().toISOString(), sources: null }
+    set((s) => ({ messages: [...s.messages, tmpUserMsg], isLoading: true }))
+
+    try {
+      const { queryApi } = await import('../api/client')
+      const result = await queryApi.ask({ query, conversation_id: activeConvId, top_k: topK })
+
+      const assistantMsg = {
+        id: result.message_id,
+        role: 'assistant',
+        content: result.answer,
+        sources: result.sources,
+        conversation_id: activeConvId,
+        created_at: new Date().toISOString(),
+        meta: {
+          retrieval_ms: result.retrieval_ms,
+          rerank_ms: result.rerank_ms,
+          generation_ms: result.generation_ms,
+          model: result.model,
+          source_count: result.sources?.length || 0,
+          search_query: result.search_query,
+          retrieval_strategy: result.retrieval_strategy,
+          conversation_turns_used: result.conversation_turns_used,
+        },
+      }
+
+      // Replace tmp user message with real ones, update conversation title in sidebar
+      const msgs = await convApi.messages(activeConvId)
+      const convs = await convApi.list()
+      set({ messages: msgs, conversations: convs })
+
+      return result
+    } catch (err) {
+      // Remove optimistic message on error
+      set((s) => ({ messages: s.messages.filter(m => m.id !== tmpUserMsg.id) }))
+      throw err
+    } finally {
+      set({ isLoading: false })
+    }
+  },
+}))

frontend/tailwind.config.js

@@ -0,0 +1,43 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./index.html', './src/**/*.{js,jsx}'],
+  darkMode: 'class',
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Inter Variable', 'Inter', 'system-ui', 'sans-serif'],
+        mono: ['JetBrains Mono', 'Fira Code', 'monospace'],
+      },
+      colors: {
+        surface: {
+          0: '#0a0a0f',
+          1: '#111118',
+          2: '#18181f',
+          3: '#1f1f28',
+          4: '#262630',
+        },
+        accent: {
+          DEFAULT: '#3b7fff',
+          hover: '#5a94ff',
+          muted: 'rgba(59,127,255,0.15)',
+        },
+        med: {
+          teal: '#00c9a7',
+          blue: '#3b7fff',
+          purple: '#8b5cf6',
+        },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.2s ease-out',
+        'slide-up': 'slideUp 0.25s ease-out',
+        'pulse-dot': 'pulseDot 1.4s ease-in-out infinite',
+      },
+      keyframes: {
+        fadeIn: { from: { opacity: 0 }, to: { opacity: 1 } },
+        slideUp: { from: { opacity: 0, transform: 'translateY(8px)' }, to: { opacity: 1, transform: 'translateY(0)' } },
+        pulseDot: { '0%,80%,100%': { transform: 'scale(0)', opacity: 0.5 }, '40%': { transform: 'scale(1)', opacity: 1 } },
+      },
+    },
+  },
+  plugins: [],
+}