Sensitivity registry for PolicyEngine microsim results — maps {program × deviation signature} to the most likely calibration target or imputed variable driving the mismatch. The knowledge base that powers the calibration-diagnostics agent. Load when investigating why a microsim result differs from a prior score, or when reviewing whether a reform classification is calibration-sensitive. Triggers: "why does my reform not match", "policyengine cost off", "calibration mismatch", "imputed variable", "takeup rate", "non-filer", "itemizer share", "small state variance", "ECPS calibration target", "policyengine-us-data target", "calibration dashboard", "diagnose mismatch", "deviation signature".

2026-06-220

policyengine-prior-scores

PolicyEngine/policyengine-skills

Structured index of PolicyEngine's previously-published scored reforms. Use this skill to find an anchor for Stage 5 comparison in /analyze-policy, or any time you need a benchmark magnitude for a new policy analysis. Returns a queryable mapping of {reform name → (cost, poverty, distribution, year, methodology)} drawn from policyengine.org/{us,uk,canada}/research and blog.policyengine.org. Triggers: "prior PE score", "PolicyEngine has scored", "what did PE find", "PE benchmark", "anchor reform", "comparable reform", "EITC expansion scored", "CTC expansion scored", "SALT cap analysis", "state CTC analysis", "ARPA reform impact", "American Family Act score".

2026-06-220

python

PolicyEngine/policyengine-skills

ALWAYS LOAD THIS SKILL before setting up any Python environment or installing packages. Defines the standard: uv, Python 3.13, uv pip install, .venv at project root. Triggers: "set up python", "install python", "create a venv", "virtual environment", "pip install", "install packages", "uv pip", "uv venv", "python version", "VIRTUAL_ENV", "venv conflict", "which python", "activate", "deactivate", "run the script", "run with uv", "uv run", "pyproject.toml", "install dependencies", "install requirements", "install the package", "editable install", "pip install -e", "latest package", "latest version", "current version", "newest version".

2026-06-070

policyengine-microsimulation

PolicyEngine/policyengine-skills

ALWAYS USE THIS SKILL for PolicyEngine microsimulation, population-level analysis, winners/losers calculations. Triggers: microsimulation, share who would lose/gain, policy impact, national average, weighted analysis, cost, revenue impact, budgetary, estimate the cost, federal revenues, tax revenue, budget score, how much would it cost, how much would the policy cost, total cost of, aggregate impact, cost to the government, revenue loss, fiscal impact, poverty impact, child poverty, deep poverty, poverty rate, poverty reduction, how many people lifted out of poverty, SPM poverty, distributional impact, state tax, state-level, California, New York, UBI, universal basic income, flat tax, standard deduction, winners and losers, winners, losers, inequality, Gini, decile, SALT, marginal tax rate, effective tax rate. NOT for single-household calculations like "what would my benefit be" - use policyengine-us or policyengine-uk for those. Use this skill's code pattern; explore codebase for parameter paths if needed.

2026-06-070

policyengine-python-client

PolicyEngine/policyengine-skills

ONLY use this skill when users explicitly ask about the PolicyEngine Python package installation, REST API endpoints, API authentication, rate limits, or policyengine.py client library. DO NOT use for household benefit/tax calculations — ALWAYS use policyengine-us or policyengine-uk instead. This skill is about the API/client tooling itself, not about calculating benefits or taxes.

2026-06-070

policyengine-canada

PolicyEngine/policyengine-skills

