Merge pull request #111 from GLNPardhiv/docs/Add-docstrings-routes

backend/app/routes/auth.py

@@ -17,7 +17,28 @@ router = APIRouter(prefix="/auth", tags=["Authentication"])
 
 @router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
 def register(payload: UserRegister, db: Session = Depends(get_db)):
-    """Register a new user account."""
+    """
+    Register a new user account and return authentication tokens.
+
+    Creates a new user in the database after validating that the username and
+    email are not already taken. The password is hashed before storage. On
+    success, access and refresh tokens are generated and returned along with
+    the user's public information.
+
+    Args:
+        payload (UserRegister): The registration details including username, email, and password.
+        db (Session, optional): Database session dependency. Defaults to Depends(get_db).
+
+    Returns:
+        TokenResponse: An object containing:
+            - access_token (str): jwt access token for authenticating API requests.
+            - refresh_token (str): jwt refresh token for obtaining new access tokens.
+            - user : UserResponse object with registered user's public information (id, username, email).
+
+    Raises:
+        HTTPException: If the username is already taken (409 Conflict).
+        HTTPException: If the email is already registered (409 Conflict).
+    """
     # Check existing username
     if db.query(User).filter(User.username == payload.username).first():
         raise HTTPException(
@@ -55,7 +76,27 @@ def register(payload: UserRegister, db: Session = Depends(get_db)):
 
 @router.post("/login", response_model=TokenResponse)
 def login(payload: UserLogin, db: Session = Depends(get_db)):
-    """Login with email and password."""
+    """
+    Authenticate a user with email and password.
+
+    Verifies that the provided email exists in the database and that the
+    plain text password matches the stored hash. Upon successful authentication,
+    generates new access and refresh tokens for the user session.
+
+    Args:
+        payload (UserLogin): User login data containing email and password.
+        db (Session, optional): Database session dependency. Defaults to Depends(get_db).
+
+    Returns:
+        TokenResponse: An object containing:
+            - access_token: JWT access token for API authentication.
+            - refresh_token: JWT refresh token for obtaining new access tokens.
+            - user: UserResponse object with the authenticated user's details.
+    
+    Raises:
+        HTTPException: 401 Unauthorized if the email is not found or the
+            password does not match the stored hash.
+    """
     user = db.query(User).filter(User.email == payload.email).first()
 
     if not user or not verify_password(payload.password, user.hashed_password):
@@ -76,7 +117,28 @@ def login(payload: UserLogin, db: Session = Depends(get_db)):
 
 @router.post("/refresh", response_model=TokenResponse)
 def refresh_token(payload: RefreshRequest, db: Session = Depends(get_db)):
-    """Refresh access token."""
+    """
+    Refresh both access and refresh tokens using a valid refresh token.
+
+    Decodes the provided refresh token to extract the user ID. If the token
+    is valid and the user still exists in the database, a new pair of access
+    and refresh tokens is generated and returned.
+
+    Args:
+        payload (RefreshRequest): An object containing the refresh token to be used for generating new tokens
+        db (Session, optional): Database session dependency. Defaults to Depends(get_db).
+
+    Returns:
+        TokenResponse: A fresh set of credentials containing:
+            - access_token: New JWT access token.
+            - refresh_token: New JWT refresh token.
+            - user: UserResponse object with the user's public details.
+    
+    Raises:
+        HTTPException: 401 Unauthorized if:
+            - The refresh token is invalid or expired.
+            - The user associated with the token no longer exists.
+    """
     user_id = decode_token(payload.refresh_token, token_type="refresh")
     if not user_id:
         raise HTTPException(
@@ -103,15 +165,59 @@ def refresh_token(payload: RefreshRequest, db: Session = Depends(get_db)):
 
 @router.get("/me", response_model=UserResponse)
 def get_me(user: User = Depends(get_current_user)):
-    """Get current authenticated user profile."""
+    """Retrieve the profile of the currently authenticated user.
+
+    Returns the user object associated with the valid access token provided
+    in the request. This endpoint is useful for fetching the current user's
+    information after login or token refresh.
+
+    Args:
+        user: The currently authenticated user, obtained from the `get_current_user` dependency.
+
+    Returns:
+        UserResponse: The authenticated user's public profile data, including
+        id, username, email, and any other exposed fields.
+
+    Note:
+        This endpoint relies on the `get_current_user` dependency, which
+        will automatically return a 401 Unauthorized response if the access
+        token is missing, invalid, or expired. Therefore, this function
+        itself does not need to raise any HTTP exceptions.
+    """
     return UserResponse.model_validate(user)
 
 @router.put("/update")
 def update_user_info(payload:UserUpdate,
                     user: User = Depends(get_current_user),
                     db: Session = Depends(get_db))-> UserUpdateResponse:
+    """Update the current user's profile information.
+
+    Allows an authenticated user to change their username and/or email address.
+    At least one of `username` or `email` must be provided. If a new value
+    is supplied, it is checked for uniqueness against existing users. On
+    success, the updated user record is returned.
+
+    Args:
+        payload: UserUpdate object containing optional `username` and `email` fields to update.
+        user: The currently authenticated user, obtained from the `get_current_user` dependency.
+        db: SQLAlchemy database session, obtained from the dependency.
+
+    Returns:
+        UserUpdateResponse: The updated user profile data (same structure as
+        the database model, exposed through the response model).
 
-    """Update user info."""
+    Raises:
+        HTTPException: 400 if:
+            - Neither `username` nor `email` is provided.
+            - The new username is already taken.
+            - The new email is already registered (checks both fields).
+            - A database error occurs (e.g., integrity or connection issue).
+
+    Note:
+        The function commits changes to the database and refreshes the user
+        instance before returning. Any `SQLAlchemyError` triggers a rollback
+        and a 400 response.
+    """
     if payload.username is None and payload.email is None:
         raise HTTPException(status_code=400, detail="Username and email are required")
 
@@ -142,7 +248,32 @@ def update_user_info(payload:UserUpdate,
 def update_password(payload:UpdatePassword,
                     user: User = Depends(get_current_user),
                     db: Session = Depends(get_db))-> UpdatePasswordResponse:
-    """Update user password."""
+    """Update the authenticated user's password.
+
+    Validates that both the new password and confirmation are provided and
+    match each other. If valid, the password is hashed and stored. The user
+    record is then committed to the database.
+
+    Args:
+        payload: UpdatePassword object containing `password` and `confirm_password` fields.
+        user: The currently authenticated user, obtained from the `get_current_user` dependency.
+        db: SQLAlchemy database session, obtained from the dependency.
+
+    Returns:
+        UpdatePasswordResponse: The updated user object (typically containing 
+        user details excluding the password hash).
+
+    Raises:
+        HTTPException: 400 if:
+            - Either `password` or `confirm_password` is missing or empty.
+            - The two password fields do not match.
+            - A database error (SQLAlchemyError) occurs during commit.
+
+    Note:
+        The function hashes the password using `hash_password()` before
+        saving. Any `SQLAlchemyError` triggers a rollback and raises a 400
+        response.
+    """
     if not payload.password and not payload.confirm_password:
         raise HTTPException(status_code=400, detail="Password and confirm_password are required")
     if len(payload.password) == 0 and len(payload.confirm_password) == 0:

backend/app/routes/chat.py

@@ -26,7 +26,33 @@ def ask_question(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with RAG retrieval (non-streaming)."""
+    """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).
+    """
     # Validate document exists if specified
     if payload.document_id:
         doc = db.query(Document).filter(
@@ -67,7 +93,41 @@ def ask_question_stream(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Ask a question with SSE streaming response."""
+    """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.
+    """
     # Validate document
     if payload.document_id:
         doc = db.query(Document).filter(
@@ -135,7 +195,25 @@ def get_chat_history(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Get chat history for a specific document."""
+    """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.
+    """
     messages = (
         db.query(ChatMessage)
         .filter(
@@ -173,11 +251,32 @@ def export_chat_history(
     token: Optional[str] = None,
     db: Session = Depends(get_db),
 ):
-    """Export chat history for a document as a downloadable .md or .txt file.
-    
-    Accepts auth via either:
-    - Authorization: Bearer <token> header (standard)
-    - ?token=<jwt> query parameter (for browser downloads)
+    """Export the chat history for a document as a downloadable file.
+
+    Supports Markdown (.md) or plain text (.txt) 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) or "txt" (plain text). 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.
+            - `media_type`: `text/markdown` or `text/plain`.
+            - `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" or "txt".
+        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.
     """
     from fastapi import Request
     from app.auth import decode_token as _decode
@@ -245,7 +344,20 @@ def clear_chat_history(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Clear chat history for a specific document."""
+    """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.
+    """
     db.query(ChatMessage).filter(
         ChatMessage.user_id == user.id,
         ChatMessage.document_id == document_id,
@@ -263,7 +375,31 @@ def _save_message(
     content: str,
     sources: list = None,
 ):
-    """Helper: save a chat message to the database."""
+    """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()`.
+    """
     msg = ChatMessage(
         user_id=user_id,
         document_id=document_id,
@@ -276,7 +412,23 @@ def _save_message(
 
 
 def _format_markdown(doc, messages) -> str:
-    """Format chat history as a Markdown document."""
+    """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.
+    """
     lines = [
         f"# Chat History — {doc.original_name}",
         "",
@@ -324,7 +476,23 @@ def _format_markdown(doc, messages) -> str:
 
 
 def _format_plaintext(doc, messages) -> str:
-    """Format chat history as plain text."""
+    """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.
+    """
     lines = [
         f"Chat History — {doc.original_name}",
         f"Exported at: {__import__('datetime').datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",

backend/app/routes/documents.py

@@ -32,10 +32,28 @@ ALLOWED_MIME_TYPES = settings.ALLOWED_MIME_TYPES
 
 
 async def validate_upload(file: UploadFile):
-    """Validate an incoming UploadFile. Returns path to a temporary saved file.
+    """Validate an uploaded file and save it to a temporary file.
 
-    Checks extension, size (against settings.MAX_UPLOAD_SIZE_MB), MIME signature
-    using libmagic, and attempts to parse the file for deep validation.
+    Checks the file extension, size (against `settings.MAX_UPLOAD_SIZE_MB`),
+    MIME type via libmagic, and performs deep validation by attempting to
+    parse the file (PDF with pypdf, DOCX with python-docx). On success,
+    returns the path to a temporary saved file. 
+
+    Args:
+        file: The FastAPI UploadFile object to validate.
+
+    Returns:
+        str: Path to the temporary saved file that passed all validations.
+    
+    Raises:
+        HTTPException: With status code 400 if:
+            - No filename is provided.
+            - The file extension is not allowed. (only .pdf or .docx)
+            - The file size exceeds the maximum limit.
+            - The MIME type does not match allowed types for the extension.
+            - The file is corrupted or cannot be parsed. (invalid PDF/DOCX)
+        HTTPException: With status code 500 if:
+            - 'python-magic' dependency is missing on the server.
     """
     if not file.filename:
         raise HTTPException(status_code=400, detail="No filename provided")
@@ -97,8 +115,26 @@ async def validate_upload(file: UploadFile):
 
 def _ingest_document(document_id: str, filepath: str, original_name: str, user_id: str):
     """
-    Background task: chunk document, generate embeddings, store in ChromaDB.
-    Updates document status in the database.
+    Process a document in the background: chunk document, generate embeddings, and store in ChromaDB.
+
+    This function is intended to be run as a background task. 
+    It creates its own database session, updates the
+    document status, extracts text, splits into chunks, generates embeddings,
+    stores everything in ChromaDB, and marks the document as 'ready'. On
+    failure, it sets status to 'failed' and records the error message.
+
+    Args:
+        document_id: Unique identifier of the document in the database.
+        filepath: Absolute or relative path to the uploaded file on disk.
+        original_name: original filename provided by the user (for logging and metadata).
+        user_id: Identifier of the user who owns the document.
+    
+    Returns:
+        None
+
+    Note:
+        This function does not raise exceptions to the caller;
+        all errors are logged and the database record is updated accordingly. 
     """
     from app.database import SessionLocal
 
@@ -162,7 +198,31 @@ async def upload_document(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Upload a document for RAG processing."""
+    """
+    Upload a document for RAG processing.
+    
+    Validates the uploaded file (extension, size, MIME type, integrity),
+    saves it to the user's directory, creates a database record with status
+    'pending', and schedules a background task for chunking and embedding.
+
+    Args:
+        background_tasks: FastAPI BackgroundTasks instance to run the ingestion process asynchronously.
+        file: The uploaded file, provided as a multipart/form-data field in the request.
+        user: The currently authenticated user, injected by the `get_current_user` dependency.
+        db: Database session, injected by the `get_db` dependency.
+
+    Returns:
+        DocumentResponse: The created document record, validated against the
+        response model (includes id, filename, original_name, file_size, status, etc.).
+
+    Raises:
+        HTTPException: With status code 400 if:
+            - No filename is provided.
+            - The file extension is not allowed. (only .pdf or .docx)
+            - The file fails validation checks (size, MIME type, integrity).
+        HTTPException: With status code 500 if:
+            - The server lacks the 'python-magic' dependency. 
+    """
     # ── Validate file type ───────────────────────────
     if not file.filename:
         raise HTTPException(status_code=400, detail="No filename provided")
@@ -219,6 +279,26 @@ def list_documents(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
+    """
+    List all documents for the authenticated user with pagination.
+
+    Returns a paginated list of documents belonging to the current user,
+    ordered by upload date (newest first).
+
+    Args:
+        page: The page number to retrieve (1: indexed). Defaults to 1.
+        per_page: The number of documents to return per page. Defaults to 20.
+        user: The currently authenticated user, injected by the `get_current_user` dependency.
+        db: Database session, injected by the `get_db` dependency.
+        
+    Returns:
+        DocumentListResponse: A response model containing:
+            - items: A list of DocumentResponse objects for the current page.
+            - total: The total number of documents for the user.
+            - page: The current page number.
+            - pages: The total number of pages available.
+    """
+
     """Number of rows to skip"""
     skip: int = (page - 1) * per_page
 
@@ -254,7 +334,24 @@ def get_document(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Get a specific document's details."""
+    """
+    Retrieve a specific document by its ID for the authenticated user.
+
+    Fetches the document that matches both the provided `document_id` and
+    the current user's ID. If no such document exists, a 404 error is raised.
+
+    Args:
+        document_id: The unique identifier of the document to retrieve.
+        user: The currently authenticated user, injected by the `get_current_user` dependency.
+        db: Database session, injected by the `get_db` dependency.
+
+    Returns:
+        DocumentResponse: The document record that matches the criteria, validated against the response model
+        (includes id, filename, original_name, file_size, status, etc.).
+
+    Raises:
+        HTTPException: With status code 404 if the document is not found or does not belong to the authenticated user.
+    """
     doc = db.query(Document).filter(
         Document.id == document_id,
         Document.user_id == user.id,
@@ -272,7 +369,25 @@ def serve_pdf(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Serve the PDF file for the document viewer."""
+    """
+    Serve the PDF file for the document viewer.
+
+    Retrieves the document from the database to verify ownership, then
+    returns the actual PDF file from disk as a downloadable response.
+
+    Args:
+        document_id: The unique identifier of the document whose PDF is to be served.
+        user: The currently authenticated user, injected by the `get_current_user` dependency.
+        db: Database session, injected by the `get_db` dependency.
+
+    Returns:
+        FileResponse: A FastAPI FileResponse object that streams the PDF
+        file to the client with the correct media type and original filename.
+    
+    Raises:
+        HTTPException: 404 if the document does not exist or does not belong
+            to the authenticated user, or if the file is missing on disk.
+    """
     doc = db.query(Document).filter(
         Document.id == document_id,
         Document.user_id == user.id,
@@ -299,7 +414,30 @@ def delete_document(
     user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Delete a document and its vector embeddings."""
+    """
+    Delete a document and its associated vector embeddings.
+
+    Removes the document from the database, deletes the physical file from
+    disk, and attempts to delete all corresponding vector chunks from ChromaDB.
+    If ChromaDB deletion fails, the error is logged but does not block the
+    overall operation.
+
+    Args:
+        document_id: The unique identifier of the document to delete.
+        user: The currently authenticated user, injected by the `get_current_user` dependency.
+        db: Database session, injected by the `get_db` dependency.
+
+    Returns:
+        dict: A JSON response containing a success message confirming the deletion of the document.
+
+    Raises:
+        HTTPException: With status code 404 if the document is not found or does not belong to the authenticated user.
+
+    Note:
+        ChromaDB deletion errors are caught and logged only; they do not
+        raise an HTTP exception because the main document record is already
+        removed from the database.
+    """
     doc = db.query(Document).filter(
         Document.id == document_id,
         Document.user_id == user.id,