@langfuse/client 4.1.0-alpha.2 → 4.2.0

package/dist/index.cjs

@@ -99,6 +99,7 @@ var DatasetManager = class {
    *
    * const result = await dataset.runExperiment({
    *   name: "GPT-4 Benchmark",
+   *   runName: "GPT-4 Benchmark v1.2", // optional exact run name
    *   description: "Evaluating GPT-4 on our benchmark tasks",
    *   task: async ({ input }) => {
    *     const response = await openai.chat.completions.create({
@@ -115,7 +116,7 @@ var DatasetManager = class {
    *   ]
    * });
    *
-   * console.log(await result.prettyPrint());
+   * console.log(await result.format());
    * ```
    *
    * @example Handling large datasets
@@ -224,6 +225,7 @@ var ExperimentManager = class {
    *
    * @param config - The experiment configuration
    * @param config.name - Human-readable name for the experiment
+   * @param config.runName - Optional exact name for the experiment run (defaults to name + timestamp)
    * @param config.description - Optional description of the experiment's purpose
    * @param config.metadata - Optional metadata to attach to the experiment run
    * @param config.data - Array of data items to process (ExperimentItem[] or DatasetItem[])
@@ -233,10 +235,11 @@ var ExperimentManager = class {
    * @param config.maxConcurrency - Maximum number of concurrent task executions (default: Infinity)
    *
    * @returns Promise that resolves to experiment results including:
+   *   - runName: The experiment run name (either provided or generated)
    *   - itemResults: Results for each processed data item
    *   - runEvaluations: Results from run-level evaluators
    *   - datasetRunId: ID of the dataset run (if using Langfuse datasets)
-   *   - prettyPrint: Function to format and display results
+   *   - format: Function to format results for display
    *
    * @throws {Error} When task execution fails and cannot be handled gracefully
    * @throws {Error} When required evaluators fail critically
@@ -289,11 +292,16 @@ var ExperimentManager = class {
       evaluators,
       task,
       name,
+      runName: providedRunName,
       description,
       metadata,
       maxConcurrency: batchSize = Infinity,
       runEvaluators
     } = config;
+    const runName = this.createExperimentRunName({
+      name,
+      runName: providedRunName
+    });
     if (!this.isOtelRegistered()) {
       this.logger.warn(
         "OpenTelemetry has not been set up. Traces will not be sent to Langfuse.See our docs on how to set up OpenTelemetry: https://langfuse.com/docs/observability/sdk/typescript/setup#tracing-setup"
@@ -308,6 +316,7 @@ var ExperimentManager = class {
           evaluators,
           task,
           experimentName: name,
+          experimentRunName: runName,
           experimentDescription: description,
           experimentMetadata: metadata
         });
@@ -365,11 +374,12 @@ var ExperimentManager = class {
     }
     await this.langfuseClient.score.flush();
     return {
+      runName,
       itemResults,
       datasetRunId,
       datasetRunUrl,
       runEvaluations,
-      prettyPrint: async (options) => {
+      format: async (options) => {
         var _a;
         return await this.prettyPrintResults({
           datasetRunUrl,
@@ -377,6 +387,7 @@ var ExperimentManager = class {
           originalData: data,
           runEvaluations,
           name: config.name,
+          runName,
           description: config.description,
           includeItemResults: (_a = options == null ? void 0 : options.includeItemResults) != null ? _a : false
         });
@@ -395,6 +406,7 @@ var ExperimentManager = class {
    *
    * @param params - Parameters for item execution
    * @param params.experimentName - Name of the parent experiment
+   * @param params.experimentRunName - Run name for the parent experiment
    * @param params.experimentDescription - Description of the parent experiment
    * @param params.experimentMetadata - Metadata for the parent experiment
    * @param params.item - The data item to process
@@ -409,7 +421,7 @@ var ExperimentManager = class {
    */
   async runItem(params) {
     const { item, evaluators = [], task, experimentMetadata = {} } = params;
-    const { output, traceId } = await (0, import_tracing.startActiveObservation)(
+    const { output, traceId, observationId } = await (0, import_tracing.startActiveObservation)(
       "experiment-item-run",
       async (span) => {
         var _a;
@@ -418,7 +430,8 @@ var ExperimentManager = class {
           input: item.input,
           output: output2,
           metadata: {
-            experimentName: params.experimentName,
+            experiment_name: params.experimentName,
+            experiment_run_name: params.experimentRunName,
             ...experimentMetadata,
             ...(_a = item.metadata) != null ? _a : {},
             ..."id" in item && "datasetId" in item ? {
@@ -427,17 +440,18 @@ var ExperimentManager = class {
             } : {}
           }
         });
-        return { output: output2, traceId: span.traceId };
+        return { output: output2, traceId: span.traceId, observationId: span.id };
       }
     );
     let datasetRunId = void 0;
     if ("id" in item) {
       await this.langfuseClient.api.datasetRunItems.create({
-        runName: params.experimentName,
+        runName: params.experimentRunName,
         runDescription: params.experimentDescription,
         metadata: params.experimentMetadata,
         datasetItemId: item.id,
-        traceId
+        traceId,
+        observationId
       }).then((result) => {
         datasetRunId = result.datasetRunId;
       }).catch(
@@ -559,6 +573,7 @@ ${JSON.stringify(params2)}
       originalData,
       runEvaluations,
       name,
+      runName,
       description,
       includeItemResults = false
     } = params;
@@ -616,7 +631,7 @@ ${index + 1}. Item ${index + 1}:
     } else {
       output += `Individual Results: Hidden (${itemResults.length} items)
 `;
-      output += "\u{1F4A1} Call prettyPrint({ includeItemResults: true }) to view them\n";
+      output += "\u{1F4A1} Call format({ includeItemResults: true }) to view them\n";
     }
     const totalItems = itemResults.length;
     const evaluationNames = new Set(
@@ -625,7 +640,9 @@ ${index + 1}. Item ${index + 1}:
     output += `
 ${"\u2500".repeat(50)}
 `;
-    output += `\u{1F4CA} ${name}`;
+    output += `\u{1F9EA} Experiment: ${name}`;
+    output += `
+\u{1F4CB} Run name: ${runName}`;
     if (description) {
       output += ` - ${description}`;
     }
@@ -700,6 +717,26 @@ Run Evaluations:`;
     }
     return tracerProvider.constructor.name !== "NoopTracerProvider";
   }
+  /**
+   * Creates an experiment run name based on provided parameters.
+   *
+   * If runName is provided, returns it directly. Otherwise, generates
+   * a name by combining the experiment name with an ISO timestamp.
+   *
+   * @param params - Parameters for run name creation
+   * @param params.name - The experiment name
+   * @param params.runName - Optional provided run name
+   * @returns The final run name to use
+   *
+   * @internal
+   */
+  createExperimentRunName(params) {
+    if (params.runName) {
+      return params.runName;
+    }
+    const isoTimestamp = (/* @__PURE__ */ new Date()).toISOString();
+    return `${params.name} - ${isoTimestamp}`;
+  }
 };
 
 // src/media/index.ts
@@ -1215,10 +1252,10 @@ var ChatPromptClient = class _ChatPromptClient extends BasePromptClient {
             JSON.stringify(placeholderValue)
           );
         } else {
-          messagesWithPlaceholdersReplaced.push({
-            variableName: item.name,
-            optional: false
-          });
+          messagesWithPlaceholdersReplaced.push([
+            "placeholder",
+            `{${item.name}}`
+          ]);
         }
       } else if ("role" in item && "content" in item && item.type === "chatmessage" /* ChatMessage */) {
         messagesWithPlaceholdersReplaced.push({