Metadata-Version: 2.4
Name: policyengine-household-api
Version: 0.14.4
Summary: PolicyEngine Household API
Author-email: PolicyEngine <hello@policyengine.org>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: anthropic
Requires-Dist: authlib>=1.7.0
Requires-Dist: cloud-sql-python-connector
Requires-Dist: flask-caching==2.0.2
Requires-Dist: flask-cors>=3
Requires-Dist: flask-limiter
Requires-Dist: flask-sqlalchemy>=3
Requires-Dist: flask>=2.2
Requires-Dist: google-cloud-logging
Requires-Dist: google-cloud-storage
Requires-Dist: gunicorn
Requires-Dist: inflect
Requires-Dist: joserfc>=1.6.0
Requires-Dist: policyengine-canada==0.96.3
Requires-Dist: policyengine-il==0.1.0
Requires-Dist: policyengine-ng==0.5.1
Requires-Dist: policyengine-uk==2.31.0
Requires-Dist: policyengine-us==1.663.0
Requires-Dist: pydantic
Requires-Dist: pyjwt
Requires-Dist: pymysql
Requires-Dist: python-dotenv
Requires-Dist: urllib3<=1.26.20,>=1.21.1
Provides-Extra: dev
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: towncrier>=24.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# PolicyEngine Household API 

A version of the PolicyEngine API that runs the `calculate` endpoint over household object. To debug locally, run `make debug`. 

## Quick self-hosted run

If you want to try the API without requesting hosted credentials, run the published Docker image:

```
docker run --rm -p 8080:8080 ghcr.io/policyengine/policyengine-household-api:latest
```

The image can take a little time to initialize on first start and is best run on a machine with roughly
4 GB of RAM available.

Then inspect the service metadata:

```
curl http://localhost:8080/
```

and send calculations to:

```
http://localhost:8080/us/calculate
```

Hosted API docs live at https://www.policyengine.org/us/api.

## Local development with Docker Compose

To run this app locally via Docker Compose:

```
% make docker-build
% make docker-run
```

and point your browser at http://localhost:8080 to access the API.

To develop the code locally, you will want to instead start only the Redis docker container and a one-off
API container, with your local filesystem mounted into the running docker container.

```
% make services-start
% make docker-console
```

Then inside the container, start the Flask service:

```
policyapi@[your-docker-id]:/code$ make debug
```

and point your browser at http://localhost:8080 to access the API.

### Running with other PolicyEngine services

If you're running this alongside other PolicyEngine services (e.g., the main API) and need
containers to communicate across projects, use the external network mode:

```
% make docker-network-create   # Create shared network (once)
% make docker-run-external     # Run with external network
```

This connects the household API to a shared `policyengine-api_default` network that other
PolicyEngine docker-compose projects can also join.

For development with external networking:

```
% make docker-network-create
% make services-start-external
% make docker-console
```

## Development rules

1. Every endpoint should return a JSON object with at least a "status" and "message" field.

Please note that we do not support branched operations at this time.
