apache · kennknowles · Sep 2, 2026
diff --git a/.github/workflows/pr-bot-new-prs.yml b/.github/workflows/pr-bot-new-prs.yml
@@ -47,4 +47,5 @@ jobs:
       - run: npm run processNewPrs
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
         working-directory: 'scripts/ci/pr-bot'
diff --git a/scripts/ci/pr-bot/dryRunAdvisor.ts b/scripts/ci/pr-bot/dryRunAdvisor.ts
@@ -0,0 +1,145 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { buildPrHistoryContext } from "./shared/gitHistory";
+import {
+  GeminiReviewerAdvisor,
+  GeminiClient,
+} from "./shared/geminiReviewerAdvisor";
+import { assignReviewersWithExpertise } from "./shared/commentStrings";
+
+/**
+ * Dry-run script to demonstrate and evaluate the Gemini Reviewer Assigner locally.
+ *
+ * Usage:
+ *   node lib/dryRunAdvisor.js [file1] [file2] ...
+ *
+ * If no files are specified, defaults to representative Beam files (e.g. KafkaIO).
+ */
+async function runDryRun() {
+  const customFiles = process.argv.slice(2);
+
+  const defaultFiles = [
+    {
+      filename:
+        "sdks/java/io/kafka/src/main/java/org/apache/beam/sdk/io/kafka/KafkaIO.java",
+      additions: 85,
+      deletions: 12,
+      changes: 97,
+      status: "modified",
+    },
+    {
+      filename:
+        "sdks/java/io/kafka/src/test/java/org/apache/beam/sdk/io/kafka/KafkaIOTest.java",
+      additions: 40,
+      deletions: 5,
+      changes: 45,
+      status: "modified",
+    },
+  ];
+
+  const filesToEvaluate =
+    customFiles.length > 0
+      ? customFiles.map((f) => ({
+          filename: f,
+          additions: 50,
+          deletions: 10,
+          changes: 60,
+          status: "modified",
+        }))
+      : defaultFiles;
+
+  console.log("=================================================");
+  console.log(" Beam LLM Review Assigner — Dry Run Prototype");
+  console.log("=================================================\n");
+
+  console.log("1. Extracting git history for touched files...");
+  for (const f of filesToEvaluate) {
+    console.log(`   - ${f.filename}`);
+  }
+
+  const prContext = buildPrHistoryContext(
+    39999,
+    "KafkaIO: Optimize consumer polling and watermark estimation",
+    "Refactors the reader loop to prevent deadlocks and improve dynamic backlog tracking.",
+    "sampleAuthor",
+    filesToEvaluate
+  );
+
+  console.log(
+    `\n2. Found ${prContext.candidates.length} candidate contributors in git history:`
+  );
+  for (const c of prContext.candidates.slice(0, 5)) {
+    console.log(
+      `   • @${c.login || c.email} (${c.name}): ${
+        c.commitCount
+      } commits, last active ${c.lastCommitDate}`
+    );
+  }
+
+  const apiKey = process.env.GEMINI_API_KEY || "";
+  const advisor = new GeminiReviewerAdvisor({
+    geminiClient: apiKey ? new GeminiClient(apiKey) : undefined,
+    committerCheck: async (login) =>
+      [
+        "kennknowles",
+        "chamikaramj",
+        "jrmccluskey",
+        "johnjcasey",
+        "damccorm",
+      ].includes(login.toLowerCase()),
+  });
+
+  console.log(
+    `\n3. Evaluating candidate expertise (${
+      apiKey ? "using Gemini API" : "using familiarity heuristic fallback"
+    })...\n`
+  );
+
+  const advice = await advisor.adviseReviewers(prContext);
+
+  console.log("---------------- Selected Reviewers ----------------");
+  for (const reviewer of advice.selectedReviewers) {
+    console.log(
+      `Reviewer: @${
+        reviewer.username
+      } [${reviewer.role.toUpperCase()}] (Committer: ${reviewer.isCommitter})`
+    );
+    console.log(`Expertise: ${reviewer.expertise}`);
+    console.log(`Covered files: ${reviewer.coveredFiles.join(", ")}\n`);
+  }
+
+  if (advice.alternateReviewers.length > 0) {
+    console.log("---------------- Alternate Reviewers ---------------");
+    for (const alt of advice.alternateReviewers) {
+      console.log(`Backup: @${alt.username} — ${alt.expertise}`);
+    }
+    console.log();
+  }
+
+  console.log("Reasoning: " + advice.reasoning);
+
+  console.log("\n================ Generated GitHub Comment ================\n");
+  console.log(assignReviewersWithExpertise(advice));
+  console.log("==========================================================");
+}
+
+runDryRun().catch((err) => {
+  console.error("Dry run encountered error:", err);
+  process.exit(1);
+});
diff --git a/scripts/ci/pr-bot/package.json b/scripts/ci/pr-bot/package.json
@@ -11,7 +11,8 @@
     "processPrUpdate": "npm run build && node lib/processPrUpdate.js",
     "gatherMetrics": "npm run build && node lib/gatherMetrics.js",
     "updateReviewers": "npm run build && node lib/updateReviewers.js",
