@launchdarkly/server-sdk-ai 0.14.1 → 0.15.0

package/src/api/chat/TrackedChat.ts

@@ -1,163 +0,0 @@
-import { LDLogger } from '@launchdarkly/js-server-sdk-common';
-
-import { LDAIConfigTracker } from '../config/LDAIConfigTracker';
-import { LDAICompletionConfig, LDMessage } from '../config/types';
-import { Judge } from '../judge/Judge';
-import { JudgeResponse } from '../judge/types';
-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: LDAICompletionConfig,
-    protected readonly tracker: LDAIConfigTracker,
-    protected readonly provider: AIProvider,
-    protected readonly judges: Record<string, Judge> = {},
-    private readonly _logger?: LDLogger,
-  ) {
-    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),
-    );
-
-    if (
-      this.aiConfig.judgeConfiguration?.judges &&
-      this.aiConfig.judgeConfiguration.judges.length > 0
-    ) {
-      response.evaluations = this._evaluateWithJudges(this.messages, response);
-    }
-
-    this.messages.push(response.message);
-    return response;
-  }
-
-  /**
-   * Evaluates the response with all configured judges.
-   * Returns a promise that resolves to an array of evaluation results.
-   *
-   * @param messages Array of messages representing the conversation history
-   * @param response The AI response to be evaluated
-   * @returns Promise resolving to array of judge evaluation results
-   */
-  private async _evaluateWithJudges(
-    messages: LDMessage[],
-    response: ChatResponse,
-  ): Promise<Array<JudgeResponse | undefined>> {
-    const judgeConfigs = this.aiConfig.judgeConfiguration!.judges;
-
-    // Start all judge evaluations in parallel
-    const evaluationPromises = judgeConfigs.map(async (judgeConfig) => {
-      const judge = this.judges[judgeConfig.key];
-      if (!judge) {
-        this._logger?.warn(
-          `Judge configuration is not enabled: ${judgeConfig.key}`,
-          this.tracker.getTrackData(),
-        );
-        return undefined;
-      }
-
-      const judgeResponse = await judge.evaluateMessages(
-        messages,
-        response,
-        judgeConfig.samplingRate,
-      );
-
-      if (judgeResponse && judgeResponse.success) {
-        this.tracker.trackJudgeResponse(judgeResponse);
-      }
-
-      return judgeResponse;
-    });
-
-    // ensure all evaluations complete even if some fail
-    const results = await Promise.allSettled(evaluationPromises);
-
-    return results.map((result) => (result.status === 'fulfilled' ? result.value : undefined));
-  }
-
-  /**
-   * Get the underlying AI configuration used to initialize this TrackedChat.
-   */
-  getConfig(): LDAICompletionConfig {
-    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;
-  }
-
-  /**
-   * Get the judges associated with this TrackedChat.
-   * Returns a record of judge instances keyed by their configuration keys.
-   */
-  getJudges(): Record<string, Judge> {
-    return this.judges;
-  }
-
-  /**
-   * 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

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

package/src/api/chat/types.ts

@@ -1,24 +0,0 @@
-import { LDMessage } from '../config/types';
-import { JudgeResponse } from '../judge/types';
-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;
-
-  /**
-   * Promise that resolves to judge evaluation results.
-   * Only present when judges are configured for evaluation.
-   */
-  evaluations?: Promise<Array<JudgeResponse | undefined>>;
-}

package/src/api/config/LDAIConfigTracker.ts

