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

package/src/prompt/markup/tokens.js

@@ -0,0 +1,26 @@
+import { ValidationError } from '@outputai/core';
+import { extractAttributes } from './attributes.js';
+
+export const extractTag = v => {
+  const capture = v.match( /^<\/?\s*([\w-]+)(?:\s+(.+?))?\s*>$/ );
+  if ( !capture ) {
+    throw new ValidationError( `Could not parse tag "${v}".` );
+  }
+  const [ name, rawAttributes ] = capture.slice( 1, 3 );
+  if ( !name ) {
+    throw new ValidationError( `Could not parse tag "${v}".` );
+  }
+  return {
+    tagName: name.toLowerCase(),
+    attributes: rawAttributes ? extractAttributes( rawAttributes ) : {}
+  };
+};
+
+const hasClosing = v => /\/\s*>$/.test( v );
+const hasOpening = v => /^<[A-Za-z][\w-]*(?=\s|\/?>)[^<]*>$/.test( v );
+
+export const isOpeningTag = v => hasOpening( v ) && !hasClosing( v );
+export const isComment = v => v.startsWith( '<!--' ) && v.endsWith( '-->' ) && v.length >= 7 && !v.slice( 4, -3 ).includes( '-->' );
+export const isSelfClosingTag = v => hasOpening( v ) && hasClosing( v );
+export const isEmptyText = v => /^\s*$/.test( v );
+export const isClosingTag = v => /^<\/\s*[A-Za-z]+[\w-]*\s*>$/.test( v );

package/src/prompt/markup/tokens.spec.js

