GBR: ADR-0002 Padronização OpenAI, Streaming OTP e Poda de Contexto (gbr_llm)

• *Status:* Feito(2026-05-17)
• *Data:* 2026-05-13

*Contexto:*

A biblioteca gbr_llm necessita prover abstrações para a comunicação com Modelos de Linguagem de Grande Escala (LLMs) em nuvem (BYOC). APIs de IA sofrem de alta latência na geração de respostas longas e impõem limites rígidos de tokens por requisição. Além disso, o mercado de provedores é fragmentado, dificultando a manutenção de múltiplos SDKs. O uso de clientes HTTP bloqueantes (síncronos) na Erlang VM causaria inanição de recursos (Starvation) e congelaria as interfaces de usuário (CLI/Web).

*Decisão:*

A biblioteca gbr_llm adotará os seguintes princípios arquiteturais:

1. *Padrão de API Agnóstico:* Todas as integrações de nuvem implementarão estritamente o formato de requisição e resposta da *OpenAI API* (messages, role, content, tools), garantindo compatibilidade imediata com 99% dos provedores do mercado (OpenAI, Groq, vLLM, DeepSeek, etc.).
2. *Cliente HTTP Assíncrono (Gun):* A comunicação será delegada à biblioteca Erlang ninenines/gun (via bindings Gleam), garantindo suporte a HTTP/2 e não-bloqueio de threads.
3. *Streaming Nativo (SSE via Mensagens OTP):* Todas as requisições de inferência utilizarão o modo de transmissão de eventos (Streaming). O Ator de Sessão repassará chunks de texto ao consumidor através de envio de mensagens de Ator, viabilizando interfaces de "máquina de escrever".
4. *Poda de Contexto (Context Pruning):* O Ator OTP implementará uma janela deslizante limitadora. Quando a soma aproximada de caracteres/tokens do estado interno atingir um limiar de segurança (ex: 80% do limite configurado), mensagens antigas (excluindo o System Prompt) serão expurgadas antes do envio da requisição.

*Consequências:*

• *Positivas:* Experiência de usuário fluida através de Streaming de baixa latência; imunidade a erros de limite de contexto (400 Bad Request); extrema facilidade para trocar de provedores de IA sem refatoração de código; estabilidade de rede garantida pela robustez da biblioteca gun.
• *Negativas:* Adoção de dependência nativa Erlang (gun) adiciona complexidade à compilação e tipagem na fronteira do Gleam; o tratamento de Server-Sent Events fragmentados exige analisadores (parsers) de estado cuidadosos.

Reanálise dos Artefatos Finais (ADR e EARS)

Observando a máquina de estados e o código OTP conceitual, *afirmo integralmente a validade do ADR e seus respectivos EARS.*

• *A decisão de usar o Gun (ADR):* A máquina de estados comprova o porquê o gun é vital. Ele permite que o método handle_cast (o Prompt no Gleam) execute em 1 milissegundo. A espera pela OpenAI não consome CPU, apenas gera eventos assíncronos que o nosso seletor de mensagens (handle_info) processa de forma limpa e paralela.
• *O Padrão OpenAI:* Transformar o histórico no array JSON blinda o núcleo do nosso sistema. Podemos trocar a URL do Gun de api.openai.com para o IP de um LLM local no futuro, e o ator continuará funcionando sem mudar uma vírgula do fluxo de mensagens.
• *Conclusão da Análise:* Os artefatos arquiteturais estão corretos, maduros e alinhados com o estado da arte do BEAM.