Merge remote-tracking branch 'upstream/dev' into feat/issue-114-hybrid-search

.env.example

@@ -122,6 +122,16 @@ HF_TOKEN=your_huggingface_token_here
 
 # ── RAG Config (Optional — defaults shown) ───────────
 
+# ── Knowledge Graph / GraphRAG (Optional — defaults shown) ─────────────────
+
+# Directory where GraphRAG stores per-document knowledge graphs.
+# Optional — defaults to "./data/graphs"
+# GRAPH_PERSIST_DIR=./data/graphs
+
+# Maximum number of graph relationships appended to the RAG prompt.
+# Optional — defaults to 12
+# GRAPH_MAX_RELATIONSHIPS=12
+
 # ── ChromaDB (Vector Store) ─────────────────────────────────
 
 # Directory where ChromaDB persists its vector index to disk.

.gitignore

@@ -29,3 +29,4 @@ Thumbs.db
 # Misc
 *.log
 static/
+.planning/

.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+repos:
+  # ── Python Formatting ─────────────────────────────────────
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+        language_version: python3
+        args: [--line-length=120]
+        files: ^backend/
+
+  # ── Python Linting ────────────────────────────────────────
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        args:
+          - --max-line-length=120
+          - --select=E9,F63,F7,F82,E501
+          - --count
+        files: ^backend/
+
+  # ── JavaScript / TypeScript / JSON / CSS / Markdown Formatting ──
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        types_or: [javascript, jsx, ts, tsx, json, css, markdown]
+        files: ^frontend/
+        exclude: ^frontend/(node_modules|.next|dist|build)/
+
+  # ── General Hygiene ───────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-json
+        exclude: ^frontend/(node_modules|.next)/
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: mixed-line-ending
+        args: [--fix=lf]
+        exclude: \.(bat|cmd|ps1)$
+
+  # ── Security ─────────────────────────────────────────────
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: [--baseline, .secrets.baseline]
+        exclude: \.env\.example$

CONTRIBUTING.md

@@ -61,6 +61,36 @@ cp ../.env.example .env            # Fill in your own dev values
 uvicorn app.main:app --reload --port 8000
 ```
 
+### Pre-commit Hooks (Required)
+
+We use [`pre-commit`](https://pre-commit.com/) to enforce code style automatically before every commit. This prevents style-related CI failures.
+
+```bash
+# Install pre-commit (one-time setup)
+pip install pre-commit
+
+# Install the hooks into your local clone (one-time per checkout)
+pre-commit install
+
+# (Optional) Run against all files to verify setup
+pre-commit run --all-files
+```
+
+**What the hooks check:**
+
+| Hook | Tool | Scope |
+|------|------|-------|
+| Python formatting | `black` (line-length 120) | `backend/` |
+| Python linting | `flake8` (errors only) | `backend/` |
+| JS/TS/JSON/CSS/MD formatting | `prettier` | `frontend/` |
+| Trailing whitespace | `pre-commit-hooks` | All files |
+| YAML/JSON validity | `pre-commit-hooks` | All files |
+| Merge-conflict markers | `pre-commit-hooks` | All files |
+| Large file guard (>1 MB) | `pre-commit-hooks` | All files |
+| Secret detection | `detect-secrets` | All files |
+
+> ⚠️ If a hook modifies files, it will block your commit. Just `git add` the auto-fixed files and commit again.
+
 ### Frontend (Next.js)
 
 ```bash

Dockerfile

@@ -33,7 +33,8 @@ RUN python -m venv "$VIRTUAL_ENV"
 
 COPY backend/requirements.txt ./requirements.txt
 RUN pip install --no-cache-dir --upgrade pip setuptools wheel && \
-    pip install --no-cache-dir -r requirements.txt
+    pip install --no-cache-dir -r requirements.txt && \
+    python -m spacy download en_core_web_sm
 
 # --------------------------------------------------------
 # Stage 3: Runtime image with only app code and artifacts
@@ -68,7 +69,7 @@ COPY backend/__init__.py ./backend/__init__.py
 COPY --from=frontend-builder /app/frontend/out ./frontend/out
 
 # Create data directories with proper permissions
-RUN mkdir -p /app/data/uploads /app/data/chroma_db /app/data/huggingface && \
+RUN mkdir -p /app/data/uploads /app/data/chroma_db /app/data/graphs /app/data/huggingface && \
     chown -R appuser:appuser /app
 
 # Copy entrypoint

backend/app/config.py

@@ -45,6 +45,22 @@ class Settings(BaseSettings):
     TOP_K_RETRIEVAL: int = 10
     TOP_K_RERANK: int = 5
 
+    # ── Knowledge Graph (GraphRAG) ───────────────────────
+    GRAPH_PERSIST_DIR: str = "./data/graphs"
+    GRAPH_ENTITY_LABELS: set = {
+        "PERSON",
+        "ORG",
+        "GPE",
+        "LOC",
+        "PRODUCT",
+        "EVENT",
+        "WORK_OF_ART",
+        "LAW",
+        "NORP",
+        "FAC",
+    }
+    GRAPH_MAX_RELATIONSHIPS: int = 12
+
     # ── Embeddings (local HuggingFace model) ─────────────
     EMBEDDING_MODEL: str = "sentence-transformers/all-MiniLM-L6-v2"
     EMBEDDING_DIMENSION: int = 384

backend/app/models.py

@@ -8,11 +8,9 @@ import hashlib
 from datetime import datetime, timezone
 
 from cryptography.fernet import Fernet
-from sqlalchemy import Column, String, Integer, DateTime, ForeignKey, Text, Boolean
+from sqlalchemy import Column, String, Integer, DateTime, ForeignKey, Text, Boolean, Enum as SQLAlchemyEnum
 from sqlalchemy.types import TypeDecorator, CHAR
 from sqlalchemy.dialects.postgresql import UUID as PG_UUID
-from sqlalchemy import Column, String, Integer, DateTime, ForeignKey, Text, Boolean, Enum as SQLAlchemyEnum
-from sqlalchemy.types import TypeDecorator
 from sqlalchemy.orm import relationship
 
 from app.database import Base
@@ -85,11 +83,6 @@ class EncryptedString(TypeDecorator):
             return value
 
 
-def generate_uuid():
-    """Generates a standard unique string identifier for database records."""
-    return str(uuid.uuid4())
-
-
 class UserRole(str, enum.Enum):
     """
     Defines the available user roles for Role-Based Access Control (RBAC).
@@ -129,6 +122,7 @@ class User(Base):
     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")
+    chat_sessions = relationship("ChatSession", back_populates="user", cascade="all, delete-orphan")
 
 
 class ApiKey(Base):
@@ -148,6 +142,22 @@ class ApiKey(Base):
     user = relationship("User", back_populates="api_keys")
 
 
+class ChatSession(Base):
+    """
+    Groups chat messages into logical sessions/threads.
+    """
+    __tablename__ = "chat_sessions"
+
+    id = Column(GUID, primary_key=True, default=uuid.uuid4)
+    user_id = Column(GUID, ForeignKey("users.id"), nullable=False, index=True)
+    title = Column(String(255), nullable=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
+
+    # Relationships
+    user = relationship("User", back_populates="chat_sessions")
+    messages = relationship("ChatMessage", back_populates="session", cascade="all, delete-orphan")
+
+
 class Document(Base):
     """
     Metadata and processing status for files uploaded by users.
@@ -159,11 +169,6 @@ class Document(Base):
     filename = Column(String(255), nullable=False)        # Stored filename (UUID-based)
     original_name = Column(String(255), nullable=False)    # User's original filename
     file_size = Column(Integer, default=0)                 # Size in bytes
-    id = Column(String, primary_key=True, default=generate_uuid)
-    user_id = Column(String, ForeignKey("users.id"), nullable=False, index=True)
-    filename = Column(String(255), nullable=False)         # Internal UUID-based filename
-    original_name = Column(String(255), nullable=False)     # Original name for user display
-    file_size = Column(Integer, default=0)                  # Size in bytes
     page_count = Column(Integer, default=0)
     chunk_count = Column(Integer, default=0)
     status = Column(String(20), default="pending")          # pending | processing | ready | failed
@@ -185,6 +190,7 @@ class ChatMessage(Base):
     id = Column(GUID, primary_key=True, default=uuid.uuid4)
     user_id = Column(GUID, ForeignKey("users.id"), nullable=False, index=True)
     document_id = Column(GUID, ForeignKey("documents.id"), nullable=True, index=True)
+    session_id = Column(GUID, ForeignKey("chat_sessions.id"), nullable=True, index=True)
     role = Column(String(20), nullable=False)  # "user" | "assistant"
     content = Column(Text, nullable=False)
     sources_json = Column(Text, nullable=True)  # JSON representation of retrieved sources
@@ -193,6 +199,7 @@ class ChatMessage(Base):
     # Relationships
     user = relationship("User", back_populates="messages")
     document = relationship("Document", back_populates="messages")
+    session = relationship("ChatSession", back_populates="messages")
     shared_message = relationship("SharedMessage", back_populates="message", uselist=False, cascade="all, delete-orphan")
 
 

backend/app/rag/agent.py

@@ -9,6 +9,7 @@ from typing import List, Dict, Any, Optional, Generator
 from huggingface_hub import InferenceClient
 from app.config import get_settings
 from app.rag.retriever import retrieve
+from app.rag.graph_retriever import get_entity_context
 from app.rag.prompts import SYSTEM_PROMPT, RAG_PROMPT_TEMPLATE, GREETING_PROMPT
 from app.rag.tracing import trace_function
 
@@ -48,6 +49,26 @@ def build_context(chunks: List[Dict[str, Any]]) -> str:
     return "\n\n---\n\n".join(context_parts)
 
 