ALWAYS LOAD THIS SKILL FIRST before writing PolicyEngine-Canada code or answering household-level Canadian tax/benefit questions. Covers federal/provincial rules for household calculations. IMPORTANT: no representative population microdata; do NOT attempt microsimulation or population-level estimates. Only household-level analysis. Triggers: what would, how much would a, benefit be, eligible for, qualify for, single parent, married couple, family of, household of, if they earn, earning $, making $, calculate benefits, calculate taxes, benefit for a, what would I get, maximum, rate, income limit, benefit amount, compare provinces, CCB, Canada Child Benefit, GST credit, HST credit, GST/HST, OAS, GIS, CWB, Canada Workers Benefit, EI, CPP, Ontario Child Benefit, OCB, OTB, BC Climate Action, Alberta Child Benefit, Quebec, CRA, Canadian, Canada, Ontario, British Columbia, Alberta, Saskatchewan, Manitoba, Nova Scotia, New Brunswick, PEI, Newfoundland, Yukon, NWT, Nunavut, provincial tax, federal tax Canada.

2026-05-200

name	policyengine-api-v2
description	PolicyEngine API v2 - Next-generation microservices architecture with monorepo structure

PolicyEngine API v2

The next-generation PolicyEngine API is a monorepo containing multiple microservices built with modern Python tooling.

For Users

What is API v2?

API v2 is the next generation of the PolicyEngine API, currently in active development. When complete, it will replace the current Flask API with a more scalable, maintainable microservices architecture.

Status: 🚧 Active development (not yet in production)

Key improvements over v1:

Microservices architecture for better scalability
Modern Python tooling (Python 3.13+, uv package manager)
Docker-based development and deployment
Auto-generated OpenAPI specs and clients
Supabase for database management

For Analysts

When to Use v2

Currently, analysts should continue using the v1 API at https://api.policyengine.org.

API v2 is not yet ready for production use. Check the repository README for the latest status.

For Contributors

Repository

Location: PolicyEngine/policyengine-api-v2

Clone:

git clone https://github.com/PolicyEngine/policyengine-api-v2
cd policyengine-api-v2

Architecture Overview

API v2 is a monorepo containing multiple microservices:

To see current structure:

tree -L 2 .

# Expected structure:
# ├── api-full/        - Main API (port 8081)
# ├── api-simulation/  - Economic simulation (port 8082)
# ├── api-tagger/      - Deployment management (port 8083)
# ├── docker-compose.yml
# └── shared/          - Shared utilities

Microservices

1. api-full (port 8081)

Main API service
Household calculations
Policy management
Most endpoints from v1

2. api-simulation (port 8082)

Economic simulation engine
Population-wide impact calculations
Resource-intensive operations

3. api-tagger (port 8083)

Deployment management
Version tagging
Release coordination

Technology Stack

To see current dependencies:

# Check pyproject.toml in each service
cat api-full/pyproject.toml
cat api-simulation/pyproject.toml
cat api-tagger/pyproject.toml

Key technologies:

Python 3.13+ - Latest Python version
uv - Fast Python package manager
Docker + Docker Compose - Local development and deployment
Supabase - PostgreSQL database with auth
OpenAPI - API specification generation
FastAPI or Flask - (check current implementation)

Development Setup

To start all services locally:

# See current docker-compose setup
cat docker-compose.yml

# Start services
docker-compose up

# Services should be available at:
# - http://localhost:8081 (api-full)
# - http://localhost:8082 (api-simulation)
# - http://localhost:8083 (api-tagger)

Alternative: Run individual service:

cd api-full
uv pip install -e .
python main.py  # or whatever the entry point is

Package Management with uv

API v2 uses uv instead of pip for faster dependency management:

To see current uv usage:

# Check if uv is used
cat pyproject.toml | grep -A 5 "tool.uv"

# Or check for uv.lock files
find . -name "uv.lock"

Common uv commands:

# Install dependencies
uv pip install -e .

# Add a dependency
uv add package-name

# Sync dependencies
uv sync

Supabase Integration

To see current Supabase setup:

# Check for Supabase configuration
cat .env.example | grep SUPABASE
grep -r "supabase" . --include="*.py" | head -10

# Supabase client initialization
grep -r "create_client" . --include="*.py"

Common patterns:

# Example (check actual implementation)
from supabase import create_client

supabase = create_client(supabase_url, supabase_key)

# Query
result = supabase.table('policies').select('*').execute()

