@molecule/api-ai-openai 1.4.5 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -117
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/provider.d.ts +1 -0
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +109 -18
- package/dist/types.d.ts +9 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-
|
|
6
|
+
Generated: 2026-11-04T14:08:52.008Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/api-ai-openai
|
|
@@ -62,6 +62,15 @@ interface OpenaiConfig {
|
|
|
62
62
|
maxTokens?: number
|
|
63
63
|
/** Override the API base URL (for proxies / Azure). */
|
|
64
64
|
baseUrl?: string
|
|
65
|
+
/**
|
|
66
|
+
* How the upstream uses OpenAI's documented 429 quota codes. `'openai'`
|
|
67
|
+
* treats them as exhausted billing/spend limits and stops without retrying;
|
|
68
|
+
* `'retryable'` treats them as ordinary throttling. Defaults to `'openai'`
|
|
69
|
+
* for `api.openai.com` and `*.openai.azure.com` (including explicit ports),
|
|
70
|
+
* and `'retryable'` for every other host. Set `'openai'` for a proxy that
|
|
71
|
+
* forwards OpenAI or Azure OpenAI quota failures unchanged.
|
|
72
|
+
*/
|
|
73
|
+
quotaSemantics?: 'openai' | 'retryable'
|
|
65
74
|
/** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
|
|
66
75
|
onRateLimit?: AiRateLimitCallback
|
|
67
76
|
/**
|
|
@@ -112,6 +121,7 @@ class OpenaiAIProvider implements AIProvider {
|
|
|
112
121
|
private baseUrl: string
|
|
113
122
|
private onRateLimit?: AiRateLimitCallback
|
|
114
123
|
private api: OpenaiApi
|
|
124
|
+
private quotaSemantics: OpenaiQuotaSemantics
|
|
115
125
|
|
|
116
126
|
constructor(config: OpenaiConfig = {}) {
|
|
117
127
|
this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? ''
|
|
@@ -120,13 +130,8 @@ class OpenaiAIProvider implements AIProvider {
|
|
|
120
130
|
this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com'
|
|
121
131
|
this.onRateLimit = config.onRateLimit
|
|
122
132
|
this.api = config.api ?? defaultApiFor(this.baseUrl)
|
|
133
|
+
this.quotaSemantics = config.quotaSemantics ?? defaultQuotaSemanticsFor(this.baseUrl)
|
|
123
134
|
|
|
124
|
-
// Fail fast with an actionable local error rather than a cryptic 401 on the
|
|
125
|
-
// first request. The default `provider` export constructs lazily on first
|
|
126
|
-
// use (see index.ts), so this surfaces the moment the provider is actually
|
|
127
|
-
// used, not at bond/module-load time. A key is required only for the
|
|
128
|
-
// official endpoint — a custom baseUrl may target a keyless self-hosted /
|
|
129
|
-
// local server (Ollama, LM Studio), where the auth header is omitted below.
|
|
130
135
|
const usingCustomEndpoint = Boolean(config.baseUrl ?? process.env.OPENAI_BASE_URL)
|
|
131
136
|
if (!this.apiKey && !usingCustomEndpoint) {
|
|
132
137
|
throw new Error(
|
|
@@ -135,15 +140,6 @@ class OpenaiAIProvider implements AIProvider {
|
|
|
135
140
|
}
|
|
136
141
|
}
|
|
137
142
|
|
|
138
|
-
/**
|
|
139
|
-
* Build the request body for `POST /v1/chat/completions`.
|
|
140
|
-
*
|
|
141
|
-
* @param params - The caller's chat parameters.
|
|
142
|
-
* @param model - The resolved model id.
|
|
143
|
-
* @param maxTokens - The resolved output-token limit.
|
|
144
|
-
* @param useStream - Whether to request an SSE stream.
|
|
145
|
-
* @returns The JSON request body.
|
|
146
|
-
*/
|
|
147
143
|
private buildChatCompletionsBody(
|
|
148
144
|
params: ChatParams,
|
|
149
145
|
model: string,
|
|
@@ -153,40 +149,14 @@ class OpenaiAIProvider implements AIProvider {
|
|
|
153
149
|
const messages = this.formatMessages(params.messages, params.system)
|
|
154
150
|
|
|
155
151
|
const body: Record<string, unknown> = {
|
|
156
|
-
// BYO / provider-native tunables (reasoning_effort, enable_thinking, …).
|
|
157
|
-
// Spread FIRST so the structural fields below (model, messages,
|
|
158
|
-
// max_completion_tokens, tools, stream) always win and cannot be broken.
|
|
159
152
|
...(params.extraBody ?? {}),
|
|
160
|
-
// Abuse attribution (see ChatParams.endUserId). OpenAI DEPRECATED `user`
|
|
161
|
-
// and replaced it with `safety_identifier` for exactly this purpose —
|
|
162
|
-
// their guidance is a hashed, stable per-user string, which is what
|
|
163
|
-
// endUserId already is. Sibling OpenAI-compatible bonds keep `user`: it is
|
|
164
|
-
// the field they actually implement, verified accepted by deepseek, xai,
|
|
165
|
-
// moonshot, alibaba and zhipu against their live APIs.
|
|
166
|
-
//
|
|
167
|
-
// This bond is also pointed at arbitrary BYO OpenAI-compatible endpoints
|
|
168
|
-
// (molecule-dev's custom providers), so the unknown-field question matters
|
|
169
|
-
// here: those same five providers all returned 200 when sent an unknown
|
|
170
|
-
// `safety_identifier`, i.e. tolerating unknown body params is the norm.
|
|
171
|
-
// A BYO endpoint therefore ignores this rather than rejecting it — and BYO
|
|
172
|
-
// runs on the user's OWN key, where attribution protects nothing of ours.
|
|
173
153
|
...(params.endUserId ? { safety_identifier: params.endUserId } : {}),
|
|
174
154
|
model,
|
|
175
155
|
messages,
|
|
176
|
-
// `max_completion_tokens`, NOT `max_tokens`. Every GPT-5-family model
|
|
177
|
-
// hard-rejects the latter — "Unsupported parameter: 'max_tokens' is not
|
|
178
|
-
// supported with this model" (400) — and the catalog's OpenAI entries are
|
|
179
|
-
// all gpt-5.6-*, so this bond could not call any of its own models. The
|
|
180
|
-
// newer name is accepted by the older generations too (verified 200 on
|
|
181
|
-
// gpt-4o-mini and gpt-3.5-turbo), so there is no need to branch per model.
|
|
182
156
|
max_completion_tokens: maxTokens,
|
|
183
157
|
}
|
|
184
158
|
if (params.temperature !== undefined) body.temperature = params.temperature
|
|
185
159
|
|
|
186
|
-
// Reasoning depth: the caller resolves the model's native reasoning_effort
|
|
187
|
-
// value (none | low | medium | high | xhigh on GPT-5.4/5.5-family) from the
|
|
188
|
-
// model catalog and passes it as `thinking.effort`. Without it, omit the
|
|
189
|
-
// param entirely (the model's own default applies — medium on gpt-5.5).
|
|
190
160
|
if (params.thinking?.effort) {
|
|
191
161
|
body.reasoning_effort = params.thinking.effort
|
|
192
162
|
}
|
|
@@ -207,83 +177,11 @@ class OpenaiAIProvider implements AIProvider {
|
|
|
207
177
|
}
|
|
208
178
|
return body
|
|
209
179
|
}
|
|
210
|
-
|
|
211
|
-
/**
|
|
212
|
-
* Send a chat request and yield streamed `ChatEvent`s.
|
|
213
|
-
*
|
|
214
|
-
* @param params - Chat parameters.
|
|
215
|
-
* @yields {ChatEvent}
|
|
216
|
-
*/
|
|
217
|
-
async *chat(params: ChatParams): AsyncIterable<ChatEvent> {
|
|
218
|
-
const model = params.model ?? this.defaultModel
|
|
219
|
-
const maxTokens = params.maxTokens ?? this.maxTokens
|
|
220
|
-
const useStream = params.stream !== false
|
|
221
|
-
const isResponses = this.api === 'responses'
|
|
222
|
-
|
|
223
|
-
const body = isResponses
|
|
224
|
-
? buildResponsesBody(params, model, maxTokens, useStream)
|
|
225
|
-
: this.buildChatCompletionsBody(params, model, maxTokens, useStream)
|
|
226
|
-
const path = isResponses ? '/v1/responses' : '/v1/chat/completions'
|
|
227
|
-
|
|
228
|
-
// Per-call correlation (see ChatParams.requestId): a header rather than the
|
|
229
|
-
// body's `user`, which is the stable per-account abuse-attribution value.
|
|
230
|
-
const requestId = params.requestId ?? randomUUID()
|
|
231
|
-
const call: OpenaiCallContext = {
|
|
232
|
-
meta: { requestId, endpoint: `${this.baseUrl}${path}` },
|
|
233
|
-
endUserId: params.endUserId,
|
|
234
|
-
}
|
|
235
|
-
|
|
236
|
-
const headers: Record<string, string> = {
|
|
237
|
-
'Content-Type': 'application/json',
|
|
238
|
-
// Omitted for a keyless custom endpoint (a self-hosted / local server).
|
|
239
|
-
...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
|
|
240
|
-
'X-Mol-Request-Id': requestId,
|
|
241
|
-
}
|
|
242
|
-
|
|
243
|
-
const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000
|
|
244
|
-
const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
|
|
245
|
-
|
|
246
|
-
const MAX_RETRIES = 3
|
|
247
|
-
let response: Response | null = null
|
|
248
|
-
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
|
|
249
|
-
response = await fetch(`${this.baseUrl}${path}`, {
|
|
250
|
-
method: 'POST',
|
|
251
|
-
headers,
|
|
252
|
-
body: JSON.stringify(body),
|
|
253
|
-
signal,
|
|
254
|
-
})
|
|
255
|
-
|
|
256
|
-
if (response.status === 429 || response.status === 503) {
|
|
257
|
-
const willRetry = attempt < MAX_RETRIES
|
|
258
|
-
// Retry-After is equally-valid as delta-seconds or an HTTP-date;
|
|
259
|
-
// parseInt on the date form yields NaN, degrading the backoff to a
|
|
260
|
-
// ~0ms retry against an already rate-limiting API. Guard it.
|
|
261
|
-
const retryAfter = response.headers.get('retry-after')
|
|
262
|
-
const parsedRetryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN
|
|
263
|
-
const hasRetryAfter =
|
|
264
|
-
Number.isFinite(parsedRetryAfterSeconds) && parsedRetryAfterSeconds >= 0
|
|
265
|
-
// Additive jitter (<500ms): concurrent callers rejected together must
|
|
266
|
-
// not sleep identical delays and re-arrive as the same burst.
|
|
267
|
-
const delayMs = willRetry
|
|
268
|
-
? (hasRetryAfter
|
|
269
|
-
? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
|
|
270
|
-
: Math.min(1000 * 2 ** attempt, 30_000)) + Math.floor(Math.random() * 500)
|
|
271
|
-
: 0
|
|
272
|
-
try {
|
|
273
|
-
this.onRateLimit?.({
|
|
274
|
-
provider: this.name,
|
|
275
|
-
model,
|
|
276
|
-
status: response.status,
|
|
277
|
-
attempt: attempt + 1,
|
|
278
|
-
willRetry,
|
|
279
|
-
retryInMs: delayMs,
|
|
280
|
-
...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
|
|
281
|
-
})
|
|
282
|
-
} catch (error) {
|
|
283
|
-
// Host-app telemetry; its failure must never break the request.
|
|
284
|
-
// … truncated — the full declaration is in node_modules/@molecule/api-ai-openai/dist/provider.d.ts
|
|
180
|
+
// … truncated — 7 more members: chat, formatMessages, formatBlock, formatTools, parseNonStreamingResponse, parseStreamingResponse, processSSELines; the full declaration is in node_modules/@molecule/api-ai-openai/dist/provider.d.ts
|
|
285
181
|
```
|
|
286
182
|
|
|
183
|
+
_(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/api-ai-openai/dist/provider.d.ts`.)_
|
|
184
|
+
|
|
287
185
|
### Functions
|
|
288
186
|
|
|
289
187
|
#### `createProvider(config)`
|
|
@@ -368,6 +266,11 @@ tools (`serverTools`, e.g. `{ type: 'web_search', name: 'web_search' }`); chat/c
|
|
|
368
266
|
ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
|
|
369
267
|
keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
|
|
370
268
|
|
|
269
|
+
**Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
|
|
270
|
+
quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
|
|
271
|
+
Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
|
|
272
|
+
`quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
|
|
273
|
+
|
|
371
274
|
**Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
|
|
372
275
|
first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
|
|
373
276
|
not at bond/module-load time) — it never silently sends an empty key.
|
package/dist/index.d.ts
CHANGED
|
@@ -33,6 +33,11 @@
|
|
|
33
33
|
* ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
|
|
34
34
|
* keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
|
|
35
35
|
*
|
|
36
|
+
* **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
|
|
37
|
+
* quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
|
|
38
|
+
* Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
|
|
39
|
+
* `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
|
|
40
|
+
*
|
|
36
41
|
* **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
|
|
37
42
|
* first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
|
|
38
43
|
* not at bond/module-load time) — it never silently sends an empty key.
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChE,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAMlD,mCAAmC;AACnC,eAAO,MAAM,QAAQ,EAAE,UAUrB,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -33,6 +33,11 @@
|
|
|
33
33
|
* ignores `serverTools`. `extraBody` is merged into whichever endpoint's body is sent, so its
|
|
34
34
|
* keys must be that endpoint's params (e.g. `reasoning`, not `reasoning_effort`, on Responses).
|
|
35
35
|
*
|
|
36
|
+
* **Quota semantics**: OpenAI and Azure OpenAI hosts treat documented 429 billing, spend, and
|
|
37
|
+
* quota codes as exhausted without retrying; other hosts retry them as ordinary throttling.
|
|
38
|
+
* Set `quotaSemantics: 'openai'` when a proxy forwards those failures unchanged, or
|
|
39
|
+
* `quotaSemantics: 'retryable'` to preserve retries on a native host with different semantics.
|
|
40
|
+
*
|
|
36
41
|
* **Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
|
|
37
42
|
* first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
|
|
38
43
|
* not at bond/module-load time) — it never silently sends an empty key.
|
package/dist/provider.d.ts
CHANGED
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAGX,MAAM,kBAAkB,CAAA;AAQzB,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAGX,MAAM,kBAAkB,CAAA;AAQzB,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,YAAY,CAAA;AAiHzD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,QAAQ,CAAC,IAAI,YAAW;IACxB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,WAAW,CAAC,CAAqB;IACzC,OAAO,CAAC,GAAG,CAAW;IACtB,OAAO,CAAC,cAAc,CAAsB;gBAEhC,MAAM,GAAE,YAAiB;IAuBrC;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAgEhC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IA0KzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IAmEtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA6BnB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA8ClC;;;;;OAKG;YACY,sBAAsB;IAgFrC;;;;;;OAMG;IACH,OAAO,CAAE,eAAe;CAyGzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,UAAU,CAEhE"}
|
package/dist/provider.js
CHANGED
|
@@ -19,6 +19,19 @@ import { streamErrorEvent } from './utilities.js';
|
|
|
19
19
|
const logger = getLogger();
|
|
20
20
|
/** OpenAI's own API host — the only one assumed to serve `/v1/responses`. */
|
|
21
21
|
const OPENAI_API_HOST = 'api.openai.com';
|
|
22
|
+
/** The URL's normalized hostname, without a port or a trailing DNS root dot. */
|
|
23
|
+
function normalizedHostname(baseUrl) {
|
|
24
|
+
try {
|
|
25
|
+
return new URL(baseUrl).hostname.replace(/\.$/, '');
|
|
26
|
+
}
|
|
27
|
+
catch (_error) {
|
|
28
|
+
return undefined;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/** Whether a base URL addresses OpenAI's own API rather than a compatible service. */
|
|
32
|
+
function isOpenAIEndpoint(baseUrl) {
|
|
33
|
+
return normalizedHostname(baseUrl) === OPENAI_API_HOST;
|
|
34
|
+
}
|
|
22
35
|
/**
|
|
23
36
|
* Pick the default endpoint for a base URL: Responses for OpenAI's own API,
|
|
24
37
|
* chat/completions for anything else.
|
|
@@ -27,13 +40,62 @@ const OPENAI_API_HOST = 'api.openai.com';
|
|
|
27
40
|
* @returns The endpoint to use.
|
|
28
41
|
*/
|
|
29
42
|
function defaultApiFor(baseUrl) {
|
|
43
|
+
return isOpenAIEndpoint(baseUrl) ? 'responses' : 'chat-completions';
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Pick the quota semantics native OpenAI and Azure OpenAI endpoints use.
|
|
47
|
+
* Compatible services retain ordinary 429 retries unless explicitly configured
|
|
48
|
+
* to forward OpenAI's billing/quota behavior.
|
|
49
|
+
*/
|
|
50
|
+
function defaultQuotaSemanticsFor(baseUrl) {
|
|
51
|
+
const hostname = normalizedHostname(baseUrl);
|
|
52
|
+
return hostname === OPENAI_API_HOST || hostname?.endsWith('.openai.azure.com')
|
|
53
|
+
? 'openai'
|
|
54
|
+
: 'retryable';
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* OpenAI's documented billing, spend, and quota errors on HTTP 429
|
|
58
|
+
* (https://platform.openai.com/docs/guides/error-codes/api-errors). Retrying
|
|
59
|
+
* cannot restore access; ordinary rate-limit codes on that status stay retryable.
|
|
60
|
+
*/
|
|
61
|
+
const QUOTA_EXHAUSTED_CODES = new Set([
|
|
62
|
+
'insufficient_quota',
|
|
63
|
+
'credit_balance_exhausted',
|
|
64
|
+
'organization_spend_limit_exceeded',
|
|
65
|
+
'project_spend_limit_exceeded',
|
|
66
|
+
'organization_usage_limit_exceeded',
|
|
67
|
+
]);
|
|
68
|
+
/** Whether this is a documented account quota failure on its documented status. */
|
|
69
|
+
function isQuotaExhausted(status, error) {
|
|
70
|
+
return status === 429 && error?.type !== undefined && QUOTA_EXHAUSTED_CODES.has(error.type);
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Read the upstream's explanation from a rejected response body: its error
|
|
74
|
+
* `code` (or broader `type`) and `message`, the message bounded to 500 characters.
|
|
75
|
+
* OpenAI directs callers to inspect the specific `code` for billing failures.
|
|
76
|
+
*
|
|
77
|
+
* @param text - The rejected response's body text.
|
|
78
|
+
* @returns The upstream error, or `undefined` when the body carried neither field.
|
|
79
|
+
*/
|
|
80
|
+
function parseUpstreamError(text) {
|
|
81
|
+
let error;
|
|
30
82
|
try {
|
|
31
|
-
|
|
83
|
+
error = JSON.parse(text)?.error;
|
|
32
84
|
}
|
|
33
85
|
catch (_error) {
|
|
34
|
-
//
|
|
35
|
-
|
|
86
|
+
// Not JSON (a proxy's error page, plain text): a short body is the message itself.
|
|
87
|
+
const trimmed = text.trim();
|
|
88
|
+
return trimmed && trimmed.length <= 500 ? { message: trimmed } : undefined;
|
|
36
89
|
}
|
|
90
|
+
const type = typeof error?.code === 'string'
|
|
91
|
+
? error.code
|
|
92
|
+
: typeof error?.type === 'string'
|
|
93
|
+
? error.type
|
|
94
|
+
: undefined;
|
|
95
|
+
const message = typeof error?.message === 'string' ? error.message.slice(0, 500) : undefined;
|
|
96
|
+
if (!type && !message)
|
|
97
|
+
return undefined;
|
|
98
|
+
return { ...(type ? { type } : {}), ...(message ? { message } : {}) };
|
|
37
99
|
}
|
|
38
100
|
/**
|
|
39
101
|
* OpenAI Chat Completions provider implementing the `AIProvider` interface.
|
|
@@ -46,6 +108,7 @@ export class OpenaiAIProvider {
|
|
|
46
108
|
baseUrl;
|
|
47
109
|
onRateLimit;
|
|
48
110
|
api;
|
|
111
|
+
quotaSemantics;
|
|
49
112
|
constructor(config = {}) {
|
|
50
113
|
this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? '';
|
|
51
114
|
this.defaultModel = config.defaultModel ?? 'gpt-6-luna';
|
|
@@ -53,6 +116,7 @@ export class OpenaiAIProvider {
|
|
|
53
116
|
this.baseUrl = config.baseUrl ?? process.env.OPENAI_BASE_URL ?? 'https://api.openai.com';
|
|
54
117
|
this.onRateLimit = config.onRateLimit;
|
|
55
118
|
this.api = config.api ?? defaultApiFor(this.baseUrl);
|
|
119
|
+
this.quotaSemantics = config.quotaSemantics ?? defaultQuotaSemanticsFor(this.baseUrl);
|
|
56
120
|
// Fail fast with an actionable local error rather than a cryptic 401 on the
|
|
57
121
|
// first request. The default `provider` export constructs lazily on first
|
|
58
122
|
// use (see index.ts), so this surfaces the moment the provider is actually
|
|
@@ -161,7 +225,9 @@ export class OpenaiAIProvider {
|
|
|
161
225
|
const signal = params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
|
|
162
226
|
const MAX_RETRIES = 3;
|
|
163
227
|
let response = null;
|
|
228
|
+
let rejectedBody;
|
|
164
229
|
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
|
|
230
|
+
rejectedBody = undefined;
|
|
165
231
|
response = await fetch(`${this.baseUrl}${path}`, {
|
|
166
232
|
method: 'POST',
|
|
167
233
|
headers,
|
|
@@ -169,7 +235,24 @@ export class OpenaiAIProvider {
|
|
|
169
235
|
signal,
|
|
170
236
|
});
|
|
171
237
|
if (response.status === 429 || response.status === 503) {
|
|
172
|
-
|
|
238
|
+
// Read the body once: an unread body pins its connection, and only the
|
|
239
|
+
// body says whether a 429 is a rate limit or an exhausted quota.
|
|
240
|
+
try {
|
|
241
|
+
rejectedBody = await response.text();
|
|
242
|
+
}
|
|
243
|
+
catch (error) {
|
|
244
|
+
// Caller cancellation still ends the request; any other read failure
|
|
245
|
+
// only loses the reason, so the body counts as read and the retry
|
|
246
|
+
// policy goes on (the same guard the moonshot bond applies).
|
|
247
|
+
signal.throwIfAborted();
|
|
248
|
+
logger.debug('OpenAI rejected response body could not be read', { error });
|
|
249
|
+
rejectedBody = '';
|
|
250
|
+
}
|
|
251
|
+
const upstreamError = parseUpstreamError(rejectedBody);
|
|
252
|
+
// Billing, spend, and quota failures do not recover by waiting: a
|
|
253
|
+
// bounded retry budget fails at once instead of burning its retries.
|
|
254
|
+
const quotaExhausted = this.quotaSemantics === 'openai' && isQuotaExhausted(response.status, upstreamError);
|
|
255
|
+
const willRetry = !quotaExhausted && attempt < MAX_RETRIES;
|
|
173
256
|
// Retry-After is equally-valid as delta-seconds or an HTTP-date;
|
|
174
257
|
// parseInt on the date form yields NaN, degrading the backoff to a
|
|
175
258
|
// ~0ms retry against an already rate-limiting API. Guard it.
|
|
@@ -192,6 +275,7 @@ export class OpenaiAIProvider {
|
|
|
192
275
|
willRetry,
|
|
193
276
|
retryInMs: delayMs,
|
|
194
277
|
...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
|
|
278
|
+
...(upstreamError ? { upstreamError } : {}),
|
|
195
279
|
});
|
|
196
280
|
}
|
|
197
281
|
catch (error) {
|
|
@@ -199,10 +283,13 @@ export class OpenaiAIProvider {
|
|
|
199
283
|
logger.warn('onRateLimit callback threw', { error });
|
|
200
284
|
}
|
|
201
285
|
if (willRetry) {
|
|
202
|
-
logger.warn(
|
|
286
|
+
logger.warn(quotaExhausted
|
|
287
|
+
? 'OpenAI account quota exhausted, retrying until recharged'
|
|
288
|
+
: 'OpenAI API rate limited, retrying', {
|
|
203
289
|
status: response.status,
|
|
204
290
|
attempt: attempt + 1,
|
|
205
291
|
delayMs,
|
|
292
|
+
...(upstreamError ? { upstreamError } : {}),
|
|
206
293
|
});
|
|
207
294
|
await new Promise((resolve) => {
|
|
208
295
|
const timer = setTimeout(resolve, delayMs);
|
|
@@ -219,7 +306,8 @@ export class OpenaiAIProvider {
|
|
|
219
306
|
break;
|
|
220
307
|
}
|
|
221
308
|
if (!response.ok) {
|
|
222
|
-
|
|
309
|
+
// A 429/503 body was already read by the retry loop; a body reads only once.
|
|
310
|
+
const errorBody = rejectedBody ?? (await response.text());
|
|
223
311
|
let detail = `HTTP ${response.status}`;
|
|
224
312
|
try {
|
|
225
313
|
const parsed = JSON.parse(errorBody);
|
|
@@ -232,18 +320,21 @@ export class OpenaiAIProvider {
|
|
|
232
320
|
detail = errorBody;
|
|
233
321
|
}
|
|
234
322
|
logger.error('OpenAI API error', { status: response.status, detail });
|
|
235
|
-
const clientMessage =
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
?
|
|
242
|
-
: response.status === 400
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
323
|
+
const clientMessage = this.quotaSemantics === 'openai' &&
|
|
324
|
+
isQuotaExhausted(response.status, parseUpstreamError(errorBody))
|
|
325
|
+
? 'AI service is unavailable right now. Please try again later.'
|
|
326
|
+
: response.status === 429
|
|
327
|
+
? 'AI rate limit exceeded. Please try again shortly.'
|
|
328
|
+
: response.status === 401
|
|
329
|
+
? 'AI service configuration error.'
|
|
330
|
+
: response.status === 400 &&
|
|
331
|
+
/context.*length|maximum context|too many tokens|prompt is too long/i.test(detail)
|
|
332
|
+
? "Conversation too long for the model's context window."
|
|
333
|
+
: response.status === 400
|
|
334
|
+
? 'AI request was invalid — check the model and request parameters.'
|
|
335
|
+
: response.status === 503 || response.status === 502
|
|
336
|
+
? 'AI service is temporarily overloaded. Please try again in a moment.'
|
|
337
|
+
: 'AI service error. Please try again.';
|
|
247
338
|
yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' };
|
|
248
339
|
return;
|
|
249
340
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -14,6 +14,15 @@ export interface OpenaiConfig {
|
|
|
14
14
|
maxTokens?: number;
|
|
15
15
|
/** Override the API base URL (for proxies / Azure). */
|
|
16
16
|
baseUrl?: string;
|
|
17
|
+
/**
|
|
18
|
+
* How the upstream uses OpenAI's documented 429 quota codes. `'openai'`
|
|
19
|
+
* treats them as exhausted billing/spend limits and stops without retrying;
|
|
20
|
+
* `'retryable'` treats them as ordinary throttling. Defaults to `'openai'`
|
|
21
|
+
* for `api.openai.com` and `*.openai.azure.com` (including explicit ports),
|
|
22
|
+
* and `'retryable'` for every other host. Set `'openai'` for a proxy that
|
|
23
|
+
* forwards OpenAI or Azure OpenAI quota failures unchanged.
|
|
24
|
+
*/
|
|
25
|
+
quotaSemantics?: 'openai' | 'retryable';
|
|
17
26
|
/** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
|
|
18
27
|
onRateLimit?: AiRateLimitCallback;
|
|
19
28
|
/**
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,kBAAkB,CAAA;AAExD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAA;IACtB,yGAAyG;IACzG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;IACvC,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,qDAAqD;AACrD,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,kBAAkB,CAAA;AAExD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAA;IACtB,yGAAyG;IACzG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-ai-openai",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.1",
|
|
4
4
|
"description": "",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/api-ai-openai",
|
|
6
6
|
"type": "module",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
"directory": "packages/api/bonds/ai/openai"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@molecule/api-ai": "1.
|
|
37
|
-
"@molecule/api-bond": "1.0.
|
|
36
|
+
"@molecule/api-ai": "1.5.0",
|
|
37
|
+
"@molecule/api-bond": "1.0.4",
|
|
38
38
|
"@types/node": "26.6.5",
|
|
39
39
|
"typescript": "6.0.3",
|
|
40
40
|
"vitest": "4.1.12"
|