Ahuvista-NN: Modular Multi-Modal Neural Network for Healthcare

A lightweight, Rust-based neural network library optimized for multi-modal data processing in low-compute environments, with a focus on maternal health outcome predictions.

🌟 Key Features

🧩 Modular Multi-Modal Architecture: Selectively enable/disable tabular, temporal, text, and image modalities based on available data
🔗 Late Fusion Strategy: Extracts specialized features from each modality before combination for optimal performance
⚖️ Population-Informed Weighting: Addresses class imbalance with demographic stratification and cause-specific weights
⚡ Optimized for Efficiency: Designed to run on low-compute resources (edge devices, embedded systems, limited infrastructure)
🔄 Complete Data Pipeline: Includes preprocessors and transformers for all supported data types
⚙️ Flexible Configuration: Configure via JSON files, programmatic API, or command-line arguments
🚀 Production-Ready Inference: Lightweight prediction binary optimized for deployment
📊 Bayesian Calibration: Probability calibration based on population prevalence for reliable risk assessment

🚀 Installation

Prerequisites

Rust: 1.70 or higher (Install Rust)
Cargo: Comes bundled with Rust
Operating Systems: Linux, macOS, Windows

Build from Source

# Clone the repository
git clone https://github.com/dandychux/ahuvista-nn.git
cd ahuvista-nn

# Build the project (debug mode)
cargo build

# Build optimized release version
cargo build --release

# Run tests to verify installation
cargo test --release

Compiled Binaries

After building, you'll find two binaries in target/release/:

ahuvista-train: Training binary with full configuration options
ahuvista-predict: Lightweight inference binary for production deployment

Verify Installation

# Check training binary
cargo run --release --bin ahuvista-train -- --help

# Check prediction binary
cargo run --release --bin ahuvista-predict -- --help

🏃 Quick Start

1. Train a Simple Model (Tabular Data Only)

# Train with minimal configuration
cargo run --release --bin ahuvista-train -- \
  --modalities tabular \
  --epochs 20 \
  --batch-size 32 \
  --verbose

2. Train with Multiple Modalities

# Train with tabular and temporal data
cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal \
  --epochs 50 \
  --batch-size 32 \
  --learning-rate 0.001 \
  --output-dir ./models

3. Make a Prediction

First, create an input file patient_data.json:

{
  "patient_id": "PAT-001",
  "tabular": [0.5, 0.3, 0.8, 0.1, 0.9, 0.4, 0.7, 0.2, 0.6, 0.5],
  "temporal": [
    [120.0, 80.0, 98.6, 72.0, 16.0],
    [125.0, 82.0, 98.8, 75.0, 18.0]
  ]
}

Then run prediction:

cargo run --release --bin ahuvista-predict -- \
  --model models/maternal_mortality_model_modular.bin \
  --modalities tabular,temporal \
  --input patient_data.json \
  --output result.json

🏗️ Architecture Overview

System Design

Ahuvista-NN uses a late fusion architecture where each modality is processed by a specialized neural network before features are combined:

┌─────────────────────────────────────────────────────────────────────┐
│                    Modular Late Fusion Network                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────┐│
│  │   Tabular    │  │   Temporal   │  │     Text     │  │ Image  ││
│  │   Network    │  │   Network    │  │   Network    │  │Network ││
│  │ (Feed-Fwd)   │  │    (RNN)     │  │   (RNN +     │  │ (CNN)  ││
│  │              │  │              │  │  Embedding)  │  │        ││
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └───┬────┘│
│         │                 │                 │              │      │
│         │    Feature      │    Feature      │   Feature    │      │
│         │    Vector       │    Vector       │   Vector     │      │
│         │    (16-32d)     │    (16-32d)     │   (32-64d)   │      │
│         │                 │                 │              │      │
│         └─────────────────┴─────────────────┴──────────────┘      │
│                                  │                                 │
│                          ┌───────▼────────┐                        │
│                          │  Concatenation │                        │
│                          │  Fusion Layer  │                        │
│                          └───────┬────────┘                        │
│                                  │                                 │
│                          ┌───────▼────────┐                        │
│                          │   Classifier   │                        │
│                          │    Network     │                        │
│                          │   (64→32→1)    │                        │
│                          └───────┬────────┘                        │
│                                  │                                 │
│                          ┌───────▼────────┐                        │
│                          │   Prediction   │                        │
│                          │  Risk Score    │                        │
│                          │    (0.0-1.0)   │                        │
│                          └────────────────┘                        │
└─────────────────────────────────────────────────────────────────────┘

