Know what a metric-definition change means before it changes the business.
Business metrics are not just numbers on a dashboard. They are executable definitions of how a business works. Branchline makes changes to those definitions reviewable before they affect reports, alerts, or AI-assisted analysis.
A metric tree is a computable map of how a business outcome is produced by its drivers.
flowchart BT
Visitors[Visitors] --> Orders[Orders]
Conversion[Conversion rate] --> Orders
Orders --> Revenue[Revenue]
AOV[Average order value] --> Revenue
For this example:
Orders = Visitors × Conversion rate
Revenue = Orders × Average order value
If revenue changes, the tree gives a system a principled path to investigate the drivers beneath it. The tree is deterministic when its arithmetic is governed: given the same data and the same definitions, it produces the same answer every time.
Teams increasingly keep metric-tree definitions in Git, which is the right instinct. But a text diff does not describe the business consequence of a change.
- net_revenue = gmv * take_rate
+ net_revenue = gmv * take_rate - refundsThat one-line pull request may be correct, but it is not a cosmetic edit. It changes the definition of Net Revenue, restates historical results, changes recurring reports, and requires the right domain owners to understand the change.
Most configuration checks answer only: “Is this YAML valid?”
This project answers the more useful question:
What changed in the business model, what did it change historically, and who should review it before merge?
Branchline validates a tree, compares a base definition with a proposed one, replays both against representative data, and produces a semantic pull-request review.
flowchart LR
PR["Metric-tree pull request"] --> Python["Python computation engine"]
Data["Approved replay data"] --> Python
Python --> Report["Versioned impact-report.json"]
Report --> TypeScript["TypeScript review adapter"]
TypeScript --> Review["PR summary: restatement, owners, contracts"]
The demo change adds refunds to the Net Revenue definition. Its replay reports a $2,700 / 5.21% historical downward restatement and suggests both Finance and Customer Experience as reviewers.
- Validates metric references, duplicate IDs, graph cycles, safe formulas, and unit algebra.
- Differentiates arithmetic identities, decompositions, observations, experiments, and hypotheses.
- Computes a semantic diff and downstream blast radius.
- Replays base and proposed deterministic definitions against a representative CSV extract.
- Classifies the change as
patch,minor, ormajor. - Runs structured analysis contracts—the deterministic seam an eventual agent-evaluation harness can use.
- Emits a versioned JSON report in Python and renders a human-readable PR artifact in TypeScript.
The language split follows responsibilities rather than novelty:
| Layer | Language | Responsibility |
|---|---|---|
| Computation | Python | Graph validation, formula evaluation, replay, restatement, analysis contracts |
| Integration | TypeScript | Typed report boundary, Markdown PR renderer, Node/GitHub integration point |
The two layers communicate through impact-report.json, whose report_version makes the boundary evolvable and testable.
This repository uses uv for every Python setup, dependency, test, and command workflow.
uv sync --all-groups
npm ci
uv run pytest
npm run test:tsGenerate the end-to-end review artifact:
uv run branchline impact examples/revenue_base.yml examples/revenue_pr.yml \
--data fixtures/monthly_marketplace.csv \
--contracts examples/analysis_contracts.yml \
--output impact-report.json
npm run build
node dist/typescript/cli.js --report impact-report.json --output pr-review.mdThe resulting examples/expected-impact-report.json is a stable example of the Python-to-TypeScript contract.
uv run branchline check examples/marketplace.yml
uv run branchline diff examples/marketplace_base.yml examples/marketplace.yml
uv run branchline report examples/marketplace.yml \
--compare examples/marketplace_base.yml \
--output report.htmlThe repository intentionally uses an illustrative YAML schema and CSV replay data so it is self-contained. It does not claim causal inference: an arithmetic identity is exact, while an observed or hypothesized relationship needs different evidence.
A production adapter would replace the CSV replay with governed DuckDB or warehouse queries over an approved snapshot, enforce metric-grain compatibility, capture query/source revisions, and publish an idempotent GitHub PR comment.
For implementation detail and trade-offs, see the architecture notes.