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 npm design tokens:

# Design tokens from app-v2
npm install @policyengine/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:

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

1. Find current endpoint pattern:

   bashCopy

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

2. Follow the pattern (likely FastAPI or Flask)

3. Update OpenAPI spec (may be auto-generated)

4. Add tests:

   bashCopy

   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