# Generation Budget Estimator v0.1.0

Workflow code is MIT licensed: see [LICENSE](n8n-generation-budget-estimator-LICENSE.txt) and [scope notice](n8n-generation-budget-estimator-NOTICE.md). The premium commercial licence remains separate and unchanged.

Manual, inactive, credential-free, offline calculator. It never calls a model, bills, changes provider/account settings or reserves money. Every outcome has `generation_allowed: false` and `reservation_required: true`. A prompt, supplied approval flag, rate date or budget number is not verified permission, pricing or balance evidence.

## Important n8n import settings limitation

In the tested n8n file-import flow, the new workflow retained default UTC and default execution-saving settings instead of applying the export settings. The JSON declares Africa/Luanda and no execution-data saving, but **do not assume those settings survive import**. Open the new workflow settings, review and explicitly configure timezone and your execution-data retention policy before using private inputs. All live tests used fictional data. Budget arithmetic does not depend on the workflow timezone. No settings round-trip audit is claimed.

## Required input

- `currency: USD`, valid Gregorian `rate_date` (YYYY-MM-DD), `rates_are_example` boolean
- Explicit `input_usd_per_million`, `output_usd_per_million`, `max_input_tokens`, `max_output_tokens`
- `spent_usd`, `reserved_usd`, `monthly_cap_usd` from one consistent, reconciled scope and period
- Explicit `additional_costs: []` for no non-token costs; otherwise one entry per known maximum charge: `{kind: tool|image|other, name, rate_date, max_usd}`. Maximums must cover every relevant unit, tool call, image, surcharge and retry you intend to include. Unknown or missing extra costs block estimation. Unsupported entry fields are rejected. The code cannot discover costs a caller leaves undeclared

All rates/amounts are actual finite nonnegative numbers ≤1,000,000,000 with at most 9 fractional decimal places in their canonical JavaScript Number representation. Numeric strings, negative zero, NaN/Infinity, excess precision and unsafe values reject. Token bounds must be safe nonnegative integers ≤1,000,000,000. There may be at most 100 extras; each name is nonempty and at most 120 characters. Calendar dates support years 0001–9999, including correct Gregorian leap years; a future date is syntactically accepted and does not prove current pricing.

Unknown token maxima return `cannot_estimate`. Do not substitute estimated character counts for a guaranteed bound. Malformed inputs return `blocked`, including absent rates or missing explicit cost scope. Invalid data takes priority over missing bounds. Zero tokens/rates are permitted explicit values, not inferred defaults.

## Exact arithmetic and output

Token estimate = input bound × input rate / 1,000,000 + output bound × output rate / 1,000,000. Total estimate includes every declared non-token maximum. Available = cap − spent − reserved; a negative result always prevents affordability.

Inputs are converted to integer nanodollars, then token multiplication and division are represented exactly at 15 decimal USD places. Comparison uses BigInt integer units, with no floating tolerance or rounding. `*_usd_decimal` strings are authoritative; matching numeric fields are display conveniences and may be rounded by IEEE-754. Never use numeric convenience output to make a spending decision. Output is JSON-safe and contains no BigInt values.

`budget_check` and `status` are `within_limit`, `insufficient_budget`, `cannot_estimate` or `blocked`. A cost equal to available balance fits inclusively. `within_limit` is only a comparison of supplied values; it authorizes nothing.

## Fake example and recovery

The sample uses explicitly fictional rates: input USD 1/M, output USD 2/M, 2,000 input and 1,000 output tokens. Result: USD 0.004; USD 10 cap minus USD 1 spent and USD 0.5 reserved leaves USD 8.5. These are not a price quote or a real account balance.

1. Import `workflow.json` into a new inactive n8n workflow. Inspect all three nodes and run the sample: `within_limit`, estimated_max_usd_decimal `0.004`
2. Set spent and reserved to zero, cap to 0.003: `insufficient_budget`
3. Set cap to 0.004: `within_limit`, with generation still false
4. Remove max_input_tokens: `cannot_estimate`; restore it and the valid result returns
5. Add an image/tool charge with missing max_usd: `blocked`; supply its verified full maximum before recalculating

A fresh isolated import in the n8n workspace passed the sufficient, insufficient, exact-balance, missing-input-token-bound and canonical-restored cases on 30 September 2026. Unit tests and embedded Code-node parity also pass. A brief workspace outage interrupted the test session; completed results were checked before continuing. No post-save runtime-export audit is claimed. Exact evidence and hashes are recorded in `docs/queue-budget-candidates-2026-09-30.json`.

## Production requirements

Real use needs independently verified, dated official rates for the chosen model and tools, authoritative balances, an atomic reservation before any paid call, and reconciliation with observed usage afterwards. Retry estimates must include their maximum planned cost. Two parallel estimators provide no concurrency protection. Provider budget alerts must not be described as guaranteed hard stops. Unknown consumption retains its reservation until reconciliation; do not release and retry blindly.

This generic module compares one explicit budget scope. A future integration must separately enforce each authorized per-service and overall budget, period and currency using authoritative ledgers; passing one calculation proves neither all service limits nor an aggregate limit. Paid subscriptions and incremental API charges must be accounted for according to the actual approved scope. No user-specific financial limits are embedded as policy in this template.

Run: `node --test automation/editorial/generation-budget.test.cjs automation/editorial/queue-budget-packages.test.cjs`.

Maintainers: regenerate deterministic exports and the allowlisted download route with `node automation/editorial/build-queue-budget-workflows.cjs`, then rerun tests and the production build. Public release approved on 30 September 2026; this does not activate a production workflow or authorize paid generation.

Runtime version evidence: the pre-restart About version was not captured. An initial template-link parameter suggested 2.39.6, but is not authoritative. About n8n after the workspace restart explicitly showed 2.41.4. WF11 and WF12 initial/insufficient cases ran before that restart; WF12 exact-balance, missing-bound and recovery cases ran afterwards. Both workflows retained restored canonical fake inputs after reload and stayed unpublished.