Supported Modalities

Modality	Description	Network Type	Use Cases
Tabular	Structured clinical data	Feed-forward MLP	Demographics, lab results, vital signs
Temporal	Time-series sequences	Recurrent (RNN)	Continuous monitoring, longitudinal data
Text	Unstructured text	RNN + Embeddings	Clinical notes, reports, documentation
Image	Visual data	Convolutional (CNN)	Medical imaging, ultrasounds, photographs

Why Late Fusion?

Modality-Specific Learning: Each network learns patterns specific to its data type
Flexible Architecture: Easy to add/remove modalities without retraining everything
Computational Efficiency: Only processes enabled modalities
Interpretability: Can analyze contribution of each modality independently

🎓 Training Models

Ahuvista-NN offers three methods for training models, each suited for different use cases.

1. Configuration File Approach (Recommended)

Best for: Production deployments, reproducible experiments, complex configurations

Step 1: Create Configuration File

Create config.json:

{
  "modalities": {
    "use_tabular": true,
    "use_temporal": true,
    "use_text": false,
    "use_image": false
  },
  "data_paths": {
    "data_dir": "datasets",
    "patient_id_column": "PatientID",
    "tabular_files": ["patient_demographics.csv", "lab_results.csv"],
    "temporal_files": ["vitals_timeseries.csv"],
    "text_files": null,
    "image_files": null
  },
  "training": {
    "epochs": 100,
    "batch_size": 32,
    "learning_rate": 0.001
  },
  "model": {
    "tabular_hidden_sizes": [128, 64],
    "tabular_output_size": 32,
    "temporal_hidden_size": 64,
    "temporal_output_size": 32,
    "text_embedding_dim": 100,
    "text_hidden_size": 64,
    "text_max_vocab": 10000,
    "image_channels": 3,
    "image_height": 224,
    "image_width": 224,
    "classifier_hidden_sizes": [128, 64]
  }
}

Step 2: Train with Configuration

cargo run --release --bin ahuvista-train -- --config config.json

Step 3: Override Specific Parameters

# Use config but override training parameters
cargo run --release --bin ahuvista-train -- \
  --config config.json \
  --epochs 200 \
  --learning-rate 0.0005 \
  --batch-size 64

2. Command-Line Interface

Best for: Quick experiments, testing, simple configurations

Basic Training

cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal \
  --epochs 50 \
  --batch-size 32 \
  --learning-rate 0.001 \
  --output-dir ./trained_models \
  --verbose

All CLI Options

Option	Short	Description	Example
`--config`	`-c`	Path to JSON config file	`--config config.json`
`--modalities`	`-m`	Comma-separated modalities	`--modalities tabular,text`
`--epochs`	`-e`	Number of training epochs	`--epochs 100`
`--batch-size`	`-b`	Training batch size	`--batch-size 64`
`--learning-rate`	`-l`	Learning rate	`--learning-rate 0.001`
`--output-dir`	`-o`	Model output directory	`--output-dir ./models`
`--verbose`	`-v`	Enable verbose logging	`--verbose`

Examples

# Quick test with verbose output
cargo run --release --bin ahuvista-train -- \
  --modalities tabular \
  --epochs 10 \
  --verbose

# Production training with all options
cargo run --release --bin ahuvista-train -- \
  --config production.json \
  --epochs 200 \
  --batch-size 64 \
  --learning-rate 0.0001 \
  --output-dir ./production_models

# Multi-modal with custom output
cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal,text,image \
  --epochs 150 \
  --batch-size 32 \
  --output-dir ./multimodal_models

3. Programmatic API

Best for: Custom training pipelines, research, integration with other systems

