{"service":"MonitoraggioCDV Agent API","version":"2.1","description":"API read-only di un servizio indipendente e non ufficiale (non affiliato alla Regione Campania), progettata per essere consumata da altri agenti LLM. Fornisce accesso a ~300k atti gia' pubblici della Regione Campania piu' ~840k progetti d'investimento (CUP) (Casa di Vetro, Consiglio Regionale, BURC, Gare, ODG Giunta, OpenCUP) con ricerca FTS, ricerca semantica vettoriale (pgvector + multilingual-e5-base), ricerca ibrida FTS+vettoriale (RRF), filtri strutturati e paginazione a cursore per censimenti esaustivi.","base_url":"https://monitoraggiocdv.progetti.campania.it","auth":{"type":"bearer","header":"Authorization: Bearer <AGENT_TOKEN>","note":"il token e' fornito dall'admin del servizio, separato dall'ADMIN_TOKEN."},"endpoints":[{"path":"/api/agent/manifest","method":"GET","auth":false,"description":"Questo documento. Discovery delle capability."},{"path":"/api/agent/search","method":"GET","auth":true,"description":"Ricerca multi-source con FTS, filtri strutturati e paginazione a cursore. Restituisce i top-K risultati da CDV, CR, BURC, gare, ODG. La ricerca FTS sugli atti CDV include anche il TESTO DEGLI ALLEGATI (Allegato A/B/C, elenchi, graduatorie): un nome presente solo in un allegato rende comunque trovabile il decreto. Paginazione a cursore disponibile per censimenti esaustivi (consigliato: sources=cdv).","params":{"q":"stringa di ricerca (obbligatoria, min 1 char)","limit":"int 1-200 (default 10). Hard-cap automatico a 25 se snippet=true.","sources":"CSV: 'cdv','cr','burc','gare','odg' (default tutti). Es. sources=cdv,cr per solo atti regionali.","snippet":"bool (default true) — frammenti evidenziati con <mark>. Disabilitare per risposte compatte (snippet=false).","fields":"CSV di campi da includere nella risposta. Riduce drasticamente il payload token. Es. fields=id,num_atto_anno,data,struttura,title,citation_url porta ogni riga da ~400-700 a ~80-120 token. Omettere per risposta completa.","struttura":"Filtro struttura CDV (prefix match sul codice + nome). Es. struttura=50.11 (matcha '50.11 Direzione...'). Anche formato pipe accettato: 50|11 → 50.11.","tipologia":"Filtro codice tipologia_atto CDV. Es. tipologia=E (Decreto Dirigenziale). Vedi /api/agent/tipologie per i codici validi.","data_da":"Data minima atto CDV (ISO YYYY-MM-DD inclusa)","data_a":"Data massima atto CDV (ISO YYYY-MM-DD inclusa)","fonte":"Filtro fonte CDV: 'vecchio' o 'nuovo'","cig":"Filtro ESAUSTIVO per CIG (match esatto). Restituisce TUTTI gli atti che citano quel CIG, anche solo nel testo del PDF, non un top-N per pertinenza. q diventa opzionale. Solo CDV. Ordine per data, paginabile con cursor, con total reale. Per la filiera raggruppata usa /api/agent/fascicolo.","cup":"Filtro ESAUSTIVO per CUP (match esatto), analogo a cig. Utile per rendicontazione PNRR di un progetto d'investimento.","sort":"'relevance' (default) — rank FTS decrescente. 'date' — data_atto decrescente, stabile per paginazione.","cursor":"Cursore opaco base64 per la pagina successiva. Ottenuto da next_cursor della risposta precedente. Quando presente, viene interrogata solo la sorgente CDV.","mode":"'fts' (default) — ricerca full-text PostgreSQL (tsquery). 'semantic' — ricerca vettoriale pgvector (cosine, multilingual-e5-base).   Utile per query in linguaggio naturale, sinonimi, concetti correlati.   Richiede che gli embeddings siano stati generati (generate_embeddings.py). 'hybrid' — fusione FTS + vettoriale via Reciprocal Rank Fusion.   Migliore precisione nei casi misti.   Con mode=semantic/hybrid, il cursore e sort non sono supportati (solo prima pagina).   Nota: il primo invocazione semantic/hybrid carica il modello (~20-30s)."},"response":{"query":"stringa passata","sources":"sorgenti effettivamente interrogate","total":"Conteggio reale match CDV (COUNT separato). Presente solo sulla prima pagina (cursor assente) e solo quando CDV e' in sources.","next_cursor":"Cursore per la pagina successiva (stringa opaca base64). null = fine dei risultati.","results":"array risultati ordinati per pertinenza o data"},"notes":["Con cursor presente, viene interrogata solo CDV (le altre sorgenti non supportano la paginazione).","Per censimenti esaustivi CDV: usa sort=date&snippet=false&fields=id,num_atto_anno,data,struttura,title,citation_url&limit=100","Budget token: ~80-120 token/riga (fields compatti) vs ~400-700 (snippet full).","Struttura: il formato 50.11 viene convertito automaticamente in 50|11 (formato DB)."],"example_census":"/api/agent/search?q=terreni+fabbricati&sources=cdv&sort=date&snippet=false&fields=id,num_atto_anno,data,struttura,title,citation_url&struttura=60.06&limit=100","example_quick":"/api/agent/search?q=PCE+groundwater+contamination&limit=5","example_cig":"/api/agent/search?cig=87119554B2&sort=date&snippet=false&fields=id,num_atto_anno,data,struttura,title,citation_url&limit=100"},{"path":"/api/agent/fascicolo","method":"GET","auth":true,"description":"Filiera COMPLETA di un contratto/progetto per CIG (o CUP): tutti gli atti CDV che citano il codice, raggruppati per fase procedurale (impegni, gara, aggiudicazione, contratto, liquidazioni, varianti, rettifiche, altri). Per audit e rendicontazione: una sola chiamata, esaustiva e verificabile.","params":{"cig":"CIG della filiera (obbligatorio se manca cup)","cup":"CUP della filiera (alternativo a cig)","max_atti":"tetto atti recuperati (default 500, max 2000)"},"response":{"cig|cup":"il codice interrogato","total":"numero atti trovati","troncato":"true se raggiunto max_atti","conteggi_fase":"{fase: n} per ciascun gruppo non vuoto","fascicolo":"{fase: [atti]} — atti in ordine cronologico"},"example":"/api/agent/fascicolo?cig=87119554B2"},{"path":"/api/agent/fetch","method":"GET","auth":true,"description":"Restituisce un singolo documento con metadati + testo completo estratto dal PDF + allegati. Identificato da source + id, oppure dalla citation_url.","params":{"source":"cdv | cr | burc | gare | odg","id":"intero (id interno del documento)","max_text":"int — taglia il testo a N caratteri (default 50000)"},"example":"/api/agent/fetch?source=cdv&id=14662"},{"path":"/api/agent/recent","method":"GET","auth":true,"description":"Ultimi atti pubblicati nelle 24/48/N ore. Utile per agenti che fanno briefing giornalieri.","params":{"hours":"int (default 48)","limit":"int (default 30)","sources":"CSV come in /search"}},{"path":"/api/agent/structure","method":"GET","auth":true,"description":"Mappa delle strutture amministrative regionali (DG, UOD) con codici e nomi correnti. Usata dagli agenti per interpretare i campi 'struttura' nei documenti."},{"path":"/api/agent/tipologie","method":"GET","auth":false,"description":"Mappa codice tipologia → label (E=Decreto Dirigenziale, ...)."}],"data_model":{"cdv":"Atti amministrativi Casa di Vetro — 298k+ atti dal 2011 (Decreti Dirigenziali ~150k, DGR ~5k, Decreti Assessorili, ecc.)","cr":"Atti del Consiglio Regionale (interrogazioni, mozioni, leggi regionali)","burc":"Bollettino Ufficiale Regione Campania (numeri pubblicati dal 2015)","gare":"Gare d'appalto dal Portale Gare Telematiche (PGT)","odg":"Ordini del giorno delle sedute di Giunta (Sedute Giunta)","cup":"Progetti d'investimento pubblico localizzati in Campania (OpenCUP/DIPE, ~840k CUP). Per CUP, descrizione, soggetto titolare, importo finanziato, settore/natura intervento. Citazione: opencup.gov.it/portale/progetto/-/cup/<CUP>."},"query_syntax":{"operators":{"\"frase esatta\"":"match esatto di una sequenza di parole","-parola":"esclusione del termine","parola*":"prefix match (es. formaz* cattura formazione/formativo)","A OR B":"alternative (OR esplicito; default e' AND)","595/2025":"numero/anno atto — riconosciuto automaticamente","DGR 254 del 24/05/2022":"query naturale italiana — parser dedicato"},"tip":"Per il comune: usa la phrase-match '\"Comune di Sarno\"' nella query e combina con struttura= per restringere la DG competente."},"tipologie_cdv":{"E":"Decreto Dirigenziale","G":"Delibera di Giunta","D":"Determina Dirigenziale","S":"Decreto Assessorile","P":"Decreto Presidenziale","A":"Attivita di Controllo"},"censimento_recipe":{"description":"Come enumerare TUTTI gli atti di una struttura senza perderne nessuno","steps":["1. GET /search?q=...&sources=cdv&sort=date&snippet=false&fields=id,num_atto_anno,data,struttura,title,citation_url&struttura=XX.YY&limit=100","2. Prendi next_cursor dalla risposta; total indica il totale atteso.","3. Ripeti GET /search?...&cursor=<next_cursor> finche' next_cursor=null.","4. Deduplica per id se necessario."],"note":"Con sort=date la paginazione e' stabile: nessun buco, nessun duplicato a parita' di query. Usa sort=relevance solo per i top-K, non per censimenti esaustivi."},"rate_limit":"nessuno applicato lato server; rispetta convenzioni 1 req/s consigliate per uso agente","license":"dati pubblici Regione Campania (CC-BY 4.0)","contact":"MonitoraggioCDV — progetto indipendente (non ufficiale)"}