@output.ai/llm 0.0.15 → 0.2.0

package/README.md

@@ -1,30 +1,128 @@
 # LLM Module
 
-Provides llm calls abstractions.
+Framework abstraction to interact with LLM models, including prompt management and structured generation.
 
-## completions()
+## Quick Start
 
-Allow to use chat messages with a LLM model.
+```js
+import { generateText } from '@output.ai/llm';
+
+const response = await generateText({
+  prompt: 'my_prompt@v1',
+  variables: { topic: 'AI workflows' }
+});
+```
+
+## Features
+
+- **Unified API**: Single import for prompt loading and LLM generation
+- **Multiple Generation Types**: Text, objects, arrays, and enums
+- **Prompt Management**: Load and render `.prompt` files with variable interpolation
+- **Multi-Provider Support**: Anthropic, OpenAI, and Azure
+- **Type Safety**: Full TypeScript support with Zod schemas
+
+## Generate Text
+
+Generate unstructured text from an LLM:
 
 ```js
 import { generateText } from '@output.ai/llm';
 
-const response = generateText({
-  configs: {
-    model: 'model-name', // eg claude-3.5
-    provider: 'provider-name', // eg anthropic
-  },
-  messages: [
-    {
-      role: 'assistant',
-      content: 'You are an assistant...',
-    },
-    {
-      role: 'user',
-      content: 'Whats the capital of Nicaragua?',
-    },
-  ],
+const response = await generateText({
+  prompt: 'explain_topic@v1',
+  variables: { topic: 'machine learning' }
+});
+```
+
+## Generate Object
+
+Generate a structured object matching a Zod schema:
+
+```js
+import { generateObject } from '@output.ai/llm';
+import { z } from '@output.ai/core';
+
+const recipeSchema = z.object({
+  title: z.string(),
+  ingredients: z.array(z.string()),
+  steps: z.array(z.string())
+});
+
+const recipe = await generateObject({
+  prompt: 'recipe@v1',
+  variables: { dish: 'lasagna' },
+  schema: recipeSchema
 });
 ```
 