use ahuvista_nn::{
    config::{ModalityConfig, Settings},
    core::fusion_modular::{LateFusionNet, MultiModalInput},
    training::training_loop::TrainingConfig,
};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Configure modalities
    let modality_config = ModalityConfig {
        use_tabular: true,
        use_temporal: true,
        use_text: false,
        use_image: false,
    };

    // 2. Build model
    let mut model = LateFusionNet::new(
        modality_config,
        Some((10, vec![64, 32], 16)),  // tabular: (input_size, hidden_layers, output_size)
        Some((5, 32, 16)),              // temporal: (input_size, hidden_size, output_size)
        None,                            // text: disabled
        None,                            // image: disabled
        &[64, 32],                      // classifier hidden sizes
    )?;

    println!("Model created with modalities: {:?}", model.enabled_modalities());

    // 3. Load and prepare data
    // ... your data loading code ...

    // 4. Configure training
    let training_config = TrainingConfig {
        epochs: 50,
        batch_size: 32,
        learning_rate: 0.001,
        val_frequency: 1,
    };

    // 5. Train model
    // ... your training loop ...

    // 6. Save model
    model.save("models/my_model.bin")?;

    Ok(())
}

Advanced: Dynamic Modality Selection

fn create_model_from_available_data(
    has_tabular: bool,
    has_temporal: bool,
    has_text: bool,
    has_image: bool,
) -> Result<LateFusionNet, Box<dyn std::error::Error>> {
    // Build configuration from available data
    let config = ModalityConfig {
        use_tabular: has_tabular,
        use_temporal: has_temporal,
        use_text: has_text,
        use_image: has_image,
    };

    // Validate at least one modality
    config.validate()?;

    // Build model with appropriate parameters
    let model = LateFusionNet::new(
        config,
        if has_tabular { Some((10, vec![64, 32], 16)) } else { None },
        if has_temporal { Some((5, 32, 16)) } else { None },
        if has_text { Some((HashMap::new(), 50, 32)) } else { None },
        if has_image { Some((3, 224, 224)) } else { None },
        &[64, 32],
    )?;

    Ok(model)
}

🔮 Making Predictions

Single Prediction

Step 1: Prepare Input Data

Create patient_input.json:

{
  "patient_id": "PAT-12345",
  "tabular": [0.5, 0.3, 0.8, 0.1, 0.9, 0.4, 0.7, 0.2, 0.6, 0.5],
  "temporal": [
    [120.0, 80.0, 98.6, 72.0, 16.0],
    [125.0, 82.0, 98.8, 75.0, 18.0],
    [130.0, 85.0, 99.0, 78.0, 20.0]
  ],
  "text": null,
  "image_path": null
}

Step 2: Run Prediction

cargo run --release --bin ahuvista-predict -- \
  --model models/maternal_mortality_model_modular.bin \
  --config config.json \
  --input patient_input.json \
  --output prediction_result.json

Or using modality specification:

cargo run --release --bin ahuvista-predict -- \
  --model models/model.bin \
  --modalities tabular,temporal \
  --input patient_input.json \
  --output result.json

Step 3: View Results

Output file prediction_result.json:

{
  "risk_score": 0.73,
  "calibrated_score": null,
  "risk_category": "HIGH",
  "confidence": 0.89,
  "modalities_used": ["tabular", "temporal"],
  "patient_id": "PAT-12345",
  "timestamp": "2024-01-15T10:30:00Z"
}

Batch Predictions

Process multiple patients efficiently:

Step 1: Organize Input Files

mkdir patient_inputs
# Add patient_001.json, patient_002.json, patient_003.json, etc.

Step 2: Run Batch Prediction

cargo run --release --bin ahuvista-predict -- \
  --model models/model.bin \
  --config config.json \
  --input patient_inputs \
  --output batch_results.json \
  --batch

Step 3: Review Batch Results

Output batch_results.json contains an array of all predictions:

[
  {
    "risk_score": 0.73,
    "risk_category": "HIGH",
    "patient_id": "PAT-001",
    ...
  },
  {
    "risk_score": 0.24,
    "risk_category": "LOW",
    "patient_id": "PAT-002",
    ...
  }
]

Calibrated Predictions

Apply Bayesian calibration for more accurate probability estimates:

cargo run --release --bin ahuvista-predict -- \
  --model models/model.bin \
  --config config.json \
  --input patient.json \
  --calibrate 0.001 \
  --output result.json

The --calibrate parameter specifies the population prevalence (e.g., 0.001 = 0.1% prevalence).

Why Use Calibration?

Adjusts predictions based on known population prevalence
Provides more reliable probability estimates
Crucial for imbalanced datasets
Recommended for clinical decision support

🎛️ Modality Selection Guide

Understanding Modalities

Each modality processes a different type of healthcare data:

