Token Forecast

The embeddable, zero-runtime-dependency cost forecaster for Massive Intelligence (IM) agents and non-human entities (NHEs). The weather forecast for LLM spend: record cost events, forecast next month with a prediction interval before the bill arrives, attribute a spike to the feature that caused it, detect drift before it compounds, and simulate model swaps.

tokenforecast is a library you import, not a dashboard you ship data to. It runs inside your own process, your edge function, your agent, and never embeds a provider price table that would go stale. The forecasting is honest and explainable: classical exponential smoothing with learned seasonality, a Bayesian cold-start for brand-new features, and a backtested error on every result, so you always know how much to trust the number.

Core promise: zero required runtime dependencies, single-function setup, ergonomic TypeScript types, ESM + CJS dual distribution, SLSA provenance on every release.

---

Where it fits

Helicone, Langfuse, Portkey, and CloudZero are excellent at telling you what you already spent, and CloudZero and Portkey will even project it on their platform. Token Forecast is the part that runs in your code: a small, honest, in-process forecaster you embed, with no account, no sidecar, no SaaS lock-in. It is the cost-intelligence layer of the @takk family, the natural consumer of the token meter that @takk/alkaline already emits.

You want	Reach for
A hosted dashboard, RBAC, and a vendor to own it	CloudZero, Helicone, Langfuse, Portkey
A forecaster you npm add and call in-process, on Node or the edge, with zero dependencies	Token Forecast

---

Install

pnpm add @takk/tokenforecast
# or: npm install @takk/tokenforecast
# or: yarn add @takk/tokenforecast
# or: bun add @takk/tokenforecast

The core and every entry point have zero runtime dependencies. The optional @takk sibling peers (for example @takk/alkaline) are only needed if you use their bridge.

---

Quickstart

// src/example.ts
import { createForecaster } from '@takk/tokenforecast';

const tf = createForecaster({ granularity: 'day' });

// Record what you spent. You compute the cost; Token Forecast never prices for you.
tf.add([
  { at: Date.now() - 2 * 86_400_000, provider: 'openai', model: 'gpt-4o', feature: 'chat', user: 'acme', inputTokens: 1200, outputTokens: 800, cost: 0.018 },
  // ... more events ...
]);

// Forecast the next 7 days with a 90% prediction interval.
const result = tf.forecast({ horizon: 7, level: 0.9 });
console.log(result.method);   // 'holt-winters' | 'holt' | 'ses' | 'seasonal-naive'
console.log(result.backtest); // { mape, smape, mae, samples } so you can judge it
for (const point of result.points) {
  console.log(new Date(point.at).toISOString(), point.mean, `[${point.lower}, ${point.upper}]`);
}

// Will next week breach the budget, and when?
const budget = tf.budget(50, { horizon: 7 });
console.log(budget.willExceed, budget.exceedAt, budget.utilization);

Every forecast carries the method it chose (by an out-of-sample holdout backtest), an explicit prediction interval, and the backtested error. No opaque model.

---

Forecast a brand-new feature (Bayesian cold-start)

The hardest case is the one that matters most: a feature you launched on Monday whose cost spiked by Wednesday. There is not enough history to fit a model, so instead of refusing, Token Forecast blends a prior you supply with the little data you have and returns honest, wide bounds. The number is yours, never fabricated.

import { forecast, bucketEvents } from '@takk/tokenforecast';

const series = bucketEvents(threeDaysOfEvents, { granularity: 'day' });
const result = forecast(series, {
  prior: { mean: 10, uncertainty: 0.5 }, // your expectation: ~$10/day, plus or minus 50%
  horizon: 7,
});
console.log(result.method); // 'cold-start' (clearly labeled, wide intervals)

---

Attribution, drift, scenario, price shifts

// Which feature drove the cost change before vs after a deploy?
const why = tf.attribute(deployTimestamp, 'feature');
console.log(why.rows[0]); // { key: 'summarize', delta: 31.2, share: 0.83, ... }

// Did cost behavior shift, before it shows up in the month-end total?
const drift = tf.drift(); // Page-Hinkley: { detected, direction, at, magnitude }

