Module token_estimator 

Local prompt-token estimation (PERF-01): a lightweight, dependency- free heuristic that estimates the prompt token count of a canonical ChatRequest BEFORE the upstream provider is contacted. The estimate feeds a budget pre-check that rejects requests exceeding the remaining token-budget window with 429 ai_budget_exceeded BEFORE the provider call, so a holder near the limit cannot overrun by a large prompt.

Design: character-based heuristic, not a tokenizer

The issue proposed tiktoken-rs or a BPE approximation. This module implements a CHARACTER-BASED heuristic instead — no new dependency, no license review, no vendored BPE merge tables. The trade-off is accuracy: the heuristic approximates ~4 characters per token for English text (the widely-cited rule of thumb from the OpenAI cookbook), with per-message structural overhead. The estimate is CONSERVATIVE (it rounds UP and adds per-message overhead) so the pre-check errs on the side of rejecting rather than undercounting — the actual spend is still provider-reported (crate::ai::budget records the provider’s usage.total_tokens after the call).

What is estimated

• Each message’s text content (role + content parts).
• Each tool call’s name + arguments (assistant messages).
• Each tool definition’s name + description + JSON-Schema parameters (serialized to a compact JSON string for the character count).
• Per-message structural overhead (role markers, formatting): a fixed 4-token allowance per message.
• Image parts: a conservative fixed estimate (85 tokens per image, the OpenAI detail: low overhead — the gateway cannot decode the image to measure its tile count, so the low-detail cost is the honest floor).

max_tokens (the requested output cap) is NOT included here; the caller adds it to the prompt estimate for the total-request pre-check (the budget window covers total tokens, not just the prompt).

Dependency direction

ai depends on config only; this module reads crate::ai::types::ChatRequest (same level). No new dependencies.

Functions

estimate_prompt_tokens

Estimate the prompt token count for a canonical ChatRequest (PERF-01). The estimate is CONSERVATIVE (rounds up, adds per-message overhead) so the budget pre-check errs on the side of rejecting rather than undercounting. The actual spend is still provider- reported (crate::ai::budget records the provider’s usage.total_tokens after the call).