@output.ai/llm 0.1.0 → 0.2.1

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.1.0",
+  "version": "0.2.1",
   "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

@@ -4,6 +4,31 @@ import { openai } from '@ai-sdk/openai';
 
 const providers = { azure, anthropic, openai };
 
-export const loadModel = prompt => {
-  return providers[prompt.config.provider]( prompt.config.model );
-};
+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' );
+  }
+
+  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_sdk.js

@@ -2,6 +2,7 @@ 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 traceWrapper = async ( traceId, fn ) => {
   try {
@@ -14,28 +15,47 @@ const traceWrapper = async ( traceId, fn ) => {
   }
 };
 
-const extraAiSdkOptionsFromPrompt = prompt => ( {
-  model: loadModel( prompt ),
-  messages: prompt.messages,
-  ...( prompt.config.temperature && { temperature: prompt.config.temperature } ),
-  ...( prompt.config.max_tokens && { maxOutputTokens: prompt.config.maxTokens } ),
-  providerOptions: prompt.providerOptions
-} );
+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 {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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 } ) {
-  validateGenerateTextArgs( { prompt } );
-  const traceId = `generateText-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateText', id: traceId, details: { prompt } } );
+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( prompt ) ).then( r => r.text )
+    AI.generateText( extraAiSdkOptionsFromPrompt( loadedPrompt ) ).then( r => r.text )
   );
 }
 
@@ -43,7 +63,8 @@ export async function generateText( { prompt } ) {
  * Use an LLM model to generate an object with a fixed schema.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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
@@ -51,10 +72,9 @@ export async function generateText( { prompt } ) {
  */
 export async function generateObject( args ) {
   validateGenerateObjectArgs( args );
-  const { prompt, schema, schemaName, schemaDescription } = args;
-
-  const traceId = `generateObject-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateObject', id: traceId, details: 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( {
@@ -62,7 +82,7 @@ export async function generateObject( args ) {
       schema,
       schemaName,
       schemaDescription,
-      ...extraAiSdkOptionsFromPrompt( prompt )
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
     } ).then( r => r.object )
   );
 }
