@molecule/api-ai-openai 1.0.0 → 1.0.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.
Files changed (2) hide show
  1. package/README.md +176 -0
  2. 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-openai",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
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.0",
30
- "@molecule/api-bond": "1.0.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.0",
37
- "@molecule/api-bond": "^1.0.0",
38
- "@molecule/api-secrets": "^1.0.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": {