💻 computer science

ProjAgent: Procedural Similarity Retrieval for Repository-Level Code Generation

ProjAgent è un sistema di generazione di codice a livello di repository che migliora le prestazioni recuperando le funzioni in base alla somiglianza procedurale attraverso un flusso di lavoro agentico e raffinando gli output tramite il feedback dell'analisi statica, raggiungendo un Pass@1 del 41,14% sul benchmark REPOCOD.

Autori originali: QiHong Chen, Aaron Imani, Iftekhar Ahmed

Pubblicato 2026-07-10

📖 5 min di lettura🧠 Approfondimento

CC BY 4.0

Autori originali: QiHong Chen, Aaron Imani, Iftekhar Ahmed

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina di dover scrivere un nuovo capitolo per un mastodontico romanzo giallo di 10.000 pagine. Conosci il punto della trama da raggiungere, ma non conosci i nomi dei personaggi, le regole specifiche della città o come il detective risolva solitamente i crimini. Se dovessi semplicemente tirare a indovinare, potresti inventare un personaggio che non esiste o violare le leggi della città, rovinando la storia. Questo è esattamente ciò che accade quando l'Intelligenza Artificiale cerca di scrivere codice per un grande progetto software.

Per molto tempo, gli assistenti AI hanno cercato aiuto cercando dei "simili". Se chiedevi una funzione per calcolare la temperatura, l'IA cercava altro codice che usasse la parola "temperatura" o che sembrasse simile in superficie. Il paper sostiene che questo sia come cercare una ricetta per una torta solo perché l'altra ricetta menziona anche lo "zucchero". Si perde la vera magia: come avviene effettivamente la cottura.

Gli autori, Qihong Chen, Aaron Imani e Iftekhar Ahmed, hanno costruito un nuovo sistema chiamato ProjAgent. Hanno scoperto che il codice più utile non è sempre quello che ha l'aspetto uguale; è il codice che pensa nello stesso modo.

Il "Pensiero" contro il "Parlare"

Il paper suggerisce che il codice abbia due livelli: le parole che usa (come i nomi delle variabili e i commenti) e i passi effettivi che compie per risolvere un problema (la logica).

Immagina due chef. Lo Chef A sta preparando una pizza e lo Chef B sta preparando un'insalata.

Il Vecchio Modo (Ricerca Lessicale/Semantica): Se chiedi aiuto per fare una pizza, la vecchia IA ignorerebbe lo Chef B perché sta facendo un'insalata. Cercherebbe solo altri chef della pizza.
Il Nuovo Modo (ProjAgent): ProjAgent si rende conto che entrambi gli chef devono fare la stessa cosa: tagliare gli ingredienti, controllare se sono freschi e metterli in una ciotola. Anche se uno sta facendo l'insalata e l'altro la pizza, i loro passi procedurali sono identici. ProjAgent trova lo Chef B e dice: "Ehi, guarda come lo Chef B controlla se la lattuga è fresca! Puoi usare quella stessa logica per controllare se il tuo pomodoro è fresco!"

Il paper esclude esplicitamente l'idea che la somiglianza superficiale (guardare le parole) sia sufficiente. Sostengono che fare affidamento solo sulle parole o sul semplice significato spesso fa perdere i passaggi critici del "come fare" perché progetti diversi usano nomi diversi per le stesse azioni.

Come funziona ProjAgent: L'Agente Detective

ProjAgent agisce come un detective super intelligente con uno strumento speciale. Ecco come risolve il mistero:

Scomporre il problema: Prende il nuovo codice che vuoi scrivere e lo scompone in piccoli passi logici, come "controlla se il numero è negativo" o "converti le unità".
La Ricerca del "Pensiero": Invece di leggere solo le parole, ProjAgent usa un trucco speciale per guardare i "pensieri nascosti" del modello di IA. Elimina il vocabolario ricercato e guarda solo la pura logica. Trova altro codice nel progetto che compie la stessa identica danza mentale, anche se scritto in una parte completamente diversa del codebase.
La Caccia dell'Agente: Se la prima ricerca non trova abbastanza risultati, un "agente" digitale (un piccolo robot IA) va in una caccia al tesoro attraverso i file del progetto. Legge i file, cerca le funzioni e chiede: "C'è qualcosa qui che pensa in questo modo?".
Doppio Controllo: Per assicurarsi di non essere stato ingannato, il sistema utilizza uno strumento di "analisi statica". Immaginalo come un correttore ortografico per la logica. Controlla se il codice viene eseguito senza crashare. Se l'IA commette un errore, il sistema dice: "Ops, questo non funzionerà", e chiede all'IA di riprovare. Questo ciclo avviene fino a 10 volte finché il codice non è solido.

I Risultati: Ha Funzionato?

Gli autori hanno testato ProjAgent su un benchmark chiamato REPOCOD, che contiene 980 problemi di programmazione reali provenienti da 11 diversi progetti software.

