@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.
Files changed (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +84 -0
  3. package/dist/anthropic/index.d.ts +41 -0
  4. package/dist/anthropic/index.js +500 -0
  5. package/dist/anthropic/index.js.map +1 -0
  6. package/dist/chunk-CUCRF5W6.js +136 -0
  7. package/dist/chunk-CUCRF5W6.js.map +1 -0
  8. package/dist/chunk-FTFX2VET.js +424 -0
  9. package/dist/chunk-FTFX2VET.js.map +1 -0
  10. package/dist/chunk-QUUX4G7U.js +117 -0
  11. package/dist/chunk-QUUX4G7U.js.map +1 -0
  12. package/dist/chunk-Y6Q7JCNP.js +39 -0
  13. package/dist/chunk-Y6Q7JCNP.js.map +1 -0
  14. package/dist/google/index.d.ts +69 -0
  15. package/dist/google/index.js +517 -0
  16. package/dist/google/index.js.map +1 -0
  17. package/dist/http/index.d.ts +61 -0
  18. package/dist/http/index.js +43 -0
  19. package/dist/http/index.js.map +1 -0
  20. package/dist/index.d.ts +792 -0
  21. package/dist/index.js +898 -0
  22. package/dist/index.js.map +1 -0
  23. package/dist/openai/index.d.ts +204 -0
  24. package/dist/openai/index.js +1340 -0
  25. package/dist/openai/index.js.map +1 -0
  26. package/dist/provider-CUJWjgNl.d.ts +192 -0
  27. package/dist/retry-I2661_rv.d.ts +118 -0
  28. package/package.json +88 -0
  29. package/src/anthropic/index.ts +3 -0
  30. package/src/core/image.ts +188 -0
  31. package/src/core/llm.ts +619 -0
  32. package/src/core/provider.ts +92 -0
  33. package/src/google/index.ts +3 -0
  34. package/src/http/errors.ts +112 -0
  35. package/src/http/fetch.ts +210 -0
  36. package/src/http/index.ts +31 -0
  37. package/src/http/keys.ts +136 -0
  38. package/src/http/retry.ts +205 -0
  39. package/src/http/sse.ts +136 -0
  40. package/src/index.ts +32 -0
  41. package/src/openai/index.ts +9 -0
  42. package/src/providers/anthropic/index.ts +17 -0
  43. package/src/providers/anthropic/llm.ts +196 -0
  44. package/src/providers/anthropic/transform.ts +452 -0
  45. package/src/providers/anthropic/types.ts +213 -0
  46. package/src/providers/google/index.ts +17 -0
  47. package/src/providers/google/llm.ts +203 -0
  48. package/src/providers/google/transform.ts +487 -0
  49. package/src/providers/google/types.ts +214 -0
  50. package/src/providers/openai/index.ts +151 -0
  51. package/src/providers/openai/llm.completions.ts +201 -0
  52. package/src/providers/openai/llm.responses.ts +211 -0
  53. package/src/providers/openai/transform.completions.ts +628 -0
  54. package/src/providers/openai/transform.responses.ts +718 -0
  55. package/src/providers/openai/types.ts +711 -0
  56. package/src/types/content.ts +133 -0
  57. package/src/types/errors.ts +85 -0
  58. package/src/types/index.ts +105 -0
  59. package/src/types/llm.ts +211 -0
  60. package/src/types/messages.ts +182 -0
  61. package/src/types/provider.ts +195 -0
  62. package/src/types/schema.ts +58 -0
  63. package/src/types/stream.ts +146 -0
  64. package/src/types/thread.ts +226 -0
  65. package/src/types/tool.ts +88 -0
  66. package/src/types/turn.ts +118 -0
  67. package/src/utils/id.ts +28 -0
@@ -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 };