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

package/src/unstable/ai/Prompt.ts

@@ -7,7 +7,8 @@
  * options. It supports rich content types like text, files, tool calls, and
  * reasoning.
  *
- * @example
+ * **Example** (Creating a structured conversation)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -34,7 +35,8 @@
  * ])
  * ```
  *
- * @example
+ * **Example** (Combining prompts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -81,8 +83,8 @@ import type * as Response from "./Response.ts"
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export const ProviderOptions: Schema.$Record<
   Schema.String,
@@ -90,8 +92,11 @@ export const ProviderOptions: Schema.$Record<
 > = Schema.Record(Schema.String, Schema.NullOr(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
 
@@ -104,8 +109,8 @@ const PartTypeId = "~effect/ai/Prompt/Part" as const
 /**
  * Type guard to check if a value is a Part.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, PartTypeId)
 
@@ -115,8 +120,8 @@ export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, PartTy
  * 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
@@ -130,8 +135,8 @@ export type Part =
 /**
  * Encoded representation of a Part.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type PartEncoded =
   | TextPartEncoded
@@ -147,8 +152,8 @@ export type PartEncoded =
  *
  * 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
@@ -165,8 +170,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> {
   /**
@@ -189,7 +194,8 @@ const BasePart = Schema.Struct({
 /**
  * Creates a new content part of the specified type.
  *
- * @example
+ * **Example** (Creating content parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -204,8 +210,8 @@ const BasePart = Schema.Struct({
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makePart = <const Type extends Part["type"]>(
   /**
@@ -221,20 +227,19 @@ export const makePart = <const Type extends Part["type"]>(
      */
     readonly options?: Extract<Part, { type: Type }>["options"] | undefined
   }
-): Extract<Part, { type: Type }> =>
-  (({
-    ...params,
-    [PartTypeId]: PartTypeId,
-    type,
-    options: params.options ?? {}
-  }) as any)
+): Extract<Part, { type: Type }> => (({
+  ...params,
+  [PartTypeId]: PartTypeId,
+  type,
+  options: params.options ?? {}
+}) as any)
 
 /**
  * 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"> & {
   /**
@@ -252,7 +257,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"
  *
@@ -261,8 +267,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> {
   /**
@@ -274,8 +280,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> {
   /**
@@ -288,16 +294,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 const TextPart: Schema.Struct<
   {
@@ -320,8 +326,8 @@ export const TextPart: Schema.Struct<
 /**
  * Constructs a new text part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const textPart = (params: PartConstructorParams<TextPart>): TextPart => makePart("text", params as any)
 
@@ -330,20 +336,22 @@ export const textPart = (params: PartConstructorParams<TextPart>): TextPart => m
 // =============================================================================
 
 /**
- * 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> {
   /**
@@ -355,8 +363,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> {
   /**
@@ -369,16 +377,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 const ReasoningPart: Schema.Struct<{
   readonly type: Schema.Literal<"reasoning">
@@ -399,8 +407,8 @@ export const ReasoningPart: Schema.Struct<{
 /**
  * Constructs a new reasoning part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const reasoningPart = (params: PartConstructorParams<ReasoningPart>): ReasoningPart =>
   makePart("reasoning", params as any)
@@ -415,7 +423,8 @@ export const reasoningPart = (params: PartConstructorParams<ReasoningPart>): Rea
  *
  * Supports various file types including images, documents, and binary data.
  *
- * @example
+ * **Example** (Creating file parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -432,8 +441,8 @@ export const reasoningPart = (params: PartConstructorParams<ReasoningPart>): Rea
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePart extends BasePart<"file", FilePartOptions> {
   /**
@@ -453,8 +462,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> {
   /**
@@ -475,16 +484,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 const FilePart: Schema.Struct<{
   readonly type: Schema.Literal<"file">
@@ -509,8 +518,8 @@ export const FilePart: Schema.Struct<{
 /**
  * Constructs a new file part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const filePart = (params: PartConstructorParams<FilePart>): FilePart => makePart("file", params as any)
 
@@ -521,7 +530,8 @@ export const filePart = (params: PartConstructorParams<FilePart>): FilePart => m
 /**
  * Content part representing a tool call request.
  *
- * @example
+ * **Example** (Creating tool call parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -533,8 +543,8 @@ export const filePart = (params: PartConstructorParams<FilePart>): FilePart => m
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolCallPart extends BasePart<"tool-call", ToolCallPartOptions> {
   /**
@@ -558,8 +568,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> {
   /**
@@ -584,16 +594,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 const ToolCallPart: Schema.Struct<{
   readonly type: Schema.Literal<"tool-call">
@@ -620,8 +630,8 @@ export const ToolCallPart: Schema.Struct<{
 /**
  * Constructs a new tool call part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolCallPart =>
   makePart("tool-call", params as any)
@@ -633,7 +643,8 @@ export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolC
 /**
  * Content part representing the result of a tool call.
  *
- * @example
+ * **Example** (Creating tool result parts)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -649,8 +660,8 @@ export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolC
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOptions> {
   /**
@@ -674,8 +685,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> {
   /**
@@ -700,16 +711,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 const ToolResultPart: Schema.Struct<{
   readonly type: Schema.Literal<"tool-result">
@@ -736,8 +747,8 @@ export const ToolResultPart: Schema.Struct<{
 /**
  * Constructs a new tool result part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): ToolResultPart =>
   makePart("tool-result", params as any)
@@ -752,7 +763,8 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  * 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"
  *
@@ -774,8 +786,8 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalResponsePart extends BasePart<"tool-approval-response", ToolApprovalResponsePartOptions> {
   /**
@@ -795,8 +807,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>
@@ -819,16 +831,16 @@ export interface ToolApprovalResponsePartEncoded
  * 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 const ToolApprovalResponsePart: Schema.Struct<{
   readonly type: Schema.Literal<"tool-approval-response">
@@ -853,8 +865,8 @@ export const ToolApprovalResponsePart: Schema.Struct<{
 /**
  * Constructs a new tool approval response part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolApprovalResponsePart = (
   params: PartConstructorParams<ToolApprovalResponsePart>
@@ -871,7 +883,8 @@ export const toolApprovalResponsePart = (
  * execution. The user responds with a `ToolApprovalResponsePart` in a tool
  * message.
  *
- * @example
+ * **Example** (Creating tool approval requests)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -884,8 +897,8 @@ export const toolApprovalResponsePart = (
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request", ToolApprovalRequestPartOptions> {
   /**
@@ -901,8 +914,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>
@@ -921,16 +934,16 @@ export interface ToolApprovalRequestPartEncoded
  * 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 const ToolApprovalRequestPart: Schema.Struct<{
   readonly type: Schema.Literal<"tool-approval-request">
@@ -953,8 +966,8 @@ export const ToolApprovalRequestPart: Schema.Struct<{
 /**
  * Constructs a new tool approval request part.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolApprovalRequestPart = (
   params: PartConstructorParams<ToolApprovalRequestPart>
@@ -969,8 +982,8 @@ const MessageTypeId = "~effect/ai/Prompt/Message" as const
 /**
  * Type guard to check if a value is a Message.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isMessage = (u: unknown): u is Message => Predicate.hasProperty(u, MessageTypeId)
 
@@ -979,8 +992,8 @@ export const isMessage = (u: unknown): u is Message => Predicate.hasProperty(u,
  *
  * 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
@@ -999,8 +1012,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> {
   /**
@@ -1023,7 +1036,8 @@ const BaseMessage = Schema.Struct({
 /**
  * Creates a new message with the specified role.
  *
- * @example
+ * **Example** (Creating messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1031,33 +1045,32 @@ const BaseMessage = Schema.Struct({
  *   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 const makeMessage = <const Role extends Message["role"]>(
   role: Role,
   params: Omit<Extract<Message, { role: Role }>, typeof MessageTypeId | "role" | "options"> & {
     readonly options?: Extract<Message, { role: Role }>["options"] | undefined
   }
-): Extract<Message, { role: Role }> =>
-  (({
-    ...params,
-    [MessageTypeId]: MessageTypeId,
-    role,
-    options: params.options ?? {}
-  }) as any)
+): Extract<Message, { role: Role }> => (({
+  ...params,
+  [MessageTypeId]: MessageTypeId,
+  role,
+  options: params.options ?? {}
+}) as any)
 
 /**
  * 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"> & {
   /**
@@ -1067,11 +1080,11 @@ export type MessageConstructorParams<M extends Message> = Omit<M, typeof Message
 }
 
 /**
- * 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 const ContentFromString: Schema.decodeTo<
   Schema.NonEmptyArray<
@@ -1107,7 +1120,8 @@ export const ContentFromString: Schema.decodeTo<
 /**
  * Message representing system instructions or context.
  *
- * @example
+ * **Example** (Creating system messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1117,8 +1131,8 @@ export const ContentFromString: Schema.decodeTo<
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface SystemMessage extends BaseMessage<"system", SystemMessageOptions> {
   /**
@@ -1130,8 +1144,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> {
   /**
@@ -1144,16 +1158,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 const SystemMessage: Schema.Struct<{
   readonly role: Schema.Literal<"system">
@@ -1174,8 +1188,8 @@ export const SystemMessage: Schema.Struct<{
 /**
  * Constructs a new system message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const systemMessage = (params: MessageConstructorParams<SystemMessage>): SystemMessage =>
   makeMessage("system", params)
@@ -1187,7 +1201,8 @@ export const systemMessage = (params: MessageConstructorParams<SystemMessage>):
 /**
  * Message representing user input or questions.
  *
- * @example
+ * **Example** (Creating user messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1213,8 +1228,8 @@ export const systemMessage = (params: MessageConstructorParams<SystemMessage>):
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface UserMessage extends BaseMessage<"user", UserMessageOptions> {
   /**
@@ -1226,16 +1241,16 @@ 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> {
   /**
@@ -1247,8 +1262,8 @@ 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
 
@@ -1256,16 +1271,16 @@ 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 const UserMessage: Schema.Struct<{
   readonly role: Schema.Literal<"user">
@@ -1342,8 +1357,8 @@ export const UserMessage: Schema.Struct<{
 /**
  * Constructs a new user message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const userMessage = (params: MessageConstructorParams<UserMessage>): UserMessage => makeMessage("user", params)
 
@@ -1354,7 +1369,8 @@ export const userMessage = (params: MessageConstructorParams<UserMessage>): User
 /**
  * Message representing large language model assistant responses.
  *
- * @example
+ * **Example** (Creating assistant messages)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1364,7 +1380,7 @@ export const userMessage = (params: MessageConstructorParams<UserMessage>): User
  *     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",
@@ -1389,8 +1405,8 @@ export const userMessage = (params: MessageConstructorParams<UserMessage>): User
  * )
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface AssistantMessage extends BaseMessage<"assistant", AssistantMessageOptions> {
   /**
@@ -1402,8 +1418,8 @@ 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
@@ -1416,8 +1432,8 @@ export type AssistantMessagePart =
 /**
  * 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>
@@ -1426,8 +1442,8 @@ 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
@@ -1441,16 +1457,16 @@ export type AssistantMessagePartEncoded =
  * 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 const AssistantMessage: Schema.Struct<{
   readonly role: Schema.Literal<"assistant">
@@ -1516,8 +1532,8 @@ export const AssistantMessage: Schema.Struct<{
 /**
  * Constructs a new assistant message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const assistantMessage = (params: MessageConstructorParams<AssistantMessage>): AssistantMessage =>
   makeMessage("assistant", params)
@@ -1527,9 +1543,11 @@ export const assistantMessage = (params: MessageConstructorParams<AssistantMessa
 // =============================================================================
 
 /**
- * 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"
  *
@@ -1551,8 +1569,8 @@ export const assistantMessage = (params: MessageConstructorParams<AssistantMessa
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolMessage extends BaseMessage<"tool", ToolMessageOptions> {
   /**
@@ -1564,16 +1582,16 @@ 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> {
   /**
@@ -1585,8 +1603,8 @@ 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
 
@@ -1594,16 +1612,16 @@ export type ToolMessagePartEncoded = ToolResultPartEncoded | ToolApprovalRespons
  * 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 const ToolMessage: Schema.Struct<{
   readonly role: Schema.Literal<"tool">
@@ -1626,8 +1644,8 @@ export const ToolMessage: Schema.Struct<{
 /**
  * Constructs a new tool message.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolMessage = (params: MessageConstructorParams<ToolMessage>): ToolMessage => makeMessage("tool", params)
 
@@ -1638,8 +1656,8 @@ export const toolMessage = (params: MessageConstructorParams<ToolMessage>): Tool
 /**
  * A type representing all possible message types in a conversation.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Message =
   | SystemMessage
@@ -1650,8 +1668,8 @@ export type Message =
 /**
  * A type representing all possible encoded message types for serialization.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MessageEncoded =
   | SystemMessageEncoded
@@ -1662,8 +1680,8 @@ export type MessageEncoded =
 /**
  * Schema for validation and encoding of messages.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const Message: Schema.Codec<Message, MessageEncoded> = Schema.Union([
   SystemMessage,
@@ -1681,8 +1699,8 @@ const TypeId = "~effect/unstable/ai/Prompt" as const
 /**
  * Type guard to check if a value is a Prompt.
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isPrompt = (u: unknown): u is Prompt => Predicate.hasProperty(u, TypeId)
 
@@ -1690,8 +1708,8 @@ export const isPrompt = (u: unknown): u is Prompt => Predicate.hasProperty(u, Ty
  * 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
@@ -1704,8 +1722,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 {
   /**
@@ -1722,8 +1740,8 @@ const $Prompt = Schema.declare((u) => isPrompt(u), { identifier: "Prompt" })
 /**
  * Describes a schema that represents a `Prompt` instance.
  *
- * @since 4.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
   content: Schema.Array(Schema.toEncoded(Message))
@@ -1754,12 +1772,11 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
 )
 
 /**
- * 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"
  *
@@ -1777,8 +1794,8 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
  * const promptInput: Prompt.RawInput = existingPrompt
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type RawInput =
   | string
@@ -1802,7 +1819,8 @@ const decodeMessagesSync = Schema.decodeSync(Schema.Array(Message))
 /**
  * An empty prompt with no messages.
  *
- * @example
+ * **Example** (Creating an empty prompt)
+ *
  * ```ts
  * import { Prompt } from "effect/unstable/ai"
  *
