Add UK Gift Aid support with PolicyEngine-UK

[MaxGhenis]

Summary

This PR adds UK tax calculation support to GiveCalc, enabling UK users to calculate the tax impact of charitable donations via Gift Aid.

Dependencies

Blocked by: PolicyEngine/policyengine-uk#1430 - Fix Gift Aid Personal Allowance taper interaction

This PR depends on the policyengine-uk fix for Gift Aid PA taper calculation. Once that PR is merged and released, the policyengine-uk version constraint here can be updated.

Changes

New UK Module (givecalc/uk/)

• constants.py: UK-specific constants (tax year, regions)
• situation.py: Creates PolicyEngine-UK situations with donation axes
• tax.py: UK tax calculations (marginal savings, donation effects)

API Endpoints (api/main.py)

• GET /api/uk/regions: List UK regions grouped by nation
• GET /api/uk/tax-programs: Gift Aid program information
• POST /api/uk/calculate: Calculate UK tax impact of Gift Aid donations

Schemas (api/schemas.py)

• UKIncomeInput, UKCalculateRequest, UKCalculateResponse
• UKRegionInfo, UKRegionsResponse
• UKDonationDataPoint, UKTaxProgramsResponse

Dependencies

• Added policyengine-uk>=2.45.0,<2.55.0 (Python 3.12 compatible)
• Includes workaround for policyengine-uk dataset attribute bug (fixed in 2.55.0+ which requires Python 3.13+)

UK Tax System Details

Gift Aid provides tax relief in two ways:

1. Charity reclaim: Charities reclaim 25p per £1 donated (basic rate relief at 20%)
2. Donor relief: Higher rate (40%+) taxpayers claim additional relief personally

Example for a £100 donation by a 40% taxpayer:

• Charity receives: £100 + £25 (basic rate reclaim) = £125
• Donor claims: £25 (difference between 40% and 20% on £125 gross)
• Net cost to donor: £75

Supports all UK regions including Scotland (with different income tax rates).

Testing

47 new tests covering:

• UK situation creation (18 tests)
• UK tax calculations (14 tests)
• UK API endpoints (13 tests)

All 80 tests pass (existing + new).

Related Issues

Closes #58 (parent issue)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
givecalc	Ready	Preview	Comment	Dec 2, 2025 4:42pm

[MaxGhenis]

Review: Vercel Deployment Setup

I noticed the Vercel deployment is running on this PR. There was a recent issue where Vercel needs the Root Directory set to frontend in the Vercel dashboard (not in vercel.json) to avoid hitting the 250MB serverless function limit.

What happened with the Vercel setup:

1. The vercel.json file was moved from repo root to frontend/vercel.json (PR #69)
2. The Root Directory must be set to frontend in the Vercel dashboard settings (Project Settings → Root Directory)

To fix Vercel deployments for this branch:

1. First, check if the vercel.json exists at frontend/vercel.json - if not, you need to add it:

{
  "buildCommand": "npm install && npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "installCommand": "npm install"
}

2. Make sure there's NO vercel.json in the repository root - Vercel should only look at the frontend folder

3. The Vercel dashboard should have Root Directory = frontend

What likely went wrong:

If there's still a vercel.json at the root OR if the dashboard Root Directory isn't set, Vercel will try to deploy the entire repo including the Python api/ folder, which exceeds the 250MB limit.

Check your branch to ensure vercel.json is ONLY in frontend/ and not at the repo root.

[MaxGhenis]

Update: I checked your branch - the vercel.json setup looks correct:

• ✅ No vercel.json at repo root
• ✅ frontend/vercel.json exists with correct config

The Vercel deployment should work as long as the Vercel dashboard has Root Directory set to frontend. If it wasn't set before, you may need to wait for Vercel to re-deploy or trigger a new deployment after confirming the dashboard setting.

Everything else in the PR looks good - comprehensive UK Gift Aid support with 47 new tests!