@molecule/api-ai 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 +551 -0
  2. package/package.json +7 -6
package/README.md ADDED
@@ -0,0 +1,551 @@
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:26.375Z
7
+ -->
8
+
9
+ # @molecule/api-ai
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
+ Model-agnostic AI chat interface for molecule.dev.
16
+
17
+ Defines the `AIProvider` interface that bond packages (Anthropic, OpenAI, etc.)
18
+ implement, plus types for messages, streaming events, tool use, and token usage.
19
+
20
+ ## Quick Start
21
+
22
+ ```typescript
23
+ import { requireProvider } from '@molecule/api-ai'
24
+ import type { ChatParams } from '@molecule/api-ai'
25
+
26
+ const ai = requireProvider()
27
+ const params: ChatParams = {
28
+ messages: [{ role: 'user', content: 'Hello!' }],
29
+ stream: true,
30
+ }
31
+ let reply = ''
32
+ for await (const event of ai.chat(params)) {
33
+ if (event.type === 'text') reply += event.content // or forward the chunk to the client (SSE)
34
+ }
35
+ console.log(reply)
36
+ ```
37
+
38
+ ## Type
39
+
40
+ `core`
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ npm install @molecule/api-ai @molecule/api-bond @molecule/api-i18n
46
+ ```
47
+
48
+ ## API
49
+
50
+ ### Interfaces
51
+
52
+ #### `AIConfig`
53
+
54
+ AI provider configuration.
55
+
56
+ ```typescript
57
+ interface AIConfig {
58
+ /** Default model to use when not specified in ChatParams. */
59
+ defaultModel?: string
60
+ /** Maximum tokens for completions. */
61
+ maxTokens?: number
62
+ /** Default temperature. */
63
+ temperature?: number
64
+ }
65
+ ```
66
+
67
+ #### `AIProvider`
68
+
69
+ AI provider interface.
70
+
71
+ Each bond package (Anthropic, OpenAI, Gemini, etc.) implements
72
+ this interface to provide model-specific chat functionality.
73
+
74
+ ```typescript
75
+ interface AIProvider {
76
+ readonly name: string
77
+
78
+ /**
79
+ * Send a chat request and stream back events.
80
+ *
81
+ * Returns an async iterable of ChatEvent objects.
82
+ * Always yields a final 'done' event with token usage.
83
+ * @returns An async iterable that yields `ChatEvent` objects (text chunks, tool calls, done, or error).
84
+ */
85
+ chat(params: ChatParams): AsyncIterable<ChatEvent>
86
+ }
87
+ ```
88
+
89
+ #### `AiRateLimitEvent`
90
+
91
+ Details of one rate-limited or overloaded upstream response, reported via a
92
+ provider config's `onRateLimit` callback each time the provider receives an
93
+ HTTP 429/503 (or a provider-specific overload status such as Anthropic's
94
+ 529), before any retry sleep. This surfaces the hits the provider's internal
95
+ retry loop goes on to recover — the early-warning signal that capacity is
96
+ running out, which a terminal error event alone would miss entirely.
97
+
98
+ ```typescript
99
+ interface AiRateLimitEvent {
100
+ /** Provider name (e.g. 'anthropic'). */
101
+ provider: string
102
+ /** Model the rejected request targeted. */
103
+ model: string
104
+ /** HTTP status the upstream returned (429, 503, or 529). */
105
+ status: number
106
+ /** 1-based attempt number that was rejected. */
107
+ attempt: number
108
+ /** Whether the provider will retry this request again after a delay. */
109
+ willRetry: boolean
110
+ /** Delay before the next retry in milliseconds; 0 when `willRetry` is false. */
111
+ retryInMs: number
112
+ /** The response's parsed `Retry-After` header in seconds, when present and valid. */
113
+ retryAfterSeconds?: number
114
+ }
115
+ ```
116
+
117
+ #### `AITool`
118
+
119
+ Tool definition that the AI model can invoke.
120
+
121
+ ```typescript
122
+ interface AITool {
123
+ name: string
124
+ description: string
125
+ parameters: JSONSchema
126
+ execute: (input: unknown) => Promise<unknown>
127
+ }
128
+ ```
129
+
130
+ #### `ChatMessage`
131
+
132
+ Chat message in a conversation.
133
+
134
+ ```typescript
135
+ interface ChatMessage {
136
+ role: 'user' | 'assistant' | 'system'
137
+ content: string | ContentBlock[]
138
+ /**
139
+ * Model-native reasoning text produced alongside this (assistant) message —
140
+ * e.g. an OpenAI-compatible provider's `reasoning_content`. Some providers
141
+ * (Moonshot's Kimi K3 / k2.7-code and other preserved-thinking models)
142
+ * require it to be replayed verbatim on subsequent requests within a
143
+ * tool-call loop to keep reasoning continuity; callers that captured
144
+ * `thinking` stream events should set it when rebuilding history. Bonds
145
+ * whose provider has no such requirement ignore it.
146
+ */
147
+ reasoning?: string
148
+ }
149
+ ```
150
+
151
+ #### `ChatParams`
152
+
153
+ Parameters for a chat call.
154
+
155
+ ```typescript
156
+ interface ChatParams {
157
+ messages: ChatMessage[]
158
+ tools?: AITool[]
159
+ /** Provider-native server tools (e.g. web search) — executed by the provider, not the caller. */
160
+ serverTools?: ServerTool[]
161
+ system?: string
162
+ stream?: boolean
163
+ maxTokens?: number
164
+ temperature?: number
165
+ model?: string
166
+ /**
167
+ * Enable extended thinking / reasoning on models that support it.
168
+ *
169
+ * `budgetTokens` is the abstract reasoning budget; bonds without a native
170
+ * token-budget param translate it (e.g. via thresholds) into their provider's
171
+ * control. `effort` — when present — is the PROVIDER-NATIVE effort value for
172
+ * the active model, resolved by the caller from the model catalog (the model's
173
+ * own `supportedEffortLevels`), e.g. Anthropic `output_config.effort`
174
+ * (`'low' | 'medium' | 'high' | 'xhigh' | 'max'`) or an OpenAI-compatible
175
+ * `reasoning_effort`. Bonds MUST prefer `effort` over
176
+ * `budgetTokens` when set: on current Anthropic models (Fable 5 / Opus 4.8 /
177
+ * Sonnet 5) a raw `budget_tokens` request is rejected with a 400 — adaptive
178
+ * thinking + effort is the only control.
179
+ */
180
+ thinking?: { type: 'enabled'; budgetTokens: number; effort?: string }
181
+ /**
182
+ * Request the provider's fast/priority speed tier for this call (e.g.
183
+ * Anthropic's `speed: "fast"` — same model, faster output, premium pricing).
184
+ *
185
+ * Callers should only set `'fast'` for models whose catalog entry declares
186
+ * `fastPricing` (that field is the capability flag). Bonds whose provider has
187
+ * no speed tier ignore it. Bonds that support it MUST report the speed the
188
+ * provider says the request actually ran at in `TokenUsage.speed`, so
189
+ * metering prices the served tier, not the requested one. No automatic
190
+ * fallback is performed here: a fast-tier rate limit surfaces as a normal
191
+ * error/retry, and the caller decides whether to drop back to standard.
192
+ */
193
+ speed?: 'standard' | 'fast'
194
+ /** Enable prompt caching. Providers that support it will cache system prompts and tools. */
195
+ cacheControl?: { type: 'ephemeral' }
196
+ /** Abort signal to cancel in-flight API requests when the client disconnects. */
197
+ signal?: AbortSignal
198
+ /**
199
+ * Control whether the model must call a tool. 'auto' (default) lets the model
200
+ * decide; 'required' forces at least one tool call (any tool); `{ type: 'tool',
201
+ * name }` forces that ONE specific tool — stronger than 'required', which only
202
+ * guarantees *some* tool and can let the model drift to a different one when the
203
+ * conversation history is biased toward it.
204
+ */
205
+ toolChoice?: 'auto' | 'required' | { type: 'tool'; name: string }
206
+ /**
207
+ * Opaque, stable identifier for the END USER on whose behalf this request is
208
+ * made — forwarded to providers that accept one (Anthropic `metadata.user_id`,
209
+ * OpenAI-compatible `user`).
210
+ *
211
+ * This is an ABUSE-ATTRIBUTION control, and it is the difference between a
212
+ * provider suspending one account and suspending your organization's key. With
213
+ * nothing sent, every request from every tenant is indistinguishable from the
214
+ * platform itself, so the only enforcement action available to the provider is
215
+ * against the key that serves all of them.
216
+ *
217
+ * It MUST be opaque — a hash/uuid, never an email, name, phone or anything else
218
+ * that identifies a person to the provider — and it MUST be stable per user, so
219
+ * a repeat offender is recognizable across sessions. Callers are expected to
220
+ * derive it (e.g. an HMAC of their internal user id) and to keep the mapping on
221
+ * their side so an abuse report naming this value can be traced back.
222
+ *
223
+ * Bonds whose provider has no equivalent field ignore it.
224
+ */
225
+ endUserId?: string
226
+ }
227
+ ```
228
+
229
+ #### `JSONSchema`
230
+
231
+ JSON Schema subset for tool parameter definitions.
232
+
233
+ ```typescript
234
+ interface JSONSchema {
235
+ type: string
236
+ properties?: Record<string, JSONSchema>
237
+ items?: JSONSchema
238
+ required?: string[]
239
+ description?: string
240
+ enum?: unknown[]
241
+ [key: string]: unknown
242
+ }
243
+ ```
244
+
245
+ #### `ServerTool`
246
+
247
+ Provider-native tool handled server-side (e.g., Anthropic's `web_search`).
248
+
249
+ Unlike `AITool`, server tools are executed by the AI provider itself —
250
+ no client-side `execute` callback is needed. The provider passes them
251
+ through to the API alongside custom tools.
252
+
253
+ ```typescript
254
+ interface ServerTool {
255
+ /**
256
+ * Provider-specific tool type identifier — a VERSIONED string the provider
257
+ * publishes (e.g. Anthropic's `"web_search_20260209"` on current models;
258
+ * older models use earlier variants like `"web_search_20250305"`). Copy the
259
+ * exact value from the provider's docs for the model in use.
260
+ */
261
+ type: string
262
+ /** Tool name. */
263
+ name: string
264
+ /** Allow additional provider-specific fields (max_uses, etc.). */
265
+ [key: string]: unknown
266
+ }
267
+ ```
268
+
269
+ #### `TokenUsage`
270
+
271
+ Token usage from a chat completion.
272
+
273
+ ```typescript
274
+ interface TokenUsage {
275
+ inputTokens: number
276
+ outputTokens: number
277
+ /** Number of input tokens written to the prompt cache. */
278
+ cacheCreationInputTokens?: number
279
+ /** Number of input tokens read from the prompt cache. */
280
+ cacheReadInputTokens?: number
281
+ /**
282
+ * The speed tier the provider REPORTS the request ran at (Anthropic wires it
283
+ * as `usage.speed` per the fast-mode docs, and as `usage.service_tier` on
284
+ * observed live responses — bonds read both). Only set by bonds whose
285
+ * provider has a fast/priority tier — absent means unreported. Metering
286
+ * prefers THIS field over the requested `ChatParams.speed`; when a
287
+ * fast-requested turn succeeds with no report, callers may conservatively
288
+ * bill the requested tier (Anthropic enforces fast-mode entitlement with a
289
+ * hard 429, so a successful fast request was served fast).
290
+ */
291
+ speed?: 'standard' | 'fast'
292
+ }
293
+ ```
294
+
295
+ ### Types
296
+
297
+ #### `AiRateLimitCallback`
298
+
299
+ Callback invoked on each rate-limited/overloaded upstream response. Must not
300
+ throw (providers guard it anyway); keep it fast — it runs on the request path.
301
+
302
+ ```typescript
303
+ type AiRateLimitCallback = (event: AiRateLimitEvent) => void
304
+ ```
305
+
306
+ #### `ChatEvent`
307
+
308
+ Streaming event from an AI chat call.
309
+
310
+ ```typescript
311
+ type ChatEvent =
312
+ | { type: 'text'; content: string }
313
+ | { type: 'thinking'; content: string }
314
+ | { type: 'tool_use'; id: string; name: string; input: unknown }
315
+ // Emitted as soon as the model BEGINS a tool call — id + name are known but the
316
+ // input is still streaming. Lets consumers show what's happening immediately
317
+ // (e.g. "Writing the plan") instead of staring at a frozen spinner for the
318
+ // seconds-to-minutes it takes to generate a large tool input (a file, a plan).
319
+ | { type: 'tool_use_start'; id: string; name: string }
320
+ // Progress for a tool call's input as the model streams its arguments:
321
+ // `chars` is the number of input characters in this chunk. Carries real
322
+ // progress (re-arms the stream-progress timeout; ticks the UI's live token
323
+ // estimate) where previously these chunks produced only `keep_alive` (no
324
+ // content) — the root cause of the dead loading indicator while a big tool
325
+ // input was being written. `chars` is a COUNT, not the full content (the UI
326
+ // only needs the magnitude, and forwarding the whole input would duplicate the
327
+ // final `tool_use`). `text` is the raw partial-JSON CHUNK for this delta —
328
+ // consumed SERVER-SIDE only (a coalescing consumer accumulates it to extract a
329
+ // few short display fields, e.g. the file `path`, so the UI can label the
330
+ // in-flight tool card before the args finish). It is never echoed wholesale to
331
+ // the client. Optional so non-streaming/legacy providers can omit it.
332
+ | { type: 'tool_input_delta'; id: string; chars: number; text?: string }
333
+ // Incremental usage SNAPSHOT — the provider's own token counts as reported so
334
+ // far on the wire (e.g. Anthropic's message_start carries the full input +
335
+ // cache token counts before any output streams). LATEST WINS; `done.usage`
336
+ // remains the authoritative final figure. METERING CONTRACT: consumers MUST
337
+ // retain the latest snapshot and book it when a stream ends WITHOUT a `done`
338
+ // (client abort, disconnect, progress timeout, provider error) — the upstream
339
+ // provider bills those tokens even though the stream was cut, and dropping
340
+ // them silently under-meters real spend. Providers whose wire protocol only
341
+ // reports usage at stream end (OpenAI-compatible `include_usage`) cannot emit
342
+ // mid-stream snapshots; consumers must estimate aborted turns for those.
343
+ | { type: 'usage'; usage: TokenUsage }
344
+ | { type: 'done'; usage: TokenUsage }
345
+ | { type: 'error'; message: string; errorKey?: string }
346
+ // Liveness signal. PROVIDER CONTRACT: every streaming provider MUST yield
347
+ // `keep_alive` whenever it receives data from the upstream API that produces
348
+ // no other ChatEvent — e.g. an SSE ping/keepalive, an empty delta, or buffered
349
+ // tool-input/argument chunks streaming in. Consumers use a (long) inter-event
350
+ // timeout to detect a dead stream; without keep_alive that timeout false-fires
351
+ // while the model is alive but producing only silent chunks (e.g. streaming a
352
+ // large tool input). Not forwarded to end clients. Enforced by the provider
353
+ // conformance test in this package's __tests__.
354
+ | { type: 'keep_alive' }
355
+ ```
356
+
357
+ #### `ContentBlock`
358
+
359
+ Rich content block within a message.
360
+
361
+ Includes text, tool interactions, and file attachments (images, documents,
362
+ audio, video). Provider bonds map these generic blocks to their native API
363
+ format (e.g., Anthropic base64 source, OpenAI image_url, etc.).
364
+
365
+ ```typescript
366
+ type ContentBlock =
367
+ | { type: 'text'; text: string }
368
+ | { type: 'image'; mediaType: string; data: string }
369
+ | { type: 'document'; mediaType: string; data: string; filename?: string }
370
+ | { type: 'audio'; mediaType: string; data: string }
371
+ | { type: 'video'; mediaType: string; data: string }
372
+ | { type: 'tool_use'; id: string; name: string; input: unknown }
373
+ | { type: 'tool_result'; tool_use_id: string; content: string | unknown }
374
+ ```
375
+
376
+ ### Functions
377
+
378
+ #### `getAllProviders()`
379
+
380
+ Retrieves all named AI providers as a Map keyed by provider name.
381
+
382
+ ```typescript
383
+ function getAllProviders(): Map<string, AIProvider>
384
+ ```
385
+
386
+ **Returns:** Map of provider name → AIProvider.
387
+
388
+ #### `getProvider()`
389
+
390
+ Retrieves the singleton AI provider, or `null` if none is bonded.
391
+
392
+ Falls back to a single named provider when no singleton is bonded —
393
+ this lets apps that wire `bond('ai', 'anthropic', provider)` directly
394
+ (without going through `setProvider`'s singleton-fallback) still work
395
+ with code that uses the simple `getProvider()` / `requireProvider()`
396
+ accessors. When multiple named providers are bonded, the fallback
397
+ declines (returns `null`) because the choice is ambiguous — those
398
+ call sites must use `getProviderByName(name)` explicitly.
399
+
400
+ This also applies to an auto-promoted singleton: `setProvider('a', p1)`
401
+ followed by `setProvider('b', p2)` does NOT leave `getProvider()` stuck
402
+ returning `p1` forever — once `'b'` is registered the pick is genuinely
403
+ ambiguous and `getProvider()` declines (`null`), same as if neither had
404
+ been auto-promoted. An explicit `setProvider(provider)` singleton is
405
+ unaffected by how many named providers exist.
406
+
407
+ ```typescript
408
+ function getProvider(): AIProvider | null
409
+ ```
410
+
411
+ **Returns:** The bonded AI provider, or `null`.
412
+
413
+ #### `getProviderByName(name)`
414
+
415
+ Retrieves a named AI provider, or `null` if not bonded.
416
+
417
+ ```typescript
418
+ function getProviderByName(name: string): AIProvider | null
419
+ ```
420
+
421
+ - `name` — The provider name (e.g. `'anthropic'`, `'xai'`).
422
+
423
+ **Returns:** The named AI provider, or `null`.
424
+
425
+ #### `hasProvider(name)`
426
+
427
+ Checks whether an AI provider is currently bonded.
428
+
429
+ ```typescript
430
+ function hasProvider(name?: string): boolean
431
+ ```
432
+
433
+ - `name` — Optional provider name. If omitted, checks the singleton.
434
+
435
+ **Returns:** `true` if the provider is bonded.
436
+
437
+ #### `requireProvider()`
438
+
439
+ Retrieves the bonded AI provider, throwing if none is bonded.
440
+ Use this when AI functionality is required.
441
+
442
+ Routes through the same resolution as `getProvider()` so the single-named-
443
+ bond fallback applies — apps that wire `bond('ai', 'anthropic', provider)`
444
+ directly still satisfy this call without having to switch to the explicit
445
+ `getProviderByName()` pattern. When resolution declined because MULTIPLE
446
+ named providers are bonded with no explicit singleton, the thrown message
447
+ says so (distinct from "nothing bonded at all") and points at
448
+ `getProviderByName()`.
449
+
450
+ ```typescript
451
+ function requireProvider(): AIProvider
452
+ ```
453
+
454
+ **Returns:** The bonded AI provider.
455
+
456
+ #### `setProvider(provider)`
457
+
458
+ Registers an AI provider in singleton mode.
459
+
460
+ - **Singleton**: `setProvider(provider)` — bonds a single default provider.
461
+
462
+ ```typescript
463
+ function setProvider(provider: AIProvider): void
464
+ ```
465
+
466
+ - `provider` — The default provider implementation for this process.
467
+
468
+ ## Available Providers
469
+
470
+ | Provider | Package |
471
+ | ------------ | ---------------------------- |
472
+ | Alibaba Qwen | `@molecule/api-ai-alibaba` |
473
+ | Anthropic | `@molecule/api-ai-anthropic` |
474
+ | Ai | `@molecule/api-ai-deepseek` |
475
+ | Ai | `@molecule/api-ai-google` |
476
+ | Ai | `@molecule/api-ai-local` |
477
+ | MiniMax | `@molecule/api-ai-minimax` |
478
+ | Moonshot | `@molecule/api-ai-moonshot` |
479
+ | Ai | `@molecule/api-ai-openai` |
480
+ | xAI | `@molecule/api-ai-xai` |
481
+ | Zhipu GLM | `@molecule/api-ai-zhipu` |
482
+
483
+ ## Injection Notes
484
+
485
+ ### Requirements
486
+
487
+ Peer dependencies:
488
+
489
+ - `@molecule/api-bond` ^1.0.1
490
+ - `@molecule/api-i18n` ^1.0.1
491
+
492
+ ### Runtime Dependencies
493
+
494
+ - `@molecule/api-bond`
495
+ - `@molecule/api-i18n`
496
+
497
+ The AI provider is a SERVER-side integration — a weak integration leaks the key, trusts
498
+ the model, or gets billed:
499
+
500
+ - **The provider API key is SERVER-ONLY.** Call `chat()` from YOUR API and stream results
501
+ to the browser (SSE); NEVER put the AI key in the frontend or call the provider directly
502
+ from the browser — the key would ship to every user.
503
+ - **Never blindly trust model output.** Treat anything the model returns — code, SQL, a
504
+ shell command, a URL, a tool-call argument — as UNTRUSTED input: validate/whitelist it,
505
+ run it only in a sandbox, and re-check permissions server-side. User/content text in the
506
+ prompt can hijack the model (prompt injection), so model output must never directly
507
+ trigger a privileged action (delete, pay, email, exec) without your own authorization +
508
+ validation.
509
+ - **Gate + budget it.** Require auth and rate-limit AI endpoints and cap `maxTokens` — an
510
+ open, unauthenticated AI route is an unbounded bill.
511
+ - `chat()` returns an async iterable of `ChatEvent` (text chunks, tool calls, a final
512
+ `done` with usage) — iterate it and forward chunks to the client.
513
+ - **`setProvider(name, provider)` ambiguity:** the FIRST named provider you register also
514
+ auto-promotes to the singleton (so plain `getProvider()`/`requireProvider()` work without
515
+ the caller knowing the name) — but that promotion is a single-provider convenience, not a
516
+ permanent pick. The moment a SECOND, differently-named provider is registered,
517
+ `getProvider()` stops returning the first one and declines (`null`) instead —
518
+ `requireProvider()` throws pointing at `getProviderByName(name)`. Call the explicit
519
+ `setProvider(provider)` (no name) form if you want one provider to always win regardless of
520
+ how many named providers you also register.
521
+
522
+ ## E2E Tests
523
+
524
+ Integration checklist — drive the real UI (live preview, no mocks), adapt
525
+ each item to this app's actual chat/AI screens, and check every box off one
526
+ by one. A box you can't check is an integration bug to fix — not a skip. The
527
+ sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
528
+ output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
529
+
530
+ - [ ] A message sent through the real chat UI comes back as a RELEVANT AI
531
+ reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
532
+ Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
533
+ the response actually contains it ("4"), proving a live model answered.
534
+ - [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
535
+ word in the UI, not one final blob dumped after a long frozen spinner. (A
536
+ streamed `chat()` yields `text` chunks then a final `done`; a single late
537
+ blob means the reply was awaited whole and streaming is broken.)
538
+ - [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
539
+ 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
540
+ line.
541
+ - [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
542
+ a graceful in-UI error message, NOT a crash, blank screen, a spinner that
543
+ never resolves, or an unhandled 500. Force one and watch the UI recover.
544
+ - [ ] The provider key + the provider call are SERVER-side only: the key
545
+ never reaches the browser (check the network tab, the JS bundle, and page
546
+ globals), and no route proxies arbitrary prompts to the model without auth
547
+ - a token cap — an open AI endpoint is an unbounded bill and abuse vector.
548
+
549
+ ## Translations
550
+
551
+ Translation strings are provided by `@molecule/api-locales-ai`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Model-agnostic AI provider interface with streaming chat and tool use",
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",
@@ -28,12 +29,12 @@
28
29
  ],
29
30
  "license": "Apache-2.0",
30
31
  "peerDependencies": {
31
- "@molecule/api-bond": "^1.0.0",
32
- "@molecule/api-i18n": "^1.0.0"
32
+ "@molecule/api-bond": "^1.0.1",
33
+ "@molecule/api-i18n": "^1.0.1"
33
34
  },
34
35
  "devDependencies": {
35
- "@molecule/api-bond": "1.0.0",
36
- "@molecule/api-i18n": "1.0.0",
36
+ "@molecule/api-bond": "1.0.1",
37
+ "@molecule/api-i18n": "1.0.1",
37
38
  "@types/node": "26.1.2",
38
39
  "typescript": "6.0.3",
39
40
  "vitest": "4.1.10"