v2 beta

certifi and chunker v2

README.md

@@ -15,6 +15,8 @@ Production-grade retrieval-augmented generation service for document-based quest
 **Base URL**: `https://pmmdot-askbookie.hf.space`  
 **Interactive Documentation**: `/docs` (Swagger UI) | `/redoc` (ReDoc)
 
+---
+
 ## Table of Contents
 
 1. [Authentication](#authentication)
@@ -24,18 +26,12 @@ Production-grade retrieval-augmented generation service for document-based quest
    - [POST /upload](#post-upload)
    - [GET /jobs/{job_id}](#get-jobsjob_id)
    - [GET /jobs](#get-jobs)
-4. [System Endpoints](#system-endpoints)
-   - [GET /health](#get-health)
-   - [GET /](#get-)
-5. [Admin Endpoints](#admin-endpoints)
-   - [GET /history](#get-history)
-   - [GET /admin/keys](#get-adminkeys)
-   - [POST /admin/keys/{key_id}/enable](#post-adminkeyskeyidenable)
-   - [POST /admin/keys/{key_id}/disable](#post-adminkeyskeyiddisable)
-   - [GET /admin/models/current](#get-adminmodelscurrent)
-   - [POST /admin/models/switch](#post-adminmodelsswitch)
-6. [Error Handling](#error-handling)
+4. [Frontend Integration Guide](#frontend-integration-guide)
+5. [System Endpoints](#system-endpoints)
+6. [Admin Endpoints](#admin-endpoints)
+7. [Error Handling](#error-handling)
 
+---
 
 ## Technical Stack
 
@@ -59,9 +55,11 @@ Production-grade retrieval-augmented generation service for document-based quest
 | 4 | GPT-4o-mini | DuckDuckGo (Free) |
 | 5 | Claude-3-Haiku | DuckDuckGo (Free) |
 
+---
+
 ## Authentication
 
-All endpoints except `/health` and `/` require HMAC-SHA256 request signing. Authentication operates on a rotating key infrastructure with 90-day expiration cycles.
+All endpoints except `/health` and `/` require HMAC-SHA256 request signing.
 
 ### Required Headers
 
@@ -78,39 +76,20 @@ The signature message follows the format:
 {timestamp}\n{HTTP_METHOD}\n{path}
 ```
 
-**Python Implementation**:
-```python
-import hmac
-import hashlib
-import time
-
-def generate_auth_headers(method: str, path: str, key_id: str, secret: str) -> dict:
-    timestamp = str(int(time.time()))
-    message = f"{timestamp}\n{method.upper()}\n{path}"
-    signature = hmac.new(
-        secret.encode(),
-        message.encode(),
-        hashlib.sha256
-    ).hexdigest()
-    
-    return {
-        "X-API-Key-Id": key_id,
-        "X-API-Timestamp": timestamp,
-        "X-API-Signature": signature
-    }
-```
-
 **JavaScript Implementation**:
 ```javascript
-const crypto = require('crypto');
-
-function generateAuthHeaders(method, path, keyId, secret) {
+async function generateAuthHeaders(method, path, keyId, secret) {
     const timestamp = Math.floor(Date.now() / 1000).toString();
     const message = `${timestamp}\n${method.toUpperCase()}\n${path}`;
-    const signature = crypto
-        .createHmac('sha256', secret)
-        .update(message)
-        .digest('hex');
+    
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+        'raw', encoder.encode(secret),
+        { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+    );
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(message));
+    const signature = Array.from(new Uint8Array(sig))
+        .map(b => b.toString(16).padStart(2, '0')).join('');
     
     return {
         'X-API-Key-Id': keyId,
@@ -122,419 +101,444 @@ function generateAuthHeaders(method, path, keyId, secret) {
 
 ### Security Constraints
 
-- Timestamp tolerance: 300 seconds (5 minutes)
-- Failed authentication lockout: 5 attempts per IP (5-minute window)
-- Constant-time signature comparison to prevent timing attacks
-
+- Timestamp tolerance: **300 seconds** (5 minutes)
+- Failed auth lockout: **5 attempts per IP** (5-minute window)
+- Constant-time signature comparison (timing attack prevention)
 
+---
 
 ## Rate Limits
 
-Rate limiting operates on a sliding window of 60 seconds per API key.
-
 | Endpoint | Limit | Window |
 |----------|-------|--------|
 | `/ask` | 30 requests | 60 seconds |
 | `/upload` | 2 requests | 60 seconds |
 | All other endpoints | 50 requests | 60 seconds |
-| Failed auth attempts | 5 per IP | 5 minutes (lockout) |
 
-When rate limited, responses include the `Retry-After` header:
-```http
-HTTP/1.1 429 Too Many Requests
-Retry-After: 60
-Content-Type: application/json
+When rate limited, responses include `Retry-After: 60` header.
+
+---
 
-{"detail": "Rate limit exceeded"}
-```
 ## Core Endpoints
 
 ### POST /ask
 
-Query the pre-vectorised document corpus. The system performs semantic retrieval against the specified subject partition, then synthesises a response using the active language model.
+Query documents using semantic retrieval + LLM synthesis.
+
+> [!IMPORTANT]
+> **Two query modes exist:**
+> 1. **Standard Mode**: Query pre-indexed university materials using `subject` + `unit`
+> 2. **Custom Upload Mode**: Query user-uploaded PDFs using `cluster` (returned from `/upload`)
+
+#### Request Schema
+
+| Field | Type | Required | Constraints | Description |
+|-------|------|----------|-------------|-------------|
+| `query` | string | **Yes** | 1-1000 chars | Natural language question |
+| `subject` | string | Conditional | 1-100 chars, alphanumeric + `_-` | Subject collection (e.g., `evs`, `physics`) |
+| `unit` | integer | Conditional | 1-4 | Unit number within the subject |
+| `cluster` | string | Conditional | max 100 chars | Temp cluster from `/upload` response |
+| `context_limit` | integer | No | 1-20, default 5 | Number of context chunks |
+
+> [!WARNING]
+> **Mutual Exclusivity**: Either provide `cluster` OR provide BOTH `subject` AND `unit`. Never mix them.
+
+#### Example 1: Standard Mode (Pre-indexed Materials)
 
-**Request**:
 ```http
 POST /ask HTTP/1.1
 Content-Type: application/json
-X-API-Key-Id: your-key-id
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
 
 {
     "query": "What are the different types of ecosystems?",
     "subject": "evs",
+    "unit": 2,
     "context_limit": 5
 }
 ```
 
-| Field | Type | Required | Constraints | Description |
-|-------|------|----------|-------------|-------------|
-| `query` | string | Yes | 1-1000 chars | Natural language question |
-| `subject` | string | Yes | 1-100 chars, alphanumeric with `_-` | Document collection identifier |
-| `context_limit` | integer | No | 1-20, default 5 | Number of context chunks for retrieval |
+#### Example 2: Custom Upload Mode (User PDF)
+
+```http
+POST /ask HTTP/1.1
+Content-Type: application/json
+
+{
+    "query": "Summarize the main findings",
+    "cluster": "temp_a1b2c3d4e5f6g7h8i9j0k1l2"
+}
+```
+
+#### Response (200 OK)
 
-**Response** (200 OK):
 ```json
 {
-    "answer": "Ecosystems are classified into two primary categories: terrestrial and aquatic. Terrestrial ecosystems include forests, grasslands, deserts, and tundra. Aquatic ecosystems are subdivided into freshwater (lakes, rivers, wetlands) and marine (oceans, coral reefs, estuaries).",
+    "answer": "Ecosystems are classified into terrestrial and aquatic...",
     "sources": [
-        {
-            "page": 12,
-            "content": "Ecosystems can be broadly categorized into terrestrial and aquatic types...",
-            "filename": "evs_chapter3.pdf"
-        },
-        {
-            "page": 15,
-            "content": "Marine ecosystems cover approximately 71% of Earth's surface...",
-            "filename": "evs_chapter3.pdf"
-        }
+        "evs_chapter3.pdf: Slide 12",
+        "evs_chapter3.pdf: Slide 15"
     ],
+    "collection": "askbookie_evs_unit-2",
     "request_id": "a1b2c3d4e5f6g7h8"
 }
 ```
+
+| Field | Description |
+|-------|-------------|
+| `answer` | LLM-generated response (Markdown formatted, LaTeX supported) |
+| `sources` | List of source references: `"filename: Slide N"` |
+| `collection` | The Qdrant collection queried |
+| `request_id` | Unique identifier for debugging |
+
 ---
+
 ### POST /upload
 
-Ingest a PDF document into the vector index. Documents are validated, chunked by page boundaries, embedded using the HuggingFace `gte-modernbert-base` model, and stored in the specified subject partition. Processing occurs asynchronously.
+Upload a PDF document for custom RAG queries. Processing is **asynchronous**.
+
+#### Request
 
-**Request**:
 ```http
 POST /upload HTTP/1.1
 Content-Type: multipart/form-data
-X-API-Key-Id: your-key-id
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
 
 file: [binary PDF data]
-subject: physics
 ```
 
-| Field | Type | Required | Constraints | Description |
-|-------|------|----------|-------------|-------------|
-| `file` | binary | Yes | PDF, max 10MB, must start with `%PDF` magic bytes | Document to ingest |
-| `subject` | string | Yes | 1-100 chars, alphanumeric with `_-` | Target collection identifier |
+| Field | Type | Required | Constraints |
+|-------|------|----------|-------------|
+| `file` | binary | **Yes** | PDF only, max 10MB, must start with `%PDF` magic bytes |
+
+#### Response (200 OK)
 
-**Response** (200 OK):
 ```json
 {
     "job_id": "a1b2c3d4e5f6g7h8i9j0k1l2",
     "status": "queued",
-    "filename": "thermodynamics_notes.pdf",
-    "subject": "physics",
-    "size": 2457600
+    "filename": "my_notes.pdf",
+    "size": 2457600,
+    "temp_cluster": "temp_a1b2c3d4e5f6g7h8i9j0k1l2"
 }
 ```
 
-**Validation Pipeline**:
-1. MIME type verification (`application/pdf`)
-2. Magic byte validation (must start with `%PDF`)
-3. Size constraint (max 10MB)
-4. Concurrent upload limit (max 3 per key)
+> [!IMPORTANT]
+> **Critical fields for frontend:**
+> - **`job_id`**: Use this to poll `/jobs/{job_id}` for processing status
+> - **`temp_cluster`**: **SAVE THIS!** Use it in `/ask` requests to query this PDF
+
+#### Processing Pipeline
+
+1. **Validation**: MIME type, magic bytes, size check
+2. **Chunking**: Split by page boundaries with context overlap
+3. **Embedding**: Vectorize using `gte-modernbert-base`
+4. **Storage**: Upsert to Qdrant under `temp_cluster` collection
+
+#### Job Status Values
+
+| Status | Description |
+|--------|-------------|
+| `queued` | Accepted, awaiting processing |
+| `processing` | Currently being chunked/embedded |
+| `done` | Ready for queries |
+| `failed` | Check `error` field for details |
+
 ---
 
 ### GET /jobs/{job_id}
 
-Retrieve the status of a PDF processing job. Jobs transition through the following states: `queued` → `processing` → `done` | `failed`.
+Poll the status of a PDF processing job.
 
-**Request**:
-```http
-GET /jobs/a1b2c3d4e5f6g7h8i9j0k1l2 HTTP/1.1
-X-API-Key-Id: your-key-id
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
-```
-
-**Response** (200 OK):
 ```json
 {
     "job_id": "a1b2c3d4e5f6g7h8i9j0k1l2",
-    "key_id": "your-key-id",
-    "filename": "thermodynamics_notes.pdf",
-    "subject": "physics",
-    "size": 2457600,
     "status": "done",
-    "error": null,
-    "created_at": 1705234567.0,
-    "updated_at": 1705234890.0
+    "temp_cluster": "temp_a1b2c3d4e5f6g7h8i9j0k1l2",
+    "filename": "my_notes.pdf",
+    "error": null
 }
 ```
 
-| Status | Description |
-|--------|-------------|
-| `queued` | Job accepted, awaiting processing |
-| `processing` | Document being chunked and embedded |
-| `done` | Successfully ingested into vector store |
-| `failed` | Processing error (check `error` field) |
 ---
 
 ### GET /jobs
 
-List all jobs associated with the authenticated API key. Results are ordered by creation time (descending).
+List all jobs for the authenticated API key.
 
-**Request**:
-```http
-GET /jobs HTTP/1.1
-X-API-Key-Id: your-key-id
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
+---
+
+## Frontend Integration Guide
+
+> [!IMPORTANT]
+> This section provides implementation guidance for frontend developers.
+
+### Chat Session State Model
+
+```typescript
+interface ChatSession {
+    // User selection (standard mode)
+    subject: string | null;      // e.g., "evs", "physics"
+    unit: number | null;         // 1-4
+    
+    // Custom upload (custom mode)  
+    tempCluster: string | null;  // From /upload response
+    uploadJobId: string | null;  // For status polling
+    
+    // Mode lock
+    isCustomMode: boolean;       // Once PDF uploaded, lock to custom mode
+}
 ```
 
-**Response** (200 OK):
-```json
-{
-    "jobs": [
-        {
-            "job_id": "a1b2c3d4e5f6g7h8i9j0k1l2",
-            "filename": "thermodynamics_notes.pdf",
-            "subject": "physics",
-            "size": 2457600,
-            "status": "done",
-            "error": null,
-            "created_at": 1705234567.0
+### Flow 1: Standard Query (Pre-indexed Materials)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  User selects Subject: [EVS ▼] and Unit: [2 ▼]          │
+│  ─────────────────────────────────────────────────────  │
+│  User types: "What are ecosystem types?"                │
+│                                                         │
+│  → POST /ask { query, subject: "evs", unit: 2 }         │
+│  ← Response with answer + sources                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Flow 2: Custom PDF Upload
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Step 1: User uploads PDF                               │
+│  ─────────────────────────────────────────────────────  │
+│  → POST /upload (multipart/form-data)                   │
+│  ← { job_id, temp_cluster, status: "queued" }           │
+│                                                         │
+│  ⚠️  SAVE: temp_cluster = "temp_abc123..."              │
+│  ⚠️  LOCK: subject/unit dropdowns (disable them)        │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│  Step 2: Poll for completion                            │
+│  ─────────────────────────────────────────────────────  │
+│  Loop every 2-3 seconds:                                │
+│  → GET /jobs/{job_id}                                   │
+│  ← { status: "processing" | "done" | "failed" }         │
+│                                                         │
+│  When status === "done": Enable chat input              │
+│  When status === "failed": Show error, unlock dropdowns │
+└─────────────────────────────────────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────────────┐
+│  Step 3: Query the uploaded PDF                         │
+│  ─────────────────────────────────────────────────────  │
+│  User types: "Summarize the main points"                │
+│                                                         │
+│  → POST /ask { query, cluster: "temp_abc123..." }       │
+│  ← Response with answer + sources from their PDF        │
+│                                                         │
+│  ⚠️  Keep using the same temp_cluster for all queries   │
+│      in this chat session                               │
+└─────────────────────────────────────────────────────────┘
+```
+
+### UI State Logic
+
+```typescript
+// When user uploads a PDF
+async function handlePdfUpload(file: File) {
+    const formData = new FormData();
+    formData.append('file', file);
+    
+    const response = await fetch('/upload', {
+        method: 'POST',
+        headers: generateAuthHeaders('POST', '/upload'),
+        body: formData
+    });
+    const data = await response.json();
+    
+    // CRITICAL: Store these values in session state
+    session.tempCluster = data.temp_cluster;  // ← SAVE THIS
+    session.uploadJobId = data.job_id;
+    session.isCustomMode = true;              // ← LOCK MODE
+    
+    // Disable subject/unit dropdowns in UI
+    disableSubjectUnitSelectors();
+    
+    // Start polling
+    pollJobStatus(data.job_id);
+}
+
+// When sending a query
+async function sendQuery(query: string) {
+    let payload;
+    
+    if (session.isCustomMode && session.tempCluster) {
+        // Custom mode: use cluster
+        payload = {
+            query: query,
+            cluster: session.tempCluster  // ← USE STORED VALUE
+        };
+    } else {
+        // Standard mode: use subject + unit
+        payload = {
+            query: query,
+            subject: session.subject,
+            unit: session.unit
+        };
+    }
+    
+    const response = await fetch('/ask', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...generateAuthHeaders('POST', '/ask')
         },
-        {
-            "job_id": "m1n2o3p4q5r6s7t8u9v0w1x2",
-            "filename": "organic_chemistry.pdf",
-            "subject": "chemistry",
-            "size": 1843200,
-            "status": "processing",
-            "error": null,
-            "created_at": 1705234500.0
-        }
-    ],
-    "total": 2
+        body: JSON.stringify(payload)
+    });
+    
+    return await response.json();
 }
 ```
 
+### Subject/Unit Locking Rules
+
+| Scenario | Subject Dropdown | Unit Dropdown | Upload Button |
+|----------|-----------------|---------------|---------------|
+| Fresh chat session | ✅ Enabled | ✅ Enabled | ✅ Enabled |
+| After selecting subject/unit | ✅ Enabled (can change) | ✅ Enabled | ✅ Enabled |
+| After uploading PDF | ❌ **Disabled** | ❌ **Disabled** | ❌ Disabled |
+| After upload fails | ✅ Re-enabled | ✅ Re-enabled | ✅ Re-enabled |
+| New chat started | ✅ Enabled (reset) | ✅ Enabled | ✅ Enabled |
+
+> [!CAUTION]
+> Once a user uploads a PDF in a chat session, **ALL subsequent queries in that session MUST use the `cluster` parameter**, not `subject`/`unit`. The `temp_cluster` is tied to their uploaded document.
+
+### Available Subjects & Units
+
+| Subject | Units Available | Collection Pattern |
+|---------|-----------------|-------------------|
+| `evs` | 1, 2, 3, 4 | `askbookie_evs_unit-{N}` |
+| `physics` | 1, 2, 3, 4 | `askbookie_physics_unit-{N}` |
+| *other subjects* | 1-4 | `askbookie_{subject}_unit-{N}` |
+
+### Answer Formatting
+
+Answers are returned in **Markdown** with **LaTeX** support:
+- Inline math: `$E = mc^2$`
+- Block math: `$$\int_0^1 x^2 dx$$`
+
+Use a Markdown renderer with KaTeX/MathJax integration.
+
+---
+
 ## System Endpoints
 
 ### GET /health
 
-Service health check endpoint. Returns operational metrics and current model configuration. No authentication required.
+Service health check. **No authentication required.**
 
-**Response** (200 OK):
 ```json
 {
     "status": "healthy",
     "uptime_hours": 48.5,
-    "total_api_calls": 15420,
-    "total_questions": 12350,
-    "active_jobs": 2,
-    "memory_mb": 1024.5,
     "current_model": {
-        "id": 1,
+        "model_id": 1,
         "name": "Gemini-3-flash",
         "description": "Gemini Primary API Key"
-    },
-    "per_user": {
-        "askbookie-pesu": {
-            "api_calls": 8500,
-            "questions_asked": 7200,
-            "uploads_attempted": 45,
-            "success_rate": 98.5,
-            "average_latency_seconds": 1.25,
-            "ask_fails": 12,
-            "upload_fails": 3,
-            "role": "user"
-        }
     }
 }
 ```
----
-### GET /
 
-Dashboard endpoint. Returns the service dashboard HTML if available, otherwise returns service metadata.
+### GET /
 
-**Response** (200 OK):
-```json
-{
-    "service": "AskBookie RAG API",
-    "version": "1.0.0"
-}
-```
+Returns dashboard HTML or service metadata.
 
+---
 
 ## Admin Endpoints
 
-### GET /history
-
-Retrieve paginated query history across all users. Useful for analytics and audit trails.
+> [!NOTE]
+> All admin endpoints require the `admin` API key.
 
-**Request**:
-```http
-GET /history?limit=50&offset=0 HTTP/1.1
-X-API-Key-Id: admin
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
-```
+### GET /history
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `limit` | integer | 100 | Number of records to return |
-| `offset` | integer | 0 | Pagination offset |
+Paginated query history across all users.
 
-**Response** (200 OK):
-```json
-{
-    "history": [
-        {
-            "id": 1,
-            "key_id": "askbookie-pesu",
-            "subject": "physics",
-            "query": "What is the first law of thermodynamics?",
-            "answer": "The first law of thermodynamics states that energy cannot be created or destroyed...",
-            "sources": [...],
-            "request_id": "a1b2c3d4e5f6g7h8",
-            "latency_ms": 1250.5,
-            "timestamp": 1705234567.0
-        }
-    ],
-    "total": 12350,
-    "limit": 50,
-    "offset": 0
-}
-```
----
 ### GET /admin/keys
 
-List all configured API keys with their metadata.
+List all API keys with status.
 
-**Response** (200 OK):
-```json
-{
-    "keys": [
-        {
-            "key_id": "askbookie-pesu",
-            "role": "user",
-            "active": true,
-            "expires_at": "2025-04-14T00:00:00+00:00"
-        },
-        {
-            "key_id": "admin",
-            "role": "admin",
-            "active": true,
-            "expires_at": null
-        }
-    ]
-}
-```
----
 ### POST /admin/keys/{key_id}/enable
 
-Re-enable a disabled API key.
+Re-enable a disabled key.
 
-**Response** (200 OK):
-```json
-{
-    "status": "enabled",
-    "key_id": "askbookie-pesu"
-}
-```
----
 ### POST /admin/keys/{key_id}/disable
 
-Disable an API key. Disabled keys cannot authenticate requests. The admin key cannot be disabled.
+Disable an API key (cannot disable `admin`).
 
-**Response** (200 OK):
-```json
-{
-    "status": "disabled",
-    "key_id": "askbookie-pesu"
-}
-```
----
 ### GET /admin/models/current
 
-Retrieve the currently active language model configuration.
+Get current active model.
+
+### POST /admin/models/switch
 
-**Response** (200 OK):
 ```json
-{
-    "id": 1,
-    "name": "Gemini-3-flash",
-    "description": "Gemini Primary API Key"
-}
+{ "model_id": 2 }
 ```
----
-### POST /admin/models/switch
 
-Switch the active language model. The system supports multiple model backends for failover and experimentation.
+Switch to a different LLM backend (1-5).
 
-**Request**:
-```http
-POST /admin/models/switch HTTP/1.1
-Content-Type: application/json
-X-API-Key-Id: admin
-X-API-Timestamp: 1705234567
-X-API-Signature: a1b2c3d4...
+---
 
-{
-    "model_id": 2
-}
+## Error Handling
+
+All errors return:
+```json
+{ "detail": "Error description" }
 ```
 
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request - Missing/invalid parameters |
+| 401 | Unauthorized - Invalid signature or expired key |
+| 403 | Forbidden - Admin endpoint accessed with non-admin key |
+| 404 | Not Found - Job doesn't exist or wrong owner |
+| 413 | Payload Too Large - PDF > 10MB or JSON > 16KB |
+| 429 | Rate Limited - See `Retry-After` header |
+| 500 | Internal Error - RAG pipeline failure |
+
+### Special 429 Cases
+
+| Detail Message | Cause | Frontend Action |
+|----------------|-------|-----------------|
+| `"Rate limit exceeded"` | Too many requests | Wait 60s, show countdown |
+| `"Too many concurrent uploads"` | 3+ uploads in progress | Wait for pending jobs |
+| `"LLM quota exhausted"` | Model API limit hit | Retry in 1hr or notify user |
+| `"Too many failed attempts"` | Auth lockout | Wait 5 minutes |
+
+---
 
-**Response** (200 OK):
+## Quick Reference: /ask Request Bodies
+
+**Standard Mode:**
 ```json
 {
-    "status": "success",
-    "message": "Switched to model 2",
-    "model": {
-        "id": 2,
-        "name": "Gemini-3-flash(Back-up)",
-        "description": "Gemini Secondary API Key"
-    }
+    "query": "Your question here",
+    "subject": "evs",
+    "unit": 2
 }
 ```
----
-## Error Handling
-
-All errors return JSON responses with consistent structure:
 
+**Custom Upload Mode:**
 ```json
 {
-    "detail": "Error description"
+    "query": "Your question here", 
+    "cluster": "temp_a1b2c3d4e5f6g7h8i9j0k1l2"
 }
 ```
-### HTTP Status Codes
-
-| Code | Meaning |
-|------|---------|
-| 400 | Bad Request - Invalid parameters, malformed JSON, unsupported file type |
-| 401 | Unauthorized - Invalid or expired signature, missing auth headers |
-| 403 | Forbidden - Insufficient permissions for admin endpoints |
-| 404 | Not Found - Job or resource does not exist |
-| 413 | Payload Too Large - File exceeds 10MB or JSON exceeds 16KB |
-| 429 | Too Many Requests - Rate limit exceeded, auth lockout, or LLM quota exhausted |
-| 500 | Internal Server Error - RAG pipeline failure |
-
 
----
-### cURL Examples
-
-```bash
-generate_sig() {
-    local method=$1 path=$2 secret=$3
-    local ts=$(date +%s)
-    local msg="${ts}"$'\n'"${method}"$'\n'"${path}"
-    local sig=$(echo -n "$msg" | openssl dgst -sha256 -hmac "$secret" | cut -d' ' -f2)
-    echo "-H 'X-API-Key-Id: $KEY_ID' -H 'X-API-Timestamp: $ts' -H 'X-API-Signature: $sig'"
+**❌ Invalid (mixing modes):**
+```json
+{
+    "query": "question",
+    "subject": "evs",
+    "cluster": "temp_..."
 }
-
-curl -X POST https://pmmdot-askbookie.hf.space/ask \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key-Id: your-key-id" \
-  -H "X-API-Timestamp: $(date +%s)" \
-  -H "X-API-Signature: <computed>" \
-  -d '{"query": "What is thermodynamics?", "subject": "physics"}'
-
-curl -X POST https://pmmdot-askbookie.hf.space/upload \
-  -H "X-API-Key-Id: your-key-id" \
-  -H "X-API-Timestamp: $(date +%s)" \
-  -H "X-API-Signature: <computed>" \
-  -F "file=@document.pdf" \
-  -F "subject=physics"
-
-curl https://pmmdot-askbookie.hf.space/health
 ```

pyproject.toml

@@ -5,6 +5,7 @@ description = "API for AskBookie - a question answering system powered by LangCh
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 dependencies = [
+    "certifi>=2025.11.12",
     "fastapi>=0.128.0",
     "g4f>=6.8.3",
     "langchain-community>=0.4.1",

src/database.py

@@ -1,6 +1,8 @@
 import os
 import time
 import logging
+import ssl
+import certifi
 from datetime import datetime, timezone
 from typing import Optional, List
 
@@ -23,9 +25,10 @@ def get_database():
     try:
         _client = MongoClient(
             MONGODB_URI, 
-            serverSelectionTimeoutMS=5000,
+            serverSelectionTimeoutMS=10000,
             tls=True,
-            tlsAllowInvalidCertificates=True
+            tlsAllowInvalidCertificates=True,
+            tlsCAFile=certifi.where()
         )
         _client.admin.command('ping')
         _db = _client.askbookie

src/rag.py

@@ -225,6 +225,37 @@ class RAGService:
         
         return {"answer": answer, "sources": sources}
 
+    def ask_collection(self, query_text: str, collection_name: str):
+        """Query a specific collection by name (for custom uploads/temp clusters)."""
+        max_retries = 3
+        last_error = None
+        
+        for attempt in range(max_retries):
+            try:
+                client = QdrantClient(url=self.qdrant_url, api_key=self.qdrant_key, timeout=120)
+                vectorstore = QdrantVectorStore(client=client, collection_name=collection_name, embedding=self.embeddings)
+                results = vectorstore.similarity_search_with_score(query_text, k=5)
+                break
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise last_error
+
+        top_results = results[:5]
+        context_text = "\n\n---\n\n".join([doc.page_content for doc, _ in top_results])
+        
+        full_prompt = PROMPT_TEMPLATE.format(context=context_text, question=query_text)
+        answer = call_llm(full_prompt)
+        
+        sources = [
+            f"{doc.metadata.get('source', 'Unknown')}: Slide {doc.metadata.get('slide_number', 'Unknown')}" 
+            for doc, _ in top_results
+        ]
+        
+        return {"answer": answer, "sources": sources}
+
 
 def process_pdf(file_path: str, original_filename: str, subject: str, status_callback=None, temp_cluster_id: str = None) -> str:
     qdrant_url = os.getenv("QDRANT_CLUSTER_URL")

uv.lock

@@ -153,6 +153,7 @@ name = "askbookie-api"
 version = "0.1.0"
 source = { virtual = "." }
 dependencies = [
+    { name = "certifi" },
     { name = "fastapi" },
     { name = "g4f" },
     { name = "langchain-community" },
@@ -173,6 +174,7 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
+    { name = "certifi", specifier = ">=2025.11.12" },
     { name = "fastapi", specifier = ">=0.128.0" },
     { name = "g4f", specifier = ">=6.8.3" },
     { name = "langchain-community", specifier = ">=0.4.1" },