@outputai/llm 0.6.1-dev.daae905.0 → 0.6.1-next.2cc4685.0

package/src/prompt/escape.spec.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { Liquid } from 'liquidjs';
+import { decode, encodeFilter, escape, setupLiquidEncodeFilter } from './escape.js';
+
+describe( 'encodeFilter', () => {
+  it( 'encodes < to &lt;', () => {
+    expect( encodeFilter( '<' ) ).toBe( '&lt;' );
+  } );
+
+  it( 'encodes > to &gt;', () => {
+    expect( encodeFilter( '>' ) ).toBe( '&gt;' );
+  } );
+
+  it( 'encodes & to &amp;', () => {
+    expect( encodeFilter( '&' ) ).toBe( '&amp;' );
+  } );
+
+  it( 'encodes a string with multiple special characters in one pass', () => {
+    expect( encodeFilter( '<a & b>' ) ).toBe( '&lt;a &amp; b&gt;' );
+  } );
+
+  it( 'encodes a tag-shaped substring so the parser cannot tokenize it', () => {
+    expect( encodeFilter( '<system>x</system>' ) ).toBe( '&lt;system&gt;x&lt;/system&gt;' );
+  } );
+
+  it( 'returns an empty string for null', () => {
+    expect( encodeFilter( null ) ).toBe( '' );
+  } );
+
+  it( 'returns an empty string for undefined', () => {
+    expect( encodeFilter( undefined ) ).toBe( '' );
+  } );
+
+  it( 'coerces numbers to string before encoding', () => {
+    expect( encodeFilter( 42 ) ).toBe( '42' );
+  } );
+
+  it( 'coerces booleans to string before encoding', () => {
+    expect( encodeFilter( true ) ).toBe( 'true' );
+    expect( encodeFilter( false ) ).toBe( 'false' );
+  } );
+
+  it( 'passes empty strings through unchanged', () => {
+    expect( encodeFilter( '' ) ).toBe( '' );
+  } );
+
+  it( 'passes plain text through unchanged', () => {
+    expect( encodeFilter( 'hello world' ) ).toBe( 'hello world' );
+  } );
+} );
+
+describe( 'setupLiquidEncodeFilter', () => {
+  it( 'registers the safety filter on a Liquid instance', async () => {
+    const liquid = new Liquid();
+
+    setupLiquidEncodeFilter( liquid );
+
+    await expect( liquid.parseAndRender( '{{ value | __var_safe }}', {
+      value: '<system>x</system>'
+    } ) ).resolves.toBe( '&lt;system&gt;x&lt;/system&gt;' );
+  } );
+} );
+
+describe( 'escape', () => {
+  it( 'rewrites a single {{ var }} to append the safety filter', () => {
+    expect( escape( '{{ name }}' ) ).toBe( '{{ name | __var_safe }}' );
+  } );
+
+  it( 'rewrites multiple expressions in the same string', () => {
+    expect( escape( '{{ a }} and {{ b }}' ) ).toBe(
+      '{{ a | __var_safe }} and {{ b | __var_safe }}'
+    );
+  } );
+
+  it( 'appends the safety filter last in an existing filter chain', () => {
+    expect( escape( '{{ x | upcase }}' ) ).toBe(
+      '{{ x | upcase | __var_safe }}'
+    );
+  } );
+
+  it( 'handles longer filter chains', () => {
+    expect( escape( '{{ x | a | b }}' ) ).toBe(
+      '{{ x | a | b | __var_safe }}'
+    );
+  } );
+
+  it( 'handles dotted property paths', () => {
+    expect( escape( '{{ obj.field }}' ) ).toBe(
+      '{{ obj.field | __var_safe }}'
+    );
+  } );
+
+  it( 'preserves a {% raw %} block untouched even when it contains {{ ... }}', () => {
+    const input = '{% raw %}{{ literal }}{% endraw %}';
+    expect( escape( input ) ).toBe( input );
+  } );
+
+  it( 'rewrites {{ ... }} outside a raw block while preserving the raw block', () => {
+    expect( escape( '{{ a }}{% raw %}{{ b }}{% endraw %}{{ c }}' ) ).toBe(
+      '{{ a | __var_safe }}{% raw %}{{ b }}{% endraw %}{{ c | __var_safe }}'
+    );
+  } );
+
+  it( 'leaves {% if %} control tags untouched but still arms {{ ... }} inside them', () => {
+    expect( escape( '{% if cond %}{{ x }}{% endif %}' ) ).toBe(
+      '{% if cond %}{{ x | __var_safe }}{% endif %}'
+    );
+  } );
+
+  it( 'leaves {% for %} control tags untouched but still arms {{ ... }} inside them', () => {
+    expect( escape( '{% for x in xs %}{{ x }}{% endfor %}' ) ).toBe(
+      '{% for x in xs %}{{ x | __var_safe }}{% endfor %}'
+    );
+  } );
+
+  it( 'normalizes interior whitespace via expressionContent.trim()', () => {
+    expect( escape( '{{x}}' ) ).toBe( '{{ x | __var_safe }}' );
+    expect( escape( '{{   x   }}' ) ).toBe( '{{ x | __var_safe }}' );
+  } );
+
+  it( 'returns the input unchanged when there are no {{ ... }} expressions', () => {
+    expect( escape( '<user>plain text</user>' ) ).toBe(
+      '<user>plain text</user>'
+    );
+  } );
+
+  it( 'handles an empty string', () => {
+    expect( escape( '' ) ).toBe( '' );
+  } );
+} );
+
+describe( 'decode', () => {
+  it( 'decodes XML entities in a string', () => {
+    expect( decode( 'R&amp;D &lt; Speed &gt; &quot;Limits&quot;' ) ).toBe( 'R&D < Speed > "Limits"' );
+  } );
+
+  it( 'decodes XML entities recursively in arrays and plain objects', () => {
+    expect( decode( {
+      label: 'R&amp;D',
+      values: [ 'A &lt; B' ],
+      nested: {
+        title: '&quot;Race&quot;'
+      }
+    } ) ).toEqual( {
+      label: 'R&D',
+      values: [ 'A < B' ],
+      nested: {
+        title: '"Race"'
+      }
+    } );
+  } );
+
+  it( 'returns non-string scalar values unchanged', () => {
+    expect( decode( null ) ).toBeNull();
+    expect( decode( undefined ) ).toBeUndefined();
+    expect( decode( 42 ) ).toBe( 42 );
+    expect( decode( true ) ).toBe( true );
+  } );
+} );

