♻️ rework product base classes

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.
 

mindee/v2/client_options/base_parameters.py → 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",

mindee/v2/parsing/inference/base_response.py → mindee/v2/parsing/inference/base_inference_response.py

@@ -5,11 +5,12 @@
 from mindee.v2.parsing.inference.base_inference import BaseInference
 
 
-class BaseResponse(ABC, CommonResponse):
+class BaseInferenceResponse(ABC, CommonResponse):
     """Base class for V2 inference responses."""
 
     inference: BaseInference
     """The inference result for a split utility request"""
+
     _slug: ClassVar[str]
     """Slug of the inference."""
 

mindee/v2/product/classification/classification_response.py

@@ -1,13 +1,13 @@
 from typing import ClassVar
 
 from mindee.parsing.common.string_dict import StringDict
-from mindee.v2.parsing.inference.base_response import BaseResponse
+from mindee.v2.parsing.inference.base_inference_response import BaseInferenceResponse
 from mindee.v2.product.classification.classification_inference import (
     ClassificationInference,
 )
 
 
-class ClassificationResponse(BaseResponse):
+class ClassificationResponse(BaseInferenceResponse):
     """Represent a classification inference response from Mindee V2 API."""
 
     inference: ClassificationInference

mindee/v2/product/classification/params/classification_parameters.py

@@ -1,9 +1,9 @@
 from typing import ClassVar
 
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 
 
-class ClassificationParameters(BaseParameters):
+class ClassificationParameters(BaseProductParameters):
     """
     Parameters accepted by the classification utility v2 endpoint.
     """

mindee/v2/product/crop/crop_response.py

@@ -1,11 +1,11 @@
 from typing import ClassVar
 
 from mindee.parsing.common.string_dict import StringDict
-from mindee.v2.parsing.inference.base_response import BaseResponse
+from mindee.v2.parsing.inference.base_inference_response import BaseInferenceResponse
 from mindee.v2.product.crop.crop_inference import CropInference
 
 
-class CropResponse(BaseResponse):
+class CropResponse(BaseInferenceResponse):
     """Represent a crop inference response from Mindee V2 API."""
 
     inference: CropInference

mindee/v2/product/crop/params/crop_parameters.py

@@ -1,9 +1,9 @@
 from typing import ClassVar
 
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 
 
-class CropParameters(BaseParameters):
+class CropParameters(BaseProductParameters):
     """
     Parameters accepted by the crop utility v2 endpoint.
     """

mindee/v2/product/extraction/extraction_response.py

@@ -1,11 +1,11 @@
 from typing import ClassVar
 
 from mindee.parsing.common.string_dict import StringDict
-from mindee.v2.parsing.inference.base_response import BaseResponse
+from mindee.v2.parsing.inference.base_inference_response import BaseInferenceResponse
 from mindee.v2.product.extraction.extraction_inference import ExtractionInference
 
 
-class ExtractionResponse(BaseResponse):
+class ExtractionResponse(BaseInferenceResponse):
     """Represent an inference response from Mindee V2 API."""
 
     inference: ExtractionInference

mindee/v2/product/extraction/params/extraction_parameters.py

@@ -2,12 +2,12 @@
 from dataclasses import dataclass
 from typing import ClassVar
 
-from mindee.v2.client_options.base_parameters import BaseParameters
+from mindee.v2.client_options.base_product_parameters import BaseProductParameters
 from mindee.v2.product.extraction.params.data_schema import DataSchema
 
 
 @dataclass
-class ExtractionParameters(BaseParameters):
+class ExtractionParameters(BaseProductParameters):
     """Inference parameters to set when sending a file."""
 
     rag: bool | None = None
@@ -41,13 +41,13 @@ def __post_init__(self):
         elif isinstance(self.data_schema, dict):
             self.data_schema = DataSchema(**self.data_schema)
 
-    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.
 
         :return: A dict of parameters.
         """
-        data = super().get_form_data()
+        data = super().get_request_parameters()
         if self.data_schema is not None:
             data["data_schema"] = str(self.data_schema)
         if self.rag is not None: