@launchdarkly/server-sdk-ai 0.14.1 → 0.15.0

package/src/LDAIConfigTrackerImpl.ts

@@ -1,288 +0,0 @@
-import { LDContext } from '@launchdarkly/js-server-sdk-common';
-
-import { name as aiSdkName, version as aiSdkVersion } from '../package.json';
-import { LDAIConfigTracker } from './api/config';
-import { LDAIMetricSummary } from './api/config/LDAIConfigTracker';
-import { EvalScore, JudgeResponse } from './api/judge/types';
-import {
-  createBedrockTokenUsage,
-  createOpenAiUsage,
-  createVercelAISDKTokenUsage,
-  LDAIMetrics,
-  LDFeedbackKind,
-  LDTokenUsage,
-} from './api/metrics';
-import { LDClientMin } from './LDClientMin';
-
-export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
-  private _trackedMetrics: LDAIMetricSummary = {};
-
-  constructor(
-    private _ldClient: LDClientMin,
-    private _configKey: string,
-    private _variationKey: string,
-    private _version: number,
-    private _modelName: string,
-    private _providerName: string,
-    private _context: LDContext,
-  ) {}
-
-  getTrackData(): {
-    variationKey: string;
-    configKey: string;
-    version: number;
-    modelName: string;
-    providerName: string;
-    aiSdkName: string;
-    aiSdkVersion: string;
-  } {
-    return {
-      variationKey: this._variationKey,
-      configKey: this._configKey,
-      version: this._version,
-      modelName: this._modelName,
-      providerName: this._providerName,
-      aiSdkName,
-      aiSdkVersion,
-    };
-  }
-
-  trackDuration(duration: number): void {
-    this._trackedMetrics.durationMs = duration;
-    this._ldClient.track('$ld:ai:duration:total', this._context, this.getTrackData(), duration);
-  }
-
-  async trackDurationOf<TRes>(func: () => Promise<TRes>): Promise<TRes> {
-    const startTime = Date.now();
-    try {
-      // Be sure to await here so that we can track the duration of the function and also handle errors.
-      const result = await func();
-      return result;
-    } finally {
-      const endTime = Date.now();
-      const duration = endTime - startTime; // duration in milliseconds
-      this.trackDuration(duration);
-    }
-  }
-
-  trackTimeToFirstToken(timeToFirstTokenMs: number) {
-    this._trackedMetrics.timeToFirstTokenMs = timeToFirstTokenMs;
-    this._ldClient.track(
-      '$ld:ai:tokens:ttf',
-      this._context,
-      this.getTrackData(),
-      timeToFirstTokenMs,
-    );
-  }
-
-  trackEvalScores(scores: Record<string, EvalScore>) {
-    Object.entries(scores).forEach(([metricKey, evalScore]) => {
-      this._ldClient.track(metricKey, this._context, this.getTrackData(), evalScore.score);
-    });
-  }
-
-  trackJudgeResponse(response: JudgeResponse) {
-    Object.entries(response.evals).forEach(([metricKey, evalScore]) => {
-      this._ldClient.track(
-        metricKey,
-        this._context,
-        { ...this.getTrackData(), judgeConfigKey: response.judgeConfigKey },
-        evalScore.score,
-      );
-    });
-  }
-
-  trackFeedback(feedback: { kind: LDFeedbackKind }): void {
-    this._trackedMetrics.feedback = feedback;
-    if (feedback.kind === LDFeedbackKind.Positive) {
-      this._ldClient.track('$ld:ai:feedback:user:positive', this._context, this.getTrackData(), 1);
-    } else if (feedback.kind === LDFeedbackKind.Negative) {
-      this._ldClient.track('$ld:ai:feedback:user:negative', this._context, this.getTrackData(), 1);
-    }
-  }
-
-  trackSuccess(): void {
-    this._trackedMetrics.success = true;
-    this._ldClient.track('$ld:ai:generation:success', this._context, this.getTrackData(), 1);
-  }
-
-  trackError(): void {
-    this._trackedMetrics.success = false;
-    this._ldClient.track('$ld:ai:generation:error', this._context, this.getTrackData(), 1);
-  }
-
-  async trackMetricsOf<TRes>(
-    metricsExtractor: (result: TRes) => LDAIMetrics,
-    func: () => Promise<TRes>,
-  ): Promise<TRes> {
-    let result: TRes;
-
-    try {
-      result = await this.trackDurationOf(func);
-    } catch (err) {
-      this.trackError();
-      throw err;
-    }
-
-    // Extract metrics after successful AI call
-    const metrics = metricsExtractor(result);
-
-    // Track success/error based on metrics
-    if (metrics.success) {
-      this.trackSuccess();
-    } else {
-      this.trackError();
-    }
-
-    // Track token usage if available
-    if (metrics.usage) {
-      this.trackTokens(metrics.usage);
-    }
-
-    return result;
-  }
-
-  trackStreamMetricsOf<TStream>(
-    streamCreator: () => TStream,
-    metricsExtractor: (stream: TStream) => Promise<LDAIMetrics>,
-  ): TStream {
-    const startTime = Date.now();
-
-    try {
-      // Create the stream synchronously
-      const stream = streamCreator();
-
-      // Start background metrics tracking (fire and forget)
-      this._trackStreamMetricsInBackground(stream, metricsExtractor, startTime);
-
-      // Return stream immediately for consumption
-      return stream;
-    } catch (error) {
-      // Track error if stream creation fails
-      this.trackDuration(Date.now() - startTime);
-      this.trackError();
-      throw error;
-    }
-  }
-
-  private async _trackStreamMetricsInBackground<TStream>(
-    stream: TStream,
-    metricsExtractor: (stream: TStream) => Promise<LDAIMetrics>,
-    startTime: number,
-  ): Promise<void> {
-    try {
-      // Wait for metrics to be available
-      const metrics = await metricsExtractor(stream);
-
-      // Track success/error based on metrics
-      if (metrics.success) {
-        this.trackSuccess();
-      } else {
-        this.trackError();
-      }
-
-      // Track token usage if available
-      if (metrics.usage) {
-        this.trackTokens(metrics.usage);
-      }
-    } catch (error) {
-      // If metrics extraction fails, track error
-      this.trackError();
-    } finally {
-      // Track duration regardless of success/error
-      this.trackDuration(Date.now() - startTime);
-    }
-  }
-
-  async trackOpenAIMetrics<
-    TRes extends {
-      usage?: {
-        total_tokens?: number;
-        prompt_tokens?: number;
-        completion_tokens?: number;
-      };
-    },
-  >(func: () => Promise<TRes>): Promise<TRes> {
-    try {
-      const result = await this.trackDurationOf(func);
-      this.trackSuccess();
-      if (result.usage) {
-        this.trackTokens(createOpenAiUsage(result.usage));
-      }
-      return result;
-    } catch (err) {
-      this.trackError();
-      throw err;
-    }
-  }
-
-  trackBedrockConverseMetrics<
-    TRes extends {
-      $metadata: { httpStatusCode?: number };
-      metrics?: { latencyMs?: number };
-      usage?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-      };
-    },
-  >(res: TRes): TRes {
-    if (res.$metadata?.httpStatusCode === 200) {
-      this.trackSuccess();
-    } else if (res.$metadata?.httpStatusCode && res.$metadata.httpStatusCode >= 400) {
-      this.trackError();
-    }
-    if (res.metrics && res.metrics.latencyMs) {
-      this.trackDuration(res.metrics.latencyMs);
-    }
-    if (res.usage) {
-      this.trackTokens(createBedrockTokenUsage(res.usage));
-    }
-    return res;
-  }
-
-  async trackVercelAISDKGenerateTextMetrics<
-    TRes extends {
-      usage?: {
-        totalTokens?: number;
-        inputTokens?: number;
-        promptTokens?: number;
-        outputTokens?: number;
-        completionTokens?: number;
-      };
-    },
-  >(func: () => Promise<TRes>): Promise<TRes> {
-    try {
-      const result = await this.trackDurationOf(func);
-      this.trackSuccess();
-      if (result.usage) {
-        this.trackTokens(createVercelAISDKTokenUsage(result.usage));
-      }
-      return result;
-    } catch (err) {
-      this.trackError();
-      throw err;
-    }
-  }
-
-  trackTokens(tokens: LDTokenUsage): void {
-    this._trackedMetrics.tokens = tokens;
-    const trackData = this.getTrackData();
-    if (tokens.total > 0) {
-      this._ldClient.track('$ld:ai:tokens:total', this._context, trackData, tokens.total);
-    }
-    if (tokens.input > 0) {
-      this._ldClient.track('$ld:ai:tokens:input', this._context, trackData, tokens.input);
-    }
-    if (tokens.output > 0) {
-      this._ldClient.track('$ld:ai:tokens:output', this._context, trackData, tokens.output);
-    }
-  }
-
-  /**
-   * Get a summary of the tracked metrics.
-   */
-  getSummary(): LDAIMetricSummary {
-    return { ...this._trackedMetrics };
-  }
-}

