Skip to main content Link Search Menu Expand Document (external link)
effect

Response.ts overview

The Response module provides data structures to represent responses from large language models.

This module defines the complete structure of AI model responses, including various content parts for text, reasoning, tool calls, files, and metadata, supporting both streaming and non-streaming responses.

Example

import { Response } from "@effect/ai"

// Create a simple text response part
const textResponse = Response.makePart("text", {
  text: "The weather is sunny today!"
})

// Create a tool call response part
const toolCallResponse = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco" },
  providerExecuted: false
})

Since v1.0.0

Exports Grouped by Category

Constructors

makePart

Creates a new response content part of the specified type.

Example

import { Response } from "@effect/ai"

const textPart = Response.makePart("text", {
  text: "Hello, world!"
})

const toolCallPart = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco" },
  providerExecuted: false
})

Signature

declare const makePart: <const Type extends AnyPart["type"]>(
  type: Type,
  params: Omit<Extract<AnyPart, { type: Type }>, PartTypeId | "type" | "metadata"> & {
    readonly metadata?: Extract<AnyPart, { type: Type }>["metadata"] | undefined
  }
) => Extract<AnyPart, { type: Type }>

Source

Since v1.0.0

Guards

isPart

Type guard to check if a value is a Response Part.

Signature

declare const isPart: (u: unknown) => u is AnyPart

Source

Since v1.0.0

Models

AllParts (type alias)

Union type for all response parts with tool-specific typing.

Signature

type AllParts<Tools> =
  | TextPart
  | TextStartPart
  | TextDeltaPart
  | TextEndPart
  | ReasoningPart
  | ReasoningStartPart
  | ReasoningDeltaPart
  | ReasoningEndPart
  | ToolParamsStartPart
  | ToolParamsDeltaPart
  | ToolParamsEndPart
  | ToolCallParts<Tools>
  | ToolResultParts<Tools>
  | FilePart
  | DocumentSourcePart
  | UrlSourcePart
  | ResponseMetadataPart
  | FinishPart
  | ErrorPart

Source

Since v1.0.0

AllPartsEncoded (type alias)

Encoded representation of all response parts for serialization.

Signature

type AllPartsEncoded =
  | TextPartEncoded
  | TextStartPartEncoded
  | TextDeltaPartEncoded
  | TextEndPartEncoded
  | ReasoningPartEncoded
  | ReasoningStartPartEncoded
  | ReasoningDeltaPartEncoded
  | ReasoningEndPartEncoded
  | ToolParamsStartPartEncoded
  | ToolParamsDeltaPartEncoded
  | ToolParamsEndPartEncoded
  | ToolCallPartEncoded
  | ToolResultPartEncoded
  | FilePartEncoded
  | DocumentSourcePartEncoded
  | UrlSourcePartEncoded
  | ResponseMetadataPartEncoded
  | FinishPartEncoded
  | ErrorPartEncoded

Source

Since v1.0.0

AnyPart (type alias)

Union type representing all possible response content parts.

Signature

type AnyPart =
  | TextPart
  | TextStartPart
  | TextDeltaPart
  | TextEndPart
  | ReasoningPart
  | ReasoningStartPart
  | ReasoningDeltaPart
  | ReasoningEndPart
  | ToolParamsStartPart
  | ToolParamsDeltaPart
  | ToolParamsEndPart
  | ToolCallPart<any, any>
  | ToolResultPart<any, any>
  | FilePart
  | DocumentSourcePart
  | UrlSourcePart
  | ResponseMetadataPart
  | FinishPart
  | ErrorPart

Source

Since v1.0.0

AnyPartEncoded (type alias)

Encoded representation of all possible response content parts for serialization.

Signature

type AnyPartEncoded =
  | TextPartEncoded
  | TextStartPartEncoded
  | TextDeltaPartEncoded
  | TextEndPartEncoded
  | ReasoningPartEncoded
  | ReasoningStartPartEncoded
  | ReasoningDeltaPartEncoded
  | ReasoningEndPartEncoded
  | ToolParamsStartPartEncoded
  | ToolParamsDeltaPartEncoded
  | ToolParamsEndPartEncoded
  | ToolCallPartEncoded
  | ToolResultPartEncoded
  | FilePartEncoded
  | DocumentSourcePartEncoded
  | UrlSourcePartEncoded
  | ResponseMetadataPartEncoded
  | FinishPartEncoded
  | ErrorPartEncoded