Modality	Data Type	Examples	When to Use
Tabular	Structured	Demographics, lab results, vitals	Always include if available
Temporal	Time-series	Continuous monitoring, trends	When tracking changes over time
Text	Unstructured	Clinical notes, reports	Rich qualitative information available
Image	Visual	Ultrasounds, X-rays, photos	Visual diagnosis required

Common Configuration Patterns

Pattern 1: Clinical Data Only (Tabular + Temporal)

Use Case: EMR/EHR systems with structured data

cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal \
  --epochs 50

Configuration:

{
  "modalities": {
    "use_tabular": true,
    "use_temporal": true,
    "use_text": false,
    "use_image": false
  }
}

Pattern 2: Medical Imaging Focus

Use Case: Radiology, ultrasound analysis

cargo run --release --bin ahuvista-train -- \
  --modalities image \
  --epochs 100

Pattern 3: Documentation-Rich System

Use Case: Systems with extensive clinical notes

cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal,text \
  --epochs 75

Pattern 4: Full Multi-Modal (All Data Types)

Use Case: Comprehensive healthcare systems with all data types

cargo run --release --bin ahuvista-train -- \
  --modalities tabular,temporal,text,image \
  --epochs 150

Modality Selection Decision Tree

Do you have structured patient data?
├─ YES → Enable TABULAR
│   │
│   └─ Do you have time-series data?
│       ├─ YES → Enable TEMPORAL
│       └─ NO → Continue
│
└─ Do you have clinical notes?
    ├─ YES → Enable TEXT
    └─ NO → Continue

Do you have medical images?
├─ YES → Enable IMAGE
└─ NO → Complete configuration

Performance Considerations

Configuration	Memory	Speed	Accuracy Potential
Tabular only	~50MB	Very Fast	Good
Tabular + Temporal	~75MB	Fast	Better
Tabular + Text	~100MB	Moderate	Better
Tabular + Image	~150MB	Moderate	Better
All modalities	~200MB	Slower	Best

📊 Data Format Specifications

Tabular Data

Format: CSV files with headers

Requirements:

Must include PatientID column (or configured identifier)
Numeric features only
Missing values should be imputed before training

Example (patient_data.csv):

PatientID,Age,BMI,BloodPressure,HeartRate,Temperature,Hemoglobin,Glucose,RiskFactor1,RiskFactor2
PAT-001,28,24.5,120,75,98.6,12.5,95,0.8,0.3
PAT-002,35,28.1,130,82,99.1,11.8,110,0.6,0.5
PAT-003,22,22.3,115,70,98.4,13.2,88,0.2,0.1

Temporal Data

Format: CSV with timestamp column

Requirements:

Must include PatientID column
Must include Timestamp or time-ordered rows
Each patient can have multiple time points

Example (vitals_timeseries.csv):

PatientID,Timestamp,SystolicBP,DiastolicBP,Temperature,HeartRate,RespiratoryRate
PAT-001,2024-01-01 08:00,120,80,98.6,72,16
PAT-001,2024-01-01 12:00,125,82,98.8,75,18
PAT-001,2024-01-01 16:00,130,85,99.0,78,20
PAT-002,2024-01-01 08:00,135,88,99.2,85,22

Text Data

Format: Plain text files or CSV with text column

Requirements:

One document per patient
UTF-8 encoding
Vocabulary will be built automatically

Example (clinical_notes.txt):

PAT-001: Patient presents with mild hypertension. Blood pressure elevated but stable...
PAT-002: Routine prenatal visit. Patient reports feeling well. No complications noted...

Image Data

Format: Standard image formats (JPG, PNG, TIFF)

Requirements:

Images will be resized to configured dimensions (default 224x224)
RGB or grayscale
One image per patient (or multiple images in directory structure)

Directory Structure:

images/
├── PAT-001.jpg
├── PAT-002.png
├── PAT-003.jpg

Prediction Input Format

JSON Structure:

{
  "patient_id": "string (optional)",
  "tabular": [array of numbers] or null,
  "temporal": [[array of numbers per timestep]] or null,
  "text": "string" or null,
  "image_path": "path/to/image.jpg" or null
}

Complete Example:

{
  "patient_id": "PAT-12345",
  "tabular": [28.0, 24.5, 120.0, 75.0, 98.6, 12.5, 95.0, 0.8, 0.3, 0.1],
  "temporal": [
    [120.0, 80.0, 98.6, 72.0, 16.0],
    [125.0, 82.0, 98.8, 75.0, 18.0],
    [130.0, 85.0, 99.0, 78.0, 20.0]
  ],
  "text": "Patient presents with mild hypertension during routine prenatal visit.",
  "image_path": "images/ultrasound_001.jpg"
}

