effect 4.0.0-beta.100 → 4.0.0-beta.102

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -3,24 +3,18 @@
  * structured output.
  *
  * The main entry point returns the JSON Schema to send to Anthropic and a codec
- * for decoding the model response back into the original application type. When
- * Anthropic cannot express the original schema shape directly, the conversion
- * rewrites supported cases such as tuples, records, optional properties, and
- * `oneOf` unions. Schema kinds that cannot be represented throw during
- * conversion instead of producing a lossy schema.
+ * for decoding the model response back into the original application type.
+ * Unsupported constraints can be omitted from the provider schema and remain
+ * enforced by the returned codec.
  *
  * @since 4.0.0
  */
-import * as Arr from "../../Array.ts"
 import * as JsonSchema from "../../JsonSchema.ts"
-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 SchemaAST from "../../SchemaAST.ts"
-import * as SchemaTransformation from "../../SchemaTransformation.ts"
+import * as InternalStructuredOutput from "./internal/structured-output.ts"
 import * as LanguageModel from "./LanguageModel.ts"
 import * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
-import * as Tool from "./Tool.ts"
 
 /**
  * Converts a `Schema.Codec` to Anthropic structured-output JSON Schema and a
@@ -35,17 +29,21 @@ import * as Tool from "./Tool.ts"
  * **Details**
  *
  * 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 Anthropic's
- * supported JSON Schema subset, the original codec is returned unchanged.
+ * decoding the model response. The codec remains authoritative: the provider
+ * JSON Schema can be a lossy, less restrictive representation when Anthropic
+ * cannot express an Effect Schema constraint.
  *
  * **Gotchas**
  *
  * - 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.
+ *   numeric string keys, objects with index signatures become arrays of
+ *   `[key, value]` pairs, and optional properties become required nullable
+ *   properties.
  * - `oneOf` unions are emitted as `anyOf` unions.
- * - Unsupported schema kinds throw during conversion instead of producing a
- *   lossy schema.
+ * - Unsupported constraints are removed from the provider schema and are still
+ *   checked while decoding with the returned codec.
+ * - Recursive schemas throw during conversion because Anthropic structured
+ *   output does not support recursive references.
  *
  * @see {@link LanguageModel.CodecTransformer} for the structured-output transformer contract
  * @see {@link OpenAiStructuredOutput.toCodecOpenAI} for the OpenAI-specific transformer
@@ -59,349 +57,120 @@ export function toCodecAnthropic<T, E, RD, RE>(
   readonly codec: Schema.ConstraintCodec<T, unknown, RD, RE>
   readonly jsonSchema: JsonSchema.JsonSchema
 } {
-  const to = schema.ast
-  const from = recur(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 = { ...document.schema }
+  const codec = InternalStructuredOutput.toCodec(schema)
+  const unresolvedDocument = Schema.toJsonSchemaDocument(codec, { generateDescriptions: true })
+  if (hasReferenceCycle(unresolvedDocument.schema, unresolvedDocument.definitions)) {
+    throw new Error("AnthropicStructuredOutput: Recursive schemas are not supported")
+  }
+  const document = JsonSchema.resolveTopLevel$ref(unresolvedDocument)
+  const jsonSchema = rewriteAnthropic(document.schema)
   if (Object.keys(document.definitions).length > 0) {
-    jsonSchema.$defs = document.definitions
+    jsonSchema.$defs = Rec.map(document.definitions, rewriteAnthropic)
   }
   return { codec, jsonSchema }
 }
 
-function recur(ast: SchemaAST.AST): SchemaAST.AST {
-  switch (ast._tag) {
-    case "Declaration":
-    case "Void":
-    case "Never":
-    case "Unknown":
-    case "Any":
-    case "BigInt":
-    case "Symbol":
-    case "UniqueSymbol":
-    case "ObjectKeyword":
-    case "Enum":
-    case "TemplateLiteral":
-    case "Suspend":
-      return unsupportedAst(
-        ast,
-        "Anthropic structured output does not support this schema kind; consider transforming the schema or using a different provider"
-      )
-    case "Undefined":
-      return unsupportedAst(
-        ast,
-        "Anthropic structured output does not support undefined; consider transforming the schema or using a different provider; if using `Schema.optional`, consider using `Schema.optionalKey` instead"
-      )
-    case "Null":
-      return ast
-    case "String": {
-      const { annotations, filters } = get(ast)
-      if (annotations !== undefined || filters !== undefined) {
-        return new SchemaAST.String(annotations, filters)
-      }
-      return ast
-    }
-    case "Number": {
-      const { annotations, filters } = get(ast)
-      if (annotations !== undefined || filters !== undefined) {
-        return new SchemaAST.Number(annotations, filters)
-      }
-      return ast
-    }
-    case "Boolean":
-      return ast
-    case "Literal": {
-      const literal = ast.literal
-      if (typeof literal === "string" || typeof literal === "number" || typeof literal === "boolean") {
-        const { annotations, filters } = get(ast)
-        if (annotations !== undefined || filters !== undefined) {
-          return new SchemaAST.Literal(ast.literal, annotations, filters)
-        }
-        return ast
-      }
-      throw new Error(
-        `${errorPrefix}: Unsupported literal type ${typeof literal} (value: ${
-          String(literal)
-        }) (supported: string | number | boolean)`
-      )
-    }
-    case "Union": {
-      if (ast.mode === "oneOf") {
-        return new SchemaAST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
-      }
-      const types = SchemaAST.mapOrSame(ast.types, recur)
-      const { annotations, filters } = get(ast)
-      if (types !== ast.types || annotations !== undefined || filters !== undefined) {
-        return new SchemaAST.Union(types, "anyOf", annotations, filters)
-      }
-      return ast
-    }
-    case "Arrays": {
-      if (ast.rest.length > 1) {
-        throw new Error(
-          `${errorPrefix}: Post-rest elements are not supported for arrays (rest length: ${ast.rest.length})`
-        )
-      }
-      let { annotations, filters } = get(ast)
-      if (ast.elements.length > 0) {
-        // tuples are not supported by Anthropic, we translate them to objects with string keys
-        if (annotations !== undefined && typeof annotations.description === "string") {
-          annotations.description = `${TUPLE_DESCRIPTION}; ${annotations.description}`
-        } else {
-          annotations ??= {}
-          annotations.description = TUPLE_DESCRIPTION
-        }
-        const propertySignatures = ast.elements.map((e, i) => {
-          return new SchemaAST.PropertySignature(String(i), e)
-        })
-        if (ast.rest.length === 1) {
-          propertySignatures.push(
-            new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], ast.rest))
-          )
-        }
-        return SchemaAST.decodeTo(
-          recur(new SchemaAST.Objects(propertySignatures, [], annotations, filters)),
-          ast,
-          SchemaTransformation.transform({
-            decode: (o) => {
-              let t: Array<unknown> = []
-              for (let i = 0; i < ast.elements.length; i++) {
-                const k = String(i)
-                if (o[k] !== undefined) {
-                  t.push(o[k])
-                }
-              }
-              if (REST_PROPERTY_NAME in o) {
-                t = [...t, ...o[REST_PROPERTY_NAME]]
-              }
-              return t
-            },
-            encode: (t) => {
-              const o: Record<string, unknown> = {}
-              for (let i = 0; i < ast.elements.length; i++) {
-                if (t.length >= i) {
-                  o[String(i)] = t[i]
-                }
-              }
-              if (ast.rest.length === 1) {
-                o[REST_PROPERTY_NAME] = t.length >= ast.elements.length ? t.slice(ast.elements.length) : []
-              }
-              return o
-            }
-          })
-        )
-      } else {
-        const rest = SchemaAST.mapOrSame(ast.rest, recur)
-        if (rest !== ast.rest || annotations !== undefined || filters !== undefined) {
-          return new SchemaAST.Arrays(false, [], rest, annotations, filters)
-        }
-        return ast
-      }
-    }
-    case "Objects": {
-      let { annotations, filters } = get(ast)
-      if (ast.indexSignatures.length === 0) {
-        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})`
-            )
-          }
-          let type = recur(ps.type)
-          // opttional properties are not supported by Anthropic, so we translate them to nullable unions
-          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)
-              })
-            )
-          }
-          if (type === ps.type) {
-            return ps
-          }
-          return new SchemaAST.PropertySignature(ps.name, type)
-        })
-        if (
-          propertySignatures !== ast.propertySignatures || annotations !== undefined || filters !== undefined
-        ) {
-          return new SchemaAST.Objects(propertySignatures, [], annotations, filters)
-        }
-      } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
-        const is = ast.indexSignatures[0]
-        if (Tool.isEmptyParamsRecord(is)) {
-          return ast
-        }
-        // records are not supported by Anthropic, so we translate them to arrays of key-value pairs
-        if (annotations !== undefined && typeof annotations.description === "string") {
-          annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`
-        } else {
-          annotations ??= {}
-          annotations.description = RECORD_DESCRIPTION
-        }
-        return SchemaAST.decodeTo(
-          recur(
-            new SchemaAST.Arrays(false, [], [new SchemaAST.Arrays(false, [is.parameter, is.type], [])], annotations)
-          ),
-          ast,
-          SchemaTransformation.transform({
-            decode: Object.fromEntries,
-            encode: Object.entries
-          })
-        )
-      } else {
-        throw new Error(
-          `${errorPrefix}: unsupported object schema shape (properties: ${ast.propertySignatures.length}, indexSignatures: ${ast.indexSignatures.length}). Supported: plain objects (properties only) or records (single index signature, no properties)`
-        )
+function hasReferenceCycle(
+  root: JsonSchema.JsonSchema,
+  definitions: JsonSchema.Definitions
+): boolean {
+  const visiting = new Set<JsonSchema.JsonSchema>()
+  const visited = new Set<JsonSchema.JsonSchema>()
+
+  function visit(schema: JsonSchema.JsonSchema): boolean {
+    if (visiting.has(schema)) return true
+    if (visited.has(schema)) return false
+
+    visiting.add(schema)
+    let cycle = false
+    InternalStructuredOutput.walkJsonSchema(schema, (node) => {
+      if (!cycle && typeof node.$ref === "string") {
+        const target = node.$ref === "#" ? root : JsonSchema.resolve$ref(node.$ref, definitions)
+        if (target !== undefined && visit(target)) cycle = true
       }
-      return ast
-    }
+      return node
+    })
+    visiting.delete(schema)
+    visited.add(schema)
+    return cycle
   }
-}
-
-const errorPrefix = "AnthropicStructuredOutput"
 
-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)
+  return visit(root)
 }
 
-const REST_PROPERTY_NAME = "__rest__"
-
-const RECORD_DESCRIPTION =
-  "Object encoded as array of [key, value] pairs. Apply object constraints to the decoded object"
-
-const TUPLE_DESCRIPTION =
-  "Tuple encoded as an object with numeric string keys ('0', '1', ...). If present, '__rest__' contains remaining elements"
-
-type Annotation =
-  | { readonly _tag: "description"; readonly description: string }
-  | { readonly _tag: "format"; readonly format: string }
-
-type Filter =
-  | Annotation
-  | { readonly _tag: "filter"; readonly filter: SchemaAST.Filter<any> }
-
-const get = (ast: SchemaAST.AST): {
-  annotations: Record<string, string> | undefined
-  filters: [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]] | undefined
-} => {
-  const annotations: Record<string, string> = {}
-  const filters: Array<SchemaAST.Filter<any>> = []
-  const checks = getChecks(ast)
-  if (checks.length > 0) {
-    for (const check of checks) {
-      switch (check._tag) {
-        case "description": {
-          if (annotations.description !== undefined) {
-            annotations.description += ` and ${check.description}`
-          } else {
-            annotations.description = check.description
-          }
-          break
-        }
-        case "format": {
-          annotations.format = check.format
-          break
-        }
-        case "filter": {
-          filters.push(check.filter)
-          break
-        }
+function rewriteAnthropic(schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
+  return InternalStructuredOutput.walkJsonSchema(schema, (schema) => {
+    const normalized = hoistAllOfDescriptions(schema)
+    const out: JsonSchema.JsonSchema = {}
+    let unsupportedFormat: string | undefined
+    for (const [key, value] of Object.entries(normalized)) {
+      if (key === "format") {
+        if (
+          typeof value === "string" && formats.has(value) &&
+          (normalized.type === undefined || normalized.type === "string")
+        ) {
+          out.format = value
+        } else if (typeof value === "string") unsupportedFormat = value
+      } else if (supportedKeywords.has(key)) {
+        if (key !== "additionalProperties" || value === false) out[key] = value
       }
     }
-  }
-  return {
-    annotations: Object.keys(annotations).length > 0 ? annotations : undefined,
-    filters: Arr.isArrayNonEmpty(filters) ? filters : undefined
-  }
+    if (unsupportedFormat !== undefined) {
+      InternalStructuredOutput.appendDescription(out, `a value with a format of ${unsupportedFormat}`)
+    }
+    return out
+  })
 }
 
-const getChecks = (ast: SchemaAST.AST): Array<Filter> => [
-  ...(ast.checks !== undefined ? getFilters(ast.checks) : []),
-  ...getAnnotations(ast.annotations)
-]
+function hoistAllOfDescriptions(schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
+  if (!Array.isArray(schema.allOf)) return schema
 
-const getAnnotations = (annotations: Schema.Annotations.Filter | undefined): Array<Annotation> => {
-  const out: Array<Annotation> = []
-  if (annotations !== undefined) {
-    const description = annotations?.description
-      ?? (annotations.meta?._tag === "isInt" || annotations.meta?._tag === "isFinite"
-        ? undefined
-        : annotations?.expected)
-    if (typeof description === "string") {
-      out.push({ _tag: "description", description })
-    }
-    const format = annotations?.format
-    if (typeof format === "string") {
-      if (formats.includes(format)) {
-        out.push({ _tag: "format", format })
-      } else {
-        out.push({ _tag: "description", description: `a value with a format of ${format}` })
-      }
-    }
+  const out: JsonSchema.JsonSchema = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== "allOf") out[key] = value
   }
-  return out
-}
-
-function getFilter(filter: SchemaAST.Filter<any>): Array<Filter> {
-  let out: Array<Filter> = []
-  const annotations = getAnnotations(filter.annotations)
-  const meta = filter.annotations?.meta
-  if (meta !== undefined) {
-    switch (meta._tag) {
-      case "isInt":
-      case "isFinite": {
-        out = out.concat(annotations)
-        out.push({ _tag: "filter", filter: resetFilter(filter) })
-        break
-      }
-      default: {
-        out = out.concat(annotations)
-        break
-      }
-    }
-    if ("regExp" in meta && meta.regExp instanceof RegExp) {
-      out.push({ _tag: "filter", filter: resetFilter(filter) })
+  const members: Array<JsonSchema.JsonSchema> = []
+  for (const member of schema.allOf) {
+    if (!InternalStructuredOutput.isJsonSchema(member)) continue
+    const { description, format, title, ...memberRest } = member
+    const rest = { ...memberRest }
+    if (schema.type !== undefined && schema.type !== "string") delete rest.pattern
+    if (typeof description === "string") {
+      InternalStructuredOutput.appendDescription(out, description)
     }
+    if (out.format === undefined && typeof format === "string") out.format = format
+    if (out.title === undefined && typeof title === "string") out.title = title
+    if (Object.keys(rest).length > 0) members.push(rest)
   }
+  if (members.length > 0) out.allOf = members
   return out
 }
 
-function resetFilter(filter: SchemaAST.Filter<any>): SchemaAST.Filter<any> {
-  return filter.annotate({
-    description: undefined,
-    expected: undefined,
-    title: undefined,
-    format: undefined
-  })
-}
-
-function getFilters(checks: readonly [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]]): Array<Filter> {
-  return checks.flatMap((check) => {
-    switch (check._tag) {
-      case "Filter":
-        return getFilter(check)
-      case "FilterGroup":
-        return getFilters(check.checks)
-    }
-  })
-}
-
-const formats = [
+const supportedKeywords = new Set([
+  "$ref",
+  "type",
+  "title",
+  "description",
+  "enum",
+  "const",
+  "anyOf",
+  "allOf",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "pattern"
+])
+
+const formats = new Set([
   "date-time",
   "time",
   "date",
   "duration",
   "email",
   "hostname",
+  "uri",
   "ipv4",
   "ipv6",
   "uuid"
-]
+])

package/src/unstable/ai/EmbeddingModel.ts

@@ -69,7 +69,7 @@ export class Dimensions extends Context.Service<Dimensions, number>()(
 export class EmbeddingUsage extends Schema.Class<EmbeddingUsage>(
   "effect/ai/EmbeddingModel/EmbeddingUsage"
 )({
-  inputTokens: Schema.UndefinedOr(Schema.Finite)
+  inputTokens: Schema.optional(Schema.Finite)
 }) {}
 
 /**