@tanstack-ai-browser/afm 0.0.0-stage → 0.2.2

package/src/schema.ts

@@ -0,0 +1,153 @@
+/**
+ * JSON Schema (what `chat()` gives adapters for tools and structured output)
+ * read into the framework's own schema (`NativeSchema`), which the model's
+ * output is held to: a tool's arguments always fit its parameters.
+ *
+ * Properties keep their order, which the model writes them in. Each object is
+ * named by its path, so two objects never share a name. A property that may be
+ * null is optional. `$ref`s to `$defs` (or `definitions`) become references to
+ * named definitions; one to a plain value is written in place.
+ */
+import type { NativeGenerationSchema, NativeSchema } from "./native.js"
+
+type Json = Record<string, unknown>
+
+const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** Drops undefined fields: the native bridge takes JSON. */
+function defined<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as T
+}
+
+const isNull = (schema: unknown) =>
+  isObject(schema) && (schema.type === "null" || (Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === "null"))
+
+/** Whether a schema allows null: `type: [..., "null"]`, or a null choice in `anyOf`. */
+function nullable(schema: unknown): boolean {
+  if (!isObject(schema)) return false
+  if (Array.isArray(schema.type) && schema.type.includes("null")) return true
+  const variants = schema.anyOf ?? schema.oneOf
+  return Array.isArray(variants) && variants.some(isNull)
+}
+
+const number = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : undefined)
+
+/** A schema's name for the framework: letters, digits and underscores. */
+const typeName = (name: string) => name.replace(/[^A-Za-z0-9_]/g, "_") || "Value"
+
+/**
+ * The framework's schema for a JSON Schema, named `name` (a tool's name, or
+ * the structured answer's).
+ */
+export function toNativeSchema(schema: unknown, name: string): NativeGenerationSchema {
+  const json = isObject(schema) ? schema : {}
+  const defs: Json = { ...(isObject(json.definitions) ? json.definitions : {}), ...(isObject(json.$defs) ? json.$defs : {}) }
+  const definitions = new Map<string, NativeSchema>()
+
+  const convert = (value: unknown, path: string): NativeSchema => {
+    if (!isObject(value)) return { kind: "string" }
+    if (typeof value.$ref === "string") {
+      const target = value.$ref.split("/").at(-1) ?? ""
+      const def = defs[target]
+      if (!isObject(def)) return { kind: "string" }
+      const converted = definitions.get(target) ?? convertDefinition(def, target)
+      // Only named schemas (objects, choices) can be referred to.
+      return converted.kind === "object" || converted.kind === "anyOf" ? { kind: "reference", name: typeName(target) } : converted
+    }
+    if ("const" in value && typeof value.const === "string") return { kind: "string", constant: value.const }
+    if (Array.isArray(value.enum)) {
+      const members: Array<unknown> = value.enum.filter((v) => v !== null)
+      if (members.every((v) => typeof v === "string")) {
+        return members.length > 0 ? { kind: "string", choices: members } : { kind: "string" }
+      }
+      // true and false both: any boolean. One alone, the framework can't hold it to.
+      if (members.every((v) => typeof v === "boolean")) {
+        if (new Set(members).size === 2) return { kind: "boolean" }
+        throw new Error(`${path}: an enum of only ${String(members[0])} isn't supported (Apple's framework can't hold a boolean to one value)`)
+      }
+      // Integers (and strings among them): a choice of exact values, each integer
+      // a range of itself, which the framework holds the model to. A decimal
+      // can't be: a range of one decimal fails in Apple's generator.
+      if (members.some((v) => typeof v === "number" && !Number.isInteger(v))) {
+        throw new Error(`${path}: an enum of decimal numbers isn't supported (Apple's framework can't hold a decimal to exact values)`)
+      }
+      if (members.every((v) => typeof v === "string" || Number.isInteger(v))) {
+        const choices: Array<NativeSchema> = members.map((v) =>
+          typeof v === "string" ? { kind: "string", constant: v } : { kind: "integer", minimum: v as number, maximum: v as number }
+        )
+        if (choices.length === 1) return choices[0]
+        return defined({ kind: "anyOf" as const, name: typeName(path), description: typeof value.description === "string" ? value.description : undefined, choices })
+      }
+      throw new Error(`${path}: an enum mixing ${[...new Set(members.map((v) => typeof v))].join(" and ")} values isn't supported by Apple's framework`)
+    }
+    const variants = value.anyOf ?? value.oneOf
+    if (Array.isArray(variants)) {
+      const choices = variants.filter((v) => !isNull(v))
+      if (choices.length === 1) return convert({ ...choices[0], description: value.description ?? choices[0].description }, path)
+      if (choices.length > 1) {
+        return defined({
+          kind: "anyOf" as const,
+          name: typeName(path),
+          description: typeof value.description === "string" ? value.description : undefined,
+          choices: choices.map((choice, i) => convert(choice, `${path}_${i + 1}`))
+        })
+      }
+    }
+    const types = Array.isArray(value.type) ? value.type.filter((t) => t !== "null") : [value.type]
+    const type = typeof types[0] === "string" ? types[0] : isObject(value.properties) ? "object" : value.items ? "array" : "string"
+    switch (type) {
+      case "object": {
+        const required = Array.isArray(value.required) ? value.required : []
+        const properties = Object.entries(isObject(value.properties) ? value.properties : {}).map(([key, property]) =>
+          defined({
+            name: key,
+            description: isObject(property) && typeof property.description === "string" ? property.description : undefined,
+            optional: !required.includes(key) || nullable(property),
+            schema: convert(property, `${path}_${key}`)
+          })
+        )
+        return defined({
+          kind: "object" as const,
+          name: typeName(path),
+          description: typeof value.description === "string" ? value.description : undefined,
+          properties
+        })
+      }
+      case "array":
+        return defined({
+          kind: "array" as const,
+          items: convert(Array.isArray(value.items) ? value.items[0] : value.items, `${path}_item`),
+          minimumElements: number(value.minItems),
+          maximumElements: number(value.maxItems)
+        })
+      case "integer":
+      case "number":
+        return defined({
+          kind: type,
+          minimum: number(value.minimum) ?? number(value.exclusiveMinimum),
+          maximum: number(value.maximum) ?? number(value.exclusiveMaximum)
+        })
+      case "boolean":
+        return { kind: "boolean" }
+      case "null":
+        return { kind: "null" }
+      default:
+        return { kind: "string" }
+    }
+  }
+
+  const convertDefinition = (def: Json, target: string): NativeSchema => {
+    // Set first, so a definition that refers to itself finds its name.
+    definitions.set(target, { kind: "object", name: typeName(target), properties: [] })
+    const converted = convert(def, target)
+    const named = converted.kind === "object" || converted.kind === "anyOf" ? { ...converted, name: typeName(target) } : converted
+    definitions.set(target, named)
+    return named
+  }
+
+  const root = convert(json, name)
+  return {
+    root,
+    definitions: [...definitions.values()].filter((d) => d.kind === "object" || d.kind === "anyOf")
+  }
+}