⚙️ Configuration Reference

Complete Configuration Schema

{
  "modalities": {
    "use_tabular": true,      // Enable/disable tabular data processing
    "use_temporal": true,     // Enable/disable temporal/time-series processing
    "use_text": false,        // Enable/disable text/NLP processing
    "use_image": false        // Enable/disable image processing
  },
  "data_paths": {
    "data_dir": "datasets",             // Root directory for all data files
    "patient_id_column": "PatientID",   // Column name for patient identifiers
    "tabular_files": ["file1.csv", "file2.csv"],    // List of tabular CSV files
    "temporal_files": ["timeseries.csv"],            // List of temporal CSV files
    "text_files": ["notes.txt", "reports.txt"],      // List of text files
    "image_files": ["images/", "scans/"]             // Image directories or file lists
  },
  "training": {
    "epochs": 50,              // Number of complete passes through training data
    "batch_size": 32,          // Number of samples per training batch
    "learning_rate": 0.001     // Learning rate for gradient descent
  },
  "model": {
    // Tabular network architecture
    "tabular_hidden_sizes": [64, 32],   // Hidden layer sizes (2 layers: 64→32 neurons)
    "tabular_output_size": 16,           // Size of tabular feature vector

    // Temporal network architecture
    "temporal_hidden_size": 32,          // RNN hidden state size
    "temporal_output_size": 16,          // Size of temporal feature vector

    // Text network architecture
    "text_embedding_dim": 50,            // Word embedding dimension
    "text_hidden_size": 32,              // Text RNN hidden state size
    "text_max_vocab": 5000,              // Maximum vocabulary size

    // Image network architecture
    "image_channels": 3,                 // Number of image channels (3=RGB, 1=grayscale)
    "image_height": 224,                 // Target image height in pixels
    "image_width": 224,                  // Target image width in pixels

    // Classifier network
    "classifier_hidden_sizes": [64, 32]  // Final classifier hidden layers
  }
}

Configuration Parameter Guide

Modalities Section

Parameter	Type	Default	Description
`use_tabular`	boolean	`true`	Process structured tabular data
`use_temporal`	boolean	`true`	Process time-series sequences
`use_text`	boolean	`false`	Process unstructured text
`use_image`	boolean	`false`	Process image data

Note: At least one modality must be enabled.

Training Section

Parameter	Type	Range	Recommended	Description
`epochs`	integer	1-1000	50-100	Full training passes
`batch_size`	integer	1-256	16-64	Samples per batch
`learning_rate`	float	0.00001-0.1	0.001-0.01	Gradient step size

Tuning Tips:

Small datasets (< 1000 samples): Lower batch size (8-16), more epochs (100-200)
Medium datasets (1000-10000): Standard settings (batch=32, epochs=50-100)
Large datasets (> 10000): Larger batch size (64-128), fewer epochs (20-50)

Model Architecture Section

Tabular Network:

tabular_hidden_sizes: List of hidden layer sizes. Example: [128, 64] creates two layers
tabular_output_size: Feature vector dimension (typically 16-32)

Temporal Network:

temporal_hidden_size: RNN memory size (typically 32-64)
temporal_output_size: Feature vector dimension (typically 16-32)

Text Network:

text_embedding_dim: Word vector size (typically 50-300)
text_hidden_size: RNN memory size (typically 32-128)
text_max_vocab: Vocabulary limit (typically 5000-20000)

Image Network:

image_channels: 3 for RGB, 1 for grayscale
image_height/image_width: Target dimensions (commonly 224x224 or 256x256)

Classifier:

classifier_hidden_sizes: Final layers that combine modality features

🎯 Advanced Usage

Custom Training with Population Weighting

use ahuvista_nn::training::balancing::{
    compute_sample_weights,
    BayesianCalibrator,
    CauseWeights
};
use std::collections::HashMap;

// Define population-level cause frequencies
let mut cause_frequencies = HashMap::new();
cause_frequencies.insert(0, 0.25); // Hemorrhage: 25%
cause_frequencies.insert(1, 0.20); // Hypertensive disorders: 20%
cause_frequencies.insert(2, 0.15); // Infection: 15%
cause_frequencies.insert(3, 0.10); // Thromboembolism: 10%
cause_frequencies.insert(4, 0.30); // Other: 30%

