API Documentation

API Documentation.md

@@ -0,0 +1,309 @@
+# Lung Cancer AI Advisor API Documentation
+
+
+## Base URL
+```
+https://moazx-lung-cancer-ai-advisor.hf.space/  # Production
+http://127.0.0.1:7860/                         # Development
+```
+
+---
+
+## 1. POST `/ask`
+**Full Endpoint:** `https://moazx-lung-cancer-ai-advisor.hf.space/ask` (Production)
+**Development:** `http://127.0.0.1:7860/ask`
+**Purpose:** Get a complete AI response for a lung cancer-related medical query.
+
+### Request
+- **Method:** `POST`
+- **Content-Type:** `application/json`
+- **Authentication:** Required (via `Authorization` header)
+
+**Request Body (JSON):**
+```json
+{
+  "query": "What are the early symptoms of lung cancer?",
+  "session_id": "user_123_session_1699612345"
+}
+```
+
+**Parameters:**
+- `query` (required, string): The medical question about lung cancer
+- `session_id` (required, string): Unique session identifier for conversation continuity. Format: `user_{user_id}_session_{timestamp}`
+
+### Response (200 OK)
+```json
+{
+  "response": "Early symptoms of lung cancer may include...\n\n**Common Early Signs:**\n- Persistent cough...",
+  "session_id": "user_123_session_1699612345"
+}
+```
+
+### Error Responses
+- **400 Bad Request**: Missing or invalid parameters
+- **401 Unauthorized**: Missing or invalid authentication
+- **500 Internal Server Error**: Error processing the query
+- **503 Service Unavailable**: Service is initializing, try again later
+
+---
+
+## 2. POST `/ask/stream` (Recommended)
+**Full Endpoint:** `https://moazx-lung-cancer-ai-advisor.hf.space/ask/stream` (Production)
+**Development:** `http://127.0.0.1:7860/ask/stream`
+**Purpose:** Stream AI response in real-time for better UX.
+
+### Request
+- **Method:** `POST`
+- **Content-Type:** `application/json`
+- **Authentication:** Required (via `Authorization` header)
+
+**Request Body (JSON):**
+```json
+{
+  "query": "What are the early symptoms of lung cancer?",
+  "session_id": "user_123_session_1699612345"
+}
+```
+
+**Parameters:**
+- `query` (required, string): The medical question about lung cancer
+- `session_id` (required, string): Unique session identifier for conversation continuity. Format: `user_{user_id}_session_{timestamp}`
+
+### Response
+- Streams the AI response in chunks (text/event-stream or similar).
+- Each chunk contains a part of the response.
+
+### Error Responses
+- **400 Bad Request**: Missing or invalid parameters
+- **401 Unauthorized**: Missing or invalid authentication
+- **500 Internal Server Error**: Error processing the query
+- **503 Service Unavailable**: Service is initializing, try again later
+
+---
+
+## 3. GET `/health`
+**Full Endpoint:** `https://moazx-lung-cancer-ai-advisor.hf.space/health` (Production)
+**Development:** `http://127.0.0.1:7860/health`
+
+**Related Endpoints:**
+- `GET /health/ping` - Basic connectivity check
+- `GET /health/initialization` - Check initialization status
+- `GET /health/version` - Get API version information
+**Purpose:** Comprehensive health check of all system components.
+
+### Response (200 OK)
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "timestamp": "2024-01-01T12:00:00Z",
+  "components": {
+    "agent": "healthy",
+    "vector_store": "healthy",
+    "data_loaders": "healthy",
+    "tools": "healthy"
+  },
+  "initialization": {
+    "is_complete": true,
+    "status_message": "Initialization complete",
+    "is_successful": true,
+    "error": null
+  }
+}
+```
+
+**Component Status Values:**
+- `healthy`: Component is functioning normally
+- `unhealthy`: Component is not functioning
+- `initializing`: Component is still initializing
+
+**Initialization Status:**
+- `is_complete`: Whether initialization has completed
+- `is_successful`: Whether initialization was successful
+- `status_message`: Current status message
+- `error`: Any error that occurred during initialization
+
+---
+
+## 4. Export Endpoints
+
+### 4.1 GET `/export/{format}`
+**Full Endpoint:** `https://moazx-lung-cancer-ai-advisor.hf.space/export/{format}` (Production)
+**Development:** `http://127.0.0.1:7860/export/{format}`
+**Purpose:** Export conversation history in the specified format.
+
+**Path Parameters:**
+- `format` (string, required): 
+  - `docx`: Microsoft Word document (.docx)
+  - `pdf`: Portable Document Format (.pdf)
+
+**Query Parameters:**
+- `session_id` (string, required): The session ID to export (e.g., "user_123_session_1699612345")
+
+**Example Request:**
+```
+GET /export/pdf?session_id=user_123_session_1699612345
+```
+
+**Responses:**
+- **200 OK**: 
+  - Returns the exported file with appropriate content-type header
+  - Headers:
+    - `Content-Type`: `application/pdf` or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+    - `Content-Disposition`: `attachment; filename=conversation_{session_id}_{timestamp}.{format}`
+- **400 Bad Request**: 
+  - Invalid format (not 'docx' or 'pdf')
+  - Missing required parameters
+- **401 Unauthorized**: Missing or invalid authentication
+- **404 Not Found**: No conversation history found for the specified session
+- **500 Internal Server Error**: Error generating export file
+- **503 Service Unavailable**: Service is initializing, try again later
+
+**Response Headers:**
+- `Content-Type`: `application/pdf` or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+- `Content-Disposition`: `attachment; filename=conversation_{session_id}_{timestamp}.{format}`
+
+**Frontend Integration Tips:**
+- Trigger file download using the browser's built-in behavior
+- Show loading state during export generation
+- Handle errors gracefully with user-friendly messages
+- For PDF exports, consider showing a preview using PDF.js
+
+---
+
+## 5. Session Management
+
+### 5.1 GET `/sessions`
+**Purpose:** List all active conversation sessions.
+
+**Response (200 OK):**
+```json
+{
+  "active_sessions": ["session1", "session2"],
+  "count": 2,
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+### 5.2 DELETE `/sessions/{session_id}`
+**Purpose:** Clear conversation history for a specific session.
+
+**Path Parameters:**
+- `session_id`: The session ID to clear
+
+**Response (200 OK):**
+```json
+{
+  "message": "Session 'session_id' cleared successfully",
+  "session_id": "session_id",
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+### 5.3 DELETE `/sessions`
+**Purpose:** Clear all conversation sessions.
+
+**Response (200 OK):**
+```json
+{
+  "message": "All sessions cleared successfully",
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+---
+
+## 6. Error Handling
+
+All error responses follow this format:
+```json
+{
+  "error": "error_type",
+  "message": "Human-readable error message",
+  "details": {
+    "field": "Additional error details"
+  },
+  "timestamp": "2024-01-01T12:00:00Z"
+}
+```
+
+**Common Error Types:**
+- `validation_error`: Request validation failed
+- `authentication_error`: Invalid or missing authentication
+- `not_found`: Requested resource not found
+- `rate_limit_exceeded`: Too many requests
+- `server_error`: Internal server error
+
+---
+
+## 7. Rate Limiting
+
+- **Rate Limit:** 100 requests per minute per IP address
+- **Headers:**
+  - `X-RateLimit-Limit`: Request limit per time window
+  - `X-RateLimit-Remaining`: Remaining requests in current window
+  - `X-RateLimit-Reset`: Time when the rate limit resets (UTC timestamp)
+
+---
+
+## 8. Authentication
+
+All endpoints (except `/health` and `/health/ping`) require authentication.
+
+**Authentication Header:**
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+**Getting an API Key:**
+Contact the administrator to obtain an API key with appropriate permissions.
+
+---
+
+## 9. Best Practices
+
+1. **Session Management**
+   - Always use unique session IDs for different users
+   - Reuse the same session ID for follow-up questions
+   - Clean up old sessions when no longer needed
+
+2. **Error Handling**
+   - Implement retry logic for transient errors (5xx)
+   - Cache successful responses when appropriate
+   - Log errors for debugging purposes
+
+3. **Performance**
+   - Use the streaming endpoint (`/ask/stream`) for better UX
+   - Implement client-side caching of responses
+   - Batch requests when possible
+
+4. **Security**
+   - Never expose API keys in client-side code
+   - Use HTTPS for all requests
+   - Validate all user input
+
+---
+
+## 10. Support
+
+For questions or issues, please contact:
+- **Email:** support@lungcanceradvisor.com
+- **Slack:** #api-support channel
+- **Documentation:** https://docs.lungcanceradvisor.com/api
+
+---
+
+## Changelog
+
+### v1.0.0 (2024-01-01)
+- Initial release of the Lung Cancer AI Advisor API
+- Support for streaming and non-streaming queries
+- Session-based conversation history
+- Export functionality (PDF/DOCX)
+- Comprehensive health monitoring
+
+---
+
+*Documentation last updated: November 10, 2024*
+
+For questions or further integration help, contact the backend team.