effect 4.0.0-beta.70 → 4.0.0-beta.71

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.
+ * Runtime schema and codec 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
  */

package/src/unstable/ai/Tokenizer.ts

@@ -1,38 +1,49 @@
 /**
- * The `Tokenizer` module provides tokenization and text truncation capabilities
- * for large language model text processing workflows.
+ * Token counting and prompt truncation for AI integrations. A tokenizer is a
+ * service because tokenization depends on the target model, provider, and
+ * encoding rules rather than on Effect itself.
  *
- * This module offers services for converting text into tokens and truncating
- * prompts based on token limits, essential for managing context length
- * constraints in large language models.
+ * **Mental model**
  *
- * **Example** (Tokenizing text)
+ * {@link Tokenizer} provides two operations over prompt input: `tokenize`
+ * converts a prompt into provider-specific token ids, and `truncate` keeps a
+ * prompt within a token budget before it is sent to a model. Implementations
+ * are usually provided by an AI provider package or by wrapping the tokenizer
+ * used by the model.
  *
- * ```ts
- * import { Effect } from "effect"
- * import { Tokenizer } from "effect/unstable/ai"
+ * **Common tasks**
  *
- * const tokenizeText = Effect.gen(function*() {
- *   const tokenizer = yield* Tokenizer.Tokenizer
- *   const tokens = yield* tokenizer.tokenize("Hello, world!")
- *   console.log(`Token count: ${tokens.length}`)
- *   return tokens
- * })
- * ```
+ * - Count prompt tokens before choosing a model or request size
+ * - Drop older conversation messages before a chat completion call
+ * - Provide a custom tokenizer with {@link make} for tests or unsupported
+ *   providers
  *
- * **Example** (Truncating a prompt)
+ * **Gotchas**
+ *
+ * - Token ids are model-specific. Counts from one tokenizer may not match
+ *   another model's tokenizer.
+ * - The `truncate` implementation produced by {@link make} keeps complete
+ *   messages from the end of the prompt; it does not split a message to fit the
+ *   remaining budget.
+ * - Programs that access {@link Tokenizer} require a tokenizer service to be
+ *   provided.
+ *
+ * **Example** (Providing a test tokenizer)
  *
  * ```ts
  * import { Effect } from "effect"
  * import { Tokenizer } from "effect/unstable/ai"
  *
- * // Truncate a prompt to fit within token limits
- * const truncatePrompt = Effect.gen(function*() {
- *   const tokenizer = yield* Tokenizer.Tokenizer
- *   const longPrompt = "This is a very long prompt..."
- *   const truncated = yield* tokenizer.truncate(longPrompt, 100)
- *   return truncated
+ * const tokenizer = Tokenizer.make({
+ *   tokenize: (prompt) =>
+ *     Effect.succeed(prompt.content.map((_, index) => index))
  * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const service = yield* Tokenizer.Tokenizer
+ *   const tokens = yield* service.tokenize("Count this prompt")
+ *   return tokens.length
+ * }).pipe(Effect.provideService(Tokenizer.Tokenizer, tokenizer))
  * ```
  *
  * @since 4.0.0

package/src/unstable/ai/Tool.ts

@@ -1,28 +1,57 @@
 /**
- * The `Tool` module provides functionality for defining and managing tools
- * that language models can call to augment their capabilities.
- *
- * This module enables creation of both user-defined and provider-defined tools,
- * with full schema validation, type safety, and handler support. Tools allow
- * AI models to perform actions like searching databases, calling APIs, or
- * executing code within your application context.
- *
- * **Example** (Defining a calculator tool)
+ * The `Tool` module describes callable capabilities that a language model can
+ * request during a workflow. A tool definition names the operation, describes
+ * its parameter shape, declares the success and failure payloads, and carries
+ * annotations that providers or MCP adapters can expose to clients.
+ *
+ * **Mental model**
+ *
+ * - `Tool.make` defines an application-owned tool whose handler is supplied by
+ *   a toolkit.
+ * - `dynamic` represents tools discovered at runtime, including tools backed by
+ *   raw JSON Schema.
+ * - `providerDefined` represents native provider features such as web search or
+ *   code execution, optionally with an application handler for returned data.
+ * - Schemas validate tool-call parameters and encode/decode handler results;
+ *   `failureMode` controls whether handler failures fail the effect or become a
+ *   returned tool-result value.
+ *
+ * **Common tasks**
+ *
+ * - Define typed application tools with {@link make}.
+ * - Register runtime-discovered tools with {@link dynamic}.
+ * - Model provider-native tools with {@link providerDefined}.
+ * - Generate provider-facing parameter JSON Schema with {@link getJsonSchema}.
+ * - Add tool metadata with annotations such as {@link Title}, {@link Readonly},
+ *   {@link Destructive}, {@link Idempotent}, {@link OpenWorld}, and
+ *   {@link Strict}.
+ *
+ * **Gotchas**
+ *
+ * - Tool names are runtime lookup keys for toolkits; choose stable names.
+ * - Tool definitions do not execute anything by themselves. Handlers are bound
+ *   when tools are placed in a toolkit.
+ * - Dynamic tools created from raw JSON Schema receive `unknown` parameters in
+ *   handlers. Use Effect `Schema` values when you need typed parameters.
+ * - Provider-defined tools have both a custom Effect name and a provider name
+ *   so multiple providers can expose similarly named native tools.
+ *
+ * **Example** (Defining a typed tool)
  *
  * ```ts
  * import { Schema } from "effect"
  * import { Tool } from "effect/unstable/ai"
  *
- * // Define a simple calculator tool
- * const Calculator = Tool.make("Calculator", {
- *   description: "Performs basic arithmetic operations",
+ * const SearchDocs = Tool.make("SearchDocs", {
+ *   description: "Search project documentation",
  *   parameters: Schema.Struct({
- *     operation: Schema.Literals(["add", "subtract", "multiply", "divide"]),
- *     a: Schema.Number,
- *     b: Schema.Number
+ *     query: Schema.String,
+ *     limit: Schema.optional(Schema.Number)
  *   }),
- *   success: Schema.Number
- * })
+ *   success: Schema.Array(Schema.String),
+ *   failure: Schema.String,
+ *   needsApproval: ({ limit }) => limit !== undefined && limit > 20
+ * }).annotate(Tool.Readonly, true)
  * ```
  *
  * @since 4.0.0
@@ -1289,7 +1318,7 @@ export const make = <
  *
  * **When to use**
  *
- * This is useful for tools where the schema isn't known at compile time,
+ * Use when this is useful for tools where the schema isn't known at compile time,
  * such as MCP tools discovered at runtime or tools from external configurations.
  *
  * **Details**
@@ -1334,7 +1363,7 @@ export const dynamic: {
    *
    * **When to use**
    *
-   * This is useful for tools where the schema isn't known at compile time,
+   * Use when this is useful for tools where the schema isn't known at compile time,
    * such as MCP tools discovered at runtime or tools from external configurations.
    *
    * **Details**
@@ -1901,6 +1930,18 @@ export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Str
 /**
  * Returns the strict mode setting for a tool, or `undefined` if not set.
  *
+ * **When to use**
+ *
+ * Use to inspect the per-tool strict JSON Schema override attached through
+ * `Tool.Strict`.
+ *
+ * **Gotchas**
+ *
+ * `undefined` means no per-tool override is set. It is distinct from `false`;
+ * provider or global configuration determines the final behavior.
+ *
+ * @see {@link Strict} for the annotation read by this helper
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -1983,8 +2024,17 @@ function filter(obj: any) {
 }
 
 /**
- * **Unsafe**: This function will throw an error if an insecure property is
- * found in the parsed JSON or if the provided JSON text is not parseable.
+ * Parses JSON text while rejecting prototype-pollution keys.
+ *
+ * **When to use**
+ *
+ * Use when thrown parse and security failures are acceptable.
+ *
+ * **Gotchas**
+ *
+ * Invalid JSON throws through `JSON.parse`. Parsed objects containing an own
+ * `__proto__` property or a dangerous `constructor.prototype` shape throw a
+ * `SyntaxError`.
  *
  * @category utils
  * @since 4.0.0
@@ -2016,6 +2066,17 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
 /**
  * A schema for tools that accept no parameters.
  *
+ * **When to use**
+ *
+ * Use when a tool needs an explicit no-parameter `parameters` schema.
+ *
+ * **Details**
+ *
+ * This is `Schema.Record(Schema.String, Schema.Never)`, representing an empty
+ * object parameter shape with no additional properties.
+ *
+ * @see {@link make} for the tool constructor that defaults omitted parameters to this schema
+ *
  * @category schemas
  * @since 4.0.0
  */

