@effect/ai 0.14.1 → 0.16.0

package/src/AiInput.ts

@@ -1,227 +1,197 @@
 /**
  * @since 1.0.0
  */
-import type { PlatformError } from "@effect/platform/Error"
-import * as FileSystem from "@effect/platform/FileSystem"
-import * as Path from "@effect/platform/Path"
-import * as Chunk from "effect/Chunk"
-import * as Context from "effect/Context"
-import * as Effect from "effect/Effect"
-import * as Encoding from "effect/Encoding"
 import { dual } from "effect/Function"
-import * as Option from "effect/Option"
-import * as ParseResult from "effect/ParseResult"
 import * as Predicate from "effect/Predicate"
-import * as Schema_ from "effect/Schema"
-import { AiResponse, ToolCallId, WithResolved } from "./AiResponse.js"
-import * as AiRole from "./AiRole.js"
-
-const constDisableValidation = { disableValidation: true } as const
+import * as Schema from "effect/Schema"
+import * as AiResponse from "./AiResponse.js"
+import * as InternalCommon from "./internal/common.js"
 
 /**
  * @since 1.0.0
- * @category parts
+ * @category Type Ids
  */
-export const PartTypeId: unique symbol = Symbol("@effect/ai/AiInput/Part")
+export const TypeId = Symbol.for("@effect/ai/AiInput")
 
 /**
  * @since 1.0.0
- * @category parts
+ * @category Type Ids
  */
-export type PartTypeId = typeof PartTypeId
+export type TypeId = typeof TypeId
 
 /**
+ * Represents input to a large language model.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class TextPart extends Schema_.TaggedClass<TextPart>("@effect/ai/AiInput/TextPart")("Text", {
-  content: Schema_.String
+export class AiInput extends Schema.Class<AiInput>(
+  "@effect/ai/AiInput"
+)({
+  messages: Schema.Array(Schema.suspend(() => Message))
 }) {
   /**
    * @since 1.0.0
    */
-  readonly [PartTypeId]: PartTypeId = PartTypeId
-  /**
-   * @since 1.0.0
-   */
-  static fromContent(content: string): TextPart {
-    return new TextPart({ content }, constDisableValidation)
-  }
+  readonly [TypeId]: TypeId = TypeId
 }
 
 /**
  * @since 1.0.0
- * @category parts
+ * @category Models
+ */
+export const FromJson = Schema.parseJson(AiInput)
+
+/**
+ * Represents raw input types that can be converted into an `AiInput`.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export type Raw =
+  | string
+  | Message
+  | Iterable<Message>
+  | AiInput
+  | AiResponse.AiResponse
+  | AiResponse.WithStructuredOutput<any>
+  | AiResponse.WithToolCallResults<any>
+
+// =============================================================================
+// Message
+// =============================================================================
+
+/**
+ * @since 1.0.0
+ * @category Type Ids
  */
-export const ImageQuality = Schema_.Literal("low", "high", "auto")
+export const MessageTypeId = Symbol.for("@effect/ai/AiInput/Message")
 
 /**
  * @since 1.0.0
- * @category parts
+ * @category Type Ids
  */
-export type ImageQuality = typeof ImageQuality.Type
+export type MessageTypeId = typeof MessageTypeId
 
 /**
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class ImageUrlPart extends Schema_.TaggedClass<ImageUrlPart>("@effect/ai/AiInput/ImageUrlPart")("ImageUrl", {
-  url: Schema_.String,
-  quality: ImageQuality.pipe(
-    Schema_.propertySignature,
-    Schema_.withConstructorDefault(() => "auto" as const)
-  )
+export class UserMessage extends Schema.TaggedClass<UserMessage>(
+  "@effect/ai/AiInput/Message/UserMessage"
+)("UserMessage", {
+  parts: Schema.Array(Schema.suspend(() => UserMessagePart)),
+  userName: Schema.optional(Schema.String)
 }) {
   /**
    * @since 1.0.0
    */
