@molecule/api-ai-openai 1.0.0 → 1.0.2
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 +176 -0
- package/dist/provider.d.ts +18 -1
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +67 -10
- package/package.json +13 -7
package/README.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:47:34.951Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/api-ai-openai
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
OpenAI (GPT) AI provider for molecule.dev.
|
|
16
|
+
|
|
17
|
+
## Type
|
|
18
|
+
|
|
19
|
+
`provider`
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @molecule/api-ai-openai @molecule/api-ai @molecule/api-bond @molecule/api-secrets
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## API
|
|
28
|
+
|
|
29
|
+
### Interfaces
|
|
30
|
+
|
|
31
|
+
#### `OpenaiConfig`
|
|
32
|
+
|
|
33
|
+
OpenAI provider configuration.
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
interface OpenaiConfig {
|
|
37
|
+
/** Override the API key (defaults to `process.env.OPENAI_API_KEY`). */
|
|
38
|
+
apiKey?: string
|
|
39
|
+
/** Default model when callers don't specify one. */
|
|
40
|
+
defaultModel?: string
|
|
41
|
+
/** Default max output tokens. */
|
|
42
|
+
maxTokens?: number
|
|
43
|
+
/** Override the API base URL (for proxies / Azure). */
|
|
44
|
+
baseUrl?: string
|
|
45
|
+
/** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
|
|
46
|
+
onRateLimit?: AiRateLimitCallback
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
#### `ProcessEnv`
|
|
51
|
+
|
|
52
|
+
Environment variables read by this provider.
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
interface ProcessEnv {
|
|
56
|
+
/** OpenAI API key (required unless `config.apiKey` is passed). */
|
|
57
|
+
OPENAI_API_KEY: string
|
|
58
|
+
/** Base URL override (for proxies / Azure-compatible gateways). Defaults to `https://api.openai.com`. */
|
|
59
|
+
OPENAI_BASE_URL?: string
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Classes
|
|
64
|
+
|
|
65
|
+
#### `OpenaiAIProvider`
|
|
66
|
+
|
|
67
|
+
OpenAI Chat Completions provider implementing the `AIProvider` interface.
|
|
68
|
+
|
|
69
|
+
### Functions
|
|
70
|
+
|
|
71
|
+
#### `createProvider(config)`
|
|
72
|
+
|
|
73
|
+
Create an OpenAI AI provider instance.
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
function createProvider(config?: OpenaiConfig): AIProvider
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- `config` — OpenAI-specific configuration.
|
|
80
|
+
|
|
81
|
+
**Returns:** An `AIProvider` backed by OpenAI's Chat Completions API.
|
|
82
|
+
|
|
83
|
+
### Constants
|
|
84
|
+
|
|
85
|
+
#### `aiOpenaiSecretDefinitions`
|
|
86
|
+
|
|
87
|
+
Secret definitions required by the OpenAI AI bond.
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
const aiOpenaiSecretDefinitions: SecretDefinition[]
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
#### `provider`
|
|
94
|
+
|
|
95
|
+
The provider implementation.
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
const provider: AIProvider
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Core Interface
|
|
102
|
+
|
|
103
|
+
Implements `@molecule/api-ai` interface.
|
|
104
|
+
|
|
105
|
+
## Bond Wiring
|
|
106
|
+
|
|
107
|
+
Setup function to register this provider with the bond system:
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
import { bond } from '@molecule/api-bond'
|
|
111
|
+
import { provider } from '@molecule/api-ai-openai'
|
|
112
|
+
|
|
113
|
+
export function setupAiOpenai(): void {
|
|
114
|
+
bond('ai', 'openai', provider)
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Injection Notes
|
|
119
|
+
|
|
120
|
+
### Requirements
|
|
121
|
+
|
|
122
|
+
Peer dependencies:
|
|
123
|
+
|
|
124
|
+
- `@molecule/api-ai` ^1.0.1
|
|
125
|
+
- `@molecule/api-bond` ^1.0.1
|
|
126
|
+
- `@molecule/api-secrets` ^1.0.1
|
|
127
|
+
|
|
128
|
+
### Environment Variables
|
|
129
|
+
|
|
130
|
+
- `OPENAI_API_KEY` _(required)_ — OpenAI API key
|
|
131
|
+
- Setup: Create a secret key on the OpenAI platform (API keys page).
|
|
132
|
+
- Get it here: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
|
|
133
|
+
- Example: `sk-proj-...`
|
|
134
|
+
|
|
135
|
+
### Runtime Dependencies
|
|
136
|
+
|
|
137
|
+
- `@molecule/api-ai`
|
|
138
|
+
- `@molecule/api-bond`
|
|
139
|
+
- `@molecule/api-secrets`
|
|
140
|
+
|
|
141
|
+
Config: `OPENAI_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
|
|
142
|
+
|
|
143
|
+
**Missing `OPENAI_API_KEY` fails fast**: the provider throws naming the exact env var on
|
|
144
|
+
first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
|
|
145
|
+
not at bond/module-load time) — it never silently sends an empty key.
|
|
146
|
+
|
|
147
|
+
**Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
|
|
148
|
+
malformed tool schema) gets its own non-retryable message distinct from the generic
|
|
149
|
+
"AI service error. Please try again." used for retryable failures.
|
|
150
|
+
|
|
151
|
+
## E2E Tests
|
|
152
|
+
|
|
153
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
154
|
+
each item to this app's actual chat/AI screens, and check every box off one
|
|
155
|
+
by one. A box you can't check is an integration bug to fix — not a skip. The
|
|
156
|
+
sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
|
|
157
|
+
output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
|
|
158
|
+
|
|
159
|
+
- [ ] A message sent through the real chat UI comes back as a RELEVANT AI
|
|
160
|
+
reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
|
|
161
|
+
Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
|
|
162
|
+
the response actually contains it ("4"), proving a live model answered.
|
|
163
|
+
- [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
|
|
164
|
+
word in the UI, not one final blob dumped after a long frozen spinner. (A
|
|
165
|
+
streamed `chat()` yields `text` chunks then a final `done`; a single late
|
|
166
|
+
blob means the reply was awaited whole and streaming is broken.)
|
|
167
|
+
- [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
|
|
168
|
+
previous turn (e.g. after "2 + 2", ask "now double that" -> understood as 8) works — proving the full `messages` history is sent, not just the last
|
|
169
|
+
line.
|
|
170
|
+
- [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
|
|
171
|
+
a graceful in-UI error message, NOT a crash, blank screen, a spinner that
|
|
172
|
+
never resolves, or an unhandled 500. Force one and watch the UI recover.
|
|
173
|
+
- [ ] The provider key + the provider call are SERVER-side only: the key
|
|
174
|
+
never reaches the browser (check the network tab, the JS bundle, and page
|
|
175
|
+
globals), and no route proxies arbitrary prompts to the model without auth
|
|
176
|
+
- a token cap — an open AI endpoint is an unbounded bill and abuse vector.
|
package/dist/provider.d.ts
CHANGED
|
@@ -31,9 +31,26 @@ export declare class OpenaiAIProvider implements AIProvider {
|
|
|
31
31
|
/**
|
|
32
32
|
* Convert internal `ChatMessage` objects to the OpenAI message format.
|
|
33
33
|
* The system prompt becomes a leading `{role:'system'}` message.
|
|
34
|
+
*
|
|
35
|
+
* `tool_use` and `tool_result` blocks are serialized STRUCTURALLY — a
|
|
36
|
+
* `tool_use` becomes an assistant message carrying `tool_calls`, a
|
|
37
|
+
* `tool_result` becomes its own `{role:'tool', tool_call_id, content}`
|
|
38
|
+
* message — exactly as the Chat Completions API requires and as the sibling
|
|
39
|
+
* OpenAI-compatible bonds (minimax/deepseek) already do. They used to be
|
|
40
|
+
* flattened to placeholder text (`[tool_result for <id>]`), which silently
|
|
41
|
+
* dropped every tool result: a multi-turn agentic loop fed the model empty
|
|
42
|
+
* placeholders, so at temperature 0 it re-emitted the same opening tool call
|
|
43
|
+
* forever and never finalized (observed 0/8 on gpt-5.6-luna in the
|
|
44
|
+
* starting-point selftest — the failure was this serialization, NOT the
|
|
45
|
+
* model). Single-shot text/vision requests are unaffected: they never carry
|
|
46
|
+
* these block types.
|
|
34
47
|
*/
|
|
35
48
|
private formatMessages;
|
|
36
|
-
/**
|
|
49
|
+
/**
|
|
50
|
+
* Map a generic content-part `ContentBlock` (text/image/document/audio/video)
|
|
51
|
+
* to OpenAI's content-part shape. `tool_use`/`tool_result` are handled
|
|
52
|
+
* structurally in {@link formatMessages} and never reach here.
|
|
53
|
+
*/
|
|
37
54
|
private formatBlock;
|
|
38
55
|
/** Convert internal `AITool` definitions to OpenAI's `tools` array. */
|
|
39
56
|
private formatTools;
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAc9C;;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;gBAE7B,MAAM,GAAE,YAAiB;IAkBrC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAsKzD
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,UAAU,EAGV,SAAS,EAET,UAAU,EAEX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAc9C;;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;gBAE7B,MAAM,GAAE,YAAiB;IAkBrC;;;;;OAKG;IACI,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC;IAsKzD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,cAAc;IA+DtB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IA6BnB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAE,yBAAyB;IA8ClC;;;;;OAKG;YACY,sBAAsB;IA4ErC;;;;;;OAMG;IACH,OAAO,CAAE,eAAe;CA0EzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,UAAU,CAEhE"}
|
package/dist/provider.js
CHANGED
|
@@ -200,6 +200,19 @@ export class OpenaiAIProvider {
|
|
|
200
200
|
/**
|
|
201
201
|
* Convert internal `ChatMessage` objects to the OpenAI message format.
|
|
202
202
|
* The system prompt becomes a leading `{role:'system'}` message.
|
|
203
|
+
*
|
|
204
|
+
* `tool_use` and `tool_result` blocks are serialized STRUCTURALLY — a
|
|
205
|
+
* `tool_use` becomes an assistant message carrying `tool_calls`, a
|
|
206
|
+
* `tool_result` becomes its own `{role:'tool', tool_call_id, content}`
|
|
207
|
+
* message — exactly as the Chat Completions API requires and as the sibling
|
|
208
|
+
* OpenAI-compatible bonds (minimax/deepseek) already do. They used to be
|
|
209
|
+
* flattened to placeholder text (`[tool_result for <id>]`), which silently
|
|
210
|
+
* dropped every tool result: a multi-turn agentic loop fed the model empty
|
|
211
|
+
* placeholders, so at temperature 0 it re-emitted the same opening tool call
|
|
212
|
+
* forever and never finalized (observed 0/8 on gpt-5.6-luna in the
|
|
213
|
+
* starting-point selftest — the failure was this serialization, NOT the
|
|
214
|
+
* model). Single-shot text/vision requests are unaffected: they never carry
|
|
215
|
+
* these block types.
|
|
203
216
|
*/
|
|
204
217
|
formatMessages(messages, systemPrompt) {
|
|
205
218
|
const out = [];
|
|
@@ -210,14 +223,62 @@ export class OpenaiAIProvider {
|
|
|
210
223
|
out.push({ role: 'system', content: typeof m.content === 'string' ? m.content : '' });
|
|
211
224
|
continue;
|
|
212
225
|
}
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
226
|
+
if (typeof m.content === 'string') {
|
|
227
|
+
out.push({ role: m.role, content: m.content });
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
const parts = [];
|
|
231
|
+
const toolCalls = [];
|
|
232
|
+
const toolResults = [];
|
|
233
|
+
for (const block of m.content) {
|
|
234
|
+
switch (block.type) {
|
|
235
|
+
case 'tool_use':
|
|
236
|
+
toolCalls.push({
|
|
237
|
+
id: block.id,
|
|
238
|
+
type: 'function',
|
|
239
|
+
function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
|
|
240
|
+
});
|
|
241
|
+
break;
|
|
242
|
+
case 'tool_result':
|
|
243
|
+
toolResults.push({
|
|
244
|
+
role: 'tool',
|
|
245
|
+
tool_call_id: block.tool_use_id,
|
|
246
|
+
content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
|
|
247
|
+
});
|
|
248
|
+
break;
|
|
249
|
+
default:
|
|
250
|
+
parts.push(this.formatBlock(block));
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
// Tool results are standalone `role:'tool'` messages. An assistant turn
|
|
254
|
+
// that made tool calls carries them on the message; a plain content
|
|
255
|
+
// message (text/image/…) is emitted as-is. These are mutually exclusive
|
|
256
|
+
// in practice (assistant emits tool_use, the next user turn the results).
|
|
257
|
+
if (toolResults.length > 0) {
|
|
258
|
+
for (const tr of toolResults)
|
|
259
|
+
out.push(tr);
|
|
260
|
+
}
|
|
261
|
+
else if (toolCalls.length > 0) {
|
|
262
|
+
out.push({
|
|
263
|
+
role: 'assistant',
|
|
264
|
+
content: parts.length > 0 ? parts : null,
|
|
265
|
+
tool_calls: toolCalls,
|
|
266
|
+
});
|
|
267
|
+
}
|
|
268
|
+
else {
|
|
269
|
+
out.push({
|
|
270
|
+
role: m.role,
|
|
271
|
+
content: parts.length === 1 && parts[0].type === 'text' ? parts[0].text : parts,
|
|
272
|
+
});
|
|
273
|
+
}
|
|
217
274
|
}
|
|
218
275
|
return out;
|
|
219
276
|
}
|
|
220
|
-
/**
|
|
277
|
+
/**
|
|
278
|
+
* Map a generic content-part `ContentBlock` (text/image/document/audio/video)
|
|
279
|
+
* to OpenAI's content-part shape. `tool_use`/`tool_result` are handled
|
|
280
|
+
* structurally in {@link formatMessages} and never reach here.
|
|
281
|
+
*/
|
|
221
282
|
formatBlock(block) {
|
|
222
283
|
switch (block.type) {
|
|
223
284
|
case 'text':
|
|
@@ -242,12 +303,8 @@ export class OpenaiAIProvider {
|
|
|
242
303
|
type: 'text',
|
|
243
304
|
text: `[Video attachment (${block.mediaType}) — not supported by this provider]`,
|
|
244
305
|
};
|
|
245
|
-
case 'tool_use':
|
|
246
|
-
return { type: 'text', text: `[tool_use ${block.name}]` };
|
|
247
|
-
case 'tool_result':
|
|
248
|
-
return { type: 'text', text: `[tool_result for ${block.tool_use_id}]` };
|
|
249
306
|
default:
|
|
250
|
-
return
|
|
307
|
+
return { type: 'text', text: '' };
|
|
251
308
|
}
|
|
252
309
|
}
|
|
253
310
|
/** Convert internal `AITool` definitions to OpenAI's `tools` array. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-ai-openai",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
}
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
|
-
"dist"
|
|
20
|
+
"dist",
|
|
21
|
+
"README.md"
|
|
21
22
|
],
|
|
22
23
|
"keywords": [
|
|
23
24
|
"molecule",
|
|
@@ -25,17 +26,22 @@
|
|
|
25
26
|
"openai"
|
|
26
27
|
],
|
|
27
28
|
"license": "Apache-2.0",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "https://github.com/molecule-dev/molecule.git",
|
|
32
|
+
"directory": "packages/api/bonds/ai/openai"
|
|
33
|
+
},
|
|
28
34
|
"devDependencies": {
|
|
29
|
-
"@molecule/api-ai": "1.0.
|
|
30
|
-
"@molecule/api-bond": "1.0.
|
|
35
|
+
"@molecule/api-ai": "1.0.1",
|
|
36
|
+
"@molecule/api-bond": "1.0.1",
|
|
31
37
|
"@types/node": "26.1.2",
|
|
32
38
|
"typescript": "6.0.3",
|
|
33
39
|
"vitest": "4.1.10"
|
|
34
40
|
},
|
|
35
41
|
"peerDependencies": {
|
|
36
|
-
"@molecule/api-ai": "^1.0.
|
|
37
|
-
"@molecule/api-bond": "^1.0.
|
|
38
|
-
"@molecule/api-secrets": "^1.0.
|
|
42
|
+
"@molecule/api-ai": "^1.0.1",
|
|
43
|
+
"@molecule/api-bond": "^1.0.1",
|
|
44
|
+
"@molecule/api-secrets": "^1.0.1"
|
|
39
45
|
},
|
|
40
46
|
"peerDependenciesMeta": {
|
|
41
47
|
"@molecule/api-ai": {
|