Source

Since v1.0.0

BasePart (interface)

Base interface for all response content parts.

Provides common structure including type identifier and optional metadata.

Signature

export interface BasePart<Type extends string, Metadata extends ProviderMetadata> {
  readonly [PartTypeId]: PartTypeId
  /**
   * The type of this response part.
   */
  readonly type: Type
  /**
   * Optional provider-specific metadata for this part.
   */
  readonly metadata: Metadata
}

Source

Since v1.0.0

BasePartEncoded (interface)

Base interface for encoded response content parts.

Signature

export interface BasePartEncoded<Type extends string, Metadata extends ProviderMetadata> {
  /**
   * The type of this response part.
   */
  readonly type: Type
  /**
   * Optional provider-specific metadata for this part.
   */
  readonly metadata?: Metadata | undefined
}

Source

Since v1.0.0

DocumentSourcePart (interface)

Response part representing a document source reference.

Used to reference documents that were used in generating the response.

Signature

export interface DocumentSourcePart extends BasePart<"source", DocumentSourcePartMetadata> {
  /**
   * Type discriminator for document sources.
   */
  readonly sourceType: "document"
  /**
   * Unique identifier for the document.
   */
  readonly id: string
  /**
   * MIME type of the document.
   */
  readonly mediaType: string
  /**
   * Display title of the document.
   */
  readonly title: string
  /**
   * Optional filename of the document.
   */
  readonly fileName?: string
}

Source

Since v1.0.0

DocumentSourcePartEncoded (interface)

Encoded representation of document source parts for serialization.

Signature

export interface DocumentSourcePartEncoded extends BasePartEncoded<"source", DocumentSourcePartMetadata> {
  /**
   * Type discriminator for document sources.
   */
  readonly sourceType: "document"
  /**
   * Unique identifier for the document.
   */
  readonly id: string
  /**
   * MIME type of the document.
   */
  readonly mediaType: string
  /**
   * Display title of the document.
   */
  readonly title: string
  /**
   * Optional filename of the document.
   */
  readonly fileName?: string
}

Source

Since v1.0.0

ErrorPart (interface)

Response part indicating that an error occurred generating the response.

Example

import { Response } from "@effect/ai"

const errorPart: Response.ErrorPart = Response.makePart("error", {
  error: new Error("boom")
})

Signature

export interface ErrorPart extends BasePart<"error", ErrorPartMetadata> {
  readonly error: unknown
}

Source

Since v1.0.0

ErrorPartEncoded (interface)

Encoded representation of error parts for serialization.

Signature

export interface ErrorPartEncoded extends BasePartEncoded<"error", ErrorPartMetadata> {
  readonly error: unknown
}

Source

Since v1.0.0

FilePart (interface)

Response part representing a file attachment.

Supports various file types including images, documents, and binary data.

Example

import { Response } from "@effect/ai"

const imagePart: Response.FilePart = Response.makePart("file", {
  mediaType: "image/jpeg",
  data: new Uint8Array([1, 2, 3])
})

Signature

export interface FilePart extends BasePart<"file", FilePartMetadata> {
  /**
   * MIME type of the file (e.g., "image/jpeg", "application/pdf").
   */
  readonly mediaType: string
  /**
   * File data as a byte array.
   */
  readonly data: Uint8Array
}

Source

Since v1.0.0

FilePartEncoded (interface)

Encoded representation of file parts for serialization.

Signature

export interface FilePartEncoded extends BasePartEncoded<"file", FilePartMetadata> {
  /**
   * MIME type of the file (e.g., "image/jpeg", "application/pdf").
   */
  readonly mediaType: string
  /**
   * File data as a base64 string.
   */
  readonly data: string
}

Source

Since v1.0.0

FinishPart (interface)

Response part indicating the completion of a response generation.

Example

import { Response } from "@effect/ai"

const finishPart: Response.FinishPart = Response.makePart("finish", {
  reason: "stop",
  usage: {
    inputTokens: 50,
    outputTokens: 25,
    totalTokens: 75
  }
})

Signature

