diff --git a/src/api/providers/utils/USAGE_NORMALIZATION.md b/src/api/providers/utils/USAGE_NORMALIZATION.md deleted file mode 100644 index 38cd5ec616..0000000000 --- a/src/api/providers/utils/USAGE_NORMALIZATION.md +++ /dev/null @@ -1,54 +0,0 @@ -# Usage Normalization (AI SDK Providers) - -This folder centralizes usage/cache normalization for AI-SDK-backed providers. - -## Canonical Contract - -The normalizer derives a canonical usage shape before emitting stream chunks: - -- `inputTokensTotal` -- `inputTokensNonCached` (optional) -- `outputTokens` -- `cacheWriteTokens` -- `cacheReadTokens` -- `reasoningTokens` (optional) -- `totalCostCandidate` (optional, provider-reported) - -`ApiStreamUsageChunk` then carries: - -- `inputTokens` (always total input tokens) -- `nonCachedInputTokens?` -- `outputTokens` -- `cacheWriteTokens?` -- `cacheReadTokens?` -- `reasoningTokens?` -- `totalCost?` - -## Precedence Policy - -For each metric, extraction precedence is: - -1. `providerMetadata` -2. AI SDK `usage` -3. `usage.raw` fallback - -This is implemented in `normalize-provider-usage.ts`. - -## Profiles - -`usage-profiles.ts` defines per-provider extraction profiles: - -- The profile specifies candidate paths per metric for `providerMetadata`, `usage`, and `raw`. -- Profiles should contain field mapping only (no provider-specific arithmetic). -- Exceptions (e.g., custom pricing behavior) should be applied at call sites via `totalCostOverride`. - -## New Provider Checklist - -1. Add/confirm a profile in `usage-profiles.ts`. -2. Wire provider usage handling to `normalizeProviderUsage(...)`. -3. Ensure `inputTokens` emitted to stream remains total input tokens. -4. Add/extend provider usage tests for: - - first-turn cache write heavy payload - - second-turn cache read heavy payload - - metadata vs usage conflicts -5. If provider has custom pricing logic, pass `totalCostOverride` explicitly and test it.