@outputai/llm 0.1.0

package/src/parser.js

@@ -0,0 +1,28 @@
+import matter from 'gray-matter';
+import { FatalError } from '@outputai/core';
+
+export function parsePrompt( raw ) {
+  const { data: config, content } = matter( raw );
+
+  if ( !content || content.trim() === '' ) {
+    throw new FatalError( '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 FatalError(
+      `No valid message blocks found in prompt file.
+Expected format: <system>...</system>, <user>...</user>, etc.
+Content preview: ${contentPreview}${ellipsis}`
+    );
+  }
+
+  return { config, messages };
+}

package/src/parser.spec.js

@@ -0,0 +1,122 @@
+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.config ).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/ );
+  } );
+
+  it( 'should use providerOptions with budgetTokens in camelCase', () => {
+    // Frontmatter uses canonical format: providerOptions.thinking.budgetTokens
+    const raw = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.7
+maxTokens: 64000
+providerOptions:
+  thinking:
+    type: enabled
+    budgetTokens: 1500
+---
+
+<user>Test</user>`;
+
+    const result = parsePrompt( raw );
+
+    expect( result.config.provider ).toBe( 'anthropic' );
+    expect( result.config.model ).toBe( 'claude-sonnet-4-20250514' );
+    expect( result.config.temperature ).toBe( 0.7 );
+    expect( result.config.maxTokens ).toBe( 64000 );
+
+    // Now expects canonical schema format in front-matter
+    expect( result.config.providerOptions ).toBeDefined();
+    expect( result.config.providerOptions.thinking ).toBeDefined();
+    expect( result.config.providerOptions.thinking.type ).toBe( 'enabled' );
+    expect( result.config.providerOptions.thinking.budgetTokens ).toBe( 1500 );
+  } );
+
+  it( 'should parse snake_case fields as-is (validation catches them later)', () => {
+    // Parser extracts fields as-is from frontmatter; validation happens later
+    const raw = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.7
+max_tokens: 64000
+providerOptions:
+  thinking:
+    type: enabled
+    budget_tokens: 1500
+---
+
+<user>Test</user>`;
+
+    const result = parsePrompt( raw );
+
+    // Parser extracts snake_case fields as-is
+    expect( result.config.provider ).toBe( 'anthropic' );
+    expect( result.config.model ).toBe( 'claude-sonnet-4-20250514' );
+    expect( result.config.temperature ).toBe( 0.7 );
+    // snake_case preserved here because we're only calling parsePrompt, not validatePrompt
+    expect( result.config.max_tokens ).toBe( 64000 );
+    // camelCase not set because we only call parsePrompt
+    expect( result.config.maxTokens ).toBeUndefined();
+
+    // Snake_case fields in nested objects also preserved
+    expect( result.config.providerOptions ).toBeDefined();
+    expect( result.config.providerOptions.thinking ).toBeDefined();
+    expect( result.config.providerOptions.thinking.type ).toBe( 'enabled' );
+    expect( result.config.providerOptions.thinking.budget_tokens ).toBe( 1500 ); // snake_case preserved
+    expect( result.config.providerOptions.thinking.budgetTokens ).toBeUndefined(); // camelCase not set
+  } );
+} );

package/src/prompt_loader.js

