feat: add libpostal docker image and api entrypoint

Author: github-actions

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+# Install system dependencies for libpostal
+RUN apt-get update && apt-get install -y \
+    build-essential curl automake autoconf libtool pkg-config git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Build and install libpostal from source
+RUN git clone https://github.com/openvenues/libpostal.git /tmp/libpostal \
+    && cd /tmp/libpostal \
+    && ./bootstrap.sh \
+    && ./configure --datadir=/usr/local/share/libpostal \
+    && make \
+    && make install \
+    && ldconfig \
+    && rm -rf /tmp/libpostal
+
+WORKDIR /app
+
+# Allow overriding install ref (defaults to main)
+ARG RYANDATA_ADDR_UTILS_REF=main
+
+# Install the package from git ref
+RUN pip install --no-cache-dir "git+https://github.com/Abstract-Data/RyanData-Address-Utils.git@${RYANDATA_ADDR_UTILS_REF}"
+
+# Optional: copy source for local development/mounting (no-op unless mounted)
+COPY . /app
+
+# Default to Python shell; can override with CMD for API (see Make targets)
+CMD ["python"]
+

Makefile

@@ -14,6 +14,12 @@ help:
 	@echo "  make typecheck    Run mypy type checker"
 	@echo "  make format       Format code with ruff"
 	@echo ""
+	@echo "Docker:"
+	@echo "  make docker-build   Build libpostal-enabled image"
+	@echo "  make docker-shell   Shell into the image"
+	@echo "  make docker-test    Run a sample parse inside the image"
+	@echo "  make docker-run-api Run the optional API server"
+	@echo ""
 	@echo "Cleanup:"
 	@echo "  make clean        Remove build artifacts"
 
@@ -41,6 +47,25 @@ typecheck:
 format:
 	uv run ruff format src/
 
