fix: resolve i18n merge conflicts

.env.example

@@ -91,6 +91,24 @@ HF_TOKEN=your_huggingface_token_here
 # Optional — defaults to 1024
 # LLM_MAX_NEW_TOKENS=1024
 
+# ── LangSmith Tracing (Optional) ────────────────────────
+
+# Enable LangSmith tracing for the backend RAG pipeline.
+# Optional — defaults to False
+# LANGSMITH_TRACING=False
+
+# LangSmith API key.
+# Optional — only needed when LANGSMITH_TRACING=True
+# LANGSMITH_API_KEY=
+
+# LangSmith API endpoint.
+# Optional — defaults to "https://api.smith.langchain.com"
+# LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+
+# LangSmith project name used for traced runs.
+# Optional — defaults to "pdf-assistant-rag"
+# LANGSMITH_PROJECT=pdf-assistant-rag
+
 # ── Embeddings (Optional — defaults shown)──────────────────────────────────────────────
 
 # SentenceTransformer model ID for generating document embeddings.

.github/workflows/ci.yml

@@ -54,6 +54,15 @@ jobs:
         run: |
           python -c "import sys; sys.path.insert(0, 'backend'); from app.config import settings; print('✅ Config imports OK')" || true
 
+      - name: Run backend pytest suite
+        env:
+          SECRET_KEY: ci-dummy-secret
+          DATABASE_URL: sqlite:///./ci_test.db
+          HF_TOKEN: ci-dummy-token
+          UPLOAD_DIR: /tmp/uploads
+          CHROMA_PERSIST_DIR: /tmp/chroma
+        run: pytest backend/tests -v
+
   # ── 2. Frontend Build Check ─────────────────────────────
   frontend-check:
     name: ⚛️ Frontend — TypeScript & Build

CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, the following branches and versions of PDF-Assistant-RAG are supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| `dev`   | :white_check_mark: |
+| `main`  | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of our users and their data very seriously. If you discover a security vulnerability in this project, please **do not** report it by creating a public GitHub issue. 
+
+Instead, please privately report it by emailing the repository owner directly.
+
+When reporting a vulnerability, please include:
+* A detailed description of the vulnerability.
+* The steps required to reproduce the vulnerability.
+* Any potential impact or risk to users.
+
+We will acknowledge your email within 48 hours and work with you to understand and resolve the issue. We aim to fix critical security issues as fast as possible and will credit you in the release notes if you wish.
+
+Thank you for helping keep this project secure!

backend/app/auth.py

@@ -67,12 +67,39 @@ def decode_token(token: str, token_type: str = "access") -> Optional[str]:
 
 # ── FastAPI Dependencies ─────────────────────────────
 
+import hashlib
+
 def get_current_user(
     credentials: HTTPAuthorizationCredentials = Depends(security),
     db: Session = Depends(get_db),
 ) -> User:
-    """Dependency: extract and validate user from JWT bearer token."""
+    """Dependency: extract and validate user from JWT bearer token or API key."""
     token = credentials.credentials
+
+    # Check if token is an API key
+    if token.startswith("rag_"):
+        hashed = hashlib.sha256(token.encode("utf-8")).hexdigest()
+        from app.models import ApiKey
+        api_key = db.query(ApiKey).filter(ApiKey.hashed_key == hashed).first()
+        if not api_key:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid API key",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        api_key.last_used = datetime.now(timezone.utc)
+        db.commit()
+
+        user = api_key.user
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found for this API key",
+            )
+        return user
+
+    # Otherwise, process as JWT
     user_id = decode_token(token)
 
     if not user_id:

backend/app/config.py

@@ -56,8 +56,18 @@ class Settings(BaseSettings):
     LLM_TEMPERATURE: float = 0.3
     SUMMARY_MAX_TOKENS: int = 512
 
+    # ── LangSmith Tracing (optional) ─────────────────────
+    LANGSMITH_TRACING: bool = False
+    LANGSMITH_API_KEY: str = ""
+    LANGSMITH_ENDPOINT: str = "https://api.smith.langchain.com"
+    LANGSMITH_PROJECT: str = "pdf-assistant-rag"
+
     # ── Reranker ─────────────────────────────────────────
     RERANKER_MODEL: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+    # ── Vision / Image captioning ─────────────────────
+    VISION_PROVIDER: str | None = None  # e.g. 'openai'
+    VISION_MODEL: str | None = None
+    OPENAI_API_KEY: str = ""
 
 
     @property

backend/app/database.py

@@ -3,11 +3,13 @@ SQLAlchemy database setup with SQLite.
 Uses synchronous SQLAlchemy for simplicity and compatibility.
 """
 import os
-from sqlalchemy import create_engine
+import logging
+from sqlalchemy import create_engine, inspect, text
 from sqlalchemy.orm import sessionmaker, declarative_base
 from app.config import get_settings
 
 settings = get_settings()
+logger = logging.getLogger(__name__)
 
 # ── Ensure data directory exists ─────────────────────
 db_path = settings.DATABASE_URL.replace("sqlite:///", "")
@@ -34,7 +36,34 @@ def get_db():
         db.close()
 
 
+def _migrate_schema():
+    """Apply schema migrations for existing databases (SQLite-compatible).
+
+    SQLAlchemy's ``create_all`` only creates new tables and does **not**
+    add missing columns to existing tables.  This helper fills that gap
+    for non-destructive changes such as new nullable columns.
+    """
+    inspector = inspect(engine)
+    existing_columns = {c["name"] for c in inspector.get_columns("users")}
+
+    migrations = [
+        ("users", "hf_token", "ALTER TABLE users ADD COLUMN hf_token VARCHAR(255)"),
+    ]
+
+    for table, column, ddl in migrations:
+        if column not in existing_columns:
+            try:
+                with engine.begin() as conn:
+                    conn.execute(text(ddl))
+                logger.info("Migration: added column %s.%s", table, column)
+            except Exception:
+                logger.warning(
+                    "Migration skipped (may already exist): %s.%s", table, column
+                )
+
+
 def init_db():
-    """Create all tables on startup."""
+    """Create all tables on startup and apply schema migrations."""
     from app import models  # noqa: F401 — import to register models
     Base.metadata.create_all(bind=engine)
+    _migrate_schema()

backend/app/models.py

@@ -22,10 +22,26 @@ class User(Base):
     is_admin = Column(Boolean, default=False)
     created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
     last_login = Column(DateTime, nullable=True, index=True)
+    hf_token = Column(String(255), nullable=True)
 
     # Relationships
     documents = relationship("Document", back_populates="owner", cascade="all, delete-orphan")
     messages = relationship("ChatMessage", back_populates="user", cascade="all, delete-orphan")
+    api_keys = relationship("ApiKey", back_populates="user", cascade="all, delete-orphan")
+
+
+class ApiKey(Base):
+    __tablename__ = "api_keys"
+
+    id = Column(String, primary_key=True, default=generate_uuid)
+    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
+    key_prefix = Column(String(10), nullable=False)
+    hashed_key = Column(String(255), nullable=False, unique=True, index=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+    last_used = Column(DateTime, nullable=True)
+
+    # Relationships
+    user = relationship("User", back_populates="api_keys")
 
 
 class Document(Base):

backend/app/rag/agent.py

@@ -10,6 +10,7 @@ from huggingface_hub import InferenceClient
 from app.config import get_settings
 from app.rag.retriever import retrieve
 from app.rag.prompts import SYSTEM_PROMPT, RAG_PROMPT_TEMPLATE, GREETING_PROMPT
+from app.rag.tracing import trace_function
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -65,6 +66,14 @@ def _chat_messages(system: str, user_content: str) -> list:
     ]
 
 
+@trace_function(
+    "generate_answer",
+    metadata_factory=lambda question, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "llm_model": settings.LLM_MODEL,
+    },
+)
 def generate_answer(
     question: str,
     user_id: str,
@@ -145,6 +154,14 @@ def generate_answer(
     return {"answer": answer, "sources": sources}
 
 
+@trace_function(
+    "generate_answer_stream",
+    metadata_factory=lambda question, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "llm_model": settings.LLM_MODEL,
+    },
+)
 def generate_answer_stream(
     question: str,
     user_id: str,

backend/app/rag/chunker.py

@@ -28,6 +28,34 @@ def extract_pdf(filepath: str) -> List[Dict[str, Any]]:
     return pages
 
 
+def extract_pdf_images(filepath: str) -> List[Dict[str, Any]]:
+    """Extract images from a PDF and return list of dicts with image bytes and page number.
+
+    Each entry: {"image_bytes": b"...", "page": int}
+    """
+    images = []
+    doc = fitz.open(filepath)
+
+    for page_num, page in enumerate(doc):
+        # get_images returns a list of tuples where first item is xref
+        for img in page.get_images(full=True):
+            xref = img[0]
+            try:
+                pix = fitz.Pixmap(doc, xref)
+                # Convert to RGB if it's CMYK or has alpha
+                if pix.n >= 4:
+                    pix = fitz.Pixmap(fitz.csRGB, pix)
+
+                img_bytes = pix.tobytes("png")
+                images.append({"image_bytes": img_bytes, "page": page_num + 1})
+            except Exception:
+                # ignore extracting this image
+                continue
+
+    doc.close()
+    return images
+
+
 def extract_docx(filepath: str) -> List[Dict[str, Any]]:
     """Extract text from DOCX files."""
     doc = docx.Document(filepath)
@@ -50,10 +78,13 @@ def chunk_document(filepath: str) -> List[Dict[str, Any]]:
     Returns list of dicts with 'text', 'page', and 'chunk_index'.
     """
     ext = filepath.rsplit(".", 1)[-1].lower()
