@12-apps/llm 0.0.0-stage → 1.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/README.md +289 -2
- package/dist/index.d.ts +586 -0
- package/dist/index.js +1115 -0
- package/dist/index.js.map +1 -0
- package/package.json +71 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,586 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Credential strategies, interchangeable behind one interface.
|
|
3
|
+
*
|
|
4
|
+
* - `apiKey`: a static secret the HOST supplies, read at call time through a
|
|
5
|
+
* resolver (or given directly). The package never persists it, logs it or
|
|
6
|
+
* puts it in an error message.
|
|
7
|
+
* - `oauth`: an access token the host provides, with its expiry, plus a
|
|
8
|
+
* refresh hook. Before a call the package refreshes a token that is within
|
|
9
|
+
* `refreshSkewMs` of expiring; after a 401 it refreshes once and retries
|
|
10
|
+
* once. A refresh is SINGLE-FLIGHT per session (B1): concurrent calls that
|
|
11
|
+
* find the token expiring, or get a 401, share one `refresh()` — providers
|
|
12
|
+
* rotate the refresh token on use, and two refreshes racing can revoke the
|
|
13
|
+
* login. A 401 on a token older than the last refresh adopts that refresh
|
|
14
|
+
* instead of starting another. It never runs a login flow: obtaining the first token, storing the
|
|
15
|
+
* refreshed one and choosing which provider's login is allowed at all are
|
|
16
|
+
* the host's (see the README's terms note).
|
|
17
|
+
*
|
|
18
|
+
* Which strategies a provider accepts is the ADAPTER's declaration
|
|
19
|
+
* (`ProviderAdapter.credentialKinds`), checked when the client is created.
|
|
20
|
+
*/
|
|
21
|
+
type CredentialKind = "apiKey" | "oauth";
|
|
22
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
23
|
+
interface ApiKeyCredentials {
|
|
24
|
+
kind: "apiKey";
|
|
25
|
+
/** The key, or a resolver the package calls before every request. */
|
|
26
|
+
apiKey: string | (() => MaybePromise<string>);
|
|
27
|
+
}
|
|
28
|
+
interface OAuthToken {
|
|
29
|
+
accessToken: string;
|
|
30
|
+
/** Epoch milliseconds; omitted when the token does not say. */
|
|
31
|
+
expiresAt?: number;
|
|
32
|
+
}
|
|
33
|
+
type RefreshReason = "expiring" | "unauthorized";
|
|
34
|
+
interface OAuthCredentials {
|
|
35
|
+
kind: "oauth";
|
|
36
|
+
/** The host's current token. Called before every request. */
|
|
37
|
+
token: () => MaybePromise<OAuthToken>;
|
|
38
|
+
/**
|
|
39
|
+
* Obtain a fresh token. The host stores it so `token()` returns it next
|
|
40
|
+
* time; the package only uses it for the call in flight.
|
|
41
|
+
*/
|
|
42
|
+
refresh: (reason: RefreshReason) => MaybePromise<OAuthToken>;
|
|
43
|
+
/** How close to expiry a token is refreshed first. Default 60 s. */
|
|
44
|
+
refreshSkewMs?: number;
|
|
45
|
+
/**
|
|
46
|
+
* The host's "this account was disconnected" check, called before a token is
|
|
47
|
+
* handed out and again after a refresh lands. Once it returns true,
|
|
48
|
+
* `current()` and `afterUnauthorized()` throw `CredentialRevokedError`, and a
|
|
49
|
+
* refresh that was in flight is discarded: never returned, never cached.
|
|
50
|
+
*/
|
|
51
|
+
isRevoked?: () => MaybePromise<boolean>;
|
|
52
|
+
}
|
|
53
|
+
type Credentials = ApiKeyCredentials | OAuthCredentials;
|
|
54
|
+
declare const INSPECT: unique symbol;
|
|
55
|
+
/**
|
|
56
|
+
* The secret an adapter sends on ONE request. Its value is non-enumerable and
|
|
57
|
+
* it prints as `[credential apiKey]`, so a log line, a JSON dump or an error
|
|
58
|
+
* context that captures it carries no secret.
|
|
59
|
+
*/
|
|
60
|
+
declare class ResolvedCredential {
|
|
61
|
+
readonly kind: CredentialKind;
|
|
62
|
+
readonly secret: string;
|
|
63
|
+
constructor(kind: CredentialKind, secret: string);
|
|
64
|
+
toJSON(): string;
|
|
65
|
+
toString(): string;
|
|
66
|
+
[INSPECT](): string;
|
|
67
|
+
}
|
|
68
|
+
interface CredentialSessionOptions {
|
|
69
|
+
now?: () => number;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Wraps one strategy for the client: `current()` before a request,
|
|
73
|
+
* `afterUnauthorized()` once after a 401 (null when nothing can be renewed).
|
|
74
|
+
*/
|
|
75
|
+
interface CredentialSession {
|
|
76
|
+
readonly kind: CredentialKind;
|
|
77
|
+
current(): Promise<ResolvedCredential>;
|
|
78
|
+
/** `used` is the credential the 401 answered, so a refresh made since is adopted. */
|
|
79
|
+
afterUnauthorized(used: ResolvedCredential): Promise<ResolvedCredential | null>;
|
|
80
|
+
}
|
|
81
|
+
declare function createCredentialSession(credentials: Credentials, options?: CredentialSessionOptions): CredentialSession;
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The provider-agnostic vocabulary: one chat turn in, one normalized result
|
|
85
|
+
* out. Every adapter maps this interface to its provider's API and back, so a
|
|
86
|
+
* host writes its prompts, tools and metering once.
|
|
87
|
+
*/
|
|
88
|
+
/**
|
|
89
|
+
* What a model client can do. Only `chat` ships today; a later capability
|
|
90
|
+
* (speech-to-text, say) joins this union and an adapter declares it.
|
|
91
|
+
*/
|
|
92
|
+
type Capability = "chat";
|
|
93
|
+
/** A cache lifetime hint. Providers that cache implicitly ignore it. */
|
|
94
|
+
type CacheTtl = "5m" | "1h";
|
|
95
|
+
/**
|
|
96
|
+
* One block of the system prompt. Order the blocks MOST STABLE FIRST: a
|
|
97
|
+
* provider caches a prefix, so a block that changes invalidates every block
|
|
98
|
+
* after it. `cache` marks a breakpoint at the END of this block: everything up
|
|
99
|
+
* to and including it is written to the provider's prompt cache.
|
|
100
|
+
*/
|
|
101
|
+
interface SystemBlock {
|
|
102
|
+
text: string;
|
|
103
|
+
cache?: boolean | {
|
|
104
|
+
ttl: CacheTtl;
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
/** A JSON Schema object. Kept loose: the strict rules are checked at runtime. */
|
|
108
|
+
type JsonSchema = Record<string, unknown>;
|
|
109
|
+
/**
|
|
110
|
+
* A tool the model may call. `inputSchema` is a STRICT JSON schema: every
|
|
111
|
+
* object sets `additionalProperties: false` and lists every property in
|
|
112
|
+
* `required` (an optional field is a nullable type instead). That is the
|
|
113
|
+
* common ground of the providers' strict modes, so the same definition is
|
|
114
|
+
* strict everywhere (see `assertStrictSchema`).
|
|
115
|
+
*/
|
|
116
|
+
interface ToolDefinition {
|
|
117
|
+
name: string;
|
|
118
|
+
description: string;
|
|
119
|
+
inputSchema: JsonSchema;
|
|
120
|
+
}
|
|
121
|
+
/** `required` makes the model call at least one tool this turn. */
|
|
122
|
+
type ToolChoice = "auto" | "none" | "required";
|
|
123
|
+
/** A coarse reasoning-depth hint; each adapter maps it to its own knob. */
|
|
124
|
+
type Effort = "low" | "medium" | "high";
|
|
125
|
+
/** A tool call the model asked for, its input already parsed from JSON. */
|
|
126
|
+
interface ToolCall {
|
|
127
|
+
id: string;
|
|
128
|
+
name: string;
|
|
129
|
+
input: unknown;
|
|
130
|
+
}
|
|
131
|
+
/** The host's answer to one tool call. */
|
|
132
|
+
interface ToolResult {
|
|
133
|
+
callId: string;
|
|
134
|
+
/** The tool's name; some providers match results by name, not by id. */
|
|
135
|
+
name: string;
|
|
136
|
+
output: string;
|
|
137
|
+
isError?: boolean;
|
|
138
|
+
}
|
|
139
|
+
interface UserMessage {
|
|
140
|
+
role: "user";
|
|
141
|
+
text: string;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* A model turn. `raw` carries the provider's own content for this turn, which
|
|
145
|
+
* an adapter of the SAME provider replays verbatim (thinking blocks and
|
|
146
|
+
* signatures some providers require back in a tool loop); any other adapter
|
|
147
|
+
* ignores it and rebuilds the turn from `text` and `toolCalls`.
|
|
148
|
+
*/
|
|
149
|
+
interface AssistantMessage {
|
|
150
|
+
role: "assistant";
|
|
151
|
+
text: string;
|
|
152
|
+
toolCalls: ToolCall[];
|
|
153
|
+
raw?: {
|
|
154
|
+
provider: string;
|
|
155
|
+
content: unknown;
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
/** The results of the previous assistant turn's tool calls, all together. */
|
|
159
|
+
interface ToolResultsMessage {
|
|
160
|
+
role: "tool";
|
|
161
|
+
results: ToolResult[];
|
|
162
|
+
}
|
|
163
|
+
type Message = UserMessage | AssistantMessage | ToolResultsMessage;
|
|
164
|
+
/** One chat turn. */
|
|
165
|
+
interface ChatRequest {
|
|
166
|
+
/** Overrides the client's model for this call only. */
|
|
167
|
+
model?: string;
|
|
168
|
+
system?: SystemBlock[];
|
|
169
|
+
messages: Message[];
|
|
170
|
+
tools?: ToolDefinition[];
|
|
171
|
+
toolChoice?: ToolChoice;
|
|
172
|
+
maxOutputTokens: number;
|
|
173
|
+
effort?: Effort;
|
|
174
|
+
/** A sampling hint; adapters whose API refuses sampling params drop it. */
|
|
175
|
+
temperature?: number;
|
|
176
|
+
/**
|
|
177
|
+
* Ask the provider to also cache the conversation so far (a breakpoint on
|
|
178
|
+
* the last message). Providers that cache implicitly ignore it.
|
|
179
|
+
*/
|
|
180
|
+
cacheConversation?: boolean;
|
|
181
|
+
/** A stable key that routes requests sharing a prefix to the same cache. */
|
|
182
|
+
cacheKey?: string;
|
|
183
|
+
signal?: AbortSignal;
|
|
184
|
+
}
|
|
185
|
+
type StopReason = "end" | "tool_use" | "max_tokens" | "refusal" | "other";
|
|
186
|
+
/**
|
|
187
|
+
* Token usage of one turn. `inputTokens` counts only the input that was
|
|
188
|
+
* neither written to nor read from the cache, so the four counters add up to
|
|
189
|
+
* everything billed, and each can be priced at its own rate.
|
|
190
|
+
*/
|
|
191
|
+
interface Usage {
|
|
192
|
+
inputTokens: number;
|
|
193
|
+
cacheCreationTokens: number;
|
|
194
|
+
cacheReadTokens: number;
|
|
195
|
+
outputTokens: number;
|
|
196
|
+
/** The provider's usage object, untouched. */
|
|
197
|
+
raw: unknown;
|
|
198
|
+
}
|
|
199
|
+
/** Why the provider declined, when it says. */
|
|
200
|
+
interface Refusal {
|
|
201
|
+
category: string | null;
|
|
202
|
+
explanation: string | null;
|
|
203
|
+
}
|
|
204
|
+
/** One normalized turn result. */
|
|
205
|
+
interface ChatResult {
|
|
206
|
+
provider: string;
|
|
207
|
+
model: string;
|
|
208
|
+
text: string;
|
|
209
|
+
toolCalls: ToolCall[];
|
|
210
|
+
stopReason: StopReason;
|
|
211
|
+
/** The provider's own stop reason, for logs. */
|
|
212
|
+
providerStopReason: string | null;
|
|
213
|
+
refusal: Refusal | null;
|
|
214
|
+
usage: Usage;
|
|
215
|
+
/** The turn as a message, ready to append to the conversation. */
|
|
216
|
+
message: AssistantMessage;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* The adapter port and the registry the factory picks adapters from.
|
|
221
|
+
*
|
|
222
|
+
* An adapter is the ONLY place a provider's API shape lives. It declares what
|
|
223
|
+
* it can do (`capabilities`) and which credential strategies its provider
|
|
224
|
+
* accepts (`credentialKinds`), and turns one `ChatRequest` into one
|
|
225
|
+
* `ChatResult` with the credential it is handed. Retry, OAuth refresh and the
|
|
226
|
+
* strict-schema check are the client's, so an adapter never repeats them.
|
|
227
|
+
*/
|
|
228
|
+
|
|
229
|
+
/** What the client hands an adapter for one call. */
|
|
230
|
+
interface ChatCall {
|
|
231
|
+
model: string;
|
|
232
|
+
request: ChatRequest;
|
|
233
|
+
credential: ResolvedCredential;
|
|
234
|
+
}
|
|
235
|
+
interface ProviderAdapter {
|
|
236
|
+
/** The provider id a host names in `createModelClient({ provider })`. */
|
|
237
|
+
readonly id: string;
|
|
238
|
+
/** Used when the host names no model; an adapter may ship none. */
|
|
239
|
+
readonly defaultModel?: string;
|
|
240
|
+
readonly capabilities: readonly Capability[];
|
|
241
|
+
readonly credentialKinds: readonly CredentialKind[];
|
|
242
|
+
/**
|
|
243
|
+
* Run one chat turn. Throws the package's typed errors (map an SDK failure
|
|
244
|
+
* with `mapProviderError`); a refusal is a RESULT, not an error.
|
|
245
|
+
*/
|
|
246
|
+
chat(call: ChatCall): Promise<ChatResult>;
|
|
247
|
+
}
|
|
248
|
+
interface RegisterOptions {
|
|
249
|
+
/** Replace an adapter already registered under the same id. */
|
|
250
|
+
replace?: boolean;
|
|
251
|
+
}
|
|
252
|
+
interface AdapterRegistry {
|
|
253
|
+
register(adapter: ProviderAdapter, options?: RegisterOptions): AdapterRegistry;
|
|
254
|
+
get(id: string): ProviderAdapter;
|
|
255
|
+
has(id: string): boolean;
|
|
256
|
+
ids(): string[];
|
|
257
|
+
}
|
|
258
|
+
/**
|
|
259
|
+
* A registry of adapters, keyed by provider id. A host adds its own adapter
|
|
260
|
+
* (or replaces a built-in one, say with a different base URL) with
|
|
261
|
+
* `register`, without touching this package.
|
|
262
|
+
*/
|
|
263
|
+
declare function createAdapterRegistry(adapters?: readonly ProviderAdapter[]): AdapterRegistry;
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* The Anthropic adapter, over the official `@anthropic-ai/sdk` (an optional
|
|
267
|
+
* peer, imported only when this adapter builds its own client).
|
|
268
|
+
*
|
|
269
|
+
* Mapping notes:
|
|
270
|
+
* - System blocks keep their order; a block marked `cache` carries a
|
|
271
|
+
* `cache_control` breakpoint. Tools render before the system prompt, so the
|
|
272
|
+
* first breakpoint also caches the tool list. At most four breakpoints in
|
|
273
|
+
* all, `cacheConversation` included (the API's limit).
|
|
274
|
+
* - Tools are sent with `strict: true`. `toolChoice: "required"` becomes
|
|
275
|
+
* `{ type: "any" }`, which some models refuse: steer with the prompt there.
|
|
276
|
+
* - `effort` becomes `output_config.effort`. `temperature` is dropped: the
|
|
277
|
+
* current Messages API refuses sampling parameters.
|
|
278
|
+
* - An assistant turn this adapter produced is replayed from `raw`, so
|
|
279
|
+
* thinking blocks go back unchanged inside a tool loop.
|
|
280
|
+
*/
|
|
281
|
+
|
|
282
|
+
declare const ANTHROPIC_PROVIDER = "anthropic";
|
|
283
|
+
declare const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-5-5";
|
|
284
|
+
/**
|
|
285
|
+
* The slice of the SDK client this adapter calls. `params` is the SDK's
|
|
286
|
+
* `MessageCreateParamsNonStreaming`; it is typed `never` here so this
|
|
287
|
+
* package's public types do not require the optional SDK to be installed.
|
|
288
|
+
*/
|
|
289
|
+
interface AnthropicClientLike {
|
|
290
|
+
messages: {
|
|
291
|
+
create(params: never, options?: {
|
|
292
|
+
signal?: AbortSignal;
|
|
293
|
+
}): Promise<unknown>;
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
interface AnthropicAdapterOptions {
|
|
297
|
+
/** Build the SDK client for one call (tests inject a recording fake). */
|
|
298
|
+
client?: (credential: ResolvedCredential) => AnthropicClientLike | Promise<AnthropicClientLike>;
|
|
299
|
+
baseURL?: string;
|
|
300
|
+
/** The `fetch` the SDK sends with (a proxy, a test double). */
|
|
301
|
+
fetch?: typeof globalThis.fetch;
|
|
302
|
+
defaultModel?: string;
|
|
303
|
+
}
|
|
304
|
+
declare function anthropicAdapter(options?: AnthropicAdapterOptions): ProviderAdapter;
|
|
305
|
+
|
|
306
|
+
/**
|
|
307
|
+
* The Gemini adapter, over the official Google GenAI SDK (`@google/genai`, an
|
|
308
|
+
* optional peer, imported only when this adapter builds its own client).
|
|
309
|
+
*
|
|
310
|
+
* Mapping notes:
|
|
311
|
+
* - System blocks become `systemInstruction` parts, in order. The Gemini API
|
|
312
|
+
* caches repeated prefixes implicitly; explicit cached contents are a
|
|
313
|
+
* separate resource this adapter does not manage, so `cache` breakpoints,
|
|
314
|
+
* `cacheConversation` and `cacheKey` have nothing to map to.
|
|
315
|
+
* - Tools become function declarations with `parametersJsonSchema` (JSON
|
|
316
|
+
* Schema, `additionalProperties` included). `toolChoice` becomes the
|
|
317
|
+
* function-calling mode (`required` is `ANY`).
|
|
318
|
+
* - `effort` becomes `thinkingConfig.thinkingLevel`; `temperature` is passed.
|
|
319
|
+
* - Usage: `promptTokenCount` includes the cached tokens; output counts the
|
|
320
|
+
* candidates plus the thinking tokens, which Gemini bills as output.
|
|
321
|
+
* - A model turn this adapter produced is replayed from `raw`, so thought
|
|
322
|
+
* signatures go back unchanged inside a tool loop.
|
|
323
|
+
* - Credentials: an API key, or a Google OAuth access token for the Gemini
|
|
324
|
+
* API (Google's own OAuth, which its terms allow for this API).
|
|
325
|
+
*/
|
|
326
|
+
|
|
327
|
+
declare const GEMINI_PROVIDER = "gemini";
|
|
328
|
+
/**
|
|
329
|
+
* The slice of the SDK client this adapter calls. `params` is the SDK's
|
|
330
|
+
* `GenerateContentParameters`, typed `never` here so this package's public
|
|
331
|
+
* types do not require the optional SDK to be installed.
|
|
332
|
+
*/
|
|
333
|
+
interface GeminiClientLike {
|
|
334
|
+
models: {
|
|
335
|
+
generateContent(params: never): Promise<unknown>;
|
|
336
|
+
};
|
|
337
|
+
}
|
|
338
|
+
interface GeminiAdapterOptions {
|
|
339
|
+
/** Build the SDK client for one call (tests inject a recording fake). */
|
|
340
|
+
client?: (credential: ResolvedCredential) => GeminiClientLike | Promise<GeminiClientLike>;
|
|
341
|
+
baseURL?: string;
|
|
342
|
+
/** The `fetch` the SDK sends with (a proxy, a test double). */
|
|
343
|
+
fetch?: typeof globalThis.fetch;
|
|
344
|
+
defaultModel?: string;
|
|
345
|
+
}
|
|
346
|
+
declare function geminiAdapter(options?: GeminiAdapterOptions): ProviderAdapter;
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* The OpenAI adapter, over the official `openai` SDK's Chat Completions API
|
|
350
|
+
* with function tools (an optional peer, imported only when this adapter
|
|
351
|
+
* builds its own client).
|
|
352
|
+
*
|
|
353
|
+
* Mapping notes:
|
|
354
|
+
* - System blocks become one system message, its text parts in order.
|
|
355
|
+
* OpenAI caches prompt prefixes by itself, so `cache` breakpoints and
|
|
356
|
+
* `cacheConversation` have nothing to map to; `cacheKey` becomes
|
|
357
|
+
* `prompt_cache_key`, which routes requests sharing a prefix together.
|
|
358
|
+
* - Tools are sent with `strict: true`; arguments come back as JSON text and
|
|
359
|
+
* are parsed here.
|
|
360
|
+
* - `effort` becomes `reasoning_effort`; `temperature` is passed when given.
|
|
361
|
+
* - Usage: `prompt_tokens` includes the cached tokens, so `inputTokens` is
|
|
362
|
+
* the prompt minus the cache reads and writes.
|
|
363
|
+
* - Credentials: API keys only. OpenAI's API authenticates with keys, and a
|
|
364
|
+
* ChatGPT or Codex sign-in is not a credential a third-party product may
|
|
365
|
+
* use (see the README's terms note).
|
|
366
|
+
*/
|
|
367
|
+
|
|
368
|
+
declare const OPENAI_PROVIDER = "openai";
|
|
369
|
+
/**
|
|
370
|
+
* The slice of the SDK client this adapter calls. `params` is the SDK's
|
|
371
|
+
* `ChatCompletionCreateParamsNonStreaming`, typed `never` here so this
|
|
372
|
+
* package's public types do not require the optional SDK to be installed.
|
|
373
|
+
*/
|
|
374
|
+
interface OpenAIClientLike {
|
|
375
|
+
chat: {
|
|
376
|
+
completions: {
|
|
377
|
+
create(params: never, options?: {
|
|
378
|
+
signal?: AbortSignal;
|
|
379
|
+
}): Promise<unknown>;
|
|
380
|
+
};
|
|
381
|
+
};
|
|
382
|
+
}
|
|
383
|
+
interface OpenAIAdapterOptions {
|
|
384
|
+
/** Build the SDK client for one call (tests inject a recording fake). */
|
|
385
|
+
client?: (credential: ResolvedCredential) => OpenAIClientLike | Promise<OpenAIClientLike>;
|
|
386
|
+
baseURL?: string;
|
|
387
|
+
/** The `fetch` the SDK sends with (a proxy, a test double). */
|
|
388
|
+
fetch?: typeof globalThis.fetch;
|
|
389
|
+
defaultModel?: string;
|
|
390
|
+
}
|
|
391
|
+
declare function openaiAdapter(options?: OpenAIAdapterOptions): ProviderAdapter;
|
|
392
|
+
|
|
393
|
+
/**
|
|
394
|
+
* The xAI (Grok) adapter (FUT-3738). xAI's API speaks OpenAI's Chat
|
|
395
|
+
* Completions, so this is the OpenAI-compatible adapter under its own id,
|
|
396
|
+
* with xAI's own API root and the store's own xAI key. It reads NOTHING from
|
|
397
|
+
* the platform's `OPENAI_*` variables: the base URL, organisation and project
|
|
398
|
+
* are passed explicitly and the sealed fetch sends only this key (B3).
|
|
399
|
+
*
|
|
400
|
+
* - No default model: a host names the Grok model it pays for.
|
|
401
|
+
* - `cacheKey` is not sent: `prompt_cache_key` is OpenAI's parameter.
|
|
402
|
+
* - Credentials: API keys only, as for OpenAI.
|
|
403
|
+
* - The `openai` SDK is the optional peer this adapter needs.
|
|
404
|
+
*/
|
|
405
|
+
|
|
406
|
+
declare const XAI_PROVIDER = "xai";
|
|
407
|
+
type XaiAdapterOptions = OpenAIAdapterOptions;
|
|
408
|
+
declare function xaiAdapter(options?: XaiAdapterOptions): ProviderAdapter;
|
|
409
|
+
|
|
410
|
+
/** Fresh instances of the built-in adapters, with their defaults. */
|
|
411
|
+
declare function builtInAdapters(): ProviderAdapter[];
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* Typed errors. Every adapter maps its SDK's failures onto these, so a host
|
|
415
|
+
* decides retry, hand-off and alerting once, whatever the provider.
|
|
416
|
+
*
|
|
417
|
+
* No error carries a credential: messages are built here, from the provider's
|
|
418
|
+
* status and its own message with any secret the call used scrubbed out.
|
|
419
|
+
*/
|
|
420
|
+
|
|
421
|
+
type LlmErrorKind = "auth" | "rate_limit" | "refusal" | "invalid_request" | "unavailable" | "invalid_response" | "unsupported";
|
|
422
|
+
declare class LlmError extends Error {
|
|
423
|
+
readonly kind: LlmErrorKind;
|
|
424
|
+
readonly provider: string;
|
|
425
|
+
/** The provider's HTTP status, when there was one. */
|
|
426
|
+
readonly status: number | undefined;
|
|
427
|
+
constructor(kind: LlmErrorKind, provider: string, message: string, status?: number);
|
|
428
|
+
}
|
|
429
|
+
/** The credential was refused (401) or lacks permission (403). */
|
|
430
|
+
declare class AuthError extends LlmError {
|
|
431
|
+
constructor(provider: string, message: string, status?: number);
|
|
432
|
+
}
|
|
433
|
+
/** The host revoked the credential (the account was disconnected): nothing is sent or refreshed with it. */
|
|
434
|
+
declare class CredentialRevokedError extends AuthError {
|
|
435
|
+
constructor(provider?: string);
|
|
436
|
+
}
|
|
437
|
+
/** Too many requests. `retryAfterMs` is the provider's own hint, when given. */
|
|
438
|
+
declare class RateLimitError extends LlmError {
|
|
439
|
+
readonly retryAfterMs: number | undefined;
|
|
440
|
+
constructor(provider: string, message: string, retryAfterMs?: number);
|
|
441
|
+
}
|
|
442
|
+
/** The model declined. Thrown by `ensureNotRefused`; `chat` returns it as data. */
|
|
443
|
+
declare class RefusalError extends LlmError {
|
|
444
|
+
readonly refusal: Refusal;
|
|
445
|
+
constructor(provider: string, refusal: Refusal);
|
|
446
|
+
}
|
|
447
|
+
/** The request itself is wrong (400, 404, 413, 422) and will fail again as is. */
|
|
448
|
+
declare class InvalidRequestError extends LlmError {
|
|
449
|
+
constructor(provider: string, message: string, status?: number);
|
|
450
|
+
}
|
|
451
|
+
/** The provider is down, overloaded or unreachable (5xx, 529, network). */
|
|
452
|
+
declare class ProviderUnavailableError extends LlmError {
|
|
453
|
+
constructor(provider: string, message: string, status?: number);
|
|
454
|
+
}
|
|
455
|
+
/** The provider answered with something this package cannot read. */
|
|
456
|
+
declare class InvalidResponseError extends LlmError {
|
|
457
|
+
constructor(provider: string, message: string);
|
|
458
|
+
}
|
|
459
|
+
/** A provider, credential kind or capability nobody registered or declared. */
|
|
460
|
+
declare class UnsupportedError extends LlmError {
|
|
461
|
+
constructor(provider: string, message: string);
|
|
462
|
+
}
|
|
463
|
+
/** `retry-after-ms`, else `retry-after` in seconds or as an HTTP date. */
|
|
464
|
+
declare function retryAfterFrom(headers: unknown, now?: () => number): number | undefined;
|
|
465
|
+
/**
|
|
466
|
+
* Map any SDK error onto the taxonomy by its HTTP status (every official SDK
|
|
467
|
+
* exposes `status`), so an adapter needs no SDK class import. An `LlmError`
|
|
468
|
+
* passes through untouched, and so does anything that is not a provider
|
|
469
|
+
* failure (an abort, a bug, a host exception).
|
|
470
|
+
*/
|
|
471
|
+
declare function mapProviderError(provider: string, error: unknown, secrets?: readonly string[]): unknown;
|
|
472
|
+
|
|
473
|
+
/**
|
|
474
|
+
* The abstract factory: `createModelClient` picks an adapter by provider id
|
|
475
|
+
* and wraps it with what every provider shares: the credential strategy
|
|
476
|
+
* (including the OAuth refresh on near-expiry and the single retry after a
|
|
477
|
+
* 401), the strict tool-schema check, and the host's retry policy.
|
|
478
|
+
*/
|
|
479
|
+
|
|
480
|
+
/**
|
|
481
|
+
* The host's ONE retry policy. Called after each failed attempt with the
|
|
482
|
+
* typed error and the attempt number (1 for the first failure). Return a
|
|
483
|
+
* delay in milliseconds to try again, or `null` to give up and throw.
|
|
484
|
+
* The package itself never retries (the SDKs' own retries are switched off),
|
|
485
|
+
* so this hook is the whole policy. A 401 under OAuth is not seen here: the
|
|
486
|
+
* client refreshes and retries it once by itself.
|
|
487
|
+
*/
|
|
488
|
+
type RetryPolicy = (error: LlmError, attempt: number) => number | null;
|
|
489
|
+
interface ModelClientOptions {
|
|
490
|
+
provider: string;
|
|
491
|
+
/** Defaults to the adapter's default model. */
|
|
492
|
+
model?: string;
|
|
493
|
+
credentials: Credentials;
|
|
494
|
+
retry?: RetryPolicy;
|
|
495
|
+
/** Where to find adapters. Defaults to a registry of the built-in four. */
|
|
496
|
+
registry?: AdapterRegistry;
|
|
497
|
+
/** Test seams. */
|
|
498
|
+
sleep?: (ms: number) => Promise<void>;
|
|
499
|
+
now?: () => number;
|
|
500
|
+
}
|
|
501
|
+
interface ModelClient {
|
|
502
|
+
readonly provider: string;
|
|
503
|
+
readonly model: string;
|
|
504
|
+
readonly capabilities: readonly Capability[];
|
|
505
|
+
supports(capability: Capability): boolean;
|
|
506
|
+
chat(request: ChatRequest): Promise<ChatResult>;
|
|
507
|
+
}
|
|
508
|
+
/** Retries rate limits and outages, honouring retry-after; gives up after `maxAttempts`. */
|
|
509
|
+
declare function retryTransient(options?: {
|
|
510
|
+
maxAttempts?: number;
|
|
511
|
+
baseDelayMs?: number;
|
|
512
|
+
}): RetryPolicy;
|
|
513
|
+
declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
514
|
+
|
|
515
|
+
/**
|
|
516
|
+
* The tool-use loop: run turns until the model stops calling tools, refuses,
|
|
517
|
+
* runs out of output budget, or the turn limit is reached.
|
|
518
|
+
*
|
|
519
|
+
* The host supplies an executor per tool name and a usage callback; every
|
|
520
|
+
* turn's normalized usage is reported through it, before anything else
|
|
521
|
+
* happens with that turn, so a host meters cost even for a turn that ends the
|
|
522
|
+
* loop. A refusal is a typed RESULT (`status: "refused"`), never an error, so
|
|
523
|
+
* the host can hand the conversation to a person.
|
|
524
|
+
*
|
|
525
|
+
* The returned `messages` are always a valid request for the NEXT turn (B2):
|
|
526
|
+
* a turn the loop ends on keeps its text but never a tool call that was not
|
|
527
|
+
* run (no tool_use without its tool_result), and a turn with neither text nor
|
|
528
|
+
* a tool call — an empty refusal — is not appended at all. Either would make
|
|
529
|
+
* the provider reject the host's next request with a 400.
|
|
530
|
+
*/
|
|
531
|
+
|
|
532
|
+
/** What an executor returns: the output text, or the text marked as an error. */
|
|
533
|
+
type ToolOutput = string | {
|
|
534
|
+
output: string;
|
|
535
|
+
isError?: boolean;
|
|
536
|
+
};
|
|
537
|
+
type ToolExecutor = (input: unknown, context: {
|
|
538
|
+
call: ToolCall;
|
|
539
|
+
turn: number;
|
|
540
|
+
}) => Promise<ToolOutput> | ToolOutput;
|
|
541
|
+
interface ToolLoopOptions {
|
|
542
|
+
client: ModelClient;
|
|
543
|
+
/** The first turn's request. `messages` is the conversation so far. */
|
|
544
|
+
request: ChatRequest;
|
|
545
|
+
executors: Readonly<Record<string, ToolExecutor>>;
|
|
546
|
+
/** Turns at most, each turn being one model call. Default 8. */
|
|
547
|
+
maxTurns?: number;
|
|
548
|
+
/** Called once per turn with that turn's usage, turn numbers from 1. */
|
|
549
|
+
onUsage?: (usage: Usage, turn: number, result: ChatResult) => void | Promise<void>;
|
|
550
|
+
}
|
|
551
|
+
type ToolLoopStatus = "completed" | "refused" | "max_turns" | "max_tokens" | "stopped";
|
|
552
|
+
interface ToolLoopResult {
|
|
553
|
+
status: ToolLoopStatus;
|
|
554
|
+
/** The conversation, with every turn and tool result appended. */
|
|
555
|
+
messages: Message[];
|
|
556
|
+
/** The last model turn. */
|
|
557
|
+
final: ChatResult;
|
|
558
|
+
turns: number;
|
|
559
|
+
/** The sum of every turn's usage (without the raw objects). */
|
|
560
|
+
usage: Omit<Usage, "raw">;
|
|
561
|
+
/** Set when `status` is "refused". */
|
|
562
|
+
refusal: Refusal | null;
|
|
563
|
+
}
|
|
564
|
+
declare function runToolLoop(options: ToolLoopOptions): Promise<ToolLoopResult>;
|
|
565
|
+
/** Throw a `RefusalError` when a turn was refused; return it otherwise. */
|
|
566
|
+
declare function ensureNotRefused(result: ChatResult): ChatResult;
|
|
567
|
+
|
|
568
|
+
/**
|
|
569
|
+
* The strict-schema rule every tool input schema meets, whatever the provider.
|
|
570
|
+
*
|
|
571
|
+
* Each provider's strict mode guarantees the model's arguments validate
|
|
572
|
+
* against the schema, and each asks for a slightly different subset. The
|
|
573
|
+
* common ground, which this check enforces, is: the root is an object; every
|
|
574
|
+
* object sets `additionalProperties: false`; every object lists ALL its
|
|
575
|
+
* properties in `required`. An optional field is spelled as a nullable type
|
|
576
|
+
* (`type: ["string", "null"]`), which every provider accepts.
|
|
577
|
+
*/
|
|
578
|
+
|
|
579
|
+
/** Every reason `schema` is not strict, with a path to each; empty when it is. */
|
|
580
|
+
declare function strictSchemaProblems(schema: JsonSchema, path?: string): string[];
|
|
581
|
+
/** Every problem in a tool list: duplicate names and non-strict schemas. */
|
|
582
|
+
declare function toolSchemaProblems(tools: readonly ToolDefinition[]): string[];
|
|
583
|
+
/** Throws a TypeError naming every problem in every tool's input schema. */
|
|
584
|
+
declare function assertStrictTools(tools: readonly ToolDefinition[]): void;
|
|
585
|
+
|
|
586
|
+
export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_PROVIDER, type AdapterRegistry, type AnthropicAdapterOptions, type AnthropicClientLike, type ApiKeyCredentials, type AssistantMessage, AuthError, type CacheTtl, type Capability, type ChatCall, type ChatRequest, type ChatResult, type CredentialKind, CredentialRevokedError, type CredentialSession, type CredentialSessionOptions, type Credentials, type Effort, GEMINI_PROVIDER, type GeminiAdapterOptions, type GeminiClientLike, InvalidRequestError, InvalidResponseError, type JsonSchema, LlmError, type LlmErrorKind, type Message, type ModelClient, type ModelClientOptions, type OAuthCredentials, type OAuthToken, OPENAI_PROVIDER, type OpenAIAdapterOptions, type OpenAIClientLike, type ProviderAdapter, ProviderUnavailableError, RateLimitError, type RefreshReason, type Refusal, RefusalError, type RegisterOptions, ResolvedCredential, type RetryPolicy, type StopReason, type SystemBlock, type ToolCall, type ToolChoice, type ToolDefinition, type ToolExecutor, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStatus, type ToolOutput, type ToolResult, type ToolResultsMessage, UnsupportedError, type Usage, type UserMessage, XAI_PROVIDER, type XaiAdapterOptions, anthropicAdapter, assertStrictTools, builtInAdapters, createAdapterRegistry, createCredentialSession, createModelClient, ensureNotRefused, geminiAdapter, mapProviderError, openaiAdapter, retryAfterFrom, retryTransient, runToolLoop, strictSchemaProblems, toolSchemaProblems, xaiAdapter };
|