Cerca entita' geopolitiche storiche nel database AtlasPI applicando filtri combinabili su nome, anno, tipo, continente e status. Usa questo tool quando l'utente chiede di trovare imperi, regni, repubbliche, citta'-stato, sultanati, ducati, ecc. con criteri specifici (es: 'tutti gli imperi attivi nel 100 a.C. in Asia'). Ritorna un elenco paginato con id, nome originale, lingua, intervallo temporale, capitale e geometria GeoJSON. Per dettagli completi su una singola entita', usa get_entity con l'id ottenuto qui.

Recupera il dettaglio completo di una entita' storica dato il suo id numerico. Ritorna nome originale e lingua, varianti linguistiche con fonti, capitale (nome + coordinate), confine GeoJSON, intervallo temporale, confidence_score, fonti citate e metadati storici. Usa questo tool dopo search_entities o snapshot_at_year per approfondire una specifica entita'.

Fetch multiple entities by ID in a single batch request — much faster than calling get_entity N times. Use when the user asks to compare several empires/kingdoms, or when you've just received a list of related IDs (from successors, predecessors, similar, etc.) and need full detail for all. Max 100 IDs per call. Returns {requested, found, not_found, entities}.

Restituisce uno snapshot del mondo in un dato anno: tutte le entita' geopolitiche attive in quell'anno (year_start <= anno <= year_end), con possibilita' di filtrare per tipo o continente. Usa questo tool per domande del tipo 'che mappa politica c'era nel 300 a.C.?' o 'quali regni esistevano in Africa nel 1500?'. Ricorda: gli anni negativi sono a.C.

Trova le entita' geopolitiche piu' vicine a una coppia di coordinate (latitudine, longitudine) attive in un dato anno. Ordina per distanza geodetica dalla capitale dell'entita'. Usa questo tool per domande del tipo 'cosa c'era vicino a lat 41.9, lon 12.5 nel 100 d.C.?' (cioe' Roma) o 'quali entita' circondavano queste coordinate nel medioevo?'.

v6.34: reverse-geocoding temporale. Dato un punto geografico (lat, lon) e un anno, restituisce tutte le entita' storiche il cui boundary_geojson contiene quel punto in quell'anno. Primary use case: GENEALOGIA / DIASPORA ("Il mio bisnonno da Leopoli nel 1905 — sotto che stato era?"). Due modalita': (1) year-specific: entita' che controllavano il punto in un anno; (2) include_history=true: timeline completa di TUTTI gli imperi/ regni che hanno mai controllato quel punto, ordinati cronologicamente. Se il punto e' in territorio contestato (ETHICS-003), ritorna tutte le entita' che lo rivendicano con status='disputed', senza arbitrare la sovranita'. Usa per domande tipo 'chi comandava a Istanbul nel 1500?', 'che impero controllava Berlino nel 1945?', 'storia di Gerusalemme dal 1000 a.C. a oggi' (include_history=true).

Confronta due entita' storiche dato il loro id numerico. Ritorna un report strutturato con sovrapposizione temporale, differenze di estensione territoriale, diversita' di status, capitali e fonti. Utile per domande comparative tipo 'paragona Roma Repubblicana e Impero Bizantino' o 'che differenze ci sono tra il Sacro Romano Impero e l'Impero Carolingio?'.

Restituisce una entita' storica casuale, opzionalmente filtrata per tipo, anno, continente o status. Pensato per esplorazione, suggerimenti, generazione di curiosita' storiche o per permettere all'agente di proporre 'lo sapevi che...' contestuali. Esempio: random_entity(type='khanate', continent='Asia') ritorna un khanato asiatico a caso.

Restituisce la timeline dei cambi territoriali di una entita': annessioni, perdite di territorio, cambi di capitale, transizioni di regime, eventi di scissione o unificazione. Ogni evento ha anno, descrizione, fonte e (quando disponibile) acquisition_method per documentare se un territorio fu acquisito per conquista, matrimonio dinastico, trattato, ecc. Importante per ricostruire l'arco storico di un'entita' nel tempo.

Trova entita' storiche simili a quella specificata, ordinate per punteggio di similarita' (0.0-1.0). Il punteggio considera: tipo di entita' (35%), sovrapposizione temporale (30%), durata simile (15%), confidence simile (10%), stesso status (10%). Usa questo tool quando l'utente chiede 'quali imperi erano simili a Roma?' o 'trova stati paragonabili al Sacro Romano Impero' o 'suggerisci paralleli storici per l'Impero Mongolo'. Il risultato include id, nome, tipo, periodo e punteggio per ogni entita' simile.

