@launchdarkly/server-sdk-ai 0.11.4 → 0.12.0

package/src/api/config/LDAIConfigTracker.ts

@@ -1,4 +1,4 @@
-import { LDFeedbackKind, LDTokenUsage } from '../metrics';
+import { LDAIMetrics, LDFeedbackKind, LDTokenUsage } from '../metrics';
 
 /**
  * Metrics which have been tracked.
@@ -87,6 +87,25 @@ export interface LDAIConfigTracker {
    */
   trackDurationOf(func: () => Promise<any>): Promise<any>;
 
+  /**
+   * Track metrics for a generic AI operation.
+   *
+   * This function will track the duration of the operation, extract metrics using the provided
+   * metrics extractor function, and track success or error status accordingly.
+   *
+   * If the provided function throws, then this method will also throw.
+   * In the case the provided function throws, this function will record the duration and an error.
+   * A failed operation will not have any token usage data.
+   *
+   * @param metricsExtractor Function that extracts LDAIMetrics from the operation result
+   * @param func Function which executes the operation
+   * @returns The result of the operation
+   */
+  trackMetricsOf<TRes>(
+    metricsExtractor: (result: TRes) => LDAIMetrics,
+    func: () => Promise<TRes>,
+  ): Promise<TRes>;
+
   /**
    * Track an OpenAI operation.
    *

package/src/api/index.ts

@@ -1,4 +1,6 @@
 export * from './config';
 export * from './agents';
+export * from './chat';
 export * from './metrics';
 export * from './LDAIClient';
+export * from './providers';

package/src/api/metrics/LDAIMetrics.ts

@@ -0,0 +1,18 @@
+import { LDTokenUsage } from './LDTokenUsage';
+
+/**
+ * Metrics information for AI operations that includes success status and token usage.
+ * This class combines success/failure tracking with token usage metrics.
+ */
+export interface LDAIMetrics {
+  /**
+   * Whether the AI operation was successful.
+   */
+  success: boolean;
+
+  /**
+   * Token usage information for the operation.
+   * This will be undefined if no token usage data is available.
+   */
+  usage?: LDTokenUsage;
+}

package/src/api/metrics/index.ts

@@ -1,5 +1,6 @@
 export * from './BedrockTokenUsage';
 export * from './OpenAiUsage';
 export * from './LDFeedbackKind';
+export * from './LDAIMetrics';
 export * from './LDTokenUsage';
 export * from './VercelAISDKTokenUsage';

package/src/api/providers/AIProvider.ts

