@providerprotocol/ai 0.0.37 → 0.0.39

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 (85) hide show
  1. package/README.md +94 -3
  2. package/dist/anthropic/index.d.ts +3 -2
  3. package/dist/cerebras/index.d.ts +3 -2
  4. package/dist/chunk-3Q5VELKG.js +124 -0
  5. package/dist/chunk-3Q5VELKG.js.map +1 -0
  6. package/dist/{chunk-LTEMH3CI.js → chunk-5XPRVUOK.js} +6 -4
  7. package/dist/{chunk-LTEMH3CI.js.map → chunk-5XPRVUOK.js.map} +1 -1
  8. package/dist/chunk-7ULSRWDH.js +83 -0
  9. package/dist/chunk-7ULSRWDH.js.map +1 -0
  10. package/dist/{chunk-YQLR3XOA.js → chunk-BIBMNP7Y.js} +1 -75
  11. package/dist/chunk-BIBMNP7Y.js.map +1 -0
  12. package/dist/{chunk-7GTWHZY2.js → chunk-IDZR4ROP.js} +5 -3
  13. package/dist/{chunk-7GTWHZY2.js.map → chunk-IDZR4ROP.js.map} +1 -1
  14. package/dist/{chunk-4RX4VQCB.js → chunk-IIMTP3XC.js} +2 -2
  15. package/dist/{chunk-ZRVNAET3.js → chunk-KNBODIQU.js} +6 -3
  16. package/dist/chunk-KNBODIQU.js.map +1 -0
  17. package/dist/{chunk-FYSZFIZS.js → chunk-O32SBS6S.js} +5 -3
  18. package/dist/{chunk-FYSZFIZS.js.map → chunk-O32SBS6S.js.map} +1 -1
  19. package/dist/{chunk-IK6NRCW5.js → chunk-RDC5GYST.js} +7 -7
  20. package/dist/{chunk-5IWHCXKN.js → chunk-SAMIK4WZ.js} +2 -2
  21. package/dist/{chunk-EPB3GQNL.js → chunk-U6M3MXNI.js} +11 -2
  22. package/dist/chunk-U6M3MXNI.js.map +1 -0
  23. package/dist/{chunk-2YXFLRQ6.js → chunk-WNB5PSY6.js} +2 -2
  24. package/dist/{chunk-CRP6Y7NF.js → chunk-ZDYEDI2A.js} +2 -2
  25. package/dist/{embedding-CwZ1ZNWv.d.ts → embedding-iNQCeXfk.d.ts} +1 -1
  26. package/dist/google/index.d.ts +3 -2
  27. package/dist/groq/index.d.ts +3 -2
  28. package/dist/http/index.d.ts +4 -3
  29. package/dist/{image-stream-CeQHtjxS.d.ts → image-stream-ARno6XlS.d.ts} +1 -1
  30. package/dist/index.d.ts +8 -7
  31. package/dist/index.js +11 -2
  32. package/dist/index.js.map +1 -1
  33. package/dist/{llm-DS_-l71X.d.ts → llm-CZqlijjK.d.ts} +16 -9
  34. package/dist/middleware/logging/index.d.ts +3 -2
  35. package/dist/middleware/parsed-object/index.d.ts +3 -2
  36. package/dist/middleware/persistence/index.d.ts +3 -2
  37. package/dist/middleware/pubsub/index.d.ts +5 -4
  38. package/dist/middleware/pubsub/index.js +49 -3
  39. package/dist/middleware/pubsub/index.js.map +1 -1
  40. package/dist/middleware/pubsub/server/express/index.d.ts +3 -2
  41. package/dist/middleware/pubsub/server/express/index.js +2 -2
  42. package/dist/middleware/pubsub/server/fastify/index.d.ts +3 -2
  43. package/dist/middleware/pubsub/server/fastify/index.js +2 -2
  44. package/dist/middleware/pubsub/server/h3/index.d.ts +3 -2
  45. package/dist/middleware/pubsub/server/h3/index.js +2 -2
  46. package/dist/middleware/pubsub/server/index.d.ts +3 -2
  47. package/dist/middleware/pubsub/server/index.js +5 -5
  48. package/dist/middleware/pubsub/server/webapi/index.d.ts +3 -2
  49. package/dist/middleware/pubsub/server/webapi/index.js +2 -2
  50. package/dist/moonshot/index.d.ts +511 -0
  51. package/dist/moonshot/index.js +1090 -0
  52. package/dist/moonshot/index.js.map +1 -0
  53. package/dist/ollama/index.d.ts +3 -2
  54. package/dist/openai/index.d.ts +3 -2
  55. package/dist/openrouter/index.d.ts +3 -2
  56. package/dist/proxy/index.d.ts +5 -4
  57. package/dist/proxy/index.js +12 -10
  58. package/dist/proxy/index.js.map +1 -1
  59. package/dist/proxy/server/express/index.d.ts +5 -4
  60. package/dist/proxy/server/express/index.js +3 -2
  61. package/dist/proxy/server/fastify/index.d.ts +5 -4
  62. package/dist/proxy/server/fastify/index.js +3 -2
  63. package/dist/proxy/server/h3/index.d.ts +19 -17
  64. package/dist/proxy/server/h3/index.js +3 -2
  65. package/dist/proxy/server/index.d.ts +5 -4
  66. package/dist/proxy/server/index.js +9 -8
  67. package/dist/proxy/server/webapi/index.d.ts +5 -4
  68. package/dist/proxy/server/webapi/index.js +3 -2
  69. package/dist/responses/index.d.ts +3 -2
  70. package/dist/{retry-CgoBNa51.d.ts → retry-C1eJbEMV.d.ts} +1 -1
  71. package/dist/{stream-sXhBtWjl.d.ts → stream-DVVUIKpz.d.ts} +3 -416
  72. package/dist/tool-D22EhP5F.d.ts +507 -0
  73. package/dist/{types-Cr4F0tVy.d.ts → types-CyXF0J7C.d.ts} +16 -3
  74. package/dist/utils/index.d.ts +65 -1
  75. package/dist/utils/index.js +15 -1
  76. package/dist/xai/index.d.ts +3 -2
  77. package/package.json +22 -3
  78. package/dist/chunk-EPB3GQNL.js.map +0 -1
  79. package/dist/chunk-YQLR3XOA.js.map +0 -1
  80. package/dist/chunk-ZRVNAET3.js.map +0 -1
  81. /package/dist/{chunk-4RX4VQCB.js.map → chunk-IIMTP3XC.js.map} +0 -0
  82. /package/dist/{chunk-IK6NRCW5.js.map → chunk-RDC5GYST.js.map} +0 -0
  83. /package/dist/{chunk-5IWHCXKN.js.map → chunk-SAMIK4WZ.js.map} +0 -0
  84. /package/dist/{chunk-2YXFLRQ6.js.map → chunk-WNB5PSY6.js.map} +0 -0
  85. /package/dist/{chunk-CRP6Y7NF.js.map → chunk-ZDYEDI2A.js.map} +0 -0
