@launchdarkly/server-sdk-ai 0.15.1 → 0.16.0

package/dist/index.d.cts

@@ -440,8 +440,14 @@ interface LDAIJudgeConfigDefault extends LDAIConfigDefault {
      */
     messages?: LDMessage[];
     /**
-     * Evaluation metric keys for judge configurations.
+     * Evaluation metric key for judge configurations.
+     * The key of the metric that this judge can evaluate.
+     */
+    evaluationMetricKey?: string;
+    /**
+     * Evaluation metric keys for judge configurations (legacy).
      * The keys of the metrics that this judge can evaluate.
+     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
      */
     evaluationMetricKeys?: string[];
 }
@@ -486,10 +492,16 @@ interface LDAIJudgeConfig extends LDAIConfig {
      */
     messages?: LDMessage[];
     /**
-     * Evaluation metric keys for judge configurations.
+     * Evaluation metric key for judge configurations.
+     * The key of the metric that this judge can evaluate.
+     */
+    evaluationMetricKey?: string;
+    /**
+     * Evaluation metric keys for judge configurations (legacy).
      * The keys of the metrics that this judge can evaluate.
+     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
      */
-    evaluationMetricKeys: string[];
+    evaluationMetricKeys?: string[];
 }
 /**
  * Union type for all AI Config variants.
@@ -597,6 +609,13 @@ declare class Judge {
     private readonly _logger?;
     private readonly _evaluationResponseStructure;
     constructor(_aiConfig: LDAIJudgeConfig, _aiConfigTracker: LDAIConfigTracker, _aiProvider: AIProvider, logger?: LDLogger$1);
+    /**
+     * Gets the evaluation metric key, prioritizing evaluationMetricKey over evaluationMetricKeys.
+     * Falls back to the first valid (non-empty, non-whitespace) value in evaluationMetricKeys if evaluationMetricKey is not provided.
+     * Treats empty strings and whitespace-only strings as invalid.
+     * @returns The evaluation metric key, or undefined if not available
+     */
+    private _getEvaluationMetricKey;
     /**
      * Evaluates an AI response using the judge's configuration.
      *
@@ -858,7 +877,7 @@ interface LDAIClient {
      *   enabled: true,
      *   model: { name: 'gpt-4' },
      *   provider: { name: 'openai' },
-     *   evaluationMetricKeys: ['$ld:ai:judge:relevance'],
+     *   evaluationMetricKey: '$ld:ai:judge:relevance',
      *   messages: [{ role: 'system', content: 'You are a relevance judge.' }]
      * }, variables);
      *
@@ -977,7 +996,7 @@ interface LDAIClient {
      *     enabled: true,
      *     model: { name: "gpt-4" },
      *     provider: { name: "openai" },
-     *     evaluationMetricKeys: ['$ld:ai:judge:relevance'],
+     *     evaluationMetricKey: '$ld:ai:judge:relevance',
      *     messages: [{ role: 'system', content: 'You are a relevance judge.' }]
      *   },
      *   { metric: "relevance" }

package/dist/index.d.ts

@@ -440,8 +440,14 @@ interface LDAIJudgeConfigDefault extends LDAIConfigDefault {
      */
     messages?: LDMessage[];
     /**
-     * Evaluation metric keys for judge configurations.
+     * Evaluation metric key for judge configurations.
+     * The key of the metric that this judge can evaluate.
+     */
+    evaluationMetricKey?: string;
+    /**
+     * Evaluation metric keys for judge configurations (legacy).
      * The keys of the metrics that this judge can evaluate.
+     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
      */
     evaluationMetricKeys?: string[];
 }
