@tanstack/ai 0.21.3 → 0.22.0

package/src/activities/generateSpeech/index.ts

@@ -103,10 +103,10 @@ function createId(prefix: string): string {
  * @example Generate speech from text
  * ```ts
  * import { generateSpeech } from '@tanstack/ai'
- * import { openaiTTS } from '@tanstack/ai-openai'
+ * import { openaiSpeech } from '@tanstack/ai-openai'
  *
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1-hd'),
+ *   adapter: openaiSpeech('tts-1-hd'),
  *   text: 'Hello, welcome to TanStack AI!',
  *   voice: 'nova'
  * })
@@ -117,7 +117,7 @@ function createId(prefix: string): string {
  * @example With format and speed options
  * ```ts
  * const result = await generateSpeech({
- *   adapter: openaiTTS('tts-1'),
+ *   adapter: openaiSpeech('tts-1'),
  *   text: 'This is slower speech.',
  *   voice: 'alloy',
  *   format: 'wav',

package/src/types.ts

@@ -800,10 +800,26 @@ export interface TextOptions<
 
   /**
    * Schema for structured output.
-   * When provided, the adapter should use the provider's native structured output API
-   * to ensure the response conforms to this schema.
-   * The schema will be converted to JSON Schema format before being sent to the provider.
-   * Supports any Standard JSON Schema compliant library (Zod, ArkType, Valibot, etc.).
+   *
+   * **Two distinct use sites:**
+   *
+   * 1. **User-facing (activity layer):** accepts any
+   *    {@link SchemaInput} — Zod, ArkType, Valibot, or a raw JSON Schema.
+   *    The activity layer converts to JSON Schema before handing off.
+   *
+   * 2. **Adapter-facing (`chatStream` call):** the engine populates this with
+   *    a pre-converted JSON Schema **only** when the adapter declared
+   *    `supportsCombinedToolsAndSchema(modelOptions) === true`. The adapter
+   *    should then wire the schema into the upstream request (e.g.
+   *    `response_format: { type: 'json_schema', ... }`, `text.format`,
+   *    `output_format`) alongside any `tools`. The model's natural final
+   *    turn carries the schema-constrained JSON text and the engine
+   *    harvests it from the agent loop without a separate finalization
+   *    round-trip.
+   *
+   *    Adapters that did NOT declare the capability never see this field
+   *    populated — the engine instead invokes `structuredOutput` /
+   *    `structuredOutputStream` after the agent loop.
    */
   outputSchema?: SchemaInput
   /**