@@ -0,0 +1,45 @@
+import { parsePrompt } from './parser.js';
+import { Liquid } from 'liquidjs';
+import { loadContent } from './load_content.js';
+import { validatePrompt } from './prompt_validations.js';
+import { FatalError } from '@outputai/core';
+
+const liquid = new Liquid();
+
+const renderPrompt = ( name, content, values ) => {
+  try {
+    return liquid.parseAndRenderSync( content, values );
+  } catch ( error ) {
+    throw new FatalError( `Failed to render template in prompt "${name}": ${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 | boolean>} [values] - Variables to interpolate
+ * @param {string} [dir] - Directory to search for the prompt file (defaults to stack-resolved invocation dir)
+ * @returns {Prompt} Loaded and rendered prompt object
+ */
+export const loadPrompt = ( name, values = {}, dir ) => {
+  const promptContent = dir ? loadContent( `${name}.prompt`, dir ) : loadContent( `${name}.prompt` );
+  if ( !promptContent ) {
+    throw new FatalError( `Prompt ${name} not found.` );
+  }
+
+  const renderedContent = renderPrompt( name, promptContent, values );
+
+  const { config, messages } = parsePrompt( renderedContent );
+
+  const prompt = {
+    name,
+    config,
+    messages
+  };
+
+  validatePrompt( prompt );
+
+  return prompt;
+};
+

package/src/prompt_loader.spec.js

@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadPrompt } from './prompt_loader.js';
+
+// Mock dependencies that perform I/O or validation
+vi.mock( './load_content.js', () => ( {
+  loadContent: vi.fn()
+} ) );
+
+vi.mock( './prompt_validations.js', () => ( {
+  validatePrompt: vi.fn()
+} ) );
+
+import { loadContent } from './load_content.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 );
+
+    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/ );
+  } );
+
+} );
+
+describe( 'loadPrompt - template hydration in headers (integration tests)', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+  } );
+
+  it( 'should hydrate template variables in YAML headers', () => {
+    const promptContent = `---
+provider: {{ provider_name }}
+model: {{ model_id }}
+temperature: 0.7
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {
+      provider_name: 'anthropic',
+      model_id: 'claude-sonnet-4'
+    } );
+
+    expect( result.config.provider ).toBe( 'anthropic' );
+    expect( result.config.model ).toBe( 'claude-sonnet-4' );
+    expect( result.config.temperature ).toBe( 0.7 );
+  } );
+
+  it( 'should hydrate template variables in both headers and messages', () => {
+    const promptContent = `---
+provider: {{ provider }}
+model: {{ model }}
+---
+
+<user>Tell me about {{ topic }}</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {
+      provider: 'openai',
+      model: 'gpt-4',
+      topic: 'testing'
+    } );
+
+    expect( result.config.provider ).toBe( 'openai' );
+    expect( result.config.model ).toBe( 'gpt-4' );
+    expect( result.messages[0].content ).toBe( 'Tell me about testing' );
+  } );
+
+  it( 'should render undefined template variables as null', () => {
+    const promptContent = `---
+provider: {{ undefined_var }}
+model: claude-3-5-sonnet-20241022
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {} );
+
+    // Liquid renders undefined variables as empty, which becomes null in YAML
+    expect( result.config.provider ).toBe( null );
+    expect( result.config.model ).toBe( 'claude-3-5-sonnet-20241022' );
+  } );
+
+  it( 'should handle complex template expressions in headers', () => {
+    const promptContent = `---
+provider: anthropic
+model: {{ base_model }}-{{ version }}
+temperature: 0.7
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {
+      base_model: 'claude-sonnet',
+      version: '4'
+    } );
+
+    expect( result.config.model ).toBe( 'claude-sonnet-4' );
+  } );
+
+  it( 'should use camelCase config keys', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+maxTokens: 1024
+temperature: 0.7
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {} );
+
+    expect( result.config.maxTokens ).toBe( 1024 );
+  } );
+
+  it( 'should render boolean variables correctly', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+<user>{% if debug %}Debug mode enabled{% else %}Debug mode disabled{% endif %}</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', { debug: true } );
+
+    expect( result.messages[0].content ).toBe( 'Debug mode enabled' );
+  } );
+
+  it( 'should render false boolean variables', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-3-5-sonnet-20241022
+---
+
+<user>{% if enabled %}Feature enabled{% else %}Feature disabled{% endif %}</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', { enabled: false } );
+
+    expect( result.messages[0].content ).toBe( 'Feature disabled' );
+  } );
+
+} );

package/src/prompt_loader_validation.spec.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadPrompt } from './prompt_loader.js';
+
+vi.mock( './load_content.js', () => ( {
+  loadContent: vi.fn()
+} ) );
+
+import { loadContent } from './load_content.js';
+
+describe( 'loadPrompt - validation with real schema', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+  } );
+
+  it( 'should accept valid camelCase format with providerOptions and budgetTokens', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+temperature: 0.7
+maxTokens: 64000
+providerOptions:
+  thinking:
+    type: enabled
+    budgetTokens: 1500
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    const result = loadPrompt( 'test', {} );
+
+    expect( result.config.providerOptions ).toBeDefined();
+    expect( result.config.providerOptions.thinking.type ).toBe( 'enabled' );
+    expect( result.config.providerOptions.thinking.budgetTokens ).toBe( 1500 );
+  } );
+
+  it( 'should accept snake_case max_tokens via config passthrough (no longer strict)', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+max_tokens: 64000
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    // Config uses passthrough, so max_tokens is accepted (though ignored by SDK)
+    expect( () => {
+      loadPrompt( 'test', {} );
+    } ).not.toThrow();
+  } );
+
+  it( 'should accept "options" field via config passthrough (no longer strict)', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+options:
+  thinking:
+    type: enabled
+    budgetTokens: 1500
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    // Config uses passthrough, so 'options' passes through (though not used)
+    expect( () => {
+      loadPrompt( 'test', {} );
+    } ).not.toThrow();
+  } );
+
+  it( 'should accept snake_case budget_tokens in thinking via passthrough', () => {
+    const promptContent = `---
+provider: anthropic
+model: claude-sonnet-4-20250514
+providerOptions:
+  thinking:
+    type: enabled
+    budget_tokens: 1500
+---
+
+<user>Hello</user>`;
+
+    loadContent.mockReturnValue( promptContent );
+
+    // budget_tokens is silently stripped from thinking (unknown field), not rejected
+    expect( () => {
+      loadPrompt( 'test', {} );
+    } ).not.toThrow();
+  } );
+
+} );

package/src/prompt_validations.js

@@ -0,0 +1,60 @@
+import { ValidationError, z } from '@outputai/core';
+
+export const promptSchema = z.object( {
+  name: z.string(),
+  config: z.object( {
+    provider: z.string().min( 1 ),
+    model: z.string(),
+    temperature: z.number().optional(),
+    maxTokens: z.number().optional(),
+    tools: z.record( z.string(), z.object( {} ).passthrough() ).optional(),
+    providerOptions: z.object( {
+      thinking: z.object( {
+        type: z.enum( [ 'enabled', 'disabled' ] ),
+        budgetTokens: z.number().optional()
+      } ).passthrough().optional()
+    } ).passthrough().optional()
+  } ).passthrough(),
+  messages: z.array(
+    z.object( {
+      role: z.string(),
+      content: z.string()
+    } ).strict()
+  )
+} ).strict();
+
+const SNAKE_CASE_WARNINGS = {
+  max_tokens: 'maxTokens',
+  budget_tokens: 'budgetTokens',
+  top_p: 'topP',
+  top_k: 'topK',
+  stop_sequences: 'stopSequences',
+  options: 'providerOptions'
+};
+
+function warnSnakeCaseFields( config ) {
+  for ( const [ snake, camel ] of Object.entries( SNAKE_CASE_WARNINGS ) ) {
+    if ( Object.hasOwn( config, snake ) ) {
+      console.warn( `[output-llm] "${snake}" found in prompt config. Did you mean "${camel}"?` );
+    }
+  }
+  const thinking = config.providerOptions?.thinking;
+  if ( thinking && Object.hasOwn( thinking, 'budget_tokens' ) ) {
+    console.warn( '[output-llm] "budget_tokens" found in providerOptions.thinking. Did you mean "budgetTokens"?' );
+  }
+}
+
+export function validatePrompt( prompt ) {
+  const result = promptSchema.safeParse( prompt );
+  if ( !result.success ) {
+    const promptIdentifier = prompt?.name ? `"${prompt.name}"` : '(unnamed)';
+    const errorMessage = z.prettifyError( result.error );
+
+    throw new ValidationError(
+      `Invalid prompt file ${promptIdentifier}: ${errorMessage}`,
+      { cause: result.error }
+    );
+  }
+
+  warnSnakeCaseFields( result.data.config );
+}