compare_branches

Run a project on two branches concurrently and compare the resulting outputs side-by-side. Returns a structured project-output diff with absolute and percentage deltas for every changed metric. Changes of 10% or more are flagged as significant. Both branches run against the same data snapshot for an apples-to-apples comparison.

read-only

Parameters

Name	Type	Required	Default	Description
project_name	Annotated[str, Field(description='Name of the Bridge Town project.')]	Yes	—
scenario_branch	Annotated[str, Field(description='Name of the scenario branch to compare against the base.')]	Yes	—
model_name	`Annotated[str	None, Field(description=“Model entry point to run for comparison (without .py extension). Defaults to ‘run’.”)]`	No	None
output_name	`Annotated[str	None, Field(description=‘Named output from the model run to compare. Omit to compare all outputs.’)]`	No	None
base_branch	Annotated[str, Field(description="Base branch to compare against (typically 'main').")]	No	'main'
ctx	`Context	None`	No	None

Returns

Returns a structured object. Top-level fields:

• project (string)
• base_branch (string)
• base_commit_sha (string)
• base_status (string)
• scenario_branch (string)
• scenario_commit_sha (string)
• scenario_status (string)
• data_snapshot_ref (null)
• diff (array<object>)
• summary (object)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "compare_branches",
  "arguments": {
    "project_name": "forecasts",
    "scenario_branch": "scenario/aggressive-growth",
    "model_name": "revenue",
    "output_name": "revenue",
    "base_branch": "main"
  }
}

Response

{
  "project": "forecasts",
  "base_branch": "main",
  "base_commit_sha": "abc1234def5678901234567890abcdef12345678",
  "base_status": "success",
  "scenario_branch": "scenario/aggressive-growth",
  "scenario_commit_sha": "0123456789abcdef0123456789abcdef01234567",
  "scenario_status": "success",
  "data_snapshot_ref": null,
  "diff": [
    {
      "metric": "revenue",
      "base_value": 100,
      "scenario_value": 120,
      "significant": true,
      "absolute_delta": 20,
      "pct_delta": 0.2
    },
    {
      "metric": "revenue",
      "base_value": 110,
      "scenario_value": 138,
      "significant": true,
      "absolute_delta": 28,
      "pct_delta": 0.255
    }
  ],
  "summary": {
    "total_diff": 48,
    "rows_compared": 2
  }
}

Notes

• Module: Scenario Comparison
• Requires authentication via API token or Auth0 JWT.