✨ Add inference options, fix polygons

.github/workflows/_test-code-samples.yml

@@ -13,7 +13,7 @@ jobs:
       matrix:
         php-version:
           - "7.4"
-          - "8.2"
+          - "8.3"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/_test-units.yml

@@ -24,7 +24,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
       - name: Unit testing with phpunit
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
@@ -55,7 +55,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
       - name: Change ImageMagick security policy on Ubuntu
         run: |
           DQT='"'
@@ -90,7 +90,7 @@ jobs:
           phpts: zts
         with:
           php-version: ${{ matrix.php-version }}
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
       - name: Unit testing with phpunit
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
@@ -133,7 +133,7 @@ jobs:
 #          php-version: ${{ matrix.php-version }}
 #      - name: Install Imagick
 #        run: pecl install imagick
-#      - uses: ramsey/composer-install@v2
+#      - uses: ramsey/composer-install@v3
 #      - name: Unit testing with phpunit
 #        env:
 #          MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
@@ -163,7 +163,7 @@ jobs:
         with:
           php-version: ${{ matrix.php-version }}
           extensions: curl, fileinfo, json
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
       - name: Unit testing with phpunit
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
@@ -200,7 +200,7 @@ jobs:
         with:
           php-version: ${{ matrix.php-version }}
           extensions: curl, fileinfo, json, imagick
-      - uses: ramsey/composer-install@v2
+      - uses: ramsey/composer-install@v3
       - name: Unit testing with phpunit
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}

docs/code_samples/default_v2.txt

@@ -14,8 +14,19 @@ $mindeeClient = new ClientV2($apiKey);
 // Set inference parameters
 // Note: modelId is mandatory.
 $inferenceParams = new InferenceParameters(
+    // ID of the model, required.
     $modelId,
-    // If set to `true`, will enable Retrieval-Augmented Generation.
+
+    // Options: set to `true` or `false` to override defaults
+
+    // Enhance extraction accuracy with Retrieval-Augmented Generation.
+    false,
+    // Extract the full text content from the document as strings.
+    false,
+    // Calculate bounding box polygons for all fields.
+    false,
+    // Boost the precision and accuracy of all extractions.
+    // Calculate confidence scores for all fields.
     false
 );
 

src/Geometry/Point.php

@@ -2,10 +2,13 @@
 
 namespace Mindee\Geometry;
 
+use ArrayAccess;
+use InvalidArgumentException;
+
 /**
  * Representation of the coordinates of a point.
  */