@@ -0,0 +1,250 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { extractAttributes } from './attributes.js';
+import {
+  extractTag,
+  isClosingTag,
+  isComment,
+  isEmptyText,
+  isOpeningTag,
+  isSelfClosingTag
+} from './tokens.js';
+
+vi.mock( './attributes.js', () => ( {
+  extractAttributes: vi.fn()
+} ) );
+
+describe( 'extractTag', () => {
+  beforeEach( () => {
+    vi.mocked( extractAttributes ).mockReset().mockReturnValue( {} );
+  } );
+
+  it( 'extracts and lowercases an opening tag name', () => {
+    expect( extractTag( '<User>' ) ).toEqual( {
+      tagName: 'user',
+      attributes: {}
+    } );
+    expect( extractAttributes ).not.toHaveBeenCalled();
+  } );
+
+  it( 'extracts a hyphenated tag name', () => {
+    expect( extractTag( '<CUSTOM-BLOCK>' ) ).toEqual( {
+      tagName: 'custom-block',
+      attributes: {}
+    } );
+  } );
+
+  it( 'extracts a closing tag name', () => {
+    expect( extractTag( '</User>' ) ).toEqual( {
+      tagName: 'user',
+      attributes: {}
+    } );
+  } );
+
+  it( 'supports whitespace inside closing tags', () => {
+    expect( extractTag( '</ User >' ) ).toEqual( {
+      tagName: 'user',
+      attributes: {}
+    } );
+    expect( extractAttributes ).not.toHaveBeenCalled();
+  } );
+
+  it( 'delegates raw opening-tag attributes', () => {
+    const attributes = { options: 'cached shared', pinned: true };
+    vi.mocked( extractAttributes ).mockReturnValue( attributes );
+
+    expect( extractTag( '<user options = "cached shared" pinned>' ) ).toEqual( {
+      tagName: 'user',
+      attributes
+    } );
+    expect( extractAttributes ).toHaveBeenCalledOnce();
+    expect( extractAttributes ).toHaveBeenCalledWith( 'options = "cached shared" pinned' );
+  } );
+
+  it( 'propagates attribute parsing errors', () => {
+    vi.mocked( extractAttributes ).mockImplementation( () => {
+      throw new Error( 'invalid attributes' );
+    } );
+
+    expect( () => extractTag( '<user color="red>' ) ).toThrow( 'invalid attributes' );
+  } );
+
+  it( 'throws a descriptive error for a malformed token', () => {
+    expect( () => extractTag( 'plain text' ) )
+      .toThrow( /^Could not parse tag "plain text"\.$/ );
+  } );
+} );
+
+describe( 'isOpeningTag', () => {
+  it.each( [
+    '<user>',
+    '<user >',
+    '<User options="cached">',
+    '<custom-block mode=fast>',
+    '<user\toptions=fast>',
+    '<user\noptions="cached shared">',
+    '<user condition="score > 10">',
+    '<user color=\'red>'
+  ] )( 'recognizes %s', token => {
+    expect( isOpeningTag( token ) ).toBe( true );
+  } );
+
+  it.each( [
+    '</user>',
+    '< user>',
+    '<>',
+    '<,>',
+    '<b,b>',
+    '<b, b>',
+    '<user,>',
+    '<user=admin>',
+    '<user.name>',
+    '<1user>',
+    '<_user>',
+    '<üser>',
+    '<user />',
+    '<user/>',
+    '<user options="cached" />',
+    '<user / >',
+    '<!-- note -->',
+    '<!DOCTYPE html>',
+    '<?xml version="1.0"?>',
+    '<user',
+    'user>',
+    '<user></user>',
+    '<user<other>>',
+    '<user condition="a < b">',
+    'plain text'
+  ] )( 'rejects %s', token => {
+    expect( isOpeningTag( token ) ).toBe( false );
+  } );
+} );
+
+describe( 'isClosingTag', () => {
+  it.each( [
+    '</user>',
+    '</User>',
+    '</custom-block>',
+    '</ user >',
+    '</user   >',
+    '</\tuser\t>',
+    '</\nuser\n>'
+  ] )( 'recognizes %s', token => {
+    expect( isClosingTag( token ) ).toBe( true );
+  } );
+
+  it.each( [
+    '<user>',
+    '<user />',
+    '<!-- note -->',
+    '</>',
+    '< /user>',
+    '</user',
+    '</user/>',
+    '</user / >',
+    '</user options=ignored>',
+    '</b,b>',
+    '</1user>',
+    '</_user>',
+    '</üser>',
+    '</user> suffix',
+    'prefix </user>',
+    '</user></system>',
+    '</user<system>>',
+    'plain text'
+  ] )( 'rejects %s', token => {
+    expect( isClosingTag( token ) ).toBe( false );
+  } );
+} );
+
+describe( 'isSelfClosingTag', () => {
+  it.each( [
+    '<user/>',
+    '<user />',
+    '<CUSTOM-BLOCK />',
+    '<image source="avatar.png" />',
+    '<user options = "cached shared" />',
+    '<user condition="score > 10"/>',
+    '<user\tmode=fast\t/>',
+    '<user\nmode=fast\n/>',
+    '<user / >',
+    '<user color=\'red />'
+  ] )( 'recognizes %s', token => {
+    expect( isSelfClosingTag( token ) ).toBe( true );
+  } );
+
+  it.each( [
+    '<user>',
+    '</user>',
+    '<!-- note -->',
+    '< user/>',
+    '<>',
+    '<,/>',
+    '<b,b/>',
+    '<user,/>',
+    '<1user/>',
+    '<_user/>',
+    '<üser/>',
+    '</user/>',
+    '<user/',
+    '<user/> suffix',
+    'prefix <user/>',
+    '<user/><system/>',
+    '<user<other>/>',
+    '<!DOCTYPE html />',
+    '<?xml version="1.0"?>',
+    '<user path="/tmp">',
+    '<user path="/" >',
+    'plain text'
+  ] )( 'rejects %s', token => {
+    expect( isSelfClosingTag( token ) ).toBe( false );
+  } );
+} );
+
+describe( 'isComment', () => {
+  it.each( [
+    '<!---->',
+    '<!-- -->',
+    '<!-- note -->',
+    '<!-- first\nsecond -->',
+    '<!-- <user>text</user> -->',
+    '<!-- a > b and c < d -->'
+  ] )( 'recognizes %s', token => {
+    expect( isComment( token ) ).toBe( true );
+  } );
+
+  it.each( [
+    '<!-->',
+    '<! -- note -->',
+    '<!-- unfinished',
+    '<!-- note -- >',
+    '<!-- note --!>',
+    'prefix <!-- note -->',
+    '<!-- note --> suffix',
+    '<user><!-- note --></user>',
+    '<!-- first --><!-- second -->',
+    '<!-- first -->\n<!-- second -->',
+    '<!-- -->text<!-- -->'
+  ] )( 'rejects %s', token => {
+    expect( isComment( token ) ).toBe( false );
+  } );
+} );
+
+describe( 'isEmptyText', () => {
+  it.each( [
+    '',
+    ' ',
+    '\t',
+    '\n\n',
+    ' \n\t '
+  ] )( 'recognizes whitespace-only text', token => {
+    expect( isEmptyText( token ) ).toBe( true );
+  } );
+
+  it.each( [
+    'text',
+    ' text ',
+    '<user>'
+  ] )( 'rejects non-whitespace text', token => {
+    expect( isEmptyText( token ) ).toBe( false );
+  } );
+} );

