@effect/ai 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/Chat/package.json +6 -0
  2. package/EmbeddingModel/package.json +6 -0
  3. package/IdGenerator/package.json +6 -0
  4. package/LanguageModel/package.json +6 -0
  5. package/Model/package.json +6 -0
  6. package/Prompt/package.json +6 -0
  7. package/Response/package.json +6 -0
  8. package/Telemetry/package.json +6 -0
  9. package/Tool/package.json +6 -0
  10. package/Toolkit/package.json +6 -0
  11. package/dist/cjs/AiError.js +575 -11
  12. package/dist/cjs/AiError.js.map +1 -1
  13. package/dist/cjs/Chat.js +302 -0
  14. package/dist/cjs/Chat.js.map +1 -0
  15. package/dist/cjs/EmbeddingModel.js +184 -0
  16. package/dist/cjs/EmbeddingModel.js.map +1 -0
  17. package/dist/cjs/IdGenerator.js +255 -0
  18. package/dist/cjs/IdGenerator.js.map +1 -0
  19. package/dist/cjs/LanguageModel.js +584 -0
  20. package/dist/cjs/LanguageModel.js.map +1 -0
  21. package/dist/cjs/McpServer.js +12 -4
  22. package/dist/cjs/McpServer.js.map +1 -1
  23. package/dist/cjs/Model.js +118 -0
  24. package/dist/cjs/Model.js.map +1 -0
  25. package/dist/cjs/Prompt.js +649 -0
  26. package/dist/cjs/Prompt.js.map +1 -0
  27. package/dist/cjs/Response.js +635 -0
  28. package/dist/cjs/Response.js.map +1 -0
  29. package/dist/cjs/Telemetry.js +176 -0
  30. package/dist/cjs/Telemetry.js.map +1 -0
  31. package/dist/cjs/Tokenizer.js +87 -8
  32. package/dist/cjs/Tokenizer.js.map +1 -1
  33. package/dist/cjs/Tool.js +556 -0
  34. package/dist/cjs/Tool.js.map +1 -0
  35. package/dist/cjs/Toolkit.js +279 -0
  36. package/dist/cjs/Toolkit.js.map +1 -0
  37. package/dist/cjs/index.js +21 -19
  38. package/dist/dts/AiError.d.ts +577 -9
  39. package/dist/dts/AiError.d.ts.map +1 -1
  40. package/dist/dts/Chat.d.ts +356 -0
  41. package/dist/dts/Chat.d.ts.map +1 -0
  42. package/dist/dts/EmbeddingModel.d.ts +153 -0
  43. package/dist/dts/EmbeddingModel.d.ts.map +1 -0
  44. package/dist/dts/IdGenerator.d.ts +272 -0
  45. package/dist/dts/IdGenerator.d.ts.map +1 -0
  46. package/dist/dts/LanguageModel.d.ts +458 -0
  47. package/dist/dts/LanguageModel.d.ts.map +1 -0
  48. package/dist/dts/McpSchema.d.ts +25 -25
  49. package/dist/dts/McpServer.d.ts +6 -4
  50. package/dist/dts/McpServer.d.ts.map +1 -1
  51. package/dist/dts/Model.d.ts +124 -0
  52. package/dist/dts/Model.d.ts.map +1 -0
  53. package/dist/dts/Prompt.d.ts +1119 -0
  54. package/dist/dts/Prompt.d.ts.map +1 -0
  55. package/dist/dts/Response.d.ts +1519 -0
  56. package/dist/dts/Response.d.ts.map +1 -0
  57. package/dist/dts/Telemetry.d.ts +520 -0
  58. package/dist/dts/Telemetry.d.ts.map +1 -0
  59. package/dist/dts/Tokenizer.d.ts +131 -13
  60. package/dist/dts/Tokenizer.d.ts.map +1 -1
  61. package/dist/dts/Tool.d.ts +876 -0
  62. package/dist/dts/Tool.d.ts.map +1 -0
  63. package/dist/dts/Toolkit.d.ts +310 -0
  64. package/dist/dts/Toolkit.d.ts.map +1 -0
  65. package/dist/dts/index.d.ts +498 -13
  66. package/dist/dts/index.d.ts.map +1 -1
  67. package/dist/esm/AiError.js +570 -10
  68. package/dist/esm/AiError.js.map +1 -1
  69. package/dist/esm/Chat.js +291 -0
  70. package/dist/esm/Chat.js.map +1 -0
  71. package/dist/esm/EmbeddingModel.js +173 -0
  72. package/dist/esm/EmbeddingModel.js.map +1 -0
  73. package/dist/esm/IdGenerator.js +245 -0
  74. package/dist/esm/IdGenerator.js.map +1 -0
  75. package/dist/esm/LanguageModel.js +572 -0
  76. package/dist/esm/LanguageModel.js.map +1 -0
  77. package/dist/esm/McpServer.js +12 -4
  78. package/dist/esm/McpServer.js.map +1 -1
  79. package/dist/esm/Model.js +108 -0
  80. package/dist/esm/Model.js.map +1 -0
  81. package/dist/esm/Prompt.js +633 -0
  82. package/dist/esm/Prompt.js.map +1 -0
  83. package/dist/esm/Response.js +619 -0
  84. package/dist/esm/Response.js.map +1 -0
  85. package/dist/esm/Telemetry.js +166 -0
  86. package/dist/esm/Telemetry.js.map +1 -0
  87. package/dist/esm/Tokenizer.js +87 -8
  88. package/dist/esm/Tokenizer.js.map +1 -1
  89. package/dist/esm/Tool.js +534 -0
  90. package/dist/esm/Tool.js.map +1 -0
  91. package/dist/esm/Toolkit.js +269 -0
  92. package/dist/esm/Toolkit.js.map +1 -0
  93. package/dist/esm/index.js +498 -13
  94. package/dist/esm/index.js.map +1 -1
  95. package/package.json +76 -68
  96. package/src/AiError.ts +739 -9
  97. package/src/Chat.ts +546 -0
  98. package/src/EmbeddingModel.ts +311 -0
  99. package/src/IdGenerator.ts +320 -0
  100. package/src/LanguageModel.ts +1074 -0
  101. package/src/McpServer.ts +337 -194
  102. package/src/Model.ts +155 -0
  103. package/src/Prompt.ts +1616 -0
  104. package/src/Response.ts +2131 -0
  105. package/src/Telemetry.ts +655 -0
  106. package/src/Tokenizer.ts +145 -24
  107. package/src/Tool.ts +1267 -0
  108. package/src/Toolkit.ts +516 -0
  109. package/src/index.ts +499 -13
  110. package/AiChat/package.json +0 -6
  111. package/AiEmbeddingModel/package.json +0 -6
  112. package/AiInput/package.json +0 -6
  113. package/AiLanguageModel/package.json +0 -6
  114. package/AiModel/package.json +0 -6
  115. package/AiResponse/package.json +0 -6
  116. package/AiTelemetry/package.json +0 -6
  117. package/AiTool/package.json +0 -6
  118. package/AiToolkit/package.json +0 -6
  119. package/dist/cjs/AiChat.js +0 -122
  120. package/dist/cjs/AiChat.js.map +0 -1
  121. package/dist/cjs/AiEmbeddingModel.js +0 -109
  122. package/dist/cjs/AiEmbeddingModel.js.map +0 -1
  123. package/dist/cjs/AiInput.js +0 -458
  124. package/dist/cjs/AiInput.js.map +0 -1
  125. package/dist/cjs/AiLanguageModel.js +0 -351
  126. package/dist/cjs/AiLanguageModel.js.map +0 -1
  127. package/dist/cjs/AiModel.js +0 -37
  128. package/dist/cjs/AiModel.js.map +0 -1
  129. package/dist/cjs/AiResponse.js +0 -681
  130. package/dist/cjs/AiResponse.js.map +0 -1
  131. package/dist/cjs/AiTelemetry.js +0 -58
  132. package/dist/cjs/AiTelemetry.js.map +0 -1
  133. package/dist/cjs/AiTool.js +0 -150
  134. package/dist/cjs/AiTool.js.map +0 -1
  135. package/dist/cjs/AiToolkit.js +0 -157
  136. package/dist/cjs/AiToolkit.js.map +0 -1
  137. package/dist/cjs/internal/common.js +0 -21
  138. package/dist/cjs/internal/common.js.map +0 -1
  139. package/dist/dts/AiChat.d.ts +0 -101
  140. package/dist/dts/AiChat.d.ts.map +0 -1
  141. package/dist/dts/AiEmbeddingModel.d.ts +0 -65
  142. package/dist/dts/AiEmbeddingModel.d.ts.map +0 -1
  143. package/dist/dts/AiInput.d.ts +0 -590
  144. package/dist/dts/AiInput.d.ts.map +0 -1
  145. package/dist/dts/AiLanguageModel.d.ts +0 -302
  146. package/dist/dts/AiLanguageModel.d.ts.map +0 -1
  147. package/dist/dts/AiModel.d.ts +0 -25
  148. package/dist/dts/AiModel.d.ts.map +0 -1
  149. package/dist/dts/AiResponse.d.ts +0 -863
  150. package/dist/dts/AiResponse.d.ts.map +0 -1
  151. package/dist/dts/AiTelemetry.d.ts +0 -242
  152. package/dist/dts/AiTelemetry.d.ts.map +0 -1
  153. package/dist/dts/AiTool.d.ts +0 -334
  154. package/dist/dts/AiTool.d.ts.map +0 -1
  155. package/dist/dts/AiToolkit.d.ts +0 -96
  156. package/dist/dts/AiToolkit.d.ts.map +0 -1
  157. package/dist/dts/internal/common.d.ts +0 -2
  158. package/dist/dts/internal/common.d.ts.map +0 -1
  159. package/dist/esm/AiChat.js +0 -111
  160. package/dist/esm/AiChat.js.map +0 -1
  161. package/dist/esm/AiEmbeddingModel.js +0 -98
  162. package/dist/esm/AiEmbeddingModel.js.map +0 -1
  163. package/dist/esm/AiInput.js +0 -433
  164. package/dist/esm/AiInput.js.map +0 -1
  165. package/dist/esm/AiLanguageModel.js +0 -340
  166. package/dist/esm/AiLanguageModel.js.map +0 -1
  167. package/dist/esm/AiModel.js +0 -29
  168. package/dist/esm/AiModel.js.map +0 -1
  169. package/dist/esm/AiResponse.js +0 -657
  170. package/dist/esm/AiResponse.js.map +0 -1
  171. package/dist/esm/AiTelemetry.js +0 -48
  172. package/dist/esm/AiTelemetry.js.map +0 -1
  173. package/dist/esm/AiTool.js +0 -134
  174. package/dist/esm/AiTool.js.map +0 -1
  175. package/dist/esm/AiToolkit.js +0 -147
  176. package/dist/esm/AiToolkit.js.map +0 -1
  177. package/dist/esm/internal/common.js +0 -14
  178. package/dist/esm/internal/common.js.map +0 -1
  179. package/src/AiChat.ts +0 -251
  180. package/src/AiEmbeddingModel.ts +0 -169
  181. package/src/AiInput.ts +0 -602
  182. package/src/AiLanguageModel.ts +0 -685
  183. package/src/AiModel.ts +0 -53
  184. package/src/AiResponse.ts +0 -986
  185. package/src/AiTelemetry.ts +0 -333
  186. package/src/AiTool.ts +0 -579
  187. package/src/AiToolkit.ts +0 -265
  188. package/src/internal/common.ts +0 -12
