✨ add support for split utility

.github/workflows/_test-integrations.yml

@@ -49,6 +49,7 @@ 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_SPLIT_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_SPLIT_MODEL_ID }}
       run: |
         pytest --cov mindee -m integration
 

mindee/client.py

@@ -353,7 +353,7 @@ def enqueue_and_parse(  # pylint: disable=too-many-locals
             if poll_results.job.status == "failed":
                 raise MindeeError("Parsing failed for job {poll_results.job.id}")
             logger.debug(
-                "Polling server for parsing result with job id: %s", queue_result.job.id
+                "Polling server for product result with job id: %s", queue_result.job.id
             )
             retry_counter += 1
             sleep(delay_sec)

mindee/client_v2.py

@@ -1,10 +1,11 @@
+import warnings
 from time import sleep
-from typing import Optional, Union
+from typing import Optional, Union, Type, TypeVar
 
 from mindee.client_mixin import ClientMixin
 from mindee.error.mindee_error import MindeeError
 from mindee.error.mindee_http_error_v2 import handle_error_v2
-from mindee.input import UrlInputSource
+from mindee.input import UrlInputSource, BaseParameters
 from mindee.input.inference_parameters import InferenceParameters
 from mindee.input.polling_options import PollingOptions
 from mindee.input.sources.local_input_source import LocalInputSource
@@ -15,9 +16,12 @@
     is_valid_post_response,
 )
 from mindee.parsing.v2.common_response import CommonStatus
+from mindee.v2.parsing.inference.base_response import BaseResponse
 from mindee.parsing.v2.inference_response import InferenceResponse
 from mindee.parsing.v2.job_response import JobResponse
 
+TypeBaseInferenceResponse = TypeVar("TypeBaseInferenceResponse", bound=BaseResponse)
+
 
 class ClientV2(ClientMixin):
     """
@@ -41,20 +45,34 @@ def __init__(self, api_key: Optional[str] = None) -> None:
     def enqueue_inference(
         self,
         input_source: Union[LocalInputSource, UrlInputSource],
-        params: InferenceParameters,
+        params: BaseParameters,
+        disable_redundant_warnings: bool = False,
+    ) -> JobResponse:
+        """[Deprecated] Use `enqueue` instead."""
+        if not disable_redundant_warnings:
+            warnings.warn(
+                "enqueue_inference is deprecated; use enqueue instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self.enqueue(input_source, params)
+
+    def enqueue(
+        self,
+        input_source: Union[LocalInputSource, UrlInputSource],
+        params: BaseParameters,
     ) -> JobResponse:
         """
         Enqueues a document to a given model.
 
         :param input_source: The document/source file to use. Can be local or remote.
-
         :param params: Parameters to set when sending a file.
+
         :return: A valid inference response.
         """
         logger.debug("Enqueuing inference using model: %s", params.model_id)
-
         response = self.mindee_api.req_post_inference_enqueue(
-            input_source=input_source, params=params
+            input_source=input_source, params=params, slug=params.get_enqueue_slug()
         )
         dict_response = response.json()
 
@@ -79,34 +97,78 @@ def get_job(self, job_id: str) -> JobResponse:
         dict_response = response.json()
         return JobResponse(dict_response)
 
-    def get_inference(self, inference_id: str) -> InferenceResponse:
+    def get_inference(
+        self,
+        inference_id: str,
+        response_type: Type[BaseResponse] = InferenceResponse,
+        disable_redundant_warnings: bool = False,
+    ) -> BaseResponse:
+        """[Deprecated] Use `get_result` instead."""
+        if not disable_redundant_warnings:
+            warnings.warn(
+                "get_inference is deprecated; use get_result instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self.get_result(inference_id, response_type)
+
+    def get_result(
+        self,
+        inference_id: str,
+        response_type: Optional[Type[BaseResponse]] = InferenceResponse,
+    ) -> BaseResponse:
         """
         Get the result of an inference that was previously enqueued.
 
         The inference will only be available after it has finished processing.
 
         :param inference_id: UUID of the inference to retrieve.
+        :param response_type: Class of the product to instantiate.
+        :return: An inference response.
+        """
+        response_type = response_type or InferenceResponse
+        response = self._get_result(inference_id, response_type)
+        assert isinstance(response, response_type), (
+            f'Invalid response type "{type(response)}"'
+        )
+        return response
+
+    def _get_result(
+        self,
+        inference_id: str,
+        response_type: Type[BaseResponse] = InferenceResponse,
+    ) -> BaseResponse:
+        """
+        Get the result of an inference that was previously enqueued.
+
+        The inference will only be available after it has finished processing.
+
+        :param inference_id: UUID of the inference to retrieve.
+        :param response_type: Class of the product to instantiate.
         :return: An inference response.
         """
         logger.debug("Fetching inference: %s", inference_id)
 
-        response = self.mindee_api.req_get_inference(inference_id)
+        response = self.mindee_api.req_get_inference(
+            inference_id, response_type.get_result_slug()
+        )
         if not is_valid_get_response(response):
             handle_error_v2(response.json())
         dict_response = response.json()
-        return InferenceResponse(dict_response)
+        return response_type(dict_response)
 
-    def enqueue_and_get_inference(
+    def _enqueue_and_get(
         self,
         input_source: Union[LocalInputSource, UrlInputSource],
-        params: InferenceParameters,
-    ) -> InferenceResponse:
+        params: BaseParameters,
+        response_type: Optional[Type[BaseResponse]] = InferenceResponse,
+    ) -> BaseResponse:
         """
         Enqueues to an asynchronous endpoint and automatically polls for a response.
 
         :param input_source: The document/source file to use. Can be local or remote.
-
         :param params: Parameters to set when sending a file.
