feat: Add natural language URL lookup with Gemini CLI integration

- Add --search/-s flag for natural language document search
- Integrate Gemini CLI for intelligent normattiva.it URL discovery
- Add lookup_normattiva_url() function with error handling
- Update tests with URLLookupTest class
- Bump version to 1.5.0
- Update documentation and LOG.md

Author: aborruso

.genkit/traces_idx/genkit.metadata

@@ -0,0 +1 @@
+{"version":"1.21.0"}

LOG.md

@@ -4,6 +4,52 @@ Questo file documenta gli avanzamenti significativi e le decisioni chiave del pr
 
 ## 2025-11-02
 
+### ✅ Release Completata e Testata
+
+**Stato**: Release v1.5.0 distribuita con successo
+- ✅ GitHub Actions completato: Binari Linux/Windows generati automaticamente
+- ✅ Release GitHub creata: https://github.com/aborruso/normattiva_2_md/releases/tag/v1.5.0
+- ✅ PyPI aggiornato: Versione 1.5.0 disponibile per installazione
+- ✅ Funzionalità testata: Ricerca "legge di bilancio 2024" → conversione riuscita
+- ✅ Binari standalone: Linux (21MB) e Windows (9MB) disponibili per download
+
+#### 📦 Distribuzione
+- **PyPI**: `pip install akoma2md==1.5.0`
+- **GitHub Releases**: Binari standalone per sistemi senza Python
+- **Installazione Gemini CLI**: Richiesta per funzionalità ricerca (`gemini --help`)
+
+### 🔍 Test Funzionalità Ricerca
+Comando testato: `python3 convert_akomantoso.py --search "legge di bilancio 2024"`
+- ✅ Gemini CLI integrato correttamente
+- ✅ URL trovato: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2023-12-30;213
+- ✅ Conversione XML→Markdown completata
+- ✅ Documento: "Bilancio di previsione dello Stato per l'anno finanziario 2024"
+
+## 2025-11-02
+
+### 🚀 Release v1.5.0: Ricerca Naturale con Gemini CLI
+
+**Nuova funzionalità principale**: Ricerca intelligente di documenti legali per nome naturale
+
+#### ✨ Nuove Funzionalità
+- Aggiunto flag `--search/-s` per ricerca per nome naturale
+- Integrazione con Gemini CLI per ricerca intelligente su normattiva.it
+- Conversione automatica da nome a URL a documento Markdown
+- Mantenimento compatibilità con metodi esistenti
+
+#### 🔧 Implementazione Tecnica
+- Nuovo modulo `lookup_normattiva_url()` con Gemini CLI headless
+- Parsing JSON strutturato per risposte AI
+- Gestione errori robusta per CLI non installato/configurato
+- Tests unitari e di integrazione completi
+
+#### 📚 Documentazione
+- Aggiornato README con esempi ricerca naturale
+- Istruzioni complete installazione e configurazione Gemini CLI
+- Esempi pratici per tutti i metodi di input
+
+## 2025-11-02
+
 ### ✅ Aggiunto flag --version/-v
 
 - Implementato flag CLI per mostrare versione pacchetto

README.md

@@ -62,6 +62,21 @@ cd normattiva_2_md
 python convert_akomantoso.py input.xml output.md
 ```
 
+### Installazione Gemini CLI (opzionale)
+
+Per utilizzare la funzionalità di ricerca per nome naturale, installa [Gemini CLI](https://github.com/google/gemini-cli):
+
+```bash
+# Installazione globale
+npm install -g @google/gemini-cli
+
+# Oppure esecuzione diretta senza installazione
+npx @google/gemini-cli
+
+# Configurazione (richiede API key Google AI)
+gemini setup
+```
+
 ## 💻 Utilizzo
 
 ### Metodo 1: Da URL Normattiva (consigliato)
@@ -90,6 +105,49 @@ akoma2md -i input.xml -o output.md
 akoma2md --input input.xml --output output.md
 ```
 