// What if I had served this traffic on gpt-4o instead of gpt-4-turbo?
const whatIf = tf.simulate({
  swaps: [{ from: 'gpt-4-turbo', to: 'gpt-4o' }],
  priceBook: { 'gpt-4-turbo': { inputPer1k: 0.01, outputPer1k: 0.03 }, 'gpt-4o': { inputPer1k: 0.0025, outputPer1k: 0.01 } },
});
console.log(whatIf.savings); // fraction saved by the swap

// Did a model's effective price drift, invalidating older forecasts?
const shifts = tf.priceShifts(lastWeek);

---

Entry points

Nine library entry points (dual ESM + CJS, each with its own types) plus the tokenforecast CLI. The whole engine is Node-free, so edge is the full core, importable in Cloudflare Workers, Vercel Edge, Deno, Bun, and the browser.

Import	What it gives you
@takk/tokenforecast	createForecaster, forecast, budgetForecast, and re-exports of everything below
@takk/tokenforecast/ingest	bucketEvents, seriesValues, totalCost, filterEvents
@takk/tokenforecast/features	decompose, seasonalProfile, anomalies
@takk/tokenforecast/forecast	the forecasting engine and budgetForecast
@takk/tokenforecast/attribution	attribute, splitAt
@takk/tokenforecast/drift	detectDrift (Page-Hinkley)
@takk/tokenforecast/scenario	simulate, repriceEvents, priceEvent, detectPriceShifts
@takk/tokenforecast/alkaline	createMeterIngestor, the @takk/alkaline token-meter bridge
@takk/tokenforecast/edge	the full engine, free of any Node built-in

---

CLI

# Forecast from a JSON array of cost events, with a budget check.
npx @takk/tokenforecast forecast events.json --horizon 7 --level 0.9 --budget 500

# Detect a shift in cost behavior.
npx @takk/tokenforecast drift events.json

# Attribute a cost change across a dimension at a timestamp.
npx @takk/tokenforecast attribute events.json --at 1750000000000 --by feature

# Machine-readable output.
npx @takk/tokenforecast forecast events.json --json | jq

The CLI runs as a single Node process with sysexits codes (0 success, 64 usage, 65 bad data, 66 unreadable input).

---

Bridge with @takk/alkaline

@takk/alkaline emits a token charge per durable step through a TokenMeter. Token Forecast is a meter the runtime accepts, turning every charge into a cost event you can forecast. It imports nothing from Alkaline, so the zero-dependency promise holds whether or not Alkaline is installed.

import { createMeterIngestor } from '@takk/tokenforecast/alkaline';

const { meter, drain } = createMeterIngestor({ provider: 'openai', model: 'gpt-4o', pricePer1kTokens: 0.01 });
const runtime = createRuntime({ store, meter }); // @takk/alkaline
// later:
tf.add(drain());

---

Honest limits

Token Forecast tells you exactly how much to trust it. Read these before you wire a forecast into an alert.

• Forecasting needs history. Below 4 buckets it refuses, unless you supply a cold-start prior; the prior is yours, and a bad prior produces a bad forecast (the interval stays honest about the uncertainty, but garbage in is still garbage out).
• detectPriceShifts measures blended effective price (total cost over total tokens per model). It catches real provider price changes, but it also moves when the input-to-output token mix shifts, because a cost event carries one total cost, not a per-direction split. Treat a flagged shift as a prompt to investigate, not a proof of a price change.
• It is statistical, not magic. The engine is exponential smoothing with learned seasonality and prediction intervals, not a foundation model. It is honest, explainable, and zero-dependency, and it ships the backtested error so the band, not the point, is the product.

---

Quality

• 53 tests across 12 suites, all passing under Vitest 4, green on Node 20, 22, and 24.
• Coverage: statements 95.9%, lines 95.9%, functions 99%, branches 82.6%.
• Lint and format clean under Biome 2.
• Typecheck clean under TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes, useUnknownInCatchVariables, noUncheckedIndexedAccess, noImplicitReturns).
• publint clean, are-the-types-wrong clean across all nine entry points.
• A dist smoke test that runs the built artifacts and the compiled CLI as a single Node process.
• Published with --provenance (SLSA attestation by GitHub Actions).

See SPEC.md for the formal specification, public surface, and stability promise.

---

FAQ