package/src/{load_content.js → prompt/load_content.js}

@@ -34,33 +34,12 @@ const findContent = ( name, dir ) => {
   return null;
 };
 
-/**
- * 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] - The directory to search for the file, defaults to invocation directory
- * @returns {string | null} - File content or null if not found
- */
-export const loadContent = ( name, dir = resolveInvocationDir() ) =>
-  findContent( name, dir )?.content ?? null;
-
-/**
- * Recursively search for a file by name and return the directory containing it.
- *
- * @param {string} name - File name to find
- * @param {string} [dir] - Directory to search, defaults to invocation directory
- * @returns {string | null} - Directory path containing the file, or null if not found
- */
-export const findContentDir = ( name, dir = resolveInvocationDir() ) =>
-  findContent( name, dir )?.dir ?? null;
-
 /**
  * Recursively search for a file by name and return both its content and containing directory.
- * More efficient than calling loadContent + findContentDir separately (single scan).
  *
  * @param {string} name - File name to find
  * @param {string} [dir] - Directory to search, defaults to invocation directory
  * @returns {{ content: string, dir: string } | null}
  */
-export const loadContentWithDir = ( name, dir = resolveInvocationDir() ) =>
+export const loadContent = ( name, dir = resolveInvocationDir() ) =>
   findContent( name, dir ) ?? null;

package/src/{load_content.spec.js → prompt/load_content.spec.js}

