effect 4.0.0-beta.102 → 4.0.0-beta.104

package/dist/unstable/ai/Prompt.d.ts

@@ -93,7 +93,7 @@ export interface BasePartEncoded<Type extends string, Options extends ProviderOp
  *
  * **Example** (Creating content parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const textPart = Prompt.makePart("text", {
@@ -105,6 +105,8 @@ export interface BasePartEncoded<Type extends string, Options extends ProviderOp
  *   fileName: "screenshot.png",
  *   data: new Uint8Array([1, 2, 3])
  * })
+ *
+ * const result = [textPart.type, filePart.type] // => ["text", "file"]
  * ```
  *
  * @category constructors
@@ -153,12 +155,13 @@ export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId |
  *
  * **Example** (Creating text parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const textPart: Prompt.TextPart = Prompt.makePart("text", {
  *   text: "Hello, how can I help you today?"
  * })
+ * textPart.text // => "Hello, how can I help you today?"
  * ```
  *
  * @category models
@@ -216,13 +219,14 @@ export declare const textPart: (params: PartConstructorParams<TextPart>) => Text
  *
  * **Example** (Creating reasoning parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const reasoningPart: Prompt.ReasoningPart = Prompt.makePart("reasoning", {
  *   text:
  *     "Summary: the response compares the requested options by price and availability."
  * })
+ * reasoningPart.type // => "reasoning"
  * ```
  *
  * @category models
@@ -284,7 +288,7 @@ export declare const reasoningPart: (params: PartConstructorParams<ReasoningPart
  *
  * **Example** (Creating file parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const imagePart: Prompt.FilePart = Prompt.makePart("file", {
@@ -298,6 +302,8 @@ export declare const reasoningPart: (params: PartConstructorParams<ReasoningPart
  *   fileName: "report.pdf",
  *   data: new Uint8Array([1, 2, 3])
  * })
+ *
+ * const result = [imagePart.mediaType, documentPart.fileName] // => ["image/jpeg", "report.pdf"]
  * ```
  *
  * @category models
@@ -379,7 +385,7 @@ export declare const filePart: (params: PartConstructorParams<FilePart>) => File
  *
  * **Example** (Creating tool call parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const toolCallPart: Prompt.ToolCallPart = Prompt.makePart("tool-call", {
@@ -388,6 +394,7 @@ export declare const filePart: (params: PartConstructorParams<FilePart>) => File
  *   params: { city: "San Francisco", units: "celsius" },
  *   providerExecuted: false
  * })
+ * toolCallPart.name // => "get_weather"
  * ```
  *
  * @category models
@@ -471,7 +478,7 @@ export declare const toolCallPart: (params: PartConstructorParams<ToolCallPart>)
  *
  * **Example** (Creating tool result parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const toolResultPart: Prompt.ToolResultPart = Prompt.makePart("tool-result", {
@@ -482,8 +489,10 @@ export declare const toolCallPart: (params: PartConstructorParams<ToolCallPart>)
  *     temperature: 22,
  *     condition: "sunny",
  *     humidity: 65
- *   }
+ *   },
+ *   providerExecuted: false
  * })
+ * const result = [toolResultPart.name, toolResultPart.isFailure] // => ["get_weather", false]
  * ```
  *
  * @category models
@@ -506,6 +515,10 @@ export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOp
      * The result returned by the tool execution.
      */
     readonly result: unknown;
+    /**
+     * Whether the tool was executed by the provider (true) or framework (false).
+     */
+    readonly providerExecuted: boolean;
 }
 /**
  * Encoded representation of tool result parts for serialization.
@@ -530,6 +543,10 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
      * The result returned by the tool execution.
      */
     readonly result: unknown;
+    /**
+     * Whether the tool was executed by the provider (true) or framework (false).
+     */
+    readonly providerExecuted?: boolean | undefined;
 }
 /**
  * Represents provider-specific options that can be associated with a
@@ -552,6 +569,7 @@ export declare const ToolResultPart: Schema.Struct<{
     readonly name: Schema.String;
     readonly isFailure: Schema.Boolean;
     readonly result: Schema.Unknown;
+    readonly providerExecuted: Schema.withDecodingDefault<Schema.Boolean>;
     readonly "~effect/ai/Prompt/Part": Schema.withDecodingDefaultKey<Schema.Literal<"~effect/ai/Prompt/Part">>;
     readonly options: Schema.withDecodingDefault<Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.Json>>>>;
 }>;
@@ -572,7 +590,7 @@ export declare const toolResultPart: (params: PartConstructorParams<ToolResultPa
  *
  * **Example** (Creating tool approval responses)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const approvalResponse: Prompt.ToolApprovalResponsePart = Prompt.makePart(
@@ -591,6 +609,8 @@ export declare const toolResultPart: (params: PartConstructorParams<ToolResultPa
  *     reason: "Operation not allowed"
  *   }
  * )
+ *
+ * const result = [approvalResponse.approved, denialResponse.approved] // => [true, false]
  * ```
  *
  * @category models
@@ -671,7 +691,7 @@ export declare const toolApprovalResponsePart: (params: PartConstructorParams<To
  *
  * **Example** (Creating tool approval requests)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const approvalRequest: Prompt.ToolApprovalRequestPart = Prompt.makePart(
@@ -681,6 +701,7 @@ export declare const toolApprovalResponsePart: (params: PartConstructorParams<To
  *     toolCallId: "call_456"
  *   }
  * )
+ * const result = [approvalRequest.approvalId, approvalRequest.toolCallId] // => ["approval_123", "call_456"]
  * ```
  *
  * @category models
@@ -741,6 +762,21 @@ export declare const ToolApprovalRequestPart: Schema.Struct<{
  * @since 4.0.0
  */
 export declare const toolApprovalRequestPart: (params: PartConstructorParams<ToolApprovalRequestPart>) => ToolApprovalRequestPart;
+/**
+ * Schema for validation and encoding of content parts.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export declare const Part: Schema.Union<readonly [
+    typeof TextPart,
+    typeof ReasoningPart,
+    typeof FilePart,
+    typeof ToolCallPart,
+    typeof ToolResultPart,
+    typeof ToolApprovalResponsePart,
+    typeof ToolApprovalRequestPart
+]>;
 declare const MessageTypeId: "~effect/ai/Prompt/Message";
 /**
  * Type guard to check if a value is a Message.
@@ -792,7 +828,7 @@ export interface BaseMessageEncoded<Role extends string, Options extends Provide
  *
  * **Example** (Creating messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const textPart = Prompt.makePart("text", {
@@ -802,6 +838,7 @@ export interface BaseMessageEncoded<Role extends string, Options extends Provide
  * const userMessage = Prompt.makeMessage("user", {
  *   content: [textPart]
  * })
+ * const result = [userMessage.role, userMessage.content.length] // => ["user", 1]
  * ```
  *
  * @category constructors
@@ -847,13 +884,14 @@ export declare const ContentFromString: Schema.decodeTo<Schema.NonEmptyArray<Sch
  *
  * **Example** (Creating system messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const systemMessage: Prompt.SystemMessage = Prompt.makeMessage("system", {
  *   content: "You are a helpful assistant specialized in mathematics. " +
  *     "Always show your work step by step."
  * })
+ * systemMessage.role // => "system"
  * ```
  *
  * @category models
@@ -910,7 +948,7 @@ export declare const systemMessage: (params: MessageConstructorParams<SystemMess
  *
  * **Example** (Creating user messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const textUserMessage: Prompt.UserMessage = Prompt.makeMessage("user", {
@@ -933,6 +971,8 @@ export declare const systemMessage: (params: MessageConstructorParams<SystemMess
  *     })
  *   ]
  * })
+ *
+ * const result = [textUserMessage.content.length, multimodalUserMessage.content.length] // => [1, 2]
  * ```
  *
  * @category models
@@ -970,6 +1010,13 @@ export interface UserMessageEncoded extends BaseMessageEncoded<"user", UserMessa
  * @since 4.0.0
  */
 export type UserMessagePartEncoded = TextPartEncoded | FilePartEncoded;
+/**
+ * Schema for validation and encoding of user message content parts.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export declare const UserMessagePart: Schema.Union<readonly [typeof TextPart, typeof FilePart]>;
 /**
  * Represents provider-specific options that can be associated with a
  * `UserMessage` through module augmentation.
@@ -1026,7 +1073,7 @@ export declare const userMessage: (params: MessageConstructorParams<UserMessage>
  *
  * **Example** (Creating assistant messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const assistantMessage: Prompt.AssistantMessage = Prompt.makeMessage(
@@ -1050,7 +1097,8 @@ export declare const userMessage: (params: MessageConstructorParams<UserMessage>
  *         result: {
  *           temperature: 72,
  *           condition: "sunny"
- *         }
+ *         },
+ *         providerExecuted: true
  *       }),
  *       Prompt.makePart("text", {
  *         text: "The weather in San Francisco is currently 72°F and sunny."
@@ -1058,6 +1106,7 @@ export declare const userMessage: (params: MessageConstructorParams<UserMessage>
  *     ]
  *   }
  * )
+ * assistantMessage.content.map((part) => part.type) // => ["text", "tool-call", "tool-result", "text"]
  * ```
  *
  * @category models
@@ -1092,6 +1141,20 @@ export interface AssistantMessageEncoded extends BaseMessageEncoded<"assistant",
  * @since 4.0.0
  */
 export type AssistantMessagePartEncoded = TextPartEncoded | FilePartEncoded | ReasoningPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded;
+/**
+ * Schema for validation and encoding of assistant message content parts.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export declare const AssistantMessagePart: Schema.Union<readonly [
+    typeof TextPart,
+    typeof FilePart,
+    typeof ReasoningPart,
+    typeof ToolCallPart,
+    typeof ToolResultPart,
+    typeof ToolApprovalRequestPart
+]>;
 /**
  * Represents provider-specific options that can be associated with a
  * `AssistantMessage` through module augmentation.
@@ -1155,7 +1218,7 @@ export declare const assistantMessage: (params: MessageConstructorParams<Assista
  *
  * **Example** (Creating tool messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const toolMessage: Prompt.ToolMessage = Prompt.makeMessage("tool", {
@@ -1170,10 +1233,12 @@ export declare const assistantMessage: (params: MessageConstructorParams<Assista
  *           { title: "TypeScript Handbook", url: "https://..." },
  *           { title: "Effective TypeScript", url: "https://..." }
  *         ]
- *       }
+ *       },
+ *       providerExecuted: false
  *     })
  *   ]
  * })
+ * const result = [toolMessage.role, toolMessage.content[0].type] // => ["tool", "tool-result"]
  * ```
  *
  * @category models
@@ -1211,6 +1276,13 @@ export interface ToolMessageEncoded extends BaseMessageEncoded<"tool", ToolMessa
  * @since 4.0.0
  */
 export type ToolMessagePartEncoded = ToolResultPartEncoded | ToolApprovalResponsePartEncoded;
+/**
+ * Schema for validation and encoding of tool message content parts.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export declare const ToolMessagePart: Schema.Union<readonly [typeof ToolResultPart, typeof ToolApprovalResponsePart]>;
 /**
  * Represents provider-specific options that can be associated with a
  * `ToolMessage` through module augmentation.
@@ -1307,8 +1379,8 @@ export declare const Prompt: Schema.Codec<Prompt, PromptEncoded>;
  *
  * **Example** (Accepting raw prompt input)
  *
- * ```ts
- * import type { Prompt } from "effect/unstable/ai"
+ * ```ts import.meta.vitest
+ * import { Prompt } from "effect/unstable/ai"
  *
  * // String input - creates a user message
  * const stringInput: Prompt.RawInput = "Hello, world!"
@@ -1319,9 +1391,9 @@ export declare const Prompt: Schema.Codec<Prompt, PromptEncoded>;
  *   { role: "user", content: [{ type: "text", text: "Hi!" }] }
  * ]
  *
- * // Existing prompt
- * declare const existingPrompt: Prompt.Prompt
- * const promptInput: Prompt.RawInput = existingPrompt
+ * const promptInput: Prompt.RawInput = Prompt.empty
+ *
+ * const result = [typeof stringInput, Array.isArray(messagesInput), promptInput.content.length] // => ["string", true, 0]
  * ```
  *
  * @category models
@@ -1333,11 +1405,11 @@ export type RawInput = string | Iterable<MessageEncoded> | Prompt;
  *
  * **Example** (Creating an empty prompt)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const emptyPrompt = Prompt.empty
- * console.log(emptyPrompt.content) // []
+ * emptyPrompt.content // => []
  * ```
  *
  * @category constructors
@@ -1354,7 +1426,7 @@ export declare const empty: Prompt;
  *
  * **Example** (Creating prompts from inputs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * // From string - creates a user message
@@ -1366,9 +1438,9 @@ export declare const empty: Prompt;
  *   { role: "user", content: [{ type: "text", text: "Hi!" }] }
  * ])
  *
- * // From existing prompt
- * declare const existingPrompt: Prompt.Prompt
- * const copiedPrompt = Prompt.make(existingPrompt)
+ * const copiedPrompt = Prompt.make(Prompt.empty)
+ *
+ * const result = [textPrompt.content[0].role, structuredPrompt.content.length, copiedPrompt.content.length] // => ["user", 2, 0]
  * ```
  *
  * @category constructors
@@ -1380,7 +1452,7 @@ export declare const make: (input: RawInput) => Prompt;
  *
  * **Example** (Creating prompts from messages)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const messages: ReadonlyArray<Prompt.Message> = [
@@ -1393,6 +1465,7 @@ export declare const make: (input: RawInput) => Prompt;
  * ]
  *
  * const prompt = Prompt.fromMessages(messages)
+ * prompt.content.length // => 2
  * ```
  *
  * @category constructors
@@ -1407,7 +1480,7 @@ export declare const fromMessages: (messages: ReadonlyArray<Message>) => Prompt;
  *
  * **Example** (Creating prompts from response parts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt, Response } from "effect/unstable/ai"
  *
  * const responseParts: ReadonlyArray<Response.AnyPart> = [
@@ -1433,6 +1506,7 @@ export declare const fromMessages: (messages: ReadonlyArray<Message>) => Prompt;
  *
  * const prompt = Prompt.fromResponseParts(responseParts)
  * // Creates an assistant message with the response content
+ * prompt.content.map((message) => message.role) // => ["assistant", "tool"]
  * ```
  *
  * @category constructors
@@ -1449,7 +1523,7 @@ export declare const fromResponseParts: (parts: ReadonlyArray<Response.AnyPart>)
  *
  * **Example** (Concatenating prompts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const systemPrompt = Prompt.make([{
@@ -1458,6 +1532,7 @@ export declare const fromResponseParts: (parts: ReadonlyArray<Response.AnyPart>)
  * }])
  *
  * const merged = Prompt.concat(systemPrompt, "Hello, world!")
+ * merged.content.map((message) => message.role) // => ["system", "user"]
  * ```
  *
  * @category combinators
@@ -1474,7 +1549,7 @@ export declare const concat: {
      *
      * **Example** (Concatenating prompts)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1483,6 +1558,7 @@ export declare const concat: {
      * }])
      *
      * const merged = Prompt.concat(systemPrompt, "Hello, world!")
+     * merged.content.map((message) => message.role) // => ["system", "user"]
      * ```
      *
      * @category combinators
@@ -1499,7 +1575,7 @@ export declare const concat: {
      *
      * **Example** (Concatenating prompts)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1508,6 +1584,7 @@ export declare const concat: {
      * }])
      *
      * const merged = Prompt.concat(systemPrompt, "Hello, world!")
+     * merged.content.map((message) => message.role) // => ["system", "user"]
      * ```
      *
      * @category combinators
@@ -1526,7 +1603,7 @@ export declare const concat: {
  *
  * **Example** (Replacing system instructions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const systemPrompt = Prompt.make([{
@@ -1542,6 +1619,7 @@ export declare const concat: {
  *   prompt,
  *   "You are an expert in programming"
  * )
+ * replaced.content[0].content // => "You are an expert in programming"
  * ```
  *
  * @category combinators
@@ -1559,7 +1637,7 @@ export declare const setSystem: {
      *
      * **Example** (Replacing system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1575,6 +1653,7 @@ export declare const setSystem: {
      *   prompt,
      *   "You are an expert in programming"
      * )
+     * replaced.content[0].content // => "You are an expert in programming"
      * ```
      *
      * @category combinators
@@ -1592,7 +1671,7 @@ export declare const setSystem: {
      *
      * **Example** (Replacing system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1608,6 +1687,7 @@ export declare const setSystem: {
      *   prompt,
      *   "You are an expert in programming"
      * )
+     * replaced.content[0].content // => "You are an expert in programming"
      * ```
      *
      * @category combinators
@@ -1623,7 +1703,7 @@ export declare const setSystem: {
  *
  * **Example** (Prepending system instructions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const systemPrompt = Prompt.make([{
@@ -1640,6 +1720,7 @@ export declare const setSystem: {
  *   "You are a helpful assistant. "
  * )
  * // result content: "You are a helpful assistant. You are an expert in programming."
+ * replaced.content[0].content // => "You are a helpful assistant. You are an expert in programming."
  * ```
  *
  * @category combinators
@@ -1654,7 +1735,7 @@ export declare const prependSystem: {
      *
      * **Example** (Prepending system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1671,6 +1752,7 @@ export declare const prependSystem: {
      *   "You are a helpful assistant. "
      * )
      * // result content: "You are a helpful assistant. You are an expert in programming."
+     * replaced.content[0].content // => "You are a helpful assistant. You are an expert in programming."
      * ```
      *
      * @category combinators
@@ -1685,7 +1767,7 @@ export declare const prependSystem: {
      *
      * **Example** (Prepending system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1702,6 +1784,7 @@ export declare const prependSystem: {
      *   "You are a helpful assistant. "
      * )
      * // result content: "You are a helpful assistant. You are an expert in programming."
+     * replaced.content[0].content // => "You are a helpful assistant. You are an expert in programming."
      * ```
      *
      * @category combinators
@@ -1717,7 +1800,7 @@ export declare const prependSystem: {
  *
  * **Example** (Appending system instructions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Prompt } from "effect/unstable/ai"
  *
  * const systemPrompt = Prompt.make([{
@@ -1734,6 +1817,7 @@ export declare const prependSystem: {
  *   " You are a helpful assistant."
  * )
  * // result content: "You are an expert in programming. You are a helpful assistant."
+ * replaced.content[0].content // => "You are an expert in programming. You are a helpful assistant."
  * ```
  *
  * @category combinators
@@ -1748,7 +1832,7 @@ export declare const appendSystem: {
      *
      * **Example** (Appending system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1765,6 +1849,7 @@ export declare const appendSystem: {
      *   " You are a helpful assistant."
      * )
      * // result content: "You are an expert in programming. You are a helpful assistant."
+     * replaced.content[0].content // => "You are an expert in programming. You are a helpful assistant."
      * ```
      *
      * @category combinators
@@ -1779,7 +1864,7 @@ export declare const appendSystem: {
      *
      * **Example** (Appending system instructions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Prompt } from "effect/unstable/ai"
      *
      * const systemPrompt = Prompt.make([{
@@ -1796,6 +1881,7 @@ export declare const appendSystem: {
      *   " You are a helpful assistant."
      * )
      * // result content: "You are an expert in programming. You are a helpful assistant."
+     * replaced.content[0].content // => "You are an expert in programming. You are a helpful assistant."
      * ```
      *
      * @category combinators