export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
  /**
   * The reason why the model finished generating the response.
   */
  readonly reason: FinishReason
  /**
   * Token usage statistics for the request.
   */
  readonly usage: Usage
}

Source

Since v1.0.0

FinishPartEncoded (interface)

Encoded representation of finish parts for serialization.

Signature

export interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartMetadata> {
  /**
   * The reason why the model finished generating the response.
   */
  readonly reason: typeof FinishReason.Encoded
  /**
   * Token usage statistics for the request.
   */
  readonly usage: typeof Usage.Encoded
}

Source

Since v1.0.0

FinishReason

Represents the reason why a model finished generation of a response.

Possible finish reasons:

  • "stop": The model generated a stop sequence.
  • "length": The model exceeded its token budget.
  • "content-filter": The model generated content which violated a content filter.
  • "tool-calls": The model triggered a tool call.
  • "error": The model encountered an error.
  • "pause": The model requested to pause execution.
  • "other": The model stopped for a reason not supported by this protocol.
  • "unknown": The model did not specify a finish reason.

Signature

declare const FinishReason: Schema.Literal<
  ["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"]
>

Source

Since v1.0.0

FinishReason (type alias)

Signature

type FinishReason = typeof FinishReason.Type

Source

Since v1.0.0

Part (type alias)

A type for representing non-streaming response parts with tool-specific typing.

Signature

type Part<Tools> =
  | TextPart
  | ReasoningPart
  | ToolCallParts<Tools>
  | ToolResultParts<Tools>
  | FilePart
  | DocumentSourcePart
  | UrlSourcePart
  | ResponseMetadataPart
  | FinishPart

Source

Since v1.0.0

PartEncoded (type alias)

Encoded representation of non-streaming response parts for serialization.

Signature

type PartEncoded =
  | TextPartEncoded
  | ReasoningPartEncoded
  | ReasoningDeltaPartEncoded
  | ReasoningEndPartEncoded
  | ToolCallPartEncoded
  | ToolResultPartEncoded
  | FilePartEncoded
  | DocumentSourcePartEncoded
  | UrlSourcePartEncoded
  | ResponseMetadataPartEncoded
  | FinishPartEncoded

Source

Since v1.0.0

ProviderMetadata (type alias)

Signature

type ProviderMetadata = typeof ProviderMetadata.Type

Source

Since v1.0.0

ReasoningDeltaPart (interface)

Response part containing incremental reasoning content to be added to the existing chunk of reasoning text with the same unique identifier.

Signature

export interface ReasoningDeltaPart extends BasePart<"reasoning-delta", ReasoningDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding reasoning chunk.
   */
  readonly id: string
  /**
   * The incremental reasoning content to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

ReasoningDeltaPartEncoded (interface)

Encoded representation of reasoning delta parts for serialization.

Signature

export interface ReasoningDeltaPartEncoded extends BasePartEncoded<"reasoning-delta", ReasoningDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding reasoning chunk.
   */
  readonly id: string
  /**
   * The incremental reasoning content to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

ReasoningEndPart (interface)

Response part indicating the end of streaming reasoning content.

Marks the completion of a chunk of reasoning content.

Signature

export interface ReasoningEndPart extends BasePart<"reasoning-end", ReasoningEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding reasoning chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

ReasoningEndPartEncoded (interface)

Encoded representation of reasoning end parts for serialization.

Signature

export interface ReasoningEndPartEncoded extends BasePartEncoded<"reasoning-end", ReasoningEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding reasoning chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

ReasoningPart (interface)

Response part representing reasoning or chain-of-thought content.

Contains the internal reasoning process or explanation from the large language model.

Example

import { Response } from "@effect/ai"

const reasoningPart: Response.ReasoningPart = Response.makePart("reasoning", {
  text: "Let me think step by step: First I need to analyze the user's question..."
})

Signature

export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartMetadata> {
  /**
   * The reasoning or thought process text.
   */
  readonly text: string
}

Source

Since v1.0.0

ReasoningPartEncoded (interface)

Encoded representation of reasoning parts for serialization.

Signature

export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", ReasoningPartMetadata> {
  /**
   * The reasoning or thought process text.
   */
  readonly text: string
}

Source

Since v1.0.0

ReasoningStartPart (interface)

