Add policyengine.graph: static variable dependency graph

[MaxGhenis]

Summary

New subpackage policyengine.graph for querying PolicyEngine Variable dependency structure by AST-walking source trees. No runtime dependency on country models — pure static analysis, so it works on any policyengine-us / policyengine-uk checkout regardless of whether the jurisdiction is installed and fully provisioned.

Motivation

grep answers "who mentions this symbol" but not "what is the dataflow DAG." PolicyEngine variables form deep dependency chains — state EITC reads federal EITC reads earned income, state AGI reads federal AGI reads dozens of income components, etc. A graph-shaped API gives meaningful:

• Refactor impact analysis: "what breaks if I change the definition of adjusted_gross_income?"
• CI pre-merge checks: "this PR adds a new variable — is it reachable from anything?"
• Docs generation: auto-generate variable provenance graphs.
• Code-introspection from policyengine-claude (which, per the migration plan, will call policyengine.py as the canonical programmatic contract).

Generic graph tools (I evaluated GitNexus) miss PolicyEngine's core pattern because variables are string-keyed inside formula bodies (person("adjusted_gross_income", period)) rather than imported and called directly. A PolicyEngine-aware extractor is the right shape.

Public API

from policyengine.graph import extract_from_path

graph = extract_from_path("/path/to/policyengine-us/policyengine_us/variables")

graph.deps("adjusted_gross_income")
# ['irs_gross_income', 'above_the_line_deductions', 'basic_income']

graph.impact("adjusted_gross_income")
# [504 downstream variables in policyengine-us]

graph.path("wages", "federal_income_tax")
# ['wages', 'irs_gross_income', 'adjusted_gross_income', 'taxable_income', 'federal_income_tax']

Reference patterns (v1)

1. <entity>("<var>", <period>) — direct call on person / tax_unit / spm_unit / household / family / marital_unit / benunit with a string literal first arg.
2. add(<entity>, <period>, ["v1", "v2"]) — sum helper (also aggr); each string in the list becomes an edge.

Tracked for v2: parameter references (parameters(period).gov...), entity.sum("var") method calls, dynamic variable names (string concatenation / f-strings).

Real-data smoke

Indexing policyengine-us... done: 0.8s, 4577 variables
impact(adjusted_gross_income): 504 variables
deps(adjusted_gross_income): ['irs_gross_income', 'above_the_line_deductions', 'basic_income']

Matches the adjusted_gross_income formula body exactly. 504 transitively dependent variables out of 4577 (≈ 11 % of the US model depends on AGI) — sounds right for a central income concept. Grep finds 202 files; the graph finds 504 variables via transitive chains the single-level grep doesn't follow.

Test plan

• pytest tests/test_graph/test_extractor.py --noconftest — 9 tests pass (regime detection for all 7 patterns + path + non-Variable-class-ignored).
• Tests load the graph submodule via importlib rather than through policyengine/__init__.py. The package init eagerly imports country models, which is fine on CI but fails in dev environments missing release manifests. The graph subpackage is dep-light (stdlib + networkx) so the workaround is clean.
• ruff format --check src/policyengine/graph/ tests/test_graph/ clean.
• Changelog fragment: changelog.d/variable-graph.added.md.

Follow-up ideas

• CLI entry point: pe-graph impact <var>, pe-graph deps <var>, pe-graph path <src> <dst>.
• Parameter graph (v2).
• Graphviz / Mermaid exporter for diagrams.
• Cross-jurisdiction dependency comparison (US AGI vs UK adjusted net income).

🤖 Generated with Claude Code

[MaxGhenis]

Superseded by #306 which landed a broader subpackage plus the reference-documentation generator.