@outputai/llm 0.11.0 → 0.11.1-next.2223fa5.0

package/src/prompt/content.js

@@ -0,0 +1,70 @@
+import { Role } from '../consts.js';
+import { decode } from './interpolations.js';
+import { FatalError } from '@outputai/core';
+import { parseMarkup } from './markup/nodes.js';
+
+/** Merge two objects 2-level deep. */
+const mergeOptions = ( base = {}, extra = {} ) => {
+  const merged = { ...base };
+  for ( const [ namespace, options ] of Object.entries( extra ) ) {
+    merged[namespace] = { ...merged[namespace], ...options };
+  }
+  return merged;
+};
+
+/** Gets the options attribute from the message attributes */
+const extractOptions = attributes => {
+  const { options, ...unsupportedAttributes } = attributes;
+  if ( Object.keys( unsupportedAttributes ).length > 0 ) {
+    throw new FatalError( 'Message has unsupported attributes. The only supported attribute is "options".' );
+  }
+  if ( options === true ) {
+    throw new FatalError( 'Message "options" attribute must have a value.' );
+  }
+  const rawOptions = options?.trim();
+  return rawOptions ? rawOptions.split( /\s+/ ) : null;
+};
+
+/** Merge down messageOptions selected from a list */
+const resolveProviderOptions = ( options, messageOptions ) =>
+  options.reduce( ( result, option ) => {
+    if ( !messageOptions[option] ) {
+      throw new FatalError( `Message "options" attribute references unknown option "${option}" in \`config.messageOptions\`.` );
+    }
+    return mergeOptions( result, messageOptions[option] );
+  }, {} );
+
+const promptRoleSet = new Set( [ Role.SYSTEM, Role.USER, Role.ASSISTANT ] );
+
+/**
+ * Extract messages or instructions from prompt content. A leading role tag yields
+ * messages and null instructions; otherwise instructions are the decoded body.
+ */
+export const parseContent = ( content, messageOptions ) => {
+  const nodes = parseMarkup( content );
+
+  if ( nodes.length === 0 ) {
+    return { messages: [], instructions: decode( content.trim() ) };
+  }
+
+  const invalidRole = nodes.find( node => !promptRoleSet.has( node.tagName ) );
+  if ( invalidRole ) {
+    throw new FatalError( `Message has invalid role "${invalidRole.tagName}".` );
+  }
+
+  return {
+    messages: nodes.map( node => {
+      const options = extractOptions( node.attributes );
+      if ( options && Object.keys( messageOptions ?? {} ).length === 0 ) {
+        throw new FatalError( 'Message has "options" attribute but `config.messageOptions` is empty.' );
+      }
+      const providerOptions = options ? resolveProviderOptions( options, messageOptions ) : null;
+      return {
+        role: node.tagName.toLowerCase(),
+        content: decode( node.content.trim() ),
+        ...( providerOptions && { providerOptions } )
+      };
+    } ),
+    instructions: null
+  };
+};

package/src/prompt/content.spec.js

