https://github.com/steipete/tokentally
One tiny lib for LLM token + cost math
https://github.com/steipete/tokentally
cost token typescript
Last synced: 3 months ago
JSON representation
One tiny lib for LLM token + cost math
- Host: GitHub
- URL: https://github.com/steipete/tokentally
- Owner: steipete
- License: other
- Created: 2025-12-19T11:43:00.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T07:08:54.000Z (3 months ago)
- Last Synced: 2026-03-30T05:39:00.855Z (3 months ago)
- Topics: cost, token, typescript
- Language: TypeScript
- Homepage: https://tokentally.dev
- Size: 77.1 KB
- Stars: 53
- Watchers: 2
- Forks: 11
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🧮 tokentally — One tiny lib for LLM token + cost math
Token usage in, dollar totals out.
Small TypeScript library for:
- Normalizing token usage across providers
- Resolving per-token pricing (static maps, LiteLLM catalog, OpenRouter catalog)
- Estimating and aggregating USD cost
## Install
```bash
pnpm add tokentally
```
## Core usage (browser-safe)
```ts
import { estimateUsdCost, normalizeTokenUsage, pricingFromUsdPerMillion } from 'tokentally';
const usage = normalizeTokenUsage({ prompt_tokens: 1000, completion_tokens: 250 });
const pricing = pricingFromUsdPerMillion({ inputUsdPerMillion: 1.75, outputUsdPerMillion: 14 });
const cost = estimateUsdCost({ usage, pricing });
// { inputUsd: ..., outputUsd: ..., totalUsd: ... }
```
## Node helpers (catalog sources)
### LiteLLM pricing + limits
```ts
import { loadLiteLlmCatalog, resolveLiteLlmPricing, resolveLiteLlmMaxOutputTokens } from 'tokentally/node';
const { catalog } = await loadLiteLlmCatalog({ env: process.env, fetchImpl: fetch });
const pricing = catalog ? resolveLiteLlmPricing(catalog, 'openai/gpt-5.2') : null;
const maxOut = catalog ? resolveLiteLlmMaxOutputTokens(catalog, 'openai/gpt-5.2') : null;
```
### OpenRouter pricing (optional)
```ts
import { fetchOpenRouterPricingMap, resolvePricingFromMap } from 'tokentally/node';
const map = await fetchOpenRouterPricingMap({ apiKey: process.env.OPENROUTER_API_KEY!, fetchImpl: fetch });
const pricing = resolvePricingFromMap(map, 'openai/gpt-5.2');
```
## API
- `normalizeTokenUsage(raw)` → `{ inputTokens, outputTokens, reasoningTokens, totalTokens } | null`
- `pricingFromUsdPerMillion({ inputUsdPerMillion, outputUsdPerMillion })`
- `estimateUsdCost({ usage, pricing })`
- `tallyCosts(calls)` → totals + per-model breakdown
## Non-goals
- Perfect accounting. This is a **best-effort estimate** based on the pricing source you provide.
- Provider-specific invoice reconciliation.
## License
MIT