[PUBLISHED ON NPMJS] @takk/tokenforecast@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-06-19T11:03:27Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/tokenforecast/v/1.0.0

[1.0.0] - 2026-06-19T03:13:43Z

Initial stable release. Token Forecast is the embeddable, zero-runtime-dependency cost forecaster for Massive Intelligence (IM) agents and non-human entities (NHEs): the weather forecast for LLM spend, a library you import instead of a dashboard you ship data to.

Added

Ingestion and series

• bucketEvents(events, options): normalizes raw CostEvent records into a uniform, gap-filled time series, aligned to UTC hour, day, or week buckets, with empty buckets zero-filled so every downstream model sees uniform spacing.
• seriesValues, totalCost, filterEvents helpers. Cost is always supplied by the caller; the library never embeds a provider price table that would go stale.

Forecasting engine

• forecast(series, options): single, double (Holt), and triple (Holt-Winters additive, with learned seasonality) exponential smoothing, the method auto-selected by an out-of-sample holdout backtest, refit on the full series, and projected with widening prediction intervals (Acklam normal inverse) at a configurable confidence level.
• Every forecast carries the method it chose and a backtested error (MAPE, sMAPE, MAE, sample count), so the band, not the point, is the contract.
• budgetForecast(forecast, budget): predicts whether and when cumulative expected spend breaches a budget, plus a worst-case total from the interval upper bounds.

Bayesian cold-start

• forecast(series, { prior }): when history is too thin to fit a smoothing model (fewer than 4 buckets), a caller-supplied prior (mean, uncertainty, optional strength) is blended with the little data via a conjugate normal-mean update, returning a flat posterior with deliberately wide, horizon-widening intervals labeled method: 'cold-start'. The number is the caller's, never fabricated; without a prior the engine still refuses thin history rather than invent a forecast.

Feature engineering

• decompose(series, season): additive trend, seasonal, and residual decomposition.
• seasonalProfile(series): learned multiplicative hour-of-day and day-of-week indices.
• anomalies(series, options): a robust per-bucket z-score (median and median absolute deviation), with a standard-deviation fallback when more than half the buckets are identical, so a lone spike against a flat baseline is still caught.

Attribution, drift, scenarios, price shifts

• attribute(before, after, dimension): ranks the drivers of a cost change across provider, model, feature, or user, by absolute delta, with each driver's signed share.
• detectDrift(series, options): a two-sided Page-Hinkley change-point test that flags a sustained shift in cost behavior before a month-end total would reveal it.
• simulate(events, { swaps, priceBook }): re-costs recorded token volumes under model swaps using a caller-supplied price book, both baseline and scenario, so the delta isolates the model choice.
• detectPriceShifts(before, after): flags models whose effective blended cost per 1,000 tokens moved between two windows, the mitigation for provider price changes invalidating forecasts. It measures blended effective price, so it also moves when the input-to-output token mix shifts; treat a flag as a prompt to investigate.

Facade, bridge, CLI

• createForecaster(options): a stateful facade that holds events and composes the engine (forecast, budget, seasonalProfile, anomalies, attribute, drift, simulate, priceShifts).
• createMeterIngestor (subpath @takk/tokenforecast/alkaline): a structural bridge that turns @takk/alkaline token-meter charges into cost events, importing nothing from Alkaline so the zero-dependency promise holds.
• CLI tokenforecast (forecast, drift, attribute) over a JSON events file, with sysexits exit codes.

Entry points and tooling

• Nine library entry points: core, ./ingest, ./features, ./forecast, ./attribution, ./drift, ./scenario, ./alkaline, ./edge. The whole engine is free of any Node built-in, so the edge entry is the full core and runs in Cloudflare Workers, Vercel Edge, Deno, Bun, and the browser.

Quality

• 53 tests across 12 suites passing under Vitest 4, green on Node 20, 22, and 24.
• Coverage: statements 95.9%, lines 95.9%, functions 99%, branches 82.6%.
• TypeScript strict mode at maximum under TypeScript 6, lint and format clean under Biome 2, publint clean, are-the-types-wrong clean across all nine entry points.
• The core, edge, ingest, features, forecast, attribution, drift, scenario, and alkaline bundles are verified free of any Node built-in; the CLI uses only node:fs and node:process.

Honest scope

• The forecasting is classical statistical time-series (exponential smoothing with learned seasonality and a Bayesian cold-start), not a foundation model, and it does not claim to be. It is honest, explainable, zero-dependency, and ships its backtested error. Cost forecasting in the broader market is also served by hosted platforms (CloudZero, Portkey, Helicone, Langfuse); Token Forecast is the embeddable, in-process, zero-dependency option that runs in your code and on the edge.

Security

• Published with --provenance (SLSA attestation by GitHub Actions). Consumers can verify via npm view @takk/tokenforecast --json | jq .dist.attestations.
• Zero outbound network calls, no telemetry, no persisted state, no API keys held. See SECURITY.md.

Licensing

• Licensed under the Apache License, Version 2.0. The NOTICE file ships in the tarball alongside LICENSE.

Engines

• Node >=20.0.0. Tested on Node 20, 22, and 24.