ADR 0015: Especificação do BPE Tokenizer

• *Status:* Proposto
• *Data:* 4 de Junho, 2026

Contexto Para que o nosso Agente Gleam Especialista e Semântico possa interagir eficientemente com Modelos de Linguagem (LLMs), gerenciar seu contexto em RAG (Retrieval-Augmented Generation) e evitar estouro do Context Window, precisamos ser capazes de contar e prever o número exato de tokens de um texto antes de enviá-lo ao modelo.

Modelos populares (como os da OpenAI e muitos modelos abertos compatíveis com o ecossistema) utilizam *Byte Pair Encoding (BPE)*, em particular codificações como o cl100k_base usado pela série GPT-4/gpt-3.5-turbo, que é a base da biblioteca tiktoken mantida pela OpenAI.

A ausência de uma contagem preditiva de tokens em Gleam/Erlang no momento força estimativas imprecisas (ex: 1 token ≈ 4 caracteres), o que não é escalável nem seguro para a janela de contexto rigorosa do nosso OS Distribuído P2P, além de falhar criticamente com códigos (que tem densidade de tokens diferente de linguagem natural).

Decisão Criar ou adaptar uma implementação de **BPE Tokenizer baseada no tiktoken** nativa para a BEAM. As alternativas de implementação são:

1. *NIF em Rust (Rustler): - *Prós: O tiktoken oficial e várias versões portadas em Rust (como tiktoken-rs) são extremamente rápidas e bem testadas. Com Rustler, podemos expor essa biblioteca diretamente para o Gleam via NIF de Erlang com alta segurança e concorrência nativa. - Contras: Requer toolchain do Rust e introduz código nativo, o que dificulta cross-compilation em alguns ambientes, embora com Rustler Precompiled isso seja superado.

2. *Implementação Pura em Gleam/Erlang: - *Prós: Zero dependências externas (sem NIFs), deploy extremamente portável. - Contras: Construir um BPE parser rápido na BEAM que suporte regex complexos (pcre) exigidos pelo padrão cl100k_base pode ser desafiador em termos de performance e tempo de engenharia.

*Decidimos adotar a Abordagem 1 (NIF em Rust via Rustler / Gleam FFI)*. Iremos criar uma biblioteca packages/gbr_tokenizer que encapsula o parser em Rust, expondo funções Gleam puras: - tokenizer.encode(text: String, model: Model) -> List(Int) - tokenizer.decode(tokens: List(Int), model: Model) -> String - tokenizer.count_tokens(text: String, model: Model) -> Int

Consequências - *Positivas:* Permite ao motor de RAG (gbr_vector, semantic_rag) fazer podas cirúrgicas do contexto, e calcular o custo financeiro na Token-Economia M2M de forma determinística antes da execução. - *Negativas:* Adiciona complexidade na pipeline de build para compilar NIFs do Rustler.

Considerações sobre a Token-Economia Como a meta final é cobrar por trabalho de máquina (M2M crypto economy), o tokenizer torna-se o "medidor de energia" do sistema. Sua precisão deve ser exata de acordo com as métricas oficiais para evitar vazamentos financeiros.