+        :param response_type: The product class to use for the response object.
 
         :return: A valid inference response.
         """
@@ -117,9 +179,9 @@ def enqueue_and_get_inference(
             params.polling_options.delay_sec,
             params.polling_options.max_retries,
         )
-        enqueue_response = self.enqueue_inference(input_source, params)
+        enqueue_response = self.enqueue_inference(input_source, params, True)
         logger.debug(
-            "Successfully enqueued inference with job id: %s", enqueue_response.job.id
+            "Successfully enqueued document with job id: %s", enqueue_response.job.id
         )
         sleep(params.polling_options.initial_delay_sec)
         try_counter = 0
@@ -134,8 +196,51 @@ def enqueue_and_get_inference(
                     f"Parsing failed for job {job_response.job.id}: {detail}"
                 )
             if job_response.job.status == CommonStatus.PROCESSED.value:
-                return self.get_inference(job_response.job.id)
+                result = self.get_inference(
+                    job_response.job.id, response_type or InferenceResponse, True
+                )
+                return result
             try_counter += 1
             sleep(params.polling_options.delay_sec)
 
         raise MindeeError(f"Couldn't retrieve document after {try_counter + 1} tries.")
+
+    def enqueue_and_get_inference(
+        self,
+        input_source: Union[LocalInputSource, UrlInputSource],
+        params: InferenceParameters,
+    ) -> InferenceResponse:
+        """[Deprecated] Use `enqueue_and_get_result` instead."""
+        warnings.warn(
+            "enqueue_and_get_inference is deprecated; use enqueue_and_get_result",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        response = self._enqueue_and_get(input_source, params)
+        assert isinstance(response, InferenceResponse), (
+            f'Invalid response type "{type(response)}"'
+        )
+        return response
+
+    def enqueue_and_get_result(
+        self,
+        response_type: Type[TypeBaseInferenceResponse],
+        input_source: Union[LocalInputSource, UrlInputSource],
+        params: BaseParameters,
+    ) -> TypeBaseInferenceResponse:
+        """
+        Enqueues to an asynchronous endpoint and automatically polls for a response.
+
+        :param input_source: The document/source file to use. Can be local or remote.
+
+        :param params: Parameters to set when sending a file.
+
+        :param response_type: The product class to use for the response object.
+
+        :return: A valid inference response.
+        """
+        response = self._enqueue_and_get(input_source, params, response_type)
+        assert isinstance(response, response_type), (
+            f'Invalid response type "{type(response)}"'
+        )
+        return response

mindee/error/mindee_http_error_v2.py

@@ -1,5 +1,5 @@
 import json
-from typing import Optional
+from typing import List, Optional
 
 from mindee.parsing.common.string_dict import StringDict
 from mindee.parsing.v2 import ErrorItem, ErrorResponse
@@ -18,7 +18,7 @@ def __init__(self, response: ErrorResponse) -> None:
         self.title = response.title
         self.code = response.code
         self.detail = response.detail
-        self.errors: list[ErrorItem] = response.errors
+        self.errors: List[ErrorItem] = response.errors
         super().__init__(
             f"HTTP {self.status} - {self.title} :: {self.code} - {self.detail}"
         )

mindee/input/__init__.py

@@ -1,4 +1,7 @@
 from mindee.input.local_response import LocalResponse
+from mindee.input.base_parameters import BaseParameters
+from mindee.input.inference_parameters import InferenceParameters
+from mindee.v2.product.split.split_parameters import SplitParameters
 from mindee.input.page_options import PageOptions
 from mindee.input.polling_options import PollingOptions
 from mindee.input.sources.base_64_input import Base64Input
@@ -11,15 +14,18 @@
 from mindee.input.workflow_options import WorkflowOptions
 
 __all__ = [
+    "Base64Input",
+    "BaseParameters",
+    "BytesInput",
+    "FileInput",
     "InputType",
+    "InferenceParameters",
     "LocalInputSource",
-    "UrlInputSource",
+    "LocalResponse",
+    "PageOptions",
     "PathInput",
-    "FileInput",
-    "Base64Input",
-    "BytesInput",
-    "WorkflowOptions",
     "PollingOptions",
-    "PageOptions",
-    "LocalResponse",
+    "UrlInputSource",
+    "SplitParameters",
+    "WorkflowOptions",
 ]

mindee/input/base_parameters.py

@@ -0,0 +1,44 @@
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Dict, Optional, List, Union
+
+from mindee.input.polling_options import PollingOptions
+
+
+@dataclass
+class BaseParameters(ABC):
+    """Base class for parameters accepted by all V2 endpoints."""
+
+    _slug: str = field(init=False)
+    """Slug of the endpoint."""
+
+    model_id: str
+    """ID of the model, required."""
+    alias: Optional[str] = None
+    """Use an alias to link the file to your own DB. If empty, no alias will be used."""
+    webhook_ids: Optional[List[str]] = None
+    """IDs of webhooks to propagate the API response to."""
+    polling_options: Optional[PollingOptions] = None
+    """Options for polling. Set only if having timeout issues."""
+    close_file: bool = True
+    """Whether to close the file after product."""
+
+    def get_form_data(self) -> Dict[str, Union[str, List[str]]]:
+        """
+        Return the parameters as a config dictionary.
+
+        :return: A dict of parameters.
+        """
+        data: Dict[str, Union[str, List[str]]] = {
+            "model_id": self.model_id,
+        }
+        if self.alias is not None:
+            data["alias"] = self.alias
+        if self.webhook_ids and len(self.webhook_ids) > 0:
+            data["webhook_ids"] = self.webhook_ids
+        return data
+
+    @classmethod
+    def get_enqueue_slug(cls) -> str:
+        """Getter for the enqueue slug."""
+        return cls._slug