README.md

HNTAI - Medical Data Extraction & AI Processing Platform

A comprehensive, scalable AI platform for medical data extraction, processing, and analysis. Built with FastAPI, supporting multiple AI model backends including Transformers, OpenVINO, and GGUF models with automatic GPU/CPU optimization.

🏥 Overview

HNTAI is a production-ready medical AI platform that provides:

• Medical Document Processing: PDF, DOCX, image, and audio transcription
• Protected Health Information (PHI) Scrubbing: HIPAA-compliant data anonymization
• AI-Powered Summarization: Multi-model support with automatic device optimization
• Patient Summary Generation: Comprehensive clinical assessments
• Scalable Architecture: Kubernetes-ready with monitoring and security features

🚀 Key Features

🤖 Multi-Model AI Support

• Transformers Models: Hugging Face models with automatic GPU/CPU detection
• OpenVINO Optimization: Intel-optimized models for production performance
• GGUF Models: Quantized models for efficient inference
• Automatic Device Selection: GPU when available, CPU fallback
• Model Caching: Intelligent model management and caching

📄 Document Processing

• Multi-format Support: PDF, DOCX, images, audio files
• OCR Integration: Tesseract-based text extraction
• Audio Transcription: Whisper-based speech-to-text
• Batch Processing: Async processing for scalability

🔒 Security & Compliance

• HIPAA Compliance: PHI scrubbing with audit logging
• Data Encryption: Secure data handling and storage
• Audit Trails: Comprehensive logging for compliance
• Non-root Containers: Security-hardened deployments

📊 Monitoring & Observability

• Health Endpoints: /health/live, /health/ready
• Prometheus Metrics: /metrics endpoint
• Structured Logging: Comprehensive application monitoring
• Performance Tracking: Model inference metrics

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI       │    │   AI Models     │    │   PostgreSQL    │
│   Web Server    │◄──►│   (Multi-backend)│    │   Database      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Redis Cache   │    │   File Storage  │    │   Audit Logs    │
│   (PHI Stats)   │    │   (Documents)   │    │   (Compliance)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ Installation

Prerequisites

• Python 3.11+
• CUDA 11.8+ (for GPU support)
• Docker (for containerized deployment)
• PostgreSQL 13+
• Redis 6+

Local Development

1. Clone the repository:

git clone <repository-url>
cd HNTAI

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

export DATABASE_URL="postgresql://user:password@localhost:5432/hntai"
export REDIS_URL="redis://localhost:6379"
export SECRET_KEY="your-secret-key"
export JWT_SECRET_KEY="your-jwt-secret"
export HF_HOME="/tmp/huggingface"

5. Run the application:

# Development server
python -m uvicorn services.ai-service.src.ai_med_extract.main:app --reload --host 0.0.0.0 --port 7860

# Or using the service directly
cd services/ai-service
python src/ai_med_extract/main.py

Docker Deployment

1. Build the image:

docker build -t hntai:latest .

2. Run with Docker Compose:

docker-compose up -d

Kubernetes Deployment

1. Apply Kubernetes manifests:

kubectl apply -f infra/k8s/secure_deployment.yaml

2. Check deployment status:

kubectl get pods -l app=hntai

📚 API Documentation

Core Endpoints

Health & Monitoring

• GET /health/live - Liveness probe
• GET /health/ready - Readiness probe
• GET /metrics - Prometheus metrics

Document Processing

• POST /upload - Upload and process documents
• POST /transcribe - Transcribe audio files
• GET /get_updated_medical_data - Retrieve processed data
• PUT /update_medical_data - Update medical data

AI Processing

• POST /generate_patient_summary - Generate comprehensive patient summaries
• POST /api/generate_summary - Generate text summaries
• POST /api/patient_summary_openvino - OpenVINO-optimized summaries
• POST /extract_medical_data - Extract structured medical data

Model Management

• POST /api/load_model - Load specific AI models
• GET /api/model_info - Get model information
• POST /api/switch_model - Switch between models

🤖 AI Model Configuration

Supported Model Types

1. Transformers Models

{
    "model_name": "microsoft/Phi-3-mini-4k-instruct",
    "model_type": "text-generation"
}

2. OpenVINO Models

{
    "model_name": "OpenVINO/Phi-3-mini-4k-instruct-fp16-ov",
    "model_type": "openvino"
}