# Insert
supabase.table('policies').insert({'data': policy}).execute()

Design Tokens Integration

API v2 may integrate with design tokens from policyengine-app-v2:

To check design token usage:

# Look for design token imports
grep -r "design.*token\|designTokens" . --include="*.py"
grep -r "@policyengine/design" package.json

# Check if tokens are in dependencies
cat package.json | grep -A 5 "dependencies"

If using design tokens:

# Design tokens currently live in PolicyEngine frontend repos, not a public npm package.
# Inspect local/workspace token sources instead of installing an unclaimed package name.
rg "design.*token|designTokens" ../policyengine-app-v2 ../policyengine-ui-kit package.json

# If a repo defines a local workspace package, install it by explicit local path.
bun add ./path/to/design-tokens

OpenAPI Specification

To see current API spec generation:

# Look for OpenAPI/Swagger setup
grep -r "openapi\|swagger" . --include="*.py"

# Check for spec files
find . -name "openapi*.json" -o -name "openapi*.yaml"

# If using FastAPI, specs auto-generated at /docs

Testing

To see current test setup:

ls -la tests/
cat pytest.ini  # or pyproject.toml for pytest config

Run tests:

# All services
pytest

# Specific service
cd api-full && pytest

# With docker-compose
docker-compose run api-full pytest

Migration from v1

Key architectural differences:

Aspect	v1 (Flask monolith)	v2 (Microservices)
Structure	Single Flask app	Multiple services
Database	Redis + Cloud SQL	Supabase (PostgreSQL)
Deployment	Google App Engine	Docker containers
Package manager	pip	uv
Python version	3.9+	3.13+

To understand migration patterns:

# Compare endpoint implementations
# v1: policyengine-api/policyengine_api/endpoints/
# v2: api-full/endpoints/ (or similar)

# See what's been ported
git log --grep="migrate\|port" --oneline

Common Development Tasks

Task 1: Add New Endpoint to api-full

Find current endpoint pattern:

# Look at existing endpoints
ls api-full/endpoints/  # or api-full/routes/
cat api-full/endpoints/example.py

Follow the pattern (likely FastAPI or Flask)
Update OpenAPI spec (may be auto-generated)
Add tests:
```
cat tests/test_endpoints.py
```

Task 2: Work with Supabase

# See current database schema
cat supabase/migrations/*.sql  # if using migrations

# Test database locally
docker-compose up supabase  # if in docker-compose

Task 3: Use Design Tokens

# Check if design tokens are integrated
grep -r "design.*token" .

# If using from app-v2, import them:
# (Actual implementation depends on current setup)

Environment Variables

To see required environment variables:

cat .env.example

# Common variables:
# - SUPABASE_URL
# - SUPABASE_KEY
# - DATABASE_URL
# - API_PORT (8081, 8082, 8083)

Monorepo Best Practices

To see current monorepo structure:

# List all services
ls -d */

# Check for shared code
ls shared/ common/ lib/  # (if exists)

# See inter-service dependencies
grep -r "../api-" pyproject.toml

Pattern:

Each service should be independently deployable
Shared code goes in shared/ or similar
Each service has its own tests
Docker Compose for local multi-service development

Related Skills

policyengine-api-skill - v1 API patterns (for migration reference)
policyengine-core-skill - Understanding the simulation engine
policyengine-us-skill - Country model integration
policyengine-design-skill - Design tokens and branding
policyengine-standards-skill - Code quality standards

Resources

Repository: https://github.com/PolicyEngine/policyengine-api-v2

Related:

v1 API: https://github.com/PolicyEngine/policyengine-api
App v2 (design tokens): https://github.com/PolicyEngine/policyengine-app-v2
Supabase: https://supabase.com/docs

Development Status

⚠️ Important: API v2 is in active development. Always check the repository README for:

Current status and roadmap
Breaking changes
Migration timeline from v1
Deployment instructions

To see current status:

cat README.md
git log -10 --oneline