feat: add progress bar to experiments

packages/client/package.json

@@ -41,6 +41,10 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
-    "@types/mustache": "^4.2.6"
+    "@types/mustache": "^4.2.6",
+    "@types/progress": "^2.0.7"
+  },
+  "optionalDependencies": {
+    "progress": "^2.0.3"
   }
 }

packages/client/src/experiment/ExperimentManager.ts

@@ -187,6 +187,7 @@ export class ExperimentManager {
       metadata,
       maxConcurrency: batchSize = 50,
       runEvaluators,
+      progress: progressOption,
     } = config;
 
     const runName = this.createExperimentRunName({
@@ -200,6 +201,29 @@ export class ExperimentManager {
       );
     }
 
+    let progressBar: { tick: (n?: number) => void } | null = null;
+    const showProgress =
+      progressOption ??
+      (typeof process !== "undefined" && process.stderr?.isTTY === true);
+    const canShowBar =
+      showProgress &&
+      typeof process !== "undefined" &&
+      data.length > 0 &&
+      (process.stderr?.isTTY === true || progressOption === true);
+    if (canShowBar) {
+      const Progress = (await import("progress")).default as new (
+        format: string,
+        options: { total: number; stream: NodeJS.WritableStream },
+      ) => { tick: (n?: number) => void };
+      progressBar = new Progress(
+        "Experiment [:bar] :current/:total :percent :eta",
+        {
+          total: data.length,
+          stream: process.stderr,
+        },
+      );
+    }
+
     const itemResults: ExperimentItemResult<Input, ExpectedOutput, Metadata>[] =
       [];
 
@@ -208,8 +232,8 @@ export class ExperimentManager {
 
       const promises: Promise<
         ExperimentItemResult<Input, ExpectedOutput, Metadata>
-      >[] = batch.map(async (item) => {
-        return this.runItem({
+      >[] = batch.map((item) =>
+        this.runItem({
           item,
           evaluators,
           task,
@@ -218,8 +242,10 @@ export class ExperimentManager {
           experimentDescription: description,
           experimentMetadata: metadata,
           datasetVersion: config.datasetVersion,
-        });
-      });
+        }).finally(() => {
+          progressBar?.tick(1);
+        }),
+      );
 
       const settledResults = await Promise.allSettled(promises);
       const results = settledResults.reduce(

packages/client/src/experiment/types.ts

@@ -244,6 +244,14 @@ export type ExperimentParams<
    * If not provided, returns the latest version.
    */
   datasetVersion?: string;
+
+  /**
+   * Whether to show a terminal progress bar (tqdm-style) when running in Node with a TTY.
+   *
+   * Default: true when stderr is a TTY, false otherwise (e.g. browser, CI, piped output).
+   * Set to false to disable the bar.
+   */
+  progress?: boolean;
 };
 
 export type ExperimentItemResult<

tests/e2e/experiments.e2e.test.ts

@@ -370,6 +370,42 @@ describe("Langfuse Datasets E2E", () => {
     expect(result.datasetRunId).toBeUndefined();
   });
 
+  describe("Progress bar", () => {
+    it("should run experiment with progress: false (no bar)", async () => {
+      const result = await langfuse.experiment.run({
+        name: "Progress disabled",
+        description: "Experiment with progress bar disabled",
+        data: dataset.slice(0, 2),
+        task,
+        evaluators: [createEvaluatorFromAutoevals(Factuality)],
+        progress: false,
+      });
+
+      await testEnv.spanProcessor.forceFlush();
+      await waitForServerIngestion(1000);
+
+      expect(result.itemResults).toHaveLength(2);
+      expect(result.runName).toContain("Progress disabled");
+    });
+
+    it("should run experiment with progress: true (bar when TTY)", async () => {
+      const result = await langfuse.experiment.run({
+        name: "Progress enabled",
+        description: "Experiment with progress bar enabled",
+        data: dataset.slice(0, 2),
+        task,
+        evaluators: [createEvaluatorFromAutoevals(Factuality)],
+        progress: true,
+      });
+
+      await testEnv.spanProcessor.forceFlush();
+      await waitForServerIngestion(1000);
+
+      expect(result.itemResults).toHaveLength(2);
+      expect(result.runName).toContain("Progress enabled");
+    });
+  });
+
   // Error Handling Tests
   describe("Error Handling", () => {
     it("should handle evaluator failures gracefully", async () => {