@@ -1,7 +1,8 @@
1
- import { T as Turn, i as StreamResult } from '../../../stream-sXhBtWjl.js';
2
- import { d as EmbeddingResult } from '../../../embedding-CwZ1ZNWv.js';
3
- import { N as ImageResult } from '../../../llm-DS_-l71X.js';
4
- import { I as ImageStreamLike } from '../../../image-stream-CeQHtjxS.js';
1
+ import { T as Turn, g as StreamResult } from '../../../stream-DVVUIKpz.js';
2
+ import { d as EmbeddingResult } from '../../../embedding-iNQCeXfk.js';
3
+ import { N as ImageResult } from '../../../llm-CZqlijjK.js';
4
+ import { I as ImageStreamLike } from '../../../image-stream-ARno6XlS.js';
5
+ import '../../../tool-D22EhP5F.js';
5
6
 
6
7
  /**
7
8
  * @fileoverview H3/Nitro/Nuxt adapter for proxy server.
@@ -18,6 +19,7 @@ import { I as ImageStreamLike } from '../../../image-stream-CeQHtjxS.js';
18
19
  interface H3Event {
19
20
  node: {
20
21
  res: {
22
+ statusCode: number;
21
23
  setHeader(name: string, value: string): void;
22
24
  write(chunk: string): boolean;
23
25
  end(): void;
@@ -57,14 +59,14 @@ declare function sendImageJSON(result: ImageResult, event: H3Event): unknown;
57
59
  /**
58
60
  * Stream a StreamResult as Server-Sent Events.
59
61
  *
60
- * @param stream - The StreamResult from instance.stream()
61
- * @param event - H3 event object
62
- *
63
- * @example
62
+ * Note: For better H3/Nuxt integration, prefer using `createSSEStream` with `sendStream`:
64
63
  * ```typescript
65
- * const stream = instance.stream(messages);
66
- * return h3Adapter.streamSSE(stream, event);
64
+ * import { sendStream } from 'h3';
65
+ * return sendStream(event, h3Adapter.createSSEStream(stream));
67
66
  * ```
67
+ *
68
+ * @param stream - The StreamResult from instance.stream()
69
+ * @param event - H3 event object
68
70
  */
