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
- **Simplified Architecture**: Clean, maintainable codebase with essential 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`
- **Basic Metrics**: Simple performance tracking
- **Structured Logging**: Application logging
- **Audit Logging**: HIPAA-compliant audit trails

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    FastAPI Application                  │
│                      (main.py)                          │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                     │
        ▼                   ▼                     ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Routes     │   │   Agents      │   │   Utils       │
│              │   │               │   │               │
│ - /upload    │   │ - Text        │   │ - Model       │
│ - /transcribe│   │   Extractor   │   │   Manager     │
│ - /generate  │   │ - PHI         │   │ - JSON        │
│   _summary   │   │   Scrubber    │   │   Parser      │
│              │   │ - Patient     │   │ - Config      │
│              │   │   Summary     │   │               │
│              │   │ - Whisper     │   │               │
└──────────────┘   └──────────────┘   └──────────────┘
        │                   │                     │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Models     │   │   Database   │   │   Health     │
│              │   │   (Optional)  │   │              │
│ - Transformers│   │ - Audit Logs │   │ - /health    │
│ - GGUF       │   │   (HIPAA)    │   │ - /metrics   │
│ - OpenVINO   │   │              │   │              │
│ - Whisper    │   │              │   │              │
└──────────────┘   └──────────────┘   └──────────────┘
```

## 🛠️ Installation

### Prerequisites
- Python 3.11+
- CUDA 11.8+ (for GPU support)
- Docker (for containerized deployment)
- PostgreSQL 13+ (optional - for audit logs)

### 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"  # Optional - for audit logs
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 (optional - for audit logs) | Not 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
# The app.py file automatically detects HF Spaces environment
```

## 📁 Project Structure

```
HNTAI/
├── services/
│   └── ai-service/
│       └── src/
│           └── ai_med_extract/
│               ├── agents/              # Core agents (simplified)
│               │   ├── text_extractor.py
│               │   ├── phi_scrubber.py
│               │   ├── patient_summary_agent.py
│               │   └── medical_data_extractor.py
│               ├── api/
│               │   └── routes_fastapi.py  # All routes in one file
│               ├── utils/
│               │   ├── unified_model_manager.py  # Single model manager
│               │   ├── robust_json_parser.py
│               │   └── model_config.py
│               ├── app.py               # FastAPI app setup
│               ├── main.py              # Entry point
│               ├── health_endpoints.py  # Simple health checks
│               └── database_audit.py     # HIPAA audit logging
├── docs/
│   ├── hf-spaces/              # HF Spaces deployment guides
│   └── archive/                # Archived documentation
├── app.py                      # HF Spaces wrapper (minimal)
├── preload_models.py           # Model preloading
├── requirements.txt
└── README.md
```

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

## 📚 Documentation

### Main Documentation
- **README_DEPLOYMENT.md** - Quick deployment reference for HF Spaces
- **services/ai-service/README.md** - Detailed service documentation

### Deployment Guides (docs/hf-spaces/)
- **HF_SPACES_QUICKSTART.md** - 10-minute deployment guide
- **DEPLOYMENT_CHECKLIST.md** - Step-by-step checklist
- **MODEL_USAGE_GUIDE.md** - Model configuration and usage
- **HF_SPACES_DEPLOYMENT.md** - Complete deployment reference

### Additional Resources
- **docs/archive/** - Historical documentation and summaries
- **services/ai-service/src/ai_med_extract/PRODUCTION_READY_SUMMARY.md** - Production notes
- **services/ai-service/src/ai_med_extract/utils/INTEGRATION_GUIDE.md** - Integration guide

## 🆘 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
- ✅ **Simplified architecture** - Removed over-engineered components
- ✅ **Unified model management** - Single model manager for all model types
- ✅ **Consolidated routes** - All API endpoints in one file
- ✅ **Simplified agents** - Removed duplicate implementations
- ✅ **Enhanced security and HIPAA compliance** - Maintained audit logging
- ✅ **Cleaner codebase** - 50% fewer files, 40% less code

---

**Built with ❤️ for the medical AI community**