♻️ 💥 fully remove v2 Inference in favor of Extraction (#186)

Author: sebastianMindee

docs/code_samples/v2_extraction_polling.txt

@@ -1,9 +1,9 @@
 <?php
 
 use Mindee\V2\Client;
-use Mindee\V2\Product\Extraction\Params\InferenceParameters;
+use Mindee\V2\Product\Extraction\Params\ExtractionParameters;
 use Mindee\Input\PathInput;
-use Mindee\V2\Parsing\Inference\InferenceResponse;
+use Mindee\V2\Product\Extraction\ExtractionResponse;
 
 $apiKey = "MY_API_KEY";
 $filePath = "/path/to/the/file.ext";
@@ -14,7 +14,7 @@ $mindeeClient = new Client($apiKey);
 
 // Set inference parameters
 // Note: modelId is mandatory.
-$inferenceParams = new InferenceParameters(
+$inferenceParams = new ExtractionParameters(
     // ID of the model, required.
     $modelId,
 
@@ -36,7 +36,7 @@ $inputSource = new PathInput($filePath);
 
 // Send for processing using polling
 $response = $mindeeClient->enqueueAndGetResult(
-    InferenceResponse::class,
+    ExtractionResponse::class,
     $inputSource,
     $inferenceParams
 );

docs/code_samples/v2_extraction_webhook.txt

@@ -1,7 +1,7 @@
 <?php
 
 use Mindee\V2\Client;
-use Mindee\V2\Product\Extraction\Params\InferenceParameters;
+use Mindee\V2\Product\Extraction\Params\ExtractionParameters;
 use Mindee\Input\PathInput;
 
 $apiKey = "MY_API_KEY";
@@ -13,7 +13,7 @@ $mindeeClient = new Client($apiKey);
 
 // Set inference parameters
 // Note: modelId is mandatory.
-$inferenceParams = new InferenceParameters(
+$inferenceParams = new ExtractionParameters(
     // ID of the model, required.
     $modelId,
     webhooksIds: ["MY_WEBHOOK_ID"],

src/V1/Parsing/Common/ApiResponse.php

@@ -8,7 +8,7 @@
 abstract class ApiResponse
 {
     /**
-     * @var \Mindee\V1\Parsing\Common\ApiRequest Request part of the response.
+     * @var ApiRequest Request part of the response.
      */
     public ApiRequest $apiRequest;
     /**

src/V1/Parsing/Common/AsyncPredictResponse.php

@@ -10,12 +10,12 @@
 class AsyncPredictResponse extends ApiResponse
 {
     /**
-     * @var \Mindee\V1\Parsing\Common\Job Job object link to the prediction.
+     * @var Job Job object link to the prediction.
      * As long as it isn't complete, the prediction doesn't exist.
      */
     public Job $job;
     /**
-     * @var \Mindee\V1\Parsing\Common\Document|null Document object. Can be null when enqueuing.
+     * @var Document|null Document object. Can be null when enqueuing.
      */
     public ?Document $document;
 

src/V1/Parsing/Common/Document.php

@@ -6,6 +6,8 @@
 use Mindee\Error\MindeeApiException;
 use Mindee\V1\Parsing\Common\Extras\Extras;
 use Mindee\V1\Parsing\Common\OCR\OCR;
+use ReflectionClass;
+use ReflectionException;
 
 /**
  * Base class for all predictions.
@@ -17,7 +19,7 @@ class Document
      */
     public string $filename;
     /**
-     * @var \Mindee\V1\Parsing\Common\Inference|object|string Result of the base inference.
+     * @var Inference|object|string Result of the base inference.
      */
     public Inference $inference;
     /**
@@ -29,28 +31,28 @@ class Document
      */
     public int $nPages;
     /**
-     * @var \Mindee\V1\Parsing\Common\Extras\Extras|null Potential Extras fields sent back along with the prediction.
+     * @var Extras|null Potential Extras fields sent back along with the prediction.
      */
     public ?Extras $extras;
     /**
-     * @var \Mindee\V1\Parsing\Common\OCR\OCR|null Potential raw text results read by the OCR (limited feature)
+     * @var OCR|null Potential raw text results read by the OCR (limited feature)
      */
     public ?OCR $ocr;
 
     /**
      * @param string $predictionType Type of prediction.
      * @param array  $rawResponse    Raw HTTP response.
-     * @throws \Mindee\Error\MindeeApiException Throws if the prediction type isn't recognized.
+     * @throws MindeeApiException Throws if the prediction type isn't recognized.
      */
     public function __construct(string $predictionType, array $rawResponse)
     {
         $this->id = $rawResponse['id'];
         $this->nPages = $rawResponse['n_pages'];
         $this->filename = $rawResponse['name'];
         try {
-            $reflection = new \ReflectionClass($predictionType);
+            $reflection = new ReflectionClass($predictionType);
             $this->inference = $reflection->newInstance($rawResponse['inference']);
-        } catch (\ReflectionException $e) {
+        } catch (ReflectionException $e) {
             throw new MindeeApiException(
                 "Unable to create custom product " . $predictionType,
                 ErrorCode::INTERNAL_LIBRARY_ERROR,

src/V1/Parsing/Common/Inference.php

@@ -10,7 +10,7 @@
 abstract class Inference
 {
     /**
-     * @var \Mindee\V1\Parsing\Common\Product Name and version of a given product, as sent back by the API.
+     * @var Product Name and version of a given product, as sent back by the API.
      */
     public Product $product;
     /**
@@ -22,7 +22,7 @@ abstract class Inference
      */
     public static string $endpointVersion;
     /**
-     * @var \Mindee\V1\Parsing\Common\Prediction A document's top-level Prediction.
+     * @var Prediction A document's top-level Prediction.
      */
     public Prediction $prediction;
     /**
@@ -38,7 +38,7 @@ abstract class Inference
      */
     public ?int $pageId;
     /**
-     * @var \Mindee\V1\Parsing\Common\Extras\Extras|null Potential Extras fields sent back along with the prediction.
+     * @var Extras|null Potential Extras fields sent back along with the prediction.
      */
     public ?Extras $extras;
 

src/V1/Parsing/Common/OCR/OCR.php

@@ -8,7 +8,7 @@
 class OCR
 {
     /**
-     * @var \Mindee\V1\Parsing\Common\OCR\MVisionV1 Mindee Vision v1 results.
+     * @var MVisionV1 Mindee Vision v1 results.
      */
     public MVisionV1 $mvisionV1;
 

src/V1/Parsing/Standard/PositionField.php

@@ -11,23 +11,23 @@
 class PositionField extends BaseField
 {
     /**
-     * @var \Mindee\Geometry\Polygon|null Polygon of cropped area, identical to the `polygon` property.
+     * @var Polygon|null Polygon of cropped area, identical to the `polygon` property.
      */
     public $value;
     /**
-     * @var \Mindee\Geometry\Polygon|null Polygon of cropped area.
+     * @var Polygon|null Polygon of cropped area.
      */
     public ?Polygon $polygon;
     /**
-     * @var \Mindee\Geometry\Polygon|null Quadrangle of cropped area (does not exceed the canvas).
+     * @var Polygon|null Quadrangle of cropped area (does not exceed the canvas).
      */
     public ?Polygon $quadrangle;
     /**
-     * @var \Mindee\Geometry\Polygon|null Oriented rectangle of cropped area (may exceed the canvas).
+     * @var Polygon|null Oriented rectangle of cropped area (may exceed the canvas).
      */
     public ?Polygon $rectangle;
     /**
-     * @var \Mindee\Geometry\Polygon|null Straight rectangle of cropped area (does not exceed the canvas).
+     * @var Polygon|null Straight rectangle of cropped area (does not exceed the canvas).
      */
     public ?Polygon $boundingBox;
 
@@ -36,7 +36,7 @@ class PositionField extends BaseField
      *
      * @param array  $rawPrediction Raw prediction array.
      * @param string $key           Key to use for the value.
-     * @return \Mindee\Geometry\Polygon|null
+     * @return Polygon|null
      */
     private static function getQuadrilateral(array $rawPrediction, string $key): ?Polygon
     {
@@ -52,7 +52,7 @@ private static function getQuadrilateral(array $rawPrediction, string $key): ?Po
      *
      * @param array  $rawPrediction Raw prediction array.
      * @param string $key           Key to use for the value.
-     * @return \Mindee\Geometry\Polygon|null
+     * @return Polygon|null
      */
     private static function getPolygon(array $rawPrediction, string $key): ?Polygon
     {

src/V2/Client.php

@@ -2,15 +2,15 @@
 
 namespace Mindee\V2;
 
+use Mindee\ClientOptions\PollingOptions;
 use Mindee\CustomSleepMixin;
 use Mindee\Error\MindeeException;
 use Mindee\Input\InputSource;
 use Mindee\V2\ClientOptions\BaseParameters;
 use Mindee\V2\HTTP\MindeeAPIV2;
 use Mindee\V2\Parsing\Inference\BaseResponse;
-use Mindee\V2\Parsing\Inference\InferenceResponse;
 use Mindee\V2\Parsing\JobResponse;
-use Mindee\V2\Product\Extraction\Params\InferenceParameters;
+use Mindee\V2\Product\Extraction\Params\ExtractionParameters;
 
 /**
  * Mindee Client V2.
@@ -37,15 +37,15 @@ public function __construct(?string $apiKey = null)
     /**
      * Send the document to an asynchronous endpoint and return its ID in the queue.
      *
-     * @param InputSource         $inputSource File to parse.
-     * @param InferenceParameters $params      Parameters relating to prediction options.
+     * @param InputSource          $inputSource File to parse.
+     * @param ExtractionParameters $params      Parameters relating to prediction options.
      * @return JobResponse A JobResponse containing the job (queue) corresponding to a document.
      * @throws MindeeException Throws if the input document is not provided.
      * @category Asynchronous
      */
     public function enqueueInference(
         InputSource $inputSource,
-        InferenceParameters $params
+        ExtractionParameters $params
     ): JobResponse {
         return $this->enqueue($inputSource, $params);
     }
@@ -65,17 +65,6 @@ public function enqueue(
         return $this->mindeeApi->reqPostEnqueue($inputSource, $params);
     }
 
-    /**
-     * Retrieves an inference.
-     *
-     * @param string $inferenceId ID of the queue to poll.
-     * @return InferenceResponse An InferenceResponse containing a Job.
-     * @category Asynchronous
-     */
-    public function getInference(string $inferenceId): InferenceResponse
-    {
-        return $this->mindeeApi->reqGetInference($inferenceId);
-    }
 
     /**
      * @template T of BaseResponse
@@ -118,40 +107,28 @@ public function getJob(string $jobId): JobResponse
         return $this->mindeeApi->reqGetJob($jobId);
     }
 
-    /**
-     * Send a document to an endpoint and poll the server until the result is sent or
-     * until the maximum number of tries is reached.
-     *
-     * @param InputSource         $inputDoc Input document to parse.
-     * @param InferenceParameters $params   Parameters relating to prediction options.
-     * @return InferenceResponse A response containing parsing results.
-     * @throws MindeeException Throws if enqueueing fails, job fails, or times out.
-     */
-    public function enqueueAndGetInference(
-        InputSource $inputDoc,
-        InferenceParameters $params
-    ): InferenceResponse {
-        return $this->enqueueAndGetResult(InferenceResponse::class, $inputDoc, $params);
-    }
-
     /**
      * Send a document to an endpoint and poll the server until the result is sent or
      * until the maximum number of tries is reached.
      *
      * @template T of BaseResponse
-     * @param string         $responseClass The response class to construct.
+     * @param string              $responseClass  The response class to construct.
      * @phpstan-param class-string<T> $responseClass
-     * @param InputSource    $inputDoc      Input document to parse.
-     * @param BaseParameters $params        Parameters relating to prediction options.
+     * @param InputSource         $inputDoc       Input document to parse.
+     * @param BaseParameters      $params         Parameters relating to prediction options.
+     * @param PollingOptions|null $pollingOptions Options to apply to the polling.
      * @return BaseResponse A response containing parsing results.
      * @throws MindeeException Throws if enqueueing fails, job fails, or times out.
      */
     public function enqueueAndGetResult(
         string $responseClass,
         InputSource $inputDoc,
-        BaseParameters $params
+        BaseParameters $params,
+        ?PollingOptions $pollingOptions = null
     ): BaseResponse {
-        $pollingOptions = $params->pollingOptions;
+        if (!$pollingOptions) {
+            $pollingOptions = new PollingOptions();
+        }
 
         $enqueueResponse = $this->enqueue($inputDoc, $params);
 

src/V2/ClientOptions/BaseParameters.php

@@ -2,8 +2,6 @@
 
 namespace Mindee\V2\ClientOptions;
 
-use Mindee\ClientOptions\PollingOptions;
-
 /**
  * Base parameters for running an inference.
  */
@@ -25,17 +23,11 @@ abstract class BaseParameters
     public array $webhooksIds;
 
     /**
-     * @var PollingOptions Polling options.
+     * @param string             $modelId     ID of the model.
+     * @param string|null        $alias       Optional file alias.
+     * @param array<string>|null $webhooksIds List of webhook IDs.
      */
-    public PollingOptions $pollingOptions;
-
-    /**
-     * @param string              $modelId        ID of the model.
-     * @param string|null         $alias          Optional file alias.
-     * @param array<string>|null  $webhooksIds    List of webhook IDs.
-     * @param PollingOptions|null $pollingOptions Polling options.
-     */
-    public function __construct(string $modelId, ?string $alias, ?array $webhooksIds, ?PollingOptions $pollingOptions)
+    public function __construct(string $modelId, ?string $alias, ?array $webhooksIds)
     {
         $this->modelId = $modelId;
 
@@ -47,10 +39,6 @@ public function __construct(string $modelId, ?string $alias, ?array $webhooksIds
         } else {
             $this->webhooksIds = [];
         }
-        if (!$pollingOptions) {
-            $pollingOptions = new PollingOptions();
-        }
-        $this->pollingOptions = $pollingOptions;
     }
 
     /**