token-budget-js

Token counting and context window budget management for LLMs. Prevent overflow with smart truncation — zero dependencies.

Install

npm install token-budget-js

Quick Start

const { countTokens, Budget } = require('token-budget-js');

// Count tokens
countTokens("Hello world"); // → ~2

// Budget guard
const budget = new Budget('gpt-4'); // auto 8192 limit
const messages = [
  { role: 'system', content: systemPrompt },
  { role: 'user', content: hugeDocument },
];

if (budget.wouldOverflow(messages)) {
  const safe = budget.fit(messages);  // auto-truncated
}

Token Counting

const { countTokens, countMessages, getLimit } = require('token-budget-js');

countTokens("Hello world");     // ~2 tokens
countMessages(messages);         // total tokens in chat format
getLimit('gpt-4');              // 8192
getLimit('gpt-4-turbo');        // 128000
getLimit('claude-3-opus');      // 200000

Budget Management

const budget = new Budget('gpt-4', { reserve: 1000 });

budget.wouldOverflow(messages);  // boolean
budget.remaining(messages);      // tokens left
budget.fit(messages);            // truncated copy
budget.fit(messages, 'head');    // keep beginning
budget.fit(messages, 'tail');    // keep end (default)
budget.fit(messages, 'middle');  // keep head + tail

Features

• 30+ model limits built-in (OpenAI, Anthropic, Google, Meta, Mistral)
• Fast approximation (~4 chars/token) — no native deps needed
• Head/tail/middle truncation strategies
• System message preservation during truncation
• Reserve tokens for response

License

MIT