Response part indicating the start of streaming reasoning content.

Marks the beginning of a reasoning chunk with a unique identifier.

Signature

export interface ReasoningStartPart extends BasePart<"reasoning-start", ReasoningStartPartMetadata> {
  /**
   * Unique identifier for this reasoning chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

ReasoningStartPartEncoded (interface)

Encoded representation of reasoning start parts for serialization.

Signature

export interface ReasoningStartPartEncoded extends BasePartEncoded<"reasoning-start", ReasoningStartPartMetadata> {
  /**
   * Unique identifier for this reasoning stream.
   */
  readonly id: string
}

Source

Since v1.0.0

ResponseMetadataPart (interface)

Response part containing metadata about the large language model response.

Example

import { Response } from "@effect/ai"
import { Option, DateTime } from "effect"

const metadataPart: Response.ResponseMetadataPart = Response.makePart("response-metadata", {
  id: Option.some("resp_123"),
  modelId: Option.some("gpt-4"),
  timestamp: Option.some(DateTime.unsafeNow())
})

Signature

export interface ResponseMetadataPart extends BasePart<"response-metadata", ResponseMetadataPartMetadata> {
  /**
   * Optional unique identifier for this specific response.
   */
  readonly id: Option.Option<string>
  /**
   * Optional identifier of the AI model that generated the response.
   */
  readonly modelId: Option.Option<string>
  /**
   * Optional timestamp when the response was generated.
   */
  readonly timestamp: Option.Option<DateTime.Utc>
}

Source

Since v1.0.0

ResponseMetadataPartEncoded (interface)

Encoded representation of response metadata parts for serialization.

Signature

export interface ResponseMetadataPartEncoded
  extends BasePartEncoded<"response-metadata", ResponseMetadataPartMetadata> {
  /**
   * Optional unique identifier for this specific response.
   */
  readonly id?: string | undefined
  /**
   * Optional identifier of the AI model that generated the response.
   */
  readonly modelId?: string | undefined
  /**
   * Optional timestamp when the response was generated.
   */
  readonly timestamp?: string | undefined
}

Source

Since v1.0.0

StreamPart (type alias)

A type for representing streaming response parts with tool-specific typing.

Signature

type StreamPart<Tools> =
  | TextStartPart
  | TextDeltaPart
  | TextEndPart
  | ReasoningStartPart
  | ReasoningDeltaPart
  | ReasoningEndPart
  | ToolParamsStartPart
  | ToolParamsDeltaPart
  | ToolParamsEndPart
  | ToolCallParts<Tools>
  | ToolResultParts<Tools>
  | FilePart
  | DocumentSourcePart
  | UrlSourcePart
  | ResponseMetadataPart
  | FinishPart
  | ErrorPart

Source

Since v1.0.0

StreamPartEncoded (type alias)

Encoded representation of streaming response parts for serialization.

Signature

type StreamPartEncoded =
  | TextStartPartEncoded
  | TextDeltaPartEncoded
  | TextEndPartEncoded
  | ReasoningStartPartEncoded
  | ReasoningDeltaPartEncoded
  | ReasoningEndPartEncoded
  | ToolParamsStartPartEncoded
  | ToolParamsDeltaPartEncoded
  | ToolParamsEndPartEncoded
  | ToolCallPartEncoded
  | ToolResultPartEncoded
  | FilePartEncoded
  | DocumentSourcePartEncoded
  | UrlSourcePartEncoded
  | ResponseMetadataPartEncoded
  | FinishPartEncoded
  | ErrorPartEncoded

Source

Since v1.0.0

TextDeltaPart (interface)

Response part containing incremental text content to be added to the existing text chunk with the same unique identifier.

Signature

