{"id":35098644,"url":"https://github.com/ondata/normattiva_2_md","last_synced_at":"2026-01-29T20:00:51.578Z","repository":{"id":321973552,"uuid":"1021905195","full_name":"ondata/normattiva_2_md","owner":"ondata","description":"Trasforma i testi delle leggi italiane in formato leggibile e pronto per l'uso con intelligenze artificiali","archived":false,"fork":false,"pushed_at":"2026-01-21T15:01:43.000Z","size":7171,"stargazers_count":5,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-22T01:32:22.377Z","etag":null,"topics":["ai","akoma-ntoso","italian-law","italy","legal","legislative-texts","markdown","nlp","normattiva","open-data"],"latest_commit_sha":null,"homepage":"https://ondata.github.io/normattiva_2_md/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ondata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-18T06:17:24.000Z","updated_at":"2026-01-21T15:20:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"cb937109-cbc6-4b72-8dd2-48553d020581","html_url":"https://github.com/ondata/normattiva_2_md","commit_stats":null,"previous_names":["aborruso/normattiva_2_md"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/ondata/normattiva_2_md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ondata%2Fnormattiva_2_md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ondata%2Fnormattiva_2_md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ondata%2Fnormattiva_2_md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ondata%2Fnormattiva_2_md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ondata","download_url":"https://codeload.github.com/ondata/normattiva_2_md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ondata%2Fnormattiva_2_md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28883960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T19:55:09.949Z","status":"ssl_error","status_checked_at":"2026-01-29T19:55:08.490Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","akoma-ntoso","italian-law","italy","legal","legislative-texts","markdown","nlp","normattiva","open-data"],"created_at":"2025-12-27T16:10:11.891Z","updated_at":"2026-01-29T20:00:51.544Z","avatar_url":"https://github.com/ondata.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔄 Normattiva2MD - Convertitore Akoma Ntoso in Markdown\n\n[![Versione PyPI](https://img.shields.io/pypi/v/normattiva2md.svg)](https://pypi.org/project/normattiva2md/)\n[![Versione Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)\n[![Licenza](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![deepwiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ondata/normattiva_2_md)\n\n**Normattiva2MD** è uno strumento da riga di comando progettato per convertire documenti XML in formato **Akoma Ntoso** (in particolare le norme pubblicate su `normattiva.it`) in documenti **Markdown** leggibili e ben formattati. L'obiettivo principale è offrire un formato compatto e immediatamente riutilizzabile quando le norme devono essere fornite come contesto a un **Large Language Model (LLM)** o elaborate in pipeline di Intelligenza Artificiale.\n\n---\n\n## ⚠️ Avvertenza legale\n\n**I testi presenti nella banca dati \"Normattiva\" non hanno carattere di ufficialità.**\n\n**L'unico testo ufficiale e definitivo è quello pubblicato sulla Gazzetta Ufficiale Italiana a mezzo stampa, che prevale in casi di discordanza.**\n\nGli utenti di questo strumento devono essere consapevoli che i documenti convertiti da normattiva.it sono forniti a scopo informativo e non hanno valore legale ufficiale. Per qualsiasi utilizzo legale o giuridico, consultare sempre la versione ufficiale pubblicata sulla Gazzetta Ufficiale Italiana.\n\n---\n\n👉 Se vuoi una **panoramica eccellente** di normattiva2md leggi [**questo wiki**](https://deepwiki.com/ondata/normattiva_2_md) generato dall'AI.\n\n---\n\n## 🎯 Perché Markdown per le norme?\n\nConvertire le norme legali da XML Akoma Ntoso a Markdown offre vantaggi significativi:\n\n- **📝 Ottimizzato per LLM**: Il formato Markdown è ideale per modelli linguistici di grandi dimensioni (Claude, ChatGPT, ecc.), permettendo di fornire intere normative come contesto per analisi, interpretazione e risposta a domande legali\n- **🤖 Applicazioni AI**: Facilita la creazione di chatbot legali, assistenti normativi e sistemi di Q\u0026A automatizzati\n- **👁️ Leggibilità**: Il testo è immediatamente comprensibile sia da persone che da sistemi automatici, senza tag XML complessi\n- **🔍 Ricerca e analisi**: È un formato ottimale per indicizzazione, ricerca semantica e processamento del linguaggio naturale\n- **📊 Documentazione**: Si integra con facilità in wiki, basi di conoscenza e piattaforme di documentazione\n\n## 🚀 Caratteristiche\n\n- ✅ **Conversione completa** da XML Akoma Ntoso a Markdown\n- ✅ **Filtro articolo CLI** con flag `--art` (es: `--art 4`, `--art 16bis`) senza modificare URL\n- ✅ **Supporto URL articolo-specifico** (`~art3`, `~art16bis`, etc.) per estrarre singoli articoli\n- ✅ **Gestione degli articoli** con numerazione corretta\n- ✅ **Supporto per le modifiche legislative** con evidenziazione `((modifiche))`\n- ✅ **Gerarchia book-style intelligente** con parsing strutturato (H1→H2→H3→H4)\n- ✅ **Front matter YAML** con metadati completi (URL, dataGU, codiceRedaz, dataVigenza, article)\n- ✅ **Machine-to-machine ready** per LLM, RAG e parsing automatici\n- ✅ **CLI flessibile** con argomenti posizionali e nominati\n- ✅ **Gestione errori robusta** con messaggi informativi\n- ✅ **Dipendenze minime**: requests (URL fetch), rich (output terminalizzato)\n- ✅ **Ricerca in linguaggio naturale** richiede [Exa AI API](https://exa.ai) per l'integrazione AI\n- ✅ **Modalità debug interattiva** (v2.0.16+) con download guidato e nomi file intelligenti\n\n## 📦 Installazione\n\n### Installazione da PyPI (Raccomandato)\n\nIl pacchetto è pubblicato su [PyPI](https://pypi.org/project/normattiva2md/) come `normattiva2md`.\n\n```bash\n# Con uv\nuv tool install normattiva2md\n\n# Con pip\npip install normattiva2md\n\n# Utilizzo\nnormattiva2md input.xml output.md\n```\n\n### Configurazione Exa AI API (opzionale - per ricerca in linguaggio naturale)\n\nPer utilizzare la funzionalità di ricerca in linguaggio naturale (`--search`), è necessario configurare una [API key di Exa AI](https://exa.ai).\n\n#### Metodo 1: File .env (Raccomandato)\n\nCrea un file `.env` nella directory del progetto:\n\n```bash\n# Crea il file .env\necho 'EXA_API_KEY=\"your-exa-api-key-here\"' \u003e .env\n\n# Verifica che sia configurato\ncat .env\n```\n\nIl programma caricherà automaticamente l'API key dal file `.env` all'avvio.\n\n### Metodo 2: Variabile d'ambiente (Linux/macOS)\n\n```bash\n# Configura la variabile d'ambiente con la tua API key\nexport EXA_API_KEY='your-exa-api-key-here'\n\n# Verifica che sia configurata\necho $EXA_API_KEY\n```\n\n### Metodo 3: Parametro CLI (per uso temporaneo)\n\n```bash\n# Passa l'API key direttamente come parametro\nnormattiva2md -s \"legge stanca accessibilità\" --exa-api-key \"your-exa-api-key\" output.md\n```\n\n### Installazione da sorgenti\n\n```bash\ngit clone https://github.com/ondata/normattiva_2_md.git\ncd normattiva_2_md\npython3 -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n# .venv\\Scripts\\activate  # Windows\npip3 install -e .\nnormattiva2md input.xml output.md\n```\n\n### Esecuzione diretta (senza installazione)\n\n```bash\ngit clone https://github.com/ondata/normattiva_2_md.git\ncd normattiva_2_md\npython3 __main__.py input.xml output.md\n```\n\n\n## 🐍 Utilizzo come Libreria Python\n\n\u003e **Nota:** Per vedere esempi pratici e testare la libreria, puoi aprire il notebook Jupyter di esempio: [examples/quickstart.ipynb](examples/quickstart.ipynb)\n\u003e\n\u003e **📚 Documentazione API completa:** [docs/API_REFERENCE.md](docs/API_REFERENCE.md) - Tutti i metodi, classi, eccezioni con esempi dettagliati.\n\nOltre al CLI, `normattiva2md` è utilizzabile come libreria Python nei tuoi script o notebook Jupyter:\n\n### Quick Start\n\n```python\nfrom normattiva2md import convert_url, convert_xml, search_law\n\n# Conversione da URL\nresult = convert_url(\"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\")\nprint(result.markdown[:500])\nprint(result.title)\nprint(result.metadata)\nresult.save(\"legge_stanca.md\")\n\n# Conversione da file XML locale\nresult = convert_xml(\"documento.xml\")\nresult.save(\"output.md\")\n\n# Ricerca in linguaggio naturale (richiede Exa API key)\nresults = search_law(\"legge stanca accessibilità\")\nfor r in results:\n    print(f\"[{r.score:.2f}] {r.title}\")\n    print(f\"  URL: {r.url}\")\n```\n\n### Classe Converter per Uso Avanzato\n\n```python\nfrom normattiva2md import Converter\n\n# Converter con configurazione persistente\nconv = Converter(\n    exa_api_key=\"your-key\",  # o usa EXA_API_KEY da .env\n    quiet=True\n)\n\n# Ricerca e conversione in un passo\nresult = conv.search_and_convert(\"decreto dignità\")\nresult.save(\"decreto_dignita.md\")\n\n# Batch processing\nurls = [\n    \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\",\n    \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82\",\n]\nfor i, url in enumerate(urls):\n    result = conv.convert_url(url)\n    if result:\n        result.save(f\"legge_{i+1}.md\")\n```\n\n### Gestione Errori\n\n```python\nfrom normattiva2md import (\n    convert_url,\n    InvalidURLError,\n    ConversionError,\n    APIKeyError,\n    Normattiva2MDError,\n)\n\ntry:\n    result = convert_url(\"https://www.normattiva.it/...\")\nexcept InvalidURLError as e:\n    print(f\"URL non valido: {e}\")\nexcept ConversionError as e:\n    print(f\"Errore conversione: {e}\")\nexcept Normattiva2MDError as e:\n    print(f\"Errore: {e}\")\n\n# Gestione errori soft (ritornano None)\nresult = convert_url(url, article=\"999\")\nif result is None:\n    print(\"Articolo non trovato\")\n```\n\n### Opzioni Avanzate\n\n```python\n# Estrai singolo articolo\nresult = convert_url(url, article=\"16bis\")\n\n# Genera link markdown ai riferimenti\nresult = convert_url(url, with_urls=True)\n\n# Modalità silenziosa (no logging)\nresult = convert_url(url, quiet=True)\n```\n\n### Oggetti Ritornati\n\n- **`ConversionResult`**: Contiene `markdown`, `metadata`, `url`, `url_xml` + helper come `title`, `data_gu`, `save()`\n- **`SearchResult`**: Contiene `url`, `title`, `score`\n\n## 💻 Utilizzo\n\n### Metodo 1: Da URL Normattiva (consigliato)\n\nLa CLI riconosce automaticamente gli URL di `normattiva.it` e scarica il documento Akoma Ntoso prima di convertirlo:\n\n```bash\n# Conversione diretta URL → Markdown (output su file)\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53\" legge.md\n\n# Forza download via OpenData (quando manca export Akoma)\nnormattiva2md --opendata \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53\" legge.md\n\n# Conversione diretta con output su stdout (utile per pipe)\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82\"\n\n# Conversione articolo specifico (solo art. 3)\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto-legge:2018-07-12;87~art3\" art3.md\n\n# Conversione articolo con estensione (art. 16-bis)\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis\" art16bis.md\n\n# Forza conversione completa anche con URL articolo-specifico\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto-legge:2018-07-12;87~art3\" --completo legge_completa.md\nnormattiva2md -c \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis\" legge_completa.md\n\n# Conservare l'XML scaricato\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53\" legge.md --keep-xml\n```\n\n### Metodo 2: Da file XML locale\n\n```bash\n# Argomenti posizionali (più semplice)\nnormattiva2md input.xml output.md\n\n# Argomenti nominati\nnormattiva2md -i input.xml -o output.md\nnormattiva2md --input input.xml --output output.md\n```\n\n### Metodo 2bis: Filtrare un singolo articolo con `--art`\n\nIl flag `--art` consente di estrarre un singolo articolo senza modificare l'URL:\n\n```bash\n# Filtrare articolo da file XML locale\nnormattiva2md --art 4 input.xml output.md\nnormattiva2md --art 3bis input.xml articolo.md\n\n# Filtrare articolo da URL (più semplice che costruire URL con ~artN)\nnormattiva2md --art 16bis \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53\" art16bis.md\n\n# Il flag --art ha priorità su ~artN nell'URL\nnormattiva2md --art 3 \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82~art5\" art3.md\n# → Mostra art. 3, ignora ~art5 nell'URL\n\n# Combinare con --with-urls per link automatici\nnormattiva2md --art 4 --with-urls input.xml output.md\n\n# Output su stdout\nnormattiva2md --art 3 input.xml \u003e articolo.md\n```\n\n**Note:**\n- Formato articoli: numero + estensione opzionale (es: `4`, `16bis`, `3ter`)\n- Case-insensitive: `16BIS` = `16bis`\n- Se articolo non trovato: output con solo metadata + warning su stderr\n- `--art` ha priorità su `--completo` e `~artN` nell'URL\n\n### Metodo 3: Esportazione provvedimenti attuativi\n\nEsporta i provvedimenti attuativi previsti da una legge in formato CSV:\n\n```bash\n# Esporta provvedimenti in CSV (richiede URL normattiva.it)\nnormattiva2md --provvedimenti \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2024;207\" legge.md\n\n# Genera due file:\n# - legge.md: conversione markdown della legge\n# - 2024_207_provvedimenti.csv: provvedimenti attuativi in formato CSV\n\n# Solo conversione markdown (nessun CSV se non ci sono provvedimenti)\nnormattiva2md \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:1973;295\" legge.md\n```\n\n**Formato CSV generato:**\n- 7 colonne: `dettagli`, `governo`, `fonte_provvedimento`, `oggetto`, `provvedimento_previsto`, `adozione`, `link_al_provvedimento`\n- Encoding: UTF-8\n- Nome file: `{anno}_{numero}_provvedimenti.csv`\n- Posizione: stessa directory del file markdown\n\n### Metodo 4: Ricerca in linguaggio naturale (con Exa AI)\n\n**⚠️ Richiede API key Exa AI configurata**\n\nPrima di utilizzare questa funzionalità, assicurati di aver configurato l'[API key di Exa AI](#configurazione-exa-ai-api-opzionale---per-ricerca-in-linguaggio-naturale).\n\n**Importante**: Per la ricerca in linguaggio naturale devi **sempre usare il flag `-s` o `--search`**:\n\n```bash\n# Ricerca automatica (seleziona automaticamente il miglior risultato)\n# Usa --auto-select per evitare i prompt interattivi e usare il primo risultato suggerito.\nnormattiva2md -s \"legge stanca accessibilità\" output.md\nnormattiva2md -s \"codice amministrazione digitale\" --auto-select \u003e cad.md\nnormattiva2md --search \"decreto dignità\" --exa-api-key \"your-key\" \u003e decreto.md\n\n# Output su stdout\nnormattiva2md -s \"codice della strada\"\nnormattiva2md -s \"legge stanca accessibilità\" --exa-api-key \"your-key\" \u003e legge_stanca.md\n\n# Modalità debug interattiva (--debug-search)\n# Ti permette di vedere tutti i risultati e scegliere manualmente\nnormattiva2md -s \"legge stanca accessibilità\" --debug-search\n```\n\n#### 🔍 Modalità Debug Interattiva\n\nLa modalità `--debug-search` ti mostra tutti i risultati trovati e ti permette di scegliere manualmente quello desiderato:\n\n```bash\nnormattiva2md -s \"legge stanca accessibilità\" --debug-search\n```\n\n**Cosa succede:**\n1. Mostra il JSON completo della risposta Exa API (per debugging)\n2. Lista tutti i risultati con titolo, URL e punteggio di preferenza\n3. Ti chiede di selezionare il numero del risultato desiderato\n4. **Nuovo in v2.0.16**: Dopo la selezione, ti chiede se vuoi scaricare il documento\n5. Suggerisce un nome file in formato snake_case basato sul titolo\n6. Puoi accettare (premendo ENTER) o personalizzare il nome\n7. Se il file esiste già, chiede conferma prima di sovrascriverlo\n\n**Esempio di sessione interattiva:**\n\n```bash\n$ normattiva2md -s \"legge stanca accessibilità\" --debug-search\n\n🔍 Risultati trovati per: legge stanca\nSeleziona il numero del risultato desiderato (1-5), o 0 per annullare:\n  [1] DECRETO-LEGGE 7 giugno 2024, n. 73...\n      URL: https://www.normattiva.it/...\n      Preferenza: -30\n\n  [2] LEGGE 24 maggio 1970, n. 336...\n      URL: https://www.normattiva.it/uri-res/N2Ls?...\n      Preferenza: 24\n\n  [3] LEGGE 9 gennaio 2004, n. 4...\n      URL: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig\n      Preferenza: 24\n\nScelta: 3\n✅ URL selezionato manualmente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig\n\n📥 Vuoi scaricare questo documento? (s/N): s\n📝 Nome file [legge_9_gennaio_2004_n_4.md]:\n✅ URL selezionato: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig\nRilevato URL normattiva.it: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig\n...\n✅ Conversione completata: legge_9_gennaio_2004_n_4.md\n```\n\n**Opzioni nella modalità interattiva:**\n- **Conferma download**: Rispondi `s`, `si`, `sì`, `y`, o `yes` per confermare\n- **Nome file**: Premi ENTER per accettare il nome suggerito, oppure digita un nome personalizzato\n- **Sovrascrittura**: Se il file esiste già, ti chiede conferma prima di sovrascriverlo\n- **Annulla**: Rispondi `n` o `N` in qualsiasi momento, oppure premi Ctrl+C\n\n### Esempi pratici\n\n```bash\n# Convertire un file XML locale\nnormattiva2md decreto_82_2005.xml codice_amministrazione_digitale.md\n\n# Con percorsi assoluti\nnormattiva2md /percorso/documento.xml /percorso/output.md\n\n# Ricerca in linguaggio naturale (richiede Exa AI API - usa SEMPRE -s)\nnormattiva2md -s \"legge stanca accessibilità\" legge_stanca.md\nnormattiva2md -s \"decreto dignità\" \u003e decreto.md\n\n# Visualizzare l'aiuto\nnormattiva2md --help\n\n# Generare link markdown agli articoli citati su normattiva.it\nnormattiva2md --with-urls input.xml output.md\nnormattiva2md --with-urls \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53\" legge_con_link.md\n\n# Esportare provvedimenti attuativi in CSV\nnormattiva2md --provvedimenti \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2024;207\" legge.md\n# Genera: legge.md + 2024_207_provvedimenti.csv\n```\n\n### Opzioni disponibili\n\n```\nutilizzo: normattiva2md [-h] [-v] [-i INPUT] [-o OUTPUT] [-s SEARCH]\n                       [--keep-xml] [-q] [-c] [--with-references]\n                       [--with-urls] [--debug-search] [--auto-select]\n                       [--exa-api-key EXA_API_KEY]\n                       [file_input] [file_output]\n\nConverte un file XML Akoma Ntoso in formato Markdown\n\nargomenti posizionali:\n  file_input            File XML di input in formato Akoma Ntoso o URL normattiva.it\n  file_output           File Markdown di output (default: stdout)\n\nopzioni:\n   -h, --help            Mostra questo messaggio di aiuto\n   -v, --version         Mostra la versione del programma\n   -i INPUT, --input INPUT\n                         File XML di input in formato Akoma Ntoso o URL normattiva.it\n   -o OUTPUT, --output OUTPUT\n                         File Markdown di output (default: stdout)\n   -s SEARCH, --search SEARCH\n                         Cerca documento in linguaggio naturale (richiede Exa AI API)\n  --keep-xml            Mantiene il file XML temporaneo dopo la conversione\n  --opendata            Forza download Akoma Ntoso via API OpenData (ZIP AKN)\n   -q, --quiet           Modalità silenziosa (nessun output su stderr)\n   -c, --completo        Forza download completo anche con URL articolo-specifico\n   --with-references     Scarica anche tutti i riferimenti legislativi citati\n   --with-urls           Genera link markdown agli articoli citati su normattiva.it\n   --provvedimenti       Esporta provvedimenti attuativi in CSV (richiede URL normattiva.it)\n   --debug-search        Modalità debug interattiva per la ricerca (mostra tutti i risultati)\n   --auto-select         Seleziona automaticamente il miglior risultato (default: True)\n   --exa-api-key EXA_API_KEY\n                         API key di Exa AI (alternativa a EXA_API_KEY env var)\n\nnota: per ricerca in linguaggio naturale usare -s/--search\n```\n\n**Modalità ricerca:**\n- **Automatica** (default): `-s \"query\"` seleziona automaticamente il miglior risultato\n- **Interattiva**: `-s \"query\" --debug-search` mostra tutti i risultati e permette selezione manuale con download interattivo\n\n## 📋 Formato di input supportato\n\nLo strumento supporta documenti XML in formato **Akoma Ntoso 3.0**, inclusi:\n\n- 📜 **Decreti legislativi**\n- 📜 **Leggi**\n- 📜 **Decreti legge**\n- 📜 **Costituzione**\n- 📜 **Regolamenti**\n- 📜 **Altri atti normativi**\n\n📖 **Guida agli URL**: Consulta [URL_NORMATTIVA.md](docs/URL_NORMATTIVA.md) per la struttura completa degli URL e esempi pratici.\n\n### Strutture supportate\n\n- ✅ Preamboli e intestazioni\n- ✅ Capitoli e sezioni\n- ✅ Articoli e commi\n- ✅ Liste e definizioni\n- ✅ Modifiche legislative evidenziate\n- ✅ Note e aggiornamenti\n\n## 📄 Formato di output\n\nIl Markdown generato include:\n\n- **Front matter YAML** con metadati completi (URL, dataGU, codiceRedaz, dataVigenza)\n- **Gerarchia heading book-style** ottimizzata per lettura e parsing LLM:\n  - `#` (H1) per titolo documento\n  - `##` (H2) per Capi (capitoli principali)\n  - `###` (H3) per Sezioni\n  - `####` (H4) per Articoli\n- **Liste puntate** per le definizioni\n- **Numerazione corretta** dei commi e articoli\n- **Evidenziazione delle modifiche** con `((testo modificato))`\n- **Struttura machine-to-machine** ready per LLM e parser automatici\n\n### Esempio di output\n\n```markdown\n---\nurl: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82\nurl_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20050307\u0026codiceRedaz=005G0104\u0026dataVigenza=20251101\ndataGU: 20050307\ncodiceRedaz: 005G0104\ndataVigenza: 20251101\n---\n\n# Codice dell'amministrazione digitale.\n\n## Capo I - PRINCIPI GENERALI\n\n### Sezione I - Definizioni, finalita' e ambito di applicazione\n\n#### Art. 1. - Definizioni\n\n1. Ai fini del presente codice si intende per:\n\n- a) documento informatico: il documento elettronico...\n- b) firma digitale: un particolare tipo di firma...\n- c) ((identità digitale)): la rappresentazione informatica...\n\n#### Art. 2. - Finalita' e ambito di applicazione\n\n1. Lo Stato, le Regioni e le autonomie locali...\n\n### Sezione II - ((Carta della cittadinanza digitale))\n\n#### Art. 3. - Diritto all'uso delle tecnologie\n\n1. I cittadini e le imprese hanno il diritto...\n```\n\n## 🔧 Sviluppo\n\n### Requisiti\n\n- Python 3.7+\n- requests\u003e=2.25.0 (URL fetch)\n- rich\u003e=13.0.0,\u003c14.0.0 (output terminalizzato)\n- [Exa AI API](https://exa.ai) per funzionalità di ricerca in linguaggio naturale (opzionale)\n\n### Configurazione dell'ambiente di sviluppo\n\n```bash\ngit clone https://github.com/ondata/normattiva_2_md.git\ncd normattiva_2_md\npython3 -m venv .venv\nsource .venv/bin/activate  # Su Windows: .venv\\Scripts\\activate\npip3 install -e .\n```\n\n### Creazione di un eseguibile autonomo (opzionale)\n\nPer creare un eseguibile autonomo per uso locale:\n\n```bash\npip install pyinstaller\npython3 -m PyInstaller --onefile --name normattiva2md __main__.py\n# L'eseguibile sarà in dist/normattiva2md\n```\n\n### Binari precompilati su GitHub\n\nOgni tag `v*` scatena la GitHub Action [`Build Releases`](.github/workflows/release-binaries.yml) che genera gli eseguibili standalone PyInstaller per **Linux x86_64** e **Windows x86_64**. I pacchetti (`.tar.gz` per Linux, `.zip` per Windows) vengono caricati come asset della release corrispondente e sono disponibili anche come artifact quando il workflow viene avviato manualmente (`workflow_dispatch`). Per pubblicare una nuova release:\n\n1. Aggiorna il numero di versione in `setup.py` (e negli altri file pertinenti, se necessario).\n2. Esegui i test locali (`make test`) e documenta eventuali cambiamenti in `LOG.md` e `VERIFICATION.md`.\n3. Crea un tag Git `vX.Y.Z` e pushalo su GitHub (`git tag vX.Y.Z \u0026\u0026 git push origin vX.Y.Z`), oppure avvia manualmente il workflow specificando lo stesso tag già pubblicato.\n4. Verifica che la release su GitHub contenga gli asset `normattiva2md-X.Y.Z-linux-x86_64.tar.gz` e `normattiva2md-X.Y.Z-windows-x86_64.zip`.\n\n### Test\n\n```bash\n# Test di base (con package installato)\nnormattiva2md sample.xml output.md\n\n# Test dell'eseguibile\n./dist/normattiva2md sample.xml output.md\n```\n\n## 📝 Licenza\n\nQuesto progetto è distribuito con licenza [MIT](LICENSE).\n\n## 🤝 Contributi\n\nI contributi sono benvenuti! Segui questi passaggi:\n\n1. Esegui un fork del progetto\n2. Crea un ramo per la nuova funzionalità (`git checkout -b funzione/descrizione`)\n3. Registra le modifiche (`git commit -m 'Descrizione sintetica della modifica'`)\n4. Pubblica il ramo (`git push origin funzione/descrizione`)\n5. Invia una richiesta di integrazione\n\n## 📞 Supporto\n\n- 🐛 **Segnalazioni di bug**: [pagina delle segnalazioni](https://github.com/ondata/normattiva_2_md/issues)\n- 💡 **Proposte di nuove funzionalità**: [pagina delle segnalazioni](https://github.com/ondata/normattiva_2_md/issues)\n\n## 🏗️ Stato del progetto\n\n- ✅ **Funzionalità principali**: implementate\n- ✅ **Interfaccia a riga di comando**: completa\n- ✅ **Gestione errori**: robusta\n- 🔄 **Verifiche automatiche**: in evoluzione\n- 📚 **Documentazione**: aggiornata\n\n---\n\n**Akoma2MD** - Trasforma i tuoi documenti legali XML in Markdown leggibile! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fondata%2Fnormattiva_2_md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fondata%2Fnormattiva_2_md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fondata%2Fnormattiva_2_md/lists"}