@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
@@ -1,31 +1,527 @@
1
+ /**
2
+ * The `AiError` module provides comprehensive error handling for AI operations.
3
+ *
4
+ * This module defines a hierarchy of error types that can occur when working
5
+ * with AI services, including HTTP request/response errors, input/output
6
+ * validation errors, and general runtime errors. All errors follow Effect's
7
+ * structured error patterns and provide detailed context for debugging.
8
+ *
9
+ * ## Error Types
10
+ *
11
+ * - **HttpRequestError**: Errors occurring during HTTP request processing
12
+ * - **HttpResponseError**: Errors occurring during HTTP response processing
13
+ * - **MalformedInput**: Errors when input data doesn't match expected format
14
+ * - **MalformedOutput**: Errors when output data can't be parsed or validated
15
+ * - **UnknownError**: Catch-all for unexpected runtime errors
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { AiError } from "@effect/ai"
20
+ * import { Effect, Match } from "effect"
21
+ *
22
+ * const handleAiError = Match.type<AiError.AiError>().pipe(
23
+ * Match.tag("HttpRequestError", (err) =>
24
+ * Effect.logError(`Request failed: ${err.message}`)
25
+ * ),
26
+ * Match.tag("HttpResponseError", (err) =>
27
+ * Effect.logError(`Response error (${err.response.status}): ${err.message}`)
28
+ * ),
29
+ * Match.tag("MalformedInput", (err) =>
30
+ * Effect.logError(`Invalid input: ${err.message}`)
31
+ * ),
32
+ * Match.tag("MalformedOutput", (err) =>
33
+ * Effect.logError(`Invalid output: ${err.message}`)
34
+ * ),
35
+ * Match.orElse((err) =>
36
+ * Effect.logError(`Unknown error: ${err.message}`)
37
+ * )
38
+ * )
39
+ * ```
40
+ *
41
+ * @example
42
+ * ```ts
43
+ * import { AiError } from "@effect/ai"
44
+ * import { Effect, Option } from "effect"
45
+ *
46
+ * const aiOperation = Effect.gen(function* () {
47
+ * // Some AI operation that might fail
48
+ * return yield* new AiError.HttpRequestError({
49
+ * module: "OpenAI",
50
+ * method: "completion",
51
+ * reason: "Transport",
52
+ * request: {
53
+ * method: "POST",
54
+ * url: "https://api.openai.com/v1/completions",
55
+ * urlParams: [],
56
+ * hash: Option.none(),
57
+ * headers: { "Authorization": "Bearer ***" }
58
+ * }
59
+ * })
60
+ * })
61
+ *
62
+ * const program = aiOperation.pipe(
63
+ * Effect.catchTag("HttpRequestError", (error) => {
64
+ * console.log("Request failed:", error.message)
65
+ * return Effect.succeed("fallback response")
66
+ * })
67
+ * )
68
+ * ```
69
+ *
70
+ * @since 1.0.0
71
+ */
72
+ import type * as HttpClientError from "@effect/platform/HttpClientError";
73
+ import type { ParseError } from "effect/ParseResult";
1
74
  import * as Schema from "effect/Schema";
2
75
  /**
76
+ * Unique identifier for AI errors.
77
+ *
3
78
  * @since 1.0.0
4
- * @category type ids
79
+ * @category Type Ids
5
80
  */
6
- export declare const TypeId: unique symbol;
81
+ export declare const TypeId = "~@effect/ai/AiError";
7
82
  /**
83
+ * Type-level representation of the AI error identifier.
84
+ *
8
85
  * @since 1.0.0
9
- * @category type ids
86
+ * @category Type Ids
10
87
  */
11
88
  export type TypeId = typeof TypeId;
