@outputai/llm 0.11.1-next.da26845.0 → 0.12.0

package/src/validations.spec.js

@@ -1,631 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { ValidationError } from '@outputai/core';
-import {
-  parseGenerateTextArgs,
-  parseGenerateTextWithStreamingArgs,
-  parseStreamTextArgs,
-  parseGenerateImageArgs,
-  parseAgentArgs,
-  parseAgentGenerateArgs,
-  parseAgentGenerateWithStreamingArgs,
-  parseAgentStreamArgs
-} from './validations.js';
-
-const makeOutput = () => ( { name: 'object' } );
-
-const searchTool = { description: 'Search' };
-const stopWhen = () => false;
-const promptObject = {
-  name: 'custom',
-  config: {
-    provider: 'openai',
-    model: 'gpt-4o',
-    maxSteps: 10,
-    skills: []
-  },
-  messages: [ { role: 'user', content: 'Hello' } ],
-  instructions: null,
-  fileDir: '/prompts',
-  variables: {}
-};
-
-describe( 'prompt arguments', () => {
-  it.each( [
-    [ 'generateText', parseGenerateTextArgs ],
-    [ 'generateTextWithStreaming', parseGenerateTextWithStreamingArgs ],
-    [ 'streamText', parseStreamTextArgs ],
-    [ 'generateImage', parseGenerateImageArgs ],
-    [ 'Agent', parseAgentArgs ]
-  ] )( 'normalizes a prompt object for %s', ( _, parse ) => {
-    expect( parse( { prompt: promptObject } ) ).toEqual( {
-      promptObject
-    } );
-  } );
-
-  it.each( [ 'promptDir', 'variables' ] )( 'rejects %s with a prompt object', field => {
-    expect( () => parseGenerateTextArgs( {
-      prompt: promptObject,
-      [field]: field === 'promptDir' ? '/other' : { topic: 'other' }
-    } ) ).toThrow( `${field} cannot be used when prompt is an object` );
-  } );
-
-  it( 'rejects prompt file arguments with an Agent prompt object', () => {
-    expect( () => parseAgentArgs( {
-      prompt: promptObject,
-      promptDir: '/other'
-    } ) ).toThrow( 'promptDir cannot be used when prompt is an object' );
-  } );
-
-  it( 'reports specific validation issues for an invalid prompt object', () => {
-    expect( () => parseGenerateTextArgs( {
-      prompt: {
-        ...promptObject,
-        config: {
-          provider: 'openai'
-        }
-      }
-    } ) ).toThrow( /prompt\.config\.model/ );
-  } );
-
-  it.each( [
-    [ 'missing', {} ],
-    [ 'numeric', { prompt: 123, variables: { topic: 'testing' } } ]
-  ] )( 'keeps filename-shaped errors for a %s prompt', ( _, args ) => {
-    const error = { message: '' };
-    try {
-      parseGenerateTextArgs( args );
-    } catch ( e ) {
-      error.message = e.message;
-    }
-
-    expect( error.message ).toContain( 'expected string' );
-    expect( error.message ).not.toContain( 'variables cannot be used when prompt is an object' );
-  } );
-} );
-
-describe( 'parseGenerateTextArgs', () => {
-  it( 'renames prompt to promptFile and keeps allowlisted leftovers', () => {
-    const abortSignal = AbortSignal.abort();
-    const tools = { search: searchTool };
-    const output = makeOutput();
-
-    expect( parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      variables: { topic: 'testing', count: 2, draft: false },
-      promptDir: '/prompts',
-      tools,
-      output,
-      toolChoice: { type: 'tool', toolName: 'search' },
-      stopWhen,
-      abortSignal
-    } ) ).toEqual( {
-      promptFile: 'summary@v1',
-      variables: { topic: 'testing', count: 2, draft: false },
-      promptDir: '/prompts',
-      tools,
-      output,
-      toolChoice: { type: 'tool', toolName: 'search' },
-      stopWhen,
-      abortSignal
-    } );
-  } );
-
-  it( 'accepts an array of stopWhen functions', () => {
-    const parsed = parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      stopWhen: [ stopWhen ]
-    } );
-
-    expect( parsed.stopWhen ).toEqual( [ stopWhen ] );
-  } );
-
-  it( 'throws ValidationError with generateText prefix for invalid args', () => {
-    expect( () => parseGenerateTextArgs( {
-      variables: { topic: 'testing' }
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 123
-    } ) ).toThrow( /Invalid generateText\(\) arguments/ );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      promptDir: ''
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      abortSignal: {}
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'does not keep prompt-owned call arguments on the parsed result', () => {
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      skills: [ { name: 'style', description: 'Style', instructions: '# Style' } ]
-    } ) ).toThrow( /skills must be set in the prompt file/ );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      maxSteps: 4,
-      skills: [ './writer.md' ]
-    } ) ).toThrow( /must be set in the prompt file/ );
-  } );
-
-  it( 'throws ValidationError for unrecognized call arguments', () => {
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      temperature: 0.2
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      maxRetries: 2
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      onChunk: () => {}
-    } ) ).toThrow( /unrecognized key/i );
-  } );
-
-  it( 'accepts nested objects and arrays as variables', () => {
-    const variables = {
-      company: { name: 'Acme', industries: [ 'SaaS', 'AI' ] },
-      criteria: [ { name: 'Accuracy', required: true } ]
-    };
-
-    expect( parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      variables
-    } ).variables ).toEqual( variables );
-  } );
-
-  it( 'throws ValidationError for invalid allowlisted field shapes', () => {
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      variables: [ 'not a record' ]
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      tools: { search: true }
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      output: true
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      stopWhen: { type: 'custom-stop' }
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      toolChoice: 'maybe'
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'accepts opaque tools and output objects', () => {
-    expect( parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      tools: { search: { description: 'Search' } },
-      output: { type: 'object' }
-    } ) ).toMatchObject( {
-      tools: { search: { description: 'Search' } },
-      output: { type: 'object' }
-    } );
-  } );
-
-  it( 'preserves class-based tool and output identities', () => {
-    class TestTool {
-      #result = 'searched';
-
-      execute() {
-        return this.#result;
-      }
-    }
-
-    class TestOutput {
-      #result = 'parsed';
-
-      parseCompleteOutput() {
-        return this.#result;
-      }
-    }
-
-    const tool = new TestTool();
-    const output = new TestOutput();
-    const parsed = parseGenerateTextArgs( {
-      prompt: 'summary@v1',
-      tools: { search: tool },
-      output
-    } );
-
-    expect( parsed.tools.search ).toBe( tool );
-    expect( parsed.tools.search.execute() ).toBe( 'searched' );
-    expect( parsed.output ).toBe( output );
-    expect( parsed.output.parseCompleteOutput() ).toBe( 'parsed' );
-  } );
-} );
-
-describe( 'parseStreamTextArgs', () => {
-  it( 'keeps stream callbacks on the parsed result', () => {
-    const parsed = parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      variables: { topic: 'testing' },
-      promptDir: '/prompts',
-      onEnd: () => {},
-      onError: () => {},
-      onChunk: () => {}
-    } );
-
-    expect( parsed.promptFile ).toBe( 'summary@v1' );
-    expect( parsed.variables ).toEqual( { topic: 'testing' } );
-    expect( parsed.promptDir ).toBe( '/prompts' );
-    expect( parsed.onEnd ).toBeTypeOf( 'function' );
-    expect( parsed.onError ).toBeTypeOf( 'function' );
-    expect( parsed.onChunk ).toBeTypeOf( 'function' );
-  } );
-
-  it( 'throws ValidationError with streamText prefix for invalid args', () => {
-    expect( () => parseStreamTextArgs( {} ) ).toThrow( ValidationError );
-    expect( () => parseStreamTextArgs( { prompt: null } ) ).toThrow( /Invalid streamText\(\) arguments/ );
-
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      promptDir: ''
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'throws ValidationError for invalid callbacks', () => {
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      onEnd: 'not a function'
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      onError: {}
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      onChunk: 'not a function'
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'throws ValidationError for unrecognized call arguments', () => {
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      temperature: 0.2
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      skills: [ { name: 'style', description: 'Style', instructions: '# Style' } ]
-    } ) ).toThrow( /skills must be set in the prompt file/ );
-
-    expect( () => parseStreamTextArgs( {
-      prompt: 'summary@v1',
-      maxSteps: 1.5
-    } ) ).toThrow( /maxSteps must be set in the prompt file/ );
-  } );
-} );
-
-describe( 'parseGenerateTextWithStreamingArgs', () => {
-  it( 'keeps onChunk and omits streamText-only callbacks', () => {
-    const parsed = parseGenerateTextWithStreamingArgs( {
-      prompt: 'summary@v1',
-      onChunk: () => {}
-    } );
-
-    expect( parsed.promptFile ).toBe( 'summary@v1' );
-    expect( parsed.onChunk ).toBeTypeOf( 'function' );
-
-    expect( () => parseGenerateTextWithStreamingArgs( {
-      prompt: 'summary@v1',
-      onEnd: () => {}
-    } ) ).toThrow( /unrecognized key/i );
-  } );
-
-  it( 'uses the generateTextWithStreaming error prefix', () => {
-    expect( () => parseGenerateTextWithStreamingArgs( {
-      prompt: 'summary@v1',
-      maxSteps: 0
-    } ) ).toThrow( /Invalid generateTextWithStreaming\(\) arguments[\s\S]*maxSteps must be set in the prompt file/ );
-  } );
-} );
-
-describe( 'parseGenerateImageArgs', () => {
-  it( 'renames prompt to promptFile and keeps allowlisted leftovers', () => {
-    const images = [ Buffer.from( 'image-bytes' ) ];
-    const mask = Buffer.from( 'mask-bytes' );
-    const abortSignal = AbortSignal.abort();
-
-    expect( parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      variables: { scene: 'race cars' },
-      promptDir: '/prompts',
-      images,
-      mask,
-      abortSignal
-    } ) ).toEqual( {
-      promptFile: 'image@v1',
-      variables: { scene: 'race cars' },
-      promptDir: '/prompts',
-      images,
-      mask,
-      abortSignal
-    } );
-  } );
-
-  it( 'accepts text-to-image args without images or mask', () => {
-    expect( parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      variables: { topic: 'race cars' },
-      promptDir: '/prompts'
-    } ) ).toEqual( {
-      promptFile: 'image@v1',
-      variables: { topic: 'race cars' },
-      promptDir: '/prompts'
-    } );
-  } );
-
-  it( 'accepts all supported image input shapes', () => {
-    const buffer = Buffer.from( 'image-bytes' );
-    const uint8Array = new Uint8Array( [ 1, 2, 3 ] );
-    const arrayBuffer = new ArrayBuffer( 3 );
-    const paddedBase64 = 'aW1hZ2UtYnl0ZXM=';
-    const unpaddedBase64 = 'aW1hZ2U';
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      images: [
-        buffer,
-        uint8Array,
-        arrayBuffer,
-        paddedBase64,
-        unpaddedBase64,
-        { data: buffer, mediaType: 'image/png' },
-        { data: uint8Array },
-        { data: arrayBuffer, mediaType: 'image/jpeg' },
-        { data: paddedBase64, mediaType: 'image/webp' }
-      ],
-      mask: { data: Buffer.from( 'mask-bytes' ), mediaType: 'image/png' }
-    } ) ).not.toThrow();
-  } );
-
-  it( 'throws ValidationError for invalid image args', () => {
-    expect( () => parseGenerateImageArgs( {
-      prompt: ''
-    } ) ).toThrow( /Invalid generateImage\(\) arguments/ );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      images: []
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      images: [ { data: null } ]
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      images: [ { data: 'aW1hZ2U=', mediaType: '' } ]
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'rejects image strings that are not raw base64 data', () => {
-    for ( const image of [
-      'https://example.com/image.png',
-      'data:image/png;base64,aW1hZ2U=',
-      'not base64',
-      'abcde'
-    ] ) {
-      expect( () => parseGenerateImageArgs( {
-        prompt: 'image@v1',
-        images: [ image ]
-      } ) ).toThrow( /Image strings must be raw base64 data/ );
-    }
-  } );
-
-  it( 'requires images when mask is provided', () => {
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      mask: Buffer.from( 'mask-bytes' )
-    } ) ).toThrow( /mask requires images/ );
-  } );
-
-  it( 'throws ValidationError for unrecognized or prompt-owned call arguments', () => {
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      size: '1024x1024',
-      n: 2
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      aspectRatio: '1:1'
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      providerOptions: { openai: { quality: 'high' } }
-    } ) ).toThrow( /unrecognized key/i );
-
-    expect( () => parseGenerateImageArgs( {
-      prompt: 'image@v1',
-      maxSteps: 4
-    } ) ).toThrow( /unrecognized key/i );
-  } );
-} );
-
-describe( 'parseAgentArgs', () => {
-  it( 'renames prompt to promptFile and keeps allowlisted leftovers', () => {
-    const tools = { search: searchTool };
-    const output = makeOutput();
-    const messageStore = { getMessages() {}, addMessages() {} };
-
-    const parsed = parseAgentArgs( {
-      prompt: 'summary@v1',
-      variables: { topic: 'testing' },
-      promptDir: '/prompts',
-      tools,
-      output,
-      stopWhen,
-      messageStore
-    } );
-
-    expect( parsed ).toEqual( {
-      promptFile: 'summary@v1',
-      variables: { topic: 'testing' },
-      promptDir: '/prompts',
-      tools,
-      output,
-      stopWhen,
-      messageStore
-    } );
-    expect( parsed.messageStore ).toBe( messageStore );
-  } );
-
-  it( 'preserves class-based message store identity', () => {
-    class TestMessageStore {
-      #messages = [];
-
-      getMessages() {
-        return this.#messages;
-      }
-
-      addMessages( messages ) {
-        this.#messages.push( ...messages );
-      }
-    }
-
-    const messageStore = new TestMessageStore();
-    const parsed = parseAgentArgs( {
-      prompt: 'summary@v1',
-      messageStore
-    } );
-    const message = { role: 'user', content: 'Hello' };
-
-    parsed.messageStore.addMessages( [ message ] );
-
-    expect( parsed.messageStore ).toBe( messageStore );
-    expect( parsed.messageStore.getMessages() ).toEqual( [ message ] );
-  } );
-
-  it( 'throws ValidationError with Agent prefix for invalid args', () => {
-    expect( () => parseAgentArgs( {} ) ).toThrow( ValidationError );
-    expect( () => parseAgentArgs( { prompt: '' } ) ).toThrow( /Invalid Agent\(\) arguments/ );
-
-    expect( () => parseAgentArgs( {
-      prompt: 'summary@v1',
-      promptDir: ''
-    } ) ).toThrow( ValidationError );
-  } );
-
-  it( 'does not keep prompt-owned call arguments on the parsed result', () => {
-    expect( () => parseAgentArgs( {
-      prompt: 'summary@v1',
-      skills: [ { name: 'style', description: 'Style', instructions: '# Style' } ]
-    } ) ).toThrow( /skills must be set in the prompt file/ );
-
-    expect( () => parseAgentArgs( {
-      prompt: 'summary@v1',
-      maxSteps: 4,
-      skills: [ './writer.md' ]
-    } ) ).toThrow( /must be set in the prompt file/ );
-  } );
-
-  it( 'throws ValidationError for unrecognized constructor arguments', () => {
-    expect( () => parseAgentArgs( {
-      prompt: 'summary@v1',
-      temperature: 0.2
-    } ) ).toThrow( /unrecognized key/i );
-  } );
-
-  it( 'throws ValidationError for an invalid message store', () => {
-    expect( () => parseAgentArgs( {
-      prompt: 'summary@v1',
-      messageStore: { getMessages() {} }
-    } ) ).toThrow( ValidationError );
-  } );
-} );
-
-describe( 'parseAgentGenerateArgs', () => {
-  it( 'defaults omitted args and messages to an empty list', () => {
-    expect( parseAgentGenerateArgs() ).toEqual( { messages: [] } );
-    expect( parseAgentGenerateArgs( undefined ) ).toEqual( { messages: [] } );
-    expect( parseAgentGenerateArgs( {} ) ).toEqual( { messages: [] } );
-  } );
-
-  it( 'keeps allowlisted generate options', () => {
-    const messages = [ { role: 'user', content: 'Hello' } ];
-    const abortSignal = AbortSignal.abort();
-
-    expect( parseAgentGenerateArgs( {
-      messages,
-      abortSignal,
-      toolChoice: 'required'
-    } ) ).toEqual( {
-      messages,
-      abortSignal,
-      toolChoice: 'required'
-    } );
-  } );
-
-  it( 'throws ValidationError for unrecognized or prompt-owned call arguments', () => {
-    expect( () => parseAgentGenerateArgs( { temperature: 0.2 } ) ).toThrow( /unrecognized key/i );
-    expect( () => parseAgentGenerateArgs( { onChunk: () => {} } ) ).toThrow( /unrecognized key/i );
-    expect( () => parseAgentGenerateArgs( { maxSteps: 4 } ) ).toThrow( /maxSteps must be set in the prompt file/ );
-  } );
-
-  it( 'throws ValidationError for invalid messages or toolChoice', () => {
-    expect( () => parseAgentGenerateArgs( {
-      messages: [ { content: 'Hello' } ]
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseAgentGenerateArgs( {
-      messages: [ { role: 'moderator', content: 'Hello' } ]
-    } ) ).toThrow( ValidationError );
-
-    expect( () => parseAgentGenerateArgs( {
-      toolChoice: { type: 'tool' }
-    } ) ).toThrow( ValidationError );
-  } );
-} );
-
-describe( 'parseAgentGenerateWithStreamingArgs', () => {
-  it( 'defaults omitted args and accepts onChunk', () => {
-    expect( parseAgentGenerateWithStreamingArgs() ).toEqual( { messages: [] } );
-
-    const parsed = parseAgentGenerateWithStreamingArgs( { onChunk: () => {} } );
-    expect( parsed.messages ).toEqual( [] );
-    expect( parsed.onChunk ).toBeTypeOf( 'function' );
-  } );
-
-  it( 'rejects stream-only callbacks', () => {
-    expect( () => parseAgentGenerateWithStreamingArgs( { onEnd: () => {} } ) ).toThrow( /unrecognized key/i );
-  } );
-} );
-
-describe( 'parseAgentStreamArgs', () => {
-  it( 'defaults omitted args and keeps stream callbacks', () => {
-    expect( parseAgentStreamArgs() ).toEqual( { messages: [] } );
-
-    const parsed = parseAgentStreamArgs( {
-      onEnd: () => {},
-      onError: () => {},
-      onChunk: () => {}
-    } );
-
-    expect( parsed.messages ).toEqual( [] );
-    expect( parsed.onEnd ).toBeTypeOf( 'function' );
-    expect( parsed.onError ).toBeTypeOf( 'function' );
-    expect( parsed.onChunk ).toBeTypeOf( 'function' );
-  } );
-} );