Merge pull request #237 from Exodus2004/feat/chat-sessions

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/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/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()

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/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/store/chat-store.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { create } from "zustand";
+import { api } from "@/lib/api";
 
 export interface SourceChunk {
   text: string;
@@ -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,
     });
   },
 }));