@@ -486,10 +492,16 @@ interface LDAIJudgeConfig extends LDAIConfig {
      */
     messages?: LDMessage[];
     /**
-     * Evaluation metric keys for judge configurations.
+     * Evaluation metric key for judge configurations.
+     * The key of the metric that this judge can evaluate.
+     */
+    evaluationMetricKey?: string;
+    /**
+     * Evaluation metric keys for judge configurations (legacy).
      * The keys of the metrics that this judge can evaluate.
+     * @deprecated Use evaluationMetricKey instead. This field is kept for legacy support.
      */
-    evaluationMetricKeys: string[];
+    evaluationMetricKeys?: string[];
 }
 /**
  * Union type for all AI Config variants.
@@ -597,6 +609,13 @@ declare class Judge {
     private readonly _logger?;
     private readonly _evaluationResponseStructure;
     constructor(_aiConfig: LDAIJudgeConfig, _aiConfigTracker: LDAIConfigTracker, _aiProvider: AIProvider, logger?: LDLogger$1);
+    /**
+     * Gets the evaluation metric key, prioritizing evaluationMetricKey over evaluationMetricKeys.
+     * Falls back to the first valid (non-empty, non-whitespace) value in evaluationMetricKeys if evaluationMetricKey is not provided.
+     * Treats empty strings and whitespace-only strings as invalid.
+     * @returns The evaluation metric key, or undefined if not available
+     */
+    private _getEvaluationMetricKey;
     /**
      * Evaluates an AI response using the judge's configuration.
      *
@@ -858,7 +877,7 @@ interface LDAIClient {
      *   enabled: true,
      *   model: { name: 'gpt-4' },
      *   provider: { name: 'openai' },
-     *   evaluationMetricKeys: ['$ld:ai:judge:relevance'],
+     *   evaluationMetricKey: '$ld:ai:judge:relevance',
      *   messages: [{ role: 'system', content: 'You are a relevance judge.' }]
      * }, variables);
      *
@@ -977,7 +996,7 @@ interface LDAIClient {
      *     enabled: true,
      *     model: { name: "gpt-4" },
      *     provider: { name: "openai" },
-     *     evaluationMetricKeys: ['$ld:ai:judge:relevance'],
+     *     evaluationMetricKey: '$ld:ai:judge:relevance',
      *     messages: [{ role: 'system', content: 'You are a relevance judge.' }]
      *   },
      *   { metric: "relevance" }

package/dist/index.js

@@ -147,6 +147,9 @@ var LDAIConfigUtils = class {
     if ("instructions" in config && config.instructions !== void 0) {
       flagValue.instructions = config.instructions;
     }
+    if ("evaluationMetricKey" in config && config.evaluationMetricKey !== void 0) {
+      flagValue.evaluationMetricKey = config.evaluationMetricKey;
+    }
     if ("evaluationMetricKeys" in config && config.evaluationMetricKeys !== void 0) {
       flagValue.evaluationMetricKeys = config.evaluationMetricKeys;
     }
@@ -192,8 +195,7 @@ var LDAIConfigUtils = class {
         return {
           key,
           enabled: false,
-          tracker: void 0,
-          evaluationMetricKeys: []
+          tracker: void 0
         };
       case "completion":
       default:
@@ -257,11 +259,20 @@ var LDAIConfigUtils = class {
    * @returns A judge configuration
    */
   static toJudgeConfig(key, flagValue, tracker) {
+    let evaluationMetricKey;
+    if (flagValue.evaluationMetricKey && flagValue.evaluationMetricKey.trim().length > 0) {
+      evaluationMetricKey = flagValue.evaluationMetricKey.trim();
+    } else if (flagValue.evaluationMetricKeys && flagValue.evaluationMetricKeys.length > 0) {
+      const validKey = flagValue.evaluationMetricKeys.find(
+        (metricKey) => metricKey && metricKey.trim().length > 0
+      );
+      evaluationMetricKey = validKey ? validKey.trim() : void 0;
+    }
     return {
       ...this._toBaseConfig(key, flagValue),
       tracker,
       messages: flagValue.messages,
-      evaluationMetricKeys: flagValue.evaluationMetricKeys || []
+      evaluationMetricKey
     };
   }
 };