+def build_augmented_context(
+    chunks: List[Dict[str, Any]],
+    question: str,
+    user_id: str,
+    document_id: Optional[str] = None,
+) -> str:
+    """Combine vector-retrieved excerpts with GraphRAG relationships."""
+    context = build_context(chunks)
+    graph_context = get_entity_context(
+        query=question,
+        user_id=user_id,
+        document_id=document_id,
+    )
+
+    if not graph_context:
+        return context
+
+    return f"{context}\n\n---\n\n{graph_context}"
+
+
 def _chat_messages(system: str, user_content: str) -> list:
     """Build messages list for chat completion API."""
     return [
@@ -108,7 +129,12 @@ def generate_answer(
 
     # ── Build prompt ─────────────────────────────────
     # Format retrieved chunks into a readable context block, then inject into the RAG prompt template
-    context = build_context(chunks)
+    context = build_augmented_context(
+        chunks=chunks,
+        question=question,
+        user_id=user_id,
+        document_id=document_id,
+    )
     user_content = RAG_PROMPT_TEMPLATE.format(context=context, question=question)
     messages = _chat_messages(SYSTEM_PROMPT, user_content)
 
@@ -222,7 +248,12 @@ def generate_answer_stream(
 
     # ── Build prompt ─────────────────────────────────
     # Format retrieved chunks into a readable context block, then inject into the RAG prompt template
-    context = build_context(chunks)
+    context = build_augmented_context(
+        chunks=chunks,
+        question=question,
+        user_id=user_id,
+        document_id=document_id,
+    )
     user_content = RAG_PROMPT_TEMPLATE.format(context=context, question=question)
     messages = _chat_messages(SYSTEM_PROMPT, user_content)
 

backend/app/rag/chunker.py

@@ -2,6 +2,7 @@
 Smart document chunking using LangChain's RecursiveCharacterTextSplitter.
 Supports PDF, DOCX, TXT, and Markdown files with page-level metadata.
 """
+import json
 import fitz  # PyMuPDF
 import docx
 from typing import List, Dict, Any
@@ -11,8 +12,72 @@ from app.config import get_settings
 settings = get_settings()
 
 
+def _is_word_inside_bbox(word: Dict[str, Any], bbox: tuple) -> bool:
+    """Return True when the word center falls inside a pdfplumber bbox."""
+    x0, top, x1, bottom = bbox
+    word_x = (float(word["x0"]) + float(word["x1"])) / 2
+    word_y = (float(word["top"]) + float(word["bottom"])) / 2
+    return x0 <= word_x <= x1 and top <= word_y <= bottom
+
+
+def _words_to_text(words: List[Dict[str, Any]], line_tolerance: float = 3.0) -> str:
+    """Rebuild readable text from positioned pdfplumber words."""
+    if not words:
+        return ""
+
+    sorted_words = sorted(words, key=lambda item: (round(float(item["top"]) / line_tolerance), item["x0"]))
+    lines: List[List[Dict[str, Any]]] = []
+
+    for word in sorted_words:
+        if not lines:
+            lines.append([word])
+            continue
+
+        current_top = sum(float(item["top"]) for item in lines[-1]) / len(lines[-1])
+        if abs(float(word["top"]) - current_top) <= line_tolerance:
+            lines[-1].append(word)
+        else:
+            lines.append([word])
+
+    text_lines = [
+        " ".join(item["text"] for item in sorted(line, key=lambda item: item["x0"]))
+        for line in lines
+    ]
+    return "\n".join(line for line in text_lines if line.strip())
+
+
+def _table_to_markdown(rows: List[List[Any]]) -> str:
+    """Serialize extracted table rows into Markdown for retrieval."""
+    cleaned_rows = [
+        ["" if cell is None else str(cell).replace("\n", " ").strip() for cell in row]
+        for row in rows
+        if row and any(cell is not None and str(cell).strip() for cell in row)
+    ]
+    if not cleaned_rows:
+        return ""
+
+    width = max(len(row) for row in cleaned_rows)
+    normalized = [row + [""] * (width - len(row)) for row in cleaned_rows]
+
+    def fmt(row: List[str]) -> str:
+        return "| " + " | ".join(cell.replace("|", "\\|") for cell in row) + " |"
+
+    header = normalized[0]
+    separator = ["---"] * width
+    body = normalized[1:]
+    return "\n".join([fmt(header), fmt(separator), *[fmt(row) for row in body]])
+
+
 def extract_pdf(filepath: str) -> List[Dict[str, Any]]:
-    """Extract text from PDF with page numbers."""
+    """Extract PDF text while preserving tables as separate bbox-aware chunks."""
+    try:
+        return extract_pdf_with_tables(filepath)
+    except ImportError:
+        return extract_pdf_with_pymupdf(filepath)
+
+
+def extract_pdf_with_pymupdf(filepath: str) -> List[Dict[str, Any]]:
+    """Fallback PDF extraction with page numbers using PyMuPDF."""
     doc = fitz.open(filepath)
     pages = []
 
@@ -22,12 +87,52 @@ def extract_pdf(filepath: str) -> List[Dict[str, Any]]:
             pages.append({
                 "text": text,
                 "page": page_num + 1,
+                "chunk_type": "text",
             })
 
     doc.close()
     return pages
 
 
+def extract_pdf_with_tables(filepath: str) -> List[Dict[str, Any]]:
+    """Detect tables with pdfplumber, remove table text from paragraphs, and keep table bboxes."""
+    import pdfplumber
+
+    pages: List[Dict[str, Any]] = []
+
+    with pdfplumber.open(filepath) as pdf:
+        for page_num, page in enumerate(pdf.pages, start=1):
+            tables = page.find_tables()
+            table_bboxes = [table.bbox for table in tables]
+
+            words = page.extract_words() or []
+            paragraph_words = [
+                word for word in words
+                if not any(_is_word_inside_bbox(word, bbox) for bbox in table_bboxes)
+            ]
+            paragraph_text = _words_to_text(paragraph_words)
+
+            if paragraph_text.strip():
+                pages.append({
+                    "text": paragraph_text,
+                    "page": page_num,
+                    "chunk_type": "text",
+                })
+
+            for table_index, table in enumerate(tables):
+                table_text = _table_to_markdown(table.extract() or [])
+                if table_text.strip():
+                    pages.append({
+                        "text": table_text,
+                        "page": page_num,
+                        "chunk_type": "table",
+                        "bbox": json.dumps([round(float(value), 2) for value in table.bbox]),
+                        "table_index": table_index,
+                    })
+
+    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.
 
@@ -109,6 +214,19 @@ def chunk_document(filepath: str) -> List[Dict[str, Any]]:
     for page_data in pages:
         text = page_data["text"]
         page_num = page_data["page"]
+        chunk_type = page_data.get("chunk_type", "text")
+
+        if chunk_type == "table":
+            all_chunks.append({
+                "text": text.strip(),
+                "page": page_num,
+                "chunk_index": chunk_index,
+                "chunk_type": "table",
+                "bbox": page_data.get("bbox", ""),
+                "table_index": page_data.get("table_index", 0),
+            })
+            chunk_index += 1
+            continue
 
         # Split this page's text
         splits = splitter.split_text(text)
@@ -119,6 +237,7 @@ def chunk_document(filepath: str) -> List[Dict[str, Any]]:
                     "text": split_text.strip(),
                     "page": page_num,
                     "chunk_index": chunk_index,
+                    "chunk_type": chunk_type,
                 })
                 chunk_index += 1
 

backend/app/rag/graph_builder.py

@@ -0,0 +1,185 @@
+"""
+Knowledge graph construction and persistence for GraphRAG.
+"""
+import json
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+import networkx as nx
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+_nlp = None
+
+
+@dataclass(frozen=True)
+class Entity:
+    id: str
+    text: str
+    label: str
+
+
+def _safe_id(value: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", value).strip("._")
+    return safe or "unknown"
+
+
+def get_graph_path(user_id: str, document_id: str) -> Path:
+    """Return the on-disk graph path for one user/document pair."""
+    filename = f"{_safe_id(user_id)}_{_safe_id(document_id)}.json"
+    return Path(settings.GRAPH_PERSIST_DIR) / filename
+
+
+def iter_graph_paths(user_id: str) -> Iterable[Path]:
+    """Yield every persisted graph path for a user."""
+    graph_dir = Path(settings.GRAPH_PERSIST_DIR)
+    if not graph_dir.exists():
+        return []
+
+    prefix = f"{_safe_id(user_id)}_"
+    return sorted(graph_dir.glob(f"{prefix}*.json"))
+
+
+def _get_nlp():
+    """Load the spaCy English NER model lazily."""
+    global _nlp
+    if _nlp is None:
+        import spacy
+
+        try:
+            _nlp = spacy.load("en_core_web_sm")
+        except OSError as exc:
+            raise RuntimeError(
+                "spaCy model 'en_core_web_sm' is required for GraphRAG entity extraction. "
+                "Install it with: python -m spacy download en_core_web_sm"
+            ) from exc
+    return _nlp
+
+
+def _entity_id(text: str, label: str) -> str:
+    normalized = " ".join(text.split()).casefold()
+    return f"{label}:{normalized}"
+
+
+def extract_entities(text: str) -> List[Entity]:
+    """Extract configured named entities from text."""
+    if not text or not text.strip():
+        return []
+
+    doc = _get_nlp()(text)
+    entities: Dict[str, Entity] = {}
+
+    for ent in doc.ents:
+        value = " ".join(ent.text.split()).strip()
+        if not value or ent.label_ not in settings.GRAPH_ENTITY_LABELS:
+            continue
+
+        entity_id = _entity_id(value, ent.label_)
+        entities.setdefault(
+            entity_id,
+            Entity(id=entity_id, text=value, label=ent.label_),
+        )
+
+    return list(entities.values())
+
+
+def build_graph(chunks: List[Dict[str, Any]]) -> nx.Graph:
+    """Build an entity co-occurrence graph from document chunks."""
+    graph = nx.Graph()
+
+    for chunk in chunks:
+        text = chunk.get("text", "")
+        page = chunk.get("page")
+        chunk_index = chunk.get("chunk_index")
+        entities = extract_entities(text)
+
+        for entity in entities:
+            if graph.has_node(entity.id):
+                graph.nodes[entity.id]["mentions"] += 1
+                graph.nodes[entity.id]["pages"].add(page)
+                graph.nodes[entity.id]["chunks"].add(chunk_index)
+            else:
+                graph.add_node(
+                    entity.id,
+                    name=entity.text,
+                    label=entity.label,
+                    mentions=1,
+                    pages={page},
+                    chunks={chunk_index},
+                )
+
+        for left_index, left in enumerate(entities):
+            for right in entities[left_index + 1:]:
+                if graph.has_edge(left.id, right.id):
+                    graph[left.id][right.id]["weight"] += 1
+                    graph[left.id][right.id]["pages"].add(page)
+                    graph[left.id][right.id]["chunks"].add(chunk_index)
+                else:
+                    graph.add_edge(
+                        left.id,
+                        right.id,
+                        weight=1,
+                        pages={page},
+                        chunks={chunk_index},
+                    )
+
+    _convert_sets_for_json(graph)
+    return graph
+
+
+def _convert_sets_for_json(graph: nx.Graph) -> None:
+    for _, data in graph.nodes(data=True):
+        data["pages"] = sorted(item for item in data.get("pages", []) if item is not None)
+        data["chunks"] = sorted(item for item in data.get("chunks", []) if item is not None)
+
+    for _, _, data in graph.edges(data=True):
+        data["pages"] = sorted(item for item in data.get("pages", []) if item is not None)
+        data["chunks"] = sorted(item for item in data.get("chunks", []) if item is not None)
+
+
+def save_graph(graph: nx.Graph, user_id: str, document_id: str) -> Path:
+    """Persist a graph to disk as node-link JSON."""
+    graph_path = get_graph_path(user_id, document_id)
+    graph_path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = nx.node_link_data(graph)
+    data["metadata"] = {
+        "user_id": user_id,
+        "document_id": document_id,
+        "node_count": graph.number_of_nodes(),
+        "edge_count": graph.number_of_edges(),
+    }
+
+    graph_path.write_text(json.dumps(data, ensure_ascii=True, indent=2), encoding="utf-8")
+    logger.info(
+        "Saved knowledge graph for document %s with %s nodes and %s edges",
+        document_id,
+        graph.number_of_nodes(),
+        graph.number_of_edges(),
+    )
+    return graph_path
+
+
+def load_graph(user_id: str, document_id: str) -> Optional[nx.Graph]:
+    """Load a persisted graph for one user/document pair."""
+    return load_graph_path(get_graph_path(user_id, document_id))
+
+
+def load_graph_path(graph_path: Path) -> Optional[nx.Graph]:
+    """Load a graph from a concrete JSON path."""
+    if not graph_path.exists():
+        return None
+
+    data = json.loads(graph_path.read_text(encoding="utf-8"))
+    return nx.node_link_graph(data)
+
+
+def delete_graph(user_id: str, document_id: str) -> None:
+    """Delete a persisted graph file if it exists."""
+    get_graph_path(user_id, document_id).unlink(missing_ok=True)

backend/app/rag/graph_retriever.py

@@ -0,0 +1,123 @@
+"""
+Knowledge graph retrieval for augmenting RAG context.
+"""
+import logging
+from typing import Dict, Iterable, List, Optional, Set, Tuple
+
+import networkx as nx
+
+from app.config import get_settings
+from app.rag.graph_builder import (
+    extract_entities,
+    iter_graph_paths,
+    load_graph,
+    load_graph_path,
+)
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+def _candidate_graphs(user_id: str, document_id: Optional[str]) -> Iterable[nx.Graph]:
+    if document_id:
+        graph = load_graph(user_id, document_id)
+        return [graph] if graph is not None else []
+
+    graphs = []
+    for path in iter_graph_paths(user_id):
+        graph = load_graph_path(path)
+        if graph is not None:
+            graphs.append(graph)
+    return graphs
+
+
+def _node_name(graph: nx.Graph, node_id: str) -> str:
+    return graph.nodes[node_id].get("name", node_id.split(":", 1)[-1])
+
+
+def _match_query_nodes(graph: nx.Graph, query: str) -> Set[str]:
+    query_entities = extract_entities(query)
+    matched = {entity.id for entity in query_entities if graph.has_node(entity.id)}
+
+    if matched:
+        return matched
+
+    query_text = query.casefold()
+    for node_id, data in graph.nodes(data=True):
+        name = data.get("name", "").casefold()
+        if name and name in query_text:
+            matched.add(node_id)
+
+    return matched
+
+
+def _format_pages(pages: List[int]) -> str:
+    if not pages:
+        return "unknown pages"
+    if len(pages) == 1:
+        return f"page {pages[0]}"
+    return "pages " + ", ".join(str(page) for page in pages[:4])
+
+
+def _relationship_key(left: str, right: str) -> Tuple[str, str]:
+    return tuple(sorted((left, right)))
+
+
+def get_entity_context(
+    query: str,
+    user_id: str,
+    document_id: Optional[str] = None,
+) -> str:
+    """Return compact graph relationship context relevant to the query."""
+    relationships: Dict[Tuple[str, str], Dict[str, object]] = {}
+
+    try:
+        graphs = _candidate_graphs(user_id=user_id, document_id=document_id)
+        for graph in graphs:
+            matched_nodes = _match_query_nodes(graph, query)
+
+            for node_id in matched_nodes:
+                neighbors = sorted(
+                    graph.neighbors(node_id),
+                    key=lambda neighbor: graph[node_id][neighbor].get("weight", 0),
+                    reverse=True,
+                )
+                for neighbor_id in neighbors:
+                    edge = graph[node_id][neighbor_id]
+                    left = _node_name(graph, node_id)
+                    right = _node_name(graph, neighbor_id)
+                    key = _relationship_key(left.casefold(), right.casefold())
+                    existing = relationships.setdefault(
+                        key,
+                        {
+                            "left": left,
+                            "right": right,
+                            "weight": 0,
+                            "pages": set(),
+                        },
+                    )
+                    existing["weight"] = int(existing["weight"]) + int(edge.get("weight", 1))
+                    existing["pages"].update(edge.get("pages", []))
+    except Exception as exc:
+        logger.warning("GraphRAG context retrieval failed: %s", exc)
+        return ""
+
+    if not relationships:
+        return ""
+
+    ranked = sorted(
+        relationships.values(),
+        key=lambda item: int(item["weight"]),
+        reverse=True,
+    )[: settings.GRAPH_MAX_RELATIONSHIPS]
+
+    lines = ["## Knowledge Graph Context"]
+    for item in ranked:
+        pages = sorted(item["pages"])
+        lines.append(
+            f"- {item['left']} is related to {item['right']} "
+            f"through document co-occurrence on {_format_pages(pages)} "
+            f"(strength: {item['weight']})."
+        )
+
+    return "\n".join(lines)

backend/app/rag/vectorstore.py

@@ -91,6 +91,9 @@ def store_chunks(
             "document_id": document_id,
             "page": chunk["page"],
             "chunk_index": chunk["chunk_index"],
+            "chunk_type": chunk.get("chunk_type", "text"),
+            **({"bbox": chunk.get("bbox", "")} if chunk.get("bbox") else {}),
+            **({"table_index": chunk.get("table_index", 0)} if chunk.get("chunk_type") == "table" else {}),
             # 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 {}),
@@ -169,6 +172,8 @@ def query_chunks(
                 "filename": metadata.get("filename", ""),
                 "document_id": metadata.get("document_id", ""),
                 "page": metadata.get("page", 1),
+                "chunk_type": metadata.get("chunk_type", "text"),
+                "bbox": metadata.get("bbox", ""),
                 "score": round(similarity, 4),
             })
 

backend/app/routes/chat.py

@@ -7,20 +7,16 @@ import time
 from datetime import datetime
 from io import BytesIO
 import logging
-from typing import Optional
+from typing import Optional, List
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
-from reportlab.lib.pagesizes import letter
-from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
-from reportlab.lib.units import inch
-from reportlab.platypus import Paragraph, SimpleDocTemplate, Spacer
 from sqlalchemy.orm import Session
 
 from app.auth import get_current_user
 from app.database import get_db
 from app.metrics import record_query_response_time
-from app.models import User, ChatMessage, Document, SharedMessage
+from app.models import User, ChatMessage, Document, SharedMessage, ChatSession
 from app.rate_limit import limiter
 from app.schemas import (
     ChatRequest,
@@ -30,6 +26,8 @@ from app.schemas import (
     ShareAnswerResponse,
     ShareLinkResponse,
     SourceChunk,
+    ChatSessionCreate,
+    ChatSessionResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -77,11 +75,139 @@ def create_share_link(
         db.commit()
 
     return ShareLinkResponse(
-        message_id=message.id,
+        message_id=str(message.id),
         share_url=f"/share?message_id={message.id}",
     )
 
 
+@router.get("/sessions", response_model=List[ChatSessionResponse])
+def get_chat_sessions(
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Retrieve all chat sessions for the authenticated user."""
+    sessions = (
+        db.query(ChatSession)
+        .filter(ChatSession.user_id == user.id)
+        .order_by(ChatSession.created_at.desc())
+        .all()
+    )
+    return sessions
+
+
+@router.post("/sessions", response_model=ChatSessionResponse, status_code=201)
+def create_chat_session(
+    payload: ChatSessionCreate,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Create a new chat session."""
+    session = ChatSession(
+        user_id=user.id,
+        title=payload.title,
+    )
+    db.add(session)
+    db.commit()
+    db.refresh(session)
+    return session
+
+
+@router.put("/sessions/{session_id}", response_model=ChatSessionResponse)
+def rename_chat_session(
+    session_id: str,
+    payload: ChatSessionCreate,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Rename an existing chat session."""
+    session = (
+        db.query(ChatSession)
+        .filter(
+            ChatSession.id == session_id,
+            ChatSession.user_id == user.id,
+        )
+        .first()
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Chat session not found")
+    session.title = payload.title
+    db.commit()
+    db.refresh(session)
+    return session
+
+
+@router.delete("/sessions/{session_id}")
+def delete_chat_session(
+    session_id: str,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Delete a chat session and all its messages."""
+    session = (
+        db.query(ChatSession)
+        .filter(
+            ChatSession.id == session_id,
+            ChatSession.user_id == user.id,
+        )
+        .first()
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Chat session not found")
+    db.delete(session)
+    db.commit()
+    return Response(status_code=204)
+
+
+@router.get("/history/session/{session_id}", response_model=ChatHistoryResponse)
+def get_session_history(
+    session_id: str,
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    """Retrieve chat history for a specific chat session."""
+    session = (
+        db.query(ChatSession)
+        .filter(
+            ChatSession.id == session_id,
+            ChatSession.user_id == user.id,
+        )
+        .first()
+    )
+    if not session:
+        raise HTTPException(status_code=404, detail="Chat session not found")
+
+    messages = (
+        db.query(ChatMessage)
+        .filter(
+            ChatMessage.session_id == session_id,
+            ChatMessage.user_id == user.id,
+        )
+        .order_by(ChatMessage.created_at.asc())
+        .all()
+    )
+
+    formatted = []
+    for msg in messages:
+        sources = []
+        if msg.sources_json:
+            try:
+                sources = [SourceChunk(**s) for s in json.loads(msg.sources_json)]
+            except Exception:
+                pass
+
+        formatted.append(
+            ChatMessageResponse(
+                id=str(msg.id),
+                role=msg.role,
+                content=msg.content,
+                sources=sources,
+                created_at=msg.created_at,
+            )
+        )
+
+    return ChatHistoryResponse(messages=formatted, document_id=None)
+
+
 def generate_answer(question: str, user_id: str, document_id: Optional[str] = None, hf_token: Optional[str] = None):
     from app.rag.agent import generate_answer as _generate_answer
 
@@ -102,33 +228,7 @@ def ask_question(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with RAG retrieval (non-streaming).
-
-    Processes a user's question by retrieving relevant document chunks,
-    generating an answer using an LLM, and saving the conversation to chat
-    history. If a `document_id` is provided, the retrieval is scoped to that
-    specific document; otherwise, it searches across all documents owned by
-    the user.
-
-    Args:
-        payload: ChatRequest containing the `question` text and optionally a
-            `document_id` to limit the retrieval scope.
-        user: The currently authenticated user, obtained from the dependency.
-        db: SQLAlchemy database session, obtained from the dependency.
-
-    Returns:
-        ChatResponse: An object containing:
-            - answer: The generated answer text.
-            - sources: A list of `SourceChunk` objects with metadata about
-              the retrieved chunks (e.g., filename, page number, text snippet).
-            - document_id: The document ID that was used (if any).
-
-    Raises:
-        HTTPException: 404 if the specified `document_id` does not exist or
-            does not belong to the authenticated user.
-        HTTPException: 400 if the document exists but its status is not
-            "ready" (e.g., still processing or failed).
-    """
+    """Ask a question with RAG retrieval (non-streaming)."""
     started_at = time.perf_counter()
     try:
         # Validate document exists if specified
@@ -147,6 +247,17 @@ def ask_question(
                     detail=f"Document is still {doc.status}. Please wait for processing to complete.",
                 )
 
+        # Resolve or create session
+        session_id = payload.session_id
+        if not session_id:
+            session = db.query(ChatSession).filter(ChatSession.user_id == user.id).first()
+            if not session:
+                session = ChatSession(user_id=user.id, title="Default Chat")
+                db.add(session)
+                db.commit()
+                db.refresh(session)
+            session_id = session.id
+
         result = generate_answer(
             question=payload.question,
             user_id=user.id,
@@ -155,8 +266,8 @@ def ask_question(
         )
 
         # 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_message(db, user.id, payload.document_id, "user", payload.question, session_id=session_id)
+        _save_message(db, user.id, payload.document_id, "assistant", result["answer"], result["sources"], session_id=session_id)
 
         return ChatResponse(
             answer=result["answer"],
@@ -175,41 +286,7 @@ def ask_question_stream(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with Server-Sent Events (SSE) streaming response.
-
-    Processes a user's question using RAG and streams the answer token by
-    token over SSE. The user's question is saved to chat history immediately.
-    The assistant's answer is accumulated on the server and saved to history
-    only after the stream completes. If a `document_id` is provided, retrieval
-    is scoped to that document.
-
-    Args:
-        payload: ChatRequest containing the `question` text and optionally a
-            `document_id` to limit the retrieval scope.
-        user: The currently authenticated user, obtained from the dependency.
-        db: SQLAlchemy database session, obtained from the dependency.
-
-    Returns:
-        StreamingResponse: A FastAPI `StreamingResponse` with:
-            - media_type: "text/event-stream"
-            - Headers: Cache-Control, Connection, and X-Accel-Buffering set
-              for proper SSE behavior.
-            - Body: A generator yielding SSE messages with `token` (partial
-              answer) and `sources` (final source metadata) events.
-
-    Raises:
-        HTTPException: 404 if the specified `document_id` does not exist or
-            does not belong to the authenticated user.
-        HTTPException: 400 if the document exists but its status is not
-            "ready" (e.g., still processing or failed).
-
-    Note:
-        The streaming response uses a generator `event_stream` that yields
-        raw SSE chunks. The assistant's full answer is reconstructed from
-        the stream to save the complete conversation history. A separate
-        database session is created inside the generator to avoid using the
-        closed request session.
-    """
+    """Ask a question with Server-Sent Events (SSE) streaming response."""
     # Validate document
     if payload.document_id:
         doc = db.query(Document).filter(
@@ -228,8 +305,19 @@ def ask_question_stream(
 
     started_at = time.perf_counter()
 
+    # Resolve or create session
+    session_id = payload.session_id
+    if not session_id:
+        session = db.query(ChatSession).filter(ChatSession.user_id == user.id).first()
+        if not session:
+            session = ChatSession(user_id=user.id, title="Default Chat")
+            db.add(session)
+            db.commit()
+            db.refresh(session)
+        session_id = session.id
+
     # Save user message immediately
-    _save_message(db, user.id, payload.document_id, "user", payload.question)
+    _save_message(db, user.id, payload.document_id, "user", payload.question, session_id=session_id)
 
     # Stream response
     def event_stream():
@@ -260,7 +348,7 @@ def ask_question_stream(
             from app.database import SessionLocal
             save_db = SessionLocal()
             try:
-                _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources)
+                _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources, session_id=session_id)
             finally:
                 save_db.close()
         finally:
@@ -283,25 +371,7 @@ def get_chat_history(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Retrieve the complete chat history for a specific document.
-
-    Fetches all messages (both user and assistant) associated with the given
-    document and the authenticated user, ordered chronologically from oldest
-    to newest. Assistant messages that contain source metadata will have the
-    `sources` field populated.
-
-    Args:
-        document_id: The unique identifier of the document whose chat history is requested.
-        user: The currently authenticated user, obtained from the dependency.
-        db: SQLAlchemy database session, obtained from the dependency.
-
-    Returns:
-        ChatHistoryResponse: An object containing:
-            - messages: A list of `ChatMessageResponse` objects, each with
-              `id`, `role` ("user" or "assistant"), `content`, `sources`
-              (list of `SourceChunk` for assistant messages), and `created_at`.
-            - document_id: The document ID that was queried.
-    """
+    """Retrieve the complete chat history for a specific document."""
     messages = (
         db.query(ChatMessage)
         .filter(
@@ -322,7 +392,7 @@ def get_chat_history(
                 pass
 
         formatted.append(ChatMessageResponse(
-            id=msg.id,
+            id=str(msg.id),
             role=msg.role,
             content=msg.content,
             sources=sources,
@@ -339,33 +409,7 @@ def export_chat_history(
     token: Optional[str] = None,
     db: Session = Depends(get_db),
 ):
-    """Export the chat history for a document as a downloadable file.
-
-    Supports Markdown (.md), plain text (.txt), or PDF (.pdf) export. The function accepts
-    authentication via either the standard `Authorization: Bearer <token>`
-    header (handled by the dependency chain) or a `token` query parameter to
-    facilitate browser-initiated downloads that cannot set custom headers.
-
-    Args:
-        document_id: The unique identifier of the document whose chat history is to be exported.
-        format: Output format, either "md" (Markdown), "txt" (plain text), or "pdf". Defaults to "md".
-        token: Optional JWT token passed as a query parameter. Used for browser
-            downloads when the `Authorization` header is not available.
-        db: SQLAlchemy database session, obtained from the dependency.
-
-    Returns:
-        Response: A FastAPI `Response` object with:
-            - `content`: Formatted chat history as a string or PDF bytes.
-            - `media_type`: `text/markdown`, `text/plain`, or `application/pdf`.
-            - `headers`: `Content-Disposition` attachment header with a generated filename.
-
-    Raises:
-        HTTPException: 401 if neither the token query parameter nor a valid
-            bearer token provides an authenticated user.
-        HTTPException: 400 if the `format` parameter is not "md", "txt", or "pdf".
-        HTTPException: 404 if the document does not exist or does not belong
-            to the user, or if no chat messages are found for the document.
-    """
+    """Export the chat history for a document as a downloadable file."""
     from app.auth import decode_token as _decode
 
     # Resolve user from query-param token (browser download links can't set headers)
@@ -412,6 +456,7 @@ def export_chat_history(
         media_type = "text/plain"
         extension = "txt"
     else:
+        from app.routes.chat_export import format_pdf as _format_pdf
         content = _format_pdf(doc, messages)
         media_type = "application/pdf"
         extension = "pdf"
@@ -434,20 +479,7 @@ def clear_chat_history(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Delete all chat messages associated with a specific document.
-
-    Removes every chat message (both user and assistant) linked to the given
-    `document_id` and the authenticated user. The deletion is permanent and
-    cannot be undone.
-
-    Args:
-        document_id: The unique identifier of the document whose chat history should be cleared.
-        user: The currently authenticated user, obtained from the dependency.
-        db: SQLAlchemy database session, obtained from the dependency.
-
-    Returns:
-        dict: A simple JSON object with a `message` field confirming the deletion.
-    """
+    """Delete all chat messages associated with a specific document."""
     db.query(ChatMessage).filter(
         ChatMessage.user_id == user.id,
         ChatMessage.document_id == document_id,
@@ -464,35 +496,22 @@ def _save_message(
     role: str,
     content: str,
     sources: list = None,
+    session_id: Optional[str] = None,
 ):
-    """Save a chat message to the database.
-
-    Creates a `ChatMessage` record with the provided user, document,
-    role, content, and optional source metadata. The message is added to
-    the session and committed immediately. The database session must be
-    managed by the caller (e.g., closed after use).
-
-    Args:
-        user_id: The ID of the authenticated user.
-        document_id: Optional document ID that the message pertains to.
-            Can be `None` for global chat contexts.
-        db: SQLAlchemy database session (active, typically from a dependency).
-        role: The message sender role, e.g., "user" or "assistant".
-        content: The full text content of the message.
-        sources: Optional list of source dictionaries (usually from RAG
-            retrieval) to be stored as JSON. Defaults to `None`.
-
-    Returns:
-        None
-
-    Note:
-        The function commits the transaction. It does not close the session,
-        leaving that responsibility to the caller. If `sources` is provided,
-        it is serialized using `json.dumps()`.
-    """
+    """Save a chat message to the database."""
+    if not session_id:
+        session = db.query(ChatSession).filter(ChatSession.user_id == user_id).first()
+        if not session:
+            session = ChatSession(user_id=user_id, title="Default Chat")
+            db.add(session)
+            db.commit()
+            db.refresh(session)
+        session_id = session.id
+
     msg = ChatMessage(
         user_id=user_id,
         document_id=document_id,
+        session_id=session_id,
         role=role,
         content=content,
         sources_json=json.dumps(sources) if sources else None,
@@ -511,7 +530,7 @@ def _share_answer_response(message: ChatMessage) -> ShareAnswerResponse:
             sources = []
 
     return ShareAnswerResponse(
-        id=message.id,
+        id=str(message.id),
         content=message.content,
         created_at=message.created_at,
         sources=sources,
@@ -519,28 +538,12 @@ def _share_answer_response(message: ChatMessage) -> ShareAnswerResponse:
 
 
 def _format_markdown(doc, messages) -> str:
-    """Format chat history as a Markdown document.
-
-    Generates a Markdown string containing the document metadata and the
-    full conversation. User messages are labeled "You", assistant messages
-    are labeled "Assistant". For assistant responses, if source information
-    is available, it is rendered as a numbered list with filename, page,
-    confidence, and a text preview.
-
-    Args:
-        doc: The Document object (must have `original_name` attribute).
-        messages: List of ChatMessage objects, each with attributes:
-            `role` (str), `content` (str), `created_at` (datetime, optional),
-            and `sources_json` (str, JSON-encoded list of source dicts).
-
-    Returns:
-        str: A Markdown string ready for writing to a `.md` file.
-    """
+    """Format chat history as a Markdown document."""
     lines = [
         f"# Chat History — {doc.original_name}",
         "",
         f"**Document:** {doc.original_name}  ",
-        f"**Exported at:** {__import__('datetime').datetime.now().strftime('%Y-%m-%d %H:%M:%S')}  ",
+        f"**Exported at:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}  ",
         f"**Total messages:** {len(messages)}",
         "",
         "---",
@@ -557,7 +560,6 @@ def _format_markdown(doc, messages) -> str:
         lines.append(msg.content)
         lines.append("")
 
-        # Include source citations for assistant messages
         if msg.role == "assistant" and msg.sources_json:
             try:
                 sources = json.loads(msg.sources_json)
@@ -583,26 +585,10 @@ def _format_markdown(doc, messages) -> str:
 
 
 def _format_plaintext(doc, messages) -> str:
-    """Format chat history as a plain text document.
-
-    Generates a plain text string containing the document metadata and the
-    full conversation. User messages are labeled "You", assistant messages
-    are labeled "Assistant". For assistant responses, if source information
-    is available, it is rendered as a numbered list with filename, page,
-    and confidence (text preview is omitted in plain text format).
-
-    Args:
-        doc: The Document object (must have `original_name` attribute).
-        messages: List of ChatMessage objects, each with attributes:
-            `role` (str), `content` (str), `created_at` (datetime, optional),
-            and `sources_json` (str, JSON‑encoded list of source dicts).
-
-    Returns:
-        str: A plain text string ready for writing to a `.txt` file.
-    """
+    """Format chat history as a plain text document."""
     lines = [
         f"Chat History — {doc.original_name}",
-        f"Exported at: {__import__('datetime').datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"Exported at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
         f"Total messages: {len(messages)}",
         "=" * 60,
         "",
@@ -615,7 +601,6 @@ def _format_plaintext(doc, messages) -> str:
         lines.append(f"[{role_label}] ({timestamp})")
         lines.append(msg.content)
 
-        # Include source citations for assistant messages
         if msg.role == "assistant" and msg.sources_json:
             try:
                 sources = json.loads(msg.sources_json)
@@ -633,81 +618,3 @@ def _format_plaintext(doc, messages) -> str:
         lines.append("")
 
     return "\n".join(lines)
-
-
-def _format_pdf(doc, messages) -> bytes:
-    """Format chat history as a PDF document."""
-    buffer = BytesIO()
-    pdf = SimpleDocTemplate(
-        buffer,
-        pagesize=letter,
-        leftMargin=0.75 * inch,
-        rightMargin=0.75 * inch,
-        topMargin=0.75 * inch,
-        bottomMargin=0.75 * inch,
-    )
-
-    styles = getSampleStyleSheet()
-    metadata_style = styles["Normal"]
-    metadata_style.spaceAfter = 6
-    content_style = ParagraphStyle(
-        "ChatContent",
-        parent=styles["BodyText"],
-        leading=14,
-        spaceAfter=10,
-    )
-    source_style = ParagraphStyle(
-        "ChatSource",
-        parent=styles["BodyText"],
-        leftIndent=14,
-        leading=12,
-        spaceAfter=4,
-    )
-
-    story = [
-        Paragraph(f"Chat History - {html.escape(doc.original_name)}", styles["Title"]),
-        Spacer(1, 0.15 * inch),
-        Paragraph(f"Document: {html.escape(doc.original_name)}", metadata_style),
-        Paragraph(f"Exported at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}", metadata_style),
-        Paragraph(f"Total messages: {len(messages)}", metadata_style),
-        Spacer(1, 0.2 * inch),
-    ]
-
-    for msg in messages:
-        timestamp = msg.created_at.strftime("%Y-%m-%d %H:%M:%S") if msg.created_at else ""
-        role_label = "You" if msg.role == "user" else "Assistant"
-
-        story.append(Paragraph(f"<b>{html.escape(role_label)}</b>", styles["Heading3"]))
-        story.append(Paragraph(html.escape(timestamp), styles["Italic"]))
-        story.append(Paragraph(_pdf_text(msg.content), content_style))
-
-        if msg.role == "assistant" and msg.sources_json:
-            try:
-                sources = json.loads(msg.sources_json)
-                if sources:
-                    story.append(Paragraph("<b>Sources:</b>", metadata_style))
-                    for i, src in enumerate(sources, 1):
-                        filename = html.escape(str(src.get("filename", "Unknown")))
-                        page = html.escape(str(src.get("page", "?")))
-                        confidence = html.escape(str(src.get("confidence", 0)))
-                        story.append(
-                            Paragraph(
-                                f"[{i}] {filename}, Page {page} (Confidence: {confidence}%)",
-                                source_style,
-                            )
-                        )
-                        text_preview = str(src.get("text", "")).strip()
-                        if text_preview:
-                            story.append(Paragraph(_pdf_text(text_preview), source_style))
-            except Exception:
-                pass
-
-        story.append(Spacer(1, 0.15 * inch))
-
-    pdf.build(story)
-    return buffer.getvalue()
-
-
-def _pdf_text(text: str) -> str:
-    """Escape text for ReportLab paragraphs while preserving line breaks."""
-    return html.escape(text or "").replace("\n", "<br/>")

backend/app/routes/documents.py

@@ -172,6 +172,15 @@ def _ingest_document(document_id: str, filepath: str, original_name: str, user_i
             db.commit()
             return
 
+        # Build and persist a lightweight entity co-occurrence graph for GraphRAG.
+        try:
+            from app.rag.graph_builder import build_graph, save_graph
+
+            graph = build_graph(chunks)
+            save_graph(graph, user_id=user_id, document_id=document_id)
+        except Exception as e:
+            logger.warning(f"Could not build knowledge graph for document {document_id}: {e}")
+
         # Store embeddings in ChromaDB
         chunk_count = store_chunks(
             chunks=chunks,
@@ -629,6 +638,14 @@ def delete_document(
     except Exception as e:
         logger.warning(f"Error deleting vectors: {e}")
 
+    # Delete persisted knowledge graph
+    try:
+        from app.rag.graph_builder import delete_graph
+
+        delete_graph(user_id=user.id, document_id=document_id)
+    except Exception as e:
+        logger.warning(f"Error deleting knowledge graph: {e}")
+
     # Delete from database (cascades to chat messages)
     db.delete(doc)
     db.commit()

backend/app/schemas.py

@@ -146,6 +146,7 @@ class AdminStatsResponse(BaseModel):
 class ChatRequest(BaseModel):
     question: str = Field(..., min_length=1, max_length=2000)
     document_id: Optional[str] = None
+    session_id: Optional[str] = None
 
 
 class SourceChunk(BaseModel):
@@ -192,5 +193,20 @@ class ShareLinkResponse(BaseModel):
     share_url: str
 
 
+# ── Chat Session ──────────────────────────────────────
+
+class ChatSessionCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+
+
+class ChatSessionResponse(BaseModel):
+    id: str
+    title: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
 # Rebuild models for forward references
 TokenResponse.model_rebuild()

backend/requirements.txt

@@ -25,6 +25,7 @@ httpx
 
 # Document Processing
 PyMuPDF
+pdfplumber
 python-docx
 
 # LangChain & RAG
@@ -42,6 +43,9 @@ transformers
 
 # Vector Database
 chromadb
+networkx>=3.3
+spacy>=3.7
+neo4j>=5.0
 
 # LLM Inference
 huggingface-hub

backend/tests/test_chunker.py

@@ -1,7 +1,10 @@
 from pathlib import Path
+import sys
+import types
 
 import pytest
 
+from app.rag import chunker
 from app.rag.chunker import chunk_document, get_page_count
 
 
@@ -36,3 +39,49 @@ def test_get_page_count_for_txt_returns_one(tmp_path):
     file_path.write_text("hello", encoding="utf-8")
 
     assert get_page_count(str(file_path)) == 1
+
+
+def test_pdf_table_detection_separates_table_from_paragraph(monkeypatch):
+    class FakeTable:
+        bbox = (40, 90, 300, 160)
+
+        def extract(self):
+            return [["Name", "Amount"], ["Alpha", "$10"]]
+
+    class FakePage:
+        def find_tables(self):
+            return [FakeTable()]
+
+        def extract_words(self):
+            return [
+                {"text": "Intro", "x0": 40, "x1": 70, "top": 20, "bottom": 30},
+                {"text": "paragraph", "x0": 75, "x1": 140, "top": 20, "bottom": 30},
+                {"text": "Name", "x0": 45, "x1": 80, "top": 100, "bottom": 110},
+                {"text": "Amount", "x0": 160, "x1": 220, "top": 100, "bottom": 110},
+                {"text": "Alpha", "x0": 45, "x1": 85, "top": 125, "bottom": 135},
+                {"text": "$10", "x0": 160, "x1": 185, "top": 125, "bottom": 135},
+            ]
+
+    class FakePdf:
+        pages = [FakePage()]
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, traceback):
+            return False
+
+    fake_pdfplumber = types.SimpleNamespace(open=lambda _filepath: FakePdf())
+    monkeypatch.setitem(sys.modules, "pdfplumber", fake_pdfplumber)
+    monkeypatch.setattr(chunker, "extract_pdf_images", lambda _filepath: [])
+
+    chunks = chunk_document("report.pdf")
+
+    assert len(chunks) == 2
+    assert chunks[0]["chunk_type"] == "text"
+    assert chunks[0]["text"] == "Intro paragraph"
+    assert "Name" not in chunks[0]["text"]
+    assert chunks[1]["chunk_type"] == "table"
+    assert chunks[1]["bbox"] == "[40.0, 90.0, 300.0, 160.0]"
+    assert "| Name | Amount |" in chunks[1]["text"]
+    assert "| Alpha | $10 |" in chunks[1]["text"]

backend/tests/test_documents.py

@@ -1,3 +1,9 @@
+import types
+
+from app.models import Document
+from app.routes.documents import _ingest_document
+
+
 def test_api_health(client):
     response = client.get("/api/health")
 
@@ -32,3 +38,76 @@ def test_upload_rejects_unsupported_extension_before_deep_validation(client, aut
 
     assert response.status_code == 400
     assert "not supported" in response.json()["detail"]
+
+
+def test_ingest_document_builds_and_saves_graph(db_session, monkeypatch, tmp_path, user):
+    document = Document(
+        user_id=user.id,
+        filename="graph.txt",
+        original_name="graph.txt",
+        file_size=128,
+        status="pending",
+    )
+    db_session.add(document)
+    db_session.commit()
+    db_session.refresh(document)
+    user_id = user.id
+    document_id = document.id
+    chunks = [{"text": "OpenAI works with Microsoft.", "page": 1, "chunk_index": 0}]
+    saved = {}
+
+    monkeypatch.setattr("app.routes.documents.get_page_count", lambda filepath: 1)
+    monkeypatch.setattr("app.routes.documents.chunk_document", lambda filepath: chunks)
+    monkeypatch.setattr("app.routes.documents.store_chunks", lambda **kwargs: len(chunks))
+    monkeypatch.setattr("app.database.SessionLocal", lambda: db_session)
+
+    fake_summary = types.ModuleType("app.rag.summarizer")
+    fake_summary.generate_document_summary = lambda filepath, max_sentences=2: "Summary"
+    monkeypatch.setitem(__import__("sys").modules, "app.rag.summarizer", fake_summary)
+
+    monkeypatch.setattr(
+        "app.rag.graph_builder.build_graph",
+        lambda received_chunks: {"chunks": received_chunks},
+    )
+    monkeypatch.setattr(
+        "app.rag.graph_builder.save_graph",
+        lambda graph, user_id, document_id: saved.update(
+            {"graph": graph, "user_id": user_id, "document_id": document_id}
+        ),
+    )
+
+    _ingest_document(
+        document_id=document_id,
+        filepath=str(tmp_path / "graph.txt"),
+        original_name=document.original_name,
+        user_id=user_id,
+    )
+
+    assert saved == {
+        "graph": {"chunks": chunks},
+        "user_id": user_id,
+        "document_id": document_id,
+    }
+    refreshed = db_session.get(Document, document_id)
+    assert refreshed.status == "ready"
+    assert refreshed.chunk_count == 1
+
+
+def test_delete_document_removes_knowledge_graph(client, auth_headers, ready_document, monkeypatch):
+    deleted = {}
+
+    monkeypatch.setattr("app.routes.documents.delete_document_chunks", lambda **kwargs: None)
+    monkeypatch.setattr(
+        "app.rag.graph_builder.delete_graph",
+        lambda user_id, document_id: deleted.update(
+            {"user_id": user_id, "document_id": document_id}
+        ),
+    )
+
+    response = client.delete(
+        f"/api/v1/documents/{ready_document.id}",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    assert deleted["document_id"] == ready_document.id

backend/tests/test_graph_builder.py

@@ -0,0 +1,89 @@
+import json
+
+from app.rag import graph_builder
+
+
+class FakeEntity:
+    def __init__(self, text, label):
+        self.text = text
+        self.label_ = label
+
+
+class FakeDoc:
+    def __init__(self, entities):
+        self.ents = entities
+
+
+class FakeNlp:
+    def __call__(self, text):
+        entities = []
+        for value, label in (
+            ("OpenAI", "ORG"),
+            ("Microsoft", "ORG"),
+            ("Azure", "PRODUCT"),
+            ("Ignored Date", "DATE"),
+        ):
+            if value in text:
+                entities.append(FakeEntity(value, label))
+        return FakeDoc(entities)
+
+
+def test_extract_entities_filters_configured_labels(monkeypatch):
+    monkeypatch.setattr(graph_builder, "_nlp", FakeNlp())
+
+    entities = graph_builder.extract_entities("OpenAI works with Microsoft on Ignored Date")
+
+    assert {entity.text for entity in entities} == {"OpenAI", "Microsoft"}
+    assert {entity.label for entity in entities} == {"ORG"}
+
+
+def test_build_graph_tracks_entity_edges_and_weights(monkeypatch):
+    monkeypatch.setattr(graph_builder, "_nlp", FakeNlp())
+    chunks = [
+        {
+            "text": "OpenAI works with Microsoft.",
+            "page": 1,
+            "chunk_index": 0,
+        },
+        {
+            "text": "OpenAI and Microsoft use Azure.",
+            "page": 2,
+            "chunk_index": 1,
+        },
+    ]
+
+    graph = graph_builder.build_graph(chunks)
+
+    openai_id = "ORG:openai"
+    microsoft_id = "ORG:microsoft"
+    azure_id = "PRODUCT:azure"
+    assert graph.nodes[openai_id]["name"] == "OpenAI"
+    assert graph.nodes[openai_id]["pages"] == [1, 2]
+    assert graph[openai_id][microsoft_id]["weight"] == 2
+    assert graph[openai_id][microsoft_id]["pages"] == [1, 2]
+    assert graph.has_edge(microsoft_id, azure_id)
+
+
+def test_save_load_and_delete_graph_roundtrip(tmp_path, monkeypatch):
+    monkeypatch.setattr(graph_builder.settings, "GRAPH_PERSIST_DIR", str(tmp_path))
+    graph = graph_builder.build_graph([])
+    graph.add_node("ORG:openai", name="OpenAI", label="ORG", mentions=1, pages=[1], chunks=[0])
+
+    path = graph_builder.save_graph(graph, user_id="user-1", document_id="doc-1")
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    loaded = graph_builder.load_graph(user_id="user-1", document_id="doc-1")
+
+    assert payload["metadata"]["document_id"] == "doc-1"
+    assert loaded.nodes["ORG:openai"]["name"] == "OpenAI"
+
+    graph_builder.delete_graph(user_id="user-1", document_id="doc-1")
+    assert not path.exists()
+
+
+def test_empty_chunks_produce_empty_graph(monkeypatch):
+    monkeypatch.setattr(graph_builder, "_nlp", FakeNlp())
+
+    graph = graph_builder.build_graph([])
+
+    assert graph.number_of_nodes() == 0
+    assert graph.number_of_edges() == 0

backend/tests/test_graph_retriever.py

@@ -0,0 +1,97 @@
+from app.rag import graph_builder, graph_retriever
+
+
+class FakeEntity:
+    def __init__(self, text, label):
+        self.text = text
+        self.label_ = label
+
+
+class FakeDoc:
+    def __init__(self, entities):
+        self.ents = entities
+
+
+class FakeNlp:
+    def __call__(self, text):
+        entities = []
+        for value, label in (
+            ("OpenAI", "ORG"),
+            ("Microsoft", "ORG"),
+            ("Azure", "PRODUCT"),
+        ):
+            if value in text:
+                entities.append(FakeEntity(value, label))
+        return FakeDoc(entities)
+
+
+def _save_sample_graph(tmp_path, monkeypatch, user_id="user-1", document_id="doc-1"):
+    monkeypatch.setattr(graph_builder.settings, "GRAPH_PERSIST_DIR", str(tmp_path))
+    monkeypatch.setattr(graph_builder, "_nlp", FakeNlp())
+    graph = graph_builder.build_graph(
+        [
+            {
+                "text": "OpenAI works with Microsoft.",
+                "page": 1,
+                "chunk_index": 0,
+            },
+            {
+                "text": "Microsoft deploys Azure.",
+                "page": 2,
+                "chunk_index": 1,
+            },
+        ]
+    )
+    graph_builder.save_graph(graph, user_id=user_id, document_id=document_id)
+
+
+def test_get_entity_context_returns_one_hop_relationships(tmp_path, monkeypatch):
+    _save_sample_graph(tmp_path, monkeypatch)
+
+    context = graph_retriever.get_entity_context(
+        query="How is OpenAI related to Microsoft?",
+        user_id="user-1",
+        document_id="doc-1",
+    )
+
+    assert "## Knowledge Graph Context" in context
+    assert "OpenAI" in context
+    assert "Microsoft" in context
+    assert "page 1" in context
+
+
+def test_get_entity_context_returns_empty_for_no_match(tmp_path, monkeypatch):
+    _save_sample_graph(tmp_path, monkeypatch)
+
+    context = graph_retriever.get_entity_context(
+        query="What about Google?",
+        user_id="user-1",
+        document_id="doc-1",
+    )
+
+    assert context == ""
+
+
+def test_get_entity_context_returns_empty_for_missing_graph(tmp_path, monkeypatch):
+    monkeypatch.setattr(graph_builder.settings, "GRAPH_PERSIST_DIR", str(tmp_path))
+    monkeypatch.setattr(graph_builder, "_nlp", FakeNlp())
+
+    context = graph_retriever.get_entity_context(
+        query="OpenAI",
+        user_id="user-1",
+        document_id="missing",
+    )
+
+    assert context == ""
+
+
+def test_get_entity_context_isolates_users(tmp_path, monkeypatch):
+    _save_sample_graph(tmp_path, monkeypatch, user_id="user-1", document_id="doc-1")
+
+    context = graph_retriever.get_entity_context(
+        query="OpenAI",
+        user_id="user-2",
+        document_id="doc-1",
+    )
+
+    assert context == ""

backend/tests/test_graphrag_agent.py

@@ -0,0 +1,92 @@
+from app.rag import agent
+
+
+class FakeMessage:
+    content = "Graph answer"
+
+
+class FakeChoice:
+    message = FakeMessage()
+
+
+class FakeResponse:
+    choices = [FakeChoice()]
+
+
+class FakeClient:
+    def __init__(self):
+        self.messages = None
+
+    def chat_completion(self, messages, **kwargs):
+        self.messages = messages
+        return FakeResponse()
+
+
+def test_generate_answer_appends_graph_context_without_changing_sources(monkeypatch):
+    client = FakeClient()
+    chunks = [
+        {
+            "text": "Vector context",
+            "filename": "doc.pdf",
+            "page": 1,
+            "score": 0.9,
+            "confidence": 100.0,
+        }
+    ]
+
+    monkeypatch.setattr(agent, "get_llm_client", lambda: client)
+    monkeypatch.setattr(agent, "retrieve", lambda **kwargs: chunks)
+    monkeypatch.setattr(
+        agent,
+        "get_entity_context",
+        lambda **kwargs: "## Knowledge Graph Context\n- OpenAI is related to Microsoft on page 1.",
+    )
+
+    result = agent.generate_answer("How are OpenAI and Microsoft related?", "user-1", "doc-1")
+
+    prompt = client.messages[1]["content"]
+    assert "Vector context" in prompt
+    assert "Knowledge Graph Context" in prompt
+    assert result["sources"] == [
+        {
+            "text": "Vector context",
+            "filename": "doc.pdf",
+            "page": 1,
+            "score": 0.9,
+            "confidence": 100.0,
+        }
+    ]
+
+
+def test_generate_answer_stream_appends_graph_context(monkeypatch):
+    captured = {}
+
+    class StreamingClient:
+        def chat_completion(self, messages, **kwargs):
+            captured["messages"] = messages
+            return iter([])
+
+    monkeypatch.setattr(agent, "get_llm_client", lambda: StreamingClient())
+    monkeypatch.setattr(
+        agent,
+        "retrieve",
+        lambda **kwargs: [
+            {
+                "text": "Vector stream context",
+                "filename": "doc.pdf",
+                "page": 1,
+                "score": 0.9,
+                "confidence": 100.0,
+            }
+        ],
+    )
+    monkeypatch.setattr(
+        agent,
+        "get_entity_context",
+        lambda **kwargs: "## Knowledge Graph Context\n- OpenAI is related to Microsoft on page 1.",
+    )
+
+    events = list(agent.generate_answer_stream("OpenAI Microsoft", "user-1", "doc-1"))
+
+    assert events[0].startswith("data:")
+    assert "Knowledge Graph Context" in captured["messages"][1]["content"]

frontend/e2e/snapshots.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test, type Page } from "@playwright/test";
+
+const user = {
+  id: "user-1",
+  username: "tester",
+  email: "tester@example.com",
+  is_admin: false,
+  created_at: "2026-05-28T00:00:00Z",
+};
+
+const uploadedDocument = {
+  id: "doc-1",
+  original_name: "notes.txt",
+  file_size: 11,
+  page_count: 1,
+  chunk_count: 1,
+  status: "ready",
+  error_message: null,
+  uploaded_at: "2026-05-28T00:00:00Z",
+};
+
+async function mockDashboardApis(page: Page, documents: typeof uploadedDocument[] = []) {
+  await page.route("**/api/v1/auth/me", async (route) => {
+    await route.fulfill({ json: user });
+  });
+
+  await page.route("**/api/v1/documents/", async (route) => {
+    await route.fulfill({
+      json: {
+        items: documents,
+        total: documents.length,
+        page: 1,
+        pages: documents.length > 0 ? 1 : 0,
+      },
+    });
+  });
+}
+
+test.describe("Frontend Snapshot Tests", () => {
+  test("login page snapshot", async ({ page }) => {
+    await page.goto("/login");
+    await page.waitForSelector("#login-email");
+    
+    if (!process.env.CI) {
+      await expect(page).toHaveScreenshot("login-page.png", {
+        maxDiffPixelRatio: 0.1,
+        threshold: 0.2,
+      });
+    } else {
+      await expect(page.locator("#login-email")).toBeVisible();
+    }
+  });
+
+  test("register page snapshot", async ({ page }) => {
+    await page.goto("/register");
+    await page.waitForSelector("#reg-username");
+    
+    if (!process.env.CI) {
+      await expect(page).toHaveScreenshot("register-page.png", {
+        maxDiffPixelRatio: 0.1,
+        threshold: 0.2,
+      });
+    } else {
+      await expect(page.locator("#reg-username")).toBeVisible();
+    }
+  });
+
+  test("dashboard empty page snapshot", async ({ page }) => {
+    // Set mock token
+    await page.addInitScript(() => {
+      localStorage.setItem("token", "access-token");
+      localStorage.setItem("refresh_token", "refresh-token");
+    });
+
+    await mockDashboardApis(page, []);
+    await page.goto("/dashboard");
+    await page.waitForSelector("text=No documents yet");
+
+    if (!process.env.CI) {
+      await expect(page).toHaveScreenshot("dashboard-empty.png", {
+        maxDiffPixelRatio: 0.1,
+        threshold: 0.2,
+      });
+    } else {
+      await expect(page.locator("text=No documents yet")).toBeVisible();
+    }
+  });
+
+  test("dashboard with document page snapshot", async ({ page }) => {
+    // Set mock token
+    await page.addInitScript(() => {
+      localStorage.setItem("token", "access-token");
+      localStorage.setItem("refresh_token", "refresh-token");
+    });
+
+    await mockDashboardApis(page, [uploadedDocument]);
+    await page.goto("/dashboard");
+    await page.waitForSelector("text=notes.txt");
+
+    if (!process.env.CI) {
+      await expect(page).toHaveScreenshot("dashboard-with-doc.png", {
+        maxDiffPixelRatio: 0.1,
+        threshold: 0.2,
+      });
+    } else {
+      await expect(page.locator("text=notes.txt")).toBeVisible();
+    }
+  });
+});

frontend/src/app/dashboard/page.tsx

@@ -7,8 +7,8 @@ import { useAuth } from "@/lib/auth";
 import { api, CONNECTION_ERROR_BANNER_MESSAGE, CONNECTION_ERROR_MESSAGE } from "@/lib/api";
 import Header from "@/components/layout/Header";
 import DocumentSidebar from "@/components/document/DocumentSidebar";
+import ChatSessionSidebar from "@/components/chat/ChatSessionSidebar";
 import ChatPanel from "@/components/chat/ChatPanel";
-
 function PDFViewerSkeleton() {
   return (
     <div
@@ -164,6 +164,9 @@ export default function DashboardPage() {
           </div>
         )}
 
+        {/* ── Left-Center: Chat Sessions Sidebar ──── */}
+        <ChatSessionSidebar />
+
         {/* ── Center: Chat Panel ──────────────────────────────────── */}
         <div className="flex-1 min-w-0 flex flex-col">
           <ChatPanel

frontend/src/components/auth/HuggingFaceTokenModal.tsx

@@ -0,0 +1,231 @@
+"use client";
+
+import { useState, useRef, useEffect, isValidElement, type ReactNode } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { useAuthStore } from "@/store/auth-store";
+import { Eye, EyeOff, AlertCircle, CheckCircle2, Loader2, ExternalLink, Key } from "lucide-react";
+
+interface HuggingFaceTokenModalProps {
+  /** Optional — if provided, allows a button-triggered dialog pattern */
+  children?: ReactNode;
+}
+
+export default function HuggingFaceTokenModal({ children }: HuggingFaceTokenModalProps) {
+  const user = useAuthStore((state) => state.user);
+  const setHfToken = useAuthStore((state) => state.setHfToken);
+
+  const existingToken = user?.hf_token ?? "";
+  const hasExistingToken = existingToken.length > 0;
+
+  const [open, setOpen] = useState(false);
+  const [inputToken, setInputToken] = useState(existingToken);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [success, setSuccess] = useState(false);
+  const [showToken, setShowToken] = useState(false);
+
+  const mountedRef = useRef(true);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Cleanup auto-close timeout and unmount guard on unmount
+  useEffect(() => {
+    return () => {
+      mountedRef.current = false;
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  const clearAutoCloseTimeout = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  };
+
+  const handleOpenChange = (newOpen: boolean) => {
+    clearAutoCloseTimeout();
+    setOpen(newOpen);
+    if (newOpen) {
+      // Reset to current store value when opening (picks up changes from background saves)
+      const currentToken = useAuthStore.getState().user?.hf_token ?? "";
+      setInputToken(currentToken);
+      setSaving(false);
+      setError(null);
+      setSuccess(false);
+      setShowToken(false);
+    }
+  };
+
+  const handleSave = async () => {
+    if (saving) return;
+    const token = inputToken.trim();
+    if (!token) {
+      setError("Please enter a valid token");
+      return;
+    }
+
+    setSaving(true);
+    setError(null);
+    setSuccess(false);
+
+    try {
+      await setHfToken(token);
+      if (!mountedRef.current) return;
+      setSaving(false);
+      setSuccess(true);
+      // Auto-close after 1.5s
+      timeoutRef.current = setTimeout(() => setOpen(false), 1500);
+    } catch (err) {
+      if (!mountedRef.current) return;
+      setSaving(false);
+      setError(err instanceof Error ? err.message : "Failed to save token");
+    }
+  };
+
+  const isSaveDisabled = inputToken.trim() === "" || saving;
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      {children ? (
+        <DialogTrigger render={isValidElement(children) ? children : <span>{children}</span>} />
+      ) : (
+        <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>HuggingFace Token</span>
+            </button>
+          }
+        />
+      )}
+      <DialogContent className="max-w-md sm:rounded-2xl border-border/40 p-6 md:p-8 bg-background/95 backdrop-blur-xl shadow-2xl" showCloseButton={false}>
+        <DialogHeader className="gap-1">
+          <DialogTitle className="text-2xl font-bold tracking-tight">
+            🤗 HuggingFace Token
+          </DialogTitle>
+          <DialogDescription className="text-sm text-muted-foreground mt-1.5">
+            Enter your HuggingFace API token to enable inference endpoints and model access.
+          </DialogDescription>
+        </DialogHeader>
+
+        <form onSubmit={(e) => { e.preventDefault(); if (!isSaveDisabled) handleSave(); }}>
+        <div className="space-y-4 mt-6">
+          {/* Token label with configured indicator */}
+          <div className="flex items-center gap-2">
+            <label htmlFor="hf-token-input" className="text-sm font-medium text-foreground/80">
+              Token
+            </label>
+            {hasExistingToken && (
+              <span className="inline-flex items-center gap-1 text-xs text-primary">
+                <CheckCircle2 className="w-3 h-3" />
+                Token configured
+              </span>
+            )}
+          </div>
+
+          {/* Input wrapper with visibility toggle */}
+          <div className="relative">
+            <Input
+              id="hf-token-input"
+              type={showToken ? "text" : "password"}
+              value={inputToken}
+              onChange={(e) => {
+                setInputToken(e.target.value);
+                if (error) setError(null);
+                if (success) setSuccess(false);
+              }}
+              placeholder="hf_..."
+              className="pr-10 font-mono"
+              disabled={saving}
+              autoFocus
+              aria-label="HuggingFace API Token"
+            />
+            <Button
+              variant="ghost"
+              size="icon-xs"
+              className="absolute right-2 top-1/2 -translate-y-1/2"
+              onClick={() => setShowToken(!showToken)}
+              type="button"
+              aria-label={showToken ? "Hide token" : "Show token"}
+              disabled={saving}
+            >
+              {showToken ? <EyeOff className="w-4 h-4" /> : <Eye className="w-4 h-4" />}
+            </Button>
+          </div>
+
+          {/* External link */}
+          <a
+            href="https://huggingface.co/settings/tokens"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-xs text-muted-foreground hover:text-primary underline-offset-2 transition-colors inline-flex items-center gap-1"
+          >
+            <ExternalLink className="w-3 h-3" />
+            Get your API token from HuggingFace Settings
+          </a>
+        </div>
+
+        {/* Error banner */}
+        {error && (
+          <div
+            className="p-4 border border-destructive/30 bg-destructive/5 rounded-xl text-sm text-destructive flex items-start gap-2 mt-4 animate-in fade-in slide-in-from-top-2 duration-200"
+            role="alert"
+            aria-live="polite"
+          >
+            <AlertCircle className="w-4 h-4 mt-0.5 shrink-0" />
+            <span>{error}</span>
+          </div>
+        )}
+
+        {/* Success banner */}
+        {success && (
+          <div
+            className="p-4 border border-primary/20 bg-primary/5 rounded-xl text-sm text-primary flex items-start gap-2 mt-4 animate-in fade-in slide-in-from-top-2 duration-200"
+            aria-live="polite"
+          >
+            <CheckCircle2 className="w-4 h-4 mt-0.5 shrink-0" />
+            <span>Token saved successfully</span>
+          </div>
+        )}
+        </form>
+
+        {/* Footer */}
+        <DialogFooter className="mt-4">
+          <Button variant="outline" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button
+            onClick={handleSave}
+            disabled={isSaveDisabled}
+            aria-busy={saving}
+            title={hasExistingToken ? "Replace existing token with a new one" : undefined}
+          >
+            {saving ? (
+              <>
+                <Loader2 className="w-4 h-4 animate-spin mr-1.5" />
+                Saving...
+              </>
+            ) : hasExistingToken ? (
+              "Update Token"
+            ) : (
+              "Save Token"
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend/src/components/chat/ChatPanel.tsx

@@ -22,11 +22,13 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
   const input = useChatStore((state) => state.input);
   const streaming = useChatStore((state) => state.streaming);
   const isTyping = useChatStore((state) => state.isTyping);
+  const activeSessionId = useChatStore((state) => state.activeSessionId);
   const setMessages = useChatStore((state) => state.setMessages);
   const setInput = useChatStore((state) => state.setInput);
   const setStreaming = useChatStore((state) => state.setStreaming);
   const setIsTyping = useChatStore((state) => state.setIsTyping);
   const resetChat = useChatStore((state) => state.resetChat);
+  const fetchSessionHistory = useChatStore((state) => state.fetchSessionHistory);
   const [showExportMenu, setShowExportMenu] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const bottomRef = useRef<HTMLDivElement>(null);
@@ -61,8 +63,13 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
     };
   }, [resetChat]);
 
-  // Load history on doc change
+  // Load history on activeSessionId or fallback to activeDoc change
   useEffect(() => {
+    if (activeSessionId) {
+      fetchSessionHistory(activeSessionId);
+      return;
+    }
+
     if (!activeDoc) {
       prevDocId.current = null;
       setMessages([]);
@@ -100,7 +107,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
     return () => {
       cancelled = true;
     };
-  }, [activeDoc, resetChat, setMessages]);
+  }, [activeSessionId, activeDoc, fetchSessionHistory, setMessages]);
 
   const handleSend = async () => {
     if (!input.trim() || streaming) return;
@@ -128,6 +135,7 @@ export default function ChatPanel({ activeDoc, onCitationClick }: Props) {
       const stream = api.streamPost("/api/v1/chat/ask/stream", {
         question,
         document_id: activeDoc?.id || null,
+        session_id: activeSessionId,
       });
 
       for await (const event of stream) {

frontend/src/components/chat/ChatSessionSidebar.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { Plus, Edit2, Trash2, MessageSquare, ChevronLeft } from "lucide-react";
+import { useChatStore, type ChatSession } from "@/store/chat-store";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+
+export default function ChatSessionSidebar() {
+  const sessions = useChatStore((state) => state.sessions);
+  const activeSessionId = useChatStore((state) => state.activeSessionId);
+  const fetchSessions = useChatStore((state) => state.fetchSessions);
+  const createSession = useChatStore((state) => state.createSession);
+  const renameSession = useChatStore((state) => state.renameSession);
+  const deleteSession = useChatStore((state) => state.deleteSession);
+  const setActiveSessionId = useChatStore((state) => state.setActiveSessionId);
+  const fetchSessionHistory = useChatStore((state) => state.fetchSessionHistory);
+
+  const [isOpen, setIsOpen] = useState(true);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editTitle, setEditTitle] = useState("");
+  const [creating, setCreating] = useState(false);
+
+  // Load sessions on mount
+  useEffect(() => {
+    fetchSessions();
+  }, [fetchSessions]);
+
+  const handleCreate = async () => {
+    if (creating) return;
+    setCreating(true);
+    try {
+      const defaultTitle = `Chat ${sessions.length + 1}`;
+      const newId = await createSession(defaultTitle);
+      setEditingId(newId);
+      setEditTitle(defaultTitle);
+    } catch (err) {
+      console.error(err);
+    } finally {
+      setCreating(false);
+    }
+  };
+
+  const handleStartRename = (session: ChatSession, e: React.MouseEvent) => {
+    e.stopPropagation();
+    setEditingId(session.id);
+    setEditTitle(session.title);
+  };
+
+  const handleSaveRename = async (id: string, e?: React.FormEvent) => {
+    if (e) e.preventDefault();
+    if (!editTitle.trim()) {
+      setEditingId(null);
+      return;
+    }
+    try {
+      await renameSession(id, editTitle.trim());
+    } catch (err) {
+      console.error(err);
+    } finally {
+      setEditingId(null);
+    }
+  };
+
+  const handleDelete = async (id: string, e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (confirm("Are you sure you want to delete this chat session?")) {
+      try {
+        await deleteSession(id);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  };
+
+  const handleSelectSession = async (id: string) => {
+    setActiveSessionId(id);
+    await fetchSessionHistory(id);
+  };
+
+  return (
+    <div className={cn("relative flex h-full border-r border-border/50 bg-card/20 select-none transition-all duration-300", isOpen ? "w-64" : "w-0")}>
+      <div className={cn("flex flex-col h-full w-full overflow-hidden transition-opacity duration-200", isOpen ? "opacity-100" : "opacity-0 pointer-events-none")}>
+        {/* Sidebar Header */}
+        <div className="flex items-center justify-between p-3 border-b border-border/50 shrink-0 bg-card/45">
+          <span className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">Chat Sessions</span>
+          <Button
+            onClick={handleCreate}
+            variant="outline"
+            size="icon"
+            className="h-7 w-7 bg-background/50 hover:bg-accent hover:text-accent-foreground"
+            disabled={creating}
+          >
+            <Plus className="w-4 h-4" />
+          </Button>
+        </div>
+
+        {/* Sessions List */}
+        <div className="flex-1 overflow-y-auto p-2 space-y-1 scrollbar-thin">
+          {sessions.length === 0 ? (
+            <div className="text-center py-8 px-4">
+              <p className="text-xs text-muted-foreground">No chat sessions. Click &quot;+&quot; to start a new chat.</p>
+            </div>
+          ) : (
+            sessions.map((session) => {
+              const isActive = session.id === activeSessionId;
+              const isEditing = session.id === editingId;
+
+              return (
+                <div
+                  key={session.id}
+                  onClick={() => !isEditing && handleSelectSession(session.id)}
+                  className={cn(
+                    "group flex items-center justify-between rounded-lg px-3 py-2 text-sm transition-all duration-200 cursor-pointer border",
+                    isActive
+                      ? "bg-accent/80 border-accent text-accent-foreground shadow-sm"
+                      : "border-transparent hover:bg-card/60 hover:text-foreground text-muted-foreground"
+                  )}
+                >
+                  <div className="flex items-center gap-2 min-w-0 flex-1">
+                    <MessageSquare className={cn("w-4 h-4 shrink-0", isActive ? "text-primary" : "text-muted-foreground")} />
+                    
+                    {isEditing ? (
+                      <form
+                        onSubmit={(e) => handleSaveRename(session.id, e)}
+                        className="flex items-center gap-1 w-full"
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        <Input
+                          value={editTitle}
+                          onChange={(e) => setEditTitle(e.target.value)}
+                          className="h-6 text-xs px-1 py-0 bg-background/50 border-input w-full"
+                          autoFocus
+                          onBlur={() => handleSaveRename(session.id)}
+                        />
+                      </form>
+                    ) : (
+                      <span className="truncate text-xs font-medium">{session.title}</span>
+                    )}
+                  </div>
+
+                  {!isEditing && (
+                    <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity duration-150 shrink-0 ml-1">
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="h-5 w-5 rounded-md hover:bg-background/80"
+                        onClick={(e) => handleStartRename(session, e)}
+                      >
+                        <Edit2 className="w-3 h-3" />
+                      </Button>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="h-5 w-5 rounded-md hover:bg-destructive/10 hover:text-destructive"
+                        onClick={(e) => handleDelete(session.id, e)}
+                      >
+                        <Trash2 className="w-3 h-3" />
+                      </Button>
+                    </div>
+                  )}
+                </div>
+              );
+            })
+          )}
+        </div>
+      </div>
+
+      {/* Collapse Toggle Button */}
+      <Button
+        onClick={() => setIsOpen(!isOpen)}
+        variant="ghost"
+        size="icon"
+        className={cn(
+          "absolute -right-3 top-1/2 -translate-y-1/2 z-40 h-6 w-6 rounded-full border border-border bg-background shadow-md hover:bg-accent hover:text-accent-foreground",
+          !isOpen && "right-auto -left-3 rotate-180"
+        )}
+      >
+        <ChevronLeft className="w-3.5 h-3.5" />
+      </Button>
+    </div>
+  );
+}

frontend/src/components/chat/SourceCard.tsx

@@ -13,6 +13,77 @@ import { ChevronDown, ChevronUp, FileText, Eye, TextQuote } from "lucide-react";
 
 const EXCERPT_THRESHOLD = 200;
 
+type ConfidenceLevel = "High" | "Medium" | "Low" | "Unknown";
+
+interface ConfidenceBadgeMeta {
+  label: ConfidenceLevel;
+  className: string;
+}
+
+const normalizeMetricValue = (value?: number) => {
+  if (typeof value !== "number" || Number.isNaN(value)) return undefined;
+  return value > 1 ? value / 100 : value;
+};
+
+const formatMetricValue = (value?: number) => {
+  const normalizedValue = normalizeMetricValue(value);
+  if (normalizedValue === undefined) return "N/A";
+  return `${Math.round(normalizedValue * 100)}%`;
+};
+
+const getConfidenceBadgeMeta = (value?: number): ConfidenceBadgeMeta => {
+  const normalizedValue = normalizeMetricValue(value);
+
+  if (normalizedValue === undefined) {
+    return {
+      label: "Unknown",
+      className: "border-muted bg-muted/40 text-muted-foreground",
+    };
+  }
+
+  if (normalizedValue >= 0.8) {
+    return {
+      label: "High",
+      className: "border-emerald-500/30 bg-emerald-500/10 text-emerald-600",
+    };
+  }
+
+  if (normalizedValue >= 0.5) {
+    return {
+      label: "Medium",
+      className: "border-amber-500/30 bg-amber-500/10 text-amber-600",
+    };
+  }
+
+  return {
+    label: "Low",
+    className: "border-red-500/30 bg-red-500/10 text-red-600",
+  };
+};
+
+const getPrimarySourceMetric = (source: SourceChunk) =>
+  source.confidence ?? source.score;
+
+const MetricBadge = ({
+  label,
+  value,
+}: {
+  label: "Score" | "Confidence";
+  value?: number;
+}) => {
+  const badgeMeta = getConfidenceBadgeMeta(value);
+
+  return (
+    <Badge
+      variant="outline"
+      className={`h-5 px-1.5 text-[9px] font-medium ${badgeMeta.className}`}
+      title={`${label}: ${formatMetricValue(value)}`}
+    >
+      {label}: {badgeMeta.label}
+    </Badge>
+  );
+};
+
 interface Props {
   sources: SourceChunk[];
   onPageClick: (page: number) => void;
@@ -36,34 +107,37 @@ export default function SourceCard({ sources = [], onPageClick }: Props) {
 
   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>
-
-        {/* ── Collapsed: Mini badges with hover preview ── */}
-        {!expanded && (
-          <div className="px-3 pb-2 flex flex-wrap gap-1">
-            {sources.map((src, i) => (
+      <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>
+
+      {!expanded && (
+        <div className="px-3 pb-2 flex flex-wrap gap-1">
+          {sources.map((src, i) => {
+            const badgeMeta = getConfidenceBadgeMeta(
+              getPrimarySourceMetric(src)
+            );
+
+            return (
               <Tooltip key={i}>
                 <TooltipTrigger className="inline-flex">
                   <Badge
-                    variant="secondary"
-                    className="text-[10px] h-5 cursor-pointer hover:bg-primary/20 transition-colors"
+                    variant="outline"
+                    className={`text-[10px] h-5 cursor-pointer hover:bg-primary/20 transition-colors ${badgeMeta.className}`}
                     onClick={() => onPageClick(src.page + 1)}
                   >
-                    p.{src.page + 1} • {src.confidence}%
+                    p.{src.page + 1} - {badgeMeta.label}
                   </Badge>
                 </TooltipTrigger>
                 <TooltipContent
@@ -71,74 +145,68 @@ export default function SourceCard({ sources = [], onPageClick }: Props) {
                   align="center"
                   className="max-w-xs p-2"
                 >
+                  <div className="mb-1 flex flex-wrap gap-1">
+                    <MetricBadge label="Score" value={src.score} />
+                    <MetricBadge label="Confidence" value={src.confidence} />
+                  </div>
                   <p className="text-[11px] leading-relaxed line-clamp-6">
                     {src.text}
                   </p>
                 </TooltipContent>
               </Tooltip>
-            ))}
-          </div>
-        )}
+            );
+          })}
+        </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>
+      {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 gap-2 mb-1.5">
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <span className="truncate text-[10px] font-medium text-muted-foreground">
+                    {src.filename}
+                  </span>
+                  <Badge variant="outline" className="h-5 px-1.5 text-[9px]">
+                    Page {src.page + 1}
+                  </Badge>
+                  <MetricBadge label="Score" value={src.score} />
+                  <MetricBadge label="Confidence" value={src.confidence} />
                 </div>
-                <p
-                  className={`text-[11px] text-muted-foreground leading-relaxed ${
-                    excerptOpen.has(i) ? "" : "line-clamp-3"
-                  }`}
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="h-6 shrink-0 px-2 text-[10px]"
+                  onClick={() => onPageClick(src.page + 1)}
                 >
-                  {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>
-                )}
+                  <Eye className="w-3 h-3 mr-1" />
+                  View
+                </Button>
               </div>
-            ))}
-          </div>
-        )}
+              <p
+                className={`text-[11px] text-muted-foreground leading-relaxed ${
+                  excerptOpen.has(i) ? "" : "line-clamp-3"
+                }`}
+              >
+                {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>
+          ))}
+        </div>
+      )}
     </div>
   );
 }

frontend/src/components/layout/ContributorsPanel.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState, useEffect } from "react";
+import Image from "next/image";
 import { GitBranch, Star, GitPullRequest, Users, X, Trophy, ExternalLink } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { api } from "@/lib/api";
@@ -124,7 +125,7 @@ export default function ContributorsPanel({ onClose }: { onClose: () => void })
                         {medals[i]}
                       </span>
                     )}
-                    <img
+                    <Image
                       src={c.avatar_url}
                       alt={c.login}
                       width={56}

frontend/src/components/layout/Header.tsx

@@ -27,6 +27,7 @@ import {
   X,
 } from "lucide-react";
 import { useTheme } from "next-themes";
+
 import { useSyncExternalStore } from "react";
 
 interface HeaderProps {

frontend/src/store/chat-store.ts

@@ -1,13 +1,14 @@
 "use client";
 
 import { create } from "zustand";
+import { api } from "@/lib/api";
 
 export interface SourceChunk {
   text: string;
   filename: string;
   page: number;
-  score: number;
-  confidence: number;
+  score?: number;
+  confidence?: number;
 }
 
 export interface ChatMsg {
@@ -18,6 +19,12 @@ export interface ChatMsg {
   isStreaming?: boolean;
 }
 
+export interface ChatSession {
+  id: string;
+  title: string;
+  created_at: string;
+}
+
 type Setter<T> = T | ((prev: T) => T);
 
 interface ChatStore {
@@ -25,21 +32,32 @@ interface ChatStore {
   input: string;
   streaming: boolean;
   isTyping: boolean;
+  sessions: ChatSession[];
+  activeSessionId: string | null;
   setMessages: (value: Setter<ChatMsg[]>) => void;
   setInput: (value: Setter<string>) => void;
   setStreaming: (value: Setter<boolean>) => void;
   setIsTyping: (value: Setter<boolean>) => void;
+  setSessions: (value: Setter<ChatSession[]>) => void;
+  setActiveSessionId: (value: Setter<string | null>) => void;
+  fetchSessions: () => Promise<void>;
+  createSession: (title: string) => Promise<string>;
+  renameSession: (id: string, title: string) => Promise<void>;
+  deleteSession: (id: string) => Promise<void>;
+  fetchSessionHistory: (id: string) => Promise<void>;
   resetChat: () => void;
 }
 
 const resolveValue = <T,>(value: Setter<T>, current: T): T =>
   typeof value === "function" ? (value as (prev: T) => T)(current) : value;
 
-export const useChatStore = create<ChatStore>((set) => ({
+export const useChatStore = create<ChatStore>((set, get) => ({
   messages: [],
   input: "",
   streaming: false,
   isTyping: false,
+  sessions: [],
+  activeSessionId: null,
 
   setMessages(value) {
     set((state) => ({ messages: resolveValue(value, state.messages) }));
@@ -57,12 +75,97 @@ export const useChatStore = create<ChatStore>((set) => ({
     set((state) => ({ isTyping: resolveValue(value, state.isTyping) }));
   },
 
+  setSessions(value) {
+    set((state) => ({ sessions: resolveValue(value, state.sessions) }));
+  },
+
+  setActiveSessionId(value) {
+    set((state) => ({ activeSessionId: resolveValue(value, state.activeSessionId) }));
+  },
+
+  async fetchSessions() {
+    try {
+      const data = await api.get<ChatSession[]>("/api/v1/chat/sessions");
+      set({ sessions: data });
+      if (data.length > 0 && !get().activeSessionId) {
+        set({ activeSessionId: data[0].id });
+        await get().fetchSessionHistory(data[0].id);
+      }
+    } catch (err) {
+      console.error("Failed to fetch chat sessions:", err);
+    }
+  },
+
+  async createSession(title) {
+    try {
+      const session = await api.post<ChatSession>("/api/v1/chat/sessions", { title });
+      set((state) => ({
+        sessions: [session, ...state.sessions],
+        activeSessionId: session.id,
+        messages: [],
+      }));
+      return session.id;
+    } catch (err) {
+      console.error("Failed to create chat session:", err);
+      throw err;
+    }
+  },
+
+  async renameSession(id, title) {
+    try {
+      const updated = await api.put<ChatSession>(`/api/v1/chat/sessions/${id}`, { title });
+      set((state) => ({
+        sessions: state.sessions.map((s) => (s.id === id ? updated : s)),
+      }));
+    } catch (err) {
+      console.error("Failed to rename chat session:", err);
+      throw err;
+    }
+  },
+
+  async deleteSession(id) {
+    try {
+      await api.delete(`/api/v1/chat/sessions/${id}`);
+      set((state) => {
+        const nextSessions = state.sessions.filter((s) => s.id !== id);
+        let nextActiveId = state.activeSessionId;
+        if (state.activeSessionId === id) {
+          nextActiveId = nextSessions.length > 0 ? nextSessions[0].id : null;
+        }
+        return {
+          sessions: nextSessions,
+          activeSessionId: nextActiveId,
+        };
+      });
+      const activeId = get().activeSessionId;
+      if (activeId) {
+        await get().fetchSessionHistory(activeId);
+      } else {
+        set({ messages: [] });
+      }
+    } catch (err) {
+      console.error("Failed to delete chat session:", err);
+      throw err;
+    }
+  },
+
+  async fetchSessionHistory(id) {
+    try {
+      const data = await api.get<{ messages: ChatMsg[] }>(`/api/v1/chat/history/session/${id}`);
+      set({ messages: data.messages });
+    } catch (err) {
+      console.error("Failed to fetch session history:", err);
+    }
+  },
+
   resetChat() {
     set({
       messages: [],
       input: "",
       streaming: false,
       isTyping: false,
+      sessions: [],
+      activeSessionId: null,
     });
   },
 }));

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "PDF-Assistant-RAG",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

requirements.txt

@@ -1,6 +1,7 @@
 flask
 python-dotenv
 pymupdf
+pdfplumber
 flask-login
 pymongo
 werkzeug
@@ -12,4 +13,4 @@ requests-oauthlib
 google-genai
 cryptography
 gunicorn
-pinecone
+pinecone