+# Docker targets (libpostal-enabled image)
+DOCKER_IMAGE ?= ghcr.io/abstract-data/ryandata-addr-utils-libpostal
+DOCKER_TAG ?= latest
+DOCKER_REF ?= main
+
+docker-build:
+	docker build --build-arg RYANDATA_ADDR_UTILS_REF=$(DOCKER_REF) -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+docker-shell:
+	docker run --rm -it $(DOCKER_IMAGE):$(DOCKER_TAG) bash
+
+docker-test:
+	docker run --rm $(DOCKER_IMAGE):$(DOCKER_TAG) \
+		python -c "from ryandata_address_utils import parse; print(parse('123 Main St, Austin TX 78749').to_dict())"
+
+docker-run-api:
+	docker run --rm -it -p 8000:8000 $(DOCKER_IMAGE):$(DOCKER_TAG) \
+		python -m ryandata_address_utils.api
+
 # Clean up
 clean:
 	rm -rf dist/ build/ *.egg-info src/*.egg-info

README.md

@@ -33,6 +33,31 @@ pip install git+https://github.com/Abstract-Data/RyanData-Address-Utils.git
 pip install "ryandata-address-utils[pandas] @ git+https://github.com/Abstract-Data/RyanData-Address-Utils.git"
 ```
 
+## Docker (libpostal-ready, “clone and go”)
+
+Build (with libpostal and this package installed from the chosen ref):
+```bash
+make docker-build            # builds ghcr.io/abstract-data/ryandata-addr-utils-libpostal:latest
+make docker-test             # quick parse inside container
+```
+
+Shell into the image:
+```bash
+make docker-shell
+```
+
+Run the optional API (FastAPI) on port 8000:
+```bash
+make docker-run-api
+# Then call: curl "http://localhost:8000/parse?address=123%20Main%20St,%20Austin%20TX%2078749"
+# International (if libpostal available in image):
+# curl "http://localhost:8000/parse_international?address=10%20Downing%20St,%20London"
+```
+
+Notes:
+- Image name: `ghcr.io/abstract-data/ryandata-addr-utils-libpostal` (configurable via `DOCKER_IMAGE`, `DOCKER_TAG`, `DOCKER_REF`).
+- The image bundles libpostal; use it when you need international parsing without host installs.
+
 ## Quick start
 
 ```python

src/ryandata_address_utils/api.py

@@ -0,0 +1,86 @@
+"""Minimal FastAPI service for parsing/validation (US + optional international via libpostal)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Query
+
+from ryandata_address_utils.service import AddressService, parse
+
+try:
+    from postal.parser import parse_address as lp_parse_address
+except ImportError:
+    lp_parse_address = None
+
+app = FastAPI(title="RyanData Address Utils API", version="0.3.1")
+service = AddressService()
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/parse")
+def parse_us_address(
+    address: str = Query(..., min_length=3),
+    validate: bool = True,
+) -> dict[str, Any]:
+    """Parse a US address using the standard service."""
+    result = parse(address, validate=validate)
+    return {
+        "is_valid": result.is_valid,
+        "is_parsed": result.is_parsed,
+        "address": result.to_dict() if result.address else None,
+        "errors": [e.message for e in (result.validation.errors if result.validation else [])]
+        if result.validation
+        else [],
+    }
+
+
+@app.get("/parse_international")
+def parse_international(address: str = Query(..., min_length=3)) -> dict[str, Any]:
+    """Parse an international address via libpostal, if available."""
+    if lp_parse_address is None:
+        raise HTTPException(status_code=501, detail="libpostal not available in this environment")
+
+    parsed = lp_parse_address(address)
+    # Convert list of (component, label) tuples into a dict of lists to preserve duplicates
+    components: dict[str, list[str]] = {}
+    for value, label in parsed:
+        components.setdefault(label, []).append(value)
+
+    return {"address": address, "components": components}
+
+
+@app.get("/parse_auto")
+def parse_auto(address: str = Query(..., min_length=3), validate: bool = True) -> dict[str, Any]:
+    """Auto route: try US parser first; if it fails and libpostal is available, fall back."""
+    us_result = parse(address, validate=validate)
+    if us_result.is_valid:
+        return {
+            "mode": "us",
+            "is_valid": True,
+            "is_parsed": True,
+            "address": us_result.to_dict(),
+            "errors": [],
+        }
+
+    if lp_parse_address is None:
+        return {
+            "mode": "us",
+            "is_valid": False,
+            "is_parsed": False,
+            "errors": ["US parse failed and libpostal is not available"],
+        }
+
+    parsed = lp_parse_address(address)
+    components: dict[str, list[str]] = {}
+    for value, label in parsed:
+        components.setdefault(label, []).append(value)
+
+    return {"mode": "international", "is_valid": True, "is_parsed": True, "components": components}
+
+
+# To run: uvicorn ryandata_address_utils.api:app --host 0.0.0.0 --port 8000

src/ryandata_address_utils/service.py

@@ -14,6 +14,12 @@
 from ryandata_address_utils.parsers import ParserFactory
 from ryandata_address_utils.validation.validators import create_default_validators
 
+# Optional libpostal import for international parsing
+try:
+    from postal.parser import parse_address as lp_parse_address
+except ImportError:
+    lp_parse_address = None
+
 if TYPE_CHECKING:
     import pandas as pd
 
@@ -234,6 +240,49 @@ def normalize_state(self, state: str) -> Optional[str]:
         """
         return self._data_source.normalize_state(state)
 
+    # -------------------------------------------------------------------------
+    # International / libpostal parsing
+    # -------------------------------------------------------------------------
+
+    def parse_international(self, address_string: str) -> ParseResult:
+        """Parse an address using libpostal if available."""
+        if lp_parse_address is None:
+            return ParseResult(
+                raw_input=address_string,
+                error=RuntimeError("libpostal not available"),
+                address=None,
+                validation=None,
+            )
+
+        try:
+            parsed_tokens = lp_parse_address(address_string)
+            # Convert list of (value, label) tuples into a dict; labels may repeat
+            parsed_dict: dict[str, str] = {}
+            for value, label in parsed_tokens:
+                if label in parsed_dict:
+                    parsed_dict[label] = f"{parsed_dict[label]} {value}"
+                else:
+                    parsed_dict[label] = value
+
+            # Return parsed tokens in address field for downstream use
+            return ParseResult(
+                raw_input=address_string,
+                address=parsed_dict,  # type: ignore
+                error=None,
+                validation=None,
+            )
+        except Exception as e:  # pragma: no cover
+            return ParseResult(raw_input=address_string, error=e)
+
+    def parse_auto_route(self, address_string: str, *, validate: bool = True) -> ParseResult:
+        """Try US parse first; if invalid and libpostal is available, fall back to international."""
+        us_result = self.parse(address_string, validate=validate)
+        if us_result.is_valid:
+            return us_result
+        if lp_parse_address is None:
+            return us_result
+        return self.parse_international(address_string)
+
     # -------------------------------------------------------------------------
     # Pandas integration methods
     # -------------------------------------------------------------------------