Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

usage.ts

159 lines5.4 KB

1import { buildBaseUsage } from '@tanstack/ai'
2import type { TokenUsage } from '@tanstack/ai'
3import type OpenAI from 'openai'
4​
5/**
6 * Build normalized {@link TokenUsage} from an OpenAI-compatible Chat
7 * Completions `usage` object.
8 *
9 * Shared by every provider that routes through
10 * {@link OpenAIBaseChatCompletionsTextAdapter} (OpenAI Chat Completions, Grok,
11 * Groq). Surfaces cached prompt tokens and reasoning/audio detail tokens when
12 * the provider reports them. Returns `undefined` when the provider reported no
13 * usage object, so callers omit the field rather than fabricating zeroed totals.
14 */
15export function buildChatCompletionsUsage(
16 usage: OpenAI.Chat.Completions.ChatCompletion['usage'] | undefined | null,
17): TokenUsage | undefined {
18 if (!usage) return undefined
19​
20 const result = buildBaseUsage({
21 promptTokens: usage.prompt_tokens || 0,
22 completionTokens: usage.completion_tokens || 0,
23 totalTokens: usage.total_tokens || 0,
24 })
25​
26 const completionDetails = usage.completion_tokens_details
27 const completionTokensDetails = {
28 ...(completionDetails?.reasoning_tokens
29 ? { reasoningTokens: completionDetails.reasoning_tokens }
30 : {}),
31 ...(completionDetails?.audio_tokens
32 ? { audioTokens: completionDetails.audio_tokens }
33 : {}),
34 }
35​
36 const promptDetails = usage.prompt_tokens_details
37 const promptTokensDetails = {
38 ...(promptDetails?.cached_tokens
39 ? { cachedTokens: promptDetails.cached_tokens }
40 : {}),
41 ...(promptDetails?.audio_tokens
42 ? { audioTokens: promptDetails.audio_tokens }
43 : {}),
44 }
45​
46 if (Object.keys(completionTokensDetails).length > 0) {
47 result.completionTokensDetails = completionTokensDetails
48 }
49 if (Object.keys(promptTokensDetails).length > 0) {
50 result.promptTokensDetails = promptTokensDetails
51 }
52​
53 // Predicted Outputs accepted/rejected counts have no canonical TokenUsage
54 // slot but are still billed (rejected tokens included), so surface them under
55 // providerUsageDetails — matching how the OpenRouter adapter exposes them.
56 const providerUsageDetails = {
57 ...(completionDetails?.accepted_prediction_tokens
58 ? {
59 acceptedPredictionTokens:
60 completionDetails.accepted_prediction_tokens,
61 }
62 : {}),
63 ...(completionDetails?.rejected_prediction_tokens
64 ? {
65 rejectedPredictionTokens:
66 completionDetails.rejected_prediction_tokens,
67 }
68 : {}),
69 }
70 if (Object.keys(providerUsageDetails).length > 0) {
71 result.providerUsageDetails = providerUsageDetails
72 }
73​
74 return result
76​
77/**
78 * Build normalized {@link TokenUsage} from an OpenAI Responses API
79 * `ResponseUsage` object.
80 *
81 * Shared by every provider that routes through
82 * {@link OpenAIBaseResponsesTextAdapter}. Surfaces cached prompt tokens and
83 * reasoning detail tokens when present. Returns `undefined` when the provider
84 * reported no usage object, so callers omit the field rather than fabricating
85 * zeroed totals.
86 */
87export function buildResponsesUsage(
88 usage: OpenAI.Responses.ResponseUsage | undefined | null,
89): TokenUsage | undefined {
90 if (!usage) return undefined
91​
92 const result = buildBaseUsage({
93 promptTokens: usage.input_tokens || 0,
94 completionTokens: usage.output_tokens || 0,
95 totalTokens: usage.total_tokens || 0,
96 })
97​
98 // Despite the SDK types marking these required, they can be undefined at runtime.
99 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
100 const cachedTokens = usage.input_tokens_details?.cached_tokens
101 if (cachedTokens && cachedTokens > 0) {
102 result.promptTokensDetails = {
103 ...result.promptTokensDetails,
104 cachedTokens,
105 }
106 }
107​
108 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
109 const reasoningTokens = usage.output_tokens_details?.reasoning_tokens
110 if (reasoningTokens && reasoningTokens > 0) {
111 result.completionTokensDetails = {
112 ...result.completionTokensDetails,
113 reasoningTokens,
114 }
115 }
116​
117 return result
119​
120/**
121 * Build normalized {@link TokenUsage} from an OpenAI Images API `usage` object.
122 *
123 * Shared by every provider that generates images through the OpenAI Images SDK
124 * (OpenAI, Grok). Token-billed image models (e.g. gpt-image-1) report an input
125 * breakdown of text vs image tokens, which is surfaced on `promptTokensDetails`.
126 * Models that don't return usage (e.g. DALL·E) yield `undefined` so callers can
127 * omit the field rather than emit zeroed totals.
128 */
129export function buildImagesUsage(
130 usage: OpenAI.Images.ImagesResponse['usage'] | undefined | null,
131): TokenUsage | undefined {
132 if (!usage) return undefined
133​
134 const result = buildBaseUsage({
135 promptTokens: usage.input_tokens || 0,
136 completionTokens: usage.output_tokens || 0,
137 totalTokens: usage.total_tokens || 0,
138 })
139​
140 // The SDK types input_tokens_details (and its numeric fields) as required, but
141 // real responses — e.g. from DALL·E or other non-token-billed models — can
142 // omit them, so treat the breakdown as optional.
143 const inputDetails = usage.input_tokens_details as
144 | { text_tokens?: number; image_tokens?: number }
145 | undefined
146 const promptTokensDetails = {
147 ...(inputDetails?.text_tokens
148 ? { textTokens: inputDetails.text_tokens }
149 : {}),
150 ...(inputDetails?.image_tokens
151 ? { imageTokens: inputDetails.image_tokens }
152 : {}),
153 }
154 if (Object.keys(promptTokensDetails).length > 0) {
155 result.promptTokensDetails = promptTokensDetails
156 }
157​
158 return result