feat: Animal Visto app

.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

.idea/animal-visto.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/material_theme_project_new.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MaterialThemeProjectNewConfig">
+    <option name="metadata">
+      <MTProjectMetadataState>
+        <option name="userId" value="-47692bf2:19e97ac351f:-7ffd" />
+      </MTProjectMetadataState>
+    </option>
+  </component>
+</project>

.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/animal-visto.iml" filepath="$PROJECT_DIR$/.idea/animal-visto.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

README.md

@@ -0,0 +1,59 @@
+---
+title: Animal Visto
+emoji: 🐾
+colorFrom: green
+colorTo: green
+sdk: gradio
+sdk_version: "4.44.0"
+app_file: app.py
+pinned: false
+license: mit
+short_description: Mapeamento colaborativo de animais de rua com IA
+---
+
+# 🐾 Animal Visto
+
+**Mapeamento colaborativo de animais de rua** · Build Small Hackathon · Trilha Backyard AI
+
+Qualquer pessoa tira uma foto de um animal de rua pelo celular, o app detecta automaticamente a localização GPS, e usa IA para identificar se aquele animal já foi registrado antes — agrupando avistamentos e mostrando a trajetória no mapa.
+
+## Como funciona
+
+1. **📷 Registrar** — tire uma foto, confirme a localização GPS e envie
+2. **🤖 IA (Nemotron Nano VL)** — identifica espécie, raça, cor e marcações
+3. **🔍 Matching** — cosine similarity entre embeddings verifica se é o mesmo animal
+4. **🗺️ Mapa** — pin colorido no mapa com histórico de avistamentos
+
+## Secrets necessários no HF Space
+
+| Secret | Descrição |
+|--------|-----------|
+| `HF_TOKEN` | Token HF com permissão de leitura (Settings → Tokens) |
+| `HF_MODEL` | Opcional. Padrão: `meta-llama/Llama-3.2-11B-Vision-Instruct` |
+| `MATCH_THRESHOLD` | Opcional. Threshold de similaridade. Padrão: `0.80` |
+
+> Os embeddings rodam com `sentence-transformers` **localmente no Space** (sem custo de API).
+> Só a análise de imagem usa créditos HF (1 chamada por foto enviada).
+
+## Storage Bucket
+
+Configure um Persistent Storage Bucket no Space para que `/data/` persista entre restarts.
+O banco (`viralata.db`) e as fotos ficam em `/data/`.
+
+## Stack
+
+- **Frontend**: Gradio 4 + Leaflet.js
+- **Backend**: Python · SQLite · sentence-transformers
+- **IA**: Nemotron Nano VL via NVIDIA NIM API
+- **Matching**: Cosine similarity em embeddings `all-MiniLM-L6-v2`
+- **Mapa**: OpenStreetMap via Leaflet.js
+
+## Cores dos pins
+
+- 🟢 Verde — cão visto pela 1ª vez
+- 🟠 Laranja — animal com múltiplos avistamentos
+- 🔴 Vermelho — não visto há mais de 30 dias
+
+---
+
+*Feito com 💚 para Vinhedo, SP — e qualquer outra cidade.*

app.py

