Metadata-Version: 2.4
Name: houses-client
Version: 1.4.0
Summary: Python SDK for the Mayo Clinic HOUSES API
Author-email: Tim Tschampel <tschampel.timothy@mayo.edu>
License: MIT
Project-URL: Homepage, https://www.mayo.edu/research/centers-programs/mayo-clinic-houses-program/overview
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: oidc-client==0.2.6
Requires-Dist: requests<3,>=2.31
Dynamic: license-file

# houses-client

Python SDK for the [Mayo Clinic HOUSES API](https://www.mayo.edu/research/centers-programs/mayo-clinic-houses-program/overview).

## Requirements

Python 3.11+

## Installation

```shell
pip install houses-client
```

## Usage

### Synchronous lookup (small batches up to 25 addresses)

```python
from houses_client import HousesClient

client = HousesClient(
    api_endpoint="https://houses.konfidential.io",
    client_id="my oidc client id",
    client_secret="my oidc client secret",
)

result = client.lookup(
    addresses=[
        {"id": "1", "address": "123 Main St", "city": "Rochester", "state": "MN", "zip": "55905"},
        {"id": "2", "address": "456 Main St Anytown NY 55555"},
    ],
    year=2021,
)
print(result["results"])
```

### Async batch (any size, file-based)

```python
client.batch(
    input_path="myinput.csv",
    output_path="myoutput.csv",
    year=2021,
    delimiter=",",
)
```

### Index metadata

```python
client.metadata()  # available years and index versions
```

### Self-hosted mode (no auth)

```python
client = HousesClient(api_endpoint="http://localhost:9002", self_hosted=True)
```

### Errors

The SDK raises typed exceptions you can catch:

| Exception              | Raised when                                            |
|------------------------|--------------------------------------------------------|
| `ConfigurationError`   | Missing required constructor arguments                 |
| `AuthenticationError`  | OIDC login or token refresh fails                      |
| `APIError`             | The API returns a non-2xx status (`status_code`, `body`) |
| `TaskError`            | An async batch task reports `ERROR` status             |
| `HousesError`          | Base class for all of the above                        |

```python
from houses_client import HousesClient, APIError, TaskError

try:
    client.batch(input_path="in.csv", output_path="out.csv", year=2021)
except APIError as e:
    print(f"API failed: status={e.status_code}, body={e.body}")
except TaskError as e:
    print(f"Task failed: {e}")
```

## Constructor options

| Property        | Type    | Default   | Description                                          |
|-----------------|---------|-----------|------------------------------------------------------|
| `api_endpoint`  | str     | required  | HOUSES API base URL                                  |
| `client_id`     | str     | None      | OIDC Client ID (required unless `self_hosted=True`)  |
| `client_secret` | str     | None      | OIDC Client Secret (required unless `self_hosted`)   |
| `self_hosted`   | bool    | `False`   | Skip OIDC; uses anonymous auth                       |
| `log_level`     | str     | `"INFO"`  | One of `DEBUG`, `INFO`, `WARNING`, `ERROR`           |
| `timeout`       | float   | `60.0`    | Per-request HTTP timeout in seconds                  |

## CLI

After installing, the `houses-client` console script is available:

```shell
houses-client \
    -e http://localhost:9002 \
    -i sample1.csv \
    -o sample1_output.csv \
    -y 2021 \
    -d , \
    --selfhosted
```

Run `houses-client --help` for the full option list.

## Input data schema

### Single-string address

```
id,address,year
1,"123 main st anytown ny 5555",2019
2,"456 main st anytown ny 55555",2018
```

The address string should include at least one of: city+state, city, state, or zip.
The `year` column is optional and overrides the request-level year. Add a
`referenceAddress` column to override per-row.

### Component address

```
id,address,secondary,city,state,zip,year
1,"123 main st","Apt 4B","Anytown","NY","55555",2019
```

## Build

```shell
python3 -m pip install --upgrade build
python3 -m build
```

The version is read from `houses_client.__version__`. Bump it in
`houses_client/__init__.py` before building.