Il Punteggio: ProjAgent ha ottenuto un punteggio Pass@1 del 41,14%. Ciò significa che, al primo tentativo, ha scritto codice funzionante per circa 41 problemi ogni 100.
Il Confronto: Questo ha superato i metodi precedenti. I vecchi metodi di "ricerca densa" (dense search) ottenevano solo il 28,83%, e la "ricerca sparsa" (sparse search, basata sulle parole chiave) il 26,58%. Persino un sistema di alto livello chiamato SpecAgent ha raggiunto solo il 34,52%.
La Prova: Il paper suggerisce che il maggiore incremento sia derivato dal trovare quei passi " proceduralmente simili". Quando hanno rimosso la ricerca procedurale, il punteggio è sceso al 25,76%. Quando hanno rimosso la ricerca semantica (la parte di corrispondenza delle parole), è sceso al 32,29%. Questo prova che è necessario avere sia il "come" che il "cosa" per avere successo.

Cosa il Paper NON Rivendica

È importante sapere cosa questo paper non afferma.

Non rivendica di aver risolto tutti i problemi di programmazione. Il punteggio è del 41,14%, il che significa che fallisce ancora più della metà delle volte.
Non dice che questo funzioni per ogni linguaggio di programmazione. I test sono stati eseguiti solo su progetti Python.
Non rivendica che l' "agente" sia perfetto. Gli autori ammettono che a volte l'agente esaurisce il tempo o la memoria e non riesce a trovare il codice migliore, suggerendo che siano necessari strumenti di esplorazione migliori.

In Sintesi

Il paper suggerisce che, per scrivere buon codice per grandi progetti, l'IA deve smettere di cercare solo parole che corrispondono e iniziare a cercare modelli di pensiero. Trovando codice che risolve i problemi nello stesso modo, anche se le parole sono totalmente diverse, ProjAgent aiuta l'IA a scrivere software migliore e più affidabile. È un passo avanti, ma il viaggio verso la generazione di codice perfetto è ancora in corso.

Riassunto Tecnico: ProjAgent: Recupero della Similitudine Procedurale per la Generazione di Codice a Livello di Repository

Definizione del Problema

La generazione di codice a livello di repository richiede che i Large Language Models (LLM) implementino funzioni target navigando tra complesse dipendenze cross-file, convenzioni specifiche del progetto e utility distribuite. Gli approrenti di generazione aumentata dal recupero (RAG) esistenti per questo compito si affidano prevalentemente alla similitudine lessicale (es. BM25) o semantica (es. embedding densi).

Gli autori identificano un limite critico in questi metodi: essi spesso falliscono nel recuperare funzioni del repository che implementano una logica procedurale simile ma differiscono significamente in termini di denominazione, tipi di dati o domini di applicazione. Ad esempio, una funzione che valida le forme degli input in un modulo di cosmologia può essere proceduralmente identica a una funzione che valida gli input di temperatura in un modulo di fisica, eppure le metriche di similitudine superficiale (lessicale o semantica) non riescono a collegarle. Questo "gap procedurale" porta gli LLM ad allucinare API o a generare codice che viola le convenzioni del progetto perché i pattern logici necessari mancano nel contesto recuperato.

Metodologia: ProjAgent

Il paper propone ProjAgent, un sistema di generazione di codice a livello di repository che introduce la similitudine procedurale come un segnale di recupero esplicito, integrato all'interno di un workflow agentico e di un ciclo di feedback basato sull'analisi statica.

1. Rappresentazione della Similitudine Procedurale

Per catturare il comportamento dell'implementazione oltre il testo superficiale, ProjAgent utilizza proiezioni dello spazio di ragionamento derivate dagli stati latenti (hidden states) dell'LLM.

Decomposizione dello Spazio: Basandosi su Hu et al. [14], il sistema decompone lo spazio degli stati latenti dell'LLM in uno spazio semantico (espressione linguistica) e uno spazio di ragionamento (logica interna). Ciò avviene tramite la Decomposizione dei Valori Singolari (SVD) sullo strato di unembedding.
Proiezione: Gli stati latenti dei passi di codice vengono proiettati sullo spazio di ragionamento per isolare la logica procedurale.
Debiasing: Per affrontare il fenomeno dell'anisotropia (dove i vettori si raggruppano in una direzione comune indipendentemente dal contenuto), gli autori introducono un passaggio di debiasing basato sulla Analisi delle Componenti Principali (PCA). Questo rimuove la direzione condivisa dominante e la centratura della media, migliorando significativamente il potere discriminante della similitudine del coseno per il matching procedurale.

2. Il Workflow di Recupero Agentico

ProjAgent impiega un processo di recupero multi-stadio per costruire un contesto ricco per la funzione target:

