Best Practices - Biologia Marina
Linee guida pratiche per chi sviluppa applicazioni AI/RAG/agent sul dominio della biologia marina, con riferimento alle fonti tassonomiche e alle pratiche di qualità del dato.
Usa sempre l'AphiaID WoRMS come identificatore stabile delle specie
I nomi scientifici latini sono soggetti a revisioni nomenclaturali: un genere può essere sinonimizzato, una specie può essere spostata in un altro genere, un epiteto può essere corretto. Usare solo il nome testuale come chiave in un corpus RAG o in un database produce duplicati e record orphan dopo ogni revisione. Fare: aggiungere il campo aphia_id a ogni record di specie e usarlo come foreign key stabile. WoRMS espone un'API REST (https://www.marinespecies.org/rest/AphiaRecordsByName/{scientificname}) che restituisce il record completo incluso il campo AphiaID. Non fare: usare il nome comune come identificatore - la stessa specie può avere decine di nomi comuni in italiano.
Cita sempre la fonte tassonomica e l'anno per ogni nome scientifico
Nei contenuti educativi e nei pack dati, ogni nome scientifico dovrebbe comparire nella forma completa: Genere specie Autore, Anno (es. Caretta caretta Linnaeus, 1758). Questo non è formalismo: la combinazione nome+autore+anno consente di risolvere ambiguità (omonimi: due specie in generi diversi con lo stesso epiteto) e di tracciare la fonte nomenclaturale. Fare: usare il formato WoRMS completo nelle voci di glossario e nelle didascalie di corpus.jsonl. Non fare: usare nomi latini truncati o senza autore nei contesti in cui la precisione tassonomica è richiesta (eval.jsonl, corpus.jsonl).
Valida ogni nome latino su WoRMS, FishBase o IUCN prima di includerlo nel corpus
I modelli linguistici generano nomi latini strutturalmente plausibili ma non attestati nelle fonti autorevoli. Prima di finalizzare un corpus RAG per biologia marina, verificare ogni nome scientifico su WoRMS (marinespecies.org) o FishBase (fishbase.org). Un nome non trovato non deve essere incluso. Fare: utilizzare l'API WoRMS AphiaIDByName (fuzzy search) per validare i nomi in batch. Non fare: fidarsi della coerenza interna del corpus generato dal LLM come unica validazione.
Distingui tra nome accettato, sinonimo e nome non valido
WoRMS classifica ogni record nomenclaturale come "accepted" (nome valido corrente), "unaccepted" (sinonimo o nome obsoleto rimandato al record accettato), o "nomen dubium" (nome di dubbia applicazione). Nei tuoi dati e nei tuoi prompt, usa sempre il nome accepted. Fare: richiamare AphiaRecordsByName con marine_only=true e filtrare status="accepted". Non fare: usare sinonimi obsoleti (es. Posidonia oceanica non ha sinonimi validi accettati, ma altri generi come Cystoseira hanno subito revisioni recenti verso Gongolaria e Treptacantha).
Segmenta il corpus per profondità batimetrica nelle query RAG
Il dominio biologia marina ha una dimensione spaziale verticale fondamentale: un documento che descrive un organismo mesopelagico (200–1000 m) non è rilevante per una query su organismi bentonici costieri (0–50 m). Aggiungere metadati di zona batimetrica (coastal, mesopelagic, bathypelagic, abyssal) a ogni chunk di corpus.jsonl e filtrarli nella query di retrieval. Fare: includere il campo depth_zone nei metadati di ogni corpus entry. Non fare: trattare l'oceano come un ambiente omogeneo nel retrieval - la produzione di risposte mismatched (es. organismi profondi in risposta a domande su zona intertidale) degrada la qualità del sistema RAG.
Gestisci le nomenclature in doppia lingua (it+en) con tabelle di concordanza
Un Knowledge Pack bilingue deve garantire che il termine italiano e quello inglese si riferiscano esattamente alla stessa specie o concetto. Non sempre la traduzione è ovvia (es. "riccio di mare" → Paracentrotus lividus in Mediterraneo, ma in inglese "sea urchin" è generico; "orca" in italiano = "killer whale" in inglese = Orcinus orca). Fare: mantenere una tabella {it_term, en_term, aphia_id, latin_name} come sorgente di verità per la traduzione dei termini; includere l'AphiaID come pivot stabile. Non fare: tradurre i nomi comuni da una lingua all'altra senza ancorare la traduzione al nome scientifico.
Includi disclaimer su usi operativi in contesti safety-adjacent
Biologia marina come dominio educativo è low-stakes, ma alcuni contenuti si avvicinano a contesti safety-adjacent: toxicità di specie (pesci palla: Lagocephalus sceleratus; ricci Toxopneustes pileolus; meduse Physalia physalis), rischi da ingestione di molluschi durante HAB, norme sulla sicurezza subacquea. Fare: includere un disclaimer esplicito "Informazione a scopo educativo - non sostituisce la consulenza di un esperto qualificato" nelle sezioni che trattano tossicità o sicurezza in acqua. Non fare: elencare proprietà tossicologiche come istruzioni operative o claim assoluti.
Struttura i prompt di sistema per rispettare la gerarchia tassonomica
Un sistema RAG o chatbot su biologia marina è più preciso se il prompt di sistema include esplicitamente la gerarchia tassonomica linneana (dominio → regno → phylum → classe → ordine → famiglia → genere → specie) e istruisce il modello a riportare sempre il livello tassonomico pertinente per la risposta. Fare: inserire nel system prompt una sezione "Tassonomia: rispondi sempre specificando phylum e, se disponibile, il nome scientifico WoRMS accettato". Non fare: lasciare il modello libero di usare nomi comuni ambigui senza ancoraggio scientifico.
Differenzia chiaramente tra dati di distribuzione storica e attuale
Le distribuzioni geografiche delle specie cambiano nel tempo per riscaldamento marino, invasioni biologiche e pressioni di pesca. Un corpus che mescola dati storici (anni '80) con dati attuali produce retrieval incoerente. Fare: aggiungere il campo observation_year o almeno decade a ogni record di distribuzione; filtrare nelle query per periodo. Non fare: presentare come "distribuzione attuale" dati estratti da fonti che risalgono a decenni prima senza verifica aggiornata su GBIF o WoRMS.
Usa formati geoJSON per la distribuzione spaziale delle specie
Le coordinate di distribuzione delle specie marine devono essere archiviate in formato georeferenziato standard (GeoJSON, WKT) con datum WGS84 esplicito. I sistemi RAG geospaziali possono filtrare per area geografica solo se i dati sono in formato standard. Fare: usare il formato GeoJSON FeatureCollection con proprietà {species, aphia_id, date, depth_m, source_url}. Non fare: archiviare coordinate come stringhe di testo non parsabili ("vicino a Capo Gallo, Sicilia").
Valida JSONL riga per riga prima del commit
I file eval.jsonl e corpus.jsonl sono letti riga per riga; una singola riga malformata (virgolette non escapate, caratteri Unicode non UTF-8, campo mancante) interrompe il parsing e invalida l'intera sessione di eval o retrieval. Fare: eseguire python3 -c "import json; [json.loads(l) for l in open('eval.jsonl')]" come gate pre-commit e assicurarsi che ogni riga sia valida. Non fare: commettere JSONL non validato - un file corrotto non produce errori visibili fino al runtime del sistema RAG.
Usa il codice IUCN come valore enum per lo stato di conservazione
Lo stato di conservazione di una specie deve essere archiviato come enum dei codici IUCN standard (EX, EW, CR, EN, VU, NT, LC, DD, NE) e non come testo libero ("in pericolo", "vulnerabile"). I codici sono stabili tra lingue e permettono il filtraggio programmatico. Fare: aggiungere il campo iucn_status: "VU" a ogni record di specie nel corpus.jsonl. Non fare: usare descrizioni in prosa per lo stato di conservazione nei campi dati strutturati.