@launchdarkly/server-sdk-ai 0.11.3 → 0.12.0

package/src/api/chat/TrackedChat.ts

@@ -0,0 +1,100 @@
+import { LDAIConfig, LDMessage } from '../config/LDAIConfig';
+import { LDAIConfigTracker } from '../config/LDAIConfigTracker';
+import { AIProvider } from '../providers/AIProvider';
+import { ChatResponse } from './types';
+
+/**
+ * Concrete implementation of TrackedChat that provides chat functionality
+ * by delegating to an AIProvider implementation.
+ * This class handles conversation management and tracking, while delegating
+ * the actual model invocation to the provider.
+ */
+export class TrackedChat {
+  protected messages: LDMessage[];
+
+  constructor(
+    protected readonly aiConfig: LDAIConfig,
+    protected readonly tracker: LDAIConfigTracker,
+    protected readonly provider: AIProvider,
+  ) {
+    this.messages = [];
+  }
+
+  /**
+   * Invoke the chat model with a prompt string.
+   * This method handles conversation management and tracking, delegating to the provider's invokeModel method.
+   */
+  async invoke(prompt: string): Promise<ChatResponse> {
+    // Convert prompt string to LDMessage with role 'user' and add to conversation history
+    const userMessage: LDMessage = {
+      role: 'user',
+      content: prompt,
+    };
+    this.messages.push(userMessage);
+
+    // Prepend config messages to conversation history for model invocation
+    const configMessages = this.aiConfig.messages || [];
+    const allMessages = [...configMessages, ...this.messages];
+
+    // Delegate to provider-specific implementation with tracking
+    const response = await this.tracker.trackMetricsOf(
+      (result: ChatResponse) => result.metrics,
+      () => this.provider.invokeModel(allMessages),
+    );
+
+    // Add the assistant response to the conversation history
+    this.messages.push(response.message);
+
+    return response;
+  }
+
+  /**
+   * Get the underlying AI configuration used to initialize this TrackedChat.
+   */
+  getConfig(): LDAIConfig {
+    return this.aiConfig;
+  }
+
+  /**
+   * Get the underlying AI configuration tracker used to initialize this TrackedChat.
+   */
+  getTracker(): LDAIConfigTracker {
+    return this.tracker;
+  }
+
+  /**
+   * Get the underlying AI provider instance.
+   * This provides direct access to the provider for advanced use cases.
+   */
+  getProvider(): AIProvider {
+    return this.provider;
+  }
+
+  /**
+   * Append messages to the conversation history.
+   * Adds messages to the conversation history without invoking the model,
+   * which is useful for managing multi-turn conversations or injecting context.
+   *
+   * @param messages Array of messages to append to the conversation history
+   */
+  appendMessages(messages: LDMessage[]): void {
+    this.messages.push(...messages);
+  }
+
+  /**
+   * Get all messages in the conversation history.
+   *
+   * @param includeConfigMessages Whether to include the config messages from the AIConfig.
+   *                              Defaults to false.
+   * @returns Array of messages. When includeConfigMessages is true, returns both config
+   *          messages and conversation history with config messages prepended. When false,
+   *          returns only the conversation history messages.
+   */
+  getMessages(includeConfigMessages: boolean = false): LDMessage[] {
+    if (includeConfigMessages) {
+      const configMessages = this.aiConfig.messages || [];
+      return [...configMessages, ...this.messages];
+    }
+    return [...this.messages];
+  }
+}

package/src/api/chat/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './TrackedChat';

package/src/api/chat/types.ts

@@ -0,0 +1,17 @@
+import { LDMessage } from '../config/LDAIConfig';
+import { LDAIMetrics } from '../metrics/LDAIMetrics';
+
+/**
+ * Chat response structure.
+ */
+export interface ChatResponse {
+  /**
+   * The response message from the AI.
+   */
+  message: LDMessage;
+
+  /**
+   * Metrics information including success status and token usage.
+   */
+  metrics: LDAIMetrics;
+}

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.
    *
@@ -149,7 +168,9 @@ export interface LDAIConfigTracker {
     TRes extends {
       usage?: {
         totalTokens?: number;
+        inputTokens?: number;
         promptTokens?: number;
+        outputTokens?: number;
         completionTokens?: number;
       };
     },
@@ -174,7 +195,9 @@ export interface LDAIConfigTracker {
       finishReason?: Promise<string>;
       usage?: Promise<{
         totalTokens?: number;
+        inputTokens?: number;
         promptTokens?: number;
+        outputTokens?: number;
         completionTokens?: number;
       }>;
     },

package/src/api/config/VercelAISDK.ts

@@ -10,6 +10,7 @@ export interface VercelAISDKConfig<TMod> {
   model: TMod;
   messages?: LDMessage[] | undefined;
   maxTokens?: number | undefined;
+  maxOutputTokens?: number | undefined;
   temperature?: number | undefined;
   topP?: number | undefined;
   topK?: number | undefined;

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/VercelAISDKTokenUsage.ts

@@ -2,12 +2,14 @@ import { LDTokenUsage } from './LDTokenUsage';
 
 export function createVercelAISDKTokenUsage(data: {
   totalTokens?: number;
+  inputTokens?: number;
   promptTokens?: number;
+  outputTokens?: number;
   completionTokens?: number;
 }): LDTokenUsage {
   return {
     total: data.totalTokens ?? 0,
-    input: data.promptTokens ?? 0,
-    output: data.completionTokens ?? 0,
+    input: data.inputTokens ?? data.promptTokens ?? 0,
+    output: data.outputTokens ?? data.completionTokens ?? 0,
   };
 }

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"]
 }