@tanstack/ai 0.0.3 → 0.2.0

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)}`
+  }
+}

package/src/activities/summarize/index.ts

@@ -0,0 +1,287 @@
+/**
+ * Summarize Activity
+ *
+ * Generates summaries from text input.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import { aiEventClient } from '../../event-client.js'
+import type { SummarizeAdapter } from './adapter'
+import type {
+  StreamChunk,
+  SummarizationOptions,
+  SummarizationResult,
+} from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'summarize' as const
+
+// ===========================
+// Type Extraction Helpers
+// ===========================
+
+/** Extract provider options from a SummarizeAdapter via ~types */
+export type SummarizeProviderOptions<TAdapter> =
+  TAdapter extends SummarizeAdapter<any, any>
+    ? TAdapter['~types']['providerOptions']
+    : object
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the summarize activity.
+ * The model is extracted from the adapter's model property.
+ *
+ * @template TAdapter - The summarize adapter type
+ * @template TStream - Whether to stream the output
+ */
+export interface SummarizeActivityOptions<
+  TAdapter extends SummarizeAdapter<string, object>,
+  TStream extends boolean = false,
+> {
+  /** The summarize adapter to use (must be created with a model) */
+  adapter: TAdapter & { kind: typeof kind }
+  /** The text to summarize */
+  text: string
+  /** Maximum length of the summary (in words or characters, provider-dependent) */
+  maxLength?: number
+  /** Style of summary to generate */
+  style?: 'bullet-points' | 'paragraph' | 'concise'
+  /** Topics or aspects to focus on in the summary */
+  focus?: Array<string>
+  /** Provider-specific options */
+  modelOptions?: SummarizeProviderOptions<TAdapter>
+  /**
+   * Whether to stream the summarization result.
+   * When true, returns an AsyncIterable<StreamChunk> for streaming output.
+   * When false or not provided, returns a Promise<SummarizationResult>.
+   *
+   * @default false
+   */
+  stream?: TStream
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
+
+/**
+ * Result type for the summarize activity.
+ * - If stream is true: AsyncIterable<StreamChunk>
+ * - Otherwise: Promise<SummarizationResult>
+ */
+export type SummarizeActivityResult<TStream extends boolean> =
+  TStream extends true
+    ? AsyncIterable<StreamChunk>
+    : Promise<SummarizationResult>
+
+// ===========================
+// Helper Functions
+// ===========================
+
+function createId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+// ===========================
+// Activity Implementation
+// ===========================
+
+/**
+ * Summarize activity - generates summaries from text.
+ *
+ * Supports both streaming and non-streaming modes.
+ *
+ * @example Basic summarization
+ * ```ts
+ * import { summarize } from '@tanstack/ai'
+ * import { openaiSummarize } from '@tanstack/ai-openai'
+ *
+ * const result = await summarize({
+ *   adapter: openaiSummarize('gpt-4o-mini'),
+ *   text: 'Long article text here...'
+ * })
+ *
+ * console.log(result.summary)
+ * ```
+ *
+ * @example Summarization with style
+ * ```ts
+ * const result = await summarize({
+ *   adapter: openaiSummarize('gpt-4o-mini'),
+ *   text: 'Long article text here...',
+ *   style: 'bullet-points',
+ *   maxLength: 100
+ * })
+ * ```
+ *
+ * @example Focused summarization
+ * ```ts
+ * const result = await summarize({
+ *   adapter: openaiSummarize('gpt-4o-mini'),
+ *   text: 'Long technical document...',
+ *   focus: ['key findings', 'methodology']
+ * })
+ * ```
+ *
+ * @example Streaming summarization
+ * ```ts
+ * for await (const chunk of summarize({
+ *   adapter: openaiSummarize('gpt-4o-mini'),
+ *   text: 'Long article text here...',
+ *   stream: true
+ * })) {
+ *   if (chunk.type === 'content') {
+ *     process.stdout.write(chunk.delta)
+ *   }
+ * }
+ * ```
+ */
+export function summarize<
+  TAdapter extends SummarizeAdapter<string, object>,
+  TStream extends boolean = false,
+>(
+  options: SummarizeActivityOptions<TAdapter, TStream>,
+): SummarizeActivityResult<TStream> {
+  const { stream } = options
+
+  if (stream) {
+    return runStreamingSummarize(
+      options as unknown as SummarizeActivityOptions<
+        SummarizeAdapter<string, object>,
+        true
+      >,
+    ) as SummarizeActivityResult<TStream>
+  }
+
+  return runSummarize(
+    options as unknown as SummarizeActivityOptions<
+      SummarizeAdapter<string, object>,
+      false
+    >,
+  ) as SummarizeActivityResult<TStream>
+}
+
+/**
+ * Run non-streaming summarization
+ */
+async function runSummarize(
+  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, false>,
+): Promise<SummarizationResult> {
+  const { adapter, text, maxLength, style, focus } = options
+  const model = adapter.model
+  const requestId = createId('summarize')
+  const inputLength = text.length
+  const startTime = Date.now()
+
+  aiEventClient.emit('summarize:started', {
+    requestId,
+    model,
+    inputLength,
+    timestamp: startTime,
+  })
+
+  const summarizeOptions: SummarizationOptions = {
+    model,
+    text,
+    maxLength,
+    style,
+    focus,
+  }
+
+  const result = await adapter.summarize(summarizeOptions)
+
+  const duration = Date.now() - startTime
+  const outputLength = result.summary.length
+
+  aiEventClient.emit('summarize:completed', {
+    requestId,
+    model,
+    inputLength,
+    outputLength,
+    duration,
+    timestamp: Date.now(),
+  })
+
+  return result
+}
+
+/**
+ * Run streaming summarization
+ * Uses the adapter's native streaming if available, otherwise falls back
+ * to non-streaming and yields the result as a single chunk.
+ */
+async function* runStreamingSummarize(
+  options: SummarizeActivityOptions<SummarizeAdapter<string, object>, true>,
+): AsyncIterable<StreamChunk> {
+  const { adapter, text, maxLength, style, focus } = options
+  const model = adapter.model
+
+  const summarizeOptions: SummarizationOptions = {
+    model,
+    text,
+    maxLength,
+    style,
+    focus,
+  }
+
+  // Use real streaming if the adapter supports it
+  if (adapter.summarizeStream) {
+    yield* adapter.summarizeStream(summarizeOptions)
+    return
+  }
+
+  // Fall back to non-streaming and yield as a single chunk
+  const result = await adapter.summarize(summarizeOptions)
+
+  // Yield content chunk with the summary
+  yield {
+    type: 'content',
+    id: result.id,
+    model: result.model,
+    timestamp: Date.now(),
+    delta: result.summary,
+    content: result.summary,
+    role: 'assistant',
+  }
+
+  // Yield done chunk
+  yield {
+    type: 'done',
+    id: result.id,
+    model: result.model,
+    timestamp: Date.now(),
+    finishReason: 'stop',
+    usage: result.usage,
+  }
+}
+
+// ===========================
+// Options Factory
+// ===========================
+
+/**
+ * Create typed options for the summarize() function without executing.
+ */
+export function createSummarizeOptions<
+  TAdapter extends SummarizeAdapter<string, object>,
+  TStream extends boolean = false,
+>(
+  options: SummarizeActivityOptions<TAdapter, TStream>,
+): SummarizeActivityOptions<TAdapter, TStream> {
+  return options
+}
+
+// Re-export adapter types
+export type {
+  SummarizeAdapter,
+  SummarizeAdapterConfig,
+  AnySummarizeAdapter,
+} from './adapter'
+export { BaseSummarizeAdapter } from './adapter'

package/src/event-client.ts

@@ -110,7 +110,7 @@ export interface AIDevtoolsEventMap {
     duration: number
     timestamp: number
   }
-  'tanstack-ai-devtools:chat:started': {
+  'tanstack-ai-devtools:text:started': {
     requestId: string
     streamId: string
     provider: string
@@ -122,9 +122,9 @@ export interface AIDevtoolsEventMap {
     clientId?: string
     toolNames?: Array<string>
     options?: Record<string, unknown>
-    providerOptions?: Record<string, unknown>
+    modelOptions?: Record<string, unknown>
   }
-  'tanstack-ai-devtools:chat:completed': {
+  'tanstack-ai-devtools:text:completed': {
     requestId: string
     streamId: string
     model: string
@@ -138,7 +138,7 @@ export interface AIDevtoolsEventMap {
     }
     timestamp: number
   }
-  'tanstack-ai-devtools:chat:iteration': {
+  'tanstack-ai-devtools:text:iteration': {
     requestId: string
     streamId: string
     iterationNumber: number
@@ -159,22 +159,6 @@ export interface AIDevtoolsEventMap {
     timestamp: number
   }
 
-  // Embedding events
-  'tanstack-ai-devtools:embedding:started': {
-    requestId: string
-    model: string
-    inputCount: number
-    timestamp: number
-    clientId?: string
-  }
-  'tanstack-ai-devtools:embedding:completed': {
-    requestId: string
-    model: string
-    inputCount: number
-    duration: number
-    timestamp: number
-  }
-
   // Summarize events
   'tanstack-ai-devtools:summarize:started': {
     requestId: string
@@ -192,7 +176,7 @@ export interface AIDevtoolsEventMap {
     timestamp: number
   }
 
-  // Chat Client events - from @tanstack/ai-client package
+  // Text Client events - from @tanstack/ai-client package
   'tanstack-ai-devtools:client:created': {
     clientId: string
     initialMessageCount: number