Add detailed model card

README.md

@@ -1,22 +1,185 @@
 ---
-base_model: unsloth/gemma-4-e2b-it-unsloth-bnb-4bit
+language:
+- en
+- bn
+- es
+- id
+license: apache-2.0
+base_model: google/gemma-4-e2b-it
 tags:
-- text-generation-inference
-- transformers
 - unsloth
 - gemma4
 - trl
-license: apache-2.0
-language:
-- en
+- spatial
+- humanitarian
+- tool-calling
+- lora
+- offline
+- edge-ai
+- raspberry-pi
+pipeline_tag: text-generation
+---
+
+# gemma-4-e2b-spatial-lora
+
+> **Gemma 4 E2B fine-tuned for humanitarian spatial tool calling**  
+> Part of [GemmaTerrain](https://huggingface.co/tasfuuu19) — Multimodal GeoAI for the Unconnected
+
+[![Base Model](https://img.shields.io/badge/Base-Gemma%204%20E2B-blue)](https://huggingface.co/google/gemma-4-e2b-it)
+[![License](https://img.shields.io/badge/License-Apache%202.0-yellow)](https://opensource.org/licenses/Apache-2.0)
+[![Trained with Unsloth](https://img.shields.io/badge/Trained%20with-Unsloth-purple)](https://github.com/unslothai/unsloth)
+
+---
+
+## Overview
+
+This is a **LoRA adapter** for `google/gemma-4-e2b-it`, fine-tuned to output structured JSON tool calls for humanitarian spatial queries. It runs offline on ARM edge hardware (Raspberry Pi 5, Steam Deck) as part of the GemmaTerrain system — no internet, no cloud, no GPU required.
+
+Given a natural language query in English, Bangla, Spanish, or Indonesian, the model selects exactly one spatial tool and outputs its arguments as JSON.
+
+**Example:**
+
+| Input | Output |
+|---|---|
+| `"Find the nearest hospital to Camp 6"` | `{"name": "find_nearest_poi_with_route", "arguments": {"poi_type": "hospital", "lat": 21.2, "lon": 92.16}}` |
+| `"15 minute walking radius from Condado"` | `{"name": "generate_isochrone", "arguments": {"lat": 18.46, "lon": -66.07, "max_minutes": 15}}` |
+| `"Camp 6 er kache hospital kothay?"` | `{"name": "find_nearest_poi_with_route", "arguments": {"poi_type": "hospital", "lat": 21.2, "lon": 92.16}}` |
+| `"Farmacias dentro de 1km de Ocean Park"` | `{"name": "list_pois", "arguments": {"poi_type": "pharmacy", "lat": 18.46, "lon": -66.05, "radius_m": 1000}}` |
+
+---
+
+## Spatial Tools
+
+The model is trained to call exactly one of these 6 tools:
+
+| Tool | Use case |
+|---|---|
+| `find_nearest_poi_with_route` | "Nearest hospital to X" — returns closest POI + walking route |
+| `list_pois` | "Clinics within 2km of X" — returns all POIs in radius |
+| `calculate_route` | "Walk from A to B" — returns distance + time |
+| `generate_isochrone` | "15 min walking area from X" — returns reachable boundary |
+| `find_along_route` | "Pharmacies along the way from A to B" |
+| `geocode_place` | "Where is X?" — resolves place name to coordinates |
+
+**Supported POI types:** `hospital`, `clinic`, `doctors`, `pharmacy`, `police`, `fire_station`, `shelter`, `school`, `university`, `bank`, `atm`, `supermarket`, `marketplace`, `drinking_water`, `water_point`, `fuel`, `bus_station`, `place_of_worship`
+
+---
+
+## Training Details
+
+| Parameter | Value |
+|---|---|
+| Base model | `google/gemma-4-e2b-it` |
+| Method | QLoRA (4-bit quantization) |
+| LoRA rank | 16 |
+| LoRA alpha | 32 |
+| Target modules | `q_proj`, `k_proj`, `v_proj`, `o_proj` |
+| Max sequence length | 512 tokens |
+| Training examples | 28 unique × augmented to 5,000 |
+| Epochs | 3 |
+| Batch size | 2 (effective: 8 with grad accumulation) |
+| Learning rate | 2e-4 |
+| Precision | fp16 |
+| Framework | Unsloth + TRL SFTTrainer |
+| Hardware | Kaggle T4 (15GB) |
+| Training time | ~45 minutes |
+
+---
+
+## Dataset
+
+28 hand-crafted humanitarian spatial query → tool call pairs across **3 real-world locations** and **4 languages**:
+
+| Location | Context |
+|---|---|
+| **Cox's Bazar, Bangladesh** | Rohingya refugee camps (Camp 3, 6, 8W, 9, 12, 15) |
+| **San Juan, Puerto Rico** | Post-hurricane disaster response (Condado, Santurce, Miramar) |
+| **Jakarta, Indonesia** | Urban humanitarian operations (Menteng, Gelora, Gambir, Kemang) |
+
+**Languages:** English · Bangla (transliterated) · Spanish · Indonesian
+
+**Query types:** nearest POI, radius search, route calculation, isochrone, along-route search
+
+---
+
+## System Prompt
+
+```
+You are Meridian, a humanitarian spatial assistant running offline on edge hardware.
+Select exactly ONE tool. Output only the tool call JSON — no explanation.
+
+Valid poi_type values: hospital, clinic, doctors, pharmacy, police, fire_station,
+shelter, school, university, bank, atm, supermarket, marketplace, drinking_water,
+water_point, fuel, bus_station, place_of_worship
+```
+
+---
+
+## Usage
+
+### With Unsloth (recommended)
+
+```python
+from unsloth import FastModel
+
+model, tokenizer = FastModel.from_pretrained(
+    model_name="tasfuuu19/gemma-4-e2b-spatial-lora",
+    max_seq_length=512,
+    load_in_4bit=True,
+)
+```
+
+### With Transformers
+
+```python
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+base = AutoModelForCausalLM.from_pretrained("google/gemma-4-e2b-it", load_in_4bit=True)
+model = PeftModel.from_pretrained(base, "tasfuuu19/gemma-4-e2b-spatial-lora")
+tokenizer = AutoTokenizer.from_pretrained("tasfuuu19/gemma-4-e2b-spatial-lora")
+```
+
+### Inference example
+
+```python
+messages = [
+    {"role": "system", "content": "You are Meridian, a humanitarian spatial assistant..."},
+    {"role": "user", "content": "Find the nearest hospital to Camp 6"},
+]
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to("cuda")
+outputs = model.generate(**inputs, max_new_tokens=128, temperature=0.1)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+# {"name": "find_nearest_poi_with_route", "arguments": {"poi_type": "hospital", "lat": 21.2, "lon": 92.16}}
+```
+
 ---
 
-# Uploaded  model
+## GemmaTerrain System
+
+This adapter is the **E2B component** of the GemmaTerrain dual-model routing system:
+
+```
+Query → Geocode Layer → Cactus Router → Gemma 4 E2B (this model) → Spatial Tool → Result
+                                      ↘ Gemma 4 E4B (complex/multimodal queries)
+```
 
-- **Developed by:** tasfuuu19
-- **License:** apache-2.0
-- **Finetuned from model :** unsloth/gemma-4-e2b-it-unsloth-bnb-4bit
+The router sends queries to E2B for simple spatial lookups (nearest, list, route, isochrone) and to E4B for multimodal or complex multi-hop reasoning. Battery level is also a routing signal — below 20%, all queries go to E2B.
+
+The spatial backend uses **NetworKit** (Dijkstra routing) + **DuckDB** (spatial queries) on OpenStreetMap data, running fully offline.
+
+---
+
+## Limitations
+
+- Training set is small (28 unique examples) — generalization relies heavily on the base model
+- Coordinates in training data are fixed to 3 locations; novel locations require geocoding pre-processing
+- Walking speed hardcoded at 5 km/h (83.33 m/min)
+- Not suitable for driving or cycling routing
+
+---
 
-This gemma4 model was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth)
+## License
 
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+Apache 2.0 — same as the base Gemma 4 model.