@tanstack/ai 0.0.3 → 0.1.0

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

package/src/index.ts

@@ -1,6 +1,40 @@
-export { chat } from './core/chat'
-export { summarize } from './core/summarize'
-export { embedding } from './core/embedding'
+// Activity functions - individual exports for each activity
+export {
+  chat,
+  summarize,
+  generateImage,
+  generateVideo,
+  getVideoJobStatus,
+  generateSpeech,
+  generateTranscription,
+} from './activities/index'
+
+// Create options functions - for pre-defining typed configurations
+export { createChatOptions } from './activities/chat/index'
+export { createSummarizeOptions } from './activities/summarize/index'
+export { createImageOptions } from './activities/generateImage/index'
+export { createVideoOptions } from './activities/generateVideo/index'
+export { createSpeechOptions } from './activities/generateSpeech/index'
+export { createTranscriptionOptions } from './activities/generateTranscription/index'
+
+// Re-export types
+export type {
+  AIAdapter,
+  ImageAdapter,
+  AnyImageAdapter,
+  TextAdapter,
+  AnyTextAdapter,
+  AnySummarizeAdapter,
+  SummarizeAdapter,
+  AnyTTSAdapter,
+  TTSAdapter,
+  AnyTranscriptionAdapter,
+  TranscriptionAdapter,
+  AnyVideoAdapter,
+  VideoAdapter,
+} from './activities/index'
+
+// Tool definition
 export {
   toolDefinition,
   type ToolDefinition,
@@ -12,33 +46,42 @@ export {
   type InferToolName,
   type InferToolInput,
   type InferToolOutput,
-} from './tools/tool-definition'
-export { convertZodToJsonSchema } from './tools/zod-converter'
+} from './activities/chat/tools/tool-definition'
+export { convertZodToJsonSchema } from './activities/chat/tools/zod-converter'
+
+// Stream utilities
 export {
+  streamToText,
   toServerSentEventsStream,
   toStreamResponse,
-} from './utilities/stream-to-response'
-export { BaseAdapter } from './base-adapter'
-export { ToolCallManager } from './tools/tool-calls'
+  toHttpStream,
+} from './stream-to-response'
+
+// Tool call management
+export { ToolCallManager } from './activities/chat/tools/tool-calls'
+
+// Agent loop strategies
 export {
   maxIterations,
   untilFinishReason,
   combineStrategies,
-} from './utilities/agent-loop-strategies'
+} from './activities/chat/agent-loop-strategies'
+
+// All types
 export * from './types'
-export { chatOptions } from './utilities/chat-options'
-export { messages } from './utilities/messages'
+
+// Event client
 export { aiEventClient } from './event-client'
 
 // Message converters
 export {
   convertMessagesToModelMessages,
+  generateMessageId,
   uiMessageToModelMessages,
   modelMessageToUIMessage,
   modelMessagesToUIMessages,
   normalizeToUIMessage,
-  generateMessageId,
-} from './message-converters'
+} from './activities/chat/messages'
 
 // Stream processing (unified for server and client)
 export {
@@ -52,7 +95,7 @@ export {
   PartialJSONParser,
   defaultJSONParser,
   parsePartialJSON,
-} from './stream'
+} from './activities/chat/stream/index'
 export type {
   ChunkStrategy,
   ChunkRecording,
@@ -65,4 +108,4 @@ export type {
   ToolCallState,
   ToolResultState,
   JSONParser,
-} from './stream'
+} from './activities/chat/stream/index'

package/src/stream-to-response.ts

