@effect/ai 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/ai",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Effect modules for working with AI apis",
   "license": "MIT",
   "repository": {

package/src/LanguageModel.ts

@@ -1010,12 +1010,13 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
 
   return Effect.forEach(toolCalls, (toolCall) => {
     return toolkit.handle(toolCall.name, toolCall.params as any).pipe(
-      Effect.map(({ encodedResult, result }) =>
+      Effect.map(({ encodedResult, isFailure, result }) =>
         Response.makePart("tool-result", {
           id: toolCall.id,
           name: toolCall.name,
           result,
           encodedResult,
+          isFailure,
           providerExecuted: false,
           ...(toolCall.providerName !== undefined
             ? { providerName: toolCall.providerName }

package/src/Prompt.ts

@@ -606,13 +606,11 @@ export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolC
  * const toolResultPart: Prompt.ToolResultPart = Prompt.makePart("tool-result", {
  *   id: "call_123",
  *   name: "get_weather",
+ *   isFailure: false,
  *   result: {
- *     _tag: "Right",
- *     right: {
- *       temperature: 22,
- *       condition: "sunny",
- *       humidity: 65
- *     }
+ *     temperature: 22,
+ *     condition: "sunny",
+ *     humidity: 65
  *   }
  * })
  * ```
@@ -629,10 +627,14 @@ export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOp
    * Name of the tool that was executed.
    */
   readonly name: string
+  /**
+   * Whether or not the result of executing the tool call handler was an error.
+   */
+  readonly isFailure: boolean
   /**
    * The result returned by the tool execution.
    */
-  readonly result: Schema.EitherEncoded<unknown, unknown>
+  readonly result: unknown
 }
 
 /**
@@ -650,10 +652,14 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
    * Name of the tool that was executed.
    */
   readonly name: string
+  /**
+   * Whether or not the result of executing the tool call handler was an error.
+   */
+  readonly isFailure: boolean
   /**
    * The result returned by the tool execution.
    */
-  readonly result: Schema.EitherEncoded<unknown, unknown>
+  readonly result: unknown
 }
 
 /**
@@ -675,10 +681,8 @@ export const ToolResultPart: Schema.Schema<ToolResultPart, ToolResultPartEncoded
   type: Schema.Literal("tool-result"),
   id: Schema.String,
   name: Schema.String,
-  result: Schema.encodedSchema(Schema.Either({
-    left: Schema.Unknown,
-    right: Schema.Unknown
-  })),
+  isFailure: Schema.Boolean,
+  result: Schema.Unknown,
   options: Schema.optionalWith(ProviderOptions, { default: constEmptyObject })
 }).pipe(
   Schema.attachPropertySignature(PartTypeId, PartTypeId),
@@ -1028,9 +1032,10 @@ export const userMessage = (params: MessageConstructorParams<UserMessage>): User
  *     Prompt.makePart("tool-result", {
  *       id: "call_123",
  *       name: "get_weather",
+ *       isFailure: false,
  *       result: {
- *         _tag: "Right",
- *         right: { temperature: 72, condition: "sunny" }
+ *         temperature: 72,
+ *         condition: "sunny"
  *       }
  *     }),
  *     Prompt.makePart("text", {
@@ -1138,15 +1143,13 @@ export const assistantMessage = (params: MessageConstructorParams<AssistantMessa
  *     Prompt.makePart("tool-result", {
  *       id: "call_123",
  *       name: "search_web",
+ *       isFailure: false,
  *       result: {
- *         _tag: "Right",
- *         right: {
- *           query: "TypeScript best practices",
- *           results: [
- *             { title: "TypeScript Handbook", url: "https://..." },
- *             { title: "Effective TypeScript", url: "https://..." }
- *           ]
- *         }
+ *         query: "TypeScript best practices",
+ *         results: [
+ *           { title: "TypeScript Handbook", url: "https://..." },
+ *           { title: "Effective TypeScript", url: "https://..." }
+ *         ]
  *       }
  *     })
  *   ]
@@ -1564,8 +1567,9 @@ const isValidPart = (part: Response.AnyPart): part is ValidResponsePart => {
  *   Response.makePart("tool-result", {
  *     id: "call_1",
  *     name: "get_time",
- *     result: Either.right("10:30 AM"),
- *     encodedResult: { _tag: "Right", right: "10:30 AM" },
+ *     isFailure: false,
+ *     result: "10:30 AM",
+ *     encodedResult: "10:30 AM",
  *     providerExecuted: false
  *   })
  * ]
@@ -1650,6 +1654,7 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
           toolParts.push(makePart("tool-result", {
             id: part.id,
             name: part.providerName ?? part.name,
+            isFailure: part.isFailure,
             result: part.encodedResult
           }))
           break

package/src/Response.ts

@@ -28,7 +28,6 @@
  */
 import type * as DateTime from "effect/DateTime"
 import * as Effect from "effect/Effect"
-import type * as Either from "effect/Either"
 import { constFalse } from "effect/Function"
 import type * as Option from "effect/Option"
 import * as ParseResult from "effect/ParseResult"
@@ -1506,6 +1505,75 @@ export const toolCallPart = <const Name extends string, Params>(
 // Tool Call Result Part
 // =============================================================================
 
+/**
+ * The base fields of a tool result part.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface BaseToolResult<Name extends string> extends BasePart<"tool-result", ToolResultPartMetadata> {
+  /**
+   * Unique identifier matching the original tool call.
+   */
+  readonly id: string
+  /**
+   * Name of the tool being called, which corresponds to the name of the tool
+   * in the `Toolkit` included with the request.
+   */
+  readonly name: Name
+  /**
+   * The encoded result for serialization purposes.
+   */
+  readonly encodedResult: unknown
+  /**
+   * Optional provider-specific name for the tool, which can be useful when the
+   * name of the tool in the `Toolkit` and the name of the tool used by the
+   * model are different.
+   *
+   * This is usually happens only with provider-defined tools which require a
+   * user-space handler.
+   */
+  readonly providerName?: string | undefined
+  /**
+   * Whether the tool was executed by the provider (true) or framework (false).
+   */
+  readonly providerExecuted: boolean
+}
+
+/**
+ * Represents a successful tool call result.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface ToolResultSuccess<Name extends string, Success> extends BaseToolResult<Name> {
+  /**
+   * The decoded success returned by the tool execution.
+   */
+  readonly result: Success
+  /**
+   * Whether or not the result of executing the tool call handler was an error.
+   */
+  readonly isFailure: false
+}
+
+/**
+ * Represents a failed tool call result.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export interface ToolResultFailure<Name extends string, Failure> extends BaseToolResult<Name> {
+  /**
+   * The decoded failure returned by the tool execution.
+   */
+  readonly result: Failure
+  /**
+   * Whether or not the result of executing the tool call handler was an error.
+   */
+  readonly isFailure: true
+}
+
 /**
  * Response part representing the result of a tool call.
  *
@@ -1527,18 +1595,16 @@ export const toolCallPart = <const Name extends string, Params>(
  * > = Response.toolResultPart({
  *   id: "call_123",
  *   name: "get_weather",
- *   result: Either.right({
+ *   isFailure: false,
+ *   result: {
  *     temperature: 22,
  *     condition: "sunny",
  *     humidity: 65
- *   }),
+ *   },
  *   encodedResult: {
- *     _tag: "Right",
- *     right: {
- *       temperature: 22,
- *       condition: "sunny",
- *       humidity: 65
- *     }
+ *     temperature: 22,
+ *     condition: "sunny",
+ *     humidity: 65
  *   },
  *   providerExecuted: false
  * })
@@ -1547,40 +1613,9 @@ export const toolCallPart = <const Name extends string, Params>(
  * @since 1.0.0
  * @category Models
  */
-export interface ToolResultPart<Name extends string, Success, Failure>
-  extends BasePart<"tool-result", ToolResultPartMetadata>
-{
-  /**
-   * Unique identifier matching the original tool call.
-   */
-  readonly id: string
-  /**
-   * Name of the tool being called, which corresponds to the name of the tool
-   * in the `Toolkit` included with the request.
-   */
-  readonly name: Name
-  /**
-   * The decoded result returned by the tool execution.
-   */
-  readonly result: Either.Either<Success, Failure>
-  /**
-   * The encoded result for serialization purposes.
-   */
-  readonly encodedResult: Schema.EitherEncoded<unknown, unknown>
-  /**
-   * Optional provider-specific name for the tool, which can be useful when the
-   * name of the tool in the `Toolkit` and the name of the tool used by the
-   * model are different.
-   *
-   * This is usually happens only with provider-defined tools which require a
-   * user-space handler.
-   */
-  readonly providerName?: string | undefined
-  /**
-   * Whether the tool was executed by the provider (true) or framework (false).
-   */
-  readonly providerExecuted: boolean
-}
+export type ToolResultPart<Name extends string, Success, Failure> =
+  | ToolResultSuccess<Name, Success>
+  | ToolResultFailure<Name, Failure>
 
 /**
  * Encoded representation of tool result parts for serialization.
@@ -1601,7 +1636,11 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
   /**
    * The result returned by the tool execution.
    */
-  readonly result: Schema.EitherEncoded<unknown, unknown>
+  readonly result: unknown
+  /**
+   * Whether or not the result of executing the tool call handler was an error.
+   */
+  readonly isFailure: boolean
   /**
    * Optional provider-specific name for the tool, which can be useful when the
    * name of the tool in the `Toolkit` and the name of the tool used by the
@@ -1644,15 +1683,13 @@ export const ToolResultPart = <
   ToolResultPart<Name, Schema.Schema.Type<Success>, Schema.Schema.Type<Failure>>,
   ToolResultPartEncoded
 > => {
-  const ResultSchema = Schema.Either({
-    left: failure,
-    right: success
-  })
   const Base = Schema.Struct({
     id: Schema.String,
     type: Schema.Literal("tool-result"),
-    providerName: Schema.optional(Schema.String)
+    providerName: Schema.optional(Schema.String),
+    isFailure: Schema.Boolean
   })
+  const ResultSchema = Schema.Union(success, failure)
   const Encoded = Schema.Struct({
     ...Base.fields,
     name: Schema.String,
@@ -1692,11 +1729,9 @@ export const ToolResultPart = <
       encode: Effect.fnUntraced(function*(decoded) {
         const encoded = yield* encodeResult(decoded.result)
         return {
-          id: decoded.id,
-          type: decoded.type,
-          name: decoded.name,
+          ...decoded,
           result: encoded,
-          ...(decoded.metadata ? { metadata: decoded.metadata } : {}),
+          ...(decoded.metadata ?? {}),
           ...(decoded.providerName ? { providerName: decoded.providerName } : {}),
           ...(decoded.providerExecuted ? { providerExecuted: true } : {})
         }
@@ -1711,9 +1746,21 @@ export const ToolResultPart = <
  * @since 1.0.0
  * @category Constructors
  */
-export const toolResultPart = <const Name extends string, Success, Failure>(
-  params: ConstructorParams<ToolResultPart<Name, Success, Failure>>
-): ToolResultPart<Name, Success, Failure> => makePart("tool-result", params)
+export const toolResultPart = <
+  const Params extends ConstructorParams<ToolResultPart<string, any, any>>
+>(
+  params: Params
+): Params extends {
+  readonly name: infer Name extends string
+  readonly isFailure: false
+  readonly result: infer Success
+} ? ToolResultPart<Name, Success, never>
+  : Params extends {
+    readonly name: infer Name extends string
+    readonly isFailure: true
+    readonly result: infer Failure
+  } ? ToolResultPart<Name, never, Failure>
+  : never => makePart("tool-result", params) as any
 
 // =============================================================================
 // File Part

package/src/Tool.ts

@@ -27,7 +27,7 @@
  * @since 1.0.0
  */
 import * as Context from "effect/Context"
-import * as Effect from "effect/Effect"
+import type * as Effect from "effect/Effect"
 import { constFalse, constTrue, identity } from "effect/Function"
 import * as JsonSchema from "effect/JSONSchema"
 import * as Option from "effect/Option"
@@ -37,7 +37,7 @@ import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as AST from "effect/SchemaAST"
 import type { Covariant } from "effect/Types"
-import * as AiError from "./AiError.js"
+import type * as AiError from "./AiError.js"
 
 // =============================================================================
 // Type Ids
@@ -164,12 +164,6 @@ export interface Tool<
    */
   readonly failureSchema: Config["failure"]
 
-  /**
-   * A `Schema` representing the result of a tool call, whether it succeeds or
-   * fails.
-   */
-  readonly resultSchema: Schema.Either<Config["success"], Config["failure"]>
-
   /**
    * A `Context` object containing tool annotations which can store metadata
    * about the tool.
@@ -340,13 +334,6 @@ export interface ProviderDefined<
    * this tool into a `Layer`.
    */
   readonly requiresHandler: RequiresHandler
-
-  /**
-   * Decodes the result received after the provider-defined tool is called.
-   */
-  decodeResult(
-    args: unknown
-  ): Effect.Effect<Config["success"]["Type"], AiError.AiError>
 }
 
 /**
@@ -509,7 +496,6 @@ export interface Any extends Pipeable {
   readonly parametersSchema: AnyStructSchema
   readonly successSchema: Schema.Schema.Any
   readonly failureSchema: Schema.Schema.All
-  readonly resultSchema: Schema.Either<any, any>
   readonly failureMode: FailureMode
   readonly annotations: Context.Context<never>
 }
@@ -705,8 +691,8 @@ export type Result<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? Schema.Either<_Config["success"], _Config["failure"]>["Type"] :
-  never
+> ? Success<T> | Failure<T>
+  : never
 
 /**
  * A utility type to extract the encoded type of the tool call result whether
@@ -719,8 +705,8 @@ export type ResultEncoded<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? Schema.Either<_Config["success"], _Config["failure"]>["Encoded"] :
-  never
+> ? SuccessEncoded<T> | FailureEncoded<T>
+  : never
 
 /**
  * A utility type to extract the requirements of an `Tool`.
@@ -759,6 +745,10 @@ export interface Handler<Name extends string> {
  * @category Models
  */
 export interface HandlerResult<Tool extends Any> {
+  /**
+   * Whether the result of executing the tool call handler was an error or not.
+   */
+  readonly isFailure: boolean
   /**
    * The result of executing the handler for a particular tool.
    */
@@ -768,7 +758,7 @@ export interface HandlerResult<Tool extends Any> {
    * tool as a JSON-serializable value. The encoded result can be incorporated
    * into subsequent requests to the large language model.
    */
-  readonly encodedResult: Schema.EitherEncoded<unknown, unknown>
+  readonly encodedResult: unknown
 }
 
 /**
@@ -782,7 +772,7 @@ export type HandlerError<T> = T extends Tool<
   infer _Name,
   infer _Config,
   infer _Requirements
-> ? _Config["failureMode"] extends "error" ? Schema.Schema.Type<_Config["failure"]>
+> ? _Config["failureMode"] extends "error" ? _Config["failure"]["Type"]
   : never
   : never
 
@@ -863,21 +853,7 @@ const Proto = {
 
 const ProviderDefinedProto = {
   ...Proto,
-  [ProviderDefinedTypeId]: ProviderDefinedTypeId,
-  decodeResult(this: AnyProviderDefined, result: unknown) {
-    return Schema.decodeUnknown(this.successSchema)(result).pipe(
-      Effect.orElse(() => Schema.decodeUnknown(this.failureSchema as any)(result)),
-      Effect.mapError(
-        (cause) =>
-          new AiError.MalformedOutput({
-            module: "Tool",
-            method: "ProviderDefined.decodeResult",
-            description: `Failed to decode the result of provider-defined tool '${this.name}'`,
-            cause
-          })
-      )
-    )
-  }
+  [ProviderDefinedTypeId]: ProviderDefinedTypeId
 }
 
 const userDefinedProto = <
@@ -892,7 +868,6 @@ const userDefinedProto = <
   readonly parametersSchema: Parameters
   readonly successSchema: Success
   readonly failureSchema: Failure
-  readonly resultSchema: Schema.Either<Success, Failure>
   readonly annotations: Context.Context<never>
   readonly failureMode: Mode
 }): Tool<
@@ -927,7 +902,6 @@ const providerDefinedProto = <
   readonly parametersSchema: Parameters
   readonly successSchema: Success
   readonly failureSchema: Failure
-  readonly resultSchema: Schema.Either<Success, Failure>
   readonly failureMode: FailureMode
 }): ProviderDefined<
   Name,
@@ -1022,10 +996,6 @@ export const make = <
 > => {
   const successSchema = options?.success ?? Schema.Void
   const failureSchema = options?.failure ?? Schema.Never
-  const resultSchema = Schema.Either({
-    left: failureSchema,
-    right: successSchema
-  })
   return userDefinedProto({
     name,
     description: options?.description,
@@ -1034,7 +1004,6 @@ export const make = <
       : constEmptyStruct,
     successSchema,
     failureSchema,
-    resultSchema,
     failureMode: options?.failureMode ?? "error",
     annotations: Context.empty()
   }) as any
@@ -1146,10 +1115,6 @@ export const providerDefined = <
   const failureMode = "failureMode" in args ? args.failureMode : undefined
   const successSchema = options?.success ?? Schema.Void
   const failureSchema = options?.failure ?? Schema.Never
-  const resultSchema = Schema.Either({
-    right: successSchema,
-    left: failureSchema
-  })
   return providerDefinedProto({
     id: options.id,
     name: options.toolkitName,
@@ -1162,7 +1127,6 @@ export const providerDefined = <
       : constEmptyStruct,
     successSchema,
     failureSchema,
-    resultSchema,
     failureMode: failureMode ?? "error"
   }) as any
 }
@@ -1213,10 +1177,6 @@ export const fromTaggedRequest = <S extends AnyTaggedRequestSchema>(
     parametersSchema: schema,
     successSchema: schema.success,
     failureSchema: schema.failure,
-    resultSchema: Schema.Either({
-      left: schema.failure,
-      right: schema.success
-    }),
     failureMode: "error",
     annotations: Context.empty()
   }) as any

package/src/Toolkit.ts

@@ -40,7 +40,6 @@
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import { CommitPrototype } from "effect/Effectable"
-import * as Either from "effect/Either"
 import { identity } from "effect/Function"
 import type { Inspectable } from "effect/Inspectable"
 import { BaseProto as InspectableProto } from "effect/Inspectable"
@@ -267,16 +266,17 @@ const Proto = {
         readonly context: Context.Context<never>
         readonly handler: (params: any) => Effect.Effect<any, any>
         readonly decodeParameters: (u: unknown) => Effect.Effect<Tool.Parameters<any>, ParseError>
-        readonly validateResult: (u: unknown) => Effect.Effect<Either.Either<unknown, unknown>, ParseError>
-        readonly encodeResult: (u: unknown) => Effect.Effect<Schema.EitherEncoded<unknown, unknown>, ParseError>
+        readonly validateResult: (u: unknown) => Effect.Effect<unknown, ParseError>
+        readonly encodeResult: (u: unknown) => Effect.Effect<unknown, ParseError>
       }>()
       const getSchemas = (tool: Tool.Any) => {
         let schemas = schemasCache.get(tool)
         if (Predicate.isUndefined(schemas)) {
           const handler = context.unsafeMap.get(tool.id)! as Tool.Handler<any>
           const decodeParameters = Schema.decodeUnknown(tool.parametersSchema) as any
-          const validateResult = Schema.validate(tool.resultSchema) as any
-          const encodeResult = Schema.encodeUnknown(tool.resultSchema) as any
+          const resultSchema = Schema.Union(tool.successSchema, tool.failureSchema)
+          const validateResult = Schema.validate(resultSchema) as any
+          const encodeResult = Schema.encodeUnknown(resultSchema) as any
           schemas = {
             context: handler.context,
             handler: handler.handler,
@@ -313,15 +313,16 @@ const Proto = {
                 cause
               })
           )
-          const result = yield* schemas.handler(decodedParams).pipe(
-            Effect.matchEffect({
-              onFailure: (error) =>
-                tool.failureMode === "error"
-                  ? Effect.fail(error)
-                  : Effect.succeed(Either.left(error)),
-              onSuccess: (value) => Effect.succeed(Either.right(value))
-            }),
-            Effect.flatMap((either) => schemas.validateResult(either)),
+          const { isFailure, result } = yield* schemas.handler(decodedParams).pipe(
+            Effect.map((result) => ({ result, isFailure: false })),
+            Effect.catchAll((error) =>
+              // If the tool handler failed, check the tool's failure mode to
+              // determine how the result should be returned to the end user
+              tool.failureMode === "error"
+                ? Effect.fail(error)
+                : Effect.succeed({ result: error, isFailure: true })
+            ),
+            Effect.tap(({ result }) => schemas.validateResult(result)),
             Effect.mapInputContext((input) => Context.merge(schemas.context, input)),
             Effect.mapError((cause) =>
               ParseResult.isParseError(cause)
@@ -345,6 +346,7 @@ const Proto = {
               })
           )
           return {
+            isFailure,
             result,
             encodedResult
           } satisfies Tool.HandlerResult<any>
@@ -352,7 +354,7 @@ const Proto = {
       )
       return {
         tools,
-        handle: handle as any
+        handle
       } satisfies WithHandler<Record<string, any>>
     })
   },