Merge branch 'dev' into admin-metrics

.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.

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,6 +56,12 @@ 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 ─────────────────────

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/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/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:
@@ -154,5 +160,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

@@ -31,6 +31,7 @@ langchain
 langchain-community
 langchain-huggingface
 langchain-text-splitters
+langsmith
 
 # Embeddings & ML
 sentence-transformers

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

@@ -13,6 +13,7 @@
         "clsx": "^2.1.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",
@@ -8691,6 +8692,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

@@ -16,6 +16,7 @@
     "clsx": "^2.1.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/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

@@ -3,6 +3,7 @@ import { Inter } from "next/font/google";
 import "./globals.css";
 import { AuthProvider } from "@/lib/auth";
 import { TooltipProvider } from "@/components/ui/tooltip";
+import { ThemeProvider } from "@/components/layout/ThemeProvider";
 
 const inter = Inter({
   variable: "--font-sans",
@@ -23,14 +24,21 @@ 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>
-          <TooltipProvider>
-            {children}
-          </TooltipProvider>
-        </AuthProvider>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          enableSystem={false}
+          disableTransitionOnChange
+        >
+          <AuthProvider>
+            <TooltipProvider>
+              {children}
+            </TooltipProvider>
+          </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 {
   Shield,
   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,22 +34,18 @@ 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 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();
@@ -75,20 +74,27 @@ 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 ? "Light mode" : "Dark mode"}>
-          {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 ? "Light mode" : "Dark mode"}>
+            {isDark ? <Sun className="w-4 h-4" /> : <Moon className="w-4 h-4" />}
+          </Button>
+        )}
 
         <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>
@@ -110,4 +116,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>
+  );
+}