-The response is a string.
+## Generate Array
+
+Generate an array of structured items:
+
+```js
+import { generateArray } from '@output.ai/llm';
+import { z } from '@output.ai/core';
+
+const taskSchema = z.object({
+  title: z.string(),
+  priority: z.number()
+});
+
+const tasks = await generateArray({
+  prompt: 'task_list@v1',
+  variables: { project: 'website' },
+  schema: taskSchema
+});
+```
+
+## Generate Enum
+
+Generate a value from a list of allowed options:
+
+```js
+import { generateEnum } from '@output.ai/llm';
+
+const category = await generateEnum({
+  prompt: 'categorize@v1',
+  variables: { text: 'Product announcement' },
+  enum: ['marketing', 'engineering', 'sales', 'support']
+});
+```
+
+## Prompt Files
+
+Prompt files use YAML frontmatter for configuration and support LiquidJS templating:
+
+**File: `explain_topic@v1.prompt`**
+```yaml
+---
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.7
+---
+
+<system>
+You are a concise technical explainer.
+</system>
+
+<user>
+Explain {{ topic }} in 3 bullet points.
+</user>
+```
+
+## Configuration Options
+
+Prompt files support these configuration fields:
+
+```yaml
+---
+provider: anthropic | openai | azure
+model: model-name
+temperature: 0.0-1.0 (optional)
+maxTokens: number (optional)
+providerOptions: (optional)
+  thinking:
+    type: enabled
+    budgetTokens: number
+---
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/llm",
-  "version": "0.0.15",
+  "version": "0.2.0",
   "description": "Framework abstraction to interact with LLM models",
   "type": "module",
   "main": "src/index.js",
@@ -13,8 +13,9 @@
     "@ai-sdk/azure": "2.0.53",
     "@ai-sdk/openai": "2.0.52",
     "@output.ai/core": ">=0.0.1",
-    "@output.ai/prompt": ">=0.0.1",
-    "ai": "5.0.48"
+    "ai": "5.0.48",
+    "gray-matter": "4.0.3",
+    "liquidjs": "10.22.0"
   },
   "license": "UNLICENSED"
 }

package/src/ai_model.js

@@ -1,29 +1,34 @@
 import { anthropic } from '@ai-sdk/anthropic';
 import { azure } from '@ai-sdk/azure';
 import { openai } from '@ai-sdk/openai';
-import { ValidationError, z } from '@output.ai/core';
 
 const providers = { azure, anthropic, openai };
 
-const promptSchema = z.object( {
-  config: z.object( {
-    provider: z.enum( [ 'anthropic', 'azure', 'openai' ] ),
-    model: z.string(),
-    temperature: z.number().optional(),
-    max_tokens: z.number().optional()
-  } ),
-  messages: z.array(
-    z.object( {
-      role: z.string(),
-      content: z.string()
-    } )
-  )
-} );
-
-export const loadModel = prompt => {
-  const result = promptSchema.safeParse( prompt );
-  if ( !result.success ) {
-    throw new ValidationError( `Invalid prompt object: ${result.error.message}` );
+export function loadModel( prompt ) {
+  const config = prompt?.config;
+
+  if ( !config ) {
+    throw new Error( 'Prompt is missing config object' );
+  }
+
+  const { provider: providerName, model: modelName } = config;
+
+  if ( !providerName ) {
+    throw new Error( 'Prompt config is missing "provider" field' );
+  }
+
+  if ( !modelName ) {
+    throw new Error( 'Prompt config is missing "model" field' );
   }
-  return providers[prompt.config.provider]( prompt.config.model );
-};
+
+  const provider = providers[providerName];
+
+  if ( !provider ) {
+    const validProviders = Object.keys( providers ).join( ', ' );
+    throw new Error(
+      `Invalid provider "${providerName}". Valid providers: ${validProviders}`
+    );
+  }
+
+  return provider( modelName );
+}

package/src/ai_model.spec.js

@@ -0,0 +1,33 @@
+import { it, expect, vi, afterEach } from 'vitest';
+
+const openaiImpl = vi.fn( model => `openai:${model}` );
+const azureImpl = vi.fn( model => `azure:${model}` );
+const anthropicImpl = vi.fn( model => `anthropic:${model}` );
+
+vi.mock( '@ai-sdk/openai', () => ( {
+  openai: ( ...values ) => openaiImpl( ...values )
+} ) );
+
+vi.mock( '@ai-sdk/azure', () => ( {
+  azure: ( ...values ) => azureImpl( ...values )
+} ) );
+
+vi.mock( '@ai-sdk/anthropic', () => ( {
+  anthropic: ( ...values ) => anthropicImpl( ...values )
+} ) );
+
+import { loadModel } from './ai_model.js';
+
+afterEach( async () => {
+  await vi.resetModules();
+  vi.clearAllMocks();
+} );
+
+it( 'loads model using selected provider', () => {
+  const result = loadModel( { config: { provider: 'openai', model: 'gpt-4o-mini' } } );
+
+  expect( result ).toBe( 'openai:gpt-4o-mini' );
+  expect( openaiImpl ).toHaveBeenCalledWith( 'gpt-4o-mini' );
+  expect( azureImpl ).not.toHaveBeenCalled();
+  expect( anthropicImpl ).not.toHaveBeenCalled();
+} );

package/src/ai_sdk.js

@@ -1,8 +1,10 @@
 import { Tracing } from '@output.ai/core/tracing';
 import { loadModel } from './ai_model.js';
 import * as AI from 'ai';
+import { validateGenerateTextArgs, validateGenerateObjectArgs, validateGenerateArrayArgs, validateGenerateEnumArgs } from './validations.js';
+import { loadPrompt } from './prompt_loader.js';
 
-const generationWrapper = async ( traceId, fn ) => {
+const traceWrapper = async ( traceId, fn ) => {
   try {
     const result = await fn();
     Tracing.addEventEnd( { id: traceId, details: result } );
@@ -13,33 +15,126 @@ const generationWrapper = async ( traceId, fn ) => {
   }
 };
 
-export async function generateText( { prompt, ...nativeAiSdkArgs } ) {
-  const traceId = `generateText-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateText', id: traceId, details: { prompt, nativeAiSdkArgs } } );
-
-  return generationWrapper( traceId, async () => {
-    return ( await AI.generateText( {
-      model: loadModel( prompt ),
-      messages: prompt.messages,
-      temperature: prompt.config.temperature,
-      maxOutputTokens: prompt.config.max_tokens ?? 64000,
-      ...nativeAiSdkArgs
-    } ) ).text;
-  } );
+const createTraceId = name => `${name}-${Date.now()}`;
+
+const startTrace = ( name, details ) => {
+  const traceId = createTraceId( name );
+  Tracing.addEventStart( { kind: 'llm', name, id: traceId, details } );
+  return traceId;
+};
+
+const extraAiSdkOptionsFromPrompt = prompt => {
+  const options = {
+    model: loadModel( prompt ),
+    messages: prompt.messages,
+    providerOptions: prompt.config.providerOptions
+  };
+
+  if ( prompt.config.temperature ) {
+    options.temperature = prompt.config.temperature;
+  }
+
+  if ( prompt.config.maxTokens ) {
+    options.maxOutputTokens = prompt.config.maxTokens;
+  }
+
+  return options;
+};
+
+/**
+ * Use an LLM model to generate text.
+ *
+ * @param {object} args - Generation arguments
+ * @param {string} args.prompt - Prompt file name
+ * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
+ * @returns {Promise<string>} Generated text
+ */
+export async function generateText( { prompt, variables } ) {
+  validateGenerateTextArgs( { prompt, variables } );
+  const loadedPrompt = loadPrompt( prompt, variables );
+  const traceId = startTrace( 'generateText', { prompt: loadedPrompt } );
+
+  return traceWrapper( traceId, async () =>
+    AI.generateText( extraAiSdkOptionsFromPrompt( loadedPrompt ) ).then( r => r.text )
+  );
+}
+
+/**
+ * Use an LLM model to generate an object with a fixed schema.
+ *
+ * @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
+ * @returns {Promise<object>} Object matching the provided schema
+ */
+export async function generateObject( args ) {
+  validateGenerateObjectArgs( args );
+  const { prompt, variables, schema, schemaName, schemaDescription } = args;
+  const loadedPrompt = loadPrompt( prompt, variables );
+  const traceId = startTrace( 'generateObject', { ...args, prompt: loadedPrompt } );
+
+  return traceWrapper( traceId, async () =>
+    AI.generateObject( {
+      output: 'object',
+      schema,
+      schemaName,
+      schemaDescription,
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+    } ).then( r => r.object )
+  );
 }
 