@@ -0,0 +1,639 @@
+"""
+app.py — Animal Visto 🐾
+Mapeamento colaborativo de animais de rua.
+Build Small Hackathon · Trilha Backyard AI · Junho 2026
+"""
+import json
+import logging
+import os
+
+import gradio as gr
+
+from core.ai import AnimalAI
+from core.database import Database
+from core.matcher import AnimalMatcher
+
+logging.basicConfig(level=logging.INFO)
+
+db      = Database()
+ai      = AnimalAI()
+matcher = AnimalMatcher()
+
+# ─── Paleta (spec §4) ────────────────────────────────────────────────────────
+C_GREEN   = "#388C59"
+C_GREEN_L = "#D9EBD9"
+C_TEXT    = "#212121"
+C_CARD    = "#F4F4F0"
+C_RED     = "#E53935"
+C_ORANGE  = "#FB8C00"
+
+# ─── CSS ─────────────────────────────────────────────────────────────────────
+CSS = f"""
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
+* {{ box-sizing: border-box; font-family: 'Inter', sans-serif; }}
+
+/* Wrapper mobile-first */
+.gradio-container {{
+    max-width: 480px !important;
+    margin: 0 auto !important;
+    padding: 0 !important;
+    background: #ffffff !important;
+    min-height: 100dvh;
+}}
+
+footer {{ display: none !important; }}
+.svelte-1gfkn6j {{ display: none !important; }}
+
+/* Top bar */
+#top-bar {{
+    background: {C_GREEN};
+    color: white;
+    padding: 14px 16px 12px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    box-shadow: 0 2px 8px rgba(0,0,0,.15);
+}}
+#top-bar h1 {{
+    margin: 0;
+    font-size: 18px;
+    font-weight: 700;
+    letter-spacing: -0.3px;
+}}
+#top-bar small {{
+    font-size: 12px;
+    opacity: .75;
+    font-weight: 400;
+}}
+#stats-badge {{
+    background: rgba(255,255,255,.2);
+    border-radius: 20px;
+    padding: 4px 10px;
+    font-size: 12px;
+    font-weight: 600;
+}}
+
+/* Tabs — visual de nav bar */
+.tabs > .tab-nav {{
+    background: #fff;
+    border-top: 1px solid #eee;
+    border-bottom: none !important;
+    display: flex;
+    position: sticky;
+    bottom: 0;
+    z-index: 100;
+    box-shadow: 0 -2px 10px rgba(0,0,0,.08);
+    padding: 0;
+    gap: 0;
+}}
+.tabs > .tab-nav button {{
+    flex: 1 !important;
+    padding: 10px 4px 8px !important;
+    border-radius: 0 !important;
+    border: none !important;
+    background: transparent !important;
+    color: #999 !important;
+    font-size: 11px !important;
+    font-weight: 500 !important;
+    line-height: 1.4 !important;
+    transition: color .15s, border-top .15s;
+    border-top: 3px solid transparent !important;
+}}
+.tabs > .tab-nav button.selected {{
+    color: {C_GREEN} !important;
+    border-top: 3px solid {C_GREEN} !important;
+    font-weight: 700 !important;
+}}
+
+/* Filter pills */
+.filter-row {{
+    display: flex;
+    gap: 6px;
+    padding: 10px 12px;
+    overflow-x: auto;
+    scrollbar-width: none;
+    background: white;
+    border-bottom: 1px solid #f0f0f0;
+}}
+.filter-row button {{
+    border-radius: 20px !important;
+    border: 1.5px solid #ddd !important;
+    background: white !important;
+    color: {C_TEXT} !important;
+    font-size: 13px !important;
+    padding: 5px 14px !important;
+    white-space: nowrap;
+    font-weight: 500 !important;
+    transition: all .15s;
+    min-width: unset !important;
+}}
+.filter-row button:hover,
+.filter-row button.active {{
+    background: {C_GREEN} !important;
+    border-color: {C_GREEN} !important;
+    color: white !important;
+}}
+.filter-row button.secondary {{
+    border-color: #eee !important;
+    color: #888 !important;
+    font-size: 12px !important;
+    padding: 5px 10px !important;
+}}
+.filter-row button.secondary:hover {{
+    border-color: {C_GREEN} !important;
+    color: {C_GREEN} !important;
+    background: {C_GREEN_L} !important;
+}}
+
+/* Register form */
+#register-tab {{
+    padding: 0 0 80px;
+}}
+.reg-section {{
+    padding: 16px 16px 0;
+}}
+.reg-label {{
+    font-size: 13px;
+    font-weight: 600;
+    color: #555;
+    margin-bottom: 6px;
+}}
+#register-tab .image-container {{
+    border-radius: 12px !important;
+    border: 2px dashed #ddd !important;
+    background: {C_GREEN_L} !important;
+    min-height: 200px;
+}}
+#register-tab textarea {{
+    border-radius: 10px !important;
+    border: 1.5px solid #e0e0e0 !important;
+    font-size: 14px !important;
+    resize: none;
+}}
+#register-tab textarea:focus {{
+    border-color: {C_GREEN} !important;
+    box-shadow: 0 0 0 3px {C_GREEN}22 !important;
+}}
+
+/* Submit button */
+#submit-btn {{
+    margin: 16px !important;
+    width: calc(100% - 32px) !important;
+    background: {C_GREEN} !important;
+    border: none !important;
+    border-radius: 12px !important;
+    font-size: 15px !important;
+    font-weight: 600 !important;
+    padding: 14px !important;
+    color: white !important;
+    box-shadow: 0 4px 12px {C_GREEN}55;
+}}
+#submit-btn:hover {{ background: #2d7a4a !important; }}
+#submit-btn:disabled {{ background: #ccc !important; box-shadow: none !important; }}
+
+/* Status card */
+#status-card {{
+    margin: 8px 16px 80px;
+    border-radius: 12px;
+    padding: 14px 16px;
+    font-size: 14px;
+    line-height: 1.5;
+}}
+#status-card.ok  {{ background: #e8f5e9; color: #2e7d32; border-left: 4px solid {C_GREEN}; }}
+#status-card.err {{ background: #ffebee; color: #b71c1c; border-left: 4px solid {C_RED};   }}
+
+/* Animals list */
+#animals-tab {{ padding: 0 0 80px; }}
+.animal-card {{
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    background: white;
+    border-radius: 12px;
+    padding: 14px 16px;
+    margin: 8px 12px;
+    box-shadow: 0 2px 8px rgba(0,0,0,.07);
+    border: 1px solid #f0f0f0;
+}}
+.animal-avatar {{
+    width: 46px; height: 46px;
+    border-radius: 50%;
+    display: flex; align-items: center; justify-content: center;
+    font-size: 22px;
+    flex-shrink: 0;
+}}
+.animal-info {{ flex: 1; min-width: 0; }}
+.animal-name {{ font-weight: 600; font-size: 14px; color: {C_TEXT}; }}
+.animal-meta {{ font-size: 12px; color: #888; margin-top: 2px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }}
+.animal-badge {{
+    background: {C_GREEN_L};
+    color: {C_GREEN};
+    border-radius: 20px;
+    padding: 3px 9px;
+    font-size: 12px;
+    font-weight: 700;
+    flex-shrink: 0;
+}}
+.animal-badge.urgent {{ background: #ffebee; color: {C_RED}; }}
+.section-header {{
+    padding: 14px 16px 6px;
+    font-size: 13px;
+    font-weight: 600;
+    color: #888;
+    text-transform: uppercase;
+    letter-spacing: .5px;
+}}
+
+/* GPS box */
+#gps-box {{
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    background: {C_GREEN_L};
+    border-radius: 10px;
+    padding: 10px 14px;
+    font-size: 13px;
+    color: #2e7d32;
+    font-weight: 500;
+}}
+"""
+
+# ─── GPS JavaScript ───────────────────────────────────────────────────────────
+GPS_HTML = """
+<div id="gps-box">
+  <span id="gps-icon" style="font-size:18px">📍</span>
+  <span id="gps-text">Detectando localização...</span>
+</div>
+<script>
+(function() {
+  var icon = document.getElementById('gps-icon');
+  var text = document.getElementById('gps-text');
+  function setCoords(coords) {
+    // Atualiza hidden textbox do Gradio via evento sintético
+    var tb = document.querySelector('#gps-coords textarea');
+    if (tb) {
+      var nativeSet = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+      nativeSet.call(tb, JSON.stringify(coords));
+      tb.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+  }
+  if (!navigator.geolocation) {
+    icon.textContent = '⚠️';
+    text.textContent = 'GPS não disponível neste navegador.';
+    return;
+  }
+  navigator.geolocation.getCurrentPosition(
+    function(pos) {
+      var lat = parseFloat(pos.coords.latitude.toFixed(5));
+      var lng = parseFloat(pos.coords.longitude.toFixed(5));
+      icon.textContent = '✅';
+      text.textContent = 'Localização: ' + lat + ', ' + lng;
+      setCoords({ lat: lat, lng: lng });
+    },
+    function(err) {
+      icon.textContent = '⚠️';
+      text.textContent = 'Localização não disponível — avistamento sem GPS.';
+    },
+    { enableHighAccuracy: true, timeout: 10000, maximumAge: 60000 }
+  );
+})();
+</script>
+"""
+
+# ─── Leaflet map HTML ─────────────────────────────────────────────────────────
+def build_map_html(species: str = "all", timeframe: str = "all") -> str:
+    data = db.get_map_data(species, timeframe)
+    data_js = json.dumps(data, ensure_ascii=False)
+
+    return f"""
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+<div id="pawmap" style="height:calc(100dvh - 185px);min-height:300px;width:100%;"></div>
+<script>
+(function() {{
+  if (window._pawmap) {{ window._pawmap.remove(); window._pawmap = null; }}
+  var map = L.map('pawmap', {{ zoomControl: true }}).setView([-23.0316, -46.9785], 13);
+  window._pawmap = map;
+
+  L.tileLayer('https://{{s}}.tile.openstreetmap.org/{{z}}/{{x}}/{{y}}.png', {{
+    attribution: '© <a href="https://openstreetmap.org">OSM</a>',
+    maxZoom: 19
+  }}).addTo(map);
+
+  var animals = {data_js};
+  if (animals.length === 0) {{
+    var msg = L.control({{ position: 'topright' }});
+    msg.onAdd = function() {{
+      var d = L.DomUtil.create('div');
+      d.style.cssText = 'background:white;padding:8px 12px;border-radius:8px;font-size:13px;color:#888;box-shadow:0 2px 8px rgba(0,0,0,.1)';
+      d.textContent = 'Nenhum avistamento ainda 🐾';
+      return d;
+    }};
+    msg.addTo(map);
+  }}
+
+  animals.forEach(function(a) {{
+    var color = a.days_since > 30 ? '{C_RED}'
+              : a.count > 1      ? '{C_ORANGE}'
+              :                    '{C_GREEN}';
+    var em = a.species === 'dog' ? '🐕' : '🐈';
+    var badge = a.count > 1
+      ? '<span style="position:absolute;top:-5px;right:-5px;background:white;color:' + color +
+        ';border:1.5px solid ' + color + ';border-radius:10px;min-width:16px;height:16px;' +
+        'font-size:9px;font-weight:700;display:flex;align-items:center;justify-content:center;padding:0 2px;">'
+        + a.count + '</span>'
+      : '';
+    var ico = L.divIcon({{
+      html: '<div style="position:relative;background:' + color + ';width:36px;height:36px;' +
+            'border-radius:50%;display:flex;align-items:center;justify-content:center;' +
+            'font-size:20px;box-shadow:0 2px 8px rgba(0,0,0,.3);border:2.5px solid white;">' +
+            em + badge + '</div>',
+      className: '',
+      iconSize: [36, 36],
+      iconAnchor: [18, 18],
+      popupAnchor: [0, -20]
+    }});
+    var speciesPt = a.species === 'dog' ? 'Cão' : 'Gato';
+    var urgency = a.days_since > 30 ? '<br><span style="color:{C_RED};font-size:11px;">⚠️ Não visto há ' + a.days_since + ' dias</span>' : '';
+    L.marker([a.lat, a.lng], {{ icon: ico }}).addTo(map)
+      .bindPopup(
+        '<div style="min-width:160px;">' +
+        '<b style="font-size:14px;">' + em + ' ' + speciesPt + ' #' + a.id + '</b>' +
+        (a.desc ? '<br><span style="font-size:12px;color:#666;">' + a.desc + '</span>' : '') +
+        '<br><span style="font-size:12px;">👁 Visto <b>' + a.count + 'x</b> · último: ' + a.last_seen + '</span>' +
+        urgency + '</div>',
+        {{ maxWidth: 220 }}
+      );
+  }});
+}})();
+</script>
+"""
+
+
+# ─── Animals list HTML ────────────────────────────────────────────────────────
+def build_animals_html() -> str:
+    animals = db.get_recent_animals(limit=30)
+    if not animals:
+        return (
+            '<div style="padding:40px 16px;text-align:center;color:#aaa;">'
+            '<div style="font-size:48px;margin-bottom:12px;">🐾</div>'
+            '<div style="font-size:15px;font-weight:500;">Nenhum animal registrado ainda</div>'
+            '<div style="font-size:13px;margin-top:6px;">Vá para Registrar e tire a primeira foto!</div>'
+            "</div>"
+        )
+
+    cards = []
+    for a in animals:
+        try:
+            desc = json.loads(a.get("description") or "{}")
+        except Exception:
+            desc = {}
+
+        is_dog     = a["species"] == "dog"
+        em         = "🐕" if is_dog else "🐈"
+        sp_pt      = "Cão" if is_dog else "Gato"
+        urgent     = a.get("days_since", 0) > 30
+        color      = C_RED if urgent else C_GREEN
+        badge_cls  = "animal-badge urgent" if urgent else "animal-badge"
+        breed      = desc.get("breed_estimate", "raça desconhecida")
+        color_coat = desc.get("primary_color", "")
+        meta       = f"{breed}{' · ' + color_coat if color_coat else ''}"
+        last_seen  = a.get("last_seen_short", "")
+        count      = a["sighting_count"]
+
+        cards.append(f"""
+        <div class="animal-card">
+          <div class="animal-avatar" style="background:{color}20;">{em}</div>
+          <div class="animal-info">
+            <div class="animal-name">{sp_pt} #{a['id']}</div>
+            <div class="animal-meta">{meta}</div>
+            <div class="animal-meta" style="color:{color};">
+              {'⚠️ ' if urgent else ''}Visto {count}x · último: {last_seen}
+            </div>
+          </div>
+          <div class="{badge_cls}">{count}x</div>
+        </div>
+        """)
+
+    total_a = db.total_animals()
+    total_s = db.total_sightings()
+    header  = (
+        f'<div class="section-header">🐾 {total_a} animais · {total_s} avistamentos</div>'
+    )
+    return header + "".join(cards)
+
+
+# ─── Confirmation card HTML ───────────────────────────────────────────────────
+def build_confirmation_html(animal_id: int, is_new: bool, count: int, species: str) -> str:
+    em    = "🐕" if species == "dog" else "🐈"
+    sp_pt = "cão" if species == "dog" else "gato"
+    if is_new:
+        title = f"Novo {sp_pt} registrado!"
+        sub   = "1º avistamento — obrigada por registrar! 🙏"
+    else:
+        title = f"{em} Animal reconhecido!"
+        sub   = f"Este {sp_pt} já foi avistado <b>{count}x</b> na região."
+
+    return f"""
+    <div style="background:#e8f5e9;border-left:4px solid {C_GREEN};
+                border-radius:10px;padding:14px 16px;margin:8px 0;
+                font-size:14px;color:#2e7d32;line-height:1.6;">
+      <div style="font-size:24px;margin-bottom:6px;">✅ {em}</div>
+      <div style="font-weight:700;font-size:15px;">{title}</div>
+      <div>{sub}</div>
+      <div style="font-size:12px;margin-top:6px;color:#555;">
+        ID #{animal_id} · Avistamento salvo com localização
+      </div>
+    </div>
+    """
+
+
+# ─── Backend: processar avistamento ──────────────────────────────────────────
+def process_sighting(image, gps_json: str, notes: str, progress=gr.Progress()):
+    if image is None:
+        return (
+            gr.update(),
+            '<div style="color:#b71c1c;background:#ffebee;border-left:4px solid #E53935;'
+            'border-radius:10px;padding:12px 16px;font-size:14px;">'
+            "❌ Tire uma foto do animal antes de registrar.</div>",
+        )
+
+    progress(0.15, desc="Analisando imagem...")
+    try:
+        coords = json.loads(gps_json) if gps_json and gps_json.strip() else {}
+    except Exception:
+        coords = {}
+
+    lat = round(float(coords["lat"]), 5) if coords.get("lat") else None
+    lng = round(float(coords["lng"]), 5) if coords.get("lng") else None
+
+    progress(0.40, desc="Identificando animal com IA...")
+    description = ai.analyze_image(image)
+    embedding   = ai.get_embedding(description)
+
+    progress(0.70, desc="Verificando avistamentos anteriores...")
+    candidates = db.get_all_animals_with_embeddings()
+    match      = matcher.find_match(embedding, candidates)
+
+    photo_path = db.save_photo(image)
+
+    if match:
+        animal_id, _score = match
+        db.add_sighting(animal_id, photo_path, lat, lng, notes)
+        db.update_animal(animal_id)
+        animal  = db.get_animal(animal_id)
+        count   = animal["sighting_count"]
+        species = animal["species"]
+        is_new  = False
+    else:
+        animal_id = db.create_animal(description, embedding)
+        db.add_sighting(animal_id, photo_path, lat, lng, notes)
+        count   = 1
+        species = description.get("species", "dog")
+        is_new  = True
+
+    progress(1.0, desc="Salvo!")
+    html = build_confirmation_html(animal_id, is_new, count, species)
+    return gr.update(value=build_map_html()), html
+
+
+# ─── Filter helpers ───────────────────────────────────────────────────────────
+def filter_map(species: str, timeframe: str):
+    return gr.update(value=build_map_html(species, timeframe)), species, timeframe
+
+
+# ─── Stats for top bar ────────────────────────────────────────────────────────
+def get_stats_html():
+    a = db.total_animals()
+    s = db.total_sightings()
+    return f'<div id="stats-badge">{a} animais · {s} avistamentos</div>'
+
+
+# ─── Gradio app ───────────────────────────────────────────────────────────────
+with gr.Blocks(css=CSS, theme=gr.themes.Base(), title="Animal Visto 🐾") as demo:
+
+    # Top bar
+    gr.HTML(
+        '<div id="top-bar">'
+        '<h1>🐾 Animal Visto</h1>'
+        '<small>Vinhedo, SP</small>'
+        "</div>"
+    )
+
+    species_st  = gr.State("all")
+    timeframe_st = gr.State("all")
+
+    with gr.Tabs(elem_classes="tabs") as tabs:
+
+        # ── Tab 1: Mapa ───────────────────────────────────────────────────────
+        with gr.Tab("🗺️ Mapa"):
+            with gr.Row(elem_classes="filter-row"):
+                btn_all    = gr.Button("🐾 Todos",        elem_classes="filter-row")
+                btn_dogs   = gr.Button("🐕 Cães",         elem_classes="filter-row")
+                btn_cats   = gr.Button("🐈 Gatos",        elem_classes="filter-row")
+                btn_today  = gr.Button("Hoje",            elem_classes="filter-row secondary")
+                btn_week   = gr.Button("Esta semana",     elem_classes="filter-row secondary")
+
+            map_html = gr.HTML(build_map_html(), elem_id="map-container")
+
+        # ── Tab 2: Registrar ──────────────────────────────────────────────────
+        with gr.Tab("📷 Registrar", elem_id="register-tab"):
+            with gr.Column(elem_classes="reg-section"):
+                gr.HTML(GPS_HTML)
+
+            # Hidden textbox recebe coords do JS
+            gps_coords = gr.Textbox(
+                value="",
+                visible=False,
+                elem_id="gps-coords",
+                interactive=True,
+            )
+
+            with gr.Column(elem_classes="reg-section"):
+                gr.HTML('<div class="reg-label">📸 Foto do animal</div>')
+                photo_input = gr.Image(
+                    label="",
+                    type="pil",
+                    sources=["upload", "webcam"],
+                    interactive=True,
+                    show_label=False,
+                )
+
+            with gr.Column(elem_classes="reg-section"):
+                gr.HTML('<div class="reg-label">📝 Observações (opcional)</div>')
+                notes_input = gr.Textbox(
+                    label="",
+                    placeholder="Ex: parece ferido, tem coleira, está com filhotes...",
+                    lines=2,
+                    max_lines=4,
+                    show_label=False,
+                )
+
+            submit_btn = gr.Button(
+                "📍 Registrar avistamento",
+                variant="primary",
+                elem_id="submit-btn",
+            )
+            status_html = gr.HTML("", elem_id="status-card")
+
+        # ── Tab 3: Avistados ──────────────────────────────────────────────────
+        with gr.Tab("🐾 Avistados", elem_id="animals-tab"):
+            refresh_btn    = gr.Button("🔄 Atualizar lista", size="sm", variant="secondary")
+            animals_display = gr.HTML(build_animals_html())
+
+    # ─── Events ───────────────────────────────────────────────────────────────
+
+    # Registrar avistamento
+    submit_btn.click(
+        process_sighting,
+        inputs=[photo_input, gps_coords, notes_input],
+        outputs=[map_html, status_html],
+    )
+
+    # Filtros do mapa — Todos
+    btn_all.click(
+        lambda: (build_map_html("all", "all"), "all", "all"),
+        outputs=[map_html, species_st, timeframe_st],
+    )
+    # Cães (mantém timeframe)
+    btn_dogs.click(
+        lambda t: (build_map_html("dog", t), "dog", t),
+        inputs=[timeframe_st],
+        outputs=[map_html, species_st, timeframe_st],
+    )
+    # Gatos (mantém timeframe)
+    btn_cats.click(
+        lambda t: (build_map_html("cat", t), "cat", t),
+        inputs=[timeframe_st],
+        outputs=[map_html, species_st, timeframe_st],
+    )
+    # Hoje (mantém espécie)
+    btn_today.click(
+        lambda s: (build_map_html(s, "today"), s, "today"),
+        inputs=[species_st],
+        outputs=[map_html, species_st, timeframe_st],
+    )
+    # Esta semana (mantém espécie)
+    btn_week.click(
+        lambda s: (build_map_html(s, "week"), s, "week"),
+        inputs=[species_st],
+        outputs=[map_html, species_st, timeframe_st],
+    )
+
+    # Atualizar lista de avistados
+    refresh_btn.click(build_animals_html, outputs=[animals_display])
+
+    # Recarregar mapa ao abrir o app
+    demo.load(build_map_html, outputs=[map_html])
+
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+        show_error=True,
+    )

