Merge branch 'dev' into fix/mobile-responsiveness-130

.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/ISSUE_TEMPLATE/bug_report.yml

@@ -1,84 +1,65 @@
-name: 🐛 Bug Report
-description: Report a bug or unexpected behavior
-labels: ["bug", "needs-triage"]
-assignees: []
-
+name: "\U0001f41b Bug Report"
+description: "Create a report to help us improve the project by fixing a bug."
+title: "[BUG] "
+labels: ["bug"]
+assignees:
+  - "param20h"
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for taking the time to file a bug report! Please fill this out as completely as possible.
+        Thanks for taking the time to fill out this bug report! 
+        Before you submit, please search the issue tracker to see if this has already been reported.
 
   - type: textarea
     id: description
     attributes:
-      label: Describe the Bug
-      description: A clear description of what the bug is.
-      placeholder: "When I do X, Y happens instead of Z."
+      label: "Description of the Bug"
+      description: "A clear and concise description of what the bug is."
+      placeholder: "When I click on X, nothing happens..."
     validations:
       required: true
 
   - type: textarea
     id: reproduction
     attributes:
-      label: Steps to Reproduce
-      description: How do we reproduce this bug?
-      placeholder: |
+      label: "Steps to Reproduce"
+      description: "How can we reproduce this issue?"
+      value: |
         1. Go to '...'
-        2. Click on '...'
-        3. See error
+        2. Click on '....'
+        3. Scroll down to '....'
+        4. See error
     validations:
       required: true
 
   - type: textarea
     id: expected
     attributes:
-      label: Expected Behavior
-      description: What should have happened?
+      label: "Expected Behavior"
+      description: "A clear and concise description of what you expected to happen."
     validations:
       required: true
 
   - type: textarea
     id: screenshots
     attributes:
-      label: Screenshots / Logs
-      description: Paste any relevant error output or screenshots here.
+      label: "Screenshots / Logs"
+      description: "If applicable, add screenshots or error logs to help explain your problem."
 
-  - type: dropdown
-    id: area
+  - type: input
+    id: environment
     attributes:
-      label: Area Affected
-      multiple: true
-      options:
-        - Backend (FastAPI)
-        - Frontend (Next.js)
-        - RAG / Embeddings
-        - Authentication
-        - File Upload
-        - Chat / Streaming
-        - Docker / Deployment
-        - Documentation
+      label: "Environment"
+      description: "What OS, browser, or environment were you using?"
+      placeholder: "e.g., macOS Sequoia, Chrome 120, Node.js v20"
     validations:
       required: true
 
-  - type: input
-    id: python-version
-    attributes:
-      label: Python Version (if backend issue)
-      placeholder: "e.g. 3.11"
-
-  - type: input
-    id: node-version
-    attributes:
-      label: Node.js Version (if frontend issue)
-      placeholder: "e.g. 20.x"
-
   - type: checkboxes
-    id: checklist
+    id: gssoc
     attributes:
-      label: Checklist
+      label: "GSSoC '24"
+      description: "Are you a GSSoC contributor?"
       options:
-        - label: I have searched existing issues and this is not a duplicate.
-          required: true
-        - label: I am targeting the `dev` branch, not `main`.
-          required: true
+        - label: "Yes, I am participating in GirlScript Summer of Code and would like to fix this."

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,69 +1,48 @@
-name: ✨ Feature Request
-description: Suggest a new feature or enhancement
-labels: ["enhancement", "needs-triage"]
-assignees: []
-
+name: "\U0001f680 Feature Request"
+description: "Suggest an idea for this project."
+title: "[FEAT] "
+labels: ["enhancement"]
+assignees:
+  - "param20h"
 body:
   - type: markdown
     attributes:
       value: |
-        Got an idea? Great! Please describe it clearly so we can discuss and prioritize it.
+        Thanks for taking the time to suggest a new feature! 
+        Please provide as much context as possible so we can properly evaluate your idea.
 
   - type: textarea
     id: problem
     attributes:
-      label: Problem / Motivation
-      description: What problem does this solve? What's the current limitation?
-      placeholder: "I find it frustrating when..."
+      label: "Is your feature request related to a problem? Please describe."
+      description: "A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]"
     validations:
       required: true
 
   - type: textarea
     id: solution
     attributes:
-      label: Proposed Solution
-      description: What do you want to happen?
+      label: "Describe the solution you'd like"
+      description: "A clear and concise description of what you want to happen."
     validations:
       required: true
 
   - type: textarea
     id: alternatives
     attributes:
-      label: Alternatives Considered
-      description: Any other approaches you considered?
-
-  - type: dropdown
-    id: area
-    attributes:
-      label: Which area does this affect?
-      multiple: true
-      options:
-        - Backend (FastAPI)
-        - Frontend (Next.js)
-        - RAG / Embeddings
-        - Authentication
-        - File Upload
-        - Chat / Streaming
-        - Docker / Deployment
-        - Documentation
-        - New Area
-    validations:
-      required: true
+      label: "Describe alternatives you've considered"
+      description: "A clear and concise description of any alternative solutions or features you've considered."
 
-  - type: dropdown
-    id: difficulty
+  - type: textarea
+    id: additional_context
     attributes:
-      label: Estimated Difficulty
-      options:
-        - "🟢 Easy (good first issue)"
-        - "🟡 Medium"
-        - "🔴 Hard / Needs discussion"
+      label: "Additional Context"
+      description: "Add any other context, screenshots, or mockups about the feature request here."
 
   - type: checkboxes
-    id: checklist
+    id: gssoc
     attributes:
-      label: Checklist
+      label: "GSSoC '24"
+      description: "Are you a GSSoC contributor?"
       options:
-        - label: I have searched existing issues and this is not a duplicate.
-          required: true
-        - label: I am willing to work on this myself (optional but appreciated!).
+        - label: "Yes, I am participating in GirlScript Summer of Code and would like to build this."

.github/workflows/ci.yml

@@ -48,16 +48,18 @@ jobs:
         env:
           SECRET_KEY: ci-dummy-secret
           DATABASE_URL: sqlite:///./ci_test.db
+          DEBUG: "false"
           HF_TOKEN: ci-dummy-token
           UPLOAD_DIR: /tmp/uploads
           CHROMA_PERSIST_DIR: /tmp/chroma
         run: |
-          python -c "import sys; sys.path.insert(0, 'backend'); from app.config import settings; print('✅ Config imports OK')" || true
+          python -c "import sys; sys.path.insert(0, 'backend'); from app.config import get_settings; get_settings(); print('Config imports OK')"
 
       - name: Run backend pytest suite
         env:
           SECRET_KEY: ci-dummy-secret
           DATABASE_URL: sqlite:///./ci_test.db
+          DEBUG: "false"
           HF_TOKEN: ci-dummy-token
           UPLOAD_DIR: /tmp/uploads
           CHROMA_PERSIST_DIR: /tmp/chroma

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/main.py

@@ -92,11 +92,13 @@ from app.routes.auth import router as auth_router
 from app.routes.documents import router as documents_router
 from app.routes.chat import router as chat_router
 from app.routes.github import router as github_router
+from app.routes.admin import router as admin_router
 
 app.include_router(auth_router, prefix="/api/v1")
 app.include_router(documents_router, prefix="/api/v1")
 app.include_router(chat_router, prefix="/api/v1")
 app.include_router(github_router, prefix="/api/v1")
+app.include_router(admin_router, prefix="/api/v1")
 
 
 # ── Health Check ─────────────────────────────────────

backend/app/metrics.py

@@ -0,0 +1,33 @@
+"""
+Runtime metrics helpers for lightweight operational statistics.
+"""
+from threading import Lock
+
+
+_metrics_lock = Lock()
+_query_count = 0
+_query_response_time_total_ms = 0.0
+
+
+def record_query_response_time(duration_seconds: float) -> None:
+    """Record one completed query response duration."""
+    global _query_count, _query_response_time_total_ms
+
+    duration_ms = max(duration_seconds, 0) * 1000
+    with _metrics_lock:
+        _query_count += 1
+        _query_response_time_total_ms += duration_ms
+
+
+def get_query_metrics() -> dict[str, float | int]:
+    """Return aggregate query metrics for the current process lifetime."""
+    with _metrics_lock:
+        average_ms = (
+            _query_response_time_total_ms / _query_count
+            if _query_count
+            else 0.0
+        )
+        return {
+            "query_count": _query_count,
+            "average_query_response_time_ms": round(average_ms, 2),
+        }

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):
@@ -62,3 +78,15 @@ class ChatMessage(Base):
     # Relationships
     user = relationship("User", back_populates="messages")
     document = relationship("Document", back_populates="messages")
