openosservaprezzi 0.1.0__tar.gz

openosservaprezzi-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+tmp/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.cache/
+dist/

openosservaprezzi-0.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+# Guida per agenti
+
+`osservaprezzi` è una CLI read-only sui dati pubblici dell'Osservatorio Prezzi (MIMIT). Non scrive nulla sul portale, non richiede credenziali, non usa un browser.
+
+## Primo comando
+
+```bash
+osservaprezzi agent-context
+```
+
+Restituisce in una sola chiamata l'intero contratto: collezioni, dimensioni con le loro dipendenze, comandi con un esempio ciascuno, codici di uscita, forma degli errori e garanzie. Non dedurre queste informazioni dall'help testuale: chiedile qui.
+
+## Modalità agente
+
+Aggiungi `--agent` a qualsiasi comando: equivale a `--json`, senza colori e senza interazione. Vale per dati ed errori.
+
+```bash
+osservaprezzi catalog --agent
+osservaprezzi get consumo --year 2025 --month 5 --province Roma --category energia --agent
+```
+
+## Regole che evitano gli errori più comuni
+
+1. **Non inventare valori.** Ogni valore ammesso si ottiene da `values`. I suggerimenti negli errori vengono dal form del portale, mai da somiglianze.
+2. **I domini dipendenti richiedono i genitori.** I mesi dipendono dall'anno, le settimane da anno e mese: `values ortofrutta-it week --year 2025 --month 5`.
+3. **`get` vuole tutti i filtri.** Non esistono default impliciti; per usare quelli del portale serve `--latest`, che li dichiara nel campo `defaults_used`.
+4. **Distingui le uscite.** `2` significa che il portale ha rifiutato un valore, `3` che i filtri erano validi ma non c'erano dati. Non sono la stessa cosa.
+5. **Leggi gli errori da `stderr`.** `stdout` contiene solo dati: `comando --agent 2>&1 >/dev/null | jq .`
+6. **Prima di un archivio, chiedi il piano.** `archive ... --dry-run --agent` dice quante richieste servono, senza eseguirle.
+
+## Nessun parallelismo
+
+Le richieste al portale sono serializzate su tutta la macchina da un lock su file: una sola per volta, con un intervallo minimo condiviso fra processi. Lanciare più istanze in parallelo non accelera nulla — si alternano. Non tentare di aggirare il vincolo con task concorrenti: il traffico complessivo resterebbe lo stesso e serviresti solo a rendere imprevedibili le attese. Se un comando sembra fermo, sta aspettando il suo turno e lo dichiara su `stderr` con `--verbose`.
+
+`--lock-timeout` limita l'attesa: allo scadere il comando esce con `service_unavailable` (uscita 5, `retryable: true`), mai proseguendo in parallelo.
+
+## Interpretazione dei dati
+
+I prezzi sono **livelli** in euro, non indici. Il portale sconsiglia i confronti fra province e fra mesi: sotto la stessa descrizione possono esserci varietà, marche e confezioni diverse. Per le serie storiche la fonte corretta sono gli indici ISTAT (NIC, IPCA), disponibili via SDMX.
+
+Ogni record conserva `collection`, `source_url` e `retrieved_at`: citali quando riporti un valore.
+
+## Sviluppo
+
+```bash
+uv sync
+uv run pytest
+```
+
+I test girano su fixture HTML ritagliate, senza rete. `scripts/refresh_fixtures.py` le rigenera.