69
71
  declare function streamSSE(stream: StreamResult, event: H3Event): void;
70
72
  /**
@@ -95,7 +97,7 @@ declare function createSSEStream(stream: StreamResult): ReadableStream<Uint8Arra
95
97
  */
96
98
  declare function createImageSSEStream(stream: ImageStreamLike): ReadableStream<Uint8Array>;
97
99
  /**
98
- * Send an error response.
100
+ * Send an error response with proper HTTP status.
99
101
  *
100
102
  * @param message - Error message
101
103
  * @param status - HTTP status code
@@ -112,10 +114,10 @@ declare function sendError(message: string, status: number, event: H3Event): {
112
114
  * @example Basic usage
113
115
  * ```typescript
114
116
  * // Nuxt server route: server/api/ai.post.ts
117
+ * import { sendStream } from 'h3';
115
118
  * import { llm } from '@providerprotocol/ai';
116
119
  * import { anthropic } from '@providerprotocol/ai/anthropic';
117
- * import { parseBody } from '@providerprotocol/ai/proxy';
118
- * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
120
+ * import { parseBody, h3 as h3Adapter } from '@providerprotocol/ai/proxy';
119
121
  *
120
122
  * export default defineEventHandler(async (event) => {
121
123
  * const body = await readBody(event);
@@ -124,7 +126,7 @@ declare function sendError(message: string, status: number, event: H3Event): {
124
126
  *
125
127
  * const wantsStream = getHeader(event, 'accept')?.includes('text/event-stream');
126
128
  * if (wantsStream) {
127
- * return h3Adapter.streamSSE(instance.stream(messages), event);
129
+ * return sendStream(event, h3Adapter.createSSEStream(instance.stream(messages)));
128
130
  * } else {
129
131
  * const turn = await instance.generate(messages);
130
132
  * return h3Adapter.sendJSON(turn, event);
@@ -135,11 +137,11 @@ declare function sendError(message: string, status: number, event: H3Event): {
135
137
  * @example API Gateway with authentication (Nuxt)
136
138
  * ```typescript
137
139
  * // server/api/ai.post.ts
140
+ * import { sendStream } from 'h3';
138
141
  * import { llm } from '@providerprotocol/ai';
139
142
  * import { anthropic } from '@providerprotocol/ai/anthropic';
140
143
  * import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
141
- * import { parseBody } from '@providerprotocol/ai/proxy';
142
- * import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
144
+ * import { parseBody, h3 as h3Adapter } from '@providerprotocol/ai/proxy';
143
145
  *
144
146
  * // Server manages AI provider keys - users never see them
145
147
  * const claude = llm({
@@ -168,7 +170,7 @@ declare function sendError(message: string, status: number, event: H3Event): {
168
170
  * const { messages, system, params } = parseBody(body);
169
171
  *
170
172
  * if (params?.stream) {
171
- * return h3Adapter.streamSSE(claude.stream(messages, { system }), event);
173
+ * return sendStream(event, h3Adapter.createSSEStream(claude.stream(messages, { system })));
172
174
  * }
173
175
  * const turn = await claude.generate(messages, { system });
174
176
  * return h3Adapter.sendJSON(turn, event);
@@ -8,8 +8,9 @@ import {
8
8
  sendJSON,
9
9
  streamImageSSE,
10
10
  streamSSE
11
- } from "../../../chunk-ZRVNAET3.js";
12
- import "../../../chunk-YQLR3XOA.js";
11
+ } from "../../../chunk-KNBODIQU.js";
12
+ import "../../../chunk-BIBMNP7Y.js";
13
+ import "../../../chunk-7ULSRWDH.js";
13
14
  import "../../../chunk-ETBFOLQN.js";
14
15
  import "../../../chunk-N5DX5JW3.js";
15
16
  import "../../../chunk-WU4U6IHF.js";
@@ -6,10 +6,11 @@ import { sendJSON, sendEmbeddingJSON, sendImageJSON, streamSSE, streamImageSSE,
6
6
  export { express } from './express/index.js';
7
7
  import { parseBody, parseEmbeddingBody, parseImageBody, toJSON, toEmbeddingJSON, toImageJSON, toSSE, toImageSSE, toError, bindTools } from './webapi/index.js';
8
8
  export { ParsedEmbeddingRequest, ParsedImageRequest, ParsedRequest, webapi } from './webapi/index.js';
9
- import { M as Message, J as JSONSchema, H as ToolMetadata, T as Turn, i as StreamResult } from '../../stream-sXhBtWjl.js';
10
- import '../../embedding-CwZ1ZNWv.js';
11
- import '../../llm-DS_-l71X.js';
12
- import '../../image-stream-CeQHtjxS.js';
9
+ import { M as Message, T as Turn, g as StreamResult } from '../../stream-DVVUIKpz.js';
10
+ import { J as JSONSchema, j as ToolMetadata } from '../../tool-D22EhP5F.js';
11
+ import '../../embedding-iNQCeXfk.js';
12
+ import '../../llm-CZqlijjK.js';
13
+ import '../../image-stream-ARno6XlS.js';
13
14
 
14
15
  /**
15
16
  * @fileoverview Shared types for proxy server adapters.
@@ -1,12 +1,15 @@
1
1
  import {
2
2
  server
3
- } from "../../chunk-IK6NRCW5.js";
3
+ } from "../../chunk-RDC5GYST.js";
4
+ import {
5
+ express
6
+ } from "../../chunk-O32SBS6S.js";
4
7
  import {
5
8
  h3
6
- } from "../../chunk-ZRVNAET3.js";
9
+ } from "../../chunk-KNBODIQU.js";
7
10
  import {
8
11
  fastify
9
- } from "../../chunk-7GTWHZY2.js";
12
+ } from "../../chunk-IDZR4ROP.js";
10
13
  import {
11
14
  bindTools,
12
15
  parseBody,
@@ -19,11 +22,9 @@ import {
19
22
  toJSON,
20
23
  toSSE,
21
24
  webapi
22
- } from "../../chunk-LTEMH3CI.js";
23
- import {
24
- express
25
- } from "../../chunk-FYSZFIZS.js";
26
- import "../../chunk-YQLR3XOA.js";
25
+ } from "../../chunk-5XPRVUOK.js";
26
+ import "../../chunk-BIBMNP7Y.js";
27
+ import "../../chunk-7ULSRWDH.js";
27
28
  import "../../chunk-ETBFOLQN.js";
28
29
  import "../../chunk-N5DX5JW3.js";
29
30
  import "../../chunk-WU4U6IHF.js";
@@ -1,7 +1,8 @@
1
- import { M as Message, J as JSONSchema, H as ToolMetadata, T as Turn, i as StreamResult, d as Tool } from '../../../stream-sXhBtWjl.js';
2
- import { o as Image, E as EmbeddingInput, N as ImageResult } from '../../../llm-DS_-l71X.js';
3
- import { d as EmbeddingResult } from '../../../embedding-CwZ1ZNWv.js';
4
- import { I as ImageStreamLike } from '../../../image-stream-CeQHtjxS.js';
1
+ import { M as Message, T as Turn, g as StreamResult } from '../../../stream-DVVUIKpz.js';
2
+ import { o as Image, E as EmbeddingInput, N as ImageResult } from '../../../llm-CZqlijjK.js';
3
+ import { J as JSONSchema, j as ToolMetadata, b as Tool } from '../../../tool-D22EhP5F.js';
4
+ import { d as EmbeddingResult } from '../../../embedding-iNQCeXfk.js';
5
+ import { I as ImageStreamLike } from '../../../image-stream-ARno6XlS.js';
5
6
 
6
7
  /**
7
8
  * @fileoverview Media serialization utilities for proxy transport.
@@ -10,8 +10,9 @@ import {
10
10
  toJSON,
11
11
  toSSE,
12
12
  webapi
13
- } from "../../../chunk-LTEMH3CI.js";
14
- import "../../../chunk-YQLR3XOA.js";
13
+ } from "../../../chunk-5XPRVUOK.js";
14
+ import "../../../chunk-BIBMNP7Y.js";
15
+ import "../../../chunk-7ULSRWDH.js";
15
16
  import "../../../chunk-ETBFOLQN.js";
16
17
  import "../../../chunk-N5DX5JW3.js";
17
18
  import "../../../chunk-WU4U6IHF.js";
@@ -1,5 +1,6 @@
1
- import { e as Provider } from '../llm-DS_-l71X.js';
2
- import '../stream-sXhBtWjl.js';
1
+ import { e as Provider } from '../llm-CZqlijjK.js';
2
+ import '../stream-DVVUIKpz.js';
3
+ import '../tool-D22EhP5F.js';
3
4
 
4
5
  /**
5
6
  * @fileoverview OpenResponses Provider Type Definitions
@@ -1,4 +1,4 @@
1
- import { K as KeyStrategy, c as ProviderConfig, f as Modality, R as RetryStrategy, U as UPPError } from './llm-DS_-l71X.js';
1
+ import { K as KeyStrategy, c as ProviderConfig, f as Modality, R as RetryStrategy, U as UPPError } from './llm-CZqlijjK.js';
2
2
 
3
3
  /**
4
4
  * API key management strategies for load balancing and dynamic key selection.
@@ -1,3 +1,5 @@
1
+ import { c as ToolCall, d as ToolResult, e as ToolExecution } from './tool-D22EhP5F.js';
2
+
1
3
  /**
2
4
  * @fileoverview Content block types for multimodal messages.
3
5
  *
@@ -500,421 +502,6 @@ declare function isVideoBlock(block: ContentBlock): block is VideoBlock;
500
502
  */