@@ -0,0 +1,208 @@
+import { describe, it, expect } from 'vitest';
+import { FatalError } from '@outputai/core';
+import { Role } from '../consts.js';
+import { parseContent } from './content.js';
+
+const cached = { anthropic: { cacheControl: { type: 'ephemeral' } } };
+const cachedLong = { anthropic: { cacheControl: { type: 'ephemeral', ttl: '1h' } } };
+const thinking = { anthropic: { thinking: { type: 'enabled' } } };
+const openaiKey = { openai: { promptCacheKey: 'enrich-v1' } };
+
+describe( 'parseContent', () => {
+  describe( 'messages and instructions', () => {
+    it( 'returns messages and null instructions when role tags are present', () => {
+      expect( parseContent( '<system>Hi</system>\n<user>Yo</user>' ) ).toEqual( {
+        messages: [
+          { role: Role.SYSTEM, content: 'Hi' },
+          { role: Role.USER, content: 'Yo' }
+        ],
+        instructions: null
+      } );
+    } );
+
+    it( 'treats content that starts with text as instructions', () => {
+      expect( parseContent( 'Note\n<user>Yo</user>\nTail' ) ).toEqual( {
+        messages: [],
+        instructions: 'Note\n<user>Yo</user>\nTail'
+      } );
+    } );
+
+    it( 'returns instructions and no messages when there are no role tags', () => {
+      expect( parseContent( 'Generate a cinematic poster.' ) ).toEqual( {
+        messages: [],
+        instructions: 'Generate a cinematic poster.'
+      } );
+    } );
+
+    it( 'trims instructions', () => {
+      expect( parseContent( '  poster  ' ).instructions ).toBe( 'poster' );
+    } );
+
+    it( 'extracts every authored prompt role', () => {
+      const roles = [ Role.SYSTEM, Role.USER, Role.ASSISTANT ];
+      const body = roles.map( role => `<${role}>${role} body</${role}>` ).join( '\n' );
+
+      expect( parseContent( body ).messages.map( message => message.role ) ).toEqual( roles );
+    } );
+
+    it( 'omits providerOptions when the tag has no options attribute', () => {
+      expect( parseContent( '<user>Hi</user>' ).messages[0] ).toEqual( { role: Role.USER, content: 'Hi' } );
+    } );
+
+    it( 'trims each message body', () => {
+      expect( parseContent( '<user>\n  Hello  \n</user>' ).messages[0].content ).toBe( 'Hello' );
+    } );
+
+    it( 'decodes XML entities in message content', () => {
+      expect( parseContent( '<user>R&amp;D &lt; Speed</user>' ).messages[0].content ).toBe( 'R&D < Speed' );
+    } );
+
+    it( 'keeps a different nested role tag inside the top-level message', () => {
+      const body = [
+        '<user>',
+        'Here:',
+        '```',
+        '<system>sys</system>',
+        '```',
+        '</user>'
+      ].join( '\n' );
+
+      expect( parseContent( body ) ).toEqual( {
+        messages: [ {
+          role: Role.USER,
+          content: 'Here:\n```\n<system>sys</system>\n```'
+        } ],
+        instructions: null
+      } );
+    } );
+
+    it( 'rejects a nested tag with the same role', () => {
+      expect( () => parseContent( '<user>ass<user>asasas</user></user>' ) )
+        .toThrow( 'Invalid child tag: <user> cannot appear inside another <user>. Escape it as "&lt;user&gt;".' );
+    } );
+
+    it( 'rejects an invalid top-level role', () => {
+      expect( () => parseContent( '<div><user>Hi</user></div>' ) )
+        .toThrow( 'Message has invalid role "div".' );
+      expect( () => parseContent( '<tool>Search result</tool>' ) )
+        .toThrow( 'Message has invalid role "tool".' );
+    } );
+
+    it( 'keeps closed inner markup in the message body', () => {
+      expect( parseContent( '<user>Compare <div></div> and <span></span> tags</user>' ).messages[0].content )
+        .toBe( 'Compare <div></div> and <span></span> tags' );
+    } );
+  } );
+
+  describe( 'options attribute', () => {
+    it( 'resolves a referenced messageOptions set into providerOptions', () => {
+      expect( parseContent( '<system options="cached">Docs</system>\n<user>Hello</user>', { cached } ) ).toEqual( {
+        messages: [
+          { role: Role.SYSTEM, content: 'Docs', providerOptions: cached },
+          { role: Role.USER, content: 'Hello' }
+        ],
+        instructions: null
+      } );
+    } );
+
+    it( 'does not put attributes on the message', () => {
+      const [ system ] = parseContent( '<system options="cached">Docs</system>', { cached } ).messages;
+      expect( system ).not.toHaveProperty( 'attributes' );
+    } );
+
+    it( 'lowercases the options attribute name', () => {
+      const [ system ] = parseContent( '<system OPTIONS="cached">Docs</system>', { cached } ).messages;
+      expect( system.providerOptions ).toEqual( cached );
+    } );
+
+    it( 'splits multiple set names on whitespace', () => {
+      const [ system ] = parseContent(
+        '<system options="cached openaiKey">Docs</system>',
+        { cached: cachedLong, openaiKey }
+      ).messages;
+
+      expect( system.providerOptions ).toEqual( { ...cachedLong, ...openaiKey } );
+    } );
+
+    it( 'trims extra whitespace around set names', () => {
+      const [ system ] = parseContent( '<system options="  cached  ">Docs</system>', { cached } ).messages;
+      expect( system.providerOptions ).toEqual( cached );
+    } );
+
+    it( 'treats blank or whitespace-only options as no options', () => {
+      expect( parseContent( '<system options="  ">Docs</system>' ).messages ).toEqual( [
+        { role: Role.SYSTEM, content: 'Docs' }
+      ] );
+      expect( parseContent( '<system options="">Docs</system>' ).messages ).toEqual( [
+        { role: Role.SYSTEM, content: 'Docs' }
+      ] );
+    } );
+
+    it( 'throws when options has no value', () => {
+      expect( () => parseContent( '<system options>Docs</system>' ) )
+        .toThrow( new FatalError( 'Message "options" attribute must have a value.' ) );
+    } );
+
+    it( 'merges keys from two sets that share a provider namespace', () => {
+      const [ system ] = parseContent(
+        '<system options="cached thinking">Docs</system>',
+        { cached, thinking }
+      ).messages;
+
+      expect( system.providerOptions ).toEqual( {
+        anthropic: {
+          cacheControl: { type: 'ephemeral' },
+          thinking: { type: 'enabled' }
+        }
+      } );
+    } );
+
+    it( 'lets a later set win on overlapping keys in the same namespace', () => {
+      const [ system ] = parseContent(
+        '<system options="short long">Docs</system>',
+        { short: cached, long: cachedLong }
+      ).messages;
+
+      expect( system.providerOptions ).toEqual( cachedLong );
+    } );
+
+    it( 'replaces nested objects instead of deep-merging them', () => {
+      const [ system ] = parseContent(
+        '<system options="withTtl noTtl">Docs</system>',
+        { withTtl: cachedLong, noTtl: cached }
+      ).messages;
+
+      expect( system.providerOptions.anthropic.cacheControl ).toEqual( { type: 'ephemeral' } );
+    } );
+
+    it( 'applies the same set twice without changing the result', () => {
+      const once = parseContent( '<system options="cached">Docs</system>', { cached } );
+      const twice = parseContent( '<system options="cached cached">Docs</system>', { cached } );
+
+      expect( twice.messages[0].providerOptions ).toEqual( once.messages[0].providerOptions );
+    } );
+
+    it( 'throws when the tag has an unsupported attribute', () => {
+      expect( () => parseContent( '<system options="cached" ttl="1h">Docs</system>', { cached } ) )
+        .toThrow( FatalError );
+      expect( () => parseContent( '<system pinned>Docs</system>' ) ).toThrow( /unsupported attributes/ );
+      expect( () => parseContent( '<user data="x">Hi</user>' ) ).toThrow( /unsupported attributes/ );
+    } );
+
+    it( 'throws when options is set but messageOptions is missing or empty', () => {
+      expect( () => parseContent( '<system options="cached">Docs</system>' ) )
+        .toThrow( /config.messageOptions/ );
+      expect( () => parseContent( '<system options="cached">Docs</system>', {} ) )
+        .toThrow( /config.messageOptions/ );
+    } );
+
+    it( 'throws when a set name is not in messageOptions', () => {
+      expect( () => parseContent( '<user options="missing">Hello</user>', { cached } ) )
+        .toThrow( /unknown option "missing"/ );
+    } );
+
+    it( 'does not throw on missing messageOptions when no tag uses options', () => {
+      expect( () => parseContent( '<user>Hello</user>' ) ).not.toThrow();
+    } );
+  } );
+} );

