O ttok 0.4 corrige bug antigo do Click e ganha comando para listar modelos suportados

O desenvolvedor Simon Willison publicou em 8 de outubro de 2026 a versão 0.4 do ttok, sua ferramenta de linha de comando para contar (e truncar) tokens de texto. É uma atualização de manutenção, mas vale entender o que o ttok faz e por que um detalhe tão pequeno quanto contar tokens no terminal economiza tempo de quem constrói com LLM no dia a dia.

O que mudou nesta versão

Segundo o próprio Willison, o projeto "não recebia atualização havia um par de anos". A versão 0.4 resolve três pendências: um aviso de depreciação do Click (o framework Python usado para montar a interface de linha de comando), a atualização da integração contínua do repositório e a adição de um novo comando, --list-models, que lista os modelos que o ttok reconhece.

Eu finalmente corrigi um aviso do Click, atualizei a integração contínua e adicionei um comando --list-models para listar os modelos disponíveis.

I finally fixed a Click warning, updated CI, and added a --list-models command to list available models.Simon Willison, criador do ttok

A fonte não detalha qual era exatamente o aviso do Click, mas é comum em ferramentas Python mantidas por anos: uma versão nova da biblioteca descontinua algum argumento ou comportamento que o código antigo ainda usava, e o aviso só aparece quando alguém finalmente atualiza a dependência. Resolver isso não muda o comportamento do ttok para quem usa, mas evita que a ferramenta pare de funcionar quando o ambiente for atualizado.

Para que serve o ttok, afinal

O ttok conta quantos tokens um texto vai ocupar quando for enviado a um modelo de linguagem, usando a biblioteca tiktoken, de código aberto, mantida pela própria OpenAI. Token é a unidade que esses modelos usam para processar texto, geralmente um pedaço de palavra, e é também a unidade de cobrança da maioria das APIs. Além de contar, o ttok também trunca um texto num número exato de tokens, recurso que já existia antes da 0.4 e segue funcionando: útil para cortar um prompt longo antes que ele estoure o limite de contexto do modelo.

O uso mais simples é direto no terminal, sem escrever uma linha de Python:

cat relatorio.txt | uvx ttok

O uvx é o executor de ferramentas do uv (o gerenciador de pacotes Python da Astral): ele baixa o ttok, cria um ambiente isolado na hora, roda o comando e descarta tudo depois, sem precisar de pip install nem de ambiente virtual configurado antes. Para quem prefere instalar de vez, o caminho tradicional também funciona:

pip install ttok
ttok --list-models

O novo comando --list-models mostra quais nomes de modelo o ttok reconhece, para escolher a codificação (encoding) correta na hora de contar. Isso importa porque modelos diferentes da OpenAI usam tokenizações diferentes entre si, e contar com a codificação errada dá um número impreciso.

Por que isso importa pra quem constrói com LLM

Um desenvolvedor que monta um agente de RAG (busca e geração aumentada) e injeta trechos de documento no prompt final tem um problema recorrente: saber se aquele bloco de texto cabe no limite de contexto do modelo escolhido antes de montar a chamada de API e descobrir o erro só em produção. Rodar cat contexto.txt | uvx ttok antes de montar o prompt resolve isso em um comando, sem precisar abrir um notebook Python nem importar tiktoken manualmente no código.

O mesmo vale para estimar custo. Como a cobrança da maioria das APIs de LLM é por token, saber antecipadamente quantos tokens um prompt vai consumir ajuda a decidir se vale resumir o texto antes de enviar ou se o orçamento de tokens do projeto aguenta aquele volume. É um cálculo que qualquer um faria em código, mas que no terminal sai mais rápido, principalmente para depurar um prompt específico antes de automatizar o pipeline inteiro.

O limite que o nome não deixa óbvio

O ponto que fica escondido para quem não olha o código é que o ttok conta tokens usando o tiktoken, a biblioteca de tokenização da própria OpenAI. Isso significa que a contagem é precisa para modelos da família GPT, mas vira aproximação para qualquer modelo de outro fabricante, porque Anthropic, Google e Meta usam tokenizadores próprios, diferentes do BPE que a OpenAI emprega. Um texto que o ttok conta como 500 tokens pode render um número diferente num modelo Claude ou Gemini, por exemplo.

Essa limitação não é um bug nem uma falha da versão 0.4: é consequência da arquitetura do projeto, que sempre dependeu do tiktoken. Vale ter isso em mente antes de confiar no número do ttok para calcular custo ou limite de contexto de um modelo que não seja da OpenAI: o resultado serve como estimativa, não como valor exato.

Quando vale usar e quando não vale

Vale usar o ttok quando o trabalho é com modelos da OpenAI, quando o objetivo é debugar um prompt específico rápido no terminal sem montar código, ou quando se quer truncar um texto manualmente antes de colar num chat ou numa chamada de API.

Não vale confiar cegamente quando o modelo-alvo é de outro fabricante (a contagem vira estimativa), nem quando o projeto já tem uma pipeline automatizada chamando tiktoken diretamente em Python: nesse caso o ttok é redundante, porque a biblioteca já está embutida no código.

Para quem nunca usou, o caminho mais rápido para testar é um uvx ttok apontando para qualquer arquivo de texto que esteja por perto. É um comando pequeno, mas resolve um problema recorrente de quem lida com prompt todos os dias: saber quanto aquele texto vai custar antes de descobrir isso na fatura.

Fonte: Simon Willison