package/src/validate.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+
+import { schemaErrors } from "./validate.js"
+
+const city = { type: "object", properties: { city: { type: "string" } }, required: ["city"] }
+
+test("a value that fits its schema has no errors", () => {
+  assert.deepEqual(schemaErrors(city, { city: "Paris" }), [])
+  assert.deepEqual(schemaErrors({ type: "array", items: { type: "integer" }, minItems: 1 }, [1, 2]), [])
+  assert.deepEqual(schemaErrors({ type: ["string", "null"] }, null), [])
+})
+
+test("missing required fields, wrong types and values outside an enum are errors, with their paths", () => {
+  assert.deepEqual(schemaErrors(city, {}), ["/city: missing"])
+  assert.deepEqual(schemaErrors(city, { city: 123 }), ["/city: should be string, not number"])
+  assert.deepEqual(schemaErrors(city, "Paris"), ["/: should be object, not string"])
+  const action = { type: "object", properties: { operation: { type: "string", enum: ["add", "remove"] } }, required: ["operation"] }
+  assert.deepEqual(schemaErrors(action, { operation: "burn" }), ['/operation: "burn" is not one of "add", "remove"'])
+  assert.deepEqual(schemaErrors({ type: "integer" }, 1.5), ["/: should be integer, not number"])
+})
+
+test("nested arrays, $refs, choices, extra properties and bounds are checked", () => {
+  const schema = {
+    type: "object",
+    properties: { actions: { type: "array", items: { $ref: "#/$defs/Action" }, maxItems: 2 } },
+    required: ["actions"],
+    $defs: { Action: { type: "object", properties: { n: { type: "integer", minimum: 1, maximum: 4 } }, required: ["n"], additionalProperties: false } }
+  }
+  assert.deepEqual(schemaErrors(schema, { actions: [{ n: 2 }] }), [])
+  assert.deepEqual(schemaErrors(schema, { actions: [{ n: 0 }, { n: 2, x: 1 }, { n: 3 }] }), [
+    "/actions: more than 2 items",
+    "/actions/0/n: less than 1",
+    "/actions/1/x: not a property of the schema"
+  ])
+  assert.deepEqual(schemaErrors({ anyOf: [{ type: "string" }, { type: "integer" }] }, true), ["/: fits 0 of its anyOf choices"])
+  assert.deepEqual(schemaErrors({ const: "a" }, "b"), ['/: should be "a", not "b"'])
+})

