README.md

---
title: PawMap
emoji: 🐾
colorFrom: green
colorTo: green
sdk: docker
app_file: app.py
pinned: true
license: mit
short_description: Collaborative stray animal mapping with AI
tags:
  - stray-animals
  - animal-welfare
  - maps
  - computer-vision
  - small-models
  - gradio
  - build-small-hackathon
  - track:backyard
  - sponsor:nvidia
  - achievement:offbrand
  - achievement:sharing
  - backyard-ai
  - leaflet
  - cosine-similarity
models:
  - meta-llama/Llama-3.2-11B-Vision-Instruct
  - nvidia/Nemotron-Mini-4B-Instruct
  - sentence-transformers/all-MiniLM-L6-v2
---

# PawMap 🐾 — Collaborative stray animal mapping with AI

Take a photo of the stray animal you just spotted. The AI identifies species, breed and color — and checks if it's already been registered before.  
Over time, the map tells each animal's story: where it shows up, who helped, whether it's doing okay.

Built for the [**Build Small Hackathon 2026**](https://huggingface.co/build-small-hackathon) · **Backyard AI** track 🏡

**Try it:** [live Space](https://huggingface.co/spaces/build-small-hackathon/viralata-mapper) · **Traces:** [dataset on the Hub](https://huggingface.co/datasets/build-small-hackathon/viralata-mapper-storage)

> 🎬 **Demo video:** `TODO — paste your YouTube / Vimeo / Loom link here before submitting`
> 📣 **Social post:** `TODO — paste your X / LinkedIn / Bluesky / Mastodon post link here before submitting`

---

## The Problem

Brasília, DF — the capital of Brazil — has thousands of stray dogs and cats scattered across its residential wings, parking lots and green areas. Independent rescuers know each animal by nickname, by street, by habit. But that knowledge lives in WhatsApp groups, in individual memory, nowhere persistent.

The friend who inspired this app has been feeding a colony of cats near the Asa Norte commercial strip for years. She knows exactly which ones have been neutered, which ones have a history of injury, which one vanished last month. But when someone new wants to help — or when she needs backing to request food donations — there's nothing to show. No map, no timeline, no proof that a specific animal has been living on that block for two years.

**PawMap is that record.** Anyone takes a photo of a stray animal with their phone. The AI identifies it, GPS pins the location, and the app checks whether that animal has been seen before — linking all sightings to its profile. The map is public. The animal's trail becomes visible. Anyone who wants to help knows exactly where to go.

---

## How it works

There are two AI-powered flows: **registering a sighting** and **recording help**.

### Sighting flow

```mermaid
flowchart TD
    A["📷 Photo from phone"] --> B["🤖 Vision AI\nLlama-3.2-11B-Vision\n(NVIDIA NIM / HF)"]
    B -->|"is it an animal?"| C{Animal detected?}
    C -->|"No"| ERR["❌ Error message\n'No dog or cat identified'"]
    C -->|"Yes"| D["📝 Structured JSON\nNemotron Mini 4B Instruct structures\nspecies · breed · color · condition · marks"]
    D --> E["🔢 Semantic embedding\nall-MiniLM-L6-v2 · 384 dim\n(local, 22M params)"]
    E --> F{Cosine similarity\n≥ 0.80?}
    F -->|"Yes — known animal"| G["➕ New sighting\nadded to existing animal"]
    F -->|"No — new animal"| H["🆕 New animal\nregistered in the database"]
    G --> I["💾 SQLite"]
    H --> I
    I --> J["🗺️ Leaflet map\nprofiles · trail · gallery"]
```

Before confirming, the user sees the top 3 most similar animals already in the database — they can edit what the AI detected, give the animal a name, and note its condition. Only then is the sighting saved.

### Help flow

When someone wants to help an animal, they can submit a **help proof** — a photo showing they fed it, treated a wound, or got it to a vet. The AI does two things with that photo:

```mermaid
flowchart TD
    A["📷 Help proof photo\n(optional)"] --> B["🤖 Vision AI\nanalyzes the new photo"]
    B --> C["🔢 New embedding\ngenerated from description"]
    C --> D{Cosine similarity\nagainst registered animal?}
    D -->|"Match ≥ 0.80\nsame animal ID"| E["✅ AI-verified\nmatch score shown"]
    D -->|"No match"| F["⚠️ Unverified\nstill recorded"]
    B --> G{Condition improved?}
    G -->|"e.g. injured → healthy"| H["📈 Condition update\nlogged on profile"]
    G -->|"same or worse"| I["No change"]
    E --> J["💾 Help event saved\nto sightings table"]
    F --> J
    H --> J
    I --> J
```

The profile page shows the full help history with photos, help type (fed / treated / rescued / other), AI verification status and any detected condition improvement.

The map uses color to signal urgency: **🟢 green** = dog · **🟠 orange** = cat · **🔴 red** = not seen in +30 days.

---

## What's inside

| Component | Model / Library | Where it runs |
|---|---|---|
| Visual identification | **Llama-3.2-11B-Vision-Instruct** (11B) via NVIDIA NIM (or HF Serverless) | remote API |
| Text reasoning / JSON | **Nemotron Mini 4B Instruct** via NVIDIA NIM | remote API |
| Semantic embedding | **all-MiniLM-L6-v2** (384 dim, 22M params) | CPU, local |
| Animal matching | Cosine similarity (threshold 0.80) | CPU, local |
| Database | SQLite | local / persistent |
| Frontend | SPA via `gradio.Server` + Leaflet.js + Lucide Icons | browser |

**Total parameters running locally: ~22M** (MiniLM). The vision and reasoning models run via serverless API — nothing heavy on the Space machine. **Every model used is well under the 32B hackathon cap:** Llama-3.2-11B-Vision (11B), Nemotron Mini 4B Instruct (4B) and MiniLM-L6-v2 (22M).

---

## Screens

| Screen | Description |
|---|---|
| 🗺️ **Map** | Color-coded pins by species/urgency, floating card with "View profile" |
| 📷 **Register** | Photo upload + automatic GPS + AI analysis |
| 🤖 **Analysis** | Auto-identification with editable fields + top 3 similar animals |
| ✅ **Confirm** | Sighting summary before saving |
| 👁️ **Spotted** | List of all registered animals |
| 🐾 **Profile** | Full animal card with gallery, map trail and help history |

---

## Badges

This submission earns the following hackathon bonus quests:

- 🎨 **Off-Brand** — Fully custom interface via `gradio.Server`, no default Gradio components visible. SPA frontend with Leaflet.js for the map, Lucide Icons, and custom design.
- 📡 **Sharing is Caring** — Full traces of every sighting (photo → AI analysis → embedding → matching result) are automatically published as a dataset on the Hub via `/admin/push-traces`.
- 🤏 **Tiny Titan** — The only on-device model is `all-MiniLM-L6-v2` (22M params, far under 4B): all animal matching runs locally on a tiny embedding model.
- 🟩 **NVIDIA / Nemotron** — Structured identification is normalized by `Nemotron-Mini-4B-Instruct` via NVIDIA NIM — small (4B), well under the 32B cap.

---

## Running locally

```bash
git clone https://huggingface.co/spaces/build-small-hackathon/viralata-mapper
cd viralata-mapper
pip install -r requirements.txt

# Recommended: NVIDIA NIM powers both vision (Llama-3.2-11B-Vision) and Nemotron Mini 4B
NVIDIA_API_KEY=nvapi_... python app.py

# Alternative: vision via HuggingFace Serverless
HF_TOKEN=hf_... python app.py

# no key — runs in fallback mode without AI identification
python app.py

# open http://localhost:7860
```

On first run the app seeds the database with demo animals around Brasília so the map isn't empty.

---

## Space configuration

### Secrets

| Secret | Description |
|---|---|
| `NVIDIA_API_KEY` | NVIDIA NIM key — powers **both** vision (Llama-3.2-11B-Vision) and Nemotron Mini 4B normalization. A single key is enough. |
| `HF_TOKEN` | Optional — vision via HF Serverless if you don't use NVIDIA NIM |
| `MATCH_THRESHOLD` | Optional. Similarity threshold. Default: `0.80` |
| `HF_DATASET_ID` | Optional. Hub dataset for trace publishing (e.g. `org/dataset-name`) |

> Without a Vision AI key the app runs in fallback mode — registration and matching still work, but automatic breed/color/condition identification is disabled.

### Persistent Storage

Set up a **Persistent Storage Bucket** in the Space and mount it at `/data/` so photos and the database survive restarts. Without it, all data is wiped on each deploy.

---

## Repository structure

```
.
├── app.py                  # Entrypoint — FastAPI routes + Gradio Server
├── requirements.txt
├── Dockerfile
├── index.html              # SPA frontend
├── static/
│   ├── app.js              # Client logic (map, camera, registration flow)
│   ├── style.css
│   └── lottie/             # Loading animations
├── core/
│   ├── ai.py               # Vision AI (HF or NVIDIA NIM) + embeddings
│   ├── database.py         # SQLite — animals and sightings
│   ├── matcher.py          # Cosine similarity for animal matching
│   ├── seed.py             # Demo data for the initial map (Brasília, DF)
│   └── tracer.py           # Trace logging + push to HF Hub
├── db/
│   └── schema.sql          # Database schema
└── data/                   # Runtime — SQLite database + photos + traces
    ├── viralata.db
    ├── photos/
    └── traces.jsonl
```

---

## Limitations

- **Vision AI via API** — breed identification requires `HF_TOKEN` or `NVIDIA_API_KEY`. Without a key, registrations use generic data (breed "SRD / Domestic Shorthair").
- **GPS on mobile** — accuracy depends on the device. Indoors or with weak signal, coordinates may be imprecise.
- **Matching is not foolproof** — the 0.80 threshold is conservative to avoid false positives, but two very similar animals (e.g. two caramel SRDs) may get grouped together. The user reviews the candidates before confirming and can correct.
- **Portuguese / English only** — the interface is in Portuguese; the AI generates descriptions in English for embedding consistency.

---

## Credits

- **[Meta](https://ai.meta.com/llama/)** — Llama 3.2 11B Vision Instruct (Llama 3.2 Community License).
- **[NVIDIA](https://build.nvidia.com/)** — Nemotron Mini 4B Instruct via NVIDIA NIM.
- **[Hugging Face](https://huggingface.co/)** — `sentence-transformers/all-MiniLM-L6-v2`, Serverless Inference, Space hosting.
- **[Leaflet.js](https://leafletjs.com/)** — interactive map.
- **[Gradio](https://gradio.app/)** — `gradio.Server` for the custom frontend.
- **[Lucide Icons](https://lucide.dev/)** — UI icons.

---

## License

MIT for the application code. Models follow their own licenses — see the Meta (Llama 3.2) and NVIDIA (Nemotron Mini 4B Instruct) model cards for full terms.

---

*Built for Brasília, DF — capital of Brazil — and any city that wants to map its stray animals.* 🐾