@tanstack/ai 0.0.3 → 0.2.0

package/src/{core/chat.ts → activities/chat/index.ts}

@@ -1,26 +1,186 @@
-import { aiEventClient } from '../event-client.js'
-import { ToolCallManager, executeToolCalls } from '../tools/tool-calls'
-import { maxIterations as maxIterationsStrategy } from '../utilities/agent-loop-strategies'
+/**
+ * Text Activity
+ *
+ * Handles agentic text generation, one-shot text generation, and agentic structured output.
+ * This is a self-contained module with implementation, types, and JSDoc.
+ */
+
+import { aiEventClient } from '../../event-client.js'
+import { streamToText } from '../../stream-to-response.js'
+import { ToolCallManager, executeToolCalls } from './tools/tool-calls'
+import {
+  convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
+} from './tools/schema-converter'
+import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import type {
   ApprovalRequest,
   ClientToolRequest,
   ToolResult,
-} from '../tools/tool-calls'
+} from './tools/tool-calls'
+import type { AnyTextAdapter } from './adapter'
 import type {
-  AIAdapter,
   AgentLoopStrategy,
-  ChatOptions,
-  ChatStreamOptionsForModel,
+  ConstrainedModelMessage,
   DoneStreamChunk,
+  InferSchemaType,
   ModelMessage,
+  SchemaInput,
   StreamChunk,
+  TextOptions,
   Tool,
   ToolCall,
-} from '../types'
+} from '../../types'
+
+// ===========================
+// Activity Kind
+// ===========================
+
+/** The adapter kind this activity handles */
+export const kind = 'text' as const
+
+// ===========================
+// Activity Options Type
+// ===========================
+
+/**
+ * Options for the text activity.
+ * Types are extracted directly from the adapter (which has pre-resolved generics).
+ *
+ * @template TAdapter - The text adapter type (created by a provider function)
+ * @template TSchema - Optional Standard Schema for structured output
+ * @template TStream - Whether to stream the output (default: true)
+ */
+export interface TextActivityOptions<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined,
+  TStream extends boolean,
+> {
+  /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
+  adapter: TAdapter
+  /** Conversation messages - content types are constrained by the adapter's input modalities and metadata */
+  messages?: Array<
+    ConstrainedModelMessage<{
+      inputModalities: TAdapter['~types']['inputModalities']
+      messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
+    }>
+  >
+  /** System prompts to prepend to the conversation */
+  systemPrompts?: TextOptions['systemPrompts']
+  /** Tools for function calling (auto-executed when called) */
+  tools?: TextOptions['tools']
+  /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
+  temperature?: TextOptions['temperature']
+  /** Nucleus sampling parameter. The model considers tokens with topP probability mass. */
+  topP?: TextOptions['topP']
+  /** The maximum number of tokens to generate in the response. */
+  maxTokens?: TextOptions['maxTokens']
+  /** Additional metadata to attach to the request. */
+  metadata?: TextOptions['metadata']
+  /** Model-specific provider options (type comes from adapter) */
+  modelOptions?: TAdapter['~types']['providerOptions']
+  /** AbortController for cancellation */
+  abortController?: TextOptions['abortController']
+  /** Strategy for controlling the agent loop */
+  agentLoopStrategy?: TextOptions['agentLoopStrategy']
+  /** Unique conversation identifier for tracking */
+  conversationId?: TextOptions['conversationId']
+  /**
+   * Optional Standard Schema for structured output.
+   * When provided, the activity will:
+   * 1. Run the full agentic loop (executing tools as needed)
+   * 2. Once complete, return a Promise with the parsed output matching the schema
+   *
+   * Supports any Standard Schema compliant library (Zod v4+, ArkType, Valibot, etc.)
+   *
+   * @example
+   * ```ts
+   * const result = await chat({
+   *   adapter: openaiText('gpt-4o'),
+   *   messages: [{ role: 'user', content: 'Generate a person' }],
+   *   outputSchema: z.object({ name: z.string(), age: z.number() })
+   * })
+   * // result is { name: string, age: number }
+   * ```
+   */
+  outputSchema?: TSchema
+  /**
+   * Whether to stream the text result.
+   * When true (default), returns an AsyncIterable<StreamChunk> for streaming output.
+   * When false, returns a Promise<string> with the collected text content.
+   *
+   * Note: If outputSchema is provided, this option is ignored and the result
+   * is always a Promise<InferSchemaType<TSchema>>.
+   *
+   * @default true
+   *
+   * @example Non-streaming text
+   * ```ts
+   * const text = await chat({
+   *   adapter: openaiText('gpt-4o'),
+   *   messages: [{ role: 'user', content: 'Hello!' }],
+   *   stream: false
+   * })
+   * // text is a string with the full response
+   * ```
+   */
+  stream?: TStream
+}
+
+// ===========================
+// Chat Options Helper
+// ===========================
+
+/**
+ * Create typed options for the chat() function without executing.
+ * This is useful for pre-defining configurations with full type inference.
+ *
+ * @example
+ * ```ts
+ * const chatOptions = createChatOptions({
+ *   adapter: anthropicText('claude-sonnet-4-5'),
+ * })
+ *
+ * const stream = chat({ ...chatOptions, messages })
+ * ```
+ */
+export function createChatOptions<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined = undefined,
+  TStream extends boolean = true,
+>(
+  options: TextActivityOptions<TAdapter, TSchema, TStream>,
+): TextActivityOptions<TAdapter, TSchema, TStream> {
+  return options
+}
+
+// ===========================
+// Activity Result Type
+// ===========================
 
