Riassunto Tecnico: SHERLOC – Localizzazione Diagnostica Strutturata per Agenti di Riparazione del Codice

1. Definizione del Problema

La riparazione del codice a livello di repository si affida sempre più a agenti basati su Large Language Model (LLM) che intercalano il ragionamento con chiamate strutturate a strumenti per risolvere problemi su GitHub. Tuttavia, un'analisi sistematica degli agenti esistenti rivela un'inefficienza critica: gli agenti spendono quasi metà del loro budget di interazione (una media di 18,5 turni e oltre 320k token per istanza) esclusivamente sulla localizzazione dei guasti prima di tentare una patch del codice.

Gli attuali metodi di localizzazione soffrono di due limitazioni primarie:

1. Output Incompleto: La maggior parte degli approcci recupera i file o le funzioni difettose, ma non fornisce il contesto diagnostico (causa radice, direzione della soluzione) necessario affinché gli agenti di riparazione a valle possano agire efficacemente.
2. Disallineamento della Valutazione: I framework di localizzazione dedicati sono spesso valutati come sistemi di recupero di file piuttosto che come strumenti diagnostici azionabili, producendo localizzazioni prive del ragionamento necessario per la riparazione.

Ciò crea un collo di bottiglia nelle prestazioni dove ingenti risorse computazionali vengono consumate nella ricerca anziché nella costruzione, e le localizzazioni risultanti spesso mancano della specificità necessaria per guidare la riparazione.

2. Metodologia: SHERLOC

Gli autori introducono SHERLOC (Structured Hypothesis-driven Exploration and Reasoning for Localization), un framework senza necessità di fine-tuning progettato per accoppiare un LLM di ragionamento con una suite compatta di strumenti di repository e meccanismi di auto-recupero.

Architettura Core

SHERLOC opera come un singolo LLM di ragionamento che interagisce con un esecutore di strumenti deterministico attraverso un ciclo iterativo limitato (massimo 20 turni). Non richiede fine-tuning, apprendimento per rinforzo o orchestrazione multi-agente.

• Suite di Strumenti: Il framework utilizza quattro strumenti adatti agli LLM:
  • View File: Ispeziona il contenuto dei file con fuzzy path matching e intervalli di righe opzionali.
  • Codebase Search: Esegue ricerche letterali in tutto il repository con contesto.
    il Repository Tree: Visualizza la gerarchia dei file filtrata per recuperare il contesto globale.
  • Connected Tree: Riassume le relazioni di importazione (dirette e inverse) per navigare nelle dipendenze.
• Interazione Iterativa: Il modello alterna tra ragionamento e selezione dello strumento. Accumula osservazioni (snippet, percorsi, riassunti di dipendenze) nella cronologia del contesto per formare uno stato ipotetico.
• Meccanismi di Auto-Recupero: Per stabilizzare l'uso prolungato degli strumenti, SHERLOC impiega strategie di recupero leggere:
  • Troncamento del contesto (preservando il prompt iniziale e i turni recenti).
  • Rilevamento dei cicli (avviso contro chiamate ripetitive improduttive).
  • Recupero implicito delle chiamate agli strumenti (parsing di richieste malformate ma univoche).
  • Sintesi dell'ultimo turno (forzare una conclusione quando il budget dei passaggi è esaurito).

Output Diagnostico Strutturato

A differenza dei metodi precedenti che restituiscono solo i percorsi dei file, SHERLOC emette un risultato diagnostico strutturato per ogni posizione prevista. Questo risultato include cinque campi:

1. Spiegazione della Localizzazione: Perché il file è sospettato.
2. Causa Radice: Il meccanismo sottostante del bug.
3. Idea di Soluzione: Guida azionabile per la correzione (senza codice).
4. Dipendenze: Impatto su altri moduli.
5. Impatto sui Test: Modifiche ai test suggerite.

Metriche di Valutazione

Il documento propone metriche a livello di chunk agnostiche rispetto alla struttura (recall di copertura, precisione e compattezza media) invece di intervalli di numero di riga, riconoscendo che le patch non sempre si allineano con unità sintattiche come funzioni o classi.

3. Risultati Chiave

Prestazioni di Localizzazione

SHERLOC raggiunge lo stato dell'arte (SOTA) nella localizzazione a livello di file attraverso diverse scale di modelli senza training specifico per il task:

