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

package/dist/unstable/ai/Response.d.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 Schema from "../../Schema.ts";
@@ -34,36 +35,36 @@ declare const PartTypeId: "~effect/ai/Content/Part";
 /**
  * Type guard to check if a value is a Response Part.
  *
- * @since 1.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isPart: (u: unknown) => u is AnyPart;
 /**
  * Union type representing all possible response content parts.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyPart = TextPart | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallPart<any, any> | ToolResultPart<any, any, any> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart;
 /**
  * Encoded representation of all possible response content parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnyPartEncoded = TextPartEncoded | TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded;
 /**
  * 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 | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallParts<Tools> | ToolResultParts<Tools> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart;
 /**
  * Encoded representation of all response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AllPartsEncoded = TextPartEncoded | TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded;
 /**
@@ -72,7 +73,8 @@ export type AllPartsEncoded = TextPartEncoded | TextStartPartEncoded | TextDelta
  * 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"
@@ -87,58 +89,58 @@ export type AllPartsEncoded = TextPartEncoded | TextStartPartEncoded | TextDelta
  * const allPartsSchema = Response.AllParts(myToolkit)
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const AllParts: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T) => Schema.Codec<AllParts<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>, AllPartsEncoded, Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>, Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>>;
 /**
  * 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 | ReasoningPart | ToolCallParts<Tools> | ToolResultParts<Tools> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart;
 /**
  * Encoded representation of non-streaming response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type PartEncoded = TextPartEncoded | ReasoningPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded;
 /**
  * Creates a Schema for non-streaming response parts based on a toolkit.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const Part: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T) => Schema.Codec<Part<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>, PartEncoded, Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>, Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>>;
 /**
  * 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 | TextDeltaPart | TextEndPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallParts<Tools> | ToolResultParts<Tools> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart;
 /**
  * Encoded representation of streaming response parts for serialization.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type StreamPartEncoded = TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded;
 /**
  * Creates a Schema for streaming response parts based on a toolkit.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const StreamPart: <T extends Toolkit.Any | Toolkit.WithHandler<any>>(toolkit: T) => Schema.Codec<StreamPart<T extends Toolkit.Any ? Toolkit.Tools<T> : Toolkit.WithHandlerTools<T>>, StreamPartEncoded, Tool.ResultDecodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>, Tool.ResultEncodingServices<Toolkit.Tools<T>[keyof Toolkit.Tools<T>]>>;
 /**
  * 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]>> : never;
@@ -146,32 +148,26 @@ 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 ? ToolResultPart<Name, Tool.Success<Tools[Name]>, Tool.FailureResult<Tools[Name]>> : never;
 }[keyof Tools];
 /**
- * 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 declare const ProviderMetadata: Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<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;
 /**
@@ -179,8 +175,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;
@@ -196,8 +192,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> {
     /**
@@ -212,7 +208,8 @@ export interface BasePartEncoded<Type extends string, Metadata extends ProviderM
 /**
  * Creates a new response content part of the specified type.
  *
- * @example
+ * **Example** (Creating response content parts)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -228,8 +225,8 @@ export interface BasePartEncoded<Type extends string, Metadata extends ProviderM
  * })
  * ```
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makePart: <const Type extends AnyPart["type"]>(
 /**
@@ -255,8 +252,8 @@ params: Omit<Extract<AnyPart, {
  * 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"> & {
     /**
@@ -267,7 +264,8 @@ export type ConstructorParams<Part extends AnyPart> = Omit<Part, typeof PartType
 /**
  * Response part representing plain text content.
  *
- * @example
+ * **Example** (Creating a text part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -276,8 +274,8 @@ export type ConstructorParams<Part extends AnyPart> = Omit<Part, typeof PartType
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TextPart extends BasePart<"text", TextPartMetadata> {
     /**
@@ -288,8 +286,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> {
     /**
@@ -301,16 +299,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 declare const TextPart: Schema.Struct<{
     readonly type: Schema.tag<"text">;
@@ -323,8 +321,8 @@ export declare 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> {
     /**
@@ -335,8 +333,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> {
     /**
@@ -348,16 +346,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 declare const TextStartPart: Schema.Struct<{
     readonly type: Schema.tag<"text-start">;
@@ -369,8 +367,8 @@ export declare 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> {
     /**
@@ -385,8 +383,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> {
     /**
@@ -402,16 +400,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 declare const TextDeltaPart: Schema.Struct<{
     readonly type: Schema.tag<"text-delta">;
@@ -425,8 +423,8 @@ export declare 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> {
     /**
@@ -437,8 +435,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> {
     /**
@@ -450,16 +448,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 declare const TextEndPart: Schema.Struct<{
     readonly type: Schema.tag<"text-end">;
@@ -468,12 +466,12 @@ export declare const TextEndPart: Schema.Struct<{
     readonly metadata: Schema.withDecodingDefault<Schema.$Record<Schema.String, Schema.Codec<Schema.Json>>>;
 }>;
 /**
- * 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"
  *
@@ -483,8 +481,8 @@ export declare const TextEndPart: Schema.Struct<{
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ReasoningPart extends BasePart<"reasoning", ReasoningPartMetadata> {
     /**
@@ -495,8 +493,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> {
     /**
@@ -508,16 +506,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 declare const ReasoningPart: Schema.Struct<{
     readonly type: Schema.tag<"reasoning">;
@@ -530,8 +528,8 @@ export declare 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> {
     /**
@@ -542,8 +540,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> {
     /**
@@ -555,16 +553,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 declare const ReasoningStartPart: Schema.Struct<{
     readonly type: Schema.tag<"reasoning-start">;
@@ -576,8 +574,8 @@ export declare 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> {
     /**
@@ -592,8 +590,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> {
     /**
@@ -609,16 +607,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 declare const ReasoningDeltaPart: Schema.Struct<{
     readonly type: Schema.tag<"reasoning-delta">;
@@ -632,8 +630,8 @@ export declare 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> {
     /**
@@ -644,8 +642,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> {
     /**
@@ -657,16 +655,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 declare const ReasoningEndPart: Schema.Struct<{
     readonly type: Schema.tag<"reasoning-end">;
@@ -680,8 +678,8 @@ export declare 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> {
     /**
@@ -701,8 +699,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> {
     /**
@@ -723,16 +721,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 declare const ToolParamsStartPart: Schema.Struct<{
     readonly type: Schema.tag<"tool-params-start">;
@@ -748,8 +746,8 @@ export declare 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> {
     /**
@@ -764,8 +762,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> {
     /**
@@ -781,16 +779,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 declare const ToolParamsDeltaPart: Schema.Struct<{
     readonly type: Schema.tag<"tool-params-delta">;
@@ -805,8 +803,8 @@ export declare 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> {
     /**
@@ -817,8 +815,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> {
     /**
@@ -830,16 +828,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 declare const ToolParamsEndPart: Schema.Struct<{
     readonly type: Schema.tag<"tool-params-end">;
@@ -850,7 +848,8 @@ export declare 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"
@@ -874,8 +873,8 @@ export declare 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> {
     /**
@@ -899,8 +898,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> {
     /**
@@ -925,16 +924,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 declare const ToolCallPart: <const Name extends string, Params extends Schema.Top>(name: Name, params: Params) => Schema.Struct<{
     readonly type: Schema.Literal<"tool-call">;
@@ -948,15 +947,15 @@ export declare const ToolCallPart: <const Name extends string, Params extends Sc
 /**
  * Constructs a new tool call part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolCallPart: <const Name extends string, Params>(params: ConstructorParams<ToolCallPart<Name, Params>>) => ToolCallPart<Name, 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> {
     /**
@@ -990,8 +989,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> {
     /**
@@ -1006,8 +1005,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> {
     /**
@@ -1022,7 +1021,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"
  *
@@ -1055,15 +1055,15 @@ 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> | ToolResultFailure<Name, 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> {
     /**
@@ -1098,16 +1098,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 declare const ToolResultPart: <const Name extends string, Success extends Schema.Top, Failure extends Schema.Top>(name: Name, success: Success, failure: Failure) => Schema.decodeTo<Schema.Struct<{
     readonly "~effect/ai/Content/Part": Schema.Literal<"~effect/ai/Content/Part">;
@@ -1133,8 +1133,8 @@ export declare const ToolResultPart: <const Name extends string, Success extends
 /**
  * Constructs a new tool result part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolResultPart: <const Params extends ConstructorParams<ToolResultPart<string, unknown, unknown>>>(params: Params) => Params extends {
     readonly name: infer Name extends string;
@@ -1152,7 +1152,8 @@ export declare const toolResultPart: <const Params extends ConstructorParams<Too
  * 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"
  *
@@ -1165,8 +1166,8 @@ export declare const toolResultPart: <const Params extends ConstructorParams<Too
  * )
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ToolApprovalRequestPart extends BasePart<"tool-approval-request", ToolApprovalRequestPartMetadata> {
     /**
@@ -1181,8 +1182,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> {
     /**
@@ -1198,16 +1199,16 @@ export interface ToolApprovalRequestPartEncoded extends BasePartEncoded<"tool-ap
  * 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 declare const ToolApprovalRequestPart: Schema.Struct<{
     readonly type: Schema.tag<"tool-approval-request">;
@@ -1219,8 +1220,8 @@ export declare const ToolApprovalRequestPart: Schema.Struct<{
 /**
  * Constructs a new tool approval request part.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const toolApprovalRequestPart: (params: ConstructorParams<ToolApprovalRequestPart>) => ToolApprovalRequestPart;
 /**
@@ -1228,7 +1229,8 @@ export declare const toolApprovalRequestPart: (params: ConstructorParams<ToolApp
  *
  * Supports various file types including images, documents, and binary data.
  *
- * @example
+ * **Example** (Creating a file part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -1238,8 +1240,8 @@ export declare const toolApprovalRequestPart: (params: ConstructorParams<ToolApp
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FilePart extends BasePart<"file", FilePartMetadata> {
     /**
@@ -1254,8 +1256,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> {
     /**
@@ -1271,16 +1273,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 declare const FilePart: Schema.Struct<{
     readonly type: Schema.tag<"file">;
@@ -1294,8 +1296,8 @@ export declare 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> {
     /**
@@ -1322,8 +1324,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> {
     /**
@@ -1351,16 +1353,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 declare const DocumentSourcePart: Schema.Struct<{
     readonly type: Schema.tag<"source">;
@@ -1377,8 +1379,8 @@ export declare 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> {
     /**
@@ -1401,8 +1403,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> {
     /**
@@ -1426,16 +1428,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 declare const UrlSourcePart: Schema.Struct<{
     readonly type: Schema.tag<"source">;
@@ -1453,7 +1455,8 @@ export declare 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"
  *
@@ -1466,8 +1469,8 @@ export declare const UrlSourcePart: Schema.Struct<{
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const HttpRequestDetails: Schema.Struct<{
     readonly method: Schema.Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"]>;
@@ -1483,7 +1486,8 @@ export declare 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"
  *
@@ -1496,8 +1500,8 @@ export declare const HttpRequestDetails: Schema.Struct<{
  * }
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export declare const HttpResponseDetails: Schema.Struct<{
     readonly status: Schema.Number;
@@ -1506,7 +1510,8 @@ export declare 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"
@@ -1522,8 +1527,8 @@ export declare const HttpResponseDetails: Schema.Struct<{
  * )
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ResponseMetadataPart extends BasePart<"response-metadata", ResponseMetadataPartMetadata> {
     /**
@@ -1546,8 +1551,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> {
     /**
@@ -1571,16 +1576,16 @@ export interface ResponseMetadataPartEncoded extends BasePartEncoded<"response-m
  * 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 declare const ResponseMetadataPart: Schema.Struct<{
     readonly type: Schema.tag<"response-metadata">;
@@ -1604,8 +1609,8 @@ export declare 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 declare const FinishReason: Schema.Literals<[
     "stop",
@@ -1618,8 +1623,14 @@ export declare const FinishReason: Schema.Literals<[
     "unknown"
 ]>;
 /**
- * @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;
 declare const Usage_base: Schema.Class<Usage, Schema.Struct<{
@@ -1669,15 +1680,16 @@ declare const Usage_base: Schema.Class<Usage, Schema.Struct<{
  * 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 declare class Usage extends Usage_base {
 }
 /**
  * Response part indicating the completion of a response generation.
  *
- * @example
+ * **Example** (Creating a finish part)
+ *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
@@ -1700,8 +1712,8 @@ export declare class Usage extends Usage_base {
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
     /**
@@ -1720,8 +1732,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> {
     /**
@@ -1741,16 +1753,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 declare const FinishPart: Schema.Struct<{
     readonly type: Schema.tag<"finish">;
@@ -1772,7 +1784,8 @@ export declare 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"
  *
@@ -1781,8 +1794,8 @@ export declare const FinishPart: Schema.Struct<{
  * })
  * ```
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ErrorPart extends BasePart<"error", ErrorPartMetadata> {
     readonly error: unknown;
@@ -1790,8 +1803,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;
@@ -1800,16 +1813,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 declare const ErrorPart: Schema.Struct<{
     readonly type: Schema.tag<"error">;