-interface ChatEngineConfig<
-  TAdapter extends AIAdapter<any, any, any, any>,
-  TParams extends ChatOptions<any, any> = ChatOptions<any>,
+/**
+ * Result type for the text activity.
+ * - If outputSchema is provided: Promise<InferSchemaType<TSchema>>
+ * - If stream is false: Promise<string>
+ * - Otherwise (stream is true, default): AsyncIterable<StreamChunk>
+ */
+export type TextActivityResult<
+  TSchema extends SchemaInput | undefined,
+  TStream extends boolean = true,
+> = TSchema extends SchemaInput
+  ? Promise<InferSchemaType<TSchema>>
+  : TStream extends false
+    ? Promise<string>
+    : AsyncIterable<StreamChunk>
+
+// ===========================
+// ChatEngine Implementation
+// ===========================
+
+interface TextEngineConfig<
+  TAdapter extends AnyTextAdapter,
+  TParams extends TextOptions<any, any> = TextOptions<any>,
 > {
   adapter: TAdapter
   systemPrompts?: Array<string>
@@ -28,11 +188,11 @@ interface ChatEngineConfig<
 }
 
 type ToolPhaseResult = 'continue' | 'stop' | 'wait'
-type CyclePhase = 'processChat' | 'executeToolCalls'
+type CyclePhase = 'processText' | 'executeToolCalls'
 