Why not just use Helicone, Langfuse, or CloudZero? They are platforms you send your data to; CloudZero and Portkey will even forecast it for you on their dashboards. Token Forecast is a library you pnpm add and run in your own process, on Node or the edge, with zero dependencies and no account. Different shape, different job; they are complementary.

Is the forecasting machine learning? No, and it does not claim to be. It is classical time-series forecasting (single, double, and triple exponential smoothing, the method auto-selected by an out-of-sample backtest), plus a Bayesian cold-start. That is a deliberate choice: it stays zero-dependency, explainable, and honest, and every result carries its backtested error.

Does it work in Cloudflare Workers, Vercel Edge, Bun, or Deno? Yes. The whole engine imports no Node built-in, so @takk/tokenforecast/edge (and the core) run unchanged on any modern JavaScript runtime. Only the tokenforecast CLI is Node-targeted.

Where does the cost history live? Wherever you keep it. Token Forecast is stateless between calls: you bring the events, it does the math. That keeps it embeddable and free of a storage dependency; persistence is your application's choice.

Does it know what models cost? No, on purpose. You supply the cost on each event and the price book for scenarios. A library that embedded a price table would ship stale prices the day a provider changes them.

---

Contributing

See .github/CONTRIBUTING.md for the contributor guide. Substantive proposals open a GitHub Issue first; trivial fixes can go straight to a PR. All commits require DCO sign-off (git commit -s). Non-trivial contributions are governed by the Contributor License Agreement.

Community and support

• Issues and feature requests. Open a GitHub issue at davccavalcante/tokenforecast/issues. For each report, include the package version, a minimal reproduction, and expected vs actual behavior.
• Security disclosures. Do NOT open public issues for vulnerabilities. Follow the responsible-disclosure flow in SECURITY.md, contact davcavalcante@proton.me (or say@takk.ag) with the [SECURITY] prefix.
• Code of Conduct. This project follows the Contributor Covenant 2.1. Participation in any Token Forecast space (issues, PRs, discussions) implies agreement.
• Contributions. All non-trivial contributions go through the Contributor License Agreement. Tests, lint, typecheck, and build must be green before review (pnpm verify).

---

Author

Created by David C Cavalcante, davcavalcante@proton.me (preferred), say@takk.ag (Takk relay), linkedin.com/in/hellodav, x.com/davccavalcante, takk.ag.

Token Forecast is the cost-intelligence layer of a broader portfolio of NPM packages targeting Massive Intelligence (IM) infrastructure for 2026 to 2030, built at Takk Innovate Studio.

---

Related research by the author

The philosophy behind Token Forecast, honest, explainable layers that compose, echoes the author's research frameworks:

• MAIC (Massive Artificial Intelligence Consciousness), a systemic intelligence framework to coordinate, supervise, and govern large-scale Massive Intelligence (IM) ecosystems across multiple models, agents, and decision layers.
• HIM (Hybrid Entity Intelligence Model), a hybrid layer that integrates Massive Intelligence (IM) systems with human-defined logic, rules, and strategic intent.
• NHE (Noumenal Higher-order Entity), a non-human entity with a defined functional identity and operational agency, operating through coordinated intelligence layers while keeping a non-anthropomorphic identity.

These frameworks are published independently of Token Forecast and are separate works:

• Research papers: The Soul of the Machine, Beyond Consciousness in LLMs, The Cave of Silence.
• PhilPapers profile: David Cortes Cavalcante.
• Hugging Face: TeleologyHI.
• GitHub: davccavalcante, Takk8IS.

---

Sponsors

Join the journey as the portfolio continues to ship Massive Intelligence (IM) infrastructure. Your support is the cornerstone of this work.

• Sponsor on GitHub: github.com/sponsors/davccavalcante
• USDT (TRC-20): TS1vuhMAhFpbd7y68cu5ZtP9PsXVmZWmeh

---

Privacy

Token Forecast runs entirely inside your own process and infrastructure. It makes no outbound calls, collects no telemetry, and ships no analytics. It does not even hold your API keys; it works on the cost events you record. See PRIVACY.md for the full data-handling notice.

---

License

Licensed under the Apache License 2.0. See LICENSE for the full text and NOTICE for attribution and third-party component licenses.