awb-extractor 0.1.1__py3-none-any.whl

awb_extractor/__init__.py

@@ -0,0 +1,18 @@
+from .extractor import AWBExtractor
+from .models import AWBResult
+from .exceptions import (
+    AWBExtractorError,
+    APIKeyError,
+    PDFDownloadError,
+    ExtractionError,
+)
+
+__version__ = "0.1.1"
+__all__ = [
+    "AWBExtractor",
+    "AWBResult",
+    "AWBExtractorError",
+    "APIKeyError",
+    "PDFDownloadError",
+    "ExtractionError",
+]

awb_extractor/exceptions.py

@@ -0,0 +1,22 @@
+class AWBExtractorError(Exception):
+    pass
+
+
+class APIKeyError(AWBExtractorError):
+    pass
+
+
+class PDFDownloadError(AWBExtractorError):
+    def __init__(self, url: str, status_code: int = None, message: str = None):
+        self.url = url
+        self.status_code = status_code
+        detail = f"status={status_code}" if status_code else message or "unknown error"
+        super().__init__(f"Failed to download PDF from {url!r}: {detail}")
+
+
+class ExtractionError(AWBExtractorError):
+    def __init__(self, raw_response: str = None):
+        self.raw_response = raw_response
+        super().__init__(
+            f"Failed to parse Claude response as JSON. Raw: {raw_response!r}"
+        )

awb_extractor/extractor.py

@@ -0,0 +1,129 @@
+import base64
+import json
+from pathlib import Path
+from typing import Optional
+
+import anthropic
+import httpx
+
+from .exceptions import APIKeyError, ExtractionError, PDFDownloadError
+from .models import AWBResult
+
+_SYSTEM_PROMPT = """You are an OCR system that extracts information from shipping labels (AWB).
+Return only raw JSON, no explanation, no markdown. Required format:
+{
+  "tracking_number": "",
+  "recipient_name": "",
+  "recipient_phone": "",
+  "recipient_address": "",
+  "recipient_ward": "",
+  "recipient_district": "",
+  "recipient_province": "",
+  "sender_name": "",
+  "sender_address": "",
+  "cod": "",
+  "weight": "",
+  "order_id": ""
+}"""
+
+
+class AWBExtractor:
+    DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+
+    def __init__(
+        self,
+        api_key: str,
+        http_headers: Optional[dict] = None,
+        model: str = DEFAULT_MODEL,
+        timeout: int = 30,
+    ):
+        if not api_key:
+            raise APIKeyError("api_key is required.")
+        self._client = anthropic.Anthropic(api_key=api_key)
+        self._http_headers = http_headers or {}
+        self._model = model
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def from_bytes(self, pdf_bytes: bytes) -> AWBResult:
+        raw_json = self._call_claude(pdf_bytes)
+        return AWBResult.from_dict(raw_json)
+
+    def from_file(self, pdf_path: str) -> AWBResult:
+        pdf_bytes = Path(pdf_path).read_bytes()
+        return self.from_bytes(pdf_bytes)
+
+    def from_url(self, url: str, extra_headers: Optional[dict] = None) -> AWBResult:
+        pdf_bytes = self._download(url, extra_headers)
+        return self.from_bytes(pdf_bytes)
+
+    def from_urls(self, urls: list[str]) -> list[dict]:
+        results = []
+        for url in urls:
+            try:
+                results.append({
+                    "url": url,
+                    "data": self.from_url(url),
+                    "error": None,
+                })
+            except Exception as e:
+                results.append({
+                    "url": url,
+                    "data": None,
+                    "error": str(e),
+                })
+        return results
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _download(self, url: str, extra_headers: Optional[dict] = None) -> bytes:
+        headers = {**self._http_headers, **(extra_headers or {})}
+        try:
+            resp = httpx.get(url, headers=headers, follow_redirects=True, timeout=self._timeout)
+            resp.raise_for_status()
+            return resp.content
+        except httpx.HTTPStatusError as e:
+            raise PDFDownloadError(url, status_code=e.response.status_code) from e
+        except httpx.RequestError as e:
+            raise PDFDownloadError(url, message=str(e)) from e
+
+    def _call_claude(self, pdf_bytes: bytes) -> dict:
+        pdf_base64 = base64.standard_b64encode(pdf_bytes).decode("utf-8")
+
+        response = self._client.messages.create(
+            model=self._model,
+            max_tokens=1024,
+            system=_SYSTEM_PROMPT,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "document",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "application/pdf",
+                                "data": pdf_base64,
+                            },
+                        },
+                        {
+                            "type": "text",
+                            "text": "Extract all information from this shipping label.",
+                        },
+                    ],
+                }
+            ],
+        )
+
+        raw = response.content[0].text.strip()
+        raw = raw.replace("```json", "").replace("```", "").strip()
+
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ExtractionError(raw_response=raw) from e

