snug

Fit prioritised content into a token budget.

Every LLM application has the same problem: you have a context window of N tokens and need to fit a system prompt, conversation history, retrieved documents, and tool definitions into it — with space left for the model's reply. Every team writes their own solution from scratch.

snug is a single function that solves this once.

import { fit } from '@jeremysnr/snug';

const { included } = fit(
  [
    { id: 'system',  content: systemPrompt,  priority: 100 },
    { id: 'history', content: chatHistory,   priority:  60 },
    { id: 'rag',     content: retrievedDocs, priority:  40 },
  ],
  { budget: 8192, reserve: 1024, tokenizer: myTokenizer },
);

// included — items that fit, in original input order
// excluded — items that didn't fit

Items are selected greedily in descending priority order. The result preserves original input order. Zero dependencies. Works in Node, Deno, Bun, and edge runtimes.

Install

npm install @jeremysnr/snug

API

fit(items, options)

fit(items: Item[], options: FitOptions): FitResult

Item

Field	Type	Description
id	string	Unique identifier
content	unknown	Your content — not inspected by snug
priority	number	Higher = included first
tokens	number	Pre-counted cost (optional — see below)
pairId	string	Atomic pair group (optional — see below)

FitOptions

Field	Type	Default	Description
budget	number	—	Token limit for included items
tokenizer	(text: string) => number	built-in approx	Your token counter
reserve	number	0	Tokens to hold back (e.g. for model response)
suppressApproximationWarning	boolean	false	Silence the no-tokenizer warning

FitResult

{
  included: Item[];     // items that fit, original order
  excluded: Item[];     // items that didn't fit
  tokensUsed: number;
  tokensRemaining: number;
}

Pair constraints

Anthropic's API requires strict 1:1 pairing between tool_use and tool_result messages — orphaning either half causes a 400 error. Mark paired items with a shared pairId and snug treats them as an atomic unit: both are included or neither is.

fit(
  [
    { id: 'use',    content: toolUse,    priority: 80, pairId: 'call-1' },
    { id: 'result', content: toolResult, priority: 80, pairId: 'call-1' },
  ],
  { budget: 2048, tokenizer },
);

All items in a pair group must share the same priority.

Token counting

Pass any (text: string) => number function:

// tiktoken (OpenAI / Anthropic)
import { encoding_for_model } from 'tiktoken';
const enc = encoding_for_model('gpt-4o');
const tokenizer = (text: string) => enc.encode(text).length;

If you already have a token count (e.g. from an API usage response), pass it directly via the tokens field and skip counting entirely:

{ id: 'msg', content: msg, priority: 50, tokens: 342 }

When no tokenizer is supplied, snug falls back to Math.ceil(text.length / 4) and prints a warning. This is useful for prototyping but can be off by up to 37% in production.

Ecosystem

Package	What it does
@jeremysnr/snug	Zero-dependency core — bring your own tokenizer
@jeremysnr/snug-tiktoken	Pre-wired with tiktoken, model-agnostic
@jeremysnr/snug-openai	Accepts OpenAI SDK message arrays directly
@jeremysnr/snug-anthropic	Accepts Anthropic SDK message arrays, auto-pairs tool messages

Licence

MIT