>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3615553. --> Reported by: [camoa](https://www.drupal.org/user/2448054) Related to !53 >>> <h3>Problem/Motivation</h3> <p><code>estimated_cost_usd</code> is overstated by exactly <code>cached_tokens * input_per_token</code> on any provider whose API reports input tokens <em>inclusive</em> of cache reads.</p> <p><strong>Affected:</strong> OpenAI and OpenAI-compatible providers &mdash; <code>OpenAiBasedProviderClientBase.php:633,637</code> sets input from <code>prompt_tokens</code> and cached from <code>prompt_tokens_details.cached_tokens</code>, where cached is a <em>subset</em> of prompt_tokens. Gemini behaves the same way (<code>GeminiProvider.php:441,446</code>, where <code>promptTokenCount</code> includes <code>cachedContentTokenCount</code>).</p> <p><strong>Not affected:</strong> Anthropic, which reports <code>input_tokens</code> <em>exclusive</em> of cache reads (<code>AnthropicProvider.php:1803,1822</code>; streaming path identical in <code>AnthropicStreamedChatMessageIterator.php:154,160</code>). Anthropic is the module's default, so many sites will not see this.</p> <p><code>AiPostGenerateSubscriber::extractTokens()</code> (<code>:234-242</code>) passes both values through unmodified. <code>TokenEstimator::calculateCost()</code> (<code>:139-146</code>) then computes <code>input_tokens * in_rate</code> and <code>cached_tokens * cache_rate</code> and sums both, so cached tokens are charged at the full input rate and again at the cache rate.</p> <p>Worked example with the rates this module ships for <code>openai:gpt-4o</code> (<code>config/install/ai_metering.settings.yml:22-25</code>), for a call with <code>prompt_tokens</code> 1000 of which 800 cached, <code>completion_tokens</code> 200:</p> <ul> <li>Recorded: 1000*0.0000025 + 800*0.00000125 + 200*0.00001 = <strong>$0.0055</strong></li> <li>Actual: 200*0.0000025 + 800*0.00000125 + 200*0.00001 = <strong>$0.0035</strong></li> <li>Overstated by 57%. The error scales with cache hit rate, so the dashboard makes prompt caching appear to <em>increase</em> cost.</li> </ul> <p><strong>Root cause</strong> is a contract ambiguity upstream: <code>TokenUsageDto</code> (<code>ai/src/Dto/TokenUsageDto.php:16-31</code>) documents no convention for whether input includes cached, and the two provider families implement opposite conventions. This module's own docblock (<code>TokenEstimator.php:87-89</code>, "Number of input (non-cached) tokens") specifies the exclusive form &mdash; so the contract here is correct and the caller violates it for OpenAI/Gemini.</p> <p><strong>Scope:</strong> affects <code>estimated_cost_usd</code> (<code>QuotaManager.php:162</code>) and everything derived from it &mdash; dashboard, personal usage blocks, provider breakdowns, rollups, CSV/JSON exports. Quota enforcement and threshold alerts are token-based (<code>QuotaManager.php:190,211</code>) and are <strong>not</strong> affected, so nothing breaks functionally; this is silent inaccuracy in the module's primary output.</p> <h3>Steps to reproduce</h3> <ol> <li>Configure an OpenAI (or Gemini) provider and issue repeated chat calls sharing a large stable system prompt, so the provider begins reporting a non-zero cached token count.</li> <li>Compare the module's recorded <code>estimated_cost_usd</code> for those calls against the provider's own billed cost. Recorded cost exceeds actual by <code>cached_tokens * input_per_token</code>, growing as cache hit rate rises.</li> </ol> <h3>Environment</h3> <ul> <li>Drupal version: n/a &mdash; not reproduced on a running site, see AI assistance note</li> <li>ai_metering version: 1.0.x at commit a39fea9</li> <li>AI provider module + version: affects ai_provider_openai and gemini_provider (and any OpenAI-compatible provider); ai_provider_anthropic is NOT affected</li> <li>AI feature module tested: none &mdash; found by code inspection</li> </ul> <h3>Proposed resolution</h3> <p>Normalise in <code>extractTokens()</code> according to each provider's convention, so <code>calculateCost()</code> always receives the cached-exclusive input its contract already documents.</p> <p>A blind <code>max(0, input - cached)</code> must be avoided &mdash; it would corrupt Anthropic, which is currently correct.</p> <p>The durable fix belongs upstream: <code>TokenUsageDto</code> should document and enforce a single convention across providers. Worth raising with the <code>ai</code> maintainers &mdash; see also the related cache-write gap in <a href="https://www.drupal.org/project/ai_metering/issues/3615562">#3615562</a>, which is blocked on the same DTO.</p> <h3>Remaining tasks</h3> <ul> <li>Decide the normalisation point and how provider convention is detected.</li> <li>Add test coverage passing a non-zero <code>$cached_tokens</code> &mdash; no existing test passes the 5th argument to <code>calculateCost()</code>, which is why this path was never exercised.</li> <li>Decide whether historical rows should be back-corrected or left with a documented caveat.</li> <li>Confirm empirically against a live OpenAI account before fixing.</li> </ul> <h3>User interface changes</h3> <p>None directly. Recorded and displayed costs will drop on affected providers once fixed, which may surprise operators comparing against historical figures.</p> <h3>API changes</h3> <p>None expected. <code>TokenEstimator::calculateCost()</code> keeps its signature and its documented contract; the caller is what changes.</p> <h3>Data model changes</h3> <p>None required. Historical <code>ai_metering_usage.estimated_cost_usd</code> rows for affected providers remain overstated unless a back-correction is chosen (see Remaining tasks).</p> <h3>AI assistance</h3> <p>AI-Generated: Yes (Claude Code &mdash; multi-agent code analysis located this defect and traced the token path line by line with concrete values; this issue text was drafted with AI assistance). No module code was generated. Every claim is code-cited and was reviewed before filing; the citations can be checked against the referenced lines.</p>