@@ -71,7 +91,8 @@ export async function generateObject( args ) {
  * Use an LLM model to generate an array of values with a fixed schema.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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
@@ -79,10 +100,9 @@ export async function generateObject( args ) {
  */
 export async function generateArray( args ) {
   validateGenerateArrayArgs( args );
-  const { prompt, schema, schemaName, schemaDescription } = args;
-
-  const traceId = `generateArray-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateArray', id: traceId, details: 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( {
@@ -90,7 +110,7 @@ export async function generateArray( args ) {
       schema,
       schemaName,
       schemaDescription,
-      ...extraAiSdkOptionsFromPrompt( prompt )
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
     } ).then( r => r.object )
   );
 }
@@ -99,18 +119,22 @@ export async function generateArray( args ) {
  * Use an LLM model to generate a result from an enum (array of string values).
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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, enum: _enum } = args;
-
-  const traceId = `generateEnum-${Date.now()}`;
-  Tracing.addEventStart( { kind: 'llm', name: 'generateEnum', id: traceId, details: 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( prompt ) } ).then( r => r.object )
+    AI.generateObject( {
+      output: 'enum',
+      enum: _enum,
+      ...extraAiSdkOptionsFromPrompt( loadedPrompt )
+    } ).then( r => r.object )
   );
 }

package/src/ai_sdk.spec.js

@@ -27,12 +27,21 @@ const validators = {
 };
 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 },
-  messages: [ { role: 'user', content: 'Hi' } ],
-  providerOptions: { thinking: { enabled: true } }
+  config: {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    temperature: 0.3,
+    providerOptions: { thinking: { enabled: true } }
+  },
+  messages: [ { role: 'user', content: 'Hi' } ]
 };
 
 beforeEach( () => {
@@ -41,6 +50,7 @@ beforeEach( () => {
   tracingSpies.addEventError.mockClear();
 
   loadModelImpl.mockReset().mockReturnValue( 'MODEL' );
+  loadPromptImpl.mockReset().mockReturnValue( basePrompt );
 
   aiFns.generateText.mockReset().mockResolvedValue( { text: 'TEXT' } );
   aiFns.generateObject.mockReset().mockResolvedValue( { object: 'OBJECT' } );
@@ -59,9 +69,10 @@ afterEach( async () => {
 describe( 'ai_sdk', () => {
   it( 'generateText: validates, traces, calls AI and returns text', async () => {
     const { generateText } = await importSut();
-    const result = await generateText( { prompt: basePrompt } );
+    const result = await generateText( { prompt: 'test_prompt@v1' } );
 
-    expect( validators.validateGenerateTextArgs ).toHaveBeenCalledWith( { prompt: basePrompt } );
+    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 );
 
@@ -70,7 +81,7 @@ describe( 'ai_sdk', () => {
       model: 'MODEL',
       messages: basePrompt.messages,
       temperature: 0.3,
-      providerOptions: basePrompt.providerOptions
+      providerOptions: basePrompt.config.providerOptions
     } );
     expect( result ).toBe( 'TEXT' );
   } );
@@ -81,13 +92,14 @@ describe( 'ai_sdk', () => {
 
     const schema = z.object( { a: z.number() } );
     const result = await generateObject( {
-      prompt: basePrompt,
+      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 );
 
@@ -99,7 +111,7 @@ describe( 'ai_sdk', () => {
       model: 'MODEL',
       messages: basePrompt.messages,
       temperature: 0.3,
-      providerOptions: basePrompt.providerOptions
+      providerOptions: basePrompt.config.providerOptions
     } );
     expect( result ).toEqual( { a: 1 } );
   } );
@@ -110,13 +122,14 @@ describe( 'ai_sdk', () => {
 
     const schema = z.number();
     const result = await generateArray( {
-      prompt: basePrompt,
+      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 );
 
@@ -128,7 +141,7 @@ describe( 'ai_sdk', () => {
       model: 'MODEL',
       messages: basePrompt.messages,
       temperature: 0.3,
-      providerOptions: basePrompt.providerOptions
+      providerOptions: basePrompt.config.providerOptions
     } );
     expect( result ).toEqual( [ 1, 2 ] );
   } );
@@ -137,9 +150,10 @@ describe( 'ai_sdk', () => {
     const { generateEnum } = await importSut();
     aiFns.generateObject.mockResolvedValueOnce( { object: 'B' } );
 
-    const result = await generateEnum( { prompt: basePrompt, enum: [ 'A', 'B', 'C' ] } );
+    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 );
 
@@ -149,7 +163,7 @@ describe( 'ai_sdk', () => {
       model: 'MODEL',
       messages: basePrompt.messages,
       temperature: 0.3,
-      providerOptions: basePrompt.providerOptions
+      providerOptions: basePrompt.config.providerOptions
     } );
     expect( result ).toBe( 'B' );
   } );

package/src/index.d.ts

@@ -1,21 +1,90 @@
 import type { z } from '@output.ai/core';
-import type { Prompt } from '@output.ai/prompt';
 
-export type { Prompt };
+/**
+ * Represents a single message in a prompt conversation
+ * @example
+ * const msg: PromptMessage = {
+ *   role: 'user',
+ *   content: 'Hello, Claude!'
+ * };
+ */
+export type PromptMessage = {
+  /** The role of the message. Examples: 'system', 'user', 'assistant' */
+  role: string;
+  /** The content of the message */
+  content: string;
+};
+
+/**
+ * Configuration for LLM prompt generation
+ * @example
+ * const prompt: Prompt = {
+ *   name: 'summarizePrompt',
+ *   config: {
+ *     provider: 'anthropic',
+ *     model: 'claude-opus-4-1',
+ *     temperature: 0.7,
+ *     maxTokens: 2048
+ *   },
+ *   messages: [...]
+ * };
+ */
+export type Prompt = {
+  /** Name of the prompt file */
+  name: string;
+
+  /** General configurations for the LLM */
+  config: {
+    /** LLM Provider */
+    provider: 'anthropic' | 'openai' | 'azure';
+
+    /** Model name/identifier */
+    model: string;
+
+    /** Generation temperature (0-2). Lower = more deterministic */
+    temperature?: number;
+
+    /** Maximum tokens in the response */
+    maxTokens?: number;
+
+    /** Additional provider-specific options */
+    options?: Record<string, Record<string, JSONValue>>;
+
+    /** Provider-specific configurations */
+    providerOptions?: Record<string, unknown>;
+  };
+
+  /** Array of messages in the conversation */
+  messages: PromptMessage[];
+};
+
+/**
+ * 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>} [variables] - Variables to interpolate
+ * @returns {Prompt} Loaded and rendered prompt object
+ */
+export function loadPrompt(
+  name: string,
+  variables?: Record<string, string | number>
+): Prompt;
 
 /**
  * Use an LLM model to generate text.
  *
  * This function is a wrapper over the AI SDK's `generateText`.
- * The `Prompt` sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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: {
-    prompt: Prompt
+    prompt: string,
+    variables?: Record<string, string | number>
   }
 ): Promise<string>;
 
@@ -23,10 +92,11 @@ export function generateText(
  * 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` sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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
@@ -34,8 +104,9 @@ export function generateText(
  */
 export function generateObject<TSchema extends z.ZodObject>(
   args: {
-    prompt: Prompt,
-    schema?: TSchema,
+    prompt: string,
+    variables?: Record<string, string | number>,
+    schema: TSchema,
     schemaName?: string,
     schemaDescription?: string
   }
@@ -45,10 +116,11 @@ export function generateObject<TSchema extends z.ZodObject>(
  * 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` sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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
@@ -56,8 +128,9 @@ export function generateObject<TSchema extends z.ZodObject>(
  */
 export function generateArray<TSchema extends z.ZodType>(
   args: {
-    prompt: Prompt,
-    schema?: TSchema,
+    prompt: string,
+    variables?: Record<string, string | number>,
+    schema: TSchema,
     schemaName?: string,
     schemaDescription?: string
   }
@@ -67,16 +140,18 @@ export function generateArray<TSchema extends z.ZodType>(
  * 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` sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
+ * The prompt file sets `model`, `messages`, `temperature`, `max_tokens`, and `provider_options`.
  *
  * @param {object} args - Generation arguments
- * @param {Prompt} args.prompt - `@output.ai/prompt` Prompt object
+ * @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 generateEnum<const TEnum extends readonly [string, ...string[]]>(
   args: {
-    prompt: Prompt,
+    prompt: string,
+    variables?: Record<string, string | number>,
     enum: TEnum
   }
 ): Promise<TEnum[number]>;

package/src/index.js

@@ -1,2 +1,3 @@
 export { generateText, generateArray, generateObject, generateEnum } from './ai_sdk.js';
+export { loadPrompt } from './prompt_loader.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

@@ -1,12 +1,13 @@
 import { ValidationError, z } from '@output.ai/core';
-import { promptSchema } from '@output.ai/prompt';
 
 const generateTextArgsSchema = z.object( {
-  prompt: promptSchema
+  prompt: z.string(),
+  variables: z.any().optional()
 } );
 
 const generateObjectArgsSchema = z.object( {
-  prompt: promptSchema,
+  prompt: z.string(),
+  variables: z.any().optional(),
   schema: z.custom( v => v instanceof z.ZodObject, {
     message: 'schema must be a ZodObject'
   } ),
@@ -15,7 +16,8 @@ const generateObjectArgsSchema = z.object( {
 } );
 
 const generateArrayArgsSchema = z.object( {
-  prompt: promptSchema,
+  prompt: z.string(),
+  variables: z.any().optional(),
   schema: z.custom( v => v instanceof z.ZodType, {
     message: 'schema must be a ZodType'
   } ),
@@ -24,29 +26,30 @@ const generateArrayArgsSchema = z.object( {
 } );
 
 const generateEnumArgsSchema = z.object( {
-  prompt: promptSchema,
+  prompt: z.string(),
+  variables: z.any().optional(),
   enum: z.array( z.string() )
 } );
 
-export function validateSchema( schema, input, errorPrefix ) {
+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' );
-};
+}