Pre-elaborazione Offline: Il repository viene pre-elaborato per decomporre le funzioni di contesto in passi logici (es. validazione dell'input, trasformazione dello stato). Ogni passo viene validato rispetto al codice originale e proiettato nello spazio di ragionamento.
Recupero Procedurale (Agentico):
- Ricerca dei Semi (Seed Finding): La funzione target viene decomposta in passi. Un set iniziale di passi di contesto proceduralmente simili viene identificato tramite similitudine di proiezione.
- Esplorazione Agentica: Un agente LLM naviga il repository utilizzando strumenti (es. read_func, search_func) per scoprire nuove funzioni che possano contenere passi proceduralmente simili, espandendo iterativamente il set di semi.
- Espansione e Verifica dei Semi: Il sistema espande la ricerca alle funzioni non ancora elaborate utilizzando soglie di similitudine di proiezione. Un passaggio di verifica (basato su LLM) filtra i falsi positivi, in particolare per le operazioni generiche, garantendo match procedurali di alta qualità.
Recupero Semantico: Per completare la logica procedurale, il sistema recupera simboli semanticamente correlati (API, classi, costanti) utilizzando un ibrido di punteggi lessicali (BM25) e semantici (embedding densi). Ciò assicura che l'LLM abbia accesso alle entità specifiche del repository necessarie per implementare la logica recuperata.
Generazione del Codice e Feedback: L'LLM genera il codice utilizzando il contesto procedurale e semantico combinato. Un ciclo di feedback di analisi statica conservativo affina iterativamente il codice. Esso esegue controlli di sintassi basati su AST e controlli di coerenza semantica (chiamate a metodi, accesso ai campi, risoluzione delle variabili), fornendo gli errori all'LLM per la riparazione.

Contributi Chiave

La Similitudine Procedurale come Dimensione di Recupero: Il paper introduce la similitudine procedurale come un segnale di recupero distinto ed efficace, affrontando il gap in cui le funzioni condividono pattern logici ma mancano di sovrapposizione lessicale o semantica.
Proiezioni dello Spazio di Ragionamento: Gli autori sfruttano le proiezioni degli stati latenti dell'LLM per rappresentare la logica procedurale, consentendo il recupero di funzioni correlate attraverso diverse convenzioni di denominazione e domini.
Sistema ProjAgent: Un sistema completo che integra un workflow agentico per la scoperta del contesto procedurale, il recupero ibrido (procedurale + semantico) e un ciclo di feedback di analisi statica per la riparazione iterativa del codice.
Valutazione Esaustiva: Una valutazione rigorosa sul benchmark REPOCOD, inclusi studi di ablazione e analisi dei contributi dei componenti di recupero.

Risultati

Valutato sul benchmark REPOCOD (980 problemi in 11 repository) utilizzando il modello Qwen2.5-Coder-14B-Instruct:

Performance: ProjAgent ha raggiunto un Pass@1 del 41.14%, superando i baseline esistenti:
- SpecAgent (SOTA): 34.52%
- Recupero Denso: 28.83%
- Recupero Sparso: 26.58%
- Recupero Stesso File: 14.98%
Studi di Ablazione:
- Rimuovere il recupero procedurale ha causato il calo di performance più grande (41.14% $\to$ 25.76%), evidenziando il suo ruolo critico nel fornire guida all'implementazione.
- Rimuovere il recupero semantico ha anche degradato significativamente le performance (41.14% $\to$ 32.29%), confermando la necessità di simboli specifici del repository.
- Rimuovere il ciclo di feedback ha causato una diminuzione modesta (41.14% $\to$ 40.29%), attribuita alla natura conservativa dell'analisi statica.
Efficacia del Recupero: Il metodo di similitudine di proiezione si è rivelato altamente efficace nel filtrare contesti dissimilari (alta precisione nel gruppo "leftover") ma ha richiesto un design a due stadi (proiezione + verifica) per gestire i falsi positivi nel gruppo "promoted".

Significato e Rivendicazioni

Il paper sostiene che la similitudine procedurale è una dimensione di recupero efficace e precedentemente inesplorata per la generazione di codice a livello di repository. Gli autori argomentano che una generazione di codice di successo dipende non solo dal recupero di codice semanticamente rilevante, ma anche dal recupero di un contesto che condivida gli stessi processi computazionali sottostanti.

Integrando la similitudine procedurale con i convenzionali segnali lessicali e semantici, ProjAgent dimostra che gli LLM possono essere guidati nell'implementare logiche complesse anche quando il codice sorgente differisce significativamente per dominio o vocabolario. Il lavoro suggerisce una transizione verso metodi di recupero consapevoli del comportamento nell'ingegneria del software, andando oltre il semplice matching testuale superficiale per catturare l'intento funzionale del codice. Gli autori rimangono modesti riguardo alla validità esterna, notando che i risultati sono specifici per i repository Python e per il particolare modello backbone utilizzato, e che la copertura della ricerca rimane un collo di bottiglia per ulteriori miglioramenti.