+### Metodo 3: Ricerca per nome naturale (con Gemini CLI)
+
+**⚠️ Richiede Gemini CLI installato e configurato come dipendenza esterna**
+
+Prima di utilizzare questa funzionalità:
+
+1. **Installa Gemini CLI**: [Installazione Gemini CLI](https://geminicli.com/docs/get-started/installation/)
+2. **Ottieni una API Key**: Vai su [Google AI Studio](https://aistudio.google.com/app/apikey) e crea una API key
+3. **Configura l'autenticazione**: [Autenticazione Gemini CLI](https://geminicli.com/docs/get-started/authentication/)
+
+```bash
+# Installazione
+npm install -g @google/gemini-cli
+
+# Configurazione interattiva (apre browser per login)
+gemini setup
+
+# OPPURE configura manualmente con API key
+export GEMINI_API_KEY="your-api-key-here"
+```
+
+Poi puoi usare la ricerca per nome in due modi:
+
+#### Argomenti posizionali (più semplice)
+```bash
+# Ricerca diretta con argomenti posizionali
+akoma2md "legge stanca" output.md
+akoma2md "decreto dignità" > decreto.md
+
+# Output su stdout
+akoma2md "codice della strada"
+```
+
+#### Argomenti nominati
+```bash
+# Ricerca con flag espliciti
+akoma2md -s "legge stanca" output.md
+akoma2md --search "decreto dignità" > decreto.md
+
+# Output su stdout
+akoma2md -s "codice della strada" > codice_strada.md
+```
+
 ### Esempi pratici
 
 ```bash
@@ -99,6 +157,10 @@ akoma2md decreto_82_2005.xml codice_amministrazione_digitale.md
 # Con percorsi assoluti
 akoma2md /percorso/documento.xml /percorso/output.md
 
+# Ricerca per nome naturale (richiede Gemini CLI)
+akoma2md "legge stanca" legge_stanca.md
+akoma2md "decreto dignità" > decreto.md
+
 # Visualizzare l'aiuto
 akoma2md --help
 ```
@@ -120,6 +182,12 @@ opzioni:
                         File XML di input in formato Akoma Ntoso
   -o OUTPUT, --output OUTPUT
                         File Markdown di output
+  -s SEARCH, --search SEARCH
+                        Cerca documento per nome naturale (richiede Gemini CLI)
+
+argomenti posizionali:
+  input                 File XML locale, URL normattiva.it, oppure stringa di ricerca (con Gemini CLI)
+  output                File Markdown di output (default: stdout)
 ```
 
 ## 📋 Formato di input supportato

convert_akomantoso.py

@@ -17,7 +17,7 @@
 MAX_FILE_SIZE_MB = 50
 MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024
 DEFAULT_TIMEOUT = 30
-VERSION = '1.4.2'
+VERSION = '1.5.0'
 
 def extract_metadata_from_xml(root):
     """
@@ -862,6 +862,72 @@ def process_article(article_element, markdown_content_list, ns, level=2):
                 markdown_content_list.append('\n'.join(quoted_lines))
                 markdown_content_list.append("\n")
 
+def lookup_normattiva_url(search_query):
+    """
+    Usa Gemini CLI per cercare l'URL normattiva.it corrispondente alla query di ricerca.
+
+    Args:
+        search_query (str): La stringa di ricerca naturale (es. "legge stanca")
+
+    Returns:
+        str or None: L'URL trovato, oppure None se non trovato o errore
+    """
+    import subprocess
+    import re
+    import json
+
+    # Prompt semplificato per Gemini CLI
+    prompt = f"""Cerca su normattiva.it l'URL della "{search_query}" e restituisci solo l'URL completo che inizia con https://www.normattiva.it/"""
+
+    try:
+        # Chiama Gemini CLI con il prompt via stdin e output JSON
+        result = subprocess.run(
+            ['gemini', '--output-format', 'json'],
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=60  # Aumentato il timeout per ricerche più complesse
+        )
+
+        if result.returncode != 0:
+            print(f"❌ Errore Gemini CLI: {result.stderr}", file=sys.stderr)
+            return None
+
+        # Parse JSON response
+        try:
+            json_response = json.loads(result.stdout.strip())
+            response_text = json_response.get('response', '').strip()
+        except json.JSONDecodeError as e:
+            print(f"❌ Errore nel parsing JSON da Gemini CLI: {e}", file=sys.stderr)
+            return None
+
+        # Cerca URL normattiva.it nella risposta
+        url_pattern = r'https://www\.normattiva\.it/[^\s]+'
+        match = re.search(url_pattern, response_text)
+
+        if match:
+            url = match.group(0)
+            # Valida che sia un URL normattiva valido
+            if is_normattiva_url(url):
+                return url
+            else:
+                print(f"❌ URL trovato non è valido per normattiva.it: {url}", file=sys.stderr)
+                return None
+        else:
+            print(f"❌ Nessun URL normattiva.it trovato nella risposta di Gemini", file=sys.stderr)
+            return None
+
+    except subprocess.TimeoutExpired:
+        print("❌ Timeout nella chiamata a Gemini CLI", file=sys.stderr)
+        return None
+    except FileNotFoundError:
+        print("❌ Gemini CLI non trovato. Installalo con: gemini --help", file=sys.stderr)
+        print("   Per istruzioni: https://github.com/google/gemini-cli", file=sys.stderr)
+        return None
+    except Exception as e:
+        print(f"❌ Errore nella ricerca URL: {e}", file=sys.stderr)
+        return None
+
 def main():
     """
     Funzione principale che gestisce gli argomenti della riga di comando
@@ -871,26 +937,30 @@ def main():
         description='Converte documenti Akoma Ntoso in formato Markdown da file XML o URL normattiva.it',
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
-Esempi d'uso:
-
-  # Output a file
-  python convert_akomantoso.py input.xml output.md
-  python convert_akomantoso.py -i input.xml -o output.md
-
-  # Output a stdout (default se -o omesso)
-  python convert_akomantoso.py input.xml
-  python convert_akomantoso.py input.xml > output.md
-  python convert_akomantoso.py -i input.xml
-
-  # Da URL normattiva.it (auto-detect)
-  python convert_akomantoso.py "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" output.md
-  python convert_akomantoso.py "URL" > output.md
-  python convert_akomantoso.py -i "URL" -o output.md
-
-  # Mantenere XML scaricato da URL
-  python convert_akomantoso.py "URL" output.md --keep-xml
-  python convert_akomantoso.py "URL" --keep-xml > output.md
-        """
+ Esempi d'uso:
+
+   # Output a file
+   python convert_akomantoso.py input.xml output.md
+   python convert_akomantoso.py -i input.xml -o output.md
+
+   # Output a stdout (default se -o omesso)
+   python convert_akomantoso.py input.xml
+   python convert_akomantoso.py input.xml > output.md
+   python convert_akomantoso.py -i input.xml
+
+   # Da URL normattiva.it (auto-detect)
+   python convert_akomantoso.py "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" output.md
+   python convert_akomantoso.py "URL" > output.md
+   python convert_akomantoso.py -i "URL" -o output.md
+
+   # Ricerca per nome naturale (richiede Gemini CLI)
+   python convert_akomantoso.py -s "legge stanca" output.md
+   python convert_akomantoso.py --search "decreto dignità" > output.md
+
+   # Mantenere XML scaricato da URL
+   python convert_akomantoso.py "URL" output.md --keep-xml
+   python convert_akomantoso.py "URL" --keep-xml > output.md
+         """
     )
 
     # Version flag
@@ -904,20 +974,31 @@ def main():
 
     # Argomenti opzionali (per maggiore flessibilità)
     parser.add_argument('-i', '--input', dest='input_named',
-                       help='File XML locale o URL normattiva.it')
+                        help='File XML locale o URL normattiva.it')
     parser.add_argument('-o', '--output', dest='output_named',
-                       help='File Markdown di output (default: stdout)')
+                        help='File Markdown di output (default: stdout)')
+    parser.add_argument('-s', '--search', dest='search_query',
+                        help='Cerca documento legale per nome naturale (es. "legge stanca")')
     parser.add_argument('--keep-xml', action='store_true',
-                       help='Mantieni file XML temporaneo dopo conversione da URL')
+                        help='Mantieni file XML temporaneo dopo conversione da URL')
     parser.add_argument('-q', '--quiet', action='store_true',
-                       help='Modalità silenziosa: mostra solo errori')
+                        help='Modalità silenziosa: mostra solo errori')
 
     args = parser.parse_args()
 
     # Determina input e output
     input_source = args.input or args.input_named
+    search_query = args.search_query
     output_file = args.output or args.output_named
 
+    # Valida che almeno input o search sia specificato
+    if not input_source and not search_query:
+        parser.error("Input richiesto.\n"
+                    "Uso: python convert_akomantoso.py <input> [output.md]\n"
+                    "oppure: python convert_akomantoso.py -i <input> [-o output.md]\n"
+                    "oppure: python convert_akomantoso.py -s <query> [-o output.md]\n"
+                    "Se output omesso, markdown va a stdout")
+
     # Sanitize output path if provided
     if output_file:
         try:
@@ -926,12 +1007,18 @@ def main():
             print(f"❌ Errore nel path di output: {e}", file=sys.stderr)
             sys.exit(1)
 
-    # Valida che input sia specificato
-    if not input_source:
-        parser.error("Input richiesto.\n"
-                    "Uso: python convert_akomantoso.py <input> [output.md]\n"
-                    "oppure: python convert_akomantoso.py -i <input> [-o output.md]\n"
-                    "Se output omesso, markdown va a stdout")
+    # Gestisci ricerca naturale se specificata
+    if search_query:
+        if not args.quiet:
+            print(f"🔍 Ricerca documento: {search_query}", file=sys.stderr)
+
+        input_source = lookup_normattiva_url(search_query)
+        if not input_source:
+            print("❌ Impossibile trovare URL per la ricerca specificata", file=sys.stderr)
+            sys.exit(1)
+
+        if not args.quiet:
+            print(f"✅ URL trovato: {input_source}", file=sys.stderr)
 
     # Auto-detect: URL o file locale?
     if is_normattiva_url(input_source):

openspec/changes/archive/2025-11-02-add-natural-language-url-lookup/design.md

@@ -0,0 +1,28 @@
+## Context
+The current tool requires users to provide exact normattiva.it URLs. This proposal adds natural language input capability using Gemini CLI to interpret user strings and find corresponding URLs.
+
+## Goals / Non-Goals
+- Goals: Enable natural language search for legal documents, maintain existing URL/XML input methods
+- Non-Goals: Replace existing input methods, add general web search (only normattiva.it), store search history
+
+## Decisions
+- Use Gemini CLI headless with -p flag for AI-powered interpretation
+- Add new CLI flag for natural language input
+- Integrate URL lookup as preprocessing step before existing conversion
+- Fallback to existing behavior if URL lookup fails
+
+## Risks / Trade-offs
+- External dependency on Gemini CLI (user must install separately)
+- Potential API rate limits or costs for Gemini usage
+- Accuracy of AI interpretation may vary
+- Increased complexity in CLI argument handling
+
+## Migration Plan
+- Additive feature, no migration needed
+- Existing scripts continue to work unchanged
+- New functionality available via new flag
+
+## Open Questions
+- How to handle multiple URL matches from Gemini?
+- What error messages for failed lookups?
+- Should we cache successful lookups?

openspec/changes/archive/2025-11-02-add-natural-language-url-lookup/proposal.md

@@ -0,0 +1,14 @@
+## Why
+Users currently need to know exact normattiva.it URLs to convert legal documents. This creates a barrier for users who know the law by name (e.g., "legge stanca") but not its URL. Adding natural language search would make the tool more accessible and user-friendly.
+
+## What Changes
+- Add new CLI option to accept natural language strings instead of URLs
+- Integrate Gemini CLI headless to interpret strings and search normattiva.it
+- Automatically resolve found URLs and pass to existing conversion logic
+- **BREAKING**: No breaking changes, this is an additive feature
+
+## Impact
+- Affected specs: New url-lookup capability
+- Affected code: Main CLI entry point, new URL lookup module
+- New dependency: Gemini CLI (external tool)
+- User experience: Simplified input for legal document conversion