Ripensare discover_dataflows: da keyword matching a catalogo queryabile

[aborruso]

Contesto

Questa issue nasce da un problema pratico e si collega alla discussione più ampia in #32 (ricerca semantica per trovare il dataflow giusto).

Il problema immediato

discover_dataflows con keyword generiche produce output che supera il limite di token MCP:

discover_dataflows(keywords: "occupati,attività economica,settore")
→ Error: result (179,285 characters) exceeds maximum allowed tokens

discover_dataflows(keywords: "occupati,ATECO")
→ Error: result (332,090 characters) exceeds maximum allowed tokens

La keyword occupat matcha centinaia di dataflow ISTAT. La conversazione si blocca.

Il problema reale (vedi #32)

L'overflow è un sintomo. La causa è che discover_dataflows usa keyword matching testuale, che:

1. Non capisce il contesto: "occupati per settore" → dovrebbe cercare dataflow con dimensione ATECO, non tutti quelli che contengono "occupat"
2. Non distingue la granularità: "incidenti nei comuni" → dovrebbe cercare dataflow con REF_AREA comunale, non quelli nazionali/regionali (Ricerca semantica per trovare il dataflow giusto: il caso degli incidenti stradali comunali #32)
3. Non penalizza dataflow problematici: quelli lenti, con troppe dimensioni, o con regolamento precedente
4. Restituisce tutto in un blob: nessun modo di esplorare incrementalmente i risultati

Proposta: catalogo DuckDB queryabile

Invece di restituire JSON nel messaggio MCP, scrivere i dataflow in una tabella DuckDB locale arricchita con metadati strutturati.

Schema proposto

CREATE TABLE dataflows (
    id TEXT PRIMARY KEY,
    name_it TEXT,
    name_en TEXT,
    description_it TEXT,
    description_en TEXT,
    id_datastructure TEXT,
    last_update TIMESTAMP,
    -- campi arricchiti derivati dai constraints
    n_dimensions INTEGER,           -- numero di dimensioni
    has_regional_detail BOOLEAN,    -- REF_AREA contiene regioni
    has_provincial_detail BOOLEAN,  -- REF_AREA contiene province
    has_municipal_detail BOOLEAN,   -- REF_AREA contiene comuni
    has_ateco BOOLEAN,              -- ha dimensione ATECO
    has_sex BOOLEAN,                -- ha dimensione sesso
    has_age BOOLEAN,                -- ha dimensione età
    has_citizenship BOOLEAN,        -- ha dimensione cittadinanza
    dimensions TEXT[],              -- lista nomi dimensioni
    time_start TEXT,                -- inizio copertura temporale
    time_end TEXT                   -- fine copertura temporale
);

Flusso di lavoro

1. discover_dataflows → popola/aggiorna la tabella DuckDB → restituisce solo "Catalogo aggiornato: 1200 dataflow disponibili nella tabella dataflows"
2. L'LLM usa SQL via DuckDB MCP per cercare in modo mirato:

-- "occupati per settore economico"
SELECT id, name_it, n_dimensions, last_update
FROM dataflows
WHERE name_it ILIKE '%occupat%' AND has_ateco = true
ORDER BY last_update DESC LIMIT 20;

-- "incidenti stradali nei comuni" (#32)
SELECT id, name_it, n_dimensions
FROM dataflows
WHERE name_it ILIKE '%incident%' AND has_municipal_detail = true;

-- dataflow aggiornati con poche dimensioni (più affidabili)
SELECT id, name_it, n_dimensions
FROM dataflows
WHERE name_it ILIKE '%disocc%' AND n_dimensions <= 10
ORDER BY n_dimensions ASC, last_update DESC;

Vantaggi

• Nessun overflow: il messaggio MCP è sempre una riga
• Filtraggio potente: SQL con WHERE, ILIKE, AND/OR, ORDER BY, LIMIT
• Granularità territoriale: l'LLM può filtrare per livello (comunale/provinciale/regionale) senza leggere i nomi
• Qualità della scelta: penalizzare dataflow con troppe dimensioni o vecchi
• Esplorazione incrementale: l'LLM può fare più query successive senza richiamare l'API

Relazione con la cache esistente

La cache diskcache attuale resta inalterata — continua a gestire TTL e rate-limiting verso l'API ISTAT. Il DB DuckDB è un layer di presentazione separato, alimentato dagli stessi dati in cache.

Da definire

• Dove salvare il file DuckDB (path configurabile?)
• Come e quando arricchire i campi derivati (al primo discover_dataflows? in background?)
• Estendere lo stesso pattern a get_constraints e search_constraint_values?
• Integrazione con ricerca semantica futura (Ricerca semantica per trovare il dataflow giusto: il caso degli incidenti stradali comunali #32)

Riferimenti

• Ricerca semantica per trovare il dataflow giusto: il caso degli incidenti stradali comunali #32 — Ricerca semantica per trovare il dataflow giusto: il caso degli incidenti stradali comunali