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:

```python
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

```text
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
```

---