@@ -0,0 +1,43 @@
+import { LDLogger } from '@launchdarkly/js-server-sdk-common';
+
+import { ChatResponse } from '../chat/types';
+import { LDAIConfig, LDMessage } from '../config/LDAIConfig';
+
+/**
+ * Abstract base class for AI providers that implement chat model functionality.
+ * This class provides the contract that all provider implementations must follow
+ * to integrate with LaunchDarkly's tracking and configuration capabilities.
+ *
+ * Following the AICHAT spec recommendation to use base classes with non-abstract methods
+ * for better extensibility and backwards compatibility.
+ */
+export abstract class AIProvider {
+  protected readonly logger?: LDLogger;
+
+  constructor(logger?: LDLogger) {
+    this.logger = logger;
+  }
+  /**
+   * Invoke the chat model with an array of messages.
+   * This method should convert messages to provider format, invoke the model,
+   * and return a ChatResponse with the result and metrics.
+   *
+   * @param messages Array of LDMessage objects representing the conversation
+   * @returns Promise that resolves to a ChatResponse containing the model's response
+   */
+  abstract invokeModel(messages: LDMessage[]): Promise<ChatResponse>;
+
+  /**
+   * Static method that constructs an instance of the provider.
+   * Each provider implementation must provide their own static create method
+   * that accepts an AIConfig and returns a configured instance.
+   *
+   * @param aiConfig The LaunchDarkly AI configuration
+   * @param logger Optional logger for the provider
+   * @returns Promise that resolves to a configured provider instance
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static async create(aiConfig: LDAIConfig, logger?: LDLogger): Promise<AIProvider> {
+    throw new Error('Provider implementations must override the static create method');
+  }
+}

package/src/api/providers/AIProviderFactory.ts

@@ -0,0 +1,152 @@
+import { LDLogger } from '@launchdarkly/js-server-sdk-common';
+
+import { LDAIConfig } from '../config/LDAIConfig';
+import { AIProvider } from './AIProvider';
+
+/**
+ * List of supported AI providers.
+ */
+export const SUPPORTED_AI_PROVIDERS = [
+  'openai',
+  // Multi-provider packages should be last in the list
+  'langchain',
+  'vercel',
+] as const;
+
+/**
+ * Type representing the supported AI providers.
+ */
+export type SupportedAIProvider = (typeof SUPPORTED_AI_PROVIDERS)[number];
+
+/**
+ * Factory for creating AIProvider instances based on the provider configuration.
+ */
+export class AIProviderFactory {
+  /**
+   * Create an AIProvider instance based on the AI configuration.
+   * This method attempts to load provider-specific implementations dynamically.
+   * Returns undefined if the provider is not supported.
+   *
+   * @param aiConfig The AI configuration
+   * @param logger Optional logger for logging provider initialization
+   * @param defaultAiProvider Optional default AI provider to use
+   */
+  static async create(
+    aiConfig: LDAIConfig,
+    logger?: LDLogger,
+    defaultAiProvider?: SupportedAIProvider,
+  ): Promise<AIProvider | undefined> {
+    const providerName = aiConfig.provider?.name?.toLowerCase();
+    // Determine which providers to try based on defaultAiProvider
+    const providersToTry = this._getProvidersToTry(defaultAiProvider, providerName);
+
+    // Try each provider in order
+    // eslint-disable-next-line no-restricted-syntax
+    for (const providerType of providersToTry) {
+      // eslint-disable-next-line no-await-in-loop
+      const provider = await this._tryCreateProvider(providerType, aiConfig, logger);
+      if (provider) {
+        return provider;
+      }
+    }
+
+    // If no provider was successfully created, log a warning
+    logger?.warn(
+      `Provider is not supported or failed to initialize: ${aiConfig.provider?.name ?? 'unknown'}`,
+    );
+    return undefined;
+  }
+
+  /**
+   * Determine which providers to try based on defaultAiProvider and providerName.
+   */
+  private static _getProvidersToTry(
+    defaultAiProvider?: SupportedAIProvider,
+    providerName?: string,
+  ): SupportedAIProvider[] {
+    // If defaultAiProvider is set, only try that specific provider
+    if (defaultAiProvider) {
+      return [defaultAiProvider];
+    }
+
+    // If no defaultAiProvider is set, try all providers in order
+    const providerSet = new Set<SupportedAIProvider>();
+
+    // First try the specific provider if it's supported
+    if (providerName && SUPPORTED_AI_PROVIDERS.includes(providerName as SupportedAIProvider)) {
+      providerSet.add(providerName as SupportedAIProvider);
+    }
+
+    // Then try multi-provider packages, but avoid duplicates
+    const multiProviderPackages: SupportedAIProvider[] = ['langchain', 'vercel'];
+    multiProviderPackages.forEach((provider) => {
+      providerSet.add(provider);
+    });
+
+    return Array.from(providerSet);
+  }
+
+  /**
+   * Try to create a provider of the specified type.
+   */
+  private static async _tryCreateProvider(
+    providerType: SupportedAIProvider,
+    aiConfig: LDAIConfig,
+    logger?: LDLogger,
+  ): Promise<AIProvider | undefined> {
+    switch (providerType) {
+      case 'openai':
+        return this._createProvider(
+          '@launchdarkly/server-sdk-ai-openai',
+          'OpenAIProvider',
+          aiConfig,
+          logger,
+        );
+      case 'langchain':
+        return this._createProvider(
+          '@launchdarkly/server-sdk-ai-langchain',
+          'LangChainProvider',
+          aiConfig,
+          logger,
+        );
+      case 'vercel':
+        return this._createProvider(
+          '@launchdarkly/server-sdk-ai-vercel',
+          'VercelProvider',
+          aiConfig,
+          logger,
+        );
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Create a provider instance dynamically.
+   */
+  private static async _createProvider(
+    packageName: string,
+    providerClassName: string,
+    aiConfig: LDAIConfig,
+    logger?: LDLogger,
+  ): Promise<AIProvider | undefined> {
+    try {
+      // Try to dynamically import the provider
+      // This will work if the package is installed
+      // eslint-disable-next-line import/no-extraneous-dependencies, global-require, import/no-dynamic-require
+      const { [providerClassName]: ProviderClass } = require(packageName);
+
+      const provider = await ProviderClass.create(aiConfig, logger);
+      logger?.debug(
+        `Successfully created AIProvider for: ${aiConfig.provider?.name} with package ${packageName}`,
+      );
+      return provider;
+    } catch (error) {
+      // If the provider is not available or creation fails, return undefined
+      logger?.warn(
+        `Error creating AIProvider for: ${aiConfig.provider?.name} with package ${packageName}: ${error}`,
+      );
+      return undefined;
+    }
+  }
+}

package/src/api/providers/index.ts

@@ -0,0 +1,2 @@
+export * from './AIProvider';
+export * from './AIProviderFactory';

package/tsconfig.eslint.json

@@ -1,5 +1,5 @@
 {
   "extends": "./tsconfig.json",
-  "include": ["/**/*.ts"],
-  "exclude": ["node_modules"]
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
 }