@molecule/api-ai-local 1.0.7 → 1.0.9

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 +30 -34
  2. package/package.json +4 -4
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-10-16T23:28:28.190Z
6
+ Generated: 2026-11-13T19:22:13.503Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-ai-local
@@ -97,9 +97,6 @@ class LocalAIProvider implements AIProvider {
97
97
  private onRateLimit?: AiRateLimitCallback
98
98
 
99
99
  constructor(config: LocalConfig = {}) {
100
- // Keyless by default — many local servers ignore auth. Empty string means
101
- // "no key", so no Authorization header is sent. NEVER throws for a missing
102
- // key at construction.
103
100
  this.apiKey = config.apiKey ?? process.env.LOCAL_AI_API_KEY ?? ''
104
101
  this.defaultModel = config.model ?? process.env.LOCAL_AI_MODEL ?? DEFAULT_MODEL
105
102
  this.maxTokens = DEFAULT_MAX_TOKENS
@@ -111,12 +108,6 @@ class LocalAIProvider implements AIProvider {
111
108
  DEFAULT_BASE_URL
112
109
  }
113
110
 
114
- /**
115
- * Send a chat request and yield streamed `ChatEvent`s.
116
- *
117
- * @param params - Chat parameters.
118
- * @yields {ChatEvent}
119
- */
120
111
  async *chat(params: ChatParams): AsyncIterable<ChatEvent> {
121
112
  const model = params.model ?? this.defaultModel
122
113
  const maxTokens = params.maxTokens ?? this.maxTokens
@@ -124,10 +115,6 @@ class LocalAIProvider implements AIProvider {
124
115
  const messages = this.formatMessages(params.messages, params.system)
125
116
 
126
117
  const body: Record<string, unknown> = {
127
- // Abuse attribution (see ChatParams.endUserId): OpenAI-compatible APIs
128
- // scope enforcement by `user`, so an abusive tenant can be actioned
129
- // individually instead of the org key that serves everyone. The value is
130
- // the caller's opaque hash — never derived or logged here.
131
118
  ...(params.endUserId ? { user: params.endUserId } : {}),
132
119
  model,
133
120
  messages,
@@ -135,9 +122,6 @@ class LocalAIProvider implements AIProvider {
135
122
  }
136
123
  if (params.temperature !== undefined) body.temperature = params.temperature
137
124
 
138
- // Reasoning depth: the caller resolves the model's native reasoning_effort
139
- // value from the model catalog and passes it as `thinking.effort`. Local
140
- // servers that don't support it typically ignore an unknown field.
141
125
  if (params.thinking?.effort) {
142
126
  body.reasoning_effort = params.thinking.effort
143
127
  }
@@ -158,8 +142,6 @@ class LocalAIProvider implements AIProvider {
158
142
  body.stream_options = { include_usage: true }
159
143
  }
160
144
 
161
- // Per-call correlation (see ChatParams.requestId): a header rather than the
162
- // body's `user`, the stable per-account abuse-attribution value.
163
145
  const requestId = params.requestId ?? randomUUID()
164
146
  const call: LocalCallContext = {
165
147
  meta: { requestId, endpoint: this.baseUrl },
@@ -170,7 +152,6 @@ class LocalAIProvider implements AIProvider {
170
152
  'Content-Type': 'application/json',
171
153
  'X-Mol-Request-Id': requestId,
172
154
  }
173
- // Only authenticate when a key is configured — local servers are keyless.
174
155
  if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`
175
156
 
176
157
  const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000
@@ -191,15 +172,10 @@ class LocalAIProvider implements AIProvider {
191
172
 
192
173
  if (response.status === 429 || response.status === 503) {
193
174
  const willRetry = attempt < MAX_RETRIES
194
- // Retry-After is equally-valid as delta-seconds or an HTTP-date;
195
- // parseInt on the date form yields NaN, degrading the backoff to
196
- // a ~0ms retry against an already-busy local endpoint. Guard it.
197
175
  const retryAfter = response.headers.get('retry-after')
198
176
  const parsedRetryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN
199
177
  const hasRetryAfter =
200
178
  Number.isFinite(parsedRetryAfterSeconds) && parsedRetryAfterSeconds >= 0
201
- // Additive jitter (<500ms): concurrent callers rejected together must
202
- // not sleep identical delays and re-arrive as the same burst.
203
179
  const delayMs = willRetry
204
180
  ? (hasRetryAfter
205
181
  ? Math.min(parsedRetryAfterSeconds * 1000, 60_000)
@@ -216,7 +192,6 @@ class LocalAIProvider implements AIProvider {
216
192
  ...(hasRetryAfter ? { retryAfterSeconds: parsedRetryAfterSeconds } : {}),
217
193
  })
218
194
  } catch (error) {
219
- // Host-app telemetry; its failure must never break the request.
220
195
  logger.warn('onRateLimit callback threw', { error })
221
196
  }
222
197
  if (willRetry) {
@@ -250,7 +225,6 @@ class LocalAIProvider implements AIProvider {
250
225
  const parsed = JSON.parse(errorBody) as { error?: { message?: string } }
251
226
  if (parsed.error?.message) detail = parsed.error.message
252
227
  } catch (_error) {
253
- // Best-effort: detail already has an HTTP-status fallback; malformed body just stays as-is.
254
228
  if (errorBody.length > 0 && errorBody.length < 200) detail = errorBody
255
229
  }
256
230
  logger.error('Local AI endpoint error', { status: response!.status, url, detail })
@@ -271,15 +245,37 @@ class LocalAIProvider implements AIProvider {
271
245
  : response!.status === 503 || response!.status === 502
272
246
  ? 'AI service is temporarily overloaded. Please try again in a moment.'
273
247
  : 'AI service error. Please try again.'
274
- // Non-OK is a soft failure surfaced as an in-band error EVENT then a
275
- // graceful return — matching the 8 sibling providers. molecule-dev's
276
- // chat-handler consumes this via its `case 'error':` branch, which is a
277
- // different path from its outer try/catch; throwing here would break
278
- // that consumer contract.
279
248
  yield { type: 'error', message: clientMessage, errorKey: 'ai.error.apiError' }
280
- // … truncated — the full declaration is in node_modules/@molecule/api-ai-local/dist/provider.d.ts
249
+ return
250
+ }
251
+
252
+ if (!useStream) {
253
+ const data = (await response!.json()) as Record<string, unknown>
254
+ yield* this.parseNonStreamingResponse(data)
255
+ return
256
+ }
257
+
258
+ const traceId =
259
+ response!.headers.get('x-request-id') ?? response!.headers.get('request-id') ?? undefined
260
+ if (traceId) call.meta.traceId = traceId
261
+
262
+ yield* this.parseStreamingResponse(response!, call)
263
+ } catch (error) {
264
+ if (signal.aborted) throw error
265
+ logger.error('Local AI endpoint request failed', { url, error })
266
+ yield {
267
+ type: 'error',
268
+ message: 'AI service error. Please try again.',
269
+ errorKey: 'ai.error.apiError',
270
+ }
271
+ return
272
+ }
273
+ }
274
+ // … truncated — 7 more members: formatMessages, formatBlock, formatTools, parseNonStreamingResponse, parseStreamingResponse, processSSELines, processToolCallDeltas; the full declaration is in node_modules/@molecule/api-ai-local/dist/provider.d.ts
281
275
  ```
282
276
 
277
+ _(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/api-ai-local/dist/provider.d.ts`.)_
278
+
283
279
  ### Functions
284
280
 
285
281
  #### `createProvider(config)`
@@ -337,7 +333,7 @@ export function setupAiLocal(): void {
337
333
 
338
334
  Peer dependencies:
339
335
 
340
- - `@molecule/api-ai` ^1.0.1
336
+ - `@molecule/api-ai` ^1.6.0
341
337
  - `@molecule/api-bond` ^1.0.1
342
338
  - `@molecule/api-i18n` ^1.0.1
343
339
  - `@molecule/api-secrets` ^1.0.1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-ai-local",
3
- "version": "1.0.7",
3
+ "version": "1.0.9",
4
4
  "description": "AIProvider bond for any OpenAI-compatible local inference server (Ollama, LM Studio, llama.cpp, vLLM) — configurable base URL, keyless by default, streamed via raw fetch.",
5
5
  "homepage": "https://www.molecule.dev/packages/api-ai-local",
6
6
  "type": "module",
@@ -33,15 +33,15 @@
33
33
  "directory": "packages/api/bonds/ai/local"
34
34
  },
35
35
  "devDependencies": {
36
- "@molecule/api-ai": "1.3.5",
37
- "@molecule/api-bond": "1.0.3",
36
+ "@molecule/api-ai": "1.6.0",
37
+ "@molecule/api-bond": "1.0.4",
38
38
  "@molecule/api-secrets": "1.0.2",
39
39
  "@types/node": "26.6.5",
40
40
  "typescript": "6.0.3",
41
41
  "vitest": "4.1.12"
42
42
  },
43
43
  "peerDependencies": {
44
- "@molecule/api-ai": "^1.0.1",
44
+ "@molecule/api-ai": "^1.6.0",
45
45
  "@molecule/api-bond": "^1.0.1",
46
46
  "@molecule/api-i18n": "^1.0.1",
47
47
  "@molecule/api-secrets": "^1.0.1"