TokenMeter

Quanto da janela de contexto uma conversa está usando.

Use quando estiver construindo uma interface de chat contra um modelo com limite de contexto. Um cliente que não mostra isso funciona bem no começo e depois falha: cada turno reenvia todo o histórico, a requisição só cresce e em algum momento o provedor a rejeita por exceder o limite. Este componente mostra esse crescimento antes da rejeição.

Início rápido

Uso básico

<r-token-meter limit="65536" used="12800"></r-token-meter>

const meter = document.createElement('r-token-meter');
meter.limit = 65536;
meter.used = 41200; // o contexto que a próxima requisição vai carregar
meter.spent = 128431; // tokens cobrados ao longo da conversa, opcional
composer.append(meter);

A barra se enche até used / limit e escala por três níveis: ok, warn (a partir de 80% do limite) e over. level é refletido no host, então a página pode reagir à mesma escalada que a barra mostra:

r-token-meter[level='warn'] ~ .composer-hint {
  display: block;
}

`used` e `spent` são números diferentes

used: o que a próxima requisição vai carregar — o histórico, não a conversa inteira. É o número a que o limite se aplica e o que a barra desenha.
spent: o que já foi cobrado ao longo da conversa. Ele só cresce e não é limitado pela janela.

Truncar uma transcrição reduz used e deixa spent intacto. Mostrar apenas um deles responde só a uma das duas perguntas que o usuário tem ("a próxima mensagem vai caber?" e "quanto isso já me custou?").

Sem limite

Com limit indefinido ou zero a barra some e restam apenas as contagens, útil enquanto o tamanho da janela é desconhecido.

Trocar o rótulo

<r-token-meter label="Contexto" limit="65536" used="41200"></r-token-meter>
<!-- label="" deixa apenas as contagens -->

Referência da API

Propriedades

Propriedade	Atributo	Tipo	Padrão	Descrição
`limit`	`limit`	`number`	`0`	Tamanho da janela de contexto em tokens. Zero ou ausente esconde a barra.
`used`	`used`	`number`	`0`	Tokens que a próxima requisição vai carregar.
`spent`	`spent`	`number`	`0`	Tokens cobrados na conversa até agora.
`label`	`label`	`string`	`'Context'`	Prefixo do texto; `''` deixa apenas as contagens.
`level`	`level`	`'ok' \| 'warn' \| 'over'`	derivado	Quão cheia está a janela. Definido pelo elemento: escrevê-lo é sobrescrito.
`sheet`	`sheet`	`string`	`''`	CSS injetado no shadow root.

As contagens são formatadas para leitura rápida: exatas abaixo de mil (847 é curto o bastante para ser lido exato) e abreviadas acima (41.2k, 128k); o terceiro dígito de 128.431 não muda o que o leitor faz com ele.

Partes

Parte	Elemento
`meter`	O elemento inteiro
`track`	O fundo da barra
`fill`	A porção preenchida
`text`	O rótulo e as contagens

Acessibilidade

O elemento sempre carrega um title declarando os números, então a cor nunca é a única portadora do aviso: a barra ficar âmbar é um segundo sinal, não o único. Mantenha assim se você reestilizar os níveis.

Estilos

O <r-token-meter> expõe 9 propriedades personalizadas de CSS próprias, além dos tokens semânticos que lê do tema. Defina uma em qualquer lugar de onde ela seja herdada: :root, um contêiner ou o próprio elemento:

r-token-meter {
  --ran-token-meter-fill-background: var(--ran-color-bg-subtle);
}

Partes: fill · meter · text · track

A lista completa está em tokens de estilo; qual token escolher é assunto do design system.

Boas práticas

Atualize used no mesmo lugar em que você monta a requisição, não numa passada de renderização: o número em que as pessoas confiam é o que a próxima requisição vai de fato enviar.
Escale em volta do medidor, não dentro dele. Em level="over" a interface útil é uma sugestão (resumir, começar uma nova conversa), e isso pertence ao aplicativo.
Não anime o preenchimento numa troca de tema: veja as diretrizes de design.