@@ -271,15 +282,20 @@ import Mustache from "mustache";
 
 // src/api/judge/EvaluationSchemaBuilder.ts
 var EvaluationSchemaBuilder = class {
-  static build(evaluationMetricKeys) {
+  static build(evaluationMetricKey) {
+    if (!evaluationMetricKey) {
+      return {};
+    }
     return {
       type: "object",
       properties: {
         evaluations: {
           type: "object",
-          description: `Object containing evaluation results for ${evaluationMetricKeys.join(", ")} metrics`,
-          properties: this._buildKeyProperties(evaluationMetricKeys),
-          required: evaluationMetricKeys,
+          description: `Object containing evaluation results for ${evaluationMetricKey} metric`,
+          properties: {
+            [evaluationMetricKey]: this._buildKeySchema(evaluationMetricKey)
+          },
+          required: [evaluationMetricKey],
           additionalProperties: false
         }
       },
@@ -287,15 +303,6 @@ var EvaluationSchemaBuilder = class {
       additionalProperties: false
     };
   }
-  static _buildKeyProperties(evaluationMetricKeys) {
-    return evaluationMetricKeys.reduce(
-      (acc, key) => {
-        acc[key] = this._buildKeySchema(key);
-        return acc;
-      },
-      {}
-    );
-  }
   static _buildKeySchema(key) {
     return {
       type: "object",
@@ -324,9 +331,26 @@ var Judge = class {
     this._aiConfigTracker = _aiConfigTracker;
     this._aiProvider = _aiProvider;
     this._logger = logger;
-    this._evaluationResponseStructure = EvaluationSchemaBuilder.build(
-      this._aiConfig.evaluationMetricKeys
-    );
+    const evaluationMetricKey = this._getEvaluationMetricKey();
+    this._evaluationResponseStructure = EvaluationSchemaBuilder.build(evaluationMetricKey);
+  }
+  /**
+   * Gets the evaluation metric key, prioritizing evaluationMetricKey over evaluationMetricKeys.
+   * Falls back to the first valid (non-empty, non-whitespace) value in evaluationMetricKeys if evaluationMetricKey is not provided.
+   * Treats empty strings and whitespace-only strings as invalid.
+   * @returns The evaluation metric key, or undefined if not available
+   */
+  _getEvaluationMetricKey() {
+    if (this._aiConfig.evaluationMetricKey && this._aiConfig.evaluationMetricKey.trim().length > 0) {
+      return this._aiConfig.evaluationMetricKey.trim();
+    }
+    if (this._aiConfig.evaluationMetricKeys && this._aiConfig.evaluationMetricKeys.length > 0) {
+      const validKey = this._aiConfig.evaluationMetricKeys.find(
+        (key) => key && key.trim().length > 0
+      );
+      return validKey ? validKey.trim() : void 0;
+    }
+    return void 0;
   }
   /**
    * Evaluates an AI response using the judge's configuration.
@@ -338,9 +362,10 @@ var Judge = class {
    */
   async evaluate(input, output, samplingRate = 1) {
     try {
-      if (!this._aiConfig.evaluationMetricKeys || this._aiConfig.evaluationMetricKeys.length === 0) {
+      const evaluationMetricKey = this._getEvaluationMetricKey();
+      if (!evaluationMetricKey) {
         this._logger?.warn(
-          "Judge configuration is missing required evaluationMetricKeys",
+          "Judge configuration is missing required evaluation metric key",
           this._aiConfigTracker.getTrackData()
         );
         return void 0;
@@ -362,10 +387,10 @@ var Judge = class {
         () => this._aiProvider.invokeStructuredModel(messages, this._evaluationResponseStructure)
       );
       let { success } = response.metrics;
-      const evals = this._parseEvaluationResponse(response.data);
-      if (Object.keys(evals).length !== this._aiConfig.evaluationMetricKeys.length) {
+      const evals = this._parseEvaluationResponse(response.data, evaluationMetricKey);
+      if (!evals[evaluationMetricKey]) {
         this._logger?.warn(
-          "Judge evaluation did not return all evaluations",
+          "Judge evaluation did not return the expected evaluation",
           this._aiConfigTracker.getTrackData()
         );
         success = false;
@@ -438,42 +463,40 @@ var Judge = class {
   /**
    * Parses the structured evaluation response from the AI provider.
    */
-  _parseEvaluationResponse(data) {
+  _parseEvaluationResponse(data, evaluationMetricKey) {
     const evaluations = data.evaluations;
     const results = {};
     if (!data.evaluations || typeof data.evaluations !== "object") {
       this._logger?.warn("Invalid response: missing or invalid evaluations object");
       return results;
     }
-    this._aiConfig.evaluationMetricKeys.forEach((metricKey) => {
-      const evaluation = evaluations[metricKey];
-      if (!evaluation || typeof evaluation !== "object") {
-        this._logger?.warn(
-          `Missing evaluation for metric key: ${metricKey}`,
-          this._aiConfigTracker.getTrackData()
-        );
-        return;
-      }
-      const evalData = evaluation;
-      if (typeof evalData.score !== "number" || evalData.score < 0 || evalData.score > 1) {
-        this._logger?.warn(
-          `Invalid score evaluated for ${metricKey}: ${evalData.score}. Score must be a number between 0 and 1 inclusive`,
-          this._aiConfigTracker.getTrackData()
-        );
-        return;
-      }
-      if (typeof evalData.reasoning !== "string") {
-        this._logger?.warn(
-          `Invalid reasoning evaluated for ${metricKey}: ${evalData.reasoning}. Reasoning must be a string`,
-          this._aiConfigTracker.getTrackData()
-        );
-        return;
-      }
-      results[metricKey] = {
-        score: evalData.score,
-        reasoning: evalData.reasoning
-      };
-    });
+    const evaluation = evaluations[evaluationMetricKey];
+    if (!evaluation || typeof evaluation !== "object") {
+      this._logger?.warn(
+        `Missing evaluation for metric key: ${evaluationMetricKey}`,
+        this._aiConfigTracker.getTrackData()
+      );
+      return results;
+    }
+    const evalData = evaluation;
+    if (typeof evalData.score !== "number" || evalData.score < 0 || evalData.score > 1) {
+      this._logger?.warn(
+        `Invalid score evaluated for ${evaluationMetricKey}: ${evalData.score}. Score must be a number between 0 and 1 inclusive`,
+        this._aiConfigTracker.getTrackData()
+      );
+      return results;
+    }
+    if (typeof evalData.reasoning !== "string") {
+      this._logger?.warn(
+        `Invalid reasoning evaluated for ${evaluationMetricKey}: ${evalData.reasoning}. Reasoning must be a string`,
+        this._aiConfigTracker.getTrackData()
+      );
+      return results;
+    }
+    results[evaluationMetricKey] = {
+      score: evalData.score,
+      reasoning: evalData.reasoning
+    };
     return results;
   }
 };
@@ -675,7 +698,7 @@ function createVercelAISDKTokenUsage(data) {
 
 // src/sdkInfo.ts
 var aiSdkName = "@launchdarkly/server-sdk-ai";
-var aiSdkVersion = "0.15.1";
+var aiSdkVersion = "0.16.0";
 
 // src/LDAIConfigTrackerImpl.ts
 var LDAIConfigTrackerImpl = class {