@output.ai/llm 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/llm",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Framework abstraction to interact with LLM models",
   "type": "module",
   "main": "src/index.js",

package/src/ai_sdk.js

@@ -5,24 +5,25 @@ import * as AI from 'ai';
 import { validateGenerateTextArgs, validateGenerateObjectArgs, validateGenerateArrayArgs, validateGenerateEnumArgs } from './validations.js';
 import { loadPrompt } from './prompt_loader.js';
 
-/*
-  Word of wisdom:
-  We could retrieve the result object using the rest operator:
-  ```js
-  const { usage, providerMetadata, ...rest } = response;
-  const result = rest[resultProperty];
-  ```
-  But we CAN'T because the response of the generateText is an instance of `DefaultGenerateTextResult`
-  and 'text' is a getter (`get text()`).
-  Be aware of this when refactoring.
-*/
 const traceWrapper = async ( { traceId, resultProperty, fn } ) => {
   try {
     const response = await fn();
     const { usage, providerMetadata } = response;
     const result = response[resultProperty];
     Tracing.addEventEnd( { id: traceId, details: { result, usage, providerMetadata } } );
-    return result;
+
+    // Use a Proxy to add 'result' as a unified field name without mutating the AI SDK response.
+    // This preserves the original response object (with its getters/prototype) while allowing
+    // developers to use 'result' consistently across all generate* functions.
+    // Note: Don't use spread/rest on response - AI SDK uses getters that won't copy correctly.
+    return new Proxy( response, {
+      get( target, prop, receiver ) {
+        if ( prop === 'result' ) {
+          return target[resultProperty];
+        }
+        return Reflect.get( target, prop, receiver );
+      }
+    } );
   } catch ( error ) {
     Tracing.addEventError( { id: traceId, details: error } );
     throw error;
@@ -63,7 +64,7 @@ const extraAiSdkOptionsFromPrompt = prompt => {
  * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
  * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
  * @throws {FatalError} If the prompt file is not found or template rendering fails
- * @returns {Promise<string>} Generated text
+ * @returns {Promise<GenerateTextResult>} AI SDK response with text and metadata
  */
 export async function generateText( { prompt, variables } ) {
   validateGenerateTextArgs( { prompt, variables } );
@@ -87,7 +88,7 @@ export async function generateText( { prompt, variables } ) {
  * @param {string} [args.schemaDescription] - Output schema description
  * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
  * @throws {FatalError} If the prompt file is not found or template rendering fails
- * @returns {Promise<object>} Object matching the provided schema
+ * @returns {Promise<GenerateObjectResult>} AI SDK response with object and metadata
  */
 export async function generateObject( args ) {
   validateGenerateObjectArgs( args );
@@ -118,7 +119,7 @@ export async function generateObject( args ) {
  * @param {string} [args.schemaDescription] - Output schema description
  * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
  * @throws {FatalError} If the prompt file is not found or template rendering fails
- * @returns {Promise<object>} Array where each element matches the schema
+ * @returns {Promise<GenerateObjectResult>} AI SDK response with array and metadata
  */
 export async function generateArray( args ) {
   validateGenerateArrayArgs( args );
@@ -147,7 +148,7 @@ export async function generateArray( args ) {
  * @param {string[]} args.enum - Allowed values for the generation
  * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
  * @throws {FatalError} If the prompt file is not found or template rendering fails
- * @returns {Promise<string>} One of the provided enum values
+ * @returns {Promise<GenerateObjectResult>} AI SDK response with enum value and metadata
  */
 export async function generateEnum( args ) {
   validateGenerateEnumArgs( args );

package/src/ai_sdk.spec.js

@@ -52,8 +52,17 @@ beforeEach( () => {
   loadModelImpl.mockReset().mockReturnValue( 'MODEL' );
   loadPromptImpl.mockReset().mockReturnValue( basePrompt );
 
-  aiFns.generateText.mockReset().mockResolvedValue( { text: 'TEXT' } );
-  aiFns.generateObject.mockReset().mockResolvedValue( { object: 'OBJECT' } );
+  aiFns.generateText.mockReset().mockResolvedValue( {
+    text: 'TEXT',
+    sources: [],
+    usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+    finishReason: 'stop'
+  } );
+  aiFns.generateObject.mockReset().mockResolvedValue( {
+    object: 'OBJECT',
+    usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+    finishReason: 'stop'
+  } );
 
   validators.validateGenerateTextArgs.mockClear();
   validators.validateGenerateObjectArgs.mockClear();
@@ -83,12 +92,19 @@ describe( 'ai_sdk', () => {
       temperature: 0.3,
       providerOptions: basePrompt.config.providerOptions
     } );
-    expect( result ).toBe( 'TEXT' );
+    expect( result.text ).toBe( 'TEXT' );
+    expect( result.sources ).toEqual( [] );
+    expect( result.usage ).toEqual( { inputTokens: 10, outputTokens: 5, totalTokens: 15 } );
+    expect( result.finishReason ).toBe( 'stop' );
   } );
 
   it( 'generateObject: validates, traces, calls AI with output object and returns object', async () => {
     const { generateObject } = await importSut();
-    aiFns.generateObject.mockResolvedValueOnce( { object: { a: 1 } } );
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: { a: 1 },
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
 
     const schema = z.object( { a: z.number() } );
     const result = await generateObject( {
@@ -113,12 +129,16 @@ describe( 'ai_sdk', () => {
       temperature: 0.3,
       providerOptions: basePrompt.config.providerOptions
     } );
-    expect( result ).toEqual( { a: 1 } );
+    expect( result.object ).toEqual( { a: 1 } );
   } );
 
   it( 'generateArray: validates, traces, calls AI (item schema) and returns array', async () => {
     const { generateArray } = await importSut();
-    aiFns.generateObject.mockResolvedValueOnce( { object: [ 1, 2 ] } );
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: [ 1, 2 ],
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
 
     const schema = z.number();
     const result = await generateArray( {
@@ -143,12 +163,16 @@ describe( 'ai_sdk', () => {
       temperature: 0.3,
       providerOptions: basePrompt.config.providerOptions
     } );
-    expect( result ).toEqual( [ 1, 2 ] );
+    expect( result.object ).toEqual( [ 1, 2 ] );
   } );
 
   it( 'generateEnum: validates, traces, calls AI with output enum and returns value', async () => {
     const { generateEnum } = await importSut();
-    aiFns.generateObject.mockResolvedValueOnce( { object: 'B' } );
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: 'B',
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
 
     const result = await generateEnum( { prompt: 'test_prompt@v1', enum: [ 'A', 'B', 'C' ] } );
 
@@ -165,6 +189,309 @@ describe( 'ai_sdk', () => {
       temperature: 0.3,
       providerOptions: basePrompt.config.providerOptions
     } );
-    expect( result ).toBe( 'B' );
+    expect( result.object ).toBe( 'B' );
+  } );
+
+  it( 'generateText: passes provider-specific options to AI SDK', async () => {
+    const promptWithProviderOptions = {
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-20250514',
+        providerOptions: {
+          thinking: {
+            type: 'enabled',
+            budgetTokens: 5000
+          },
+          anthropic: {
+            effort: 'medium',
+            customOption: 'value'
+          },
+          customField: 'should-be-passed'
+        }
+      },
+      messages: [ { role: 'user', content: 'Test' } ]
+    };
+    loadPromptImpl.mockReturnValueOnce( promptWithProviderOptions );
+
+    const { generateText } = await importSut();
+    await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( aiFns.generateText ).toHaveBeenCalledWith( {
+      model: 'MODEL',
+      messages: promptWithProviderOptions.messages,
+      providerOptions: {
+        thinking: {
+          type: 'enabled',
+          budgetTokens: 5000
+        },
+        anthropic: {
+          effort: 'medium',
+          customOption: 'value'
+        },
+        customField: 'should-be-passed'
+      }
+    } );
+  } );
+
+  it( 'generateObject: passes provider-specific options to AI SDK', async () => {
+    const promptWithOpenAIOptions = {
+      config: {
+        provider: 'openai',
+        model: 'o3-mini',
+        temperature: 0.8,
+        providerOptions: {
+          openai: {
+            reasoningEffort: 'high',
+            reasoningSummary: 'detailed'
+          }
+        }
+      },
+      messages: [ { role: 'user', content: 'Generate object' } ]
+    };
+    loadPromptImpl.mockReturnValueOnce( promptWithOpenAIOptions );
+
+    const { generateObject } = await importSut();
+    const schema = z.object( { result: z.string() } );
+    await generateObject( { prompt: 'test_prompt@v1', schema } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'object',
+      schema,
+      schemaName: undefined,
+      schemaDescription: undefined,
+      model: 'MODEL',
+      messages: promptWithOpenAIOptions.messages,
+      temperature: 0.8,
+      providerOptions: {
+        openai: {
+          reasoningEffort: 'high',
+          reasoningSummary: 'detailed'
+        }
+      }
+    } );
+  } );
+
+  it( 'generateArray: passes azure-specific options to AI SDK', async () => {
+    const promptWithAzureOptions = {
+      config: {
+        provider: 'azure',
+        model: 'gpt-4',
+        maxTokens: 2000,
+        providerOptions: {
+          azure: {
+            deploymentName: 'my-deployment',
+            apiVersion: '2023-12-01-preview'
+          }
+        }
+      },
+      messages: [ { role: 'user', content: 'Generate array' } ]
+    };
+    loadPromptImpl.mockReturnValueOnce( promptWithAzureOptions );
+
+    const { generateArray } = await importSut();
+    const schema = z.string();
+    await generateArray( { prompt: 'test_prompt@v1', schema } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'array',
+      schema,
+      schemaName: undefined,
+      schemaDescription: undefined,
+      model: 'MODEL',
+      messages: promptWithAzureOptions.messages,
+      maxOutputTokens: 2000,
+      providerOptions: {
+        azure: {
+          deploymentName: 'my-deployment',
+          apiVersion: '2023-12-01-preview'
+        }
+      }
+    } );
+  } );
+
+  it( 'generateEnum: passes mixed provider options to AI SDK', async () => {
+    const promptWithMixedOptions = {
+      config: {
+        provider: 'anthropic',
+        model: 'claude-3-opus-20240229',
+        providerOptions: {
+          thinking: {
+            type: 'enabled',
+            budgetTokens: 3000
+          },
+          anthropic: {
+            effort: 'high'
+          },
+          customField: { nested: 'value' }
+        }
+      },
+      messages: [ { role: 'user', content: 'Choose option' } ]
+    };
+    loadPromptImpl.mockReturnValueOnce( promptWithMixedOptions );
+
+    const { generateEnum } = await importSut();
+    await generateEnum( { prompt: 'test_prompt@v1', enum: [ 'A', 'B', 'C' ] } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'enum',
+      enum: [ 'A', 'B', 'C' ],
+      model: 'MODEL',
+      messages: promptWithMixedOptions.messages,
+      providerOptions: {
+        thinking: {
+          type: 'enabled',
+          budgetTokens: 3000
+        },
+        anthropic: {
+          effort: 'high'
+        },
+        customField: { nested: 'value' }
+      }
+    } );
+  } );
+
+  it( 'generateText: passes through providerMetadata', async () => {
+    aiFns.generateText.mockResolvedValueOnce( {
+      text: 'TEXT',
+      sources: [],
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop',
+      providerMetadata: { anthropic: { cacheReadInputTokens: 50 } }
+    } );
+
+    const { generateText } = await importSut();
+    const result = await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( result.providerMetadata ).toEqual( { anthropic: { cacheReadInputTokens: 50 } } );
+  } );
+
+  it( 'generateText: passes through warnings and response metadata', async () => {
+    aiFns.generateText.mockResolvedValueOnce( {
+      text: 'TEXT',
+      sources: [],
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop',
+      warnings: [ { type: 'other', message: 'Test warning' } ],
+      response: { id: 'req_123', modelId: 'gpt-4o-2024-05-13' }
+    } );
+
+    const { generateText } = await importSut();
+    const result = await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( result.warnings ).toEqual( [ { type: 'other', message: 'Test warning' } ] );
+    expect( result.response ).toEqual( { id: 'req_123', modelId: 'gpt-4o-2024-05-13' } );
+  } );
+
+  it( 'generateText: includes unified result field that matches text', async () => {
+    const { generateText } = await importSut();
+    const response = await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( response.result ).toBe( 'TEXT' );
+    expect( response.result ).toBe( response.text );
+  } );
+
+  it( 'generateObject: includes unified result field that matches object', async () => {
+    const { generateObject } = await importSut();
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: { a: 1, b: 'test' },
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
+
+    const schema = z.object( { a: z.number(), b: z.string() } );
+    const response = await generateObject( { prompt: 'test_prompt@v1', schema } );
+
+    expect( response.result ).toEqual( { a: 1, b: 'test' } );
+    expect( response.result ).toEqual( response.object );
+  } );
+
+  it( 'generateArray: includes unified result field that matches object', async () => {
+    const { generateArray } = await importSut();
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: [ 'item1', 'item2', 'item3' ],
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
+
+    const schema = z.string();
+    const response = await generateArray( { prompt: 'test_prompt@v1', schema } );
+
+    expect( response.result ).toEqual( [ 'item1', 'item2', 'item3' ] );
+    expect( response.result ).toEqual( response.object );
+  } );
+
+  it( 'generateEnum: includes unified result field that matches object', async () => {
+    const { generateEnum } = await importSut();
+    aiFns.generateObject.mockResolvedValueOnce( {
+      object: 'yes',
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    } );
+
+    const response = await generateEnum( { prompt: 'test_prompt@v1', enum: [ 'yes', 'no' ] } );
+
+    expect( response.result ).toBe( 'yes' );
+    expect( response.result ).toBe( response.object );
+  } );
+
+  it( 'generateText: traces error and rethrows when AI SDK fails', async () => {
+    const error = new Error( 'API rate limit exceeded' );
+    aiFns.generateText.mockRejectedValueOnce( error );
+    const { generateText } = await importSut();
+
+    await expect( generateText( { prompt: 'test_prompt@v1' } ) ).rejects.toThrow( 'API rate limit exceeded' );
+    expect( tracingSpies.addEventError ).toHaveBeenCalledWith(
+      expect.objectContaining( { details: error } )
+    );
+  } );
+
+  it( 'generateObject: traces error and rethrows when AI SDK fails', async () => {
+    const error = new Error( 'Invalid schema' );
+    aiFns.generateObject.mockRejectedValueOnce( error );
+    const { generateObject } = await importSut();
+
+    const schema = z.object( { a: z.number() } );
+    await expect( generateObject( { prompt: 'test_prompt@v1', schema } ) ).rejects.toThrow( 'Invalid schema' );
+    expect( tracingSpies.addEventError ).toHaveBeenCalledWith(
+      expect.objectContaining( { details: error } )
+    );
+  } );
+
+  it( 'generateText: Proxy correctly handles AI SDK response with getter', async () => {
+    const responseWithGetter = {
+      _internalText: 'TEXT_FROM_GETTER',
+      get text() {
+        return this._internalText;
+      },
+      sources: [],
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    };
+    aiFns.generateText.mockResolvedValueOnce( responseWithGetter );
+
+    const { generateText } = await importSut();
+    const response = await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( response.text ).toBe( 'TEXT_FROM_GETTER' );
+    expect( response.result ).toBe( 'TEXT_FROM_GETTER' );
+  } );
+
+  it( 'generateObject: Proxy correctly handles AI SDK response with getter', async () => {
+    const responseWithGetter = {
+      _internalObject: { value: 42 },
+      get object() {
+        return this._internalObject;
+      },
+      usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      finishReason: 'stop'
+    };
+    aiFns.generateObject.mockResolvedValueOnce( responseWithGetter );
+
+    const { generateObject } = await importSut();
+    const schema = z.object( { value: z.number() } );
+    const response = await generateObject( { prompt: 'test_prompt@v1', schema } );
+
+    expect( response.object ).toEqual( { value: 42 } );
+    expect( response.result ).toEqual( { value: 42 } );
   } );
 } );

package/src/index.d.ts

@@ -1,23 +1,32 @@
 import type { z } from '@output.ai/core';
+import type {
+  GenerateTextResult as AIGenerateTextResult,
+  GenerateObjectResult as AIGenerateObjectResult
+} from 'ai';
 
 /**
- * Represents a single message in a prompt conversation
+ * Represents a single message in a prompt conversation.
+ *
  * @example
+ * ```ts
  * const msg: PromptMessage = {
  *   role: 'user',
  *   content: 'Hello, Claude!'
  * };
+ * ```
  */
 export type PromptMessage = {
-  /** The role of the message. Examples: 'system', 'user', 'assistant' */
+  /** The role of the message. Examples include 'system', 'user', and 'assistant'. */
   role: string;
   /** The content of the message */
   content: string;
 };
 
 /**
- * Configuration for LLM prompt generation
+ * Configuration for LLM prompt generation.
+ *
  * @example
+ * ```ts
  * const prompt: Prompt = {
  *   name: 'summarizePrompt',
  *   config: {
@@ -28,14 +37,15 @@ export type PromptMessage = {
  *   },
  *   messages: [...]
  * };
+ * ```
  */
 export type Prompt = {
   /** Name of the prompt file */
   name: string;
 
-  /** General configurations for the LLM */
+  /** General configuration for the LLM */
   config: {
-    /** LLM Provider */
+    /** LLM provider */
     provider: 'anthropic' | 'openai' | 'azure' | 'vertex';
 
     /** Model name/identifier */
@@ -44,10 +54,10 @@ export type Prompt = {
     /** Generation temperature (0-2). Lower = more deterministic */
     temperature?: number;
 
-    /** Maximum tokens in the response */
+    /** Maximum number of tokens in the response */
     maxTokens?: number;
 
-    /** Provider-specific configurations */
+    /** Provider-specific options */
     providerOptions?: Record<string, unknown>;
   };
 
@@ -55,12 +65,42 @@ export type Prompt = {
   messages: PromptMessage[];
 };
 
+// Re-export AI SDK types directly (auto-synced with AI SDK updates)
+export type {
+  LanguageModelUsage,
+  FinishReason,
+  LanguageModelResponseMetadata,
+  ProviderMetadata,
+  CallWarning
+} from 'ai';
+
+/**
+ * Result from generateText including full AI SDK response metadata.
+ * Extends AI SDK's GenerateTextResult with a unified `result` field.
+ */
+export type GenerateTextResult =
+  AIGenerateTextResult<Record<string, never>, unknown> & {
+    /** Unified field name alias for 'text' - provides consistency across all generate* functions */
+    result: string;
+  };
+
+/**
+ * Result from generateObject/generateArray/generateEnum including full AI SDK response metadata.
+ * Extends AI SDK's GenerateObjectResult with a unified `result` field.
+ * @typeParam T - The type of the generated object, inferred from the schema parameter
+ */
+export type GenerateObjectResult<T> =
+  AIGenerateObjectResult<T> & {
+    /** Unified field name alias for 'object' - provides consistency across all generate* functions */
+    result: T;
+  };
+
 /**
- * Load a prompt file and render it with variables.
+ * Loads a prompt file and interpolates variables into its content.
  *
- * @param {string} name - Name of the prompt file (without .prompt extension)
- * @param {Record<string, string | number | boolean>} [variables] - Variables to interpolate
- * @returns {Prompt} Loaded and rendered prompt object
+ * @param name - Name of the prompt file (without `.prompt` extension).
+ * @param variables - Variables to interpolate.
+ * @returns The loaded prompt object.
  */
 export function loadPrompt(
   name: string,
@@ -71,33 +111,33 @@ export function loadPrompt(
  * Use an LLM model to generate text.
  *
  * This function is a wrapper over the AI SDK's `generateText`.
- * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
  *
- * @param {object} args - Generation arguments
- * @param {string} args.prompt - Prompt file name
- * @param {Record<string, string | number | boolean>} args.variables - Variables to interpolate
- * @returns {Promise<string>} Generated text
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @returns AI SDK response with text and metadata.
  */
 export function generateText(
   args: {
     prompt: string,
     variables?: Record<string, string | number | boolean>
   }
-): Promise<string>;
+): Promise<GenerateTextResult>;
 
 /**
  * Use an LLM model to generate an object with a fixed schema.
  *
  * This function is a wrapper over the AI SDK's `generateObject`.
- * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
  *
- * @param {object} args - Generation arguments
- * @param {string} args.prompt - Prompt file name
- * @param {Record<string, string | number | boolean>} args.variables - Variables to interpolate
- * @param {z.ZodObject} args.schema - Output schema
- * @param {string} [args.schemaName] - Output schema name
- * @param {string} [args.schemaDescription] - Output schema description
- * @returns {Promise<object>} Object matching the provided schema
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @param args.schema - Output schema.
+ * @param args.schemaName - Output schema name.
+ * @param args.schemaDescription - Output schema description.
+ * @returns AI SDK response with object and metadata.
  */
 export function generateObject<TSchema extends z.ZodObject>(
   args: {
@@ -107,21 +147,21 @@ export function generateObject<TSchema extends z.ZodObject>(
     schemaName?: string,
     schemaDescription?: string
   }
-): Promise<z.infer<TSchema>>;
+): Promise<GenerateObjectResult<z.infer<TSchema>>>;
 
 /**
  * Use an LLM model to generate an array of values with a fixed schema.
  *
  * This function is a wrapper over the AI SDK's `generateObject` with `output: 'array'`.
- * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
  *
- * @param {object} args - Generation arguments
- * @param {string} args.prompt - Prompt file name
- * @param {Record<string, string | number | boolean>} args.variables - Variables to interpolate
- * @param {z.ZodType} args.schema - Output schema (array item)
- * @param {string} [args.schemaName] - Output schema name
- * @param {string} [args.schemaDescription] - Output schema description
- * @returns {Promise<object>} Array where each element matches the schema
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @param args.schema - Output schema (array item).
+ * @param args.schemaName - Output schema name.
+ * @param args.schemaDescription - Output schema description.
+ * @returns AI SDK response with array and metadata.
  */
 export function generateArray<TSchema extends z.ZodType>(
   args: {
@@ -131,19 +171,19 @@ export function generateArray<TSchema extends z.ZodType>(
     schemaName?: string,
     schemaDescription?: string
   }
-): Promise<Array<z.infer<TSchema>>>;
+): Promise<GenerateObjectResult<Array<z.infer<TSchema>>>>;
 
 /**
  * Use an LLM model to generate a result from an enum (array of string values).
  *
  * This function is a wrapper over the AI SDK's `generateObject` with `output: 'enum'`.
- * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
  *
- * @param {object} args - Generation arguments
- * @param {string} args.prompt - Prompt file name
- * @param {Record<string, string | number | boolean>} args.variables - Variables to interpolate
- * @param {string[]} args.enum - Allowed values for the generation
- * @returns {Promise<string>} One of the provided enum values
+ * @param args - Generation arguments.
+ * @param args.prompt - Prompt file name.
+ * @param args.variables - Variables to interpolate.
+ * @param args.enum - Allowed values for the generation.
+ * @returns AI SDK response with enum value and metadata.
  */
 export function generateEnum<const TEnum extends readonly [string, ...string[]]>(
   args: {
@@ -151,4 +191,4 @@ export function generateEnum<const TEnum extends readonly [string, ...string[]]>
     variables?: Record<string, string | number | boolean>,
     enum: TEnum
   }
-): Promise<TEnum[number]>;
+): Promise<GenerateObjectResult<TEnum[number]>>;

package/src/prompt_validations.js

@@ -11,8 +11,13 @@ export const promptSchema = z.object( {
       thinking: z.object( {
         type: z.literal( 'enabled' ),
         budgetTokens: z.number()
-      } ).strict().optional()
-    } ).strict().optional()
+      } ).optional(),
+      anthropic: z.record( z.string(), z.unknown() ).optional(),
+      openai: z.record( z.string(), z.unknown() ).optional(),
+      azure: z.record( z.string(), z.unknown() ).optional(),
+      vertex: z.record( z.string(), z.unknown() ).optional(),
+      google: z.record( z.string(), z.unknown() ).optional()
+    } ).passthrough().optional()
   } ).strict(),
   messages: z.array(
     z.object( {
@@ -35,6 +40,19 @@ const getHintForError = errorMessage => {
   return '';
 };
 
+// Known providerOptions fields. Note: these don't map 1:1 to providers.
+// - 'google' is used by Vertex provider for Gemini language models
+// - 'vertex' is used by Vertex provider for Imagen image models
+// - 'anthropic' is used by both Anthropic provider and Vertex Anthropic
+const knownProviderOptionsFields = new Set( [
+  'thinking',
+  'anthropic',
+  'openai',
+  'azure',
+  'vertex',
+  'google'
+] );
+
 export function validatePrompt( prompt ) {
   const result = promptSchema.safeParse( prompt );
   if ( !result.success ) {
@@ -47,4 +65,12 @@ export function validatePrompt( prompt ) {
       { cause: result.error }
     );
   }
+
+  const providerOptions = prompt?.config?.providerOptions;
+  if ( providerOptions ) {
+    const unknownFields = Object.keys( providerOptions ).filter( k => !knownProviderOptionsFields.has( k ) );
+    if ( unknownFields.length > 0 ) {
+      console.warn( `Prompt "${prompt.name}": Unrecognized providerOptions fields: ${unknownFields.join( ', ' )}` );
+    }
+  }
 }

package/src/prompt_validations.spec.js

@@ -65,6 +65,115 @@ describe( 'validatePrompt', () => {
     expect( () => validatePrompt( promptWithThinking ) ).not.toThrow();
   } );
 
+  it( 'should validate a prompt with anthropic-specific providerOptions', () => {
+    const promptWithAnthropicOptions = {
+      name: 'anthropic-options-prompt',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4-20250514',
+        providerOptions: {
+          thinking: {
+            type: 'enabled',
+            budgetTokens: 5000
+          },
+          anthropic: {
+            effort: 'medium',
+            customOption: 'value'
+          }
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Solve this problem.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithAnthropicOptions ) ).not.toThrow();
+  } );
+
+  it( 'should validate a prompt with openai-specific providerOptions', () => {
+    const promptWithOpenAIOptions = {
+      name: 'openai-options-prompt',
+      config: {
+        provider: 'openai',
+        model: 'o3-mini',
+        providerOptions: {
+          openai: {
+            reasoningEffort: 'high',
+            reasoningSummary: 'detailed',
+            customParameter: 'test'
+          }
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Analyze this data.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithOpenAIOptions ) ).not.toThrow();
+  } );
+
+  it( 'should validate a prompt with azure-specific providerOptions', () => {
+    const promptWithAzureOptions = {
+      name: 'azure-options-prompt',
+      config: {
+        provider: 'azure',
+        model: 'gpt-4',
+        providerOptions: {
+          azure: {
+            deploymentName: 'my-deployment',
+            customConfig: { key: 'value' }
+          }
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Process this request.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithAzureOptions ) ).not.toThrow();
+  } );
+
+  it( 'should validate a prompt with mixed providerOptions including unknown fields', () => {
+    const promptWithMixedOptions = {
+      name: 'mixed-options-prompt',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-3-opus-20240229',
+        providerOptions: {
+          thinking: {
+            type: 'enabled',
+            budgetTokens: 3000
+          },
+          anthropic: {
+            effort: 'high'
+          },
+          customProviderField: 'should-be-allowed',
+          anotherCustomField: {
+            nested: 'value',
+            array: [ 1, 2, 3 ]
+          }
+        }
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Complex request with multiple options.'
+        }
+      ]
+    };
+
+    expect( () => validatePrompt( promptWithMixedOptions ) ).not.toThrow();
+  } );
+
   it( 'should throw ValidationError when provider is invalid', () => {
     const invalidPrompt = {
       name: 'invalid-provider',