+    shared_message = relationship("SharedMessage", back_populates="message", uselist=False, cascade="all, delete-orphan")
+
+
+class SharedMessage(Base):
+    __tablename__ = "shared_messages"
+
+    id = Column(String, primary_key=True, default=generate_uuid)
+    message_id = Column(String, ForeignKey("chat_messages.id"), nullable=False, unique=True, index=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+
+    # Relationships
+    message = relationship("ChatMessage", back_populates="shared_message")

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

@@ -4,10 +4,7 @@ Per-user collections for data isolation.
 """
 import logging
 from typing import List, Dict, Any, Optional
-import chromadb
-from chromadb.config import Settings as ChromaSettings
 from app.config import get_settings
-from app.rag.embeddings import get_embedding_model
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -16,12 +13,15 @@ settings = get_settings()
 _chroma_client = None
 
 
-def get_chroma_client() -> chromadb.ClientAPI:
+def get_chroma_client():
     """Get or create persistent ChromaDB client."""
     global _chroma_client
 
     if _chroma_client is None:
         import os
+        import chromadb
+        from chromadb.config import Settings as ChromaSettings
+
         os.makedirs(settings.CHROMA_PERSIST_DIR, exist_ok=True)
 
         _chroma_client = chromadb.PersistentClient(
@@ -55,7 +55,17 @@ def store_chunks(
     if not chunks:
         return 0
 
+    # Generate captions for any extracted images before embedding
+    try:
+        from app.rag.vision import generate_captions_for_chunks
+
+        generate_captions_for_chunks(chunks)
+    except Exception as e:
+        logger.warning(f"Could not generate image captions: {e}")
+
     client = get_chroma_client()
+    from app.rag.embeddings import get_embedding_model
+
     embedding_model = get_embedding_model()
 
     collection_name = get_collection_name(user_id)
@@ -74,6 +84,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/admin.py

@@ -0,0 +1,73 @@
+"""
+Admin-only operational statistics routes.
+"""
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from app.auth import get_admin_user
+from app.config import get_settings
+from app.database import get_db
+from app.metrics import get_query_metrics
+from app.models import Document, User
+from app.schemas import AdminStatsResponse, DiskUsageResponse
+
+router = APIRouter(prefix="/admin", tags=["Admin"])
+settings = get_settings()
+
+
+def _directory_size(path: Path) -> int:
+    if not path.exists():
+        return 0
+
+    total = 0
+    for item in path.rglob("*"):
+        if item.is_file():
+            try:
+                total += item.stat().st_size
+            except OSError:
+                continue
+    return total
+
+
+@router.get("/stats", response_model=AdminStatsResponse)
+def get_admin_stats(
+    _admin: User = Depends(get_admin_user),
+    db: Session = Depends(get_db),
+):
+    """Return aggregate system statistics for administrators."""
+    upload_dir = Path(settings.UPLOAD_DIR).resolve()
+    upload_dir.mkdir(parents=True, exist_ok=True)
+
+    disk_usage = shutil.disk_usage(upload_dir)
+    used_percent = (
+        round((disk_usage.used / disk_usage.total) * 100, 2)
+        if disk_usage.total
+        else 0.0
+    )
+    query_metrics = get_query_metrics()
+
+    total_pdfs_uploaded = (
+        db.query(Document)
+        .filter(func.lower(Document.original_name).like("%.pdf"))
+        .count()
+    )
+
+    return AdminStatsResponse(
+        total_users=db.query(User).count(),
+        total_pdfs_uploaded=total_pdfs_uploaded,
+        average_query_response_time_ms=float(
+            query_metrics["average_query_response_time_ms"]
+        ),
+        query_count=int(query_metrics["query_count"]),
+        disk_space_usage=DiskUsageResponse(
+            total_bytes=disk_usage.total,
+            used_bytes=disk_usage.used,
+            free_bytes=disk_usage.free,
+            usage_percent=used_percent,
+            upload_dir_bytes=_directory_size(upload_dir),
+        ),
+    )

backend/app/routes/auth.py

@@ -11,9 +11,10 @@ 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,
+    HFTokenUpdate,
     RefreshRequest,
     TokenResponse,
     UpdatePassword,
@@ -23,6 +24,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
 
@@ -277,6 +280,34 @@ def get_me(user: User = Depends(get_current_user)):
     """
     return UserResponse.model_validate(user)
 
+@router.put("/hf-token", response_model=UserResponse)
+def update_hf_token(
+    payload: HFTokenUpdate,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Update the HuggingFace token for the authenticated user.
+
+    Stores the provided HF token in the user's profile so it can be used
+    for HuggingFace API calls (e.g. InferenceClient) in place of the
+    globally configured ``HF_TOKEN`` environment variable.
+
+    Args:
+        payload: HFTokenUpdate object containing the new ``hf_token`` value.
+        user: The currently authenticated user, obtained from the
+            ``get_current_user`` dependency.
+        db: SQLAlchemy database session, obtained from the dependency.
+
+    Returns:
+        UserResponse: The updated user profile including the new ``hf_token``
+        field.
+    """
+    user.hf_token = payload.hf_token
+    db.commit()
+    db.refresh(user)
+    return UserResponse.model_validate(user)
+
+
 @router.put("/update")
 def update_user_info(payload:UserUpdate,
                     user: User = Depends(get_current_user),
@@ -383,6 +414,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/routes/chat.py

@@ -3,6 +3,7 @@ Chat routes — ask questions with RAG, stream responses via SSE, manage history
 """
 import html
 import json
+import time
 from datetime import datetime
 from io import BytesIO
 import logging
@@ -16,18 +17,83 @@ from reportlab.lib.units import inch
 from reportlab.platypus import Paragraph, SimpleDocTemplate, Spacer
 from sqlalchemy.orm import Session
 
-from app.database import get_db
-from app.models import User, ChatMessage, Document
-from app.schemas import ChatRequest, ChatResponse, ChatMessageResponse, ChatHistoryResponse, SourceChunk
 from app.auth import get_current_user
-from app.rag.agent import generate_answer, generate_answer_stream
+from app.database import get_db
+from app.metrics import record_query_response_time
+from app.models import User, ChatMessage, Document, SharedMessage
 from app.rate_limit import limiter
+from app.schemas import (
+    ChatRequest,
+    ChatResponse,
+    ChatMessageResponse,
+    ChatHistoryResponse,
+    ShareAnswerResponse,
+    ShareLinkResponse,
+    SourceChunk,
+)
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/chat", tags=["Chat"])
 
 
+@router.get("/share/{message_id}", response_model=ShareAnswerResponse)
+def get_shared_answer(
+    message_id: str,
+    db: Session = Depends(get_db),
+):
+    message = db.query(ChatMessage).filter(
+        ChatMessage.id == message_id,
+        ChatMessage.role == "assistant",
+    ).first()
+
+    if not message or not db.query(SharedMessage).filter(SharedMessage.message_id == message.id).first():
+        raise HTTPException(status_code=404, detail="Shared answer not found")
+
+    return _share_answer_response(message)
+
+
+@router.post("/share/{message_id}", response_model=ShareLinkResponse)
+def create_share_link(
+    message_id: str,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    message = db.query(ChatMessage).filter(
+        ChatMessage.id == message_id,
+        ChatMessage.user_id == user.id,
+    ).first()
+
+    if not message:
+        raise HTTPException(status_code=404, detail="Message not found")
+
+    if message.role != "assistant":
+        raise HTTPException(status_code=400, detail="Only assistant messages can be shared")
+
+    shared_message = db.query(SharedMessage).filter(SharedMessage.message_id == message.id).first()
+    if not shared_message:
+        shared_message = SharedMessage(message_id=message.id)
+        db.add(shared_message)
+        db.commit()
+
+    return ShareLinkResponse(
+        message_id=message.id,
+        share_url=f"/share?message_id={message.id}",
+    )
+
+
+def generate_answer(question: str, user_id: str, document_id: Optional[str] = None):
+    from app.rag.agent import generate_answer as _generate_answer
+
+    return _generate_answer(question=question, user_id=user_id, document_id=document_id)
+
+
+def generate_answer_stream(question: str, user_id: str, document_id: Optional[str] = None):
+    from app.rag.agent import generate_answer_stream as _generate_answer_stream
+
+    return _generate_answer_stream(question=question, user_id=user_id, document_id=document_id)
+
+
 @router.post("/ask", response_model=ChatResponse)
 @limiter.limit("10/minute")
 def ask_question(
@@ -63,38 +129,41 @@ def ask_question(
         HTTPException: 400 if the document exists but its status is not
             "ready" (e.g., still processing or failed).
     """
-    # Validate document exists if specified
-    if payload.document_id:
-        doc = db.query(Document).filter(
-            Document.id == payload.document_id,
-            Document.user_id == user.id,
-        ).first()
-
-        if not doc:
-            raise HTTPException(status_code=404, detail="Document not found")
-
-        if doc.status != "ready":
-            raise HTTPException(
-                status_code=400,
-                detail=f"Document is still {doc.status}. Please wait for processing to complete.",
-            )
-
-    # Generate answer
-    result = generate_answer(
-        question=payload.question,
-        user_id=user.id,
-        document_id=payload.document_id,
-    )
+    started_at = time.perf_counter()
+    try:
+        # Validate document exists if specified
+        if payload.document_id:
+            doc = db.query(Document).filter(
+                Document.id == payload.document_id,
+                Document.user_id == user.id,
+            ).first()
+
+            if not doc:
+                raise HTTPException(status_code=404, detail="Document not found")
+
+            if doc.status != "ready":
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Document is still {doc.status}. Please wait for processing to complete.",
+                )
+
+        result = generate_answer(
+            question=payload.question,
+            user_id=user.id,
+            document_id=payload.document_id,
+        )
 
-    # Save to chat history
-    _save_message(db, user.id, payload.document_id, "user", payload.question)
-    _save_message(db, user.id, payload.document_id, "assistant", result["answer"], result["sources"])
+        # Save to chat history
+        _save_message(db, user.id, payload.document_id, "user", payload.question)
+        _save_message(db, user.id, payload.document_id, "assistant", result["answer"], result["sources"])
 
-    return ChatResponse(
-        answer=result["answer"],
-        sources=[SourceChunk(**s) for s in result["sources"]],
-        document_id=payload.document_id,
-    )
+        return ChatResponse(
+            answer=result["answer"],
+            sources=[SourceChunk(**s) for s in result["sources"]],
+            document_id=payload.document_id,
+        )
+    finally:
+        record_query_response_time(time.perf_counter() - started_at)
 
 
 @router.post("/ask/stream")
@@ -156,6 +225,8 @@ def ask_question_stream(
                 detail=f"Document is still {doc.status}. Please wait for processing to complete.",
             )
 
+    started_at = time.perf_counter()
+
     # Save user message immediately
     _save_message(db, user.id, payload.document_id, "user", payload.question)
 
@@ -164,31 +235,34 @@ def ask_question_stream(
         full_answer = ""
         sources = []
 
-        for chunk in generate_answer_stream(
-            question=payload.question,
-            user_id=user.id,
-            document_id=payload.document_id,
-        ):
-            yield chunk
-
-            # Parse to accumulate full answer for history
-            try:
-                if chunk.startswith("data: "):
-                    data = json.loads(chunk[6:].strip())
-                    if data.get("type") == "token":
-                        full_answer += data.get("data", "")
-                    elif data.get("type") == "sources":
-                        sources = data.get("data", [])
-            except Exception:
-                pass
-
-        # Save assistant response to history
-        from app.database import SessionLocal
-        save_db = SessionLocal()
         try:
-            _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources)
+            for chunk in generate_answer_stream(
+                question=payload.question,
+                user_id=user.id,
+                document_id=payload.document_id,
+            ):
+                yield chunk
+
+                # Parse to accumulate full answer for history
+                try:
+                    if chunk.startswith("data: "):
+                        data = json.loads(chunk[6:].strip())
+                        if data.get("type") == "token":
+                            full_answer += data.get("data", "")
+                        elif data.get("type") == "sources":
+                            sources = data.get("data", [])
+                except Exception:
+                    pass
+
+            # Save assistant response to history
+            from app.database import SessionLocal
+            save_db = SessionLocal()
+            try:
+                _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources)
+            finally:
+                save_db.close()
         finally:
-            save_db.close()
+            record_query_response_time(time.perf_counter() - started_at)
 
     return StreamingResponse(
         event_stream(),
@@ -425,6 +499,23 @@ def _save_message(
     db.commit()
 
 
+def _share_answer_response(message: ChatMessage) -> ShareAnswerResponse:
+    """Format a shared assistant message with only safe public fields."""
+    sources = []
+    if message.sources_json:
+        try:
+            sources = [SourceChunk(**item) for item in json.loads(message.sources_json)]
+        except Exception:
+            sources = []
+
+    return ShareAnswerResponse(
+        id=message.id,
+        content=message.content,
+        created_at=message.created_at,
+        sources=sources,
+    )
+
+
 def _format_markdown(doc, messages) -> str:
     """Format chat history as a Markdown document.
 

backend/app/schemas.py

@@ -53,11 +53,30 @@ class RefreshRequest(BaseModel):
     refresh_token: str
 
 
+class HFTokenUpdate(BaseModel):
+    """Request schema for updating the user's HuggingFace token."""
+    hf_token: str
+
+
+class ApiKeyResponse(BaseModel):
+    id: str
+    key_preview: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class ApiKeyCreateResponse(ApiKeyResponse):
+    raw_key: str
+
+
 class UserResponse(BaseModel):
     id: str
     username: str
     email: str
     is_admin: bool
+    hf_token: Optional[str] = None
     created_at: datetime
 
     class Config:
@@ -99,6 +118,24 @@ class DocumentListResponse(BaseModel):
     pages: int
 
 
+# Admin
+
+class DiskUsageResponse(BaseModel):
+    total_bytes: int
+    used_bytes: int
+    free_bytes: int
+    usage_percent: float
+    upload_dir_bytes: int
+
+
+class AdminStatsResponse(BaseModel):
+    total_users: int
+    total_pdfs_uploaded: int
+    average_query_response_time_ms: float
+    query_count: int
+    disk_space_usage: DiskUsageResponse
+
+
 # ── Chat ─────────────────────────────────────────────
 
 class ChatRequest(BaseModel):
@@ -136,5 +173,17 @@ class ChatHistoryResponse(BaseModel):
     document_id: Optional[str] = None
 
 
+class ShareAnswerResponse(BaseModel):
+    id: str
+    content: str
+    sources: List[SourceChunk] = []
+    created_at: datetime
+
+
+class ShareLinkResponse(BaseModel):
+    message_id: str
+    share_url: str
+
+
 # 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

backend/tests/conftest.py

@@ -16,11 +16,12 @@ 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"))
+os.environ["SECRET_KEY"] = "test-secret-key-that-is-long-enough"
+os.environ["DATABASE_URL"] = "sqlite:///./test_bootstrap.db"
+os.environ["DEBUG"] = "false"
+os.environ["HF_TOKEN"] = "test-hf-token"
+os.environ["UPLOAD_DIR"] = str(ROOT / "backend" / "test_uploads")
+os.environ["CHROMA_PERSIST_DIR"] = str(ROOT / "backend" / "test_chroma")
 
 
 fake_embeddings = types.ModuleType("app.rag.embeddings")
@@ -83,7 +84,7 @@ 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
+from app.models import ChatMessage, Document, User
 
 
 @pytest.fixture()
@@ -140,6 +141,19 @@ def user(db_session):
     return instance
 
 
+@pytest.fixture()
+def other_user(db_session):
+    instance = User(
+        username="other",
+        email="other@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)
@@ -181,3 +195,43 @@ def pending_document(db_session, user):
     db_session.commit()
     db_session.refresh(instance)
     return instance
+
+
+@pytest.fixture()
+def assistant_message(db_session, user):
+    instance = ChatMessage(
+        user_id=user.id,
+        role="assistant",
+        content="Shared assistant answer",
+        sources_json='[{"text":"Source text","filename":"file.txt","page":1,"score":0.9,"confidence":95.0}]',
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance
+
+
+@pytest.fixture()
+def user_message(db_session, user):
+    instance = ChatMessage(
+        user_id=user.id,
+        role="user",
+        content="Private user prompt",
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance
+
+
+@pytest.fixture()
+def other_user_assistant_message(db_session, other_user):
+    instance = ChatMessage(
+        user_id=other_user.id,
+        role="assistant",
+        content="Other user's answer",
+    )
+    db_session.add(instance)
+    db_session.commit()
+    db_session.refresh(instance)
+    return instance

backend/tests/test_admin.py

@@ -0,0 +1,65 @@
+from app.auth import create_access_token, hash_password
+from app.metrics import record_query_response_time
+from app.models import Document, User
+
+
+def test_admin_stats_requires_admin(client, auth_headers):
+    response = client.get("/api/v1/admin/stats", headers=auth_headers)
+
+    assert response.status_code == 403
+    assert response.json()["detail"] == "Admin access required"
+
+
+def test_admin_stats_returns_aggregate_metrics(client, db_session):
+    admin = User(
+        username="admin",
+        email="admin@example.com",
+        hashed_password=hash_password("password123"),
+        is_admin=True,
+    )
+    regular = User(
+        username="regular",
+        email="regular@example.com",
+        hashed_password=hash_password("password123"),
+    )
+    db_session.add_all([admin, regular])
+    db_session.commit()
+    db_session.refresh(admin)
+    db_session.refresh(regular)
+
+    db_session.add_all(
+        [
+            Document(
+                user_id=regular.id,
+                filename="first.pdf",
+                original_name="first.pdf",
+                file_size=100,
+                status="ready",
+            ),
+            Document(
+                user_id=regular.id,
+                filename="notes.txt",
+                original_name="notes.txt",
+                file_size=50,
+                status="ready",
+            ),
+        ]
+    )
+    db_session.commit()
+
+    record_query_response_time(0.25)
+
+    token = create_access_token(admin.id)
+    response = client.get(
+        "/api/v1/admin/stats",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["total_users"] == 2
+    assert payload["total_pdfs_uploaded"] == 1
+    assert payload["average_query_response_time_ms"] > 0
+    assert payload["query_count"] >= 1
+    assert payload["disk_space_usage"]["total_bytes"] > 0
+    assert payload["disk_space_usage"]["usage_percent"] >= 0

backend/tests/test_auth.py

@@ -79,3 +79,39 @@ def test_refresh_token_success(client, refresh_token):
     assert payload["access_token"]
     assert payload["refresh_token"]
     assert payload["token_type"] == "bearer"
+
+
+def test_update_hf_token_success(client, auth_headers):
+    response = client.put(
+        "/api/v1/auth/hf-token",
+        json={"hf_token": "hf_new_token_value"},
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["hf_token"] == "hf_new_token_value"
+
+
+def test_update_hf_token_requires_auth(client):
+    response = client.put(
+        "/api/v1/auth/hf-token",
+        json={"hf_token": "hf_unauth"},
+    )
+
+    assert response.status_code in (401, 403)
+
+
+def test_hf_token_appears_in_user_response(client, auth_headers, user, db_session):
+    # First update the token
+    put_resp = client.put(
+        "/api/v1/auth/hf-token",
+        json={"hf_token": "hf_persist_token"},
+        headers=auth_headers,
+    )
+    assert put_resp.status_code == 200
+
+    # Then verify it shows up in GET /me
+    me_resp = client.get("/api/v1/auth/me", headers=auth_headers)
+    assert me_resp.status_code == 200
+    assert me_resp.json()["hf_token"] == "hf_persist_token"

backend/tests/test_share.py

@@ -0,0 +1,61 @@
+def test_share_link_creation_success(client, auth_headers, assistant_message):
+    response = client.post(
+        f"/api/v1/chat/share/{assistant_message.id}",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["message_id"] == assistant_message.id
+    assert payload["share_url"] == f"/share?message_id={assistant_message.id}"
+
+
+def test_share_link_unauthorized_for_other_users_message(client, auth_headers, other_user_assistant_message):
+    response = client.post(
+        f"/api/v1/chat/share/{other_user_assistant_message.id}",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Message not found"
+
+
+def test_cannot_share_user_message(client, auth_headers, user_message):
+    response = client.post(
+        f"/api/v1/chat/share/{user_message.id}",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == "Only assistant messages can be shared"
+
+
+def test_public_fetch_fails_before_share(client, assistant_message):
+    response = client.get(f"/api/v1/chat/share/{assistant_message.id}")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Shared answer not found"
+
+
+def test_public_fetch_shared_answer_success_after_share(client, auth_headers, assistant_message):
+    share_response = client.post(
+        f"/api/v1/chat/share/{assistant_message.id}",
+        headers=auth_headers,
+    )
+    assert share_response.status_code == 200
+
+    response = client.get(f"/api/v1/chat/share/{assistant_message.id}")
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["id"] == assistant_message.id
+    assert payload["content"] == "Shared assistant answer"
+    assert len(payload["sources"]) == 1
+    assert payload["sources"][0]["filename"] == "file.txt"
+
+
+def test_missing_message_returns_404(client):
+    response = client.get("/api/v1/chat/share/missing-message-id")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Shared answer not found"

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

@@ -11,12 +11,16 @@
         "@base-ui/react": "^1.4.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
+        "i18next": "^26.3.0",
+        "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",
         "react-dropzone": "^15.0.0",
+        "react-i18next": "^17.0.8",
         "react-markdown": "^10.1.0",
         "react-pdf": "^10.4.1",
         "rehype-highlight": "^7.0.2",
@@ -79,6 +83,7 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -672,6 +677,7 @@
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -2106,6 +2112,7 @@
       "resolved": "https://registry.npmjs.org/@noble/ciphers/-/ciphers-1.3.0.tgz",
       "integrity": "sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": "^14.21.3 || >=16"
       },
@@ -2213,6 +2220,7 @@
       "integrity": "sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==",
       "devOptional": true,
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "playwright": "1.60.0"
       },
@@ -2681,6 +2689,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.39.tgz",
       "integrity": "sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -2690,6 +2699,7 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
       "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "csstype": "^3.2.2"
       }
@@ -2776,6 +2786,7 @@
       "integrity": "sha512-TI1XGwKbDpo9tRW8UDIXCOeLk55qe9ZFGs8MTKU6/M08HWTw52DD/IYhfQtOEhEdPhLMT26Ka/x7p70nd3dzDg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.59.0",
         "@typescript-eslint/types": "8.59.0",
@@ -3320,6 +3331,7 @@
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -3774,6 +3786,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.10.12",
         "caniuse-lite": "^1.0.30001782",
@@ -4825,6 +4838,7 @@
       "integrity": "sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -5010,6 +5024,7 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -5309,6 +5324,7 @@
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
       "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "accepts": "^2.0.0",
         "body-parser": "^2.2.1",
@@ -5668,6 +5684,7 @@
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
       "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -6132,10 +6149,20 @@
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
       "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
     },
+    "node_modules/html-parse-stringify": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/html-parse-stringify/-/html-parse-stringify-3.0.1.tgz",
+      "integrity": "sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==",
+      "license": "MIT",
+      "dependencies": {
+        "void-elements": "3.1.0"
+      }
+    },
     "node_modules/html-url-attributes": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",
@@ -6188,6 +6215,44 @@
         "node": ">=18.18.0"
       }
     },
+    "node_modules/i18next": {
+      "version": "26.3.0",
+      "resolved": "https://registry.npmjs.org/i18next/-/i18next-26.3.0.tgz",
+      "integrity": "sha512-gHSgGpUXVmuqE2El1W61DmxeyeTlFfZgdJRWMo9jScAn5pu7TuTuiccb1zh3E2J9hEBVGJ23+96x0ieBhfuIHA==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://www.locize.com/i18next"
+        },
+        {
+          "type": "individual",
+          "url": "https://www.i18next.com/how-to/faq#i18next-is-awesome.-how-can-i-support-the-project"
+        },
+        {
+          "type": "individual",
+          "url": "https://www.locize.com"
+        }
+      ],
+      "license": "MIT",
+      "peer": true,
+      "peerDependencies": {
+        "typescript": "^5 || ^6"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/i18next-browser-languagedetector": {
+      "version": "8.2.1",
+      "resolved": "https://registry.npmjs.org/i18next-browser-languagedetector/-/i18next-browser-languagedetector-8.2.1.tgz",
+      "integrity": "sha512-bZg8+4bdmaOiApD7N7BPT9W8MLZG+nPTOFlLiJiT8uzKXFjhxw4v2ierCXOwB5sFDMtuA5G4kgYZ0AznZxQ/cw==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.23.2"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.7.2",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
@@ -8691,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",
@@ -9516,6 +9591,7 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
       "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -9525,6 +9601,7 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
       "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -9549,6 +9626,33 @@
         "react": ">= 16.8 || 18.0.0"
       }
     },
+    "node_modules/react-i18next": {
+      "version": "17.0.8",
+      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-17.0.8.tgz",
+      "integrity": "sha512-0ooKbGLU8JXhe1zwpQUWIeXSgLPOfwJmgheWRIUpcoA0CpyabpGhayjdG+/eA5esC1AQ8h2jWpXjJfzQzeDOCw==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.29.2",
+        "html-parse-stringify": "^3.0.1",
+        "use-sync-external-store": "^1.6.0"
+      },
+      "peerDependencies": {
+        "i18next": ">= 26.2.0",
+        "react": ">= 16.8.0",
+        "typescript": "^5 || ^6"
+      },
+      "peerDependenciesMeta": {
+        "react-dom": {
+          "optional": true
+        },
+        "react-native": {
+          "optional": true
+        },
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/react-is": {
       "version": "16.13.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
@@ -10822,6 +10926,7 @@
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -11090,6 +11195,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "devOptional": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -11423,6 +11529,15 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/void-elements": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/void-elements/-/void-elements-3.1.0.tgz",
+      "integrity": "sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/warning": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/warning/-/warning-4.0.3.tgz",
@@ -11763,6 +11878,7 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

frontend/package.json

@@ -14,12 +14,16 @@
     "@base-ui/react": "^1.4.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "i18next": "^26.3.0",
+    "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",
     "react-dropzone": "^15.0.0",
+    "react-i18next": "^17.0.8",
     "react-markdown": "^10.1.0",
     "react-pdf": "^10.4.1",
     "rehype-highlight": "^7.0.2",

frontend/src/app/admin/page.tsx

@@ -0,0 +1,277 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useRouter } from "next/navigation";
+import {
+  ArrowLeft,
+  Clock3,
+  Database,
+  FileText,
+  HardDrive,
+  RefreshCw,
+  Users,
+} from "lucide-react";
+
+import { api, CONNECTION_ERROR_MESSAGE } from "@/lib/api";
+import { useAuth } from "@/lib/auth";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import { Skeleton } from "@/components/ui/skeleton";
+
+interface AdminStats {
+  total_users: number;
+  total_pdfs_uploaded: number;
+  average_query_response_time_ms: number;
+  query_count: number;
+  disk_space_usage: {
+    total_bytes: number;
+    used_bytes: number;
+    free_bytes: number;
+    usage_percent: number;
+    upload_dir_bytes: number;
+  };
+}
+
+const formatBytes = (bytes: number) => {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const index = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    units.length - 1
+  );
+
+  return `${(bytes / 1024 ** index).toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+};
+
+const formatTime = (milliseconds: number) => {
+  if (milliseconds >= 1000) return `${(milliseconds / 1000).toFixed(2)} s`;
+  return `${Math.round(milliseconds)} ms`;
+};
+
+function MetricCard({
+  icon: Icon,
+  label,
+  value,
+  detail,
+}: {
+  icon: typeof Users;
+  label: string;
+  value: string;
+  detail: string;
+}) {
+  return (
+    <Card className="min-h-36">
+      <CardHeader className="grid-cols-[1fr_auto]">
+        <div>
+          <CardDescription>{label}</CardDescription>
+          <CardTitle className="mt-2 text-3xl tabular-nums">{value}</CardTitle>
+        </div>
+        <div className="flex h-9 w-9 items-center justify-center rounded-lg bg-primary/15 text-primary">
+          <Icon className="h-4 w-4" />
+        </div>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">{detail}</p>
+      </CardContent>
+    </Card>
+  );
+}
+
+function AdminSkeleton() {
+  return (
+    <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+      {[1, 2, 3, 4].map((item) => (
+        <Card key={item} className="min-h-36">
+          <CardHeader>
+            <Skeleton className="h-4 w-28" />
+            <Skeleton className="h-8 w-20" />
+          </CardHeader>
+          <CardContent>
+            <Skeleton className="h-4 w-36" />
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+export default function AdminPage() {
+  const { user, loading } = useAuth();
+  const router = useRouter();
+  const [stats, setStats] = useState<AdminStats | null>(null);
+  const [statsLoading, setStatsLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [lastUpdated, setLastUpdated] = useState<Date | null>(null);
+
+  useEffect(() => {
+    if (loading) return;
+    if (!user) router.replace("/login");
+    else if (!user.is_admin) router.replace("/dashboard");
+  }, [loading, router, user]);
+
+  const loadStats = useCallback(async () => {
+    try {
+      setStatsLoading(true);
+      const data = await api.get<AdminStats>("/api/v1/admin/stats");
+      setStats(data);
+      setLastUpdated(new Date());
+      setError("");
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : CONNECTION_ERROR_MESSAGE;
+      setError(message);
+    } finally {
+      setStatsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!user?.is_admin) return;
+
+    const initialLoad = window.setTimeout(() => void loadStats(), 0);
+    const interval = window.setInterval(() => void loadStats(), 10000);
+
+    return () => {
+      window.clearTimeout(initialLoad);
+      window.clearInterval(interval);
+    };
+  }, [loadStats, user?.is_admin]);
+
+  const diskDetail = useMemo(() => {
+    if (!stats) return "";
+    const disk = stats.disk_space_usage;
+    return `${formatBytes(disk.used_bytes)} used of ${formatBytes(disk.total_bytes)}`;
+  }, [stats]);
+
+  if (loading || !user || !user.is_admin) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="animate-pulse-glow w-12 h-12 rounded-full bg-primary/20" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="sticky top-0 z-40 flex h-14 items-center justify-between border-b border-border/50 bg-card/50 px-4 backdrop-blur-md">
+        <div className="flex items-center gap-3">
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => router.push("/dashboard")}
+            title="Back to dashboard"
+          >
+            <ArrowLeft className="h-4 w-4" />
+          </Button>
+          <div className="flex items-center gap-2">
+            <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-primary/15">
+              <Database className="h-4 w-4 text-primary" />
+            </div>
+            <span className="text-sm font-semibold">Admin Metrics</span>
+          </div>
+        </div>
+
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => void loadStats()}
+          disabled={statsLoading}
+        >
+          <RefreshCw className={statsLoading ? "h-4 w-4 animate-spin" : "h-4 w-4"} />
+          Refresh
+        </Button>
+      </header>
+
+      <main className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-4 py-6">
+        <div className="flex flex-col gap-1">
+          <h1 className="text-2xl font-semibold tracking-normal">System overview</h1>
+          <p className="text-sm text-muted-foreground">
+            {lastUpdated
+              ? `Last updated ${lastUpdated.toLocaleTimeString()}`
+              : "Waiting for live metrics"}
+          </p>
+        </div>
+
+        {error && (
+          <div
+            role="alert"
+            className="rounded-lg border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive"
+          >
+            {error}
+          </div>
+        )}
+
+        {statsLoading && !stats ? (
+          <AdminSkeleton />
+        ) : stats ? (
+          <>
+            <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+              <MetricCard
+                icon={Users}
+                label="Total users"
+                value={stats.total_users.toLocaleString()}
+                detail="Registered accounts"
+              />
+              <MetricCard
+                icon={FileText}
+                label="PDFs uploaded"
+                value={stats.total_pdfs_uploaded.toLocaleString()}
+                detail="All uploaded PDF records"
+              />
+              <MetricCard
+                icon={Clock3}
+                label="Avg response time"
+                value={formatTime(stats.average_query_response_time_ms)}
+                detail={`${stats.query_count.toLocaleString()} measured queries`}
+              />
+              <MetricCard
+                icon={HardDrive}
+                label="Upload storage"
+                value={formatBytes(stats.disk_space_usage.upload_dir_bytes)}
+                detail="Files in the upload directory"
+              />
+            </div>
+
+            <Card>
+              <CardHeader>
+                <CardTitle>Disk space usage</CardTitle>
+                <CardDescription>{diskDetail}</CardDescription>
+              </CardHeader>
+              <CardContent className="space-y-4">
+                <Progress value={stats.disk_space_usage.usage_percent} />
+                <div className="grid gap-3 text-sm sm:grid-cols-3">
+                  <div>
+                    <p className="text-muted-foreground">Used</p>
+                    <p className="font-medium tabular-nums">
+                      {formatBytes(stats.disk_space_usage.used_bytes)}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-muted-foreground">Free</p>
+                    <p className="font-medium tabular-nums">
+                      {formatBytes(stats.disk_space_usage.free_bytes)}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-muted-foreground">Usage</p>
+                    <p className="font-medium tabular-nums">
+                      {stats.disk_space_usage.usage_percent.toFixed(2)}%
+                    </p>
+                  </div>
+                </div>
+              </CardContent>
+            </Card>
+          </>
+        ) : null}
+      </main>
+    </div>
+  );
+}

frontend/src/app/dashboard/page.tsx

@@ -63,11 +63,23 @@ export default function DashboardPage() {
   const [viewerOpen, setViewerOpen] = useState(true);
   const [connectionError, setConnectionError] = useState("");
 
-  // 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

@@ -3,6 +3,8 @@ import { Inter } from "next/font/google";
 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",
@@ -23,13 +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>
-          <TooltipProvider>
-            {children}
-          </TooltipProvider>
-        </AuthProvider>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          enableSystem={false}
+          disableTransitionOnChange
+        >
+          <AuthProvider>
+            <I18nProvider>
+              <TooltipProvider>{children}</TooltipProvider>
+            </I18nProvider>
+          </AuthProvider>
+        </ThemeProvider>
       </body>
     </html>
   );

frontend/src/app/login/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth";
+import { useTranslation } from "react-i18next";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
@@ -12,6 +13,7 @@ import GoogleSignInButton from "@/components/auth/GoogleSignInButton";
 
 export default function LoginPage() {
   const { login } = useAuth();
+  const { t } = useTranslation();
   const router = useRouter();
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
@@ -32,7 +34,7 @@ export default function LoginPage() {
       await login(email, password);
       router.replace("/dashboard");
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : "Login failed";
+      const message = err instanceof Error ? err.message : t("login.fallbackError");
       setError(message);
     } finally {
       setLoading(false);
@@ -51,8 +53,8 @@ export default function LoginPage() {
               <Brain className="w-6 h-6 text-primary" />
             </div>
           </div>
-          <CardTitle className="text-2xl font-bold">Welcome back</CardTitle>
-          <CardDescription>Sign in to your Document AI Analyst account</CardDescription>
+          <CardTitle className="text-2xl font-bold">{t("login.title")}</CardTitle>
+          <CardDescription>{t("login.description")}</CardDescription>
         </CardHeader>
 
         <CardContent>
@@ -71,7 +73,7 @@ export default function LoginPage() {
             )}
 
             <div className="space-y-2">
-              <label className="text-sm font-medium">Email</label>
+              <label className="text-sm font-medium">{t("common.email")}</label>
               <Input
                 id="login-email"
                 type="email"
@@ -84,7 +86,7 @@ export default function LoginPage() {
             </div>
 
             <div className="space-y-2">
-              <label className="text-sm font-medium">Password</label>
+              <label className="text-sm font-medium">{t("common.password")}</label>
               <div className="relative">
                 <Input
                   id="login-password"
@@ -109,18 +111,18 @@ export default function LoginPage() {
               {loading ? (
                 <span className="flex items-center gap-2">
                   <span className="w-4 h-4 border-2 border-primary-foreground/30 border-t-primary-foreground rounded-full animate-spin" />
-                  Signing in...
+                  {t("login.submitting")}
                 </span>
               ) : (
-                "Sign In"
+                t("login.submit")
               )}
             </Button>
           </form>
 
           <p className="text-center text-sm text-muted-foreground mt-6">
-            Don&apos;t have an account?{" "}
+            {t("login.noAccount")}{" "}
             <Link href="/register" className="text-primary hover:underline font-medium">
-              Create one
+              {t("login.createOne")}
             </Link>
           </p>
         </CardContent>

frontend/src/app/register/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useState } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth";
+import { useTranslation } from "react-i18next";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
@@ -12,6 +13,7 @@ import GoogleSignInButton from "@/components/auth/GoogleSignInButton";
 
 export default function RegisterPage() {
   const { register } = useAuth();
+  const { t } = useTranslation();
   const router = useRouter();
   const [username, setUsername] = useState("");
   const [email, setEmail] = useState("");
@@ -33,7 +35,7 @@ export default function RegisterPage() {
       await register(username, email, password);
       router.replace("/dashboard");
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : "Registration failed";
+      const message = err instanceof Error ? err.message : t("register.fallbackError");
       setError(message);
     } finally {
       setLoading(false);
@@ -51,8 +53,8 @@ export default function RegisterPage() {
               <Brain className="w-6 h-6 text-primary" />
             </div>
           </div>
-          <CardTitle className="text-2xl font-bold">Create Account</CardTitle>
-          <CardDescription>Start analyzing documents with AI</CardDescription>
+          <CardTitle className="text-2xl font-bold">{t("register.title")}</CardTitle>
+          <CardDescription>{t("register.description")}</CardDescription>
         </CardHeader>
 
         <CardContent>
@@ -71,7 +73,7 @@ export default function RegisterPage() {
             )}
 
             <div className="space-y-2">
-              <label className="text-sm font-medium">Username</label>
+              <label className="text-sm font-medium">{t("common.username")}</label>
               <Input
                 id="reg-username"
                 type="text"
@@ -85,7 +87,7 @@ export default function RegisterPage() {
             </div>
 
             <div className="space-y-2">
-              <label className="text-sm font-medium">Email</label>
+              <label className="text-sm font-medium">{t("common.email")}</label>
               <Input
                 id="reg-email"
                 type="email"
@@ -98,12 +100,12 @@ export default function RegisterPage() {
             </div>
 
             <div className="space-y-2">
-              <label className="text-sm font-medium">Password</label>
+              <label className="text-sm font-medium">{t("common.password")}</label>
               <div className="relative">
                 <Input
                   id="reg-password"
                   type={showPw ? "text" : "password"}
-                  placeholder="Minimum 6 characters"
+                  placeholder={t("register.passwordPlaceholder")}
                   value={password}
                   onChange={(e) => setPassword(e.target.value)}
                   required
@@ -124,18 +126,18 @@ export default function RegisterPage() {
               {loading ? (
                 <span className="flex items-center gap-2">
                   <span className="w-4 h-4 border-2 border-primary-foreground/30 border-t-primary-foreground rounded-full animate-spin" />
-                  Creating account...
+                  {t("register.submitting")}
                 </span>
               ) : (
-                "Create Account"
+                t("register.submit")
               )}
             </Button>
           </form>
 
           <p className="text-center text-sm text-muted-foreground mt-6">
-            Already have an account?{" "}
+            {t("register.hasAccount")}{" "}
             <Link href="/login" className="text-primary hover:underline font-medium">
-              Sign in
+              {t("register.signIn")}
             </Link>
           </p>
         </CardContent>

frontend/src/app/share/page.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+import { Suspense, useEffect, useState } from "react";
+import { useSearchParams } from "next/navigation";
+import ReactMarkdown, { type Components } from "react-markdown";
+import rehypeHighlight from "rehype-highlight";
+import remarkGfm from "remark-gfm";
+import { Brain } from "lucide-react";
+import { api } from "@/lib/api";
+
+interface SharedSource {
+  text: string;
+  filename: string;
+  page: number;
+  score: number;
+  confidence: number;
+}
+
+interface SharedAnswer {
+  id: string;
+  content: string;
+  created_at: string;
+  sources: SharedSource[];
+}
+
+const markdownComponents: Components = {
+  table: ({ children }) => (
+    <div className="my-3 overflow-x-auto rounded-lg border border-border/70">
+      <table className="min-w-full border-collapse text-left text-sm">
+        {children}
+      </table>
+    </div>
+  ),
+  thead: ({ children }) => (
+    <thead className="bg-muted/60 text-foreground">{children}</thead>
+  ),
+  th: ({ children }) => (
+    <th className="border-b border-border/70 px-3 py-2 font-semibold">
+      {children}
+    </th>
+  ),
+  td: ({ children }) => (
+    <td className="border-b border-border/50 px-3 py-2 align-top">
+      {children}
+    </td>
+  ),
+  pre: ({ children }) => (
+    <pre className="not-prose my-3 overflow-x-auto rounded-lg border border-border/70 bg-zinc-950 p-3 text-sm text-zinc-100">
+      {children}
+    </pre>
+  ),
+  code: ({ className, children, ...props }) => {
+    const language = /language-(\w+)/.exec(className ?? "")?.[1];
+
+    return (
+      <code className={className} data-language={language} {...props}>
+        {children}
+      </code>
+    );
+  },
+};
+
+function ShareAnswerContent() {
+  const searchParams = useSearchParams();
+  const messageId = searchParams.get("message_id");
+  const missingMessageId = !messageId;
+  const [answer, setAnswer] = useState<SharedAnswer | null>(null);
+  const [error, setError] = useState("");
+  const loading = !error && !answer && !missingMessageId;
+
+  useEffect(() => {
+    if (missingMessageId) {
+      return;
+    }
+
+    let cancelled = false;
+
+    void api
+      .get<SharedAnswer>(`/api/v1/chat/share/${messageId}`)
+      .then((data) => {
+        if (cancelled) return;
+        setAnswer(data);
+        setError("");
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        setAnswer(null);
+        setError(err instanceof Error ? err.message : "Shared answer not found");
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [messageId, missingMessageId]);
+
+  if (missingMessageId) {
+    return (
+      <div className="min-h-screen flex items-center justify-center px-4">
+        <div className="rounded-xl border border-border/50 bg-card/80 px-6 py-5 text-center">
+          <p className="text-lg font-semibold mb-1">Shared answer unavailable</p>
+          <p className="text-sm text-muted-foreground">This shared answer could not be found.</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center px-4">
+        <div className="text-sm text-muted-foreground">Loading shared answer...</div>
+      </div>
+    );
+  }
+
+  if (error || !answer) {
+    return (
+      <div className="min-h-screen flex items-center justify-center px-4">
+        <div className="rounded-xl border border-border/50 bg-card/80 px-6 py-5 text-center">
+          <p className="text-lg font-semibold mb-1">Shared answer unavailable</p>
+          <p className="text-sm text-muted-foreground">{error || "This shared answer could not be found."}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen px-4 py-10 bg-background text-foreground">
+      <div className="max-w-3xl mx-auto">
+        <div className="rounded-2xl border border-border/50 bg-card/80 backdrop-blur-sm p-6">
+          <div className="flex items-center gap-3 mb-5">
+            <div className="w-10 h-10 rounded-xl bg-primary/15 flex items-center justify-center">
+              <Brain className="w-5 h-5 text-primary" />
+            </div>
+            <div>
+              <h1 className="text-xl font-semibold">Shared AI Answer</h1>
+              <p className="text-sm text-muted-foreground">
+                {new Date(answer.created_at).toLocaleString()}
+              </p>
+            </div>
+          </div>
+
+          <div className="prose-chat text-sm">
+            <ReactMarkdown
+              remarkPlugins={[remarkGfm]}
+              rehypePlugins={[rehypeHighlight]}
+              components={markdownComponents}
+            >
+              {answer.content}
+            </ReactMarkdown>
+          </div>
+
+          {answer.sources.length > 0 && (
+            <div className="mt-6 border-t border-border/50 pt-4">
+              <h2 className="text-sm font-semibold mb-3">Sources</h2>
+              <div className="space-y-2">
+                {answer.sources.map((source, index) => (
+                  <div
+                    key={`${answer.id}-${index}`}
+                    className="rounded-lg border border-border/50 bg-background/60 p-3"
+                  >
+                    <p className="text-xs font-medium mb-1">
+                      {source.filename} • Page {source.page}
+                    </p>
+                    <p className="text-xs text-muted-foreground">{source.text}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function ShareAnswerPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen flex items-center justify-center px-4">
+          <div className="text-sm text-muted-foreground">Loading shared answer...</div>
+        </div>
+      }
+    >
+      <ShareAnswerContent />
+    </Suspense>
+  );
+}

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/ChatPanel.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState, useRef, useEffect } from "react";
+import { useTranslation } from "react-i18next";
 import type { DocInfo } from "@/app/dashboard/page";
 import { api, API_BASE } from "@/lib/api";
 import { useChatStore, type ChatMsg, type SourceChunk } from "@/store/chat-store";
@@ -16,6 +17,7 @@ interface Props {
 }
 
 export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
+  const { t } = useTranslation();
   const messages = useChatStore((state) => state.messages);
   const input = useChatStore((state) => state.input);
   const streaming = useChatStore((state) => state.streaming);
@@ -185,7 +187,9 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
           m.id === assistantId
             ? {
                 ...m,
-                content: `Failed to get response: ${err instanceof Error ? err.message : "Unknown error"}`,
+                content: t("chat.fallbackError", {
+                  message: err instanceof Error ? err.message : "Unknown error",
+                }),
                 isStreaming: false,
               }
             : m
@@ -198,7 +202,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
   };
 
   const handleClear = async () => {
-    if (!activeDoc || !confirm("Clear all chat history for this document?")) return;
+    if (!activeDoc || !confirm(t("chat.clearConfirm"))) return;
     try {
       await api.delete(`/api/v1/chat/history/${activeDoc.id}`);
       setMessages([]);
@@ -250,12 +254,12 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
               <MessageSquare className="w-8 h-8 text-primary/60" />
             </div>
             <h3 className="text-lg font-semibold mb-1">
-              {activeDoc ? "Ask about your document" : "Select a document"}
+              {activeDoc ? t("chat.askAboutDocument") : t("chat.selectDocument")}
             </h3>
             <p className="text-sm text-muted-foreground text-center max-w-sm">
               {activeDoc
-                ? `"${activeDoc.original_name}" is ready. Ask any question and get cited answers.`
-                : "Upload and select a document from the sidebar to start chatting."}
+                ? t("chat.readyPrompt", { name: activeDoc.original_name })
+                : t("chat.uploadPrompt")}
             </p>
           </div>
         ) : (
@@ -293,8 +297,8 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
             onKeyDown={handleKeyDown}
             placeholder={
               activeDoc
-                ? `Ask about "${activeDoc.original_name}"...`
-                : "Select a document first..."
+                ? t("chat.askPlaceholder", { name: activeDoc.original_name })
+                : t("chat.selectPlaceholder")
             }
             disabled={streaming}
             className="min-h-[44px] max-h-32 resize-none bg-background/50 border-border/50"
@@ -324,7 +328,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
                     size="icon"
                     onClick={() => setShowExportMenu((v) => !v)}
                     className="h-[44px] w-[44px] text-muted-foreground hover:text-primary"
-                    title="Export chat history"
+                    title={t("chat.exportTitle")}
                   >
                     <Download className="w-4 h-4" />
                   </Button>
@@ -336,7 +340,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
                         className="w-full flex items-center gap-2 rounded-md px-3 py-2 text-sm hover:bg-accent transition-colors text-left"
                       >
                         <span className="text-base">📝</span>
-                        Markdown (.md)
+                        {t("chat.markdown")}
                       </button>
                       <button
                         id="export-txt-btn"
@@ -344,7 +348,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
                         className="w-full flex items-center gap-2 rounded-md px-3 py-2 text-sm hover:bg-accent transition-colors text-left"
                       >
                         <span className="text-base">📄</span>
-                        Plain Text (.txt)
+                        {t("chat.plainText")}
                       </button>
                       <button
                         id="export-pdf-btn"
@@ -352,7 +356,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
                         className="w-full flex items-center gap-2 rounded-md px-3 py-2 text-sm hover:bg-accent transition-colors text-left"
                       >
                         <span className="text-base">📕</span>
-                        PDF (.pdf)
+                        {t("chat.pdf")}
                       </button>
                     </div>
                   )}

frontend/src/components/chat/MessageBubble.tsx

@@ -5,7 +5,8 @@ import ReactMarkdown, { type Components } from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
 import type { ChatMsg } from "@/store/chat-store";
-import { Brain, User, Copy, Check } from "lucide-react";
+import { api } from "@/lib/api";
+import { Brain, User, Copy, Check, Share2, Link2, X } from "lucide-react";
 import { Button } from "@/components/ui/button";
 
 interface Props {
@@ -52,7 +53,10 @@ const markdownComponents: Components = {
 export default function MessageBubble({ message }: Props) {
   const isUser = message.role === "user";
   const [copied, setCopied] = useState(false);
+  const [shared, setShared] = useState(false);
+  const [shareFailed, setShareFailed] = useState(false);
   const copiedTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const sharedTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const handleCopy = async () => {
     if (!message.content) return;
@@ -66,6 +70,31 @@ export default function MessageBubble({ message }: Props) {
     }
   };
 
+  const handleShare = async () => {
+    if (!message.content || message.isStreaming) return;
+
+    try {
+      const data = await api.post<{ message_id: string; share_url: string }>(
+        `/api/v1/chat/share/${message.id}`
+      );
+      await navigator.clipboard.writeText(`${window.location.origin}${data.share_url}`);
+      setShared(true);
+      setShareFailed(false);
+      if (sharedTimeoutRef.current) clearTimeout(sharedTimeoutRef.current);
+      sharedTimeoutRef.current = setTimeout(() => {
+        setShared(false);
+        setShareFailed(false);
+      }, 2000);
+    } catch {
+      setShareFailed(true);
+      setShared(false);
+      if (sharedTimeoutRef.current) clearTimeout(sharedTimeoutRef.current);
+      sharedTimeoutRef.current = setTimeout(() => {
+        setShareFailed(false);
+      }, 2000);
+    }
+  };
+
   return (
     <div
       className={`flex gap-3 py-3 animate-fade-in-up ${isUser ? "justify-end" : "justify-start"}`}
@@ -88,26 +117,50 @@ export default function MessageBubble({ message }: Props) {
         ) : (
           <>
             {message.content && (
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon-xs"
-                className={`absolute top-2 right-2 text-muted-foreground hover:text-foreground transition-opacity ${
-                  copied
-                    ? "opacity-100"
-                    : "opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto"
-                }`}
-                onClick={handleCopy}
-                aria-label={copied ? "Copied" : "Copy response"}
-              >
-                {copied ? (
-                  <Check className="w-3.5 h-3.5 text-emerald-400" />
-                ) : (
-                  <Copy className="w-3.5 h-3.5" />
+              <>
+                {!message.isStreaming && (
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    className={`absolute top-2 right-2 text-muted-foreground hover:text-foreground transition-opacity ${
+                      shared || shareFailed
+                        ? "opacity-100"
+                        : "opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto"
+                    }`}
+                    onClick={handleShare}
+                    aria-label={shared ? "Link copied" : shareFailed ? "Share failed" : "Share response"}
+                  >
+                    {shared ? (
+                      <Link2 className="w-3.5 h-3.5 text-emerald-400" />
+                    ) : shareFailed ? (
+                      <X className="w-3.5 h-3.5 text-destructive" />
+                    ) : (
+                      <Share2 className="w-3.5 h-3.5" />
+                    )}
+                  </Button>
                 )}
-              </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-xs"
+                  className={`absolute top-2 right-9 text-muted-foreground hover:text-foreground transition-opacity ${
+                    copied
+                      ? "opacity-100"
+                      : "opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto"
+                  }`}
+                  onClick={handleCopy}
+                  aria-label={copied ? "Copied" : "Copy response"}
+                >
+                  {copied ? (
+                    <Check className="w-3.5 h-3.5 text-emerald-400" />
+                  ) : (
+                    <Copy className="w-3.5 h-3.5" />
+                  )}
+                </Button>
+              </>
             )}
-            <div className={`prose-chat text-sm ${message.content ? "pr-7" : ""}`}>
+            <div className={`prose-chat text-sm ${message.content ? "pr-14" : ""}`}>
               {message.content ? (
                 <ReactMarkdown
                   remarkPlugins={[remarkGfm]}

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/document/DocumentSidebar.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState, useCallback } from "react";
+import { useTranslation } from "react-i18next";
 import type { DocInfo } from "@/app/dashboard/page";
 import { api } from "@/lib/api";
 import { ScrollArea } from "@/components/ui/scroll-area";
@@ -20,6 +21,7 @@ interface Props {
 }
 
 export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc, onDocumentsChange }: Props) {
+  const { t } = useTranslation();
   const [uploading, setUploading] = useState(false);
   const [uploadProgress, setUploadProgress] = useState(0);
   const [uploadError, setUploadError] = useState("");
@@ -43,7 +45,7 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
           }
           onDocumentsChange();
         } catch (err) {
-          const message = err instanceof Error ? err.message : "Upload failed";
+          const message = err instanceof Error ? err.message : t("documents.uploadFailed");
           setUploadError(message);
         } finally {
           setUploading(false);
@@ -51,7 +53,7 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
         }
       })();
     },
-    [onDocumentsChange]
+    [onDocumentsChange, t]
   );
 
   const { getRootProps, getInputProps, isDragActive } = useDropzone({
@@ -67,7 +69,7 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
 
   const handleDelete = async (docId: string, e: React.MouseEvent) => {
     e.stopPropagation();
-    if (!confirm("Delete this document and all its data?")) return;
+    if (!confirm(t("documents.deleteConfirm"))) return;
     setDeleting(docId);
     try {
       await api.delete(`/api/v1/documents/${docId}`);
@@ -119,17 +121,17 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
           {uploading ? (
             <div className="space-y-2">
               <Loader2 className="w-5 h-5 mx-auto animate-spin text-primary" />
-              <p className="text-xs text-muted-foreground">Uploading...</p>
+              <p className="text-xs text-muted-foreground">{t("documents.uploading")}</p>
               <Progress value={uploadProgress} className="h-1" />
             </div>
           ) : (
             <>
               <Upload className="w-5 h-5 mx-auto text-muted-foreground mb-2" />
               <p className="text-xs text-muted-foreground">
-                {isDragActive ? "Drop files here" : "Drop files or click to upload"}
+                {isDragActive ? t("documents.dropHere") : t("documents.dropOrClick")}
               </p>
               <p className="text-[10px] text-muted-foreground/60 mt-1">
-                PDF, DOCX, TXT, MD (max 50MB)
+                {t("documents.uploadFormats")}
               </p>
             </>
           )}
@@ -139,7 +141,7 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
       {/* ── Documents List ──────────────────────────── */}
       <div className="px-3 pt-3 pb-1">
         <h3 className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground mb-2">
-          Documents ({documents.length})
+          {t("documents.documentsTitle", { count: documents.length })}
         </h3>
       </div>
 
@@ -147,8 +149,8 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
         {documents.length === 0 ? (
           <div className="text-center py-12">
             <FolderOpen className="w-8 h-8 mx-auto text-muted-foreground/40 mb-3" />
-            <p className="text-sm text-muted-foreground">No documents yet</p>
-            <p className="text-xs text-muted-foreground/60 mt-1">Upload a file to get started</p>
+            <p className="text-sm text-muted-foreground">{t("documents.noDocuments")}</p>
+            <p className="text-xs text-muted-foreground/60 mt-1">{t("documents.getStarted")}</p>
           </div>
         ) : (
           <div className="space-y-1 pb-3">
@@ -179,22 +181,22 @@ export default function DocumentSidebar({ documents = [], activeDoc, onSelectDoc
                         <>
                           <span className="text-[10px] text-muted-foreground">•</span>
                           <span className="text-[10px] text-muted-foreground">
-                            {doc.page_count} pg
+                            {t("documents.pagesShort", { count: doc.page_count })}
                           </span>
                           <span className="text-[10px] text-muted-foreground">•</span>
                           <span className="text-[10px] text-muted-foreground">
-                            {doc.chunk_count} chunks
+                            {t("documents.chunks", { count: doc.chunk_count })}
                           </span>
                         </>
                       )}
                       {doc.status === "processing" && (
                         <Badge variant="secondary" className="text-[9px] h-4 px-1.5">
-                          Processing
+                          {t("documents.processing")}
                         </Badge>
                       )}
                       {doc.status === "failed" && (
                         <Badge variant="destructive" className="text-[9px] h-4 px-1.5">
-                          Failed
+                          {t("documents.failed")}
                         </Badge>
                       )}
                     </div>

frontend/src/components/layout/Header.tsx

@@ -2,6 +2,7 @@
 
 import { useState } from "react";
 import { useAuth } from "@/lib/auth";
+import { useTranslation } from "react-i18next";
 import { useRouter } from "next/navigation";
 import { Button } from "@/components/ui/button";
 import { Avatar, AvatarFallback } from "@/components/ui/avatar";
@@ -20,6 +21,7 @@ import {
   PanelRightOpen,
   LogOut,
   Moon,
+  Shield,
   Sun,
   Menu,
   X,
@@ -48,6 +50,7 @@ export default function Header({
   mobileSheetContent,
 }: HeaderProps) {
   const { user, logout } = useAuth();
+  const { t, i18n } = useTranslation();
   const router = useRouter();
   const { theme, setTheme } = useTheme();
   const mounted = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
@@ -61,6 +64,19 @@ export default function Header({
     router.replace("/login");
   };
 
+  const languageLabel = (language: string) => {
+    switch (language) {
+      case "hi":
+        return t("common.hindi");
+      case "es":
+        return t("common.spanish");
+      case "fr":
+        return t("common.french");
+      default:
+        return t("common.english");
+    }
+  };
+
   return (
     <>
       <header className="h-14 flex items-center justify-between px-4 border-b border-border/50 bg-card/50 backdrop-blur-md flex-shrink-0 z-50">
@@ -205,4 +221,4 @@ export default function Header({
 </aside>
     </>
   );
-}
+}

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>
+  );
+}

frontend/src/components/providers/I18nProvider.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { useEffect } from "react";
+import { I18nextProvider } from "react-i18next";
+import i18n from "@/lib/i18n";
+
+export default function I18nProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    document.documentElement.lang = i18n.resolvedLanguage || "en";
+
+    const handleLanguageChanged = (language: string) => {
+      document.documentElement.lang = language;
+    };
+
+    i18n.on("languageChanged", handleLanguageChanged);
+    return () => {
+      i18n.off("languageChanged", handleLanguageChanged);
+    };
+  }, []);
+
+  return <I18nextProvider i18n={i18n}>{children}</I18nextProvider>;
+}

frontend/src/lib/api.ts

@@ -201,6 +201,29 @@ class ApiClient {
     return res.json();
   }
 
+  async put<T>(path: string, body?: unknown, options?: FetchOptions): Promise<T> {
+    const res = await this.fetchWithConnectionError(`${this.baseUrl}${path}`, {
+      method: "PUT",
+      headers: this.getHeaders(options?.token),
+      body: body ? JSON.stringify(body) : undefined,
+      ...options,
+    });
+
+    // Auto-refresh on 401
+    if (res.status === 401 && !options?._skipRefresh) {
+      const newToken = await this.tryRefreshToken();
+      if (newToken) {
+        return this.put<T>(path, body, { ...options, token: newToken, _skipRefresh: true });
+      }
+    }
+
+    if (!res.ok) {
+      throw new Error(await this.getErrorMessage(res, res.statusText || "Request failed"));
+    }
+
+    return res.json();
+  }
+
   async postForm<T>(path: string, formData: FormData, options?: FetchOptions): Promise<T> {
     const token = options?.token || this.getToken();
     const headers: HeadersInit = {};