✨ add support for OCR V2 (+ fix tests)

sebastianMindee · sebastianMindee · commit 4a2199e867f9 · 2026-02-04T17:58:49.000+01:00
diff --git a/.github/workflows/_test-code-samples.yml b/.github/workflows/_test-code-samples.yml
@@ -40,7 +40,7 @@ jobs:
 
       - name: Tests code samples
         run: |
-            ./tests/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }}  ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}  ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}  ${{ secrets.MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID }}
+            ./tests/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }}  ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}  ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }} ${{ secrets.MINDEE_V2_SE_TESTS_CLASSIFICATION_MODEL_ID }} ${{ secrets.MINDEE_V2_SE_TESTS_CROP_MODEL_ID }} ${{ secrets.MINDEE_V2_SE_TESTS_CROP_MODEL_ID }} ${{ secrets.MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID }}
 
       - name: Notify Slack Action on Failure
         uses: ravsamhq/notify-slack-action@2.3.0
diff --git a/.github/workflows/_test-integrations.yml b/.github/workflows/_test-integrations.yml
@@ -49,7 +49,10 @@ jobs:
           MINDEE_V2_API_KEY: ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}
           MINDEE_V2_FINDOC_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}
           MINDEE_V2_SE_TESTS_BLANK_PDF_URL: ${{ secrets.MINDEE_V2_SE_TESTS_BLANK_PDF_URL }}
+          MINDEE_V2_SE_TESTS_CLASSIFICATION_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_CLASSIFICATION_MODEL_ID }}
+          MINDEE_V2_SE_TESTS_CROP_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_CROP_MODEL_ID }}
           MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID }}
+          MINDEE_V2_SE_TESTS_OCR_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_OCR_MODEL_ID }}
       run: |
         pytest --cov mindee -m integration
 
diff --git a/docs/extras/code_samples/v2_classification.txt b/docs/extras/code_samples/v2_classification.txt
@@ -0,0 +1,27 @@
+from mindee import ClientV2, ClassificationParameters, ClassificationResponse, PathInput
+
+input_path = "/path/to/the/file.ext"
+api_key = "MY_API_KEY"
+model_id = "MY_CLASSIFICATION_MODEL_ID"
+
+# Init a new client
+mindee_client = ClientV2(api_key)
+
+# Set inference parameters
+params = ClassificationParameters(
+    # ID of the model, required.
+    model_id=model_id,
+)
+
+# Load a file from disk
+input_source = PathInput(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    ClassificationResponse,
+    input_source,
+    params,
+)
+
+# Print a brief summary of the parsed data
+print(response.inference)
diff --git a/docs/extras/code_samples/v2_crop.txt b/docs/extras/code_samples/v2_crop.txt
@@ -0,0 +1,27 @@
+from mindee import ClientV2, CropParameters, CropResponse, PathInput
+
+input_path = "/path/to/the/file.ext"
+api_key = "MY_API_KEY"
+model_id = "MY_CROP_MODEL_ID"
+
+# Init a new client
+mindee_client = ClientV2(api_key)
+
+# Set inference parameters
+params = CropParameters(
+    # ID of the model, required.
+    model_id=model_id,
+)
+
+# Load a file from disk
+input_source = PathInput(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    CropResponse,
+    input_source,
+    params,
+)
+
+# Print a brief summary of the parsed data
+print(response.inference)
diff --git a/docs/extras/code_samples/v2_ocr.txt b/docs/extras/code_samples/v2_ocr.txt
@@ -0,0 +1,27 @@
+from mindee import ClientV2, OCRParameters, OCRResponse, PathInput
+
+input_path = "/path/to/the/file.ext"
+api_key = "MY_API_KEY"
+model_id = "MY_OCR_MODEL_ID"
+
+# Init a new client
+mindee_client = ClientV2(api_key)
+
+# Set inference parameters
+params = OCRParameters(
+    # ID of the model, required.
+    model_id=model_id,
+)
+
+# Load a file from disk
+input_source = PathInput(input_path)
+
+# Send for processing
+response = mindee_client.enqueue_and_get_result(
+    OCRResponse,
+    input_source,
+    params,
+)
+
+# Print a brief summary of the parsed data
+print(response.inference)
diff --git a/mindee/v2/__init__.py b/mindee/v2/__init__.py
@@ -1,11 +1,15 @@
 from mindee.v2.product.crop.crop_parameters import CropParameters
 from mindee.v2.product.crop.crop_response import CropResponse
