effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/ai/Chat.ts

@@ -1,48 +1,58 @@
 /**
- * The `Chat` module provides a stateful conversation interface for AI language
- * models.
+ * Stateful conversation sessions on top of a language model.
  *
- * This module enables persistent chat sessions that maintain conversation
- * history, support tool calling, and offer both streaming and non-streaming
- * text generation. It integrates seamlessly with the Effect AI ecosystem,
- * providing type-safe conversational AI capabilities.
+ * A `Chat` keeps `Prompt` history in a `Ref` and reuses it for text generation,
+ * streaming, and structured output. Each generation call combines the current
+ * history with the caller's new prompt, invokes the active language model, and
+ * appends the response parts back into history. Constructors create fresh
+ * sessions, seed sessions from prompts, restore exported history, or connect a
+ * chat to persistence.
  *
- * **Example** (Creating a chat session)
+ * **Mental model**
+ *
+ * A {@link Service} is a mutable conversation handle. It stores history, while
+ * the language model implementation is still supplied through the Effect
+ * environment when `generateText`, `streamText`, or `generateObject` runs.
+ * Local sessions created with {@link empty} and {@link fromPrompt} live only in
+ * memory; persisted sessions add a backing store and save after generation.
+ *
+ * **Common tasks**
+ *
+ * - Start an empty session with {@link empty}.
+ * - Seed system prompts or prior messages with {@link fromPrompt}.
+ * - Restore saved history with {@link fromExport} or {@link fromJson}.
+ * - Persist sessions by providing {@link Persistence} with {@link makePersisted}
+ *   or {@link layerPersisted}.
+ *
+ * **Example** (Starting a chat session)
  *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
  *
- * // Create a new chat session
  * const program = Effect.gen(function*() {
- *   const chat = yield* Chat.empty
+ *   const chat = yield* Chat.fromPrompt([{
+ *     role: "system",
+ *     content: "Answer in one sentence."
+ *   }])
  *
- *   // Send a message and get response
  *   const response = yield* chat.generateText({
- *     prompt: "Hello! What can you help me with?"
+ *     prompt: "What does Effect provide for TypeScript applications?"
  *   })
  *
- *   console.log(response.content)
+ *   const saved = yield* chat.exportJson
  *
- *   return response
+ *   return { text: response.text, saved }
  * })
  * ```
  *
- * **Example** (Streaming chat responses)
+ * **Gotchas**
  *
- * ```ts
- * import { Effect, Stream } from "effect"
- * import { Chat } from "effect/unstable/ai"
- *
- * // Streaming chat with tool support
- * const streamingChat = Effect.gen(function*() {
- *   const chat = yield* Chat.empty
- *
- *   yield* chat.streamText({
- *     prompt: "Generate a creative story"
- *   }).pipe(Stream.runForEach((part) => Effect.sync(() => console.log(part))))
- * })
- * ```
+ * Generation requires a language model service in the environment. `streamText`
+ * records the parts emitted by the stream when the stream finalizes, so consume
+ * the stream to completion when the full assistant response should become part
+ * of history. Direct writes to `history` are possible, but bypass the helpers
+ * that encode, decode, export, and persist the conversation.
  *
  * @since 4.0.0
  */
@@ -69,7 +79,12 @@ import type * as Response from "./Response.ts"
 import type * as Tool from "./Tool.ts"
 
 /**
- * The `Chat` service tag for dependency injection.
+ * Service tag for stateful AI conversation sessions.
+ *
+ * **When to use**
+ *
+ * Use to access or provide conversational AI sessions through the Effect
+ * context.
  *
  * **Details**
  *
@@ -92,7 +107,7 @@ import type * as Tool from "./Tool.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class Chat extends Context.Service<Chat, Service>()(
@@ -102,6 +117,15 @@ export class Chat extends Context.Service<Chat, Service>()(
 /**
  * Represents the interface that the `Chat` service provides.
  *
+ * **When to use**
+ *
+ * Use as the service contract for code that receives or constructs a stateful
+ * chat session and needs history, export, text generation, streaming, and
+ * structured-output operations.
+ *
+ * @see {@link Chat} for the context tag that provides this service
+ * @see {@link Persisted} for the persistence-backed extension
+ *
  * @category models
  * @since 4.0.0
  */
@@ -481,7 +505,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  *
  * **When to use**
  *
