multi_llm_chatbot_backend/app/api/README.md

app/api – REST API Layer for Multi-LLM Chatbot

This module defines the complete FastAPI-based HTTP interface for all backend features, including chat, session management, RAG operations, provider switching, and document interaction.

Each file in this directory defines route groups (APIRouter) to modularize functionality.

---

API Directory Layout

File	Purpose
auth.py	Handles user authentication (login, signup, token validation)
chat.py	Core routes for LLM-backed chat, reply-to-advisor, and multi-turn flow
chat_sessions.py	Stores user conversations and provides access to saved history
debug.py	Developer tools: debug personas, RAG tests, ranking advisor responses
documents.py	Upload, parse, index, and query documents via RAG
provider.py	Switch between Gemini and Ollama providers
root.py	Root / endpoint for heartbeat and versioning
sessions.py	Tracks and resets session-specific in-memory context
utils.py	Helpers used by multiple routers (e.g. session ID management)

---

auth.py – User Authentication API

Endpoint	Method	Description
/signup	POST	Register a new user
/login	POST	Authenticate user and return access token
/me	GET	Return current logged-in user
/healthcheck	GET	Ping endpoint to check login status

Uses JWT-based Bearer token auth via FastAPI dependencies.

---

chat.py – Chat Interaction

Endpoint	Method	Description
/chat-stream	POST	Stream advisor responses as newline-delimited JSON
/reply-to-advisor	POST	Ask a question to a specific advisor/persona

These routes handle:

• Message routing via ImprovedChatOrchestrator
• Persona-wise response generation
• Embedding document-aware context
• Returning consistent message structure

---

chat_sessions.py – Persistent Storage of Conversations

Endpoint	Method	Description
/chat-sessions	GET	List all saved chat sessions
/chat-sessions/{id}	GET	Retrieve specific chat session
/chat-sessions/{id}	DELETE	Soft-delete a chat session
/chat-sessions/save	POST	Save in-memory session to MongoDB

Saves message history, metadata, and uploaded files.

---

debug.py – Developer Tools

Endpoint	Method	Description
/debug/personas	GET	List current personas, prompts, keywords
/debug/ranked-personas	GET	Return top advisors for current session
/debug/rag-status	GET	Run sample RAG query + return health info

Provides insight into:

• Persona prompt preview
• RAG test queries and indexed documents
• Session size + truncation status

---

documents.py – Document Upload and RAG

Endpoint	Method	Description
/upload-document	POST	Upload and parse a document for semantic search
/search-documents	POST	RAG search using text query and persona context
/document-stats	GET	Overview of documents uploaded to session
/uploaded-files	GET	Return list of uploaded file names
/document-insights/{filename}	GET	Get detailed metadata for a document
/export-chat	GET	Export current or stored chat session (PDF, TXT, DOCX)
/chat-summary	GET	Export summary generated by LLM (multi-format)

Supports file parsing (PDF, DOCX, TXT), chunking, embedding, and export.

---

provider.py – LLM Provider Control

Endpoint	Method	Description
/current-provider	GET	Return currently active provider and model
/switch-provider	POST	Dynamically switch between gemini and ollama
/current-model	GET	Get currently loaded model name
/switch-model	POST	Alias for switching based on model name

Changes are propagated by:

• Creating new LLM client
• Re-registering all personas

---

sessions.py – In-Memory Session Management

Endpoint	Method	Description
/context	GET	Return current session context (messages, documents, stats)
/reset-session	POST	Reset in-memory session or specific chat context
/session-stats	GET	Return stats like message count, file size, timestamps
/active-sessions	GET	Return list of all active in-memory sessions
/cleanup-sessions	POST	Manually trigger expired session cleanup

Supports ephemeral sessions and reusable chat contexts (e.g. for documents).

---

utils.py – Route-Level Utilities

Defines shared helper:

• get_or_create_session_for_request(request)
• get_or_create_session_for_request_async(request)

These parse session cookies or generate new session IDs, crucial for maintaining separation across:

• In-memory ephemeral sessions
• Document-linked long-term sessions

---

root.py – API Healthcheck

Endpoint	Method	Description
/	GET	Return version + feature list

Simple heartbeat endpoint used for readiness probes and sanity checks.

---

Auth Flow Integration

Most routes use:

Depends(get_current_active_user)

This ensures only logged-in users can:

• Upload and retrieve files
• Export summaries
• Save or delete chat sessions

JWT tokens are passed via the Authorization: Bearer ... header.

---

High-Level Flow

Frontend → /chat-stream → orchestrator → personas → RAG + LLM → response[]
        ↘ /upload-document → extractor → RAG chunks → indexed
        ↘ /context or /reset-session → session_manager
        ↘ /export-chat or /chat-summary → utils + formatter

---