LlamaIndex ‘legal-kb’: Agentic Retrieval over Index v2 with retrieve, find, read, and grep Tools

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 })

  const retrieve = tool({
    description: 'Run a semantic retrieval query against an index.',
    inputSchema: z.object({
      query: z.string(),
      top_k: z.number().nullable(),
      score_threshold: z.number().nullable(),
      rerank_top_n: z.number().nullable(),   // set to enable reranking
      file_name: z.string().nullable(),      // metadata filter
      file_version: z.number().nullable(),
    }),
    execute: async ({ query, top_k, score_threshold, rerank_top_n, file_name }) => {
      const custom_filters = file_name
        ? { file_name: { operator: 'eq' as const, value: file_name } }
        : undefined

      const response = await client.beta.retrieval.retrieve({
        index_id: indexId,
        project_id: projectId,
        query,
        top_k,
        score_threshold,
        rerank: rerank_top_n != null ? { enabled: true, top_n: rerank_top_n } : undefined,
        custom_filters,
      })

      // Return a model-readable list plus citations that drive the UI chips.
      const citations = response.results.map((r) => ({
        id: makeCitationId(),                    // e.g. "c7f2qa"
        fileName: r.metadata?.file_name,
        score: r.rerank_score ?? r.score ?? null,
        preview: r.content.slice(0, 500),
      }))
      const formatted = response.results
        .map((r, i) => `### Result #${i + 1}\n\n${r.content.slice(0, 600)}`)
        .join('\n\n---\n\n')
      return { formatted, citations }
    },
  })

  // findFiles / readFile / grepFile follow the same shape, backed by
  // client.beta.retrieval.find / .read / .grep
  return { retrieve /* , findFiles, readFile, grepFile */ }
}

export function buildAgent(model, apiKey: string, projectId: string, indexId: string) {
  return new ToolLoopAgent({
    model,
    tools: createLlamaParseTools(apiKey, projectId, indexId),
    instructions:
      'Always call findFiles first, ground every answer in the documents, ' +
      'and cite ids inline as `cite:`.',
  })
}

/g,’>’);}

function match(text){
var t=text.toLowerCase(),best=null,hit=0;
INTENTS.forEach(function(it){
var c=0; it.kw.forEach(function(k){ if(t.indexOf(k)>-1)c++; });
if(c>hit){hit=c;best=it;}
});
return best;
}

function litFile(fn){
root.querySelectorAll(‘.file’).forEach(function(f){
f.classList.toggle(‘lit’, f.getAttribute(‘data-fn’)===fn);
});
}

function addStep(cls,label,html,delay){
return new Promise(function(res){
setTimeout(function(){
var s=document.createElement(‘div’);s.className=”step”;
s.innerHTML=’

‘+label+’

‘+html;
feed.appendChild(s); ping(); res();
},delay);
});
}

var C1,C2;
function run(forceKey){
if(busy)return; busy=true; go.disabled=true;
if(empty)empty.style.display=’none’;
feed.innerHTML=”;
var it = forceKey ? INTENTS.filter(function(x){return x.key===forceKey;})[0] : match(input.value||”);
C1=rid(); C2=rid();

if(!it){
addStep(‘find’,’findFiles’,callHTML(‘findFiles’,{},’3 files: Mutual_NDA.pdf (v2), MSA_Acme_Vendor.pdf (v1), Employment_Agreement.pdf (v1)’),150)
.then(function(){ return addStep(‘ans’,’answer’,’

The indexed documents do not contain enough information to answer that. Try termination, confidentiality, payment terms, non-compete, liability, or governing law.

‘,700); })
.then(done); return;
}

litFile(it.file);

// 1) findFiles (always first)
addStep(‘find’,’findFiles’,callHTML(‘findFiles’,{},’3 files listed · ‘+it.file+’ (v’+it.ver+’) is a candidate’),150)
// 2) retrieve (hybrid search)
.then(function(){ return addStep(”,’retrieve’,callHTML(‘retrieve’,{query:it.query,top_k:5,rerank_top_n:3},null),820); })
.then(function(){ return addStep(”,’results’,retrieveResults(it),780); })
// 3) grep to confirm exact wording
.then(function(){ return addStep(‘grep’,’grepFile’,callHTML(‘grepFile’,{file:it.file,pattern:it.grep.slice(0,32)+’…’},’1 match confirmed on p.’+it.page),820); })
// 4) grounded answer with citations
.then(function(){ return addStep(‘ans’,’answer’,’

‘+answerHTML(it)+’

‘,780); })
.then(done);
}

function done(){ busy=false; go.disabled=false; }

function callHTML(name,args,note){
var a=Object.keys(args).map(function(k){
var v=args[k];
var val = typeof v===’number’ ? ‘‘+v+’‘ : ‘“‘+esc(String(v))+'”‘;
return ‘‘+k+’: ‘+val;
}).join(‘, ‘);
var line=”

→ tool “+name+'({ ‘+a+’ })’;
if(note) line+=’
✓ ‘+esc(note)+’‘;
line+=’

‘;
return line;
}

function retrieveResults(it){
var s2=(it.score-0.14).toFixed(3);
var h=”

‘;
return h;
}

function answerHTML(it){
var html=esc(it.answer)
.replace(‘§CITE§’,’cite:’+C1+’‘)
.replace(‘§CITE2§’,’cite:’+C2+’‘);
// stash for modal
root._cur=it;
return html;
}

// citation modal
var modal=root.querySelector(‘#modal’), shot=root.querySelector(‘#shot’),
mpv=root.querySelector(‘#mpv’), mt=root.querySelector(‘#mt’);
feed.addEventListener(‘click’,function(e){
var chip=e.target.closest(‘.citechip’); if(!chip)return;
var it=root._cur; if(!it)return;
mt.textContent=it.file+’ · page ‘+it.page+’ · v’+it.ver;
shot.innerHTML=’

‘+esc(it.chunk)+’

‘+
”;
mpv.textContent=it.chunk;
modal.classList.add(‘on’); ping();
});
root.querySelector(‘#mx’).onclick=function(){modal.classList.remove(‘on’);ping();};
modal.onclick=function(e){ if(e.target===modal){modal.classList.remove(‘on’);ping();} };

go.onclick=function(){ run(null); };
input.addEventListener(‘keydown’,function(e){ if(e.key===’Enter’)run(null); });

// auto-resize for WordPress embed
function ping(){
try{
var h=document.getElementById(‘mtp-harness’).offsetHeight+40;
parent.postMessage({type:’mtp-harness-height’,height:h},’*’);
}catch(e){}
}
window.addEventListener(‘load’,ping);
window.addEventListener(‘resize’,ping);
setTimeout(ping,300);
})();