export interface TextDeltaPart extends BasePart<"text-delta", TextDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding text chunk.
   */
  readonly id: string
  /**
   * The incremental text content to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

TextDeltaPartEncoded (interface)

Encoded representation of text delta parts for serialization.

Signature

export interface TextDeltaPartEncoded extends BasePartEncoded<"text-delta", TextDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding text chunk.
   */
  readonly id: string
  /**
   * The incremental text content to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

TextEndPart (interface)

Response part indicating the end of streaming text content.

Marks the completion of a text chunk.

Signature

export interface TextEndPart extends BasePart<"text-end", TextEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding text chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

TextEndPartEncoded (interface)

Encoded representation of text end parts for serialization.

Signature

export interface TextEndPartEncoded extends BasePartEncoded<"text-end", TextEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding text chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

TextPart (interface)

Response part representing plain text content.

Example

import { Response } from "@effect/ai"

const textPart: Response.TextPart = Response.makePart("text", {
  text: "The answer to your question is 42."
})

Signature

export interface TextPart extends BasePart<"text", TextPartMetadata> {
  /**
   * The text content.
   */
  readonly text: string
}

Source

Since v1.0.0

TextPartEncoded (interface)

Encoded representation of text parts for serialization.

Signature

export interface TextPartEncoded extends BasePartEncoded<"text", TextPartMetadata> {
  /**
   * The text content.
   */
  readonly text: string
}

Source

Since v1.0.0

TextStartPart (interface)

Response part indicating the start of streaming text content.

Marks the beginning of a text chunk with a unique identifier.

Signature

export interface TextStartPart extends BasePart<"text-start", TextStartPartMetadata> {
  /**
   * Unique identifier for this text chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

TextStartPartEncoded (interface)

Encoded representation of text start parts for serialization.

Signature

export interface TextStartPartEncoded extends BasePartEncoded<"text-start", TextStartPartMetadata> {
  /**
   * Unique identifier for this text chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

ToolCallPart (interface)

Response part representing a tool call request.

Example

import { Response } from "@effect/ai"
import { Schema } from "effect"

const weatherParams = Schema.Struct({
  city: Schema.String,
  units: Schema.optional(Schema.Literal("celsius", "fahrenheit"))
})

const toolCallPart: Response.ToolCallPart<"get_weather", typeof weatherParams.fields> = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco", units: "celsius" },
  providerExecuted: false
})

Signature

export interface ToolCallPart<Name extends string, Params extends Schema.Struct.Fields>
  extends BasePart<"tool-call", ToolCallPartMetadata> {
  /**
   * Unique identifier for this 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
  /**
   * Parameters to pass to the tool.
   */
  readonly params: Schema.Struct.Type<Params>
  /**
   * 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
}

Source

Since v1.0.0

ToolCallPartEncoded (interface)

Encoded representation of tool call parts for serialization.

Signature

export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCallPartMetadata> {
  /**
   * Unique identifier for this 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: string
  /**
   * Parameters to pass to the tool.
   */
  readonly params: 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 | undefined
}

Source

Since v1.0.0

ToolParamsDeltaPart (interface)

Response part containing incremental tool parameter content.

Represents a chunk of tool parameters being streamed, containing the incremental JSON content that forms the tool parameters.

Signature

export interface ToolParamsDeltaPart extends BasePart<"tool-params-delta", ToolParamsDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding tool parameter chunk.
   */
  readonly id: string
  /**
   * The incremental parameter content (typically JSON fragment) to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

ToolParamsDeltaPartEncoded (interface)

Encoded representation of tool params delta parts for serialization.

Signature

export interface ToolParamsDeltaPartEncoded extends BasePartEncoded<"tool-params-delta", ToolParamsDeltaPartMetadata> {
  /**
   * Unique identifier matching the corresponding tool parameter chunk.
   */
  readonly id: string
  /**
   * The incremental parameter content (typically JSON fragment) to add.
   */
  readonly delta: string
}

Source

Since v1.0.0

ToolParamsEndPart (interface)

Response part indicating the end of streaming tool parameters.

Marks the completion of a tool parameter stream, indicating that all parameter data has been sent and the tool call is ready to be executed.

Signature

export interface ToolParamsEndPart extends BasePart<"tool-params-end", ToolParamsEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding tool parameter chunk.
   */
  readonly id: string
}

Source

Since v1.0.0

ToolParamsEndPartEncoded (interface)

Encoded representation of tool params end parts for serialization.

Signature

export interface ToolParamsEndPartEncoded extends BasePartEncoded<"tool-params-end", ToolParamsEndPartMetadata> {
  /**
   * Unique identifier matching the corresponding tool parameter stream.
   */
  readonly id: string
}

Source

Since v1.0.0

ToolParamsStartPart (interface)

Response part indicating the start of streaming tool parameters.