+    images = []
 
     # ── Extract text by file type ────────────────────
     if ext == "pdf":
         pages = extract_pdf(filepath)
+        # also extract images for later captioning/embedding
+        images = extract_pdf_images(filepath)
     elif ext == "docx":
         pages = extract_docx(filepath)
     elif ext in ("txt", "md"):
@@ -91,6 +122,16 @@ def chunk_document(filepath: str) -> List[Dict[str, Any]]:
                 })
                 chunk_index += 1
 
+        # Attach any images that belong to this page after text chunks for the page
+        for img in [i for i in images if i["page"] == page_num]:
+            all_chunks.append({
+                "text": "",
+                "page": page_num,
+                "chunk_index": chunk_index,
+                "image_bytes": img["image_bytes"],
+            })
+            chunk_index += 1
+
     return all_chunks
 
 

backend/app/rag/embeddings.py

@@ -6,6 +6,7 @@ import logging
 from typing import List
 from langchain_huggingface import HuggingFaceEmbeddings
 from app.config import get_settings
+from app.rag.tracing import trace_call
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -36,10 +37,26 @@ def get_embedding_model() -> HuggingFaceEmbeddings:
 def embed_texts(texts: List[str]) -> List[List[float]]:
     """Embed a batch of texts into vectors."""
     model = get_embedding_model()
-    return model.embed_documents(texts)
+    return trace_call(
+        "embed_texts",
+        lambda: model.embed_documents(texts),
+        run_type="embedding",
+        metadata={
+            "embedding_model": settings.EMBEDDING_MODEL,
+            "text_count": len(texts),
+        },
+    )
 
 
 def embed_query(query: str) -> List[float]:
     """Embed a single query string."""
     model = get_embedding_model()
-    return model.embed_query(query)
+    return trace_call(
+        "embed_query",
+        lambda: model.embed_query(query),
+        run_type="embedding",
+        metadata={
+            "embedding_model": settings.EMBEDDING_MODEL,
+            "query_length": len(query),
+        },
+    )

backend/app/rag/retriever.py

@@ -5,6 +5,7 @@ import logging
 from typing import List, Dict, Any, Optional
 from app.config import get_settings
 from app.rag.embeddings import embed_query
+from app.rag.tracing import trace_function
 from app.rag.vectorstore import query_chunks
 
 logger = logging.getLogger(__name__)
@@ -31,6 +32,17 @@ def get_reranker():
     return _reranker if _reranker != "disabled" else None
 
 
