@output.ai/llm 0.2.13 → 0.3.0-dev.pr341-daa6878

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/llm",
-  "version": "0.2.13",
+  "version": "0.3.0-dev.pr341-daa6878",
   "description": "Framework abstraction to interact with LLM models",
   "type": "module",
   "main": "src/index.js",
@@ -9,12 +9,12 @@
     "./src"
   ],
   "dependencies": {
-    "@ai-sdk/anthropic": "2.0.28",
-    "@ai-sdk/azure": "2.0.53",
-    "@ai-sdk/google-vertex": "3.0.96",
-    "@ai-sdk/openai": "2.0.52",
-    "@output.ai/core": ">=0.0.1",
-    "ai": "5.0.52",
+    "@ai-sdk/anthropic": "3.0.43",
+    "@ai-sdk/azure": "3.0.29",
+    "@ai-sdk/google-vertex": "4.0.57",
+    "@ai-sdk/openai": "3.0.28",
+    "@output.ai/core": "^0.5.2",
+    "ai": "6.0.84",
     "gray-matter": "4.0.3",
     "liquidjs": "10.22.0"
   },

package/src/ai_model.js

@@ -3,7 +3,30 @@ import { azure } from '@ai-sdk/azure';
 import { vertex } from '@ai-sdk/google-vertex';
 import { openai } from '@ai-sdk/openai';
 
-const providers = { azure, anthropic, openai, vertex };
+const builtInProviders = { azure, anthropic, openai, vertex };
+const providers = { ...builtInProviders };
+
+/** @internal Resets providers to built-in state. For testing only. */
+export function _resetProviders() {
+  for ( const key of Object.keys( providers ) ) {
+    delete providers[key];
+  }
+  Object.assign( providers, builtInProviders );
+}
+
+export function registerProvider( name, providerFn ) {
+  if ( typeof name !== 'string' || name.length === 0 ) {
+    throw new Error( 'Provider name must be a non-empty string' );
+  }
+  if ( typeof providerFn !== 'function' ) {
+    throw new Error( `Provider "${name}" must be a function that creates a model` );
+  }
+  providers[name] = providerFn;
+}
+
+export function getRegisteredProviders() {
+  return Object.keys( providers );
+}
 
 export function loadModel( prompt ) {
   const config = prompt?.config;
@@ -56,7 +79,6 @@ export function loadTools( prompt ) {
     );
   }
 
-  // Return null if empty object
   if ( Object.keys( toolsConfig ).length === 0 ) {
     return null;
   }
@@ -71,7 +93,6 @@ export function loadTools( prompt ) {
     );
   }
 