12
- declare const AiError_base: Schema.TaggedErrorClass<AiError, "AiError", {
13
- readonly _tag: Schema.tag<"AiError">;
89
+ /**
90
+ * Type guard to check if a value is an AI error.
91
+ *
92
+ * @param u - The value to check
93
+ * @returns `true` if the value is an `AiError`, `false` otherwise
94
+ *
95
+ * @example
96
+ * ```ts
97
+ * import { AiError } from "@effect/ai"
98
+ *
99
+ * const someError = new Error("generic error")
100
+ * const aiError = new AiError.UnknownError({
101
+ * module: "Test",
102
+ * method: "example"
103
+ * })
104
+ *
105
+ * console.log(AiError.isAiError(someError)) // false
106
+ * console.log(AiError.isAiError(aiError)) // true
107
+ * ```
108
+ *
109
+ * @since 1.0.0
110
+ * @category Guards
111
+ */
112
+ export declare const isAiError: (u: unknown) => u is AiError;
113
+ /**
114
+ * Schema for HTTP request details used in error reporting.
115
+ *
116
+ * Captures comprehensive information about HTTP requests that failed,
117
+ * enabling detailed error analysis and debugging.
118
+ *
119
+ * @example
120
+ * ```ts
121
+ * import { AiError } from "@effect/ai"
122
+ * import { Option } from "effect"
123
+ *
124
+ * const requestDetails: typeof AiError.HttpRequestDetails.Type = {
125
+ * method: "POST",
126
+ * url: "https://api.openai.com/v1/completions",
127
+ * urlParams: [["model", "gpt-4"], ["stream", "false"]],
128
+ * hash: Option.some("#section1"),
129
+ * headers: {
130
+ * "Content-Type": "application/json",
131
+ * "Authorization": "Bearer sk-..."
132
+ * }
133
+ * }
134
+ * ```
135
+ *
136
+ * @since 1.0.0
137
+ * @category Schemas
138
+ */
139
+ export declare const HttpRequestDetails: Schema.Struct<{
140
+ method: Schema.Literal<["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS"]>;
141
+ url: typeof Schema.String;
142
+ urlParams: Schema.Array$<Schema.Tuple2<typeof Schema.String, typeof Schema.String>>;
143
+ hash: Schema.Option<typeof Schema.String>;
144
+ headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
145
+ }>;
146
+ declare const HttpRequestError_base: Schema.TaggedErrorClass<HttpRequestError, "HttpRequestError", {
147
+ readonly _tag: Schema.tag<"HttpRequestError">;
148
+ } & {
149
+ module: typeof Schema.String;
150
+ method: typeof Schema.String;
151
+ reason: Schema.Literal<["Transport", "Encode", "InvalidUrl"]>;
152
+ request: Schema.Struct<{
153
+ method: Schema.Literal<["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS"]>;
154
+ url: typeof Schema.String;
155
+ urlParams: Schema.Array$<Schema.Tuple2<typeof Schema.String, typeof Schema.String>>;
156
+ hash: Schema.Option<typeof Schema.String>;
157
+ headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
158
+ }>;
159
+ description: Schema.optional<typeof Schema.String>;
160
+ cause: Schema.optional<typeof Schema.Defect>;
161
+ }>;
162
+ /**
163
+ * Error that occurs during HTTP request processing.
164
+ *
165
+ * This error is raised when issues arise before receiving an HTTP response,
166
+ * such as network connectivity problems, request encoding issues, or invalid
167
+ * URLs.
168
+ *
169
+ * @example
170
+ * ```ts
171
+ * import { AiError } from "@effect/ai"
172
+ * import { Effect } from "effect"
173
+ *
174
+ * const handleNetworkError = Effect.gen(function* () {
175
+ * const error = new AiError.HttpRequestError({
176
+ * module: "OpenAI",
177
+ * method: "createCompletion",
178
+ * reason: "Transport",
179
+ * request: {
180
+ * method: "POST",
181
+ * url: "https://api.openai.com/v1/completions",
182
+ * urlParams: [],
183
+ * hash: Option.none(),
184
+ * headers: { "Content-Type": "application/json" }
185
+ * },
186
+ * description: "Connection timeout after 30 seconds"
187
+ * })
188
+ *
189
+ * console.log(error.message)
190
+ * // "Transport: Connection timeout after 30 seconds (POST https://api.openai.com/v1/completions)"
191
+ * })
192
+ * ```
193
+ *
194
+ * @since 1.0.0
195
+ * @category Errors
196
+ */
197
+ export declare class HttpRequestError extends HttpRequestError_base {
198
+ /**
199
+ * @since 1.0.0
200
+ */
201
+ readonly [TypeId]: TypeId;
202
+ /**
203
+ * Creates an HttpRequestError from a platform HttpClientError.RequestError.
204
+ *
205
+ * @example
206
+ * ```ts
207
+ * import { AiError } from "@effect/ai"
208
+ * import { HttpClientError } from "@effect/platform"
209
+ * import { Option } from "effect"
210
+ *
211
+ * declare const platformError: HttpClientError.RequestError
212
+ *
213
+ * const aiError = AiError.HttpRequestError.fromRequestError({
214
+ * module: "ChatGPT",
215
+ * method: "sendMessage",
216
+ * error: platformError
217
+ * })
218
+ * ```
219
+ *
220
+ * @since 1.0.0
221
+ * @category Constructors
222
+ */
223
+ static fromRequestError({ error, ...params }: {
224
+ readonly module: string;
225
+ readonly method: string;
226
+ readonly error: HttpClientError.RequestError;
227
+ }): HttpRequestError;
228
+ get message(): string;
229
+ }
230
+ /**
231
+ * Schema for HTTP response details used in error reporting.
232
+ *
233
+ * Captures essential information about HTTP responses that caused errors,
234
+ * including status codes and headers for debugging purposes.
235
+ *
236
+ * @example
237
+ * ```ts
238
+ * import { AiError } from "@effect/ai"
239
+ *
240
+ * const responseDetails: typeof AiError.HttpResponseDetails.Type = {
241
+ * status: 429,
242
+ * headers: {
243
+ * "Content-Type": "application/json",
244
+ * "X-RateLimit-Remaining": "0",
245
+ * "Retry-After": "60"
246
+ * }
247
+ * }
248
+ * ```
249
+ *
250
+ * @since 1.0.0
251
+ * @category Schemas
252
+ */
253
+ export declare const HttpResponseDetails: Schema.Struct<{
254
+ status: typeof Schema.Number;
255
+ headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
256
+ }>;
257
+ declare const HttpResponseError_base: Schema.TaggedErrorClass<HttpResponseError, "HttpResponseError", {
258
+ readonly _tag: Schema.tag<"HttpResponseError">;
259
+ } & {
260
+ module: typeof Schema.String;
261
+ method: typeof Schema.String;
262
+ request: Schema.Struct<{
263
+ method: Schema.Literal<["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS"]>;
264
+ url: typeof Schema.String;
265
+ urlParams: Schema.Array$<Schema.Tuple2<typeof Schema.String, typeof Schema.String>>;
266
+ hash: Schema.Option<typeof Schema.String>;
267
+ headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
268
+ }>;
269
+ response: Schema.Struct<{
270
+ status: typeof Schema.Number;
271
+ headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
272
+ }>;
273
+ reason: Schema.Literal<["StatusCode", "Decode", "EmptyBody"]>;
274
+ description: Schema.optional<typeof Schema.String>;
275
+ cause: Schema.optional<typeof Schema.Defect>;
276
+ }>;
277
+ /**
278
+ * Error that occurs during HTTP response processing.
279
+ *
280
+ * This error is thrown when issues arise after receiving an HTTP response,
281
+ * such as unexpected status codes, response decoding failures, or empty
282
+ * response bodies.
283
+ *
284
+ * @example
285
+ * ```ts
286
+ * import { AiError } from "@effect/ai"
287
+ * import { Option } from "effect"
288
+ *
289
+ * const responseError = new AiError.HttpResponseError({
290
+ * module: "OpenAI",
291
+ * method: "createCompletion",
292
+ * reason: "StatusCode",
293
+ * request: {
294
+ * method: "POST",
295
+ * url: "https://api.openai.com/v1/completions",
296
+ * urlParams: [],
297
+ * hash: Option.none(),
298
+ * headers: { "Authorization": "Bearer sk-..." }
299
+ * },
300
+ * response: {
301
+ * status: 429,
302
+ * headers: { "X-RateLimit-Remaining": "0" }
303
+ * },
304
+ * description: "Rate limit exceeded"
305
+ * })
306
+ *
307
+ * console.log(responseError.message)
308
+ * // "StatusCode: Rate limit exceeded (429 POST https://api.openai.com/v1/completions)"
309
+ * ```
310
+ *
311
+ * @since 1.0.0
312
+ * @category Errors
313
+ */
314
+ export declare class HttpResponseError extends HttpResponseError_base {
315
+ /**
316
+ * @since 1.0.0
317
+ */
318
+ readonly [TypeId]: TypeId;
319
+ /**
320
+ * Creates an HttpResponseError from a platform HttpClientError.ResponseError.
321
+ *
322
+ * @example
323
+ * ```ts
324
+ * import { AiError } from "@effect/ai"
325
+ * import { Headers, HttpClientError } from "@effect/platform"
326
+ * import { Option } from "effect"
327
+ *
328
+ * declare const platformError: HttpClientError.ResponseError
329
+ *
330
+ * const aiError = AiError.HttpResponseError.fromResponseError({
331
+ * module: "OpenAI",
332
+ * method: "completion",
333
+ * error: platformError
334
+ * })
335
+ * ```
336
+ *
337
+ * @since 1.0.0
338
+ * @category Constructors
339
+ */
340
+ static fromResponseError({ error, ...params }: {
341
+ readonly module: string;
342
+ readonly method: string;
343
+ readonly error: HttpClientError.ResponseError;
344
+ }): HttpResponseError;
345
+ get message(): string;
346
+ }
347
+ declare const MalformedInput_base: Schema.TaggedErrorClass<MalformedInput, "MalformedInput", {
348
+ readonly _tag: Schema.tag<"MalformedInput">;
349
+ } & {
350
+ module: typeof Schema.String;
351
+ method: typeof Schema.String;
352
+ description: Schema.optional<typeof Schema.String>;
353
+ cause: Schema.optional<typeof Schema.Defect>;
354
+ }>;
355
+ /**
356
+ * Error thrown when input data doesn't match the expected format or schema.
357
+ *
358
+ * This error occurs when the data provided to an AI operation fails validation,
359
+ * is missing required fields, or doesn't conform to the expected structure.
360
+ *
361
+ * @example
362
+ * ```ts
363
+ * import { AiError } from "@effect/ai"
364
+ * import { Effect } from "effect"
365
+ *
366
+ * const validateInput = (data: unknown) =>
367
+ * typeof data === "string" && data.length > 0
368
+ * ? Effect.succeed(data)
369
+ * : Effect.fail(new AiError.MalformedInput({
370
+ * module: "ChatBot",
371
+ * method: "processMessage",
372
+ * description: "Input must be a non-empty string"
373
+ * }))
374
+ *
375
+ * const program = validateInput("").pipe(
376
+ * Effect.catchTag("MalformedInput", (error) => {
377
+ * console.log(`Input validation failed: ${error.description}`)
378
+ * return Effect.succeed("Please provide a valid message")
379
+ * })
380
+ * )
381
+ * ```
382
+ *
383
+ * @since 1.0.0
384
+ * @category Errors
385
+ */
386
+ export declare class MalformedInput extends MalformedInput_base {
387
+ /**
388
+ * @since 1.0.0
389
+ */
390
+ readonly [TypeId]: TypeId;
391
+ }
392
+ declare const MalformedOutput_base: Schema.TaggedErrorClass<MalformedOutput, "MalformedOutput", {
393
+ readonly _tag: Schema.tag<"MalformedOutput">;
14
394
  } & {
15
395
  module: typeof Schema.String;
16
396
  method: typeof Schema.String;
17
- description: typeof Schema.String;
397
+ description: Schema.optional<typeof Schema.String>;
18
398
  cause: Schema.optional<typeof Schema.Defect>;
19
399
  }>;
20
400
  /**
401
+ * Error thrown when output data can't be parsed or validated.
402
+ *
403
+ * This error occurs when AI service responses don't match the expected format,
404
+ * contain invalid data structures, or fail schema validation during parsing.
405
+ *
406
+ * @example
407
+ * ```ts
408
+ * import { AiError } from "@effect/ai"
409
+ * import { Effect, Schema } from "effect"
410
+ *
411
+ * const ResponseSchema = Schema.Struct({
412
+ * message: Schema.String,
413
+ * tokens: Schema.Number
414
+ * })
415
+ *
416
+ * const parseResponse = (data: unknown) =>
417
+ * Schema.decodeUnknown(ResponseSchema)(data).pipe(
418
+ * Effect.mapError(parseError =>
419
+ * new AiError.MalformedOutput({
420
+ * module: "OpenAI",
421
+ * method: "completion",
422
+ * description: "Response doesn't match expected schema",
423
+ * cause: parseError
424
+ * })
425
+ * )
426
+ * )
427
+ *
428
+ * const program = parseResponse({ invalid: "data" }).pipe(
429
+ * Effect.catchTag("MalformedOutput", (error) => {
430
+ * console.log(`Parsing failed: ${error.description}`)
431
+ * return Effect.succeed({ message: "Error", tokens: 0 })
432
+ * })
433
+ * )
434
+ * ```
435
+ *
21
436
  * @since 1.0.0
22
- * @category errors
437
+ * @category Errors
23
438
  */
24
- export declare class AiError extends AiError_base {
439
+ export declare class MalformedOutput extends MalformedOutput_base {
440
+ /**
441
+ * @since 1.0.0
442
+ */
443
+ readonly [TypeId]: TypeId;
25
444
  /**
445
+ * Creates a MalformedOutput error from a Schema ParseError.
446
+ *
447
+ * @example
448
+ * ```ts
449
+ * import { AiError } from "@effect/ai"
450
+ * import { Effect, Schema } from "effect"
451
+ *
452
+ * const UserSchema = Schema.Struct({
453
+ * name: Schema.String,
454
+ * age: Schema.Number
455
+ * })
456
+ *
457
+ * const parseUser = (data: unknown) =>
458
+ * Schema.decodeUnknown(UserSchema)(data).pipe(
459
+ * Effect.mapError((parseError) =>
460
+ * AiError.MalformedOutput.fromParseError({
461
+ * module: "UserService",
462
+ * method: "parseUserData",
463
+ * error: parseError
464
+ * })
465
+ * )
466
+ * )
467
+ * ```
468
+ *
26
469
  * @since 1.0.0
470
+ * @category Constructors
27
471
  */
28
- static is(u: unknown): u is AiError;
472
+ static fromParseError({ error, ...params }: {
473
+ readonly module: string;
474
+ readonly method: string;
475
+ readonly error: ParseError;
476
+ }): MalformedOutput;
477
+ }
478
+ declare const UnknownError_base: Schema.TaggedErrorClass<UnknownError, "UnknownError", {
479
+ readonly _tag: Schema.tag<"UnknownError">;
480
+ } & {
481
+ module: typeof Schema.String;
482
+ method: typeof Schema.String;
483
+ description: Schema.optional<typeof Schema.String>;
484
+ cause: Schema.optional<typeof Schema.Defect>;
485
+ }>;
486
+ /**
487
+ * Catch-all error for unexpected runtime errors in AI operations.
488
+ *
489
+ * This error is used when an unexpected exception occurs that doesn't fit
490
+ * into the other specific error categories. It provides context about where
491
+ * the error occurred and preserves the original cause for debugging.
492
+ *
493
+ * @example
494
+ * ```ts
495
+ * import { AiError } from "@effect/ai"
496
+ * import { Effect } from "effect"
497
+ *
498
+ * const riskyOperation = () => {
499
+ * try {
500
+ * // Some operation that might throw
501
+ * throw new Error("Unexpected network issue")
502
+ * } catch (cause) {
503
+ * return Effect.fail(new AiError.UnknownError({
504
+ * module: "ChatService",
505
+ * method: "sendMessage",
506
+ * description: "An unexpected error occurred during message processing",
507
+ * cause
508
+ * }))
509
+ * }
510
+ * }
511
+ *
512
+ * const program = riskyOperation().pipe(
513
+ * Effect.catchTag("UnknownError", (error) => {
514
+ * console.log(error.message)
515
+ * // "ChatService.sendMessage: An unexpected error occurred during message processing"
516
+ * return Effect.succeed("Service temporarily unavailable")
517
+ * })
518
+ * )
519
+ * ```
520
+ *
521
+ * @since 1.0.0
522
+ * @category Errors
523
+ */
524
+ export declare class UnknownError extends UnknownError_base {
29
525
  /**
30
526
  * @since 1.0.0
31
527
  */
@@ -35,5 +531,77 @@ export declare class AiError extends AiError_base {
35
531
  */
36
532
  get message(): string;
37
533
  }
534
+ /**
535
+ * Union type representing all possible AI operation errors.
536
+ *
537
+ * This type encompasses all error cases that can occur during AI operations,
538
+ * providing a comprehensive error handling surface for applications.
539
+ *
540
+ * @example
541
+ * ```ts
542
+ * import { AiError } from "@effect/ai"
543
+ * import { Effect, Match } from "effect"
544
+ *
545
+ * const handleAnyAiError = Match.type<AiError.AiError>().pipe(
546
+ * Match.tag("HttpRequestError", (err) =>
547
+ * `Network error: ${err.reason}`
548
+ * ),
549
+ * Match.tag("HttpResponseError", (err) =>
550
+ * `Server error: HTTP ${err.response.status}`
551
+ * ),
552
+ * Match.tag("MalformedInput", (err) =>
553
+ * `Invalid input: ${err.description || "Data validation failed"}`
554
+ * ),
555
+ * Match.tag("MalformedOutput", (err) =>
556
+ * `Invalid response: ${err.description || "Response parsing failed"}`
557
+ * ),
558
+ * Match.orElse((err) =>
559
+ * `Unknown error: ${err.message}`
560
+ * )
561
+ * )
562
+ * ```
563
+ *
564
+ * @since 1.0.0
565
+ * @category Models
566
+ */
567
+ export type AiError = HttpRequestError | HttpResponseError | MalformedInput | MalformedOutput | UnknownError;
568
+ /**
569
+ * Schema for validating and parsing AI errors.
570
+ *
571
+ * This schema can be used to decode unknown values into properly typed AI
572
+ * errors, ensuring type safety when handling errors from external sources or
573
+ * serialized data.
574
+ *
575
+ * @example
576
+ * ```ts
577
+ * import { AiError } from "@effect/ai"
578
+ * import { Schema, Effect } from "effect"
579
+ *
580
+ * const parseAiError = (data: unknown) =>
581
+ * Schema.decodeUnknown(AiError.AiError)(data).pipe(
582
+ * Effect.map(error => {
583
+ * console.log(`Parsed AI error: ${error._tag}`)
584
+ * return error
585
+ * }),
586
+ * Effect.catchAll(() =>
587
+ * Effect.succeed(new AiError.UnknownError({
588
+ * module: "Parser",
589
+ * method: "parseAiError",
590
+ * description: "Failed to parse error data"
591
+ * }))
592
+ * )
593
+ * )
594
+ * ```
595
+ *
596
+ * @since 1.0.0
597
+ * @category Schemas
598
+ */
599
+ export declare const AiError: Schema.Union<[
600
+ typeof HttpRequestError,
601
+ typeof HttpResponseError,
602
+ typeof MalformedInput,
603
+ typeof MalformedOutput,
604
+ typeof UnknownError
605
+ ]>;
38
606
  export {};
39
607
  //# sourceMappingURL=AiError.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"AiError.d.ts","sourceRoot":"","sources":["../../src/AiError.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,OAAO,MAAyC,CAAA;AAErE;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAA;;;;;;;;;AAElC;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,YAK3B;IACA;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,OAAO;IAGnC;;OAEG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAS;IAClC;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}
1
+ {"version":3,"file":"AiError.d.ts","sourceRoot":"","sources":["../../src/AiError.ts"],"names":[],"mappings":"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"}