{"service":"MonitoraggioCDV Agent API","version":"2.1","description":"API read-only progettata per essere consumata da altri agenti LLM. Fornisce accesso a 298k+ atti amministrativi della Regione Campania (Casa di Vetro, Consiglio Regionale, BURC, Gare, ODG Giunta) 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. 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'","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"},{"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)"},"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":"ferdinando @ MonitoraggioCDV / Segreteria Sebastiano Odierna"}