@@ -1,238 +0,0 @@
-import { EvalScore, JudgeResponse } from '../judge/types';
-import { LDAIMetrics, LDFeedbackKind, LDTokenUsage } from '../metrics';
-
-/**
- * Metrics which have been tracked.
- */
-export interface LDAIMetricSummary {
-  /**
-   * The duration of generation.
-   */
-  durationMs?: number;
-
-  /**
-   * Information about token usage.
-   */
-  tokens?: LDTokenUsage;
-
-  /**
-   * Was generation successful.
-   */
-  success?: boolean;
-
-  /**
-   * Any sentiment about the generation.
-   */
-  feedback?: { kind: LDFeedbackKind };
-
-  /**
-   * Time to first token for this generation.
-   */
-  timeToFirstTokenMs?: number;
-}
-
-/**
- * The LDAIConfigTracker is used to track various details about AI operations.
- */
-export interface LDAIConfigTracker {
-  /**
-   * Get the data for tracking.
-   */
-  getTrackData(): {
-    variationKey: string;
-    configKey: string;
-    version: number;
-    modelName: string;
-    providerName: string;
-    aiSdkName: string;
-    aiSdkVersion: string;
-  };
-  /**
-   * Track the duration of generation.
-   *
-   * Ideally this would not include overhead time such as network communication.
-   *
-   * @param durationMs The duration in milliseconds.
-   */
-  trackDuration(durationMs: number): void;
-
-  /**
-   * Track information about token usage.
-   *
-   * @param tokens Token usage information.
-   */
-  trackTokens(tokens: LDTokenUsage): void;
-
-  /**
-   * Generation was successful.
-   */
-  trackSuccess(): void;
-
-  /**
-   * An error was encountered during generation.
-   */
-  trackError(): void;
-
-  /**
-   * Track sentiment about the generation.
-   *
-   * @param feedback Feedback about the generation.
-   */
-  trackFeedback(feedback: { kind: LDFeedbackKind }): void;
-
-  /**
-   * Track the time to first token for this generation.
-   *
-   * @param timeToFirstTokenMs The duration in milliseconds.
-   */
-  trackTimeToFirstToken(timeToFirstTokenMs: number): void;
-
-  /**
-   * Track evaluation scores for multiple metrics.
-   *
-   * @param scores Record mapping metric keys to their evaluation scores
-   */
-  trackEvalScores(scores: Record<string, EvalScore>): void;
-
-  /**
-   * Track a judge response containing evaluation scores and judge configuration key.
-   *
-   * @param response Judge response containing evaluation scores and judge configuration key
-   */
-  trackJudgeResponse(response: JudgeResponse): void;
-
-  /**
-   * Track the duration of execution of the provided function.
-   *
-   * If the provided function throws, then this method will also throw.
-   * In the case the provided function throws, this function will still record the duration.
-   *
-   * This function does not automatically record an error when the function throws.
-   *
-   * @param func The function to track the duration of.
-   * @returns The result of the function.
-   */
-  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 metrics for a streaming 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.
-   *
-   * Unlike trackMetricsOf, this method is designed for streaming operations where:
-   * - The stream is created and returned immediately (synchronously)
-   * - Metrics are extracted asynchronously in the background once the stream completes
-   * - Duration is tracked from stream creation to metrics extraction completion
-   *
-   * The stream is returned immediately so the caller can begin consuming it without waiting.
-   * Metrics extraction happens in the background and does not block stream consumption.
-   *
-   * If the stream creator throws, then this method will also throw and record an error.
-   * If metrics extraction fails, the error is logged but does not affect stream consumption.
-   *
-   * @param streamCreator Function that creates and returns the stream (synchronous)
-   * @param metricsExtractor Function that asynchronously extracts metrics from the stream
-   * @returns The stream result (returned immediately, not a Promise)
-   */
-  trackStreamMetricsOf<TStream>(
-    streamCreator: () => TStream,
-    metricsExtractor: (stream: TStream) => Promise<LDAIMetrics>,
-  ): TStream;
-
-  /**
-   * Track an OpenAI operation.
-   *
-   * This function will track the duration of the operation, the token usage, and the success or error status.
-   *
-   * 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 func Function which executes the operation.
-   * @returns The result of the operation.
-   */
-  trackOpenAIMetrics<
-    TRes extends {
-      usage?: {
-        total_tokens?: number;
-        prompt_tokens?: number;
-        completion_tokens?: number;
-      };
-    },
-  >(
-    func: () => Promise<TRes>,
-  ): Promise<TRes>;
-
-  /**
-   * Track an operation which uses Bedrock.
-   *
-   * This function will track the duration of the operation, the token usage, and the success or error status.
-   *
-   * @param res The result of the Bedrock operation.
-   * @returns The input operation.
-   */
-  trackBedrockConverseMetrics<
-    TRes extends {
-      $metadata: { httpStatusCode?: number };
-      metrics?: { latencyMs?: number };
-      usage?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-      };
-    },
-  >(
-    res: TRes,
-  ): TRes;
-
-  /**
-   * Track a Vercel AI SDK generateText operation.
-   *
-   * This function will track the duration of the operation, the token usage, and the success or error status.
-   *
-   * 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 func Function which executes the operation.
-   * @returns The result of the operation.
-   */
-  trackVercelAISDKGenerateTextMetrics<
-    TRes extends {
-      usage?: {
-        totalTokens?: number;
-        inputTokens?: number;
-        promptTokens?: number;
-        outputTokens?: number;
-        completionTokens?: number;
-      };
-    },
-  >(
-    func: () => Promise<TRes>,
-  ): Promise<TRes>;
-
-  /**
-   * Get a summary of the tracked metrics.
-   */
-  getSummary(): LDAIMetricSummary;
-}

