README.md

metadata

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
  - backyard-ai
  - leaflet
  - cosine-similarity
models:
  - nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
  - sentence-transformers/all-MiniLM-L6-v2
  - meta-llama/Llama-3.2-11B-Vision-Instruct

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 · Backyard AI track 🏡

Try it: live Space · Traces: dataset on the Hub

---

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

flowchart TD
    A["📷 Photo from phone"] --> B["🤖 Vision AI\nLlama-3.2-11B or Nemotron Omni\n(serverless API)"]
    B -->|"is it an animal?"| C{Animal detected?}
    C -->|"No"| ERR["❌ Error message\n'No dog or cat identified'"]
    C -->|"Yes"| D["📝 Structured JSON\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:

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	Nemotron Omni 30B via NVIDIA NIM	remote API
Vision fallback	Llama-3.2-11B-Vision-Instruct via HF Serverless	remote API
Semantic embedding	all-MiniLM-L6-v2 (384 dim)	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. The vision model runs via serverless API — nothing heavy on the Space machine. The only local model is MiniLM for embeddings.

---

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.

---

Running locally

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

# with HuggingFace Serverless
HF_TOKEN=hf_... python app.py

# or with NVIDIA NIM (takes precedence over HF_TOKEN)
NVIDIA_API_KEY=nvapi_... 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
HF_TOKEN	HuggingFace token for Llama-3.2-11B-Vision via Serverless Inference
NVIDIA_API_KEY	Alternative: Nemotron Omni via NVIDIA NIM (takes precedence over HF_TOKEN)
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 — Llama 3.2 11B Vision Instruct (Llama 3.2 Community License).
• NVIDIA — Nemotron Omni 30B via NVIDIA NIM.
• Hugging Face — sentence-transformers/all-MiniLM-L6-v2, Serverless Inference, Space hosting.
• Leaflet.js — interactive map.
• Gradio — gradio.Server for the custom frontend.
• Lucide Icons — UI icons.

---

License

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

---

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