awb_extractor/models.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+import json
+
+
+@dataclass
+class AWBResult:
+    tracking_number: Optional[str] = None
+    recipient_name: Optional[str] = None
+    recipient_phone: Optional[str] = None
+    recipient_address: Optional[str] = None
+    recipient_ward: Optional[str] = None
+    recipient_district: Optional[str] = None
+    recipient_province: Optional[str] = None
+    sender_name: Optional[str] = None
+    sender_address: Optional[str] = None
+    cod: Optional[str] = None
+    weight: Optional[str] = None
+    order_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AWBResult":
+        valid_keys = cls.__dataclass_fields__.keys()
+        filtered = {k: v or None for k, v in data.items() if k in valid_keys}
+        return cls(**filtered)
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in asdict(self).items()}
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    def __repr__(self) -> str:
+        fields = ", ".join(
+            f"{k}={v!r}" for k, v in self.to_dict().items() if v is not None
+        )
+        return f"AWBResult({fields})"

awb_extractor-0.1.1.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: awb-extractor
+Version: 0.1.1
+Summary: Extract recipient address from AWB/shipping label PDF using Claude AI
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+
+# AWB Extractor
+
+Python SDK for extracting receiver and shipment information from AWB/shipping
+label PDF files using Claude AI.
+
+## Features
+
+- Extract from PDF bytes, local PDF files, or PDF URLs
+- Batch extraction from multiple URLs
+- Optional default HTTP headers for protected AWB URLs
+- Typed `AWBResult` dataclass output
+- Custom exceptions for API key, PDF download, and JSON parsing failures
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install awb-extractor
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+
+print(result.recipient_name)
+print(result.to_dict())
+```
+
+Example result:
+
+```python
+{
+    "tracking_number": "NHSVC972103440",
+    "recipient_name": "Nguyen Van A",
+    "recipient_phone": "(+84)03******37",
+    "recipient_address": "237 Nguyen Trai",
+    "recipient_ward": "Phuong Ben Thanh",
+    "recipient_district": "Quan 1",
+    "recipient_province": "TP. Ho Chi Minh",
+    "sender_name": "Onflow",
+    "sender_address": "TP. Ho Chi Minh",
+    "cod": "0",
+    "weight": "0.700 KG",
+    "order_id": "584425059595159079",
+}
+```
+
+## Supported Inputs
+
+### PDF bytes
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+
+with open("label.pdf", "rb") as file:
+    result = extractor.from_bytes(file.read())
+```
+
+### Local PDF file
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+result = extractor.from_file("label.pdf")
+```
+
+### PDF URL
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(
+    api_key="sk-ant-...",
+    http_headers={"Authorization": "Bearer token"},
+)
+
+result = extractor.from_url("https://example.com/awb.pdf")
+```
+
+You can pass request-specific headers with `extra_headers`:
+
+```python
+result = extractor.from_url(
+    "https://example.com/awb.pdf",
+    extra_headers={"X-Request-ID": "request-123"},
+)
+```
+
+### Multiple URLs
+
+`from_urls()` returns a list of dictionaries with `url`, `data`, and `error`.
+Failed URLs do not stop the whole batch.
+
+```python
+from awb_extractor import AWBExtractor
+
+extractor = AWBExtractor(api_key="sk-ant-...")
+results = extractor.from_urls([
+    "https://example.com/good.pdf",
+    "https://example.com/bad.pdf",
+])
+```
+
+## Result Fields
+
+`AWBResult` includes:
+
+- `tracking_number`
+- `recipient_name`
+- `recipient_phone`
+- `recipient_address`
+- `recipient_ward`
+- `recipient_district`
+- `recipient_province`
+- `sender_name`
+- `sender_address`
+- `cod`
+- `weight`
+- `order_id`
+
+Use `to_dict()` or `to_json()` to serialize the result.
+
+## Exceptions
+
+- `APIKeyError`: missing API key
+- `PDFDownloadError`: PDF URL download failed
+- `ExtractionError`: Claude response could not be parsed as JSON
+
+## Package Structure
+
+- `awb_extractor/extractor.py`: public `AWBExtractor` class
+- `awb_extractor/models.py`: `AWBResult` dataclass
+- `awb_extractor/exceptions.py`: package exceptions
+
+## Publishing
+
+GitHub Actions builds and publishes the package to PyPI on every push to `main`.
+
+The repository must define this GitHub secret:
+
+```text
+PYPI_API_TOKEN
+```
+
+PyPI does not allow replacing an existing version. If a commit on `main` does not
+bump `project.version` in `pyproject.toml`, the publish step skips the existing
+distribution.

awb_extractor-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+awb_extractor/__init__.py,sha256=GfsBdTsmNHcNuKKmAo4wgQEaBjZsB5TYoUNhlu4y41w,342
+awb_extractor/exceptions.py,sha256=PRf0h1WLyxmcoSbaEyQtmrnx8Nz-ZifaZMW9f-PA1ic,693
+awb_extractor/extractor.py,sha256=GJb5XRbRLmgZgKW3jhRHgs7oM04T9fkoHYp75X7oaLI,4250
+awb_extractor/models.py,sha256=cY3T1hcGpOzZKaEma_eevsAXKCndNe1GXOMpqq4JTvg,1224
+awb_extractor-0.1.1.dist-info/METADATA,sha256=AnhxwhUFBi0xqLxC0sCCD6rYZb1M6Qk0bjrTwdK_8pg,3830
+awb_extractor-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+awb_extractor-0.1.1.dist-info/top_level.txt,sha256=OjoN1DneQqcJc6-VrQC53k8s0JvGCSoMPD73t5YGpig,14
+awb_extractor-0.1.1.dist-info/RECORD,,

awb_extractor-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

awb_extractor-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+awb_extractor