Report & Documentazione

📊 Statistiche Comparative — Dati Estratti dai File XML

I numeri in questa pagina sono calcolati a runtime rileggendo i 30 file data/xml_dataset/*.xml già validati contro il DTD: non sono scritti a mano nel report. Gli XML, a loro volta, derivano dai dati sorgente (con alcune correzioni manuali documentate sui dati grezzi, p.es. gli override distretti per Luxembourg e Stockholm). Il report è quindi il riflesso diretto dei documenti — se cambia un XML, cambia la statistica.

🔍 Da dove viene ogni numero — provenienza degli indicatori

In ogni XML confluiscono due famiglie di dati: i contenuti testuali estratti algoritmicamente dai dump Wikivoyage (trasporti, attrazioni, distretti, locali) e gli indici numerici presi da city_indices.json (fonti internazionali). L'unico valore derivato dalla pipeline è l'Appeal Score, ricalcolato dai tre indici.

Le fonti complete con i link a Numbeo, EEA e l'avvertenza accademica sono nella sezione AI Usage → Fonti degli Indici Numerici.

🧮 Come si calcola l'Appeal Score

È l'unico indice composito: pesa la sicurezza e la sostenibilità al 40% ciascuna e l'accessibilità economica al 20% (il costo viene invertito con 100−Costo, così «più economico = punteggio più alto»). Determina il ranking qui sotto.

Media del dataset: Appeal 61.3 · Safety 66.0 · Green 71.8 (calcolate sui 30 file).

🍺 Locali notturni per categoria — estratti con un predicato XPath

Questi conteggi non scorrono l'intera lista filtrando in Python: usano direttamente un predicato per valore d'attributo, //venue[@category="…"], che lascia selezionare al motore XPath i soli elementi desiderati (l'attributo category è enumerato nel DTD: bar | pub | nightclub).

Dettaglio tecnico del costrutto nella sezione Uso di XPath.

🏆 Classifiche per Indicatore

Top 5 capitali per ogni indicatore. La barra è proporzionale al valore, normalizzata sul massimo del dataset; per il prezzo la scala è invertita (barra più lunga = più economica), così in ogni grafico la barra più piena è sempre la posizione migliore.

⚙️ Architettura della Pipeline TEAM

Il progetto è composto da cinque componenti Python. La pipeline trasforma dump MediaWiki in file XML conformi al DTD (con content-model misto), li valida, genera le pagine HTML navigabili annotate con microdata e indicizza i contenuti in un sistema RAG per le query in linguaggio naturale.

⚠️ Dati Non Reperibili da Wikivoyage — Integrazione AI

Le seguenti informazioni non erano presenti nei dump Wikivoyage scaricati e sono state integrate con testo sintetico generato da AI (Gemini), chiaramente identificato nel dataset:

⚠️ Tutti i testi generati da AI sono identificabili nel dataset dalla presenza della stringa (Source: AI-generated — ...) nel campo <transport> del file XML.

📄 Schema DTD — Struttura dei Documenti XML

Ogni file in xml_dataset/ è validato rispetto a city_report.dtd prima della scrittura. La validazione è eseguita a runtime con lxml.etree.DTD. I file non validi vengono segnalati ma non scritti.

Script di validazione dedicato — validate.py

Oltre alla validazione integrata nella pipeline, un script Python standalone (scripts/validate.py), indipendente dal resto del progetto, costruisce il DOM di ogni documento e lo valida rispetto al DTD. Distingue i tre esiti: mal formato (etree.parse() solleva XMLSyntaxError), non valido (dtd.validate() → False) e valido.

from lxml import etree

dtd = etree.DTD(open("data/city_report.dtd", "rb"))   # carica il DTD

for filename in files:                                  # scorre la directory XML
    try:
        tree = etree.parse(path)                        # parsing → DOM (buona forma)
    except etree.XMLSyntaxError:
        ...                                             # documento MAL FORMATO
        continue
    if dtd.validate(tree):                              # validazione del DOM
        ...                                             # VALIDO
    else:
        print(dtd.error_log.filter_from_errors())       # NON VALIDO

✅ Esecuzione: python scripts/validate.py → 30/30 validi · 0 non validi · 0 malformati. Lo script restituisce codice di uscita 0 solo se tutti i documenti sono validi.

Struttura ad albero

city_report [@appeal_score, @currency?, @region]
├── metadata
│   ├── title          (nome EN)
│   ├── name_it        (nome IT)
│   └── flag           (emoji bandiera)
├── indicators
│   ├── hotel_count
│   ├── hotel_price
│   ├── safety         [@index_score]
│   ├── environment    [@green_score]
│   ├── cost_index     [@value]
│   └── economic_accessibility [@score]
├── transport          (testo descrittivo)
├── accommodation
│   └── hotel*
│       ├── name
│       └── price
├── highlights
│   └── attraction*    [@lat @lon]
│       ├── name
│       └── description
├── districts?
│   └── district*
│       ├── name
│       └── description
├── description        (sintesi strategica EN)
├── wiki_intro?        (intro da Wikivoyage, ripulita)
└── landmark_image?    (URL immagine simbolo)

Dichiarazione DTD (file sorgente)

<!ELEMENT city_report (metadata, indicators, transport, accommodation, highlights, districts?, description, wiki_intro?, landmark_image?, nightlife?)>
<!-- currency: codice ISO 4217 della valuta locale (es. "GBP", "SEK").
     Attributo OPZIONALE (#IMPLIED): è assente per le città dell'area euro,
     presente solo per le capitali che usano una valuta diversa dall'euro.
     region: macro-regione geografica (geoscheme UN M49). Attributo ENUMERATO
     e OBBLIGATORIO: ogni capitale appartiene a una e una sola area. -->
<!ATTLIST city_report
    appeal_score CDATA                                       #REQUIRED
    currency     CDATA                                       #IMPLIED
    region       (northern | western | southern | eastern)   #REQUIRED>

<!ELEMENT metadata (title, name_it, flag, source_url)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT name_it (#PCDATA)>
<!ELEMENT flag (#PCDATA)>
<!-- Canonical URI/IRI of the city: used as microdata itemid in the HTML so that
     the identifiers in the site correspond exactly to those in the documents -->
<!ELEMENT source_url (#PCDATA)>

<!ELEMENT indicators (hotel_count, hotel_price, safety, environment, cost_index, economic_accessibility)>
<!ELEMENT hotel_count (#PCDATA)>
<!ELEMENT hotel_price (#PCDATA)>

<!ELEMENT safety EMPTY>
<!ATTLIST safety index_score CDATA #REQUIRED>

<!ELEMENT environment EMPTY>
<!ATTLIST environment green_score CDATA #REQUIRED>

<!ELEMENT cost_index EMPTY>
<!ATTLIST cost_index value CDATA #REQUIRED>

<!ELEMENT economic_accessibility EMPTY>
<!ATTLIST economic_accessibility score CDATA #REQUIRED>

<!ELEMENT transport (#PCDATA | b | i | link)*>
<!ELEMENT accommodation (hotel*)>
<!ELEMENT hotel (name, price)>
<!ELEMENT price (#PCDATA)>

<!ELEMENT highlights (attraction*)>
<!ELEMENT attraction (name, description)>
<!ATTLIST attraction 
    lat CDATA #REQUIRED 
    lon CDATA #REQUIRED>

<!ELEMENT districts (district*)>
<!ELEMENT district (name, description)>

<!ELEMENT name (#PCDATA)>
<!ELEMENT description (#PCDATA | b | i | link)*>
<!ELEMENT wiki_intro (#PCDATA | b | i | link)*>
<!ELEMENT landmark_image (#PCDATA)>

<!-- Inline elements for mixed content (content-model misto) -->
<!ELEMENT b (#PCDATA)>
<!ELEMENT i (#PCDATA)>
<!ELEMENT link (#PCDATA)>
<!ATTLIST link href CDATA #REQUIRED>

<!ELEMENT nightlife (venue*)>
<!ELEMENT venue (name)>
<!-- lat/lon obbligatorie: ogni venue è geolocalizzata sulla mappa.
     category è un attributo ENUMERATO: solo questi tre valori sono ammessi. -->
<!ATTLIST venue lat CDATA #REQUIRED
               lon CDATA #REQUIRED
               category (bar | pub | nightclub) #REQUIRED>

🔬 Tecniche di Parsing e Pulizia del Testo

🧭 Uso di XPath

La fase di lettura ed estrazione dei documenti XML si basa su XPath, a due livelli: il motore XPath completo di lxml (metodo .xpath()) e il suo sottoinsieme ElementPath (.find() / .findall() / .findtext()).

1. XPath completo — .xpath()

Due esempi mostrano l'intera gamma dei costrutti. string(.//safety/@index_score) combina path discendente, asse attributo e funzione XPath per leggere gli indici memorizzati come attributi di elementi EMPTY. .//venue[@category="pub"] usa invece un predicato ([…]): il filtro per valore d'attributo che lascia selezionare al motore XPath i soli locali desiderati — più robusto del filtraggio manuale in Python e immune all'ordine degli elementi. Entrambe le espressioni alimentano numeri reali nella sezione Statistiche.

Resilienza nel casting. I valori estratti sono sempre stringhe: la conversione a numero (medie di Appeal, Safety, prezzi) passa per una funzione fv() che applica float(str(x).strip()) dentro un try/except. Così un eventuale valore corrotto (es. "dieci") non manda in crash la pipeline ma viene neutralizzato, permettendo di proseguire con gli altri documenti.

2. ElementPath — find() / findall() / findtext()

Sottoinsieme di XPath di ElementTree/lxml, usato pervasivamente per navigare il DOM — es. tree.findall('.//mw:page', ns) (final_processor.py), root.findall('.//attraction') (validate.py), root.findtext(".//title") (deploy_dashboard.py). Gli attributi (es. @category, @lat) si leggono invece con element.get('attr').

🏷️ Microdata Schema.org — Quantificazione

Lo script deploy_dashboard.py annota i documenti HTML con microdata Schema.org (vincolo del progetto). Le annotazioni sono generate dallo script e i conteggi qui sotto sono calcolati a runtime ri-scansionando i file HTML appena prodotti (index.html + 30 pagine città), quindi non sono valori statici.

Item per tipo Schema.org

Proprietà annotate (itemprop)

name 838 · containsPlace 628 · geo 570 · latitude 570 · longitude 570 · description 330 · value 120 · additionalProperty 90 · priceRange 88 · containedInPlace 60 · alternateName 36 · aggregateRating 30 · ratingValue 30 · bestRating 30 · worstRating 30 · ratingCount 30 · identifier 30 · propertyID 30 · sameAs 30 · image 30 · url 30

Struttura annidata e identità (itemid ↔ documento)

La gerarchia rispecchia il pattern multi-livello visto a lezione (lab_microdata.py): ogni <city report> diventa una City che contiene (containsPlace) le entità annidate del documento — TouristAttraction, Hotel e i locali notturni — ognuna con il proprio blocco geo/GeoCoordinates (latitude/longitude), e che a sua volta è contenuta (containedInPlace) nella propria macro-regione e nel continente:

City [itemid = source_url]
 ├─ containedInPlace → Place "… Europe"  [identifier → PropertyValue "UN M49"]
 │   └─ containedInPlace → Continent "Europe"  (sameAs → wikidata.org/Q46)
 ├─ aggregateRating → AggregateRating   (ratingValue = appeal_score, best/worst 100/0)
 ├─ additionalProperty → PropertyValue  (Safety Index · Green Score · Economic Accessibility)
 ├─ containsPlace → TouristAttraction   (name, description, geo → GeoCoordinates)
 ├─ containsPlace → Hotel               (name, priceRange)
 └─ containsPlace → BarOrPub | NightClub (name, geo → GeoCoordinates)

Due scelte semantiche degne di nota: (1) l'attributo XML enumerato category (bar | pub | nightclub) viene mappato sulla classe Schema.org più specifica — NightClub per le discoteche, BarOrPub altrimenti; (2) gli indicatori numerici sono modellati correttamente: l'Appeal Score (composito) come AggregateRating — l'unico aggregateRating ammesso su un Place — e i tre sotto-indici come PropertyValue via additionalProperty, evitando di forzare più rating distinti su una sola proprietà; (3) l'attributo XML region (UN M49) diventa la relazione di contenimento geografico containedInPlace — speculare a containsPlace — risalendo dalla città alla macro-regione (Place, con il codice M49 come identifier) fino al Continent "Europe" (sameAs Wikidata).

Ogni itemid è l'URI canonico letto dal documento XML (elemento <source_url>): gli identificatori nel sito corrispondono esattamente a quelli nei documenti, come nell'esempio dei castelli del corso (itemid ↔ id del file XML).

Verifica round-trip. Lo script standalone scripts/check_microdata.py ri-estrae i microdata dalle pagine con la libreria microdata (microdata.get_items(), la stessa del laboratorio lab_microdata.py) e controlla che: ogni pagina esponga una City top-level; l'itemid ri-letto dall'HTML coincida con il <source_url> del relativo XML; gli oggetti annidati (TouristAttraction/Hotel/BarOrPub) portino GeoCoordinates e l'AggregateRating il suo ratingValue. Esito: round-trip coerente su 30/30 pagine, con conteggi per tipo identici a quelli del contatore qui sopra — due metodi indipendenti (regex di scrittura ↔ parser di rilettura) che concordano.

♿ HTML Semantico e Accessibilità

«HTML è il linguaggio base del Web. Deve essere usato in modo semantico, evitando tag procedurali deprecati come <font> e preferendo una chiara organizzazione logica. Gli elementi si dividono in quelli di blocco (che vanno a capo) e inline (come <em>, <strong> o il generico <span>), che si inseriscono nel flusso del testo senza spezzarlo.»

Tutto l'HTML prodotto da deploy_dashboard.py applica questo principio. Di seguito come la teoria si traduce nel codice generato e, soprattutto, in un effetto reale.

1. Niente tag procedurali deprecati

Sulle 33 pagine generate: zero <font>, <center>, <marquee>, <strike> e zero attributi presentazionali (align, bgcolor, valign…). La presentazione è interamente delegata al foglio di stile stile.css.

2. Organizzazione logica con elementi di blocco

Ogni pagina è strutturata con elementi di blocco semantici — non <div> generici — che descrivono il ruolo del contenuto: <header> (testata), <nav> (navigazione), <main> (contenuto principale, uno per pagina), <section> / <article> (blocchi tematici), <footer> (piè di pagina), con una gerarchia coerente di heading h1→h2→h3.

3. Inline semantici (strong / em / span)

Il vocabolario inline del content-model misto nel XML (b, i, link) viene mappato dalla funzione inline_to_html() ai tag semantici dell'HTML — b→<strong>, i→<em>, link→<a> — perché in quei punti l'enfasi porta significato (nome città, termine straniero). Il generico <span> è usato per i frammenti senza semantica propria (es. valori delle statistiche). I rari <b> residui sono enfasi puramente visiva: in HTML5 <b> non è deprecato ma ridefinito come «testo stilisticamente distinto senza importanza semantica».

4. La «traduzione» del semantico: l'accessibilità

L'HTML semantico è volutamente invisibile all'occhio (<strong> si vede come un grassetto), ma si traduce in significato leggibile dalle macchine. Il canale principale è l'albero di accessibilità: gli elementi semantici generano automaticamente dei landmark ARIA — <header>→banner, <nav>→navigation, <main>→main, <footer>→contentinfo — tra i quali uno screen reader può saltare. Per rendere questa struttura realmente usabile abbiamo aggiunto:

• Skip link «Salta al contenuto» come primo elemento (visibile solo al focus da tastiera), per bypassare la navigazione;
• aria-label sulle <nav> duplicate (Principale / Tra le città / Sezioni del report) così lo screen reader le distingue;
• aria-current="page" sul link attivo; lang sul documento e alt su tutte le immagini.

Verifica: DevTools del browser → scheda Accessibility (mostra i landmark etichettati), oppure la navigazione per landmark di uno screen reader (VoiceOver / NVDA).

5. Il sito come riflesso diretto dei documenti

Coerentemente con la semantica, ogni dato del documento XML è reso visibile nella pagina, non solo scaricabile. In particolare l'URI canonico del documento (elemento <source_url>) è ora un link cliccabile in ogni pagina città, e coincide con l'itemid dei microdata: lo stesso identificatore vive nel documento, nel link visibile e nell'annotazione machine-readable. Il download del file XML resta un'aggiunta, non l'unico modo di accedere ai dati.

Sintesi: principio → costrutto → effetto

6. Target tattili (tap-target) sulla mappa

Un audit Lighthouse (accessibilità 96/100) ha segnalato che alcuni marker Leaflet della mappa (es. Stoccolma, Oslo, Roma) avevano un'area tattile inferiore a 24×24 px o parzialmente sovrapposta — un problema per chi naviga da touch o ha difficoltà motorie. Interventi correttivi:

• marker dei locali e delle attrazioni (pagine città) portati a 32×32 px, ben oltre la soglia di 24;
• i marker delle capitali, che a zoom basso si sovrapponevano, sono ora raggruppati con L.markerClusterGroup: gli overlap si fondono in un unico bersaglio cliccabile e si riaprono allo zoom (≥ 6);
• raggio dei punti-attrazione aumentato per un'area di tocco più comoda.

7. Contrasto del colore (WCAG AA)

Un controllo del contrasto ha rilevato un link sotto la soglia AA per testo piccolo (4.5:1): il link Report & Documentation nel footer usava l'accent #E74C3C su sfondo chiaro (3.82:1). È stato portato all'accent scuro #C0392B (5.44:1, conforme AA). La barra di navigazione superiore, pur avendo testo chiaro, è invece su sfondo scuro #0B1524 (10.48:1): già ampiamente conforme.

7. Albero di accessibilità — index.html

È la struttura che uno screen reader «vede»: solo ruoli e nomi accessibili, non lo stile. I landmark (banner / navigation / main / contentinfo) e i heading h1→h2 offrono una mappa navigabile della pagina; il widget chat flottante è esposto come dialog. Questa è una copia dell'albero reale della home:

document  "EuroCity Strategic Intelligence"            [lang="en"]
├─ link        "Salta al contenuto"                    (skip-link, visibile al focus)
├─ banner                                              <header>
│  └─ navigation  "Navigazione principale"             <nav>  → Home · Report · Map
├─ heading h1  "30 European capitals, one intelligence."
├─ region      "How the data is built"                 <section aria-label>
│  └─ heading h2  "How the data is built"
├─ main        "Griglia delle capitali"                <main id="city-grid">
│  ├─ article → heading h2 "Amsterdam"  + link
│  ├─ article → heading h2 "Athens"     + link
│  └─ …  (30 article, una card per capitale)
├─ contentinfo                                         <footer>  → link "Report & Documentation"
├─ button      "Back to top"
└─ dialog      "Virtual Analyst"                       <div role="dialog">  ← widget flottante
     button "Ask the analyst" · textbox · button "Ask" · button "Close the analyst"

🎨 Architettura Frontend — CSS & JavaScript

L'interfaccia Travel 2026 applica una rigorosa separazione delle competenze: tutta la presentazione vive in un unico file esterno, stile.css. Il JavaScript è limitato a tre soli compiti — commutare le classi dei tab, leggere gli attributi data-pct per alimentare le custom property CSS e chiamare map.invalidateSize() quando il contenitore della mappa torna visibile. Nel markup generato non viene scritto alcun attributo style="" inline.

1. Foglio di stile esterno — stile.css

Tutte le 30 pagine città condividono un unico foglio di stile, versionato con un hash MD5 del suo contenuto (stile.css?v=hash): così ogni modifica forza l'invalidazione della cache del browser. Le nuove regole delle pagine città sono confinate sotto i prefissi .city-detail e .city-hero per non intaccare index.html né questo report.html.

2. I tab della scheda città

Ogni scheda città è organizzata in cinque tab — Overview, Sights, Nightlife, Stay (mostrato solo se la città ha hotel catalogati) e Tips. Il gestore dei click commuta soltanto le classi active:

var btns   = document.querySelectorAll('.city-tab-btn');
var panels = document.querySelectorAll('.city-tab-panel');
btns.forEach(function(btn){
  btn.addEventListener('click', function(){
    btns.forEach(function(b){ b.classList.remove('active'); });
    panels.forEach(function(p){ p.classList.remove('active'); });
    this.classList.add('active');
    var panel = document.getElementById('tab-' + this.dataset.tab);
    if(panel){ panel.classList.add('active'); }
    // Leaflet deve ricalcolare le dimensioni quando il tab Overview torna attivo
    if(this.dataset.tab === 'overview' && cityMap){
      setTimeout(function(){ cityMap.invalidateSize(); }, 50);
    }
  });
});

3. data-pct → custom property CSS

Le metric card portano un attributo HTML data-pct con il valore numerico (0–100). Quando il DOM è pronto, un unico ciclo legge ciascun attributo e ne riversa il valore nella custom property CSS corrispondente — l'unica eccezione ammessa alla regola «zero stili inline» (impostare una custom property con style.setProperty alimenta una variabile, non una regola di presentazione):

document.querySelectorAll('[data-pct]').forEach(function(el){
  var v = el.dataset.pct;
  if(el.classList.contains('circular-ring')){
    el.style.setProperty('--pct', v);         // pilota l'angolo del conic-gradient
  } else {
    el.style.setProperty('--bar-w', v + '%'); // pilota la larghezza della barra → parte la transizione CSS
  }
});

4. Leaflet — il pattern invalidateSize()

La mappa Leaflet si trova nel tab Overview (il pannello attivo di default), quindi viene renderizzata correttamente al primo caricamento. Quando l'utente esce e torna, il contenitore è già stato dimensionato una volta; la chiamata setTimeout(..., 50) lascia al browser il tempo di completare il ciclo di paint del display: block prima che Leaflet rilegga le dimensioni. La variabile cityMap è dichiarata fuori dalla IIFE così che il gestore dei tab possa raggiungerla.

5. Soglie dei badge hero (calcolate in fase di build)

I badge sono calcolati da deploy_dashboard.py durante la rigenerazione delle pagine, tarati sugli intervalli reali del dataset (appeal 48–68, safety 47–75, green 60–88, prezzo 88–163 €):

🔎 Virtual Analyst — l'assistente che risponde alle domande

Il Virtual Analyst è l'assistente del sito: risponde a domande scritte in linguaggio naturale (italiano o inglese) sulle 30 capitali — per esempio «bar a Dublino» o «discoteche nelle città fuori dall'euro». È un sistema RAG (Retrieval-Augmented Generation): invece di "sapere" le risposte, le va a cercare nei 30 file XML e le mostra in modo ordinato. Non inventa: riporta solo ciò che è nel dataset.

Come trova la risposta giusta

Per ogni domanda cerca in due modi complementari allo stesso tempo: per significato (capisce il senso anche con parole diverse — «dove dormire» trova gli hotel) e per parole chiave (cerca i termini esatti). Poi fonde le due classifiche in un'unica graduatoria: un risultato che convince entrambi i metodi finisce in cima.

La marcia in più: cercare tra i metadati

La ricerca nel testo va bene per le domande discorsive, ma fa fatica con quelle precise (es. «discoteche nelle città che non usano l'euro»). Per questo l'analista sfrutta i metadati già iniettati in ogni città — macro-regione, valuta, tipo di locale, punteggi numerici — esattamente come i filtri di un sito di e-commerce: prima restringe il campo a colpo sicuro (es. valuta ≠ euro e tipo = discoteca), poi cerca nel testo solo dentro quel sottoinsieme. È il punto in cui RAG e Web of Data (i microdata Schema.org) si fondono: la stessa informazione che descrive le città per i motori di ricerca serve anche a rispondere meglio.

I tre vantaggi della fusione RAG × Web of Data

• Precisione: i filtri su @region, @currency, @category sono esatti — niente più «zuppa di tag» da indovinare nel testo.
• Niente confusione tra categorie: un pub e una discoteca si distinguono dall'etichetta tipizzata (BarOrPub / NightClub), non dal contesto della frase.
• Numeri garantiti: coordinate (GeoCoordinates), appeal (AggregateRating) e indicatori sono restituiti identici al dato — zero allucinazioni sui numeri.

I due "motori": uno in locale, uno nel browser

La versione completa è un piccolo server Python (FastAPI) con gli indici di ricerca veri: è la reference implementation, si avvia sul proprio computer. Ma il sito è pubblicato su GitHub Pages, che ospita solo file statici e non può eseguire un server Python: perciò, quando non riesce a contattare il server locale, la pagina usa una versione che gira interamente nel browser (metadataQuery()) sui dati già inclusi nella pagina. I due motori usano la stessa logica di filtraggio: quello del browser è ciò che i visitatori usano davvero, e funziona senza alcun server.

Dettagli tecnici (approfondimento)

Le sezioni precedenti bastano per capire il sistema; qui sotto il "sotto il cofano".

data/xml_dataset/*.xml  →  rag/ingest.py  →  rag_index/  (index.faiss 384-dim · docs.json 452 chunk + meta)
                                              ↓
                       rag/vectorstore.py   FAISS + BM25Okapi → Reciprocal Rank Fusion + pre-filtro metadati
                                              ↓
                       rag/api.py           FastAPI (127.0.0.1:8000) · parse_filters() · rilevamento intento

• FAISS IndexFlatIP (384 dim, all-MiniLM-L6-v2) per la ricerca semantica; BM25Okapi per quella lessicale; fusione con Reciprocal Rank Fusion (α=0.5, k=60);
• il rilevamento d'intento (transport / hotel / attractions / safety / districts / nightlife) dà priorità ai chunk della sezione pertinente.

ingest.py allega a ogni chunk i metadati strutturati dell'XML, così la ricerca filtra su valori esatti invece di cercarli nel testo:

{
  "text": "[BERLIN] Bar e locali notturni: ...",
  "city": "BERLIN", "section": "nightlife", "source": "Berlin.xml",
  "meta": { "appeal": 63.2, "currency": "EUR", "region": "western",
           "safety": 72.5, "green": 78.0, "cost": 85.0, "economy": 15.0, "price": 157.25 },
  "categories": ["bar", "pub", "nightclub"]
}

Dimensioni di filtro riconosciute

I vincoli si combinano in AND (es. eurozone + green over 70). Lato server la risposta /query include il campo filters con le dimensioni applicate (trasparenza); lato client il motore restituisce in più i valori garantiti verbatim dai metadati.

Limiti noti: alcune città (Londra, Budapest, Parigi…) mancano di dati hotel nelle sorgenti Wikivoyage; la sintesi delle risposte testuali è euristica (estrazione di frasi), non generativa.

🤖 Dichiarazione Utilizzo Strumenti AI

Claude Code (Anthropic) — Assistenza allo Sviluppo

Lo strumento Claude Code è stato utilizzato per:

• Debugging della pipeline di parsing (problema selezione pagina principale nei dump Wikivoyage multi-pagina)
• Scrittura della funzione advanced_wiki_cleaner() per la pulizia del Wikitext con regex
• Risoluzione del problema accent-insensitive per Reykjavík (uso di unicodedata.normalize)
• Identificazione e correzione del bug nell'estrazione distretti in deploy_dashboard.py (d.text invece di d.findtext('name'))
• Generazione della griglia di override distretti per Luxembourg e Stockholm
• Generazione di questo file report.html e del README.md

AI per i Contenuti del Dataset

Le sintesi strategiche in inglese in city_descriptions.json (mostrate come Strategic Summary nel tab Tips delle schede città) sono state generate con Gemini (Google AI) tramite prompt strutturati. Fonte: testo a scopo didattico, non estratto da una singola fonte primaria.

Genera una descrizione strategica in inglese (max 2 frasi) di [CITTÀ]
come capitale europea, focalizzandoti su: innovazione urbana, sostenibilità,
sicurezza, accessibilità economica. Tono: analitico, da report istituzionale.

Fonti degli Indici Numerici

⚠️ Avvertenza accademica: i valori numerici in city_indices.json sono stime rielaborate con AI a partire da fonti pubbliche. Non sostituiscono la consultazione diretta dei dataset originali Numbeo o EEA per usi di ricerca.

📁 Elenco Completo dei File e Fonti

Inventario completo del repository, con link diretto a ogni file su GitHub e alla fonte originale. I conteggi qui sotto sono calcolati a runtime scandendo le cartelle del progetto.

👥 Il Team

Progetto sviluppato nell'ambito della Laurea Magistrale in Governance e Politiche dell'Innovazione Digitale (GEPID) — Università di Bologna, A.A. 2024/2025.