Restituisce statistiche aggregate del dataset AtlasPI: numero totale di entita', breakdown per tipo, distribuzione per status (confirmed / uncertain / disputed), distribuzione per continente, intervallo temporale coperto (year_range), confidence_score medio, numero totale di fonti citate e di cambi territoriali. Utile come tool di scoperta iniziale per capire la copertura del dataset prima di formulare query specifiche.

Cerca eventi storici con filtri su anno, tipo, status e silenzio documentato. ETHICS-007: i tipi usano termini espliciti — GENOCIDE, COLONIAL_VIOLENCE, ETHNIC_CLEANSING, MASSACRE, DEPORTATION — senza eufemismi. Per domande tipo 'quali genocidi sono registrati nel XX secolo?' (event_type='GENOCIDE', year_min=1900, year_max=2000). ETHICS-008: known_silence=true filtra eventi storicamente insabbiati (es. genocidio armeno nella storiografia turca).

Dettaglio completo di un evento storico dato il suo id: tipo, anno, descrizione, entità coinvolte con ruolo esplicito (MAIN_ACTOR, VICTIM, PARTICIPANT, AFFECTED, WITNESS, FOUNDED, DISSOLVED), fonti con page/confidence, ethical_notes. ETHICS-007: il main_actor è sempre presente — la voce attiva ('chi ha fatto cosa a chi') è obbligatoria per eventi di violenza.

