✨ add support for us w9

Author: sebastianMindee

docs/extras/code_samples/us_w9_v1.txt

@@ -0,0 +1,13 @@
+from mindee import Client, documents
+
+# Init a new client
+mindee_client = Client(api_key="my-api-key")
+
+# Load a file from disk
+input_doc = mindee_client.doc_from_path("/path/to/the/file.ext")
+
+# Parse the US W9 by passing the appropriate type
+result = input_doc.parse(documents.us.TypeW9V1)
+
+# Print a brief summary of the parsed data
+print("\n".join([str(page) for page in result.pages]))

docs/predictions/standard/documents/us/w9_v1.rst

@@ -0,0 +1,10 @@
+W9 V1
+-----
+
+**Sample Code:**
+
+.. literalinclude:: /extras/code_samples/us_w9_v1.txt
+    :language: Python
+
+.. autoclass:: mindee.documents.us.W9V1
+    :members:

mindee/cli.py

@@ -51,6 +51,10 @@ class CommandConfig(Generic[TypeDoc]):
         help="US Bank Check",
         doc_class=documents.us.TypeBankCheckV1,
     ),
+    "us-w9": CommandConfig(
+        help="US W9",
+        doc_class=documents.us.TypeW9V1,
+    ),
     "eu-license-plate": CommandConfig(
         help="EU License Plate",
         doc_class=documents.eu.TypeLicensePlateV1,

mindee/client.py

@@ -469,6 +469,11 @@ def _init_default_endpoints(self) -> None:
                 url_name="material_certificate",
                 version="1",
             ),
+            ConfigSpec(
+                doc_class=documents.us.W9V1,
+                url_name="us_w9",
+                version="1",
+            ),
         ]
 
         for config in configs:

mindee/documents/us/__init__.py

@@ -1 +1,2 @@
 from .bank_check.bank_check_v1 import BankCheckV1, TypeBankCheckV1
+from .w9.w9_v1 import W9V1, TypeW9V1

mindee/documents/us/w9/__init__.py

@@ -0,0 +1,138 @@
+from typing import Optional, TypeVar
+
+from mindee.documents.base import Document, TypeApiPrediction, clean_out_string
+from mindee.fields.position import PositionField
+from mindee.fields.text import TextField
+
+
+class W9V1(Document):
+    """US W9 v1 prediction results."""
+
+    address: TextField
+    """The street address (number, street, and apt. or suite no.) of the applicant."""
+    business_name: TextField
+    """The business name or disregarded entity name, if different from Name."""
+    city_state_zip: TextField
+    """The city, state, and ZIP code of the applicant."""
+    ein: TextField
+    """The employer identification number."""
+    name: TextField
+    """Name as shown on the applicant's income tax return."""
+    signature_date_position: PositionField
+    """Position of the signature date on the document."""
+    signature_position: PositionField
+    """Position of the signature on the document."""
+    ssn: TextField
+    """The applicant's social security number."""
+    tax_classification: TextField
+    """The federal tax classification, which can vary depending on the revision date."""
+    tax_classification_llc: TextField
+    """Depending on revision year, among S, C, P or D for Limited Liability Company Classification."""
+    tax_classif_other_details: TextField
+    """Tax Classification Other Details."""
+    w9_revision_date: TextField
+    """The Revision month and year of the W9 form."""
+
+    def __init__(
+        self,
+        api_prediction=None,
+        input_source=None,
+        page_n: Optional[int] = None,
+    ):
+        """
+        US W9 v1 prediction results.
+
+        :param api_prediction: Raw prediction from HTTP response
+        :param input_source: Input object
+        :param page_n: Page number for multi pages pdf input
+        """
+        super().__init__(
+            input_source=input_source,
+            document_type="w9",
+            api_prediction=api_prediction,
+            page_n=page_n,
+        )
+        self._build_from_api_prediction(api_prediction["prediction"], page_n=page_n)
+
+    def _build_from_api_prediction(
+        self, api_prediction: TypeApiPrediction, page_n: Optional[int] = None
+    ) -> None:
+        """
+        Build the object from the prediction API JSON.
+
+        :param api_prediction: Raw prediction from HTTP response
+        :param page_n: Page number
+        """
+        self.address = TextField(
+            api_prediction.get("address", {}),
+            page_id=page_n,
+        )
+        self.business_name = TextField(
+            api_prediction.get("business_name", {}),
+            page_id=page_n,
+        )
+        self.city_state_zip = TextField(
+            api_prediction.get("city_state_zip", {}),
+            page_id=page_n,
+        )
+        self.ein = TextField(
+            api_prediction.get("ein", {}),
+            page_id=page_n,
+        )
+        self.name = TextField(
+            api_prediction.get("name", {}),
+            page_id=page_n,
+        )
+        self.signature_date_position = PositionField(
+            api_prediction.get("signature_date_position", {}),
+            page_id=page_n,
+        )
+        self.signature_position = PositionField(
+            api_prediction.get("signature_position", {}),
+            page_id=page_n,
+        )
+        self.ssn = TextField(
+            api_prediction.get("ssn", {}),
+            page_id=page_n,
+        )
+        self.tax_classification = TextField(
+            api_prediction.get("tax_classification", {}),
+            page_id=page_n,
+        )
+        self.tax_classification_llc = TextField(
+            api_prediction.get("tax_classification_llc", {}),
+            page_id=page_n,
+        )
+        self.tax_classif_other_details = TextField(
+            api_prediction.get("tax_classification_other_details", {}),
+            page_id=page_n,
+        )
+        self.w9_revision_date = TextField(
+            api_prediction.get("w9_revision_date", {}),
+            page_id=page_n,
+        )
+
+    def __str__(self) -> str:
+        return clean_out_string(
+            "US W9 V1 Prediction\n"
+            "======================\n"
+            f":Filename: {self.filename or ''}\n"
+            f":Name: {self.name}\n"
+            f":SSN: {self.ssn}\n"
+            f":Address: {self.address}\n"
+            f":City State Zip: {self.city_state_zip}\n"
+            f":Business Name: {self.business_name}\n"
+            f":EIN: {self.ein}\n"
+            f":Tax Classification: {self.tax_classification}\n"
+            f":Tax Classification Other Details: {self.tax_classif_other_details}\n"
+            f":W9 Revision Date: {self.w9_revision_date}\n"
+            f":Signature Position: {self.signature_position}\n"
+            f":Signature Date Position: {self.signature_date_position}\n"
+            f":Tax Classification LLC: {self.tax_classification_llc}\n"
+        )
+
+
+TypeW9V1 = TypeVar(
+    "TypeW9V1",
+    bound=W9V1,
+)

