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

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
+ *
+ * **Gotchas**
  *
- * **Example** (Truncating a prompt)
+ * - 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
@@ -44,7 +55,12 @@ import type * as AiError from "./AiError.ts"
 import * as Prompt from "./Prompt.ts"
 
 /**
- * The `Tokenizer` service tag for dependency injection.
+ * Service tag for model tokenization services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide model-specific token counting and prompt truncation
+ * operations.
  *
  * **Details**
  *
@@ -64,7 +80,7 @@ import * as Prompt from "./Prompt.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class Tokenizer extends Context.Service<Tokenizer, Service>()(

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**
@@ -1556,8 +1585,8 @@ export const providerDefined = <
 // =============================================================================
 
 /**
- * A utility which allows mapping between a provider-defined name for a tool
- * and the name given to the tool by the Effect AI SDK.
+ * Maps between a provider-defined tool name and the name given to the tool by
+ * the Effect AI SDK.
  *
  * **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
@@ -2014,7 +2064,18 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
 export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
 
 /**
- * A schema for tools that accept no parameters.
+ * 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