Panoramica

L'Analista geopolitico strutturale è uno strumento per condurre analisi geopolitiche rigorose seguendo il metodo strutturale, fase per fase. Ogni fase compone un aspetto dell'analisi (ammissibilità, parametri, classificazione, proprietà dello spazio, relazioni/attori, scenari, ecc.).

Quando l'app si ferma dopo una fase, sei tu a decidere se proseguire, ottenere informazioni sullo stato corrente, o ricalibrare elementi precedenti.

In breve

• Scrivi qualcosa per proseguire alla fase successiva
• Usa slash-comandi (/stato, /compara, ecc.) per azioni specifiche
• Leggi le correzioni di P10 se suggerite, ma sono informative, non obbligatorie
• Il report finale (P13) può essere generato con /report dopo P12

Comandi disponibili

Fai click su questi comandi slash (/comando) in qualsiasi momento durante l'analisi per eseguire azioni specifiche.

Avanzamento automatico

Se non usi un comando slash, scrivi un testo libero per proseguire alla fase successiva:

• Una frase, una domanda, un'osservazione
• Anche solo continua o ok
• Il testo viene passato come contesto (l'insieme di dati, informazioni e messaggi precedenti che un sistema usa per capire una richiesta e dare una risposta coerente) alla fase successiva

Modalità di conoscenza (EIL)

Con EIL_ABILITATO = true (config.php / config-work.php) e le credenziali configurate, in sidebar compare un selettore Conoscenza a quattro opzioni. Come la Modalità, la scelta si fissa al primo messaggio (fase P00) e non cambia a metà analisi. Con la costante a false il selettore è nascosto e nessuna query a EIL parte, nemmeno chiamando l'endpoint a mano (controllo autoritativo lato server).

Macro-sezioni

EIL è interrogato una volta per macro-sezione, non per fase: S1 inquadramento (P03–P04), S2 caratteri dello spazio (P05–P06), S3 relazioni/attori o attore dominante (P07–P08 oppure P09a-c). La risposta è memorizzata in eil_sezioni nello stato dell'analisi e riusata da tutte le fasi della sezione, con lo stesso eil_session_id (follow-up per EIL).

Se EIL non risponde

• Certificata: l'analisi si sospende con tipo: 'eil_non_disponibile', prima di segnare la sezione come interrogata — così un semplice reinvio del messaggio ritenta EIL. Nessun'altra fonte è ammessa in questa modalità.
• Mista / Mista integrata: non blocca. La fase prosegue: la sezione è segnata come "vista" senza contesto EIL, e grounding + ricerca approfondita restano il fallback.
• EIL risponde ma senza fonti pertinenti (citations e sources_consulted vuoti): non è un errore. In tutte le modalità l'analisi prosegue; in Certificata ciò che manca resta lacuna.

Provenienza nel report

Nelle modalità EIL, il report P13 marca le citazioni di documenti certificati con [EIL] dopo la parentesi — es. (limes-13062026.pdf, n.d.) [EIL] — e in bibliografia mostra il chip 📚 documento certificato (EIL). Le fonti web restano (Autore, Anno) senza marcatore. Gli "elementi aggiuntivi da ricerca Gemini" della modalità integrata vanno etichettati con la loro provenienza reale (ricerca_web_attiva / inferenza_propria), mai come EIL.

Vedi anche Token e costi per come il consumo EIL entra nei totali, e Fonti e bibliografia per la tabella completa delle provenienze.

Flusso della pipeline

Ecco il percorso completo dell'analisi, con i due rami principali (A/B) che si diramano dopo la classificazione (P04):

Rami paralleli (A vs B)

Tipo A: Analisi di uno spazio geopolitico e le relazioni tra gruppi di attori

• P07 analizza le conflittualità e le relazioni
• P08 mappa i singoli attori e il loro peso

Tipo B: Analisi di uno spazio sottoposto al controllo di un attore dominante

• P09a esamina la coesione interna dell'attore
• P09b valuta l'intensità della presa di controllo
• P09c identifica i fattori di forza e proiezione

Quando la pipeline attende una tua scelta

L'app si ferma dopo ogni fase e attende il tuo input. Ecco cosa succede in ciascun punto:

P01 — Ammissibilità

Il tema proposto viene valutato. Se ammesso in quanto ritenuto suscettibile di essere affrontato in una prospettiva geopolitica (e quindi non di diverso approccio disciplinare), la pipeline ti chiede di continuare. Se rifiutato o riformulabile, suggerisce un'alternativa.

P02–P05, P06, P07–P09, P11–P12

Al termine di ogni fase, digita qualcosa (comando slash o testo libero) per proseguire. L'output mostra i risultati della fase corrente in forma strutturata (chip colorati, tabelle, sezioni).

P10 — Autoverifica ⚠️

Questa è la fase critica: P10 revisiona tutta l'analisi precedente e segnala:

• Coerenza complessiva (soddisfacente / con riserve / problematica)
• Problemi rilevati (leader-centrismo, monocausalità, strutturale/contingente non distinti)
• Correzioni proposte per ogni problema

Vedi la sezione P10 (Autoverifica) per capire come interpretare e applicare le correzioni.

P13 — Report

Dopo P12, fai click su /report per generare il report narrativo assemblato. Se non hai già cliccato su /report, la pipeline ti suggerirà di farlo.

P14 — Comparazione (opzionale)

Dopo P11, puoi usare /compara [descrizione] per confrontare la tua analisi con un altro caso. Non è obbligatorio; P13 si genera in ogni caso.

Fase P01: Ammissibilità

P01 è il gate d'ingresso della pipeline: prima di avviare l’analisi l’applicazione si preoccupa di verificare che il tema proposto sia davvero trattabile con il metodo geopolitico strutturale. È l'unica fase che può interrompere l'analisi (esito RESPINTO) invece di limitarsi a segnalare un problema e proseguire.

Il test decisivo

Tutto il gate ruota attorno a una sola domanda, applicata al tema proposto:

Se questa domanda non è nemmeno formulabile — non esiste una porzione di spazio di cui si possa predicare il dominio o la contesa — il tema non ammette una risposta geopolitica e va respinto o riformulato. P01 verifica quattro condizioni in sequenza: esiste un candidato-spazio (esplicito o ricavabile), è davvero uno spazio materiale e non una metafora, vi si esercita potere osservabile, e la risposta sarebbe informativa (non ovvia e priva di conseguenze).

I campi che P01 restituisce

Le cinque famiglie di temi non adatti

Le ultime due sono le "categorie senza recupero": non consentono mai l'esito AMMESSO, e se il tema risulta RIFORMULABILE la proposta di riformulazione diventa obbligatoria (senza, il tema resta semplicemente respinto).

Fase P02: Parametri

Subito dopo che P01 ammette il tema, P02 fissa il perimetro e l'impostazione dell'analisi: dove guardare, quanto in profondità, e su quale arco temporale. Sono le decisioni che condizionano tutte le fasi successive — un perimetro tracciato male o un solo fattore causale individuato qui si trascinano fino al report finale.

I campi che P02 fissa

Il perimetro: quanto ampio tracciarlo

Il criterio piu_ampio_possibile_per_incertezza è quello che P02 usa di default quando i confini dello spazio non sono ovvi. La regola del metodo è esplicita: meglio una riduzione deliberata successiva che un'esclusione preventiva affrettata — tagliare fuori qualcosa che poi risulta rilevante è un errore peggiore che includere, all'inizio, qualcosa di superfluo.

Profondità storica: perché servono almeno tre fattori

Un'analisi che individua un solo fattore causale è, per il metodo, il primo sintomo di uno squilibrio monocausale — il prompt di P02 lo vieta esplicitamente, chiedendo almeno tre fattori distinti, ciascuno sulla propria scala temporale:

Un fattore può anche essere segnato come invariante (es. la posizione assoluta di uno spazio): per quelli non serve nemmeno ricostruire una traiettoria storica.

Come vengono trovati questi parametri

P02 riceve in input l'esito di P01 (il tema ammesso) e propone i parametri seguendo le regole del metodo appena descritte. Ma c'è un punto poco intuitivo, utile da sapere:

In pratica: se hai già un'idea precisa del perimetro (es. "limita l'analisi al solo bacino del Mediterraneo orientale, taglio di profondità"), è qui — e solo qui — che vale la pena scriverlo esplicitamente. Lasciato vuoto o generico ("continua", "ok"), P02 propone i default che ritiene più adatti al tema.

Modifica manuale dei parametri, senza richiamare il modello

Sotto il riepilogo di P02 compare il pulsante "✏️ Modifica parametri". Apre un form precompilato con i valori proposti, dove ogni campo a scelta chiusa — criterio, ambienti coinvolti, scale coinvolte, taglio, impianto, scala temporale di ciascun fattore causale — è una tendina o un gruppo di checkbox con tutti e soli i valori ammessi dallo schema, mai testo libero da indovinare. I campi che nello schema sono effettivamente testo libero (descrizione del perimetro, limiti di generalizzabilità, fattore causale, punto di partenza, parametri assunti non confermati) restano campi di testo, editabili ma non "a scelta".

A differenza di /riclassifica (che rifà la fase richiamando di nuovo Gemini), qui non parte nessuna nuova chiamata al modello: il server valida i valori scelti contro le stesse liste che li hanno generati (Validators::opzioniP02(), letta direttamente da schemas/p02_params.json — se lo schema cambia, form e validazione lo seguono senza bisogno di toccare altro) e, se sono tutti validi, sostituisce l'output già salvato di P02 con quello corretto. Nessun token consumato, nessun costo, effetto immediato: la risposta di successo non porta un campo token_usage, apposta perché il frontend non aggiunga un chip token o un badge grounding che non avrebbe senso qui.

Un valore fuori lista (es. un client che chiamasse l'endpoint a mano con un valore inventato) non viene mai salvato: il server risponde con tipo: 'p02_override_invalido' e un messaggio che elenca esattamente quale campo non è valido — distinto apposta da errore_validazione, che nel resto della pipeline significa "il modello ha fallito i tentativi previsti", non "l'utente ha inviato un valore scorretto". Ogni sovrascrittura riuscita lascia una riga nel log per-utente (storage/log/<utente>.log): P02 parametri modificati manualmente dall'utente.

Fase P03: Introduzione

P03 costruisce la cornice introduttiva dell'analisi, prima ancora della classificazione (P04): perché il tema merita uno studio strutturato, quale domanda guiderà l'analisi, e — quando è già formulabile — un'ipotesi di partenza. Riceve in input l'esito di P01 e i parametri di P02.

I tre campi di P03

Fase P04: Classificazione

P04 è il cuore decisionale della pipeline: assegna il tipo (A, B, C.1, C.2 o SOSPESO) da cui dipende l'intero ramo successivo — se il tema è di tipo C, la pipeline devia prima su P05 (Spazializzazione); da lì in poi, e per i tipi A/B fin da subito, il tipo effettivo decide se si procede verso P07/P08 (ramo A) o P09a/b/c (ramo B).

I due assi indipendenti

Accertamento sostanziale, non formale

La regola guida di P04 è che il dominio va accertato sostanzialmente, non per attribuzione convenzionale: uno spazio giuridicamente sotto la sovranità di un attore può essere di fatto conteso. Le tre zone grigie verificate esplicitamente sono il vuoto di potere (transitorio, non pregiudica l'ammissibilità), lo spazio libero con eventuale politicizzazione prospettica (un'assenza di interesse oggi può dipendere da limiti tecnologici destinati a cadere), e la trappola territoriale (l'idea che uno spazio esista stabilmente solo perché oggi corrisponde a un territorio riconosciuto sotto un'unica sovranità).

Fase P05: Spazializzazione

P05 esiste solo per i temi classificati tipo C in P04 — uno spazio non pre-individuato, come un settore merceologico o un fenomeno sociale. Il suo compito è ricostruire un vero perimetro spaziale a partire da un oggetto di studio che inizialmente non ne ha uno esplicito, e infine ricondurre il tema al tipo A o B, sbloccando così le fasi successive (P06 in poi).

I quattro passi, in ordine

Fase P06: Proprietà strutturali dello spazio

P06 non è una singola chiamata ma una catena di dodici sotto-fasi, una per ciascuna proprietà strutturale dello spazio, seguite da una sintesi trasversale (P06_sintesi). Il frontend le presenta come un unico passo della pipeline, ma tecnicamente sono tredici richieste separate — vedi anche la sezione Token e costi per come vengono conteggiate.

Le dodici proprietà

Ogni sotto-fase risponde allo stesso schema e alla stessa regola obbligatoria sul campo rilevante: se true, deve produrre analisi.testo e almeno un'analisi.inferenza_principale — un elenco di fatti non è un'inferenza, serve una conclusione esplicita su rapporti di potere o configurazione spaziale. Se false, deve spiegare in motivazione_irrilevanza perché quella proprietà è trascurabile per questo tema specifico: non può mai restare vuota. È esattamente questa regola — verificata da un validatore — che genera l'errore più comune nelle sotto-fasi P06 quando manca.

P06_sintesi: non un riassunto, un'elaborazione

Dopo le dodici proprietà, P06_sintesi le rilegge tutte e produce un livello di analisi che non emerge guardando ogni proprietà isolatamente:

Fase P07: Relazioni tra gruppi

P07 apre il ramo di tipo A (spazio senza attore dominante): analizza come i gruppi umani coinvolti si relazionano tra loro, prima ancora di descrivere i singoli attori (che arriva dopo, in P08). Riceve in input parametri, classificazione e la sintesi di P06.

I campi principali

Fase P08: Attori geopolitici

P08 completa il ramo di tipo A: mappa i singoli attori dello spazio, il loro peso e le loro narrazioni, sulla base delle relazioni già descritte in P07. La tassonomia delle categorie, i ruoli e la visibilità sono descritti in dettaglio nella sezione Attori: categorie, ruoli, visibilità — qui trovi come la fase li usa.

I quattro compiti, in ordine

Fasi P09a/b/c: il ramo dell'attore dominante

Quando il tipo effettivo è B (uno spazio sottoposto al controllo di un attore dominante), la pipeline segue tre fasi in sequenza invece di P07/P08: coesione interna, intensità della presa, fattori di forza per la proiezione esterna. Tutte e tre si concentrano sullo stesso attore, identificato per primo in P09a.

P09a — Coesione interna

Prima cosa: identifica e nomina l'attore dominante (nome_attore). Poi vaglia sistematicamente tutti e dodici i piani della coesione interna — storico, demografico, istituzionale, immigratorio, mediatico, sociale, politico_ideologico, geografico, etnico, religioso, culturale, infrastrutturale — un validatore impone che compaiano tutti e dodici nell'array piani_coesione, anche quelli dichiarati non pertinenti. Per ognuno: pertinente sì/no e, se sì, un'analisi con valutazione (fattore di coesione / divisione / neutro). Chiude con valutazione_complessiva (alta/media/bassa) e un' inferenza_principale.

P09b — Intensità della presa

Analizza quanto a fondo l'attore identificato in P09a esercita il controllo, rispondendo a quattro interrogativi: funzioni di sicurezza, funzioni organizzative, sfruttamento delle opportunità offerte dallo spazio, struttura organizzativa articolata sul territorio. Ne deriva forma_controllo_interna sulla stessa scala usata in P04 (dominio → egemonia → sfera_influenza → ingerenza → sfera_interessi → cogestione → rinuncia_volontaria → autorita_nominale) e intensita_presa (forte/media/debole).

P09c — Fattori di forza per la proiezione esterna

Esamina dieci ambiti (economico, istituzionale, militare, reputazionale, sensibilità collettive, geografico, tecnologico, legale, ideologico, demografico) e, per ciascuno rilevante, classifica il fattore secondo quattro dicotomie indipendenti: rendimento (remunerativo/tattico/simbolico), natura (materiale/immateriale), stato (già posseduto/potenziale), origine (tradizionale/recente).

Fase P10: Autoverifica

P10 è la revisione critica dell'intera analisi. Legge tutte le fasi precedenti e identifica incoerenze, pregiudizi, assunzioni non fondate.

Cosa segnala P10

• Coerenza complessiva: soddisfacente / con riserve / problematica
• Fattori strutturali vs contingenti: sono chiaramente distinti?
• Leader-centrismo: l'analisi dipende troppo da un singolo attore?
• Monocausalità: si assegna troppo peso a una sola causa?
• Problemi rilevati: lista di problemi specifici con gravità (alta/media/bassa)
• Lacune non dichiarate: a differenza delle lacune viste durante l'analisi (vedi sezione Lacune dichiarate), qui P10 rilegge tutto il lavoro già fatto e segnala mancanze che avrebbero dovuto essere dichiarate prima e non lo sono state — un controllo a posteriori, non una dichiarazione nel momento in cui si scrive

Come applicare una correzione

Quando P10 suggerisce una correzione (es: "Riconsiderare i fattori basici di P07: la conflittualità non è sufficientemente radicata in fattori strutturali"), il suggerimento è informativo, non esecutivo.

Strategia consigliata

1. Leggi attentamente il riepilogo di P10
2. Se sono presenti problemi di gravità alta in P04, considera /riclassifica
3. Per problemi in fasi successive, continua comunque verso P11/P12/P13
4. Nel report finale (P13), i limiti metodologici saranno documentati

Fase P11: Conclusioni

P11 chiude la parte analitica della pipeline: rilegge introduzione, sintesi di P06, il ramo completato (P07/P08 o P09a/b/c) e l'autoverifica di P10, e ne trae le conclusioni. È l'ultima fase prima degli scenari (P12) e del report (P13).

La struttura obbligatoria

Fase P12: Scenari

P12 costruisce gli scenari futuri a partire dalle conclusioni di P11. È, per esplicita scelta del metodo, la fase con i vincoli più stringenti di tutta la pipeline — cinque regole vincolanti, tutte verificate da un validatore dedicato.

Le cinque regole vincolanti

Ogni scenario, campo per campo

denominazione (nome breve e memorabile), descrizione, probabilita_qualitativa, motivo_di_inclusione (probabilità / conseguenze_clamorose / entrambi), nessi_causali (la catena logica che porta allo scenario), condizioni_abilitanti, fattori_stabilizzatori (con stabilita per ciascuno), fattori_aleatori (cosa potrebbe smentirlo), scala_temporale.

Fase P13: Report narrativo

P13 non produce nuova analisi: assembla in prosa continua tutto ciò che le fasi precedenti hanno già stabilito. Va invocata esplicitamente col comando /report dopo P12 — non parte da sola. È l'unica fase il cui output non è pensato per essere letto come un messaggio strutturato in un certo formato, ma come testo narrativo leggibile.

Cosa riceve in input

Introduzione (P03), la sintesi di P06 (non le 12 proprietà per esteso, solo sintesi_strutturale, proprieta_piu_rilevanti e inferenze_trasversali — selezione deliberata per non saturare il contesto), il ramo analitico completo (P07/P08 o P09a/b/c), conclusioni (P11), scenari (P12), e un elenco esatto delle fonti citabili in-text con l'etichetta autore/anno esatta con cui compariranno in bibliografia — vedi Fonti e bibliografia.

La struttura attesa

Cinque sezioni, in ordine dal generale al particolare: introduzione, caratteri dello spazio, poi — a seconda del tipo effettivo — relazioni e attori (tipo A) oppure presa interna e proiezione esterna (tipo B), infine conclusioni e scenari. La sezione dedicata agli attori (o all'attore, tipo B) non va mai compressa: è il punto su cui si concentra la curiosità del lettore, e un validatore dedicato la confronta con la lunghezza media delle altre sezioni.

Fase P14: Comparazione (opzionale)

P14 non fa parte del percorso lineare: si invoca col comando /compara [descrizione del caso] dopo P11, per confrontare l'analisi appena condotta con un altro caso proposto da te. Non è mai obbligatoria — P13 si genera comunque senza passare da qui.

I tre divieti, verificati prima di tutto

Prima di procedere al confronto vero e proprio, P14 verifica esplicitamente tre condizioni di ammissibilità — se anche una sola è violata, la comparazione viene rifiutata (ammissibilita.ammessa = false), con motivazione e, quando possibile, una proposta alternativa di confronto tra singoli aspetti omologhi invece che tra i due casi nella loro interezza:

Se la comparazione è ammessa

Il confronto procede aspetto per aspetto (mai i due casi nella loro interezza): per ciascun aspetto, caso_principale vs caso_confronto, le differenze_rilevanti e un'inferenza. Chiude con variazioni_locali_emerse (differenze che illuminano aspetti non visibili in una singola analisi) e nuove_chiavi_lettura.

Lacune dichiarate

Durante l'analisi vedi comparire, nella sidebar "Lacune dichiarate", elementi che il modello segnala come mancanti invece di inventarli. Questa sezione spiega da dove nascono, cosa significano davvero, e come usarle.

Da dove nascono

Ogni fase riceve, tra le sue regole permanenti (lo stesso blocco iniettato in ogni fase, vedi Fonti e bibliografia), questa istruzione letterale:

In pratica: quando il modello dovrebbe affermare un dato preciso ma non ha una fonte verificabile a sostegno, l'alternativa all'inventare (o all'affermarlo comunque, senza basi) è dichiarare esplicitamente cosa manca. Ogni lacuna ha due parti:

In quali fasi possono comparire

Solo le fasi che devono affermare fatti verificabili hanno un campo lacune nel proprio schema: P03 (Introduzione), P05 (Spazializzazione), ogni sotto-fase di P06 (le 12 proprietà strutturali) più P06_sintesi, P07 (Relazioni), P08 (Attori), P09a/P09b/P09c (coesione, presa, fattori di forza — solo tipo B, attore dominante).

Non compaiono in P01, P02, P04, P12, P13, P14. Sono fasi di setup, classificazione, generazione di scenari o assemblaggio — P04, ad esempio, esprime l'incertezza in altro modo, con il campo confidenza (alta/media/bassa), non con lacune.

Due campi diversi, spesso confusi con le lacune

P10 e P11 hanno campi che sembrano lacune ma non lo sono, nello stesso senso:

Come vengono raccolte e mostrate

Il server cerca ricorsivamente un array lacune ovunque si trovi nell'output di ogni fase (a seconda della fase può essere alla radice o annidato, come per le fonti — vedi Fonti e bibliografia) e lo accumula per l'intera sessione. La sidebar mostra sempre il totale accumulato fino a quel momento, non solo quelle dell'ultima fase completata.

Le lacune in sidebar sono ordinate per gravità stimata, dedotta dal testo di impatto_sulla_analisi cercando parole chiave comuni in italiano (es. "critico", "significativo" → gravità alta; "marginale", "trascurabile" → gravità bassa) — quelle ad alto impatto salgono in cima con un bordo rosso e ⚠, quelle a basso impatto scendono con un bordo grigio.

Dove le trovi

• Sidebar "Lacune dichiarate" durante l'analisi, sempre aggiornata al totale reale
• Scrivendo stato in chat, che riporta comunque l'elenco completo accumulato
• Nei documenti salvati ("Salva chat" e "Salva report finale"): una sezione dedicata elenca tutte le lacune dichiarate, nello stesso ordine per gravità della sidebar

Come interpretarle

Fonti e bibliografia

Ogni fase può citare fonti a sostegno delle proprie affermazioni. Alla fine dell'analisi (P13), tutte le fonti raccolte lungo il percorso confluiscono in una bibliografia unica, allegata al report.

Da dove vengono raccolte

Non solo alla fine: dopo ogni singola fase, l'app cerca ricorsivamente un array fonti ovunque si trovi nell'output — a seconda della fase può essere alla radice, oppure annidato (es. dentro ogni indizio di P04, dentro ogni proprietà di P06, dentro ogni attore di P08) — e lo accumula in una lista di sessione. Alla fine, quella lista diventa la bibliografia completa.

La regola che genera le fonti

Ogni fase riceve, oltre alle sue istruzioni specifiche, un identico blocco di regole permanenti. Due riguardano direttamente le fonti:

• Nessun fatto senza fonte: il modello non può asserire dati specifici (cifre, date, citazioni, assetti attuali) senza una fonte verificabile o fornita da te. Se non ce l'ha, deve dichiarare una lacuna invece di inventare.
• Ogni affermazione "accertata" richiede una fonte: se il tipo di un'informazione è informazione_accertata ma non c'è una fonte reale a supporto, il modello scrive inferenza_propria — un modo per segnalare "questo è un mio ragionamento, non un dato verificato". Anche il valore "Analista" con anno assente ("n.d.") ha lo stesso significato.

Da dove viene, davvero, ogni fonte

Ogni fonte dichiara una provenienza:

I file di conoscenza (knowledge/*.md) sono invece un caso diverso: vengono caricati per davvero nelle istruzioni della fase, ma sono guide sul metodo (come ragionare), non fatti sul tema analizzato — una regola permanente vieta esplicitamente al modello di citare come dato gli esempi contenuti in quei file.

Quanto è autorevole ogni fonte — il campo natura

Sotto ogni voce della bibliografia trovi una o più etichette (es. fonte primaria, fonte secondaria — verificare, oltre alla provenienza vista sopra): sono due campi diversi e indipendenti. La provenienza dice da dove il modello l'ha presa; natura dice quanto dovresti fidartene — la stessa gerarchia di autorevolezza descritta in dettaglio nel file di metodo knowledge/06-fonti-e-retorica.md, che ogni fase consulta prima di accettare una fonte.

Il formato della citazione cambia in base al tipo di fonte

Ogni fonte dichiara anche un campo tipo_fonte, che determina quali dettagli compaiono nella citazione stile APA — non è lo stesso identico formato per tutte le voci:

Volume, fascicolo, pagine, edizione, luogo di pubblicazione e data di consultazione sono tutti campi facoltativi: se il modello non li valorizza, la citazione ricade comunque nel formato generico corretto per quel tipo, senza campi vuoti o mancanti visibili.

Il link alla fonte

Quando una fonte ha un URL, compare in coda alla citazione preceduto da "Disponibile su:" (o "Consultato il [data], da:" per i siti web con data di consultazione dichiarata, vedi sopra). Il testo del link normalmente è l'indirizzo stesso — con un'eccezione:

Citazioni in-text e numerazione

Nel testo del report, le affermazioni che derivano da una fonte specifica sono accompagnate da una citazione tra parentesi quadre e in corsivo, del tipo [Autore, Anno, N] — dove N è il numero della voce corrispondente qui in bibliografia (mostrato anch'esso tra parentesi quadre davanti a ogni voce, riferimento metodologico compreso, che è sempre la voce numero 1). Quando un'affermazione è confermata da più fonti indipendenti, compaiono insieme nella stessa parentesi, es. [Rossi, 2021, 3; Bianchi, 2022, 5] — un modo semplice per distinguere a colpo d'occhio un dato corroborato da più fonti da uno sorretto da una sola. Una parentesi nel testo che non corrisponde esattamente a una voce della bibliografia resta tonda, non quadra: non è una citazione, solo un inciso del testo.

Orientamento dichiarato

Quando una fonte esprime un punto di vista riconoscibile — un think tank vicino a un determinato governo, un editoriale schierato, un canale che rappresenta gli interessi di un attore specifico — il modello può valorizzare il campo facoltativo orientamento_dichiarato. In bibliografia compare come nota a margine sotto la citazione (es. "Orientamento dichiarato: vicino al governo di X"): non è un giudizio di valore dell'app, serve solo a segnalarti che quella fonte non è neutra "per definizione" e va letta tenendone conto — coerente con la regola di pluralismo delle prospettive del report finale.

Come si arriva alla bibliografia finale

1. Ogni fase completata contribuisce le proprie fonti alla lista di sessione
2. A P13, i link di redirect da ricerca web (grounding) vengono risolti all'URL reale, dove possibile (vedi sopra)
3. La lista completa viene deduplicata (stesso autore+titolo+URL, senza distinguere maiuscole)
4. Le voci segnaposto (Inferenza propria, Analista) vengono escluse
5. Viene aggiunto un riferimento fisso, sempre presente: Boria, E. — L'analisi geopolitica (il testo metodologico su cui si basa l'intero approccio)
6. L'elenco finale è ordinato alfabeticamente per autore
7. Ogni voce riceve il numero progressivo mostrato tra parentesi quadre (il riferimento metodologico è sempre il numero 1) — lo stesso numero usato nelle citazioni in-text del report

Attori: categorie, ruoli, visibilità

Nella sezione P08 — Attori geopolitici del report (ramo di tipo A, multi-attore), ogni riga della tabella descrive un attore con quattro campi: Nome, Categoria, Ruolo e Visibilità. Sono tre vocabolari chiusi (il modello sceglie da un elenco fisso, non inventa etichette), definiti nel file di metodo knowledge/04-attori.md che la fase usa per costruire il proprio prompt.

Categoria — la tassonomia degli undici attori

Undici categorie, classificate per orizzonte d'azione, obiettivo reale e grado di istituzionalizzazione. Non è un dettaglio formale: la categoria condiziona cosa quell'attore può realisticamente ottenere e quali vincoli subisce — ignorarla porta a giudicare le mosse di un attore con il metro di un altro.

Ruolo — oltre dominatore e dominato

Il metodo mette in guardia esplicitamente dal farsi attrarre dalle due figure "idealtipiche" di dominatore e dominato: molti attori reali ricadono in posizioni intermedie, ed è per questo che lo schema ne prevede sette, non due. Un validatore impone che nell'elenco compaia almeno un ruolo non polarizzato, proprio per impedire che l'analisi collassi sui due estremi.

Visibilità — non è la stessa cosa del peso reale

Alta, media o bassa: quanto un attore è esposto/riconoscibile pubblicamente — non quanto conta davvero. Il metodo segnala un rischio specifico: la copertura mediatica dà risalto in base a ciò che colpisce il pubblico, non in base all'importanza politica reale, per cui attori a bassa visibilità (reti informali, lobby, apparati poco trasparenti) rischiano di restare fuori da un'analisi che parte dai soggetti più evidenti. Per questo un validatore impone che nell'elenco compaia almeno un attore a visibilità bassa: è una spinta a cercarli attivamente, non un dettaglio decorativo.

Token e costi

Nella sidebar sinistra, il pannello "Token / Costo" traccia il consumo di token per ogni fase e il costo totale dell'analisi.

Cosa vedi nel pannello

• Input: token usati per il prompt (testo della fase + contesto)
• Output: token generati dal modello (risposta strutturata)
• Pensiero: token usati dal modello per ragionamento interno (se attivo)
• Ricerche web: richieste di ricerca eseguite dal grounding, se attivo — vedi sotto (compare solo se maggiore di zero)
• Totale: somma di tutti i token della sessione
• Costo: stima in valuta locale (di default USD), token + eventuale grounding

Configurazione dei prezzi

I prezzi (e l'interruttore del grounding, vedi Fonti e bibliografia) si gestiscono da una pagina dedicata, visibile solo all'utenza amministrativa di sistema — non a ogni account con ruolo amministratore:

• Preset rapidi: Gemini 2.5 Pro, 1.5 Pro, Flash (con prezzi attuali)
• Costo input/M: prezzo per milione di token di input
• Costo output/M: prezzo per milione di token di output
• Costo pensiero/M: prezzo per milione di token di ragionamento
• Costo grounding/1.000 richieste: prezzo delle ricerche web reali, indipendente dai token
• Valuta: simbolo della valuta (USD, EUR, GBP, JPY, ecc.)

I prezzi si salvano sul server (storage/token_costs.json e storage/grounding_config.json), non inviati al server Gemini.

Prezzi di riferimento per famiglia di modello

Valori pubblici indicativi (possono cambiare nel tempo): usali come punto di partenza per compilare i prezzi nella pagina di configurazione, non come listino garantito.

Costo per fase

Dopo ogni fase, un piccolo chip mostra i token consumati in quel passaggio:

in 1.234 · out 856 · tot 2.090 · $0.0342

Blocco P06

P06 esegue 13 fasi in parallelo (12 proprietà + sintesi). Il totale aggregato viene mostrato al termine di P06_sintesi.

Costo della base di conoscenza certificata (EIL)

Se l'integrazione EIL è attiva (EIL_ABILITATO in config.php) e l'utente sceglie una modalità di conoscenza diversa da Web, ogni interrogazione a EIL ha un costo: EIL usa Gemini al proprio interno per comporre la risposta, e riporta ad ANGST i token consumati e il costo in USD già calcolato con il suo listino (che può differire dal tuo). ANGST:

• mostra una riga EIL nel pannello Token / Costo (token consumati da EIL, già inclusi nel Totale);
• non riprezza quei token con il tuo listino — somma direttamente la cifra in USD fornita da EIL (canale di costo a sé, come il grounding);
• conta comunque i token EIL nella quota utente e nel tetto di sessione (LIMITE_TOKEN_SESSIONE / LIMITE_COSTO_SESSIONE).

In Mista integrata si aggiunge, per ogni macro-sezione, una chiamata Gemini di arricchimento: quella è consumo Gemini normale, prezzata con il tuo listino (voce di log ARRICCHIMENTO:S1/S2/S3).

Costanti config.php per EIL

In produzione vanno nel config-work.php privato (fuori da public_html), non nel config.php del repository.

Il token di servizio EIL (JWT, 12 h) è cachato in storage/eil_token.json; viene rinnovato da solo. Le tracce delle interrogazioni (EIL:S1 "interrogazione" / "nessuna fonte pertinente" / "non raggiungibile", ARRICCHIMENTO:S2 …) sono nel log per-utente in storage/log/.

Salvataggio e gestione dei report

L'app ti permette di salvare l'intera chat di analisi e il report finale in formato HTML, gestendoli su server: scaricare, rinominare, eliminare.

Accesso alla gestione report

Nel sidebar sinistro, clicca il pulsante 📋 I miei report per aprire la modalità di gestione. Qui trovi:

• Due pulsanti di salvataggio rapido
• Elenco di tutti i report già salvati
• Azioni per ciascun report (scarica, rinomina, elimina)

Tipi di report

L'app ti permette di salvare due cose diverse:

1. Chat di analisi completa (analisi_del_[data].html)

• Contiene tutta la conversazione (messaggi dell'utente e risposte del sistema)
• Utile per documentare l'intero processo di analisi
• Formattato come pagina HTML leggibile
• Pulsante: 💾 Salva chat

2. Report finale (report_finale_analisi_del_[data].html)

• Contiene solo il report narrativo generato da P13
• Più professionale e compatto rispetto alla chat completa
• Include solo le sezioni finali e le conclusioni
• Pulsante: 💾 Salva report finale

Naming convention

I file vengono salvati automaticamente con la data e ora corrente:

Formato: [tipo]_del_[DD-MM-YYYY_HH-MM-SS].html

Azioni sui report

⬇ Scarica

Scarica il file HTML nel tuo computer. Puoi aprirlo in qualsiasi browser senza necessità di connessione internet.

✏ Rinomina

Rinomina il file con un nome personalizzato. Esempi:

• analisi_Stretto_di_Hormuz.html
• report_geopolitica_Pacifico.html
• 2026_Q3_area_MENA.html

L'estensione .html viene aggiunta automaticamente se omessa.

✕ Elimina

Elimina definitivamente il file dal server. Richiede conferma. Non è possibile recuperare un file eliminato, quindi usa con cautela.

Informazioni metadata

Per ciascun report salvato, puoi vedere:

• Tipo: analisi | report_finale
• Dimensione: in KB
• Data di salvataggio: GG/MM/AAAA HH:MM

Come usare i report HTML

I file HTML salvati sono documenti autoportanti e professionali:

1. Scarica il file dal pannello report
2. Apri nel browser (o condividi per email)
3. Stampa in PDF (Ctrl+P) se hai bisogno di un formato statico
4. Modifica con un editor HTML se vuoi personalizzarlo ulteriormente

Dove vengono archiviati

I file vengono salvati nel server backend in storage/reports/. Rimangono disponibili per il download finché non li elimini.

Domande frequenti

Che cosa succede se non digito nulla?

L'app rimane in attesa. Digita qualcosa (anche solo "continua") o fai click su un comando per proseguire alla fase successiva.

Posso tornare indietro a una fase precedente?

No, tranne con /riclassifica che ricomincia da P04. Se hai bisogno di riconsiderare fasi precedenti, devi resettare l'analisi (pulsante "Nuova analisi") e ricominciare dal principio.

Cosa significa "Tipo SOSPESO"?

Se in P04 la classificazione non è chiara (né A né B), il tipo rimane SOSPESO. P06 (Caratteri dello spazio) fornisce ulteriori indizi per risolverlo in P06_sintesi. Se rimane indeterminato, si usa A come fallback.

Le lacune dichiarate bloccano l'analisi?

No. Le lacune (dati mancanti, fonti non disponibili, ipotesi non testate) si registrano lungo il percorso, senza mai bloccare il flusso — vedi la sezione Lacune dichiarate per il dettaglio completo su come nascono, dove trovarle e come interpretarle.

Cosa fare se P10 segnala molti problemi?

Leggi la gravità di ciascun problema. Se ci sono problemi alti in P04, considera /riclassifica, eventualmente con una nota facoltativa dopo il comando che P04 leggerà con priorità. Per problemi in fasi successive, procedi verso il report finale (P13) che documentarà i limiti metodologici.

Posso salvare l'analisi?

Al momento l'analisi rimane nella sessione del browser. Se chiudi il tab o il browser, i dati si perdono. Usa il comando /report per generare il report narrativo che puoi copiare/stampare.

Quale modello usa questa app?

Di default, Gemini 2.5 Pro con output strutturato (JSON conforme agli schemi di ogni fase). Configurabile in config.php.

I dati della mia analisi vengono inviati da qualche parte?

I dati vengono inviati a Google Gemini API per l'elaborazione (tema, parametri, contesto dello spazio, ecc.). Non vengono archiviati su server terzi oltre Google Cloud. Il costo token è calcolato localmente nel tuo browser.

Posso fare più analisi contemporaneamente?

Ogni tab/finestra del browser mantiene una sessione indipendente. Apri nuovi tab per analisi parallele. Il reset da un tab non influenza gli altri.

Cosa succede se il modello genera un output che non rispetta lo schema?

L'app ritenta automaticamente fino a 2 volte, iniettando l'errore nel prompt successivo perché il modello lo corregga. Se fallisce dopo i tentativi, la pipeline si ferma e mostra l'errore di validazione.