- * This is the most common way to start a fresh chat session without
+ * Use when this is the most common way to start a fresh chat session without
  * any initial context or system prompts.
  *
  * **Example** (Creating an empty chat)
@@ -675,9 +699,14 @@ export const fromJson = (data: string): Effect.Effect<
 // =============================================================================
 
 /**
- * An error that occurs when attempting to retrieve a persisted `Chat` that
+ * Represents an error that occurs when attempting to retrieve a persisted `Chat` that
  * does not exist in the backing persistence store.
  *
+ * **When to use**
+ *
+ * Use to represent a missing persisted conversation when lookup by id cannot
+ * find stored history.
+ *
  * @category errors
  * @since 4.0.0
  */
@@ -689,9 +718,14 @@ export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
 }) {}
 
 /**
- * The context tag for chat persistence.
+ * Service tag for persistence-backed AI conversation storage.
+ *
+ * **When to use**
  *
- * @category services
+ * Use to provide the storage operations needed by persisted conversation
+ * sessions.
+ *
+ * @category tags
  * @since 4.0.0
  */
 // @effect-diagnostics effect/leakingRequirements:off
@@ -761,11 +795,19 @@ export interface Persisted extends Service {
 /**
  * Creates a new chat persistence service.
  *
+ * **When to use**
+ *
+ * Use to construct the `Chat.Persistence` service from the current
+ * `BackingPersistence` when you want to create and retrieve persisted chats
+ * programmatically by chat id.
+ *
  * **Details**
  *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
+ * @see {@link layerPersisted} for the `Layer`-based constructor
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -916,11 +958,18 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
 /**
  * Creates a `Layer` for a new chat persistence service.
  *
+ * **When to use**
+ *
+ * Use to provide `Chat.Persistence` from a configured `BackingPersistence` when
+ * your application needs persisted chat sessions backed by a named store.
+ *
  * **Details**
  *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
+ * @see {@link makePersisted} for the effect constructor when building the service directly instead of providing it as a layer
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/ai/EmbeddingModel.ts

@@ -1,18 +1,50 @@
 /**
- * The `EmbeddingModel` module provides provider-agnostic text embedding capabilities.
+ * The `EmbeddingModel` module defines the provider-neutral service for turning
+ * text into embedding vectors. It exposes single-input `embed` and ordered
+ * batch `embedMany` operations, and keeps provider failures represented as
+ * `AiError` values.
  *
- * **Example** (Embedding text with a model)
+ * **Mental model**
+ *
+ * Providers supply one batch embedding function through `make`. The module
+ * derives single-input `embed` calls from a request resolver, so concurrent
+ * single-input requests can be batched into one provider call. Provider
+ * vectors are wrapped as `EmbedResponse` values, while `EmbedManyResponse`
+ * preserves input order and carries token usage when the provider reports it.
+ *
+ * **Common tasks**
+ *
+ * - Build an `EmbeddingModel` service from a provider implementation.
+ * - Use `embed` for one query or document, and `embedMany` when the caller
+ *   already has a batch.
+ * - Read `Dimensions` when downstream code needs the configured vector size.
+ *
+ * **Example** (Building a small embedding model)
  *
  * ```ts
  * import { Effect } from "effect"
  * import { EmbeddingModel } from "effect/unstable/ai"
  *
  * const program = Effect.gen(function*() {
- *   const model = yield* EmbeddingModel.EmbeddingModel
- *   return yield* model.embed("hello world")
+ *   const model = yield* EmbeddingModel.make({
+ *     embedMany: ({ inputs }) =>
+ *       Effect.succeed({
+ *         results: inputs.map((input) => [input.length]),
+ *         usage: { inputTokens: inputs.join(" ").length }
+ *       })
+ *   })
+ *
+ *   const response = yield* model.embed("hello")
+ *   return response.vector
  * })
  * ```
  *
+ * **Gotchas**
+ *
+ * - `embedMany([])` returns an empty response without invoking the provider.
+ * - Provider batch responses must contain exactly one vector for each input,
+ *   in the same order as the input array.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -26,6 +58,15 @@ import * as AiError from "./AiError.ts"
 /**
  * Service tag for embedding model operations.
  *
+ * **When to use**
+ *
+ * Use to retrieve or provide an `EmbeddingModel.Service` when an `Effect`
+ * program needs to embed text into vectors.
+ *
+ * @see {@link Service} for the service contract provided by this tag
+ * @see {@link make} for constructing an embedding model service from a provider
+ * @see {@link Dimensions} for the current embedding vector size service
+ *
  * @category services
  * @since 4.0.0
  */
@@ -36,6 +77,13 @@ export class EmbeddingModel extends Context.Service<EmbeddingModel, Service>()(
 /**
  * Service tag that provides the current embedding dimensions.
  *
+ * **When to use**
+ *
+ * Use to retrieve or provide the configured embedding vector size through
+ * context.
+ *
+ * @see {@link EmbeddingModel} for the embedding service that uses these dimensions
+ *
  * @category services
  * @since 4.0.0
  */
@@ -44,7 +92,13 @@ export class Dimensions extends Context.Service<Dimensions, number>()(
 ) {}
 
 /**
- * Token usage metadata for embedding operations.
+ * Represents token usage metadata for embedding operations.
+ *
+ * **Details**
+ *
+ * Contains optional provider-reported `inputTokens`. The value may be
+ * `undefined` when the provider does not report usage or when `embedMany([])`
+ * bypasses the provider.
  *
  * @category models
  * @since 4.0.0
@@ -68,7 +122,16 @@ export class EmbedResponse extends Schema.Class<EmbedResponse>(
 }) {}
 
 /**
- * Response for multiple embeddings.
+ * Response for batch embedding requests containing per-input embeddings and usage
+ * metadata.
+ *
+ * **Details**
+ *
+ * `embeddings` preserves batch order, and `usage` carries token metadata for
+ * the operation.
+ *
+ * @see {@link EmbedResponse} for individual embedding responses
+ * @see {@link EmbeddingUsage} for token usage metadata
  *
  * @category models
  * @since 4.0.0
@@ -104,7 +167,16 @@ export interface ProviderResponse {
 }
 
 /**
- * Tagged request used by request resolvers for embedding operations.
+ * Represents a tagged request used by request resolvers for embedding operations.
+ *
+ * **When to use**
+ *
+ * Use when building or calling a low-level embedding request resolver and you
+ * need a typed request for one input that resolves to `EmbedResponse`.
+ *
+ * @see {@link Service} for the resolver-bearing service contract
+ * @see {@link make} for constructing the request resolver from a provider implementation
+ * @see {@link EmbedResponse} for the response produced by this request
  *
  * @category constructors
  * @since 4.0.0
@@ -116,7 +188,7 @@ export class EmbeddingRequest extends Request.TaggedClass("EmbeddingRequest")<
 > {}
 
 /**
- * Service interface for embedding operations.
+ * Defines the service interface for embedding operations.
  *
  * @category models
  * @since 4.0.0
@@ -137,6 +209,30 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
 /**
  * Creates an EmbeddingModel service from a provider embedMany implementation.
  *
+ * **When to use**
+ *
+ * Use to adapt a provider's batch embedding implementation into an
+ * `EmbeddingModel.Service` that offers single-input and batch embedding
+ * operations.
+ *
+ * **Details**
+ *
+ * The returned service builds single-input `embed` calls through a request
+ * resolver, so concurrent `embed` requests can be batched into one provider
+ * `embedMany` call. Direct `embedMany` calls pass the input array to the
+ * provider, while `embedMany([])` returns an empty response without calling the
+ * provider.
+ *
+ * **Gotchas**
+ *
+ * Provider responses are interpreted positionally and must contain exactly one
+ * result for each requested input. If the provider returns a different number
+ * of results, `embed` and `embedMany` fail with `AiError.InvalidOutputError`.
+ *
+ * @see {@link Service} for the service shape returned by this constructor
+ * @see {@link ProviderOptions} for the input passed to the provider implementation
+ * @see {@link ProviderResponse} for the provider response contract consumed by this constructor
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/ai/IdGenerator.ts

@@ -55,7 +55,12 @@ import * as Predicate from "../../Predicate.ts"
 import * as Random from "../../Random.ts"
 
 /**
- * The `IdGenerator` service tag for dependency injection.
+ * Service tag for AI identifier generation services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide the service that creates identifiers for AI tool
+ * calls and related generated values.
  *
  * **Details**
  *
@@ -76,7 +81,7 @@ import * as Random from "../../Random.ts"
  * })
  * ```
  *
- * @category models
+ * @category tags
  * @since 4.0.0
  */
 export class IdGenerator extends Context.Service<IdGenerator, Service>()(
@@ -301,7 +306,7 @@ export const make = Effect.fnUntraced(function*({
  *
  * **When to use**
  *
- * This is the recommended way to provide ID generation capabilities to your
+ * Use when this is the recommended way to provide ID generation capabilities to your
  * application. The layer will fail during construction if the configuration is
  * invalid.
  *

package/src/unstable/ai/LanguageModel.ts

@@ -82,7 +82,12 @@ import * as Toolkit from "./Toolkit.ts"
 // =============================================================================
 
 /**
- * The `LanguageModel` service key for dependency injection, providing access to text generation, streaming, and structured output capabilities throughout an application.
+ * Service tag for AI model services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide text generation, streaming generation, structured
+ * output, and tool-calling capabilities through the Effect context.
  *
  * **Example** (Accessing the language model service)
  *
@@ -99,7 +104,7 @@ import * as Toolkit from "./Toolkit.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class LanguageModel extends Context.Service<LanguageModel, Service>()(
@@ -234,6 +239,20 @@ export type CodecTransformer = <T, E, RD, RE>(schema: Schema.Codec<T, E, RD, RE>
  * The default codec transformer that passes schemas through without
  * provider-specific rewrites.
  *
+ * **When to use**
+ *
+ * Use as the codec transformer for provider implementations when the provider
+ * accepts the JSON Schema generated from an `Effect` Schema codec without
+ * provider-specific rewrites.
+ *
+ * **Details**
+ *
+ * The transformer returns the original codec, resolves a top-level `$ref`, and
+ * copies schema definitions into `$defs`.
+ *
+ * @see {@link CodecTransformer} for the structured-output transformer contract
+ * @see {@link make} for where this transformer is used as the default
+ *
  * @category services
  * @since 4.0.0
  */
@@ -286,7 +305,7 @@ export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
    *
    * **When to use**
    *
-   * Use this when you want to include tool call definitions from an `AiToolkit`
+   * Use when you want to include tool call definitions from an `AiToolkit`
    * in requests to the large language model, while controlling tool call
    * resolver execution yourself.
    */
@@ -734,7 +753,32 @@ export interface ProviderOptions {
 }
 
 /**
- * Creates a LanguageModel service from provider-specific text generation and streaming implementations.
+ * Creates a LanguageModel service from provider-specific text generation and
+ * streaming implementations.
+ *
+ * **When to use**
+ *
+ * Use to build a `LanguageModel.Service` from provider-specific final and
+ * streaming text generation functions.
+ *
+ * **Details**
+ *
+ * The returned service implements `generateText`, `generateObject`, and
+ * `streamText`. It prepares `ProviderOptions` for each request, including the
+ * normalized prompt, tools, tool choice, response format, tracing span, and
+ * incremental response fields, before calling the supplied provider hook.
+ * Structured object generation uses the `generateText` hook and the configured
+ * `codecTransformer`, or `defaultCodecTransformer` when none is supplied.
+ *
+ * **Gotchas**
+ *
+ * Provider hooks must return encoded response parts that match the toolkit and
+ * response format prepared in `ProviderOptions`; invalid parts fail decoding as
+ * `AiError.InvalidOutputError`.
+ *
+ * @see {@link Service} for the returned service contract
+ * @see {@link ProviderOptions} for the normalized options passed to provider hooks
+ * @see {@link defaultCodecTransformer} for the default structured-output schema transformer
  *
  * @category constructors
  * @since 4.0.0
@@ -1582,7 +1626,7 @@ export const make: (params: {
 // =============================================================================
 
 /**
- * Generate text using a language model.
+ * Generates text using a language model.
  *
  * **Example** (Generating text with options)
  *
@@ -1651,7 +1695,7 @@ export const generateText: {
   )
 
 /**
- * Generate a structured object from a schema using a language model.
+ * Generates a structured object from a schema using a language model.
  *
  * **Example** (Generating an object)
  *
@@ -1703,7 +1747,7 @@ export const generateObject = <
   ) as any
 
 /**
- * Generate text using a language model with streaming output.
+ * Generates text using a language model with streaming output.
  *
  * **Details**
  *