Marks the beginning of tool parameter streaming with metadata about the tool call.

Signature

export interface ToolParamsStartPart extends BasePart<"tool-params-start", ToolParamsStartPartMetadata> {
  /**
   * Unique identifier for this tool parameter chunk.
   */
  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: string
  /**
   * 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
}

Source

Since v1.0.0

ToolParamsStartPartEncoded (interface)

Encoded representation of tool params start parts for serialization.

Signature

export interface ToolParamsStartPartEncoded extends BasePartEncoded<"tool-params-start", ToolParamsStartPartMetadata> {
  /**
   * Unique identifier for this tool parameter chunk.
   */
  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: string
  /**
   * 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
}

Source

Since v1.0.0

ToolResultPart (interface)

Response part representing the result of a tool call.

Example

import { Response } from "@effect/ai"

interface WeatherData {
  temperature: number
  condition: string
  humidity: number
}

const toolResultPart: Response.ToolResultPart<"get_weather", WeatherData> = Response.makePart("tool-result", {
  id: "call_123",
  name: "get_weather",
  result: {
    temperature: 22,
    condition: "sunny",
    humidity: 65
  },
  encodedResult: {
    temperature: 22,
    condition: "sunny",
    humidity: 65
  },
  providerExecuted: false
})

Signature

export interface ToolResultPart<Name extends string, Result> 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: Result
  /**
   * 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
}

Source

Since v1.0.0

ToolResultPartEncoded (interface)

Encoded representation of tool result parts for serialization.

Signature

export interface ToolResultPartEncoded extends BasePartEncoded<"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: string
  /**
   * The result returned by the tool execution.
   */
  readonly result: 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 | undefined
}

Source

Since v1.0.0

UrlSourcePart (interface)

Response part representing a URL source reference.

Used to reference web URLs that were used in generating the response.

Signature

export interface UrlSourcePart extends BasePart<"source", UrlSourcePartMetadata> {
  /**
   * Type discriminator for URL sources.
   */
  readonly sourceType: "url"
  /**
   * Unique identifier for the URL.
   */
  readonly id: string
  /**
   * The URL that was referenced.
   */
  readonly url: URL
  /**
   * Display title of the URL content.
   */
  readonly title: string
}

Source

Since v1.0.0

UrlSourcePartEncoded (interface)

Encoded representation of URL source parts for serialization.

Signature

export interface UrlSourcePartEncoded extends BasePartEncoded<"source", UrlSourcePartMetadata> {
  /**
   * Type discriminator for URL sources.
   */
  readonly sourceType: "url"
  /**
   * Unique identifier for the URL.
   */
  readonly id: string
  /**
   * The URL that was referenced as a string.
   */
  readonly url: string
  /**
   * Display title of the URL content.
   */
  readonly title: string
}

Source

Since v1.0.0

Usage (class)

Represents usage information for a request to a large language model provider.

If the model provider returns additional usage information than what is specified here, you can generally find that information under the provider metadata of the finish part of the response.

Signature

declare class Usage

Source

Since v1.0.0

ProviderOptions

DocumentSourcePartMetadata (interface)

Represents provider-specific metadata that can be associated with a DocumentSourcePart through module augmentation.

Signature

export interface DocumentSourcePartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ErrorPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ErrorPart through module augmentation.

Signature

export interface ErrorPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

FilePartMetadata (interface)

Represents provider-specific metadata that can be associated with a FilePart through module augmentation.

Signature

export interface FilePartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

FinishPartMetadata (interface)

Represents provider-specific metadata that can be associated with a FinishPart through module augmentation.

Signature

export interface FinishPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ReasoningDeltaPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ReasoningDeltaPart through module augmentation.

Signature

export interface ReasoningDeltaPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ReasoningEndPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ReasoningEndPart through module augmentation.

Signature

export interface ReasoningEndPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ReasoningPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ReasoningPart through module augmentation.

Signature

export interface ReasoningPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ReasoningStartPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ReasoningStartPart through module augmentation.

Signature

export interface ReasoningStartPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ResponseMetadataPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ResponseMetadataPart through module augmentation.

Signature

export interface ResponseMetadataPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

TextDeltaPartMetadata (interface)

