@tanstack/ai 0.1.0 → 0.2.0

package/src/activities/chat/index.ts

@@ -8,20 +8,25 @@
 import { aiEventClient } from '../../event-client.js'
 import { streamToText } from '../../stream-to-response.js'
 import { ToolCallManager, executeToolCalls } from './tools/tool-calls'
-import { convertZodToJsonSchema } from './tools/zod-converter'
+import {
+  convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
+} from './tools/schema-converter'
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import type {
   ApprovalRequest,
   ClientToolRequest,
   ToolResult,
 } from './tools/tool-calls'
-import type { z } from 'zod'
 import type { AnyTextAdapter } from './adapter'
 import type {
   AgentLoopStrategy,
   ConstrainedModelMessage,
   DoneStreamChunk,
+  InferSchemaType,
   ModelMessage,
+  SchemaInput,
   StreamChunk,
   TextOptions,
   Tool,
@@ -44,12 +49,12 @@ export const kind = 'text' as const
  * Types are extracted directly from the adapter (which has pre-resolved generics).
  *
  * @template TAdapter - The text adapter type (created by a provider function)
- * @template TSchema - Optional Zod schema for structured output
+ * @template TSchema - Optional Standard Schema for structured output
  * @template TStream - Whether to stream the output (default: true)
  */
 export interface TextActivityOptions<
   TAdapter extends AnyTextAdapter,
-  TSchema extends z.ZodType | undefined,
+  TSchema extends SchemaInput | undefined,
   TStream extends boolean,
 > {
   /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
@@ -82,11 +87,13 @@ export interface TextActivityOptions<
   /** Unique conversation identifier for tracking */
   conversationId?: TextOptions['conversationId']
   /**
-   * Optional Zod schema for structured output.
+   * Optional Standard Schema for structured output.
    * When provided, the activity will:
    * 1. Run the full agentic loop (executing tools as needed)
    * 2. Once complete, return a Promise with the parsed output matching the schema
    *
+   * Supports any Standard Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
+   *
    * @example
    * ```ts
    * const result = await chat({
@@ -104,7 +111,7 @@ export interface TextActivityOptions<
    * When false, returns a Promise<string> with the collected text content.
    *
    * Note: If outputSchema is provided, this option is ignored and the result
-   * is always a Promise<z.infer<TSchema>>.
+   * is always a Promise<InferSchemaType<TSchema>>.
    *
    * @default true
    *
@@ -140,7 +147,7 @@ export interface TextActivityOptions<
  */
 export function createChatOptions<
   TAdapter extends AnyTextAdapter,
-  TSchema extends z.ZodType | undefined = undefined,
+  TSchema extends SchemaInput | undefined = undefined,
   TStream extends boolean = true,
 >(
   options: TextActivityOptions<TAdapter, TSchema, TStream>,
@@ -154,15 +161,15 @@ export function createChatOptions<
 
 /**
  * Result type for the text activity.
- * - If outputSchema is provided: Promise<z.infer<TSchema>>
+ * - If outputSchema is provided: Promise<InferSchemaType<TSchema>>
  * - If stream is false: Promise<string>
  * - Otherwise (stream is true, default): AsyncIterable<StreamChunk>
  */
 export type TextActivityResult<
-  TSchema extends z.ZodType | undefined,
+  TSchema extends SchemaInput | undefined,
   TStream extends boolean = true,
-> = TSchema extends z.ZodType
-  ? Promise<z.infer<TSchema>>
+> = TSchema extends SchemaInput
+  ? Promise<InferSchemaType<TSchema>>
   : TStream extends false
     ? Promise<string>
     : AsyncIterable<StreamChunk>
@@ -366,14 +373,14 @@ class TextEngine<
     const { temperature, topP, maxTokens, metadata, modelOptions } = this.params
     const tools = this.params.tools
 
-    // Convert tool schemas from Zod to JSON Schema before passing to adapter
+    // Convert tool schemas to JSON Schema before passing to adapter
     const toolsWithJsonSchemas = tools?.map((tool) => ({
       ...tool,
       inputSchema: tool.inputSchema
-        ? convertZodToJsonSchema(tool.inputSchema)
+        ? convertSchemaToJsonSchema(tool.inputSchema)
         : undefined,
       outputSchema: tool.outputSchema
-        ? convertZodToJsonSchema(tool.outputSchema)
+        ? convertSchemaToJsonSchema(tool.outputSchema)
         : undefined,
     }))
 
@@ -968,7 +975,7 @@ class TextEngine<
  */
 export function chat<
   TAdapter extends AnyTextAdapter,
-  TSchema extends z.ZodType | undefined = undefined,
+  TSchema extends SchemaInput | undefined = undefined,
   TStream extends boolean = true,
 >(
   options: TextActivityOptions<TAdapter, TSchema, TStream>,
@@ -980,7 +987,7 @@ export function chat<
     return runAgenticStructuredOutput(
       options as unknown as TextActivityOptions<
         AnyTextAdapter,
-        z.ZodType,
+        SchemaInput,
         boolean
       >,
     ) as TextActivityResult<TSchema, TStream>
@@ -1046,9 +1053,9 @@ function runNonStreamingText(
  * 2. Once complete, call adapter.structuredOutput with the conversation context
  * 3. Validate and return the structured result
  */
-async function runAgenticStructuredOutput<TSchema extends z.ZodType>(
+async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
   options: TextActivityOptions<AnyTextAdapter, TSchema, boolean>,
-): Promise<z.infer<TSchema>> {
+): Promise<InferSchemaType<TSchema>> {
   const { adapter, outputSchema, ...textOptions } = options
   const model = adapter.model
 
@@ -1060,8 +1067,8 @@ async function runAgenticStructuredOutput<TSchema extends z.ZodType>(
   const engine = new TextEngine({
     adapter,
     params: { ...textOptions, model } as TextOptions<
-      Record<string, any>,
-      Record<string, any>
+      Record<string, unknown>,
+      Record<string, unknown>
     >,
   })
 
@@ -1081,8 +1088,8 @@ async function runAgenticStructuredOutput<TSchema extends z.ZodType>(
     ...structuredTextOptions
   } = textOptions
 
-  // Convert the Zod schema to JSON Schema before passing to the adapter
-  const jsonSchema = convertZodToJsonSchema(outputSchema)
+  // Convert the schema to JSON Schema before passing to the adapter
+  const jsonSchema = convertSchemaToJsonSchema(outputSchema)
   if (!jsonSchema) {
     throw new Error('Failed to convert output schema to JSON Schema')
   }
@@ -1098,15 +1105,16 @@ async function runAgenticStructuredOutput<TSchema extends z.ZodType>(
     outputSchema: jsonSchema,
   })
 
-  // Validate the result against the Zod schema
-  const validationResult = outputSchema.safeParse(result.data)
-  if (!validationResult.success) {
-    throw new Error(
-      `Structured output validation failed: ${validationResult.error.message}`,
+  // Validate the result against the schema if it's a Standard Schema
+  if (isStandardSchema(outputSchema)) {
+    return parseWithStandardSchema<InferSchemaType<TSchema>>(
+      outputSchema,
+      result.data,
     )
   }
 
-  return validationResult.data
+  // For plain JSON Schema, return the data as-is
+  return result.data as InferSchemaType<TSchema>
 }
 
 // Re-export adapter types

package/src/activities/chat/tools/schema-converter.ts

@@ -0,0 +1,332 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
+import type { JSONSchema, SchemaInput } from '../../../types'
+
+/**
+ * Check if a value is a Standard JSON Schema compliant schema.
+ * Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)
+ * implement the '~standard' property with jsonSchema converter methods.
+ */
+export function isStandardJSONSchema(
+  schema: unknown,
+): schema is StandardJSONSchemaV1 {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    '~standard' in schema &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'] === 'object' &&
+    (schema as StandardJSONSchemaV1)['~standard'].version === 1 &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema ===
+      'object' &&
+    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema.input ===
+      'function'
+  )
+}
+
+/**
+ * Check if a value is a Standard Schema compliant schema (for validation).
+ * Standard Schema compliant libraries implement the '~standard' property with a validate function.
+ */
+export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    '~standard' in schema &&
+    typeof schema['~standard'] === 'object' &&
+    schema !== null &&
+    schema['~standard'] !== null &&
+    'version' in schema['~standard'] &&
+    schema['~standard'].version === 1 &&
+    'validate' in schema['~standard'] &&
+    typeof schema['~standard'].validate === 'function'
+  )
+}
+
+/**
+ * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
+ * OpenAI requires:
+ * - All properties must be in the `required` array
+ * - Optional fields should have null added to their type union
+ * - additionalProperties must be false for objects
+ *
+ * @param schema - JSON schema to transform
+ * @param originalRequired - Original required array (to know which fields were optional)
+ * @returns Transformed schema compatible with OpenAI structured output
+ */
+function makeStructuredOutputCompatible(
+  schema: Record<string, any>,
+  originalRequired: Array<string> = [],
+): Record<string, any> {
+  const result = { ...schema }
+
+  // Handle object types
+  if (result.type === 'object' && result.properties) {
+    const properties = { ...result.properties }
+    const allPropertyNames = Object.keys(properties)
+
+    // Transform each property
+    for (const propName of allPropertyNames) {
+      const prop = properties[propName]
+      const wasOptional = !originalRequired.includes(propName)
+
+      // Recursively transform nested objects/arrays
+      if (prop.type === 'object' && prop.properties) {
+        properties[propName] = makeStructuredOutputCompatible(
+          prop,
+          prop.required || [],
+        )
+      } else if (prop.type === 'array' && prop.items) {
+        properties[propName] = {
+          ...prop,
+          items: makeStructuredOutputCompatible(
+            prop.items,
+            prop.items.required || [],
+          ),
+        }
+      } else if (wasOptional) {
+        // Make optional fields nullable by adding null to the type
+        if (prop.type && !Array.isArray(prop.type)) {
+          properties[propName] = {
+            ...prop,
+            type: [prop.type, 'null'],
+          }
+        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {
+          properties[propName] = {
+            ...prop,
+            type: [...prop.type, 'null'],
+          }
+        }
+      }
+    }
+
+    result.properties = properties
+    // ALL properties must be required for OpenAI structured output
+    result.required = allPropertyNames
+    // additionalProperties must be false
+    result.additionalProperties = false
+  }
+
+  // Handle array types with object items
+  if (result.type === 'array' && result.items) {
+    result.items = makeStructuredOutputCompatible(
+      result.items,
+      result.items.required || [],
+    )
+  }
+
+  return result
+}
+
+/**
+ * Options for schema conversion
+ */
+export interface ConvertSchemaOptions {
+  /**
+   * When true, transforms the schema to be compatible with OpenAI's structured output requirements:
+   * - All properties are added to the `required` array
+   * - Optional fields get null added to their type union
+   * - additionalProperties is set to false for all objects
+   *
+   * @default false
+   */
+  forStructuredOutput?: boolean
+}
+
+/**
+ * Converts a Standard JSON Schema compliant schema or plain JSONSchema to JSON Schema format
+ * compatible with LLM providers.
+ *
+ * Supports any schema library that implements the Standard JSON Schema spec (v1):
+ * - Zod v4+ (natively supports StandardJSONSchemaV1)
+ * - ArkType (natively supports StandardJSONSchemaV1)
+ * - Valibot (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
+ *
+ * If the input is already a plain JSONSchema object, it is returned as-is.
+ *
+ * @param schema - Standard JSON Schema compliant schema or plain JSONSchema object to convert
+ * @param options - Conversion options
+ * @returns JSON Schema object that can be sent to LLM providers
+ *
+ * @example
+ * ```typescript
+ * // Using Zod v4+ (natively supports Standard JSON Schema)
+ * import * as z from 'zod';
+ *
+ * const zodSchema = z.object({
+ *   location: z.string().describe('City name'),
+ *   unit: z.enum(['celsius', 'fahrenheit']).optional()
+ * });
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(zodSchema);
+ *
+ * @example
+ * // Using ArkType (natively supports Standard JSON Schema)
+ * import { type } from 'arktype';
+ *
+ * const arkSchema = type({
+ *   location: 'string',
+ *   unit: "'celsius' | 'fahrenheit'"
+ * });
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(arkSchema);
+ *
+ * @example
+ * // Using Valibot (via toStandardJsonSchema)
+ * import * as v from 'valibot';
+ * import { toStandardJsonSchema } from '@valibot/to-json-schema';
+ *
+ * const valibotSchema = toStandardJsonSchema(v.object({
+ *   location: v.string(),
+ *   unit: v.optional(v.picklist(['celsius', 'fahrenheit']))
+ * }));
+ *
+ * const jsonSchema = convertSchemaToJsonSchema(valibotSchema);
+ *
+ * @example
+ * // Using JSONSchema directly (passes through unchanged)
+ * const rawSchema = {
+ *   type: 'object',
+ *   properties: { location: { type: 'string' } },
+ *   required: ['location']
+ * };
+ * const result = convertSchemaToJsonSchema(rawSchema);
+ * ```
+ */
+export function convertSchemaToJsonSchema(
+  schema: SchemaInput | undefined,
+  options: ConvertSchemaOptions = {},
+): JSONSchema | undefined {
+  if (!schema) return undefined
+
+  const { forStructuredOutput = false } = options
+
+  // If it's a Standard JSON Schema compliant schema, use the standard interface
+  if (isStandardJSONSchema(schema)) {
+    const jsonSchema = schema['~standard'].jsonSchema.input({
+      target: 'draft-07',
+    })
+
+    let result = jsonSchema
+
+    if (typeof result === 'object' && '$schema' in result) {
+      // Remove $schema property as it's not needed for LLM providers
+      const { $schema, ...rest } = result
+      result = rest
+    }
+
+    // Ensure object schemas always have type: "object"
+
+    if (typeof result === 'object') {
+      // If it has properties (even empty), it should be an object type
+      if ('properties' in result && !result.type) {
+        result.type = 'object'
+      }
+
+      // Ensure properties exists for object types (even if empty)
+      if (result.type === 'object' && !('properties' in result)) {
+        result.properties = {}
+      }
+
+      // Ensure required exists for object types (even if empty array)
+      if (result.type === 'object' && !('required' in result)) {
+        result.required = []
+      }
+
+      // Apply structured output transformation if requested
+      if (forStructuredOutput) {
+        result = makeStructuredOutputCompatible(
+          result,
+          (result.required as Array<string>) || [],
+        )
+      }
+    }
+
+    return result as JSONSchema
+  }
+
+  // If it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through
+  // Still apply structured output transformation if requested
+
+  if (forStructuredOutput && typeof schema === 'object') {
+    return makeStructuredOutputCompatible(
+      schema as Record<string, any>,
+      ((schema as JSONSchema).required as Array<string>) || [],
+    ) as JSONSchema
+  }
+
+  return schema as JSONSchema
+}
+
+/**
+ * Validates data against a Standard Schema compliant schema.
+ *
+ * @param schema - Standard Schema compliant schema
+ * @param data - Data to validate
+ * @returns Validation result with success status, data or issues
+ */
+export async function validateWithStandardSchema<T>(
+  schema: unknown,
+  data: unknown,
+): Promise<
+  | { success: true; data: T }
+  | { success: false; issues: Array<{ message: string; path?: Array<string> }> }
+> {
+  if (!isStandardSchema(schema)) {
+    // If it's not a Standard Schema, just return the data as-is
+    return { success: true, data: data as T }
+  }
+
+  const result = await schema['~standard'].validate(data)
+
+  if (!result.issues) {
+    return { success: true, data: result.value as T }
+  }
+
+  return {
+    success: false,
+    issues: result.issues.map((issue) => ({
+      message: issue.message || 'Validation failed',
+      path: issue.path?.map(String),
+    })),
+  }
+}
+
+/**
+ * Synchronously validates data against a Standard Schema compliant schema.
+ * Note: Some Standard Schema implementations may only support async validation.
+ * In those cases, this function will throw.
+ *
+ * @param schema - Standard Schema compliant schema
+ * @param data - Data to validate
+ * @returns Parsed/validated data
+ * @throws Error if validation fails or if the schema only supports async validation
+ */
+export function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {
+  if (!isStandardSchema(schema)) {
+    // If it's not a Standard Schema, just return the data as-is
+    return data as T
+  }
+
+  const result = schema['~standard'].validate(data)
+
+  // Handle async result (Promise)
+  if (result instanceof Promise) {
+    throw new Error(
+      'Schema validation returned a Promise. Use validateWithStandardSchema for async validation.',
+    )
+  }
+  // Standard Schema validation returns { value } for success or { issues } for failure
+  if (!result.issues) {
+    return result.value as T
+  }
+
+  // invalid validation, throw error with all issues
+  const errorMessages = result.issues
+    .map((issue) => issue.message || 'Validation failed')
+    .join(', ')
+  throw new Error(`Validation failed: ${errorMessages}`)
+}