-  // Check if provider has tools object
   if ( !provider.tools || typeof provider.tools !== 'object' ) {
     throw new Error(
       `Provider "${providerName}" does not support provider-specific tools.`
@@ -81,11 +102,9 @@ export function loadTools( prompt ) {
   const tools = {};
 
   for ( const [ toolName, toolConfig ] of Object.entries( toolsConfig ) ) {
-    // Access tool factory directly from provider.tools (dynamic!)
     const toolFactory = provider.tools[toolName];
 
     if ( !toolFactory || typeof toolFactory !== 'function' ) {
-      // Dynamically list available tools for this provider
       const availableTools = Object.keys( provider.tools )
         .filter( key => typeof provider.tools[key] === 'function' )
         .join( ', ' );
@@ -103,7 +122,6 @@ export function loadTools( prompt ) {
       );
     }
 
-    // Call factory with config - this passes configuration to AI SDK
     tools[toolName] = toolFactory( toolConfig );
   }
 

package/src/ai_model.spec.js

@@ -46,7 +46,7 @@ vi.mock( '@ai-sdk/google-vertex', () => {
   return { vertex: vertexFn };
 } );
 
-import { loadModel, loadTools } from './ai_model.js';
+import { loadModel, loadTools, registerProvider, getRegisteredProviders, _resetProviders } from './ai_model.js';
 
 afterEach( async () => {
   await vi.resetModules();
@@ -600,3 +600,67 @@ describe( 'loadTools', () => {
     } );
   } );
 } );
+
+describe( 'registerProvider', () => {
+  afterEach( () => {
+    _resetProviders();
+  } );
+
+  it( 'registers a custom provider and uses it in loadModel', () => {
+    const customProvider = vi.fn( model => `custom:${model}` );
+    registerProvider( 'custom', customProvider );
+
+    const result = loadModel( { config: { provider: 'custom', model: 'my-model' } } );
+
+    expect( result ).toBe( 'custom:my-model' );
+    expect( customProvider ).toHaveBeenCalledWith( 'my-model' );
+  } );
+
+  it( 'overrides a built-in provider', () => {
+    const overrideOpenai = vi.fn( model => `override:${model}` );
+    registerProvider( 'openai', overrideOpenai );
+
+    const result = loadModel( { config: { provider: 'openai', model: 'gpt-custom' } } );
+
+    expect( result ).toBe( 'override:gpt-custom' );
+  } );
+
+  it( 'throws when name is empty string', () => {
+    expect( () => registerProvider( '', vi.fn() ) ).toThrow( 'non-empty string' );
+  } );
+
+  it( 'throws when name is not a string', () => {
+    expect( () => registerProvider( 123, vi.fn() ) ).toThrow( 'non-empty string' );
+  } );
+
+  it( 'throws when providerFn is not a function', () => {
+    expect( () => registerProvider( 'bad', 'not-a-function' ) ).toThrow( 'must be a function' );
+  } );
+
+  it( 'throws when providerFn is null', () => {
+    expect( () => registerProvider( 'bad', null ) ).toThrow( 'must be a function' );
+  } );
+} );
+
+describe( 'getRegisteredProviders', () => {
+  afterEach( () => {
+    _resetProviders();
+  } );
+
+  it( 'returns default providers', () => {
+    const providers = getRegisteredProviders();
+
+    expect( providers ).toContain( 'anthropic' );
+    expect( providers ).toContain( 'openai' );
+    expect( providers ).toContain( 'azure' );
+    expect( providers ).toContain( 'vertex' );
+  } );
+
+  it( 'includes dynamically registered providers', () => {
+    registerProvider( 'bedrock', vi.fn() );
+
+    const providers = getRegisteredProviders();
+
+    expect( providers ).toContain( 'bedrock' );
+  } );
+} );

package/src/ai_sdk.js

@@ -5,6 +5,14 @@ import * as AI from 'ai';
 import { validateGenerateTextArgs, validateGenerateObjectArgs, validateGenerateArrayArgs, validateGenerateEnumArgs } from './validations.js';
 import { loadPrompt } from './prompt_loader.js';
 
+const _deprecationWarned = new Set();
+const warnDeprecated = ( name, message ) => {
+  if ( !_deprecationWarned.has( name ) ) {
+    _deprecationWarned.add( name );
+    process.emitWarning( message, { type: 'DeprecationWarning', code: `OUTPUT_DEP_${name.toUpperCase()}` } );
+  }
+};
+
 const traceWrapper = async ( { traceId, resultProperty, fn } ) => {
   try {
     const response = await fn();
@@ -12,13 +20,11 @@ const traceWrapper = async ( { traceId, resultProperty, fn } ) => {
     const result = response[resultProperty];
     Tracing.addEventEnd( { id: traceId, details: { result, usage, providerMetadata } } );
 
-    // Use a Proxy to add 'result' as a unified field name without mutating the AI SDK response.
-    // This preserves the original response object (with its getters/prototype) while allowing
-    // developers to use 'result' consistently across all generate* functions.
-    // Note: Don't use spread/rest on response - AI SDK uses getters that won't copy correctly.
+    // Proxy adds unified 'result' alias and backward-compat 'object' alias without mutating the response.
+    // Don't use spread/rest on response - AI SDK uses getters that won't copy correctly.
     return new Proxy( response, {
       get( target, prop, receiver ) {
-        if ( prop === 'result' ) {
+        if ( prop === 'result' || ( prop === 'object' && resultProperty === 'output' ) ) {
           return target[resultProperty];
         }
         return Reflect.get( target, prop, receiver );
@@ -99,35 +105,40 @@ export async function generateText( { prompt, variables, ...extraAiSdkOptions }
 /**
  * Use an LLM model to generate an object with a fixed schema.
  *
- * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
- * to the underlying provider. Options from the prompt file can be overridden at call time.
+ * @deprecated Since v0.3.0. Use generateText() with Output.object({ schema }) instead.
+ *   Will be removed in v1.0.0.
+ *
+ * @example Migration:
+ * ```js
+ * // Before (deprecated):
+ * const { object } = await generateObject({ prompt: 'my_prompt', schema: MySchema });
+ *
+ * // After (recommended):
+ * const { output } = await generateText({ prompt: 'my_prompt', output: Output.object({ schema: MySchema }) });
+ * ```
  *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
- * @param {z.ZodObject} args.schema - Output schema
+ * @param {z.ZodType} args.schema - Output schema
  * @param {string} [args.schemaName] - Output schema name
  * @param {string} [args.schemaDescription] - Output schema description
- * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
- * @param {number} [args.seed] - Seed for deterministic output
- * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
- * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
- * @throws {FatalError} If the prompt file is not found or template rendering fails
+ * @see {@link generateText} for the recommended replacement
  * @returns {Promise<GenerateObjectResult>} AI SDK response with object and metadata
  */
 export async function generateObject( args ) {
+  warnDeprecated( 'generateObject',
+    'generateObject() is deprecated since v0.3.0 and will be removed in v1.0.0. ' +
+    'Use generateText() with Output.object({ schema }) instead.' );
   validateGenerateObjectArgs( args );
   const { prompt, variables, schema, schemaName, schemaDescription, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
   const traceId = startTrace( 'generateObject', { prompt, variables, schema: z.toJSONSchema( schema ), loadedPrompt } );
 
   return traceWrapper( {
-    traceId, resultProperty: 'object', fn: async () =>
-      AI.generateObject( {
-        output: 'object',
-        schema,
-        schemaName,
-        schemaDescription,
+    traceId, resultProperty: 'output', fn: async () =>
+      AI.generateText( {
+        output: AI.Output.object( { schema, name: schemaName, description: schemaDescription } ),
         ...aiSdkOptionsFromPrompt( loadedPrompt ),
         ...extraAiSdkOptions
       } )
@@ -137,8 +148,17 @@ export async function generateObject( args ) {
 /**
  * Use an LLM model to generate an array of values with a fixed schema.
  *
- * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
- * to the underlying provider. Options from the prompt file can be overridden at call time.
+ * @deprecated Since v0.3.0. Use generateText() with Output.array({ element }) instead.
+ *   Will be removed in v1.0.0.
+ *
+ * @example Migration:
+ * ```js
+ * // Before (deprecated):
+ * const { object } = await generateArray({ prompt: 'my_prompt', schema: ItemSchema });
+ *
+ * // After (recommended):
+ * const { output } = await generateText({ prompt: 'my_prompt', output: Output.array({ element: ItemSchema }) });
+ * ```
  *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
@@ -146,26 +166,22 @@ export async function generateObject( args ) {
  * @param {z.ZodType} args.schema - Output schema (array item)
  * @param {string} [args.schemaName] - Output schema name
  * @param {string} [args.schemaDescription] - Output schema description
- * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
- * @param {number} [args.seed] - Seed for deterministic output
- * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
- * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
- * @throws {FatalError} If the prompt file is not found or template rendering fails
+ * @see {@link generateText} for the recommended replacement
  * @returns {Promise<GenerateObjectResult>} AI SDK response with array and metadata
  */
 export async function generateArray( args ) {
+  warnDeprecated( 'generateArray',
+    'generateArray() is deprecated since v0.3.0 and will be removed in v1.0.0. ' +
+    'Use generateText() with Output.array({ element: schema }) instead.' );
   validateGenerateArrayArgs( args );
   const { prompt, variables, schema, schemaName, schemaDescription, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
   const traceId = startTrace( 'generateArray', { prompt, variables, schema: z.toJSONSchema( schema ), loadedPrompt } );
 
   return traceWrapper( {
-    traceId, resultProperty: 'object', fn: async () =>
-      AI.generateObject( {
-        output: 'array',
-        schema,
-        schemaName,
-        schemaDescription,
+    traceId, resultProperty: 'output', fn: async () =>
+      AI.generateText( {
+        output: AI.Output.array( { element: schema, name: schemaName, description: schemaDescription } ),
         ...aiSdkOptionsFromPrompt( loadedPrompt ),
         ...extraAiSdkOptions
       } )
@@ -175,31 +191,38 @@ export async function generateArray( args ) {
 /**
  * Use an LLM model to generate a result from an enum (array of string values).
  *
- * Accepts additional AI SDK options (maxRetries, seed, etc.) that are passed through
- * to the underlying provider. Options from the prompt file can be overridden at call time.
+ * @deprecated Since v0.3.0. Use generateText() with Output.choice({ options }) instead.
+ *   Will be removed in v1.0.0.
+ *
+ * @example Migration:
+ * ```js
+ * // Before (deprecated):
+ * const { object } = await generateEnum({ prompt: 'my_prompt', enum: ['yes', 'no', 'maybe'] });
+ *
+ * // After (recommended):
+ * const { output } = await generateText({ prompt: 'my_prompt', output: Output.choice({ options: ['yes', 'no', 'maybe'] }) });
+ * ```
  *
  * @param {object} args - Generation arguments
  * @param {string} args.prompt - Prompt file name
  * @param {Record<string, string | number>} [args.variables] - Variables to interpolate
  * @param {string[]} args.enum - Allowed values for the generation
- * @param {number} [args.maxRetries] - Max retry attempts (default: 2)
- * @param {number} [args.seed] - Seed for deterministic output
- * @param {AbortSignal} [args.abortSignal] - Signal to abort the request
- * @throws {ValidationError} If the prompt config is invalid (e.g., snake_case fields)
- * @throws {FatalError} If the prompt file is not found or template rendering fails
+ * @see {@link generateText} for the recommended replacement
  * @returns {Promise<GenerateObjectResult>} AI SDK response with enum value and metadata
  */
 export async function generateEnum( args ) {
+  warnDeprecated( 'generateEnum',
+    'generateEnum() is deprecated since v0.3.0 and will be removed in v1.0.0. ' +
+    'Use generateText() with Output.choice({ options }) instead.' );
   validateGenerateEnumArgs( args );
   const { prompt, variables, enum: _enum, ...extraAiSdkOptions } = args;
   const loadedPrompt = loadPrompt( prompt, variables );
   const traceId = startTrace( 'generateEnum', { prompt, variables, loadedPrompt } );
 
   return traceWrapper( {
-    traceId, resultProperty: 'object', fn: async () =>
-      AI.generateObject( {
-        output: 'enum',
-        enum: _enum,
+    traceId, resultProperty: 'output', fn: async () =>
+      AI.generateText( {
+        output: AI.Output.choice( { options: _enum } ),
         ...aiSdkOptionsFromPrompt( loadedPrompt ),
         ...extraAiSdkOptions
       } )