Represents provider-specific metadata that can be associated with a TextDeltaPart through module augmentation.

Signature

export interface TextDeltaPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

TextEndPartMetadata (interface)

Represents provider-specific metadata that can be associated with a TextEndPart through module augmentation.

Signature

export interface TextEndPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

TextPartMetadata (interface)

Represents provider-specific metadata that can be associated with a TextPart through module augmentation.

Signature

export interface TextPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

TextStartPartMetadata (interface)

Represents provider-specific metadata that can be associated with a TextStartPart through module augmentation.

Signature

export interface TextStartPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ToolCallPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ToolCallPart through module augmentation.

Signature

export interface ToolCallPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ToolParamsDeltaPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ToolParamsDeltaPart through module augmentation.

Signature

export interface ToolParamsDeltaPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ToolParamsEndPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ToolParamsEndPart through module augmentation.

Signature

export interface ToolParamsEndPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ToolParamsStartPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ToolParamsStartPart through module augmentation.

Signature

export interface ToolParamsStartPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

ToolResultPartMetadata (interface)

Represents provider-specific metadata that can be associated with a ToolResultPart through module augmentation.

Signature

export interface ToolResultPartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

UrlSourcePartMetadata (interface)

Represents provider-specific metadata that can be associated with a UrlSourcePart through module augmentation.

Signature

export interface UrlSourcePartMetadata extends ProviderMetadata {}

Source

Since v1.0.0

Schemas

AllParts

Creates a Schema for all response parts based on a toolkit.

Generates a schema that includes all possible response parts, with tool call and tool result parts dynamically created based on the provided toolkit.

Example

import { Response, Tool, Toolkit } from "@effect/ai"
import { Schema } from "effect"

const myToolkit = Toolkit.make(
  Tool.make("GetWeather", {
    parameters: { city: Schema.String },
    success: Schema.Struct({ temperature: Schema.Number })
  })
)

const allPartsSchema = Response.AllParts(myToolkit)

Signature

declare const AllParts: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
  toolkit: T
) => Schema.Schema<AllParts<Toolkit.Tools<T>>, AllPartsEncoded>

Source

Since v1.0.0

DocumentSourcePart

Schema for validation and encoding of document source parts.

Signature

declare const DocumentSourcePart: Schema.Schema<DocumentSourcePart, DocumentSourcePartEncoded, never>

Source

Since v1.0.0

ErrorPart

Schema for validation and encoding of error parts.

Signature

declare const ErrorPart: Schema.Schema<ErrorPart, ErrorPartEncoded, never>

Source

Since v1.0.0

FilePart

Schema for validation and encoding of file parts.

Signature

declare const FilePart: Schema.Schema<FilePart, FilePartEncoded, never>

Source

Since v1.0.0

FinishPart

Schema for validation and encoding of finish parts.

Signature

declare const FinishPart: Schema.Schema<FinishPart, FinishPartEncoded, never>

Source

Since v1.0.0

Part

Creates a Schema for non-streaming response parts based on a toolkit.

Signature

declare const Part: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
  toolkit: T
) => Schema.Schema<Part<Toolkit.Tools<T>>, PartEncoded>

Source

Since v1.0.0

ProviderMetadata

Schema for provider-specific metadata which can be attached to response parts.

Provider-specific metadata is namespaced by provider and has the structure:

{
  "<provider-specific-key>": {
    // Provider-specific metadata
  }
}

Signature

declare const ProviderMetadata: Schema.Record$<
  typeof Schema.String,
  Schema.UndefinedOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>
>

Source

Since v1.0.0

ReasoningDeltaPart

Schema for validation and encoding of reasoning delta parts.

Signature

declare const ReasoningDeltaPart: Schema.Schema<ReasoningDeltaPart, ReasoningDeltaPartEncoded, never>

Source

Since v1.0.0

ReasoningEndPart

Schema for validation and encoding of reasoning end parts.

Signature

declare const ReasoningEndPart: Schema.Schema<ReasoningEndPart, ReasoningEndPartEncoded, never>

Source

Since v1.0.0

ReasoningPart

Schema for validation and encoding of reasoning parts.

Signature

declare const ReasoningPart: Schema.Schema<ReasoningPart, ReasoningPartEncoded, never>

Source

Since v1.0.0

ReasoningStartPart

