@eserstack/ai 0.0.0-stage → 5.0.0
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/LICENSE +13 -0
- package/README.md +497 -2
- package/dist/adapters/ajan-bridge.d.ts +69 -0
- package/dist/adapters/ajan-bridge.js +661 -0
- package/dist/adapters/anthropic.d.ts +25 -0
- package/dist/adapters/anthropic.js +567 -0
- package/dist/adapters/claude-code.d.ts +28 -0
- package/dist/adapters/claude-code.js +462 -0
- package/dist/adapters/cli-shared.d.ts +36 -0
- package/dist/adapters/cli-shared.js +207 -0
- package/dist/adapters/gemini.d.ts +19 -0
- package/dist/adapters/gemini.js +91 -0
- package/dist/adapters/google-shared.d.ts +58 -0
- package/dist/adapters/google-shared.js +424 -0
- package/dist/adapters/kiro.d.ts +19 -0
- package/dist/adapters/kiro.js +195 -0
- package/dist/adapters/mod.d.ts +61 -0
- package/dist/adapters/mod.js +129 -0
- package/dist/adapters/ollama.d.ts +20 -0
- package/dist/adapters/ollama.js +226 -0
- package/dist/adapters/openai.d.ts +25 -0
- package/dist/adapters/openai.js +553 -0
- package/dist/adapters/opencode.d.ts +19 -0
- package/dist/adapters/opencode.js +158 -0
- package/dist/adapters/vertexai.d.ts +19 -0
- package/dist/adapters/vertexai.js +96 -0
- package/dist/batch.d.ts +35 -0
- package/dist/batch.js +2 -0
- package/dist/commands/ask.d.ts +30 -0
- package/dist/commands/ask.js +404 -0
- package/dist/commands/list.d.ts +2 -0
- package/dist/commands/list.js +35 -0
- package/dist/config.d.ts +21 -0
- package/dist/config.js +16 -0
- package/dist/content.d.ts +14 -0
- package/dist/content.js +103 -0
- package/dist/detect.d.ts +9 -0
- package/dist/detect.js +125 -0
- package/dist/errors.d.ts +62 -0
- package/dist/errors.js +135 -0
- package/dist/generation.d.ts +126 -0
- package/dist/generation.js +96 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +42 -0
- package/dist/mod.d.ts +16 -0
- package/dist/mod.js +11 -0
- package/dist/model.d.ts +27 -0
- package/dist/model.js +12 -0
- package/dist/module.d.ts +10 -0
- package/dist/module.js +21 -0
- package/dist/package.json +74 -0
- package/dist/registry.d.ts +22 -0
- package/dist/registry.js +97 -0
- package/dist/streams/layers.d.ts +4 -0
- package/dist/streams/layers.js +33 -0
- package/dist/streams/mod.d.ts +2 -0
- package/dist/streams/mod.js +5 -0
- package/dist/streams/sources.d.ts +6 -0
- package/dist/streams/sources.js +76 -0
- package/dist/types.d.ts +79 -0
- package/dist/types.js +2 -0
- package/package.json +60 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Copyright 2023-present Eser Ozvataf and other contributors.
|
|
2
|
+
|
|
3
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
you may not use this file except in compliance with the License.
|
|
5
|
+
You may obtain a copy of the License at
|
|
6
|
+
|
|
7
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
|
|
9
|
+
Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
See the License for the specific language governing permissions and
|
|
13
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,498 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 🤖 [@eserstack/ai](./)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/ai` is published on
|
|
4
|
+
> npm under the same name (`pnpm add @eserstack/ai`); the JSR versions stay
|
|
5
|
+
> available but get no updates.
|
|
6
|
+
|
|
7
|
+
> **eserstack Tool** — [eser/stack on GitHub](https://github.com/eser/stack)
|
|
8
|
+
> **Install:** `pnpm add @eserstack/ai`
|
|
9
|
+
|
|
10
|
+
Unified AI provider interface for eser stack. Supports cloud APIs (Anthropic,
|
|
11
|
+
OpenAI, Gemini, Vertex AI) and local agents (Claude Code, Ollama, OpenCode,
|
|
12
|
+
Kiro) through a single `LanguageModel` abstraction.
|
|
13
|
+
|
|
14
|
+
## CLI
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# Standalone, from the package directory
|
|
18
|
+
node ./main.ts ask "explain closures in JS" -p cc
|
|
19
|
+
node ./main.ts ask "summarize this" # auto-detect provider
|
|
20
|
+
node ./main.ts list # show available providers
|
|
21
|
+
|
|
22
|
+
# Via eser CLI
|
|
23
|
+
eser ai ask "hello" -p ollama -m llama3
|
|
24
|
+
eser ai ask "summarize this diff in one line" -p ant --effort low
|
|
25
|
+
eser ai list
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### Provider Aliases
|
|
29
|
+
|
|
30
|
+
| Alias | Provider | Type |
|
|
31
|
+
| ----- | ----------- | ---- |
|
|
32
|
+
| `cc` | claude-code | CLI |
|
|
33
|
+
| `ol` | ollama | HTTP |
|
|
34
|
+
| `oc` | opencode | CLI |
|
|
35
|
+
| `oai` | openai | API |
|
|
36
|
+
| `ant` | anthropic | API |
|
|
37
|
+
| `gem` | gemini | API |
|
|
38
|
+
| `vtx` | vertexai | API |
|
|
39
|
+
| `kr` | kiro | CLI |
|
|
40
|
+
|
|
41
|
+
### Flags
|
|
42
|
+
|
|
43
|
+
| Flag | Description |
|
|
44
|
+
| ---------------- | ------------------------------------------------------------------------------- |
|
|
45
|
+
| `-p, --provider` | Provider name or alias |
|
|
46
|
+
| `-m, --model` | Model ID override |
|
|
47
|
+
| `--max-tokens` | Max output tokens, a positive whole number |
|
|
48
|
+
| `--effort` | Effort level: `low`, `medium`, `high`, `xhigh` or `max` (see [Effort](#effort)) |
|
|
49
|
+
| `--json` | Output full result as JSON |
|
|
50
|
+
| `-v, --verbose` | Show detection and timing info |
|
|
51
|
+
|
|
52
|
+
`ai ask` stops before it chooses a provider when a flag has no value,
|
|
53
|
+
`--max-tokens` is not a positive whole number, or `--effort` is not one of the
|
|
54
|
+
five levels.
|
|
55
|
+
|
|
56
|
+
## Library API
|
|
57
|
+
|
|
58
|
+
The package root runs the CLI, so the library is imported from `./mod`, and the
|
|
59
|
+
provider factories from `./adapters`:
|
|
60
|
+
|
|
61
|
+
```typescript
|
|
62
|
+
import * as ai from "@eserstack/ai/mod";
|
|
63
|
+
import * as aiAdapters from "@eserstack/ai/adapters";
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Registry + Model
|
|
67
|
+
|
|
68
|
+
Register the factories you need, then add a model per configuration target. When
|
|
69
|
+
`apiKey` is not set, the Anthropic SDK reads `ANTHROPIC_API_KEY` from the
|
|
70
|
+
environment.
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
import * as ai from "@eserstack/ai/mod";
|
|
74
|
+
import * as aiAdapters from "@eserstack/ai/adapters";
|
|
75
|
+
|
|
76
|
+
const registry = new ai.Registry({
|
|
77
|
+
factories: [aiAdapters.anthropicFactory],
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
await registry.addModel("default", {
|
|
81
|
+
provider: "anthropic",
|
|
82
|
+
model: "claude-sonnet-5",
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
const model = registry.getDefault();
|
|
86
|
+
if (model === null) {
|
|
87
|
+
throw new Error("no model registered: call registry.addModel first");
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Generate Text
|
|
92
|
+
|
|
93
|
+
`generateText` returns a `Result` from `@eserstack/primitives` instead of
|
|
94
|
+
throwing. Check it before you read the value:
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import * as primitives from "@eserstack/primitives";
|
|
98
|
+
|
|
99
|
+
const result = await model.generateText({
|
|
100
|
+
messages: [ai.textMessage("user", "What is gaslighting?")],
|
|
101
|
+
maxTokens: 1024,
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
if (primitives.results.isFail(result)) {
|
|
105
|
+
throw result.error;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
console.log(ai.text(result.value));
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Streaming
|
|
112
|
+
|
|
113
|
+
`streamText` yields events as the model writes, and reports a failure as an
|
|
114
|
+
`error` event instead of throwing:
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
const messages = [ai.textMessage("user", "Write a haiku about rivers.")];
|
|
118
|
+
const parts: string[] = [];
|
|
119
|
+
|
|
120
|
+
for await (const event of model.streamText({ messages })) {
|
|
121
|
+
if (event.kind === "content_delta") {
|
|
122
|
+
parts.push(event.textDelta);
|
|
123
|
+
} else if (event.kind === "error") {
|
|
124
|
+
throw event.error;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
console.log(parts.join(""));
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Leaving the loop early with `break` or `return` ends the request. The Go bridge
|
|
132
|
+
cancels it, and the TypeScript `claude-code`, `kiro` and `opencode` adapters
|
|
133
|
+
stop the CLI process they started.
|
|
134
|
+
|
|
135
|
+
To print the text as it arrives, pipe it through `@eserstack/streams` as the
|
|
136
|
+
next section shows.
|
|
137
|
+
|
|
138
|
+
### Effort
|
|
139
|
+
|
|
140
|
+
`effort` sets how much the model thinks and how many tokens it spends on a
|
|
141
|
+
reply: `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`. Lower effort answers
|
|
142
|
+
faster and costs less. Leave it unset to keep the provider's default:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
const result = await model.generateText({
|
|
146
|
+
messages: [ai.textMessage("user", "Summarize this diff in one line.")],
|
|
147
|
+
effort: "low",
|
|
148
|
+
});
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Each provider sends it in its own way, or ignores it:
|
|
152
|
+
|
|
153
|
+
| Provider | Sent as |
|
|
154
|
+
| ---------------------------- | ------------------------------------------------------------------------------------- |
|
|
155
|
+
| `anthropic` | `output_config.effort` |
|
|
156
|
+
| `openai` | `reasoning_effort`; a model that lacks the level rejects the request |
|
|
157
|
+
| `claude-code` | the `--effort` flag, which needs a `claude` CLI version that has it |
|
|
158
|
+
| `gemini`, `vertexai` | `thinkingConfig.thinkingLevel`; `xhigh` and `max` send `HIGH`, Gemini's highest level |
|
|
159
|
+
| `ollama`, `opencode`, `kiro` | ignored |
|
|
160
|
+
|
|
161
|
+
On `anthropic` and `openai`, an explicit `effort` wins over the level that
|
|
162
|
+
`thinkingBudget` maps to.
|
|
163
|
+
|
|
164
|
+
On `gemini` and `vertexai`, an explicit `effort` is sent instead of
|
|
165
|
+
`thinkingBudget`, since the API rejects a request that sets both. The levels a
|
|
166
|
+
Gemini model takes differ from one model to the next, and the adapter sends the
|
|
167
|
+
level without checking it against the model.
|
|
168
|
+
[Google's thinking guide](https://ai.google.dev/gemini-api/docs/thinking) lists
|
|
169
|
+
the levels per model.
|
|
170
|
+
|
|
171
|
+
### Structured Output
|
|
172
|
+
|
|
173
|
+
`responseFormat` asks for a JSON reply. With `type: "json_schema"`, the reply
|
|
174
|
+
follows the JSON Schema in `jsonSchema`. The reply still arrives as text, and
|
|
175
|
+
model output is untrusted input, so parse it and check its shape before you use
|
|
176
|
+
it:
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
import * as primitives from "@eserstack/primitives";
|
|
180
|
+
|
|
181
|
+
const result = await model.generateText({
|
|
182
|
+
messages: [
|
|
183
|
+
ai.textMessage("user", "Suggest a title for a post about pnpm workspaces."),
|
|
184
|
+
],
|
|
185
|
+
responseFormat: {
|
|
186
|
+
type: "json_schema",
|
|
187
|
+
name: "post_title",
|
|
188
|
+
jsonSchema: {
|
|
189
|
+
type: "object",
|
|
190
|
+
properties: { title: { type: "string" } },
|
|
191
|
+
required: ["title"],
|
|
192
|
+
additionalProperties: false,
|
|
193
|
+
},
|
|
194
|
+
},
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
if (primitives.results.isFail(result)) {
|
|
198
|
+
throw result.error;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
const reply: unknown = JSON.parse(ai.text(result.value));
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Each provider sends a `json_schema` format in its own way, or ignores it:
|
|
205
|
+
|
|
206
|
+
| Provider | Sent as |
|
|
207
|
+
| -------------------- | ------------------------------------------------------------------------ |
|
|
208
|
+
| `anthropic` | `output_config.format`, in the same object as `effort` |
|
|
209
|
+
| `openai` | `response_format` with `strict: true` |
|
|
210
|
+
| `gemini`, `vertexai` | a response JSON schema with the `application/json` MIME type |
|
|
211
|
+
| `ollama` | `format` |
|
|
212
|
+
| `claude-code` | the `--json-schema` flag, which needs a `claude` CLI version that has it |
|
|
213
|
+
| `opencode`, `kiro` | ignored |
|
|
214
|
+
|
|
215
|
+
Every provider that sends the schema needs it: without `jsonSchema`, or with one
|
|
216
|
+
that is not an object, the call fails with a `BadRequestError` before any
|
|
217
|
+
request is sent.
|
|
218
|
+
|
|
219
|
+
On `anthropic` and `claude-code`:
|
|
220
|
+
|
|
221
|
+
- `name` is not sent, since neither has a field for it.
|
|
222
|
+
- `json_object` and `text` are ignored: Claude has no JSON mode without a
|
|
223
|
+
schema, so the prompt alone decides the shape of the reply.
|
|
224
|
+
- Claude accepts a subset of JSON Schema; on `anthropic` every object needs
|
|
225
|
+
`additionalProperties: false`. See
|
|
226
|
+
[Anthropic's structured outputs guide](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
|
|
227
|
+
|
|
228
|
+
On `claude-code`, the reply text is the CLI's structured output, and the prose
|
|
229
|
+
the model writes around it is left out. When the model gives no structured
|
|
230
|
+
output, as when it declines, the reply text is the prose instead. `streamText`
|
|
231
|
+
yields the reply as one `content_delta` once the CLI has finished.
|
|
232
|
+
|
|
233
|
+
On every provider, a reply that stops with `refusal` or `max_tokens` may not
|
|
234
|
+
match the schema, so check `stopReason` before you parse it.
|
|
235
|
+
|
|
236
|
+
### @eserstack/streams Integration
|
|
237
|
+
|
|
238
|
+
```typescript
|
|
239
|
+
import * as streams from "@eserstack/streams";
|
|
240
|
+
import * as aiStreams from "@eserstack/ai/streams";
|
|
241
|
+
|
|
242
|
+
await streams
|
|
243
|
+
.pipeline()
|
|
244
|
+
.from(aiStreams.aiTextSource(model, { messages }))
|
|
245
|
+
.to(streams.sinks.stdout())
|
|
246
|
+
.run();
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
`aiTextSource` passes on the text deltas only. When `streamText` reports an
|
|
250
|
+
`error` event, the source fails with that error, so `run()` rejects instead of
|
|
251
|
+
finishing with a partial reply.
|
|
252
|
+
|
|
253
|
+
Layers are also available:
|
|
254
|
+
|
|
255
|
+
```typescript
|
|
256
|
+
import * as aiStreams from "@eserstack/ai/streams";
|
|
257
|
+
|
|
258
|
+
// Extract text from StreamEvent chunks
|
|
259
|
+
const textLayer = aiStreams.extractText();
|
|
260
|
+
|
|
261
|
+
// Count tokens via callback
|
|
262
|
+
const counter = aiStreams.tokenCounter((usage) => {
|
|
263
|
+
console.log(`Tokens: ${usage.totalTokens}`);
|
|
264
|
+
});
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## Providers
|
|
268
|
+
|
|
269
|
+
### Cloud APIs
|
|
270
|
+
|
|
271
|
+
| Provider | Package | Features |
|
|
272
|
+
| --------- | ------------------- | --------------------------------------------------------------- |
|
|
273
|
+
| Anthropic | `@anthropic-ai/sdk` | Text, streaming, tools, vision, batch, struct, reasoning |
|
|
274
|
+
| OpenAI | `openai` | Text, streaming, tools, vision, audio, batch, struct, reasoning |
|
|
275
|
+
| Gemini | `@google/genai` | Text, streaming, tools, vision, audio, struct, reasoning |
|
|
276
|
+
| Vertex AI | `@google/genai` | Same as Gemini, project/location auth |
|
|
277
|
+
|
|
278
|
+
A provider declares the same capabilities (`model.capabilities`) whether the
|
|
279
|
+
TypeScript adapter or the Go bridge serves it.
|
|
280
|
+
|
|
281
|
+
### Local Agents
|
|
282
|
+
|
|
283
|
+
| Provider | Transport | Drives |
|
|
284
|
+
| ----------- | ------------------------ | -------------------------------------------- |
|
|
285
|
+
| Claude Code | ACP, in-process (or CLI) | `claude --print --output-format stream-json` |
|
|
286
|
+
| Ollama | HTTP fetch | `POST localhost:11434/api/chat` with JSONL |
|
|
287
|
+
| OpenCode | ACP, in-process (or CLI) | `opencode` with its JSON output flag |
|
|
288
|
+
| Kiro | ACP, in-process (or CLI) | `kiro` with its JSON output flag |
|
|
289
|
+
|
|
290
|
+
### Two paths, and which one you get
|
|
291
|
+
|
|
292
|
+
`defaultFactories()` merges the TypeScript adapters with the Go FFI bridge **per
|
|
293
|
+
provider** — the bridge wins wherever it has an entry, and the TypeScript
|
|
294
|
+
adapter remains for every provider it does not. `factoryFor(provider)` does the
|
|
295
|
+
same for a single provider without importing the others.
|
|
296
|
+
|
|
297
|
+
For the three agent providers above, the bridge speaks the Agent Client Protocol
|
|
298
|
+
to a shim that is **linked into the Go library**, not spawned: `acpfx.InProcess`
|
|
299
|
+
connects them over an in-memory pipe. There is no separate binary to install or
|
|
300
|
+
find on PATH. The shim still drives the vendor CLI, so `claude`, `kiro` or
|
|
301
|
+
`opencode` must be installed — a spawn-time requirement, reported when it fails.
|
|
302
|
+
|
|
303
|
+
When the native library cannot load, the pure-TypeScript adapters take over and
|
|
304
|
+
shell out to the same vendor CLI directly. The bridge **refuses to load over
|
|
305
|
+
WASM** deliberately: WASM loads and then fails every request, because Go's
|
|
306
|
+
`wasip1` target has no outbound network — so a WASM-only machine falls back to
|
|
307
|
+
TypeScript rather than registering a provider that is present and broken.
|
|
308
|
+
|
|
309
|
+
`binPath` on one of these providers names the **vendor CLI**, not a shim.
|
|
310
|
+
|
|
311
|
+
## Content Types
|
|
312
|
+
|
|
313
|
+
Messages use a discriminated union for content blocks:
|
|
314
|
+
|
|
315
|
+
```typescript
|
|
316
|
+
type ContentBlock =
|
|
317
|
+
| { kind: "text"; text: string }
|
|
318
|
+
| { kind: "image"; image: ImagePart }
|
|
319
|
+
| { kind: "audio"; audio: AudioPart }
|
|
320
|
+
| { kind: "file"; file: FilePart }
|
|
321
|
+
| { kind: "tool_call"; toolCall: ToolCall }
|
|
322
|
+
| { kind: "tool_result"; toolResult: ToolResult }
|
|
323
|
+
| { kind: "thinking"; thinking: ThinkingPart };
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
A `thinking` block holds the model's reasoning, which `ai.text()` leaves out.
|
|
327
|
+
Anthropic signs it (`signature`, or `redactedData` when redacted) and rejects a
|
|
328
|
+
tool-use turn sent back without it, so keep `result.content` whole when you add
|
|
329
|
+
the assistant turn to the next request. Streams deliver each block as one
|
|
330
|
+
`thinking` event, and `ai.collectStream` puts them first.
|
|
331
|
+
|
|
332
|
+
Helper constructors:
|
|
333
|
+
|
|
334
|
+
```typescript
|
|
335
|
+
ai.textMessage("user", "Hello");
|
|
336
|
+
ai.imageMessage("user", "https://example.com/photo.jpg", "high");
|
|
337
|
+
ai.toolResultMessage("call_1", "25C");
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
## Refusals
|
|
341
|
+
|
|
342
|
+
A model that declines a request, or a provider's content filter that withholds
|
|
343
|
+
the answer, ends with `stopReason: "refusal"`. The generation itself succeeds,
|
|
344
|
+
and its text, if any, explains the refusal or was cut off by the filter. Check
|
|
345
|
+
the stop reason before using the text as an answer:
|
|
346
|
+
|
|
347
|
+
```typescript
|
|
348
|
+
import * as primitives from "@eserstack/primitives";
|
|
349
|
+
|
|
350
|
+
const result = await model.generateText({ messages });
|
|
351
|
+
|
|
352
|
+
if (primitives.results.isOk(result) && result.value.stopReason === "refusal") {
|
|
353
|
+
throw new Error(`${result.value.modelId} declined the request`);
|
|
354
|
+
}
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Each provider reports a refusal in its own way:
|
|
358
|
+
|
|
359
|
+
| Provider | Reported as `"refusal"` |
|
|
360
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
361
|
+
| `anthropic` | `stop_reason: "refusal"` |
|
|
362
|
+
| `openai` | `finish_reason: "content_filter"`, or a `message.refusal`, whose text becomes the reply text |
|
|
363
|
+
| `gemini`, `vertexai` | a filter's `finishReason` (`SAFETY`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `RECITATION` and the image variants), or a blocked prompt |
|
|
364
|
+
|
|
365
|
+
A reply that was cut off ends with `stopReason: "max_tokens"`. On `anthropic`
|
|
366
|
+
that also covers `model_context_window_exceeded`, a reply cut off because the
|
|
367
|
+
context window filled up.
|
|
368
|
+
|
|
369
|
+
## Error Classification
|
|
370
|
+
|
|
371
|
+
Provider-agnostic error hierarchy with `instanceof` checking. `generateText`
|
|
372
|
+
returns these errors in a failed `Result`, `streamText` in an `error` event, and
|
|
373
|
+
the batch methods throw them:
|
|
374
|
+
|
|
375
|
+
```typescript
|
|
376
|
+
import * as primitives from "@eserstack/primitives";
|
|
377
|
+
|
|
378
|
+
const result = await model.generateText({ messages });
|
|
379
|
+
|
|
380
|
+
if (primitives.results.isFail(result)) {
|
|
381
|
+
if (result.error instanceof ai.RateLimitedError) {
|
|
382
|
+
/* 429 */
|
|
383
|
+
}
|
|
384
|
+
if (result.error instanceof ai.AuthFailedError) {
|
|
385
|
+
/* 401 */
|
|
386
|
+
}
|
|
387
|
+
if (result.error instanceof ai.BadRequestError) {
|
|
388
|
+
/* 400 */
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
## Configuration
|
|
394
|
+
|
|
395
|
+
`loadFromConfig` adds one model per target. The registry needs a factory for
|
|
396
|
+
every provider the config names; `defaultFactories()` returns all of them:
|
|
397
|
+
|
|
398
|
+
```typescript
|
|
399
|
+
import * as ai from "@eserstack/ai/mod";
|
|
400
|
+
import * as aiAdapters from "@eserstack/ai/adapters";
|
|
401
|
+
|
|
402
|
+
const config: ai.Config = {
|
|
403
|
+
targets: {
|
|
404
|
+
default: {
|
|
405
|
+
provider: "claude-code",
|
|
406
|
+
model: "claude-sonnet-5",
|
|
407
|
+
properties: { maxTurns: 1 },
|
|
408
|
+
},
|
|
409
|
+
ollama: {
|
|
410
|
+
provider: "ollama",
|
|
411
|
+
model: "llama3",
|
|
412
|
+
properties: { baseUrl: "http://localhost:11434" },
|
|
413
|
+
},
|
|
414
|
+
},
|
|
415
|
+
};
|
|
416
|
+
|
|
417
|
+
const registry = new ai.Registry({
|
|
418
|
+
factories: await aiAdapters.defaultFactories(),
|
|
419
|
+
});
|
|
420
|
+
|
|
421
|
+
await registry.loadFromConfig(config);
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
## Upgrading from 4.x
|
|
425
|
+
|
|
426
|
+
These changes since 4.5.2 need a change in code, commands or files that use this
|
|
427
|
+
package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
|
|
428
|
+
lists the changes in every package.
|
|
429
|
+
|
|
430
|
+
- `ContentBlock` has a `ThinkingBlock` (`kind: "thinking"`), `StreamEvent` a
|
|
431
|
+
`ThinkingEvent`, and `StopReason` the value `"refusal"`. An exhaustive
|
|
432
|
+
`switch` over them without a `default` no longer compiles. Add the cases, and
|
|
433
|
+
treat `"refusal"` as a declined request, not an answer:
|
|
434
|
+
|
|
435
|
+
```typescript
|
|
436
|
+
// After: check for a refusal before you use the text
|
|
437
|
+
if (result.stopReason === "refusal") {
|
|
438
|
+
return reportRefusal(result);
|
|
439
|
+
}
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
- Stop reasons: Anthropic `refusal`, OpenAI `content_filter` and
|
|
443
|
+
`message.refusal`, Gemini and Vertex AI safety, blocklist and recitation
|
|
444
|
+
reasons and blocked prompts, the claude-code CLI's `refusal`, and ACP
|
|
445
|
+
`refusal` are now `"refusal"`; they used to be `"end_turn"` or `"stop"`.
|
|
446
|
+
Anthropic `model_context_window_exceeded` is `"max_tokens"`. Gemini and Vertex
|
|
447
|
+
AI turns that call a tool end with `"tool_use"`, and unknown OpenAI and Gemini
|
|
448
|
+
reasons are `"stop"`. Check for `"refusal"` before you use the text, and
|
|
449
|
+
accept `"tool_use"` where you compared with `"end_turn"` after a tool call.
|
|
450
|
+
- A `json_schema` `responseFormat` with a missing or non-object schema fails
|
|
451
|
+
before sending with `BadRequestError`, on every provider; it used to be sent
|
|
452
|
+
without the schema. Anthropic now sends the schema as `output_config.format`,
|
|
453
|
+
so a schema outside the subset Claude accepts (for example an object without
|
|
454
|
+
`additionalProperties: false`) gets a 400 from the API. Pass a JSON Schema
|
|
455
|
+
object that follows the provider's limits, or use `json_object`:
|
|
456
|
+
|
|
457
|
+
```typescript
|
|
458
|
+
const options = {
|
|
459
|
+
// Before: { type: "json_schema" } was accepted and the schema ignored
|
|
460
|
+
responseFormat: {
|
|
461
|
+
type: "json_schema",
|
|
462
|
+
jsonSchema: {
|
|
463
|
+
type: "object",
|
|
464
|
+
properties: { title: { type: "string" } },
|
|
465
|
+
required: ["title"],
|
|
466
|
+
additionalProperties: false,
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
};
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
- claude-code with a `json_schema` format passes `--json-schema` to the CLI, and
|
|
473
|
+
`generateCommitMessage` on claude-code passes `--effort low`; a claude CLI
|
|
474
|
+
without these flags rejects the call (2.1.289 has them). The reply text is the
|
|
475
|
+
structured output, and `streamText` yields it as one `content_delta` after the
|
|
476
|
+
CLI exits. Update the claude CLI, and parse `ai.text(result)` as JSON.
|
|
477
|
+
- Capabilities: Anthropic models declare `structured_output` and `reasoning`;
|
|
478
|
+
the Gemini bridge model declares `audio`, `structured_output` and `reasoning`,
|
|
479
|
+
the OpenAI bridge model `audio`, and the Vertex AI bridge model no longer
|
|
480
|
+
declares `batch_processing`. `getByCapability("batch_processing")` no longer
|
|
481
|
+
returns a Vertex AI bridge model, which never had batch methods.
|
|
482
|
+
- `aiTextSource` (`@eserstack/ai/streams`) fails its stream with the error of a
|
|
483
|
+
`streamText` error event; it used to end normally with partial text. Handle
|
|
484
|
+
the rejection of `pipeline().run()`, or use `aiSource` to receive error events
|
|
485
|
+
as data.
|
|
486
|
+
- `eser ai ask`: a value flag with no value (`-p`, `-m`, `--max-tokens`) and a
|
|
487
|
+
`--max-tokens` that is not a positive whole number exit 1 with a message.
|
|
488
|
+
Before: `eser ai ask -m` ignored the flag. After: pass a value, as in
|
|
489
|
+
`eser ai ask "your prompt" -m your_model_id`.
|
|
490
|
+
|
|
491
|
+
## License
|
|
492
|
+
|
|
493
|
+
Apache-2.0
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
🔗 For further details, visit the
|
|
498
|
+
[eserstack repository](https://github.com/eser/stack).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ajan FFI bridge adapter for @eserstack/ai.
|
|
3
|
+
*
|
|
4
|
+
* Routes AI calls through the Go `pkg/ajan/aifx` implementation via the
|
|
5
|
+
* `@eserstack/ajan` C-shared library. Falls back gracefully when native
|
|
6
|
+
* FFI is unavailable.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import * as results from "@eserstack/primitives/results";
|
|
11
|
+
import type * as ffiTypes from "@eserstack/ajan/ffi";
|
|
12
|
+
import type * as types from "../types.ts";
|
|
13
|
+
import type * as config from "../config.ts";
|
|
14
|
+
import type * as generation from "../generation.ts";
|
|
15
|
+
import type * as batch from "../batch.ts";
|
|
16
|
+
import type * as model from "../model.ts";
|
|
17
|
+
import * as errors from "../errors.ts";
|
|
18
|
+
export declare class AjanBridgeModel implements model.BatchCapableModel {
|
|
19
|
+
#private;
|
|
20
|
+
readonly capabilities: readonly types.ProviderCapability[];
|
|
21
|
+
readonly provider: string;
|
|
22
|
+
readonly modelId: string;
|
|
23
|
+
constructor(lib: ffiTypes.FFILibrary, modelHandle: string, provider: string, modelId: string, capabilities: readonly types.ProviderCapability[]);
|
|
24
|
+
generateText(options: generation.GenerateTextOptions, signal?: AbortSignal): Promise<results.Result<generation.GenerateTextResult, errors.AiError>>;
|
|
25
|
+
streamText(options: generation.GenerateTextOptions, signal?: AbortSignal): AsyncIterable<generation.StreamEvent>;
|
|
26
|
+
submitBatch(request: batch.BatchRequest, signal?: AbortSignal): Promise<batch.BatchJob>;
|
|
27
|
+
getBatchJob(jobId: string, signal?: AbortSignal): Promise<batch.BatchJob>;
|
|
28
|
+
listBatchJobs(options?: batch.ListBatchOptions, signal?: AbortSignal): Promise<readonly batch.BatchJob[]>;
|
|
29
|
+
downloadBatchResults(job: batch.BatchJob, signal?: AbortSignal): Promise<readonly batch.BatchResult[]>;
|
|
30
|
+
/**
|
|
31
|
+
* Asks the provider to cancel a batch job.
|
|
32
|
+
*
|
|
33
|
+
* Distinct from aborting this call. `signal` aborts the local request that
|
|
34
|
+
* asks for the cancellation; the cancellation itself is a durable change of
|
|
35
|
+
* state at the provider, and aborting the ask does not undo it if it already
|
|
36
|
+
* landed.
|
|
37
|
+
*/
|
|
38
|
+
cancelBatchJob(jobId: string, signal?: AbortSignal): Promise<void>;
|
|
39
|
+
close(): Promise<void>;
|
|
40
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
41
|
+
[Symbol.dispose](): void;
|
|
42
|
+
getRawClient(): unknown;
|
|
43
|
+
}
|
|
44
|
+
export declare class AjanBridgeModelFactory implements model.ProviderFactory {
|
|
45
|
+
#private;
|
|
46
|
+
readonly provider: string;
|
|
47
|
+
constructor(lib: ffiTypes.FFILibrary, provider: string, capabilities: readonly types.ProviderCapability[]);
|
|
48
|
+
createModel(cfg: config.ResolvedConfigTarget): Promise<model.LanguageModel>;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Creates AjanBridgeModelFactory instances for all supported providers.
|
|
52
|
+
*
|
|
53
|
+
* Every provider the bridge knows, unconditionally — there is nothing that can
|
|
54
|
+
* be independently absent, because every backend is Go code inside the very
|
|
55
|
+
* library that just loaded. The vendor CLI that claude-code, kiro and opencode
|
|
56
|
+
* each drive (claude, kiro, opencode) must still be installed, but that is a
|
|
57
|
+
* spawn-time failure with its own message, not something a PATH probe can
|
|
58
|
+
* predict.
|
|
59
|
+
*/
|
|
60
|
+
export declare const createBridgeFactories: (lib: ffiTypes.FFILibrary) => readonly model.ProviderFactory[];
|
|
61
|
+
export declare const tryLoadBridgeFactories: () => Promise<readonly model.ProviderFactory[]>;
|
|
62
|
+
/**
|
|
63
|
+
* Why the Go bridge is not in use, or `null` when it loaded or was never tried.
|
|
64
|
+
*
|
|
65
|
+
* The underlying loader's own diagnostic (the checked paths, the native-vs-WASM
|
|
66
|
+
* cause) is preserved as this error's `cause`, so a caller can report the whole
|
|
67
|
+
* chain rather than just the last frame.
|
|
68
|
+
*/
|
|
69
|
+
export declare const getBridgeLoadError: () => Error | null;
|