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

package/src/unstable/ai/McpServer.ts

@@ -547,6 +547,27 @@ export const run: (options: {
  * `RpcServer.Protocol` and provides the `McpServer` and `McpServerClient`
  * services.
  *
+ * **When to use**
+ *
+ * Use when you already have a custom or externally provided
+ * `RpcServer.Protocol` and want to start an MCP server as part of a layer
+ * graph.
+ *
+ * **Details**
+ *
+ * The returned layer forks `run(options)` in the layer scope and merges
+ * `McpServer.layer`, so registration layers can use the `McpServer` service
+ * while the server is running.
+ *
+ * **Gotchas**
+ *
+ * Unlike `layerStdio` and `layerHttp`, this layer does not install a concrete
+ * transport. The surrounding layer graph must provide `RpcServer.Protocol`.
+ *
+ * @see {@link run} for the effect form used by this layer
+ * @see {@link layerStdio} for a stdio-backed layer that installs the MCP protocol and NDJSON-RPC serialization
+ * @see {@link layerHttp} for an HTTP-backed layer that registers with `HttpRouter` and installs JSON-RPC serialization
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -560,7 +581,7 @@ export const layer = (options: {
   )
 
 /**
- * Run the McpServer, using stdio for input and output.
+ * Runs the McpServer, using stdio for input and output.
  *
  * **Example** (Running an MCP server over stdio)
  *
@@ -628,7 +649,20 @@ export const layerStdio = (options: {
   )
 
 /**
- * Run the `McpServer`, registering a router with a `HttpRouter`
+ * Registers an HTTP POST JSON-RPC route at `options.path` on the current
+ * `HttpRouter`.
+ *
+ * **When to use**
+ *
+ * Use to expose an MCP server through an existing `HttpRouter`.
+ *
+ * **Details**
+ *
+ * This layer composes `layer(options)`, `RpcServer.layerProtocolHttp(options)`,
+ * and `RpcSerialization.layerJsonRpc()`.
+ *
+ * @see {@link layerStdio} for exposing the server over stdio
+ * @see {@link layer} for the base MCP server layer without a transport protocol
  *
  * @category layers
  * @since 4.0.0
@@ -645,7 +679,7 @@ export const layerHttp = (options: {
   )
 
 /**
- * Register a `Toolkit` with the `McpServer`.
+ * Registers a `Toolkit` with the `McpServer`.
  *
  * @category tools
  * @since 4.0.0
@@ -721,7 +755,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
 })
 
 /**
- * Register an AiToolkit with the McpServer.
+ * Registers an `AiToolkit` with the `McpServer`.
  *
  * @category tools
  * @since 4.0.0
@@ -770,14 +804,26 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Top>> = {
 }
 
 /**
- * Register a resource with the McpServer.
+ * Registers an MCP resource or resource template from an Effect program.
+ *
+ * **When to use**
+ *
+ * Use to add a resource to an existing MCP server from an Effect program.
+ *
+ * @see {@link resource} for the layer-based resource registration wrapper
  *
  * @category resources
  * @since 4.0.0
  */
 export const registerResource: {
   /**
-   * Register a resource with the McpServer.
+   * Registers an MCP resource or resource template from an Effect program.
+   *
+   * **When to use**
+   *
+   * Use to add a resource to an existing MCP server from an Effect program.
+   *
+   * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @category resources
    * @since 4.0.0
@@ -799,7 +845,13 @@ export const registerResource: {
     }
   ): Effect.Effect<void, never, Exclude<R, McpServerClient> | McpServer>
   /**
-   * Register a resource with the McpServer.
+   * Registers an MCP resource or resource template from an Effect program.
+   *
+   * **When to use**
+   *
+   * Use to add a resource to an existing MCP server from an Effect program.
+   *
+   * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @category resources
    * @since 4.0.0
@@ -940,14 +992,26 @@ export const registerResource: {
 } as any
 
 /**
- * Register a resource with the McpServer.
+ * Creates a layer that registers an MCP resource or resource template.
+ *
+ * **When to use**
+ *
+ * Use to compose resource registration into an MCP server layer.
+ *
+ * @see {@link registerResource} for the Effect-level resource registration API
  *
  * @category resources
  * @since 4.0.0
  */
 export const resource: {
   /**
-   * Register a resource with the McpServer.
+   * Creates a layer that registers an MCP resource or resource template.
+   *
+   * **When to use**
+   *
+   * Use to compose resource registration into an MCP server layer.
+   *
+   * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @category resources
    * @since 4.0.0
@@ -968,7 +1032,13 @@ export const resource: {
     }
   ): Layer.Layer<never, never, Exclude<R, McpServerClient>>
   /**
-   * Register a resource with the McpServer.
+   * Creates a layer that registers an MCP resource or resource template.
+   *
+   * **When to use**
+   *
+   * Use to compose resource registration into an MCP server layer.
+   *
+   * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @category resources
    * @since 4.0.0
@@ -1014,7 +1084,19 @@ export const resource: {
 } as any
 
 /**
- * Register a prompt with the McpServer.
+ * Registers an MCP prompt from an Effect program.
+ *
+ * **When to use**
+ *
+ * Use to register an MCP prompt from an Effect program.
+ *
+ * **Details**
+ *
+ * Parameters are decoded with the supplied schema, completion handlers encode
+ * per-parameter suggestions, and string prompt content is converted into a user
+ * text message.
+ *
+ * @see {@link prompt} for the layer-based prompt registration wrapper
  *
  * @category prompts
  * @since 4.0.0
@@ -1109,7 +1191,19 @@ export const registerPrompt = <
 }
 
 /**
- * Register a prompt with the McpServer.
+ * Creates a layer that registers an MCP prompt.
+ *
+ * **When to use**
+ *
+ * Use to compose prompt registration into an MCP server layer.
+ *
+ * **Details**
+ *
+ * Parameters are decoded with the supplied schema, completion handlers encode
+ * per-parameter suggestions, and string prompt content is converted into a user
+ * text message.
+ *
+ * @see {@link registerPrompt} for the Effect-level prompt registration API
  *
  * @category prompts
  * @since 4.0.0
@@ -1138,7 +1232,7 @@ export const prompt = <
   )
 
 /**
- * Requests structured input from the current MCP client and decodes the
+ * Collects structured input from the current MCP client and decodes the
  * accepted response with `schema`.
  *
  * **Details**
@@ -1181,7 +1275,7 @@ export const elicit: <S extends Schema.Encoder<Record<string, unknown>, unknown>
 }, Effect.scoped)
 
 /**
- * Access the current client's capabilities.
+ * Accesses the current client's capabilities.
  *
  * @category capabilities
  * @since 4.0.0

package/src/unstable/ai/Model.ts

@@ -1,30 +1,52 @@
 /**
- * The `Model` module provides a unified interface for AI service providers.
+ * The `Model` module wraps a provider-specific language model layer with the
+ * metadata Effect AI needs at runtime. A `Model` is still a `Layer`, but it
+ * also provides the current provider name and model name to programs that need
+ * to inspect or report which model is in use.
  *
- * This module enables creation of provider-specific AI models that can be used
- * interchangeably within the Effect AI ecosystem. It combines Layer
- * functionality with provider identification, allowing for seamless switching
- * between different AI service providers while maintaining type safety.
+ * **Mental model**
  *
- * **Example** (Creating a provider-specific model)
+ * - `make` combines a provider identifier, a model identifier, and a layer that
+ *   provides AI services such as `LanguageModel`.
+ * - Providing the resulting model installs both the provider services and the
+ *   metadata services {@link ProviderName} and {@link ModelName}.
+ * - `captureRequirements` lets effectful setup capture the current environment
+ *   into a concrete model layer.
+ *
+ * **Common tasks**
+ *
+ * - Create a provider-backed model with {@link make}.
+ * - Provide the model to a program with `Effect.provide`.
+ * - Read {@link ProviderName} and {@link ModelName} inside shared workflows,
+ *   telemetry, or provider-agnostic services.
+ *
+ * **Gotchas**
+ *
+ * - The provider and model names are metadata; the actual implementation still
+ *   comes from the layer passed to {@link make}.
+ * - If the underlying layer has requirements, those requirements must be
+ *   satisfied before the model can be provided.
+ *
+ * **Example** (Providing model metadata)
  *
  * ```ts
  * import { Effect } from "effect"
  * import type { Layer } from "effect"
  * import { LanguageModel, Model } from "effect/unstable/ai"
  *
- * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>
+ * declare const languageModelLayer: Layer.Layer<LanguageModel.LanguageModel>
  *
- * const anthropicModel = Model.make("anthropic", "claude-3-5-haiku", myAnthropicLayer)
+ * const model = Model.make("example-provider", "fast-text", languageModelLayer)
  *
  * const program = Effect.gen(function*() {
+ *   const provider = yield* Model.ProviderName
+ *   const modelName = yield* Model.ModelName
  *   const response = yield* LanguageModel.generateText({
- *     prompt: "Hello, world!"
+ *     prompt: `Generate with ${provider}/${modelName}`
  *   })
+ *
  *   return response.text
- * }).pipe(
- *   Effect.provide(anthropicModel)
- * )
+ * }).pipe(Effect.provide(model))
  * ```
  *
  * @since 4.0.0
@@ -42,7 +64,7 @@ const TypeId = "~effect/ai/Model" as const
  *
  * **When to use**
  *
- * Use a Model directly as a Layer to provide a particular model implementation
+ * Use when you use a Model directly as a Layer to provide a particular model implementation
  * to an Effect program, or use it as an Effect to "lift" dependencies of the
  * Model constructor into the parent Effect when you want to use a Model from
  * within an Effect service.

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -1,5 +1,52 @@
 /**
- * Provides codec transformations for OpenAI structured output.
+ * Adapt Effect Schema codecs to the JSON Schema subset accepted by OpenAI
+ * structured output.
+ *
+ * The main entry point is {@link toCodecOpenAI}. It returns a JSON Schema value
+ * for the model request and a codec that preserves the original decoded Type
+ * while changing the encoded representation when OpenAI cannot express that
+ * shape directly.
+ *
+ * **Mental model**
+ *
+ * OpenAI structured output requires a narrower schema vocabulary than Effect
+ * Schema. This module walks the schema AST before JSON Schema generation,
+ * rewrites unsupported shapes into OpenAI-compatible encodings, and
+ * post-processes the generated JSON Schema to remove constructs such as
+ * `allOf`.
+ *
+ * **Common tasks**
+ *
+ * - Convert a `Schema.Codec` for an OpenAI response format with
+ *   {@link toCodecOpenAI}
+ * - Decode model output back into the original application shape with the
+ *   returned codec
+ * - Represent optional properties as `T | null`, tuples as objects with
+ *   numeric string keys, and records as arrays of `[key, value]` pairs
+ *
+ * **Gotchas**
+ *
+ * - The returned codec may encode to a different shape than the input schema,
+ *   so use it for decoding model output instead of the original schema.
+ * - Unsupported schema kinds throw during conversion rather than producing a
+ *   lossy schema.
+ * - Optional properties are required in the emitted JSON Schema and use `null`
+ *   to represent absence because OpenAI requires object keys to be present.
+ *
+ * **Example** (Prepare a response schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { OpenAiStructuredOutput } from "effect/unstable/ai"
+ *
+ * const Weather = Schema.Struct({
+ *   city: Schema.String,
+ *   forecast: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * const output = OpenAiStructuredOutput.toCodecOpenAI(Weather)
+ * console.log(output.jsonSchema)
+ * ```
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Prompt.ts

@@ -522,7 +522,14 @@ export const FilePart: Schema.Struct<{
 }).annotate({ identifier: "FilePart" })
 
 /**
- * Constructs a new file part.
+ * Constructs a `FilePart` for prompt file attachments.
+ *
+ * **When to use**
+ *
+ * Use to create the file-attachment part of a prompt from typed file part
+ * parameters.
+ *
+ * @see {@link makePart} for the generic part constructor
  *
  * @category constructors
  * @since 4.0.0
@@ -768,7 +775,7 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  *
  * **When to use**
  *
- * Use this part in tool messages to approve or deny tool execution when tools
+ * Use when you use this part in tool messages to approve or deny tool execution when tools
  * have the `needsApproval` property set.
  *
  * **Example** (Creating tool approval responses)
@@ -1476,6 +1483,12 @@ export interface AssistantMessageOptions extends ProviderOptions {}
 /**
  * Schema for validation and encoding of assistant messages.
  *
+ * **Details**
+ *
+ * Assistant content can be a string decoded through `ContentFromString` or an
+ * array of text, file, reasoning, tool-call, tool-result, and
+ * tool-approval-request parts.
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1543,6 +1556,14 @@ export const AssistantMessage: Schema.Struct<{
 /**
  * Constructs a new assistant message.
  *
+ * **When to use**
+ *
+ * Use to add assistant-role prompt history or model responses.
+ *
+ * **Details**
+ *
+ * This is the role-specific wrapper around `makeMessage("assistant", params)`.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1749,7 +1770,7 @@ const $Prompt = Schema.declare((u) => isPrompt(u), { identifier: "Prompt" })
 // TODO: shoudn't the name be `PromptFrom...`?
 // TODO: is the explicit encoding necessary? maybe use the default JSON serializer?
 /**
- * Describes a schema that represents a `Prompt` instance.
+ * Schema for AI prompt instances.
  *
  * @category schemas
  * @since 4.0.0

package/src/unstable/ai/Response.ts

@@ -1,25 +1,49 @@
 /**
- * The `Response` module provides data structures to represent responses from
- * large language models.
+ * The `Response` module defines Effect AI's provider-neutral representation of
+ * model output. Text, reasoning, tool calls, tool results, files, source
+ * citations, metadata, finish information, usage, and provider errors are all
+ * modeled as typed response parts.
  *
- * This module defines the complete structure of AI model responses, including
- * various content parts for text, reasoning, tool calls, files, and metadata,
- * supporting both streaming and non-streaming responses.
+ * **Mental model**
  *
- * **Example** (Creating response parts)
+ * - A response is an ordered sequence of parts.
+ * - Non-streaming responses use complete parts such as `TextPart`,
+ *   `ReasoningPart`, `ToolCallPart`, `ToolResultPart`, and `FinishPart`.
+ * - Streaming responses use start, delta, and end parts for text, reasoning,
+ *   and tool parameters before final tool-call or finish parts appear.
+ * - Tool-aware schemas are built from a toolkit, so tool call parameters and
+ *   tool result payloads stay aligned with each tool definition.
+ *
+ * **Common tasks**
+ *
+ * - Construct individual parts with {@link makePart}, {@link toolCallPart},
+ *   {@link toolResultPart}, or {@link toolApprovalRequestPart}.
+ * - Decode or encode parts with {@link Part}, {@link StreamPart}, or
+ *   {@link AllParts}.
+ * - Read completion metadata from {@link FinishPart}, {@link FinishReason},
+ *   and {@link Usage}.
+ *
+ * **Gotchas**
+ *
+ * - `metadata` is reserved for provider-specific JSON and defaults to an empty
+ *   object.
+ * - Streaming text, reasoning, and tool parameter deltas are incremental events;
+ *   accumulate them before treating them as final content.
+ * - Tool result parts encode success and failure values according to the
+ *   corresponding tool schemas.
+ *
+ * **Example** (Constructing response parts)
  *
  * ```ts
  * import { Response } from "effect/unstable/ai"
  *
- * // Create a simple text response part
- * const textResponse = Response.makePart("text", {
- *   text: "The weather is sunny today!"
+ * const text = Response.makePart("text", {
+ *   text: "The weather is sunny today."
  * })
  *
- * // Create a tool call response part
- * const toolCallResponse = Response.makePart("tool-call", {
+ * const toolCall = Response.toolCallPart({
  *   id: "call_123",
- *   name: "get_weather",
+ *   name: "GetWeather",
  *   params: { city: "San Francisco" },
  *   providerExecuted: false
  * })
@@ -1889,6 +1913,11 @@ export interface FilePartMetadata extends ProviderMetadata {}
 /**
  * Schema for validation and encoding of file parts.
  *
+ * **Details**
+ *
+ * Decoded `data` is a `Uint8Array`; encoded `data` is a base64 string through
+ * `Schema.Uint8ArrayFromBase64`.
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1982,6 +2011,20 @@ export interface DocumentSourcePartMetadata extends ProviderMetadata {}
 /**
  * Schema for validation and encoding of document source parts.
  *
+ * **When to use**
+ *
+ * Use to validate or encode document source references returned as response
+ * content parts.
+ *
+ * **Details**
+ *
+ * Validates `type: "source"`, `sourceType: "document"`, required `id`,
+ * `mediaType`, and `title`, optional `fileName`, and the metadata fields
+ * inherited from response parts.
+ *
+ * @see {@link UrlSourcePart} for URL source references
+ * @see {@link DocumentSourcePartEncoded} for the encoded document source representation
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -2471,7 +2514,12 @@ export interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartM
 export interface FinishPartMetadata extends ProviderMetadata {}
 
 /**
- * Schema for validation and encoding of finish parts.
+ * Schema for finish response parts.
+ *
+ * **Details**
+ *
+ * Validates `type: "finish"`, `reason` through `FinishReason`, `usage`
+ * through `Usage`, and optional provider HTTP response details.
  *
  * @category schemas
  * @since 4.0.0
@@ -2548,6 +2596,16 @@ export interface ErrorPartMetadata extends ProviderMetadata {}
 /**
  * Schema for validation and encoding of error parts.
  *
+ * **Details**
+ *
+ * Validates and encodes error parts with `type: "error"` and an `error` payload
+ * kept as `unknown`.
+ *
+ * **Gotchas**
+ *
+ * The decoded `error` value is not guaranteed to be an `Error`; narrow it before
+ * reading `Error`-specific fields.
+ *
  * @category schemas
  * @since 4.0.0
  */

package/src/unstable/ai/ResponseIdTracker.ts

@@ -1,15 +1,37 @@
 /**
- * The `ResponseIdTracker` module provides a small service for reusing provider
- * response IDs across incremental language model calls. It records which prompt
- * message objects were sent for a provider response, then prepares a later
- * prompt by returning the recognized `previousResponseId` together with only
- * the new messages that should be sent.
- *
- * Use this when integrating providers that support continuing a conversation
- * from a prior response ID instead of resending the entire prompt. The tracker
- * is intentionally identity-based and mutable: it only recognizes the same
- * message objects that were previously marked, and it clears its state when a
- * prompt can no longer be matched safely.
+ * Track provider response IDs for incremental language model calls.
+ *
+ * Some providers can continue from a prior response by accepting a
+ * `previousResponseId` plus only the messages added after that response. This
+ * module exposes a small mutable service that remembers which prompt message
+ * objects were included in each provider response and prepares a shorter prompt
+ * when a later call extends the same conversation.
+ *
+ * **Mental model**
+ *
+ * The tracker is an optimization cache, not conversation storage. `markParts`
+ * associates the exact message objects that were sent with the response ID the
+ * provider returned. `prepareUnsafe` scans a future prompt, finds the latest
+ * assistant-message boundary whose prefix is tracked, and returns that response
+ * ID with only the messages after the boundary. If the prompt cannot be matched
+ * safely, the cache is cleared and no incremental send is attempted.
+ *
+ * **Common tasks**
+ *
+ * - Provide `ResponseIdTracker` to a language model implementation that can use
+ *   provider previous-response IDs
+ * - Mark prompt messages after a successful provider response
+ * - Prepare follow-up prompts so unchanged history is replaced by
+ *   `previousResponseId`
+ *
+ * **Gotchas**
+ *
+ * - Tracking is based on object identity; equivalent message values are not
+ *   recognized unless they are the same objects.
+ * - The service is mutable and intentionally exposes `Unsafe` methods because
+ *   callers coordinate it inside provider request/response code.
+ * - A mismatch clears tracked state to avoid reusing a response ID for the
+ *   wrong prompt prefix.
  *
  * @since 4.0.0
  */
@@ -61,7 +83,7 @@ export interface Service {
  *
  * **When to use**
  *
- * When provided, language model operations can use the tracker to send only new
+ * Use when when provided, language model operations can use the tracker to send only new
  * prompt messages together with the provider's prior response ID.
  *
  * @category services

package/src/unstable/ai/Telemetry.ts

@@ -1,34 +1,35 @@
 /**
- * The `Telemetry` module provides OpenTelemetry integration for operations
- * performed against a large language model provider by defining telemetry
- * attributes and utilities that follow the OpenTelemetry GenAI semantic
- * conventions.
+ * OpenTelemetry span annotation helpers for Effect AI operations.
  *
- * **Example** (Annotating AI spans)
+ * The `Telemetry` module models the OpenTelemetry GenAI semantic-convention
+ * attributes used by language model and embedding providers, and exposes small
+ * helpers for writing those attributes onto Effect tracing spans. It is used by
+ * provider implementations and by applications that want consistent
+ * `gen_ai.*` span metadata around model requests, responses, token usage, and
+ * provider-specific identifiers.
  *
- * ```ts
- * import { Effect } from "effect"
- * import { Telemetry } from "effect/unstable/ai"
+ * **Mental model**
  *
- * // Add telemetry attributes to a span
- * const addTelemetry = Effect.gen(function*() {
- *   const span = yield* Effect.currentSpan
+ * Attribute options are grouped by semantic-convention namespace: base
+ * `gen_ai`, `operation`, `request`, `response`, `token`, and `usage`.
+ * `addGenAIAnnotations` flattens those groups into span attributes, ignores
+ * nullish values, and converts camelCase field names to snake_case keys.
+ * `addSpanAttributes` provides the same prefix-and-transform behavior for
+ * custom namespaces.
  *
- *   Telemetry.addGenAIAnnotations(span, {
- *     system: "openai",
- *     operation: { name: "chat" },
- *     request: {
- *       model: "gpt-4",
- *       temperature: 0.7,
- *       maxTokens: 1000
- *     },
- *     usage: {
- *       inputTokens: 100,
- *       outputTokens: 50
- *     }
- *   })
- * })
- * ```
+ * **Common tasks**
+ *
+ * - Add standard GenAI attributes to the current span with
+ *   `addGenAIAnnotations`.
+ * - Create a custom attribute writer with `addSpanAttributes`.
+ * - Provide `CurrentSpanTransformer` so a language model implementation can
+ *   annotate the span after seeing the provider response.
+ *
+ * **Gotchas**
+ *
+ * These helpers annotate spans that already exist; they do not create or scope
+ * spans. Attribute writers mutate the provided span, and only non-nullish
+ * values are emitted.
  *
  * @since 4.0.0
  */
@@ -45,7 +46,12 @@ import type * as Response from "./Response.ts"
  * The attributes used to describe telemetry in the context of Generative
  * Artificial Intelligence (GenAI) models requests and responses.
  *
- * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ * **Details**
+ *
+ * These attributes follow the OpenTelemetry generative AI semantic
+ * conventions:
+ * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
+ *
  * @category models
  * @since 4.0.0
  */
@@ -577,6 +583,13 @@ export interface SpanTransformer {
  * Service tag for providing a `SpanTransformer` to large language model
  * operations.
  *
+ * **When to use**
+ *
+ * Use to retrieve or provide the current `SpanTransformer` through context for
+ * language model span annotation.
+ *
+ * @see {@link SpanTransformer} for the transformer contract provided by this service
+ *
  * @category services
  * @since 4.0.0
  */