@langfuse/client 4.1.0-alpha.2 → 4.2.0

package/dist/index.d.cts

@@ -120,6 +120,14 @@ type ExperimentParams<Input = any, ExpectedOutput = any, Metadata extends Record
      * Choose a descriptive name that identifies the experiment's purpose.
      */
     name: string;
+    /**
+     * Optional exact name for the experiment run.
+     *
+     * If provided, this will be used as the exact dataset run name if the data
+     * contains Langfuse dataset items. If not provided, this will default to
+     * the experiment name appended with an ISO timestamp.
+     */
+    runName?: string;
     /**
      * Optional description explaining the experiment's purpose.
      *
@@ -227,10 +235,10 @@ type ExperimentItemResult<Input = any, ExpectedOutput = any, Metadata extends Re
  * console.log(`Average score: ${avgScore?.value}`);
  *
  * // Print formatted results
- * console.log(await result.prettyPrint());
+ * console.log(await result.format());
  *
  * // Print summary with individual item results
- * console.log(await result.prettyPrint({ includeItemResults: true }));
+ * console.log(await result.format({ includeItemResults: true }));
  *
  * // Link to dataset run (if available)
  * if (result.datasetRunUrl) {
@@ -241,6 +249,13 @@ type ExperimentItemResult<Input = any, ExpectedOutput = any, Metadata extends Re
  * @public
  */
 type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = {
+    /**
+     * The experiment run name.
+     *
+     * This is equal to the dataset run name if experiment was on Langfuse dataset.
+     * Either the provided runName parameter or generated name (experiment name + timestamp).
+     */
+    runName: string;
     /**
      * ID of the dataset run in Langfuse (only for experiments on Langfuse datasets).
      *
@@ -273,7 +288,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
      */
     runEvaluations: Evaluation[];
     /**
-     * Function to format and display experiment results in a human-readable format.
+     * Function to format experiment results in a human-readable format.
      *
      * Generates a comprehensive, nicely formatted summary including individual results,
      * aggregate statistics, evaluation scores, and links to traces and dataset runs.
@@ -282,7 +297,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
      * @param options.includeItemResults - Whether to include individual item details (default: false)
      * @returns Promise resolving to formatted string representation
      */
-    prettyPrint: (options?: {
+    format: (options?: {
         includeItemResults?: boolean;
     }) => Promise<string>;
 };
@@ -301,6 +316,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
  * const dataset = await langfuse.dataset.get("my-dataset");
  * const result = await dataset.runExperiment({
  *   name: "Model Evaluation",
+ *   runName: "Model Evaluation Run 1", // optional
  *   task: myTask,
  *   evaluators: [myEvaluator]
  * });
@@ -469,6 +485,7 @@ declare class DatasetManager {
      *
      * 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({
@@ -485,7 +502,7 @@ declare class DatasetManager {
      *   ]
      * });
      *
-     * console.log(await result.prettyPrint());
+     * console.log(await result.format());
      * ```
      *
      * @example Handling large datasets
@@ -549,7 +566,7 @@ declare class DatasetManager {
  *   ]
  * });
  *
- * console.log(await result.prettyPrint());
+ * console.log(await result.format());
  * ```
  *
  * @example Using with Langfuse datasets
@@ -597,6 +614,7 @@ declare class ExperimentManager {
      *
      * @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[])
@@ -606,10 +624,11 @@ declare class ExperimentManager {
      * @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
@@ -669,6 +688,7 @@ declare class ExperimentManager {
      *
      * @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
@@ -758,6 +778,20 @@ declare class ExperimentManager {
      */
     private formatValue;
     private isOtelRegistered;
+    /**
+     * 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
+     */
+    private createExperimentRunName;
 }
 
 /**
@@ -1501,7 +1535,7 @@ declare class LangfuseClient {
      *   ]
      * });
      *
-     * console.log(await result.prettyPrint());
+     * console.log(await result.format());
      * ```
      *
      * @example Using with datasets

package/dist/index.d.ts

@@ -120,6 +120,14 @@ type ExperimentParams<Input = any, ExpectedOutput = any, Metadata extends Record
      * Choose a descriptive name that identifies the experiment's purpose.
      */
     name: string;
+    /**
+     * Optional exact name for the experiment run.
+     *
+     * If provided, this will be used as the exact dataset run name if the data
+     * contains Langfuse dataset items. If not provided, this will default to
+     * the experiment name appended with an ISO timestamp.
+     */
+    runName?: string;
     /**
      * Optional description explaining the experiment's purpose.
      *
@@ -227,10 +235,10 @@ type ExperimentItemResult<Input = any, ExpectedOutput = any, Metadata extends Re
  * console.log(`Average score: ${avgScore?.value}`);
  *
  * // Print formatted results
- * console.log(await result.prettyPrint());
+ * console.log(await result.format());
  *
  * // Print summary with individual item results
- * console.log(await result.prettyPrint({ includeItemResults: true }));
+ * console.log(await result.format({ includeItemResults: true }));
  *
  * // Link to dataset run (if available)
  * if (result.datasetRunUrl) {
@@ -241,6 +249,13 @@ type ExperimentItemResult<Input = any, ExpectedOutput = any, Metadata extends Re
  * @public
  */
 type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record<string, any> = Record<string, any>> = {
+    /**
+     * The experiment run name.
+     *
+     * This is equal to the dataset run name if experiment was on Langfuse dataset.
+     * Either the provided runName parameter or generated name (experiment name + timestamp).
+     */
+    runName: string;
     /**
      * ID of the dataset run in Langfuse (only for experiments on Langfuse datasets).
      *
@@ -273,7 +288,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
      */
     runEvaluations: Evaluation[];
     /**
-     * Function to format and display experiment results in a human-readable format.
+     * Function to format experiment results in a human-readable format.
      *
      * Generates a comprehensive, nicely formatted summary including individual results,
      * aggregate statistics, evaluation scores, and links to traces and dataset runs.
@@ -282,7 +297,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
      * @param options.includeItemResults - Whether to include individual item details (default: false)
      * @returns Promise resolving to formatted string representation
      */
-    prettyPrint: (options?: {
+    format: (options?: {
         includeItemResults?: boolean;
     }) => Promise<string>;
 };
@@ -301,6 +316,7 @@ type ExperimentResult<Input = any, ExpectedOutput = any, Metadata extends Record
  * const dataset = await langfuse.dataset.get("my-dataset");
  * const result = await dataset.runExperiment({
  *   name: "Model Evaluation",
+ *   runName: "Model Evaluation Run 1", // optional
  *   task: myTask,
  *   evaluators: [myEvaluator]
  * });
@@ -469,6 +485,7 @@ declare class DatasetManager {
      *
      * 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({
@@ -485,7 +502,7 @@ declare class DatasetManager {
      *   ]
      * });
      *
-     * console.log(await result.prettyPrint());
+     * console.log(await result.format());
      * ```
      *
      * @example Handling large datasets
@@ -549,7 +566,7 @@ declare class DatasetManager {
  *   ]
  * });
  *
- * console.log(await result.prettyPrint());
+ * console.log(await result.format());
  * ```
  *
  * @example Using with Langfuse datasets
@@ -597,6 +614,7 @@ declare class ExperimentManager {
      *
      * @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[])
@@ -606,10 +624,11 @@ declare class ExperimentManager {
      * @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
@@ -669,6 +688,7 @@ declare class ExperimentManager {
      *
      * @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
@@ -758,6 +778,20 @@ declare class ExperimentManager {
      */
     private formatValue;
     private isOtelRegistered;
+    /**
+     * 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
+     */
+    private createExperimentRunName;
 }
 
 /**
@@ -1501,7 +1535,7 @@ declare class LangfuseClient {
      *   ]
      * });
      *
-     * console.log(await result.prettyPrint());
+     * console.log(await result.format());
      * ```
      *
      * @example Using with datasets

package/dist/index.mjs

@@ -59,6 +59,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({
@@ -75,7 +76,7 @@ var DatasetManager = class {
    *   ]
    * });
    *
-   * console.log(await result.prettyPrint());
+   * console.log(await result.format());
    * ```
    *
    * @example Handling large datasets
@@ -184,6 +185,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[])
@@ -193,10 +195,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
@@ -249,11 +252,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"
@@ -268,6 +276,7 @@ var ExperimentManager = class {
           evaluators,
           task,
           experimentName: name,
+          experimentRunName: runName,
           experimentDescription: description,
           experimentMetadata: metadata
         });
@@ -325,11 +334,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,
@@ -337,6 +347,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
         });
@@ -355,6 +366,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
@@ -369,7 +381,7 @@ var ExperimentManager = class {
    */
   async runItem(params) {
     const { item, evaluators = [], task, experimentMetadata = {} } = params;
-    const { output, traceId } = await startActiveObservation(
+    const { output, traceId, observationId } = await startActiveObservation(
       "experiment-item-run",
       async (span) => {
         var _a;
@@ -378,7 +390,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 ? {
@@ -387,17 +400,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(
@@ -519,6 +533,7 @@ ${JSON.stringify(params2)}
       originalData,
       runEvaluations,
       name,
+      runName,
       description,
       includeItemResults = false
     } = params;
@@ -576,7 +591,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(
@@ -585,7 +600,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}`;
     }
@@ -660,6 +677,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
@@ -1180,10 +1217,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({