SwhaleAI/marine-mammals-api

🐋 CetaScope

Dashboard d'exploration des mammifères marins via chatbot en langage naturel.

   

Aperçu

CetaScope est une application web full-stack qui permet d'explorer des millions d'observations de cétacés à travers une interface conversationnelle en français. Pose une question, obtiens une carte, un graphique ou une fiche espèce — sans ligne de code.

Les données sont synchronisées automatiquement depuis OBIS, GBIF et l'IUCN via des pipelines GitHub Actions, et enrichies par Gemini AI (morphologie, biologie). ---

Fonctionnalités

• —Chatbot en français propulsé par Gemini 2.0 Flash — cartes, séries temporelles, fiches espèce
• —7 types de visualisations : carte d'observations, choroplèthe, évolution annuelle, profil espèce, top espèces, timeline IUCN, réponse texte
• —Navigation directe — clic sur une espèce → profil immédiat sans passer par le chat
• —Boutons de navigation rapide sur chaque profil (Observations · Évolution · Historique IUCN)
• —Historique de navigation — trail dots, flèches ← →, bouton retour navigateur
• —Cache intelligent — données en localStorage, images Wikipedia mises en cache, chargement instantané
• —Pipeline automatisé — synchronisation hebdomadaire/mensuelle via GitHub Actions
• —90 espèces couvertes — de la baleine bleue au marsouin commun

Architecture

┌─────────────────────────┐     ┌──────────────────────────┐     ┌───────────────────────┐
│  Frontend               │     │  Backend                 │     │  Base de données      │
│  React 18 · D3.js       │────▶│  FastAPI · asyncpg       │────▶│  PostgreSQL 15        │
│  GitHub Pages           │     │  HuggingFace Spaces      │     │  PostGIS · Supabase   │
└─────────────────────────┘     └──────────────────────────┘     └───────────────────────┘
                                          ▲
                                          │
                                ┌─────────────────────┐
                                │  GitHub Actions      │
                                │  Sync OBIS/GBIF      │
                                │  Enrichissement LLM  │
                                └─────────────────────┘

Stack technique

Sources de données

Démarrage local

Prérequis

• —Python 3.12+
• —PostgreSQL 15 avec extension PostGIS
• —`uv` (gestionnaire de paquets Python)
• —Fichier .env à la racine (voir .env.example)

Backend

cd backend
uv sync
uv run uvicorn app.main:app --reload --port 7860

L'API est disponible sur http://localhost:7860. La documentation Swagger est accessible sur /docs.

Frontend

Modifier frontend/config.js pour pointer vers le backend local :

window.CETA_CONFIG = {
  apiBase: 'http://localhost:7860',
  // ...
};

Puis ouvrir frontend/index.html directement dans le navigateur, ou le servir statiquement :

cd frontend
python -m http.server 3000

Scripts de données

cd scripts
uv sync

# Récupérer les espèces depuis WoRMS
uv run python fetch_species.py

# Enrichir les données (IUCN, morphologie, biologie)
uv run python enrich_iucn.py
uv run python enrich_morpho.py
uv run python enrich_biology.py

# Récupérer les observations OBIS/GBIF
uv run python fetch_observations.py

API — Endpoints

Le chatbot retourne toujours un objet { type, data, message } permettant au frontend de choisir la visualisation adaptée.

Pipeline de données (GitHub Actions)

Structure du projet

cetascope/
├── frontend/          # Interface React (statique, sans bundler)
├── backend/           # API FastAPI
│   └── app/
│       ├── routers/   # Routes par domaine (species, map, analytics…)
│       ├── services/  # Logique métier
│       └── models/    # Schémas Pydantic
├── shared/            # Package Pydantic partagé (backend + scripts)
├── scripts/           # Scripts de synchronisation et d'enrichissement
├── db/                # Migrations SQL
├── docs/              # Spécification UX + screenshots
└── .github/workflows/ # CI/CD

Contact

Lucien Laumont — lucienlaumont36@gmail.com

Projet portfolio — contributions non sollicitées.

Licence

MIT © 2025 Lucien Laumont