-class ChatEngine<
-  TAdapter extends AIAdapter<any, any, any, any>,
-  TParams extends ChatOptions<any, any> = ChatOptions<any>,
+class TextEngine<
+  TAdapter extends AnyTextAdapter,
+  TParams extends TextOptions<any, any> = TextOptions<any>,
 > {
   private readonly adapter: TAdapter
   private readonly params: TParams
@@ -57,9 +217,9 @@ class ChatEngine<
   private shouldEmitStreamEnd = true
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
-  private cyclePhase: CyclePhase = 'processChat'
+  private cyclePhase: CyclePhase = 'processText'
 
-  constructor(config: ChatEngineConfig<TAdapter, TParams>) {
+  constructor(config: TextEngineConfig<TAdapter, TParams>) {
     this.adapter = config.adapter
     this.params = config.params
     this.systemPrompts = config.params.systemPrompts || []
@@ -77,8 +237,18 @@ class ChatEngine<
     this.effectiveSignal = config.params.abortController?.signal
   }
 
-  async *chat(): AsyncGenerator<StreamChunk> {
-    this.beforeChat()
+  /** Get the accumulated content after the chat loop completes */
+  getAccumulatedContent(): string {
+    return this.accumulatedContent
+  }
+
+  /** Get the final messages array after the chat loop completes */
+  getMessages(): Array<ModelMessage> {
+    return this.messages
+  }
+
+  async *run(): AsyncGenerator<StreamChunk> {
+    this.beforeRun()
 
     try {
       const pendingPhase = yield* this.checkForPendingToolCalls()
@@ -93,7 +263,7 @@ class ChatEngine<
 
         this.beginCycle()
 
-        if (this.cyclePhase === 'processChat') {
+        if (this.cyclePhase === 'processText') {
           yield* this.streamModelResponse()
         } else {
           yield* this.processToolCalls()
@@ -102,16 +272,31 @@ class ChatEngine<
         this.endCycle()
       } while (this.shouldContinue())
     } finally {
-      this.afterChat()
+      this.afterRun()
     }
   }
 
-  private beforeChat(): void {
+  private beforeRun(): void {
     this.streamStartTime = Date.now()
-    const { model, tools, options, providerOptions, conversationId } =
-      this.params
-
-    aiEventClient.emit('chat:started', {
+    const {
+      model,
+      tools,
+      temperature,
+      topP,
+      maxTokens,
+      metadata,
+      modelOptions,
+      conversationId,
+    } = this.params
+
+    // Gather flattened options into an object for event emission
+    const options: Record<string, unknown> = {}
+    if (temperature !== undefined) options.temperature = temperature
+    if (topP !== undefined) options.topP = topP
+    if (maxTokens !== undefined) options.maxTokens = maxTokens
+    if (metadata !== undefined) options.metadata = metadata
+
+    aiEventClient.emit('text:started', {
       requestId: this.requestId,
       streamId: this.streamId,
       model: model,
@@ -122,8 +307,8 @@ class ChatEngine<
       timestamp: Date.now(),
       clientId: conversationId,
       toolNames: tools?.map((t) => t.name),
-      options: options as Record<string, unknown> | undefined,
-      providerOptions: providerOptions as Record<string, unknown> | undefined,
+      options: Object.keys(options).length > 0 ? options : undefined,
+      modelOptions: modelOptions as Record<string, unknown> | undefined,
     })
 
     aiEventClient.emit('stream:started', {
@@ -134,15 +319,15 @@ class ChatEngine<
     })
   }
 
-  private afterChat(): void {
+  private afterRun(): void {
     if (!this.shouldEmitStreamEnd) {
       return
     }
 
     const now = Date.now()
 
-    // Emit chat:completed with final state
-    aiEventClient.emit('chat:completed', {
+    // Emit text:completed with final state
+    aiEventClient.emit('text:completed', {
       requestId: this.requestId,
       streamId: this.streamId,
       model: this.params.model,
@@ -163,18 +348,18 @@ class ChatEngine<
   }
 
   private beginCycle(): void {
-    if (this.cyclePhase === 'processChat') {
+    if (this.cyclePhase === 'processText') {
       this.beginIteration()
     }
   }
 
   private endCycle(): void {
-    if (this.cyclePhase === 'processChat') {
+    if (this.cyclePhase === 'processText') {
       this.cyclePhase = 'executeToolCalls'
       return
     }
 
-    this.cyclePhase = 'processChat'
+    this.cyclePhase = 'processText'
     this.iterationCount++
   }
 
@@ -185,17 +370,30 @@ class ChatEngine<
   }
 
   private async *streamModelResponse(): AsyncGenerator<StreamChunk> {
-    const adapterOptions = this.params.options || {}
-    const providerOptions = this.params.providerOptions
+    const { temperature, topP, maxTokens, metadata, modelOptions } = this.params
     const tools = this.params.tools
 
+    // Convert tool schemas to JSON Schema before passing to adapter
+    const toolsWithJsonSchemas = tools?.map((tool) => ({
+      ...tool,
+      inputSchema: tool.inputSchema
+        ? convertSchemaToJsonSchema(tool.inputSchema)
+        : undefined,
+      outputSchema: tool.outputSchema
+        ? convertSchemaToJsonSchema(tool.outputSchema)
+        : undefined,
+    }))
+
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
       messages: this.messages,
-      tools,
-      options: adapterOptions,
+      tools: toolsWithJsonSchemas,
+      temperature,
+      topP,
+      maxTokens,
+      metadata,
       request: this.effectiveRequest,
-      providerOptions,
+      modelOptions,
       systemPrompts: this.systemPrompts,
     })) {
       if (this.isAborted()) {
@@ -365,7 +563,7 @@ class ChatEngine<
 
     const doneChunk = this.createSyntheticDoneChunk()
 
-    aiEventClient.emit('chat:iteration', {
+    aiEventClient.emit('text:iteration', {
       requestId: this.requestId,
       streamId: this.streamId,
       iterationNumber: this.iterationCount + 1,
@@ -431,7 +629,7 @@ class ChatEngine<
       return
     }
 
-    aiEventClient.emit('chat:iteration', {
+    aiEventClient.emit('text:iteration', {
       requestId: this.requestId,
       streamId: this.streamId,
       iterationNumber: this.iterationCount + 1,
@@ -710,62 +908,220 @@ class ChatEngine<
   }
 }
 
+// ===========================
+// Activity Implementation
+// ===========================
+
 /**
- * Standalone chat streaming function with type inference from adapter
- * Returns an async iterable of StreamChunks for streaming responses
- * Includes automatic tool execution loop
+ * Text activity - handles agentic text generation, one-shot text generation, and agentic structured output.
  *
- * @param options Chat options
- * @param options.adapter - AI adapter instance to use
- * @param options.model - Model name (autocompletes based on adapter)
- * @param options.messages - Conversation messages
- * @param options.tools - Optional tools for function calling (auto-executed)
- * @param options.agentLoopStrategy - Optional strategy for controlling tool execution loop
+ * This activity supports four modes:
+ * 1. **Streaming agentic text**: Stream responses with automatic tool execution
+ * 2. **Streaming one-shot text**: Simple streaming request/response without tools
+ * 3. **Non-streaming text**: Returns collected text as a string (stream: false)
+ * 4. **Agentic structured output**: Run tools, then return structured data
  *
- * @example
- * ```typescript
- * const stream = chat({
- *   adapter: openai(),
- *   model: 'gpt-4o',
- *   messages: [{ role: 'user', content: 'Hello!' }],
- *   tools: [weatherTool], // Optional: auto-executed when called
- * });
+ * @example Full agentic text (streaming with tools)
+ * ```ts
+ * import { chat } from '@tanstack/ai'
+ * import { openaiText } from '@tanstack/ai-openai'
  *
- * for await (const chunk of stream) {
+ * for await (const chunk of chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'What is the weather?' }],
+ *   tools: [weatherTool]
+ * })) {
  *   if (chunk.type === 'content') {
- *     console.log(chunk.delta);
+ *     console.log(chunk.delta)
  *   }
  * }
  * ```
+ *
+ * @example One-shot text (streaming without tools)
+ * ```ts
+ * for await (const chunk of chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * })) {
+ *   console.log(chunk)
+ * }
+ * ```
+ *
+ * @example Non-streaming text (stream: false)
+ * ```ts
+ * const text = await chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   stream: false
+ * })
+ * // text is a string with the full response
+ * ```
+ *
+ * @example Agentic structured output (tools + structured response)
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const result = await chat({
+ *   adapter: openaiText('gpt-4o'),
+ *   messages: [{ role: 'user', content: 'Research and summarize the topic' }],
+ *   tools: [researchTool, analyzeTool],
+ *   outputSchema: z.object({
+ *     summary: z.string(),
+ *     keyPoints: z.array(z.string())
+ *   })
+ * })
+ * // result is { summary: string, keyPoints: string[] }
+ * ```
  */
-export async function* chat<
-  TAdapter extends AIAdapter<any, any, any, any, any, any>,
-  const TModel extends TAdapter extends AIAdapter<
-    infer Models,
-    any,
-    any,
-    any,
-    any,
-    any
-  >
-    ? Models[number]
-    : string,
+export function chat<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined = undefined,
+  TStream extends boolean = true,
 >(
-  options: ChatStreamOptionsForModel<TAdapter, TModel>,
+  options: TextActivityOptions<TAdapter, TSchema, TStream>,
+): TextActivityResult<TSchema, TStream> {
+  const { outputSchema, stream } = options
+
+  // If outputSchema is provided, run agentic structured output
+  if (outputSchema) {
+    return runAgenticStructuredOutput(
+      options as unknown as TextActivityOptions<
+        AnyTextAdapter,
+        SchemaInput,
+        boolean
+      >,
+    ) as TextActivityResult<TSchema, TStream>
+  }
+
+  // If stream is explicitly false, run non-streaming text
+  if (stream === false) {
+    return runNonStreamingText(
+      options as unknown as TextActivityOptions<
+        AnyTextAdapter,
+        undefined,
+        false
+      >,
+    ) as TextActivityResult<TSchema, TStream>
+  }
+
+  // Otherwise, run streaming text (default)
+  return runStreamingText(
+    options as unknown as TextActivityOptions<AnyTextAdapter, undefined, true>,
+  ) as TextActivityResult<TSchema, TStream>
+}
+
+/**
+ * Run streaming text (agentic or one-shot depending on tools)
+ */
+async function* runStreamingText(
+  options: TextActivityOptions<AnyTextAdapter, undefined, true>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, ...chatOptions } = options
+  const { adapter, ...textOptions } = options
+  const model = adapter.model
 
-  const engine = new ChatEngine({
+  const engine = new TextEngine({
     adapter,
-    params: chatOptions as ChatOptions<
-      string,
+    params: { ...textOptions, model } as TextOptions<
       Record<string, any>,
-      undefined,
       Record<string, any>
     >,
   })
 
-  for await (const chunk of engine.chat()) {
+  for await (const chunk of engine.run()) {
     yield chunk
   }
 }
+
+/**
+ * Run non-streaming text - collects all content and returns as a string.
+ * Runs the full agentic loop (if tools are provided) but returns collected text.
+ */
+function runNonStreamingText(
+  options: TextActivityOptions<AnyTextAdapter, undefined, false>,
+): Promise<string> {
+  // Run the streaming text and collect all text using streamToText
+  const stream = runStreamingText(
+    options as unknown as TextActivityOptions<AnyTextAdapter, undefined, true>,
+  )
+
+  return streamToText(stream)
+}
+
+/**
+ * Run agentic structured output:
+ * 1. Execute the full agentic loop (with tools)
+ * 2. Once complete, call adapter.structuredOutput with the conversation context
+ * 3. Validate and return the structured result
+ */
+async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
+  options: TextActivityOptions<AnyTextAdapter, TSchema, boolean>,
+): Promise<InferSchemaType<TSchema>> {
+  const { adapter, outputSchema, ...textOptions } = options
+  const model = adapter.model
+
+  if (!outputSchema) {
+    throw new Error('outputSchema is required for structured output')
+  }
+
+  // Create the engine and run the agentic loop
+  const engine = new TextEngine({
+    adapter,
+    params: { ...textOptions, model } as TextOptions<
+      Record<string, unknown>,
+      Record<string, unknown>
+    >,
+  })
+
+  // Consume the stream to run the agentic loop
+  for await (const _chunk of engine.run()) {
+    // Just consume the stream to execute the agentic loop
+  }
+
+  // Get the final messages from the engine (includes tool results)
+  const finalMessages = engine.getMessages()
+
+  // Build text options for structured output, excluding tools since
+  // the agentic loop is complete and we only need the final response
+  const {
+    tools: _tools,
+    agentLoopStrategy: _als,
+    ...structuredTextOptions
+  } = textOptions
+
+  // Convert the schema to JSON Schema before passing to the adapter
+  const jsonSchema = convertSchemaToJsonSchema(outputSchema)
+  if (!jsonSchema) {
+    throw new Error('Failed to convert output schema to JSON Schema')
+  }
+
+  // Call the adapter's structured output method with the conversation context
+  // The adapter receives JSON Schema and can apply vendor-specific patches
+  const result = await adapter.structuredOutput({
+    chatOptions: {
+      ...structuredTextOptions,
+      model,
+      messages: finalMessages,
+    },
+    outputSchema: jsonSchema,
+  })
+
+  // Validate the result against the schema if it's a Standard Schema
+  if (isStandardSchema(outputSchema)) {
+    return parseWithStandardSchema<InferSchemaType<TSchema>>(
+      outputSchema,
+      result.data,
+    )
+  }
+
+  // For plain JSON Schema, return the data as-is
+  return result.data as InferSchemaType<TSchema>
+}
+
+// Re-export adapter types
+export type {
+  TextAdapter,
+  TextAdapterConfig,
+  StructuredOutputOptions,
+  StructuredOutputResult,
+} from './adapter'
+export { BaseTextAdapter } from './adapter'