@tanstack/ai 0.0.2 → 0.1.0

package/src/activities/generateVideo/adapter.ts

@@ -0,0 +1,116 @@
+import type {
+  VideoGenerationOptions,
+  VideoJobResult,
+  VideoStatusResult,
+  VideoUrlResult,
+} from '../../types'
+
+/**
+ * Configuration for video adapter instances
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Video 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.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Generic parameters:
+ * - TModel: The specific model name (e.g., 'sora-2')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface VideoAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used to determine API shape */
+  readonly kind: 'video'
+  /** 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
+  }
+
+  /**
+   * Create a new video generation job.
+   * Returns a job ID that can be used to poll for status and retrieve the video.
+   */
+  createVideoJob: (
+    options: VideoGenerationOptions<TProviderOptions>,
+  ) => Promise<VideoJobResult>
+
+  /**
+   * Get the current status of a video generation job.
+   */
+  getVideoStatus: (jobId: string) => Promise<VideoStatusResult>
+
+  /**
+   * Get the URL to download/view the generated video.
+   * Should only be called after status is 'completed'.
+   */
+  getVideoUrl: (jobId: string) => Promise<VideoUrlResult>
+}
+
+/**
+ * A VideoAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnyVideoAdapter = VideoAdapter<any, any>
+
+/**
+ * Abstract base class for video generation adapters.
+ * Extend this class to implement a video adapter for a specific provider.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Generic parameters match VideoAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseVideoAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements VideoAdapter<TModel, TProviderOptions> {
+  readonly kind = 'video' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: VideoAdapterConfig
+
+  constructor(config: VideoAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract createVideoJob(
+    options: VideoGenerationOptions<TProviderOptions>,
+  ): Promise<VideoJobResult>
+
+  abstract getVideoStatus(jobId: string): Promise<VideoStatusResult>
+
+  abstract getVideoUrl(jobId: string): Promise<VideoUrlResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}

package/src/activities/generateVideo/index.ts

@@ -0,0 +1,261 @@
+/**
+ * Video Activity (Experimental)
+ *
+ * Generates videos from text prompts using a jobs/polling architecture.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+
+import type { VideoAdapter } from './adapter'
+import type {
+  VideoJobResult,
+  VideoStatusResult,
+  VideoUrlResult,
+} from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'video' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/**
+ * Extract provider options from a VideoAdapter via ~types.
+ */
+export type VideoProviderOptions<TAdapter> =
+  TAdapter extends VideoAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Types
+// ===========================
+
+/**
+ * Base options shared by all video activity operations.
+ * The model is extracted from the adapter's model property.
+ */
+interface VideoActivityBaseOptions<
+  TAdapter extends VideoAdapter<string, object>,
+> {
+  /** The video adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+}
+
+/**
+ * Options for creating a new video generation job.
+ * The model is extracted from the adapter's model property.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoCreateOptions<
+  TAdapter extends VideoAdapter<string, object>,
+> extends 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 duration in seconds */
+  duration?: number
+  /** Provider-specific options for video generation */
+  modelOptions?: VideoProviderOptions<TAdapter>
+}
+
+/**
+ * Options for polling the status of a video generation job.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoStatusOptions<
+  TAdapter extends VideoAdapter<string, object>,
+> extends VideoActivityBaseOptions<TAdapter> {
+  /** Request type - get job status */
+  request: 'status'
+  /** The job ID to check status for */
+  jobId: string
+}
+
+/**
+ * Options for getting the URL of a completed video.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface VideoUrlOptions<
+  TAdapter extends VideoAdapter<string, object>,
+> extends VideoActivityBaseOptions<TAdapter> {
+  /** Request type - get video URL */
+  request: 'url'
+  /** The job ID to get URL for */
+  jobId: string
+}
+
+/**
+ * Union type for all video activity options.
+ * Discriminated by the `request` field.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type VideoActivityOptions<
+  TAdapter extends VideoAdapter<string, object>,
+  TRequest extends 'create' | 'status' | 'url' = 'create',
+> = TRequest extends 'status'
+  ? VideoStatusOptions<TAdapter>
+  : TRequest extends 'url'
+    ? VideoUrlOptions<TAdapter>
+    : VideoCreateOptions<TAdapter>
+
+// ===========================
+// Activity Result Types
+// ===========================
+
+/**
+ * Result type for the video activity, based on request type.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type VideoActivityResult<
+  TRequest extends 'create' | 'status' | 'url' = 'create',
+> = TRequest extends 'status'
+  ? Promise<VideoStatusResult>
+  : TRequest extends 'url'
+    ? Promise<VideoUrlResult>
+    : Promise<VideoJobResult>
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Generate video - creates a video generation job from a text prompt.
+ *
+ * Uses AI video generation models to create videos based on natural language descriptions.
+ * Unlike image generation, video generation is asynchronous and requires polling for completion.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @example Create a video generation job
+ * ```ts
+ * import { generateVideo } from '@tanstack/ai'
+ * import { openaiVideo } from '@tanstack/ai-openai'
+ *
+ * // Start a video generation job
+ * const { jobId } = await generateVideo({
+ *   adapter: openaiVideo('sora-2'),
+ *   prompt: 'A cat chasing a dog in a sunny park'
+ * })
+ *
+ * console.log('Job started:', jobId)
+ * ```
+ */
+export async function generateVideo<
+  TAdapter extends VideoAdapter<string, object>,
+>(options: VideoCreateOptions<TAdapter>): Promise<VideoJobResult> {
+  const { adapter, prompt, size, duration, modelOptions } = options
+  const model = adapter.model
+
+  return adapter.createVideoJob({
+    model,
+    prompt,
+    size,
+    duration,
+    modelOptions,
+  })
+}
+
+/**
+ * Get video job status - returns the current status, progress, and URL if available.
+ *
+ * This function combines status checking and URL retrieval. If the job is completed,
+ * it will automatically fetch and include the video URL.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @example Check job status
+ * ```ts
+ * import { getVideoJobStatus } from '@tanstack/ai'
+ * import { openaiVideo } from '@tanstack/ai-openai'
+ *
+ * const result = await getVideoJobStatus({
+ *   adapter: openaiVideo('sora-2'),
+ *   jobId: 'job-123'
+ * })
+ *
+ * console.log('Status:', result.status)
+ * console.log('Progress:', result.progress)
+ * if (result.url) {
+ *   console.log('Video URL:', result.url)
+ * }
+ * ```
+ */
+export async function getVideoJobStatus<
+  TAdapter extends VideoAdapter<string, object>,
+>(options: {
+  adapter: TAdapter & { kind: typeof kind }
+  jobId: string
+}): Promise<{
+  status: 'pending' | 'processing' | 'completed' | 'failed'
+  progress?: number
+  url?: string
+  error?: string
+}> {
+  const { adapter, jobId } = options
+
+  // Get status first
+  const statusResult = await adapter.getVideoStatus(jobId)
+
+  // If completed, also get the URL
+  if (statusResult.status === 'completed') {
+    try {
+      const urlResult = await adapter.getVideoUrl(jobId)
+      return {
+        status: statusResult.status,
+        progress: statusResult.progress,
+        url: urlResult.url,
+      }
+    } catch (error) {
+      // If URL fetch fails, still return status
+      return {
+        status: statusResult.status,
+        progress: statusResult.progress,
+        error:
+          error instanceof Error ? error.message : 'Failed to get video URL',
+      }
+    }
+  }
+
+  // Return status for non-completed jobs
+  return {
+    status: statusResult.status,
+    progress: statusResult.progress,
+    error: statusResult.error,
+  }
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the generateVideo() function without executing.
+ */
+export function createVideoOptions<
+  TAdapter extends VideoAdapter<string, object>,
+>(options: VideoCreateOptions<TAdapter>): VideoCreateOptions<TAdapter> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  VideoAdapter,
+  VideoAdapterConfig,
+  AnyVideoAdapter,
+} from './adapter'
+export { BaseVideoAdapter } from './adapter'