package/src/prompt/validations.js

@@ -1,95 +1,126 @@
 import { Logger, ValidationError, z } from '@outputai/core';
-import { attributesSchema } from './block_options.js';
+import { deprecatedProviderAliases } from '../deprecated_provider_aliases.js';
 
-const toolConfigSchema = z.record( z.string(), z.unknown() );
-const toolsConfigSchema = z.record( z.string(), toolConfigSchema );
+const log = Logger.createLogger( 'LLM' );
 
-// A provider-namespaced options object, e.g. { anthropic: { cacheControl: { type: 'ephemeral' } } }
-const providerOptionsSchema = z.record( z.string(), z.record( z.string(), z.unknown() ) );
+const handleDeprecatedKeys = prompt => {
+  const { config: { maxTokens, maxOutputTokens, provider } } = prompt;
+
+  // @TODO: maxTokens was replaced by maxOutputTokens in v0.12, it can be removed down the road
+  if ( Number.isFinite( maxTokens ) ) {
+    if ( Number.isFinite( maxOutputTokens ) ) {
+      log.warn( 'Prompt has both "maxOutputTokens" and deprecated "maxTokens" keys set, "maxTokens" value will be ignored.' );
+    } else {
+      log.warn( 'Prompt has deprecated key "maxTokens". Its value was set to "maxOutputTokens".' );
+      prompt.config.maxOutputTokens = maxTokens;
+    }
+  }
+
+  // @TODO: this handle aliases removal in v0.11, it can be removed down the road
+  if ( Object.hasOwn( deprecatedProviderAliases, provider ) ) {
+    const canonical = deprecatedProviderAliases[provider];
+    log.warn( `Prompt uses deprecated provider alias "${provider}". Use "${canonical}" instead.` );
+    prompt.config.provider = canonical;
+  }
+
+  return prompt;
+};
+
+const objectMapSchema = z.record(
+  z.string(),
+  z.record(
+    z.string(),
+    z.unknown()
+  )
+);
+
+const promptConfigSchema = z.object( {
+  aspectRatio: z.string().regex( /^\d+:\d+$/ ).optional(),
+  frequencyPenalty: z.number().optional(),
+  maxImagesPerCall: z.number().int().positive().optional(),
+  maxOutputTokens: z.number().int().positive().optional(),
+  maxSteps: z.number().int().positive().default( 10 ),
+  maxTokens: z.number().int().positive().optional(),
+  // A provider-namespaced options object, e.g. { anthropic: { cacheControl: { type: 'ephemeral' } } }
+  messageOptions: z.record( z.string(), objectMapSchema ).optional(),
+  model: z.string().min( 1 ),
+  n: z.number().int().positive().optional(),
+  presencePenalty: z.number().optional(),
+  provider: z.string().min( 1 ),
+  providerOptions: z.object( {
+    thinking: z.object( {
+      type: z.enum( [ 'enabled', 'disabled' ] ),
+      budgetTokens: z.number().optional()
+    } ).loose().optional()
+  } ).loose().optional(),
+  seed: z.number().int().optional(),
+  size: z.string().regex( /^\d+x\d+$/ ).optional(),
+  skills: z.preprocess( v => Array.isArray( v ) ? v : [].concat( v ?? [] ), z.array( z.string().min( 1 ) ) ),
+  stopSequences: z.array( z.string() ).optional(),
+  temperature: z.number().nonnegative().optional(),
+  topK: z.number().nonnegative().optional(),
+  topP: z.number().nonnegative().optional(),
+  tools: objectMapSchema.optional()
+} ).strict();
 
 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(),
-    n: z.number().int().positive().optional(),
-    maxImagesPerCall: z.number().int().positive().optional(),
-    size: z.string().regex( /^\d+x\d+$/ ).optional(),
-    aspectRatio: z.string().regex( /^\d+:\d+$/ ).optional(),
-    seed: z.number().int().optional(),
-    skills: z.union( [ z.string().min( 1 ), z.array( z.string().min( 1 ) ) ] ).optional(),
-    tools: toolsConfigSchema.optional(),
-    providerOptions: z.object( {
-      thinking: z.object( {
-        type: z.enum( [ 'enabled', 'disabled' ] ),
-        budgetTokens: z.number().optional()
-      } ).loose().optional()
-    } ).loose().optional(),
-    messageOptions: z.record( z.string(), providerOptionsSchema ).optional()
-  } ).loose(),
+  config: promptConfigSchema,
   messages: z.array(
     z.object( {
       role: z.string(),
       content: z.string(),
-      attributes: attributesSchema.optional()
+      providerOptions: objectMapSchema.optional()
     } ).strict()
   ),