let cause_weights = CauseWeights::from_population_frequencies(&cause_frequencies);

// Define demographic strata
let mut stratum_multipliers = HashMap::new();
stratum_multipliers.insert("urban_young".to_string(), 1.0);
stratum_multipliers.insert("urban_old".to_string(), 1.2);
stratum_multipliers.insert("rural_young".to_string(), 1.5);
stratum_multipliers.insert("rural_old".to_string(), 1.8);

// Compute sample weights
let sample_weights = compute_sample_weights(
    &targets,
    Some(&patient_strata),
    Some(&stratum_multipliers)
);

Model Inspection and Debugging

// Check enabled modalities
let modalities = model.enabled_modalities();
println!("Active modalities: {:?}", modalities);

// Verify specific modality
if model.is_enabled("tabular") {
    println!("Tabular processing enabled");
}

// Get model configuration
let config = model.config();
println!("Modality config: {:?}", config);

Save and Load Models

// Save trained model
model.save("models/my_model.bin")?;

// Load model for inference
let mut loaded_model = LateFusionNet::new(
    config,
    tabular_params,
    temporal_params,
    text_params,
    image_params,
    &classifier_sizes,
)?;

loaded_model.load("models/my_model.bin")?;

Custom Prediction Pipeline

use ahuvista_nn::core::fusion_modular::MultiModalInput;

// Build input programmatically
let mut input = MultiModalInput::new();

if has_tabular_data {
    input = input.with_tabular(tabular_vector);
}

if has_temporal_data {
    input = input.with_temporal(temporal_sequences);
}

// Make prediction
let risk_score = model.predict(input)?;

// Apply custom thresholds
let risk_level = if risk_score > 0.8 {
    "CRITICAL"
} else if risk_score > 0.5 {
    "HIGH"
} else {
    "MODERATE"
};

📈 Performance & Benchmarks

Computational Requirements

Configuration	RAM Usage	Training Time*	Inference Time**
Tabular only	~50 MB	2-5 min	< 10 ms
Tabular + Temporal	~75 MB	5-10 min	< 20 ms
Tabular + Text	~100 MB	10-15 min	< 30 ms
Tabular + Image	~150 MB	15-25 min	< 50 ms
All modalities	~200 MB	30-45 min	< 100 ms

* Training time for 10,000 samples, 50 epochs on CPU (Intel i7) ** Single prediction on CPU

Optimization Tips

For Faster Training:

Use release mode: cargo build --release
Increase batch size on machines with more RAM
Disable unused modalities
Use smaller network architectures for prototyping

For Lower Memory:

Reduce batch size
Use smaller hidden layer sizes
Limit vocabulary size for text
Reduce image dimensions

For Faster Inference:

Compile with optimizations: --release
Use minimal modalities needed
Batch predictions when possible
Consider model quantization (future feature)

Scalability

Small datasets (< 1,000 samples): Runs on laptops, embedded systems
Medium datasets (1,000-50,000 samples): Standard workstations
Large datasets (> 50,000 samples): Server-grade hardware recommended

📚 Examples

Example 1: Quick Prototype with Tabular Data

# Step 1: Create minimal config
cat > quick_config.json << 'EOF'
{
  "modalities": {
    "use_tabular": true,
    "use_temporal": false,
    "use_text": false,
    "use_image": false
  },
  "training": {
    "epochs": 20,
    "batch_size": 16,
    "learning_rate": 0.001
  }
}
EOF

# Step 2: Train
cargo run --release --bin ahuvista-train -- \
  --config quick_config.json \
  --verbose

# Step 3: Test prediction
cat > test_input.json << 'EOF'
{
  "tabular": [0.5, 0.3, 0.8, 0.1, 0.9, 0.4, 0.7, 0.2, 0.6, 0.5]
}
EOF

cargo run --release --bin ahuvista-predict -- \
  --model models/maternal_mortality_model_modular.bin \
  --modalities tabular \
  --input test_input.json

Example 2: Production Multi-Modal System