package/src/validate.ts

@@ -0,0 +1,112 @@
+/**
+ * Where a value doesn't fit a JSON Schema: each mismatch with its path
+ * ("/actions/0/operation: not one of add, remove"). Empty when it fits. It reads
+ * what afm converts for Apple's framework and the framework holds answers to:
+ * types (with null), objects (properties, required, additionalProperties),
+ * arrays (items, minItems, maxItems), enum, const, anyOf, oneOf, allOf, $ref to
+ * $defs or definitions, string lengths and patterns, and numeric bounds. Other
+ * keywords are left unchecked.
+ */
+type Json = Record<string, unknown>
+
+const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const typeOf = (value: unknown) => (value === null ? "null" : Array.isArray(value) ? "array" : typeof value)
+
+function equal(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => equal(v, b[i]))
+  if (isObject(a) && isObject(b)) {
+    const keys = Object.keys(a)
+    return keys.length === Object.keys(b).length && keys.every((k) => Object.hasOwn(b, k) && equal(a[k], b[k]))
+  }
+  return false
+}
+
+function fitsType(type: string, value: unknown) {
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value)
+  if (type === "number") return typeof value === "number" && Number.isFinite(value)
+  return typeOf(value) === type
+}
+
+const show = (value: unknown) => JSON.stringify(value)
+
+export function schemaErrors(schema: unknown, value: unknown): Array<string> {
+  const root = isObject(schema) ? schema : {}
+  const errors: Array<string> = []
+
+  const resolve = (ref: string): unknown => {
+    const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref)
+    const defs = match ? root[match[1]] : undefined
+    return match && isObject(defs) ? defs[decodeURIComponent(match[2])] : undefined
+  }
+
+  const check = (s: unknown, v: unknown, path: string, out: Array<string>) => {
+    if (s === true || s === undefined) return
+    if (s === false) return void out.push(`${path || "/"}: not allowed`)
+    if (!isObject(s)) return
+    if (typeof s.$ref === "string") {
+      const target = resolve(s.$ref)
+      if (target === undefined) return void out.push(`${path || "/"}: unknown $ref ${s.$ref}`)
+      check(target, v, path, out)
+    }
+    const at = path || "/"
+    if ("const" in s && !equal(s.const, v)) out.push(`${at}: should be ${show(s.const)}, not ${show(v)}`)
+    if (Array.isArray(s.enum) && !s.enum.some((e) => equal(e, v))) out.push(`${at}: ${show(v)} is not one of ${s.enum.map(show).join(", ")}`)
+    if (s.type !== undefined) {
+      const types = (Array.isArray(s.type) ? s.type : [s.type]).filter((t): t is string => typeof t === "string")
+      if (types.length > 0 && !types.some((t) => fitsType(t, v))) {
+        out.push(`${at}: should be ${types.join(" or ")}, not ${typeOf(v)}`)
+        return
+      }
+    }
+    if (Array.isArray(s.allOf)) for (const part of s.allOf) check(part, v, path, out)
+    for (const key of ["anyOf", "oneOf"] as const) {
+      const choices = s[key]
+      if (!Array.isArray(choices)) continue
+      const fitting = choices.filter((choice) => {
+        const sub: Array<string> = []
+        check(choice, v, path, sub)
+        return sub.length === 0
+      }).length
+      if (key === "anyOf" ? fitting === 0 : fitting !== 1) out.push(`${at}: fits ${fitting} of its ${key} choices`)
+    }
+    if (isObject(v)) {
+      const properties = isObject(s.properties) ? s.properties : {}
+      if (Array.isArray(s.required)) {
+        for (const key of s.required) if (typeof key === "string" && !Object.hasOwn(v, key)) out.push(`${path}/${key}: missing`)
+      }
+      for (const [key, item] of Object.entries(v)) {
+        if (Object.hasOwn(properties, key)) check(properties[key], item, `${path}/${key}`, out)
+        else if (s.additionalProperties === false) out.push(`${path}/${key}: not a property of the schema`)
+        else if (isObject(s.additionalProperties)) check(s.additionalProperties, item, `${path}/${key}`, out)
+      }
+    }
+    if (Array.isArray(v)) {
+      if (typeof s.minItems === "number" && v.length < s.minItems) out.push(`${at}: fewer than ${s.minItems} items`)
+      if (typeof s.maxItems === "number" && v.length > s.maxItems) out.push(`${at}: more than ${s.maxItems} items`)
+      if (Array.isArray(s.items)) s.items.forEach((item, i) => i < v.length && check(item, v[i], `${path}/${i}`, out))
+      else if (s.items !== undefined) v.forEach((item, i) => check(s.items, item, `${path}/${i}`, out))
+    }
+    if (typeof v === "string") {
+      if (typeof s.minLength === "number" && [...v].length < s.minLength) out.push(`${at}: shorter than ${s.minLength}`)
+      if (typeof s.maxLength === "number" && [...v].length > s.maxLength) out.push(`${at}: longer than ${s.maxLength}`)
+      if (typeof s.pattern === "string") {
+        try {
+          if (!new RegExp(s.pattern, "u").test(v)) out.push(`${at}: doesn't match ${s.pattern}`)
+        } catch {
+          // A pattern JavaScript can't read isn't checked.
+        }
+      }
+    }
+    if (typeof v === "number") {
+      if (typeof s.minimum === "number" && v < s.minimum) out.push(`${at}: less than ${s.minimum}`)
+      if (typeof s.maximum === "number" && v > s.maximum) out.push(`${at}: more than ${s.maximum}`)
+      if (typeof s.exclusiveMinimum === "number" && v <= s.exclusiveMinimum) out.push(`${at}: not more than ${s.exclusiveMinimum}`)
+      if (typeof s.exclusiveMaximum === "number" && v >= s.exclusiveMaximum) out.push(`${at}: not less than ${s.exclusiveMaximum}`)
+    }
+  }
+
+  check(root, value, "", errors)
+  return errors
+}