Metadata-Version: 2.5
Name: ng-address-resolver
Version: 0.1.0
Summary: Resolve free-text Nigerian addresses to NIPOST digital postcodes (NDAPS), only as precisely as the evidence allows.
Project-URL: Repository, https://github.com/Adeniyikayodee/ng-postcode
Author: Kayode Adeniyi
License-Expression: MIT
License-File: LICENSE
Keywords: address,address-parser,ai-agents,claude,geocoding,ndaps,nigeria,nipost,postcode
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: ng-postcode[client]<0.2,>=0.1
Requires-Dist: pydantic>=2.7
Provides-Extra: claude
Requires-Dist: anthropic<2,>=1.11; extra == 'claude'
Description-Content-Type: text/markdown

# ng-address-resolver

Resolve free-text Nigerian addresses, such as "back of Fabian Hotel, off NTA Road, Ado Ekiti", to NIPOST digital postcodes (NDAPS). It answers only as precisely as the evidence allows, and asks a question when it cannot.

**Status: pre-release.** The workflow is tested against mocked Claude, NIPOST and geocoder APIs. It has not yet been run end to end with live NIPOST and Claude credentials, and its accuracy on real addresses is unmeasured.

## How it decides

1. **A postcode written in the text** is extracted (never auto-corrected) and confirmed with NIPOST.
2. **A location pin** is reverse-geocoded by NIPOST. This is the only route to a high-confidence building code.
3. **Text only** is read by Claude into street, landmarks and their relation ("behind", "opposite", "at"), area, LGA and state, then placed with a geocoder and reverse-geocoded by NIPOST.

| Evidence | Answer |
| --- | --- |
| Typed postcode NIPOST confirms, or a pin within 10 m of a building | Building code, high confidence |
| A pin within 25 m, or the landmark the address *is* | Building code, medium confidence |
| A building near a landmark ("behind", "opposite") | Area code, e.g. `EK-01-A03-FK` |
| A street only | District code, low confidence |
| A town only, or nothing found | No code, plus a question for the user |

Text alone rarely identifies a building: a landmark's own building is not the one behind it, and a road's map point is not any house on it. Ask users for a location pin when you need the exact building.

## Usage

```sh
ng-address "back of Fabian Hotel, off NTA Road, Ado Ekiti"
ng-address "my house" --lat 7.6211 --lng 5.2214
```

The result is JSON: `status` (`resolved`, `partial`, `unresolved`), `code`, `level`, `confidence`, `method`, `question` and the `evidence` behind it.

```python
from ng_address import Resolver

result = await Resolver(nipost=..., parser=..., geocoder=...).resolve("...")
```

The core needs no model. Install `ng-address-resolver[claude]` to let the CLI and `ng_address.parse.ClaudeParser` read addresses with Claude. A caller that has already read the address, such as the host model of an MCP server, passes its own `ParsedAddress` as `resolve(..., parsed=...)` instead.

## Configuration

| Variable | Purpose |
| --- | --- |
| Anthropic credentials | Needs the `claude` extra. Read by the Anthropic SDK (`ANTHROPIC_API_KEY` or an `ant auth login` profile). Without them the raw text is searched instead. |
| `NG_POSTCODE_API_KEY` | NIPOST API key. Without it no postcode can be returned. |
| `NG_GEOCODER_URL` | A Nominatim server, ideally your own. |
| `NG_GEOCODER_CONTACT` | A URL or email sent in the User-Agent to identify you. Required for the public Nominatim. |
| `NG_ADDRESS_MODEL` | Claude model. Defaults to `claude-opus-5-5`. |

The public Nominatim at `https://nominatim.openstreetmap.org` allows light personal use only. A service whose main job is geocoding must run its own instance or use a commercial geocoder. Map data © OpenStreetMap contributors.

Each address uses at most one Claude call at low effort, up to three geocoder searches, and one or two NIPOST calls.

## License

MIT