-export async function generateObject( { prompt, ...nativeAiSdkArgs } ) {
-  const traceId = `generateObject-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateObject', id: traceId, details: { prompt, nativeAiSdkArgs } } );
-
-  return generationWrapper( traceId, async () => {
-    return ( await AI.generateObject( {
-      model: loadModel( prompt ),
-      output: nativeAiSdkArgs.object ?? 'object',
-      messages: prompt.messages,
-      temperature: prompt.config.temperature,
-      ...( prompt.config.max_tokens && { maxOutputTokens: prompt.config.max_tokens } ),
-      ...nativeAiSdkArgs
-    } ) ).object;
-  } );
+/**
+ * Use an LLM model to generate an array of values with a fixed schema.
+ *
+ * @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
+ * @returns {Promise<object>} Array where each element matches the schema
+ */
+export async function generateArray( args ) {
+  validateGenerateArrayArgs( args );
+  const { prompt, variables, schema, schemaName, schemaDescription } = args;
+  const loadedPrompt = loadPrompt( prompt, variables );
+  const traceId = startTrace( 'generateArray', { ...args, prompt: loadedPrompt } );
+
+  return traceWrapper( traceId, async () =>
+    AI.generateObject( {
+      output: 'array',
+      schema,
+      schemaName,
+      schemaDescription,
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+    } ).then( r => r.object )
+  );
+}
+
+/**
+ * Use an LLM model to generate a result from an enum (array of string values).
+ *
+ * @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
+ * @returns {Promise<string>} One of the provided enum values
+ */
+export async function generateEnum( args ) {
+  validateGenerateEnumArgs( args );
+  const { prompt, variables, enum: _enum } = args;
+  const loadedPrompt = loadPrompt( prompt, variables );
+  const traceId = startTrace( 'generateEnum', { ...args, prompt: loadedPrompt } );
+
+  return traceWrapper( traceId, async () =>
+    AI.generateObject( {
+      output: 'enum',
+      enum: _enum,
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+    } ).then( r => r.object )
+  );
 }

package/src/ai_sdk.spec.js

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { z } from '@output.ai/core';
+
+const tracingSpies = {
+  addEventStart: vi.fn(),
+  addEventEnd: vi.fn(),
+  addEventError: vi.fn()
+};
+vi.mock( '@output.ai/core/tracing', () => ( { Tracing: tracingSpies } ), { virtual: true } );
+
+const loadModelImpl = vi.fn();
+vi.mock( './ai_model.js', () => ( {
+  loadModel: ( ...values ) => loadModelImpl( ...values )
+} ) );
+
+const aiFns = {
+  generateText: vi.fn(),
+  generateObject: vi.fn()
+};
+vi.mock( 'ai', () => ( aiFns ) );
+
+const validators = {
+  validateGenerateTextArgs: vi.fn(),
+  validateGenerateObjectArgs: vi.fn(),
+  validateGenerateArrayArgs: vi.fn(),
+  validateGenerateEnumArgs: vi.fn()
+};
+vi.mock( './validations.js', () => ( validators ) );
+
+const loadPromptImpl = vi.fn();
+vi.mock( './prompt_loader.js', () => ( {
+  loadPrompt: ( ...values ) => loadPromptImpl( ...values )
+} ) );
+
+const importSut = async () => import( './ai_sdk.js' );
+
+const basePrompt = {
+  config: {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    temperature: 0.3,
+    providerOptions: { thinking: { enabled: true } }
+  },
+  messages: [ { role: 'user', content: 'Hi' } ]
+};
+
+beforeEach( () => {
+  tracingSpies.addEventStart.mockClear();
+  tracingSpies.addEventEnd.mockClear();
+  tracingSpies.addEventError.mockClear();
+
+  loadModelImpl.mockReset().mockReturnValue( 'MODEL' );
+  loadPromptImpl.mockReset().mockReturnValue( basePrompt );
+
+  aiFns.generateText.mockReset().mockResolvedValue( { text: 'TEXT' } );
+  aiFns.generateObject.mockReset().mockResolvedValue( { object: 'OBJECT' } );
+
+  validators.validateGenerateTextArgs.mockClear();
+  validators.validateGenerateObjectArgs.mockClear();
+  validators.validateGenerateArrayArgs.mockClear();
+  validators.validateGenerateEnumArgs.mockClear();
+} );
+
+afterEach( async () => {
+  await vi.resetModules();
+  vi.clearAllMocks();
+} );
+
+describe( 'ai_sdk', () => {
+  it( 'generateText: validates, traces, calls AI and returns text', async () => {
+    const { generateText } = await importSut();
+    const result = await generateText( { prompt: 'test_prompt@v1' } );
+
+    expect( validators.validateGenerateTextArgs ).toHaveBeenCalledWith( { prompt: 'test_prompt@v1' } );
+    expect( loadPromptImpl ).toHaveBeenCalledWith( 'test_prompt@v1', undefined );
+    expect( tracingSpies.addEventStart ).toHaveBeenCalledTimes( 1 );
+    expect( tracingSpies.addEventEnd ).toHaveBeenCalledTimes( 1 );
+
+    expect( loadModelImpl ).toHaveBeenCalledWith( basePrompt );
+    expect( aiFns.generateText ).toHaveBeenCalledWith( {
+      model: 'MODEL',
+      messages: basePrompt.messages,
+      temperature: 0.3,
+      providerOptions: basePrompt.config.providerOptions
+    } );
+    expect( result ).toBe( 'TEXT' );
+  } );
+
+  it( 'generateObject: validates, traces, calls AI with output object and returns object', async () => {
+    const { generateObject } = await importSut();
+    aiFns.generateObject.mockResolvedValueOnce( { object: { a: 1 } } );
+
+    const schema = z.object( { a: z.number() } );
+    const result = await generateObject( {
+      prompt: 'test_prompt@v1',
+      schema,
+      schemaName: 'Thing',
+      schemaDescription: 'A thing'
+    } );
+
+    expect( validators.validateGenerateObjectArgs ).toHaveBeenCalled();
+    expect( loadPromptImpl ).toHaveBeenCalledWith( 'test_prompt@v1', undefined );
+    expect( tracingSpies.addEventStart ).toHaveBeenCalledTimes( 1 );
+    expect( tracingSpies.addEventEnd ).toHaveBeenCalledTimes( 1 );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'object',
+      schema,
+      schemaName: 'Thing',
+      schemaDescription: 'A thing',
+      model: 'MODEL',
+      messages: basePrompt.messages,
+      temperature: 0.3,
+      providerOptions: basePrompt.config.providerOptions
+    } );
+    expect( result ).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 ] } );
+
+    const schema = z.number();
+    const result = await generateArray( {
+      prompt: 'test_prompt@v1',
+      schema,
+      schemaName: 'Numbers',
+      schemaDescription: 'Two numbers'
+    } );
+
+    expect( validators.validateGenerateArrayArgs ).toHaveBeenCalled();
+    expect( loadPromptImpl ).toHaveBeenCalledWith( 'test_prompt@v1', undefined );
+    expect( tracingSpies.addEventStart ).toHaveBeenCalledTimes( 1 );
+    expect( tracingSpies.addEventEnd ).toHaveBeenCalledTimes( 1 );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'array',
+      schema,
+      schemaName: 'Numbers',
+      schemaDescription: 'Two numbers',
+      model: 'MODEL',
+      messages: basePrompt.messages,
+      temperature: 0.3,
+      providerOptions: basePrompt.config.providerOptions
+    } );
+    expect( result ).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' } );
+
+    const result = await generateEnum( { prompt: 'test_prompt@v1', enum: [ 'A', 'B', 'C' ] } );
+
+    expect( validators.validateGenerateEnumArgs ).toHaveBeenCalled();
+    expect( loadPromptImpl ).toHaveBeenCalledWith( 'test_prompt@v1', undefined );
+    expect( tracingSpies.addEventStart ).toHaveBeenCalledTimes( 1 );
+    expect( tracingSpies.addEventEnd ).toHaveBeenCalledTimes( 1 );
+
+    expect( aiFns.generateObject ).toHaveBeenCalledWith( {
+      output: 'enum',
+      enum: [ 'A', 'B', 'C' ],
+      model: 'MODEL',
+      messages: basePrompt.messages,
+      temperature: 0.3,
+      providerOptions: basePrompt.config.providerOptions
+    } );
+    expect( result ).toBe( 'B' );
+  } );
+} );

package/src/index.d.ts

@@ -1,110 +1,87 @@
-import type * as AiTypes from 'ai';
-import type { z as CoreZ } from '@output.ai/core';
-import type { Prompt } from '@output.ai/prompt';
-
-export type { Prompt };
-
-type NativeGenerateTextArgs = Parameters<typeof AiTypes.generateText>[0];
-type NativeGenerateObjectArgs = Parameters<typeof AiTypes.generateObject>[0];
-
-/**
- * Simplify types into a plain object while preserving unions
- * (distributes over union members instead of collapsing their keys)
- */
-type Simplify<T> = T extends unknown ? { [K in keyof T]: T[K] } & {} : never;
-
-/**
- * Replace keys K in T with V, preserving unions by distributing over T
- */
-type Replace<T, K extends PropertyKey, V> = T extends unknown
-  ? Omit<T, Extract<K, keyof T>> & { [P in K]: V }
-  : never;
+import type { z } from '@output.ai/core';
 
 /**
- * Text generation arguments
- * Include all native AI SDK generateText options and a Prompt object from `@output.ai/prompt`
- */
-export type GenerateTextArgs = Simplify<
-  Replace<Partial<NativeGenerateTextArgs>, 'prompt', Prompt>
->;
-
-/**
- * Allow schemas from @output.ai/core's zod in addition to AI SDK's accepted schema types.
- */
-type WithCoreZodSchema<T> = T extends unknown
-  ? T extends { schema?: infer S }
-    ? Omit<T, 'schema'> & { schema?: S | CoreZ.ZodTypeAny }
-    : T
-  : never;
-
-/**
- * Object generation arguments
- * Include all native AI SDK generateObject options and a Prompt object from `@output.ai/prompt`
- */
-export type GenerateObjectArgs = Simplify<
-  Replace<Partial<WithCoreZodSchema<NativeGenerateObjectArgs>>, 'prompt', Prompt>
->;
-
-/**
- * Use a LLM Model to generate text
- *
- * This function a wrapper over AI SDK's generateText function.
- *
- * It accepts the same arguments of the the original function, plus a "Prompt" object, generated using the `output.ai/prompt`.
+ * Use an LLM model to generate text.
  *
- * The Prompt object will set `model`, `messages`, `temperature` and `max_tokens`, however all these can be overwritten by their AI SDK native argument values.
+ * This function is a wrapper over the AI SDK's `generateText`.
+ * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
  *
- * @param {GenerateTextArgs} args - Generation arguments
- * @returns {Promise<string>}
+ * @param {object} args - Generation arguments
+ * @param {string} args.prompt - Prompt file name
+ * @param {Record<string, string | number>} args.variables - Variables to interpolate
+ * @returns {Promise<string>} Generated text
  */
 export function generateText(
-  args: GenerateTextArgs
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number>
+  }
 ): Promise<string>;
 
 /**
- * Use a LLM Model to generate object
- *
- * This function a wrapper over AI SDK's generateObject function.
- *
- * It accepts the same arguments of the the original function, plus a "Prompt" object, generated using the `output.ai/prompt`.
- *
- * The Prompt object will set `model`, `messages`, `temperature` and `max_tokens`, however all these can be overwritten by their AI SDK native argument values.
- *
- * @param {GenerateObjectArgs} args - Generation arguments
- * @returns {Promise<object>} An object matching the provided schema
+ * 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`.
+ *
+ * @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
+ * @returns {Promise<object>} Object matching the provided schema
  */
-export function generateObject<A extends GenerateObjectArgs & { schema: CoreZ.ZodTypeAny }>(
-  args: A
-): Promise<CoreZ.infer<A['schema']>>;
+export function generateObject<TSchema extends z.ZodObject>(
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number>,
+    schema: TSchema,
+    schemaName?: string,
+    schemaDescription?: string
+  }
+): Promise<z.infer<TSchema>>;
 
 /**
- * Use a LLM Model to generate object
- *
- * This function a wrapper over AI SDK's generateObject function.
- *
- * It accepts the same arguments of the the original function, plus a "Prompt" object, generated using the `output.ai/prompt`.
- *
- * The Prompt object will set `model`, `messages`, `temperature` and `max_tokens`, however all these can be overwritten by their AI SDK native argument values.
- *
- * @param {GenerateObjectArgs} args - Generation arguments
- * @returns {Promise<object>} An object matching the provided enum
+ * 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`.
+ *
+ * @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
+ * @returns {Promise<object>} Array where each element matches the schema
  */