package/src/activities/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Activities Index
+ *
+ * Central hub for all AI activities. This module exports:
+ * - All activity implementations and their types
+ * - All adapter interfaces and base classes
+ * - Unified type definitions
+ *
+ * To add a new activity:
+ * 1. Create a new directory under activities/ with index.ts and adapter.ts
+ * 2. Export the activity and adapter from this file
+ */
+
+// Import the activity functions
+
+// Import adapter types for type definitions
+import type { AnyTextAdapter } from './chat/adapter'
+import type { AnySummarizeAdapter } from './summarize/adapter'
+import type { AnyImageAdapter } from './generateImage/adapter'
+import type { AnyVideoAdapter } from './generateVideo/adapter'
+import type { AnyTTSAdapter } from './generateSpeech/adapter'
+import type { AnyTranscriptionAdapter } from './generateTranscription/adapter'
+
+// ===========================
+// Chat Activity
+// ===========================
+
+export {
+  kind as textKind,
+  chat,
+  type TextActivityOptions,
+  type TextActivityResult,
+} from './chat/index'
+
+export {
+  BaseTextAdapter,
+  type AnyTextAdapter,
+  type TextAdapter,
+  type TextAdapterConfig,
+  type StructuredOutputOptions,
+  type StructuredOutputResult,
+} from './chat/adapter'
+
+// ===========================
+// Summarize Activity
+// ===========================
+
+export {
+  kind as summarizeKind,
+  summarize,
+  type SummarizeActivityOptions,
+  type SummarizeActivityResult,
+  type SummarizeProviderOptions,
+} from './summarize/index'
+
+export {
+  BaseSummarizeAdapter,
+  type SummarizeAdapter,
+  type SummarizeAdapterConfig,
+  type AnySummarizeAdapter,
+} from './summarize/adapter'
+
+// ===========================
+// Image Activity
+// ===========================
+
+export {
+  kind as imageKind,
+  generateImage,
+  type ImageActivityOptions,
+  type ImageActivityResult,
+  type ImageProviderOptionsForModel,
+  type ImageSizeForModel,
+} from './generateImage/index'
+
+export {
+  BaseImageAdapter,
+  type ImageAdapter,
+  type ImageAdapterConfig,
+  type AnyImageAdapter,
+} from './generateImage/adapter'
+
+// ===========================
+// Video Activity (Experimental)
+// ===========================
+
+export {
+  kind as videoKind,
+  generateVideo,
+  getVideoJobStatus,
+  type VideoActivityOptions,
+  type VideoActivityResult,
+  type VideoProviderOptions,
+  type VideoCreateOptions,
+  type VideoStatusOptions,
+  type VideoUrlOptions,
+} from './generateVideo/index'
+
+export {
+  BaseVideoAdapter,
+  type VideoAdapter,
+  type VideoAdapterConfig,
+  type AnyVideoAdapter,
+} from './generateVideo/adapter'
+
+// ===========================
+// TTS Activity
+// ===========================
+
+export {
+  kind as ttsKind,
+  generateSpeech,
+  type TTSActivityOptions,
+  type TTSActivityResult,
+  type TTSProviderOptions,
+} from './generateSpeech/index'
+
+export {
+  BaseTTSAdapter,
+  type TTSAdapter,
+  type TTSAdapterConfig,
+  type AnyTTSAdapter,
+} from './generateSpeech/adapter'
+
+// ===========================
+// Transcription Activity
+// ===========================
+
+export {
+  kind as transcriptionKind,
+  generateTranscription,
+  type TranscriptionActivityOptions,
+  type TranscriptionActivityResult,
+  type TranscriptionProviderOptions,
+} from './generateTranscription/index'
+
+export {
+  BaseTranscriptionAdapter,
+  type TranscriptionAdapter,
+  type TranscriptionAdapterConfig,
+  type AnyTranscriptionAdapter,
+} from './generateTranscription/adapter'
+
+// ===========================
+// Adapter Union Types
+// ===========================
+
+/** Union of all adapter types that can be passed to chat() */
+export type AIAdapter =
+  | AnyTextAdapter
+  | AnySummarizeAdapter
+  | AnyImageAdapter
+  | AnyVideoAdapter
+  | AnyTTSAdapter
+  | AnyTranscriptionAdapter
+
+/** Union type of all adapter kinds */
+export type AdapterKind =
+  | 'text'
+  | 'summarize'
+  | 'image'
+  | 'video'
+  | 'tts'
+  | 'transcription'

