API Documentation.md

# 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.