core/ai.py

@@ -0,0 +1,147 @@
+"""
+ai.py — Integração com HF Inference API + sentence-transformers.
+
+Variáveis de ambiente:
+  HF_TOKEN    — token do Hugging Face (obrigatório para análise de imagem)
+  HF_MODEL    — modelo de visão a usar (padrão: meta-llama/Llama-3.2-11B-Vision-Instruct)
+"""
+import base64
+import io
+import json
+import logging
+import os
+import re
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_MODEL = "meta-llama/Llama-3.2-11B-Vision-Instruct"
+
+PROMPT = (
+    "You are analyzing a photo of a stray animal. "
+    "Return ONLY a valid JSON object with these exact fields:\n"
+    '{"species":"dog or cat",'
+    '"breed_estimate":"mixed or specific breed",'
+    '"size":"small or medium or large",'
+    '"primary_color":"main coat color",'
+    '"secondary_colors":["list of other colors or empty"],'
+    '"distinctive_marks":["any spots, patches, scars, collar etc or empty"],'
+    '"condition":"healthy or thin or injured",'
+    '"description_text":"one concise sentence describing this specific animal for identity matching"}'
+    "\nReturn only the JSON, no explanation."
+)
+
+
+class AnimalAI:
+    def __init__(self):
+        token = os.environ.get("HF_TOKEN", "")
+        self.model = os.environ.get("HF_MODEL", _DEFAULT_MODEL)
+        self.client = None
+
+        if token:
+            try:
+                from huggingface_hub import InferenceClient
+                self.client = InferenceClient(model=self.model, token=token)
+                log.info(f"HF InferenceClient initialized: {self.model}")
+            except ImportError:
+                log.warning("huggingface_hub not installed. AI analysis disabled.")
+        else:
+            log.warning("HF_TOKEN not set — AI analysis will use fallback description.")
+
+        # sentence-transformers para embeddings (gratuito, roda local no Space)
+        self.embedder = None
+        try:
+            from sentence_transformers import SentenceTransformer
+            self.embedder = SentenceTransformer("all-MiniLM-L6-v2")
+            log.info("sentence-transformers loaded: all-MiniLM-L6-v2")
+        except Exception as e:
+            log.warning(f"Could not load sentence-transformers: {e}")
+
+    # ─── Public API ───────────────────────────────────────────────────────────
+
+    def analyze_image(self, image) -> dict:
+        """
+        Recebe PIL.Image, retorna dict com descrição estruturada do animal.
+        Usa HF Inference API (créditos HF). Fallback se token não configurado.
+        """
+        if self.client is None:
+            log.info("No HF client — returning fallback description.")
+            return self._fallback()
+
+        try:
+            img_b64 = self._image_to_b64(image)
+            response = self.client.chat.completions.create(
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "image_url",
+                                "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"},
+                            },
+                            {"type": "text", "text": PROMPT},
+                        ],
+                    }
+                ],
+                max_tokens=300,
+                temperature=0.1,
+            )
+            raw = response.choices[0].message.content or ""
+            return self._parse_json(raw)
+        except Exception as e:
+            log.error(f"HF Inference error: {e}")
+            return self._fallback()
+
+    def get_embedding(self, description: dict) -> list:
+        """
+        Gera embedding (384-dim, float32) a partir da descrição textual.
+        Roda 100% local com sentence-transformers — sem custo de API.
+        """
+        if self.embedder is None:
+            vec = np.random.randn(384).astype(np.float32)
+            vec /= np.linalg.norm(vec)
+            return vec.tolist()
+
+        text = description.get("description_text") or self._desc_to_text(description)
+        return self.embedder.encode(text, normalize_embeddings=True).tolist()
+
+    # ─── Helpers ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _image_to_b64(image) -> str:
+        buf = io.BytesIO()
+        image.thumbnail((800, 800))  # economiza tokens/créditos
+        image.save(buf, format="JPEG", quality=80)
+        return base64.b64encode(buf.getvalue()).decode()
+
+    @staticmethod
+    def _parse_json(raw: str) -> dict:
+        match = re.search(r"\{.*\}", raw, re.DOTALL)
+        if match:
+            try:
+                return json.loads(match.group())
+            except json.JSONDecodeError:
+                pass
+        return AnimalAI._fallback()
+
+    @staticmethod
+    def _desc_to_text(d: dict) -> str:
+        parts = [d.get("size", ""), d.get("primary_color", ""), d.get("species", ""), d.get("breed_estimate", "")]
+        marks = d.get("distinctive_marks", [])
+        if marks:
+            parts.append("with " + ", ".join(marks))
+        return " ".join(p for p in parts if p).strip() or "unknown animal"
+
+    @staticmethod
+    def _fallback() -> dict:
+        return {
+            "species": "dog",
+            "breed_estimate": "mixed",
+            "size": "medium",
+            "primary_color": "brown",
+            "secondary_colors": [],
+            "distinctive_marks": [],
+            "condition": "healthy",
+            "description_text": "medium brown mixed breed dog",
+        }