+from mindee.v2.product.ocr.ocr_parameters import OCRParameters
+from mindee.v2.product.ocr.ocr_response import OCRResponse
 from mindee.v2.product.split.split_parameters import SplitParameters
 from mindee.v2.product.split.split_response import SplitResponse
 
 __all__ = [
-    "CropParameters",
     "CropResponse",
+    "CropParameters",
+    "OCRResponse",
+    "OCRParameters",
     "SplitResponse",
     "SplitParameters",
 ]
diff --git a/mindee/v2/product/__init__.py b/mindee/v2/product/__init__.py
@@ -1,7 +1,15 @@
+from mindee.v2.product.crop.crop_parameters import CropParameters
+from mindee.v2.product.crop.crop_response import CropResponse
+from mindee.v2.product.ocr.ocr_parameters import OCRParameters
+from mindee.v2.product.ocr.ocr_response import OCRResponse
 from mindee.v2.product.split.split_parameters import SplitParameters
 from mindee.v2.product.split.split_response import SplitResponse
 
 __all__ = [
+    "CropResponse",
+    "CropParameters",
+    "OCRResponse",
+    "OCRParameters",
     "SplitResponse",
     "SplitParameters",
 ]
diff --git a/mindee/v2/product/crop/crop_box.py b/mindee/v2/product/crop/crop_box.py
@@ -6,9 +6,9 @@ class CropBox:
     """Crop inference result."""
 
     location: FieldLocation
-    """Page box of the crop inference."""
+    """Location which includes cropping coordinates for the detected object, within the source document."""
     object_type: str
-    """Document type of the crop inference."""
+    """Type or classification of the detected object."""
 
     def __init__(self, server_response: StringDict):
         self.location = FieldLocation(server_response["location"])
