@tanstack/ai 0.4.2 → 0.5.1

package/src/activities/generateVideo/adapter.ts

@@ -29,10 +29,14 @@ export interface VideoAdapterConfig {
  * Generic parameters:
  * - TModel: The specific model name (e.g., 'sora-2')
  * - TProviderOptions: 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 VideoAdapter<
   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 to determine API shape */
   readonly kind: 'video'
@@ -46,6 +50,8 @@ export interface VideoAdapter<
    */
   '~types': {
     providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
   }
 
   /**
@@ -53,7 +59,7 @@ export interface VideoAdapter<
    * Returns a job ID that can be used to poll for status and retrieve the video.
    */
   createVideoJob: (
-    options: VideoGenerationOptions<TProviderOptions>,
+    options: VideoGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,
   ) => Promise<VideoJobResult>
 
   /**
@@ -72,7 +78,7 @@ export interface VideoAdapter<
  * A VideoAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyVideoAdapter = VideoAdapter<any, any>
+export type AnyVideoAdapter = VideoAdapter<any, any, any, any>
 
 /**
  * Abstract base class for video generation adapters.
@@ -85,7 +91,14 @@ export type AnyVideoAdapter = VideoAdapter<any, any>
 export abstract class BaseVideoAdapter<
   TModel extends string = string,
   TProviderOptions extends object = Record<string, unknown>,
-> implements VideoAdapter<TModel, TProviderOptions> {
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelSizeByName extends Record<string, string> = Record<string, string>,
+> implements VideoAdapter<
+  TModel,
+  TProviderOptions,
+  TModelProviderOptionsByName,
+  TModelSizeByName
+> {
   readonly kind = 'video' as const
   abstract readonly name: string
   readonly model: TModel
@@ -93,6 +106,8 @@ export abstract class BaseVideoAdapter<
   // Type-only property - never assigned at runtime
   declare '~types': {
     providerOptions: TProviderOptions
+    modelProviderOptionsByName: TModelProviderOptionsByName
+    modelSizeByName: TModelSizeByName
   }
 
   protected config: VideoAdapterConfig
@@ -103,7 +118,7 @@ export abstract class BaseVideoAdapter<
   }
 
   abstract createVideoJob(
-    options: VideoGenerationOptions<TProviderOptions>,
+    options: VideoGenerationOptions<TProviderOptions, TModelSizeByName[TModel]>,
   ): Promise<VideoJobResult>
 
   abstract getVideoStatus(jobId: string): Promise<VideoStatusResult>

package/src/activities/generateVideo/index.ts

@@ -30,10 +30,20 @@ export const kind = 'video' as const
  * Extract provider options from a VideoAdapter via ~types.
  */
 export type VideoProviderOptions<TAdapter> =
-  TAdapter extends VideoAdapter<any, any>
+  TAdapter extends VideoAdapter<any, any, any, any>
     ? TAdapter['~types']['providerOptions']
     : object
 
+/**
+ * Extract the size type for a VideoAdapter's model via ~types.
+ */
+export type VideoSizeForAdapter<TAdapter> =
+  TAdapter extends VideoAdapter<infer TModel, any, any, infer TSizeMap>
+    ? TModel extends keyof TSizeMap
+      ? TSizeMap[TModel]
+      : string
+    : string
+
 // ===========================
 // Activity Options Types
 
@@ -47,7 +57,7 @@ function createId(prefix: string): string {
  * The model is extracted from the adapter's model property.
  */
 interface VideoActivityBaseOptions<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 > {
   /** The video adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -59,20 +69,24 @@ interface VideoActivityBaseOptions<
  *
  * @experimental Video generation is an experimental feature and may change.
  */
-export interface VideoCreateOptions<
-  TAdapter extends VideoAdapter<string, object>,
-> extends VideoActivityBaseOptions<TAdapter> {
+export type VideoCreateOptions<
+  TAdapter extends VideoAdapter<string, any, any, any>,
+> = VideoActivityBaseOptions<TAdapter> & {
   /** Request type - create a new job (default if not specified) */
   request?: 'create'
   /** Text description of the desired video */
   prompt: string
-  /** Video size in WIDTHxHEIGHT format (e.g., "1280x720") */
-  size?: string
+  /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
+  size?: VideoSizeForAdapter<TAdapter>
   /** Video duration in seconds */
   duration?: number
-  /** Provider-specific options for video generation */
-  modelOptions?: VideoProviderOptions<TAdapter>
-}
+} & ({} extends VideoProviderOptions<TAdapter>
+    ? {
+        /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
+      }
+    : {
+        /** Provider-specific options for video generation */ modelOptions: VideoProviderOptions<TAdapter>
+      })
 
 /**
  * Options for polling the status of a video generation job.
@@ -80,7 +94,7 @@ export interface VideoCreateOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoStatusOptions<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get job status */
   request: 'status'
@@ -94,7 +108,7 @@ export interface VideoStatusOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoUrlOptions<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get video URL */
   request: 'url'
@@ -109,7 +123,7 @@ export interface VideoUrlOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoActivityOptions<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
   TRequest extends 'create' | 'status' | 'url' = 'create',
 > = TRequest extends 'status'
   ? VideoStatusOptions<TAdapter>
@@ -161,7 +175,7 @@ export type VideoActivityResult<
  * ```
  */
 export async function generateVideo<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter>): Promise<VideoJobResult> {
   const { adapter, prompt, size, duration, modelOptions } = options
   const model = adapter.model
@@ -201,7 +215,7 @@ export async function generateVideo<
  * ```
  */
 export async function getVideoJobStatus<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: {
   adapter: TAdapter & { kind: typeof kind }
   jobId: string
@@ -301,7 +315,7 @@ export async function getVideoJobStatus<
  * Create typed options for the generateVideo() function without executing.
  */
 export function createVideoOptions<
-  TAdapter extends VideoAdapter<string, object>,
+  TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter>): VideoCreateOptions<TAdapter> {
   return options
 }

package/src/extend-adapter.ts

@@ -0,0 +1,182 @@
+import type { Modality } from './types'
+
+// ===========================
+// Extended Model Definition
+// ===========================
+
+/**
+ * Definition for a custom model to add to an adapter.
+ *
+ * @template TName - The model name as a literal string type
+ * @template TInput - Array of supported input modalities
+ * @template TOptions - Provider options type for this model
+ *
+ * @example
+ * ```typescript
+ * const customModels = [
+ *   createModel('my-custom-model', ['text', 'image']),
+ * ] as const
+ * ```
+ */
+export interface ExtendedModelDef<
+  TName extends string = string,
+  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
+  TOptions = unknown,
+> {
+  /** The model name identifier */
+  name: TName
+  /** Supported input modalities for this model */
+  input: TInput
+  /** Type brand for provider options - use `{} as YourOptionsType` */
+  modelOptions: TOptions
+}
+
+/**
+ * Creates a custom model definition for use with `extendAdapter`.
+ *
+ * This is a helper function that provides proper type inference without
+ * requiring manual `as const` casts on individual properties.
+ *
+ * @template TName - The model name (inferred from argument)
+ * @template TInput - The input modalities array (inferred from argument)
+ *
+ * @param name - The model name identifier (literal string)
+ * @param input - Array of supported input modalities
+ * @returns A properly typed model definition for use with `extendAdapter`
+ *
+ * @example
+ * ```typescript
+ * import { extendAdapter, createModel } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
+ *
+ * // Define custom models with full type inference
+ * const customModels = [
+ *   createModel('my-fine-tuned-gpt4', ['text', 'image']),
+ *   createModel('local-llama', ['text']),
+ * ] as const
+ *
+ * const myOpenai = extendAdapter(openaiText, customModels)
+ * ```
+ */
+export function createModel<
+  const TName extends string,
+  const TInput extends ReadonlyArray<Modality>,
+>(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {
+  return {
+    name,
+    input,
+    modelOptions: {} as unknown,
+  }
+}
+
+// ===========================
+// Type Extraction Utilities
+// ===========================
+
+/**
+ * Extract the model name union from an array of model definitions.
+ */
+type ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =
+  TDefs[number]['name']
+
+// ===========================
+// Factory Type Inference
+// ===========================
+
+/**
+ * Infer the model parameter type from an adapter factory function.
+ * For generic functions like `<T extends Union>(model: T)`, this gets `T` which
+ * TypeScript treats as the constraint union when used in parameter position.
+ */
+type InferFactoryModels<TFactory> = TFactory extends (
+  model: infer TModel,
+  ...args: Array<any>
+) => any
+  ? TModel extends string
+    ? TModel
+    : string
+  : string
+
+/**
+ * Infer the config parameter type from an adapter factory function.
+ */
+type InferConfig<TFactory> = TFactory extends (
+  model: any,
+  config?: infer TConfig,
+) => any
+  ? TConfig
+  : undefined
+
+/**
+ * Infer the adapter return type from a factory function.
+ */
+type InferAdapterReturn<TFactory> = TFactory extends (
+  ...args: Array<any>
+) => infer TReturn
+  ? TReturn
+  : never
+
+// ===========================
+// extendAdapter Function
+// ===========================
+
+/**
+ * Extends an existing adapter factory with additional custom models.
+ *
+ * The extended adapter accepts both original models (with full original type inference)
+ * and custom models (with types from your definitions).
+ *
+ * At runtime, this simply passes through to the original factory - no validation is performed.
+ * The original factory's signature is fully preserved, including any config parameters.
+ *
+ * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)
+ * @param models - Array of custom model definitions with `name` and `input`
+ * @returns A new factory function that accepts both original and custom models
+ *
+ * @example
+ * ```typescript
+ * import { extendAdapter, createModel } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
+ *
+ * // Define custom models
+ * const customModels = [
+ *   createModel('my-fine-tuned-gpt4', ['text', 'image']),
+ *   createModel('local-llama', ['text']),
+ * ] as const
+ *
+ * // Create extended adapter
+ * const myOpenai = extendAdapter(openaiText, customModels)
+ *
+ * // Use with original models - full type inference preserved
+ * const gpt4 = myOpenai('gpt-4o')
+ *
+ * // Use with custom models
+ * const custom = myOpenai('my-fine-tuned-gpt4')
+ *
+ * // Type error: 'invalid-model' is not a valid model
+ * // myOpenai('invalid-model')
+ *
+ * // Works with chat()
+ * chat({
+ *   adapter: myOpenai('my-fine-tuned-gpt4'),
+ *   messages: [...]
+ * })
+ * ```
+ */
+export function extendAdapter<
+  TFactory extends (...args: Array<any>) => any,
+  const TDefs extends ReadonlyArray<ExtendedModelDef>,
+>(
+  factory: TFactory,
+  _customModels: TDefs,
+): (
+  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,
+  ...args: InferConfig<TFactory> extends undefined
+    ? []
+    : [config?: InferConfig<TFactory>]
+) => InferAdapterReturn<TFactory> {
+  // At runtime, we simply pass through to the original factory.
+  // The _customModels parameter is only used for type inference.
+  // No runtime validation - users are trusted to pass valid model names.
+  return factory as any
+}

package/src/index.ts

@@ -114,3 +114,7 @@ export type {
   ToolResultState,
   JSONParser,
 } from './activities/chat/stream/index'
+
+// Adapter extension utilities
+export { createModel, extendAdapter } from './extend-adapter'
+export type { ExtendedModelDef } from './extend-adapter'

package/src/types.ts

@@ -789,9 +789,9 @@ export interface TextMessageContentEvent extends BaseAGUIEvent {
   type: 'TEXT_MESSAGE_CONTENT'
   /** Message identifier */
   messageId: string
-  /** The incremental content token (may be undefined if only content is provided) */
-  delta?: string
-  /** Full accumulated content so far */
+  /** The incremental content token */
+  delta: string
+  /** Full accumulated content so far (optional, for debugging) */
   content?: string
 }
 
@@ -864,8 +864,8 @@ export interface StepFinishedEvent extends BaseAGUIEvent {
   /** Step identifier */
   stepId: string
   /** Incremental thinking content */
-  delta?: string
-  /** Full accumulated thinking content */
+  delta: string
+  /** Full accumulated thinking content (optional, for debugging) */
   content?: string
 }
 
@@ -967,6 +967,7 @@ export interface SummarizationResult {
  */
 export interface ImageGenerationOptions<
   TProviderOptions extends object = object,
+  TSize extends string = string,
 > {
   /** The model to use for image generation */
   model: string
@@ -975,7 +976,7 @@ export interface ImageGenerationOptions<
   /** Number of images to generate (default: 1) */
   numberOfImages?: number
   /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
-  size?: string
+  size?: TSize
   /** Model-specific options for image generation */
   modelOptions?: TProviderOptions
 }
@@ -1022,13 +1023,14 @@ export interface ImageGenerationResult {
  */
 export interface VideoGenerationOptions<
   TProviderOptions extends object = object,
+  TSize extends string = string,
 > {
   /** The model to use for video generation */
   model: string
   /** Text description of the desired video */
   prompt: string
-  /** Video size in WIDTHxHEIGHT format (e.g., "1280x720") */
-  size?: string
+  /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
+  size?: TSize
   /** Video duration in seconds */
   duration?: number
   /** Model-specific options for video generation */