# Step 1: Create production configuration
cat > production_config.json << 'EOF'
{
  "modalities": {
    "use_tabular": true,
    "use_temporal": true,
    "use_text": true,
    "use_image": false
  },
  "data_paths": {
    "data_dir": "/data/healthcare",
    "patient_id_column": "MRN",
    "tabular_files": ["demographics.csv", "labs.csv"],
    "temporal_files": ["vitals_monitoring.csv"],
    "text_files": ["clinical_notes.txt"]
  },
  "training": {
    "epochs": 150,
    "batch_size": 64,
    "learning_rate": 0.0005
  },
  "model": {
    "tabular_hidden_sizes": [256, 128, 64],
    "tabular_output_size": 64,
    "temporal_hidden_size": 128,
    "temporal_output_size": 64,
    "text_embedding_dim": 200,
    "text_hidden_size": 128,
    "text_max_vocab": 15000,
    "classifier_hidden_sizes": [256, 128]
  }
}
EOF

# Step 2: Train with production settings
cargo run --release --bin ahuvista-train -- \
  --config production_config.json \
  --output-dir /models/production

# Step 3: Deploy for inference with calibration
cargo run --release --bin ahuvista-predict -- \
  --model /models/production/maternal_mortality_model_modular.bin \
  --config production_config.json \
  --input /data/inference/patient.json \
  --calibrate 0.0015 \
  --output /results/prediction.json

Example 3: Batch Processing for Research

# Process 1000 patients
mkdir -p batch_inputs batch_outputs

# Generate input files (your data preparation script)
# ...

# Run batch prediction
cargo run --release --bin ahuvista-predict -- \
  --model models/research_model.bin \
  --config research_config.json \
  --input batch_inputs \
  --output batch_outputs/results.json \
  --batch \
  --calibrate 0.001

Example 4: Experimentation with Different Architectures

# Test different modality combinations
for combo in "tabular" "temporal" "tabular,temporal" "tabular,text" "all"; do
  echo "Testing: $combo"

  if [ "$combo" = "all" ]; then
    modalities="tabular,temporal,text,image"
  else
    modalities="$combo"
  fi

  cargo run --release --bin ahuvista-train -- \
    --modalities $modalities \
    --epochs 30 \
    --output-dir experiments/$combo
done

🔧 Troubleshooting

Common Issues and Solutions

Issue: "At least one modality must be enabled"

Cause: No modalities selected in configuration

Solution:

# Ensure at least one modality is enabled
cargo run --release --bin ahuvista-train -- \
  --modalities tabular \
  --epochs 10

Issue: "Tabular data required but not provided"

Cause: Model expects tabular data but input doesn't include it

Solution: Ensure input JSON includes all required modalities:

{
  "tabular": [/* your data */],
  "temporal": null
}

Issue: Model training is too slow

Solutions:

Reduce batch size: --batch-size 16
Use fewer epochs: --epochs 20
Disable unnecessary modalities
Ensure using release mode: --release

Issue: Out of memory during training

Solutions:

Reduce batch size: --batch-size 8
Use smaller network architectures
Process fewer modalities simultaneously
Reduce image dimensions in config

Issue: Predictions seem uncalibrated

Solution: Use Bayesian calibration:

cargo run --release --bin ahuvista-predict -- \
  --model model.bin \
  --config config.json \
  --input patient.json \
  --calibrate 0.001

Issue: "Failed to load config file"

Causes & Solutions:

Invalid JSON syntax → Validate JSON with jsonlint
File not found → Check path is correct
Wrong permissions → Ensure read permissions on file

Getting Help

Check Logs: Use --verbose flag for detailed output
Review Examples: See the examples/ directory
Read Documentation: Check inline code documentation
Open an Issue: GitHub Issues

🤝 Contributing

Contributions are welcome! We appreciate:

🐛 Bug reports and fixes
📚 Documentation improvements
✨ New features and enhancements
🧪 Additional tests and benchmarks

Development Setup

# Clone repository
git clone https://github.com/dandychux/ahuvista-nn.git
cd ahuvista-nn

# Create feature branch
git checkout -b feature/my-new-feature

# Make changes and test
cargo test
cargo fmt
cargo clippy

# Submit pull request

Code Style

Follow Rust standard formatting (cargo fmt)
Pass all clippy lints (cargo clippy)
Add tests for new features
Update documentation as needed

📄 License

This project is dual-licensed under:

MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
Apache License 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

You may choose either license for your use.

📧 Contact & Support

Author: Chukwuma Okoroji
Email: dandychux@gmail.com
GitHub: @dandychux
Issues: GitHub Issues

