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**:
```bash
git clone <repository-url>
cd HNTAI
```

2. **Create virtual environment**:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. **Install dependencies**:
```bash
pip install -r requirements.txt
```

4. **Set up environment variables**:
```bash
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**:
```bash
# 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**:
```bash
docker build -t hntai:latest .
```

2. **Run with Docker Compose**:
```bash
docker-compose up -d
```

### Kubernetes Deployment

1. **Apply Kubernetes manifests**:
```bash
kubectl apply -f infra/k8s/secure_deployment.yaml
```

2. **Check deployment status**:
```bash
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
```python
{
    "model_name": "microsoft/Phi-3-mini-4k-instruct",
    "model_type": "text-generation"
}
```

#### 2. OpenVINO Models
```python
{
    "model_name": "OpenVINO/Phi-3-mini-4k-instruct-fp16-ov",
    "model_type": "openvino"
}
```

#### 3. GGUF Models
```python
{
    "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`:

```python
# 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
```bash
# 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
```bash
# 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
```bash
python -m uvicorn services.ai-service.src.ai_med_extract.main:app --reload
```

### 2. Docker
```bash
docker run -p 7860:7860 hntai:latest
```

### 3. Kubernetes
```bash
kubectl apply -f infra/k8s/secure_deployment.yaml
```

### 4. Hugging Face Spaces
```bash
# 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**