-export function generateObject<A extends GenerateObjectArgs & { enum: readonly unknown[]; output: 'enum' }>(
-  args: A
-): Promise<A['enum'][number]>;
+export function generateArray<TSchema extends z.ZodType>(
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number>,
+    schema: TSchema,
+    schemaName?: string,
+    schemaDescription?: string
+  }
+): Promise<Array<z.infer<TSchema>>>;
 
 /**
- * Use a LLM Model to generate object
- *
- * This function a wrapper over AI SDK's generateObject function.
- *
- * It accepts the same arguments of the the original function, plus a "Prompt" object, generated using the `output.ai/prompt`.
+ * Use an LLM model to generate a result from an enum (array of string values).
  *
- * The Prompt object will set `model`, `messages`, `temperature` and `max_tokens`, however all these can be overwritten by their AI SDK native argument 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`.
  *
- * @param {GenerateObjectArgs} args - Generation arguments
- * @returns {Promise<object>} An object without a pre-defined schema schema
+ * @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
+ * @returns {Promise<string>} One of the provided enum values
  */
-export function generateObject(
-  args: GenerateObjectArgs
-): Promise<object>;
+export function generateEnum<const TEnum extends readonly [string, ...string[]]>(
+  args: {
+    prompt: string,
+    variables?: Record<string, string | number>,
+    enum: TEnum
+  }
+): Promise<TEnum[number]>;