package/src/api/config/LDAIConfigUtils.ts

@@ -1,212 +0,0 @@
-import { LDAIConfigTracker } from './LDAIConfigTracker';
-import {
-  LDAIAgentConfig,
-  LDAICompletionConfig,
-  LDAIConfigDefaultKind,
-  LDAIConfigKind,
-  LDAIConfigMode,
-  LDAIJudgeConfig,
-  LDJudgeConfiguration,
-  LDMessage,
-  LDModelConfig,
-  LDProviderConfig,
-} from './types';
-
-/**
- * Internal flag value structure returned by LaunchDarkly.
- * This represents the raw data structure that LaunchDarkly returns for AI configuration flags.
- *
- * @internal - Not meant for external use
- */
-export interface LDAIConfigFlagValue {
-  _ldMeta?: {
-    variationKey?: string;
-    enabled: boolean;
-    version?: number;
-    mode?: LDAIConfigMode;
-  };
-  model?: LDModelConfig;
-  messages?: LDMessage[];
-  provider?: LDProviderConfig;
-  instructions?: string;
-  evaluationMetricKeys?: string[];
-  judgeConfiguration?: LDJudgeConfiguration;
-}
-
-/**
- * Utility class for converting between AI configuration types and LaunchDarkly flag values.
- *
- * @internal - This class and its types are internal implementation details and should not be used by SDK consumers.
- */
-export class LDAIConfigUtils {
-  /**
-   * Converts a default AI configuration to a LaunchDarkly flag value format.
-   *
-   * @param config The default AI configuration to convert
-   * @param mode The mode for the configuration
-   * @returns The flag value structure for LaunchDarkly
-   */
-  static toFlagValue(config: LDAIConfigDefaultKind, mode: LDAIConfigMode): LDAIConfigFlagValue {
-    const flagValue: LDAIConfigFlagValue = {
-      _ldMeta: {
-        variationKey: '', // Not available when converting from config
-        enabled: config.enabled ?? false,
-        mode,
-      },
-      model: config.model,
-    };
-
-    if ('messages' in config && config.messages !== undefined) {
-      flagValue.messages = config.messages;
-    }
-    if (config.provider !== undefined) {
-      flagValue.provider = config.provider;
-    }
-    if ('instructions' in config && config.instructions !== undefined) {
-      flagValue.instructions = config.instructions;
-    }
-    if ('evaluationMetricKeys' in config && config.evaluationMetricKeys !== undefined) {
-      flagValue.evaluationMetricKeys = config.evaluationMetricKeys;
-    }
-    if ('judgeConfiguration' in config && config.judgeConfiguration !== undefined) {
-      flagValue.judgeConfiguration = config.judgeConfiguration;
-    }
-
-    return flagValue;
-  }
-
-  /**
-   * Converts a LaunchDarkly flag value to the appropriate AI configuration type.
-   *
-   * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
-   * @returns The appropriate AI configuration type
-   */
-  static fromFlagValue(
-    key: string,
-    flagValue: LDAIConfigFlagValue,
-    tracker: LDAIConfigTracker,
-  ): LDAIConfigKind {
-    // Determine the actual mode from flag value
-    // eslint-disable-next-line no-underscore-dangle
-    const flagValueMode = flagValue._ldMeta?.mode;
-
-    switch (flagValueMode) {
-      case 'agent':
-        return this.toAgentConfig(key, flagValue, tracker);
-      case 'judge':
-        return this.toJudgeConfig(key, flagValue, tracker);
-      case 'completion':
-      default:
-        return this.toCompletionConfig(key, flagValue, tracker);
-    }
-  }
-
-  /**
-   * Creates a disabled configuration of the specified mode.
-   *
-   * @param mode The mode for the disabled config
-   * @returns A disabled config of the appropriate type
-   */
-  static createDisabledConfig(key: string, mode: LDAIConfigMode): LDAIConfigKind {
-    switch (mode) {
-      case 'agent':
-        return {
-          key,
-          enabled: false,
-          tracker: undefined,
-        } as LDAIAgentConfig;
-      case 'judge':
-        return {
-          key,
-          enabled: false,
-          tracker: undefined,
-          evaluationMetricKeys: [],
-        } as LDAIJudgeConfig;
-      case 'completion':
-      default:
-        // Default to completion config for completion mode or any unexpected mode
-        return {
-          key,
-          enabled: false,
-          tracker: undefined,
-        } as LDAICompletionConfig;
-    }
-  }
-
-  /**
-   * Creates the base configuration that all config types share.
-   *
-   * @param flagValue The flag value from LaunchDarkly
-   * @returns Base configuration object
-   */
-  private static _toBaseConfig(key: string, flagValue: LDAIConfigFlagValue) {
-    return {
-      key,
-      // eslint-disable-next-line no-underscore-dangle
-      enabled: flagValue._ldMeta?.enabled ?? false,
-      model: flagValue.model,
-      provider: flagValue.provider,
-    };
-  }
-
-  /**
-   * Creates a completion config from flag value data.
-   *
-   * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
-   * @returns A completion configuration
-   */
-  static toCompletionConfig(
-    key: string,
-    flagValue: LDAIConfigFlagValue,
-    tracker: LDAIConfigTracker,
-  ): LDAICompletionConfig {
-    return {
-      ...this._toBaseConfig(key, flagValue),
-      tracker,
-      messages: flagValue.messages,
-      judgeConfiguration: flagValue.judgeConfiguration,
-    };
-  }
-
-  /**
-   * Creates an agent config from flag value data.
-   *
-   * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
-   * @returns An agent configuration
-   */
-  static toAgentConfig(
-    key: string,
-    flagValue: LDAIConfigFlagValue,
-    tracker: LDAIConfigTracker,
-  ): LDAIAgentConfig {
-    return {
-      ...this._toBaseConfig(key, flagValue),
-      tracker,
-      instructions: flagValue.instructions,
-      judgeConfiguration: flagValue.judgeConfiguration,
-    };
-  }
-
-  /**
-   * Creates a judge config from flag value data.
-   *
-   * @param flagValue The flag value from LaunchDarkly
-   * @param tracker The tracker to add to the config
-   * @returns A judge configuration
-   */
-  static toJudgeConfig(
-    key: string,
-    flagValue: LDAIConfigFlagValue,
-    tracker: LDAIConfigTracker,
-  ): LDAIJudgeConfig {
-    return {
-      ...this._toBaseConfig(key, flagValue),
-      tracker,
-      messages: flagValue.messages,
-      evaluationMetricKeys: flagValue.evaluationMetricKeys || [],
-    };
-  }
-}

package/src/api/config/index.ts

@@ -1,3 +0,0 @@
-export * from './types';
-// LDAIConfigUtils is intentionally not exported - it's an internal utility class
-export { LDAIConfigTracker } from './LDAIConfigTracker';