@tanstack/ai 0.6.2 → 0.6.3

package/dist/esm/activities/generateImage/index.d.ts

@@ -1,5 +1,5 @@
 import { ImageAdapter } from './adapter.js';
-import { ImageGenerationResult } from '../../types.js';
+import { ImageGenerationResult, StreamChunk } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "image";
 /**
@@ -18,8 +18,9 @@ export type ImageSizeForModel<TAdapter, TModel extends string> = TAdapter extend
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The image adapter type
+ * @template TStream - Whether to stream the output
  */
-export type ImageActivityOptions<TAdapter extends ImageAdapter<string, any, any, any>> = {
+export type ImageActivityOptions<TAdapter extends ImageAdapter<string, any, any, any>, TStream extends boolean = false> = {
     /** The image adapter to use (must be created with a model) */
     adapter: TAdapter & {
         kind: typeof kind;
@@ -30,13 +31,25 @@ export type ImageActivityOptions<TAdapter extends ImageAdapter<string, any, any,
     numberOfImages?: number;
     /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
     size?: ImageSizeForModel<TAdapter, TAdapter['model']>;
+    /**
+     * Whether to stream the image generation result.
+     * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+     * When false or not provided, returns a Promise<ImageGenerationResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
 } & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']> ? {
     /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<TAdapter, TAdapter['model']>;
 } : {
     /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<TAdapter, TAdapter['model']>;
 });
-/** Result type for the image activity */
-export type ImageActivityResult = Promise<ImageGenerationResult>;
+/**
+ * Result type for the image activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<ImageGenerationResult>
+ */
+export type ImageActivityResult<TStream extends boolean = false> = TStream extends true ? AsyncIterable<StreamChunk> : Promise<ImageGenerationResult>;
 /**
  * Image activity - generates images from text prompts.
  *
@@ -82,10 +95,10 @@ export type ImageActivityResult = Promise<ImageGenerationResult>;
  * })
  * ```
  */
-export declare function generateImage<TAdapter extends ImageAdapter<string, any, any, any>>(options: ImageActivityOptions<TAdapter>): ImageActivityResult;
+export declare function generateImage<TAdapter extends ImageAdapter<string, any, any, any>, TStream extends boolean = false>(options: ImageActivityOptions<TAdapter, TStream>): ImageActivityResult<TStream>;
 /**
  * Create typed options for the generateImage() function without executing.
  */
-export declare function createImageOptions<TAdapter extends ImageAdapter<string, any, any, any>>(options: ImageActivityOptions<TAdapter>): ImageActivityOptions<TAdapter>;
+export declare function createImageOptions<TAdapter extends ImageAdapter<string, any, any, any>, TStream extends boolean = false>(options: ImageActivityOptions<TAdapter, TStream>): ImageActivityOptions<TAdapter, TStream>;
 export type { ImageAdapter, ImageAdapterConfig, AnyImageAdapter, } from './adapter.js';
 export { BaseImageAdapter } from './adapter.js';

package/dist/esm/activities/generateImage/index.js

@@ -1,10 +1,19 @@
 import { aiEventClient } from "../../event-client.js";
+import { streamGenerationResult } from "../stream-generation-result.js";
 const kind = "image";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
-async function generateImage(options) {
-  const { adapter, ...rest } = options;
+function generateImage(options) {
+  if (options.stream) {
+    return streamGenerationResult(
+      () => runGenerateImage(options)
+    );
+  }
+  return runGenerateImage(options);
+}
+async function runGenerateImage(options) {
+  const { adapter, stream: _stream, ...rest } = options;
   const model = adapter.model;
   const requestId = createId("image");
   const startTime = Date.now();

package/dist/esm/activities/generateImage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateImage/index.ts"],"sourcesContent":["/**\n * Image Activity\n *\n * Generates images from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport type { ImageAdapter } from './adapter'\nimport type { ImageGenerationResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'image' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract model-specific provider options from an ImageAdapter via ~types.\n * If the model has specific options defined in ModelProviderOptions (and not just via index signature),\n * use those; otherwise fall back to base provider options.\n */\nexport type ImageProviderOptionsForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>\n    ? string extends keyof ModelOptions\n      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions\n        BaseOptions\n      : // ModelOptions has explicit keys - check if TModel is one of them\n        TModel extends keyof ModelOptions\n        ? ModelOptions[TModel]\n        : BaseOptions\n    : object\n\n/**\n * Extract model-specific size options from an ImageAdapter via ~types.\n * If the model has specific sizes defined, use those; otherwise fall back to string.\n */\nexport type ImageSizeForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>\n    ? string extends keyof SizeByName\n      ? // SizeByName has index signature - fall back to string\n        string\n      : // SizeByName has explicit keys - check if TModel is one of them\n        TModel extends keyof SizeByName\n        ? SizeByName[TModel]\n        : string\n    : string\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the image activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The image adapter type\n */\nexport type ImageActivityOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n> = {\n  /** The image adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired image(s) */\n  prompt: string\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: ImageSizeForModel<TAdapter, TAdapter['model']>\n} & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>\n  ? {\n      /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    }\n  : {\n      /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    })\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/** Result type for the image activity */\nexport type ImageActivityResult = Promise<ImageGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Image activity - generates images from text prompts.\n *\n * Uses AI image generation models to create images based on natural language descriptions.\n *\n * @example Generate a single image\n * ```ts\n * import { generateImage } from '@tanstack/ai'\n * import { openaiImage } from '@tanstack/ai-openai'\n *\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A serene mountain landscape at sunset'\n * })\n *\n * console.log(result.images[0].url)\n * ```\n *\n * @example Generate multiple images\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-2'),\n *   prompt: 'A cute robot mascot',\n *   numberOfImages: 4,\n *   size: '512x512'\n * })\n *\n * result.images.forEach((image, i) => {\n *   console.log(`Image ${i + 1}: ${image.url}`)\n * })\n * ```\n *\n * @example With provider-specific options\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A professional headshot photo',\n *   size: '1024x1024',\n *   modelOptions: {\n *     quality: 'hd',\n *     style: 'natural'\n *   }\n * })\n * ```\n */\nexport async function generateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n>(options: ImageActivityOptions<TAdapter>): ImageActivityResult {\n  const { adapter, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('image')\n  const startTime = Date.now()\n\n  aiEventClient.emit('image:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    numberOfImages: rest.numberOfImages,\n    size: rest.size,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  return adapter.generateImages({ ...rest, model }).then((result) => {\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('image:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      images: result.images.map((image) => ({\n        url: image.url,\n        b64Json: image.b64Json,\n      })),\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('image:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    return result\n  })\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateImage() function without executing.\n */\nexport function createImageOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n>(options: ImageActivityOptions<TAdapter>): ImageActivityOptions<TAdapter> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  ImageAdapter,\n  ImageAdapterConfig,\n  AnyImageAdapter,\n} from './adapter'\nexport { BaseImageAdapter } from './adapter'\n"],"names":[],"mappings":";AAgBO,MAAM,OAAO;AA+EpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAmDA,eAAsB,cAEpB,SAA8D;AAC9D,QAAM,EAAE,SAAS,GAAG,KAAA,IAAS;AAC7B,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,MAAM,KAAK;AAAA,IACX,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,EAAE,KAAK,CAAC,WAAW;AACjE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,QAAQ,OAAO,OAAO,IAAI,CAAC,WAAW;AAAA,QACpC,KAAK,MAAM;AAAA,QACX,SAAS,MAAM;AAAA,MAAA,EACf;AAAA,MACF;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,eAAe;AAAA,QAChC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO;AAAA,EACT,CAAC;AACH;AASO,SAAS,mBAEd,SAAyE;AACzE,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateImage/index.ts"],"sourcesContent":["/**\n * Image Activity\n *\n * Generates images from text prompts.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport type { ImageAdapter } from './adapter'\nimport type { ImageGenerationResult, StreamChunk } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'image' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract model-specific provider options from an ImageAdapter via ~types.\n * If the model has specific options defined in ModelProviderOptions (and not just via index signature),\n * use those; otherwise fall back to base provider options.\n */\nexport type ImageProviderOptionsForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, infer BaseOptions, infer ModelOptions, any>\n    ? string extends keyof ModelOptions\n      ? // ModelOptions is Record<string, unknown> or has index signature - use BaseOptions\n        BaseOptions\n      : // ModelOptions has explicit keys - check if TModel is one of them\n        TModel extends keyof ModelOptions\n        ? ModelOptions[TModel]\n        : BaseOptions\n    : object\n\n/**\n * Extract model-specific size options from an ImageAdapter via ~types.\n * If the model has specific sizes defined, use those; otherwise fall back to string.\n */\nexport type ImageSizeForModel<TAdapter, TModel extends string> =\n  TAdapter extends ImageAdapter<any, any, any, infer SizeByName>\n    ? string extends keyof SizeByName\n      ? // SizeByName has index signature - fall back to string\n        string\n      : // SizeByName has explicit keys - check if TModel is one of them\n        TModel extends keyof SizeByName\n        ? SizeByName[TModel]\n        : string\n    : string\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the image activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The image adapter type\n * @template TStream - Whether to stream the output\n */\nexport type ImageActivityOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n> = {\n  /** The image adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** Text description of the desired image(s) */\n  prompt: string\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: ImageSizeForModel<TAdapter, TAdapter['model']>\n  /**\n   * Whether to stream the image generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<ImageGenerationResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n} & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>\n  ? {\n      /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    }\n  : {\n      /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<\n        TAdapter,\n        TAdapter['model']\n      >\n    })\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the image activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<ImageGenerationResult>\n */\nexport type ImageActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<ImageGenerationResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Image activity - generates images from text prompts.\n *\n * Uses AI image generation models to create images based on natural language descriptions.\n *\n * @example Generate a single image\n * ```ts\n * import { generateImage } from '@tanstack/ai'\n * import { openaiImage } from '@tanstack/ai-openai'\n *\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A serene mountain landscape at sunset'\n * })\n *\n * console.log(result.images[0].url)\n * ```\n *\n * @example Generate multiple images\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-2'),\n *   prompt: 'A cute robot mascot',\n *   numberOfImages: 4,\n *   size: '512x512'\n * })\n *\n * result.images.forEach((image, i) => {\n *   console.log(`Image ${i + 1}: ${image.url}`)\n * })\n * ```\n *\n * @example With provider-specific options\n * ```ts\n * const result = await generateImage({\n *   adapter: openaiImage('dall-e-3'),\n *   prompt: 'A professional headshot photo',\n *   size: '1024x1024',\n *   modelOptions: {\n *     quality: 'hd',\n *     style: 'natural'\n *   }\n * })\n * ```\n */\nexport function generateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateImage(options),\n    ) as ImageActivityResult<TStream>\n  }\n\n  return runGenerateImage(options) as ImageActivityResult<TStream>\n}\n\n/**\n * Internal implementation of image generation (always non-streaming).\n * Contains all devtools event emission logic.\n */\nasync function runGenerateImage<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n>(\n  options: ImageActivityOptions<TAdapter, boolean>,\n): Promise<ImageGenerationResult> {\n  const { adapter, stream: _stream, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('image')\n  const startTime = Date.now()\n\n  aiEventClient.emit('image:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    prompt: rest.prompt,\n    numberOfImages: rest.numberOfImages,\n    size: rest.size,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  return adapter.generateImages({ ...rest, model }).then((result) => {\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('image:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      images: result.images.map((image) => ({\n        url: image.url,\n        b64Json: image.b64Json,\n      })),\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    if (result.usage) {\n      aiEventClient.emit('image:usage', {\n        requestId,\n        model,\n        usage: result.usage,\n        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n        timestamp: Date.now(),\n      })\n    }\n\n    return result\n  })\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateImage() function without executing.\n */\nexport function createImageOptions<\n  TAdapter extends ImageAdapter<string, any, any, any>,\n  TStream extends boolean = false,\n>(\n  options: ImageActivityOptions<TAdapter, TStream>,\n): ImageActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  ImageAdapter,\n  ImageAdapterConfig,\n  AnyImageAdapter,\n} from './adapter'\nexport { BaseImageAdapter } from './adapter'\n"],"names":[],"mappings":";;AAiBO,MAAM,OAAO;AAgGpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAmDO,SAAS,cAId,SAC8B;AAC9B,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,iBAAiB,OAAO;AAAA,IAAA;AAAA,EAE5B;AAEA,SAAO,iBAAiB,OAAO;AACjC;AAMA,eAAe,iBAGb,SACgC;AAChC,QAAM,EAAE,SAAS,QAAQ,SAAS,GAAG,SAAS;AAC9C,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,OAAO;AAClC,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,yBAAyB;AAAA,IAC1C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,MAAM,KAAK;AAAA,IACX,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,EAAE,KAAK,CAAC,WAAW;AACjE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,2BAA2B;AAAA,MAC5C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,QAAQ,OAAO,OAAO,IAAI,CAAC,WAAW;AAAA,QACpC,KAAK,MAAM;AAAA,QACX,SAAS,MAAM;AAAA,MAAA,EACf;AAAA,MACF;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,QAAI,OAAO,OAAO;AAChB,oBAAc,KAAK,eAAe;AAAA,QAChC;AAAA,QACA;AAAA,QACA,OAAO,OAAO;AAAA,QACd,cAAc,KAAK;AAAA,QACnB,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAEA,WAAO;AAAA,EACT,CAAC;AACH;AASO,SAAS,mBAId,SACyC;AACzC,SAAO;AACT;"}

package/dist/esm/activities/generateSpeech/index.d.ts

@@ -1,5 +1,5 @@
 import { TTSAdapter } from './adapter.js';
-import { TTSResult } from '../../types.js';
+import { StreamChunk, TTSResult } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "tts";
 /**
@@ -11,8 +11,9 @@ export type TTSProviderOptions<TAdapter> = TAdapter extends TTSAdapter<any, any>
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The TTS adapter type
+ * @template TStream - Whether to stream the output
  */
-export interface TTSActivityOptions<TAdapter extends TTSAdapter<string, object>> {
+export interface TTSActivityOptions<TAdapter extends TTSAdapter<string, object>, TStream extends boolean = false> {
     /** The TTS adapter to use (must be created with a model) */
     adapter: TAdapter & {
         kind: typeof kind;
@@ -27,9 +28,21 @@ export interface TTSActivityOptions<TAdapter extends TTSAdapter<string, object>>
     speed?: number;
     /** Provider-specific options for TTS generation */
     modelOptions?: TTSProviderOptions<TAdapter>;
+    /**
+     * Whether to stream the generation result.
+     * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+     * When false or not provided, returns a Promise<TTSResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
 }
-/** Result type for the TTS activity */
-export type TTSActivityResult = Promise<TTSResult>;
+/**
+ * Result type for the TTS activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<TTSResult>
+ */
+export type TTSActivityResult<TStream extends boolean = false> = TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>;
 /**
  * TTS activity - generates speech from text.
  *
@@ -60,10 +73,10 @@ export type TTSActivityResult = Promise<TTSResult>;
  * })
  * ```
  */
-export declare function generateSpeech<TAdapter extends TTSAdapter<string, object>>(options: TTSActivityOptions<TAdapter>): TTSActivityResult;
+export declare function generateSpeech<TAdapter extends TTSAdapter<string, object>, TStream extends boolean = false>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream>;
 /**
  * Create typed options for the generateSpeech() function without executing.
  */
-export declare function createSpeechOptions<TAdapter extends TTSAdapter<string, object>>(options: TTSActivityOptions<TAdapter>): TTSActivityOptions<TAdapter>;
+export declare function createSpeechOptions<TAdapter extends TTSAdapter<string, object>, TStream extends boolean = false>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityOptions<TAdapter, TStream>;
 export type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter.js';
 export { BaseTTSAdapter } from './adapter.js';

package/dist/esm/activities/generateSpeech/index.js

@@ -1,10 +1,19 @@
 import { aiEventClient } from "../../event-client.js";
+import { streamGenerationResult } from "../stream-generation-result.js";
 const kind = "tts";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
-async function generateSpeech(options) {
-  const { adapter, ...rest } = options;
+function generateSpeech(options) {
+  if (options.stream) {
+    return streamGenerationResult(
+      () => runGenerateSpeech(options)
+    );
+  }
+  return runGenerateSpeech(options);
+}
+async function runGenerateSpeech(options) {
+  const { adapter, stream: _stream, ...rest } = options;
   const model = adapter.model;
   const requestId = createId("speech");
   const startTime = Date.now();

package/dist/esm/activities/generateSpeech/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport type { TTSAdapter } from './adapter'\nimport type { TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> =\n  TAdapter extends TTSAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, object>,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/** Result type for the TTS activity */\nexport type TTSActivityResult = Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiTTS } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiTTS('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiTTS('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport async function generateSpeech<\n  TAdapter extends TTSAdapter<string, object>,\n>(options: TTSActivityOptions<TAdapter>): TTSActivityResult {\n  const { adapter, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  return adapter.generateSpeech({ ...rest, model }).then((result) => {\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    return result\n  })\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, object>,\n>(options: TTSActivityOptions<TAdapter>): TTSActivityOptions<TAdapter> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"names":[],"mappings":";AAgBO,MAAM,OAAO;AAgDpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAoCA,eAAsB,eAEpB,SAA0D;AAC1D,QAAM,EAAE,SAAS,GAAG,KAAA,IAAS;AAC7B,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,QAAQ;AACnC,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,0BAA0B;AAAA,IAC3C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,KAAK;AAAA,IACX,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,EAAE,KAAK,CAAC,WAAW;AACjE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,4BAA4B;AAAA,MAC7C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,eAAe,OAAO;AAAA,MACtB,aAAa,OAAO;AAAA,MACpB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO;AAAA,EACT,CAAC;AACH;AASO,SAAS,oBAEd,SAAqE;AACrE,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateSpeech/index.ts"],"sourcesContent":["/**\n * TTS Activity\n *\n * Generates speech audio from text using text-to-speech models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport type { TTSAdapter } from './adapter'\nimport type { StreamChunk, TTSResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'tts' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TTSAdapter via ~types.\n */\nexport type TTSProviderOptions<TAdapter> =\n  TAdapter extends TTSAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the TTS activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The TTS adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TTSActivityOptions<\n  TAdapter extends TTSAdapter<string, object>,\n  TStream extends boolean = false,\n> {\n  /** The TTS adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Provider-specific options for TTS generation */\n  modelOptions?: TTSProviderOptions<TAdapter>\n  /**\n   * Whether to stream the generation result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TTSResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the TTS activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TTSResult>\n */\nexport type TTSActivityResult<TStream extends boolean = false> =\n  TStream extends true ? AsyncIterable<StreamChunk> : Promise<TTSResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * TTS activity - generates speech from text.\n *\n * Uses AI text-to-speech models to create audio from natural language text.\n *\n * @example Generate speech from text\n * ```ts\n * import { generateSpeech } from '@tanstack/ai'\n * import { openaiTTS } from '@tanstack/ai-openai'\n *\n * const result = await generateSpeech({\n *   adapter: openaiTTS('tts-1-hd'),\n *   text: 'Hello, welcome to TanStack AI!',\n *   voice: 'nova'\n * })\n *\n * console.log(result.audio) // base64-encoded audio\n * ```\n *\n * @example With format and speed options\n * ```ts\n * const result = await generateSpeech({\n *   adapter: openaiTTS('tts-1'),\n *   text: 'This is slower speech.',\n *   voice: 'alloy',\n *   format: 'wav',\n *   speed: 0.8\n * })\n * ```\n */\nexport function generateSpeech<\n  TAdapter extends TTSAdapter<string, object>,\n  TStream extends boolean = false,\n>(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateSpeech(options),\n    ) as TTSActivityResult<TStream>\n  }\n  return runGenerateSpeech(options) as TTSActivityResult<TStream>\n}\n\n/**\n * Run the core TTS generation logic (non-streaming).\n */\nasync function runGenerateSpeech<TAdapter extends TTSAdapter<string, object>>(\n  options: TTSActivityOptions<TAdapter, boolean>,\n): Promise<TTSResult> {\n  const { adapter, stream: _stream, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('speech')\n  const startTime = Date.now()\n\n  aiEventClient.emit('speech:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: rest.text,\n    voice: rest.voice,\n    format: rest.format,\n    speed: rest.speed,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  return adapter.generateSpeech({ ...rest, model }).then((result) => {\n    const duration = Date.now() - startTime\n\n    aiEventClient.emit('speech:request:completed', {\n      requestId,\n      provider: adapter.name,\n      model,\n      audio: result.audio,\n      format: result.format,\n      audioDuration: result.duration,\n      contentType: result.contentType,\n      duration,\n      modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n      timestamp: Date.now(),\n    })\n\n    return result\n  })\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateSpeech() function without executing.\n */\nexport function createSpeechOptions<\n  TAdapter extends TTSAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: TTSActivityOptions<TAdapter, TStream>,\n): TTSActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type { TTSAdapter, TTSAdapterConfig, AnyTTSAdapter } from './adapter'\nexport { BaseTTSAdapter } from './adapter'\n"],"names":[],"mappings":";;AAiBO,MAAM,OAAO;AA+DpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAoCO,SAAS,eAGd,SAA4E;AAC5E,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,kBAAkB,OAAO;AAAA,IAAA;AAAA,EAE7B;AACA,SAAO,kBAAkB,OAAO;AAClC;AAKA,eAAe,kBACb,SACoB;AACpB,QAAM,EAAE,SAAS,QAAQ,SAAS,GAAG,SAAS;AAC9C,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,QAAQ;AACnC,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,0BAA0B;AAAA,IAC3C;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,KAAK;AAAA,IACX,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,SAAO,QAAQ,eAAe,EAAE,GAAG,MAAM,OAAO,EAAE,KAAK,CAAC,WAAW;AACjE,UAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,kBAAc,KAAK,4BAA4B;AAAA,MAC7C;AAAA,MACA,UAAU,QAAQ;AAAA,MAClB;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,eAAe,OAAO;AAAA,MACtB,aAAa,OAAO;AAAA,MACpB;AAAA,MACA,cAAc,KAAK;AAAA,MACnB,WAAW,KAAK,IAAA;AAAA,IAAI,CACrB;AAED,WAAO;AAAA,EACT,CAAC;AACH;AASO,SAAS,oBAId,SACuC;AACvC,SAAO;AACT;"}

package/dist/esm/activities/generateTranscription/index.d.ts

@@ -1,5 +1,5 @@
 import { TranscriptionAdapter } from './adapter.js';
-import { TranscriptionResult } from '../../types.js';
+import { StreamChunk, TranscriptionResult } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "transcription";
 /**
@@ -11,8 +11,9 @@ export type TranscriptionProviderOptions<TAdapter> = TAdapter extends Transcript
  * The model is extracted from the adapter's model property.
  *
  * @template TAdapter - The transcription adapter type
+ * @template TStream - Whether to stream the output
  */
-export interface TranscriptionActivityOptions<TAdapter extends TranscriptionAdapter<string, object>> {
+export interface TranscriptionActivityOptions<TAdapter extends TranscriptionAdapter<string, object>, TStream extends boolean = false> {
     /** The transcription adapter to use (must be created with a model) */
     adapter: TAdapter & {
         kind: typeof kind;
@@ -27,9 +28,21 @@ export interface TranscriptionActivityOptions<TAdapter extends TranscriptionAdap
     responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
     /** Provider-specific options for transcription */
     modelOptions?: TranscriptionProviderOptions<TAdapter>;
+    /**
+     * Whether to stream the transcription result.
+     * When true, returns an AsyncIterable<StreamChunk> for streaming transport.
+     * When false or not provided, returns a Promise<TranscriptionResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
 }
-/** Result type for the transcription activity */
-export type TranscriptionActivityResult = Promise<TranscriptionResult>;
+/**
+ * Result type for the transcription activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<TranscriptionResult>
+ */
+export type TranscriptionActivityResult<TStream extends boolean = false> = TStream extends true ? AsyncIterable<StreamChunk> : Promise<TranscriptionResult>;
 /**
  * Transcription activity - converts audio to text.
  *
@@ -61,11 +74,22 @@ export type TranscriptionActivityResult = Promise<TranscriptionResult>;
  *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)
  * })
  * ```
+ *
+ * @example Streaming transcription result
+ * ```ts
+ * for await (const chunk of generateTranscription({
+ *   adapter: openaiTranscription('whisper-1'),
+ *   audio: audioFile,
+ *   stream: true
+ * })) {
+ *   console.log(chunk)
+ * }
+ * ```
  */
-export declare function generateTranscription<TAdapter extends TranscriptionAdapter<string, object>>(options: TranscriptionActivityOptions<TAdapter>): TranscriptionActivityResult;
+export declare function generateTranscription<TAdapter extends TranscriptionAdapter<string, object>, TStream extends boolean = false>(options: TranscriptionActivityOptions<TAdapter, TStream>): TranscriptionActivityResult<TStream>;
 /**
  * Create typed options for the generateTranscription() function without executing.
  */
-export declare function createTranscriptionOptions<TAdapter extends TranscriptionAdapter<string, object>>(options: TranscriptionActivityOptions<TAdapter>): TranscriptionActivityOptions<TAdapter>;
+export declare function createTranscriptionOptions<TAdapter extends TranscriptionAdapter<string, object>, TStream extends boolean = false>(options: TranscriptionActivityOptions<TAdapter, TStream>): TranscriptionActivityOptions<TAdapter, TStream>;
 export type { TranscriptionAdapter, TranscriptionAdapterConfig, AnyTranscriptionAdapter, } from './adapter.js';
 export { BaseTranscriptionAdapter } from './adapter.js';

package/dist/esm/activities/generateTranscription/index.js

@@ -1,10 +1,21 @@
 import { aiEventClient } from "../../event-client.js";
+import { streamGenerationResult } from "../stream-generation-result.js";
 const kind = "transcription";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
-async function generateTranscription(options) {
-  const { adapter, ...rest } = options;
+function generateTranscription(options) {
+  if (options.stream) {
+    return streamGenerationResult(
+      () => runGenerateTranscription(options)
+    );
+  }
+  return runGenerateTranscription(
+    options
+  );
+}
+async function runGenerateTranscription(options) {
+  const { adapter, stream: _stream, ...rest } = options;
   const model = adapter.model;
   const requestId = createId("transcription");
   const startTime = Date.now();

package/dist/esm/activities/generateTranscription/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../src/activities/generateTranscription/index.ts"],"sourcesContent":["/**\n * Transcription Activity\n *\n * Transcribes audio to text using speech-to-text models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport type { TranscriptionAdapter } from './adapter'\nimport type { TranscriptionResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'transcription' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TranscriptionAdapter via ~types.\n */\nexport type TranscriptionProviderOptions<TAdapter> =\n  TAdapter extends TranscriptionAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the transcription activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The transcription adapter type\n */\nexport interface TranscriptionActivityOptions<\n  TAdapter extends TranscriptionAdapter<string, object>,\n> {\n  /** The transcription adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Provider-specific options for transcription */\n  modelOptions?: TranscriptionProviderOptions<TAdapter>\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/** Result type for the transcription activity */\nexport type TranscriptionActivityResult = Promise<TranscriptionResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Transcription activity - converts audio to text.\n *\n * Uses AI speech-to-text models to transcribe audio content.\n *\n * @example Transcribe an audio file\n * ```ts\n * import { generateTranscription } from '@tanstack/ai'\n * import { openaiTranscription } from '@tanstack/ai-openai'\n *\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile, // File, Blob, or base64 string\n *   language: 'en'\n * })\n *\n * console.log(result.text)\n * ```\n *\n * @example With verbose output for timestamps\n * ```ts\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   responseFormat: 'verbose_json'\n * })\n *\n * result.segments?.forEach(segment => {\n *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)\n * })\n * ```\n */\nexport async function generateTranscription<\n  TAdapter extends TranscriptionAdapter<string, object>,\n>(\n  options: TranscriptionActivityOptions<TAdapter>,\n): TranscriptionActivityResult {\n  const { adapter, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('transcription')\n  const startTime = Date.now()\n\n  aiEventClient.emit('transcription:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    language: rest.language,\n    prompt: rest.prompt,\n    responseFormat: rest.responseFormat,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  const result = await adapter.transcribe({ ...rest, model })\n  const duration = Date.now() - startTime\n\n  aiEventClient.emit('transcription:request:completed', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: result.text,\n    language: result.language,\n    duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: Date.now(),\n  })\n\n  return result\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateTranscription() function without executing.\n */\nexport function createTranscriptionOptions<\n  TAdapter extends TranscriptionAdapter<string, object>,\n>(\n  options: TranscriptionActivityOptions<TAdapter>,\n): TranscriptionActivityOptions<TAdapter> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TranscriptionAdapter,\n  TranscriptionAdapterConfig,\n  AnyTranscriptionAdapter,\n} from './adapter'\nexport { BaseTranscriptionAdapter } from './adapter'\n"],"names":[],"mappings":";AAgBO,MAAM,OAAO;AAgDpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAsCA,eAAsB,sBAGpB,SAC6B;AAC7B,QAAM,EAAE,SAAS,GAAG,KAAA,IAAS;AAC7B,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,eAAe;AAC1C,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,iCAAiC;AAAA,IAClD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,UAAU,KAAK;AAAA,IACf,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,QAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,GAAG,MAAM,OAAO;AAC1D,QAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,gBAAc,KAAK,mCAAmC;AAAA,IACpD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,OAAO;AAAA,IACb,UAAU,OAAO;AAAA,IACjB;AAAA,IACA,cAAc,KAAK;AAAA,IACnB,WAAW,KAAK,IAAA;AAAA,EAAI,CACrB;AAED,SAAO;AACT;AASO,SAAS,2BAGd,SACwC;AACxC,SAAO;AACT;"}
+{"version":3,"file":"index.js","sources":["../../../../src/activities/generateTranscription/index.ts"],"sourcesContent":["/**\n * Transcription Activity\n *\n * Transcribes audio to text using speech-to-text models.\n * This is a self-contained module with implementation, types, and JSDoc.\n */\n\nimport { aiEventClient } from '../../event-client.js'\nimport { streamGenerationResult } from '../stream-generation-result.js'\nimport type { TranscriptionAdapter } from './adapter'\nimport type { StreamChunk, TranscriptionResult } from '../../types'\n\n// ===========================\n// Activity Kind\n// ===========================\n\n/** The adapter kind this activity handles */\nexport const kind = 'transcription' as const\n\n// ===========================\n// Type Extraction Helpers\n// ===========================\n\n/**\n * Extract provider options from a TranscriptionAdapter via ~types.\n */\nexport type TranscriptionProviderOptions<TAdapter> =\n  TAdapter extends TranscriptionAdapter<any, any>\n    ? TAdapter['~types']['providerOptions']\n    : object\n\n// ===========================\n// Activity Options Type\n// ===========================\n\n/**\n * Options for the transcription activity.\n * The model is extracted from the adapter's model property.\n *\n * @template TAdapter - The transcription adapter type\n * @template TStream - Whether to stream the output\n */\nexport interface TranscriptionActivityOptions<\n  TAdapter extends TranscriptionAdapter<string, object>,\n  TStream extends boolean = false,\n> {\n  /** The transcription adapter to use (must be created with a model) */\n  adapter: TAdapter & { kind: typeof kind }\n  /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Provider-specific options for transcription */\n  modelOptions?: TranscriptionProviderOptions<TAdapter>\n  /**\n   * Whether to stream the transcription result.\n   * When true, returns an AsyncIterable<StreamChunk> for streaming transport.\n   * When false or not provided, returns a Promise<TranscriptionResult>.\n   *\n   * @default false\n   */\n  stream?: TStream\n}\n\n// ===========================\n// Activity Result Type\n// ===========================\n\n/**\n * Result type for the transcription activity.\n * - If stream is true: AsyncIterable<StreamChunk>\n * - Otherwise: Promise<TranscriptionResult>\n */\nexport type TranscriptionActivityResult<TStream extends boolean = false> =\n  TStream extends true\n    ? AsyncIterable<StreamChunk>\n    : Promise<TranscriptionResult>\n\nfunction createId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`\n}\n\n// ===========================\n// Activity Implementation\n// ===========================\n\n/**\n * Transcription activity - converts audio to text.\n *\n * Uses AI speech-to-text models to transcribe audio content.\n *\n * @example Transcribe an audio file\n * ```ts\n * import { generateTranscription } from '@tanstack/ai'\n * import { openaiTranscription } from '@tanstack/ai-openai'\n *\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile, // File, Blob, or base64 string\n *   language: 'en'\n * })\n *\n * console.log(result.text)\n * ```\n *\n * @example With verbose output for timestamps\n * ```ts\n * const result = await generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   responseFormat: 'verbose_json'\n * })\n *\n * result.segments?.forEach(segment => {\n *   console.log(`[${segment.start}s - ${segment.end}s]: ${segment.text}`)\n * })\n * ```\n *\n * @example Streaming transcription result\n * ```ts\n * for await (const chunk of generateTranscription({\n *   adapter: openaiTranscription('whisper-1'),\n *   audio: audioFile,\n *   stream: true\n * })) {\n *   console.log(chunk)\n * }\n * ```\n */\nexport function generateTranscription<\n  TAdapter extends TranscriptionAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityResult<TStream> {\n  if (options.stream) {\n    return streamGenerationResult(() =>\n      runGenerateTranscription(options),\n    ) as TranscriptionActivityResult<TStream>\n  }\n\n  return runGenerateTranscription(\n    options,\n  ) as TranscriptionActivityResult<TStream>\n}\n\n/**\n * Run non-streaming transcription\n */\nasync function runGenerateTranscription<\n  TAdapter extends TranscriptionAdapter<string, object>,\n>(\n  options: TranscriptionActivityOptions<TAdapter, boolean>,\n): Promise<TranscriptionResult> {\n  const { adapter, stream: _stream, ...rest } = options\n  const model = adapter.model\n  const requestId = createId('transcription')\n  const startTime = Date.now()\n\n  aiEventClient.emit('transcription:request:started', {\n    requestId,\n    provider: adapter.name,\n    model,\n    language: rest.language,\n    prompt: rest.prompt,\n    responseFormat: rest.responseFormat,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: startTime,\n  })\n\n  const result = await adapter.transcribe({ ...rest, model })\n  const duration = Date.now() - startTime\n\n  aiEventClient.emit('transcription:request:completed', {\n    requestId,\n    provider: adapter.name,\n    model,\n    text: result.text,\n    language: result.language,\n    duration,\n    modelOptions: rest.modelOptions as Record<string, unknown> | undefined,\n    timestamp: Date.now(),\n  })\n\n  return result\n}\n\n// ===========================\n// Options Factory\n// ===========================\n\n/**\n * Create typed options for the generateTranscription() function without executing.\n */\nexport function createTranscriptionOptions<\n  TAdapter extends TranscriptionAdapter<string, object>,\n  TStream extends boolean = false,\n>(\n  options: TranscriptionActivityOptions<TAdapter, TStream>,\n): TranscriptionActivityOptions<TAdapter, TStream> {\n  return options\n}\n\n// Re-export adapter types\nexport type {\n  TranscriptionAdapter,\n  TranscriptionAdapterConfig,\n  AnyTranscriptionAdapter,\n} from './adapter'\nexport { BaseTranscriptionAdapter } from './adapter'\n"],"names":[],"mappings":";;AAiBO,MAAM,OAAO;AAiEpB,SAAS,SAAS,QAAwB;AACxC,SAAO,GAAG,MAAM,IAAI,KAAK,IAAA,CAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AAC1E;AAiDO,SAAS,sBAId,SACsC;AACtC,MAAI,QAAQ,QAAQ;AAClB,WAAO;AAAA,MAAuB,MAC5B,yBAAyB,OAAO;AAAA,IAAA;AAAA,EAEpC;AAEA,SAAO;AAAA,IACL;AAAA,EAAA;AAEJ;AAKA,eAAe,yBAGb,SAC8B;AAC9B,QAAM,EAAE,SAAS,QAAQ,SAAS,GAAG,SAAS;AAC9C,QAAM,QAAQ,QAAQ;AACtB,QAAM,YAAY,SAAS,eAAe;AAC1C,QAAM,YAAY,KAAK,IAAA;AAEvB,gBAAc,KAAK,iCAAiC;AAAA,IAClD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,UAAU,KAAK;AAAA,IACf,QAAQ,KAAK;AAAA,IACb,gBAAgB,KAAK;AAAA,IACrB,cAAc,KAAK;AAAA,IACnB,WAAW;AAAA,EAAA,CACZ;AAED,QAAM,SAAS,MAAM,QAAQ,WAAW,EAAE,GAAG,MAAM,OAAO;AAC1D,QAAM,WAAW,KAAK,IAAA,IAAQ;AAE9B,gBAAc,KAAK,mCAAmC;AAAA,IACpD;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB;AAAA,IACA,MAAM,OAAO;AAAA,IACb,UAAU,OAAO;AAAA,IACjB;AAAA,IACA,cAAc,KAAK;AAAA,IACnB,WAAW,KAAK,IAAA;AAAA,EAAI,CACrB;AAED,SAAO;AACT;AASO,SAAS,2BAId,SACiD;AACjD,SAAO;AACT;"}

package/dist/esm/activities/generateVideo/index.d.ts

@@ -1,5 +1,5 @@
 import { VideoAdapter } from './adapter.js';
-import { VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
+import { StreamChunk, VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
 /** The adapter kind this activity handles */
 export declare const kind: "video";
 /**
@@ -24,9 +24,12 @@ interface VideoActivityBaseOptions<TAdapter extends VideoAdapter<string, any, an
  * Options for creating a new video generation job.
  * The model is extracted from the adapter's model property.
  *
+ * @template TAdapter - The video adapter type
+ * @template TStream - Whether to stream the output
+ *
  * @experimental Video generation is an experimental feature and may change.
  */
-export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, any>> = VideoActivityBaseOptions<TAdapter> & {
+export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false> = VideoActivityBaseOptions<TAdapter> & {
     /** Request type - create a new job (default if not specified) */
     request?: 'create';
     /** Text description of the desired video */
@@ -35,6 +38,21 @@ export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, a
     size?: VideoSizeForAdapter<TAdapter>;
     /** Video duration in seconds */
     duration?: number;
+    /**
+     * Whether to stream the video generation lifecycle.
+     * When true, returns an AsyncIterable<StreamChunk> that handles the full
+     * job lifecycle: create job, poll for status, yield updates, and yield final result.
+     * When false or not provided, returns a Promise<VideoJobResult>.
+     *
+     * @default false
+     */
+    stream?: TStream;
+    /** Polling interval in milliseconds (stream mode only). @default 2000 */
+    pollingInterval?: number;
+    /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
+    maxDuration?: number;
+    /** Custom run ID (stream mode only) */
+    runId?: string;
 } & ({} extends VideoProviderOptions<TAdapter> ? {
     /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>;
 } : {
@@ -68,19 +86,24 @@ export interface VideoUrlOptions<TAdapter extends VideoAdapter<string, any, any,
  *
  * @experimental Video generation is an experimental feature and may change.
  */
-export type VideoActivityOptions<TAdapter extends VideoAdapter<string, any, any, any>, TRequest extends 'create' | 'status' | 'url' = 'create'> = TRequest extends 'status' ? VideoStatusOptions<TAdapter> : TRequest extends 'url' ? VideoUrlOptions<TAdapter> : VideoCreateOptions<TAdapter>;
+export type VideoActivityOptions<TAdapter extends VideoAdapter<string, any, any, any>, TRequest extends 'create' | 'status' | 'url' = 'create', TStream extends boolean = false> = TRequest extends 'status' ? VideoStatusOptions<TAdapter> : TRequest extends 'url' ? VideoUrlOptions<TAdapter> : VideoCreateOptions<TAdapter, TStream>;
 /**
- * Result type for the video activity, based on request type.
+ * Result type for the video activity, based on request type and streaming.
+ * - If stream is true (create request): AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<VideoJobResult | VideoStatusResult | VideoUrlResult>
  *
  * @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>;
+export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = 'create', TStream extends boolean = false> = TRequest extends 'status' ? Promise<VideoStatusResult> : TRequest extends 'url' ? Promise<VideoUrlResult> : TStream extends true ? AsyncIterable<StreamChunk> : Promise<VideoJobResult>;
 /**
  * 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.
  *
+ * When `stream: true` is passed, handles the full job lifecycle automatically:
+ * create job → poll for status → stream updates → yield final result.
+ *
  * @experimental Video generation is an experimental feature and may change.
  *
  * @example Create a video generation job
@@ -96,8 +119,23 @@ export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = '
  *
  * console.log('Job started:', jobId)
  * ```
+ *
+ * @example Stream the full video generation lifecycle
+ * ```ts
+ * import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
+ * import { openaiVideo } from '@tanstack/ai-openai'
+ *
+ * const stream = generateVideo({
+ *   adapter: openaiVideo('sora-2'),
+ *   prompt: 'A cat chasing a dog in a sunny park',
+ *   stream: true,
+ *   pollingInterval: 3000,
+ * })
+ *
+ * return toServerSentEventsResponse(stream)
+ * ```
  */
-export declare function generateVideo<TAdapter extends VideoAdapter<string, any, any, any>>(options: VideoCreateOptions<TAdapter>): Promise<VideoJobResult>;
+export declare function generateVideo<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false>(options: VideoCreateOptions<TAdapter, TStream>): VideoActivityResult<'create', TStream>;
 /**
  * Get video job status - returns the current status, progress, and URL if available.
  *
@@ -137,6 +175,6 @@ export declare function getVideoJobStatus<TAdapter extends VideoAdapter<string,
 /**
  * Create typed options for the generateVideo() function without executing.
  */
-export declare function createVideoOptions<TAdapter extends VideoAdapter<string, any, any, any>>(options: VideoCreateOptions<TAdapter>): VideoCreateOptions<TAdapter>;
+export declare function createVideoOptions<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false>(options: VideoCreateOptions<TAdapter, TStream>): VideoCreateOptions<TAdapter, TStream>;
 export type { VideoAdapter, VideoAdapterConfig, AnyVideoAdapter, } from './adapter.js';
 export { BaseVideoAdapter } from './adapter.js';

package/dist/esm/activities/generateVideo/index.js

@@ -3,7 +3,15 @@ const kind = "video";
 function createId(prefix) {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
-async function generateVideo(options) {
+function generateVideo(options) {
+  if (options.stream) {
+    return runStreamingVideoGeneration(
+      options
+    );
+  }
+  return runCreateVideoJob(options);
+}
+async function runCreateVideoJob(options) {
   const { adapter, prompt, size, duration, modelOptions } = options;
   const model = adapter.model;
   return adapter.createVideoJob({
@@ -14,6 +22,87 @@ async function generateVideo(options) {
     modelOptions
   });
 }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* runStreamingVideoGeneration(options) {
+  const { adapter, prompt, size, duration, modelOptions } = options;
+  const model = adapter.model;
+  const runId = options.runId ?? createId("run");
+  const pollingInterval = options.pollingInterval ?? 2e3;
+  const maxDuration = options.maxDuration ?? 6e5;
+  yield {
+    type: "RUN_STARTED",
+    runId,
+    timestamp: Date.now()
+  };
+  try {
+    const jobResult = await adapter.createVideoJob({
+      model,
+      prompt,
+      size,
+      duration,
+      modelOptions
+    });
+    yield {
+      type: "CUSTOM",
+      name: "video:job:created",
+      value: { jobId: jobResult.jobId },
+      timestamp: Date.now()
+    };
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxDuration) {
+      await sleep(pollingInterval);
+      const statusResult = await adapter.getVideoStatus(jobResult.jobId);
+      yield {
+        type: "CUSTOM",
+        name: "video:status",
+        value: {
+          jobId: jobResult.jobId,
+          status: statusResult.status,
+          progress: statusResult.progress,
+          error: statusResult.error
+        },
+        timestamp: Date.now()
+      };
+      if (statusResult.status === "completed") {
+        const urlResult = await adapter.getVideoUrl(jobResult.jobId);
+        yield {
+          type: "CUSTOM",
+          name: "generation:result",
+          value: {
+            jobId: jobResult.jobId,
+            status: "completed",
+            url: urlResult.url,
+            expiresAt: urlResult.expiresAt
+          },
+          timestamp: Date.now()
+        };
+        yield {
+          type: "RUN_FINISHED",
+          runId,
+          finishReason: "stop",
+          timestamp: Date.now()
+        };
+        return;
+      }
+      if (statusResult.status === "failed") {
+        throw new Error(statusResult.error || "Video generation failed");
+      }
+    }
+    throw new Error("Video generation timed out");
+  } catch (error) {
+    yield {
+      type: "RUN_ERROR",
+      runId,
+      error: {
+        message: error.message || "Video generation failed",
+        code: error.code
+      },
+      timestamp: Date.now()
+    };
+  }
+}
 async function getVideoJobStatus(options) {
   const { adapter, jobId } = options;
   const requestId = createId("video-status");