package/src/prompt/{escape.js → interpolations.js}

@@ -1,20 +1,14 @@
-import { encodeXML, decodeXML } from 'entities';
 import { Objects } from '@outputai/core/sdk/helpers';
+import { encodeXML, decodeXML } from 'entities';
 
-const VAR_SAFE_FILTER = '__var_safe';
+export const interpolationFilterToken = '__var_safe';
 
 /**
  * XML-escapes a value.
  * @param {unknown} value - Any value to escape
  * @returns {string} Escaped value or '' if original value was null/undefined
  */
-export const encodeFilter = value => [ null, undefined ].includes( value ) ? '' : encodeXML( String( value ) );
-
-/**
- * Sets up the encoder filter on a Liquid instance.
- * @param {object} liquid - LiquidJS instance
- */
-export const setupLiquidEncodeFilter = liquid => liquid.registerFilter( VAR_SAFE_FILTER, encodeFilter );
+export const encode = value => [ null, undefined ].includes( value ) ? '' : encodeXML( String( value ) );
 
 /**
  * Matches {% raw %}...{% endraw %} or {{ ... }} tags
@@ -22,10 +16,9 @@ export const setupLiquidEncodeFilter = liquid => liquid.registerFilter( VAR_SAFE
 const VAR_OR_RAW = /(\{%\s*raw\s*%\}[\s\S]*?\{%\s*endraw\s*%\})|\{\{\s*([\s\S]+?)\s*\}\}/g;
 
 /**
- * Escapes Liquid templates so rendered variable content cannot be parsed as message blocks.
+ * Appends `| __var_safe` filter to every `{{ ... }}` expression.
  *
- * Appends `| __var_safe` to every `{{ ... }}` expression so variable output is XML-escaped
- * by the filter registered on Liquid before parsePrompt tokenizes message blocks.
+ * The filter XML-escape the interpolated content so it cannot be parsed as new message blocks.
  *
  * Without this, a variable whose value contains `<system>` or `</user>` would inject extra
  * message blocks.
@@ -36,16 +29,16 @@ const VAR_OR_RAW = /(\{%\s*raw\s*%\}[\s\S]*?\{%\s*endraw\s*%\})|\{\{\s*([\s\S]+?
  * Note: The `g` flag advances past any matched raw regions, so `{{ ... }}` inside them are
  * preserved as well.
  *
- * @param {string} raw - Raw string value
- * @returns {string} Escaped string
+ * @param {string} raw - Raw template string
+ * @returns {string} Template with `| __var_safe` appended to each interpolation
  */
