API hierarchy design
Three-level architecture for simulations, analyses, and reports.
Levels of analysis
Level 2
Reports
AI-generated documents orchestrating multiple jobs. Future feature.
Level 1
Analyses
Operations on simulations - thin wrappers around policyengine package functions.
/analysis/decile-impact/*/analysis/budget-impact/*/analysis/winners-losers/*/analysis/compare/*Level 0
Simulations
Single world-state calculations - the foundation for all analyses.
/simulate/household/simulate/economyModal functions
All compute runs on Modal.com serverless functions with sub-1s cold starts.
| Function | Purpose |
|---|---|
| simulate_household_uk/us | Single household calculation |
| simulate_economy_uk/us | Single economy simulation |
| economy_comparison_uk/us | Economy comparison (decile impacts, budget) |
Mapping to policyengine package
| API endpoint | policyengine function |
|---|---|
| /simulate/household | calculate_household_impact() |
| /simulate/economy | Simulation.run() |
| /analysis/decile-impact/* | calculate_decile_impacts() |
| /analysis/budget-impact/* | ProgrammeStatistics |
| /analysis/winners-losers/* | ChangeAggregate |
Use cases
My tax under current law
/simulate/householdReform impact on my household
/analysis/compare/householdRevenue impact of reform
/analysis/budget-impact/economyDecile breakdown of reform
/analysis/decile-impact/economyWho wins and loses
/analysis/winners-losers/economyFull reform analysis
/analysis/compare/economy