package/src/index.js

@@ -1 +1,2 @@
-export { generateText, generateObject } from './ai_sdk.js';
+export { generateText, generateArray, generateObject, generateEnum } from './ai_sdk.js';
+export * as ai from 'ai';

package/src/load_content.js

@@ -0,0 +1,121 @@
+import { join, dirname } from 'path';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+function extractFilePath( fileUrlMatch, parenMatch, directMatch ) {
+  if ( fileUrlMatch ) {
+    return fileURLToPath( 'file://' + fileUrlMatch[1] );
+  }
+  if ( parenMatch ) {
+    return parenMatch[1];
+  }
+  if ( directMatch ) {
+    return directMatch[1];
+  }
+  return null;
+}
+
+export const getInvocationDir = _ => {
+  const stack = new Error().stack;
+
+  if ( !stack ) {
+    throw new Error( 'Stack trace is unavailable - cannot determine invocation directory' );
+  }
+
+  const lines = stack.split( '\n' );
+
+  // Search through stack to find first valid file path that is NOT in SDK
+  // Skip first 2 lines (Error message and getInvocationDir itself)
+  for ( const line of lines.slice( 2 ) ) {
+    // Match file:// URLs (ESM) or regular file paths
+    // Pattern 1: file:///path/to/file.js:line:col
+    // Pattern 2: at func (/path/to/file.js:line:col)
+    // Pattern 3: /path/to/file.js:line:col
+    const fileUrlMatch = line.match( /file:\/\/([^:]+\.(?:js|mjs|ts|tsx|jsx))/ );
+    const parenMatch = line.match( /\(([^:)]+\.(?:js|mjs|ts|tsx|jsx)):\d+:\d+\)/ );
+    const directMatch = line.match( /^\s*at\s+[^(]*([^:]+\.(?:js|mjs|ts|tsx|jsx)):\d+:\d+/ );
+
+    // Determine the file path from different stack trace formats
+    const filePath = extractFilePath( fileUrlMatch, parenMatch, directMatch );
+
+    if ( filePath ) {
+      // Skip internal Node.js paths
+      if ( filePath.includes( 'node:' ) || filePath.includes( 'internal/' ) ) {
+        continue;
+      }
+
+      // Skip SDK internal files - we want the actual caller, not the SDK
+      // This includes @output.ai packages and sdk/ directory
+      if ( filePath.includes( '/sdk/' ) || filePath.includes( 'node_modules/@output.ai/' ) ) {
+        continue;
+      }
+
+      // Found a valid caller file outside the SDK
+      return dirname( filePath );
+    }
+  }
+
+  throw new Error(
+    'Unable to determine invocation directory from stack trace. ' +
+    `Stack preview:\n${lines.slice( 0, 10 ).join( '\n' )}`
+  );
+};
+
+/**
+ * Recursively search for a file by its name and load its content.
+ *
+ * @param {string} name - Name of the file load its content
+ * @param {string} [dir=<invocation directory>] - The directory to search for the file
+ * @param {number} [depth=0] - Current recursion depth
+ * @param {number} [maxDepth=5] - Maximum recursion depth
+ * @returns {string | null} - File content or null if not found
+ */
+export const loadContent = ( name, dir = getInvocationDir(), depth = 0, maxDepth = 5 ) => {
+  // Stop recursion if max depth exceeded
+  if ( depth > maxDepth ) {
+    return null;
+  }
+
+  // Validate filename doesn't contain path separators (prevent directory traversal)
+  if ( name.includes( '..' ) || name.includes( '/' ) || name.includes( '\\' ) ) {
+    throw new Error( `Invalid file name "${name}" - must not contain path separators or ".."` );
+  }
+
+  try {
+    const entries = readdirSync( dir, { withFileTypes: true } );
+
+    for ( const entry of entries ) {
+      if ( entry.name === name ) {
+        try {
+          return readFileSync( join( dir, entry.name ), 'utf-8' );
+        } catch ( error ) {
+          throw new Error(
+            `Found file "${name}" in "${dir}" but failed to read it: ${error.message}`,
+            { cause: error }
+          );
+        }
+      }
+
+      // Recurse into subdirectories, but skip symlinks to prevent infinite loops
+      if ( entry.isDirectory() && !entry.isSymbolicLink() ) {
+        const content = loadContent( name, join( dir, entry.name ), depth + 1, maxDepth );
+        if ( content !== null ) {
+          return content;
+        }
+      }
+    }
+
+    return null;
+  } catch ( error ) {
+    // Only suppress ENOENT (directory doesn't exist) during recursion
+    // This is expected when searching through nested directories
+    if ( error.code === 'ENOENT' ) {
+      return null;
+    }
+    // Propagate all other errors (permission denied, I/O errors, etc.)
+    throw new Error(
+      `Failed to read directory "${dir}" while searching for "${name}": ${error.message}`,
+      { cause: error }
+    );
+  }
+};