diff --git a/mindee/v2/product/ocr/__init__.py b/mindee/v2/product/ocr/__init__.py
@@ -0,0 +1,15 @@
+from mindee.v2.product.ocr.ocr_inference import OCRInference
+from mindee.v2.product.ocr.ocr_page import OCRPage
+from mindee.v2.product.ocr.ocr_parameters import OCRParameters
+from mindee.v2.product.ocr.ocr_response import OCRResponse
+from mindee.v2.product.ocr.ocr_result import OCRResult
+from mindee.v2.product.ocr.ocr_word import OCRWord
+
+__all__ = [
+    "OCRInference",
+    "OCRPage",
+    "OCRParameters",
+    "OCRResponse",
+    "OCRResult",
+    "OCRWord",
+]
diff --git a/mindee/v2/product/ocr/ocr_inference.py b/mindee/v2/product/ocr/ocr_inference.py
@@ -0,0 +1,19 @@
+from mindee.parsing.common.string_dict import StringDict
+from mindee.v2.parsing.inference.base_inference import BaseInference
+from mindee.v2.product.ocr.ocr_result import OCRResult
+
+
+class OCRInference(BaseInference):
+    """OCR inference result."""
+
+    result: OCRResult
+    """Result of a ocr inference."""
+    _slug: str = "ocr"
+    """Slug of the endpoint."""
+
+    def __init__(self, raw_response: StringDict) -> None:
+        super().__init__(raw_response)
+        self.result = OCRResult(raw_response["result"])
+
+    def __str__(self) -> str:
+        return f"Inference\n#########\n{self.model}\n{self.file}\n{self.result}\n"
diff --git a/mindee/v2/product/ocr/ocr_page.py b/mindee/v2/product/ocr/ocr_page.py
@@ -0,0 +1,25 @@
+from typing import List
+
+from mindee.parsing.common.string_dict import StringDict
+from mindee.v2.product.ocr.ocr_word import OCRWord
+
+
+class OCRPage:
+    """OCR result for a single page."""
+
+    words: List[OCRWord]
+    """List of words extracted from the document page."""
+    content: str
+    """Full text content extracted from the document page."""
+
+    def __init__(self, raw_response: StringDict) -> None:
+        self.words = [OCRWord(word) for word in raw_response["words"]]
+        self.content = raw_response["content"]
+
+    def __str__(self) -> str:
+        ocr_words = "\n"
+        if len(self.words) > 0:
+            ocr_words += "\n\n".join([str(word) for word in self.words])
+        out_str = f"OCR Words\n======{ocr_words}"
+        out_str += f"\n\n:Content: {self.content}"
+        return out_str
diff --git a/mindee/v2/product/ocr/ocr_parameters.py b/mindee/v2/product/ocr/ocr_parameters.py
@@ -0,0 +1,9 @@
+from mindee.input.base_parameters import BaseParameters
+
+
+class OCRParameters(BaseParameters):
+    """
+    Parameters accepted by the ocr utility v2 endpoint.
+    """
+
+    _slug: str = "utilities/ocr"
diff --git a/mindee/v2/product/ocr/ocr_response.py b/mindee/v2/product/ocr/ocr_response.py
@@ -0,0 +1,17 @@
+from mindee.parsing.common.string_dict import StringDict
+from mindee.v2.parsing.inference import BaseResponse
+from mindee.v2.product.ocr.ocr_inference import OCRInference
+
+
+class OCRResponse(BaseResponse):
+    """Represent an OCR inference response from Mindee V2 API."""
+
+    inference: OCRInference
+    """Inference object for ocr inference."""
+
+    _slug: str = "utilities/ocr"
+    """Slug of the inference."""
+
+    def __init__(self, raw_response: StringDict) -> None:
+        super().__init__(raw_response)
+        self.inference = OCRInference(raw_response["inference"])
diff --git a/mindee/v2/product/ocr/ocr_result.py b/mindee/v2/product/ocr/ocr_result.py
@@ -0,0 +1,21 @@
+from typing import List
+
+from mindee.parsing.common.string_dict import StringDict
+from mindee.v2.product.ocr.ocr_page import OCRPage
+
+
+class OCRResult:
+    """OCR result info."""
+
+    pages: List[OCRPage]
+    """List of OCR results for each page in the document."""
+
+    def __init__(self, raw_response: StringDict) -> None:
+        self.pages = [OCRPage(ocr) for ocr in raw_response["pages"]]
+
+    def __str__(self) -> str:
+        pages = "\n"
+        if len(self.pages) > 0:
+            pages += "\n\n".join([str(ocr) for ocr in self.pages])
+        out_str = f"Pages\n======{pages}"
+        return out_str
diff --git a/mindee/v2/product/ocr/ocr_word.py b/mindee/v2/product/ocr/ocr_word.py
@@ -0,0 +1,17 @@
+from mindee.geometry.polygon import Polygon
+
+
+class OCRWord:
+    """OCR result for a single word extracted from the document page."""
+
+    content: str
+    """Text content of the word."""
+    polygon: Polygon
+    """Position information as a list of points in clockwise order."""
+
+    def __init__(self, raw_response: dict):
+        self.content = raw_response["content"]
+        self.polygon = Polygon(raw_response["polygon"])
+
+    def __str__(self) -> str:
+        return self.content
diff --git a/tests/test_code_samples.sh b/tests/test_code_samples.sh
@@ -7,7 +7,10 @@ ENDPOINT=$2
 API_KEY=$3
 API_KEY_V2=$4
 MODEL_ID=$5
-SPLIT_MODEL_ID=$6
+CROP_MODEL_ID=$6
+SPLIT_MODEL_ID=$7
+OCR_MODEL_ID=$8
+CLASSIFICATION_MODEL_ID=$9
 
 for f in $(find ./docs/extras/code_samples -maxdepth 1 -name "*.txt" -not -name "workflow_*.txt" | sort -h)
 do
@@ -37,6 +40,22 @@ do
     sed -i "s/my-api-key/$API_KEY/" $OUTPUT_FILE
   fi
 
