Agentic Jackal: Live Execution and Semantic Value Grounding for Text-to-JQL

Il paper introduce "Agentic Jackal", un agente basato su LLM potenziato da strumenti di esecuzione live e recupero semantico, e presenta il primo benchmark su larga scala per la traduzione da linguaggio naturale a JQL, dimostrando come questo approccio superi significativamente i modelli tradizionali risolvendo ambiguità e valori categorici specifici dell'istanza Jira.

L'essenziale

Immagina di avere un assistente personale molto intelligente, capace di capire qualsiasi cosa tu gli dica in linguaggio naturale. Tuttavia, c'è un problema: questo assistente deve parlare con un archivio gigantesco e complicato (chiamato Jira, usato dalle aziende per gestire i progetti) che parla una lingua molto tecnica e piena di regole specifiche.

Ecco di cosa parla questo articolo, spiegato come se fosse una storia avventurosa.

1. Il Problema: L'Assistente che "Indovina"

Immagina che tu chieda al tuo assistente: "Mostrami tutti i compiti relativi alla versione 6.5 del software."

Il tuo assistente (un'intelligenza artificiale avanzata) prova a tradurre questa richiesta in una query per l'archivio. Ma qui nasce il guaio:

• Non sa cosa esiste davvero: L'archivio potrebbe avere una versione chiamata "6.5", ma potrebbe anche chiamarla "6.5.0 Beta" o "6.5.1". L'assistente, non avendo accesso diretto all'archivio in tempo reale, indovina. Spesso indovina male e la ricerca torna vuota.
• Non può controllare il risultato: Se l'assistente sbaglia, non se ne accorge. Scrive la query, la invia e si ferma lì, senza sapere se ha trovato i documenti giusti o se ha appena cercato in un cassetto vuoto.

È come se un cuoco provasse a cucinare un piatto senza mai assaggiarlo e senza sapere se gli ingredienti che ha in dispensa sono davvero quelli che servono.

2. La Soluzione: "Agentic Jackal" (Il Detective con gli Occhiali Magici)

Gli autori del paper hanno creato un nuovo sistema chiamato Agentic Jackal. Invece di essere un semplice traduttore, Jackal è un investigatore attivo.

Jackal ha due superpoteri:

1. Il Potere di Eseguire (Jira Search): Non si limita a scrivere la richiesta. La invia all'archivio, guarda cosa succede e dice: "Ehi, ho trovato 0 risultati! Forse ho sbagliato la versione. Riproviamo!". Se trova errori, li corregge subito. È come un detective che controlla le prove sul campo invece di sedersi alla scrivania a immaginare.
2. Il Potere di Trovare i Nomi Esatti (JiraAnchor): Questo è il vero trucco. Quando tu dici "versione 6.5", Jackal usa un cercatore semantico (JiraAnchor) che va nell'archivio e chiede: "Ehi, quali versioni contengono '6.5'?". L'archivio risponde con la lista esatta: "6.5.0", "6.5.0 Beta", "6.5.1". Jackal sceglie quella giusta e la usa nella ricerca. È come avere un dizionario che ti dice esattamente come sono scritti i nomi delle persone nella tua lista telefonica, evitando errori di ortografia.

3. L'Esperimento: Chi vince?

Gli autori hanno messo alla prova 9 diversi "cervelli" di intelligenza artificiale (i modelli più avanzati al mondo) su un banco di prova reale con 1.000 richieste.

• Il vecchio metodo (Senza Jackal): I modelli hanno avuto successo solo nel 43% dei casi quando la richiesta era un po' ambigua o usava parole diverse. Erano come studenti che studiano a memoria ma vanno in crisi se la domanda è formulata in modo diverso.
• Il nuovo metodo (Con Jackal): Quando hanno dato agli stessi modelli gli strumenti di Jackal (il potere di controllare e di cercare i nomi esatti), il successo è salito notevolmente. Alcuni modelli sono passati dal 60% al 71% di precisione.

La metafora:
Immagina di dover trovare un libro in una biblioteca di 200.000 volumi.

• Senza Jackal: L'assistente legge il titolo che gli dai, lo scrive su un foglio e lo passa al bibliotecario. Se il titolo è leggermente sbagliato (es. "Harry Potter" invece di "Harry Potter e la Pietra Filosofale"), il bibliotecario dice "Non c'è" e l'assistente non sa che c'è un errore.
• Con Jackal: L'assistente scrive il titolo, lo passa al bibliotecario, vede che non c'è risultato, torna indietro, usa il suo "cercatore magico" per vedere come sono scritti realmente i titoli nella biblioteca, corregge il foglio e riprova. Alla fine, trova il libro.

4. Cosa hanno scoperto? (Il punto debole)

Nonostante i superpoteri, Jackal non è perfetto. Hanno scoperto che il problema principale non è più "trovare il nome giusto" (grazie a JiraAnchor), ma capire cosa vuoi davvero.

Se dici: "Cerca i bug":

• L'assistente potrebbe cercare i "bug" come tipo di problema (esatto).
• Oppure potrebbe cercare la parola "bug" scritta dentro la descrizione del compito (sbagliato, ma comprensibile).

Anche con gli strumenti migliori, l'ambiguità del linguaggio umano rimane una sfida. È come se due persone parlassero la stessa lingua ma avessero convenzioni diverse su cosa significhi una parola.

5. Il Prezzo da Pagare

C'è un piccolo rovescio della medaglia. Usare Jackal è più lento e costa di più (in termini di energia di calcolo).

• Il vecchio metodo era veloce come un lampo (pochi secondi).
• Il metodo Jackal è come una ricerca accurata: ci mette un po' di più (circa 30 secondi) perché deve fare controlli e ricerche aggiuntive.

Conclusione

In sintesi, questo paper ci dice che per far funzionare bene l'intelligenza artificiale in ambienti aziendali complessi, non basta farle "indovinare" la risposta. Dobbiamo darle strumenti per verificare le sue ipotesi e strumenti per cercare i dati reali in tempo reale.

Agentic Jackal è il primo passo per trasformare l'IA da un "saggio che parla a caso" a un "collega esperto che controlla sempre i fatti prima di rispondere".

Sommario tecnico

1. Il Problema: Traduzione da Linguaggio Naturale a JQL

La traduzione del linguaggio naturale in Jira Query Language (JQL) presenta sfide uniche rispetto ad altri domini di query (come SQL), rendendo i modelli linguistici (LLM) standard poco efficaci in contesti reali:

• Ambiguità e Riferimenti Specifici: Le query JQL richiedono la risoluzione di riferimenti ambigui a campi, valori categorici specifici dell'istanza (es. nomi di componenti, versioni di fix) e predicati booleani complessi.
• Limiti degli LLM "Single-Pass": I modelli LLM tradizionali che generano query in un singolo passaggio non possono scoprire quali valori categorici esistono realmente in una specifica istanza di Jira. Di conseguenza, tendono a generare valori plausibili ma inesistenti (es. "versione 6.5" quando l'istanza contiene solo "6.5.0 Beta1"), portando a risultati vuoti o errori silenziosi.
• Mancanza di Feedback: Senza un ciclo di feedback live, i modelli non possono verificare o raffinare le query generate contro una fonte di dati reale.
• Assenza di Benchmark: Non esisteva un benchmark open-source basato sull'esecuzione per valutare la traduzione da testo a JQL.

2. Metodologia: Agentic Jackal e JiraAnchor

Gli autori introducono Agentic Jackal, un agente multi-step potenziato da strumenti, progettato per colmare i divari strutturali sopra menzionati. L'architettura si basa su due componenti principali:

A. Agente Ciclico (Agentic Loop)

• Architettura: Un agente basato sul server Jira MCP (Model Context Protocol) che genera, esegue e raffina iterativamente le query JQL.
• Feedback Live: L'agente esegue la query su un'istanza Jira reale e osserva tre segnali distinti per correggere la query:
  1. Set di risultati non vuoto: Conferma la validità della query.
  2. Risultato zero: Indica filtri troppo restrittivi o valori errati.
  3. Messaggio di errore: Identifica violazioni di sintassi o schema.
• Iterazione: L'agente utilizza questi segnali per riscrivere la query in modo mirato invece di fare riscritture speculative, fino a quando non ottiene un output verificato.

B. JiraAnchor (Ricerca Semantica dei Valori)

• Funzione: Uno strumento di recupero semantico progettato per risolvere le menzioni di valori categorici nel linguaggio naturale mappandoli sui valori effettivi archiviati nell'istanza Jira.
• Meccanismo:
  1. Recupera tutti i valori unici per un campo specifico dall'istanza Jira tramite API REST.
  2. Utilizza la ricerca per similarità basata su embedding (e matching regex/approssimato) per confrontare la richiesta dell'utente con i valori reali.
  3. Restituisce i migliori match (Top-K) per essere utilizzati direttamente nella query JQL.
• Vantaggio: Elimina l'ipotesi del modello sui valori, fornendo dati concreti e specifici dell'istanza.

3. Contributi Chiave

1. Agentic Jackal: Il primo agente open-source basato su strumenti per la generazione di query JQL in ambito enterprise, che stabilisce un nuovo baseline per l'esecuzione iterativa e la correzione degli errori.
2. JiraAnchor: Un nuovo strumento di recupero semantico che risolve il problema della disambiguazione dei valori specifici dell'istanza, un fallimento critico nei sistemi precedenti.
3. Jackal Benchmark: Un benchmark su larga scala basato sull'esecuzione, contenente 100.000 coppie NL-JQL validate su un'istanza reale con oltre 200.000 issue. Gli autori hanno utilizzato un sottoinsieme stratificato di 1.000 query (Jackal-1K) per le valutazioni.
4. Tassonomia degli Errori: Un'analisi dettagliata che classifica i fallimenti, distinguendo tra errori di risoluzione dei valori e ambiguità semantiche intrinseche.

4. Risultati Sperimentali

Gli esperimenti sono stati condotti su 9 modelli LLM all'avanguardia (tra cui GPT-5, Claude Opus, Gemini 3, Pixtral) su due set di dati:

Esperimento 1: Agente vs. Approccio Naif (Single-Pass)

• Accuratezza Complessiva: L'approccio agentic ha migliorato l'accuratezza di esecuzione media da 62.5% a 64.4% (+2.0%).
• Impatto sulle Query Difficili: I miglioramenti sono stati concentrati sulle varianti linguisticamente più ambigue. Per le query "Short NL" (frasi brevi e concise), l'accuratezza è passata dal 43.4% al 47.3% (+3.9% assoluto, +9.0% relativo).
• Conclusione: L'iterazione e il feedback live sono cruciali quando il contesto linguistico è scarso.

Esperimento 2: Ablazione di JiraAnchor

• Impatto sulla Risoluzione dei Valori: L'uso di JiraAnchor ha portato a un miglioramento drastico nell'accuratezza delle query sensibili ai valori categorici, passando dal 48.7% al 71.7% (+23.0%).
• Caso dei Componenti: Per il campo "Component", l'accuratezza è esplosa dal 16.9% al 66.2% (+49.3%), dimostrando che senza accesso ai valori reali, i modelli falliscono quasi completamente su nomi di componenti non standard.
• Costi Operativi: L'approccio agentic aumenta la latenza (da ~5s a ~32s) e il consumo di token (da ~2K a ~27K) a causa delle iterazioni multiple, ma questo è considerato accettabile per scenari dove la precisione è prioritaria.

5. Analisi degli Errori e Limiti

L'analisi manuale dei fallimenti ha rivelato una distinzione fondamentale:

• Errori Dominanti: Il 58% dei fallimenti su query "Short NL" e il 68% su query "Semantically Similar" sono dovuti ad ambiguità semantiche intrinseche (es. confusione tra tipo di issue e ricerca testuale, selezione del campo testo summary vs description, confusione tra versioni fix e affected), non alla risoluzione dei valori.
• Limiti degli Strumenti: Gli strumenti (JiraSearch e JiraAnchor) risolvono efficacemente i problemi di sintassi e valori, ma non possono risolvere ambiguità che richiedono chiarimenti dall'utente o un contesto più ricco.
• Regressioni: In alcuni casi specifici, JiraAnchor ha causato regressioni (es. su versioni specifiche) a causa di un "over-matching" o confusione di campi, suggerendo la necessità di un'invocazione selettiva basata sulla fiducia del modello.

6. Significato e Implicazioni

Il lavoro dimostra che per le applicazioni enterprise complesse come Jira, l'approccio "single-shot" degli LLM è insufficiente.

• Necessità di Agentic Workflows: L'integrazione di cicli di esecuzione live e strumenti di recupero dati (RAG dinamico) è essenziale per raggiungere un'accuratezza utilizzabile in produzione.
• Risoluzione dei Valori: La capacità di interrogare l'istanza di destinazione per ottenere i valori esatti è un prerequisito per la generazione di query affidabili.
• Futuro della Ricerca: Le sfide future non risiedono tanto nella generazione di sintassi, quanto nella disambiguazione dell'intento dell'utente e nella gestione delle convenzioni specifiche del dominio che i modelli non possono inferire autonomamente.

In sintesi, Agentic Jackal stabilisce un nuovo standard per l'interazione testo-query in ambienti enterprise, dimostrando che l'agenticità, combinata con l'ancoraggio semantico ai dati reali, è la chiave per superare i limiti degli attuali modelli linguistici.