-export const escape = raw =>
+export const pipeInterpolations = raw =>
   raw.replace( VAR_OR_RAW, ( _, rawRegion, expressionContent ) =>
-    rawRegion === undefined ? `{{ ${expressionContent.trim()} | ${VAR_SAFE_FILTER} }}` : rawRegion
+    rawRegion === undefined ? `{{ ${expressionContent.trim()} | ${interpolationFilterToken} }}` : rawRegion
   );
 
 /**
- * Recursively XML-decodes a value.
+ * Recursive decode a XML-encoded value.
  * @param {unknown} value - Value to decode
  * @returns {unknown} Decoded value
  */
@@ -58,7 +51,7 @@ export const decode = value => {
   }
   if ( Objects.isPlainObject( value ) ) {
     return Object.fromEntries(
-      Object.entries( value ).map( ( [ k, v ] ) => [ k, decode( v ) ] )
+      Object.entries( value ).map( ( [ key, item ] ) => [ key, decode( item ) ] )
     );
   }
   return value;

package/src/prompt/interpolations.spec.js

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import { decode, encode, interpolationFilterToken, pipeInterpolations } from './interpolations.js';
+
+describe( 'encode', () => {
+  it( 'encodes XML special characters', () => {
+    expect( encode( '<a & b>' ) ).toBe( '&lt;a &amp; b&gt;' );
+  } );
+
+  it( 'encodes a tag-shaped substring so extractMessages cannot match it', () => {
+    expect( encode( '<system>x</system>' ) ).toBe( '&lt;system&gt;x&lt;/system&gt;' );
+  } );
+
+  it( 'returns an empty string for null and undefined', () => {
+    expect( encode( null ) ).toBe( '' );
+    expect( encode( undefined ) ).toBe( '' );
+  } );
+
+  it( 'coerces numbers and booleans to string', () => {
+    expect( encode( 42 ) ).toBe( '42' );
+    expect( encode( true ) ).toBe( 'true' );
+  } );
+
+  it( 'passes empty and plain strings through unchanged', () => {
+    expect( encode( '' ) ).toBe( '' );
+    expect( encode( 'hello world' ) ).toBe( 'hello world' );
+  } );
+} );
+
+describe( 'pipeInterpolations', () => {
+  const piped = expr => `{{ ${expr} | ${interpolationFilterToken} }}`;
+
+  it( 'appends the safety filter to a single interpolation', () => {
+    expect( pipeInterpolations( '{{ name }}' ) ).toBe( piped( 'name' ) );
+  } );
+
+  it( 'appends the safety filter to every interpolation', () => {
+    expect( pipeInterpolations( '{{ a }} and {{ b }}' ) ).toBe(
+      `${piped( 'a' )} and ${piped( 'b' )}`
+    );
+  } );
+
+  it( 'appends the safety filter last in an existing filter chain', () => {
+    expect( pipeInterpolations( '{{ x | upcase }}' ) ).toBe( piped( 'x | upcase' ) );
+    expect( pipeInterpolations( '{{ x | a | b }}' ) ).toBe( piped( 'x | a | b' ) );
+  } );
+
+  it( 'handles dotted property paths', () => {
+    expect( pipeInterpolations( '{{ obj.field }}' ) ).toBe( piped( 'obj.field' ) );
+  } );
+
+  it( 'preserves a {% raw %} block even when it contains {{ ... }}', () => {
+    const input = '{% raw %}{{ literal }}{% endraw %}';
+    expect( pipeInterpolations( input ) ).toBe( input );
+  } );
+
+  it( 'rewrites interpolations outside a raw block while preserving the raw block', () => {
+    expect( pipeInterpolations( '{{ a }}{% raw %}{{ b }}{% endraw %}{{ c }}' ) ).toBe(
+      `${piped( 'a' )}{% raw %}{{ b }}{% endraw %}${piped( 'c' )}`
+    );
+  } );
+
+  it( 'leaves control tags untouched and still pipes interpolations inside them', () => {
+    expect( pipeInterpolations( '{% if cond %}{{ x }}{% endif %}' ) ).toBe(
+      `{% if cond %}${piped( 'x' )}{% endif %}`
+    );
+    expect( pipeInterpolations( '{% for x in xs %}{{ x }}{% endfor %}' ) ).toBe(
+      `{% for x in xs %}${piped( 'x' )}{% endfor %}`
+    );
+  } );
+
+  it( 'normalizes interior whitespace', () => {
+    expect( pipeInterpolations( '{{x}}' ) ).toBe( piped( 'x' ) );
+    expect( pipeInterpolations( '{{   x   }}' ) ).toBe( piped( 'x' ) );
+  } );
+
+  it( 'returns the input unchanged when there are no interpolations', () => {
+    expect( pipeInterpolations( '<user>plain text</user>' ) ).toBe( '<user>plain text</user>' );
+    expect( pipeInterpolations( '' ) ).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 );
+  } );
+} );