+@trace_function(
+    "retrieve",
+    metadata_factory=lambda query, user_id, document_id=None: {
+        "user_id": user_id,
+        "document_id": document_id,
+        "embedding_model": settings.EMBEDDING_MODEL,
+        "reranker_model": settings.RERANKER_MODEL,
+        "top_k_retrieval": settings.TOP_K_RETRIEVAL,
+        "top_k_rerank": settings.TOP_K_RERANK,
+    },
+)
 def retrieve(
     query: str,
     user_id: str,

backend/app/rag/tracing.py

@@ -0,0 +1,102 @@
+"""
+Optional LangSmith tracing helpers for the RAG pipeline.
+Safe to import even when LangSmith is not installed or configured.
+"""
+import logging
+import os
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+try:
+    from langsmith import traceable as _langsmith_traceable
+except Exception:  # pragma: no cover - optional dependency safety
+    _langsmith_traceable = None
+
+
+def configure_langsmith() -> bool:
+    """Configure LangSmith environment variables when tracing is enabled."""
+    if not settings.LANGSMITH_TRACING:
+        return False
+
+    if not settings.LANGSMITH_API_KEY:
+        logger.warning("LangSmith tracing enabled but LANGSMITH_API_KEY is not set; tracing disabled.")
+        return False
+
+    os.environ["LANGSMITH_TRACING"] = "true"
+    os.environ["LANGSMITH_API_KEY"] = settings.LANGSMITH_API_KEY
+    os.environ["LANGSMITH_ENDPOINT"] = settings.LANGSMITH_ENDPOINT
+    os.environ["LANGSMITH_PROJECT"] = settings.LANGSMITH_PROJECT
+    return _langsmith_traceable is not None
+
+
+LANGSMITH_ENABLED = configure_langsmith()
+
+
+def _sanitize_metadata(metadata: Optional[dict[str, Any]]) -> dict[str, Any]:
+    return {key: value for key, value in (metadata or {}).items() if value is not None}
+
+
+def _build_traceable(name: str, run_type: str, metadata: Optional[dict[str, Any]] = None):
+    """Build a LangSmith traceable decorator safely across versions."""
+    if _langsmith_traceable is None:
+        return None
+
+    sanitized = _sanitize_metadata(metadata)
+    try:
+        return _langsmith_traceable(
+            name=name,
+            run_type=run_type,
+            metadata=sanitized or None,
+        )
+    except TypeError:
+        return _langsmith_traceable(name=name, run_type=run_type)
+
+
+def trace_call(
+    name: str,
+    fn: Callable[..., Any],
+    *args: Any,
+    run_type: str = "chain",
+    metadata: Optional[dict[str, Any]] = None,
+    **kwargs: Any,
+) -> Any:
+    """Execute a callable with LangSmith tracing when available."""
+    if not LANGSMITH_ENABLED:
+        return fn(*args, **kwargs)
+
+    decorator = _build_traceable(name, run_type, metadata)
+    if decorator is None:
+        return fn(*args, **kwargs)
+
+    traced_fn = decorator(fn)
+    return traced_fn(*args, **kwargs)
+
+
+def trace_function(
+    name: str,
+    *,
+    run_type: str = "chain",
+    metadata_factory: Optional[Callable[..., dict[str, Any]]] = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator wrapper that becomes a no-op when LangSmith is disabled."""
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(fn)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            metadata = metadata_factory(*args, **kwargs) if metadata_factory else None
+            return trace_call(
+                name,
+                fn,
+                *args,
+                run_type=run_type,
+                metadata=metadata,
+                **kwargs,
+            )
+
+        return wrapped
+
+    return decorator

backend/app/rag/vectorstore.py

@@ -8,6 +8,7 @@ import chromadb
 from chromadb.config import Settings as ChromaSettings
 from app.config import get_settings
 from app.rag.embeddings import get_embedding_model
+from app.rag.vision import generate_captions_for_chunks
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -55,6 +56,12 @@ def store_chunks(
     if not chunks:
         return 0
 
+    # Generate captions for any extracted images before embedding
+    try:
+        generate_captions_for_chunks(chunks)
+    except Exception as e:
+        logger.warning(f"Could not generate image captions: {e}")
+
     client = get_chroma_client()
     embedding_model = get_embedding_model()
 
@@ -74,6 +81,9 @@ def store_chunks(
             "document_id": document_id,
             "page": chunk["page"],
             "chunk_index": chunk["chunk_index"],
+            # Indicate whether this chunk was originally an image and include a short caption
+            **({"is_image": True, "image_caption": chunk.get("image_caption", "")}
+               if chunk.get("is_image") else {}),
         }
         for chunk in chunks
     ]

backend/app/rag/vision.py

@@ -0,0 +1,99 @@
+"""Image captioning / vision helpers for RAG pipeline.
+
+Provides a simple, pluggable interface to generate textual descriptions
+for images extracted from PDFs. By default it uses local OCR (pytesseract)
+when available as a robust fallback. An external VLM provider (OpenAI)
+can be integrated by setting `VISION_PROVIDER` and appropriate API keys
+in settings; the provider hook is intentionally small and optional.
+"""
+import logging
+from typing import List, Dict, Any
+from io import BytesIO
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+def _ocr_caption(image_bytes: bytes) -> str:
+    """Try to produce a caption using pytesseract OCR; returns empty string if not available."""
+    try:
+        from PIL import Image
+        import pytesseract
+    except Exception:
+        return ""
+
+    try:
+        img = Image.open(BytesIO(image_bytes)).convert("RGB")
+        text = pytesseract.image_to_string(img)
+        text = text.strip()
+        return text
+    except Exception as e:
+        logger.debug(f"OCR failed: {e}")
+        return ""
+
+
+def caption_image(image_bytes: bytes, page: int | None = None) -> str:
+    """Generate a caption for a single image.
+
+    Order of operations:
+    - If an external VLM provider is configured, attempt to call it (not implemented as mandatory).
+    - Fall back to local OCR (pytesseract) if available.
+    - Otherwise return a simple placeholder caption including the page number.
+    """
+    # Placeholder for provider-based captioning (e.g., OpenAI / LLaVA hooks)
+    provider = getattr(settings, "VISION_PROVIDER", None)
+    if provider == "openai":
+        try:
+            import openai
+            # Minimal integration: attempt a text-only caption via responses if available.
+            # This is a best-effort hook; users should adapt to their provider's API.
+            api_key = getattr(settings, "OPENAI_API_KEY", None)
+            if api_key:
+                openai.api_key = api_key
+                # Use a generic prompt: "Describe the following image"
+                # Note: concrete multimodal API usage may vary across SDK versions.
+                resp = openai.Image.create(
+                    prompt="Describe this image in one concise sentence.",
+                    n=1,
+                    # We do not re-upload image bytes here; this is a placeholder to show
+                    # where provider code would be invoked. For production, follow
+                    # provider docs for sending image data.
+                )
+                # openai.Image.create returns generated images, not captions — so skip.
+        except Exception:
+            # If provider integration fails, fall back to OCR below
+            logger.debug("OpenAI vision provider failed, falling back to OCR")
+
+    # Try OCR caption
+    ocr = _ocr_caption(image_bytes)
+    if ocr:
+        # Keep it short if very long
+        return (ocr[:500] + "...") if len(ocr) > 500 else ocr
+
+    # Last-resort caption
+    if page:
+        return f"Image on page {page}."
+    return "Image." 
+
+
+def generate_captions_for_chunks(chunks: List[Dict[str, Any]]) -> None:
+    """Mutate chunks in-place: for any chunk containing `image_bytes` but empty `text`,
+    generate a caption and set `text`.
+    """
+    for chunk in chunks:
+        if chunk.get("image_bytes") and not chunk.get("text"):
+            try:
+                caption = caption_image(chunk["image_bytes"], page=chunk.get("page"))
+                chunk["text"] = caption
+                # Remove raw bytes to avoid accidentally serializing them later
+                chunk.pop("image_bytes", None)
+                chunk["is_image"] = True
+                chunk["image_caption"] = caption
+            except Exception as e:
+                logger.debug(f"Failed to caption image chunk: {e}")
+                # ensure we still mark it as image to avoid losing it
+                chunk.pop("image_bytes", None)
+                chunk["is_image"] = True
+                chunk.setdefault("text", f"Image on page {chunk.get('page')}")

backend/app/routes/auth.py

@@ -11,7 +11,7 @@ from sqlalchemy.orm import Session
 from sqlalchemy import select
 from app.config import get_settings
 from app.database import get_db
-from app.models import User
+from app.models import User, ApiKey
 from app.schemas import (
     GoogleLoginRequest,
     RefreshRequest,
@@ -23,6 +23,8 @@ from app.schemas import (
     UserResponse,
     UserUpdate,
     UserUpdateResponse,
+    ApiKeyResponse,
+    ApiKeyCreateResponse,
 )
 from app.auth import hash_password, verify_password, create_access_token, create_refresh_token, get_current_user, decode_token
 
@@ -383,6 +385,42 @@ def update_password(payload:UpdatePassword,
         db.rollback()
         raise HTTPException(status_code=400, detail="Database error")
 
+from typing import List
+import hashlib
+
+@router.post("/api-keys", response_model=ApiKeyCreateResponse, status_code=status.HTTP_201_CREATED)
+def create_api_key(user: User = Depends(get_current_user), db: Session = Depends(get_db)):
+    """Create a new API key for the authenticated user."""
+    raw_key = "rag_" + secrets.token_urlsafe(32)
+    hashed_key = hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+    
+    api_key = ApiKey(
+        user_id=user.id,
+        key_prefix=raw_key[:10],
+        hashed_key=hashed_key,
+    )
+    db.add(api_key)
+    db.commit()
+    db.refresh(api_key)
+    
+    return {"key": raw_key, "api_key": api_key}
+
+@router.get("/api-keys", response_model=List[ApiKeyResponse])
+def list_api_keys(user: User = Depends(get_current_user), db: Session = Depends(get_db)):
+    """List all API keys for the authenticated user."""
+    return db.query(ApiKey).filter(ApiKey.user_id == user.id).all()
+
+@router.delete("/api-keys/{key_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_api_key(key_id: str, user: User = Depends(get_current_user), db: Session = Depends(get_db)):
+    """Revoke an API key."""
+    api_key = db.query(ApiKey).filter(ApiKey.id == key_id, ApiKey.user_id == user.id).first()
+    if not api_key:
+        raise HTTPException(status_code=404, detail="API key not found")
+    
+    db.delete(api_key)
+    db.commit()
+    return None
+
 @router.get("/config")
 def get_auth_config():
     """Return public configuration for auth providers"""

backend/app/schemas.py

@@ -53,11 +53,17 @@ class RefreshRequest(BaseModel):
     refresh_token: str
 
 
+class HFTokenUpdate(BaseModel):
+    """Request schema for updating the user's HuggingFace token."""
+    hf_token: str
+
+
 class UserResponse(BaseModel):
     id: str
     username: str
     email: str
     is_admin: bool
+    hf_token: Optional[str] = None
     created_at: datetime
 
     class Config:
@@ -136,5 +142,22 @@ class ChatHistoryResponse(BaseModel):
     document_id: Optional[str] = None
 
 
+# ── ApiKeys ─────────────────────────────────────────────
+
+class ApiKeyResponse(BaseModel):
+    id: str
+    key_prefix: str
+    created_at: datetime
+    last_used: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+class ApiKeyCreateResponse(BaseModel):
+    key: str
+    api_key: ApiKeyResponse
+
+
 # Rebuild models for forward references
 TokenResponse.model_rebuild()

backend/requirements.txt

@@ -18,6 +18,9 @@ google-auth
 # Config
 pydantic-settings
 pydantic[email]
+pytest
+pytest-cov
+httpx
 
 # Document Processing
 PyMuPDF
@@ -28,6 +31,7 @@ langchain
 langchain-community
 langchain-huggingface
 langchain-text-splitters
+langsmith
 
 # Embeddings & ML
 sentence-transformers

backend/tests/conftest.py

@@ -0,0 +1,183 @@
+import os
+import sys
+import types
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+
+ROOT = Path(__file__).resolve().parents[2]
+BACKEND_DIR = ROOT / "backend"
+
+if str(BACKEND_DIR) not in sys.path:
+    sys.path.insert(0, str(BACKEND_DIR))
+
+os.environ.setdefault("SECRET_KEY", "test-secret-key")
+os.environ.setdefault("DATABASE_URL", "sqlite:///./test_bootstrap.db")
+os.environ.setdefault("HF_TOKEN", "test-hf-token")
+os.environ.setdefault("UPLOAD_DIR", str(ROOT / "backend" / "test_uploads"))
+os.environ.setdefault("CHROMA_PERSIST_DIR", str(ROOT / "backend" / "test_chroma"))
+
+
+fake_embeddings = types.ModuleType("app.rag.embeddings")
+fake_embeddings.get_embedding_model = lambda: object()
+fake_embeddings.embed_query = lambda query: [0.0]
+fake_embeddings.embed_texts = lambda texts: [[0.0] for _ in texts]
+sys.modules.setdefault("app.rag.embeddings", fake_embeddings)
+
+
+class _FakeChromaClient:
+    def heartbeat(self):
+        return "ok"
+
+
+fake_vectorstore = types.ModuleType("app.rag.vectorstore")
+fake_vectorstore.get_chroma_client = lambda: _FakeChromaClient()
+fake_vectorstore.store_chunks = lambda chunks, document_id, filename, user_id: len(chunks)
+fake_vectorstore.delete_document_chunks = lambda document_id, user_id: None
+fake_vectorstore.query_chunks = lambda query_embedding, user_id, document_id=None, top_k=10: []
+sys.modules.setdefault("app.rag.vectorstore", fake_vectorstore)
+
+slowapi_module = types.ModuleType("slowapi")
+slowapi_errors = types.ModuleType("slowapi.errors")
+slowapi_middleware = types.ModuleType("slowapi.middleware")
+slowapi_util = types.ModuleType("slowapi.util")
+
+
+class RateLimitExceeded(Exception):
+    pass
+
+
+class SlowAPIMiddleware:
+    def __init__(self, app, *args, **kwargs):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        await self.app(scope, receive, send)
+
+
+class Limiter:
+    def __init__(self, key_func=None, *args, **kwargs):
+        self.key_func = key_func
+
+    def limit(self, _value):
+        def decorator(fn):
+            return fn
+        return decorator
+
+
+slowapi_errors.RateLimitExceeded = RateLimitExceeded
+slowapi_middleware.SlowAPIMiddleware = SlowAPIMiddleware
+slowapi_util.get_remote_address = lambda request: "127.0.0.1"
+slowapi_module.Limiter = Limiter
+
+sys.modules.setdefault("slowapi", slowapi_module)
+sys.modules.setdefault("slowapi.errors", slowapi_errors)
+sys.modules.setdefault("slowapi.middleware", slowapi_middleware)
+sys.modules.setdefault("slowapi.util", slowapi_util)
+
+from app.auth import create_access_token, create_refresh_token, hash_password
+from app.database import Base, get_db
+from app.main import app
+from app.models import Document, User
+
+
+@pytest.fixture()
+def db_session(tmp_path):
+    db_file = tmp_path / "test.db"
+    engine = create_engine(
+        f"sqlite:///{db_file}",
+        connect_args={"check_same_thread": False},
+    )
+    TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+    Base.metadata.create_all(bind=engine)
+
+    session = TestingSessionLocal()
+    try:
+        yield session
+    finally:
+        session.close()
+        Base.metadata.drop_all(bind=engine)
+        engine.dispose()
+
+
+@pytest.fixture()
+def client(db_session, monkeypatch):
+    def override_get_db():
+        try:
+            yield db_session
+        finally:
+            pass
+
+    @asynccontextmanager
+    async def no_lifespan(_app):
+        yield
+
+    monkeypatch.setattr("app.database.SessionLocal", lambda: db_session)
+    app.dependency_overrides[get_db] = override_get_db
+    app.router.lifespan_context = no_lifespan
+
+    with TestClient(app) as test_client:
+        yield test_client
+
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture()
+def user(db_session):
+    instance = User(
+        username="tester",
+        email="tester@example.com",
+        hashed_password=hash_password("password123"),
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance
+
+
+@pytest.fixture()
+def auth_headers(user):
+    token = create_access_token(user.id)
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.fixture()
+def refresh_token(user):
+    return create_refresh_token(user.id)
+
+
+@pytest.fixture()
+def ready_document(db_session, user):
+    instance = Document(
+        user_id=user.id,
+        filename="ready.txt",
+        original_name="ready.txt",
+        file_size=128,
+        page_count=1,
+        chunk_count=2,
+        status="ready",
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance
+
+
+@pytest.fixture()
+def pending_document(db_session, user):
+    instance = Document(
+        user_id=user.id,
+        filename="pending.txt",
+        original_name="pending.txt",
+        file_size=64,
+        status="pending",
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance

backend/tests/test_auth.py

@@ -0,0 +1,81 @@
+def test_register_success(client):
+    response = client.post(
+        "/api/v1/auth/register",
+        json={
+            "username": "newuser",
+            "email": "newuser@example.com",
+            "password": "password123",
+        },
+    )
+
+    assert response.status_code == 201
+    payload = response.json()
+    assert payload["access_token"]
+    assert payload["refresh_token"]
+    assert payload["user"]["email"] == "newuser@example.com"
+
+
+def test_register_duplicate_email_or_username_conflict(client):
+    payload = {
+        "username": "dupuser",
+        "email": "dup@example.com",
+        "password": "password123",
+    }
+    first = client.post("/api/v1/auth/register", json=payload)
+    assert first.status_code == 201
+
+    duplicate_email = client.post(
+        "/api/v1/auth/register",
+        json={**payload, "username": "anotheruser"},
+    )
+    assert duplicate_email.status_code == 409
+    assert duplicate_email.json()["detail"] == "Email already registered"
+
+    duplicate_username = client.post(
+        "/api/v1/auth/register",
+        json={**payload, "email": "another@example.com"},
+    )
+    assert duplicate_username.status_code == 409
+    assert duplicate_username.json()["detail"] == "Username already taken"
+
+
+def test_login_success(client, user):
+    response = client.post(
+        "/api/v1/auth/login",
+        json={"email": user.email, "password": "password123"},
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["access_token"]
+    assert payload["refresh_token"]
+    assert payload["user"]["username"] == user.username
+
+
+def test_login_invalid_password(client, user):
+    response = client.post(
+        "/api/v1/auth/login",
+        json={"email": user.email, "password": "wrong-password"},
+    )
+
+    assert response.status_code == 401
+    assert response.json()["detail"] == "Invalid email or password"
+
+
+def test_auth_me_requires_auth(client):
+    response = client.get("/api/v1/auth/me")
+
+    assert response.status_code in (401, 403)
+
+
+def test_refresh_token_success(client, refresh_token):
+    response = client.post(
+        "/api/v1/auth/refresh",
+        json={"refresh_token": refresh_token},
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["access_token"]
+    assert payload["refresh_token"]
+    assert payload["token_type"] == "bearer"

backend/tests/test_chat.py

@@ -0,0 +1,50 @@
+def test_chat_ask_success(client, auth_headers, ready_document, monkeypatch):
+    monkeypatch.setattr(
+        "app.routes.chat.generate_answer",
+        lambda question, user_id, document_id=None: {
+            "answer": "Mocked answer",
+            "sources": [
+                {
+                    "text": "Mock source",
+                    "filename": "ready.txt",
+                    "page": 1,
+                    "score": 0.99,
+                    "confidence": 99.0,
+                }
+            ],
+        },
+    )
+
+    response = client.post(
+        "/api/v1/chat/ask",
+        headers=auth_headers,
+        json={"question": "What is in the doc?", "document_id": ready_document.id},
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["answer"] == "Mocked answer"
+    assert payload["document_id"] == ready_document.id
+    assert payload["sources"][0]["filename"] == "ready.txt"
+
+
+def test_chat_ask_document_not_found(client, auth_headers):
+    response = client.post(
+        "/api/v1/chat/ask",
+        headers=auth_headers,
+        json={"question": "Missing doc?", "document_id": "missing-doc-id"},
+    )
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Document not found"
+
+
+def test_chat_ask_document_not_ready(client, auth_headers, pending_document):
+    response = client.post(
+        "/api/v1/chat/ask",
+        headers=auth_headers,
+        json={"question": "Pending doc?", "document_id": pending_document.id},
+    )
+
+    assert response.status_code == 400
+    assert "Document is still pending" in response.json()["detail"]

backend/tests/test_chunker.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+import pytest
+
+from app.rag.chunker import chunk_document, get_page_count
+
+
+def test_txt_extraction_and_chunking(tmp_path):
+    file_path = tmp_path / "notes.txt"
+    file_path.write_text("This is a sample text file for chunking.", encoding="utf-8")
+
+    chunks = chunk_document(str(file_path))
+
+    assert len(chunks) >= 1
+    assert chunks[0]["page"] == 1
+    assert "sample text file" in chunks[0]["text"]
+
+
+def test_empty_txt_returns_no_chunks(tmp_path):
+    file_path = tmp_path / "empty.txt"
+    file_path.write_text("   \n", encoding="utf-8")
+
+    assert chunk_document(str(file_path)) == []
+
+
+def test_unsupported_extension_raises_value_error(tmp_path):
+    file_path = tmp_path / "data.csv"
+    file_path.write_text("a,b,c", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="Unsupported file type"):
+        chunk_document(str(file_path))
+
+
+def test_get_page_count_for_txt_returns_one(tmp_path):
+    file_path = tmp_path / "single.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    assert get_page_count(str(file_path)) == 1

backend/tests/test_documents.py

@@ -0,0 +1,34 @@
+def test_api_health(client):
+    response = client.get("/api/health")
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["status"] == "healthy"
+    assert payload["version"] == "2.0.0"
+
+
+def test_protected_documents_list_requires_auth(client):
+    response = client.get("/api/v1/documents/")
+
+    assert response.status_code in (401, 403)
+
+
+def test_documents_list_authenticated(client, auth_headers, ready_document):
+    response = client.get("/api/v1/documents/", headers=auth_headers)
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["total"] == 1
+    assert payload["items"][0]["id"] == ready_document.id
+    assert payload["items"][0]["original_name"] == "ready.txt"
+
+
+def test_upload_rejects_unsupported_extension_before_deep_validation(client, auth_headers):
+    response = client.post(
+        "/api/v1/documents/upload",
+        headers=auth_headers,
+        files={"file": ("payload.exe", b"binary-data", "application/octet-stream")},
+    )
+
+    assert response.status_code == 400
+    assert "not supported" in response.json()["detail"]

bots/discord/README.md

@@ -0,0 +1,37 @@
+# Discord RAG Bot
+
+This bot connects to the PDF-Assistant-RAG backend to answer questions based on your uploaded documents, directly from Discord.
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Create a Discord Bot on the [Discord Developer Portal](https://discord.com/developers/applications):
+   - Go to "Bot" tab and enable **Message Content Intent**.
+   - Copy the bot token.
+   - Invite the bot to your server via the OAuth2 URL Generator (check `bot` scope and `Send Messages` permission).
+
+3. Generate an API Key from your PDF-Assistant-RAG profile dashboard.
+
+4. Set the environment variables and run:
+   ```bash
+   export DISCORD_TOKEN="your-discord-bot-token"
+   export RAG_API_KEY="rag_your-api-key"
+   
+   # Optional: set API_URL if backend is not running on localhost:8000
+   # export API_URL="http://localhost:8000/api/v1"
+   
+   python bot.py
+   ```
+
+## Usage
+In a Discord channel where the bot is present, simply use the `!ask` command:
+
+```
+!ask Summarize the latest uploaded report for me
+```
+
+The bot will query the backend API using your personal API key and reply with the generated answer.

bots/discord/bot.py

@@ -0,0 +1,68 @@
+import os
+import discord
+import requests
+from discord.ext import commands
+
+DISCORD_TOKEN = os.getenv("DISCORD_TOKEN")
+API_URL = os.getenv("API_URL", "http://localhost:8000/api/v1")
+RAG_API_KEY = os.getenv("RAG_API_KEY")
+
+if not DISCORD_TOKEN or not RAG_API_KEY:
+    print("Error: DISCORD_TOKEN and RAG_API_KEY must be set in environment variables.")
+    exit(1)
+
+intents = discord.Intents.default()
+intents.message_content = True
+bot = commands.Bot(command_prefix="!", intents=intents)
+
+@bot.event
+async def on_ready():
+    print(f"Logged in as {bot.user.name} ({bot.user.id})")
+    print("Ready to answer questions via '!ask <question>'")
+
+@bot.command(name="ask")
+async def ask_rag(ctx, *, question: str):
+    """Ask the RAG Assistant a question. Example: !ask What is in my documents?"""
+    loading_msg = await ctx.send("🤔 Thinking...")
+    
+    try:
+        headers = {
+            "Authorization": f"Bearer {RAG_API_KEY}",
+            "Content-Type": "application/json"
+        }
+        
+        # We can also support document_id if we want, but for now we do global ask.
+        payload = {"question": question}
+        
+        response = requests.post(
+            f"{API_URL}/chat/ask",
+            json=payload,
+            headers=headers,
+            timeout=30  # Give the RAG backend some time to process
+        )
+        
+        if response.status_code == 200:
+            data = response.json()
+            answer = data.get("answer", "No answer provided.")
+            
+            if len(answer) > 2000:
+                # Discord has a 2000 character limit per message
+                chunks = [answer[i:i+2000] for i in range(0, len(answer), 2000)]
+                await loading_msg.edit(content=chunks[0])
+                for chunk in chunks[1:]:
+                    await ctx.send(chunk)
+            else:
+                await loading_msg.edit(content=answer)
+        else:
+            await loading_msg.edit(content=f"⚠️ Error from RAG API: `{response.status_code}`")
+            print(f"API Error: {response.text}")
+            
+    except requests.exceptions.RequestException as e:
+        await loading_msg.edit(content=f"❌ Failed to connect to backend API.")
+        print(f"Request Error: {e}")
+    except Exception as e:
+        await loading_msg.edit(content=f"❌ An unexpected error occurred.")
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    bot.run(DISCORD_TOKEN)

bots/discord/requirements.txt

@@ -0,0 +1,2 @@
+discord.py==2.3.2
+requests==2.31.0

frontend/package-lock.json

@@ -15,6 +15,7 @@
         "i18next-browser-languagedetector": "^8.2.1",
         "lucide-react": "^1.8.0",
         "next": "16.2.4",
+        "next-themes": "^0.4.6",
         "pdfjs-dist": "^5.6.205",
         "react": "19.2.4",
         "react-dom": "19.2.4",
@@ -8755,6 +8756,16 @@
         }
       }
     },
+    "node_modules/next-themes": {
+      "version": "0.4.6",
+      "resolved": "https://registry.npmjs.org/next-themes/-/next-themes-0.4.6.tgz",
+      "integrity": "sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc"
+      }
+    },
     "node_modules/next/node_modules/postcss": {
       "version": "8.4.31",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",

frontend/package.json

@@ -18,6 +18,7 @@
     "i18next-browser-languagedetector": "^8.2.1",
     "lucide-react": "^1.8.0",
     "next": "16.2.4",
+    "next-themes": "^0.4.6",
     "pdfjs-dist": "^5.6.205",
     "react": "19.2.4",
     "react-dom": "19.2.4",

frontend/src/app/dashboard/page.tsx

@@ -57,11 +57,23 @@ export default function DashboardPage() {
   const [connectionError, setConnectionError] = useState("");
   const [documentsLoading, setDocumentsLoading] = useState(true);
 
-  // Auth guard
+    // Auth guard
   useEffect(() => {
     if (!loading && !user) router.replace("/login");
   }, [user, loading, router]);
 
+  // Intercept dashboard if Hugging Face token configuration is missing
+  useEffect(() => {
+    if (user) {
+      const existingHfToken = localStorage.getItem("hf_token");
+
+      if (!existingHfToken) {
+        console.warn("Hugging Face API configuration key missing.");
+      }
+    }
+  }, [user]);
+
+
   // Load documents
   const loadDocuments = useCallback(async () => {
     try {

frontend/src/app/globals.css

@@ -83,6 +83,35 @@
   --sidebar-ring: oklch(0.65 0.2 265);
 }
 
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.178 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.178 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.65 0.2 265);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.22 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.22 0 0);
+  --muted-foreground: oklch(0.6 0 0);
+  --accent: oklch(0.55 0.18 265);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 12%);
+  --ring: oklch(0.65 0.2 265);
+  --sidebar: oklch(0.12 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.65 0.2 265);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.22 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 8%);
+  --sidebar-ring: oklch(0.65 0.2 265);
+}
+
 .light {
   --background: oklch(0.985 0 0);
   --foreground: oklch(0.145 0 0);

frontend/src/app/layout.tsx

@@ -4,6 +4,7 @@ import "./globals.css";
 import { AuthProvider } from "@/lib/auth";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import I18nProvider from "@/components/providers/I18nProvider";
+import { ThemeProvider } from "@/components/layout/ThemeProvider";
 
 const inter = Inter({
   variable: "--font-sans",
@@ -24,15 +25,20 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en" className={`${inter.variable} dark h-full antialiased`}>
+    <html lang="en" className={`${inter.variable} h-full antialiased`} suppressHydrationWarning>
       <body className="min-h-full flex flex-col bg-background text-foreground">
-        <AuthProvider>
-          <I18nProvider>
-            <TooltipProvider>
-              {children}
-            </TooltipProvider>
-          </I18nProvider>
-        </AuthProvider>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          enableSystem={false}
+          disableTransitionOnChange
+        >
+          <AuthProvider>
+            <I18nProvider>
+              <TooltipProvider>{children}</TooltipProvider>
+            </I18nProvider>
+          </AuthProvider>
+        </ThemeProvider>
       </body>
     </html>
   );

frontend/src/components/auth/ApiKeyManager.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
+import { api } from "@/lib/api";
+import { Key, Plus, Trash2, Copy, Check } from "lucide-react";
+
+interface ApiKey {
+  id: string;
+  key_prefix: string;
+  created_at: string;
+  last_used: string | null;
+}
+
+export default function ApiKeyManager() {
+  const [keys, setKeys] = useState<ApiKey[]>([]);
+  const [newKey, setNewKey] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [copied, setCopied] = useState(false);
+
+  const fetchKeys = async () => {
+    try {
+      setLoading(true);
+      const data = await api.get<ApiKey[]>("/api/v1/auth/api-keys");
+      setKeys(data || []);
+    } catch (err) {
+      console.error("Failed to load API keys", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      fetchKeys();
+    }, 0);
+    return () => clearTimeout(timer);
+  }, []);
+
+  const generateKey = async () => {
+    try {
+      setLoading(true);
+      const data = await api.post<{ key: string; api_key: ApiKey }>("/api/v1/auth/api-keys");
+      setNewKey(data.key);
+      setKeys((prev) => [...prev, data.api_key]);
+    } catch (err) {
+      console.error("Failed to generate API key", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const revokeKey = async (id: string) => {
+    if (!confirm("Are you sure you want to revoke this key? Any integrations using it will immediately break.")) return;
+    
+    try {
+      await api.delete(`/api/v1/auth/api-keys/${id}`);
+      setKeys((prev) => prev.filter((k) => k.id !== id));
+    } catch (err) {
+      console.error("Failed to revoke API key", err);
+    }
+  };
+
+  const copyToClipboard = () => {
+    if (newKey) {
+      navigator.clipboard.writeText(newKey);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  };
+
+  return (
+    <Dialog onOpenChange={(open) => { if (!open) setNewKey(null); }}>
+      <DialogTrigger
+        render={
+          <button className="flex w-full cursor-pointer items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors hover:bg-accent hover:text-accent-foreground">
+            <Key className="mr-2 h-4 w-4" />
+            <span>API Keys</span>
+          </button>
+        }
+      />
+      <DialogContent className="max-w-2xl sm:rounded-2xl border-border/40 p-6 md:p-8 bg-background/95 backdrop-blur-xl shadow-2xl">
+
+        <DialogHeader>
+          <DialogTitle className="text-2xl font-bold tracking-tight">API Keys</DialogTitle>
+          <p className="text-sm text-muted-foreground mt-1.5">
+            Manage API keys to access the RAG engine programmatically from your own applications or scripts.
+          </p>
+        </DialogHeader>
+
+        {newKey && (
+          <div className="my-6 p-5 border border-primary/20 bg-primary/5 rounded-xl space-y-3 animate-in fade-in zoom-in-95 duration-300">
+            <h4 className="font-semibold text-primary flex items-center gap-2">
+              <Key className="w-4 h-4" /> Save your new API key
+            </h4>
+            <p className="text-sm text-muted-foreground">
+              Please copy this key and store it somewhere safe. For security reasons, you will <strong>never</strong> be able to view it again.
+            </p>
+            <div className="flex items-center gap-2 mt-2">
+              <code className="flex-1 bg-background/80 border border-border/50 px-4 py-2.5 rounded-lg text-sm font-mono break-all text-foreground shadow-inner">
+                {newKey}
+              </code>
+              <Button onClick={copyToClipboard} variant={copied ? "default" : "secondary"} className="shrink-0 shadow-sm">
+                {copied ? <Check className="w-4 h-4 mr-2" /> : <Copy className="w-4 h-4 mr-2" />}
+                {copied ? "Copied!" : "Copy"}
+              </Button>
+            </div>
+          </div>
+        )}
+
+        <div className="space-y-4 mt-6">
+          <div className="flex items-center justify-between">
+            <h3 className="text-sm font-medium text-foreground/80 uppercase tracking-wider">Active Keys</h3>
+            <Button onClick={generateKey} disabled={loading} size="sm" className="rounded-full shadow-sm hover:shadow-md transition-shadow">
+              <Plus className="w-4 h-4 mr-1.5" />
+              Generate New Key
+            </Button>
+          </div>
+
+          <div className="rounded-xl border border-border/50 bg-card overflow-hidden shadow-sm">
+            {keys.length === 0 ? (
+              <div className="p-8 text-center text-sm text-muted-foreground bg-muted/20">
+                <Key className="w-8 h-8 mx-auto mb-3 opacity-20" />
+                You don&apos;t have any API keys yet.
+              </div>
+            ) : (
+              <div className="divide-y divide-border/50">
+                {keys.map((key) => (
+                  <div key={key.id} className="flex items-center justify-between p-4 hover:bg-muted/30 transition-colors group">
+                    <div className="space-y-1">
+                      <div className="font-mono text-sm font-medium tracking-tight">
+                        {key.key_prefix}••••••••••••••••••••••
+                      </div>
+                      <div className="text-xs text-muted-foreground flex gap-4">
+                        <span>Created: {new Date(key.created_at).toLocaleDateString()}</span>
+                        <span>Last used: {key.last_used ? new Date(key.last_used).toLocaleDateString() : "Never"}</span>
+                      </div>
+                    </div>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      onClick={() => revokeKey(key.id)}
+                      className="text-destructive/70 hover:text-destructive hover:bg-destructive/10 opacity-0 group-hover:opacity-100 transition-all"
+                      title="Revoke key"
+                    >
+                      <Trash2 className="w-4 h-4" />
+                    </Button>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend/src/components/chat/SourceCard.tsx

@@ -4,7 +4,14 @@ import { useState } from "react";
 import type { SourceChunk } from "@/store/chat-store";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
-import { ChevronDown, ChevronUp, FileText, Eye } from "lucide-react";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { ChevronDown, ChevronUp, FileText, Eye, TextQuote } from "lucide-react";
+
+const EXCERPT_THRESHOLD = 200;
 
 interface Props {
   sources: SourceChunk[];
@@ -13,89 +20,125 @@ interface Props {
 
 export default function SourceCard({ sources = [], onPageClick }: Props) {
   const [expanded, setExpanded] = useState(false);
+  const [excerptOpen, setExcerptOpen] = useState<Set<number>>(new Set());
 
   if (sources.length === 0) return null;
 
+  const toggleExcerpt = (i: number) => {
+    const next = new Set(excerptOpen);
+    if (next.has(i)) {
+      next.delete(i);
+    } else {
+      next.add(i);
+    }
+    setExcerptOpen(next);
+  };
+
   return (
     <div className="rounded-lg border border-border/50 bg-card/50 overflow-hidden">
-      {/* ── Header ──────────────────────────────────── */}
-      <button
-        onClick={() => setExpanded(!expanded)}
-        className="w-full flex items-center justify-between px-3 py-2 text-xs hover:bg-accent/30 transition-colors"
-      >
-        <span className="flex items-center gap-1.5 text-muted-foreground">
-          <FileText className="w-3.5 h-3.5" />
-          {sources.length} source{sources.length > 1 ? "s" : ""} cited
-        </span>
-        {expanded ? (
-          <ChevronUp className="w-3.5 h-3.5 text-muted-foreground" />
-        ) : (
-          <ChevronDown className="w-3.5 h-3.5 text-muted-foreground" />
-        )}
-      </button>
+        {/* ── Header ──────────────────────────────────── */}
+        <button
+          onClick={() => setExpanded(!expanded)}
+          className="w-full flex items-center justify-between px-3 py-2 text-xs hover:bg-accent/30 transition-colors"
+        >
+          <span className="flex items-center gap-1.5 text-muted-foreground">
+            <FileText className="w-3.5 h-3.5" />
+            {sources.length} source{sources.length > 1 ? "s" : ""} cited
+          </span>
+          {expanded ? (
+            <ChevronUp className="w-3.5 h-3.5 text-muted-foreground" />
+          ) : (
+            <ChevronDown className="w-3.5 h-3.5 text-muted-foreground" />
+          )}
+        </button>
 
-      {/* ── Collapsed: Mini badges ──────────────────── */}
-      {!expanded && (
-        <div className="px-3 pb-2 flex flex-wrap gap-1">
-          {sources.map((src, i) => (
-            <Badge
-              key={i}
-              variant="secondary"
-              className="text-[10px] h-5 cursor-pointer hover:bg-primary/20 transition-colors"
-              onClick={() => onPageClick(src.page + 1)}
-            >
-              p.{src.page + 1} • {src.confidence}%
-            </Badge>
-          ))}
-        </div>
-      )}
-
-      {/* ── Expanded: Full source cards ─────────────── */}
-      {expanded && (
-        <div className="border-t border-border/30">
-          {sources.map((src, i) => (
-            <div
-              key={i}
-              className="px-3 py-2.5 border-b border-border/20 last:border-b-0 hover:bg-accent/20 transition-colors"
-            >
-              <div className="flex items-center justify-between mb-1.5">
-                <div className="flex items-center gap-2">
-                  <span className="text-[10px] font-medium text-muted-foreground">
-                    {src.filename}
-                  </span>
-                  <Badge variant="outline" className="text-[9px] h-4 px-1.5">
-                    Page {src.page + 1}
-                  </Badge>
+        {/* ── Collapsed: Mini badges with hover preview ── */}
+        {!expanded && (
+          <div className="px-3 pb-2 flex flex-wrap gap-1">
+            {sources.map((src, i) => (
+              <Tooltip key={i}>
+                <TooltipTrigger className="inline-flex">
                   <Badge
                     variant="secondary"
-                    className={`text-[9px] h-4 px-1.5 ${
-                      src.confidence >= 80
-                        ? "text-emerald-400 bg-emerald-400/10"
-                        : src.confidence >= 50
-                        ? "text-yellow-400 bg-yellow-400/10"
-                        : "text-muted-foreground"
-                    }`}
+                    className="text-[10px] h-5 cursor-pointer hover:bg-primary/20 transition-colors"
+                    onClick={() => onPageClick(src.page + 1)}
                   >
-                    {src.confidence}% match
+                    p.{src.page + 1} • {src.confidence}%
                   </Badge>
+                </TooltipTrigger>
+                <TooltipContent
+                  side="top"
+                  align="center"
+                  className="max-w-xs p-2"
+                >
+                  <p className="text-[11px] leading-relaxed line-clamp-6">
+                    {src.text}
+                  </p>
+                </TooltipContent>
+              </Tooltip>
+            ))}
+          </div>
+        )}
+
+        {/* ── Expanded: Full source cards ─────────────── */}
+        {expanded && (
+          <div className="border-t border-border/30">
+            {sources.map((src, i) => (
+              <div
+                key={i}
+                className="px-3 py-2.5 border-b border-border/20 last:border-b-0 hover:bg-accent/20 transition-colors"
+              >
+                <div className="flex items-center justify-between mb-1.5">
+                  <div className="flex items-center gap-2">
+                    <span className="text-[10px] font-medium text-muted-foreground">
+                      {src.filename}
+                    </span>
+                    <Badge variant="outline" className="text-[9px] h-4 px-1.5">
+                      Page {src.page + 1}
+                    </Badge>
+                    <Badge
+                      variant="secondary"
+                      className={`text-[9px] h-4 px-1.5 ${
+                        src.confidence >= 80
+                          ? "text-emerald-400 bg-emerald-400/10"
+                          : src.confidence >= 50
+                          ? "text-yellow-400 bg-yellow-400/10"
+                          : "text-muted-foreground"
+                      }`}
+                    >
+                      {src.confidence}% match
+                    </Badge>
+                  </div>
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-6 px-2 text-[10px]"
+                    onClick={() => onPageClick(src.page + 1)}
+                  >
+                    <Eye className="w-3 h-3 mr-1" />
+                    View
+                  </Button>
                 </div>
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  className="h-6 px-2 text-[10px]"
-                  onClick={() => onPageClick(src.page + 1)}
+                <p
+                  className={`text-[11px] text-muted-foreground leading-relaxed ${
+                    excerptOpen.has(i) ? "" : "line-clamp-3"
+                  }`}
                 >
-                  <Eye className="w-3 h-3 mr-1" />
-                  View
-                </Button>
+                  {src.text}
+                </p>
+                {src.text.length > EXCERPT_THRESHOLD && (
+                  <button
+                    onClick={() => toggleExcerpt(i)}
+                    className="mt-1.5 flex items-center gap-1 text-[10px] text-primary/70 hover:text-primary transition-colors"
+                  >
+                    <TextQuote className="w-3 h-3" />
+                    {excerptOpen.has(i) ? "Hide excerpt" : "Show excerpt"}
+                  </button>
+                )}
               </div>
-              <p className="text-[11px] text-muted-foreground leading-relaxed line-clamp-3">
-                {src.text}
-              </p>
-            </div>
-          ))}
-        </div>
-      )}
+            ))}
+          </div>
+        )}
     </div>
   );
 }

frontend/src/components/layout/Header.tsx

@@ -22,7 +22,10 @@ import {
   Moon,
   Sun,
 } from "lucide-react";
-import { useState } from "react";
+import { useSyncExternalStore } from "react";
+import { useTheme } from "next-themes";
+import ApiKeyManager from "@/components/auth/ApiKeyManager";
+
 
 interface HeaderProps {
   sidebarOpen: boolean;
@@ -31,23 +34,19 @@ interface HeaderProps {
   onToggleViewer: () => void;
 }
 
+const subscribe = () => () => {};
+const getSnapshot = () => true;
+const getServerSnapshot = () => false;
+
 export default function Header({ sidebarOpen, onToggleSidebar, viewerOpen, onToggleViewer }: HeaderProps) {
   const { user, logout } = useAuth();
   const { t, i18n } = useTranslation();
   const router = useRouter();
-  const [isDark, setIsDark] = useState(true);
+  const { theme, setTheme } = useTheme();
+  const mounted = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot); // ← replaces useState + useEffect
 
-  const toggleTheme = () => {
-    const html = document.documentElement;
-    if (isDark) {
-      html.classList.remove("dark");
-      html.classList.add("light");
-    } else {
-      html.classList.remove("light");
-      html.classList.add("dark");
-    }
-    setIsDark(!isDark);
-  };
+  const isDark = theme === "dark";
+  const toggleTheme = () => setTheme(isDark ? "light" : "dark");
 
   const handleLogout = () => {
     logout();
@@ -89,9 +88,11 @@ export default function Header({ sidebarOpen, onToggleSidebar, viewerOpen, onTog
           {viewerOpen ? <PanelRightClose className="w-4 h-4" /> : <PanelRightOpen className="w-4 h-4" />}
         </Button>
 
-        <Button variant="ghost" size="icon" className="h-8 w-8" onClick={toggleTheme} title={isDark ? t("header.lightMode") : t("header.darkMode")}>
-          {isDark ? <Sun className="w-4 h-4" /> : <Moon className="w-4 h-4" />}
-        </Button>
+        {mounted && (
+          <Button variant="ghost" size="icon" className="h-8 w-8" onClick={toggleTheme} title={isDark ? t("header.lightMode") : t("header.darkMode")}>
+            {isDark ? <Sun className="w-4 h-4" /> : <Moon className="w-4 h-4" />}
+          </Button>
+        )}
 
         <select
           aria-label={t("common.language")}
@@ -106,20 +107,27 @@ export default function Header({ sidebarOpen, onToggleSidebar, viewerOpen, onTog
         </select>
 
         <DropdownMenu>
-          <DropdownMenuTrigger className="flex items-center h-8 gap-2 px-2 rounded-md hover:bg-accent transition-colors cursor-pointer">
-            <Avatar className="w-6 h-6">
-              <AvatarFallback className="text-[10px] bg-primary/20 text-primary">
-                {user?.username?.slice(0, 2).toUpperCase() || "U"}
-              </AvatarFallback>
-            </Avatar>
-            <span className="text-sm hidden sm:inline">{user?.username}</span>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" className="w-48">
+          <DropdownMenuTrigger
+            render={
+              <button className="flex items-center h-8 gap-2 px-2 rounded-md hover:bg-accent transition-colors cursor-pointer">
+                <Avatar className="w-6 h-6">
+                  <AvatarFallback className="text-[10px] bg-primary/20 text-primary">
+                    {user?.username?.slice(0, 2).toUpperCase() || "U"}
+                  </AvatarFallback>
+                </Avatar>
+                <span className="text-sm hidden sm:inline">{user?.username}</span>
+              </button>
+            }
+          />
+
+          <DropdownMenuContent align="end" className="w-56">
             <div className="px-3 py-2">
               <p className="text-sm font-medium">{user?.username}</p>
               <p className="text-xs text-muted-foreground truncate">{user?.email}</p>
             </div>
             <DropdownMenuSeparator />
+            <ApiKeyManager />
+            <DropdownMenuSeparator />
             <DropdownMenuItem className="text-destructive cursor-pointer" onClick={handleLogout}>
               <LogOut className="w-4 h-4 mr-2" />
               {t("header.signOut")}
@@ -129,4 +137,4 @@ export default function Header({ sidebarOpen, onToggleSidebar, viewerOpen, onTog
       </div>
     </header>
   );
-}
+}

frontend/src/components/layout/ThemeProvider.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { ThemeProvider as NextThemesProvider } from "next-themes";
+import { type ThemeProviderProps } from "next-themes";
+
+export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
+  return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
+}

frontend/src/components/layout/ThemeToggle.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { useTheme } from "next-themes";
+import { useSyncExternalStore } from "react";
+import { Sun, Moon } from "lucide-react";
+
+// useSyncExternalStore with identical server/client snapshots = no hydration mismatch
+const subscribe = () => () => {};
+const getSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  const mounted = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  if (!mounted) return null;
+
+  return (
+    <button
+      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+      aria-label="Toggle theme"
+      className="rounded-md p-2 transition-colors hover:bg-gray-100 dark:hover:bg-gray-800"
+    >
+      {theme === "dark" ? (
+        <Sun className="h-5 w-5 text-yellow-400" />
+      ) : (
+        <Moon className="h-5 w-5 text-gray-700" />
+      )}
+    </button>
+  );
+}