• SWE-Bench Lite: 84,33% di accuratezza@1 (usando Qwen3-235B).
• SWE-Bench Verified: 81,27% di recall@1 (usando Qwen3-235B).
• Efficienza di Scala: Alla scala corrispondente di circa 30B di parametri, SHERLOC (Qwen3-30B) raggiunge il 75,07% di recall@1, superando i baseline sottoposti a fine-tuning (es. ToolTrain-32B) e i metodi non sottoposti a fine-tuning con margini significativi (+7,0 a +18,3 pp).
• Trasferibilità Cross-Family: Il metodo si trasferisce efficacemente tra famiglie di modelli (es. DeepSeek-V3 raggiunge il 79,53% di recall@1).

Trasferimento a Valle sulla Riparazione del Codice

L'iniezione delle localizzazioni e dei risultati diagnostici di SHERLOC in agenti di riparazione esistenti (OpenHands e SWE-Agent) produce miglioramenti significativi:

• Tasso di Risoluzione: Un aumento medio di +5,95 punti percentuali nel tasso di risoluzione su cinque backbone di riparazione.
• Efficienza: Una riduzione del 36,7% dei token di localizzazione e una riduzione del 23,1% dei token totali.
• Mediazione della Qualità: Il beneficio del trasferimento dipende dalla qualità. I modelli più piccoli beneficiano di "Tutti i risultati di SHERLOC", mentre i modelli più grandi e capaci beneficiano maggiormente dei Risultati filtrati per qualità (quelli valutati ≥4.0 da un giudice LLM). I risultati non filtrati possono degradare le prestazioni sugli agenti forti a causa del trasferimento negativo da diagnosi a bassa confidenza.

Studi di Ablazione e Validità

• Importanza dei Componenti: La rimozione dello strumento View File o del prompt dell'ultimo turno causa i cali di prestazione più grandi, confermando che l'ispezione del codice e la pressione alla sintesi sono critiche.
• Conoscenza Implicita vs Ragionamento: I controlli che mascherano i percorsi dei file nel testo del problema mostrano che, sebbene gli LLM possiedano una familiarità implicita con i repository popolari (es. scikit-learn, requests), l'esplorazione attiva assistita da strumenti contribuisce a una parte significativa del divario di prestazione (circa 22 pp di miglioramento rispetto ai baseline basati solo sul testo).
• Necessità del Ragionamento: I modelli in modalità "Thinking" superano significativamente i modelli in modalità "Instruct", che spesso falliscono nel sostenere il protocollo multi-turno.

4. Significato e Rivendicazioni

Il documento sostiene che l'output diagnostico strutturato, e non la mera localizzazione del file, sia l'unità operativa utile per la localizzazione. Un percorso di file corretto con una diagnosi fuorviante può trarre in inganno gli agenti a valle, mentre un risultato strutturato con analisi della causa radice e guida alla soluzione consente una riparazione efficace.

Le rivendicazioni chiave includono:

1. SOTA Senza Training: Un singolo LLM di ragionamento con strumenti compatti e auto-recupero può eguagliare o superare i sistemi di localizzazione specializzati sottoposti a fine-tuning.
2. Contesto Azionabile: L'inclusione di campi diagnostici strutturati (causa radice, idea di soluzione) è essenziale per trasferire il successo della localizzazione alle attività di riparazione a valle.
3. Efficienza: SHERLOC riduce drasticamente il costo in token della fase di localizzazione, liberando budget per la reale riparazione del codice.
4. Filtraggio della Qualità: Un filtro di qualità è necessario per prevenire il trasferimento negativo; i risultati di alta qualità guidano il successo, mentre quelli di bassa qualità possono essere dannosi.

Gli autori concludono che la localizzazione dovrebbe essere valutata in base alla azionabilità diagnostica piuttosto che solo sull'accuratezza del recupero del file. Notano che, sebbene i loro risultati siano solidi, sono in parte confusi dalla familiarità del pre-training degli LLM con i repository pubblici, e il lavoro futuro richiede distribuzioni di repository non presenti nel training per una valutazione pulita. Il framework è agnostico rispetto al linguaggio nel design, sebbene gli strumenti attuali si affidino a parser specifici per il linguaggio per gli alberi di importazione.