-  readonly [PartTypeId]: PartTypeId = PartTypeId
+  readonly [MessageTypeId]: MessageTypeId = MessageTypeId
 }
 
-const base64ContentTypeRegex = /^data:(.*?);base64$/
-
-/**
- * @since 1.0.0
- * @category base64
- */
-export interface Base64DataUrl extends
-  Schema_.transformOrFail<
-    typeof Schema_.String,
-    Schema_.Struct<{
-      data: Schema_.Schema<Uint8Array>
-      contentType: typeof Schema_.String
-    }>
-  >
-{}
-
-/**
- * @since 1.0.0
- * @category base64
- */
-export const Base64DataUrl: Base64DataUrl = Schema_.transformOrFail(
-  Schema_.String.annotations({
-    title: "Base64 Data URL",
-    description: "A base64 data URL"
-  }),
-  Schema_.Struct({
-    data: Schema_.Uint8ArrayFromSelf,
-    contentType: Schema_.String
-  }),
-  {
-    decode(base64Url, _, ast) {
-      const commaIndex = base64Url.indexOf(",")
-      if (commaIndex === -1) {
-        return ParseResult.fail(new ParseResult.Type(ast, base64Url))
-      }
-      const header = base64Url.slice(0, commaIndex)
-      const data = base64Url.slice(commaIndex + 1)
-      const contentType = base64ContentTypeRegex.exec(header)
-      if (contentType === null) {
-        return ParseResult.fail(new ParseResult.Type(ast, base64Url))
-      }
-      return Encoding.decodeBase64(data).pipe(
-        ParseResult.mapError((_) => new ParseResult.Type(ast, base64Url)),
-        ParseResult.map((data) => ({ data, contentType: contentType[1] }))
-      )
-    },
-    encode({ contentType, data }) {
-      const base64 = Encoding.encodeBase64(data)
-      return ParseResult.succeed(`data:${contentType};base64,${base64}`)
-    }
-  }
-)
-
 /**
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class ImagePart extends Schema_.TaggedClass<ImagePart>("@effect/ai/AiInput/ImagePart")("Image", {
-  image: Base64DataUrl,
-  quality: ImageQuality.pipe(
-    Schema_.propertySignature,
-    Schema_.withConstructorDefault(() => "auto" as const)
-  )
+export class AssistantMessage extends Schema.TaggedClass<AssistantMessage>(
+  "@effect/ai/AiInput/Message/AssistantMessage"
+)("AssistantMessage", {
+  parts: Schema.Array(Schema.suspend(() => AssistantMessagePart))
 }) {
   /**
    * @since 1.0.0
    */
-  readonly [PartTypeId]: PartTypeId = PartTypeId
+  readonly [MessageTypeId]: MessageTypeId = MessageTypeId
+}
 
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export class ToolMessage extends Schema.TaggedClass<ToolMessage>(
+  "@effect/ai/AiInput/Message/ToolMessage"
+)("ToolMessage", {
+  parts: Schema.Array(Schema.suspend(() => ToolMessagePart))
+}) {
   /**
    * @since 1.0.0
    */
-  static fromPath(
-    path: string,
-    quality: ImageQuality = "auto"
-  ): Effect.Effect<
-    ImagePart,
-    PlatformError,
-    FileSystem.FileSystem | Path.Path
-  > {
-    return FileSystem.FileSystem.pipe(
-      Effect.bindTo("fs"),
-      Effect.bind("Path", () => Path.Path),
-      Effect.bind("data", ({ fs }) => fs.readFile(path)),
-      Effect.map(({ Path, data }) => {
-        const ext = Path.extname(path)
-        let contentType: string
-        switch (ext) {
-          case ".jpg":
-          case ".jpeg": {
-            contentType = "image/jpeg"
-            break
-          }
-          default: {
-            if (ext.startsWith(".")) {
-              contentType = `image/${ext.slice(1)}`
-            } else {
-              contentType = "image/png"
-            }
-            break
-          }
-        }
-        return new ImagePart({
-          image: { data, contentType },
-          quality
-        }, constDisableValidation)
-      })
-    )
-  }
+  readonly [MessageTypeId]: MessageTypeId = MessageTypeId
+}
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export const Message: Schema.Union<[
+  typeof UserMessage,
+  typeof AssistantMessage,
+  typeof ToolMessage
+]> = Schema.Union(
+  UserMessage,
+  AssistantMessage,
+  ToolMessage
+)
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type Message = typeof Message.Type
+
+// =============================================================================
+// Part
+// =============================================================================
 
