Volunteer Matching System

A GNN-based system that matches volunteers to disaster-relief tasks across India, considering skills, location, language, and availability.

How it works

Each volunteer and task is represented as a node in a heterogeneous graph. A Graph Neural Network (GNN) learns to score every volunteer-task pair. The assignment engine then picks the best volunteer per skill slot — so a task needing both medical and logistics help gets two volunteers, one for each.

Skills supported:

• Medical & Healthcare
• Logistics & Operations
• Technical & Engineering
• Food & Basic Needs
• Education & Training
• Field Work / Labor

Matching factors:

• Skill match (per slot)
• Distance (closer is better)
• Language overlap (derived from coordinates)
• Availability
• Task urgency (high urgency tasks get assigned first)

---

Setup

pip install torch torch-geometric flask pandas numpy scikit-learn matplotlib networkx plotly requests

---

Pipeline

1. Generate volunteers dataset

python dataset_generator.py

2. Classify tasks with an LLM

# Using local Ollama model (default)
python task_enricher.py --input tasks_raw.csv --output tasks.csv

# Using Gemini API (add GEMINI_API_KEY to .env)
python task_enricher.py --backend gemini

3. Train the GNN

python train.py --volunteers volunteers.csv --tasks tasks.csv

4. Run assignments

python assign.py --volunteers volunteers.csv --tasks tasks.csv

5. Analyze results

python analyze.py

6. Run the web app

python app.py
# Open http://localhost:5000

---

Files

File	Purpose
model.py	GNN architecture
train.py	Training pipeline
assign.py	Multi-volunteer assignment engine
predict.py	Show all matches above a threshold
dataset_generator.py	Generate synthetic volunteer data
task_enricher.py	LLM-based task classification
lang_utils.py	Language detection from coordinates
analyze.py	Stats and visualization for assignments
visualize.py	GNN graph and score heatmap
test_sanity.py	Quick model sanity check
app.py	Flask web interface