Skip to content

About

Semantic change review for versioned metric trees

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🌿 Branchline

Know what a metric-definition change means before it changes the business.

Branchline mark

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.

First: what is a metric tree?

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
Loading

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.

The problem

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 - refunds

That 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?

The solution

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"]
Loading

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.

Capabilities

  • 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, or major.
  • 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.

Why Python and 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.

Quick start

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:ts

Generate 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.md

The resulting examples/expected-impact-report.json is a stable example of the Python-to-TypeScript contract.

Other useful commands

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.html

Scope and next steps

The 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.

About

Semantic change review for versioned metric trees

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages