{"_id":"@agentoria/ratecard","name":"@agentoria/ratecard","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.1":{"name":"@agentoria/ratecard","version":"0.2.1","description":"LLM pricing data and a tier-aware cost calculator. Bundled offline snapshot, optional live refresh.","license":"MIT","type":"module","keywords":["llm","pricing","cost","tokens","openai","anthropic","deepseek","estimate"],"repository":{"type":"git","url":"git+https://github.com/WangYihang/llm-ratecard.git","directory":"packages/ratecard"},"homepage":"https://github.com/WangYihang/llm-ratecard/tree/main/packages/ratecard","bugs":{"url":"https://github.com/WangYihang/llm-ratecard/issues"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"},"./snapshot.json":"./data/snapshot.json","./schema":{"types":"./dist/src/schema.d.ts","import":"./dist/src/schema.js"}},"main":"./dist/src/index.js","types":"./dist/src/index.d.ts","sideEffects":false,"engines":{"node":">=18"},"scripts":{"build":"tsc -b tsconfig.build.json","prepublishOnly":"npm run build"},"publishConfig":{"access":"public"},"dependencies":{"zod":"^4.4.3"},"gitHead":"8b7e6f713b5cb2cb7fc5f0882cfdf482d7155f73","_id":"@agentoria/ratecard@0.2.1","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-gRmVx+GvURTZfleJrA63MR+imJ01/2R2jXu+jn0Imn3Bp7doGxZ3tbKFOpQ9z/eYJ/dt8xUDiC7I66p8+1XerQ==","shasum":"2f5de4b2d7f4210b74f2378ac5e3dd2e2ae3ffe5","tarball":"https://registry.npmjs.org/@agentoria/ratecard/-/ratecard-0.2.1.tgz","fileCount":49,"unpackedSize":428718,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFiyPxnSKuI3z3YLEcKgGGVd1qYXBcjs+HnEbjXKhKycAiAJsSuOgr1OguzATItfW4OjyEs+3hAB1KdjCMdJKsB/7w=="}]},"_npmUser":{"name":"agentoria","email":"wangyihanger@gmail.com"},"directories":{},"maintainers":[{"name":"agentoria","email":"wangyihanger@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ratecard_0.2.1_1785925066862_0.8927628097411784"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-05T10:17:46.685Z","0.2.1":"2026-08-05T10:17:46.986Z","modified":"2026-08-05T10:17:47.220Z"},"maintainers":[{"name":"agentoria","email":"wangyihanger@gmail.com"}],"description":"LLM pricing data and a tier-aware cost calculator. Bundled offline snapshot, optional live refresh.","homepage":"https://github.com/WangYihang/llm-ratecard/tree/main/packages/ratecard","keywords":["llm","pricing","cost","tokens","openai","anthropic","deepseek","estimate"],"repository":{"type":"git","url":"git+https://github.com/WangYihang/llm-ratecard.git","directory":"packages/ratecard"},"bugs":{"url":"https://github.com/WangYihang/llm-ratecard/issues"},"license":"MIT","readme":"# @agentoria/ratecard\n\nLLM pricing data with a tier-aware cost calculator. Zero dependencies, works\noffline, optionally refreshes from the published API.\n\n```bash\nnpm install @agentoria/ratecard\n```\n\n## Why\n\nMost pricing tables are a flat `$/1M` number per model. Real bills are not\nflat: context ladders change the rate mid-call, batch APIs halve it, prompt\ncaching discounts part of the input, and half the vendors publish in CNY. This\npackage encodes all of that and tells you which rule it applied.\n\n## Quick start\n\n```ts\nimport { price } from '@agentoria/ratecard';\n\nconst r = price('gpt-5.5', { inputTokens: 300_000, outputTokens: 2_000 });\n\nr.total          // 3.09\nr.currency       // 'USD'\nr.tier.index     // 1  — the call crossed the 272K boundary\nr.tier.minTokens // 272001\nr.breakdown      // { input: 3, cachedInput: 0, output: 0.09 }\nr.unitPrices     // { input: 10, cachedInput: 1, output: 45 }\nr.warnings       // []\n```\n\nModel ids accept vendor aliases, so you can pass the same string you passed to\nthe vendor's SDK:\n\n```ts\nprice('deepseek-chat', { inputTokens: 1_000, outputTokens: 500 });\n```\n\n## Prompt caching\n\nPass the absolute cached-token count — the number vendors return in their usage\npayload — not a ratio:\n\n```ts\nprice('gpt-5.5', {\n  inputTokens: 100_000,\n  outputTokens: 2_000,\n  cachedInputTokens: 80_000,   // billed at the cache-hit rate\n});\n```\n\nIf the model publishes no cached-input price, the tokens are billed in full and\nyou get a warning saying so. Nothing is discounted silently.\n\n## Batch API\n\n```ts\nprice('qwen3-max', usage, { mode: 'batch' });\n```\n\nModels without published batch rates fall back to standard pricing, with a\nwarning. Check `result.warnings` — it is the difference between \"this is the\nbatch price\" and \"this is what you'd pay if batch existed\".\n\n## Currencies\n\nPrices are stored in each vendor's own pricing-document currency. Ask for\nwhichever you want:\n\n```ts\nprice('deepseek-chat', usage);                       // CNY — DeepSeek's native\nprice('deepseek-chat', usage, { currency: 'USD' });  // converted\n```\n\nThe bundled FX table travels with the data. Override it when you need a\nspecific rate:\n\n```ts\nprice('gpt-5.5', usage, {\n  currency: 'CNY',\n  fxRates: { base: 'USD', date: '2026-07-01', rates: { USD: 1, CNY: 7.1 } },\n});\n```\n\n## Comparing models\n\n```ts\nimport { compare } from '@agentoria/ratecard';\n\nconst { results } = compare(\n  { inputTokens: 10_000, outputTokens: 1_000 },\n  { filter: { country: 'CN', capabilities: ['tool-use'] } },\n);\n\nresults[0]; // cheapest, priced in USD so the ranking is meaningful\n```\n\n`compare` normalises to USD by default — ranking a CNY total against a USD\ntotal would silently compare different units.\n\n## Browsing the catalogue\n\n```ts\nimport { listModels, getModel, models, providers } from '@agentoria/ratecard';\n\nlistModels({ providerId: 'anthropic' });\nlistModels({ minContextLength: 200_000, status: 'ga' });\nlistModels({ search: 'flash' });\n\ngetModel('claude-opus-4-7')?.source.url;   // the vendor page it came from\n```\n\nEvery record carries `source.url` and `source.fetchedAt` — the official page it\nwas transcribed from, and when. Prices change without notice; check the source\nbefore making a procurement decision on a number.\n\n## Live data\n\nThe package ships a snapshot, so everything above works with no network. To\npick up newer prices without upgrading the package:\n\n```ts\nimport { Client } from '@agentoria/ratecard';\n\nconst client = new Client({ ttlSeconds: 3600 });\nawait client.refresh();                    // never throws\nclient.dataset.price('gpt-5.5', usage);\n```\n\n`refresh()` reports failures in its return value instead of throwing, and keeps\nserving the data it already has. A CDN blip degrades you to slightly stale\nprices; it does not take down your request path.\n\n```ts\nconst r = await client.refresh();\nif (r.error) console.warn('using cached prices:', r.error.message);\n```\n\nIt fetches a ~1 KB manifest first and only downloads the catalogue when\n`dataVersion` actually changed.\n\n## Estimating tokens\n\n```ts\nimport { estimateTokens } from '@agentoria/ratecard';\n\nestimateTokens('你好，世界');   // heuristic, ±10–20% of a real tokeniser\n```\n\nDeliberately not `tiktoken`: that is megabytes of WASM, matches one vendor, and\nthis package has to stay dependency-free. Use it for budgeting; use the\nvendor's reported token counts for anything that has to reconcile.\n\nWhen the estimate is not good enough, supply a real tokeniser instead of\nreplacing the module — a Node-side adapter is one line and stays out of the\nbrowser bundle:\n\n```ts\nimport { encode } from 'gpt-tokenizer';\nimport { Dataset, bundledSnapshot } from '@agentoria/ratecard';\n\nconst dataset = new Dataset(bundledSnapshot, { tokenizer: (t) => encode(t).length });\nconst r = dataset.priceText('gpt-5.5', prompt, 500);\nr.estimatedInputTokens;  // the count actually used\nr.tokenizerUsed;         // 'custom' — so you can tell an estimate from a measurement\n```\n\n## Billable amounts\n\n`total` is a float, and that is fine: measured across all 3,204 conformance\ncases the worst relative error against exact decimal is 2.8e-16 — one unit in\nthe last place. What is *not* fine is scaling it to cents yourself:\n\n```ts\nMath.round(0.025 * 100);              // 3\ntoMinorUnits(0.025, 'USD');           // 2n — exact, rounds half to even\n```\n\n```ts\nimport { toMinorUnits, toBillableAmount } from '@agentoria/ratecard';\n\nconst r = price('gpt-5.5', usage);\ntoMinorUnits(r.total, r.currency);     // 309n — the integer you invoice\ntoBillableAmount(r.total, r.currency); // 3.09\n```\n\nThe conversion goes through the value's decimal representation with integer\narithmetic, never a float multiply, and the Python and Go SDKs quantize\nidentically.\n\n## Errors\n\nInvalid usage throws rather than returning a plausible-looking number:\n\n```ts\nprice('gpt-5.5', { inputTokens: -1, outputTokens: 0 });          // RangeError\nprice('gpt-5.5', { inputTokens: 10, outputTokens: 0,\n                   cachedInputTokens: 11 });                     // RangeError\nprice('nope', usage);                                            // Error\n```\n\n## Tier semantics\n\nEach tier states what its token range measures, because vendors differ:\n\n| `basis` | range is compared against |\n|---|---|\n| `input_tokens` | prompt tokens (default, most common) |\n| `total_tokens` | prompt + completion |\n| `context_window` | the model's declared window, fixed per deployment |\n\n`result.tier` tells you which tier was selected and on what basis, so a\nsurprising number is always traceable.\n\n## Data source and license\n\nData is transcribed from official vendor pricing pages by\n[LLM Ratecard](https://github.com/WangYihang/llm-ratecard) and published at\n`/api/v1/`. Code is MIT; the dataset is CC BY 4.0 and asks for attribution:\n\n> Pricing data from LLM Ratecard (https://github.com/WangYihang/llm-ratecard), CC BY 4.0.\n\nIt is a community transcription, provided without warranty of accuracy. Verify\nagainst the linked official page before relying on a number for billing.\n\n## Cross-language parity\n\nThe pricing algorithm is pinned by `conformance/cases.json` in the repo — 3,200\ncases covering every model. The Python and Go SDKs are held to the same\nfixture, so all implementations produce identical numbers.\n","readmeFilename":"README.md","_rev":"1-a0729a07eddceff7726efae74fdcd789"}