Metadata-Version: 2.4
Name: addrkit
Version: 0.1.0
Summary: Address-validation & business-presence toolkit: Google Address Validation, Experian Aperture (QAS Pro), DC MAR, and Google Places behind one normalized ValidationResult. Framework-agnostic; imported as `addverify`.
Author-email: DOES / dboyd <dave@tiggr.org>
License: Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests<3,>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# addrkit

Reusable **address-validation & business-presence** toolkit for DOES apps. Four providers
sit behind one normalized `ValidationResult`, so callers can run any subset and compare
evidence side by side.

- Distribution name: **`addrkit`** · import name: **`addverify`** (same split as `azure-sso` → `azsso`).
- Framework-agnostic core (just `requests`); no web framework, no database, no secrets.
- Extracted from the `add-verify` app so `add-verify`, `add-clean`, and `emp-360` can share
  one copy instead of each carrying their own.

## Providers

| Import | Question it answers | Notes |
|---|---|---|
| `addverify.providers.google` | Is this a deliverable postal address? | Google Address Validation; USPS DPV enrichment. |
| `addverify.providers.experian` | Is this a deliverable address? (+ resolve) | Experian Aperture / QAS Pro. `resolve=True` recovers full addresses from partials. |
| `addverify.providers.mar2` | Is this a real **DC** address? | DC Master Address Repository (MAR 2). DC only — non-DC → `INVALID`. |
| `addverify.providers.places` | Is a **business** operating at this address? | Google Places (New). `verify_business(...)`. |

Every provider returns a `ValidationResult` with a coarse, cross-provider verdict:
`VALID` · `SUSPECT` · `INVALID` · `ERROR`.

## Install (Gitea PyPI registry)

Public PyPI stays primary; the extra index only serves DOES packages. Put the read token in
`pip.conf` rather than inlining it:

```ini
# .venv/pip.conf   (chmod 600)
[global]
extra-index-url = https://<gitea-read-token>@gitea.doesworks.net/api/packages/giteaadmin/pypi/simple
```

```bash
pip install "addrkit==0.1.*"
```

## Quickstart

```python
from addverify import config
from addverify.providers import google, experian, mar2, places

config.load_dotenv()  # optional: load keys from a .env

r = google.validate("1350 Pennsylvania Ave NW, Washington, DC 20004",
                    config.google_key())
print(r.verdict, r.formatted, r.components.get("possible_next_action"))

# DC authoritative source
m = mar2.validate("1350 Pennsylvania Ave NW", config.dc_mar_key())

# business-presence
b = places.verify_business("1912 Pike Pl, Seattle WA",
                          config.places_key(), business_name="Starbucks")
```

### The `ValidationResult` contract

```python
ValidationResult(
    provider,      # 'GOOGLE' | 'QAS' | 'MAR2' | 'PLACES'
    verdict,       # VALID | SUSPECT | INVALID | ERROR
    confidence,    # provider-native confidence/granularity
    input_address,
    formatted,     # standardized/canonical address
    components,    # dict of evidence highlights (DPV, ward, score, next action, …)
    raw,           # full provider response(s)
    error,
)
```

## CLI

The package ships an `addverify` console script (and `python -m addverify`):

```bash
addverify "1600 Amphitheatre Pkwy, Mountain View, CA 94043" --provider both
addverify "1350 Pennsylvania Ave NW, Washington, DC 20004" --provider all      # Google + QAS + MAR
addverify --input-csv addresses.csv --provider all --resolve                   # batch mode
```

## Configuration

Keys come from the environment (or a `.env` via `config.load_dotenv()`); the library never
hard-codes them. See `.env.example`:

| Var | Used by |
|---|---|
| `GOOGLE_ADDRESS_API_KEY` | google |
| `GOOGLE_PLACES_API_KEY` (falls back to the address/maps key) | places |
| `EXPERIAN_QAS_TOKEN` | experian |
| `DC_MAR_API_KEY` | mar2 |

## Development

```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m unittest            # fast, offline
ADDVERIFY_SMOKE=1 .venv/bin/python -m unittest tests.test_pip_install_smoke   # opt-in install test
```

## Releasing

SemVer; bump `addverify.__version__` (the dist version is dynamic from it), then build and
publish to the Gitea PyPI registry:

```bash
.venv/bin/python -m build
.venv/bin/twine upload --repository-url https://gitea.doesworks.net/api/packages/giteaadmin/pypi \
    -u <gitea-user> -p <publish-token> dist/*
```
