README.md

---
license: apache-2.0
tags:
- graph-neural-networks
- nutrition
- healthcare
- recommendation-system
- ensemble
language:
- en
library_name: pytorch
---

# MzeeChakula Nutrition Ensemble

**Graph Neural Network Ensemble for Elderly Nutrition Planning in Uganda**

## Model Description

Production-ready ensemble combining three Graph Neural Networks:
- **CRGN (40%)** - Compositional reasoning
- **HetGNN (35%)** - Heterogeneous graph handling  
- **GAT (25%)** - Attention mechanisms

**Performance:**
- 5.36M parameters (~20.4 MB)
- ~15ms inference (CPU), ~3ms (GPU)
- 90% link prediction AUC

## Quick Start

```python
from huggingface_hub import snapshot_download
import sys

# Download model
model_path = snapshot_download(repo_id="YOUR_USERNAME/mzeechakula-nutrition")
sys.path.append(model_path)

# Load and use
from nutrition_ensemble import NutritionEnsemble

ensemble = NutritionEnsemble(model_path)
recommendations = ensemble.recommend(user_id=0, top_k=10)
print(recommendations)
```

## Installation

```bash
pip install torch numpy pandas huggingface_hub
```

## Usage

### Basic Recommendations

```python
from nutrition_ensemble import NutritionEnsemble

# Initialize
ensemble = NutritionEnsemble(".")

# Get top 10 recommendations
recs = ensemble.recommend(user_id=0, top_k=10)
print(recs)
```

### With Exclusions

```python
# Exclude already consumed foods
recs = ensemble.recommend(
    user_id=0,
    top_k=10,
    exclude_foods=[1, 2, 3]  # Food IDs to exclude
)
```

## Model Details

- **Developed by:** Nannyombi Shakiran, Yul Lam Gatkuoth
- **Institution:** Makerere University
- **Supervisor:** Ggaliwango Marvin
- **License:** MIT
- **Model type:** Graph Neural Network Ensemble
- **Task:** Food recommendation for elderly nutrition

## Training Data

- 1,048 nodes (foods, nutrients, conditions, regions)
- 14,359 edges (relationships)
- Uganda-specific nutrition knowledge graph

## Intended Use

Personalized nutrition recommendations for elderly populations in Uganda:
- Health conditions (hypertension, diabetes, anemia, frailty, etc.)
- Regional food availability (Central, Western, Eastern, Northern)
- Cultural preferences (English and Luganda support)
- Cost-conscious recommendations (~4,232 UGX per meal)

## Limitations

- Trained specifically on Ugandan food data
- Requires user health profile for optimal recommendations
- Not a substitute for professional medical advice
- Best suited for elderly population (60+ years)

## Performance Benchmarks

**CPU (Intel i7):**
- Single prediction: 0.5 ms
- Top-10 recommendations: 15 ms
- Batch (100 users): 1.5 seconds

**GPU (NVIDIA T4):**
- Single prediction: 0.1 ms
- Top-10 recommendations: 3 ms
- Batch (100 users): 0.3 seconds

## Repository Structure

```
.
├── nutrition_ensemble.py      # Main model class
├── ensemble_config.json       # Model configuration
├── requirements.txt           # Dependencies
├── embeddings/                # Pre-computed embeddings
│   ├── crgn_embeddings.npy   # 7.30 MB
│   ├── hetgnn_embeddings.npy # 0.73 MB
│   └── gat_embeddings.npy    # 1.22 MB
└── examples/
    └── quickstart.py          # Usage examples
```

## Citation

```bibtex
@software{mzeechakula2025,
  title={MzeeChakula: Graph-Enhanced Nutrition Planning for Elderly in Uganda},
  author={Nannyombi, Shakiran and Gatkuoth, Yul Lam},
  year={2025},
  institution={Makerere University},
  supervisor={Ggaliwango, Marvin},
  url={https://github.com/MzeeChakula}
}
```

## Links

- **GitHub:** https://github.com/MzeeChakula/models
- **Data Repository:** https://github.com/MzeeChakula/data
- **Issues:** https://github.com/MzeeChakula/models/issues

## Contact

- **Email:** shakirannannyombi@gmail.com
- **Collaboration:** gatkuothyullam@gmail.com

---

**Made for Uganda's elderly population** 🇺🇬