Pipeline de alto nível

O LocalLens recebe uma pasta e uma pergunta e devolve uma resposta com citações. Tudo entre esses dois endpoints é um pipeline pequeno e fixo.

Pipeline de indexação

A indexação roda uma vez por brain, quando você cria.

Os passos no código:

1. discoverTextDocuments(rootPath) (src/files.ts) percorre a pasta, filtra tudo que não é um arquivo de texto seguro, e retorna LocalDocument[].
2. chunkDocuments(documents, { brainId }) (src/rag.ts) chama ragChunk para quebrar cada documento em chunks de ~220 tokens com 40 tokens de overlap, depois retorna TextChunk[].
3. QvacGateway.ingestChunks(workspace, chunks) (src/qvac.ts) embeda cada chunk com GTE_LARGE_FP16 e escreve eles num workspace QVAC nomeado.
4. LocalLensStore.saveBrain e saveChunks (src/store.ts) persistem o brain e seus chunks em .locallens/store.json.

Os três primeiros passos operam na pasta de entrada. O quarto guarda um registro do brain, então da próxima vez que você abrir o app, dá para fazer perguntas sem reindexar.

Pipeline de pergunta

Toda volta de chat percorre o mesmo caminho de quatro passos.

No código:

1. QvacGateway.search(workspace, question, 5) (src/qvac.ts) embeda a pergunta e roda ragSearch, retornando os top 5 SearchHit[].
2. buildGroundedHistory(question, hits) (src/rag.ts) produz um ChatMessage[] de duas mensagens contendo as regras de sistema e os trechos numerados.
3. QvacGateway.answer(history) (src/qvac.ts) chama o completion() do QVAC com stream: true e dá yield em cada contentDelta como um AsyncGenerator<string>.
4. LocalLensApp.askBrain (src/locallens.ts) acumula o stream e retorna { answer, citations }.

Onde cada passo mora

O que o pipeline não é

• Sem reingestão no caminho de pergunta. Perguntar nunca toca o sistema de arquivos ou o JSON store. Só lê do workspace QVAC.
• Sem segunda chamada de modelo por pergunta. Uma round-trip pro modelo de chat. Uma chamada de embedding para o passo de busca. Só.
• Sem estado conversacional. Cada pergunta é uma rodada de recuperação independente. O histórico de chat é reconstruído do zero toda vez, embasado no que a busca retornou para esta pergunta.

Essa última propriedade mantém respostas de follow-up embasadas. Se você quer diálogo multi-turno, construa acima do buildGroundedHistory, não dentro dele. A página RAG vs LLM explica por quê.

Próximo

• Fluxo de request — uma única pergunta, traçada de ponta a ponta.
• RAG vs LLM — o que cada lado faz e por que eles ficam separados.
• Por que QVAC — a superfície do SDK em uso, e o que estaríamos escrevendo sem ele.
• Layout do código — onde o código mora.