@molecule/api-ai-local 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 +168 -0
  2. package/package.json +15 -9
package/README.md ADDED
@@ -0,0 +1,168 @@
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:33.798Z
7
+ -->
8
+
9
+ # @molecule/api-ai-local
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
+ Local (OpenAI-compatible) ai-local provider for molecule.dev.
16
+
17
+ Streams chat completions from any local inference server that speaks the
18
+ OpenAI `chat/completions` protocol (Ollama, LM Studio, llama.cpp, vLLM),
19
+ keyless by default.
20
+
21
+ ## Type
22
+
23
+ `provider`
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ npm install @molecule/api-ai-local @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets
29
+ ```
30
+
31
+ ## API
32
+
33
+ ### Interfaces
34
+
35
+ #### `LocalConfig`
36
+
37
+ Local (OpenAI-compatible) provider configuration.
38
+
39
+ ```typescript
40
+ interface LocalConfig {
41
+ /** Called on each rate-limited/busy upstream response, before any retry sleep. */
42
+ onRateLimit?: AiRateLimitCallback
43
+ /**
44
+ * Base URL of the OpenAI-compatible endpoint, INCLUDING the version segment
45
+ * (e.g. `http://localhost:11434/v1`). Overrides `LOCAL_AI_BASE_URL` /
46
+ * `OLLAMA_BASE_URL`. Defaults to Ollama's `http://localhost:11434/v1`.
47
+ */
48
+ baseUrl?: string
49
+ /**
50
+ * Optional API key. Most local servers ignore auth; when omitted (and no
51
+ * `LOCAL_AI_API_KEY` env var is set) no `Authorization` header is sent.
52
+ */
53
+ apiKey?: string
54
+ /**
55
+ * Default model when a call doesn't specify one. Overrides `LOCAL_AI_MODEL`.
56
+ * Defaults to `llama3.1`.
57
+ */
58
+ model?: string
59
+ }
60
+ ```
61
+
62
+ ### Classes
63
+
64
+ #### `LocalAIProvider`
65
+
66
+ Local (OpenAI-compatible) chat provider implementing the `AIProvider`
67
+ interface. Mirrors `@molecule/api-ai-openai` so the same handler code can
68
+ dispatch to a local endpoint.
69
+
70
+ ### Functions
71
+
72
+ #### `createProvider(config)`
73
+
74
+ Create a local (OpenAI-compatible) AI provider instance.
75
+
76
+ Constructs WITHOUT requiring any secret — local endpoints run keyless.
77
+
78
+ ```typescript
79
+ function createProvider(config?: LocalConfig): AIProvider
80
+ ```
81
+
82
+ - `config` — Local provider configuration.
83
+
84
+ **Returns:** An `AIProvider` backed by an OpenAI-compatible local endpoint.
85
+
86
+ ### Constants
87
+
88
+ #### `aiLocalSecretDefinitions`
89
+
90
+ Optional secret/config overrides recognised by the local AI bond.
91
+
92
+ ```typescript
93
+ const aiLocalSecretDefinitions: SecretDefinition[]
94
+ ```
95
+
96
+ #### `provider`
97
+
98
+ The provider implementation. Constructs keyless — no secret required.
99
+
100
+ ```typescript
101
+ const provider: AIProvider
102
+ ```
103
+
104
+ ## Core Interface
105
+
106
+ Implements `@molecule/api-ai` interface.
107
+
108
+ ## Bond Wiring
109
+
110
+ Setup function to register this provider with the bond system:
111
+
112
+ ```typescript
113
+ import { bond } from '@molecule/api-bond'
114
+ import { provider } from '@molecule/api-ai-local'
115
+
116
+ export function setupAiLocal(): void {
117
+ bond('ai', 'local', provider)
118
+ }
119
+ ```
120
+
121
+ ## Injection Notes
122
+
123
+ ### Requirements
124
+
125
+ Peer dependencies:
126
+
127
+ - `@molecule/api-ai` ^1.0.1
128
+ - `@molecule/api-bond` ^1.0.1
129
+ - `@molecule/api-i18n` ^1.0.1
130
+ - `@molecule/api-secrets` ^1.0.1
131
+
132
+ ### Runtime Dependencies
133
+
134
+ - `@molecule/api-ai`
135
+ - `@molecule/api-bond`
136
+ - `@molecule/api-i18n`
137
+ - `@molecule/api-secrets`
138
+
139
+ **Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
140
+ malformed tool schema) gets its own non-retryable message distinct from the generic
141
+ "AI service error. Please try again." used for retryable failures.
142
+
143
+ ## E2E Tests
144
+
145
+ Integration checklist — drive the real UI (live preview, no mocks), adapt
146
+ each item to this app's actual chat/AI screens, and check every box off one
147
+ by one. A box you can't check is an integration bug to fix — not a skip. The
148
+ sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
149
+ output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
150
+
151
+ - [ ] A message sent through the real chat UI comes back as a RELEVANT AI
152
+ reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
153
+ Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
154
+ the response actually contains it ("4"), proving a live model answered.
155
+ - [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
156
+ word in the UI, not one final blob dumped after a long frozen spinner. (A
157
+ streamed `chat()` yields `text` chunks then a final `done`; a single late
158
+ blob means the reply was awaited whole and streaming is broken.)
159
+ - [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
160
+ 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
161
+ line.
162
+ - [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
163
+ a graceful in-UI error message, NOT a crash, blank screen, a spinner that
164
+ never resolves, or an unhandled 500. Force one and watch the UI recover.
165
+ - [ ] The provider key + the provider call are SERVER-side only: the key
166
+ never reaches the browser (check the network tab, the JS bundle, and page
167
+ globals), and no route proxies arbitrary prompts to the model without auth
168
+ - 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-local",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
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
  "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,19 +26,24 @@
25
26
  "local"
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/local"
33
+ },
28
34
  "devDependencies": {
29
- "@molecule/api-ai": "1.0.0",
30
- "@molecule/api-bond": "1.0.0",
31
- "@molecule/api-secrets": "1.0.0",
35
+ "@molecule/api-ai": "1.0.1",
36
+ "@molecule/api-bond": "1.0.1",
37
+ "@molecule/api-secrets": "1.0.1",
32
38
  "@types/node": "26.1.2",
33
39
  "typescript": "6.0.3",
34
40
  "vitest": "4.1.10"
35
41
  },
36
42
  "peerDependencies": {
37
- "@molecule/api-ai": "^1.0.0",
38
- "@molecule/api-bond": "^1.0.0",
39
- "@molecule/api-i18n": "^1.0.0",
40
- "@molecule/api-secrets": "^1.0.0"
43
+ "@molecule/api-ai": "^1.0.1",
44
+ "@molecule/api-bond": "^1.0.1",
45
+ "@molecule/api-i18n": "^1.0.1",
46
+ "@molecule/api-secrets": "^1.0.1"
41
47
  },
42
48
  "peerDependenciesMeta": {
43
49
  "@molecule/api-ai": {