-class Point
+class Point implements ArrayAccess
 {
     /**
      * @var float X coordinate.
@@ -45,4 +48,68 @@ public function getY(): float
     {
         return $this->y;
     }
+
+    /**
+     *  Whether an offset exists.
+     * @param integer|string $offset Use 0 or 1.
+     * @return boolean
+     */
+    public function offsetExists($offset): bool
+    {
+        if ($offset === 0 || $offset === 1) {
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     *  Get an offset value.
+     * @param integer|string $offset Use 0 or 1.
+     * @return float
+     * @throws InvalidArgumentException If the offset is not 0 or 1.
+     */
+    public function offsetGet($offset): float
+    {
+        if ($offset === 0) {
+            return $this->x;
+        } elseif ($offset === 1) {
+            return $this->y;
+        }
+        throw new InvalidArgumentException("Use 0 for X or 1 for Y");
+    }
+
+    /**
+     *  Set an offset value.
+     * @param integer|string       $offset Use 0 or 1.
+     * @param float|integer|string $value  Coordinate value to set.
+     * @return void
+     * @throws InvalidArgumentException If the offset is not 0 or 1.
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if ($offset === 0) {
+            $this->x = $value;
+        } elseif ($offset === 1) {
+            $this->y = $value;
+        } else {
+            throw new InvalidArgumentException("Use 0 for X or 1 for Y");
+        }
+    }
+
+    /**
+     *  Get an offset value.
+     * @param integer|string $offset Use 0 or 1.
+     * @return void
+     * @throws InvalidArgumentException If the offset is not 0 or 1.
+     */
+    public function offsetUnset($offset): void
+    {
+        if ($offset === 0) {
+            unset($this->x);
+        } elseif ($offset === 1) {
+            unset($this->y);
+        } else {
+            throw new InvalidArgumentException("Use 0 for X or 1 for Y");
+        }
+    }
 }

src/Geometry/Polygon.php

@@ -8,7 +8,7 @@
 class Polygon
 {
     /**
-     * @var array|null Vertices of the polygon.
+     * @var Point[]|null Vertices of the polygon.
      */
     public ?array $coordinates;
 
@@ -17,7 +17,14 @@ class Polygon
      */
     public function __construct(?array $coordinates = null)
     {
-        $this->coordinates = $coordinates;
+        if (!is_null($coordinates)) {
+            $this->coordinates = [];
+            foreach ($coordinates as $point) {
+                $this->coordinates[] = new Point($point[0], $point[1]);
+            }
+        } else {
+            $this->coordinates = null;
+        }
     }
 
     /**
@@ -30,6 +37,50 @@ public function getCentroid(): Point
         return PolygonUtils::getCentroid($this->coordinates);
     }
 
+    /**
+     * Retrieves the upper and lower bounds of the y-axis.
+     *
+     * @return MinMax
+     */
+    public function getMinMaxY(): MinMax
+    {
+        return MinMaxUtils::getMinMaxY($this->coordinates);
+    }
+
+    /**
+     * Retrieves the upper and lower bounds of the x-axis.
+     *
+     * @return MinMax
+     */
+    public function getMinMaxX(): MinMax
+    {
+        return MinMaxUtils::getMinMaxX($this->coordinates);
+    }
+
+    /**
+     * Checks whether a point is located within the polygon's y-axis.
+     *
+     * @param Point $point Point to check.
+     * @return boolean
+     */
+    public function isPointInY(Point $point): bool
+    {
+        $minMax = $this->getMinMaxY();
+        return PolygonUtils::isPointInY($point, $minMax->getMin(), $minMax->getMax());
+    }
+
+    /**
+     * Checks whether a point is located within the polygon's x-axis.
+     *
+     * @param Point $point Point to check.
+     * @return boolean
+     */
+    public function isPointInX(Point $point): bool
+    {
+        $minMax = $this->getMinMaxX();
+        return PolygonUtils::isPointInX($point, $minMax->getMin(), $minMax->getMax());
+    }
+
     /**
      * Checks whether the Polygon has coordinates.
      *
@@ -58,7 +109,6 @@ public function __toString()
         if (!$this->isEmpty()) {
             return 'Polygon with ' . count($this->getCoordinates()) . ' points.';
         }
-
         return '';
     }
 }

src/Geometry/PolygonUtils.php

@@ -219,6 +219,7 @@ public static function quadrilateralFromPrediction(array $prediction): Polygon
     /**
      * Generates a Polygon from a given prediction.
      *
+     * @deprecated construct a new Polygon() instead.
      * @param array $prediction Raw prediction array.
      * @return Polygon
      */
@@ -228,7 +229,6 @@ public static function polygonFromPrediction(array $prediction): Polygon
         foreach ($prediction as $point) {
             $points[] = new Point($point[0], $point[1]);
         }
-
         return new Polygon($points);
     }
 

src/Http/MindeeApiV2.php

@@ -311,8 +311,17 @@ private function documentEnqueuePost(
             $postFields['file'] = $inputSource->fileObject;
         }
 
-        if ($params->rag) {
-            $postFields['rag'] = 'true';
+        if (isset($params->rawText)) {
+            $postFields['raw_text'] = $params->rawText ? 'true' : 'false';
+        }
+        if (isset($params->polygon)) {
+            $postFields['polygon'] = $params->polygon ? 'true' : 'false';
+        }
+        if (isset($params->confidence)) {
+            $postFields['confidence'] = $params->confidence ? 'true' : 'false';
+        }
+        if (isset($params->rag)) {
+            $postFields['rag'] = $params->rag ? 'true' : 'false';
         }
 
         $url = $this->baseUrl . '/inferences/enqueue';

src/Input/InferenceParameters.php

@@ -13,9 +13,25 @@ class InferenceParameters
     public string $modelId;
 
     /**
-     * @var boolean Whether to enable Retrieval-Augmented Generation.
+     * @var boolean|null Enhance extraction accuracy with Retrieval-Augmented Generation..
      */
-    public bool $rag;
+    public ?bool $rag;
+
+    /**
+     * @var boolean|null Extract the full text content from the document as strings.
+     */
+    public ?bool $rawText;
+
+    /**
+     * @var boolean|null Calculate bounding box polygons for all fields.
+     */
+    public ?bool $polygon;
+
+    /**
+     * @var boolean|null Boost the precision and accuracy of all extractions.
+     *      Calculate confidence scores for all fields.
+     */
+    public ?bool $confidence;
 
     /**
      * @var string|null Optional file alias.
@@ -40,6 +56,9 @@ class InferenceParameters
     /**
      * @param string              $modelId        ID of the model.
      * @param boolean|null        $rag            Whether to enable Retrieval-Augmented Generation.
+     * @param boolean|null        $rawText        Whether to extract the full text content from the document as strings.
+     * @param boolean|null        $polygon        Whether to calculate bounding box polygons for all fields.
+     * @param boolean|null        $confidence     Whether to calculate confidence scores for all fields.
      * @param string|null         $alias          Optional file alias.
      * @param array<string>|null  $webhooksIds    List of webhook IDs.
      * @param PollingOptions|null $pollingOptions Polling options.
@@ -48,6 +67,9 @@ class InferenceParameters
     public function __construct(
         string $modelId,
         ?bool $rag = null,
+        ?bool $rawText = null,
+        ?bool $polygon = null,
+        ?bool $confidence = null,
         ?string $alias = null,
         ?array $webhooksIds = null,
         ?PollingOptions $pollingOptions = null,
@@ -58,7 +80,11 @@ public function __construct(
             $pollingOptions = new PollingOptions();
         }
         $this->pollingOptions = $pollingOptions;
-        $this->rag = (bool) $rag;
+        $this->rag = $rag;
+        $this->rawText = $rawText;
+        $this->polygon = $polygon;
+        $this->confidence = $confidence;
+
         $this->closeFile = (bool) $closeFile;
         if (isset($alias)) {
             $this->alias = $alias;

src/Parsing/Common/Extras/Extras.php

@@ -12,31 +12,30 @@
 class Extras
 {
     /**
-     * @var \Mindee\Parsing\Common\Extras\CropperExtra|null Cropper extra.
+     * @var CropperExtra|null Cropper extra.
      */
     public ?CropperExtra $cropper;
     /**
-     * @var \Mindee\Parsing\Common\Extras\CropperExtra|null Full text OCR extra.
+     * @var FullTextOcrExtra|null Full text OCR extra.
      */
     public ?FullTextOcrExtra $fullTextOcr;
     /**
-     * @var \Mindee\Parsing\Common\Extras\RagExtra|null Rag Extra.
+     * @var RagExtra|null Rag Extra.
      */
     public ?RagExtra $rag;
     /**
      * @var array Other extras.
      */
     private array $data;
 
-
     /**
      * Sets a field.
      *
-     * @param mixed $varName Name of the field to set.
-     * @param mixed $value   Value to set the field with.
+     * @param string $varName Name of the field to set.
+     * @param mixed  $value   Value to set the field with.
      * @return void
      */
-    public function __set($varName, $value)
+    public function __set(string $varName, $value)
     {
         $this->data[$varName] = $value;
     }

src/Parsing/Standard/PositionField.php

@@ -57,7 +57,7 @@ private static function getQuadrilateral(array $rawPrediction, string $key): ?Po
     private static function getPolygon(array $rawPrediction, string $key): ?Polygon
     {
         if (array_key_exists($key, $rawPrediction)) {
-            return PolygonUtils::polygonFromPrediction($rawPrediction[$key]);
+            return new Polygon($rawPrediction[$key]);
         }
 
         return null;