mindee/documents/us/w9/w9_v1.py

@@ -1,7 +1,7 @@
 [metadata]
 name = mindee
 author = Mindee
-author_email = devrel@mindee.com
+author_email = opensource@mindee.com
 description = Mindee API helper library for Python
 long_description = file:README.md
 long_description_content_type = text/markdown

setup.cfg

@@ -0,0 +1,43 @@
+import json
+
+import pytest
+
+from mindee.documents.us import W9V1
+
+US_W9_DATA_DIR = "./tests/data/products/us_w9"
+FILE_PATH_US_W9_V1_COMPLETE = f"{ US_W9_DATA_DIR }/response_v1/complete.json"
+FILE_PATH_US_W9_V1_EMPTY = f"{ US_W9_DATA_DIR }/response_v1/empty.json"
+
+
+@pytest.fixture
+def w9_v1_doc() -> W9V1:
+    json_data = json.load(open(FILE_PATH_US_W9_V1_COMPLETE, encoding="utf-8"))
+    return W9V1(json_data["document"]["inference"], page_n=None)
+
+
+@pytest.fixture
+def w9_v1_doc_empty() -> W9V1:
+    json_data = json.load(open(FILE_PATH_US_W9_V1_EMPTY, encoding="utf-8"))
+    return W9V1(json_data["document"]["inference"], page_n=None)
+
+
+@pytest.fixture
+def w9_v1_page0():
+    json_data = json.load(open(FILE_PATH_US_W9_V1_COMPLETE, encoding="utf-8"))
+    return W9V1(json_data["document"]["inference"]["pages"][0], page_n=0)
+
+
+def test_empty_doc_constructor(w9_v1_doc_empty):
+    assert w9_v1_doc_empty.name.value is None
+    assert w9_v1_doc_empty.ssn.value is None
+    assert w9_v1_doc_empty.address.value is None
+    assert w9_v1_doc_empty.city_state_zip.value is None
+    assert w9_v1_doc_empty.business_name.value is None
+    assert w9_v1_doc_empty.ein.value is None
+    assert w9_v1_doc_empty.tax_classification.value is None
+    assert w9_v1_doc_empty.tax_classif_other_details.value is None
+    assert w9_v1_doc_empty.w9_revision_date.value is None
+    assert w9_v1_doc_empty.signature_position.value is None
+    assert w9_v1_doc_empty.signature_date_position.value is None
+    assert w9_v1_doc_empty.tax_classification_llc.value is None
+