effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -56,34 +56,36 @@ import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Rec from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import * as Tool from "./Tool.ts"
 
 /**
- * Transforms a `Schema.Codec` into a form compatible with OpenAI's structured output constraints.
+ * Converts a `Schema.Codec` to OpenAI structured-output JSON Schema and a
+ * matching codec for model output.
+ *
+ * **When to use**
+ *
+ * Use when you send Effect Schema-backed structured output requests to OpenAI
+ * and need provider-compatible JSON Schema without losing the decoded
+ * application type.
  *
  * **Details**
  *
- * The transformation walks the schema AST and rewrites constructs that
- * OpenAI does not support natively:
+ * Returns the JSON Schema to include in the request and the codec to use when
+ * decoding the model response. If the input schema already fits OpenAI's
+ * supported JSON Schema subset, the original codec is returned unchanged.
  *
- * - **Tuples** are converted to objects with numeric string keys (e.g.
- *   `"0"`, `"1"`) since OpenAI does not support tuple schemas. Rest
- *   elements are placed under a `"__rest__"` key.
- * - **Optional properties** are replaced with `T | null` unions, because
- *   OpenAI requires all properties to be present.
- * - **Records** (index signatures) are converted to arrays of `[key, value]`
- *   pairs.
- * - **`oneOf` unions** are rewritten as `anyOf` unions.
- * - **Regex patterns** from multiple filters are merged into a single
- *   `pattern` using lookaheads, since OpenAI does not support `allOf`.
- * - **Filters and annotations** are preserved where compatible (e.g.
- *   `description`, supported `format` values like `"date-time"`, `"email"`,
- *   `"uuid"`, etc.), and stripped otherwise.
+ * **Gotchas**
  *
- * If the schema is already compatible, the original codec is returned
- * unchanged.
+ * - Some schemas use a provider-safe encoded shape: tuples become objects with
+ *   numeric string keys, records become arrays of `[key, value]` pairs, and
+ *   optional properties become required nullable properties.
+ * - `oneOf` unions are emitted as `anyOf` unions.
+ * - Regex patterns from multiple filters are merged into one `pattern` because
+ *   OpenAI structured output does not support `allOf`.
+ * - Unsupported schema kinds throw during conversion instead of producing a
+ *   lossy schema.
  *
  * @category Codec Transformation
  * @since 4.0.0
@@ -95,8 +97,10 @@ export function toCodecOpenAI<T, E, RD, RE>(
   jsonSchema: JsonSchema.JsonSchema
 } {
   const to = schema.ast
-  const from = recurOpenAI(AST.toEncoded(to))
-  const codec = from === to ? schema : Schema.make<typeof schema>(AST.decodeTo(from, to, Transformation.passthrough()))
+  const from = recurOpenAI(SchemaAST.toEncoded(to))
+  const codec = from === to
+    ? schema
+    : Schema.make<typeof schema>(SchemaAST.decodeTo(from, to, SchemaTransformation.passthrough()))
   const document = JsonSchema.resolveTopLevel$ref(Schema.toJsonSchemaDocument(codec))
   const jsonSchema = rewriteOpenAI(document.schema)
   if (Object.keys(document.definitions).length > 0) {
@@ -136,7 +140,7 @@ function rewriteOpenAI(schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
   return out
 }
 
-function recurOpenAI(ast: AST.AST): AST.AST {
+function recurOpenAI(ast: SchemaAST.AST): SchemaAST.AST {
   switch (ast._tag) {
     case "Declaration":
     case "Void":
@@ -163,14 +167,14 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     case "String": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.String(annotations, filters)
+        return new SchemaAST.String(annotations, filters)
       }
       return ast
     }
     case "Number": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.Number(annotations, filters)
+        return new SchemaAST.Number(annotations, filters)
       }
       return ast
     }
@@ -181,7 +185,7 @@ function recurOpenAI(ast: AST.AST): AST.AST {
       if (typeof literal === "string" || typeof literal === "number" || typeof literal === "boolean") {
         const { annotations, filters } = get(ast)
         if (annotations !== undefined || filters !== undefined) {
-          return new AST.Literal(ast.literal, annotations, filters)
+          return new SchemaAST.Literal(ast.literal, annotations, filters)
         }
         return ast
       }
@@ -193,12 +197,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     }
     case "Union": {
       if (ast.mode === "oneOf") {
-        return new AST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
+        return new SchemaAST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
       }
-      const types = AST.mapOrSame(ast.types, recurOpenAI)
+      const types = SchemaAST.mapOrSame(ast.types, recurOpenAI)
       const { annotations, filters } = get(ast)
       if (types !== ast.types || annotations !== undefined || filters !== undefined) {
-        return new AST.Union(types, "anyOf", annotations, filters)
+        return new SchemaAST.Union(types, "anyOf", annotations, filters)
       }
       return ast
     }
@@ -218,15 +222,17 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           annotations.description = TUPLE_DESCRIPTION
         }
         const propertySignatures = ast.elements.map((e, i) => {
-          return new AST.PropertySignature(String(i), e)
+          return new SchemaAST.PropertySignature(String(i), e)
         })
         if (ast.rest.length === 1) {
-          propertySignatures.push(new AST.PropertySignature(REST_PROPERTY_NAME, new AST.Arrays(false, [], ast.rest)))
+          propertySignatures.push(
+            new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], ast.rest))
+          )
         }
-        return AST.decodeTo(
-          recurOpenAI(new AST.Objects(propertySignatures, [], annotations, filters)),
+        return SchemaAST.decodeTo(
+          recurOpenAI(new SchemaAST.Objects(propertySignatures, [], annotations, filters)),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: (o) => {
               let t: Array<unknown> = []
               for (let i = 0; i < ast.elements.length; i++) {
@@ -255,9 +261,9 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           })
         )
       } else {
-        const rest = AST.mapOrSame(ast.rest, recurOpenAI)
+        const rest = SchemaAST.mapOrSame(ast.rest, recurOpenAI)
         if (rest !== ast.rest || annotations !== undefined || filters !== undefined) {
-          return new AST.Arrays(false, [], rest, annotations, filters)
+          return new SchemaAST.Arrays(false, [], rest, annotations, filters)
         }
         return ast
       }
@@ -265,7 +271,7 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     case "Objects": {
       let { annotations, filters } = get(ast)
       if (ast.indexSignatures.length === 0) {
-        const propertySignatures = AST.mapOrSame(ast.propertySignatures, (ps) => {
+        const propertySignatures = SchemaAST.mapOrSame(ast.propertySignatures, (ps) => {
           if (typeof ps.name !== "string") {
             throw new Error(
               `${errorPrefix}: Property names must be strings (got ${typeof ps.name})`
@@ -273,11 +279,11 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           }
           let type = recurOpenAI(ps.type)
           // optional properties are not supported by OpenAI, so we translate them to nullable unions
-          if (AST.isOptional(ps.type)) {
-            type = AST.decodeTo(
-              new AST.Union([type, AST.null], "anyOf"),
-              AST.optionalKey(type),
-              Transformation.transformOptional({
+          if (SchemaAST.isOptional(ps.type)) {
+            type = SchemaAST.decodeTo(
+              new SchemaAST.Union([type, SchemaAST.null], "anyOf"),
+              SchemaAST.optionalKey(type),
+              SchemaTransformation.transformOptional({
                 decode: Option.filter(Predicate.isNotNull),
                 encode: Option.orElseSome(() => null)
               })
@@ -286,12 +292,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           if (type === ps.type) {
             return ps
           }
-          return new AST.PropertySignature(ps.name, type)
+          return new SchemaAST.PropertySignature(ps.name, type)
         })
         if (
           propertySignatures !== ast.propertySignatures || annotations !== undefined || filters !== undefined
         ) {
-          return new AST.Objects(propertySignatures, [], annotations, filters)
+          return new SchemaAST.Objects(propertySignatures, [], annotations, filters)
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
@@ -305,10 +311,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           annotations ??= {}
           annotations.description = RECORD_DESCRIPTION
         }
-        return AST.decodeTo(
-          recurOpenAI(new AST.Arrays(false, [], [new AST.Arrays(false, [is.parameter, is.type], [])], annotations)),
+        return SchemaAST.decodeTo(
+          recurOpenAI(
+            new SchemaAST.Arrays(false, [], [new SchemaAST.Arrays(false, [is.parameter, is.type], [])], annotations)
+          ),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: Object.fromEntries,
             encode: Object.entries
           })
@@ -324,18 +332,18 @@ function recurOpenAI(ast: AST.AST): AST.AST {
       const cached = cache.get(ast)
       if (cached) return cached
       const { annotations, filters } = get(ast)
-      const out = new AST.Suspend(() => recurOpenAI(ast.thunk()), annotations, filters)
+      const out = new SchemaAST.Suspend(() => recurOpenAI(ast.thunk()), annotations, filters)
       cache.set(ast, out)
       return out
     }
   }
 }
 
-const cache = new Map<AST.AST, AST.AST>()
+const cache = new Map<SchemaAST.AST, SchemaAST.AST>()
 
 const errorPrefix = "OpenAiStructuredOutput"
 
-function unsupportedAst(ast: AST.AST, details?: string): never {
+function unsupportedAst(ast: SchemaAST.AST, details?: string): never {
   const base = `Unsupported AST ${ast._tag}`
   const full = `${errorPrefix}: ${base}`
   throw new Error(details !== undefined ? `${full} (${details})` : full)
@@ -355,17 +363,17 @@ type Annotation =
 
 type Filter =
   | Annotation
-  | { readonly _tag: "filter"; readonly filter: AST.Filter<any> }
+  | { readonly _tag: "filter"; readonly filter: SchemaAST.Filter<any> }
   | { readonly _tag: "regex"; readonly source: string }
 
-const get = (ast: AST.AST): {
+const get = (ast: SchemaAST.AST): {
   annotations: Record<string, string> | undefined
-  filters: [AST.Check<any>, ...AST.Check<any>[]] | undefined
+  filters: [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]] | undefined
 } => {
   const annotations: Record<string, string> = {}
-  const filters: Array<AST.Filter<any>> = []
+  const filters: Array<SchemaAST.Filter<any>> = []
   const regexSources: Array<string> = []
-  const checks = getChecks(ast, AST.isArrays(ast))
+  const checks = getChecks(ast, SchemaAST.isArrays(ast))
   if (checks.length > 0) {
     for (const check of checks) {
       switch (check._tag) {
@@ -394,10 +402,10 @@ const get = (ast: AST.AST): {
   }
   // OpenAI does not support allOf, so we merge multiple regex patterns into a single isPattern filter
   if (regexSources.length === 1) {
-    filters.push(AST.isPattern(new RegExp(regexSources[0])))
+    filters.push(SchemaAST.isPattern(new RegExp(regexSources[0])))
   } else if (regexSources.length > 1) {
     const combined = regexSources.map((s) => `(?=[\\s\\S]*?(?:${s}))`).join("")
-    filters.push(AST.isPattern(new RegExp(`^${combined}`)))
+    filters.push(SchemaAST.isPattern(new RegExp(`^${combined}`)))
   }
   return {
     annotations: Object.keys(annotations).length > 0 ? annotations : undefined,
@@ -405,7 +413,7 @@ const get = (ast: AST.AST): {
   }
 }
 
-const getChecks = (ast: AST.AST, isArray: boolean): Array<Filter> => [
+const getChecks = (ast: SchemaAST.AST, isArray: boolean): Array<Filter> => [
   ...(ast.checks !== undefined ? getFilters(ast.checks, isArray) : []),
   ...getAnnotations(ast.annotations)
 ]
@@ -432,7 +440,7 @@ const getAnnotations = (annotations: Schema.Annotations.Filter | undefined): Arr
   return out
 }
 
-function getFilter(filter: AST.Filter<any>, isArray: boolean): Array<Filter> {
+function getFilter(filter: SchemaAST.Filter<any>, isArray: boolean): Array<Filter> {
   let out: Array<Filter> = []
   const annotations = getAnnotations(filter.annotations)
   const meta = filter.annotations?.meta
@@ -471,7 +479,7 @@ function getFilter(filter: AST.Filter<any>, isArray: boolean): Array<Filter> {
   return out
 }
 
-function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
+function resetFilter(filter: SchemaAST.Filter<any>): SchemaAST.Filter<any> {
   return filter.annotate({
     description: undefined,
     expected: undefined,
@@ -480,7 +488,10 @@ function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
   })
 }
 
-function getFilters(checks: readonly [AST.Check<any>, ...AST.Check<any>[]], isArray: boolean): Array<Filter> {
+function getFilters(
+  checks: readonly [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]],
+  isArray: boolean
+): Array<Filter> {
   return checks.flatMap((check) => {
     switch (check._tag) {
       case "Filter":

package/src/unstable/ai/Prompt.ts

@@ -61,7 +61,7 @@ import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaIssue from "../../SchemaIssue.ts"
-import * as Parser from "../../SchemaParser.ts"
+import * as SchemaParser from "../../SchemaParser.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import type * as Response from "./Response.ts"
 
@@ -78,7 +78,7 @@ import type * as Response from "./Response.ts"
  * Provider-specific options are keyed by provider-specific names, and each
  * value is JSON or `null`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export const ProviderOptions: Schema.$Record<
@@ -90,7 +90,7 @@ export const ProviderOptions: Schema.$Record<
  * Type of provider-specific options that can be attached to prompt messages
  * and content parts.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type ProviderOptions = typeof ProviderOptions.Type
@@ -239,7 +239,7 @@ export const makePart = <const Type extends Part["type"]>(
  * A utility type for specifying the parameters required to construct a
  * specific part of a prompt.
  *
- * @category Utility Types
+ * @category utility types
  * @since 4.0.0
  */
 export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId | "type" | "options"> & {
@@ -298,7 +298,7 @@ export interface TextPartEncoded extends BasePartEncoded<"text", TextPartOptions
  * Represents provider-specific options that can be associated with a
  * `TextPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface TextPartOptions extends ProviderOptions {}
@@ -381,7 +381,7 @@ export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", Reaso
  * Represents provider-specific options that can be associated with a
  * `ReasoningPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ReasoningPartOptions extends ProviderOptions {}
@@ -490,7 +490,7 @@ export interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions
  * Represents provider-specific options that can be associated with a
  * `FilePart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface FilePartOptions extends ProviderOptions {}
@@ -607,7 +607,7 @@ export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCa
  * Represents provider-specific options that can be associated with a
  * `ToolCallPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolCallPartOptions extends ProviderOptions {}
@@ -724,7 +724,7 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
  * Represents provider-specific options that can be associated with a
  * `ToolResultPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolResultPartOptions extends ProviderOptions {}
@@ -775,8 +775,8 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  *
  * **When to use**
  *
- * Use when you use this part in tool messages to approve or deny tool execution when tools
- * have the `needsApproval` property set.
+ * Use when tool messages must approve or deny tool execution for tools with the
+ * `needsApproval` property set.
  *
  * **Example** (Creating tool approval responses)
  *
@@ -846,7 +846,7 @@ export interface ToolApprovalResponsePartEncoded
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalResponsePart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolApprovalResponsePartOptions extends ProviderOptions {}
@@ -951,7 +951,7 @@ export interface ToolApprovalRequestPartEncoded
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalRequestPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolApprovalRequestPartOptions extends ProviderOptions {}
@@ -1087,7 +1087,7 @@ export const makeMessage = <const Role extends Message["role"]>(
  * A utility type for specifying the parameters required to construct a
  * specific message for a prompt.
  *
- * @category Utility Types
+ * @category utility types
  * @since 4.0.0
  */
 export type MessageConstructorParams<M extends Message> = Omit<M, typeof MessageTypeId | "role" | "options"> & {
@@ -1176,7 +1176,7 @@ export interface SystemMessageEncoded extends BaseMessageEncoded<"system", Syste
  * Represents provider-specific options that can be associated with a
  * `SystemMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface SystemMessageOptions extends ProviderOptions {}
@@ -1289,7 +1289,7 @@ export type UserMessagePartEncoded = TextPartEncoded | FilePartEncoded
  * Represents provider-specific options that can be associated with a
  * `UserMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface UserMessageOptions extends ProviderOptions {}
@@ -1475,7 +1475,7 @@ export type AssistantMessagePartEncoded =
  * Represents provider-specific options that can be associated with a
  * `AssistantMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface AssistantMessageOptions extends ProviderOptions {}
@@ -1644,7 +1644,7 @@ export type ToolMessagePartEncoded = ToolResultPartEncoded | ToolApprovalRespons
  * Represents provider-specific options that can be associated with a
  * `ToolMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolMessageOptions extends ProviderOptions {}
@@ -1783,7 +1783,7 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
     SchemaTransformation.transformOrFail({
       decode: (input) =>
         Effect.mapBothEager(
-          Parser.decodeEffect(Schema.Array(Message))(input.content),
+          SchemaParser.decodeEffect(Schema.Array(Message))(input.content),
           {
             onSuccess: makePrompt,
             onFailure: () =>
@@ -1792,7 +1792,7 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
         ),
       encode: (prompt) =>
         Effect.mapBothEager(
-          Parser.encodeEffect(Schema.Array(Message))(prompt.content),
+          SchemaParser.encodeEffect(Schema.Array(Message))(prompt.content),
           {
             onSuccess: (messages) => ({ content: messages }),
             onFailure: () =>

package/src/unstable/ai/ResponseIdTracker.ts

@@ -83,8 +83,9 @@ export interface Service {
  *
  * **When to use**
  *
- * 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.
+ * Use when you provide a language model with previous-response ID tracking so
+ * later calls can send only new prompt messages together with the provider's
+ * prior response ID.
  *
  * @category services
  * @since 4.0.0

package/src/unstable/ai/Telemetry.ts

@@ -335,7 +335,7 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  * // Results in attributes: "custom.ai.model_name" and "custom.ai.max_tokens"
  * ```
  *
- * @category utils
+ * @category annotations
  * @since 4.0.0
  */
 export const addSpanAttributes = (
@@ -407,7 +407,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  * }
  * ```
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type GenAITelemetryAttributeOptions = BaseAttributes & {
@@ -436,10 +436,15 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
 /**
  * Applies GenAI telemetry attributes to an OpenTelemetry span.
  *
+ * **When to use**
+ *
+ * Use when you need to write GenAI request, response, token, or usage
+ * attributes onto an existing OpenTelemetry span.
+ *
  * **Details**
  *
- * This function adds standardized GenAI attributes to a span following OpenTelemetry
- * semantic conventions. It supports both curried and direct application patterns.
+ * This function adds standardized GenAI attributes to a span following
+ * OpenTelemetry semantic conventions.
  *
  * **Gotchas**
  *
@@ -462,17 +467,22 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  * })
  * ```
  *
- * @category utils
+ * @category annotations
  * @since 4.0.0
  */
 export const addGenAIAnnotations: {
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **When to use**
+   *
+   * Use when you need to write GenAI request, response, token, or usage
+   * attributes onto an existing OpenTelemetry span.
+   *
    * **Details**
    *
-   * This function adds standardized GenAI attributes to a span following OpenTelemetry
-   * semantic conventions. It supports both curried and direct application patterns.
+   * This function adds standardized GenAI attributes to a span following
+   * OpenTelemetry semantic conventions.
    *
    * **Gotchas**
    *
@@ -495,17 +505,22 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utils
+   * @category annotations
    * @since 4.0.0
    */
   (options: GenAITelemetryAttributeOptions): (span: Span) => void
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **When to use**
+   *
+   * Use when you need to write GenAI request, response, token, or usage
+   * attributes onto an existing OpenTelemetry span.
+   *
    * **Details**
    *
-   * This function adds standardized GenAI attributes to a span following OpenTelemetry
-   * semantic conventions. It supports both curried and direct application patterns.
+   * This function adds standardized GenAI attributes to a span following
+   * OpenTelemetry semantic conventions.
    *
    * **Gotchas**
    *
@@ -528,7 +543,7 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utils
+   * @category annotations
    * @since 4.0.0
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void

package/src/unstable/ai/Tokenizer.ts

@@ -80,7 +80,7 @@ import * as Prompt from "./Prompt.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class Tokenizer extends Context.Service<Tokenizer, Service>()(