Refine typing.

Author: kinyoklion

packages/sdk/ai/examples/bedrock/src/index.ts

@@ -29,11 +29,6 @@ const context = {
 
 console.log('*** SDK successfully initialized');
 
-interface MyModelConfig {
-  modelId: string;
-  prompt: { role: ConversationRole; content: string }[];
-}
-
 function mapPromptToConversation(prompt: { role: ConversationRole; content: string }[]): Message[] {
   return prompt.map((item) => ({
     role: item.role,
@@ -64,12 +59,11 @@ async function main() {
   }
 
   if (tracker) {
-    const modelConfig = configValue.config as MyModelConfig;
     const completion = await tracker.trackBedrockConverse(
       await awsClient.send(
         new ConverseCommand({
-          modelId: modelConfig.modelId,
-          messages: mapPromptToConversation(modelConfig.prompt),
+          modelId: configValue.config?.model?.modelId ?? 'default model',
+          messages: mapPromptToConversation(modelConfig?.prompt ?? 'default prompt'),
         }),
       ),
     );

packages/sdk/ai/src/LDAIConfigTrackerImpl.ts

@@ -1,25 +1,25 @@
 import { LDClient, LDContext } from '@launchdarkly/node-server-sdk';
 
 import { LDAIConfigTracker } from './api/config';
-import { createBedrockTokenUsage, FeedbackKind, TokenUsage } from './api/metrics';
+import { createBedrockTokenUsage, LDFeedbackKind, LDTokenUsage } from './api/metrics';
 import { createOpenAiUsage } from './api/metrics/OpenAiUsage';
 
 export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
   private _ldClient: LDClient;
-  private _variationId: string;
+  private _versionId: string;
   private _configKey: string;
   private _context: LDContext;
 
   constructor(ldClient: LDClient, configKey: string, versionId: string, context: LDContext) {
     this._ldClient = ldClient;
-    this._variationId = versionId;
+    this._versionId = versionId;
     this._configKey = configKey;
     this._context = context;
   }
 
-  private _getTrackData(): { variationId: string; configKey: string } {
+  private _getTrackData(): { versionId: string; configKey: string } {
     return {
-      variationId: this._variationId,
+      versionId: this._versionId,
       configKey: this._configKey,
     };
   }
@@ -37,44 +37,42 @@ export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
     return result;
   }
 
-  trackError(error: number): void {
-    this._ldClient.track('$ld:ai:error', this._context, this._getTrackData(), error);
-  }
-
-  trackFeedback(feedback: { kind: FeedbackKind }): void {
-    if (feedback.kind === FeedbackKind.Positive) {
+  trackFeedback(feedback: { kind: LDFeedbackKind }): void {
+    if (feedback.kind === LDFeedbackKind.Positive) {
       this._ldClient.track('$ld:ai:feedback:user:positive', this._context, this._getTrackData(), 1);
-    } else if (feedback.kind === FeedbackKind.Negative) {
+    } else if (feedback.kind === LDFeedbackKind.Negative) {
       this._ldClient.track('$ld:ai:feedback:user:negative', this._context, this._getTrackData(), 1);
     }
   }
 
-  trackGeneration(generation: number): void {
-    this._ldClient.track('$ld:ai:generation', this._context, this._getTrackData(), generation);
+  trackSuccess(): void {
+    this._ldClient.track('$ld:ai:generation', this._context, this._getTrackData(), 1);
   }
 
-  async trackOpenAI(func: (...args: any[]) => Promise<any>, ...args: any[]): Promise<any> {
+  async trackOpenAI<TRes>(func: (...args: any[]) => Promise<TRes>, ...args: any[]): Promise<TRes> {
     const result = await this.trackDurationOf(func, ...args);
-    this.trackGeneration(1);
+    this.trackSuccess();
     if (result.usage) {
       this.trackTokens(createOpenAiUsage(result.usage));
     }
     return result;
   }
 
-  async trackBedrockConverse(res: {
-    $metadata?: { httpStatusCode: number };
-    metrics?: { latencyMs: number };
-    usage?: {
-      inputTokens: number;
-      outputTokens: number;
-      totalTokens: number;
-    };
-  }): Promise<any> {
+  trackBedrockConverse<
+    TRes extends {
+      $metadata?: { httpStatusCode: number };
+      metrics?: { latencyMs: number };
+      usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+      };
+    },
+  >(res: TRes): TRes {
     if (res.$metadata?.httpStatusCode === 200) {
-      this.trackGeneration(1);
+      this.trackSuccess();
     } else if (res.$metadata?.httpStatusCode && res.$metadata.httpStatusCode >= 400) {
-      this.trackError(res.$metadata.httpStatusCode);
+      // this.trackError(res.$metadata.httpStatusCode);
     }
     if (res.metrics) {
       this.trackDuration(res.metrics.latencyMs);
@@ -85,7 +83,7 @@ export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
     return res;
   }
 
-  trackTokens(tokens: TokenUsage): void {
+  trackTokens(tokens: LDTokenUsage): void {
     const trackData = this._getTrackData();
     if (tokens.total > 0) {
       this._ldClient.track('$ld:ai:tokens:total', this._context, trackData, tokens.total);

packages/sdk/ai/src/api/AIClient.ts

@@ -0,0 +1,69 @@
+import { LDContext } from '@launchdarkly/node-server-sdk';
+import { LDAIConfig, LDGenerationConfig } from './config/LDAIConfig';
+
+/**
+ * Interface for performing AI operations using LaunchDarkly.
+ */
+
+export interface AIClient {
+  /**
+   * Parses and interpolates a template string with the provided variables.
+   *
+   * @param template - The template string to be parsed and interpolated.
+   * @param variables - An object containing the variables to be used for interpolation.
+   * @returns The interpolated string.
+   */
+  interpolateTemplate(template: string, variables: Record<string, unknown>): string;
+
+  /**
+   * Retrieves and processes a prompt template based on the provided key, LaunchDarkly context, and
+   * variables.
+   *
+   * @param key - A unique identifier for the prompt template. This key is used to fetch the correct
+   *  prompt from storage or configuration.
+   * @param context - The LaunchDarkly context object that contains relevant information about the
+   * current environment, user, or session. This context may influence how the prompt is processed
+   * or personalized.
+   * @param variables - A map of key-value pairs representing dynamic variables to be injected into
+   * the prompt template. The keys correspond to placeholders within the template, and the values
+   * are the corresponding replacements.
+   * @param defaultValue - A fallback value to be used if the prompt template associated with the
+   * key is not found or if any errors occur during processing.
+   *
+   * @returns The processed prompt after all variables have been substituted in the stored prompt
+   * template. If the prompt cannot be retrieved or processed, the `defaultValue` is returned.
+   *
+   * @example
+   * ```
+   * const key = "welcome_prompt";
+   * const context = {...};
+   * const variables = {username: 'john'};
+   * const defaultValue = {};
+   *
+   * const result = modelConfig(key, context, defaultValue, variables);
+   * // Output:
+   * {
+   *   modelId: "gpt-4o",
+   *   temperature: 0.2,
+   *   maxTokens: 4096,
+   *   userDefinedKey: "myValue",
+   *   prompt: [
+   *     {
+   *       role: "system",
+   *       content: "You are an amazing GPT."
+   *     },
+   *     {
+   *       role: "user",
+   *       content: "Explain how you're an amazing GPT."
+   *     }
+   *   ]
+   * }
+   * ```
+   */
+  modelConfig<TDefault extends LDGenerationConfig>(
+    key: string,
+    context: LDContext,
+    defaultValue: TDefault,
+    variables?: Record<string, unknown>,
+  ): Promise<LDAIConfig>;
+}

packages/sdk/ai/src/api/config/LDAIConfig.ts

@@ -1,13 +1,56 @@
 import { LDAIConfigTracker } from './LDAIConfigTracker';
 
+/**
+ * Configuration related to the model.
+ */
+export interface LDModelConfig {
+  /**
+   * The ID of the model.
+   */
+  modelId?: string;
+
+  /**
+   * And additional model specific information.
+   */
+  [index: string]: unknown;
+}
+
+/**
+ * Information about prompts.
+ */
+export interface LDPrompt {
+  /**
+   * The role of the prompt.
+   */
+  role: 'user' | 'assistant' | 'system';
+  /**
+   * Content for the prompt.
+   */
+  content: string;
+}
+
+/**
+ * Configuration which affects generation.
+ */
+export interface LDGenerationConfig {
+  /**
+   * Optional model configuration.
+   */
+  model?: LDModelConfig;
+  /**
+   * Optional prompt data.
+   */
+  prompt?: LDPrompt[];
+}
+
 /**
  * AI Config value and tracker.
  */
 export interface LDAIConfig {
   /**
    * The result of the AI Config customization.
    */
-  config: unknown;
+  config: LDGenerationConfig;
 
   /**
    * A tracker which can be used to generate analytics.

packages/sdk/ai/src/api/config/LDAIConfigTracker.ts

@@ -1,12 +1,71 @@
-import { FeedbackKind, TokenUsage } from '../metrics';
+import { LDFeedbackKind, LDTokenUsage } from '../metrics';
 
+/**
+ * The LDAIConfigTracker is used to track various details about AI operations.
+ */
 export interface LDAIConfigTracker {
-  trackDuration: (duration: number) => void;
-  trackTokens: (tokens: TokenUsage) => void;
-  trackError: (error: number) => void;
-  trackGeneration: (generation: number) => void;
-  trackFeedback: (feedback: { kind: FeedbackKind }) => void;
-  trackDurationOf: (func: (...args: any[]) => Promise<any>, ...args: any[]) => Promise<any>;
-  trackOpenAI: (func: (...args: any[]) => Promise<any>, ...args: any[]) => any;
-  trackBedrockConverse: (res: any) => any;
+  /**
+   * 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;
+
+  /**
+   * Track sentiment about the generation.
+   *
+   * @param feedback Feedback about the generation.
+   */
+  trackFeedback(feedback: { kind: LDFeedbackKind }): void;
+
+  /**
+   * Track the duration of execution of the provided function.
+   * @param func The function to track the duration of.
+   * @param args Arguments for the function.
+   * @returns The result of the function.
+   */
+  trackDurationOf(func: (...args: any[]) => Promise<any>, ...args: any[]): Promise<any>;
+
+  /**
+   * Track an OpenAI operation.
+   *
+   * @param func Function which executes the operation.
+   * @param args Arguments for the operation.
+   * @returns The result of the operation.
+   */
+  trackOpenAI<TRes>(func: (...args: any[]) => Promise<TRes>, ...args: any[]): Promise<TRes>;
+
+  /**
+   * Track an operation which uses Bedrock.
+   *
+   * @param res The result of the Bedrock operation.
+   * @returns The input operation.
+   */
+  trackBedrockConverse<
+    TRes extends {
+      $metadata?: { httpStatusCode: number };
+      metrics?: { latencyMs: number };
+      usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+      };
+    },
+  >(
+    res: TRes,
+  ): TRes;
 }

packages/sdk/ai/src/api/index.ts

@@ -1,2 +1,3 @@
 export * from './config';
 export * from './metrics';
+export * from './AIClient';

packages/sdk/ai/src/api/metrics/BedrockTokenUsage.ts

@@ -1,10 +1,10 @@
-import { TokenUsage } from './TokenUsage';
+import { LDTokenUsage } from './LDTokenUsage';
 
 export function createBedrockTokenUsage(data: {
   totalTokens: number;
   inputTokens: number;
   outputTokens: number;
-}): TokenUsage {
+}): LDTokenUsage {
   return {
     total: data.totalTokens || 0,
     input: data.inputTokens || 0,

packages/sdk/ai/src/api/metrics/FeedbackKind.ts

@@ -0,0 +1,13 @@
+/**
+ * Feedback about the generated content.
+ */
+export enum LDFeedbackKind {
+  /**
+   * The sentiment was positive.
+   */
+  Positive = 'positive',
+  /**
+   * The sentiment is negative.
+   */
+  Negative = 'negative',
+}

packages/sdk/ai/src/api/metrics/LDFeedbackKind.ts

@@ -0,0 +1,19 @@
+/**
+ * Information about token usage.
+ */
+export interface LDTokenUsage {
+  /**
+   * Combined token usage.
+   */
+  total: number;
+
+  /**
+   * Number of tokens in the input.
+   */
+  input: number;
+
+  /**
+   * Number of tokens in the output.
+   */
+  output: number;
+}