@@ -0,0 +1,534 @@
1
+ /**
2
+ * The `Tool` module provides functionality for defining and managing tools
3
+ * that language models can call to augment their capabilities.
4
+ *
5
+ * This module enables creation of both user-defined and provider-defined tools,
6
+ * with full schema validation, type safety, and handler support. Tools allow
7
+ * AI models to perform actions like searching databases, calling APIs, or
8
+ * executing code within your application context.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import { Tool } from "@effect/ai"
13
+ * import { Schema } from "effect"
14
+ *
15
+ * // Define a simple calculator tool
16
+ * const Calculator = Tool.make("Calculator", {
17
+ * description: "Performs basic arithmetic operations",
18
+ * parameters: {
19
+ * operation: Schema.Literal("add", "subtract", "multiply", "divide"),
20
+ * a: Schema.Number,
21
+ * b: Schema.Number
22
+ * },
23
+ * success: Schema.Number
24
+ * })
25
+ * ```
26
+ *
27
+ * @since 1.0.0
28
+ */
29
+ import * as Context from "effect/Context";
30
+ import * as Effect from "effect/Effect";
31
+ import { constFalse, constTrue, identity } from "effect/Function";
32
+ import * as JsonSchema from "effect/JSONSchema";
33
+ import * as Option from "effect/Option";
34
+ import { pipeArguments } from "effect/Pipeable";
35
+ import * as Predicate from "effect/Predicate";
36
+ import * as Schema from "effect/Schema";
37
+ import * as AST from "effect/SchemaAST";
38
+ import * as AiError from "./AiError.js";
39
+ // =============================================================================
40
+ // Type Ids
41
+ // =============================================================================
42
+ /**
43
+ * Unique identifier for user-defined tools.
44
+ *
45
+ * @since 1.0.0
46
+ * @category Type Ids
47
+ */
48
+ export const TypeId = "~@effect/ai/Tool";
49
+ /**
50
+ * Unique identifier for provider-defined tools.
51
+ *
52
+ * @since 1.0.0
53
+ * @category Type Ids
54
+ */
55
+ export const ProviderDefinedTypeId = "~@effect/ai/Tool/ProviderDefined";
56
+ // =============================================================================
57
+ // Type Guards
58
+ // =============================================================================
59
+ /**
60
+ * Type guard to check if a value is a user-defined tool.
61
+ *
62
+ * @example
63
+ * ```ts
64
+ * import { Tool } from "@effect/ai"
65
+ * import { Schema } from "effect"
66
+ *
67
+ * const UserDefinedTool = Tool.make("Calculator", {
68
+ * description: "Performs basic arithmetic operations",
69
+ * parameters: {
70
+ * operation: Schema.Literal("add", "subtract", "multiply", "divide"),
71
+ * a: Schema.Number,
72
+ * b: Schema.Number
73
+ * },
74
+ * success: Schema.Number
75
+ * })
76
+ *
77
+ * const ProviderDefinedTool = Tool.providerDefined({
78
+ * id: "openai.web_search",
79
+ * toolkitName: "WebSearch",
80
+ * providerName: "web_search",
81
+ * args: {
82
+ * query: Schema.String
83
+ * },
84
+ * success: Schema.Struct({
85
+ * results: Schema.Array(Schema.Struct({
86
+ * title: Schema.String,
87
+ * url: Schema.String,
88
+ * snippet: Schema.String
89
+ * }))
90
+ * })
91
+ * })
92
+ *
93
+ * console.log(Tool.isUserDefined(UserDefinedTool)) // true
94
+ * console.log(Tool.isUserDefined(ProviderDefinedTool)) // false
95
+ * ```
96
+ *
97
+ * @since 1.0.0
98
+ * @category Guards
99
+ */
100
+ export const isUserDefined = u => Predicate.hasProperty(u, TypeId) && !isProviderDefined(u);
101
+ /**
102
+ * Type guard to check if a value is a provider-defined tool.
103
+ *
104
+ * @param u - The value to check
105
+ * @returns `true` if the value is a provider-defined `Tool`, `false` otherwise
106
+ *
107
+ * @example
108
+ * ```ts
109
+ * import { Tool } from "@effect/ai"
110
+ * import { Schema } from "effect"
111
+ *
112
+ * const UserDefinedTool = Tool.make("Calculator", {
113
+ * description: "Performs basic arithmetic operations",
114
+ * parameters: {
115
+ * operation: Schema.Literal("add", "subtract", "multiply", "divide"),
116
+ * a: Schema.Number,
117
+ * b: Schema.Number
118
+ * },
119
+ * success: Schema.Number
120
+ * })
121
+ *
122
+ * const ProviderDefinedTool = Tool.providerDefined({
123
+ * id: "openai.web_search",
124
+ * toolkitName: "WebSearch",
125
+ * providerName: "web_search",
126
+ * args: {
127
+ * query: Schema.String
128
+ * },
129
+ * success: Schema.Struct({
130
+ * results: Schema.Array(Schema.Struct({
131
+ * title: Schema.String,
132
+ * url: Schema.String,
133
+ * snippet: Schema.String
134
+ * }))
135
+ * })
136
+ * })
137
+ *
138
+ * console.log(Tool.isUserDefined(UserDefinedTool)) // false
139
+ * console.log(Tool.isUserDefined(ProviderDefinedTool)) // true
140
+ * ```
141
+ *
142
+ * @since 1.0.0
143
+ * @category Guards
144
+ */
145
+ export const isProviderDefined = u => Predicate.hasProperty(u, ProviderDefinedTypeId);
146
+ // =============================================================================
147
+ // Constructors
148
+ // =============================================================================
149
+ const Proto = {
150
+ [TypeId]: {
151
+ _Requirements: identity
152
+ },
153
+ pipe() {
154
+ return pipeArguments(this, arguments);
155
+ },
156
+ addDependency() {
157
+ return userDefinedProto({
158
+ ...this
159
+ });
160
+ },
161
+ setParameters(parametersSchema) {
162
+ return userDefinedProto({
163
+ ...this,
164
+ parametersSchema: Schema.isSchema(parametersSchema) ? parametersSchema : Schema.Struct(parametersSchema)
165
+ });
166
+ },
167
+ setSuccess(successSchema) {
168
+ return userDefinedProto({
169
+ ...this,
170
+ successSchema
171
+ });
172
+ },
173
+ setFailure(failureSchema) {
174
+ return userDefinedProto({
175
+ ...this,
176
+ failureSchema
177
+ });
178
+ },
179
+ annotate(tag, value) {
180
+ return userDefinedProto({
181
+ ...this,
182
+ annotations: Context.add(this.annotations, tag, value)
183
+ });
184
+ },
185
+ annotateContext(context) {
186
+ return userDefinedProto({
187
+ ...this,
188
+ annotations: Context.merge(this.annotations, context)
189
+ });
190
+ }
191
+ };
192
+ const ProviderDefinedProto = {
193
+ ...Proto,
194
+ [ProviderDefinedTypeId]: ProviderDefinedTypeId,
195
+ decodeResult(result) {
196
+ return Schema.decodeUnknown(this.successSchema)(result).pipe(Effect.orElse(() => Schema.decodeUnknown(this.failureSchema)(result)), Effect.mapError(cause => new AiError.MalformedOutput({
197
+ module: "Tool",
198
+ method: "ProviderDefined.decodeResult",
199
+ description: `Failed to decode the result of provider-defined tool '${this.name}'`,
200
+ cause
201
+ })));
202
+ }
203
+ };
204
+ const userDefinedProto = options => {
205
+ const self = Object.assign(Object.create(Proto), options);
206
+ self.id = `@effect/ai/Tool/${options.name}`;
207
+ return self;
208
+ };
209
+ const providerDefinedProto = options => Object.assign(Object.create(ProviderDefinedProto), options);
210
+ const constEmptyStruct = /*#__PURE__*/Schema.Struct({});
211
+ /**
212
+ * Creates a user-defined tool with the specified name and configuration.
213
+ *
214
+ * This is the primary constructor for creating custom tools that AI models
215
+ * can call. The tool definition includes parameter validation, success/failure
216
+ * schemas, and optional service dependencies.
217
+ *
218
+ * @example
219
+ * ```ts
220
+ * import { Tool } from "@effect/ai"
221
+ * import { Schema } from "effect"
222
+ *
223
+ * // Simple tool with no parameters
224
+ * const GetCurrentTime = Tool.make("GetCurrentTime", {
225
+ * description: "Returns the current timestamp",
226
+ * success: Schema.Number
227
+ * })
228
+ * ```
229
+ *
230
+ * @since 1.0.0
231
+ * @category Constructors
232
+ */
233
+ export const make = (
234
+ /**
235
+ * The unique name identifier for this tool.
236
+ */
237
+ name, options) => {
238
+ const successSchema = options?.success ?? Schema.Void;
239
+ const failureSchema = options?.failure ?? Schema.Never;
240
+ return userDefinedProto({
241
+ name,
242
+ description: options?.description,
243
+ parametersSchema: options?.parameters ? Schema.Struct(options?.parameters) : constEmptyStruct,
244
+ successSchema,
245
+ failureSchema,
246
+ annotations: Context.empty()
247
+ });
248
+ };
249
+ /**
250
+ * Creates a provider-defined tool which leverages functionality built into a
251
+ * large language model provider (e.g. web search, code execution).
252
+ *
253
+ * These tools are executed by the large language model provider rather than
254
+ * by your application. However, they can optionally require custom handlers
255
+ * implemented in your application to process provider generated results.
256
+ *
257
+ * @example
258
+ * ```ts
259
+ * import { Tool } from "@effect/ai"
260
+ * import { Schema } from "effect"
261
+ *
262
+ * // Web search tool provided by OpenAI
263
+ * const WebSearch = Tool.providerDefined({
264
+ * id: "openai.web_search",
265
+ * toolkitName: "WebSearch",
266
+ * providerName: "web_search",
267
+ * args: {
268
+ * query: Schema.String
269
+ * },
270
+ * success: Schema.Struct({
271
+ * results: Schema.Array(Schema.Struct({
272
+ * title: Schema.String,
273
+ * url: Schema.String,
274
+ * content: Schema.String
275
+ * }))
276
+ * })
277
+ * })
278
+ * ```
279
+ *
280
+ * @since 1.0.0
281
+ * @category Constructors
282
+ */
283
+ export const providerDefined = options => args => {
284
+ const successSchema = options?.success ?? Schema.Void;
285
+ const failureSchema = options?.failure ?? Schema.Never;
286
+ const resultSchema = Schema.EitherFromUnion({
287
+ right: successSchema,
288
+ left: failureSchema
289
+ });
290
+ return providerDefinedProto({
291
+ id: options.id,
292
+ name: options.toolkitName,
293
+ providerName: options.providerName,
294
+ args,
295
+ argsSchema: Schema.Struct(options.args),
296
+ requiresHandler: options.requiresHandler ?? false,
297
+ parametersSchema: options?.parameters ? Schema.Struct(options?.parameters) : constEmptyStruct,
298
+ successSchema: options.requiresHandler === true ? successSchema : resultSchema,
299
+ failureSchema: options.requiresHandler === true ? failureSchema : Schema.Never
300
+ });
301
+ };
302
+ /**
303
+ * Creates a Tool from a Schema.TaggedRequest.
304
+ *
305
+ * This utility function converts Effect's TaggedRequest schemas into Tool
306
+ * definitions, automatically mapping the request parameters, success, and
307
+ * failure schemas.
308
+ *
309
+ * @example
310
+ * ```ts
311
+ * import { Tool } from "@effect/ai"
312
+ * import { Schema } from "effect"
313
+ *
314
+ * // Define a tagged request for user operations
315
+ * class GetUser extends Schema.TaggedRequest<GetUser>()("GetUser", {
316
+ * success: Schema.Struct({
317
+ * id: Schema.Number,
318
+ * name: Schema.String,
319
+ * email: Schema.String
320
+ * }),
321
+ * failure: Schema.Struct({
322
+ * error: Schema.Literal("UserNotFound", "DatabaseError"),
323
+ * message: Schema.String
324
+ * }),
325
+ * payload: {
326
+ * userId: Schema.Number
327
+ * }
328
+ * }) {}
329
+ *
330
+ * // Convert to a Tool
331
+ * const getUserTool = Tool.fromTaggedRequest(GetUser)
332
+ * ```
333
+ *
334
+ * @since 1.0.0
335
+ * @category Constructors
336
+ */
337
+ export const fromTaggedRequest = schema => userDefinedProto({
338
+ name: schema._tag,
339
+ description: Option.getOrUndefined(AST.getDescriptionAnnotation(schema.ast.to)),
340
+ parametersSchema: schema,
341
+ successSchema: schema.success,
342
+ failureSchema: schema.failure,
343
+ annotations: Context.empty()
344
+ });
345
+ // =============================================================================
346
+ // Utilities
347
+ // =============================================================================
348
+ /**
349
+ * Extracts the description from a tool's metadata.
350
+ *
351
+ * Returns the tool's description if explicitly set, otherwise attempts to
352
+ * extract it from the parameter schema's AST annotations.
353
+ *
354
+ * @example
355
+ * ```ts
356
+ * import { Tool } from "@effect/ai"
357
+ *
358
+ * const myTool = Tool.make("example", {
359
+ * description: "This is an example tool"
360
+ * })
361
+ *
362
+ * const description = Tool.getDescription(myTool)
363
+ * console.log(description) // "This is an example tool"
364
+ * ```
365
+ *
366
+ * @since 1.0.0
367
+ * @category Utilities
368
+ */
369
+ export const getDescription = (
370
+ /**
371
+ * The tool to get the description from.
372
+ */
373
+ tool) => {
374
+ if (Predicate.isNotUndefined(tool.description)) {
375
+ return tool.description;
376
+ }
377
+ return getDescriptionFromSchemaAst(tool.parametersSchema.ast);
378
+ };
379
+ /**
380
+ * @since 1.0.0
381
+ * @category Utilities
382
+ */
383
+ export const getDescriptionFromSchemaAst = ast => {
384
+ const annotations = ast._tag === "Transformation" ? {
385
+ ...ast.to.annotations,
386
+ ...ast.annotations
387
+ } : ast.annotations;
388
+ return AST.DescriptionAnnotationId in annotations ? annotations[AST.DescriptionAnnotationId] : undefined;
389
+ };
390
+ /**
391
+ * Generates a JSON Schema for a tool.
392
+ *
393
+ * This function creates a JSON Schema representation that can be used by
394
+ * large language models to indicate the structure and type of the parameters
395
+ * that a given tool call should receive.
396
+ *
397
+ * @example
398
+ * ```ts
399
+ * import { Tool } from "@effect/ai"
400
+ * import { Schema } from "effect"
401
+ *
402
+ * const weatherTool = Tool.make("get_weather", {
403
+ * parameters: {
404
+ * location: Schema.String,
405
+ * units: Schema.optional(Schema.Literal("celsius", "fahrenheit"))
406
+ * }
407
+ * })
408
+ *
409
+ * const jsonSchema = Tool.getJsonSchema(weatherTool)
410
+ * console.log(jsonSchema)
411
+ * // {
412
+ * // type: "object",
413
+ * // properties: {
414
+ * // location: { type: "string" },
415
+ * // units: { type: "string", enum: ["celsius", "fahrenheit"] }
416
+ * // },
417
+ * // required: ["location"]
418
+ * // }
419
+ * ```
420
+ *
421
+ * @since 1.0.0
422
+ * @category Utilities
423
+ */
424
+ export const getJsonSchema = tool => getJsonSchemaFromSchemaAst(tool.parametersSchema.ast);
425
+ /**
426
+ * @since 1.0.0
427
+ * @category Utilities
428
+ */
429
+ export const getJsonSchemaFromSchemaAst = ast => {
430
+ const props = AST.getPropertySignatures(ast);
431
+ if (props.length === 0) {
432
+ return {
433
+ type: "object",
434
+ properties: {},
435
+ required: [],
436
+ additionalProperties: false
437
+ };
438
+ }
439
+ const $defs = {};
440
+ const schema = JsonSchema.fromAST(ast, {
441
+ definitions: $defs,
442
+ topLevelReferenceStrategy: "skip"
443
+ });
444
+ if (Object.keys($defs).length === 0) return schema;
445
+ schema.$defs = $defs;
446
+ return schema;
447
+ };
448
+ // =============================================================================
449
+ // Annotations
450
+ // =============================================================================
451
+ /**
452
+ * Annotation for providing a human-readable title for tools.
453
+ *
454
+ * @example
455
+ * ```ts
456
+ * import { Tool } from "@effect/ai"
457
+ *
458
+ * const myTool = Tool.make("calculate_tip")
459
+ * .annotate(Tool.Title, "Tip Calculator")
460
+ * ```
461
+ *
462
+ * @since 1.0.0
463
+ * @category Annotations
464
+ */
465
+ export class Title extends /*#__PURE__*/Context.Tag("@effect/ai/Tool/Title")() {}
466
+ /**
467
+ * Annotation indicating whether a tool only reads data without making changes.
468
+ *
469
+ * @example
470
+ * ```ts
471
+ * import { Tool } from "@effect/ai"
472
+ *
473
+ * const readOnlyTool = Tool.make("get_user_info")
474
+ * .annotate(Tool.Readonly, true)
475
+ * ```
476
+ *
477
+ * @since 1.0.0
478
+ * @category Annotations
479
+ */
480
+ export class Readonly extends /*#__PURE__*/Context.Reference()("@effect/ai/Tool/Readonly", {
481
+ defaultValue: constFalse
482
+ }) {}
483
+ /**
484
+ * Annotation indicating whether a tool performs destructive operations.
485
+ *
486
+ * @example
487
+ * ```ts
488
+ * import { Tool } from "@effect/ai"
489
+ *
490
+ * const safeTool = Tool.make("search_database")
491
+ * .annotate(Tool.Destructive, false)
492
+ * ```
493
+ *
494
+ * @since 1.0.0
495
+ * @category Annotations
496
+ */
497
+ export class Destructive extends /*#__PURE__*/Context.Reference()("@effect/ai/Tool/Destructive", {
498
+ defaultValue: constTrue
499
+ }) {}
500
+ /**
501
+ * Annotation indicating whether a tool can be called multiple times safely.
502
+ *
503
+ * @example
504
+ * ```ts
505
+ * import { Tool } from "@effect/ai"
506
+ *
507
+ * const idempotentTool = Tool.make("get_current_time")
508
+ * .annotate(Tool.Idempotent, true)
509
+ * ```
510
+ *
511
+ * @since 1.0.0
512
+ * @category Annotations
513
+ */
514
+ export class Idempotent extends /*#__PURE__*/Context.Reference()("@effect/ai/Tool/Idempotent", {
515
+ defaultValue: constFalse
516
+ }) {}
517
+ /**
518
+ * Annotation indicating whether a tool can handle arbitrary external data.
519
+ *
520
+ * @example
521
+ * ```ts
522
+ * import { Tool } from "@effect/ai"
523
+ *
524
+ * const restrictedTool = Tool.make("internal_operation")
525
+ * .annotate(Tool.OpenWorld, false)
526
+ * ```
527
+ *
528
+ * @since 1.0.0
529
+ * @category Annotations
530
+ */
531
+ export class OpenWorld extends /*#__PURE__*/Context.Reference()("@effect/ai/Tool/OpenWorld", {
532
+ defaultValue: constTrue
533
+ }) {}
534
+ //# sourceMappingURL=Tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Tool.js","names":["Context","Effect","constFalse","constTrue","identity","JsonSchema","Option","pipeArguments","Predicate","Schema","AST","AiError","TypeId","ProviderDefinedTypeId","isUserDefined","u","hasProperty","isProviderDefined","Proto","_Requirements","pipe","arguments","addDependency","userDefinedProto","setParameters","parametersSchema","isSchema","Struct","setSuccess","successSchema","setFailure","failureSchema","annotate","tag","value","annotations","add","annotateContext","context","merge","ProviderDefinedProto","decodeResult","result","decodeUnknown","orElse","mapError","cause","MalformedOutput","module","method","description","name","options","self","Object","assign","create","id","providerDefinedProto","constEmptyStruct","make","success","Void","failure","Never","parameters","empty","providerDefined","args","resultSchema","EitherFromUnion","right","left","toolkitName","providerName","argsSchema","requiresHandler","fromTaggedRequest","schema","_tag","getOrUndefined","getDescriptionAnnotation","ast","to","getDescription","tool","isNotUndefined","getDescriptionFromSchemaAst","DescriptionAnnotationId","undefined","getJsonSchema","getJsonSchemaFromSchemaAst","props","getPropertySignatures","length","type","properties","required","additionalProperties","$defs","fromAST","definitions","topLevelReferenceStrategy","keys","Title","Tag","Readonly","Reference","defaultValue","Destructive","Idempotent","OpenWorld"],"sources":["../../src/Tool.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}