@auto-engineer/ai-gateway 0.11.15 → 0.11.16

package/package.json

@@ -3,21 +3,37 @@
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./core": {
+      "types": "./dist/src/core/index.d.ts",
+      "import": "./dist/src/core/index.js"
+    },
+    "./node": {
+      "types": "./dist/src/node/index.d.ts",
+      "import": "./dist/src/node/index.js"
+    }
+  },
   "dependencies": {
     "@ai-sdk/anthropic": "^1.2.12",
     "@ai-sdk/google": "^1.2.19",
     "@ai-sdk/openai": "^1.3.22",
     "@ai-sdk/xai": "^1.2.16",
-    "@modelcontextprotocol/sdk": "^1.3.0",
     "ai": "^4.3.16",
     "debug": "^4.4.0",
-    "dotenv": "^16.4.5",
     "zod": "^3.25.67"
   },
+  "optionalDependencies": {
+    "@modelcontextprotocol/sdk": "^1.3.0",
+    "dotenv": "^16.4.5"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.15",
+  "version": "0.11.16",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",

package/src/config.specs.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { configureAIProvider } from './config';
+import { configureAIProvider } from './node';
 
 // Mock environment variables
 const originalEnv = process.env;
@@ -7,7 +7,6 @@ const originalEnv = process.env;
 describe('AI Configuration with Custom Providers', () => {
   beforeEach(() => {
     vi.resetModules();
-    // Clear all AI-related environment variables for clean test state
     process.env = {};
   });
 

package/src/config.ts

@@ -30,14 +30,12 @@ export interface AIConfig {
   custom?: CustomProviderConfig;
 }
 
-// Helper to log provider configuration
 function logProviderConfig(providerName: string, apiKey: string | undefined): void {
   if (apiKey !== undefined) {
     debug('%s provider configured with API key ending in: ...%s', providerName, apiKey.slice(-4));
   }
 }
 
-// Helper to build custom provider config
 function buildCustomProviderConfig(): CustomProviderConfig | undefined {
   const name = process.env.CUSTOM_PROVIDER_NAME;
   const baseUrl = process.env.CUSTOM_PROVIDER_BASE_URL;

package/src/core/constants.ts

@@ -0,0 +1,8 @@
+import { AIProvider } from './types';
+
+export const DEFAULT_MODELS = {
+  [AIProvider.OpenAI]: 'gpt-5',
+  [AIProvider.Anthropic]: 'claude-sonnet-4-5-20250929',
+  [AIProvider.Google]: 'gemini-2.5-pro',
+  [AIProvider.XAI]: 'grok-4',
+} as const;

package/src/core/context.ts

@@ -0,0 +1,106 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createXai } from '@ai-sdk/xai';
+import { AIProvider, AIContext, AIConfig } from './types';
+import { DEFAULT_MODELS } from './constants';
+import { createCustomProvider } from './providers/custom';
+import { makeLogger } from './utils/log';
+
+const debugConfig = makeLogger('auto:ai-gateway:config');
+
+export function createAIContext(config: AIConfig, defaultProvider?: AIProvider): AIContext {
+  return {
+    config,
+    defaultProvider,
+  };
+}
+
+export function getAvailableProviders(context: AIContext): AIProvider[] {
+  const providers: AIProvider[] = [];
+  if (context.config.anthropic != null) providers.push(AIProvider.Anthropic);
+  if (context.config.openai != null) providers.push(AIProvider.OpenAI);
+  if (context.config.google != null) providers.push(AIProvider.Google);
+  if (context.config.xai != null) providers.push(AIProvider.XAI);
+  if (context.config.custom != null) providers.push(AIProvider.Custom);
+  debugConfig('Available providers: %o', providers);
+  return providers;
+}
+
+export function getDefaultProvider(context: AIContext): AIProvider {
+  if (context.defaultProvider != null) {
+    return context.defaultProvider;
+  }
+
+  const available = getAvailableProviders(context);
+  if (available.length === 0) {
+    throw new Error('No AI providers configured in context');
+  }
+  return available[0];
+}
+
+export function getDefaultModel(provider: AIProvider, context: AIContext): string {
+  if (provider === AIProvider.Custom) {
+    const config = context.config.custom;
+    if (config == null) {
+      throw new Error('Custom provider not configured');
+    }
+    debugConfig('Selected custom provider default model %s for provider %s', config.defaultModel, provider);
+    return config.defaultModel;
+  }
+
+  const model =
+    DEFAULT_MODELS[provider] ??
+    (() => {
+      throw new Error(`Unknown provider: ${provider}`);
+    })();
+  debugConfig('Selected default model %s for provider %s', model, provider);
+  return model;
+}
+
+const providerFactories = {
+  [AIProvider.OpenAI]: (modelName: string, context: AIContext) => {
+    const config = context.config.openai;
+    if (config == null) throw new Error('OpenAI provider not configured');
+    const openaiProvider = createOpenAI({ apiKey: config.apiKey });
+    return openaiProvider(modelName);
+  },
+  [AIProvider.Anthropic]: (modelName: string, context: AIContext) => {
+    const config = context.config.anthropic;
+    if (config == null) throw new Error('Anthropic provider not configured');
+    const anthropicProvider = createAnthropic({ apiKey: config.apiKey });
+    return anthropicProvider(modelName);
+  },
+  [AIProvider.Google]: (modelName: string, context: AIContext) => {
+    const config = context.config.google;
+    if (config == null) throw new Error('Google provider not configured');
+    const googleProvider = createGoogleGenerativeAI({ apiKey: config.apiKey });
+    return googleProvider(modelName);
+  },
+  [AIProvider.XAI]: (modelName: string, context: AIContext) => {
+    const config = context.config.xai;
+    if (config == null) throw new Error('XAI provider not configured');
+    const xaiProvider = createXai({ apiKey: config.apiKey });
+    return xaiProvider(modelName);
+  },
+  [AIProvider.Custom]: (modelName: string, context: AIContext) => {
+    const config = context.config.custom;
+    if (config == null) throw new Error('Custom provider not configured');
+    const customProvider = createCustomProvider(config);
+    return customProvider.languageModel(modelName);
+  },
+};
+
+function createProviderModel(provider: AIProvider, modelName: string, context: AIContext) {
+  const factory = providerFactories[provider];
+  if (factory == null) {
+    throw new Error(`Unknown provider: ${provider as string}`);
+  }
+  return factory(modelName, context);
+}
+
+export function getModel(provider: AIProvider, model: string | undefined, context: AIContext) {
+  const modelName = model ?? getDefaultModel(provider, context);
+  debugConfig('Creating model instance for provider %s with model %s', provider, modelName);
+  return createProviderModel(provider, modelName, context);
+}

package/src/core/generators.ts

@@ -0,0 +1,424 @@
+import { generateText as aiGenerateText, streamText as aiStreamText, generateObject, streamObject } from 'ai';
+import {
+  AIContext,
+  AIOptions,
+  StructuredAIOptions,
+  StreamStructuredAIOptions,
+  AIProvider,
+  RegisteredToolForAI,
+  AIToolValidationError,
+} from './types';
+import { getModel, getDefaultProvider, getDefaultModel } from './context';
+import { extractAndLogError } from './utils/errors';
+import { getEnhancedPrompt, handleFailedRequest } from './utils/validation';
+import { makeLogger } from './utils/log';
+
+const debugAPI = makeLogger('auto:ai-gateway:api');
+const debugStream = makeLogger('auto:ai-gateway:stream');
+const debugTools = makeLogger('auto:ai-gateway:tools');
+const debugValidation = makeLogger('auto:ai-gateway:validation');
+const debugError = makeLogger('auto:ai-gateway:error');
+
+const defaultOptions: AIOptions = {
+  temperature: 0.7,
+  maxTokens: 1000,
+};
+
+export async function generateText(context: AIContext, prompt: string, options: AIOptions = {}): Promise<string> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugAPI('generateText called - provider: %s, promptLength: %d', resolvedProvider, prompt.length);
+  const finalOptions = { ...defaultOptions, ...options };
+  const model = finalOptions.model ?? getDefaultModel(resolvedProvider, context);
+  const modelInstance = getModel(resolvedProvider, finalOptions.model, context);
+
+  try {
+    debugAPI('Making API call to %s with model %s', resolvedProvider, model);
+    debugAPI('Request params - temperature: %d, maxTokens: %d', finalOptions.temperature, finalOptions.maxTokens);
+
+    const result = await aiGenerateText({
+      model: modelInstance,
+      prompt,
+      temperature: finalOptions.temperature,
+      maxTokens: finalOptions.maxTokens,
+    });
+
+    debugAPI('API call successful - response length: %d, usage: %o', result.text.length, result.usage);
+    return result.text;
+  } catch (error) {
+    extractAndLogError(error, resolvedProvider, 'generateText');
+    throw error;
+  }
+}
+
+export async function* streamText(context: AIContext, prompt: string, options: AIOptions = {}): AsyncGenerator<string> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugStream('streamText called - provider: %s, promptLength: %d', resolvedProvider, prompt.length);
+  const finalOptions = { ...defaultOptions, ...options };
+  const modelInstance = getModel(resolvedProvider, finalOptions.model, context);
+
+  try {
+    debugStream('Starting stream from %s', resolvedProvider);
+    const stream = aiStreamText({
+      model: modelInstance,
+      prompt,
+      temperature: finalOptions.temperature,
+      maxTokens: finalOptions.maxTokens,
+    });
+
+    let totalChunks = 0;
+    let totalLength = 0;
+    for await (const chunk of stream.textStream) {
+      totalChunks++;
+      totalLength += chunk.length;
+      debugStream('Chunk %d received - size: %d bytes', totalChunks, chunk.length);
+      yield chunk;
+    }
+    debugStream('Stream completed - total chunks: %d, total length: %d', totalChunks, totalLength);
+  } catch (error) {
+    extractAndLogError(error, resolvedProvider, 'streamText');
+    throw error;
+  }
+}
+
+export async function generateTextStreaming(
+  context: AIContext,
+  prompt: string,
+  options: AIOptions = {},
+): Promise<string> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugStream('generateTextStreaming called - provider: %s', resolvedProvider);
+  const finalOptions = { ...defaultOptions, ...options };
+  let collectedResult = '';
+
+  const stream = streamText(context, prompt, finalOptions);
+
+  let tokenCount = 0;
+  for await (const token of stream) {
+    tokenCount++;
+    collectedResult += token;
+
+    if (finalOptions.streamCallback) {
+      finalOptions.streamCallback(token);
+    }
+  }
+
+  debugStream('Streaming complete - total tokens: %d, result length: %d', tokenCount, collectedResult.length);
+  return collectedResult;
+}
+
+export async function generateTextWithImage(
+  context: AIContext,
+  text: string,
+  imageBase64: string,
+  options: AIOptions = {},
+): Promise<string> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugAPI(
+    'generateTextWithImage called - provider: %s, textLength: %d, imageSize: %d',
+    resolvedProvider,
+    text.length,
+    imageBase64.length,
+  );
+  const finalOptions = { ...defaultOptions, ...options };
+  const modelInstance = getModel(resolvedProvider, finalOptions.model, context);
+
+  if (resolvedProvider !== AIProvider.OpenAI && resolvedProvider !== AIProvider.XAI) {
+    debugError('Provider %s does not support image inputs', resolvedProvider);
+    throw new Error(`Provider ${resolvedProvider} does not support image inputs`);
+  }
+
+  try {
+    debugAPI('Sending image+text to %s', resolvedProvider);
+    const result = await aiGenerateText({
+      model: modelInstance,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text },
+            { type: 'image', image: imageBase64 },
+          ],
+        },
+      ],
+      temperature: finalOptions.temperature,
+      maxTokens: finalOptions.maxTokens,
+    });
+
+    debugAPI('Image API call successful - response length: %d', result.text.length);
+    return result.text;
+  } catch (error) {
+    extractAndLogError(error, resolvedProvider, 'generateTextWithImage');
+    throw error;
+  }
+}
+
+async function attemptStructuredGeneration<T>(
+  context: AIContext,
+  prompt: string,
+  provider: AIProvider,
+  options: StructuredAIOptions<T>,
+  registeredTools: Record<string, RegisteredToolForAI>,
+  hasTools: boolean,
+): Promise<T> {
+  const maxSchemaRetries = 3;
+  let lastError: AIToolValidationError | undefined;
+
+  for (let attempt = 0; attempt < maxSchemaRetries; attempt++) {
+    try {
+      debugValidation('Structured data generation attempt %d/%d', attempt + 1, maxSchemaRetries);
+      const modelInstance = getModel(provider, options.model, context);
+
+      const enhancedPrompt = attempt > 0 && lastError ? getEnhancedPrompt(prompt, lastError) : prompt;
+      if (attempt > 0) {
+        debugValidation('Using enhanced prompt for retry attempt %d', attempt + 1);
+      }
+
+      const opts = {
+        model: modelInstance,
+        prompt: enhancedPrompt,
+        schema: options.schema,
+        schemaName: options.schemaName,
+        schemaDescription: options.schemaDescription,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+        ...(hasTools && {
+          tools: registeredTools,
+          toolChoice: 'auto' as const,
+        }),
+      };
+      debugAPI('Generating structured object with schema: %s', options.schemaName ?? 'unnamed');
+      const result = await generateObject(opts);
+      debugAPI('Structured object generated successfully');
+      return result.object;
+    } catch (error: unknown) {
+      lastError =
+        error instanceof Error
+          ? (error as AIToolValidationError)
+          : (new Error('An unknown error occurred') as AIToolValidationError);
+
+      const { shouldRetry, enhancedError } = handleFailedRequest(lastError, maxSchemaRetries, attempt);
+      lastError = enhancedError;
+
+      if (!shouldRetry) {
+        throw lastError;
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+export async function generateStructuredData<T>(
+  context: AIContext,
+  prompt: string,
+  options: StructuredAIOptions<T>,
+  registeredTools: Record<string, RegisteredToolForAI> = {},
+): Promise<T> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugAPI(
+    'generateStructuredData called - provider: %s, schema: %s',
+    resolvedProvider,
+    options.schemaName ?? 'unnamed',
+  );
+
+  const hasTools = Object.keys(registeredTools).length > 0;
+
+  return attemptStructuredGeneration(context, prompt, resolvedProvider, options, registeredTools, hasTools);
+}
+
+export async function streamStructuredData<T>(
+  context: AIContext,
+  prompt: string,
+  options: StreamStructuredAIOptions<T>,
+): Promise<T> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugStream(
+    'streamStructuredData called - provider: %s, schema: %s',
+    resolvedProvider,
+    options.schemaName ?? 'unnamed',
+  );
+  const maxSchemaRetries = 3;
+  let lastError: AIToolValidationError | undefined;
+
+  for (let attempt = 0; attempt < maxSchemaRetries; attempt++) {
+    try {
+      debugValidation('Stream structured data attempt %d/%d', attempt + 1, maxSchemaRetries);
+      const modelInstance = getModel(resolvedProvider, options.model, context);
+
+      const enhancedPrompt = attempt > 0 && lastError ? getEnhancedPrompt(prompt, lastError) : prompt;
+
+      const result = streamObject({
+        model: modelInstance,
+        prompt: enhancedPrompt,
+        schema: options.schema,
+        schemaName: options.schemaName,
+        schemaDescription: options.schemaDescription,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+      });
+
+      if (options.onPartialObject) {
+        debugStream('Starting partial object stream');
+        void (async () => {
+          try {
+            let partialCount = 0;
+            for await (const partialObject of result.partialObjectStream) {
+              partialCount++;
+              debugStream('Partial object %d received', partialCount);
+              options.onPartialObject?.(partialObject);
+            }
+            debugStream('Partial object stream complete - total partials: %d', partialCount);
+          } catch (streamError) {
+            debugError('Error in partial object stream: %O', streamError);
+          }
+        })();
+      }
+
+      const finalObject = await result.object;
+      debugStream('Final structured object received');
+      return finalObject;
+    } catch (error: unknown) {
+      lastError =
+        error instanceof Error
+          ? (error as AIToolValidationError)
+          : (new Error('An unknown error occurred') as AIToolValidationError);
+
+      const { shouldRetry, enhancedError } = handleFailedRequest(lastError, maxSchemaRetries, attempt);
+      lastError = enhancedError;
+
+      if (!shouldRetry) {
+        throw lastError;
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+async function executeToolConversation(
+  modelInstance: ReturnType<typeof getModel>,
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>,
+  registeredTools: Record<string, RegisteredToolForAI>,
+  hasTools: boolean,
+  finalOptions: AIOptions & { temperature?: number; maxTokens?: number },
+  provider: AIProvider,
+): Promise<{ finalResult: string; allToolCalls: unknown[] }> {
+  let finalResult = '';
+  const allToolCalls: unknown[] = [];
+  let attempts = 0;
+  const maxAttempts = 5;
+
+  while (attempts < maxAttempts) {
+    attempts++;
+    debugTools('Tool execution attempt %d/%d', attempts, maxAttempts);
+
+    const opts = {
+      model: modelInstance,
+      messages,
+      temperature: finalOptions.temperature,
+      maxTokens: finalOptions.maxTokens,
+      ...(hasTools && {
+        tools: registeredTools,
+        toolChoice: 'auto' as const,
+      }),
+    };
+    debugTools('Request options: %o', { ...opts, tools: hasTools ? '[tools included]' : undefined });
+
+    try {
+      const result = await aiGenerateText(opts);
+      debugTools('Result received - has text: %s, tool calls: %d', !!result.text, result.toolCalls?.length ?? 0);
+
+      if (result.text) {
+        messages.push({ role: 'assistant', content: result.text });
+        finalResult = result.text;
+        debugTools('Assistant message added to conversation');
+      }
+
+      if (result.toolCalls !== undefined && result.toolCalls.length > 0) {
+        allToolCalls.push(...result.toolCalls);
+        debugTools('Executing %d tool calls', result.toolCalls.length);
+
+        const toolResults = await executeToolCalls(result.toolCalls, registeredTools);
+        debugTools('Tool execution completed, results length: %d', toolResults.length);
+
+        messages.push({
+          role: 'user',
+          content: `${toolResults}\n\nUsing the tool outputs above, continue your response to the original request.`,
+        });
+
+        continue;
+      }
+
+      debugTools('No tool calls, conversation complete');
+      break;
+    } catch (error) {
+      extractAndLogError(error, provider, 'generateTextWithTools');
+      throw error;
+    }
+  }
+
+  return { finalResult, allToolCalls };
+}
+
+async function executeToolCalls(
+  toolCalls: unknown[],
+  registeredTools: Record<string, RegisteredToolForAI>,
+): Promise<string> {
+  debugTools('Executing %d tool calls', toolCalls.length);
+  let toolResults = '';
+
+  for (const toolCall of toolCalls) {
+    try {
+      const toolCallObj = toolCall as { toolName: string; args: Record<string, unknown> };
+      debugTools('Executing tool: %s with args: %o', toolCallObj.toolName, toolCallObj.args);
+      const tool = registeredTools[toolCallObj.toolName];
+      if (tool?.execute) {
+        const toolResult = await tool.execute(toolCallObj.args);
+        toolResults += `Tool ${toolCallObj.toolName} returned: ${String(toolResult)}\n\n`;
+        debugTools('Tool %s executed successfully', toolCallObj.toolName);
+      } else {
+        toolResults += `Error: Tool ${toolCallObj.toolName} not found or missing execute function\n\n`;
+        debugTools('Tool %s not found or missing execute function', toolCallObj.toolName);
+      }
+    } catch (error) {
+      const toolCallObj = toolCall as { toolName: string };
+      debugError('Tool execution error for %s: %O', toolCallObj.toolName, error);
+      toolResults += `Error executing tool ${toolCallObj.toolName}: ${String(error)}\n\n`;
+    }
+  }
+
+  return toolResults;
+}
+
+export async function generateTextWithTools(
+  context: AIContext,
+  prompt: string,
+  options: AIOptions = {},
+  registeredTools: Record<string, RegisteredToolForAI> = {},
+): Promise<{ text: string; toolCalls?: unknown[] }> {
+  const resolvedProvider = options.provider ?? getDefaultProvider(context);
+  debugTools('generateTextWithTools called - provider: %s', resolvedProvider);
+  const finalOptions = { ...defaultOptions, ...options };
+  const model = finalOptions.model ?? getDefaultModel(resolvedProvider, context);
+  const modelInstance = getModel(resolvedProvider, model, context);
+
+  debugTools('Registered tools: %o', Object.keys(registeredTools));
+  const hasTools = Object.keys(registeredTools).length > 0;
+  debugTools('Has tools available: %s', hasTools);
+
+  const messages: Array<{ role: 'user' | 'assistant'; content: string }> = [{ role: 'user', content: prompt }];
+
+  const { finalResult, allToolCalls } = await executeToolConversation(
+    modelInstance,
+    messages,
+    registeredTools,
+    hasTools,
+    finalOptions,
+    resolvedProvider,
+  );
+
+  return {
+    text: finalResult,
+    toolCalls: allToolCalls,
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,29 @@
+export { AIProvider } from './types';
+export type {
+  CustomProviderConfig,
+  AIConfig,
+  AIContext,
+  AIOptions,
+  StructuredAIOptions,
+  StreamStructuredAIOptions,
+  AIToolValidationError,
+  RegisteredToolForAI,
+} from './types';
+
+export { DEFAULT_MODELS } from './constants';
+
+export { createAIContext, getAvailableProviders, getDefaultProvider, getDefaultModel, getModel } from './context';
+
+export {
+  generateText,
+  streamText,
+  generateTextStreaming,
+  generateTextWithImage,
+  generateStructuredData,
+  streamStructuredData,
+  generateTextWithTools,
+} from './generators';
+
+export { createCustomProvider } from './providers/custom';
+
+export { z } from 'zod';

package/src/core/providers/custom.ts

@@ -0,0 +1,10 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { CustomProviderConfig } from '../types';
+
+export function createCustomProvider(config: CustomProviderConfig) {
+  return createOpenAI({
+    name: config.name,
+    baseURL: config.baseUrl,
+    apiKey: config.apiKey,
+  });
+}