package/src/load_content.spec.js

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { getInvocationDir, loadContent } from './load_content.js';
+import { join } from 'path';
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+describe( 'getInvocationDir', () => {
+  it( 'extracts directory from stack trace', () => {
+    const dir = getInvocationDir();
+    expect( dir ).toBeTruthy();
+    expect( typeof dir ).toBe( 'string' );
+    // Should not contain filename, only directory
+    expect( dir ).not.toContain( 'load_content.spec.js' );
+  } );
+
+  it( 'returns consistent directory when called multiple times', () => {
+    const dir1 = getInvocationDir();
+    const dir2 = getInvocationDir();
+    expect( dir1 ).toBe( dir2 );
+  } );
+
+  it( 'returns a valid filesystem path', () => {
+    const dir = getInvocationDir();
+    // Should be a non-empty string that looks like a directory path
+    expect( dir ).toBeTruthy();
+    expect( typeof dir ).toBe( 'string' );
+    expect( dir.length ).toBeGreaterThan( 0 );
+  } );
+} );
+
+describe( 'loadContent', () => {
+  it( 'loads file from root directory', () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+    const testContent = 'test file content';
+    writeFileSync( join( tempDir, 'test.txt' ), testContent );
+
+    const content = loadContent( 'test.txt', tempDir );
+
+    expect( content ).toBe( testContent );
+  } );
+
+  it( 'loads file from nested subdirectory', () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+    const subDir = join( tempDir, 'subdir' );
+    mkdirSync( subDir );
+
+    const testContent = 'nested file content';
+    writeFileSync( join( subDir, 'nested.txt' ), testContent );
+
+    const content = loadContent( 'nested.txt', tempDir );
+
+    expect( content ).toBe( testContent );
+  } );
+
+  it( 'returns null when file does not exist', () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+
+    const content = loadContent( 'nonexistent.txt', tempDir );
+
+    expect( content ).toBeNull();
+  } );
+
+  it( 'returns null when starting directory does not exist', () => {
+    // ENOENT is suppressed and returns null (expected behavior)
+    const content = loadContent( 'test.txt', '/nonexistent-root-path-12345' );
+    expect( content ).toBeNull();
+  } );
+
+  it( 'respects depth limit', () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+
+    // Create deeply nested structure: dir/1/2/3/4/5/6/deep.txt (7 levels)
+    const levels = [ 1, 2, 3, 4, 5, 6 ];
+    const deepPath = levels.reduce( ( acc, level ) => {
+      const newPath = join( acc, `level${level}` );
+      mkdirSync( newPath );
+      return newPath;
+    }, tempDir );
+    writeFileSync( join( deepPath, 'deep.txt' ), 'deeply nested' );
+
+    // Should NOT find it with default maxDepth of 5
+    const content = loadContent( 'deep.txt', tempDir );
+    expect( content ).toBeNull();
+  } );
+
+  it( 'throws error when filename contains path separators', () => {
+    const tempDir = mkdtempSync( join( tmpdir(), 'load-content-test-' ) );
+
+    expect( () => {
+      loadContent( '../test.txt', tempDir );
+    } ).toThrow( /Invalid file name/ );
+
+    expect( () => {
+      loadContent( 'foo/bar.txt', tempDir );
+    } ).toThrow( /Invalid file name/ );
+  } );
+} );