501
503
  declare function isBinaryBlock(block: ContentBlock): block is BinaryBlock;
502
504
 
503
- /**
504
- * @fileoverview JSON Schema types for tool parameters and structured outputs.
505
- *
506
- * Provides TypeScript interfaces for defining JSON Schema objects used in
507
- * LLM tool definitions and structured output specifications.
508
- *
509
- * @module types/schema
510
- */
511
- /**
512
- * Primitive and composite JSON Schema property types.
513
- *
514
- * These types correspond to the JSON Schema specification's allowed type values.
515
- */
516
- type JSONSchemaPropertyType =
517
- /** String values */
518
- 'string'
519
- /** Floating point numbers */
520
- | 'number'
521
- /** Whole numbers */
522
- | 'integer'
523
- /** Boolean true/false values */
524
- | 'boolean'
525
- /** Ordered lists of values */
526
- | 'array'
527
- /** Key-value mappings */
528
- | 'object'
529
- /** Explicit null value */
530
- | 'null';
531
- /**
532
- * JSON Schema property definition.
533
- *
534
- * Describes a single property within a JSON Schema object, including
535
- * type constraints, validation rules, and nested structure definitions.
536
- *
537
- * @example
538
- * ```typescript
539
- * const nameProperty: JSONSchemaProperty = {
540
- * type: 'string',
541
- * description: 'User name',
542
- * minLength: 1,
543
- * maxLength: 100
544
- * };
545
- * ```
546
- *
547
- * @example
548
- * ```typescript
549
- * const tagsProperty: JSONSchemaProperty = {
550
- * type: 'array',
551
- * description: 'List of tags',
552
- * items: { type: 'string' },
553
- * minItems: 1,
554
- * uniqueItems: true
555
- * };
556
- * ```
557
- */
558
- interface JSONSchemaProperty {
559
- /** The JSON type of this property */
560
- type: JSONSchemaPropertyType;
561
- /** Human-readable description for the LLM */
562
- description?: string;
563
- /** Allowed values (enumeration) */
564
- enum?: unknown[];
565
- /** Constant value this property must equal */
566
- const?: unknown;
567
- /** Default value if not provided */
568
- default?: unknown;
569
- /** Minimum string length (string type only) */
570
- minLength?: number;
571
- /** Maximum string length (string type only) */
572
- maxLength?: number;
573
- /** Regular expression pattern for validation (string type only) */
574
- pattern?: string;
575
- /** Semantic format hint (string type only) */
576
- format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
577
- /** Minimum value inclusive (number/integer types only) */
578
- minimum?: number;
579
- /** Maximum value inclusive (number/integer types only) */
580
- maximum?: number;
581
- /** Minimum value exclusive (number/integer types only) */
582
- exclusiveMinimum?: number;
583
- /** Maximum value exclusive (number/integer types only) */
584
- exclusiveMaximum?: number;
585
- /** Value must be divisible by this (number/integer types only) */
586
- multipleOf?: number;
587
- /** Schema for array elements (array type only) */
588
- items?: JSONSchemaProperty;
589
- /** Minimum array length (array type only) */
590
- minItems?: number;
591
- /** Maximum array length (array type only) */
592
- maxItems?: number;
593
- /** Whether array elements must be unique (array type only) */
594
- uniqueItems?: boolean;
595
- /** Nested property definitions (object type only) */
596
- properties?: Record<string, JSONSchemaProperty>;
597
- /** List of required property names (object type only) */
598
- required?: string[];
599
- /** Whether additional properties are allowed (object type only) */
600
- additionalProperties?: boolean;
601
- }
602
- /**
603
- * Root JSON Schema for tool parameters or structured outputs.
604
- *
605
- * This is the top-level schema definition used when defining tool
606
- * parameters or requesting structured output from an LLM.
607
- *
608
- * @example
609
- * ```typescript
610
- * const weatherToolSchema: JSONSchema = {
611
- * type: 'object',
612
- * description: 'Parameters for getting weather information',
613
- * properties: {
614
- * location: {
615
- * type: 'string',
616
- * description: 'City name or coordinates'
617
- * },
618
- * units: {
619
- * type: 'string',
620
- * enum: ['celsius', 'fahrenheit'],
621
- * description: 'Temperature units'
622
- * }
623
- * },
624
- * required: ['location']
625
- * };
626
- * ```
627
- */
628
- interface JSONSchema {
629
- /** Root schemas are always objects */
630
- type: 'object';
631
- /** Property definitions for the object */
632
- properties: Record<string, JSONSchemaProperty>;
633
- /** List of required property names */
634
- required?: string[];
635
- /** Whether additional properties are allowed beyond those defined */
636
- additionalProperties?: boolean;
637
- /** Human-readable description of the schema's purpose */
638
- description?: string;
639
- }
640
-
641
- /**
642
- * @fileoverview Tool types for LLM function calling.
643
- *
644
- * Defines the interfaces for registering tools with LLMs, handling
645
- * tool calls from the model, and managing tool execution strategies.
646
- *
647
- * @module types/tool
648
- */
649
-
650
- /**
651
- * Provider-namespaced metadata for tools.
652
- *
653
- * Each provider can attach its own metadata under its namespace,
654
- * enabling provider-specific features like caching, strict mode, etc.
655
- *
656
- * @example
657
- * ```typescript
658
- * const metadata: ToolMetadata = {
659
- * anthropic: { cache_control: { type: 'ephemeral' } },
660
- * openrouter: { cache_control: { type: 'ephemeral', ttl: '1h' } }
661
- * };
662
- * ```
663
- */
664
- interface ToolMetadata {
665
- [provider: string]: Record<string, unknown> | undefined;
666
- }
667
- /**
668
- * Tool call requested by the model.
669
- *
670
- * Represents a single function call request from the LLM, including
671
- * the tool name and parsed arguments.
672
- *
673
- * @example
674
- * ```typescript
675
- * const toolCall: ToolCall = {
676
- * toolCallId: 'call_abc123',
677
- * toolName: 'get_weather',
678
- * arguments: { location: 'San Francisco', units: 'celsius' }
679
- * };
680
- * ```
681
- */
682
- interface ToolCall {
683
- /** Unique identifier for this tool call, used to match results */
684
- toolCallId: string;
685
- /** Name of the tool being called */
686
- toolName: string;
687
- /** Parsed arguments for the tool call */
688
- arguments: Record<string, unknown>;
689
- }
690
- /**
691
- * Result of tool execution.
692
- *
693
- * Returned after executing a tool, containing the result data
694
- * and whether an error occurred.
695
- *
696
- * @example
697
- * ```typescript
698
- * const result: ToolResult = {
699
- * toolCallId: 'call_abc123',
700
- * result: { temperature: 72, conditions: 'sunny' }
701
- * };
702
- *
703
- * // Error result
704
- * const errorResult: ToolResult = {
705
- * toolCallId: 'call_abc123',
706
- * result: 'Location not found',
707
- * isError: true
708
- * };
709
- * ```
710
- */
711
- interface ToolResult {
712
- /** The tool call ID this result corresponds to */
713
- toolCallId: string;
714
- /** The result data (can be any serializable value) */
715
- result: unknown;
716
- /** Whether the tool execution resulted in an error */
717
- isError?: boolean;
718
- }
719
- /**
720
- * Tool definition for LLM function calling.
721
- *
722
- * Defines a tool that can be called by the LLM, including its
723
- * name, description, parameter schema, and execution function.
724
- *
725
- * @typeParam TParams - The type of parameters the tool accepts
726
- * @typeParam TResult - The type of result the tool returns
727
- *
728
- * @example
729
- * ```typescript
730
- * const weatherTool: Tool<{ location: string }, WeatherData> = {
731
- * name: 'get_weather',
732
- * description: 'Get current weather for a location',
733
- * parameters: {
734
- * type: 'object',
735
- * properties: {
736
- * location: { type: 'string', description: 'City name' }
737
- * },
738
- * required: ['location']
739
- * },
740
- * run: async (params) => {
741
- * return fetchWeather(params.location);
742
- * }
743
- * };
744
- * ```
745
- */
746
- interface Tool<TParams = unknown, TResult = unknown> {
747
- /** Tool name (must be unique within an llm() instance) */
748
- name: string;
749
- /** Human-readable description for the model to understand when to use this tool */
750
- description: string;
751
- /** JSON Schema defining the tool's parameters */
752
- parameters: JSONSchema;
753
- /**
754
- * Provider-specific metadata, namespaced by provider name.
755
- *
756
- * Used for provider-specific features like prompt caching:
757
- * @example
758
- * ```typescript
759
- * const tool: Tool = {
760
- * name: 'search_docs',
761
- * description: 'Search documentation',
762
- * parameters: {...},
763
- * run: async (params) => {...},
764
- * metadata: {
765
- * anthropic: { cache_control: { type: 'ephemeral' } }
766
- * }
767
- * };
768
- * ```
769
- */
770
- metadata?: ToolMetadata;
771
- /**
772
- * Executes the tool with the provided parameters.
773
- *
774
- * @param params - The parameters passed by the model
775
- * @returns The tool result, synchronously or as a Promise
776
- */
777
- run(params: TParams): TResult | Promise<TResult>;
778
- /**
779
- * Optional approval handler for sensitive operations.
780
- *
781
- * If provided, this function is called before the tool executes.
782
- * Return false to prevent execution.
783
- *
784
- * @param params - The parameters the tool would be called with
785
- * @returns Whether to approve the execution
786
- */
787
- approval?(params: TParams): boolean | Promise<boolean>;
788
- }
789
- /**
790
- * Result from onBeforeCall hook indicating whether to proceed and optionally transformed params.
791
- */
792
- interface BeforeCallResult {
793
- /** Whether to proceed with tool execution */
794
- proceed: boolean;
795
- /** Transformed parameters to use instead of the original (optional) */
796
- params?: unknown;
797
- }
798
- /**
799
- * Result from onAfterCall hook optionally containing a transformed result.
800
- */
801
- interface AfterCallResult {
802
- /** Transformed result to use instead of the original */
803
- result: unknown;
804
- }
805
- /**
806
- * Strategy for controlling tool execution behavior.
807
- *
808
- * Provides hooks for monitoring, controlling, and transforming the tool execution
809
- * loop during LLM inference.
810
- *
811
- * @example
812
- * ```typescript
813
- * const strategy: ToolUseStrategy = {
814
- * maxIterations: 5,
815
- * onToolCall: (tool, params) => {
816
- * console.log(`Calling ${tool.name} with`, params);
817
- * },
818
- * // Transform input parameters
819
- * onBeforeCall: (tool, params) => {
820
- * if (tool.name === 'search') {
821
- * return { proceed: true, params: { ...params, limit: 10 } };
822
- * }
823
- * return true;
824
- * },
825
- * // Transform output results
826
- * onAfterCall: (tool, params, result) => {
827
- * if (tool.name === 'fetch_data') {
828
- * return { result: sanitize(result) };
829
- * }
830
- * },
831
- * onMaxIterations: (iterations) => {
832
- * console.warn(`Reached max iterations: ${iterations}`);
833
- * }
834
- * };
835
- * ```
836
- */
837
- interface ToolUseStrategy {
838
- /** Maximum number of tool execution rounds (default: 10) */
839
- maxIterations?: number;
840
- /**
841
- * Called when the model requests a tool call.
842
- *
843
- * @param tool - The tool being called
844
- * @param params - The parameters for the call
845
- */
846
- onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
847
- /**
848
- * Called before tool execution. Can skip execution or transform parameters.
849
- *
850
- * @param tool - The tool about to be executed
851
- * @param params - The parameters for the call
852
- * @returns One of:
853
- * - `false` to skip execution
854
- * - `true` to proceed with original params
855
- * - `BeforeCallResult` object to control execution and optionally transform params
856
- */
857
- onBeforeCall?(tool: Tool, params: unknown): boolean | BeforeCallResult | Promise<boolean | BeforeCallResult>;
858
- /**
859
- * Called after tool execution completes. Can transform the result.
860
- *
861
- * @param tool - The tool that was executed
862
- * @param params - The parameters that were used
863
- * @param result - The result from the tool
864
- * @returns Void to use original result, or `AfterCallResult` to transform it
865
- */
866
- onAfterCall?(tool: Tool, params: unknown, result: unknown): void | AfterCallResult | Promise<void | AfterCallResult>;
867
- /**
868
- * Called when a tool execution throws an error.
869
- *
870
- * @param tool - The tool that failed
871
- * @param params - The parameters that were used
872
- * @param error - The error that was thrown
873
- */
874
- onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
875
- /**
876
- * Called when the maximum iteration limit is reached.
877
- *
878
- * @param iterations - The number of iterations that were performed
879
- */
880
- onMaxIterations?(iterations: number): void | Promise<void>;
881
- }
882
- /**
883
- * Record of a completed tool execution.
884
- *
885
- * Contains all information about a tool call that was executed,
886
- * including timing and result data.
887
- *
888
- * @example
889
- * ```typescript
890
- * const execution: ToolExecution = {
891
- * toolName: 'get_weather',
892
- * toolCallId: 'call_abc123',
893
- * arguments: { location: 'San Francisco' },
894
- * result: { temperature: 72 },
895
- * isError: false,
896
- * duration: 150,
897
- * approved: true
898
- * };
899
- * ```
900
- */
901
- interface ToolExecution {
902
- /** Name of the tool that was called */
903
- toolName: string;
904
- /** Unique identifier for this tool call */
905
- toolCallId: string;
906
- /** Arguments that were passed to the tool */
907
- arguments: Record<string, unknown>;
908
- /** Result returned by the tool */
909
- result: unknown;
910
- /** Whether the tool execution resulted in an error */
911
- isError: boolean;
912
- /** Execution duration in milliseconds */
913
- duration: number;
914
- /** Whether approval was required and granted (undefined if no approval handler) */
915
- approved?: boolean;
916
- }
917
-
918
505
  /**
919
506
  * @fileoverview Message types for conversation history.
920
507
  *
@@ -1644,4 +1231,4 @@ declare function toolExecutionStart(toolCallId: string, toolName: string, timest
1644
1231
  */