+  if echo "${f}" | grep -q "v2_classification.txt"
+  then
+    sed -i "s/MY_API_KEY/$API_KEY_V2/" $OUTPUT_FILE
+    sed -i "s/MY_CLASSIFICATION_MODEL_ID/$CLASSIFICATION_MODEL_ID/" $OUTPUT_FILE
+  else
+    sed -i "s/my-api-key/$API_KEY/" $OUTPUT_FILE
+  fi
+
+  if echo "${f}" | grep -q "v2_crop.txt"
+  then
+    sed -i "s/MY_API_KEY/$API_KEY_V2/" $OUTPUT_FILE
+    sed -i "s/MY_CROP_MODEL_ID/$CROP_MODEL_ID/" $OUTPUT_FILE
+  else
+    sed -i "s/my-api-key/$API_KEY/" $OUTPUT_FILE
+  fi
+
   if echo "${f}" | grep -q "v2_split.txt"
   then
     sed -i "s/MY_API_KEY/$API_KEY_V2/" $OUTPUT_FILE
@@ -45,6 +64,14 @@ do
     sed -i "s/my-api-key/$API_KEY/" $OUTPUT_FILE
   fi
 
+  if echo "${f}" | grep -q "v2_ocr.txt"
+  then
+    sed -i "s/MY_API_KEY/$API_KEY_V2/" $OUTPUT_FILE
+    sed -i "s/MY_OCR_MODEL_ID/$OCR_MODEL_ID/" $OUTPUT_FILE
+  else
+    sed -i "s/my-api-key/$API_KEY/" $OUTPUT_FILE
+  fi
+
   if echo "$f" | grep -q "custom_v1.txt"
   then
     sed -i "s/my-account/$ACCOUNT/g" $OUTPUT_FILE
diff --git a/tests/v2/utilities/crop/test_crop_integration.py b/tests/v2/utilities/crop/test_crop_integration.py
@@ -20,7 +20,7 @@ def v2_client() -> ClientV2:
 
 @pytest.mark.integration
 @pytest.mark.v2
-def test_crop_blank(v2_client: ClientV2, crop_model_id: str):
+def test_crop_default_sample(v2_client: ClientV2, crop_model_id: str):
     input_source = PathInput(V2_UTILITIES_DATA_DIR / "crop" / "default_sample.jpg")
     response = v2_client.enqueue_and_get_result(
         CropResponse, input_source, CropParameters(crop_model_id)
diff --git a/tests/v2/utilities/ocr/__init__.py b/tests/v2/utilities/ocr/__init__.py
diff --git a/tests/v2/utilities/ocr/test_ocr_integration.py b/tests/v2/utilities/ocr/test_ocr_integration.py
@@ -0,0 +1,34 @@
+import os
+
+import pytest
+
+from mindee import ClientV2, PathInput
+from mindee.v2 import OCRParameters, OCRResponse
+from mindee.v2.product.ocr import OCRInference, OCRResult
+from tests.utils import V2_UTILITIES_DATA_DIR
+
+
+@pytest.fixture(scope="session")
+def ocr_model_id() -> str:
+    """Identifier of the Financial Document model, supplied through an env var."""
+    return os.getenv("MINDEE_V2_SE_TESTS_OCR_MODEL_ID")
+
+
+@pytest.fixture(scope="session")
+def v2_client() -> ClientV2:
+    return ClientV2()
+
+
+@pytest.mark.integration
+@pytest.mark.v2
+def test_ocr_default_sample(v2_client: ClientV2, ocr_model_id: str):
+    input_source = PathInput(V2_UTILITIES_DATA_DIR / "ocr" / "default_sample.jpg")
+    response = v2_client.enqueue_and_get_result(
+        OCRResponse, input_source, OCRParameters(ocr_model_id)
+    )
+    assert response.inference is not None
+    assert response.inference.file.name == "default_sample.jpg"
+    assert isinstance(response.inference, OCRInference)
+    assert isinstance(response.inference.result, OCRResult)
+    assert len(response.inference.result.pages) == 1
+    assert len(response.inference.result.pages[0].words) > 0
diff --git a/tests/v2/utilities/ocr/test_ocr_response.py b/tests/v2/utilities/ocr/test_ocr_response.py
diff --git a/tests/v2/utilities/split/test_split_integration.py b/tests/v2/utilities/split/test_split_integration.py