Schema for validation and encoding of reasoning start parts.

Signature

declare const ReasoningStartPart: Schema.Schema<ReasoningStartPart, ReasoningStartPartEncoded, never>

Source

Since v1.0.0

ResponseMetadataPart

Schema for validation and encoding of response metadata parts.

Signature

declare const ResponseMetadataPart: Schema.Schema<ResponseMetadataPart, ResponseMetadataPartEncoded, never>

Source

Since v1.0.0

StreamPart

Creates a Schema for streaming response parts based on a toolkit.

Signature

declare const StreamPart: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
  toolkit: T
) => Schema.Schema<StreamPart<Toolkit.Tools<T>>, StreamPartEncoded>

Source

Since v1.0.0

TextDeltaPart

Schema for validation and encoding of text delta parts.

Signature

declare const TextDeltaPart: Schema.Schema<TextDeltaPart, TextDeltaPartEncoded, never>

Source

Since v1.0.0

TextEndPart

Schema for validation and encoding of text end parts.

Signature

declare const TextEndPart: Schema.Schema<TextEndPart, TextEndPartEncoded, never>

Source

Since v1.0.0

TextPart

Schema for validation and encoding of text parts.

Signature

declare const TextPart: Schema.Schema<TextPart, TextPartEncoded, never>

Source

Since v1.0.0

TextStartPart

Schema for validation and encoding of text start parts.

Signature

declare const TextStartPart: Schema.Schema<TextStartPart, TextStartPartEncoded, never>

Source

Since v1.0.0

ToolCallPart

Creates a Schema for tool call parts with specific tool name and parameters.

Signature

declare const ToolCallPart: <const Name extends string, Params extends Schema.Struct.Fields>(
  name: Name,
  params: Schema.Struct<Params>
) => Schema.Schema<ToolCallPart<Name, Params>, ToolCallPartEncoded>

Source

Since v1.0.0

ToolParamsDeltaPart

Schema for validation and encoding of tool params delta parts.

Signature

declare const ToolParamsDeltaPart: Schema.Schema<ToolParamsDeltaPart, ToolParamsDeltaPartEncoded, never>

Source

Since v1.0.0

ToolParamsEndPart

Schema for validation and encoding of tool params end parts.

Signature

declare const ToolParamsEndPart: Schema.Schema<ToolParamsEndPart, ToolParamsEndPartEncoded, never>

Source

Since v1.0.0

ToolParamsStartPart

Schema for validation and encoding of tool params start parts.

Signature

declare const ToolParamsStartPart: Schema.Schema<ToolParamsStartPart, ToolParamsStartPartEncoded, never>

Source

Since v1.0.0

ToolResultPart

Creates a Schema for tool result parts with specific tool name and result type.

Signature

declare const ToolResultPart: <const Name extends string, Result extends Schema.Schema.Any>(
  name: Name,
  result: Result
) => Schema.Schema<ToolResultPart<Name, Schema.Schema.Type<Result>>, ToolResultPartEncoded>

Source

Since v1.0.0

UrlSourcePart

Schema for validation and encoding of url source parts.

Signature

declare const UrlSourcePart: Schema.Schema<UrlSourcePart, UrlSourcePartEncoded, never>

Source

Since v1.0.0

Type Ids

PartTypeId

Unique identifier for Response Part instances.

Signature

declare const PartTypeId: "~effect/ai/Content/Part"

Source

Since v1.0.0

PartTypeId (type alias)

Type-level representation of the Response Part identifier.

Signature

type PartTypeId = typeof PartTypeId

Source

Since v1.0.0

Utility Types

ToolCallParts (type alias)

Utility type that extracts tool call parts from a set of tools.

Signature

type ToolCallParts<Tools> = {
  [Name in keyof Tools]: Name extends string ? ToolCallPart<Name, Tool.ParametersSchema<Tools[Name]>["fields"]> : never
}[keyof Tools]

Source

Since v1.0.0

ToolResultParts (type alias)

Utility type that extracts tool result parts from a set of tools.

Signature

type ToolResultParts<Tools> = {
  [Name in keyof Tools]: Name extends string ? ToolResultPart<Name, Tool.Success<Tools[Name]>> : never
}[keyof Tools]

Source

Since v1.0.0