Restituisce tutti gli eventi storici in cui una data entità compare (fondazione, conquiste, eventi subiti, dissoluzione). Filtro opzionale su role (MAIN_ACTOR, VICTIM, ecc.). Usa questo tool dopo get_entity/search_entities per ricostruire la storia eventuale di una specifica entità (es. 'quali eventi ha subito l'Impero Ottomano?'). Distingue tra ruoli attivi (conquiste operate) e subiti (conquiste ricevute, genocidi, colonizzazioni).

Recupera gli eventi storici geolocalizzati attorno a un dato anno, ottimizzato per la visualizzazione su mappa. Restituisce un payload leggero (10 campi per evento) con solo eventi che hanno coordinate. La finestra temporale si auto-espande per epoche antiche: ±50 anni per anni < -1000 a.C., ±25 per il periodo classico, ±10 per l'età moderna. Usa questo tool quando l'utente chiede 'cosa è successo vicino a [luogo] nel [anno]?' o per popolare una visualizzazione mappa con eventi. Non include description/sources — usa get_event per i dettagli di un singolo evento.

Restituisce gli eventi storici avvenuti in una specifica data del calendario (mese e giorno), attraverso tutti gli anni nel dataset. Formato: MM-DD (es. '07-04' per il 4 luglio, '10-12' per il 12 ottobre). Utile per curiosità storiche, efemeridi, quiz, contenuti 'accadde oggi'. Esempio: on_this_day('10-12') potrebbe restituire lo sbarco di Colombo (1492) e il giorno della scoperta del Nuovo Mondo.

Restituisce le date (MM-DD) che hanno almeno un evento nel dataset. Usa PRIMA di on_this_day per sapere se una data restituirà risultati, oppure per suggerire date 'interessanti' all'utente (es. 'In quali giorni dell'anno ci sono più eventi storici?'). La risposta include unique_dates (quante date uniche), coverage_pct (% dell'anno coperta), e la lista completa dates con mm_dd + event_count. Non richiede parametri — è un metadato del dataset.

Lista epoche storiche strutturate (Bronze Age, Classical Antiquity, Edo Period, Cold War, ecc.). Ogni periodo ha scope regionale esplicito (es. 'Middle Ages' è europeo, non globale) e confidence_score. Filtrabile per region, period_type (age/era/period/dynasty/epoch), anno (ritorna periodi che includono quell'anno), status. USA per: inquadrare un anno o entità nel contesto storico, rispondere a domande tipo 'In che epoca era il 1200 in Europa?', 'Quali periodi esistono in Giappone?'. ETHICS: le periodizzazioni sono costrutti storiografici; il campo historiographic_note documenta controversie accademiche.

Dettaglio completo di un periodo storico dato il suo ID numerico. Include description, historiographic_note (controversie accademiche), alternative_names (es. 'Dark Ages' per 'Early Middle Ages') e sources bibliografiche.

Dettaglio di un periodo dato lo slug URL-friendly (es. 'bronze-age', 'edo-period', 'islamic-golden-age'). Più leggibile di get_historical_period quando l'ID non è noto.

Ritorna tutte le epoche storiche che includono un dato anno, across regioni. ESSENZIALE per contestualizzare un evento o entità storica. Es. year=1500 → ritorna [Renaissance (europe), Late Middle Ages (europe), Edo Period NO (inizia nel 1603), Ottoman Classical Age (near_east)...]. Opzionale filtro per regione.

Ritorna le epoche storiche che si sovrappongono con la lifespan di una specifica entità (id entity). Usa per contestualizzare un'entità: es. 'Durante quali epoche esisteva la Repubblica di Venezia?' → [Early Middle Ages, High Middle Ages, Late Middle Ages, Renaissance, Early Modern Period, Industrial Revolution...].

Ritorna le epoche storiche in cui è avvenuto un evento specifico. Es. event_id=123 (Battle of Tours, 732) → [Early Middle Ages (europe), Islamic Golden Age (near_east)].

Snapshot aggregato del mondo in un dato anno: epoche attive, entità politiche esistenti, eventi di quell'anno, città attive, catene dinastiche in corso. Una sola chiamata per rispondere a 'Com'era il mondo nel 1250?' o 'Che succedeva nel 500 aC?'. Risponde con: periods (per regione), entities (top-N per confidence + breakdown per tipo), events_that_year, cities (top-N + breakdown), chains attive. Parametro top_n controlla quanti elementi top-N per categoria (default 10).

Cerca città storiche con filtri su anno di attività, tipo funzionale (CAPITAL, TRADE_HUB, RELIGIOUS_CENTER, FORTRESS, PORT, ACADEMIC_CENTER, INDUSTRIAL_CENTER, MULTI_PURPOSE), entità politica di appartenenza, bbox geografica. Una città è separata dalla capital_* di GeoEntity perché può sopravvivere più entità politiche (es. Costantinopoli/Istanbul attraversa Bizantino → Ottomano → Repubblica di Turchia).

Dettaglio di una città storica: nome originale, varianti linguistiche e storiche (ETHICS-009: rename coloniali/imperiali documentati — es. Konstantinoupolis → Istanbul, Königsberg → Kaliningrad, Tenochtitlan → Ciudad de México, Calcutta → Kolkata), coordinate, tipo, population_peak, fonti, entità politica corrente. Usa dopo search_cities per approfondire.

Cerca rotte commerciali storiche con filtri su anno di attività, tipo geografico (LAND, SEA, RIVER, CARAVAN, MIXED) e involves_slavery. ETHICS-010: involves_slavery=true restituisce le rotte che trafficavano esseri umani schiavizzati come merce primaria (Trans-Atlantic, Trans-Saharan Slave, Indian Ocean Slave Route). Il flag è esplicito perché la distinzione è eticamente rilevante. Nota: 'Silk Road' è attribuzione 1877 di Richthofen, non un'auto-designazione delle carovane storiche.

Dettaglio di una rotta commerciale: nome originale, tipo geografico, intervallo temporale, waypoints (città attraversate in ordine) con coordinate, commodities principali, flag involves_slavery, geometry_geojson per visualizzazione, ethical_notes dettagliate. ETHICS-010: le rotte della tratta atlantica documentano le stime di Middle Passage (~1.8M morti su 12.5M embarcati).

Cerca catene successorie/dinastiche/coloniali con filtri su chain_type (DYNASTY / SUCCESSION / RESTORATION / COLONIAL / IDEOLOGICAL / OTHER), region, year (almeno un'entità della catena attiva in quell'anno), status. ETHICS-002: ogni link ha transition_type esplicito (CONQUEST / REVOLUTION / REFORM / SUCCESSION / DECOLONIZATION / PARTITION / UNIFICATION / DISSOLUTION / ANNEXATION) — non esiste 'succession' generico che maschera violenze. ETHICS-003: chain_type=IDEOLOGICAL (es. Sacrum Imperium Romanum → Deutsches Kaiserreich → Deutsches Reich) porta avvertimento che la continuità self-proclaimed non implica legittimità.

Dettaglio di una catena successoria con tutti i link in ordine cronologico. Ogni link ha sequence_order, entità di riferimento, transition_year, transition_type (ETHICS-002: esplicito, no eufemismi), is_violent, description e ethical_notes specifiche per la singola transizione. Usa dopo search_chains.

Restituisce le catene in cui l'entità data ha un predecessore (sequence_order > 0), insieme al predecessore immediato, transition_year, transition_type, is_violent e ethical_notes della transizione CHE HA PORTATO A questa entità. Usa per domande tipo 'che entità ha preceduto la Repubblica di Turchia?' (→ Ottoman Empire, transition 1923 REVOLUTION).

Restituisce le catene in cui l'entità data ha un successore, insieme al successore immediato, transition_year, transition_type, is_violent e ethical_notes della transizione CHE HA PORTATO DA questa entità all'entità successiva. Usa per domande tipo 'cosa è venuto dopo Tawantinsuyu?' (→ Viceroyalty of Peru, transition 1542 CONQUEST).

Restituisce la timeline unificata di un'entità: eventi storici (via EventEntityLink), cambi territoriali e transizioni di catene successorie (predecessori + successori) in un unico stream ordinato cronologicamente. Ogni voce ha un campo discriminatore 'kind' fra 'event', 'territory_change' e 'chain_transition'. Usa questo tool invece di chiamare get_evolution + events_for_entity + entity_predecessors + entity_successors separatamente quando l'utente chiede la storia completa di un'entità (es. 'raccontami tutta la storia dell'Impero Romano d'Oriente'). Ritorna counts per ogni kind piu' lo stream unificato.

Ricerca approssimata (fuzzy) sui nomi delle entità storiche — tollera errori di spelling, trascrizioni diverse e script differenti. Usa difflib.SequenceMatcher a livello di caratteri Unicode, quindi funziona anche cross-script (latino, cirillico, arabo, cinese, devanagari, ecc.). Esempio: q='safavid' trova 'دولت صفویه' (script arabo), q='Constantinople' trova 'Κωνσταντινούπολις' (script greco). Preferisci questo tool quando search_entities non trova risultati per via di translitterazione non standard o spelling approssimativo.

Trova le città storiche più vicine a una coppia di coordinate (latitudine, longitudine), opzionalmente filtrate per anno di attività e tipo (CAPITAL, TRADE_HUB, ecc.). Calcola la distanza haversine client-side e ordina per distanza crescente. Usa per domande tipo 'che città c'erano vicino a 41.9, 12.5 nel 100 d.C.?' (città vicino Roma) o 'qual è il trade hub più vicino a Venezia nel 1400?'. Nota: questo tool trova CITTÀ storiche (dataset separato da GeoEntity) — per capitali di imperi/regni usa nearby_entities.

Diff macro-storico del mondo tra due anni: ritorna le entità apparse fra year1 e year2, quelle scomparse, e gli id di quelle persistenti. Opzionalmente filtra per tipo o continente. Usa per domande tipo 'cosa è cambiato nel Mediterraneo tra il 300 a.C. e il 100 d.C.?' o 'quali imperi sono apparsi tra il 1800 e il 1900 in Africa?'. È composizione client-side di due snapshot — più economico di due chiamate separate se servono solo id+nomi.

Sottometti un feedback strutturato sul database AtlasPI: correzioni di dati, citazioni mancanti, polygon imprecisi, bias report, ecc. Usa questo tool quando hai informazioni VERIFICATE che contraddicono i dati attuali, oppure quando vuoi suggerire una fonte accademica non ancora presente.

Il feedback non modifica direttamente i dati: va in stato 'pending' e richiede review umana per contenuti storici (vedi ETHICS).

Quando usarlo:

• Trovi una data sbagliata supportata da una fonte (es. year_end di una dinastia)

• Vuoi aggiungere una citation accademica a un'entita'

• Noti un bias di rappresentazione (es. nome coloniale come primario)

• Identifichi un'entita' storica mancante dal database

Best practice: fornisci sempre 'citation' (la fonte) e 'reasoning' (1-3 frasi che spiegano perche').

Lista i feedback gia' sottomessi da altri agenti/umani. Utile per cross-validation: prima di sottomettere un nuovo feedback, controlla se qualcuno ha gia' segnalato lo stesso problema.

Filtra per status (pending, accepted, rejected, ...), category, entity_id, o submitter_type. Trasparenza pubblica.

Counters aggregati sul feedback: totale, by_status, by_category, by_submitter_type, last_24h, last_7d. Utile per capire l'attivita' della community e identificare le categorie piu' calde.