+/**
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export const PartTypeId = Symbol.for("@effect/ai/AiInput/Message/Part")
+
+/**
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export type PartTypeId = typeof PartTypeId
+
+/**
+ * Represents a text part of a message.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class TextPart extends Schema.TaggedClass<TextPart>(
+  "@effect/ai/AiInput/TextPart"
+)("TextPart", {
+  /**
+   * The text content.
+   */
+  text: Schema.String
+}) {
   /**
    * @since 1.0.0
    */
-  static fromBlob(blob: Blob, quality: ImageQuality = "auto"): Effect.Effect<ImagePart> {
-    return Effect.promise(() => blob.arrayBuffer()).pipe(
-      Effect.map((buffer) =>
-        new ImagePart({
-          image: {
-            contentType: blob.type,
-            data: new Uint8Array(buffer)
-          },
-          quality
-        })
-      )
-    )
-  }
-
-  get asBase64(): string {
-    return Encoding.encodeBase64(this.image.data)
-  }
-
-  get asDataUri(): string {
-    return `data:${this.image.contentType};base64,${this.asBase64}`
-  }
+  readonly [PartTypeId]: PartTypeId = PartTypeId
 }
 
 /**
+ * Represents an image part of a message with binary image data.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class ToolCallPart extends Schema_.TaggedClass<ToolCallPart>("@effect/ai/AiInput/ToolCallPart")("ToolCall", {
-  id: ToolCallId,
-  name: Schema_.String,
-  params: Schema_.Unknown
+export class ImagePart extends Schema.TaggedClass<ImagePart>(
+  "@effect/ai/AiInput/ImagePart"
+)("ImagePart", {
+  /**
+   * The binary image data.
+   */
+  data: Schema.Uint8ArrayFromBase64,
+  /**
+   * The optional MIME type for the image.
+   */
+  mediaType: Schema.optional(Schema.String)
 }) {
   /**
    * @since 1.0.0
@@ -230,15 +200,19 @@ export class ToolCallPart extends Schema_.TaggedClass<ToolCallPart>("@effect/ai/
 }
 
 /**
+ * Represents an image part of a message with a URL pointing to the image.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export class ToolCallResolvedPart
-  extends Schema_.TaggedClass<ToolCallResolvedPart>("@effect/ai/AiInput/ToolCallResolvedPart")("ToolCallResolved", {
-    toolCallId: ToolCallId,
-    value: Schema_.Unknown
-  })
-{
+export class ImageUrlPart extends Schema.TaggedClass<ImageUrlPart>(
+  "@effect/ai/AiInput/ImageUrlPart"
+)("ImageUrlPart", {
+  /**
+   * The URL that points to the image.
+   */
+  url: Schema.URL
+}) {
   /**
    * @since 1.0.0
    */
@@ -246,231 +220,378 @@ export class ToolCallResolvedPart
 }
 
 /**
+ * Represents a file part of a message with binary file data.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export type Part = TextPart | ToolCallPart | ToolCallResolvedPart | ImagePart | ImageUrlPart
+export class FilePart extends Schema.TaggedClass<FilePart>(
+  "@effect/ai/AiInput/FilePart"
+)("FilePart", {
+  /**
+   * The binary file data.
+   */
+  data: Schema.Uint8ArrayFromBase64,
+  /**
+   * The optional name of the file.
+   */
+  name: Schema.optional(Schema.String),
+  /**
+   * The optional MIME type for the image.
+   */
+  mediaType: Schema.optional(Schema.String)
+}) {
+  /**
+   * @since 1.0.0
+   */
+  readonly [PartTypeId]: PartTypeId = PartTypeId
+}
 
 /**
+ * Represents a file part of a message with a URL pointing to the file.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, PartTypeId)
+export class FileUrlPart extends Schema.TaggedClass<FileUrlPart>(
+  "@effect/ai/AiInput/FileUrlPart"
+)("FileUrlPart", {
+  /**
+   * The URL that points to the file.
+   */
+  url: Schema.URL
+}) {
+  /**
+   * @since 1.0.0
+   */
+  readonly [PartTypeId]: PartTypeId = PartTypeId
+}
 
 /**
+ * Represents a part of a message containing reasoning that the model used to
+ * generate its output.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export declare namespace Part {
+export class ReasoningPart extends Schema.TaggedClass<ReasoningPart>(
+  "@effect/ai/AiInput/ReasoningPart"
+)("ReasoningPart", {
+  /**
+   * The reasoning text that the model used to return the output.
+   */
+  reasoningText: Schema.String,
+  /**
+   * An optional signature which verifies that the reasoning text was generated
+   * by the model.
+   */
+  signature: Schema.optional(Schema.String)
+}) {
   /**
    * @since 1.0.0
-   * @category parts
-   */
-  export type Schema = Schema_.Union<[
-    typeof TextPart,
-    typeof ToolCallPart,
-    typeof ToolCallResolvedPart,
-    typeof ImagePart,
-    typeof ImageUrlPart
-  ]>
+   */
+  readonly [PartTypeId]: PartTypeId = PartTypeId
 }
 
 /**
+ * Represents a part of a message containing content in the model's reasoning
+ * that was encrypted by the model provider for safety reasons.
+ *
  * @since 1.0.0
- * @category parts
+ * @category Models
  */