-  instructions: z.string().trim().min( 1 ).nullable().optional()
+  instructions: z.string().trim().min( 1 ).nullable().default( null ),
+  fileDir: z.string(),
+  variables: z.record( z.string(), z.unknown() ).default( {} )
 } ).strict().superRefine( ( prompt, ctx ) => {
   const hasMessages = prompt.messages.length > 0;
   const hasInstructions = !!prompt.instructions;
+  const addIssue = message => ctx.addIssue( { code: 'custom', path: [ 'messages', 'instructions' ], message } );
+
   if ( !hasMessages && !hasInstructions ) {
-    ctx.addIssue( {
-      code: 'custom',
-      path: [ 'messages', 'instructions' ],
-      message: 'Prompt must include either message blocks or plain instructions.'
-    } );
-  }
-  if ( hasMessages && hasInstructions ) {
-    ctx.addIssue( {
-      code: 'custom',
-      path: [ 'messages', 'instructions' ],
-      message: 'Prompt cannot include both message blocks and plain instructions.'
-    } );
+    addIssue( 'Prompt must include either message blocks or plain instructions.' );
+  } else if ( hasMessages && hasInstructions ) {
+    addIssue( 'Prompt cannot include both message blocks and plain instructions.' );
   }
-} );
-
-const SNAKE_CASE_WARNINGS = {
-  max_tokens: 'maxTokens',
-  max_images_per_call: 'maxImagesPerCall',
-  aspect_ratio: 'aspectRatio',
-  budget_tokens: 'budgetTokens',
-  top_p: 'topP',
-  top_k: 'topK',
-  stop_sequences: 'stopSequences',
-  options: 'providerOptions'
-};
+} ).transform( handleDeprecatedKeys );
+
+const promptConfigKeys = new Set( Object.keys( promptConfigSchema.shape ) );
+
+/** Converts a string to camel case */
+const toCamelCase = value => value.replace( /_([a-z])/g, ( _, letter ) => letter.toUpperCase() );
 
-function warnSnakeCaseFields( config ) {
-  for ( const [ snake, camel ] of Object.entries( SNAKE_CASE_WARNINGS ) ) {
-    if ( Object.hasOwn( config, snake ) ) {
-      Logger.warn( `[output-llm] "${snake}" found in prompt config. Did you mean "${camel}"?`, { namespace: 'LLM' } );
+/** Appends camelCase suggestions to unrecognized top-level config keys written in snake_case. */
+const appendCamelCaseSuggestions = error => {
+  for ( const issue of error.issues ) {
+    if ( issue.code !== 'unrecognized_keys' || issue.path.length !== 1 || issue.path[0] !== 'config' ) {
+      continue;
+    }
+
+    const suggestions = issue.keys
+      .filter( key => key.includes( '_' ) )
+      .map( key => ( { key, camel: toCamelCase( key ) } ) )
+      .filter( ( { key, camel } ) => camel !== key && promptConfigKeys.has( camel ) )
+      .map( ( { key, camel } ) => `"${key}" is not valid; use "${camel}"` );
+
+    if ( suggestions.length > 0 ) {
+      issue.message = `${issue.message}. ${suggestions.join( '. ' )}`;
     }
   }
-  const thinking = config.providerOptions?.thinking;
-  if ( thinking && Object.hasOwn( thinking, 'budget_tokens' ) ) {
-    Logger.warn( '[output-llm] "budget_tokens" found in providerOptions.thinking. Did you mean "budgetTokens"?', { namespace: 'LLM' } );
-  }
-}
+};
 
-export function validatePrompt( prompt ) {
+export const parsePromptSchema = prompt => {
   const result = promptSchema.safeParse( prompt );
   if ( !result.success ) {
-    const promptIdentifier = prompt?.name ? `"${prompt.name}"` : '(unnamed)';
-    const errorMessage = z.prettifyError( result.error );
+    appendCamelCaseSuggestions( result.error );
 
     throw new ValidationError(
-      `Invalid prompt file ${promptIdentifier}: ${errorMessage}`,
+      `Invalid prompt file ${prompt.name}: ${z.prettifyError( result.error )}`,
       { cause: result.error }
     );
   }
-
-  warnSnakeCaseFields( result.data.config );
-}
+  return result.data;
+};