package/src/unstable/ai/Toolkit.ts

@@ -1,7 +1,35 @@
 /**
- * The `Toolkit` module allows for creating and implementing a collection of
- * `Tool`s which can be used to enhance the capabilities of a large language
- * model beyond simple text generation.
+ * The `Toolkit` module groups AI `Tool` definitions into a single typed service
+ * that can execute tool calls by name. A toolkit is the runtime bridge between
+ * declarative tool schemas and the handler functions your application provides
+ * for a language model workflow.
+ *
+ * **Mental model**
+ *
+ * - A `Tool` describes one callable operation: its name, parameter schema,
+ *   success schema, and failure behavior.
+ * - A `Toolkit` is a record of tools that also carries the handler requirements
+ *   needed to execute those tools.
+ * - `toolkit.toLayer(...)` and `toolkit.toHandlers(...)` bind handlers into
+ *   `Context`, so yielding a toolkit produces a value with a `handle` function.
+ * - `handle` validates parameters, runs the matching handler, and returns a
+ *   `Stream` of preliminary and final encoded results.
+ *
+ * **Common tasks**
+ *
+ * - Build a toolkit from tools: {@link make}
+ * - Merge independently defined toolkits: {@link merge}
+ * - Provide handlers with `toolkit.toLayer(...)` or `toolkit.toHandlers(...)`
+ * - Emit progress from a long-running handler with `context.preliminary(...)`
+ *
+ * **Gotchas**
+ *
+ * - Tool names are runtime lookup keys. When toolkits are merged, later tools
+ *   replace earlier tools with the same name.
+ * - Handler output is validated and encoded against the tool schemas; invalid
+ *   output is reported as an AI error.
+ * - The result of `handle` is a stream because handlers can emit preliminary
+ *   results before the final value.
  *
  * **Example** (Creating and implementing toolkits)
  *
@@ -469,7 +497,7 @@ const resolveInput = <Tools extends ReadonlyArray<Tool.Any>>(
  *
  * **When to use**
  *
- * Useful as a starting point for building toolkits or as a default value. Can
+ * Use as a starting point for building toolkits or as a default value. Can
  * be extended using the merge function to add tools.
  *
  * @category constructors