-export const Part: Part.Schema = Schema_.Union(TextPart, ToolCallPart, ToolCallResolvedPart, ImagePart, ImageUrlPart)
+export class RedactedReasoningPart extends Schema.TaggedClass<RedactedReasoningPart>(
+  "@effect/ai/AiInput/RedactedReasoningPart"
+)("RedactedReasoningPart", {
+  /**
+   * The content in the reasoning that was encrypted by the model provider for
+   * safety reasons.
+   */
+  redactedText: Schema.String
+}) {
+  /**
+   * @since 1.0.0
+   */
+  readonly [PartTypeId]: PartTypeId = PartTypeId
+}
 
 /**
+ * Represents the identifier generated by a model when a tool call is requested.
+ *
  * @since 1.0.0
- * @category message
+ * @category Models
  */
-export const MessageTypeId: unique symbol = Symbol("@effect/ai/AiInput/Message")
+export const ToolCallId: Schema.brand<typeof Schema.String, "@effect/ai/ToolCallId"> = InternalCommon.ToolCallId
 
 /**
  * @since 1.0.0
- * @category message
+ * @category Models
  */
-export type MessageTypeId = typeof MessageTypeId
+export type ToolCallId = typeof ToolCallId.Type
 
 /**
+ * Represents a part of a message containing a tool call that the model has
+ * requested invocation of.
+ *
  * @since 1.0.0
- * @category message
+ * @category Models
  */
