effect 4.0.0-beta.65 → 4.0.0-beta.67

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

@@ -15,21 +15,24 @@ import type * as Response from "./Response.ts";
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare const ProviderOptions: Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.Json>>>;
 /**
- * @since 4.0.0
+ * Type of provider-specific options that can be attached to prompt messages
+ * and content parts.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ProviderOptions = typeof ProviderOptions.Type;
 declare const PartTypeId: "~effect/ai/Prompt/Part";
 /**
  * Type guard to check if a value is a Part.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export declare const isPart: (u: unknown) => u is Part;
 /**
@@ -38,15 +41,15 @@ export declare const isPart: (u: unknown) => u is Part;
  * Parts are the building blocks of message content, supporting text, files,
  * reasoning, tool calls, and tool results.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Part = TextPart | ReasoningPart | FilePart | ToolCallPart | ToolResultPart | ToolApprovalResponsePart | ToolApprovalRequestPart;
 /**
  * Encoded representation of a Part.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type PartEncoded = TextPartEncoded | ReasoningPartEncoded | FilePartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalResponsePartEncoded | ToolApprovalRequestPartEncoded;
 /**
@@ -54,8 +57,8 @@ export type PartEncoded = TextPartEncoded | ReasoningPartEncoded | FilePartEncod
  *
  * Provides common structure including type and provider options.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BasePart<Type extends string, Options extends ProviderOptions> {
     readonly [PartTypeId]: typeof PartTypeId;
@@ -71,8 +74,8 @@ export interface BasePart<Type extends string, Options extends ProviderOptions>
 /**
  * Base interface for encoded content parts.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BasePartEncoded<Type extends string, Options extends ProviderOptions> {
     /**
@@ -87,7 +90,8 @@ export interface BasePartEncoded<Type extends string, Options extends ProviderOp
 /**
  * Creates a new content part of the specified type.
  *
- * @example
+ * **Example** (Creating content parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -102,8 +106,8 @@ export interface BasePartEncoded<Type extends string, Options extends ProviderOp
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makePart: <const Type extends Part["type"]>(
 /**
@@ -129,8 +133,8 @@ params: Omit<Extract<Part, {
  * A utility type for specifying the parameters required to construct a
  * specific part of a prompt.
  *
- * @since 4.0.0
  * @category Utility Types
+ * @since 4.0.0
  */
 export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId | "type" | "options"> & {
     /**
@@ -143,7 +147,8 @@ export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId |
  *
  * The most basic content type used for textual information in messages.
  *
- * @example
+ * **Example** (Creating text parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -152,8 +157,8 @@ export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId |
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextPart extends BasePart<"text", TextPartOptions> {
     /**
@@ -164,8 +169,8 @@ export interface TextPart extends BasePart<"text", TextPartOptions> {
 /**
  * Encoded representation of text parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextPartEncoded extends BasePartEncoded<"text", TextPartOptions> {
     /**
@@ -177,16 +182,16 @@ export interface TextPartEncoded extends BasePartEncoded<"text", TextPartOptions
  * Represents provider-specific options that can be associated with a
  * `TextPart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface TextPartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of text parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const TextPart: Schema.Struct<{
     readonly type: Schema.Literal<"text">;
@@ -197,25 +202,27 @@ export declare const TextPart: Schema.Struct<{
 /**
  * Constructs a new text part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const textPart: (params: PartConstructorParams<TextPart>) => TextPart;
 /**
- * Content part representing reasoning or chain-of-thought.
+ * Content part carrying reasoning text in an assistant message, such as a
+ * provider-supplied reasoning summary or explanation.
+ *
+ * **Example** (Creating reasoning parts)
  *
- * @example
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
  * const reasoningPart: Prompt.ReasoningPart = Prompt.makePart("reasoning", {
  *   text:
- *     "Let me think step by step: First I need to understand the user's question..."
+ *     "Summary: the response compares the requested options by price and availability."
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartOptions> {
     /**
@@ -226,8 +233,8 @@ export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartOption
 /**
  * Encoded representation of reasoning parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", ReasoningPartOptions> {
     /**
@@ -239,16 +246,16 @@ export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", Reaso
  * Represents provider-specific options that can be associated with a
  * `ReasoningPart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ReasoningPartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of reasoning parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ReasoningPart: Schema.Struct<{
     readonly type: Schema.Literal<"reasoning">;
@@ -259,8 +266,8 @@ export declare const ReasoningPart: Schema.Struct<{
 /**
  * Constructs a new reasoning part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const reasoningPart: (params: PartConstructorParams<ReasoningPart>) => ReasoningPart;
 /**
@@ -269,7 +276,8 @@ export declare const reasoningPart: (params: PartConstructorParams<ReasoningPart
  *
  * Supports various file types including images, documents, and binary data.
  *
- * @example
+ * **Example** (Creating file parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -286,8 +294,8 @@ export declare const reasoningPart: (params: PartConstructorParams<ReasoningPart
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePart extends BasePart<"file", FilePartOptions> {
     /**
@@ -306,8 +314,8 @@ export interface FilePart extends BasePart<"file", FilePartOptions> {
 /**
  * Encoded representation of file parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions> {
     /**
@@ -327,16 +335,16 @@ export interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions
  * Represents provider-specific options that can be associated with a
  * `FilePart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface FilePartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of file parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const FilePart: Schema.Struct<{
     readonly type: Schema.Literal<"file">;
@@ -349,14 +357,15 @@ export declare const FilePart: Schema.Struct<{
 /**
  * Constructs a new file part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const filePart: (params: PartConstructorParams<FilePart>) => FilePart;
 /**
  * Content part representing a tool call request.
  *
- * @example
+ * **Example** (Creating tool call parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -368,8 +377,8 @@ export declare const filePart: (params: PartConstructorParams<FilePart>) => File
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolCallPart extends BasePart<"tool-call", ToolCallPartOptions> {
     /**
@@ -392,8 +401,8 @@ export interface ToolCallPart extends BasePart<"tool-call", ToolCallPartOptions>
 /**
  * Encoded representation of tool call parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCallPartOptions> {
     /**
@@ -417,16 +426,16 @@ export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCa
  * Represents provider-specific options that can be associated with a
  * `ToolCallPart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ToolCallPartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of tool call parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ToolCallPart: Schema.Struct<{
     readonly type: Schema.Literal<"tool-call">;
@@ -440,14 +449,15 @@ export declare const ToolCallPart: Schema.Struct<{
 /**
  * Constructs a new tool call part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolCallPart: (params: PartConstructorParams<ToolCallPart>) => ToolCallPart;
 /**
  * Content part representing the result of a tool call.
  *
- * @example
+ * **Example** (Creating tool result parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -463,8 +473,8 @@ export declare const toolCallPart: (params: PartConstructorParams<ToolCallPart>)
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOptions> {
     /**
@@ -487,8 +497,8 @@ export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOp
 /**
  * Encoded representation of tool result parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", ToolResultPartOptions> {
     /**
@@ -512,16 +522,16 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
  * Represents provider-specific options that can be associated with a
  * `ToolResultPart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ToolResultPartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of tool result parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ToolResultPart: Schema.Struct<{
     readonly type: Schema.Literal<"tool-result">;
@@ -535,8 +545,8 @@ export declare const ToolResultPart: Schema.Struct<{
 /**
  * Constructs a new tool result part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolResultPart: (params: PartConstructorParams<ToolResultPart>) => ToolResultPart;
 /**
@@ -545,7 +555,8 @@ export declare const toolResultPart: (params: PartConstructorParams<ToolResultPa
  * Used in tool messages to approve or deny tool execution when tools have
  * the `needsApproval` property set.
  *
- * @example
+ * **Example** (Creating tool approval responses)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -567,8 +578,8 @@ export declare const toolResultPart: (params: PartConstructorParams<ToolResultPa
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalResponsePart extends BasePart<"tool-approval-response", ToolApprovalResponsePartOptions> {
     /**
@@ -587,8 +598,8 @@ export interface ToolApprovalResponsePart extends BasePart<"tool-approval-respon
 /**
  * Encoded representation of tool approval response parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalResponsePartEncoded extends BasePartEncoded<"tool-approval-response", ToolApprovalResponsePartOptions> {
     /**
@@ -608,16 +619,16 @@ export interface ToolApprovalResponsePartEncoded extends BasePartEncoded<"tool-a
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalResponsePart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ToolApprovalResponsePartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of tool approval response parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ToolApprovalResponsePart: Schema.Struct<{
     readonly type: Schema.Literal<"tool-approval-response">;
@@ -630,8 +641,8 @@ export declare const ToolApprovalResponsePart: Schema.Struct<{
 /**
  * Constructs a new tool approval response part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolApprovalResponsePart: (params: PartConstructorParams<ToolApprovalResponsePart>) => ToolApprovalResponsePart;
 /**
@@ -641,7 +652,8 @@ export declare const toolApprovalResponsePart: (params: PartConstructorParams<To
  * execution. The user responds with a `ToolApprovalResponsePart` in a tool
  * message.
  *
- * @example
+ * **Example** (Creating tool approval requests)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -654,8 +666,8 @@ export declare const toolApprovalResponsePart: (params: PartConstructorParams<To
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request", ToolApprovalRequestPartOptions> {
     /**
@@ -670,8 +682,8 @@ export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request
 /**
  * Encoded representation of tool approval request parts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPartEncoded extends BasePartEncoded<"tool-approval-request", ToolApprovalRequestPartOptions> {
     /**
@@ -687,16 +699,16 @@ export interface ToolApprovalRequestPartEncoded extends BasePartEncoded<"tool-ap
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalRequestPart` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPartOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of tool approval request parts.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ToolApprovalRequestPart: Schema.Struct<{
     readonly type: Schema.Literal<"tool-approval-request">;
@@ -708,16 +720,16 @@ export declare const ToolApprovalRequestPart: Schema.Struct<{
 /**
  * Constructs a new tool approval request part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolApprovalRequestPart: (params: PartConstructorParams<ToolApprovalRequestPart>) => ToolApprovalRequestPart;
 declare const MessageTypeId: "~effect/ai/Prompt/Message";
 /**
  * Type guard to check if a value is a Message.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export declare const isMessage: (u: unknown) => u is Message;
 /**
@@ -725,8 +737,8 @@ export declare const isMessage: (u: unknown) => u is Message;
  *
  * Provides common structure including role and provider options.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BaseMessage<Role extends string, Options extends ProviderOptions> {
     readonly [MessageTypeId]: typeof MessageTypeId;
@@ -744,8 +756,8 @@ export interface BaseMessage<Role extends string, Options extends ProviderOption
  *
  * @template Role - String literal type for the message role
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BaseMessageEncoded<Role extends string, Options extends ProviderOptions> {
     /**
@@ -760,7 +772,8 @@ export interface BaseMessageEncoded<Role extends string, Options extends Provide
 /**
  * Creates a new message with the specified role.
  *
- * @example
+ * **Example** (Creating messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -768,13 +781,13 @@ export interface BaseMessageEncoded<Role extends string, Options extends Provide
  *   text: "Hello, world!"
  * })
  *
- * const filePart = Prompt.makeMessage("user", {
+ * const userMessage = Prompt.makeMessage("user", {
  *   content: [textPart]
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeMessage: <const Role extends Message["role"]>(role: Role, params: Omit<Extract<Message, {
     role: Role;
@@ -789,8 +802,8 @@ export declare const makeMessage: <const Role extends Message["role"]>(role: Rol
  * A utility type for specifying the parameters required to construct a
  * specific message for a prompt.
  *
- * @since 4.0.0
  * @category Utility Types
+ * @since 4.0.0
  */
 export type MessageConstructorParams<M extends Message> = Omit<M, typeof MessageTypeId | "role" | "options"> & {
     /**
@@ -799,11 +812,11 @@ export type MessageConstructorParams<M extends Message> = Omit<M, typeof Message
     readonly options?: Part["options"] | undefined;
 };
 /**
- * Schema for decoding message content (i.e. an array containing a single
- * `TextPart`) from a string.
+ * Schema that decodes a string into content containing a single `TextPart` and,
+ * when encoding, emits the `text` value of the first part.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ContentFromString: Schema.decodeTo<Schema.NonEmptyArray<Schema.toType<Schema.Struct<{
     readonly type: Schema.Literal<"text">;
@@ -814,7 +827,8 @@ export declare const ContentFromString: Schema.decodeTo<Schema.NonEmptyArray<Sch
 /**
  * Message representing system instructions or context.
  *
- * @example
+ * **Example** (Creating system messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -824,8 +838,8 @@ export declare const ContentFromString: Schema.decodeTo<Schema.NonEmptyArray<Sch
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SystemMessage extends BaseMessage<"system", SystemMessageOptions> {
     /**
@@ -836,8 +850,8 @@ export interface SystemMessage extends BaseMessage<"system", SystemMessageOption
 /**
  * Encoded representation of system messages for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SystemMessageEncoded extends BaseMessageEncoded<"system", SystemMessageOptions> {
     /**
@@ -849,16 +863,16 @@ export interface SystemMessageEncoded extends BaseMessageEncoded<"system", Syste
  * Represents provider-specific options that can be associated with a
  * `SystemMessage` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface SystemMessageOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of system messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const SystemMessage: Schema.Struct<{
     readonly role: Schema.Literal<"system">;
@@ -869,14 +883,15 @@ export declare const SystemMessage: Schema.Struct<{
 /**
  * Constructs a new system message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const systemMessage: (params: MessageConstructorParams<SystemMessage>) => SystemMessage;
 /**
  * Message representing user input or questions.
  *
- * @example
+ * **Example** (Creating user messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -902,8 +917,8 @@ export declare const systemMessage: (params: MessageConstructorParams<SystemMess
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface UserMessage extends BaseMessage<"user", UserMessageOptions> {
     /**
@@ -914,15 +929,15 @@ export interface UserMessage extends BaseMessage<"user", UserMessageOptions> {
 /**
  * Union type of content parts allowed in user messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type UserMessagePart = TextPart | FilePart;
 /**
  * Encoded representation of user messages for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface UserMessageEncoded extends BaseMessageEncoded<"user", UserMessageOptions> {
     /**
@@ -933,24 +948,24 @@ export interface UserMessageEncoded extends BaseMessageEncoded<"user", UserMessa
 /**
  * Union type of encoded content parts for user messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type UserMessagePartEncoded = TextPartEncoded | FilePartEncoded;
 /**
  * Represents provider-specific options that can be associated with a
  * `UserMessage` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface UserMessageOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of user messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const UserMessage: Schema.Struct<{
     readonly role: Schema.Literal<"user">;
@@ -984,14 +999,15 @@ export declare const UserMessage: Schema.Struct<{
 /**
  * Constructs a new user message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const userMessage: (params: MessageConstructorParams<UserMessage>) => UserMessage;
 /**
  * Message representing large language model assistant responses.
  *
- * @example
+ * **Example** (Creating assistant messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1001,7 +1017,7 @@ export declare const userMessage: (params: MessageConstructorParams<UserMessage>
  *     content: [
  *       Prompt.makePart("text", {
  *         text:
- *           "The user is asking about the weather. I should use the weather tool."
+ *           "I can check the current weather for San Francisco."
  *       }),
  *       Prompt.makePart("tool-call", {
  *         id: "call_123",
@@ -1026,8 +1042,8 @@ export declare const userMessage: (params: MessageConstructorParams<UserMessage>
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AssistantMessage extends BaseMessage<"assistant", AssistantMessageOptions> {
     /**
@@ -1038,15 +1054,15 @@ export interface AssistantMessage extends BaseMessage<"assistant", AssistantMess
 /**
  * Union type of content parts allowed in assistant messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AssistantMessagePart = TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | ToolApprovalRequestPart;
 /**
  * Encoded representation of assistant messages for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AssistantMessageEncoded extends BaseMessageEncoded<"assistant", AssistantMessageOptions> {
     readonly content: string | ReadonlyArray<AssistantMessagePartEncoded>;
@@ -1054,24 +1070,24 @@ export interface AssistantMessageEncoded extends BaseMessageEncoded<"assistant",
 /**
  * Union type of encoded content parts for assistant messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AssistantMessagePartEncoded = TextPartEncoded | FilePartEncoded | ReasoningPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded;
 /**
  * Represents provider-specific options that can be associated with a
  * `AssistantMessage` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface AssistantMessageOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of assistant messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const AssistantMessage: Schema.Struct<{
     readonly role: Schema.Literal<"assistant">;
@@ -1097,14 +1113,16 @@ export declare const AssistantMessage: Schema.Struct<{
 /**
  * Constructs a new assistant message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const assistantMessage: (params: MessageConstructorParams<AssistantMessage>) => AssistantMessage;
 /**
- * Message representing tool execution results.
+ * Message carrying tool-side content, including tool execution results and
+ * responses to tool approval requests.
+ *
+ * **Example** (Creating tool messages)
  *
- * @example
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1126,8 +1144,8 @@ export declare const assistantMessage: (params: MessageConstructorParams<Assista
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolMessage extends BaseMessage<"tool", ToolMessageOptions> {
     /**
@@ -1138,15 +1156,15 @@ export interface ToolMessage extends BaseMessage<"tool", ToolMessageOptions> {
 /**
  * Union type of content parts allowed in tool messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type ToolMessagePart = ToolResultPart | ToolApprovalResponsePart;
 /**
  * Encoded representation of tool messages for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolMessageEncoded extends BaseMessageEncoded<"tool", ToolMessageOptions> {
     /**
@@ -1157,24 +1175,24 @@ export interface ToolMessageEncoded extends BaseMessageEncoded<"tool", ToolMessa
 /**
  * Union type of encoded content parts for tool messages.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type ToolMessagePartEncoded = ToolResultPartEncoded | ToolApprovalResponsePartEncoded;
 /**
  * Represents provider-specific options that can be associated with a
  * `ToolMessage` through module augmentation.
  *
- * @since 4.0.0
  * @category ProviderOptions
+ * @since 4.0.0
  */
 export interface ToolMessageOptions extends ProviderOptions {
 }
 /**
  * Schema for validation and encoding of tool messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const ToolMessage: Schema.Struct<{
     readonly role: Schema.Literal<"tool">;
@@ -1185,45 +1203,45 @@ export declare const ToolMessage: Schema.Struct<{
 /**
  * Constructs a new tool message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolMessage: (params: MessageConstructorParams<ToolMessage>) => ToolMessage;
 /**
  * A type representing all possible message types in a conversation.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
 /**
  * A type representing all possible encoded message types for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MessageEncoded = SystemMessageEncoded | UserMessageEncoded | AssistantMessageEncoded | ToolMessageEncoded;
 /**
  * Schema for validation and encoding of messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const Message: Schema.Codec<Message, MessageEncoded>;
 declare const TypeId: "~effect/unstable/ai/Prompt";
 /**
  * Type guard to check if a value is a Prompt.
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isPrompt: (u: unknown) => u is Prompt;
 /**
  * A Prompt contains a sequence of messages that form the context of a
  * conversation with a large language model.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Prompt extends Pipeable {
     readonly [TypeId]: typeof TypeId;
@@ -1235,8 +1253,8 @@ export interface Prompt extends Pipeable {
 /**
  * Encoded representation of prompts for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface PromptEncoded {
     /**
@@ -1247,17 +1265,16 @@ export interface PromptEncoded {
 /**
  * Describes a schema that represents a `Prompt` instance.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const Prompt: Schema.Codec<Prompt, PromptEncoded>;
 /**
- * Raw input types that can be converted into a Prompt.
+ * Raw input accepted by `make`: a string, an iterable of encoded messages, or
+ * an existing `Prompt`.
  *
- * Supports various input formats for convenience, including simple strings,
- * message arrays, response parts, and existing prompts.
+ * **Example** (Accepting raw prompt input)
  *
- * @example
  * ```ts
  * import type { Prompt } from "effect/unstable/ai"
  *
@@ -1275,14 +1292,15 @@ export declare const Prompt: Schema.Codec<Prompt, PromptEncoded>;
  * const promptInput: Prompt.RawInput = existingPrompt
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type RawInput = string | Iterable<MessageEncoded> | Prompt;
 /**
  * An empty prompt with no messages.
  *
- * @example
+ * **Example** (Creating an empty prompt)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1290,8 +1308,8 @@ export type RawInput = string | Iterable<MessageEncoded> | Prompt;
  * console.log(emptyPrompt.content) // []
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const empty: Prompt;
 /**
@@ -1300,7 +1318,8 @@ export declare const empty: Prompt;
  * This is the primary constructor for creating prompts, supporting multiple
  * input formats for convenience and flexibility.
  *
- * @example
+ * **Example** (Creating prompts from inputs)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1318,14 +1337,15 @@ export declare const empty: Prompt;
  * const copiedPrompt = Prompt.make(existingPrompt)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: (input: RawInput) => Prompt;
 /**
  * Creates a Prompt from an array of messages.
  *
- * @example
+ * **Example** (Creating prompts from messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1341,18 +1361,18 @@ export declare const make: (input: RawInput) => Prompt;
  * const prompt = Prompt.fromMessages(messages)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromMessages: (messages: ReadonlyArray<Message>) => Prompt;
 /**
- * Creates a Prompt from the response parts of a previous interaction with a
- * large language model.
+ * Creates a `Prompt` from response parts by folding completed text and
+ * reasoning streams into assistant parts, placing tool calls and approval
+ * requests in an assistant message, and placing non-preliminary tool results
+ * in a tool message using their encoded results.
  *
- * Converts streaming or non-streaming AI response parts into a structured
- * prompt, typically for use in conversation history or further processing.
+ * **Example** (Creating prompts from response parts)
  *
- * @example
  * ```ts
  * import { Prompt, Response } from "effect/unstable/ai"
  *
@@ -1381,8 +1401,8 @@ export declare const fromMessages: (messages: ReadonlyArray<Message>) => Prompt;
  * // Creates an assistant message with the response content
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromResponseParts: (parts: ReadonlyArray<Response.AnyPart>) => Prompt;
 /**
@@ -1391,7 +1411,8 @@ export declare const fromResponseParts: (parts: ReadonlyArray<Response.AnyPart>)
  * Creates a new prompt containing all messages from both the original prompt,
  * and the provided raw input, maintaining the order of messages.
  *
- * @example
+ * **Example** (Concatenating prompts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1403,8 +1424,8 @@ export declare const fromResponseParts: (parts: ReadonlyArray<Response.AnyPart>)
  * const merged = Prompt.concat(systemPrompt, "Hello, world!")
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const concat: {
     /**
@@ -1413,7 +1434,8 @@ export declare const concat: {
      * Creates a new prompt containing all messages from both the original prompt,
      * and the provided raw input, maintaining the order of messages.
      *
-     * @example
+     * **Example** (Concatenating prompts)
+     *
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1425,8 +1447,8 @@ export declare const concat: {
      * const merged = Prompt.concat(systemPrompt, "Hello, world!")
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (input: RawInput): (self: Prompt) => Prompt;
     /**
@@ -1435,7 +1457,8 @@ export declare const concat: {
      * Creates a new prompt containing all messages from both the original prompt,
      * and the provided raw input, maintaining the order of messages.
      *
-     * @example
+     * **Example** (Concatenating prompts)
+     *
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1447,8 +1470,8 @@ export declare const concat: {
      * const merged = Prompt.concat(systemPrompt, "Hello, world!")
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (self: Prompt, input: RawInput): Prompt;
 };
@@ -1459,7 +1482,8 @@ export declare const concat: {
  * **NOTE**: This method will remove and replace any previous system message
  * from the prompt.
  *
- * @example
+ * **Example** (Replacing system instructions)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1478,8 +1502,8 @@ export declare const concat: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setSystem: {
     /**
@@ -1489,7 +1513,8 @@ export declare const setSystem: {
      * **NOTE**: This method will remove and replace any previous system message
      * from the prompt.
      *
-     * @example
+     * **Example** (Replacing system instructions)
+     *
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1508,8 +1533,8 @@ export declare const setSystem: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (content: string): (self: Prompt) => Prompt;
     /**
@@ -1519,7 +1544,8 @@ export declare const setSystem: {
      * **NOTE**: This method will remove and replace any previous system message
      * from the prompt.
      *
-     * @example
+     * **Example** (Replacing system instructions)
+     *
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1538,19 +1564,19 @@ export declare const setSystem: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     (self: Prompt, content: string): Prompt;
 };
 /**
- * Creates a new prompt from the specified prompt with the provided text content
- * prepended to the start of existing system message content.
+ * Creates a new prompt with a leading system message. If the prompt already has
+ * a system message, the new message uses the provided content prepended to the
+ * first existing system message's content; the original messages remain after
+ * it.
  *
- * If no system message exists in the specified prompt, the provided content
- * will be used to create a system message.
+ * **Example** (Prepending system instructions)
  *
- * @example
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1570,18 +1596,18 @@ export declare const setSystem: {
  * // result content: "You are a helpful assistant. You are an expert in programming."
  * ```
  *
- * @since 1.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const prependSystem: {
     /**
-     * Creates a new prompt from the specified prompt with the provided text content
-     * prepended to the start of existing system message content.
+     * Creates a new prompt with a leading system message. If the prompt already has
+     * a system message, the new message uses the provided content prepended to the
+     * first existing system message's content; the original messages remain after
+     * it.
      *
-     * If no system message exists in the specified prompt, the provided content
-     * will be used to create a system message.
+     * **Example** (Prepending system instructions)
      *
-     * @example
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1601,18 +1627,18 @@ export declare const prependSystem: {
      * // result content: "You are a helpful assistant. You are an expert in programming."
      * ```
      *
-     * @since 1.0.0
      * @category Combinators
+     * @since 4.0.0
      */
     (content: string): (self: Prompt) => Prompt;
     /**
-     * Creates a new prompt from the specified prompt with the provided text content
-     * prepended to the start of existing system message content.
+     * Creates a new prompt with a leading system message. If the prompt already has
+     * a system message, the new message uses the provided content prepended to the
+     * first existing system message's content; the original messages remain after
+     * it.
      *
-     * If no system message exists in the specified prompt, the provided content
-     * will be used to create a system message.
+     * **Example** (Prepending system instructions)
      *
-     * @example
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1632,19 +1658,19 @@ export declare const prependSystem: {
      * // result content: "You are a helpful assistant. You are an expert in programming."
      * ```
      *
-     * @since 1.0.0
      * @category Combinators
+     * @since 4.0.0
      */
     (self: Prompt, content: string): Prompt;
 };
 /**
- * Creates a new prompt from the specified prompt with the provided text content
- * appended to the end of existing system message content.
+ * Creates a new prompt with a leading system message. If the prompt already has
+ * a system message, the new message uses the provided content appended to the
+ * first existing system message's content; the original messages remain after
+ * it.
  *
- * If no system message exists in the specified prompt, the provided content
- * will be used to create a system message.
+ * **Example** (Appending system instructions)
  *
- * @example
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1664,18 +1690,18 @@ export declare const prependSystem: {
  * // result content: "You are an expert in programming. You are a helpful assistant."
  * ```
  *
- * @since 1.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const appendSystem: {
     /**
-     * Creates a new prompt from the specified prompt with the provided text content
-     * appended to the end of existing system message content.
+     * Creates a new prompt with a leading system message. If the prompt already has
+     * a system message, the new message uses the provided content appended to the
+     * first existing system message's content; the original messages remain after
+     * it.
      *
-     * If no system message exists in the specified prompt, the provided content
-     * will be used to create a system message.
+     * **Example** (Appending system instructions)
      *
-     * @example
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1695,18 +1721,18 @@ export declare const appendSystem: {
      * // result content: "You are an expert in programming. You are a helpful assistant."
      * ```
      *
-     * @since 1.0.0
      * @category Combinators
+     * @since 4.0.0
      */
     (content: string): (self: Prompt) => Prompt;
     /**
-     * Creates a new prompt from the specified prompt with the provided text content
-     * appended to the end of existing system message content.
+     * Creates a new prompt with a leading system message. If the prompt already has
+     * a system message, the new message uses the provided content appended to the
+     * first existing system message's content; the original messages remain after
+     * it.
      *
-     * If no system message exists in the specified prompt, the provided content
-     * will be used to create a system message.
+     * **Example** (Appending system instructions)
      *
-     * @example
      * ```ts
      * import { Prompt } from "effect/unstable/ai"
      *
@@ -1726,8 +1752,8 @@ export declare const appendSystem: {
      * // result content: "You are an expert in programming. You are a helpful assistant."
      * ```
      *
-     * @since 1.0.0
      * @category Combinators
+     * @since 4.0.0
      */
     (self: Prompt, content: string): Prompt;
 };