[ADR-0008] Arquitetura de RAG Híbrido (Síntese de AST + Context Forcing)

• *Status:* Proposto = *Data:* 16 de Maio, 2026

*Contexto:*

Modelos de Linguagem (LLMs) carecem de treinamento profundo na linguagem Gleam, resultando em alucinações sintáticas. A indexação de código-fonte bruto (usando recortes textuais genéricos) cria "lixo semântico", pois modelos de Embedding (como o all-MiniLM) são treinados em linguagem natural, não em concatenações de tokens como import_gleam_otp_actor. Injetar código irrelevante no prompt do LLM exaure a janela de contexto e aumenta custos.

*Decisão:*

A Fase 2 (gbr_semantic) adotará uma arquitetura de "RAG Híbrido com Tradução Semântica", operando em três etapas:

1. *Extração Cirúrgica (AST):* A biblioteca glance dividirá os arquivos .gleam estritamente em funções, tipos e importações.
2. *Tradução Semântica (A Ponte):* Antes da vetorização, a assinatura de cada nó da AST será convertida programaticamente em uma sentença em linguagem natural (Inglês). Exemplo: Uma função start_child(factory) será mapeada para a string "Function start_child: Initializes a new actor process using a given factory."
3. *Context Forcing (MCP):* O vetor será gerado a partir da frase em inglês, mas o DuckDB armazenará o código Gleam real nos metadados. O gleambr_ai será instruído (via System Prompt) a nunca escrever Gleam de memória, sendo forçado a chamar a ferramenta MCP search_semantic_codebase, que retornará os blocos de código exatos da AST para o contexto da conversa.

*Consequências:*

• *Positivas:* Redução drástica de alucinações; o espaço vetorial fica matematicamente denso e preciso (buscas em inglês acham o código Gleam correto); uso eficiente de tokens (apenas o código necessário é injetado).
• *Negativas:* Exige o mapeamento de templates de tradução para cada nó da AST do Gleam no momento da indexação.

Melhoria v2

• *Decisão:* A indexação de código (AST via glance) será enriquecida usando o *Gleam LSP* em background (para inferência de tipos e definições de hover). A "Tradução Semântica" extrairá a documentação real (///) e usará LLMs menores em fallback para gerar resumos de funções não documentadas. A injeção na IA será feita via *Context Forcing* (a IA é proibida de codificar sem consultar o motor semântico via MCP, poupando tokens de contexto massivo).