-export class Message extends Schema_.Class<Message>("@effect/ai/AiInput/Message")({
-  role: AiRole.AiRole,
-  parts: Schema_.Chunk(Part)
-}) {
+export class ToolCallPart extends Schema.TaggedClass<ToolCallPart>(
+  "@effect/ai/AiInput/ToolCallPart"
+)("ToolCallPart", {
   /**
-   * @since 1.0.0
+   * The identifier generated by a model when requesting a tool call.
    */
-  readonly [MessageTypeId]: MessageTypeId = MessageTypeId
-  /**
-   * @since 1.0.0
-   */
-  static is(u: unknown): u is Message {
-    return Predicate.hasProperty(u, MessageTypeId)
-  }
+  id: ToolCallId,
   /**
-   * @since 1.0.0
+   * The name of the tool to call.
    */
-  static fromInput(input: Message.Input, role: AiRole.AiRole = AiRole.user): Message {
-    if (typeof input === "string") {
-      return new Message({ role, parts: Chunk.of(TextPart.fromContent(input)) }, constDisableValidation)
-    } else if (isPart(input)) {
-      return new Message({ role, parts: Chunk.of(input) }, constDisableValidation)
-    }
-    return new Message({ role, parts: Chunk.fromIterable(input) }, constDisableValidation)
-  }
+  name: Schema.String,
   /**
-   * @since 1.0.0
+   * The arguments to call the tool with as a JSON-serializable object that
+   * matches the tool call input schema.
    */
-  static fromResponse(response: AiResponse): Option.Option<Message> {
-    if (Chunk.isEmpty(response.parts)) {
-      return Option.none()
-    }
-    return Option.some(
-      new Message({
-        role: response.role,
-        parts: Chunk.map(response.parts, (part) => {
-          switch (part._tag) {
-            case "Text": {
-              return TextPart.fromContent(part.content)
-            }
-            case "ToolCall": {
-              return new ToolCallPart(part, constDisableValidation)
-            }
-            case "ImageUrl": {
-              return new ImageUrlPart(part, constDisableValidation)
-            }
-          }
-        })
-      }, constDisableValidation)
-    )
-  }
+  params: Schema.Unknown
+}) {
   /**
    * @since 1.0.0
    */
-  static fromWithResolved<A>(response: WithResolved<A>): Message {
-    const toolParts: Array<ToolCallResolvedPart> = []
-    for (const [toolCallId, value] of response.encoded) {
-      toolParts.push(new ToolCallResolvedPart({ toolCallId, value }, constDisableValidation))
-    }
-    const toolPartsChunk = Chunk.unsafeFromArray(toolParts)
-    return Option.match(Message.fromResponse(response.response), {
-      onNone: () => new Message({ role: AiRole.model, parts: toolPartsChunk }, constDisableValidation),
-      onSome: (message) =>
-        new Message({
-          role: message.role,
-          parts: Chunk.appendAll(message.parts, toolPartsChunk)
-        }, constDisableValidation)
-    })
+  readonly [PartTypeId]: PartTypeId = PartTypeId
+
+  constructor(props: any, options?: Schema.MakeOptions) {
+    super(props, options)
   }
 }
 
 /**
+ * Represents a part of a message containing the results of tool calls that the
+ * model requested invocation of.
+ *
  * @since 1.0.0
- * @category message
+ * @category Models
  */
-export declare namespace Message {
+export class ToolCallResultPart extends Schema.TaggedClass<ToolCallResultPart>(
+  "@effect/ai/AiInput/ToolCallResultPart"
+)("ToolCallResultPart", {
+  /**
+   * The identifier generated by a model when requesting a tool call.
+   */
+  id: ToolCallId,
+  /**
+   * The result of the tool call as a JSON-serializable object.
+   */
+  result: Schema.Unknown
+}) {
   /**
    * @since 1.0.0
-   * @category message
    */
-  export type Input = string | Part | Iterable<Part>
+  readonly [PartTypeId]: PartTypeId = PartTypeId
 }
 
 /**
+ * The valid parts of a user message.
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Models
  */
-export const make = (input: Input, options?: {
-  readonly role?: AiRole.AiRole
-}): AiInput => {
-  if (typeof input !== "string" && Predicate.isIterable(input)) {
-    const chunk = Chunk.fromIterable(input as any)
-    if (Chunk.isEmpty(chunk)) {
-      return chunk as AiInput
-    } else if (Message.is(Chunk.unsafeHead(chunk))) {
-      return chunk as AiInput
-    }
-    return Chunk.of(Message.fromInput(chunk as any, options?.role))
-  } else if (AiResponse.is(input)) {
-    return Option.match(Message.fromResponse(input), {
-      onNone: Chunk.empty,
-      onSome: Chunk.of
-    })
-  } else if (WithResolved.is(input)) {
-    return Chunk.of(Message.fromWithResolved(input))
-  } else if (Message.is(input)) {
-    return Chunk.of(input)
-  }
-  return Chunk.of(Message.fromInput(input, options?.role))
-}
+export const UserMessagePart: Schema.Union<[
+  typeof TextPart,
+  typeof ImagePart,
+  typeof ImageUrlPart,
+  typeof FilePart,
+  typeof FileUrlPart
+]> = Schema.Union(
+  TextPart,
+  ImagePart,
+  ImageUrlPart,
+  FilePart,
+  FileUrlPart
+)
 
 /**
  * @since 1.0.0
- * @category constructors
+ * @category Models
  */
-export const empty: AiInput = Chunk.empty()
+export type UserMessagePart = typeof UserMessagePart.Type
 
 /**
+ * The valid parts of an assistant message.
+ *
  * @since 1.0.0
- * @category schemas
+ * @category Models
  */
-export const Schema: Schema_.Chunk<typeof Message> = Schema_.Chunk(Message)
+export const AssistantMessagePart: Schema.Union<[
+  typeof TextPart,
+  typeof ReasoningPart,
+  typeof RedactedReasoningPart,
+  typeof ToolCallPart
+]> = Schema.Union(
+  TextPart,
+  ReasoningPart,
+  RedactedReasoningPart,
+  ToolCallPart
+)
 
 /**
  * @since 1.0.0
- * @category schemas
+ * @category Models
  */
-export const SchemaJson: Schema_.Schema<Chunk.Chunk<Message>, string> = Schema_.parseJson(Schema)
+export type AssistantMessagePart = typeof AssistantMessagePart.Type
 
 /**
+ * The valid parts of a tool message.
+ *
  * @since 1.0.0
- * @category models
+ * @category Models
  */
-export type Input =
-  | string
-  | Part
-  | Iterable<Part>
-  | Message
-  | Iterable<Message>
-  | AiResponse
-  | WithResolved<unknown>
+export const ToolMessagePart: typeof ToolCallResultPart = ToolCallResultPart
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type ToolMessagePart = typeof ToolMessagePart.Type
+
+/**
+ * @since 1.0.0
+ * @category Guards
+ */
+export const is = (u: unknown): u is AiInput => Predicate.hasProperty(u, TypeId)
 
 /**
  * @since 1.0.0
- * @category models
+ * @category Guards
  */
-export type AiInput = Chunk.Chunk<Message>
+export const isMessage = (u: unknown): u is Message => Predicate.hasProperty(u, MessageTypeId)
 
 /**
  * @since 1.0.0
- * @category system
+ * @category Guards
  */
-export class SystemInstruction extends Context.Tag("@effect/ai/AiInput/SystemInstruction")<
-  SystemInstruction,
-  string
->() {}
+export const isPart = (u: unknown): u is UserMessagePart | AssistantMessagePart | ToolMessagePart =>
+  Predicate.hasProperty(u, PartTypeId)
 
 /**
  * @since 1.0.0
- * @category system
+ * @category Constructors
  */
-export const provideSystem: {
+export const empty: AiInput = new AiInput({ messages: [] })
+
+/**
+ * Constructs a new `AiInput` from raw user input.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = (input: Raw): AiInput => {
+  if (Predicate.isString(input)) {
+    const textPart = new TextPart({ text: input })
+    const message = new UserMessage({ parts: [textPart] })
+    return new AiInput({ messages: [message] })
+  }
+  if (isMessage(input)) {
+    return new AiInput({ messages: [input] })
+  }
+  if (Predicate.isIterable(input)) {
+    return new AiInput({ messages: Array.from(input) })
+  }
+  if (is(input)) {
+    return input
+  }
+  if (AiResponse.isStructured(input)) {
+    const assistantMessages = fromResponse(input).messages
+    const toolPart = new ToolCallResultPart({
+      id: input.id,
+      result: input.value
+    })
+    const toolMessage = new ToolMessage({ parts: [toolPart] })
+    return new AiInput({ messages: [...assistantMessages, toolMessage] })
+  }
+  if (AiResponse.hasToolCallResults(input)) {
+    const assistantMessages = fromResponse(input).messages
+    const toolParts: Array<ToolCallResultPart> = []
+    for (const [id, result] of input.encodedResults) {
+      toolParts.push(new ToolCallResultPart({ id, result }))
+    }
+    const toolMessage = new ToolMessage({ parts: toolParts })
+    return new AiInput({ messages: [...assistantMessages, toolMessage] })
+  }
+  return fromResponse(input)
+}
+
+const EXCLUDED_RESPONSE_PARTS: Array<AiResponse.Part["_tag"]> = [
+  "MetadataPart",
+  "ReasoningPart",
+  "RedactedReasoningPart",
+  "FinishPart"
+]
+
+const validResponseParts = (part: AiResponse.Part): part is AiResponse.TextPart | AiResponse.ToolCallPart =>
+  !EXCLUDED_RESPONSE_PARTS.includes(part._tag)
+
+const fromResponse = (
+  response: AiResponse.AiResponse
+): AiInput => {
+  if (response.parts.length === 0) {
+    return empty
+  }
+  const parts = response.parts
+    .filter(validResponseParts)
+    .map((part) =>
+      part._tag === "TextPart"
+        ? new TextPart({ text: part.text })
+        : new ToolCallPart({
+          id: part.id,
+          name: part.name,
+          params: part.params
+        })
+    )
+  const message = new AssistantMessage({ parts })
+  return new AiInput({ messages: [message] })
+}
+
+/**
+ * Concatenates the messages of one `AiInput` onto the messages of another,
+ * creating a new `AiInput` with the messages from both.
+ *
+ * @since 1.0.0
+ * @category Combination
+ */
+export const concat: {
   /**
+   * Concatenates the messages of one `AiInput` onto the messages of another,
+   * creating a new `AiInput` with the messages from both.
+   *
    * @since 1.0.0
-   * @category system
+   * @category Combination
    */
-  (input: string): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, SystemInstruction>>
+  (other: AiInput): (self: AiInput) => AiInput
   /**
+   * Concatenates the messages of one `AiInput` onto the messages of another,
+   * creating a new `AiInput` with the messages from both.
+   *
    * @since 1.0.0
-   * @category system
+   * @category Combination
    */
-  <A, E, R>(effect: Effect.Effect<A, E, R>, input: string): Effect.Effect<A, E, Exclude<R, SystemInstruction>>
-} = dual(
-  2,
-  <A, E, R>(effect: Effect.Effect<A, E, R>, input: string): Effect.Effect<A, E, Exclude<R, SystemInstruction>> =>
-    Effect.provideService(effect, SystemInstruction, input)
-)
+  (self: AiInput, other: AiInput): AiInput
+} = dual<
+  /**
+   * Concatenates the messages of one `AiInput` onto the messages of another,
+   * creating a new `AiInput` with the messages from both.
+   *
+   * @since 1.0.0
+   * @category Combination
+   */
+  (other: AiInput) => (self: AiInput) => AiInput,
+  /**
+   * Concatenates the messages of one `AiInput` onto the messages of another,
+   * creating a new `AiInput` with the messages from both.
+   *
+   * @since 1.0.0
+   * @category Combination
+   */
+  (self: AiInput, other: AiInput) => AiInput
+>(2, (self, other) =>
+  AiInput.make({
+    messages: [...self.messages, ...other.messages]
+  }))