LlamaIndex ‘legal-kb’: Agentic Retrieval index v2 con gli strumenti retrieve, find, read e grep

LlamaIndex ha pubblicato legal-kb, un’applicazione open source disponibile su GitHub. L’app è descritta come una banca dati per documenti legali alimentata da LlamaIndex Index v2 (la LlamaParse Platform). Il progetto illustra un modello chiamato Retrieval Harness per il recupero autonomo.

Un'alternativa al recupero singolo

L’approccio differisce dal recupero ad un colpo singolo. Invece di un'unico controllo di similitudine al vettore per una query, un agente è fornito con strumenti stile sistema di file. L’agente può quindi navigare in una grande banca dati evolutiva per risolvere compiti.

Gli strumenti rispecchiano le operazioni che gli ingegneri già conoscono: ricerca semantica e ricerca per parole chiave, grepp regex, ricerca file e lettura.

Che cosa è legal-kb?

legal-kb è un'app web funzionante con il framework TanStack Start, non una libreria. Si effettua il login, si crea un progetto, si caricano i file e si parla con un agente. Ogni progetto è specchiato come un indice LlamaCloud gestito (Index v2). I file caricati vengono analizzati e indicizzati automaticamente in background. L'agente del chatbot ricerca quell'indice durante il processo di conversazione.

Il meccanismo di estrazione

Il Retrieval Harness fornisce un insieme di strumenti al sistema. Gli strumenti sono progettati per essere vicini agli strumenti di sistema: un agente può elencare file, leggere un file, effettuare una ricerca o eseguire una ricerca ibrida. Poiché gli strumenti sono generici, è possibile integrarli facilmente in propri agenti autonomi.

Gli strumenti principali dell’agente

L’agente src/lib/agent.ts dispone di quattro strumenti, ognuno collegato a un API di ricerca di Index v2. Li elenchiamo qui:

• Retrieve: cerca semanticamente, permette il riranking, restituisce frammenti e citazioni
• FindFiles: cerca file per nome esatto o con substring
• ReadFile: legge il contenuto raw di un file, con finestre di offset e lunghezza
• GrepFile: cerca un pattern in un file, restituisce posizioni esatte

Funzionalità interne

Gli upload rispettano una pipeline ben definita in src/lib/files.ts. I byte vengono inviati alla sorgente LlamaCloud del progetto. Vengono scritti righe in PostgreSQL usando Prisma (relative a File e ProjectFile). Viene attivato il sincrono di un indice ma non aspettato. L’interfaccia utente interroga continuamente lo stato fino a quando non è pronto.

Il versioning è riferito alla coppia (progetto, nome file). Ricaricare nda.pdf in un solo progetto produce v1, v2, v3 in parallelo. Il layer di ricerca filtra tramite campo versione nel metadata. Questo offre controllo versionale sull’intera banca dati.

Poteri dell'agente autonomo

L'agente implementa un ToolLoopAgent dal Vercel AI SDK 6. Scegliete OpenAI o Anthropic per turno, con le proprie chiavi. L'analisi è streaming: i modelli Claude usano un'estesa considerazione; i modelli OpenAI usano un ragionamento medio.

Ecco una rappresentazione semplificata (ma fedele) degli strumenti:

import { LlamaCloud } from '@llamaindex/llama-cloud'
import { tool, ToolLoopAgent } from 'ai'
import { z } from 'zod'
import { makeCitationId } from './citations'

// One tool closure per index. Wraps Index v2 retrieval APIs.
function createLlamaParseTools(apiKey: string, projectId: string, indexId: string) {
const client = new LlamaCloud({ apiKey })

// Strumento retrieve
const retrieve = tool(...)
}

Confronto tra RAG tradizionale e il Retrieval Harness

Il harness rappresenta un modello di esecuzione diverso da RAG singolo. Qui un confronto basato sulle funzionalità:

• Flow di ricerca: unica ricerca ad un colpo vs ricerca multi passo: find → retrieve → read/grep
• Modalità di ricerca: similitudine tra vettori vs ricerca ibrida, parole chiave, regex
• Contesto: numero fikso di chunk vs l'agente legge file completi o finestre su richiesta
• Aggiornamenti: indice statico vs pipeline persistente con sincrono e versioning
• Controllo di precisione: opzioni nascoste vs topk, scorethreshold, reranktopn esposti
• Citazioni: solo ID chunk vs citazioni visibili con screenshot di pagina e riquadri

Usi principali

Il design si concentra su domini dove i sistemi autonomi navigano grandi insiemi documentari. Ad esempio, legale e fintech.

Esempi pratici

• Domanda su contratto: “Che notifica è necessaria per terminare l'MSA?” L'agente elenca file, effettua il recupero con retrieve, quindi greppa la clausola esatta.
• Analisi di due diligence: L’agente può esaminare findFiles per nome, quindi readFile per ogni candidato. Confronta clausole senza aprire ogni PDF.
• Caso di policy versionate: Poiché retrieve accetta un filtro file_version, un agente può query specifica versione, facilitando il tracciamento nel tempo.

Implementazione di riferimento

Key Takeaways da legal-kb:

• Una implementazione open-source di recupero autonomo su LlamaIndex Index v2.
• L’agente ha quattro strumenti stile file system: retrieve, findFiles, readFile e grepFile.
• Una pipeline persistente gestisce il parsing, indexing, sincronizzatori e controllo su versioni per file singoli.
• I risposte includono citazioni visuali: screenshot delle pagine con rettangoli intorno al testo citato.
• Piattaforma tecnologica: TanStack Start, AI SDK 6, Prisma, e WorkOS, chiavi per l’utente crittografate.

Consulta il repo GitHub per ulteriori dettagli.