package/src/parser.js

@@ -0,0 +1,27 @@
+import matter from 'gray-matter';
+
+export function parsePrompt( raw ) {
+  const { data, content } = matter( raw );
+
+  if ( !content || content.trim() === '' ) {
+    throw new Error( 'Prompt file has no content after frontmatter' );
+  }
+
+  const infoExtractor = /<(system|user|assistant|tool)>([\s\S]*?)<\/\1>/gm;
+  const messages = [ ...content.matchAll( infoExtractor ) ].map(
+    ( [ _, role, text ] ) => ( { role, content: text.trim() } )
+  );
+
+  if ( messages.length === 0 ) {
+    const contentPreview = content.substring( 0, 200 );
+    const ellipsis = content.length > 200 ? '...' : '';
+
+    throw new Error(
+      `No valid message blocks found in prompt file. 
+Expected format: <system>...</system>, <user>...</user>, etc. 
+Content preview: ${contentPreview}${ellipsis}`
+    );
+  }
+
+  return { data, messages };
+}

package/src/parser.spec.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { parsePrompt } from './parser.js';
+
+describe( 'parsePrompt', () => {
+  it( 'parses frontmatter config and message blocks', () => {
+    const raw = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+<system>You are a helpful assistant.</system>
+<user>Hello!</user>`;
+
+    const result = parsePrompt( raw );
+
+    expect( result.data ).toEqual( {
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20241022'
+    } );
+    expect( result.messages ).toHaveLength( 2 );
+    expect( result.messages[0] ).toEqual( {
+      role: 'system',
+      content: 'You are a helpful assistant.'
+    } );
+    expect( result.messages[1] ).toEqual( {
+      role: 'user',
+      content: 'Hello!'
+    } );
+  } );
+
+  it( 'throws error when content is empty', () => {
+    const raw = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+`;
+
+    expect( () => {
+      parsePrompt( raw );
+    } ).toThrow( /no content after frontmatter/ );
+  } );
+
+  it( 'throws error when no valid message blocks found', () => {
+    const raw = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+This is just plain text without any message tags.`;
+
+    expect( () => {
+      parsePrompt( raw );
+    } ).toThrow( /No valid message blocks found/ );
+    expect( () => {
+      parsePrompt( raw );
+    } ).toThrow( /Expected format/ );
+  } );
+} );

package/src/prompt_loader.js

@@ -0,0 +1,59 @@
+import { parsePrompt } from './parser.js';
+import { Liquid } from 'liquidjs';
+import { loadContent } from './load_content.js';
+import { validatePrompt } from './prompt_validations.js';
+
+const liquid = new Liquid();
+
+/**
+ * Render a single message with template variables.
+ *
+ * @param {string} role - The message role
+ * @param {string} content - The message content template
+ * @param {Record<string, string | number>} values - Variables to interpolate
+ * @param {string} promptName - Name of the prompt (for error messages)
+ * @param {number} index - Message index (for error messages)
+ * @returns {{role: string, content: string}} Rendered message object
+ */
+const renderMessage = ( role, content, values, promptName, index ) => {
+  try {
+    return {
+      role,
+      content: liquid.parseAndRenderSync( content, values )
+    };
+  } catch ( error ) {
+    throw new Error(
+      `Failed to render template in message ${index + 1} (role: ${role}) of prompt "${promptName}": ${error.message}`,
+      { cause: error }
+    );
+  }
+};
+
+/**
+ * Load a prompt file and render it with variables.
+ *
+ * @param {string} name - Name of the prompt file (without .prompt extension)
+ * @param {Record<string, string | number>} [values] - Variables to interpolate
+ * @returns {Prompt} Loaded and rendered prompt object
+ */
+export const loadPrompt = ( name, values ) => {
+  const promptContent = loadContent( `${name}.prompt` );
+  if ( !promptContent ) {
+    throw new Error( `Prompt ${name} not found.` );
+  }
+
+  const { data: config, messages } = parsePrompt( promptContent );
+
+  const prompt = {
+    name,
+    config,
+    messages: messages.map( ( { role, content }, index ) =>
+      renderMessage( role, content, values, name, index )
+    )
+  };
+
+  validatePrompt( prompt );
+
+  return prompt;
+};
+

package/src/prompt_loader.spec.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadPrompt } from './prompt_loader.js';
+
+// Mock dependencies
+vi.mock( './load_content.js', () => ( {
+  loadContent: vi.fn()
+} ) );
+
+vi.mock( './parser.js', () => ( {
+  parsePrompt: vi.fn()
+} ) );
+
+vi.mock( './prompt_validations.js', () => ( {
+  validatePrompt: vi.fn()
+} ) );
+
+import { loadContent } from './load_content.js';
+import { parsePrompt } from './parser.js';
+import { validatePrompt } from './prompt_validations.js';
+
+describe( 'loadPrompt', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+  } );
+
+  it( 'loads prompt file and renders with variables', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+<user>Hello {{ name }}!</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+    parsePrompt.mockReturnValue( {
+      data: { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' },
+      messages: [ { role: 'user', content: 'Hello {{ name }}!' } ]
+    } );
+
+    const result = loadPrompt( 'test', { name: 'World' } );
+
+    expect( result.name ).toBe( 'test' );
+    expect( result.config ).toEqual( { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' } );
+    expect( result.messages ).toHaveLength( 1 );
+    expect( result.messages[0].content ).toBe( 'Hello World!' );
+    expect( validatePrompt ).toHaveBeenCalledWith( result );
+  } );
+
+  it( 'throws error when prompt file not found', () => {
+    loadContent.mockReturnValue( null );
+
+    expect( () => {
+      loadPrompt( 'nonexistent' );
+    } ).toThrow( /Prompt nonexistent not found/ );
+  } );
+
+} );

package/src/prompt_validations.js

@@ -0,0 +1,30 @@
+import { ValidationError, z } from '@output.ai/core';
+
+export const promptSchema = z.object( {
+  name: z.string(),
+  config: z.object( {
+    provider: z.enum( [ 'anthropic', 'azure', 'openai' ] ),
+    model: z.string(),
+    temperature: z.number().optional(),
+    maxTokens: z.number().optional(),
+    providerOptions: z.object( {
+      thinking: z.object( {
+        type: z.literal( 'enabled' ),
+        budgetTokens: z.number()
+      } ).optional()
+    } ).optional()
+  } ),
+  messages: z.array(
+    z.object( {
+      role: z.string(),
+      content: z.string()
+    } )
+  )
+} );
+
+export function validatePrompt( prompt ) {
+  const result = promptSchema.safeParse( prompt );
+  if ( !result.success ) {
+    throw new ValidationError( `Invalid prompt file: ${z.prettifyError( result.error )}` );
+  }
+}

package/src/validations.js

@@ -0,0 +1,55 @@
+import { ValidationError, z } from '@output.ai/core';
+
+const generateTextArgsSchema = z.object( {
+  prompt: z.string(),
+  variables: z.any().optional()
+} );
+
+const generateObjectArgsSchema = z.object( {
+  prompt: z.string(),
+  variables: z.any().optional(),
+  schema: z.custom( v => v instanceof z.ZodObject, {
+    message: 'schema must be a ZodObject'
+  } ),
+  schemaName: z.string().optional(),
+  schemaDescription: z.string().optional()
+} );
+
+const generateArrayArgsSchema = z.object( {
+  prompt: z.string(),
+  variables: z.any().optional(),
+  schema: z.custom( v => v instanceof z.ZodType, {
+    message: 'schema must be a ZodType'
+  } ),
+  schemaName: z.string().optional(),
+  schemaDescription: z.string().optional()
+} );
+
+const generateEnumArgsSchema = z.object( {
+  prompt: z.string(),
+  variables: z.any().optional(),
+  enum: z.array( z.string() )
+} );
+
+function validateSchema( schema, input, errorPrefix ) {
+  const result = schema.safeParse( input );
+  if ( !result.success ) {
+    throw new ValidationError( `${errorPrefix}: ${z.prettifyError( result.error )}` );
+  }
+}
+
+export function validateGenerateTextArgs( args ) {
+  validateSchema( generateTextArgsSchema, args, 'Invalid generateText() arguments' );
+}
+
+export function validateGenerateObjectArgs( args ) {
+  validateSchema( generateObjectArgsSchema, args, 'Invalid generateObject() arguments' );
+}
+
+export function validateGenerateArrayArgs( args ) {
+  validateSchema( generateArrayArgsSchema, args, 'Invalid generateArray() arguments' );
+}
+
+export function validateGenerateEnumArgs( args ) {
+  validateSchema( generateEnumArgsSchema, args, 'Invalid generateEnum() arguments' );
+}