-    "findPrsNeedingAttention": "npm run build && node lib/findPrsNeedingAttention.js"
+    "findPrsNeedingAttention": "npm run build && node lib/findPrsNeedingAttention.js",
+    "dryRun": "npm run build && node lib/dryRunAdvisor.js"
   },
   "dependencies": {
     "@actions/exec": "^1.1.0",

diff --git a/scripts/ci/pr-bot/processNewPrs.ts b/scripts/ci/pr-bot/processNewPrs.ts
@@ -29,6 +29,12 @@ const {
   REVIEWERS_ACTION,
 } = require("./shared/constants");
 import { CheckStatus } from "./shared/checks";
+import { buildPrHistoryContext } from "./shared/gitHistory";
+import {
+  GeminiReviewerAdvisor,
+  GeminiClient,
+  ReviewerAdviceResult,
+} from "./shared/geminiReviewerAdvisor";
 
 /*
  * Returns true if the pr needs to be processed or false otherwise.
@@ -167,7 +173,9 @@ async function approvedBy(pull: any): Promise<string[]> {
 async function isAnyGithubReviewerCommitter(pull: any): Promise<boolean> {
   let reviewers: string[] = [];
   if (pull.requested_reviewers && pull.requested_reviewers.length > 0) {
-    reviewers = reviewers.concat(pull.requested_reviewers.map((r: any) => r.login));
+    reviewers = reviewers.concat(
+      pull.requested_reviewers.map((r: any) => r.login)
+    );
   }
   for (const reviewer of reviewers) {
     if (await github.checkIfCommitter(reviewer)) {
@@ -194,8 +202,8 @@ async function processPull(
       await github.addPrComment(
         pull.number,
         "Closing this PR because dependabot updates for container/** are not allowed due to generated files " +
-        "and excluded_paths is disabled due to dependabot/dependabot-core#14408. " +
-        "Once issue is resolved, please remove this step."
+          "and excluded_paths is disabled due to dependabot/dependabot-core#14408. " +
+          "Once issue is resolved, please remove this step."
       );
       await github.closePr(pull.number);
       return;
@@ -210,8 +218,10 @@ async function processPull(
   console.log(`Processing PR ${pull.number}`);
 
   // If reviewers are already assigned, we just need to check if we should assign a committer.
-  const hasReviewersAssignedForLabels = Object.keys(prState.reviewersAssignedForLabels).length > 0;
-  const hasGithubReviewers = pull.requested_reviewers && pull.requested_reviewers.length > 0;
+  const hasReviewersAssignedForLabels =
+    Object.keys(prState.reviewersAssignedForLabels).length > 0;
+  const hasGithubReviewers =
+    pull.requested_reviewers && pull.requested_reviewers.length > 0;
 
   if (hasReviewersAssignedForLabels || hasGithubReviewers) {
     if (prState.committerAssigned) {
@@ -237,7 +247,11 @@ async function processPull(
       // we can try to guess a label from the PR to assign a committer to.
       if (!labelOfReviewer) {
         let isGithubReviewer = false;
-        if (pull.requested_reviewers && pull.requested_reviewers.some((r: any) => r.login === approver)) isGithubReviewer = true;
+        if (
+          pull.requested_reviewers &&
+          pull.requested_reviewers.some((r: any) => r.login === approver)
+        )
+          isGithubReviewer = true;
 
         if (isGithubReviewer && pull.labels && pull.labels.length > 0) {
           const validLabels = reviewerConfig.getReviewersForAllLabels();
@@ -272,8 +286,7 @@ async function processPull(
         );
         const availableReviewers =
           reviewerConfig.getReviewersForLabel(labelOfReviewer);
-        const fallbackReviewers =
-          reviewerConfig.getFallbackReviewers();
+        const fallbackReviewers = reviewerConfig.getFallbackReviewers();
         const chosenCommitter = await reviewersState.assignNextCommitter(
           availableReviewers,
           fallbackReviewers
@@ -322,7 +335,82 @@ async function processPull(
   }
   prState.commentedAboutFailingChecks = false;
 
-  // Pick reviewers to assign. Store them in reviewerStateToUpdate and update the prState object with those reviewers (and their associated labels)
+  // 1. Attempt LLM / Git History based expert reviewer selection
+  let assignedViaAdvisor = false;
+  try {
+    const rawFiles = await github
+      .getGitHubClient()
+      .paginate(github.getGitHubClient().rest.pulls.listFiles, {
+        owner: REPO_OWNER,
+        repo: REPO,
+        pull_number: pull.number,
+      });
+
+    const prContext = buildPrHistoryContext(
+      pull.number,
+      pull.title,
+      pull.body || "",
+      pull.user.login,
+      rawFiles
+    );
+
+    const apiKey = process.env.GEMINI_API_KEY || "";
+    const advisor = new GeminiReviewerAdvisor({
+      geminiClient: apiKey ? new GeminiClient(apiKey) : undefined,
+      committerCheck: github.checkIfCommitter,
+      exclusionList: reviewerConfig.getAllExclusions(),
+    });
+
+    const advice: ReviewerAdviceResult = await advisor.adviseReviewers(
+      prContext
+    );
+
+    if (advice.selectedReviewers.length > 0) {
+      for (const reviewer of advice.selectedReviewers) {
+        prState.reviewersAssignedForLabels[reviewer.expertise] =
+          reviewer.username;
+      }
+      prState.alternateReviewers = advice.alternateReviewers.map(
+        (a) => a.username
+      );
+
+      console.log(
+        `Assigning reviewers with expertise for PR ${pull.number} via ${advice.source}`
+      );
+      await github.addPrComment(
+        pull.number,
+        commentStrings.assignReviewersWithExpertise(advice)
+      );
+
+      try {
+        await github.getGitHubClient().rest.pulls.requestReviewers({
+          owner: REPO_OWNER,
+          repo: REPO,
+          pull_number: pull.number,
+          reviewers: advice.selectedReviewers.map((r) => r.username),
+        });
+      } catch (reqErr) {
+        console.warn(
+          `Could not request reviewers via GitHub API for PR ${pull.number}: ${reqErr}`
+        );
+      }
+
+      github.nextActionReviewers(pull.number, pull.labels);
+      prState.nextAction = "Reviewers";
+      await stateClient.writePrState(pull.number, prState);
+      assignedViaAdvisor = true;
+    }
+  } catch (advisorErr) {
+    console.warn(
+      `Advisor selection failed for PR ${pull.number}: ${advisorErr}. Falling back to label rotation.`
+    );
+  }
+
+  if (assignedViaAdvisor) {
+    return;
+  }
+
+  // Fallback: Pick reviewers to assign using label rotation.
   let reviewerStateToUpdate: { [key: string]: typeof ReviewersForLabel } = {};
   const reviewersForLabels: { [key: string]: string[] } =
     reviewerConfig.getReviewersForLabels(pull.labels, [pull.user.login]);

diff --git a/scripts/ci/pr-bot/shared/commentStrings.ts b/scripts/ci/pr-bot/shared/commentStrings.ts
@@ -17,6 +17,7 @@
  */
 
 const { NO_MATCHING_LABEL } = require("./constants");
+import { ReviewerAdviceResult } from "./geminiReviewerAdvisor";
 
 export function allChecksPassed(reviewersToNotify: string[]): string {
   return `All checks have passed: @${reviewersToNotify.join(" ")}`;
@@ -26,9 +27,40 @@ export function assignCommitter(committer: string): string {
   return `R: @${committer} for final approval`;
 }
 
+export function assignReviewersWithExpertise(
+  advice: ReviewerAdviceResult
+): string {
+  let commentString = "### 🧭 Reviewer Assignment\n\n";
+
+  for (const reviewer of advice.selectedReviewers) {
+    const roleBadge =
+      reviewer.role === "primary"
+        ? "**Primary Reviewer**"
+        : "**Secondary Reviewer**";
+    commentString += `- R: @${reviewer.username} (${roleBadge})\n  *Expertise:* ${reviewer.expertise}\n\n`;
+  }
+
+  if (advice.alternateReviewers && advice.alternateReviewers.length > 0) {
+    const alts = advice.alternateReviewers
+      .map((r) => `@${r.username}`)
+      .join(", ");
+    commentString += `*Selected a minimal reviewer set to keep review focused. Backup expert(s): ${alts}*\n\n`;
+  }
+
+  commentString += `Note: If you would like to opt out of this review, comment \`assign to next reviewer\`.
+
+Available commands:
+- \`assign to next reviewer\` - reassign to an alternate reviewer
+- \`stop reviewer notifications\` - opt out of the automated review tooling
+- \`remind me after tests pass\` - tag the comment author after tests pass
+- \`waiting on author\` - shift the attention set back to the author (any comment or push by the author will return the attention set to the reviewers)
+
+The PR bot will only process comments in the main thread (not review comments).`;
+  return commentString;
+}
+
 export function assignReviewer(labelToReviewerMapping: any): string {
-  let commentString =
-    "Assigning reviewers:\n\n";
+  let commentString = "Assigning reviewers:\n\n";
 
   for (let label in labelToReviewerMapping) {
     let reviewer = labelToReviewerMapping[label];