@@ -0,0 +1,237 @@
+import type { StreamChunk } from './types'
+
+/**
+ * Collect all text content from a StreamChunk async iterable and return as a string.
+ *
+ * This function consumes the entire stream, accumulating content from 'content' type chunks,
+ * and returns the final concatenated text.
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @returns Promise<string> - The accumulated text content
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openaiText(),
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ * const text = await streamToText(stream);
+ * console.log(text); // "Hello! How can I help you today?"
+ * ```
+ */
+export async function streamToText(
+  stream: AsyncIterable<StreamChunk>,
+): Promise<string> {
+  let accumulatedContent = ''
+
+  for await (const chunk of stream) {
+    if (chunk.type === 'content' && chunk.delta) {
+      accumulatedContent += chunk.delta
+    }
+  }
+
+  return accumulatedContent
+}
+
+/**
+ * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format
+ *
+ * This creates a ReadableStream that emits chunks in SSE format:
+ * - Each chunk is prefixed with "data: "
+ * - Each chunk is followed by "\n\n"
+ * - Stream ends with "data: [DONE]\n\n"
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param abortController - Optional AbortController to abort when stream is cancelled
+ * @returns ReadableStream in Server-Sent Events format
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] });
+ * const readableStream = toServerSentEventsStream(stream);
+ * // Use with Response, or any API that accepts ReadableStream
+ * ```
+ */
+export function toServerSentEventsStream(
+  stream: AsyncIterable<StreamChunk>,
+  abortController?: AbortController,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          // Check if stream was cancelled/aborted
+          if (abortController?.signal.aborted) {
+            break
+          }
+
+          // Send each chunk as Server-Sent Events format
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`),
+          )
+        }
+
+        // Send completion marker
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+        controller.close()
+      } catch (error: any) {
+        // Don't send error if aborted
+        if (abortController?.signal.aborted) {
+          controller.close()
+          return
+        }
+
+        // Send error chunk
+        controller.enqueue(
+          encoder.encode(
+            `data: ${JSON.stringify({
+              type: 'error',
+              error: {
+                message: error.message || 'Unknown error occurred',
+                code: error.code,
+              },
+            })}\n\n`,
+          ),
+        )
+        controller.close()
+      }
+    },
+    cancel() {
+      // When the ReadableStream is cancelled (e.g., client disconnects),
+      // abort the underlying stream
+      if (abortController) {
+        abortController.abort()
+      }
+    },
+  })
+}
+
+/**
+ * Convert a StreamChunk async iterable to a ReadableStream in HTTP stream format (newline-delimited JSON)
+ *
+ * This creates a ReadableStream that emits chunks as newline-delimited JSON:
+ * - Each chunk is JSON.stringify'd and followed by "\n"
+ * - No SSE formatting (no "data: " prefix)
+ *
+ * This format is compatible with `fetchHttpStream` connection adapter.
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param abortController - Optional AbortController to abort when stream is cancelled
+ * @returns ReadableStream in HTTP stream format (newline-delimited JSON)
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] });
+ * const readableStream = toHttpStream(stream);
+ * // Use with Response for HTTP streaming (not SSE)
+ * return new Response(readableStream, {
+ *   headers: { 'Content-Type': 'application/x-ndjson' }
+ * });
+ * ```
+ */
+export function toHttpStream(
+  stream: AsyncIterable<StreamChunk>,
+  abortController?: AbortController,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          // Check if stream was cancelled/aborted
+          if (abortController?.signal.aborted) {
+            break
+          }
+
+          // Send each chunk as newline-delimited JSON
+          controller.enqueue(encoder.encode(`${JSON.stringify(chunk)}\n`))
+        }
+
+        controller.close()
+      } catch (error: any) {
+        // Don't send error if aborted
+        if (abortController?.signal.aborted) {
+          controller.close()
+          return
+        }
+
+        // Send error chunk
+        controller.enqueue(
+          encoder.encode(
+            `${JSON.stringify({
+              type: 'error',
+              error: {
+                message: error.message || 'Unknown error occurred',
+                code: error.code,
+              },
+            })}\n`,
+          ),
+        )
+        controller.close()
+      }
+    },
+    cancel() {
+      // When the ReadableStream is cancelled (e.g., client disconnects),
+      // abort the underlying stream
+      if (abortController) {
+        abortController.abort()
+      }
+    },
+  })
+}
+
+/**
+ * Create a streaming HTTP response from a StreamChunk async iterable
+ * Includes proper headers for Server-Sent Events
+ *
+ * @deprecated Use `toServerSentEventsStream` instead. This function will be removed in a future version.
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param init - Optional Response initialization options
+ * @param abortController - Optional AbortController to abort when client disconnects
+ * @returns Response object with SSE headers and streaming body
+ *
+ * @example
+ * ```typescript
+ * export async function POST(request: Request) {
+ *   const { messages } = await request.json();
+ *   const abortController = new AbortController();
+ *   const stream = chat({
+ *     adapter: openaiText(),
+ *     model: "gpt-4o",
+ *     messages,
+ *     options: { abortSignal: abortController.signal }
+ *   });
+ *   return toStreamResponse(stream, undefined, abortController);
+ * }
+ * ```
+ */
+export function toStreamResponse(
+  stream: AsyncIterable<StreamChunk>,
+  init?: ResponseInit & { abortController?: AbortController },
+): Response {
+  if (typeof console !== 'undefined') {
+    console.warn(
+      '`toStreamResponse` is deprecated. Use `toServerSentEventsStream` instead. Example:\n' +
+        '  const readableStream = toServerSentEventsStream(stream, abortController);\n' +
+        '  return new Response(readableStream, {\n' +
+        "    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' }\n" +
+        '  });',
+    )
+  }
+
+  const { headers, abortController, ...responseInit } = init ?? {}
+  return new Response(toServerSentEventsStream(stream, abortController), {
+    ...responseInit,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      ...(headers || {}),
+    },
+  })
+}