🙏 Acknowledgments

This project was developed to improve maternal health outcomes through accessible, efficient AI systems that can run in resource-constrained environments.

Special thanks to the open-source Rust community and healthcare professionals who provided domain expertise.

⚠️ Important Notices

Clinical Use Disclaimer

This is a research and development tool. It is NOT approved for clinical use.

Always consult qualified healthcare professionals for medical decisions
Do not use as the sole basis for diagnosis or treatment
Predictions should be validated in clinical context
Follow all applicable regulations and guidelines

Data Privacy

When using this system with patient data:

Comply with HIPAA, GDPR, and other relevant regulations
Implement appropriate data security measures
De-identify data when possible
Document all data handling procedures
Obtain necessary approvals and consents

Research Use

If using for research:

Cite this project appropriately
Follow ethical research guidelines
Obtain IRB approval when required
Report limitations and biases honestly

🚀 Quick Reference Card

Training

# Basic
cargo run --release --bin ahuvista-train -- --modalities tabular --epochs 20

# With config
cargo run --release --bin ahuvista-train -- --config config.json

# Full options
cargo run --release --bin ahuvista-train -- \
  --config config.json \
  --modalities tabular,temporal \
  --epochs 100 \
  --batch-size 32 \
  --learning-rate 0.001 \
  --output-dir ./models \
  --verbose

Prediction

# Single
cargo run --release --bin ahuvista-predict -- \
  --model model.bin \
  --config config.json \
  --input patient.json

# Batch
cargo run --release --bin ahuvista-predict -- \
  --model model.bin \
  --config config.json \
  --input patients_dir \
  --batch

# Calibrated
cargo run --release --bin ahuvista-predict -- \
  --model model.bin \
  --config config.json \
  --input patient.json \
  --calibrate 0.001

Modalities

tabular - Structured data
temporal - Time-series
text - Clinical notes
image - Medical images

Combine with commas: --modalities tabular,temporal,text

Version: 2.0.0 Last Updated: 2025 Status: Active Development

ahuvista-nn 0.1.1

Ahuvista-NN: Modular Multi-Modal Neural Network for Healthcare

🌟 Key Features

📋 Table of Contents

🚀 Installation

Prerequisites

Build from Source

Compiled Binaries

Verify Installation

🏃 Quick Start

1. Train a Simple Model (Tabular Data Only)

2. Train with Multiple Modalities

3. Make a Prediction

🏗️ Architecture Overview

System Design

Supported Modalities

Why Late Fusion?

🎓 Training Models

1. Configuration File Approach (Recommended)

Step 1: Create Configuration File

Step 2: Train with Configuration

Step 3: Override Specific Parameters

2. Command-Line Interface

Basic Training

All CLI Options

Examples

3. Programmatic API

Advanced: Dynamic Modality Selection

🔮 Making Predictions

Single Prediction

Step 1: Prepare Input Data

Step 2: Run Prediction

Step 3: View Results

Batch Predictions

Step 1: Organize Input Files

Step 2: Run Batch Prediction

Step 3: Review Batch Results

Calibrated Predictions

🎛️ Modality Selection Guide

Understanding Modalities

Common Configuration Patterns

Pattern 1: Clinical Data Only (Tabular + Temporal)

Pattern 2: Medical Imaging Focus

Pattern 3: Documentation-Rich System

Pattern 4: Full Multi-Modal (All Data Types)

Modality Selection Decision Tree

Performance Considerations

📊 Data Format Specifications

Tabular Data

Temporal Data

Text Data

Image Data

Prediction Input Format

⚙️ Configuration Reference

Complete Configuration Schema

Configuration Parameter Guide

Modalities Section

Training Section

Model Architecture Section

🎯 Advanced Usage

Custom Training with Population Weighting

Model Inspection and Debugging

Save and Load Models

Custom Prediction Pipeline

📈 Performance & Benchmarks

Computational Requirements

Optimization Tips

Scalability

📚 Examples

Example 1: Quick Prototype with Tabular Data

Example 2: Production Multi-Modal System

Example 3: Batch Processing for Research

Example 4: Experimentation with Different Architectures

🔧 Troubleshooting

Common Issues and Solutions

Issue: "At least one modality must be enabled"

Issue: "Tabular data required but not provided"

Issue: Model training is too slow

Issue: Out of memory during training

Issue: Predictions seem uncalibrated