package/src/LDClientMin.ts

@@ -1,18 +0,0 @@
-import { LDContext, LDFlagValue, LDLogger } from '@launchdarkly/js-server-sdk-common';
-
-/**
- * Interface which represents the required interface components for a sever SDK
- * to work with the AI SDK.
- */
-export interface LDClientMin {
-  variation(
-    key: string,
-    context: LDContext,
-    defaultValue: LDFlagValue,
-    callback?: (err: any, res: LDFlagValue) => void,
-  ): Promise<LDFlagValue>;
-
-  track(key: string, context: LDContext, data?: any, metricValue?: number): void;
-
-  readonly logger?: LDLogger;
-}

package/src/api/LDAIClient.ts

@@ -1,325 +0,0 @@
-import { LDContext } from '@launchdarkly/js-server-sdk-common';
-
-import { TrackedChat } from './chat';
-import {
-  LDAIAgentConfig,
-  LDAIAgentConfigDefault,
-  LDAIAgentRequestConfig,
-  LDAICompletionConfig,
-  LDAICompletionConfigDefault,
-  LDAIJudgeConfig,
-  LDAIJudgeConfigDefault,
-} from './config';
-import { Judge } from './judge/Judge';
-import { SupportedAIProvider } from './providers';
-
-/**
- * Interface for performing AI operations using LaunchDarkly.
- */
-export interface LDAIClient {
-  /**
-   * Retrieves and processes a completion AI Config based on the provided key, LaunchDarkly context,
-   * and variables. This includes the model configuration and the customized messages.
-   *
-   * @param key The key of the AI Config.
-   * @param context The LaunchDarkly context object that contains relevant information about the
-   * current environment, user, or session. This context may influence how the configuration is
-   * processed or personalized.
-   * @param defaultValue A fallback value containing model configuration and messages. This will
-   * be used if the configuration is not available from LaunchDarkly.
-   * @param variables A map of key-value pairs representing dynamic variables to be injected into
-   * the message content. The keys correspond to placeholders within the template, and the values
-   * are the corresponding replacements.
-   *
-   * @returns The AI `config`, customized `messages`, and a `tracker`. If the configuration cannot be accessed from
-   * LaunchDarkly, then the return value will include information from the `defaultValue`. The returned `tracker` can
-   * be used to track AI operation metrics (latency, token usage, etc.).
-   *
-   * @example
-   * ```
-   * const key = "welcome_prompt";
-   * const context = {...};
-   * const variables = {username: 'john'};
-   * const defaultValue = {
-   *  enabled: false,
-   *  model: { name: 'gpt-4' },
-   *  provider: { name: 'openai' },
-   * };
-   *
-   * const result = completionConfig(key, context, defaultValue, variables);
-   * // Output:
-   * {
-   *   enabled: true,
-   *   config: {
-   *     modelId: "gpt-4o",
-   *     temperature: 0.2,
-   *     maxTokens: 4096,
-   *     userDefinedKey: "myValue",
-   *   },
-   *   messages: [
-   *     {
-   *       role: "system",
-   *       content: "You are an amazing GPT."
-   *     },
-   *     {
-   *       role: "user",
-   *       content: "Explain how you're an amazing GPT."
-   *     }
-   *   ],
-   *   tracker: ...
-   * }
-   * ```
-   */
-  completionConfig(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAICompletionConfigDefault,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAICompletionConfig>;
-
-  /**
-   * @deprecated Use `completionConfig` instead. This method will be removed in a future version.
-   */
-  config(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAICompletionConfigDefault,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAICompletionConfig>;
-
-  /**
-   * Retrieves and processes a single AI Config agent based on the provided key, LaunchDarkly context,
-   * and variables. This includes the model configuration and the customized instructions.
-   *
-   * @param key The key of the AI Config agent.
-   * @param context The LaunchDarkly context object that contains relevant information about the
-   * current environment, user, or session. This context may influence how the configuration is
-   * processed or personalized.
-   * @param defaultValue A fallback value containing model configuration and instructions.
-   * @param variables A map of key-value pairs representing dynamic variables to be injected into
-   * the instructions. The keys correspond to placeholders within the template, and the values
-   * are the corresponding replacements.
-   *
-   * @returns An AI agent with customized `instructions` and a `tracker`. If the configuration
-   * cannot be accessed from LaunchDarkly, then the return value will include information from the
-   * `defaultValue`. The returned `tracker` can be used to track AI operation metrics (latency, token usage, etc.).
-   *
-   * @example
-   * ```
-   * const key = "research_agent";
-   * const context = {...};
-   * const variables = { topic: 'climate change' };
-   * const agentConfig = await client.agentConfig(key, context, {
-   *   enabled: true,
-   *   model: { name: 'gpt-4' },
-   *   provider: { name: 'openai' },
-   *   instructions: 'You are a research assistant.',
-   * }, variables);
-   *
-   * const researchResult = agentConfig.instructions; // Interpolated instructions
-   * agentConfig.tracker.trackSuccess();
-   * ```
-   */
-  agentConfig(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAIAgentConfigDefault,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAIAgentConfig>;
-
-  /**
-   * @deprecated Use `agentConfig` instead. This method will be removed in a future version.
-   */
-  agent(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAIAgentConfigDefault,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAIAgentConfig>;
-
-  /**
-   * Retrieves and processes a Judge AI Config based on the provided key, LaunchDarkly context,
-   * and variables. This includes the model configuration and the customized messages for evaluation.
-   *
-   * @param key The key of the Judge AI Config.
-   * @param context The LaunchDarkly context object that contains relevant information about the
-   * current environment, user, or session. This context may influence how the configuration is
-   * processed or personalized.
-   * @param defaultValue A fallback value containing model configuration and messages. This will
-   * be used if the configuration is not available from LaunchDarkly.
-   * @param variables Optional variables for template interpolation in messages and instructions.
-   * @returns A promise that resolves to a tracked judge configuration.
-   *
-   * @example
-   * ```typescript
-   * const judgeConf = await client.judgeConfig(key, context, {
-   *   enabled: true,
-   *   model: { name: 'gpt-4' },
-   *   provider: { name: 'openai' },
-   *   evaluationMetricKeys: ['$ld:ai:judge:relevance'],
-   *   messages: [{ role: 'system', content: 'You are a relevance judge.' }]
-   * }, variables);
-   *
-   * const config = judgeConf.config; // Interpolated configuration
-   * judgeConf.tracker.trackSuccess();
-   * ```
-   */
-  judgeConfig(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAIJudgeConfigDefault,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAIJudgeConfig>;
-
-  /**
-   * Retrieves and processes multiple AI Config agents based on the provided agent configurations
-   * and LaunchDarkly context. This includes the model configuration and the customized instructions.
-   *
-   * @param agentConfigs An array of agent configurations, each containing the agent key, default configuration,
-   * and variables for instructions interpolation.
-   * @param context The LaunchDarkly context object that contains relevant information about the
-   * current environment, user, or session. This context may influence how the configuration is
-   * processed or personalized.
-   *
-   * @returns A map of agent keys to their respective AI agents with customized `instructions` and `tracker`.
-   * If a configuration cannot be accessed from LaunchDarkly, then the return value will include information
-   * from the respective `defaultValue`. The returned `tracker` can be used to track AI operation metrics
-   * (latency, token usage, etc.).
-   *
-   * @example
-   * ```
-   * const agentConfigsList = [
-   *   {
-   *     key: 'research_agent',
-   *     defaultValue: {
-   *       enabled: true,
-   *       model: { name: 'gpt-4' },
-   *       provider: { name: 'openai' },
-   *       instructions: 'You are a research assistant.'
-   *     },
-   *     variables: { topic: 'climate change' }
-   *   },
-   *   {
-   *     key: 'writing_agent',
-   *     defaultValue: {
-   *       enabled: true,
-   *       model: { name: 'gpt-4' },
-   *       provider: { name: 'openai' },
-   *       instructions: 'You are a writing assistant.'
-   *     },
-   *     variables: { style: 'academic' }
-   *   }
-   * ] as const;
-   * const context = {...};
-   *
-   * const configs = await client.agentConfigs(agentConfigsList, context);
-   * const researchResult = configs["research_agent"].instructions; // Interpolated instructions
-   * configs["research_agent"].tracker.trackSuccess();
-   * ```
-   */
-  agentConfigs<const T extends readonly LDAIAgentRequestConfig[]>(
-    agentConfigs: T,
-    context: LDContext,
-  ): Promise<Record<T[number]['key'], LDAIAgentConfig>>;
-
-  /**
-   * @deprecated Use `agentConfigs` instead. This method will be removed in a future version.
-   */
-  agents<const T extends readonly LDAIAgentRequestConfig[]>(
-    agentConfigs: T,
-    context: LDContext,
-  ): Promise<Record<T[number]['key'], LDAIAgentConfig>>;
-
-  /**
-   * Returns a TrackedChat instance for chat interactions.
-   * This method serves as the primary entry point for creating TrackedChat instances from configuration.
-   *
-   * @param key The key identifying the AI chat configuration to use.
-   * @param context The standard LDContext used when evaluating flags.
-   * @param defaultValue A default value representing a standard AI chat config result.
-   * @param variables Dictionary of values for instruction interpolation.
-   * The variables will also be used for judge evaluation. For the judge only, the variables
-   * `message_history` and `response_to_evaluate` are reserved and will be ignored.
-   * @param defaultAiProvider Optional default AI provider to use.
-   * @returns A promise that resolves to the TrackedChat instance, or null if the configuration is disabled.
-   *
-   * @example
-   * ```
-   * const key = "customer_support_chat";
-   * const context = {...};
-   * const defaultValue = {
-   *   enabled: false,
-   *   model: { name: "gpt-4" },
-   *   provider: { name: "openai" },
-   *   messages: [
-   *     { role: "system", content: "You are a helpful customer support agent." }
-   *   ]
-   * };
-   * const variables = { customerName: 'John' };
-   *
-   * const chat = await client.createChat(key, context, defaultValue, variables);
-   * if (chat) {
-   *   const response = await chat.invoke("I need help with my order");
-   *   console.log(response.message.content);
-   * }
-   * ```
-   */
-  createChat(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAICompletionConfigDefault,
-    variables?: Record<string, unknown>,
-    defaultAiProvider?: SupportedAIProvider,
-  ): Promise<TrackedChat | undefined>;
-
-  /**
-   * @deprecated Use `createChat` instead. This method will be removed in a future version.
-   */
-  initChat(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAICompletionConfigDefault,
-    variables?: Record<string, unknown>,
-    defaultAiProvider?: SupportedAIProvider,
-  ): Promise<TrackedChat | undefined>;
-
-  /**
-   * Creates and returns a new Judge instance for AI evaluation.
-   *
-   * @param key The key identifying the AI judge configuration to use
-   * @param context Standard LDContext used when evaluating flags
-   * @param defaultValue A default value representing a standard AI config result
-   * @param variables Dictionary of values for instruction interpolation.
-   * The variables `message_history` and `response_to_evaluate` are reserved for the judge and will be ignored.
-   * @param defaultAiProvider Optional default AI provider to use.
-   * @returns Promise that resolves to a Judge instance or undefined if disabled/unsupported
-   *
-   * @example
-   * ```
-   * const judge = await client.createJudge(
-   *   "relevance-judge",
-   *   context,
-   *   {
-   *     enabled: true,
-   *     model: { name: "gpt-4" },
-   *     provider: { name: "openai" },
-   *     evaluationMetricKeys: ['$ld:ai:judge:relevance'],
-   *     messages: [{ role: 'system', content: 'You are a relevance judge.' }]
-   *   },
-   *   { metric: "relevance" }
-   * );
-   *
-   * if (judge) {
-   *   const result = await judge.evaluate("User question", "AI response");
-   *   console.log('Relevance score:', result.evals.relevance?.score);
-   * }
-   * ```
-   */
-  createJudge(
-    key: string,
-    context: LDContext,
-    defaultValue: LDAIJudgeConfigDefault,
-    variables?: Record<string, unknown>,
-    defaultAiProvider?: SupportedAIProvider,
-  ): Promise<Judge | undefined>;
-}