effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/ai/Response.ts

@@ -6,7 +6,8 @@
  * various content parts for text, reasoning, tool calls, files, and metadata,
  * supporting both streaming and non-streaming responses.
  *
- * @example
+ * **Example** (Creating response parts)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -24,7 +25,7 @@
  * })
  * ```
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import type * as DateTime from "../../DateTime.ts"
 import * as Effect from "../../Effect.ts"
@@ -44,16 +45,16 @@ const PartTypeId = "~effect/ai/Content/Part" as const
 /**
  * Type guard to check if a value is a Response Part.
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isPart = (u: unknown): u is AnyPart => Predicate.hasProperty(u, PartTypeId)
 
 /**
  * Union type representing all possible response content parts.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyPart =
   | TextPart
@@ -80,8 +81,8 @@ export type AnyPart =
 /**
  * Encoded representation of all possible response content parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyPartEncoded =
   | TextPartEncoded
@@ -108,8 +109,8 @@ export type AnyPartEncoded =
 /**
  * Union type for all response parts with tool-specific typing.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AllParts<Tools extends Record<string, Tool.Any>> =
   | TextPart
@@ -136,8 +137,8 @@ export type AllParts<Tools extends Record<string, Tool.Any>> =
 /**
  * Encoded representation of all response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AllPartsEncoded =
   | TextPartEncoded
@@ -167,7 +168,8 @@ export type AllPartsEncoded =
  * Generates a schema that includes all possible response parts, with tool call
  * and tool result parts dynamically created based on the provided toolkit.
  *
- * @example
+ * **Example** (Building a response parts schema)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Response, Tool, Toolkit } from "effect/unstable/ai"
@@ -182,8 +184,8 @@ export type AllPartsEncoded =
  * const allPartsSchema = Response.AllParts(myToolkit)
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const AllParts = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
   toolkit: T
@@ -233,8 +235,8 @@ export const AllParts = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
  * A type for representing non-streaming response parts with tool-specific
  * typing.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Part<Tools extends Record<string, Tool.Any>> =
   | TextPart
@@ -251,8 +253,8 @@ export type Part<Tools extends Record<string, Tool.Any>> =
 /**
  * Encoded representation of non-streaming response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type PartEncoded =
   | TextPartEncoded
@@ -271,8 +273,8 @@ export type PartEncoded =
 /**
  * Creates a Schema for non-streaming response parts based on a toolkit.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const Part = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
   toolkit: T
@@ -311,8 +313,8 @@ export const Part = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
 /**
  * A type for representing streaming response parts with tool-specific typing.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type StreamPart<Tools extends Record<string, Tool.Any>> =
   | TextStartPart
@@ -337,8 +339,8 @@ export type StreamPart<Tools extends Record<string, Tool.Any>> =
 /**
  * Encoded representation of streaming response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type StreamPartEncoded =
   | TextStartPartEncoded
@@ -363,8 +365,8 @@ export type StreamPartEncoded =
 /**
  * Creates a Schema for streaming response parts based on a toolkit.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
   toolkit: T
@@ -411,8 +413,8 @@ export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
 /**
  * Utility type that extracts tool call parts from a set of tools.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ToolCallParts<Tools extends Record<string, Tool.Any>> = {
   [Name in keyof Tools]: Name extends string ? ToolCallPart<Name, Tool.Parameters<Tools[Name]>>
@@ -422,8 +424,8 @@ export type ToolCallParts<Tools extends Record<string, Tool.Any>> = {
 /**
  * Utility type that extracts tool result parts from a set of tools.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ToolResultParts<Tools extends Record<string, Tool.Any>> = {
   [Name in keyof Tools]: Name extends string
@@ -436,20 +438,11 @@ export type ToolResultParts<Tools extends Record<string, Tool.Any>> = {
 // =============================================================================
 
 /**
- * Schema for provider-specific metadata which can be attached to response parts.
- *
- * Provider-specific metadata is namespaced by provider and has the structure:
+ * Schema for provider-specific metadata attached to response parts,
+ * represented as a record from provider-specific keys to JSON values or `null`.
  *
- * ```
- * {
- *   "<provider-specific-key>": {
- *     // Provider-specific metadata
- *   }
- * }
- * ```
- *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ProviderMetadata: Schema.$Record<
   Schema.String,
@@ -457,8 +450,11 @@ export const ProviderMetadata: Schema.$Record<
 > = Schema.Record(Schema.String, Schema.NullOr(Schema.Json))
 
 /**
- * @since 1.0.0
+ * Type of provider-specific metadata attached to response parts, keyed by
+ * provider-specific names with JSON or `null` values.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ProviderMetadata = typeof ProviderMetadata.Type
 
@@ -467,8 +463,8 @@ export type ProviderMetadata = typeof ProviderMetadata.Type
  *
  * Provides common structure including type identifier and optional metadata.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BasePart<Type extends string, Metadata extends ProviderMetadata> {
   readonly [PartTypeId]: typeof PartTypeId
@@ -485,8 +481,8 @@ export interface BasePart<Type extends string, Metadata extends ProviderMetadata
 /**
  * Base interface for encoded response content parts.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BasePartEncoded<Type extends string, Metadata extends ProviderMetadata> {
   /**
@@ -511,7 +507,8 @@ const BasePart = Schema.Struct({
 /**
  * Creates a new response content part of the specified type.
  *
- * @example
+ * **Example** (Creating response content parts)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -527,8 +524,8 @@ const BasePart = Schema.Struct({
  * })
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makePart = <const Type extends AnyPart["type"]>(
   /**
@@ -544,20 +541,19 @@ export const makePart = <const Type extends AnyPart["type"]>(
      */
     readonly metadata?: Extract<AnyPart, { type: Type }>["metadata"] | undefined
   }
-): Extract<AnyPart, { type: Type }> =>
-  (({
-   ...params,
-   [PartTypeId]: PartTypeId,
-   type,
-   metadata: params.metadata ?? {}
-  }) as any)
+): Extract<AnyPart, { type: Type }> => (({
+  ...params,
+  [PartTypeId]: PartTypeId,
+  type,
+  metadata: params.metadata ?? {}
+}) as any)
 
 /**
  * A utility type for specifying the parameters required to construct a
  * specific response part.
  *
- * @since 1.0.0
  * @category utility types
+ * @since 4.0.0
  */
 export type ConstructorParams<Part extends AnyPart> =
   & Omit<Part, typeof PartTypeId | "type" | "sourceType" | "metadata">
@@ -575,7 +571,8 @@ export type ConstructorParams<Part extends AnyPart> =
 /**
  * Response part representing plain text content.
  *
- * @example
+ * **Example** (Creating a text part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -584,8 +581,8 @@ export type ConstructorParams<Part extends AnyPart> =
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextPart extends BasePart<"text", TextPartMetadata> {
   /**
@@ -597,8 +594,8 @@ export interface TextPart extends BasePart<"text", TextPartMetadata> {
 /**
  * Encoded representation of text parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextPartEncoded extends BasePartEncoded<"text", TextPartMetadata> {
   /**
@@ -611,16 +608,16 @@ export interface TextPartEncoded extends BasePartEncoded<"text", TextPartMetadat
  * Represents provider-specific metadata that can be associated with a
  * `TextPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface TextPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of text parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const TextPart: Schema.Struct<{
   readonly type: Schema.tag<"text">
@@ -644,8 +641,8 @@ export const TextPart: Schema.Struct<{
  *
  * Marks the beginning of a text chunk with a unique identifier.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextStartPart extends BasePart<"text-start", TextStartPartMetadata> {
   /**
@@ -657,8 +654,8 @@ export interface TextStartPart extends BasePart<"text-start", TextStartPartMetad
 /**
  * Encoded representation of text start parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextStartPartEncoded extends BasePartEncoded<"text-start", TextStartPartMetadata> {
   /**
@@ -671,16 +668,16 @@ export interface TextStartPartEncoded extends BasePartEncoded<"text-start", Text
  * Represents provider-specific metadata that can be associated with a
  * `TextStartPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface TextStartPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of text start parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const TextStartPart: Schema.Struct<{
   readonly type: Schema.tag<"text-start">
@@ -703,8 +700,8 @@ export const TextStartPart: Schema.Struct<{
  * Response part containing incremental text content to be added to the existing
  * text chunk with the same unique identifier.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextDeltaPart extends BasePart<"text-delta", TextDeltaPartMetadata> {
   /**
@@ -720,8 +717,8 @@ export interface TextDeltaPart extends BasePart<"text-delta", TextDeltaPartMetad
 /**
  * Encoded representation of text delta parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextDeltaPartEncoded extends BasePartEncoded<"text-delta", TextDeltaPartMetadata> {
   /**
@@ -738,16 +735,16 @@ export interface TextDeltaPartEncoded extends BasePartEncoded<"text-delta", Text
  * Represents provider-specific metadata that can be associated with a
  * `TextDeltaPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface TextDeltaPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of text delta parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const TextDeltaPart: Schema.Struct<{
   readonly type: Schema.tag<"text-delta">
@@ -773,8 +770,8 @@ export const TextDeltaPart: Schema.Struct<{
  *
  * Marks the completion of a text chunk.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextEndPart extends BasePart<"text-end", TextEndPartMetadata> {
   /**
@@ -786,8 +783,8 @@ export interface TextEndPart extends BasePart<"text-end", TextEndPartMetadata> {
 /**
  * Encoded representation of text end parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextEndPartEncoded extends BasePartEncoded<"text-end", TextEndPartMetadata> {
   /**
@@ -800,16 +797,16 @@ export interface TextEndPartEncoded extends BasePartEncoded<"text-end", TextEndP
  * Represents provider-specific metadata that can be associated with a
  * `TextEndPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface TextEndPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of text end parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const TextEndPart: Schema.Struct<{
   readonly type: Schema.tag<"text-end">
@@ -829,12 +826,12 @@ export const TextEndPart: Schema.Struct<{
 // =============================================================================
 
 /**
- * Response part representing reasoning or chain-of-thought content.
+ * Response part carrying provider-supplied reasoning text, such as an exposed
+ * reasoning summary or explanation. Do not assume it contains hidden
+ * chain-of-thought.
  *
- * Contains the internal reasoning process or explanation from the large
- * language model.
+ * **Example** (Creating a reasoning part)
  *
- * @example
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -844,8 +841,8 @@ export const TextEndPart: Schema.Struct<{
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartMetadata> {
   /**
@@ -857,8 +854,8 @@ export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartMetada
 /**
  * Encoded representation of reasoning parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", ReasoningPartMetadata> {
   /**
@@ -871,16 +868,16 @@ export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", Reaso
  * Represents provider-specific metadata that can be associated with a
  * `ReasoningPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ReasoningPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of reasoning parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ReasoningPart: Schema.Struct<{
   readonly type: Schema.tag<"reasoning">
@@ -904,8 +901,8 @@ export const ReasoningPart: Schema.Struct<{
  *
  * Marks the beginning of a reasoning chunk with a unique identifier.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningStartPart extends BasePart<"reasoning-start", ReasoningStartPartMetadata> {
   /**
@@ -917,8 +914,8 @@ export interface ReasoningStartPart extends BasePart<"reasoning-start", Reasonin
 /**
  * Encoded representation of reasoning start parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningStartPartEncoded extends BasePartEncoded<"reasoning-start", ReasoningStartPartMetadata> {
   /**
@@ -931,16 +928,16 @@ export interface ReasoningStartPartEncoded extends BasePartEncoded<"reasoning-st
  * Represents provider-specific metadata that can be associated with a
  * `ReasoningStartPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ReasoningStartPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of reasoning start parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ReasoningStartPart: Schema.Struct<{
   readonly type: Schema.tag<"reasoning-start">
@@ -963,8 +960,8 @@ export const ReasoningStartPart: Schema.Struct<{
  * Response part containing incremental reasoning content to be added to the
  * existing chunk of reasoning text with the same unique identifier.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningDeltaPart extends BasePart<"reasoning-delta", ReasoningDeltaPartMetadata> {
   /**
@@ -980,8 +977,8 @@ export interface ReasoningDeltaPart extends BasePart<"reasoning-delta", Reasonin
 /**
  * Encoded representation of reasoning delta parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningDeltaPartEncoded extends BasePartEncoded<"reasoning-delta", ReasoningDeltaPartMetadata> {
   /**
@@ -998,16 +995,16 @@ export interface ReasoningDeltaPartEncoded extends BasePartEncoded<"reasoning-de
  * Represents provider-specific metadata that can be associated with a
  * `ReasoningDeltaPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ReasoningDeltaPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of reasoning delta parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ReasoningDeltaPart: Schema.Struct<{
   readonly type: Schema.tag<"reasoning-delta">
@@ -1033,8 +1030,8 @@ export const ReasoningDeltaPart: Schema.Struct<{
  *
  * Marks the completion of a chunk of reasoning content.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningEndPart extends BasePart<"reasoning-end", ReasoningEndPartMetadata> {
   /**
@@ -1046,8 +1043,8 @@ export interface ReasoningEndPart extends BasePart<"reasoning-end", ReasoningEnd
 /**
  * Encoded representation of reasoning end parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningEndPartEncoded extends BasePartEncoded<"reasoning-end", ReasoningEndPartMetadata> {
   /**
@@ -1060,16 +1057,16 @@ export interface ReasoningEndPartEncoded extends BasePartEncoded<"reasoning-end"
  * Represents provider-specific metadata that can be associated with a
  * `ReasoningEndPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ReasoningEndPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of reasoning end parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ReasoningEndPart: Schema.Struct<{
   readonly type: Schema.tag<"reasoning-end">
@@ -1094,8 +1091,8 @@ export const ReasoningEndPart: Schema.Struct<{
  * Marks the beginning of tool parameter streaming with metadata about the tool
  * call.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsStartPart extends BasePart<"tool-params-start", ToolParamsStartPartMetadata> {
   /**
@@ -1116,8 +1113,8 @@ export interface ToolParamsStartPart extends BasePart<"tool-params-start", ToolP
 /**
  * Encoded representation of tool params start parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsStartPartEncoded extends BasePartEncoded<"tool-params-start", ToolParamsStartPartMetadata> {
   /**
@@ -1139,16 +1136,16 @@ export interface ToolParamsStartPartEncoded extends BasePartEncoded<"tool-params
  * Represents provider-specific metadata that can be associated with a
  * `ToolParamsStartPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolParamsStartPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of tool params start parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolParamsStartPart: Schema.Struct<{
   readonly type: Schema.tag<"tool-params-start">
@@ -1180,8 +1177,8 @@ export const ToolParamsStartPart: Schema.Struct<{
  * Represents a chunk of tool parameters being streamed, containing the
  * incremental JSON content that forms the tool parameters.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsDeltaPart extends BasePart<"tool-params-delta", ToolParamsDeltaPartMetadata> {
   /**
@@ -1197,8 +1194,8 @@ export interface ToolParamsDeltaPart extends BasePart<"tool-params-delta", ToolP
 /**
  * Encoded representation of tool params delta parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsDeltaPartEncoded extends BasePartEncoded<"tool-params-delta", ToolParamsDeltaPartMetadata> {
   /**
@@ -1215,16 +1212,16 @@ export interface ToolParamsDeltaPartEncoded extends BasePartEncoded<"tool-params
  * Represents provider-specific metadata that can be associated with a
  * `ToolParamsDeltaPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolParamsDeltaPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of tool params delta parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolParamsDeltaPart: Schema.Struct<{
   readonly type: Schema.tag<"tool-params-delta">
@@ -1254,8 +1251,8 @@ export const ToolParamsDeltaPart: Schema.Struct<{
  * Marks the completion of a tool parameter stream, indicating that all
  * parameter data has been sent and the tool call is ready to be executed.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsEndPart extends BasePart<"tool-params-end", ToolParamsEndPartMetadata> {
   /**
@@ -1267,8 +1264,8 @@ export interface ToolParamsEndPart extends BasePart<"tool-params-end", ToolParam
 /**
  * Encoded representation of tool params end parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolParamsEndPartEncoded extends BasePartEncoded<"tool-params-end", ToolParamsEndPartMetadata> {
   /**
@@ -1281,16 +1278,16 @@ export interface ToolParamsEndPartEncoded extends BasePartEncoded<"tool-params-e
  * Represents provider-specific metadata that can be associated with a
  * `ToolParamsEndPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolParamsEndPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of tool params end parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolParamsEndPart: Schema.Struct<{
   readonly type: Schema.tag<"tool-params-end">
@@ -1312,7 +1309,8 @@ export const ToolParamsEndPart: Schema.Struct<{
 /**
  * Response part representing a tool call request.
  *
- * @example
+ * **Example** (Creating a tool call part)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { Response } from "effect/unstable/ai"
@@ -1336,8 +1334,8 @@ export const ToolParamsEndPart: Schema.Struct<{
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolCallPart<Name extends string, Params> extends BasePart<"tool-call", ToolCallPartMetadata> {
   /**
@@ -1362,8 +1360,8 @@ export interface ToolCallPart<Name extends string, Params> extends BasePart<"too
 /**
  * Encoded representation of tool call parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCallPartMetadata> {
   /**
@@ -1389,16 +1387,16 @@ export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCa
  * Represents provider-specific metadata that can be associated with a
  * `ToolCallPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolCallPartMetadata extends ProviderMetadata {}
 
 /**
  * Creates a Schema for tool call parts with specific tool name and parameters.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolCallPart: <const Name extends string, Params extends Schema.Top>(
   name: Name,
@@ -1431,8 +1429,8 @@ export const ToolCallPart: <const Name extends string, Params extends Schema.Top
 /**
  * Constructs a new tool call part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolCallPart = <const Name extends string, Params>(
   params: ConstructorParams<ToolCallPart<Name, Params>>
@@ -1445,8 +1443,8 @@ export const toolCallPart = <const Name extends string, Params>(
 /**
  * The base fields of a tool result part.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface BaseToolResult<Name extends string> extends BasePart<"tool-result", ToolResultPartMetadata> {
   /**
@@ -1481,8 +1479,8 @@ export interface BaseToolResult<Name extends string> extends BasePart<"tool-resu
 /**
  * Represents a successful tool call result.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultSuccess<Name extends string, Success> extends BaseToolResult<Name> {
   /**
@@ -1498,8 +1496,8 @@ export interface ToolResultSuccess<Name extends string, Success> extends BaseToo
 /**
  * Represents a failed tool call result.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultFailure<Name extends string, Failure> extends BaseToolResult<Name> {
   /**
@@ -1515,7 +1513,8 @@ export interface ToolResultFailure<Name extends string, Failure> extends BaseToo
 /**
  * Response part representing the result of a tool call.
  *
- * @example
+ * **Example** (Creating a tool result part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -1548,8 +1547,8 @@ export interface ToolResultFailure<Name extends string, Failure> extends BaseToo
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type ToolResultPart<Name extends string, Success, Failure> =
   | ToolResultSuccess<Name, Success>
@@ -1558,8 +1557,8 @@ export type ToolResultPart<Name extends string, Success, Failure> =
 /**
  * Encoded representation of tool result parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", ToolResultPartMetadata> {
   /**
@@ -1595,16 +1594,16 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
  * Represents provider-specific metadata that can be associated with a
  * `ToolResultPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolResultPartMetadata extends ProviderMetadata {}
 
 /**
  * Creates a Schema for tool result parts with specific tool name and result type.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolResultPart: <const Name extends string, Success extends Schema.Top, Failure extends Schema.Top>(
   name: Name,
@@ -1698,8 +1697,8 @@ export const ToolResultPart: <const Name extends string, Success extends Schema.
 /**
  * Constructs a new tool result part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolResultPart = <const Params extends ConstructorParams<ToolResultPart<string, unknown, unknown>>>(
   params: Params
@@ -1726,7 +1725,8 @@ export const toolResultPart = <const Params extends ConstructorParams<ToolResult
  * checks the tool's `needsApproval` property and emits this part instead of
  * executing the tool when approval is required.
  *
- * @example
+ * **Example** (Creating an approval request part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -1739,8 +1739,8 @@ export const toolResultPart = <const Params extends ConstructorParams<ToolResult
  * )
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request", ToolApprovalRequestPartMetadata> {
   /**
@@ -1756,8 +1756,8 @@ export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request
 /**
  * Encoded representation of tool approval request parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPartEncoded
   extends BasePartEncoded<"tool-approval-request", ToolApprovalRequestPartMetadata>
@@ -1776,16 +1776,16 @@ export interface ToolApprovalRequestPartEncoded
  * Represents provider-specific metadata that can be associated with a
  * `ToolApprovalRequestPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of tool approval request parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ToolApprovalRequestPart: Schema.Struct<{
   readonly type: Schema.tag<"tool-approval-request">
@@ -1808,8 +1808,8 @@ export const ToolApprovalRequestPart: Schema.Struct<{
 /**
  * Constructs a new tool approval request part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const toolApprovalRequestPart = (
   params: ConstructorParams<ToolApprovalRequestPart>
@@ -1824,7 +1824,8 @@ export const toolApprovalRequestPart = (
  *
  * Supports various file types including images, documents, and binary data.
  *
- * @example
+ * **Example** (Creating a file part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -1834,8 +1835,8 @@ export const toolApprovalRequestPart = (
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePart extends BasePart<"file", FilePartMetadata> {
   /**
@@ -1851,8 +1852,8 @@ export interface FilePart extends BasePart<"file", FilePartMetadata> {
 /**
  * Encoded representation of file parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePartEncoded extends BasePartEncoded<"file", FilePartMetadata> {
   /**
@@ -1869,16 +1870,16 @@ export interface FilePartEncoded extends BasePartEncoded<"file", FilePartMetadat
  * Represents provider-specific metadata that can be associated with a
  * `FilePart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface FilePartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of file parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const FilePart: Schema.Struct<{
   readonly type: Schema.tag<"file">
@@ -1904,8 +1905,8 @@ export const FilePart: Schema.Struct<{
  *
  * Used to reference documents that were used in generating the response.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface DocumentSourcePart extends BasePart<"source", DocumentSourcePartMetadata> {
   /**
@@ -1933,8 +1934,8 @@ export interface DocumentSourcePart extends BasePart<"source", DocumentSourcePar
 /**
  * Encoded representation of document source parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface DocumentSourcePartEncoded extends BasePartEncoded<"source", DocumentSourcePartMetadata> {
   /**
@@ -1963,16 +1964,16 @@ export interface DocumentSourcePartEncoded extends BasePartEncoded<"source", Doc
  * Represents provider-specific metadata that can be associated with a
  * `DocumentSourcePart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface DocumentSourcePartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of document source parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const DocumentSourcePart: Schema.Struct<{
   readonly type: Schema.tag<"source">
@@ -2004,8 +2005,8 @@ export const DocumentSourcePart: Schema.Struct<{
  *
  * Used to reference web URLs that were used in generating the response.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface UrlSourcePart extends BasePart<"source", UrlSourcePartMetadata> {
   /**
@@ -2029,8 +2030,8 @@ export interface UrlSourcePart extends BasePart<"source", UrlSourcePartMetadata>
 /**
  * Encoded representation of URL source parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface UrlSourcePartEncoded extends BasePartEncoded<"source", UrlSourcePartMetadata> {
   /**
@@ -2055,16 +2056,16 @@ export interface UrlSourcePartEncoded extends BasePartEncoded<"source", UrlSourc
  * Represents provider-specific metadata that can be associated with a
  * `UrlSourcePart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface UrlSourcePartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of url source parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const UrlSourcePart: Schema.Struct<{
   readonly type: Schema.tag<"source">
@@ -2096,7 +2097,8 @@ export const UrlSourcePart: Schema.Struct<{
  * AI provider, enabling inspection of request metadata for debugging and
  * observability purposes.
  *
- * @example
+ * **Example** (Describing an HTTP request)
+ *
  * ```ts
  * import type { Response } from "effect/unstable/ai"
  *
@@ -2109,8 +2111,8 @@ export const UrlSourcePart: Schema.Struct<{
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const HttpRequestDetails = Schema.Struct({
   method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]),
@@ -2133,7 +2135,8 @@ export const HttpRequestDetails = Schema.Struct({
  * the AI provider, including status codes and headers for debugging and
  * observability purposes.
  *
- * @example
+ * **Example** (Describing an HTTP response)
+ *
  * ```ts
  * import type { Response } from "effect/unstable/ai"
  *
@@ -2146,8 +2149,8 @@ export const HttpRequestDetails = Schema.Struct({
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const HttpResponseDetails = Schema.Struct({
   status: Schema.Number,
@@ -2167,7 +2170,8 @@ export const HttpResponseDetails = Schema.Struct({
 /**
  * Response part containing metadata about the large language model response.
  *
- * @example
+ * **Example** (Creating a metadata part)
+ *
  * ```ts
  * import { DateTime } from "effect"
  * import { Response } from "effect/unstable/ai"
@@ -2183,8 +2187,8 @@ export const HttpResponseDetails = Schema.Struct({
  * )
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ResponseMetadataPart extends BasePart<"response-metadata", ResponseMetadataPartMetadata> {
   /**
@@ -2208,8 +2212,8 @@ export interface ResponseMetadataPart extends BasePart<"response-metadata", Resp
 /**
  * Encoded representation of response metadata parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ResponseMetadataPartEncoded
   extends BasePartEncoded<"response-metadata", ResponseMetadataPartMetadata>
@@ -2236,16 +2240,16 @@ export interface ResponseMetadataPartEncoded
  * Represents provider-specific metadata that can be associated with a
  * `ResponseMetadataPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ResponseMetadataPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of response metadata parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ResponseMetadataPart: Schema.Struct<{
   readonly type: Schema.tag<"response-metadata">
@@ -2286,8 +2290,8 @@ export const ResponseMetadataPart: Schema.Struct<{
  * - `"other"`: The model stopped for a reason not supported by this protocol.
  * - `"unknown"`: The model did not specify a finish reason.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export const FinishReason: Schema.Literals<[
   "stop",
@@ -2310,8 +2314,14 @@ export const FinishReason: Schema.Literals<[
 ])
 
 /**
- * @since 1.0.0
+ * Type of the reason why a model stopped generating a response.
+ *
+ * Values include normal stops, token-limit stops, content filtering,
+ * tool-call pauses, provider errors, and unknown provider-specific finish
+ * reasons.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type FinishReason = typeof FinishReason.Type
 
@@ -2322,8 +2332,8 @@ export type FinishReason = typeof FinishReason.Type
  * specified here, you can generally find that information under the provider
  * metadata of the finish part of the response.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
   /**
@@ -2369,7 +2379,8 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
 /**
  * Response part indicating the completion of a response generation.
  *
- * @example
+ * **Example** (Creating a finish part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -2392,8 +2403,8 @@ export class Usage extends Schema.Class<Usage>("effect/ai/AiResponse/Usage")({
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
   /**
@@ -2413,8 +2424,8 @@ export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
 /**
  * Encoded representation of finish parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartMetadata> {
   /**
@@ -2435,16 +2446,16 @@ export interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartM
  * Represents provider-specific metadata that can be associated with a
  * `FinishPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface FinishPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of finish parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const FinishPart: Schema.Struct<{
   readonly type: Schema.tag<"finish">
@@ -2479,7 +2490,8 @@ export const FinishPart: Schema.Struct<{
 /**
  * Response part indicating that an error occurred generating the response.
  *
- * @example
+ * **Example** (Creating an error part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -2488,8 +2500,8 @@ export const FinishPart: Schema.Struct<{
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ErrorPart extends BasePart<"error", ErrorPartMetadata> {
   readonly error: unknown
@@ -2498,8 +2510,8 @@ export interface ErrorPart extends BasePart<"error", ErrorPartMetadata> {
 /**
  * Encoded representation of error parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ErrorPartEncoded extends BasePartEncoded<"error", ErrorPartMetadata> {
   readonly error: unknown
@@ -2509,16 +2521,16 @@ export interface ErrorPartEncoded extends BasePartEncoded<"error", ErrorPartMeta
  * Represents provider-specific metadata that can be associated with a
  * `ErrorPart` through module augmentation.
  *
- * @since 1.0.0
- * @category provider options
+ * @category configuration
+ * @since 4.0.0
  */
 export interface ErrorPartMetadata extends ProviderMetadata {}
 
 /**
  * Schema for validation and encoding of error parts.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const ErrorPart: Schema.Struct<{
   readonly type: Schema.tag<"error">