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. Optionally pass output_name to focus the returned diff on one top-level output key after both full project runs complete. model_name is a legacy compatibility hint used only for optional model existence checks; it does not narrow execution scope. Use this after creating a scenario branch and editing project files on it — this is step 3 of the scenario workflow: (1) create_branch, (2) patch_file/update_file for model edits or update_file(path=‘run.py’, …) for run.py changes on the scenario branch, (3) compare_branches to see the output diff, (4) merge_branch (Owner) or merge_pull_request to adopt the winning scenario. Returns: project (str) — project name; model_name (str, optional, legacy) — compatibility hint for model existence checks only; output_name (str, optional) — focus the returned diff on one top-level output key while still executing the full project on both branches; base_branch (str); base_commit_sha (str); base_status (str); scenario_branch (str); scenario_commit_sha (str); scenario_status (str); data_snapshot_ref (str|null) — shared data snapshot used; diff (list[{metric, base_value, scenario_value, absolute_delta, pct_delta, significant}]) — per-metric comparison; summary (dict) — aggregated delta statistics plus changed_outputs/table_summaries; finance_summary (dict, optional) — finance-aware view of list-of-dict outputs: per-column deltas with trend direction (up/down/flat/mixed) and sign-flip flag, row-keyed pairwise deltas when a period/month/date key is found, or shape_diverged warning when column schemas or row counts are incompatible; errors (list[str], optional) — run errors if any branch failed.

read-only

Parameters

Name	Type	Required	Default	Description
`project_name`	`str`	Yes	—
`scenario_branch`	`str`	Yes	—
`model_name`	`str	None`	No	`None`
`output_name`	`str	None`	No	`None`
`base_branch`	`str`	No	`'main'`

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.