package/src/activities/summarize/adapter.ts

@@ -0,0 +1,107 @@
+import type {
+  StreamChunk,
+  SummarizationOptions,
+  SummarizationResult,
+} from '../../types'
+
+/**
+ * Configuration for summarize adapter instances
+ */
+export interface SummarizeAdapterConfig {
+  apiKey?: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+}
+
+/**
+ * Summarize 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., 'gpt-4o')
+ * - TProviderOptions: Provider-specific options (already resolved)
+ */
+export interface SummarizeAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> {
+  /** Discriminator for adapter kind - used by generate() to determine API shape */
+  readonly kind: 'summarize'
+  /** 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
+  }
+
+  /**
+   * Summarize the given text
+   */
+  summarize: (options: SummarizationOptions) => Promise<SummarizationResult>
+
+  /**
+   * Stream summarization of the given text.
+   * Optional - if not implemented, the activity layer will fall back to
+   * non-streaming summarize and yield the result as a single chunk.
+   */
+  summarizeStream?: (
+    options: SummarizationOptions,
+  ) => AsyncIterable<StreamChunk>
+}
+
+/**
+ * A SummarizeAdapter with any/unknown type parameters.
+ * Useful as a constraint in generic functions and interfaces.
+ */
+export type AnySummarizeAdapter = SummarizeAdapter<any, any>
+
+/**
+ * Abstract base class for summarize adapters.
+ * Extend this class to implement a summarize adapter for a specific provider.
+ *
+ * Generic parameters match SummarizeAdapter - all pre-resolved by the provider function.
+ */
+export abstract class BaseSummarizeAdapter<
+  TModel extends string = string,
+  TProviderOptions extends object = Record<string, unknown>,
+> implements SummarizeAdapter<TModel, TProviderOptions> {
+  readonly kind = 'summarize' as const
+  abstract readonly name: string
+  readonly model: TModel
+
+  // Type-only property - never assigned at runtime
+  declare '~types': {
+    providerOptions: TProviderOptions
+  }
+
+  protected config: SummarizeAdapterConfig
+
+  constructor(config: SummarizeAdapterConfig = {}, model: TModel) {
+    this.config = config
+    this.model = model
+  }
+
+  abstract summarize(
+    options: SummarizationOptions,
+  ): Promise<SummarizationResult>
+
+  /**
+   * Stream summarization of the given text.
+   * Override this method in concrete implementations to enable streaming.
+   * If not overridden, the activity layer will fall back to non-streaming.
+   */
+  summarizeStream?(options: SummarizationOptions): AsyncIterable<StreamChunk>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  }
+}