Bank checks (beta) (#94)

* new: ✨ New Field type Position for position onfly features

* chg: ✨ added Bank_check (beta) to endpoint and client definitions

* chg: ✨ Added BankCheck class

* new: ✨ Added Position field type and BankCheck class

* new: ✅ Added tests for Position field and BankCheck class

* fix: 🐛 Fixed non used import

* minor fixes to types and for lint

Co-authored-by: Ianaré Sévi <ianare@mindee.co>

Author: jonathanMindee

docs/documents.rst

@@ -33,6 +33,13 @@ Financial Document
     :inherited-members:
     :undoc-members:
 
+Bank Check
+----------
+.. autoclass:: mindee.documents.bank_check.BankCheck
+    :members:
+    :inherited-members:
+    :undoc-members:
+
 Custom Document
 ----------------
 .. autoclass:: mindee.documents.custom_document.CustomDocument

mindee/client.py

@@ -2,13 +2,15 @@
 from typing import BinaryIO, Dict, Optional
 
 from mindee.document_config import DocumentConfig, DocumentConfigDict
+from mindee.documents.bank_check import BankCheck
 from mindee.documents.custom_document import CustomDocument
 from mindee.documents.financial_document import FinancialDocument
 from mindee.documents.invoice import Invoice
 from mindee.documents.passport import Passport
 from mindee.documents.receipt import Receipt
 from mindee.endpoints import (
     OTS_OWNER,
+    BankCheckEndpoint,
     CustomEndpoint,
     HTTPException,
     InvoiceEndpoint,
@@ -247,6 +249,22 @@ def config_passport(self, api_key: Optional[str] = None) -> "Client":
         self._doc_configs[(OTS_OWNER, "passport")] = config
         return self
 
+    def config_bank_check(self, api_key: Optional[str] = None) -> "Client":
+        """
+        Configure a Mindee Bank check document.
+
+        :param api_key: Bank check API key
+        """
+        config = DocumentConfig(
+            document_type="bank_check",
+            singular_name="bank_check",
+            plural_name="bank_checks",
+            constructor=BankCheck,
+            endpoints=[BankCheckEndpoint(api_key=api_key)],
+        )
+        self._doc_configs[(OTS_OWNER, "bank_check")] = config
+        return self
+
     def doc_from_path(
         self,
         input_path: str,

mindee/documents/bank_check.py

@@ -0,0 +1,97 @@
+from typing import List, Optional
+
+from mindee.documents.base import Document, TypeApiPrediction
+from mindee.fields.amount import Amount
+from mindee.fields.base import Field
+from mindee.fields.date import Date
+from mindee.fields.orientation import Orientation
+from mindee.fields.position import Position
+
+
+class BankCheck(Document):
+    date: Date
+    """Date the check was issued"""
+    amount: Amount
+    """Total including taxes"""
+    payees: List[Field] = []
+    """List of payees (full name or company name)"""
+    check_number: Field
+    """Check number"""
+    routing_number: Field
+    """Payer's bank account routing number"""
+    account_number: Field
+    """Payer's bank account number"""
+    check_position: Field
+    """Check's position in the image"""
+    signatures_positions: List[Field] = []
+    """Signatures' positions in the image"""
+    # orientation is only present on page-level, not document-level
+    orientation: Optional[Orientation] = None
+    """Page orientation"""
+
+    def __init__(
+        self,
+        api_prediction=None,
+        input_file=None,
+        page_n: Optional[int] = None,
+        document_type="bank_check",
+    ):
+        """
+        Bank check document.
+
+        :param api_prediction: Raw prediction from HTTP response
+        :param input_file: Input object
+        :param page_n: Page number for multi pages pdf input
+        """
+        super().__init__(
+            input_file=input_file,
+            document_type=document_type,
+            api_prediction=api_prediction,
+            page_n=page_n,
+        )
+
+    def _build_from_api_prediction(
+        self, api_prediction: TypeApiPrediction, page_n: Optional[int] = None
+    ) -> None:
+        """
+        Build the document from an API response JSON.
+
+        :param api_prediction: Raw prediction from HTTP response
+        :param page_n: Page number for multi pages pdf input
+        """
+        if page_n is not None:
+            self.orientation = Orientation(api_prediction["orientation"], page_n=page_n)
+
+        self.routing_number = Field(api_prediction["routing_number"], page_n=page_n)
+        self.account_number = Field(api_prediction["account_number"], page_n=page_n)
+        self.check_number = Field(api_prediction["check_number"], page_n=page_n)
+        self.date = Date(api_prediction["date"], "value", page_n=page_n)
+        self.amount = Amount(api_prediction["amount"], value_key="value", page_n=page_n)
+        self.payees = [
+            Field(payee, page_n=page_n) for payee in api_prediction["payees"]
+        ]
+        self.check_position = Position(api_prediction["check_position"], page_n=page_n)
+        self.signatures_positions = [
+            Position(signature_position, page_n=page_n)
+            for signature_position in api_prediction["signatures_positions"]
+        ]
+
+    def __str__(self) -> str:
+        payees = ", ".join(
+            [payee.value if payee.value is not None else "" for payee in self.payees]
+        )
+        return (
+            "-----Bank check data-----\n"
+            f"Filename: {self.filename}\n"
+            f"Routing number: {self.routing_number}\n"
+            f"Account number: {self.account_number}\n"
+            f"Check number: {self.check_number}\n"
+            f"Date: {self.date}\n"
+            f"Amount: {self.amount}\n"
+            f"Payees: {payees}\n"
+            "----------------------"
+        )
+
+    def _checklist(self) -> None:
+        """Call check methods."""
+        self.checklist = {}

mindee/endpoints.py

@@ -22,6 +22,9 @@
 PASSPORT_VERSION = "1"
 PASSPORT_URL_NAME = "passport"
 
+BANK_CHECK_VERSION = "1"
+BANK_CHECK_URL_NAME = "bank_check"
+
 
 class Endpoint:
     """Generic API endpoint for a product."""
@@ -189,5 +192,15 @@ def __init__(self, api_key: Optional[str] = None):
         )
 
 
+class BankCheckEndpoint(Endpoint):
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__(
+            owner=OTS_OWNER,
+            url_name=BANK_CHECK_URL_NAME,
+            version=BANK_CHECK_VERSION,
+            api_key=api_key,
+        )
+
+
 class HTTPException(RuntimeError):
     """An exception relating to HTTP calls."""

mindee/fields/position.py

@@ -0,0 +1,58 @@
+from typing import Optional
+
+from mindee.fields.base import Field, TypePrediction
+from mindee.geometry import Polygon, Quadrilateral
+
+
+class Position(Field):
+    value: Polygon = []
+    quadrangle: Optional[Quadrilateral]
+    rectangle: Optional[Quadrilateral]
+    bounding_box: Optional[Quadrilateral]
+
+    def __init__(
+        self,
+        position_prediction: TypePrediction,
+        value_key: str = "polygon",
+        reconstructed: bool = False,
+        page_n: Optional[int] = None,
+    ):
+        """
+        Amount field object.
+
+        :param position_prediction: Position prediction object from HTTP response
+        :param value_key: Key to use in the position_prediction dict
+        :param reconstructed: Bool for reconstructed object (not extracted in the API)
+        :param page_n: Page number for multi-page PDF
+        """
+        super().__init__(
+            position_prediction,
+            value_key=value_key,
+            reconstructed=reconstructed,
+            page_n=page_n,
+        )
+        try:
+            self.value = position_prediction[value_key]
+            self.bounding_box = (
+                position_prediction["bounding_box"]
+                if "bounding_box" in position_prediction.keys()
+                else None
+            )
+            self.quadrangle = (
+                position_prediction["quadrangle"]
+                if "quadrangle" in position_prediction.keys()
+                else None
+            )
+            self.polygon = (
+                position_prediction["polygon"]
+                if "polygon" in position_prediction.keys()
+                else None
+            )
+            self.rectangle = (
+                position_prediction["rectangle"]
+                if "rectangle" in position_prediction.keys()
+                else None
+            )
+        except (ValueError, TypeError, KeyError):
+            self.value = []
+            self.confidence = 0.0

tests/__init__.py

@@ -1,4 +1,5 @@
 RECEIPT_DATA_DIR = "./tests/data/receipt"
 INVOICE_DATA_DIR = "./tests/data/invoice"
 PASSPORT_DATA_DIR = "./tests/data/passport"
+BANK_CHECK_DATA_DIR = "./tests/data/bank_check"
 CUSTOM_DATA_DIR = "./tests/data/custom"