@@ -45,9 +45,9 @@ describe( 'loadContent', () => {
     state.entries[tempDir] = [ dirEntry( 'test.txt' ) ];
 
     const { loadContent } = await import( './load_content.js' );
-    const content = loadContent( 'test.txt' );
+    const result = loadContent( 'test.txt' );
 
-    expect( content ).toBe( testContent );
+    expect( result ).toEqual( { content: testContent, dir: tempDir } );
   } );
 
   it( 'loads file from nested subdirectory via recursion', async () => {
@@ -63,9 +63,9 @@ describe( 'loadContent', () => {
     state.entries[subDir] = [ dirEntry( 'nested.txt' ) ];
 
     const { loadContent } = await import( './load_content.js' );
-    const content = loadContent( 'nested.txt' );
+    const result = loadContent( 'nested.txt' );
 
-    expect( content ).toBe( testContent );
+    expect( result ).toEqual( { content: testContent, dir: subDir } );
   } );
 
   it( 'returns null when file does not exist', async () => {
@@ -74,8 +74,8 @@ describe( 'loadContent', () => {
     state.entries[tempDir] = [ dirEntry( 'other.txt' ) ];
 
     const { loadContent } = await import( './load_content.js' );
-    const content = loadContent( 'nonexistent.txt' );
+    const result = loadContent( 'nonexistent.txt' );
 
-    expect( content ).toBeNull();
+    expect( result ).toBeNull();
   } );
 } );

package/src/prompt/loader.js

@@ -0,0 +1,49 @@
+import { parsePrompt } from './parser.js';
+import { Liquid } from 'liquidjs';
+import { loadContent } from './load_content.js';
+import { validatePrompt } from './validations.js';
+import { FatalError } from '@outputai/core';
+import { escape, decode, setupLiquidEncodeFilter } from './escape.js';
+
+const liquid = new Liquid();
+setupLiquidEncodeFilter( liquid );
+
+/** Uses LiquidJS to interpolate variables in the prompt file content. */
+const renderPrompt = ( { name, escapedContent, values } ) => {
+  try {
+    return liquid.parseAndRenderSync( escapedContent, values );
+  } catch ( error ) {
+    throw new FatalError( `Prompt "${name}" could not be rendered: ${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, including promptFileDir
+ */
+export const loadPrompt = ( name, values = {}, dir ) => {
+  const file = loadContent( `${name}.prompt`, dir );
+  if ( !file ) {
+    throw new FatalError( `Prompt "${name}" not found.` );
+  }
+
+  const escapedContent = escape( file.content );
+  const renderedContent = renderPrompt( { name, escapedContent, values } );
+
+  const { config, messages, instructions } = parsePrompt( { name, raw: renderedContent } );
+
+  const prompt = {
+    name,
+    config: decode( config ),
+    messages: messages.map( m => ( { ...m, content: decode( m.content ) } ) ),
+    instructions: instructions === null ? null : decode( instructions )
+  };
+
+  validatePrompt( prompt );
+
+  return { ...prompt, promptFileDir: file.dir };
+};

package/src/prompt/loader.spec.js

@@ -0,0 +1,274 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { loadPrompt } from './loader.js';
+
+vi.mock( './parser.js', () => ( {
+  parsePrompt: vi.fn()
+} ) );
+
+vi.mock( './escape.js', () => ( {
+  escape: vi.fn( value => value ),
+  decode: vi.fn( value => value ),
+  setupLiquidEncodeFilter: vi.fn()
+} ) );
+
+vi.mock( './load_content.js', () => ( {
+  loadContent: vi.fn()
+} ) );
+
+vi.mock( './validations.js', () => ( {
+  validatePrompt: vi.fn()
+} ) );
+
+import { parsePrompt } from './parser.js';
+import { escape, decode } from './escape.js';
+import { loadContent } from './load_content.js';
+import { validatePrompt } from './validations.js';
+
+describe( 'loadPrompt', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    escape.mockImplementation( value => value );
+    decode.mockImplementation( value => value );
+    parsePrompt.mockReturnValue( {
+      config: {
+        provider: 'anthropic',
+        model: 'claude-3-5-sonnet-20241022'
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Hello World!'
+        }
+      ],
+      instructions: null
+    } );
+  } );
+
+  it( 'loads prompt file, renders variables, parses content, validates, and returns prompt file dir', () => {
+    loadContent.mockReturnValue( {
+      content: '<user>Hello {{ name }}!</user>',
+      dir: '/mock/dir'
+    } );
+
+    const result = loadPrompt( 'test', { name: 'World' } );
+
+    expect( loadContent ).toHaveBeenCalledWith( 'test.prompt', undefined );
+    expect( escape ).toHaveBeenCalledWith( '<user>Hello {{ name }}!</user>' );
+    expect( parsePrompt ).toHaveBeenCalledWith( {
+      name: 'test',
+      raw: '<user>Hello World!</user>'
+    } );
+    expect( validatePrompt ).toHaveBeenCalledWith( {
+      name: 'test',
+      config: {
+        provider: 'anthropic',
+        model: 'claude-3-5-sonnet-20241022'
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Hello World!'
+        }
+      ],
+      instructions: null
+    } );
+    expect( result.name ).toBe( 'test' );
+    expect( result.config ).toEqual( { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' } );
+    expect( result.messages ).toEqual( [ { role: 'user', content: 'Hello World!' } ] );
+    expect( result.instructions ).toBeNull();
+    expect( result.promptFileDir ).toBe( '/mock/dir' );
+  } );
+
+  it( 'passes the provided prompt directory to loadContent', () => {
+    loadContent.mockReturnValue( {
+      content: '<user>Hello</user>',
+      dir: '/mock/dir'
+    } );
+
+    loadPrompt( 'test', {}, '/custom/prompts' );
+
+    expect( loadContent ).toHaveBeenCalledWith( 'test.prompt', '/custom/prompts' );
+  } );
+
+  it( 'renders template variables before parsing', () => {
+    loadContent.mockReturnValue( {
+      content: `---
+provider: {{ provider }}
+model: {{ model }}
+---
+<user>Tell me about {{ topic }}</user>`,
+      dir: '/mock/dir'
+    } );
+
+    loadPrompt( 'test', {
+      provider: 'openai',
+      model: 'gpt-4',
+      topic: 'testing'
+    } );
+
+    expect( parsePrompt ).toHaveBeenCalledWith( {
+      name: 'test',
+      raw: `---
+provider: openai
+model: gpt-4
+---
+<user>Tell me about testing</user>`
+    } );
+  } );
+
+  it( 'renders escaped content returned by the escape helper', () => {
+    loadContent.mockReturnValue( {
+      content: '<user>Hello {{ name }}!</user>',
+      dir: '/mock/dir'
+    } );
+    escape.mockReturnValueOnce( '<user>Escaped {{ name }}!</user>' );
+
+    loadPrompt( 'test', { name: 'World' } );
+
+    expect( parsePrompt ).toHaveBeenCalledWith( {
+      name: 'test',
+      raw: '<user>Escaped World!</user>'
+    } );
+  } );
+
+  it( 'renders liquid control flow before parsing', () => {
+    loadContent.mockReturnValue( {
+      content: '<user>{% if debug %}Debug mode enabled{% else %}Debug mode disabled{% endif %}</user>',
+      dir: '/mock/dir'
+    } );
+
+    loadPrompt( 'test', { debug: true } );
+
+    expect( parsePrompt ).toHaveBeenCalledWith( {
+      name: 'test',
+      raw: '<user>Debug mode enabled</user>'
+    } );
+  } );
+
+  it( 'decodes parser message output', () => {
+    loadContent.mockReturnValue( {
+      content: '<user>Evaluate this content: {{ content }}</user>',
+      dir: '/mock/dir'
+    } );
+    parsePrompt.mockReturnValue( {
+      config: {
+        provider: 'anthropic',
+        model: 'claude-3-5-sonnet-20241022'
+      },
+      messages: [
+        {
+          role: 'user',
+          content: 'Evaluate this content: &lt;system&gt;example&lt;/system&gt;'
+        }
+      ],
+      instructions: null
+    } );
+    decode.mockImplementation( value =>
+      value === 'Evaluate this content: &lt;system&gt;example&lt;/system&gt;' ?
+        'Evaluate this content: <system>example</system>' :
+        value
+    );
+
+    const result = loadPrompt( 'test', {
+      content: '<system>example</system>'
+    } );
+
+    expect( decode ).toHaveBeenCalledWith( 'Evaluate this content: &lt;system&gt;example&lt;/system&gt;' );
+    expect( result.messages ).toEqual( [
+      {
+        role: 'user',
+        content: 'Evaluate this content: <system>example</system>'
+      }
+    ] );
+  } );
+
+  it( 'decodes XML-escaped instructions returned by the parser', () => {
+    loadContent.mockReturnValue( {
+      content: 'Create a poster with this text: {{ copy }}',
+      dir: '/mock/dir'
+    } );
+    parsePrompt.mockReturnValue( {
+      config: {
+        provider: 'openai',
+        model: 'gpt-image-1'
+      },
+      messages: [],
+      instructions: 'Create a poster with this text: R&amp;D &lt; Speed &gt; &quot;Limits&quot;'
+    } );
+    decode.mockImplementation( value =>
+      value === 'Create a poster with this text: R&amp;D &lt; Speed &gt; &quot;Limits&quot;' ?
+        'Create a poster with this text: R&D < Speed > "Limits"' :
+        value
+    );
+
+    const result = loadPrompt( 'image_prompt', {
+      copy: 'R&D < Speed > "Limits"'
+    } );
+
+    expect( decode ).toHaveBeenCalledWith( 'Create a poster with this text: R&amp;D &lt; Speed &gt; &quot;Limits&quot;' );
+    expect( result.messages ).toEqual( [] );
+    expect( result.instructions ).toBe( 'Create a poster with this text: R&D < Speed > "Limits"' );
+  } );
+
+  it( 'decodes XML-escaped config values recursively', () => {
+    const encodedConfig = {
+      label: 'R&amp;D',
+      values: [ 'A &lt; B' ],
+      providerOptions: {
+        metadata: {
+          title: '&quot;Race&quot;'
+        }
+      }
+    };
+
+    loadContent.mockReturnValue( {
+      content: '<user>Hello</user>',
+      dir: '/mock/dir'
+    } );
+    parsePrompt.mockReturnValue( {
+      config: encodedConfig,
+      messages: [
+        {
+          role: 'user',
+          content: 'Hello'
+        }
+      ],
+      instructions: null
+    } );
+    decode.mockImplementation( value => {
+      if ( value === encodedConfig ) {
+        return {
+          label: 'R&D',
+          values: [ 'A < B' ],
+          providerOptions: {
+            metadata: {
+              title: '"Race"'
+            }
+          }
+        };
+      }
+      return value;
+    } );
+
+    const result = loadPrompt( 'test' );
+
+    expect( result.config ).toEqual( {
+      label: 'R&D',
+      values: [ 'A < B' ],
+      providerOptions: {
+        metadata: {
+          title: '"Race"'
+        }
+      }
+    } );
+  } );
+
+  it( 'throws error when prompt file not found', () => {
+    loadContent.mockReturnValue( null );
+
+    expect( () => {
+      loadPrompt( 'nonexistent' );
+    } ).toThrow( /Prompt "nonexistent" not found/ );
+  } );
+
+} );

package/src/{prompt_loader_validation.spec.js → prompt/loader_validation.spec.js}

@@ -1,11 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { loadPrompt } from './prompt_loader.js';
+import { loadPrompt } from './loader.js';
 
 vi.mock( './load_content.js', () => ( {
-  loadContentWithDir: vi.fn()
+  loadContent: vi.fn()
 } ) );
 
-import { loadContentWithDir } from './load_content.js';
+import { loadContent } from './load_content.js';
 
 describe( 'loadPrompt - validation with real schema', () => {
   beforeEach( () => {
@@ -26,7 +26,7 @@ providerOptions:
 
 <user>Hello</user>`;
 
-    loadContentWithDir.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
+    loadContent.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
 
     const result = loadPrompt( 'test', {} );
 
@@ -35,6 +35,39 @@ providerOptions:
     expect( result.config.providerOptions.thinking.budgetTokens ).toBe( 1500 );
   } );
 
+  it( 'should accept a plain-instructions prompt without message blocks', () => {
+    const promptContent = `---
+provider: openai
+model: gpt-image-1
+size: 1024x1024
+---
+
+Create a {{ style }} NASCAR image.
+
+Scene:
+{{ scene }}`;
+
+    loadContent.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
+
+    const result = loadPrompt( 'image_prompt', {
+      scene: 'Three cars racing side-by-side through a banked turn',
+      style: 'cinematic'
+    } );
+
+    expect( result.messages ).toEqual( [] );
+    expect( result.instructions ).toBe(
+      `Create a cinematic NASCAR image.
+
+Scene:
+Three cars racing side-by-side through a banked turn`
+    );
+    expect( result.config ).toEqual( {
+      provider: 'openai',
+      model: 'gpt-image-1',
+      size: '1024x1024'
+    } );
+  } );
+
   it( 'should accept snake_case max_tokens via config passthrough (no longer strict)', () => {
     const promptContent = `---
 provider: anthropic
@@ -44,7 +77,7 @@ max_tokens: 64000
 
 <user>Hello</user>`;
 
-    loadContentWithDir.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
+    loadContent.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
 
     // Config uses passthrough, so max_tokens is accepted (though ignored by SDK)
     expect( () => {
@@ -64,7 +97,7 @@ options:
 
 <user>Hello</user>`;
 
-    loadContentWithDir.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
+    loadContent.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
 
     // Config uses passthrough, so 'options' passes through (though not used)
     expect( () => {
@@ -84,7 +117,7 @@ providerOptions:
 
 <user>Hello</user>`;
 
-    loadContentWithDir.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
+    loadContent.mockReturnValue( { content: promptContent, dir: '/mock/dir' } );
 
     // budget_tokens is silently stripped from thinking (unknown field), not rejected
     expect( () => {

package/src/prompt/parser.js

@@ -0,0 +1,19 @@
+import matter from 'gray-matter';
+import { FatalError } from '@outputai/core';
+
+export function parsePrompt( { name, raw } ) {
+  const { data: config, content } = matter( raw );
+
+  if ( !content || content.trim() === '' ) {
+    throw new FatalError( `Prompt "${name}" 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() } )
+  );
+
+  const instructions = messages.length === 0 ? content.trim() : null;
+
+  return { config, messages, instructions };
+}