♻️ rework product base classes (#456)

Author: ianardee

mindee/v2/client.py

@@ -11,13 +11,15 @@
 from mindee.logger import logger
 from mindee.mindee_http.cancellation_token import CancellationToken
 from mindee.parsing.common.common_response import CommonStatus
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.mindee_http.mindee_api_v2 import MindeeAPIV2
-from mindee.v2.parsing.inference.base_response import BaseResponse
+from mindee.v2.parsing.inference.base_inference_response import BaseInferenceResponse
 from mindee.v2.parsing.job.job_response import JobResponse
 from mindee.v2.parsing.search.search_response import SearchResponse
 
-TypeBaseResponse = TypeVar("TypeBaseResponse", bound=BaseResponse)
+TypeBaseInferenceResponse = TypeVar(
+    "TypeBaseInferenceResponse", bound=BaseInferenceResponse
+)
 
 
 class Client(ClientMixin):
@@ -44,7 +46,7 @@ def __init__(
     def enqueue(
         self,
         input_source: LocalInputSource | URLInputSource,
-        params: BaseParameters,
+        params: BaseProductParameters,
     ) -> JobResponse:
         """
         Enqueues a document to a given model.
@@ -72,9 +74,9 @@ def get_job(self, job_id: str) -> JobResponse:
 
     def get_result(
         self,
-        response_type: type[TypeBaseResponse],
+        response_type: type[TypeBaseInferenceResponse],
         inference_id: str,
-    ) -> TypeBaseResponse:
+    ) -> TypeBaseInferenceResponse:
         """
         Get the result of an inference that was previously enqueued.
 
@@ -89,8 +91,8 @@ def get_result(
         return self.mindee_api.get_result(response_type, inference_id)
 
     def get_result_from_url(
-        self, response_type: type[TypeBaseResponse], url: str
-    ) -> TypeBaseResponse:
+        self, response_type: type[TypeBaseInferenceResponse], url: str
+    ) -> TypeBaseInferenceResponse:
         """
         Get the result of an inference that was previously enqueued by its URL.
 
@@ -102,11 +104,11 @@ def get_result_from_url(
 
     def enqueue_and_get_result(
         self,
-        response_type: type[TypeBaseResponse],
+        response_type: type[TypeBaseInferenceResponse],
         input_source: LocalInputSource | URLInputSource,
-        params: BaseParameters,
+        params: BaseProductParameters,
         cancellation_token: CancellationToken | None = None,
-    ) -> TypeBaseResponse:
+    ) -> TypeBaseInferenceResponse:
         """
         Enqueues to an asynchronous endpoint and automatically polls for a response.
 

…dee/v2/client_options/base_parameters.py …lient_options/base_product_parameters.pymindee/v2/client_options/base_parameters.py renamed to mindee/v2/client_options/base_product_parameters.py mindee/v2/client_options/base_parameters.py renamed to mindee/v2/client_options/base_product_parameters.py

@@ -6,24 +6,35 @@
 
 
 @dataclass
-class BaseParameters(ABC):
-    """Base class for parameters accepted by all V2 endpoints."""
+class BaseProductParameters(ABC):
+    """Base parameters for sending a document to a product."""
 
     model_id: str
-    """ID of the model, required."""
+    """Model ID to use for the inference. Required."""
+
     alias: str | None = None
-    """Use an alias to link the file to your own DB. If empty, no alias will be used."""
+    """
+    Optional: a free-form string to tag the request with your own identifier.
+    For example, an internal document ID, reference number, or database key.
+    If set, it will be included in the job and result responses.
+    """
+
     webhook_ids: list[str] | None = None
-    """IDs of webhooks to propagate the API response to."""
+    """
+    Webhook IDs to call after all processing is finished.
+    If empty, no webhooks will be used.
+    """
+
     polling_options: PollingOptions | None = None
     """Options for polling. Set only if having timeout issues."""
+
     close_file: bool = True
     """Whether to close the file after product."""
 
     _slug: ClassVar[str]
     """Slug of the endpoint."""
 
-    def get_form_data(self) -> dict[str, str | list[str]]:
+    def get_request_parameters(self) -> dict[str, str | list[str]]:
         """
         Return the parameters as a config dictionary.
 

mindee/v2/commands/base_inference_command.py

@@ -11,7 +11,7 @@
 )
 from mindee.input import PathInput, URLInputSource
 from mindee.v2.client import Client
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.output_type import OutputType
 
 
@@ -137,7 +137,7 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         """Build the V2 inference parameters for this product."""
 
     @abstractmethod

mindee/v2/commands/classification_command.py

@@ -1,7 +1,7 @@
 from argparse import Namespace
 
 from mindee import ClassificationParameters, ClassificationResponse
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.base_inference_command import BaseInferenceCommand
 
 
@@ -20,7 +20,7 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         del parsed_args
         return ClassificationParameters(
             model_id=model_id, alias=alias, webhook_ids=webhook_ids

mindee/v2/commands/crop_command.py

@@ -1,7 +1,7 @@
 from argparse import Namespace
 
 from mindee import CropParameters, CropResponse
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.base_inference_command import BaseInferenceCommand
 
 
@@ -20,6 +20,6 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         del parsed_args
         return CropParameters(model_id=model_id, alias=alias, webhook_ids=webhook_ids)

mindee/v2/commands/extraction_command.py

@@ -1,7 +1,7 @@
 from argparse import ArgumentParser, Namespace
 
 from mindee import ExtractionParameters, ExtractionResponse
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.base_inference_command import BaseInferenceCommand
 
 
@@ -65,7 +65,7 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         return ExtractionParameters(
             model_id=model_id,
             alias=alias,

mindee/v2/commands/ocr_command.py

@@ -1,7 +1,7 @@
 from argparse import Namespace
 
 from mindee import OCRParameters, OCRResponse
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.base_inference_command import BaseInferenceCommand
 
 
@@ -20,6 +20,6 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         del parsed_args
         return OCRParameters(model_id=model_id, alias=alias, webhook_ids=webhook_ids)

mindee/v2/commands/split_command.py

@@ -1,7 +1,7 @@
 from argparse import Namespace
 
 from mindee import SplitParameters, SplitResponse
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.commands.base_inference_command import BaseInferenceCommand
 
 
@@ -20,6 +20,6 @@ def build_parameters(
         model_id: str,
         alias: str | None,
         webhook_ids: list[str] | None,
-    ) -> BaseParameters:
+    ) -> BaseProductParameters:
         del parsed_args
         return SplitParameters(model_id=model_id, alias=alias, webhook_ids=webhook_ids)

mindee/v2/mindee_http/mindee_api_v2.py

@@ -11,7 +11,7 @@
 from mindee.mindee_http.settings_mixin import SettingsMixin
 from mindee.parsing.common.string_dict import StringDict
 from mindee.v1.mindee_http.base_settings import USER_AGENT
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.error.mindee_api_v2_error import MindeeAPIV2Error
 from mindee.v2.error.mindee_http_error_v2 import (
     MindeeHTTPUnknownErrorV2,
@@ -21,7 +21,7 @@
     is_valid_get_response,
     is_valid_post_response,
 )
-from mindee.v2.parsing import BaseResponse
+from mindee.v2.parsing import BaseInferenceResponse
 from mindee.v2.parsing.job.job_response import JobResponse
 from mindee.v2.parsing.search.search_response import SearchResponse
 
@@ -34,7 +34,7 @@
 REQUEST_TIMEOUT_ENV_NAME = "MINDEE_REQUEST_TIMEOUT"
 TIMEOUT_DEFAULT = 120
 
-ResponseT = TypeVar("ResponseT", bound=BaseResponse)
+ResponseT = TypeVar("ResponseT", bound=BaseInferenceResponse)
 
 
 class MindeeAPIV2(SettingsMixin):
@@ -92,7 +92,7 @@ def set_from_env(self) -> None:
     def req_post_inference_enqueue(
         self,
         input_source: LocalInputSource | URLInputSource,
-        params: BaseParameters,
+        params: BaseProductParameters,
         slug: str,
     ) -> httpx.Response:
         """
@@ -103,7 +103,7 @@ def req_post_inference_enqueue(
         :param slug: Slug to use for the enqueueing, defaults to 'inferences'.
         :return: httpx response.
         """
-        data = params.get_form_data()
+        data = params.get_request_parameters()
         url = f"{self.url_root}/v2/{slug}/enqueue"
         post_kwargs: StringDict = {}
         if isinstance(input_source, LocalInputSource):
@@ -219,7 +219,9 @@ def req_get_search_models(
         )
 
     def enqueue(
-        self, input_source: LocalInputSource | URLInputSource, params: BaseParameters
+        self,
+        input_source: LocalInputSource | URLInputSource,
+        params: BaseProductParameters,
     ) -> JobResponse:
         """
         Enqueues a document to a given model.

mindee/v2/parsing/__init__.py

@@ -1,7 +1,7 @@
 from mindee.v2.parsing.error.error_item import ErrorItem
 from mindee.v2.parsing.error.error_response import ErrorResponse
 from mindee.v2.parsing.inference.base_inference import BaseInference
-from mindee.v2.parsing.inference.base_response import BaseResponse
+from mindee.v2.parsing.inference.base_inference_response import BaseInferenceResponse
 from mindee.v2.parsing.inference.failed_inference_response import (
     FailedInferenceResponse,
 )
@@ -15,7 +15,7 @@
 
 __all__ = [
     "BaseInference",
-    "BaseResponse",
+    "BaseInferenceResponse",
     "ErrorItem",
     "ErrorResponse",
     "ExtractionInference",