API_README.md

Flask API Server for Advanced RAG System

This Flask API server provides REST endpoints for the Advanced RAG System, allowing you to upload documents and process queries programmatically.

Features

• Document Upload: Upload and process various document formats (PDF, TXT, DOCX, HTML, etc.)
• Query Processing: Ask questions about uploaded documents
• OCR Support: Process scanned documents with OCR
• System Management: Check status, validate components, clear data
• Authentication: Bearer token authentication
• Error Handling: Comprehensive error handling and fallback mechanisms

API Endpoints

1. Health Check

GET /health

Check if the server is running and healthy.

Response:

{
  "status": "healthy",
  "rag_system_initialized": true,
  "ocr_available": true
}

2. System Status

GET /hackrx/status

Get detailed system status and statistics.

Headers:

Authorization: Bearer your_api_key_here

Response:

{
  "status": "ready",
  "statistics": {
    "vector_database": {
      "total_chunks": 150,
      "unique_sources": 3,
      "file_types": ["pdf", "txt"]
    },
    "audit_trail": {
      "total_entries": 25,
      "successful_queries": 20,
      "failed_queries": 5
    }
  },
  "ocr_available": true
}

3. Document Upload

POST /hackrx/upload

Upload and process a document.

Headers:

Authorization: Bearer your_api_key_here

Form Data:

• file: The document file to upload
• use_ocr: (optional) "true" or "false" to enable OCR for PDFs

Supported File Types:

• PDF (.pdf)
• Text (.txt)
• Word (.docx)
• HTML (.html, .htm)
• Email (.eml, .msg)
• CSV (.csv)
• JSON (.json)

Response:

{
  "success": true,
  "message": "Document processed successfully",
  "chunks_processed": 45,
  "processing_time": 2.34,
  "filename": "document.pdf"
}

4. Query Processing

POST /hackrx/run

Process questions about uploaded documents.

Headers:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Request Body:

{
  "questions": [
    "What is covered under this policy?",
    "What is the maximum coverage amount?",
    "What documents are required for claims?"
  ]
}

Response:

{
  "answers": [
    {
      "question": "What is covered under this policy?",
      "answer": "Based on the policy document, the following are covered...",
      "decision": "COVERED",
      "confidence": 0.85,
      "processing_time": 1.23,
      "amount": 50000.0,
      "waiting_period": "30 days",
      "relevant_clauses": ["Section 3.1", "Section 4.2"],
      "conditions": ["Must be hospitalized", "Pre-authorization required"],
      "exclusions": ["Cosmetic procedures", "Experimental treatments"],
      "required_documents": ["Hospital bills", "Medical reports"]
    }
  ]
}

5. System Validation

GET /hackrx/validate

Validate all system components.

Headers:

Authorization: Bearer your_api_key_here

Response:

{
  "document_processor": true,
  "vector_database": true,
  "query_parser": true,
  "reasoning_engine": true,
  "all_valid": true,
  "errors": []
}

6. Clear System

POST /hackrx/clear

Clear all system data and reset the RAG system.

Headers:

Authorization: Bearer your_api_key_here

Response:

{
  "success": true,
  "message": "System cleared successfully"
}

Authentication

All endpoints (except /health) require Bearer token authentication:

Authorization: Bearer your_api_key_here

Default API Key: your_api_key_here

Note: Change this in production for security.

Error Responses

All endpoints return appropriate HTTP status codes:

• 200: Success
• 400: Bad Request (missing parameters, invalid data)
• 401: Unauthorized (missing or invalid Authorization header)
• 403: Forbidden (invalid API key)
• 500: Internal Server Error

Error response format:

{
  "error": "Error description"
}

Usage Examples

Python Example

import requests
import json

# Configuration
BASE_URL = "http://localhost:5000"
API_KEY = "your_api_key_here"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Upload a document
with open("document.pdf", "rb") as f:
    files = {"file": f}
    data = {"use_ocr": "false"}
    upload_headers = {"Authorization": f"Bearer {API_KEY}"}
    
    response = requests.post(
        f"{BASE_URL}/hackrx/upload",
        files=files,
        data=data,
        headers=upload_headers
    )
    print("Upload response:", response.json())

# 2. Process queries
questions = [
    "What is covered under this policy?",
    "What is the maximum coverage amount?"
]

payload = {"questions": questions}
response = requests.post(
    f"{BASE_URL}/hackrx/run",
    json=payload,
    headers=HEADERS
)

answers = response.json()["answers"]
for answer in answers:
    print(f"Q: {answer['question']}")
    print(f"A: {answer['answer']}")
    print(f"Decision: {answer['decision']}")
    print(f"Confidence: {answer['confidence']}")
    print("---")

cURL Examples

Health Check:

curl http://localhost:5000/health

System Status:

curl -H "Authorization: Bearer your_api_key_here" \
     http://localhost:5000/hackrx/status

Upload Document:

curl -X POST \
     -H "Authorization: Bearer your_api_key_here" \
     -F "file=@document.pdf" \
     -F "use_ocr=false" \
     http://localhost:5000/hackrx/upload

Process Queries:

curl -X POST \
     -H "Authorization: Bearer your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"questions": ["What is covered under this policy?"]}' \
     http://localhost:5000/hackrx/run

Running the Server

1. Install Dependencies:

   pip install flask requests
   

2. Start the Server:

   python app.py
   

3. Test the API:

   python test_api.py
   

Configuration

Environment Variables

You can set these environment variables:

• FLASK_ENV: Set to production for production deployment
• API_KEY: Override the default API key
• PORT: Override the default port (5000)

Production Deployment

For production deployment:

1. Change the API key in app.py
2. Set debug=False in app.run()
3. Use a production WSGI server like Gunicorn:

   pip install gunicorn
   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   

Troubleshooting

Common Issues

1. RAG System Initialization Failed

   • Check if all required dependencies are installed
   • Ensure model files are available
   • Check system memory and resources

2. Document Upload Fails

   • Verify file format is supported
   • Check file size limits
   • Ensure proper file permissions

3. Query Processing Errors

   • Make sure documents are uploaded first
   • Check if the RAG system is properly initialized
   • Verify the question format

4. Authentication Errors

   • Ensure the Authorization header is present
   • Verify the API key is correct
   • Check the Bearer token format

Logs

The server provides detailed logging. Check the console output for:

• RAG system initialization status
• Document processing progress
• Query processing results
• Error messages and stack traces

Security Considerations

1. Change the Default API Key: Update your_api_key_here in production
2. Use HTTPS: Always use HTTPS in production
3. Rate Limiting: Consider implementing rate limiting for production use
4. Input Validation: The API includes basic validation, but add more as needed
5. File Upload Security: Implement additional file validation for production

Support

For issues and questions:

1. Check the console logs for error messages
2. Verify all dependencies are installed
3. Test with the provided test_api.py script
4. Check the system validation endpoint for component status