1645
1232
  declare function toolExecutionEnd(toolCallId: string, toolName: string, result: unknown, isError: boolean, timestamp: number, index?: number): StreamEvent;
1646
1233
 
1647
- export { createTurn as $, type AssistantContent as A, type BinaryBlock as B, type ContentBlock as C, type DocumentSource as D, type EventDelta as E, type ToolCall as F, type ToolResult as G, type ToolMetadata as H, type ImageSource as I, type JSONSchema as J, type BeforeCallResult as K, type AfterCallResult as L, Message as M, type ToolExecution as N, UserMessage as O, ToolResultMessage as P, MessageRole as Q, type ReasoningBlock as R, type StreamEvent as S, type Turn as T, type UserContent as U, type VideoBlock as V, isUserMessage as W, isAssistantMessage as X, isToolResultMessage as Y, type MessageMetadata as Z, type MessageOptions as _, type MessageJSON as a, emptyUsage as a0, aggregateUsage as a1, StreamEventType as a2, createStreamResult as a3, textDelta as a4, toolCallDelta as a5, objectDelta as a6, messageStart as a7, messageStop as a8, contentBlockStart as a9, contentBlockStop as aa, toolExecutionStart as ab, toolExecutionEnd as ac, type TurnJSON as b, type ImageBlock as c, type Tool as d, type MessageType as e, type ToolUseStrategy as f, AssistantMessage as g, type TokenUsage as h, type StreamResult as i, type DocumentBlock as j, type AudioBlock as k, type JSONSchemaProperty as l, type JSONSchemaPropertyType as m, type TextBlock as n, ContentBlockType as o, ImageSourceType as p, DocumentSourceType as q, reasoning as r, isTextBlock as s, text as t, isReasoningBlock as u, isImageBlock as v, isDocumentBlock as w, isAudioBlock as x, isVideoBlock as y, isBinaryBlock as z };
1234
+ export { contentBlockStop as $, type AssistantContent as A, type BinaryBlock as B, type ContentBlock as C, type DocumentSource as D, type EventDelta as E, isAssistantMessage as F, isToolResultMessage as G, type MessageMetadata as H, type ImageSource as I, type MessageOptions as J, createTurn as K, emptyUsage as L, Message as M, aggregateUsage as N, StreamEventType as O, createStreamResult as P, textDelta as Q, type ReasoningBlock as R, type StreamEvent as S, type Turn as T, type UserContent as U, type VideoBlock as V, toolCallDelta as W, objectDelta as X, messageStart as Y, messageStop as Z, contentBlockStart as _, type MessageJSON as a, toolExecutionStart as a0, toolExecutionEnd as a1, type TurnJSON as b, type ImageBlock as c, type MessageType as d, AssistantMessage as e, type TokenUsage as f, type StreamResult as g, type DocumentBlock as h, type AudioBlock as i, type TextBlock as j, ContentBlockType as k, ImageSourceType as l, DocumentSourceType as m, isTextBlock as n, isReasoningBlock as o, isImageBlock as p, isDocumentBlock as q, reasoning as r, isAudioBlock as s, text as t, isVideoBlock as u, isBinaryBlock as v, UserMessage as w, ToolResultMessage as x, MessageRole as y, isUserMessage as z };