@providerprotocol/ai 0.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.
- package/LICENSE +21 -0
- package/README.md +84 -0
- package/dist/anthropic/index.d.ts +41 -0
- package/dist/anthropic/index.js +500 -0
- package/dist/anthropic/index.js.map +1 -0
- package/dist/chunk-CUCRF5W6.js +136 -0
- package/dist/chunk-CUCRF5W6.js.map +1 -0
- package/dist/chunk-FTFX2VET.js +424 -0
- package/dist/chunk-FTFX2VET.js.map +1 -0
- package/dist/chunk-QUUX4G7U.js +117 -0
- package/dist/chunk-QUUX4G7U.js.map +1 -0
- package/dist/chunk-Y6Q7JCNP.js +39 -0
- package/dist/chunk-Y6Q7JCNP.js.map +1 -0
- package/dist/google/index.d.ts +69 -0
- package/dist/google/index.js +517 -0
- package/dist/google/index.js.map +1 -0
- package/dist/http/index.d.ts +61 -0
- package/dist/http/index.js +43 -0
- package/dist/http/index.js.map +1 -0
- package/dist/index.d.ts +792 -0
- package/dist/index.js +898 -0
- package/dist/index.js.map +1 -0
- package/dist/openai/index.d.ts +204 -0
- package/dist/openai/index.js +1340 -0
- package/dist/openai/index.js.map +1 -0
- package/dist/provider-CUJWjgNl.d.ts +192 -0
- package/dist/retry-I2661_rv.d.ts +118 -0
- package/package.json +88 -0
- package/src/anthropic/index.ts +3 -0
- package/src/core/image.ts +188 -0
- package/src/core/llm.ts +619 -0
- package/src/core/provider.ts +92 -0
- package/src/google/index.ts +3 -0
- package/src/http/errors.ts +112 -0
- package/src/http/fetch.ts +210 -0
- package/src/http/index.ts +31 -0
- package/src/http/keys.ts +136 -0
- package/src/http/retry.ts +205 -0
- package/src/http/sse.ts +136 -0
- package/src/index.ts +32 -0
- package/src/openai/index.ts +9 -0
- package/src/providers/anthropic/index.ts +17 -0
- package/src/providers/anthropic/llm.ts +196 -0
- package/src/providers/anthropic/transform.ts +452 -0
- package/src/providers/anthropic/types.ts +213 -0
- package/src/providers/google/index.ts +17 -0
- package/src/providers/google/llm.ts +203 -0
- package/src/providers/google/transform.ts +487 -0
- package/src/providers/google/types.ts +214 -0
- package/src/providers/openai/index.ts +151 -0
- package/src/providers/openai/llm.completions.ts +201 -0
- package/src/providers/openai/llm.responses.ts +211 -0
- package/src/providers/openai/transform.completions.ts +628 -0
- package/src/providers/openai/transform.responses.ts +718 -0
- package/src/providers/openai/types.ts +711 -0
- package/src/types/content.ts +133 -0
- package/src/types/errors.ts +85 -0
- package/src/types/index.ts +105 -0
- package/src/types/llm.ts +211 -0
- package/src/types/messages.ts +182 -0
- package/src/types/provider.ts +195 -0
- package/src/types/schema.ts +58 -0
- package/src/types/stream.ts +146 -0
- package/src/types/thread.ts +226 -0
- package/src/types/tool.ts +88 -0
- package/src/types/turn.ts +118 -0
- package/src/utils/id.ts +28 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,792 @@
|
|
|
1
|
+
import { M as ModelReference, P as ProviderConfig, L as LLMProvider, a as LLMHandler$1, E as EmbeddingHandler, I as ImageHandler, b as Provider } from './provider-CUJWjgNl.js';
|
|
2
|
+
export { B as BoundEmbeddingModel, g as BoundImageModel, e as EmbeddingProvider, c as ErrorCode, f as ImageProvider, K as KeyStrategy, d as Modality, R as RetryStrategy, U as UPPError } from './provider-CUJWjgNl.js';
|
|
3
|
+
export { D as DynamicKey, E as ExponentialBackoff, L as LinearBackoff, N as NoRetry, a as RetryAfterStrategy, R as RoundRobinKeys, T as TokenBucket, W as WeightedKeys } from './retry-I2661_rv.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Content block types for messages
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Image source types
|
|
10
|
+
*/
|
|
11
|
+
type ImageSource = {
|
|
12
|
+
type: 'base64';
|
|
13
|
+
data: string;
|
|
14
|
+
} | {
|
|
15
|
+
type: 'url';
|
|
16
|
+
url: string;
|
|
17
|
+
} | {
|
|
18
|
+
type: 'bytes';
|
|
19
|
+
data: Uint8Array;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Text content block
|
|
23
|
+
*/
|
|
24
|
+
interface TextBlock {
|
|
25
|
+
type: 'text';
|
|
26
|
+
text: string;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Image content block
|
|
30
|
+
*/
|
|
31
|
+
interface ImageBlock {
|
|
32
|
+
type: 'image';
|
|
33
|
+
source: ImageSource;
|
|
34
|
+
mimeType: string;
|
|
35
|
+
width?: number;
|
|
36
|
+
height?: number;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Audio content block
|
|
40
|
+
*/
|
|
41
|
+
interface AudioBlock {
|
|
42
|
+
type: 'audio';
|
|
43
|
+
data: Uint8Array;
|
|
44
|
+
mimeType: string;
|
|
45
|
+
duration?: number;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Video content block
|
|
49
|
+
*/
|
|
50
|
+
interface VideoBlock {
|
|
51
|
+
type: 'video';
|
|
52
|
+
data: Uint8Array;
|
|
53
|
+
mimeType: string;
|
|
54
|
+
duration?: number;
|
|
55
|
+
width?: number;
|
|
56
|
+
height?: number;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Binary content block for arbitrary data
|
|
60
|
+
*/
|
|
61
|
+
interface BinaryBlock {
|
|
62
|
+
type: 'binary';
|
|
63
|
+
data: Uint8Array;
|
|
64
|
+
mimeType: string;
|
|
65
|
+
metadata?: Record<string, unknown>;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* All content block types
|
|
69
|
+
*/
|
|
70
|
+
type ContentBlock = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
|
|
71
|
+
/**
|
|
72
|
+
* Content types allowed in user messages
|
|
73
|
+
*/
|
|
74
|
+
type UserContent = TextBlock | ImageBlock | AudioBlock | VideoBlock | BinaryBlock;
|
|
75
|
+
/**
|
|
76
|
+
* Content types allowed in assistant messages
|
|
77
|
+
*/
|
|
78
|
+
type AssistantContent = TextBlock | ImageBlock | AudioBlock | VideoBlock;
|
|
79
|
+
/**
|
|
80
|
+
* Helper to create a text block
|
|
81
|
+
*/
|
|
82
|
+
declare function text(content: string): TextBlock;
|
|
83
|
+
/**
|
|
84
|
+
* Type guard for TextBlock
|
|
85
|
+
*/
|
|
86
|
+
declare function isTextBlock(block: ContentBlock): block is TextBlock;
|
|
87
|
+
/**
|
|
88
|
+
* Type guard for ImageBlock
|
|
89
|
+
*/
|
|
90
|
+
declare function isImageBlock(block: ContentBlock): block is ImageBlock;
|
|
91
|
+
/**
|
|
92
|
+
* Type guard for AudioBlock
|
|
93
|
+
*/
|
|
94
|
+
declare function isAudioBlock(block: ContentBlock): block is AudioBlock;
|
|
95
|
+
/**
|
|
96
|
+
* Type guard for VideoBlock
|
|
97
|
+
*/
|
|
98
|
+
declare function isVideoBlock(block: ContentBlock): block is VideoBlock;
|
|
99
|
+
/**
|
|
100
|
+
* Type guard for BinaryBlock
|
|
101
|
+
*/
|
|
102
|
+
declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* JSON Schema types for tool parameters and structured outputs
|
|
106
|
+
*/
|
|
107
|
+
type JSONSchemaPropertyType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
|
|
108
|
+
/**
|
|
109
|
+
* JSON Schema property definition
|
|
110
|
+
*/
|
|
111
|
+
interface JSONSchemaProperty {
|
|
112
|
+
type: JSONSchemaPropertyType;
|
|
113
|
+
description?: string;
|
|
114
|
+
enum?: unknown[];
|
|
115
|
+
const?: unknown;
|
|
116
|
+
default?: unknown;
|
|
117
|
+
minLength?: number;
|
|
118
|
+
maxLength?: number;
|
|
119
|
+
pattern?: string;
|
|
120
|
+
format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
|
|
121
|
+
minimum?: number;
|
|
122
|
+
maximum?: number;
|
|
123
|
+
exclusiveMinimum?: number;
|
|
124
|
+
exclusiveMaximum?: number;
|
|
125
|
+
multipleOf?: number;
|
|
126
|
+
items?: JSONSchemaProperty;
|
|
127
|
+
minItems?: number;
|
|
128
|
+
maxItems?: number;
|
|
129
|
+
uniqueItems?: boolean;
|
|
130
|
+
properties?: Record<string, JSONSchemaProperty>;
|
|
131
|
+
required?: string[];
|
|
132
|
+
additionalProperties?: boolean;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* JSON Schema for tool parameters or structured outputs
|
|
136
|
+
*/
|
|
137
|
+
interface JSONSchema {
|
|
138
|
+
type: 'object';
|
|
139
|
+
properties: Record<string, JSONSchemaProperty>;
|
|
140
|
+
required?: string[];
|
|
141
|
+
additionalProperties?: boolean;
|
|
142
|
+
description?: string;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Tool call requested by the model
|
|
147
|
+
*/
|
|
148
|
+
interface ToolCall {
|
|
149
|
+
toolCallId: string;
|
|
150
|
+
toolName: string;
|
|
151
|
+
arguments: Record<string, unknown>;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Result of tool execution
|
|
155
|
+
*/
|
|
156
|
+
interface ToolResult {
|
|
157
|
+
toolCallId: string;
|
|
158
|
+
result: unknown;
|
|
159
|
+
isError?: boolean;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Tool definition
|
|
163
|
+
*/
|
|
164
|
+
interface Tool<TParams = unknown, TResult = unknown> {
|
|
165
|
+
/** Tool name (must be unique within a llm() instance) */
|
|
166
|
+
name: string;
|
|
167
|
+
/** Human-readable description for the model */
|
|
168
|
+
description: string;
|
|
169
|
+
/** JSON Schema defining parameters */
|
|
170
|
+
parameters: JSONSchema;
|
|
171
|
+
/** Tool execution function */
|
|
172
|
+
run(params: TParams): TResult | Promise<TResult>;
|
|
173
|
+
/** Optional approval handler for sensitive operations */
|
|
174
|
+
approval?(params: TParams): boolean | Promise<boolean>;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Strategy for tool execution
|
|
178
|
+
*/
|
|
179
|
+
interface ToolUseStrategy {
|
|
180
|
+
/** Maximum tool execution rounds (default: 10) */
|
|
181
|
+
maxIterations?: number;
|
|
182
|
+
/** Called when the model requests a tool call */
|
|
183
|
+
onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
|
|
184
|
+
/** Called before tool execution, return false to skip */
|
|
185
|
+
onBeforeCall?(tool: Tool, params: unknown): boolean | Promise<boolean>;
|
|
186
|
+
/** Called after tool execution */
|
|
187
|
+
onAfterCall?(tool: Tool, params: unknown, result: unknown): void | Promise<void>;
|
|
188
|
+
/** Called on tool execution error */
|
|
189
|
+
onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
|
|
190
|
+
/** Called when max iterations reached */
|
|
191
|
+
onMaxIterations?(iterations: number): void | Promise<void>;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Record of a tool execution
|
|
195
|
+
*/
|
|
196
|
+
interface ToolExecution {
|
|
197
|
+
/** The tool that was called */
|
|
198
|
+
toolName: string;
|
|
199
|
+
/** Tool call ID */
|
|
200
|
+
toolCallId: string;
|
|
201
|
+
/** Arguments passed to the tool */
|
|
202
|
+
arguments: Record<string, unknown>;
|
|
203
|
+
/** Result returned by the tool */
|
|
204
|
+
result: unknown;
|
|
205
|
+
/** Whether the tool execution resulted in an error */
|
|
206
|
+
isError: boolean;
|
|
207
|
+
/** Execution duration in milliseconds */
|
|
208
|
+
duration: number;
|
|
209
|
+
/** Whether approval was required and granted */
|
|
210
|
+
approved?: boolean;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Message type discriminator
|
|
215
|
+
*/
|
|
216
|
+
type MessageType = 'user' | 'assistant' | 'tool_result';
|
|
217
|
+
/**
|
|
218
|
+
* Provider-namespaced metadata
|
|
219
|
+
* Each provider uses its own namespace
|
|
220
|
+
*/
|
|
221
|
+
interface MessageMetadata {
|
|
222
|
+
[provider: string]: Record<string, unknown> | undefined;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Options for message construction
|
|
226
|
+
*/
|
|
227
|
+
interface MessageOptions {
|
|
228
|
+
id?: string;
|
|
229
|
+
metadata?: MessageMetadata;
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* Base message class
|
|
233
|
+
* All messages inherit from this
|
|
234
|
+
*/
|
|
235
|
+
declare abstract class Message {
|
|
236
|
+
/** Unique message identifier */
|
|
237
|
+
readonly id: string;
|
|
238
|
+
/** Timestamp */
|
|
239
|
+
readonly timestamp: Date;
|
|
240
|
+
/** Provider-specific metadata, namespaced by provider */
|
|
241
|
+
readonly metadata?: MessageMetadata;
|
|
242
|
+
/** Message type discriminator */
|
|
243
|
+
abstract readonly type: MessageType;
|
|
244
|
+
/** Raw content - implemented by subclasses */
|
|
245
|
+
protected abstract getContent(): ContentBlock[];
|
|
246
|
+
constructor(options?: MessageOptions);
|
|
247
|
+
/**
|
|
248
|
+
* Convenience accessor for text content
|
|
249
|
+
* Concatenates all text blocks with '\n\n'
|
|
250
|
+
*/
|
|
251
|
+
get text(): string;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* User input message
|
|
255
|
+
*/
|
|
256
|
+
declare class UserMessage extends Message {
|
|
257
|
+
readonly type: "user";
|
|
258
|
+
readonly content: UserContent[];
|
|
259
|
+
/**
|
|
260
|
+
* @param content - String (converted to TextBlock) or array of content blocks
|
|
261
|
+
*/
|
|
262
|
+
constructor(content: string | UserContent[], options?: MessageOptions);
|
|
263
|
+
protected getContent(): ContentBlock[];
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Assistant response message
|
|
267
|
+
* May contain text, media, and/or tool calls
|
|
268
|
+
*/
|
|
269
|
+
declare class AssistantMessage extends Message {
|
|
270
|
+
readonly type: "assistant";
|
|
271
|
+
readonly content: AssistantContent[];
|
|
272
|
+
/** Tool calls requested by the model (if any) */
|
|
273
|
+
readonly toolCalls?: ToolCall[];
|
|
274
|
+
/**
|
|
275
|
+
* @param content - String (converted to TextBlock) or array of content blocks
|
|
276
|
+
* @param toolCalls - Tool calls requested by the model
|
|
277
|
+
* @param options - Message ID and metadata
|
|
278
|
+
*/
|
|
279
|
+
constructor(content: string | AssistantContent[], toolCalls?: ToolCall[], options?: MessageOptions);
|
|
280
|
+
protected getContent(): ContentBlock[];
|
|
281
|
+
/** Check if this message requests tool execution */
|
|
282
|
+
get hasToolCalls(): boolean;
|
|
283
|
+
}
|
|
284
|
+
/**
|
|
285
|
+
* Result of tool execution (sent back to model)
|
|
286
|
+
*/
|
|
287
|
+
declare class ToolResultMessage extends Message {
|
|
288
|
+
readonly type: "tool_result";
|
|
289
|
+
readonly results: ToolResult[];
|
|
290
|
+
/**
|
|
291
|
+
* @param results - Array of tool execution results
|
|
292
|
+
* @param options - Message ID and metadata
|
|
293
|
+
*/
|
|
294
|
+
constructor(results: ToolResult[], options?: MessageOptions);
|
|
295
|
+
protected getContent(): ContentBlock[];
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Type guard for UserMessage
|
|
299
|
+
*/
|
|
300
|
+
declare function isUserMessage(msg: Message): msg is UserMessage;
|
|
301
|
+
/**
|
|
302
|
+
* Type guard for AssistantMessage
|
|
303
|
+
*/
|
|
304
|
+
declare function isAssistantMessage(msg: Message): msg is AssistantMessage;
|
|
305
|
+
/**
|
|
306
|
+
* Type guard for ToolResultMessage
|
|
307
|
+
*/
|
|
308
|
+
declare function isToolResultMessage(msg: Message): msg is ToolResultMessage;
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Token usage information
|
|
312
|
+
*/
|
|
313
|
+
interface TokenUsage {
|
|
314
|
+
/** Input tokens across all cycles */
|
|
315
|
+
inputTokens: number;
|
|
316
|
+
/** Output tokens across all cycles */
|
|
317
|
+
outputTokens: number;
|
|
318
|
+
/** Total tokens */
|
|
319
|
+
totalTokens: number;
|
|
320
|
+
/** Per-cycle breakdown (if available) */
|
|
321
|
+
cycles?: Array<{
|
|
322
|
+
inputTokens: number;
|
|
323
|
+
outputTokens: number;
|
|
324
|
+
}>;
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* A Turn represents the complete result of one inference call,
|
|
328
|
+
* including all messages produced during tool execution loops.
|
|
329
|
+
*/
|
|
330
|
+
interface Turn<TData = unknown> {
|
|
331
|
+
/**
|
|
332
|
+
* All messages produced during this inference, in chronological order.
|
|
333
|
+
* Types: UserMessage, AssistantMessage (may include toolCalls), ToolResultMessage
|
|
334
|
+
*/
|
|
335
|
+
readonly messages: Message[];
|
|
336
|
+
/** The final assistant response (convenience accessor) */
|
|
337
|
+
readonly response: AssistantMessage;
|
|
338
|
+
/** Tool executions that occurred during this turn */
|
|
339
|
+
readonly toolExecutions: ToolExecution[];
|
|
340
|
+
/** Aggregate token usage for the entire turn */
|
|
341
|
+
readonly usage: TokenUsage;
|
|
342
|
+
/** Total number of inference cycles (1 + number of tool rounds) */
|
|
343
|
+
readonly cycles: number;
|
|
344
|
+
/**
|
|
345
|
+
* Structured output data (if structure was provided).
|
|
346
|
+
* Type is inferred from the schema when using TypeScript.
|
|
347
|
+
*/
|
|
348
|
+
readonly data?: TData;
|
|
349
|
+
}
|
|
350
|
+
/**
|
|
351
|
+
* Create a Turn from accumulated data
|
|
352
|
+
*/
|
|
353
|
+
declare function createTurn<TData = unknown>(messages: Message[], toolExecutions: ToolExecution[], usage: TokenUsage, cycles: number, data?: TData): Turn<TData>;
|
|
354
|
+
/**
|
|
355
|
+
* Create empty token usage
|
|
356
|
+
*/
|
|
357
|
+
declare function emptyUsage(): TokenUsage;
|
|
358
|
+
/**
|
|
359
|
+
* Aggregate token usage from multiple cycles
|
|
360
|
+
*/
|
|
361
|
+
declare function aggregateUsage(usages: TokenUsage[]): TokenUsage;
|
|
362
|
+
|
|
363
|
+
/**
|
|
364
|
+
* Stream event types
|
|
365
|
+
*/
|
|
366
|
+
type StreamEventType = 'text_delta' | 'reasoning_delta' | 'image_delta' | 'audio_delta' | 'video_delta' | 'tool_call_delta' | 'message_start' | 'message_stop' | 'content_block_start' | 'content_block_stop';
|
|
367
|
+
/**
|
|
368
|
+
* Event delta data (type-specific)
|
|
369
|
+
*/
|
|
370
|
+
interface EventDelta {
|
|
371
|
+
text?: string;
|
|
372
|
+
data?: Uint8Array;
|
|
373
|
+
toolCallId?: string;
|
|
374
|
+
toolName?: string;
|
|
375
|
+
argumentsJson?: string;
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* A streaming event
|
|
379
|
+
*/
|
|
380
|
+
interface StreamEvent {
|
|
381
|
+
/** Event type */
|
|
382
|
+
type: StreamEventType;
|
|
383
|
+
/** Index of the content block this event belongs to */
|
|
384
|
+
index: number;
|
|
385
|
+
/** Event data (type-specific) */
|
|
386
|
+
delta: EventDelta;
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Stream result - async iterable that also provides final turn
|
|
390
|
+
*/
|
|
391
|
+
interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
|
|
392
|
+
/**
|
|
393
|
+
* Get the complete Turn after streaming finishes.
|
|
394
|
+
* Resolves when the stream completes.
|
|
395
|
+
*/
|
|
396
|
+
readonly turn: Promise<Turn<TData>>;
|
|
397
|
+
/** Abort the stream */
|
|
398
|
+
abort(): void;
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Create a stream result from an async generator and completion promise
|
|
402
|
+
*/
|
|
403
|
+
declare function createStreamResult<TData = unknown>(generator: AsyncGenerator<StreamEvent, void, unknown>, turnPromise: Promise<Turn<TData>>, abortController: AbortController): StreamResult<TData>;
|
|
404
|
+
/**
|
|
405
|
+
* Create a text delta event
|
|
406
|
+
*/
|
|
407
|
+
declare function textDelta(text: string, index?: number): StreamEvent;
|
|
408
|
+
/**
|
|
409
|
+
* Create a tool call delta event
|
|
410
|
+
*/
|
|
411
|
+
declare function toolCallDelta(toolCallId: string, toolName: string, argumentsJson: string, index?: number): StreamEvent;
|
|
412
|
+
/**
|
|
413
|
+
* Create a message start event
|
|
414
|
+
*/
|
|
415
|
+
declare function messageStart(): StreamEvent;
|
|
416
|
+
/**
|
|
417
|
+
* Create a message stop event
|
|
418
|
+
*/
|
|
419
|
+
declare function messageStop(): StreamEvent;
|
|
420
|
+
/**
|
|
421
|
+
* Create a content block start event
|
|
422
|
+
*/
|
|
423
|
+
declare function contentBlockStart(index: number): StreamEvent;
|
|
424
|
+
/**
|
|
425
|
+
* Create a content block stop event
|
|
426
|
+
*/
|
|
427
|
+
declare function contentBlockStop(index: number): StreamEvent;
|
|
428
|
+
|
|
429
|
+
/**
|
|
430
|
+
* Serialized message format
|
|
431
|
+
*/
|
|
432
|
+
interface MessageJSON {
|
|
433
|
+
id: string;
|
|
434
|
+
type: MessageType;
|
|
435
|
+
content: ContentBlock[];
|
|
436
|
+
toolCalls?: ToolCall[];
|
|
437
|
+
results?: ToolResult[];
|
|
438
|
+
metadata?: MessageMetadata;
|
|
439
|
+
timestamp: string;
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* Serialized thread format
|
|
443
|
+
*/
|
|
444
|
+
interface ThreadJSON {
|
|
445
|
+
id: string;
|
|
446
|
+
messages: MessageJSON[];
|
|
447
|
+
createdAt: string;
|
|
448
|
+
updatedAt: string;
|
|
449
|
+
}
|
|
450
|
+
/**
|
|
451
|
+
* Thread - A utility class for managing conversation history
|
|
452
|
+
* Users control their own history; Thread is optional
|
|
453
|
+
*/
|
|
454
|
+
declare class Thread {
|
|
455
|
+
/** Unique thread identifier */
|
|
456
|
+
readonly id: string;
|
|
457
|
+
/** Internal message storage */
|
|
458
|
+
private _messages;
|
|
459
|
+
/** Creation timestamp */
|
|
460
|
+
private _createdAt;
|
|
461
|
+
/** Last update timestamp */
|
|
462
|
+
private _updatedAt;
|
|
463
|
+
/**
|
|
464
|
+
* Create a new thread, optionally with initial messages
|
|
465
|
+
*/
|
|
466
|
+
constructor(messages?: Message[]);
|
|
467
|
+
/** All messages in the thread (readonly) */
|
|
468
|
+
get messages(): readonly Message[];
|
|
469
|
+
/** Number of messages */
|
|
470
|
+
get length(): number;
|
|
471
|
+
/**
|
|
472
|
+
* Append messages from a turn
|
|
473
|
+
*/
|
|
474
|
+
append(turn: Turn): this;
|
|
475
|
+
/**
|
|
476
|
+
* Add raw messages
|
|
477
|
+
*/
|
|
478
|
+
push(...messages: Message[]): this;
|
|
479
|
+
/**
|
|
480
|
+
* Add a user message
|
|
481
|
+
*/
|
|
482
|
+
user(content: string | UserContent[]): this;
|
|
483
|
+
/**
|
|
484
|
+
* Add an assistant message
|
|
485
|
+
*/
|
|
486
|
+
assistant(content: string | AssistantContent[]): this;
|
|
487
|
+
/**
|
|
488
|
+
* Get messages by type
|
|
489
|
+
*/
|
|
490
|
+
filter(type: MessageType): Message[];
|
|
491
|
+
/**
|
|
492
|
+
* Get the last N messages
|
|
493
|
+
*/
|
|
494
|
+
tail(count: number): Message[];
|
|
495
|
+
/**
|
|
496
|
+
* Create a new thread with a subset of messages
|
|
497
|
+
*/
|
|
498
|
+
slice(start?: number, end?: number): Thread;
|
|
499
|
+
/**
|
|
500
|
+
* Clear all messages
|
|
501
|
+
*/
|
|
502
|
+
clear(): this;
|
|
503
|
+
/**
|
|
504
|
+
* Convert to plain message array
|
|
505
|
+
*/
|
|
506
|
+
toMessages(): Message[];
|
|
507
|
+
/**
|
|
508
|
+
* Serialize to JSON
|
|
509
|
+
*/
|
|
510
|
+
toJSON(): ThreadJSON;
|
|
511
|
+
/**
|
|
512
|
+
* Deserialize from JSON
|
|
513
|
+
*/
|
|
514
|
+
static fromJSON(json: ThreadJSON): Thread;
|
|
515
|
+
/**
|
|
516
|
+
* Iterate over messages
|
|
517
|
+
*/
|
|
518
|
+
[Symbol.iterator](): Iterator<Message>;
|
|
519
|
+
/**
|
|
520
|
+
* Convert a message to JSON
|
|
521
|
+
*/
|
|
522
|
+
private messageToJSON;
|
|
523
|
+
/**
|
|
524
|
+
* Reconstruct a message from JSON
|
|
525
|
+
*/
|
|
526
|
+
private static messageFromJSON;
|
|
527
|
+
}
|
|
528
|
+
|
|
529
|
+
/**
|
|
530
|
+
* LLMCapabilities declares what the provider's API supports, not individual model capabilities.
|
|
531
|
+
* If a user attempts to use a feature with a model that doesn't support it,
|
|
532
|
+
* the provider's API will return an error—this is expected behavior.
|
|
533
|
+
*
|
|
534
|
+
* Capabilities are static - they are constant for the lifetime of the provider instance
|
|
535
|
+
* and do not vary per-request or per-model.
|
|
536
|
+
*/
|
|
537
|
+
interface LLMCapabilities {
|
|
538
|
+
/** Provider API supports streaming responses */
|
|
539
|
+
streaming: boolean;
|
|
540
|
+
/** Provider API supports tool/function calling */
|
|
541
|
+
tools: boolean;
|
|
542
|
+
/** Provider API supports native structured output (JSON schema) */
|
|
543
|
+
structuredOutput: boolean;
|
|
544
|
+
/** Provider API supports image input */
|
|
545
|
+
imageInput: boolean;
|
|
546
|
+
/** Provider API supports video input */
|
|
547
|
+
videoInput: boolean;
|
|
548
|
+
/** Provider API supports audio input */
|
|
549
|
+
audioInput: boolean;
|
|
550
|
+
}
|
|
551
|
+
/**
|
|
552
|
+
* Input types for inference
|
|
553
|
+
*/
|
|
554
|
+
type InferenceInput = string | Message | ContentBlock;
|
|
555
|
+
/**
|
|
556
|
+
* Options for llm() function
|
|
557
|
+
*/
|
|
558
|
+
interface LLMOptions<TParams = unknown> {
|
|
559
|
+
/** A model reference from a provider factory */
|
|
560
|
+
model: ModelReference<any>;
|
|
561
|
+
/** Provider infrastructure configuration (optional - uses env vars if omitted) */
|
|
562
|
+
config?: ProviderConfig;
|
|
563
|
+
/** Model-specific parameters (temperature, max_tokens, etc.) */
|
|
564
|
+
params?: TParams;
|
|
565
|
+
/** System prompt for all inferences */
|
|
566
|
+
system?: string;
|
|
567
|
+
/** Tools available to the model */
|
|
568
|
+
tools?: Tool[];
|
|
569
|
+
/** Tool execution strategy */
|
|
570
|
+
toolStrategy?: ToolUseStrategy;
|
|
571
|
+
/** Structured output schema (JSON Schema) */
|
|
572
|
+
structure?: JSONSchema;
|
|
573
|
+
}
|
|
574
|
+
/**
|
|
575
|
+
* LLM instance returned by llm()
|
|
576
|
+
*/
|
|
577
|
+
interface LLMInstance<TParams = unknown> {
|
|
578
|
+
/**
|
|
579
|
+
* Execute inference and return complete Turn
|
|
580
|
+
*
|
|
581
|
+
* @overload No history - single input
|
|
582
|
+
* generate(input: InferenceInput): Promise<Turn>
|
|
583
|
+
*
|
|
584
|
+
* @overload No history - multiple inputs
|
|
585
|
+
* generate(...inputs: InferenceInput[]): Promise<Turn>
|
|
586
|
+
*
|
|
587
|
+
* @overload With history
|
|
588
|
+
* generate(history: Message[] | Thread, ...inputs: InferenceInput[]): Promise<Turn>
|
|
589
|
+
*/
|
|
590
|
+
generate(historyOrInput: Message[] | Thread | InferenceInput, ...input: InferenceInput[]): Promise<Turn>;
|
|
591
|
+
/**
|
|
592
|
+
* Execute streaming inference
|
|
593
|
+
*
|
|
594
|
+
* @overload No history - single input
|
|
595
|
+
* stream(input: InferenceInput): StreamResult
|
|
596
|
+
*
|
|
597
|
+
* @overload No history - multiple inputs
|
|
598
|
+
* stream(...inputs: InferenceInput[]): StreamResult
|
|
599
|
+
*
|
|
600
|
+
* @overload With history
|
|
601
|
+
* stream(history: Message[] | Thread, ...inputs: InferenceInput[]): StreamResult
|
|
602
|
+
*/
|
|
603
|
+
stream(historyOrInput: Message[] | Thread | InferenceInput, ...input: InferenceInput[]): StreamResult;
|
|
604
|
+
/** The bound model */
|
|
605
|
+
readonly model: BoundLLMModel<TParams>;
|
|
606
|
+
/** Current system prompt */
|
|
607
|
+
readonly system: string | undefined;
|
|
608
|
+
/** Current parameters */
|
|
609
|
+
readonly params: TParams | undefined;
|
|
610
|
+
/** Provider API capabilities */
|
|
611
|
+
readonly capabilities: LLMCapabilities;
|
|
612
|
+
}
|
|
613
|
+
/**
|
|
614
|
+
* Request passed from llm() core to providers
|
|
615
|
+
* Note: config is required here because llm() core resolves defaults
|
|
616
|
+
* before passing to providers
|
|
617
|
+
*/
|
|
618
|
+
interface LLMRequest<TParams = unknown> {
|
|
619
|
+
/** All messages for this request (history + new input) */
|
|
620
|
+
messages: Message[];
|
|
621
|
+
/** System prompt */
|
|
622
|
+
system?: string;
|
|
623
|
+
/** Model-specific parameters (passed through unchanged) */
|
|
624
|
+
params?: TParams;
|
|
625
|
+
/** Tools available for this request */
|
|
626
|
+
tools?: Tool[];
|
|
627
|
+
/** Structured output schema (if requested) */
|
|
628
|
+
structure?: JSONSchema;
|
|
629
|
+
/** Provider infrastructure config (resolved by llm() core) */
|
|
630
|
+
config: ProviderConfig;
|
|
631
|
+
/** Abort signal for cancellation */
|
|
632
|
+
signal?: AbortSignal;
|
|
633
|
+
}
|
|
634
|
+
/**
|
|
635
|
+
* Raw provider response (single cycle, no tool loop)
|
|
636
|
+
*/
|
|
637
|
+
interface LLMResponse {
|
|
638
|
+
message: AssistantMessage;
|
|
639
|
+
usage: TokenUsage;
|
|
640
|
+
stopReason: string;
|
|
641
|
+
/**
|
|
642
|
+
* Structured output data extracted by the provider.
|
|
643
|
+
* Present when a structure schema was requested and the provider
|
|
644
|
+
* successfully extracted the data (via tool call or native JSON mode).
|
|
645
|
+
* Providers handle their own extraction logic - core just uses this value.
|
|
646
|
+
*/
|
|
647
|
+
data?: unknown;
|
|
648
|
+
}
|
|
649
|
+
/**
|
|
650
|
+
* Raw provider stream result
|
|
651
|
+
*/
|
|
652
|
+
interface LLMStreamResult extends AsyncIterable<StreamEvent> {
|
|
653
|
+
readonly response: Promise<LLMResponse>;
|
|
654
|
+
}
|
|
655
|
+
/**
|
|
656
|
+
* Bound LLM model - full definition
|
|
657
|
+
*/
|
|
658
|
+
interface BoundLLMModel<TParams = unknown> {
|
|
659
|
+
/** The model identifier */
|
|
660
|
+
readonly modelId: string;
|
|
661
|
+
/** Reference to the parent provider */
|
|
662
|
+
readonly provider: LLMProvider<TParams>;
|
|
663
|
+
/** Provider API capabilities */
|
|
664
|
+
readonly capabilities: LLMCapabilities;
|
|
665
|
+
/** Execute a single non-streaming inference request */
|
|
666
|
+
complete(request: LLMRequest<TParams>): Promise<LLMResponse>;
|
|
667
|
+
/** Execute a single streaming inference request */
|
|
668
|
+
stream(request: LLMRequest<TParams>): LLMStreamResult;
|
|
669
|
+
}
|
|
670
|
+
/**
|
|
671
|
+
* LLM Handler for providers
|
|
672
|
+
*/
|
|
673
|
+
interface LLMHandler<TParams = unknown> {
|
|
674
|
+
/** Bind model ID to create executable model */
|
|
675
|
+
bind(modelId: string): BoundLLMModel<TParams>;
|
|
676
|
+
/**
|
|
677
|
+
* Internal: Set the parent provider reference.
|
|
678
|
+
* Called by createProvider() after the provider is constructed.
|
|
679
|
+
* This allows bind() to return models with the correct provider reference.
|
|
680
|
+
* @internal
|
|
681
|
+
*/
|
|
682
|
+
_setProvider?(provider: LLMProvider<TParams>): void;
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
/**
|
|
686
|
+
* Create an LLM instance
|
|
687
|
+
*/
|
|
688
|
+
declare function llm<TParams = unknown>(options: LLMOptions<TParams>): LLMInstance<TParams>;
|
|
689
|
+
|
|
690
|
+
/**
|
|
691
|
+
* Options for creating a provider
|
|
692
|
+
*/
|
|
693
|
+
interface CreateProviderOptions {
|
|
694
|
+
name: string;
|
|
695
|
+
version: string;
|
|
696
|
+
modalities: {
|
|
697
|
+
llm?: LLMHandler$1;
|
|
698
|
+
embedding?: EmbeddingHandler;
|
|
699
|
+
image?: ImageHandler;
|
|
700
|
+
};
|
|
701
|
+
}
|
|
702
|
+
/**
|
|
703
|
+
* Create a provider factory function
|
|
704
|
+
*
|
|
705
|
+
* @typeParam TOptions - Provider-specific options type (defaults to unknown)
|
|
706
|
+
* @param options - Provider configuration
|
|
707
|
+
* @returns Provider function with modalities attached
|
|
708
|
+
*
|
|
709
|
+
* @example
|
|
710
|
+
* ```ts
|
|
711
|
+
* // Basic provider without options
|
|
712
|
+
* const anthropic = createProvider({
|
|
713
|
+
* name: 'anthropic',
|
|
714
|
+
* version: '1.0.0',
|
|
715
|
+
* modalities: { llm: createLLMHandler() },
|
|
716
|
+
* });
|
|
717
|
+
*
|
|
718
|
+
* // Provider with custom options (typically needs custom factory)
|
|
719
|
+
* interface MyProviderOptions { api?: 'v1' | 'v2' }
|
|
720
|
+
* const myProvider = createProvider<MyProviderOptions>({
|
|
721
|
+
* name: 'my-provider',
|
|
722
|
+
* version: '1.0.0',
|
|
723
|
+
* modalities: { llm: createLLMHandler() },
|
|
724
|
+
* });
|
|
725
|
+
* ```
|
|
726
|
+
*/
|
|
727
|
+
declare function createProvider<TOptions = unknown>(options: CreateProviderOptions): Provider<TOptions>;
|
|
728
|
+
|
|
729
|
+
/**
|
|
730
|
+
* Image class for handling images in UPP
|
|
731
|
+
*/
|
|
732
|
+
declare class Image {
|
|
733
|
+
readonly source: ImageSource;
|
|
734
|
+
readonly mimeType: string;
|
|
735
|
+
readonly width?: number;
|
|
736
|
+
readonly height?: number;
|
|
737
|
+
private constructor();
|
|
738
|
+
/**
|
|
739
|
+
* Check if this image has data loaded (false for URL sources)
|
|
740
|
+
*/
|
|
741
|
+
get hasData(): boolean;
|
|
742
|
+
/**
|
|
743
|
+
* Convert to base64 string (throws if source is URL)
|
|
744
|
+
*/
|
|
745
|
+
toBase64(): string;
|
|
746
|
+
/**
|
|
747
|
+
* Convert to data URL (throws if source is URL)
|
|
748
|
+
*/
|
|
749
|
+
toDataUrl(): string;
|
|
750
|
+
/**
|
|
751
|
+
* Get raw bytes (throws if source is URL)
|
|
752
|
+
*/
|
|
753
|
+
toBytes(): Uint8Array;
|
|
754
|
+
/**
|
|
755
|
+
* Get the URL (only for URL sources)
|
|
756
|
+
*/
|
|
757
|
+
toUrl(): string;
|
|
758
|
+
/**
|
|
759
|
+
* Convert to ImageBlock for use in messages
|
|
760
|
+
*/
|
|
761
|
+
toBlock(): ImageBlock;
|
|
762
|
+
/**
|
|
763
|
+
* Create from file path (reads file into memory)
|
|
764
|
+
*/
|
|
765
|
+
static fromPath(path: string): Promise<Image>;
|
|
766
|
+
/**
|
|
767
|
+
* Create from URL reference (does not fetch - providers handle URL conversion)
|
|
768
|
+
*/
|
|
769
|
+
static fromUrl(url: string, mimeType?: string): Image;
|
|
770
|
+
/**
|
|
771
|
+
* Create from raw bytes
|
|
772
|
+
*/
|
|
773
|
+
static fromBytes(data: Uint8Array, mimeType: string): Image;
|
|
774
|
+
/**
|
|
775
|
+
* Create from base64 string
|
|
776
|
+
*/
|
|
777
|
+
static fromBase64(base64: string, mimeType: string): Image;
|
|
778
|
+
/**
|
|
779
|
+
* Create from an existing ImageBlock
|
|
780
|
+
*/
|
|
781
|
+
static fromBlock(block: ImageBlock): Image;
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
/**
|
|
785
|
+
* UPP namespace object
|
|
786
|
+
* Provides ai.llm(), ai.embedding(), ai.image() style access
|
|
787
|
+
*/
|
|
788
|
+
declare const ai: {
|
|
789
|
+
llm: typeof llm;
|
|
790
|
+
};
|
|
791
|
+
|
|
792
|
+
export { type AssistantContent, AssistantMessage, type AudioBlock, type BinaryBlock, type BoundLLMModel, type ContentBlock, EmbeddingHandler, type EventDelta, Image, type ImageBlock, ImageHandler, type ImageSource, type InferenceInput, type JSONSchema, type JSONSchemaProperty, type JSONSchemaPropertyType, type LLMCapabilities, type LLMHandler, type LLMInstance, type LLMOptions, LLMProvider, type LLMRequest, type LLMResponse, type LLMStreamResult, Message, type MessageJSON, type MessageMetadata, type MessageOptions, type MessageType, ModelReference, Provider, ProviderConfig, type StreamEvent, type StreamEventType, type StreamResult, type TextBlock, Thread, type ThreadJSON, type TokenUsage, type Tool, type ToolCall, type ToolExecution, type ToolResult, ToolResultMessage, type ToolUseStrategy, type Turn, type UserContent, UserMessage, type VideoBlock, aggregateUsage, ai, contentBlockStart, contentBlockStop, createProvider, createStreamResult, createTurn, emptyUsage, isAssistantMessage, isAudioBlock, isBinaryBlock, isImageBlock, isTextBlock, isToolResultMessage, isUserMessage, isVideoBlock, llm, messageStart, messageStop, text, textDelta, toolCallDelta };
|