GBR: ADR-0019 Tratamento Robusto de Tool Calling e Resiliência contra JSONs Malformados

• *Status:* Proposto
• *Data:* 2026-06-09

*Contexto:*

Na arquitetura do gleambr_ai, a comunicação com LLMs via llm_streamer.gleam se baseia na recepção de payloads de streaming em formato OpenAI/Gemini. O orquestrador detecta intenções de ferramentas (como Read, Write e Execute) através da extração de payloads JSON embutidos nos pensamentos do modelo. No entanto, os LLMs frequentemente cometem erros de sintaxe (ex: faltar chaves de fechamento }, escapar aspas incorretamente em strings multilinha ou misturar textos explicativos com o JSON). Se o parser de JSON for frágil, ele lançará exceções de compilação ou decodificação, fazendo o agente falhar catastróficamente ou entrar em loops infinitos de autocorreção ("tentar de novo" gerando o mesmo erro).

*Decisão:*

Implementaremos uma camada robusta de *Pré-processamento e Parsing Tolerante a Falhas* para Tool Calling no orquestrador:

1. *Extração Inteligente de Blocos JSON:* A função find_json_block será enriquecida para atuar de forma gulosa. Ela localizará o primeiro caractere { e o último } do buffer do LLM, ignorando qualquer texto explicativo prévio ou posterior gerado pelo modelo.
2. *Sanitização de Quebras de Linha e Aspas:* Antes da decodificação com gbr_json / gleam_json, o buffer será normalizado substituindo quebras de linha cruas dentro de literais de string por escapes \n e corrigindo erros clássicos de aspas duplas aninhadas.
3. *Decodificadores Resilientes (Decoders):* Mapearemos falhas de decodificação para variantes específicas de erro (ex: aci.ActionError(reason)), que são devolvidas síncronamente como observações do sistema para o LLM. A IA receberá o erro sintático de forma limpa como feedback, permitindo que ela reescreva a chamada no turno seguinte sem quebrar o fluxo OTP.
4. *Tratamento de Chamadas Paralelas:* O parser suportará múltiplos blocos JSON na mesma mensagem para execução paralela de ferramentas, prevenindo bloqueios sequenciais desnecessários.

*Consequências:*

• *Positivas:* - Imunidade a travamentos (Silent Hangs) causados por falhas de inferência dos LLMs. - O agente ganha a capacidade de auto-correção imediata, pois recebe os erros sintáticos formatados como observações de ferramenta.
• *Negativas:* - Ligeiro aumento no consumo de CPU local para rodar buscas gulosas de caracteres e normalizações de string.