README.md

---
language:
  - en
  - ne
  - es
  - fr
  - ar
  - hi
  - te
  - zh
  - ja
  - ko
  - pt
license: llama3
library_name: transformers
base_model: meta-llama/Llama-3.1-8B-Instruct
tags:
  - disaster-management
  - emergency-response
  - humanitarian-ai
  - multilingual
  - fine-tuned
  - qlora
  - lora
  - peft
  - llama3
pipeline_tag: text-generation
model-index:
  - name: WorldDisasterLM-8B
    results: []
---

# WorldDisasterLM-8B

> **Open-source AI foundation model for global disaster intelligence, emergency response, and humanitarian aid — supporting 11 languages including Nepali.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-Llama3-green.svg)](https://ai.meta.com/llama/license/)
[![HuggingFace](https://img.shields.io/badge/🤗-WorldDisasterLM--8B-yellow)](https://huggingface.co/drdeveloper88/WorldDisasterLM-8B)
[![Tests](https://img.shields.io/badge/tests-9%20passed-brightgreen.svg)]()

---

## How to Use

```python
# pip install transformers accelerate bitsandbytes peft
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
import torch

model_id = "drdeveloper88/WorldDisasterLM-8B"

# Load with 4-bit NF4 quantization (requires ~6 GB VRAM)
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=bnb_config,
    device_map="auto",
)

# Ask a disaster question in any of the 11 supported languages
messages = [
    {
        "role": "user",
        "content": "What immediate steps should I take during a major earthquake? I am in Kathmandu, Nepal."
    }
]

input_ids = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

gen_tokens = model.generate(
    input_ids,
    max_new_tokens=512,
    do_sample=True,
    temperature=0.7,
    top_p=0.9,
    repetition_penalty=1.1,
)

response = tokenizer.decode(gen_tokens[0][input_ids.shape[-1]:], skip_special_tokens=True)
print(response)
```

### Multilingual example (Nepali)

```python
messages = [{"role": "user", "content": "भूकम्पको बेला के गर्ने? म काठमाडौंमा छु।"}]
# (What to do during an earthquake? I am in Kathmandu.)
```

### CLI inference

```bash
python inference.py --prompt "What to do during a flood?" --language English --region Nepal
python inference.py --prompt "भूकम्पको बेला के गर्ने?" --language Nepali --region Nepal
```

> **Note:** Model weights (`.safetensors`) are generated after training completes.  
> Run `python train.py` on a GPU (A100/V100 recommended) to produce the weights, then push via `scripts/push_to_hub.py`.

---

## What is WorldDisasterLM-8B?

**WorldDisasterLM-8B** is a production-grade, domain-specialized large language model fine-tuned on top of `meta-llama/Llama-3.1-8B-Instruct` using **QLoRA** (4-bit NF4 quantization, LoRA r=16). It is purpose-built to assist:

- 🌍 **Emergency responders** — real-time disaster action guidance
- 🏥 **Humanitarian aid workers** — resource allocation and triage support
- 🏛️ **Government agencies** — risk assessment and crisis intelligence
- 🌐 **Global communities** — multilingual disaster preparedness in 11 languages

Training data is collected **live** from six free public APIs: ReliefWeb, USGS Earthquake, GDACS, NOAA Weather, OpenFEMA, and WHO — with automated QA amplification generating 8 instruction variants per disaster record.

---

## Key Features

| Feature | Detail |
|---|---|
| **Base model** | `meta-llama/Llama-3.1-8B-Instruct` |
| **Fine-tuning** | QLoRA — 4-bit NF4, LoRA r=16, all attn+MLP projectors |
| **Languages** | 11: English, Nepali (नेपाली), Spanish, French, Arabic, Hindi, Telugu, Chinese, Japanese, Korean, Portuguese |
| **Data sources** | ReliefWeb, USGS, GDACS, NOAA, OpenFEMA, WHO |
| **Dataset size** | 88+ live records → 711+ instruction samples per run |
| **API** | FastAPI REST + Server-Sent Events streaming |
| **Frontend** | React 18 + Vite disaster analytics dashboard |
| **Export** | GGUF (llama.cpp) + ONNX formats |
| **HuggingFace** | Auto-push via `scripts/push_to_hub.py` |

---

## Supported Languages

| Language | Code | Script |
|---|---|---|
| English | `en` | Latin |
| **Nepali** | `ne` | **Devanagari (नेपाली)** |
| Spanish | `es` | Latin |
| French | `fr` | Latin |
| Arabic | `ar` | Arabic |
| Hindi | `hi` | Devanagari |
| Telugu | `te` | Telugu |
| Chinese | `zh` | Hanzi |
| Japanese | `ja` | Kanji/Hiragana |
| Korean | `ko` | Hangul |
| Portuguese | `pt` | Latin |

---

## Quick Start

### 1. Clone and install

```bash
git clone https://huggingface.co/drdeveloper88/WorldDisasterLM-8B worlddisasterllm
cd worlddisasterllm
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt
```

> **Windows note:** If your path has spaces, always set:
> ```powershell
> $env:PYTHONPATH = "C:\path\to\worlddisasterllm"
> ```

### 2. Configure environment

```bash
cp .env.example .env
# Add HF_TOKEN for HuggingFace publishing (optional)
```

### 3. Run the API backend

```bash
uvicorn backend.app.main:app --reload --port 8000
```

API available at: `http://localhost:8000`  
Interactive docs: `http://localhost:8000/docs`

### 4. Run the React dashboard

```bash
cd frontend
npm install
npm run dev
```

Dashboard at: `http://localhost:5173`

### 5. Run the Gradio demo

```bash
python app.py
```

Demo at: `http://localhost:7860`

### 6. Run CLI inference

```bash
# English
python inference.py --prompt "What to do during a flood?" --language English --region Nepal

# Nepali
python inference.py --prompt "भूकम्पको बेला के गर्ने?" --language Nepali --region Nepal
```

---

## Training Pipeline

### Step 1 — Collect live data

```bash
python scripts/collect_data.py
# Collects from: ReliefWeb, USGS, GDACS, NOAA, OpenFEMA, WHO
# Output: data/processed/instruction_dataset.jsonl
```

### Step 2 — Fine-tune with QLoRA

```bash
python train.py --output checkpoints/worlddisasterlm-8b-qlora
# Requires GPU (A100/V100 recommended)
# Uses: 4-bit NF4 quantization + LoRA r=16 + SFTTrainer
```

### Step 3 — Evaluate

```bash
python evaluate.py
```

### Step 4 — Push to HuggingFace

```bash
export HF_TOKEN=hf_xxxx   # or $env:HF_TOKEN on Windows
python scripts/push_to_hub.py \
    --adapter checkpoints/worlddisasterlm-8b-qlora \
    --base-model meta-llama/Llama-3.1-8B-Instruct \
    --repo-id YourUsername/WorldDisasterLM-8B
```

### Step 5 — Export to GGUF (for llama.cpp / Ollama)

```bash
python scripts/export_gguf.py \
    --model-path checkpoints/worlddisasterlm-8b-qlora \
    --output-path artifacts/worlddisasterlm-8b.gguf
```

---

## API Reference

### Health check
```
GET /health
→ { "status": "ok", "model": "WorldDisasterLM-8B" }
```

### Disaster chat
```
POST /v1/chat
{
  "messages": [{"role": "user", "content": "What to do during earthquake?"}],
  "language": "Nepali",
  "region": "Nepal"
}
→ { "answer": "[WorldDisasterLM-8B | नेपाली | Nepal] ...", "confidence": 0.74, ... }
```

### Streaming chat
```
POST /v1/chat/stream    (Server-Sent Events)
```

### Risk scoring
```
POST /v1/risk/score
{ "region": "South Asia", "hazard_type": "flood", "vulnerability_index": 0.74, "exposure_index": 0.81 }
→ { "risk_score": ..., "risk_level": "High", "recommendation": "..." }
```

### Incident classification
```
POST /v1/incidents/classify
{ "text": "Magnitude 7.1 earthquake near coastal city. Hospitals overloaded." }
→ { "incident_type": "earthquake", "severity": "critical", ... }
```

---

## Repository Structure

```
worlddisasterlm/
├── backend/                   FastAPI backend
│   └── app/
│       ├── main.py            API entrypoint
│       ├── services/
│       │   ├── inference_service.py   Core response generation (multilingual)
│       │   └── risk_engine.py         Risk scoring engine
│       ├── guardrails/
│       │   └── safety.py      Prompt safety filters
│       └── models/schemas.py  Pydantic v2 request/response models
├── worlddisasterlm/           Core ML package
│   ├── config.py              SUPPORTED_LANGUAGES, PipelineConfig
│   ├── data/
│   │   ├── collectors/        6 live API data collectors
│   │   ├── etl.py             Extract-Transform-Load pipeline
│   │   ├── qa_generator.py    8-variant QA amplification
│   │   ├── scenario_builder.py  Multilingual disaster scenarios
│   │   └── processors.py      JSONL dataset builder
│   ├── training/
│   │   ├── train_qlora.py     Production QLoRA training (SFTTrainer)
│   │   └── chat_format.py     Llama 3.1 chat template
│   ├── evaluation/
│   │   ├── metrics.py         Task + safety metrics
│   │   └── multilingual_eval.py  11-language coverage scoring
│   └── optimization/
│       ├── export_gguf.py     GGUF export (llama.cpp)
│       └── export_onnx.py     ONNX export
├── frontend/                  React 18 + Vite dashboard
│   └── src/App.jsx            Language selector, chat, analytics, monitoring
├── scripts/
│   ├── collect_data.py        Live data collection orchestrator
│   ├── push_to_hub.py         HuggingFace Hub publisher
│   ├── export_gguf.py         GGUF CLI wrapper
│   └── export_onnx.py         ONNX CLI wrapper
├── tests/
│   ├── test_api.py            FastAPI integration tests (incl. Nepali)
│   ├── test_dataset_builder.py  ETL + Nepali language tests
│   └── test_risk_engine.py    Risk scoring tests
├── inference.py               CLI inference entrypoint
├── train.py                   Training entrypoint
├── evaluate.py                Evaluation entrypoint
├── app.py                     Gradio demo
├── dataset_builder.py         Dataset build entrypoint
├── Dockerfile                 API container
├── docker-compose.yml         Full stack (API + frontend + MLflow)
└── pyproject.toml             Project metadata + pytest config
```

---

## Running Tests

```bash
# Windows
$env:PYTHONPATH = "C:\path\to\worlddisasterllm"
python -m pytest tests/ -v

# macOS/Linux
PYTHONPATH=. pytest tests/ -v
```

Expected output: **9 passed** — including Nepali language tests.

---

## Safety and Responsible AI

- Prompt-level guardrails block unsafe instructions
- Output confidence scoring with human-review flags
- Emergency disclaimers on all life-safety guidance
- Hallucination heuristics with citation anchoring
- Human-in-the-loop escalation for critical incidents

---

## HuggingFace Publishing

The model is published as **`WorldDisasterLM-8B`** on HuggingFace Hub with:
- Merged LoRA adapters (production-ready weights)
- Model card with 11-language tags (`en`, `ne`, `es`, `fr`, `ar`, `hi`, `te`, `zh`, `ja`, `ko`, `pt`)
- GGUF variant for llama.cpp / Ollama compatibility

---

## License

Base model: [Llama 3 Community License](https://ai.meta.com/llama/license/) (Meta).  
This fine-tuning code and dataset pipeline: **Apache 2.0**.

---

## Acknowledgements

- [Meta AI — Llama 3.1](https://ai.meta.com/blog/meta-llama-3/)
- [ReliefWeb API](https://reliefweb.int/help/api)
- [USGS Earthquake Hazards Program](https://earthquake.usgs.gov/fdsnws/event/1/)
- [GDACS Global Disaster Alert](https://www.gdacs.org)
- [NOAA Weather.gov API](https://api.weather.gov)
- [OpenFEMA API](https://www.fema.gov/about/openfema)
- [WHO RSS Feeds](https://www.who.int/rss-feeds)
- [NDRRMA Nepal — राष्ट्रिय विपद् जोखिम न्यूनीकरण तथा व्यवस्थापन प्राधिकरण](https://www.ndrrma.gov.np)