melbinjp/DocQA

1---2title: DocQA3emoji: 📄4colorFrom: blue5colorTo: green6sdk: docker7app_file: app.py8pinned: false9---10 11# DocQA: A Stateless, Session-Based, Multilingual Q&A API12 13DocQA is a powerful, lightweight API for building advanced question-answering applications. It allows clients to create user sessions, manage collections of documents within those sessions, and perform powerful semantic searches across single or multiple documents.14 15## Architecture Overview16 17This project is a prototype-level application built with the following components:18*   **Backend:** A Python [FastAPI](https://fastapi.tiangolo.com/) server.19*   **Embeddings:** The `sentence-transformers` library is used to generate vector embeddings for document chunks.20*   **Vector Search:** [FAISS](https://faiss.ai/) from Meta AI provides efficient in-memory similarity search.21*   **LLM:** Google's [Gemini](https://deepmind.google/technologies/gemini/) family of models is used for generating answers based on retrieved context.22*   **Session Storage:** All user sessions and document data are stored **in-memory** and are not persisted. Sessions automatically expire after a period of inactivity. This makes the server stateless but not suitable for production use without modification.23 24## Core Features25- **User Sessions:** Create isolated sessions for each user, allowing them to work with a private collection of documents.26- **Multi-Document Q&A:** Ingest multiple documents into a single session and perform semantic searches across the entire collection.27- **Multilingual:** Thanks to a powerful cross-lingual embedding model, you can ingest documents and ask questions in many different languages.28- **Stateless with Timeouts:** The server is stateless and does not persist any data to disk. All sessions are held in memory and are automatically cleared after 15 minutes of inactivity.29 30## API Workflow and Frontend Guide31 32Building a client application follows this logical flow:33 341.  **Create a User Session:** The first step for any new user is to create a session.35    -   `POST /sessions` -> returns a `session_id`.36    -   The frontend should store this `session_id` for the duration of the user's visit.37 382.  **Ingest Documents:** The user can upload multiple documents into their session.39    -   `POST /sessions/{session_id}/ingest` with a file -> returns a `doc_id`.40    -   The frontend should keep a list of the documents the user has ingested, mapping the `doc_id` to its filename.41 423.  **Ask Questions:** The user can now ask questions.43    -   `POST /sessions/{session_id}/query` with a question and an optional list of `doc_ids`.44    -   If no `doc_ids` are provided, the search runs across all documents in the session.45    -   If `doc_ids` are provided, the search is limited to that subset.46 474.  **Manage Documents:** The user can remove documents they no longer need.48    -   `DELETE /sessions/{session_id}/documents/{doc_id}`49 50---51 52## API Reference53 54### `POST /sessions`55Creates a new, empty user session.56- **Response `200 OK`:**57  ```json58  {59    "session_id": "string"60  }61  ```62 63### `POST /sessions/{session_id}/ingest`64Ingests a new document into the specified user session.65- **Request:** `multipart/form-data` with a `file` or `application/json` with a `url`.66- **Response `200 OK`:**67  ```json68  {69    "doc_id": "string",70    "source": "string"71  }72  ```73 74### `POST /sessions/{session_id}/query`75Asks a question within the user session.76- **Request Body:**77  ```json78  {79    "q": "string",80    "doc_ids": ["string"], // Optional. If omitted, searches all docs in session.81    "stream": false // Optional. Set to true for a streaming response.82  }83  ```84- **Response (Standard): `200 OK`** (`application/json`)85  When `stream` is `false` or omitted, the response is a single JSON object:86  ```json87  {88    "answer": "string",89    "sources": [90      {91        "text": "string",92        "score": "float",93        "doc_id": "string",94        "source": "string"95      }96    ]97  }98  ```99- **Response (Streaming): `200 OK`** (`text/event-stream`)100  When `stream` is `true`, the response is a Server-Sent Events (SSE) stream. The client should listen for events on this stream. Each event is a JSON object.101    1.  **Sources Event:** The first event contains the source documents that will be used to generate the answer.102        ```103        data: {"type": "sources", "data": [{"text": "...", "score": ...}]}104        ```105    2.  **Token Events:** A series of events, each containing a piece of the generated answer.106        ```107        data: {"token": "The"}108        data: {"token": " answer"}109        data: {"token": " is..."}110        ```111    3.  **End Event:** The final event signals that the stream is complete.112        ```113        data: {"type": "end"}114        ```115 116### `DELETE /sessions/{session_id}/documents/{doc_id}`117Deletes a specific document from a user session.118- **Response `204 No Content`** on success.119- **Response `404 Not Found`** if the session or document does not exist.120 121### `GET /sessions/{session_id}/status`122Checks session status and remaining time before expiration.123- **Response `200 OK`:**124  ```json125  {126    "session_id": "string",127    "active": true,128    "remaining_minutes": 12.5,129    "last_accessed": "2024-01-01T12:00:00"130  }131  ```132- Returns `active: false` if session doesn't exist or has expired.133- `remaining_minutes` only present for active sessions.134 135### `POST /sessions/{session_id}/refresh`136Refreshes a session to extend its timeout period.137- **Response `200 OK`:**138  ```json139  {140    "session_id": "string",141    "refreshed_at": "2024-01-01T12:00:00",142    "remaining_minutes": 15.0143  }144  ```145- **Response `404 Not Found`** if the session does not exist.146 147### `GET /sessions/{session_id}/health`148Simple health check for session existence and activity.149- **Response `200 OK`:** `{"status": "active"}` if session is active.150- **Response `404 Not Found`** if session doesn't exist.151- **Response `410 Gone`** if session exists but has expired.152 153---154 155## Session Management for Frontend Applications156 157The API provides session management endpoints to help frontend applications handle session lifecycles, timeouts, and user experience.158 159### Basic Usage160```javascript161// Create and manage a session162const { session_id } = await fetch('/sessions', { method: 'POST' }).then(r => r.json());163 164// Check session status165const status = await fetch(`/sessions/${session_id}/status`).then(r => r.json());166if (status.active) {167    console.log(`${status.remaining_minutes} minutes remaining`);168}169 170// Refresh session to extend timeout171await fetch(`/sessions/${session_id}/refresh`, { method: 'POST' });172 173// Quick health check174const health = await fetch(`/sessions/${session_id}/health`);175if (health.ok) console.log('Session active');176```177 178### Recommended Patterns179- **Periodic checks:** Monitor session status every 5 minutes180- **Auto-refresh:** Extend session on user activity when < 5 minutes remain181- **Error handling:** Handle 404 (not found) and 410 (expired) responses appropriately182