tokenlens weekly downloads statistics

TokenLens ========

Typed model metadata and context/cost utilities that help AI apps answer: Does this fit? What will it cost? Should we compact now? How much budget is left for the next turn?

Works great with the Vercel AI SDK out of the box, and remains SDK‑agnostic.

Highlights • Canonical model registry with alias resolution and minimal metadata you can trust. • Strong TypeScript surface: ModelId autocomplete and safe helpers. • Usage normalization across providers and SDKs (incl. Vercel AI SDK fields). • Context budgeting: remaining tokens, percent used, and next-turn budget. • Compaction helpers: when to compact and how many tokens to remove. • Cost estimation: fast, rough USD costs using source‑linked pricing when available. • Conversation utilities: sum usage, estimate conversation cost, measure context rot.

Install • npm: npm i tokenlens • pnpm: pnpm add tokenlens • yarn: yarn add tokenlens

Quick Start

Core Helpers • Registry: resolveModel, listModels, MODEL_IDS, isModelId, assertModelId • Usage: normalizeUsage, breakdownTokens, consumedTokens • Context: getContextWindow, remainingContext, percentRemaining, fitsContext, pickModelFor • Cost: estimateCost • Compaction: shouldCompact, contextHealth, tokensToCompact • Conversation: sumUsage, estimateConversationCost, computeContextRot, nextTurnBudget • Sugar: modelMeta, percentOfContextUsed, tokensRemaining, costFromUsage

Provider‑Agnostic Usage

Async Fetch (models.dev)

Picking Model Metadata

Context Budgeting & Compaction

Advanced • Caps strategy: remainingContext supports strategy: 'provider-default' | 'combined' | 'input-only'. • provider-default (default): prefers combinedMax when available; otherwise uses inputMax. • combined: always uses combinedMax (falls back to inputMax if missing). • input-only: uses only inputMax for remaining/percent calculations. • Defaults: shouldCompact defaults to threshold: 0.85; contextHealth defaults to warnAt: 0.75, compactAt: 0.85.

Conversation Utilities

Listing Models

Data Source & Sync • Primary source: models.dev (https://github.com/sst/models.dev). We periodically sync our registry from their dataset. • Official provider pages are used where applicable; if numbers aren’t explicit, fields remain undefined. • Sync locally: pnpm -C packages/tokenlens sync:models

Acknowlegements • Big thanks to the sst/models.dev maintainers and community for keeping model information current: https://github.com/sst/models.dev

License MIT

Description from the npm listing.