@tanstack/ai 0.0.3 → 0.2.0

package/src/{tools → activities/chat/tools}/tool-definition.ts

@@ -1,12 +1,17 @@
-import type { z } from 'zod'
-import type { Tool } from '../types'
+import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  InferSchemaType,
+  JSONSchema,
+  SchemaInput,
+  Tool,
+} from '../../../types'
 
 /**
  * Marker type for server-side tools
  */
 export interface ServerTool<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'server'
@@ -16,8 +21,8 @@ export interface ServerTool<
  * Marker type for client-side tools
  */
 export interface ClientTool<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > {
   __toolSide: 'client'
@@ -26,18 +31,18 @@ export interface ClientTool<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
   execute?: (
-    args: z.infer<TInput>,
-  ) => Promise<z.infer<TOutput>> | z.infer<TOutput>
+    args: InferSchemaType<TInput>,
+  ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>
 }
 
 /**
  * Tool definition that can be used directly or instantiated for server/client
  */
 export interface ToolDefinitionInstance<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends Tool<TInput, TOutput, TName> {
   __toolSide: 'definition'
@@ -47,8 +52,8 @@ export interface ToolDefinitionInstance<
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | ClientTool<any, any>
-  | ToolDefinitionInstance<any, any>
+  | ClientTool<SchemaInput, SchemaInput>
+  | ToolDefinitionInstance<SchemaInput, SchemaInput>
 
 /**
  * Extract the tool name as a literal type
@@ -56,29 +61,33 @@ export type AnyClientTool =
 export type InferToolName<T> = T extends { name: infer N } ? N : never
 
 /**
- * Extract the input type from a tool (inferred from Zod schema)
+ * Extract the input type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolInput<T> = T extends { inputSchema?: infer TInput }
-  ? TInput extends z.ZodType
-    ? z.infer<TInput>
-    : any
-  : any
+  ? TInput extends StandardJSONSchemaV1<infer TInferred, unknown>
+    ? TInferred
+    : TInput extends JSONSchema
+      ? unknown
+      : unknown
+  : unknown
 
 /**
- * Extract the output type from a tool (inferred from Zod schema)
+ * Extract the output type from a tool (inferred from Standard JSON Schema, or `unknown` for plain JSONSchema)
  */
 export type InferToolOutput<T> = T extends { outputSchema?: infer TOutput }
-  ? TOutput extends z.ZodType
-    ? z.infer<TOutput>
-    : any
-  : any
+  ? TOutput extends StandardJSONSchemaV1<infer TInferred, unknown>
+    ? TInferred
+    : TOutput extends JSONSchema
+      ? unknown
+      : unknown
+  : unknown
 
 /**
  * Tool definition configuration
  */
 export interface ToolDefinitionConfig<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > {
   name: TName
@@ -86,15 +95,15 @@ export interface ToolDefinitionConfig<
   inputSchema?: TInput
   outputSchema?: TOutput
   needsApproval?: boolean
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
 }
 
 /**
  * Tool definition builder that allows creating server or client tools from a shared definition
  */
 export interface ToolDefinition<
-  TInput extends z.ZodType = z.ZodType,
-  TOutput extends z.ZodType = z.ZodType,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 > extends ToolDefinitionInstance<TInput, TOutput, TName> {
   /**
@@ -102,8 +111,8 @@ export interface ToolDefinition<
    */
   server: (
     execute: (
-      args: z.infer<TInput>,
-    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+      args: InferSchemaType<TInput>,
+    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
   ) => ServerTool<TInput, TOutput, TName>
 
   /**
@@ -111,8 +120,8 @@ export interface ToolDefinition<
    */
   client: (
     execute?: (
-      args: z.infer<TInput>,
-    ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+      args: InferSchemaType<TInput>,
+    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
   ) => ClientTool<TInput, TOutput, TName>
 }
 
@@ -124,11 +133,15 @@ export interface ToolDefinition<
  * 2. Instantiated as a server tool with .server()
  * 3. Instantiated as a client tool with .client()
  *
+ * Supports any Standard JSON Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
+ * or plain JSON Schema objects.
+ *
  * @example
  * ```typescript
  * import { toolDefinition } from '@tanstack/ai';
  * import { z } from 'zod';
  *
+ * // Using Zod (natively supports Standard JSON Schema)
  * const addToCartTool = toolDefinition({
  *   name: 'addToCart',
  *   description: 'Add a guitar to the shopping cart (requires approval)',
@@ -168,8 +181,8 @@ export interface ToolDefinition<
  * ```
  */
 export function toolDefinition<
-  TInput extends z.ZodType = z.ZodAny,
-  TOutput extends z.ZodType = z.ZodAny,
+  TInput extends SchemaInput = SchemaInput,
+  TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
 >(
   config: ToolDefinitionConfig<TInput, TOutput, TName>,
@@ -179,8 +192,8 @@ export function toolDefinition<
     ...config,
     server(
       execute: (
-        args: z.infer<TInput>,
-      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+        args: InferSchemaType<TInput>,
+      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
     ): ServerTool<TInput, TOutput, TName> {
       return {
         __toolSide: 'server',
@@ -191,8 +204,8 @@ export function toolDefinition<
 
     client(
       execute?: (
-        args: z.infer<TInput>,
-      ) => Promise<z.infer<TOutput>> | z.infer<TOutput>,
+        args: InferSchemaType<TInput>,
+      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
     ): ClientTool<TInput, TOutput, TName> {
       return {
         __toolSide: 'client',

package/src/activities/generateImage/adapter.ts

@@ -0,0 +1,104 @@
+import type { ImageGenerationOptions, ImageGenerationResult } from '../../types'
+
+/**
+ * Configuration for image adapter instances
+ */
+export interface ImageAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Image adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'dall-e-3')
+ * - TProviderOptions: Base provider-specific options (already resolved)
+ * - TModelProviderOptionsByName: Map from model name to its specific provider options
+ * - TModelSizeByName: Map from model name to its supported sizes
+ */
+export interface ImageAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelSizeByName extends Record<string, string> = Record<string, string>,
+> {
+  /** Discriminator for adapter kind - used by generate() to determine API shape */
+  readonly kind: 'image'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
+  }
+
+  /**
+   * Generate images from a prompt
+   */
+  generateImages: (
+    options: ImageGenerationOptions<TProviderOptions>,
+  ) => Promise<ImageGenerationResult>
+}
+
+/**
+ * An ImageAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyImageAdapter = ImageAdapter<any, any, any, any>
+
+/**
+ * Abstract base class for image generation adapters.
+ * Extend this class to implement an image adapter for a specific provider.
+ *
+ * Generic parameters match ImageAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseImageAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelSizeByName extends Record<string, string> = Record<string, string>,
+> implements ImageAdapter<
+  TModel,
+  TProviderOptions,
+  TModelProviderOptionsByName,
+  TModelSizeByName
+> {
+  readonly kind = 'image' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
+  }
+
+  protected config: ImageAdapterConfig
+
+  constructor(config: ImageAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateImages(
+    options: ImageGenerationOptions<TProviderOptions>,
+  ): Promise<ImageGenerationResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateImage/index.ts

@@ -0,0 +1,162 @@
+/**
+ * Image Activity
+ *
+ * Generates images from text prompts.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import type { ImageAdapter } from './adapter'
+import type { ImageGenerationResult } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'image' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract model-specific provider options from an ImageAdapter via ~types.
+ * If the model has specific options defined in ModelProviderOptions (and not just via index signature),
+ * use those; otherwise fall back to base provider options.
+ */
+export type ImageProviderOptionsForModel<TAdapter, TModel extends string> =
+  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>
+    ? string extends keyof ModelOptions
+      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions
+        BaseOptions
+      : // ModelOptions has explicit keys - check if TModel is one of them
+        TModel extends keyof ModelOptions
+        ? ModelOptions[TModel]
+        : BaseOptions
+    : object
+
+/**
+ * Extract model-specific size options from an ImageAdapter via ~types.
+ * If the model has specific sizes defined, use those; otherwise fall back to string.
+ */
+export type ImageSizeForModel<TAdapter, TModel extends string> =
+  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>
+    ? string extends keyof SizeByName
+      ? // SizeByName has index signature - fall back to string
+        string
+      : // SizeByName has explicit keys - check if TModel is one of them
+        TModel extends keyof SizeByName
+        ? SizeByName[TModel]
+        : string
+    : string
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the image activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The image adapter type
+ */
+export interface ImageActivityOptions<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+> {
+  /** The image adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** Text description of the desired image(s) */
+  prompt: string
+  /** Number of images to generate (default: 1) */
+  numberOfImages?: number
+  /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
+  size?: ImageSizeForModel<TAdapter, TAdapter['model']>
+  /** Provider-specific options for image generation */
+  modelOptions?: ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/** Result type for the image activity */
+export type ImageActivityResult = Promise<ImageGenerationResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Image activity - generates images from text prompts.
+ *
+ * Uses AI image generation models to create images based on natural language descriptions.
+ *
+ * @example Generate a single image
+ * ```ts
+ * import { generateImage } from '@tanstack/ai'
+ * import { openaiImage } from '@tanstack/ai-openai'
+ *
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-3'),
+ *   prompt: 'A serene mountain landscape at sunset'
+ * })
+ *
+ * console.log(result.images[0].url)
+ * ```
+ *
+ * @example Generate multiple images
+ * ```ts
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-2'),
+ *   prompt: 'A cute robot mascot',
+ *   numberOfImages: 4,
+ *   size: '512x512'
+ * })
+ *
+ * result.images.forEach((image, i) => {
+ *   console.log(`Image ${i + 1}: ${image.url}`)
+ * })
+ * ```
+ *
+ * @example With provider-specific options
+ * ```ts
+ * const result = await generateImage({
+ *   adapter: openaiImage('dall-e-3'),
+ *   prompt: 'A professional headshot photo',
+ *   size: '1024x1024',
+ *   modelOptions: {
+ *     quality: 'hd',
+ *     style: 'natural'
+ *   }
+ * })
+ * ```
+ */
+export async function generateImage<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+>(options: ImageActivityOptions<TAdapter>): ImageActivityResult {
+  const { adapter, ...rest } = options
+  const model = adapter.model
+
+  return adapter.generateImages({ ...rest, model })
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateImage() function without executing.
+ */
+export function createImageOptions<
+  TAdapter extends ImageAdapter<string, object, any, any>,
+>(options: ImageActivityOptions<TAdapter>): ImageActivityOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  ImageAdapter,
+  ImageAdapterConfig,
+  AnyImageAdapter,
+} from './adapter'
+export { BaseImageAdapter } from './adapter'

package/src/activities/generateSpeech/adapter.ts

@@ -0,0 +1,87 @@
+import type { TTSOptions, TTSResult } from '../../types'
+
+/**
+ * Configuration for TTS adapter instances
+ */
+export interface TTSAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * TTS adapter interface with pre-resolved generics.
+ *
+ * An adapter is created by a provider function: `provider('model')` → `adapter`
+ * All type resolution happens at the provider call site, not in this interface.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'tts-1')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface TTSAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'tts'
+  /** Adapter name identifier */
+  readonly name: string
+  /** The model this adapter is configured for */
+  readonly model: TModel
+
+  /**
+   * @internal Type-only properties for inference. Not assigned at runtime.
+   */
+  '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  /**
+   * Generate speech from text
+   */
+  generateSpeech: (options: TTSOptions<TProviderOptions>) => Promise<TTSResult>
+}
+
+/**
+ * A TTSAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyTTSAdapter = TTSAdapter<any, any>
+
+/**
+ * Abstract base class for text-to-speech adapters.
+ * Extend this class to implement a TTS adapter for a specific provider.
+ *
+ * Generic parameters match TTSAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseTTSAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements TTSAdapter<TModel, TProviderOptions> {
+  readonly kind = 'tts' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: TTSAdapterConfig
+
+  constructor(config: TTSAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract generateSpeech(
+    options: TTSOptions<TProviderOptions>,
+  ): Promise<TTSResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateSpeech/index.ts

@@ -0,0 +1,122 @@
+/**
+ * TTS Activity
+ *
+ * Generates speech audio from text using text-to-speech models.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import type { TTSAdapter } from './adapter'
+import type { TTSResult } from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'tts' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract provider options from a TTSAdapter via ~types.
+ */
+export type TTSProviderOptions<TAdapter> =
+  TAdapter extends TTSAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the TTS activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The TTS adapter type
+ */
+export interface TTSActivityOptions<
+  TAdapter extends TTSAdapter<string, object>,
+> {
+  /** The TTS adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** The text to convert to speech */
+  text: string
+  /** The voice to use for generation */
+  voice?: string
+  /** The output audio format */
+  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'
+  /** The speed of the generated audio (0.25 to 4.0) */
+  speed?: number
+  /** Provider-specific options for TTS generation */
+  modelOptions?: TTSProviderOptions<TAdapter>
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/** Result type for the TTS activity */
+export type TTSActivityResult = Promise<TTSResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * TTS activity - generates speech from text.
+ *
+ * Uses AI text-to-speech models to create audio from natural language text.
+ *
+ * @example Generate speech from text
+ * ```ts
+ * import { generateSpeech } from '@tanstack/ai'
+ * import { openaiTTS } from '@tanstack/ai-openai'
+ *
+ * const result = await generateSpeech({
+ *   adapter: openaiTTS('tts-1-hd'),
+ *   text: 'Hello, welcome to TanStack AI!',
+ *   voice: 'nova'
+ * })
+ *
+ * console.log(result.audio) // base64-encoded audio
+ * ```
+ *
+ * @example With format and speed options
+ * ```ts
+ * const result = await generateSpeech({
+ *   adapter: openaiTTS('tts-1'),
+ *   text: 'This is slower speech.',
+ *   voice: 'alloy',
+ *   format: 'wav',
+ *   speed: 0.8
+ * })
+ * ```
+ */
+export async function generateSpeech<
+  TAdapter extends TTSAdapter<string, object>,
+>(options: TTSActivityOptions<TAdapter>): TTSActivityResult {
+  const { adapter, ...rest } = options
+  const model = adapter.model
+
+  return adapter.generateSpeech({ ...rest, model })
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateSpeech() function without executing.
+ */
+export function createSpeechOptions<
+  TAdapter extends TTSAdapter<string, object>,
+>(options: TTSActivityOptions<TAdapter>): TTSActivityOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'
+export { BaseTTSAdapter } from './adapter'