@@ -1810,8 +1828,8 @@ const decodeMessagesSync = Schema.decodeSync(Schema.Array(Message))
  * console.log(emptyPrompt.content) // []
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: Prompt = makePrompt([])
 
@@ -1821,7 +1839,8 @@ export const empty: Prompt = makePrompt([])
  * 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"
  *
@@ -1839,8 +1858,8 @@ export const empty: Prompt = makePrompt([])
  * const copiedPrompt = Prompt.make(existingPrompt)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (input: RawInput): Prompt => {
   if (typeof input === "string") {
@@ -1861,7 +1880,8 @@ export 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"
  *
@@ -1877,19 +1897,19 @@ export const make = (input: RawInput): Prompt => {
  * const prompt = Prompt.fromMessages(messages)
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromMessages = (messages: ReadonlyArray<Message>): Prompt => makePrompt(messages)
 
 /**
- * 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"
  *
@@ -1918,8 +1938,8 @@ export const fromMessages = (messages: ReadonlyArray<Message>): Prompt => makePr
  * // Creates an assistant message with the response content
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Prompt => {
   if (parts.length === 0) {
@@ -2044,7 +2064,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
  * 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"
  *
@@ -2056,8 +2077,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
  * const merged = Prompt.concat(systemPrompt, "Hello, world!")
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const concat: {
   // =============================================================================
@@ -2070,7 +2091,8 @@ export 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"
    *
@@ -2082,8 +2104,8 @@ export const concat: {
    * const merged = Prompt.concat(systemPrompt, "Hello, world!")
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (input: RawInput): (self: Prompt) => Prompt
   // =============================================================================
@@ -2096,7 +2118,8 @@ export 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"
    *
@@ -2108,8 +2131,8 @@ export const concat: {
    * const merged = Prompt.concat(systemPrompt, "Hello, world!")
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Prompt, input: RawInput): Prompt
 } = dual(2, (self: Prompt, input: RawInput): Prompt => {
@@ -2134,7 +2157,8 @@ export 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"
  *
@@ -2153,8 +2177,8 @@ export const concat: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export const setSystem: {
   // =============================================================================
@@ -2168,7 +2192,8 @@ export 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"
    *
@@ -2187,8 +2212,8 @@ export const setSystem: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (content: string): (self: Prompt) => Prompt
   // =============================================================================
@@ -2202,7 +2227,8 @@ export 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"
    *
@@ -2221,8 +2247,8 @@ export const setSystem: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category combinators
+   * @since 4.0.0
    */
   (self: Prompt, content: string): Prompt
 } = dual(2, (self: Prompt, content: string): Prompt => {
@@ -2236,13 +2262,13 @@ export const setSystem: {
 })
 
 /**
- * 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"
  *
@@ -2262,18 +2288,18 @@ export 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 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"
    *
@@ -2293,18 +2319,18 @@ export 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"
    *
@@ -2324,8 +2350,8 @@ export 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
 } = dual(2, (self: Prompt, content: string): Prompt => {
@@ -2345,13 +2371,13 @@ export const prependSystem: {
 })
 
 /**
- * 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"
  *
@@ -2371,18 +2397,18 @@ export 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 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"
    *
@@ -2402,18 +2428,18 @@ export 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"
    *
@@ -2433,8 +2459,8 @@ export 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
 } = dual(2, (self: Prompt, content: string): Prompt => {