@launchdarkly/server-sdk-ai 0.10.1 → 0.11.0

package/src/LDAIClientImpl.ts

@@ -2,8 +2,10 @@ import * as Mustache from 'mustache';
 
 import { LDContext } from '@launchdarkly/js-server-sdk-common';
 
+import { LDAIAgent, LDAIAgentConfig, LDAIAgentDefaults } from './api/agents';
 import {
   LDAIConfig,
+  LDAIConfigTracker,
   LDAIDefaults,
   LDMessage,
   LDModelConfig,
@@ -17,13 +19,16 @@ import { LDAIConfigMapper } from './LDAIConfigMapper';
 import { LDAIConfigTrackerImpl } from './LDAIConfigTrackerImpl';
 import { LDClientMin } from './LDClientMin';
 
+type Mode = 'completion' | 'agent';
+
 /**
- * Metadata assorted with a model configuration variation.
+ * Metadata associated with a model configuration variation.
  */
 interface LDMeta {
   variationKey: string;
   enabled: boolean;
   version?: number;
+  mode?: Mode;
 }
 
 /**
@@ -33,10 +38,24 @@ interface LDMeta {
 interface VariationContent {
   model?: LDModelConfig;
   messages?: LDMessage[];
+  instructions?: string;
   provider?: LDProviderConfig;
   _ldMeta?: LDMeta;
 }
 
+/**
+ * The result of evaluating a configuration.
+ */
+interface EvaluationResult {
+  tracker: LDAIConfigTracker;
+  enabled: boolean;
+  model?: LDModelConfig;
+  provider?: LDProviderConfig;
+  messages?: LDMessage[];
+  instructions?: string;
+  mode?: string;
+}
+
 export class LDAIClientImpl implements LDAIClient {
   constructor(private _ldClient: LDClientMin) {}
 
@@ -44,13 +63,13 @@ export class LDAIClientImpl implements LDAIClient {
     return Mustache.render(template, variables, undefined, { escape: (item: any) => item });
   }
 
-  async config(
+  private async _evaluate(
     key: string,
     context: LDContext,
     defaultValue: LDAIDefaults,
-    variables?: Record<string, unknown>,
-  ): Promise<LDAIConfig> {
+  ): Promise<EvaluationResult> {
     const value: VariationContent = await this._ldClient.variation(key, context, defaultValue);
+
     const tracker = new LDAIConfigTrackerImpl(
       this._ldClient,
       key,
@@ -58,26 +77,100 @@ export class LDAIClientImpl implements LDAIClient {
       value._ldMeta?.variationKey ?? '',
       // eslint-disable-next-line no-underscore-dangle
       value._ldMeta?.version ?? 1,
+      value.model?.name ?? '',
+      value.provider?.name ?? '',
       context,
     );
+
     // eslint-disable-next-line no-underscore-dangle
     const enabled = !!value._ldMeta?.enabled;
+
+    return {
+      tracker,
+      enabled,
+      model: value.model,
+      provider: value.provider,
+      messages: value.messages,
+      instructions: value.instructions,
+      // eslint-disable-next-line no-underscore-dangle
+      mode: value._ldMeta?.mode ?? 'completion',
+    };
+  }
+
+  private async _evaluateAgent(
+    key: string,
+    context: LDContext,
+    defaultValue: LDAIAgentDefaults,
+    variables?: Record<string, unknown>,
+  ): Promise<LDAIAgent> {
+    const { tracker, enabled, model, provider, instructions } = await this._evaluate(
+      key,
+      context,
+      defaultValue,
+    );
+
+    const mapper = new LDAIConfigMapper(model, provider, undefined);
+    const agent: Omit<LDAIAgent, 'toVercelAISDK'> = {
+      tracker,
+      enabled,
+    };
+
+    // We are going to modify the contents before returning them, so we make a copy.
+    // This isn't a deep copy and the application developer should not modify the returned content.
+    if (model) {
+      agent.model = { ...model };
+    }
+
+    if (provider) {
+      agent.provider = { ...provider };
+    }
+
+    const allVariables = { ...variables, ldctx: context };
+
+    if (instructions) {
+      agent.instructions = this._interpolateTemplate(instructions, allVariables);
+    }
+
+    return {
+      ...agent,
+      toVercelAISDK: <TMod>(
+        sdkProvider: VercelAISDKProvider<TMod> | Record<string, VercelAISDKProvider<TMod>>,
+        options?: VercelAISDKMapOptions | undefined,
+      ): VercelAISDKConfig<TMod> => mapper.toVercelAISDK(sdkProvider, options),
+    };
+  }
+
+  async config(
+    key: string,
+    context: LDContext,
+    defaultValue: LDAIDefaults,
+    variables?: Record<string, unknown>,
+  ): Promise<LDAIConfig> {
+    const {
+      tracker,
+      enabled,
+      model,
+      provider: configProvider,
+      messages,
+    } = await this._evaluate(key, context, defaultValue);
+
     const config: Omit<LDAIConfig, 'toVercelAISDK'> = {
       tracker,
       enabled,
     };
+
     // We are going to modify the contents before returning them, so we make a copy.
     // This isn't a deep copy and the application developer should not modify the returned content.
-    if (value.model) {
-      config.model = { ...value.model };
+    if (model) {
+      config.model = { ...model };
     }
-    if (value.provider) {
-      config.provider = { ...value.provider };
+    if (configProvider) {
+      config.provider = { ...configProvider };
     }
     const allVariables = { ...variables, ldctx: context };
 
-    if (value.messages) {
-      config.messages = value.messages.map((entry: any) => ({
+    if (messages) {
+      config.messages = messages.map((entry: any) => ({
         ...entry,
         content: this._interpolateTemplate(entry.content, allVariables),
       }));
@@ -88,9 +181,50 @@ export class LDAIClientImpl implements LDAIClient {
     return {
       ...config,
       toVercelAISDK: <TMod>(
-        provider: VercelAISDKProvider<TMod> | Record<string, VercelAISDKProvider<TMod>>,
+        sdkProvider: VercelAISDKProvider<TMod> | Record<string, VercelAISDKProvider<TMod>>,
         options?: VercelAISDKMapOptions | undefined,
-      ): VercelAISDKConfig<TMod> => mapper.toVercelAISDK(provider, options),
+      ): VercelAISDKConfig<TMod> => mapper.toVercelAISDK(sdkProvider, options),
     };
   }
+
+  async agent(
+    key: string,
+    context: LDContext,
+    defaultValue: LDAIAgentDefaults,
+    variables?: Record<string, unknown>,
+  ): Promise<LDAIAgent> {
+    // Track agent usage
+    this._ldClient.track('$ld:ai:agent:function:single', context, key, 1);
+
+    return this._evaluateAgent(key, context, defaultValue, variables);
+  }
+
+  async agents<const T extends readonly (LDAIAgentConfig & { defaultValue: LDAIAgentDefaults })[]>(
+    agentConfigs: T,
+    context: LDContext,
+  ): Promise<Record<T[number]['key'], LDAIAgent>> {
+    // Track multiple agents usage
+    this._ldClient.track(
+      '$ld:ai:agent:function:multiple',
+      context,
+      agentConfigs.length,
+      agentConfigs.length,
+    );
+
+    const agents = {} as Record<T[number]['key'], LDAIAgent>;
+
+    await Promise.all(
+      agentConfigs.map(async (config) => {
+        const agent = await this._evaluateAgent(
+          config.key,
+          context,
+          config.defaultValue,
+          config.variables,
+        );
+        agents[config.key as T[number]['key']] = agent;
+      }),
+    );
+
+    return agents;
+  }
 }

package/src/LDAIConfigTrackerImpl.ts

@@ -19,14 +19,24 @@ export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
     private _configKey: string,
     private _variationKey: string,
     private _version: number,
+    private _modelName: string,
+    private _providerName: string,
     private _context: LDContext,
   ) {}
 
-  private _getTrackData(): { variationKey: string; configKey: string; version: number } {
+  private _getTrackData(): {
+    variationKey: string;
+    configKey: string;
+    version: number;
+    modelName: string;
+    providerName: string;
+  } {
     return {
       variationKey: this._variationKey,
       configKey: this._configKey,
       version: this._version,
+      modelName: this._modelName,
+      providerName: this._providerName,
     };
   }
 
@@ -69,13 +79,11 @@ export class LDAIConfigTrackerImpl implements LDAIConfigTracker {
 
   trackSuccess(): void {
     this._trackedMetrics.success = true;
-    this._ldClient.track('$ld:ai:generation', this._context, this._getTrackData(), 1);
     this._ldClient.track('$ld:ai:generation:success', this._context, this._getTrackData(), 1);
   }
 
   trackError(): void {
     this._trackedMetrics.success = false;
-    this._ldClient.track('$ld:ai:generation', this._context, this._getTrackData(), 1);
     this._ldClient.track('$ld:ai:generation:error', this._context, this._getTrackData(), 1);
   }
 

package/src/api/LDAIClient.ts

@@ -1,5 +1,6 @@
 import { LDContext } from '@launchdarkly/js-server-sdk-common';
 
+import { LDAIAgent, LDAIAgentConfig, LDAIAgentDefaults } from './agents';
 import { LDAIConfig, LDAIDefaults } from './config/LDAIConfig';
 
 /**
@@ -63,4 +64,83 @@ export interface LDAIClient {
     defaultValue: LDAIDefaults,
     variables?: Record<string, unknown>,
   ): Promise<LDAIConfig>;
+
+  /**
+   * 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 agent = await client.agent(key, context, {
+   *   enabled: true,
+   *   instructions: 'You are a research assistant.',
+   * }, variables);
+   *
+   * const researchResult = agent.instructions; // Interpolated instructions
+   * agent.tracker.trackSuccess();
+   * ```
+   */
+  agent(
+    key: string,
+    context: LDContext,
+    defaultValue: LDAIAgentDefaults,
+    variables?: Record<string, unknown>,
+  ): Promise<LDAIAgent>;
+
+  /**
+   * 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 agentConfigs = [
+   *   {
+   *     key: 'research_agent',
+   *     defaultValue: { enabled: true, instructions: 'You are a research assistant.' },
+   *     variables: { topic: 'climate change' }
+   *   },
+   *   {
+   *     key: 'writing_agent',
+   *     defaultValue: { enabled: true, instructions: 'You are a writing assistant.' },
+   *     variables: { style: 'academic' }
+   *   }
+   * ] as const;
+   * const context = {...};
+   *
+   * const agents = await client.agents(agentConfigs, context);
+   * const researchResult = agents["research_agent"].instructions; // Interpolated instructions
+   * agents["research_agent"].tracker.trackSuccess();
+   * ```
+   */
+  agents<const T extends readonly LDAIAgentConfig[]>(
+    agentConfigs: T,
+    context: LDContext,
+  ): Promise<Record<T[number]['key'], LDAIAgent>>;
 }

package/src/api/agents/LDAIAgent.ts

@@ -0,0 +1,36 @@
+import { LDAIConfig } from '../config';
+
+/**
+ * AI Config agent and tracker.
+ */
+export interface LDAIAgent extends Omit<LDAIConfig, 'messages'> {
+  /**
+   * Instructions for the agent.
+   */
+  instructions?: string;
+}
+
+/**
+ * Configuration for a single agent request.
+ */
+export interface LDAIAgentConfig {
+  /**
+   * The agent key to retrieve.
+   */
+  key: string;
+
+  /**
+   * Default configuration for the agent.
+   */
+  defaultValue: LDAIAgentDefaults;
+
+  /**
+   * Variables for instructions interpolation.
+   */
+  variables?: Record<string, unknown>;
+}
+
+/**
+ * Default values for an agent.
+ */
+export type LDAIAgentDefaults = Omit<LDAIAgent, 'tracker'>;

package/src/api/agents/index.ts

@@ -0,0 +1 @@
+export * from './LDAIAgent';

package/src/api/index.ts

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