AI4PHC Scheduling & Forecasting System

A comprehensive FastAPI-based healthcare management system that provides intelligent patient scheduling using geographic clustering, disease outbreak forecasting, and Hausa language speech-to-text capabilities.

Features

🗓️ Intelligent Appointment Scheduling

• Geographic Clustering: Automatically groups patients by residential location using KMeans clustering
• Smart Scheduling: Schedules patients from the same cluster on similar dates to optimize healthcare delivery
• Capacity Management: Enforces daily appointment limits to prevent facility overload
• Cluster-Based Recommendations: Suggests appointment dates based on cluster patterns

📊 Disease Outbreak Forecasting

• Time Series Analysis: Uses SARIMAX models to forecast disease trends
• Multiple Diseases: Tracks and predicts malaria, cholera, meningitis, and diarrhea cases
• Performance Metrics: Calculates RMSE, MAE, and MAPE for forecast accuracy
• 12-Week Forecasts: Provides forward-looking predictions with confidence intervals

🎤 Speech-to-Text (Hausa Language)

• Audio Processing: Converts audio files to text in Hausa language
• Multi-Format Support: Handles various audio formats (automatically converted to WAV)
• Google Speech Recognition: Leverages Google's speech recognition API

⚙️ Automated Operations

• Daily Clustering Jobs: Automatically re-clusters patients every day at 00:05 (Lagos time)
• Background Processing: Runs intensive tasks asynchronously to maintain API responsiveness
• Health Monitoring: Built-in health check endpoints for system status

Tech Stack

• FastAPI: Modern Python web framework for building APIs
• SQLAlchemy: SQL toolkit and ORM for database operations
• PostgreSQL: Primary database (via psycopg2-binary)
• APScheduler: Background job scheduling
• scikit-learn: Machine learning for KMeans clustering
• statsmodels: SARIMAX time series forecasting
• pandas: Data manipulation and analysis
• SpeechRecognition: Speech-to-text conversion
• pydub: Audio file processing

Installation

Prerequisites

• Python 3.8+
• PostgreSQL database
• FFmpeg (required for audio processing with pydub)

Setup Steps

1. Clone the repository

   git clone https://github.com/Rajput2000/AI4PHC.git
   cd AI4PHC

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. Configure environment variables Create a .env file in the root directory:

   DATABASE_URL=postgresql://username:password@localhost:5432/your_database

5. Initialize the database Ensure your PostgreSQL database is running and tables are created according to the schema in src/DBSchema.py.

6. Run the application

   uvicorn app:app --reload --host 0.0.0.0 --port 8000

API Endpoints

System Health

• GET / or /health
  • Returns database and scheduler status
  • Response includes timestamp in Lagos timezone

Audio Processing

• POST /upload-audio/
  • Upload audio file for Hausa speech-to-text conversion
  • Accepts: Audio files (WAV, MP3, etc.)
  • Returns: Transcribed text

Patient Clustering

• POST /batch-cluster-patients
  • Manually trigger patient clustering job
  • Runs in background
  • Groups patients by geographic proximity

Appointment Scheduling

• POST /schedule
  • Schedule a patient appointment based on cluster assignment
  • Request body:

    {
      "patient_number": "KA-2025-00029",
      "appointment_type_name": "General Consultation",
      "max_per_day": 50
    }

  • Response:

    {
      "status": "scheduled",
      "patient_number": "KA-2025-00029",
      "cluster_id": 3,
      "appointment_type_id": 1,
      "appointment_date": "2025-10-15"
    }

Project Structure

.
├── app.py                      # Main FastAPI application
├── requirements.txt            # Python dependencies
├── notebook.ipynb            
├── .env                        # Environment variables (create this)
├── src/
│   ├── audio_translate.py     # Speech-to-text functionality
│   ├── database.py            # Database connection and session management
│   ├── DBSchema.py            # SQLAlchemy ORM models
│   ├── disease_forecast.py    # SARIMAX forecasting models
│   ├── models.py              # Pydantic request/response schemas
│   ├── scheduler.py           # Patient clustering and scheduling logic
│   └── utils.py               # Utility functions (health checks)
└── recordings/                # Directory for uploaded audio files

Database Schema

Patients Table

• patient_id: Primary key
• patient_number: Unique patient identifier
• residential_latitude: Geographic coordinate
• residential_longitude: Geographic coordinate
• cluster_id: Assigned cluster group

Appointments Table

• appointment_id: Primary key
• patient_id: Foreign key to patients
• appointment_date: Scheduled date
• appointment_type_id: Type of appointment

Scheduled Jobs

• Daily Clustering: Runs at 00:05 (Lagos time) to re-cluster all patients based on updated geographic data

Configuration

Clustering Parameters

• Default clusters: 5
• Batch size: 500 patients per update
• Algorithm: KMeans with k-means++ initialization

Forecasting Parameters

• Model: SARIMAX(1,1,1)(1,1,1,52)
• Forecast horizon: 12 weeks
• Seasonal period: 52 weeks

Scheduling Parameters

• Default max appointments per day: 50
• Default appointment type: "General Consultation"

Performance Considerations

• Connection Pooling: Configured with 10 persistent connections, 20 overflow connections
• Batch Processing: Clustering updates run in batches to prevent database timeouts
• Background Tasks: Intensive operations run asynchronously
• Pool Pre-ping: Ensures connection health before use

Error Handling

• Comprehensive logging throughout the application
• HTTP exceptions with appropriate status codes
• Database transaction rollback on errors
• Graceful scheduler shutdown

Development

Running in Development Mode

uvicorn app:app --reload

Accessing API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Timezone

All timestamps use Africa/Lagos timezone (WAT, UTC+1).