core/database.py

@@ -0,0 +1,241 @@
+"""
+database.py — SQLite CRUD para animais e avistamentos.
+Usa /data/ em produção (HF Storage Bucket) ou ./data/ localmente.
+"""
+import json
+import os
+import sqlite3
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+from PIL import Image
+
+# ─── Paths ────────────────────────────────────────────────────────────────────
+_hf_data = Path("/data")
+DATA_DIR   = _hf_data if (_hf_data.exists() and os.access(_hf_data, os.W_OK)) else Path("./data")
+DB_PATH    = DATA_DIR / "viralata.db"
+PHOTOS_DIR = DATA_DIR / "photos"
+SCHEMA     = Path(__file__).parent.parent / "db" / "schema.sql"
+
+
+class Database:
+    def __init__(self):
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        PHOTOS_DIR.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    # ─── Internal ─────────────────────────────────────────────────────────────
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(DB_PATH))
+        conn.row_factory = sqlite3.Row
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")  # pode falhar em FUSE mounts
+        except sqlite3.OperationalError:
+            pass
+        conn.execute("PRAGMA foreign_keys=ON")
+        return conn
+
+    def _init_db(self):
+        with self._conn() as conn:
+            if SCHEMA.exists():
+                conn.executescript(SCHEMA.read_text())
+            else:
+                conn.executescript("""
+                    CREATE TABLE IF NOT EXISTS animals (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        species TEXT NOT NULL,
+                        description TEXT,
+                        embedding BLOB,
+                        first_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
+                        last_seen  DATETIME DEFAULT CURRENT_TIMESTAMP,
+                        sighting_count INTEGER DEFAULT 1
+                    );
+                    CREATE TABLE IF NOT EXISTS sightings (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        animal_id INTEGER NOT NULL REFERENCES animals(id),
+                        photo_path TEXT,
+                        latitude REAL,
+                        longitude REAL,
+                        notes TEXT,
+                        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                    );
+                """)
+
+    # ─── Photos ───────────────────────────────────────────────────────────────
+
+    def save_photo(self, image: Image.Image) -> str:
+        """Salva PIL Image em /data/photos/, retorna caminho relativo."""
+        filename = f"{uuid.uuid4().hex}.jpg"
+        path = PHOTOS_DIR / filename
+        image.save(str(path), format="JPEG", quality=85)
+        return f"photos/{filename}"
+
+    def photo_url(self, relative_path: Optional[str]) -> Optional[str]:
+        """Retorna path absoluto para exibição, ou None."""
+        if not relative_path:
+            return None
+        full = DATA_DIR / relative_path
+        return str(full) if full.exists() else None
+
+    # ─── Animals ──────────────────────────────────────────────────────────────
+
+    def create_animal(self, description: dict, embedding: list) -> int:
+        """Cria novo animal, retorna seu id."""
+        emb_blob = np.array(embedding, dtype=np.float32).tobytes()
+        with self._conn() as conn:
+            cur = conn.execute(
+                """INSERT INTO animals (species, description, embedding)
+                   VALUES (?, ?, ?)""",
+                (
+                    description.get("species", "dog"),
+                    json.dumps(description, ensure_ascii=False),
+                    emb_blob,
+                ),
+            )
+            return cur.lastrowid
+
+    def update_animal(self, animal_id: int):
+        """Incrementa sighting_count e atualiza last_seen."""
+        with self._conn() as conn:
+            conn.execute(
+                """UPDATE animals
+                   SET sighting_count = sighting_count + 1,
+                       last_seen = CURRENT_TIMESTAMP
+                   WHERE id = ?""",
+                (animal_id,),
+            )
+
+    def get_animal(self, animal_id: int) -> Optional[dict]:
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM animals WHERE id = ?", (animal_id,)
+            ).fetchone()
+            return dict(row) if row else None
+
+    def get_all_animals_with_embeddings(self) -> list[dict]:
+        """Retorna todos os animais com embedding desserializado para matching."""
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT id, species, description, embedding FROM animals WHERE embedding IS NOT NULL"
+            ).fetchall()
+        result = []
+        for row in rows:
+            d = dict(row)
+            blob = d.pop("embedding")
+            try:
+                d["embedding"] = np.frombuffer(blob, dtype=np.float32).tolist()
+            except Exception:
+                d["embedding"] = None
+            result.append(d)
+        return result
+
+    # ─── Sightings ────────────────────────────────────────────────────────────
+
+    def add_sighting(
+        self,
+        animal_id: int,
+        photo_path: Optional[str],
+        lat: Optional[float],
+        lng: Optional[float],
+        notes: Optional[str],
+    ):
+        with self._conn() as conn:
+            conn.execute(
+                """INSERT INTO sightings (animal_id, photo_path, latitude, longitude, notes)
+                   VALUES (?, ?, ?, ?, ?)""",
+                (animal_id, photo_path, lat, lng, notes or ""),
+            )
+
+    def get_animal_sightings(self, animal_id: int) -> list[dict]:
+        with self._conn() as conn:
+            rows = conn.execute(
+                """SELECT * FROM sightings WHERE animal_id = ?
+                   ORDER BY created_at DESC""",
+                (animal_id,),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ─── Map data ─────────────────────────────────────────────────────────────
+
+    def get_map_data(self, species: str = "all", timeframe: str = "all") -> list[dict]:
+        """
+        Retorna dados de todos os animais para os pins do mapa.
+        Usa a última localização conhecida de cada animal.
+        """
+        filters = []
+        params: list = []
+
+        if species in ("dog", "cat"):
+            filters.append("a.species = ?")
+            params.append(species)
+        if timeframe == "today":
+            filters.append("date(a.last_seen) = date('now')")
+        elif timeframe == "week":
+            filters.append("a.last_seen >= datetime('now', '-7 days')")
+
+        where = ("WHERE " + " AND ".join(filters)) if filters else ""
+        # Subquery para pegar a última sighting com coordenadas
+        sql = f"""
+            SELECT
+                a.id,
+                a.species,
+                a.sighting_count   AS count,
+                a.description,
+                strftime('%d/%m/%Y', a.last_seen) AS last_seen,
+                CAST(julianday('now') - julianday(a.last_seen) AS INTEGER) AS days_since,
+                s.latitude  AS lat,
+                s.longitude AS lng
+            FROM animals a
+            JOIN sightings s ON s.id = (
+                SELECT id FROM sightings
+                WHERE animal_id = a.id AND latitude IS NOT NULL
+                ORDER BY created_at DESC LIMIT 1
+            )
+            {where}
+            ORDER BY a.last_seen DESC
+        """
+        with self._conn() as conn:
+            rows = conn.execute(sql, params).fetchall()
+
+        result = []
+        for row in rows:
+            d = dict(row)
+            try:
+                desc_obj = json.loads(d["description"] or "{}")
+                d["desc"] = desc_obj.get("description_text") or (
+                    f"{desc_obj.get('size','')} {desc_obj.get('primary_color','')} "
+                    f"{desc_obj.get('breed_estimate','')}"
+                ).strip()
+            except Exception:
+                d["desc"] = ""
+            del d["description"]
+            result.append(d)
+        return result
+
+    # ─── Animals list ─────────────────────────────────────────────────────────
+
+    def get_recent_animals(self, limit: int = 30) -> list[dict]:
+        sql = """
+            SELECT
+                a.*,
+                CAST(julianday('now') - julianday(a.last_seen) AS INTEGER) AS days_since,
+                strftime('%d/%m', a.last_seen) AS last_seen_short
+            FROM animals a
+            ORDER BY a.last_seen DESC
+            LIMIT ?
+        """
+        with self._conn() as conn:
+            rows = conn.execute(sql, (limit,)).fetchall()
+        return [dict(r) for r in rows]
+
+    def total_sightings(self) -> int:
+        with self._conn() as conn:
+            return conn.execute("SELECT COUNT(*) FROM sightings").fetchone()[0]
+
+    def total_animals(self) -> int:
+        with self._conn() as conn:
+            return conn.execute("SELECT COUNT(*) FROM animals").fetchone()[0]

core/matcher.py

@@ -0,0 +1,54 @@
+"""
+matcher.py — Cosine similarity para identificar se dois avistamentos são do mesmo animal.
+
+Threshold padrão: 0.80 (ajustável via MATCH_THRESHOLD env var).
+"""
+import os
+from typing import Optional, Tuple
+
+import numpy as np
+
+THRESHOLD = float(os.environ.get("MATCH_THRESHOLD", "0.80"))
+
+
+class AnimalMatcher:
+    def find_match(
+        self,
+        new_embedding: list,
+        candidates: list[dict],
+    ) -> Optional[Tuple[int, float]]:
+        """
+        Compara new_embedding com os embeddings de candidates.
+        Retorna (animal_id, score) do melhor match acima do threshold,
+        ou None se nenhum match encontrado.
+
+        candidates: lista de dicts com chaves 'id' e 'embedding' (list[float]).
+        """
+        if not candidates or not new_embedding:
+            return None
+
+        new_vec = np.array(new_embedding, dtype=np.float32)
+
+        best_id: Optional[int] = None
+        best_score: float = 0.0
+
+        for animal in candidates:
+            emb = animal.get("embedding")
+            if not emb:
+                continue
+            score = self._cosine(new_vec, np.array(emb, dtype=np.float32))
+            if score > best_score:
+                best_score = score
+                best_id = animal["id"]
+
+        if best_score >= THRESHOLD:
+            return best_id, best_score
+        return None
+
+    @staticmethod
+    def _cosine(a: np.ndarray, b: np.ndarray) -> float:
+        norm_a = np.linalg.norm(a)
+        norm_b = np.linalg.norm(b)
+        if norm_a == 0.0 or norm_b == 0.0:
+            return 0.0
+        return float(np.dot(a, b) / (norm_a * norm_b))

db/schema.sql

@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS animals (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    species         TEXT NOT NULL CHECK (species IN ('dog', 'cat')),
+    description     TEXT,           -- JSON com atributos do Nemotron
+    embedding       BLOB,           -- vetor numpy serializado (float32, 384-dim)
+    first_seen      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    last_seen       DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    sighting_count  INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE IF NOT EXISTS sightings (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    animal_id   INTEGER NOT NULL REFERENCES animals(id) ON DELETE CASCADE,
+    photo_path  TEXT,               -- caminho relativo em /data/photos/
+    latitude    REAL,
+    longitude   REAL,
+    notes       TEXT,
+    created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_sightings_animal ON sightings(animal_id);
+CREATE INDEX IF NOT EXISTS idx_animals_last_seen ON animals(last_seen);
+CREATE INDEX IF NOT EXISTS idx_animals_species ON animals(species);

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.0
+pillow>=10.0.0
+huggingface_hub>=0.23.0
+sentence-transformers>=2.7.0
+numpy>=1.26.0

setup-git.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# setup-git.sh — Conecta o projeto ao HF Space e faz o primeiro push.
+# Execute no terminal dentro da pasta animal-visto/
+#
+# Antes de rodar:
+#   1. Crie um token de escrita em https://huggingface.co/settings/tokens
+#   2. Exporte: export HF_TOKEN=hf_xxxxxxxxxxxxxxxxx
+#   3. chmod +x setup-git.sh && ./setup-git.sh
+
+set -e
+
+SPACE_URL="https://huggingface.co/spaces/build-small-hackathon/pawmap"
+HF_GIT_URL="https://user:${HF_TOKEN}@huggingface.co/spaces/build-small-hackathon/pawmap"
+
+echo "🐾 Animal Visto — setup git"
+
+# Inicializar git se ainda não existir
+if [ ! -d ".git" ]; then
+  git init
+  git branch -M main
+fi
+
+# Configurar remote
+if git remote get-url origin &>/dev/null; then
+  git remote set-url origin "$HF_GIT_URL"
+else
+  git remote add origin "$HF_GIT_URL"
+fi
+
+# LFS para arquivos grandes (HF recomenda)
+git lfs install
+git lfs track "*.jpg" "*.png" "*.db"
+git add .gitattributes 2>/dev/null || true
+
+# Commit e push
+git add .
+git commit -m "feat: initial Animal Visto app
+
+- Gradio UI mobile-first com mapa Leaflet
+- Integração NVIDIA NIM (Nemotron Nano VL)
+- Matching por cosine similarity (sentence-transformers)
+- SQLite persistente via HF Storage Bucket"
+
+echo ""
+echo "Fazendo push para $SPACE_URL ..."
+git push --force origin main
+
+echo ""
+echo "✅ Deploy feito! Acesse: $SPACE_URL"
+echo ""
+echo "⚙️  Não esqueça de configurar os secrets no Space Settings:"
+echo "   NVIDIA_API_KEY = sua chave em https://build.nvidia.com"