3. GGUF Models

{
    "model_name": "microsoft/Phi-3-mini-4k-instruct-gguf",
    "model_type": "gguf"
}

Automatic Device Detection

The system automatically detects and uses:

• GPU: When CUDA is available
• CPU: Fallback when GPU is not available
• Optimization: Intel OpenVINO for production performance

🔧 Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
REDIS_URL	Redis connection string	Required
SECRET_KEY	Application secret key	Required
JWT_SECRET_KEY	JWT signing key	Required
HF_HOME	Hugging Face cache directory	/tmp/huggingface
TORCH_HOME	PyTorch cache directory	/tmp/torch
WHISPER_CACHE	Whisper model cache	/tmp/whisper
HF_SPACES	Hugging Face Spaces mode	false
PRELOAD_GGUF	Preload GGUF models	false

Model Configuration

The system supports flexible model configuration through model_config.py:

# Default models for different tasks
DEFAULT_MODELS = {
    "text-generation": {
        "primary": "microsoft/Phi-3-mini-4k-instruct",
        "fallback": "facebook/bart-base"
    },
    "openvino": {
        "primary": "OpenVINO/Phi-3-mini-4k-instruct-fp16-ov",
        "fallback": "microsoft/Phi-3-mini-4k-instruct"
    },
    "gguf": {
        "primary": "microsoft/Phi-3-mini-4k-instruct-gguf",
        "fallback": "microsoft/Phi-3-mini-4k-instruct-gguf"
    }
}

🧪 Testing

Run Tests

# Unit tests
python -m pytest tests/

# Smoke test (no model loading)
cd services/ai-service
python run_smoke_test.py

# Integration tests
python -m pytest tests/integration/

Code Quality

# Format code
black .
isort .

# Lint code
flake8 .
mypy .

# Type checking
mypy services/ai-service/src/ai_med_extract/

📊 Monitoring

Health Checks

• Liveness: GET /health/live - Application is running
• Readiness: GET /health/ready - Application is ready to serve requests

Metrics

• Prometheus: GET /metrics - Application and model metrics
• Custom Metrics: Model inference time, success rates, error rates

Logging

• Structured Logging: JSON-formatted logs
• Audit Trails: PHI access and modification logs
• Performance Logs: Model loading and inference timing

🔒 Security Features

HIPAA Compliance

• PHI Scrubbing: Automatic removal of protected health information
• Audit Logging: Comprehensive access and modification logs
• Data Encryption: Secure data handling and storage
• Access Controls: Role-based access to sensitive data

Container Security

• Non-root Containers: Security-hardened container images
• Resource Limits: CPU and memory limits
• Network Policies: Secure network communication
• Secrets Management: Secure handling of sensitive configuration

🚀 Deployment Options

1. Local Development

python -m uvicorn services.ai-service.src.ai_med_extract.main:app --reload

2. Docker

docker run -p 7860:7860 hntai:latest

3. Kubernetes

kubectl apply -f infra/k8s/secure_deployment.yaml

4. Hugging Face Spaces

# Configure for HF Spaces
export HF_SPACES=true
python start_hf_spaces.py

📁 Project Structure

HNTAI/
├── services/
│   └── ai-service/
│       ├── src/ai_med_extract/
│       │   ├── agents/           # AI agents and processors
│       │   ├── api/             # FastAPI routes and management
│       │   ├── utils/           # Utilities and model management
│       │   ├── app.py          # Main application
│       │   └── main.py         # Application entry point
│       ├── docker-compose.yml  # Docker services
│       └── Dockerfile          # Container image
├── infra/
│   └── k8s/                   # Kubernetes manifests
├── monitoring/
│   └── prometheus.yml         # Monitoring configuration
├── database/
│   └── postgresql/           # Database schemas
└── requirements.txt          # Python dependencies

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: python -m pytest
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the /docs endpoint for interactive API documentation
• Issues: Report bugs and feature requests via GitHub Issues
• Discussions: Join community discussions for questions and support

🔄 Changelog

Latest Updates

• ✅ Fixed OpenVINO GPU/CPU auto-detection
• ✅ Improved model loading with fallback mechanisms
• ✅ Enhanced security and HIPAA compliance
• ✅ Added comprehensive monitoring and health checks
• ✅ Optimized for production deployment

---

Built with ❤️ for the medical AI community