@output.ai/llm 0.2.8 → 0.2.9

package/README.md

@@ -74,6 +74,49 @@ You are a helpful assistant.
 - **OpenAI** - Requires `OPENAI_API_KEY`
 - **Azure OpenAI** - Requires Azure-specific environment variables
 
+## Advanced Features
+
+### AI SDK Pass-Through
+
+All generate functions accept additional [AI SDK options](https://sdk.vercel.ai/docs) that are passed through to the underlying provider. This enables tool calling, retry configuration, and other advanced features.
+
+#### Tool Calling
+
+```typescript
+import { generateText, tool } from '@output.ai/llm';
+import { z } from '@output.ai/core';
+
+const result = await generateText({
+  prompt: 'agent@v1',
+  variables: { task: 'Research competitor pricing' },
+  tools: {
+    searchWeb: tool({
+      description: 'Search the web for information',
+      parameters: z.object({ query: z.string() }),
+      execute: async ({ query }) => fetchSearchResults(query)
+    })
+  },
+  toolChoice: 'auto'
+});
+
+// Access tool calls made by the model
+console.log(result.toolCalls);
+```
+
+#### Common Pass-Through Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tools` | `ToolSet` | Tools the model can call (generateText only) |
+| `toolChoice` | `'auto' \| 'none' \| 'required'` | Tool selection strategy |
+| `maxRetries` | `number` | Max retry attempts (default: 2) |
+| `seed` | `number` | Seed for deterministic output |
+| `abortSignal` | `AbortSignal` | Cancel the request |
+| `topP` | `number` | Nucleus sampling (0-1) |
+| `topK` | `number` | Top-K sampling |
+
+Options set in the prompt file (temperature, maxTokens) can be overridden at call time.
+
 ## Documentation
 
 For comprehensive documentation, visit:

package/package.json

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

package/src/ai_sdk.js

@@ -38,14 +38,14 @@ const startTrace = ( name, details ) => {
   return traceId;
 };
 
-const extraAiSdkOptionsFromPrompt = prompt => {
+const aiSdkOptionsFromPrompt = prompt => {
   const options = {
     model: loadModel( prompt ),
     messages: prompt.messages,
     providerOptions: prompt.config.providerOptions
   };
 
-  if ( prompt.config.temperature ) {
+  if ( prompt.config.temperature !== undefined ) {
     options.temperature = prompt.config.temperature;
   }
 
@@ -59,42 +59,59 @@ const extraAiSdkOptionsFromPrompt = prompt => {
 /**
  * Use an LLM model to generate text.
  *
+ * Accepts additional AI SDK options (tools, maxRetries, seed, etc.) that are passed through
+ * to the underlying provider. Options from the prompt file can be overridden at call time.
+ *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
+ * @param {object} [args.tools] - AI SDK tools the model can call
+ * @param {'auto'|'none'|'required'|object} [args.toolChoice] - Tool selection strategy
+ * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
+ * @param {number} [args.seed] - Seed for deterministic output
+ * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
  * @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<GenerateTextResult>} AI SDK response with text and metadata
+ * @returns {Promise<GenerateTextResult>} AI SDK response with text, toolCalls, and metadata
  */
-export async function generateText( { prompt, variables } ) {
+export async function generateText( { prompt, variables, ...extraAiSdkOptions } ) {
   validateGenerateTextArgs( { prompt, variables } );
   const loadedPrompt = loadPrompt( prompt, variables );
   const traceId = startTrace( 'generateText', { prompt, variables, loadedPrompt } );
 
   return traceWrapper( {
     traceId, resultProperty: 'text', fn: async () =>
-      AI.generateText( extraAiSdkOptionsFromPrompt( loadedPrompt ) )
+      AI.generateText( {
+        ...aiSdkOptionsFromPrompt( loadedPrompt ),
+        ...extraAiSdkOptions
+      } )
   } );
 }
 
 /**
  * Use an LLM model to generate an object with a fixed schema.
  *
+ * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
+ * to the underlying provider. Options from the prompt file can be overridden at call time.
+ *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [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
+ * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
+ * @param {number} [args.seed] - Seed for deterministic output
+ * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
  * @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<GenerateObjectResult>} AI SDK response with object and metadata
  */
 export async function generateObject( args ) {
   validateGenerateObjectArgs( args );
-  const { prompt, variables, schema, schemaName, schemaDescription } = args;
+  const { prompt, variables, schema, schemaName, schemaDescription, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
-  const traceId = startTrace( 'generateObject', { ...args, schema: z.toJSONSchema( schema ), loadedPrompt } );
+  const traceId = startTrace( 'generateObject', { prompt, variables, schema: z.toJSONSchema( schema ), loadedPrompt } );
 
   return traceWrapper( {
     traceId, resultProperty: 'object', fn: async () =>
@@ -103,7 +120,8 @@ export async function generateObject( args ) {
         schema,
         schemaName,
         schemaDescription,
-        ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+        ...aiSdkOptionsFromPrompt( loadedPrompt ),
+        ...extraAiSdkOptions
       } )
   } );
 }
@@ -111,21 +129,27 @@ export async function generateObject( args ) {
 /**
  * Use an LLM model to generate an array of values with a fixed schema.
  *
+ * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
+ * to the underlying provider. Options from the prompt file can be overridden at call time.
+ *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [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
+ * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
+ * @param {number} [args.seed] - Seed for deterministic output
+ * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
  * @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<GenerateObjectResult>} AI SDK response with array and metadata
  */
 export async function generateArray( args ) {
   validateGenerateArrayArgs( args );
-  const { prompt, variables, schema, schemaName, schemaDescription } = args;
+  const { prompt, variables, schema, schemaName, schemaDescription, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
-  const traceId = startTrace( 'generateArray', { ...args, schema: z.toJSONSchema( schema ), loadedPrompt } );
+  const traceId = startTrace( 'generateArray', { prompt, variables, schema: z.toJSONSchema( schema ), loadedPrompt } );
 
   return traceWrapper( {
     traceId, resultProperty: 'object', fn: async () =>
@@ -134,7 +158,8 @@ export async function generateArray( args ) {
         schema,
         schemaName,
         schemaDescription,
-        ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+        ...aiSdkOptionsFromPrompt( loadedPrompt ),
+        ...extraAiSdkOptions
       } )
   } );
 }
@@ -142,26 +167,33 @@ export async function generateArray( args ) {
 /**
  * Use an LLM model to generate a result from an enum (array of string values).
  *
+ * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
+ * to the underlying provider. Options from the prompt file can be overridden at call time.
+ *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
  * @param {string[]} args.enum - Allowed values for the generation
+ * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
+ * @param {number} [args.seed] - Seed for deterministic output
+ * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
  * @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<GenerateObjectResult>} AI SDK response with enum value and metadata
  */
 export async function generateEnum( args ) {
   validateGenerateEnumArgs( args );
-  const { prompt, variables, enum: _enum } = args;
+  const { prompt, variables, enum: _enum, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
-  const traceId = startTrace( 'generateEnum', { ...args, loadedPrompt } );
+  const traceId = startTrace( 'generateEnum', { prompt, variables, loadedPrompt } );
 
   return traceWrapper( {
     traceId, resultProperty: 'object', fn: async () =>
       AI.generateObject( {
         output: 'enum',
         enum: _enum,
-        ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+        ...aiSdkOptionsFromPrompt( loadedPrompt ),
+        ...extraAiSdkOptions
       } )
   } );
 }

package/src/ai_sdk.spec.js

@@ -494,4 +494,138 @@ describe( 'ai_sdk', () => {
     expect( response.object ).toEqual( { value: 42 } );
     expect( response.result ).toEqual( { value: 42 } );
   } );
+
+  it( 'generateText: passes through AI SDK options like tools and maxRetries', async () => {
+    const { generateText } = await importSut();
+    const mockTools = { calculator: { description: 'A calculator tool' } };
+
+    await generateText( {
+      prompt: 'test_prompt@v1',
+      tools: mockTools,
+      toolChoice: 'required',
+      maxRetries: 5,
+      seed: 42
+    } );
+
+    expect( aiFns.generateText ).toHaveBeenCalledWith(
+      expect.objectContaining( {
+        tools: mockTools,
+        toolChoice: 'required',
+        maxRetries: 5,
+        seed: 42
+      } )
+    );
+  } );
+
+  it( 'generateText: user-provided temperature overrides prompt temperature', async () => {
+    loadPromptImpl.mockReturnValueOnce( {
+      config: {
+        provider: 'openai',
+        model: 'gpt-4o',
+        temperature: 0.7
+      },
+      messages: [ { role: 'user', content: 'Hi' } ]
+    } );
+
+    const { generateText } = await importSut();
+    await generateText( { prompt: 'test_prompt@v1', temperature: 0.2 } );
+
+    expect( aiFns.generateText ).toHaveBeenCalledWith(
+      expect.objectContaining( { temperature: 0.2 } )
+    );
+  } );
+
+  it( 'generateText: passes through temperature: 0 from prompt', async () => {
+    loadPromptImpl.mockReturnValueOnce( {
+      config: {
+        provider: 'openai',
+        model: 'gpt-4o',
+        temperature: 0
+      },
+      messages: [ { role: 'user', content: 'Hi' } ]
+    } );
+
+    const { generateText } = await importSut();
+    await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( aiFns.generateText ).toHaveBeenCalledWith(
+      expect.objectContaining( { temperature: 0 } )
+    );
+  } );
+
+  it( 'generateObject: passes through AI SDK options like maxRetries and seed', async () => {
+    const { generateObject } = await importSut();
+    const schema = z.object( { a: z.number() } );
+
+    await generateObject( {
+      prompt: 'test_prompt@v1',
+      schema,
+      maxRetries: 3,
+      seed: 123,
+      topP: 0.9
+    } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith(
+      expect.objectContaining( {
+        maxRetries: 3,
+        seed: 123,
+        topP: 0.9
+      } )
+    );
+  } );
+
+  it( 'generateArray: passes through AI SDK options', async () => {
+    const { generateArray } = await importSut();
+    const schema = z.string();
+    const controller = new AbortController();
+
+    await generateArray( {
+      prompt: 'test_prompt@v1',
+      schema,
+      abortSignal: controller.signal,
+      headers: { 'X-Custom': 'value' }
+    } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith(
+      expect.objectContaining( {
+        abortSignal: controller.signal,
+        headers: { 'X-Custom': 'value' }
+      } )
+    );
+  } );
+
+  it( 'generateEnum: passes through AI SDK options', async () => {
+    const { generateEnum } = await importSut();
+
+    await generateEnum( {
+      prompt: 'test_prompt@v1',
+      enum: [ 'A', 'B' ],
+      stopSequences: [ 'END' ],
+      presencePenalty: 0.5
+    } );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith(
+      expect.objectContaining( {
+        stopSequences: [ 'END' ],
+        presencePenalty: 0.5
+      } )
+    );
+  } );
+
+  it( 'generateText: passes through unknown future options for forward compatibility', async () => {
+    const { generateText } = await importSut();
+
+    await generateText( {
+      prompt: 'test_prompt@v1',
+      experimental_futureOption: { key: 'value' },
+      unknownOption: true
+    } );
+
+    expect( aiFns.generateText ).toHaveBeenCalledWith(
+      expect.objectContaining( {
+        experimental_futureOption: { key: 'value' },
+        unknownOption: true
+      } )
+    );
+  } );
 } );

package/src/index.d.ts

@@ -1,7 +1,10 @@
 import type { z } from '@output.ai/core';
 import type {
   GenerateTextResult as AIGenerateTextResult,
-  GenerateObjectResult as AIGenerateObjectResult
+  GenerateObjectResult as AIGenerateObjectResult,
+  CallSettings,
+  ToolSet,
+  ToolChoice
 } from 'ai';
 
 /**
@@ -71,9 +74,35 @@ export type {
   FinishReason,
   LanguageModelResponseMetadata,
   ProviderMetadata,
-  CallWarning
+  CallWarning,
+  CallSettings,
+  ToolSet,
+  ToolChoice,
+  Tool
 } from 'ai';
 
+// Re-export the tool helper function for creating tools
+export { tool } from 'ai';
+
+/**
+ * Common AI SDK options that can be passed through to all generate functions.
+ * These options are passed directly to the underlying AI SDK call.
+ */
+type AiSdkOptions = Partial<Omit<CallSettings, 'maxOutputTokens'>>;
+
+/**
+ * AI SDK options specific to generateText, including tool calling support.
+ * @typeParam TOOLS - The tools available for the model to call
+ */
+type GenerateTextAiSdkOptions<TOOLS extends ToolSet = ToolSet> = AiSdkOptions & {
+  /** Tools the model can call */
+  tools?: TOOLS;
+  /** Tool choice strategy: 'auto', 'none', 'required', or specific tool */
+  toolChoice?: ToolChoice<TOOLS>;
+  /** Limit which tools are active without changing types */
+  activeTools?: Array<keyof TOOLS>;
+};
+
 /**
  * Result from generateText including full AI SDK response metadata.
  * Extends AI SDK's GenerateTextResult with a unified `result` field.
@@ -112,17 +141,20 @@ export function loadPrompt(
  *
  * This function is a wrapper over the AI SDK's `generateText`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
+ * Additional AI SDK options (tools, maxRetries, etc.) can be passed through.
  *
  * @param args - Generation arguments.
  * @param args.prompt - Prompt file name.
  * @param args.variables - Variables to interpolate.
+ * @param args.tools - Tools the model can call (optional).
+ * @param args.toolChoice - Tool selection strategy (optional).
  * @returns AI SDK response with text and metadata.
  */
-export function generateText(
+export function generateText<TOOLS extends ToolSet = ToolSet>(
   args: {
     prompt: string,
     variables?: Record<string, string | number | boolean>
-  }
+  } & GenerateTextAiSdkOptions<TOOLS>
 ): Promise<GenerateTextResult>;
 
 /**
@@ -130,6 +162,7 @@ export function generateText(
  *
  * This function is a wrapper over the AI SDK's `generateObject`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
+ * Additional AI SDK options (maxRetries, seed, etc.) can be passed through.
  *
  * @param args - Generation arguments.
  * @param args.prompt - Prompt file name.
@@ -146,7 +179,7 @@ export function generateObject<TSchema extends z.ZodObject>(
     schema: TSchema,
     schemaName?: string,
     schemaDescription?: string
-  }
+  } & AiSdkOptions
 ): Promise<GenerateObjectResult<z.infer<TSchema>>>;
 
 /**
@@ -154,6 +187,7 @@ export function generateObject<TSchema extends z.ZodObject>(
  *
  * This function is a wrapper over the AI SDK's `generateObject` with `output: 'array'`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
+ * Additional AI SDK options (maxRetries, seed, etc.) can be passed through.
  *
  * @param args - Generation arguments.
  * @param args.prompt - Prompt file name.
@@ -170,7 +204,7 @@ export function generateArray<TSchema extends z.ZodType>(
     schema: TSchema,
     schemaName?: string,
     schemaDescription?: string
-  }
+  } & AiSdkOptions
 ): Promise<GenerateObjectResult<Array<z.infer<TSchema>>>>;
 
 /**
@@ -178,6 +212,7 @@ export function generateArray<TSchema extends z.ZodType>(
  *
  * This function is a wrapper over the AI SDK's `generateObject` with `output: 'enum'`.
  * The prompt file sets `model`, `messages`, `temperature`, `maxTokens`, and `providerOptions`.
+ * Additional AI SDK options (maxRetries, seed, etc.) can be passed through.
  *
  * @param args - Generation arguments.
  * @param args.prompt - Prompt file name.
@@ -190,5 +225,5 @@ export function generateEnum<const TEnum extends readonly [string, ...string[]]>
     prompt: string,
     variables?: Record<string, string | number | boolean>,
     enum: TEnum
-  }
+  } & AiSdkOptions
 ): Promise<GenerateObjectResult<TEnum[number]>>;

package/src/index.js

@@ -1,3 +1,4 @@
 export { generateText, generateArray, generateObject, generateEnum } from './ai_sdk.js';
 export { loadPrompt } from './prompt_loader.js';
+export { tool } from 'ai';
 export * as ai from 'ai';