openosservaprezzi-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Diario delle versioni
+
+Il formato segue [Keep a Changelog](https://keepachangelog.com/it/1.1.0/); le versioni seguono il [versionamento semantico](https://semver.org/lang/it/).
+
+## [0.1.0] — 2026-08-18
+
+Prima versione, pubblicata su PyPI come `openosservaprezzi`; il comando installato è `osservaprezzi`.
+
+### Aggiunto
+
+- Tre collezioni: `consumo` (rilevazioni mensili di beni e servizi di largo consumo), `ortofrutta-it` e `ortofrutta-eu` (quotazioni all'ingrosso).
+- Percorso di scoperta `catalog` → `describe` → `values` → `get`, con i valori ammessi letti dal portale e i domini dipendenti risolti passando i filtri genitori.
+- Output in tabella, JSON e CSV, con provenienza (`collection`, `source_url`, `retrieved_at`) in ogni record e scrittura su file senza sporcare `stdout`.
+- Query salvate in YAML ed eseguibili con `run`.
+- Archivi on-demand con `archive`: piano preventivo `--dry-run`, limite `--max-requests`, esecuzione sequenziale, `manifest.json`, deduplicazione per chiave naturale, ripresa con `--resume` e filtro locale `--product`.
+- Errori distinti per categoria con codici di uscita deterministici (2 input non valido, 3 nessun dato, 4 contratto cambiato, 5 servizio indisponibile, 6 risposta parziale) ed emissione JSON su `stderr`.
+- Riconoscimento dei filtri rifiutati dal portale leggendo il form della risposta: un valore inesistente non viene più confuso con un'assenza di dati.
+- Aiuto autodescrittivo: esempi eseguibili in ogni comando, opzioni che dichiarano collezione di appartenenza e dipendenze, comando `agent-context` e opzione `--agent`.
+- Serializzazione delle richieste su tutta la macchina tramite lock su file, con intervallo minimo condiviso fra processi e `--lock-timeout`.
+- Cache locale dei soli metadati, invalidabile con `--refresh`.

openosservaprezzi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Borruso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openosservaprezzi-0.1.0/LOG.md

@@ -0,0 +1,29 @@
+# Log
+
+## 2026-08-18
+
+- README: aggiunta la sezione sul valore dei dati, con il confronto fra pane (referenze eterogenee) e benzina (prodotto omogeneo) e la tabella delle analisi che reggono.
+- Aggiunti al PRD due principi fondativi: l'aiuto come contratto e l'accesso serializzato al servizio pubblico (RF-27…RF-38).
+- Aiuto autodescrittivo: esempi in ogni comando, opzioni che dichiarano collezione e dipendenze, comando `agent-context`, opzione `--agent`, `AGENTS.md`.
+- Introdotto un lock su file che impedisce esecuzioni parallele sulla stessa macchina, con intervallo minimo condiviso fra processi e `--lock-timeout`.
+- Aggiunta licenza MIT e riscritto il README per chi analizza i dati.
+- Completata la prima versione: verificati sul campo `run` e `archive`, aggiunti i test di parità, contratto e archivio (57 test verdi).
+- Eseguito l'archivio di accettazione su 64 province: 60 righe, nessun duplicato, manifest `complete` conservato in `docs/evidence/`.
+- Corretto un difetto della vista tabella: `catalog` nascondeva la colonna `collection`, cioè l'identificatore da usare nei comandi successivi.
+- Corretto un difetto della cache: i domini venivano memorizzati anche da pagine con filtri rifiutati.
+- Chiusi tre rilievi della revisione: `defaults_used` nella provenienza di ogni record, test dell'uscita 6 per l'archivio parziale, nota sulla vista tabella nel README.
+- Allineati `docs/evaluation.md` e `tasks/todo.md` con le evidenze e la revisione dei dieci criteri di accettazione.
+
+## 2026-08-17
+
+- Tracciato il traffico del portale con `agent-browser`: unica GET del documento, nessuna XHR di dati, endpoint ausiliario ancora non risolvibile.
+- Verificato che l'echo dei filtri copre tutte le dimensioni e distingue parametro non valido da assenza di dati; `submit=Applica` non è necessario.
+- Realizzata la prima versione della CLI `osservaprezzi`: catalog, describe, values, get, run, archive, version, cache.
+- Aggiunte fixture HTML ritagliate, script di rigenerazione e 17 test offline verdi.
+- Conclusa l'indagine di fattibilità: tre collezioni fattibili via GET HTML, con rischio medio.
+- Documentate evidenze, replay HTTP, parità dei form, archivi e raccomandazione in `docs/evaluation.md`.
+- Aggiornato il PRD con dimensioni reali, filtri espliciti e vincoli degli archivi.
+- Aggiunti al PRD archivi on-demand con espansione delle dimensioni, manifest, deduplicazione e ripresa.
+- Esteso il PRD con la parità completa tra controlli dei form HTML e parametri CLI.
+- Scritto il PRD preliminare della CLI unificata e read-only.
+- Preparato il piano per la verifica di fattibilità della CLI Osservatorio Prezzi.

openosservaprezzi-0.1.0/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: openosservaprezzi
+Version: 0.1.0
+Summary: CLI read-only per i dati pubblici dell'Osservatorio Prezzi
+Project-URL: Homepage, https://github.com/aborruso/open-osservatorio-prezzi
+Project-URL: Source, https://github.com/aborruso/open-osservatorio-prezzi
+Project-URL: Issues, https://github.com/aborruso/open-osservatorio-prezzi/issues
+Project-URL: Changelog, https://github.com/aborruso/open-osservatorio-prezzi/blob/main/CHANGELOG.md
+Author-email: Andrea Borruso <aborruso@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,mimit,open-data,osservatorio-prezzi,prezzi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5.2
+Requires-Dist: portalocker>=4.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# osservaprezzi
+
+Porta sul tuo computer, in forma analizzabile, i prezzi pubblicati dall'[Osservatorio Prezzi](https://osservaprezzi.mise.gov.it/) del Ministero delle Imprese e del Made in Italy.
+
+Sul portale quei dati si consultano una pagina alla volta, scegliendo mese, provincia e categoria da quattro menu a tendina. Se vuoi confrontare il prezzo del pane in tutta Italia, o seguire le quotazioni degli ortaggi in dieci mercati, ti servono decine di consultazioni manuali e altrettanti copia-incolla. Questo strumento fa quel lavoro al posto tuo e ti restituisce un CSV.
+
+**Cosa NON fa**: non inventa valori, non stima, non completa i buchi. Se un dato non è pubblicato, te lo dice.
+
+Prima di impostare un'analisi leggi [A cosa servono davvero questi dati](#a-cosa-servono-davvero-questi-dati): non tutti i confronti che sembrano possibili lo sono, e la differenza dipende dal prodotto.
+
+## I dati disponibili
+
+| | Cosa contiene | Aggiornamento | Dettaglio |
+|---|---|---|---|
+| **consumo** | Prezzi al dettaglio di beni e servizi — pane, carne, pesce, benzina, ortofrutta, parrucchiere, lavanderia… — fino a circa 160 voci, con differenze fra province | mensile | 64 province |
+| **ortofrutta-it** | Quotazioni all'ingrosso di frutta e verdura | settimanale | 23 mercati italiani |
+| **ortofrutta-eu** | Le stesse quotazioni sui mercati esteri | settimanale | 11 mercati europei |
+
+Si parte dal 2021. Per `consumo` ogni riga riporta prezzo minimo, massimo e medio rilevati nella provincia; per l'ortofrutta specie, varietà, calibro, origine e prezzo.
+
+## Installazione
+
+Il modo più semplice, se hai [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install openosservaprezzi
+```
+
+Il pacchetto si chiama `openosservaprezzi`, il comando che installa è `osservaprezzi`.
+
+Per provarlo senza installare nulla:
+
+```bash
+uvx --from openosservaprezzi osservaprezzi catalog
+```
+
+Con pip:
+
+```bash
+pip install openosservaprezzi
+```
+
+Verifica che funzioni:
+
+```bash
+osservaprezzi version
+```
+
+## I primi tre comandi
+
+### Cosa c'è
+
+```bash
+osservaprezzi catalog
+```
+
+```
+collection     title                                                      status     dimensions
+-------------  ---------------------------------------------------------  ---------  --------------------------------
+consumo        Rilevazioni mensili di beni e servizi di largo consumo     available  year, month, province, category
+ortofrutta-it  Prodotti ortofrutticoli all'ingrosso nei mercati italiani  available  year, month, week, market, group
+ortofrutta-eu  Prodotti ortofrutticoli all'ingrosso nei mercati europei   available  year, month, week, market, group
+```
+
+Le parole nell'ultima colonna sono i filtri che dovrai indicare. Per `consumo` servono anno, mese, provincia e categoria.
+
+### Quali valori posso usare
+
+Non devi indovinarli: te li elenca lo strumento, chiedendoli al portale.
+
+```bash
+osservaprezzi values consumo category
+```
+
+```
+value       label
+----------  -------------------------------
+altri_alim  Alimentari
+energia     Energetici
+groc        Cura della persona e della casa
+ittici      Ittici
+orto        Ortofrutta
+servizi     Servizi
+```
+
+Stessa cosa per province, mercati, gruppi:
+
+```bash
+osservaprezzi values ortofrutta-eu market
+```
+
+```
+value       label
+----------  ----------
+AMBURGO     AMBURGO
+BARCELLONA  BARCELLONA
+BERLINO     BERLINO
+BOLOGNA     BOLOGNA
+LIONE       LIONE
+MILANO      MILANO
+MONACO      MONACO
+PARIGI      PARIGI
+PERPIGNANO  PERPIGNANO
+ROMA        ROMA
+STOCCARDA   STOCCARDA
+```
+
+Attenzione a mesi e settimane: dipendono dall'anno, quindi vanno chiesti indicandolo.
+
+```bash
+osservaprezzi values ortofrutta-it week --year 2021 --month 1
+```
+
+Gennaio 2021 ha cinque settimane, maggio 2025 ne ha quattro: è il portale a dirlo.
+
+### I dati
+
+```bash
+osservaprezzi get consumo --year 2025 --month 5 --province Roma --category ittici
+```
+
+```
+year  month  province  category  product                                          price_min  price_max  price_avg
+----  -----  --------  --------  -----------------------------------------------  ---------  ---------  ---------
+2025  5      Roma      ittici    Alici Fresche Di Pescata (1000 Gr)               5.9        29.9       10.36
+2025  5      Roma      ittici    Sgombri Freschi Di Pescata (1000 Gr)             5.99       24.0       10.99
+2025  5      Roma      ittici    Merluzzi O Naselli Freschi Di Pescata (1000 Gr)  18.01      29.9       24.99
+2025  5      Roma      ittici    Trote Di Allevamento Fresche (1000 Gr)           6.9        16.0       10.5
+2025  5      Roma      ittici    Salmone Fresco (1000 Gr)                         12.9       30.92      20.14
+2025  5      Roma      ittici    Mitili O Cozze Fresche (1000 Gr)                 4.44       7.01       5.57
+2025  5      Roma      ittici    Vongole Fresche (1000 Gr)                        5.99       28.0       21.53
+```
+
+I prezzi sono in euro, riferiti alla quantità tra parentesi.
+
+## Portare i dati in Excel, R, Python
+
+Aggiungi `--csv` e `--output`:
+
+```bash
+osservaprezzi get consumo --year 2025 --month 5 --province Bologna --category energia \
+  --csv --output benzina-bologna.csv
+```
+
+Il file contiene anche l'indirizzo esatto della pagina da cui il dato proviene e il momento in cui è stato letto — utile quando dovrai citare la fonte:
+
+```
+year,month,province,category,product,price_min,price_max,price_avg,category_label,collection,source_url,retrieved_at
+2025,5,Bologna,energia,Gasolio Per Auto Con Servizio Alla Pompa (1 L),1.512,2.142,1.75,Energetici,consumo,https://…
+```
+
+Con `--json` ottieni invece una struttura pronta per essere elaborata.
+
+## Il pane in tutta Italia: gli archivi
+
+Qui lo strumento dà il meglio. Vuoi il prezzo di un prodotto in tutte le province? Non serve ripetere 64 comandi:
+
+```bash
+osservaprezzi archive consumo \
+  --year 2025 --month 5 --category altri_alim \
+  --all province \
+  --product "Pane Fresco Con Farina Di Grano (1000 Gr)" \
+  --output pane-maggio-2025
+```
+
+Prima di partire puoi vedere quanto costerà, senza chiedere niente al portale:
+
+```bash
+osservaprezzi archive consumo --year 2025 --month 5 --category altri_alim \
+  --all province --dry-run
+```
+
+```
+richieste previste: 64
+dimensioni espanse: province (64)
+```
+
+Al termine trovi due file:
+
+- **`data.csv`** — i dati, senza duplicati;
+- **`manifest.json`** — cosa è stato chiesto, a quale indirizzo, quando, quali province hanno risposto e quali no.
+
+Nell'esempio reale: 64 province interrogate, 60 con quel pane, 4 dove non è stato rilevato. Il prezzo medio andava da 2,42 a 7,04 euro al chilo.
+
+Se l'esecuzione si interrompe, riprende da dove era rimasta:
+
+```bash
+osservaprezzi archive … --output pane-maggio-2025 --resume
+```
+
+Puoi espandere anche altre dimensioni — tutti i mercati per una settimana, per esempio:
+
+```bash
+osservaprezzi archive ortofrutta-it --year 2025 --month 5 --week 2 \
+  --group ORTAGGI --all market --output ortaggi-settimana2
+```
+
+## Riusare la stessa interrogazione
+
+Salva i filtri in un file e rieseguili quando vuoi:
+
+```yaml
+# ortaggi-roma.yaml
+version: 1
+collection: ortofrutta-it
+filters:
+  year: 2025
+  month: 5
+  week: 2
+  market: ROMA
+  group: ORTAGGI
+format: csv
+```
+
+```bash
+osservaprezzi run ortaggi-roma.yaml --output ortaggi.csv
+```
+
+È il modo più semplice per rifare la stessa estrazione il mese prossimo, o per condividerla con un collega.
+
+## A cosa servono davvero questi dati
+
+Vale la pena saperlo prima di impostare un'analisi, perché il valore di questi numeri cambia molto a seconda di cosa si guarda.
+
+### Il limite da cui parte tutto
+
+Una descrizione come «Pane Fresco Con Farina Di Grano (1000 Gr)» non identifica un prodotto: identifica una **categoria**. Dentro ci finiscono pani diversi per varietà, marca, confezione e negozio in cui sono stati rilevati — quella combinazione, nel linguaggio Istat, si chiama *referenza*. Ogni provincia campiona le proprie, e da un mese all'altro il campione può cambiare.
+
+Lo si vede nei dati stessi. Maggio 2025, stessa descrizione, stesso mese:
+
+| | minimo | massimo | medio |
+|---|---:|---:|---:|
+| Napoli | 2,00 | 2,99 | **2,42** |
+| Roma | 2,29 | 4,89 | **3,41** |
+| Palermo | 3,50 | 5,00 | **4,42** |
+| Milano | 2,99 | 7,00 | **4,97** |
+| Bologna | 3,99 | 7,80 | **5,23** |
+
+A Milano il pane più caro costa 2,3 volte il più economico, nella stessa città e nello stesso mese: quella dispersione interna è la prova che sotto l'etichetta ci sono prodotti differenti. Perciò la distanza fra Napoli e Bologna mescola due cose inseparabili — quanto costa il pane e quali pani sono finiti nel campione.
+
+Il portale lo dice esplicitamente: i confronti fra città e fra mesi «possono essere effettuati correttamente solo utilizzando gli indici dei prezzi al consumo».
+
+### Cosa regge comunque
+
+**La dispersione dentro una singola rilevazione.** Minimo, massimo e medio della stessa cella vengono dalla stessa rilevazione: confrontarli fra loro è legittimo. È anche l'informazione più concreta per chi compra — dice quanto conviene guardarsi intorno — e per chi osserva un mercato, perché misura quanto è differenziato.
+
+**I prodotti omogenei.** L'avvertenza morde dove la referenza è variabile; dove il prodotto è sempre lo stesso quasi sparisce. Benzina verde self, maggio 2025:
+
+| | medio |
+|---|---:|
+| Milano | 1,688 |
+| Bologna | 1,692 |
+| Napoli | 1,695 |
+| Palermo | 1,715 |
+
+Uno scarto dell'1,6% fra la prima e l'ultima, contro il più del doppio che separa le stesse città sul pane. La benzina verde è la benzina verde ovunque: niente varietà, niente marca artigianale, niente pezzatura. Sui carburanti il confronto territoriale regge.
+
+**L'ortofrutta all'ingrosso.** Lì specie, varietà, calibro, categoria, presentazione e origine sono colonne esplicite, non nascoste in una descrizione: sai esattamente cosa stai confrontando, quindi puoi confrontarlo.
+
+### Cosa non regge
+
+Classifiche fra città sugli alimentari e serie storiche di qualsiasi voce. Non è una cautela formale: sono conclusioni che i dati non sostengono. Per l'andamento nel tempo la fonte corretta sono gli indici dei prezzi al consumo dell'Istat, costruiti confrontando ogni prodotto con se stesso e quindi immuni al cambio di composizione. In cambio danno la variazione, non il prezzo in euro. Sono pubblicati via SDMX: il **NIC** arriva fino al dettaglio provinciale (132 aree fra Italia, ripartizioni, regioni e province) ed espone numeri indice e variazioni congiunturali e tendenziali; l'**IPCA**, l'indice armonizzato europeo, è invece solo nazionale.
+
+Sono due strumenti con due mestieri: i **livelli** dicono quanto si paga qui e ora, gli **indici** come si muove nel tempo.
+
+### Perché allora esistono
+
+Questi livelli nascono dalla stessa raccolta che alimenta gli indici dei prezzi al consumo, ma non sono dati grezzi: sono elaborazioni. Per la rilevazione tradizionale e le fonti amministrative il portale pubblica il prezzo minimo e massimo effettivamente rilevati e la media delle quotazioni validate; per i dati degli scanner di cassa il minimo e il massimo fra i prezzi medi mensili di ciascun codice a barre, e una media provinciale ponderata sul peso campionario dei punti vendita. Le singole quotazioni per punto vendita non sono pubbliche. Servono inoltre alla sorveglianza dei prezzi — individuare situazioni anomale, alimentare il lavoro del Garante e delle commissioni di allerta rapida — dove basta un ordine di grandezza pubblico e verificabile.
+
+### In breve
+
+| Analisi | Regge? |
+|---|---|
+| Dispersione min-max in una provincia e un mese | sì |
+| Confronto fra province sui carburanti | sì |
+| Ortofrutta all'ingrosso fra mercati | sì, i descrittori sono espliciti |
+| Copertura: dove e quando un prodotto è rilevato | sì |
+| Classifica delle città sul costo degli alimentari | no |
+| Serie storica di un prodotto | no, usa gli indici Istat |
+
+## Altre due cose da sapere
+
+**Le assenze significano «non rilevato».** Se un prodotto non compare per una provincia non vuol dire che lì non si venda: quel mese non è stato rilevato. A Roma i prodotti ittici sono sette, ad Aosta quattro. Negli archivi queste situazioni sono registrate nel manifest, non nascoste.
+
+**Il dettaglio è provinciale, non comunale.** Le province coperte sono 64 delle 107 italiane.
+
+## Un vincolo voluto: una richiesta alla volta
+
+Il portale è un servizio pubblico pensato per la consultazione umana, senza API. Per non sovraccaricarlo, lo strumento lascia passare **una sola richiesta alla volta su tutto il computer**, con almeno un secondo fra l'una e l'altra. Se lanci due comandi in parallelo non raddoppi il traffico: si alternano, e nell'insieme vanno alla velocità di uno solo. Un archivio lungo non ti impedisce quindi di fare nel frattempo una singola interrogazione — aspetterà solo il suo turno.
+
+Non è una limitazione da aggirare: è il motivo per cui uno strumento del genere può esistere senza creare problemi a chi lo ospita. Se ti servono volumi molto grandi, la strada giusta è chiedere i dati alla fonte.
+
+## Quando qualcosa non va
+
+Lo strumento distingue i casi, invece di restituire silenziosamente una tabella vuota come fa il portale:
+
+| Messaggio | Cosa significa |
+|---|---|
+| `invalid_parameter` | hai indicato un valore che non esiste; ti vengono elencati quelli ammessi |
+| `no_data` | i filtri erano corretti, ma per quel periodo non ci sono rilevazioni |
+| `contract_changed` | il portale ha cambiato struttura: lo strumento va aggiornato |
+| `service_unavailable` | il portale non risponde, oppure un'altra esecuzione è in corso |
+
+Se sbagli il nome di un mercato te lo dice subito, con la lista giusta:
+
+```bash
+osservaprezzi get ortofrutta-it --year 2025 --month 5 --week 2 --market MESSINA --group ORTAGGI
+# errore [invalid_parameter]: valori non ammessi dal portale: market
+#   valori ammessi: BERGAMO, BOLOGNA, BOLZANO, CAGLIARI, CATANIA, …
+```
+
+## Usarlo con un assistente AI
+
+Ogni comando ha `--agent`, che produce output strutturato, e c'è un comando che descrive l'intero strumento in una volta sola:
+
+```bash
+osservaprezzi agent-context
+```
+
+Se lavori con Claude, Copilot o simili, il file [`AGENTS.md`](AGENTS.md) contiene le istruzioni da dare all'assistente.
+
+## Fonte e licenza
+
+I dati provengono dall'Osservatorio Prezzi del MIMIT, che li elabora a partire da rilevazioni Istat, Unioncamere e BMTI. Cita sempre la fonte e l'indirizzo della pagina: li trovi in ogni riga esportata.
+
+La licenza dei dati non è dichiarata in modo univoco dal portale: prima di ripubblicare archivi derivati, verifica le condizioni con le fonti.
+
+Il codice di questo strumento è rilasciato con licenza MIT (vedi [`LICENSE`](LICENSE)).
+
+## Contribuire
+
+Segnalazioni e proposte sono benvenute. Per lavorare al codice:
+
+```bash
+uv sync
+uv run pytest
+```
+
+I test girano su pagine HTML salvate in locale e non richiedono connessione.