♻️ simplify RAG CRUD

src/V2/Client.php

@@ -12,6 +12,7 @@
 use Mindee\Input\LocalInputSource;
 use Mindee\V2\ClientOptions\BaseAnnotationParameters;
 use Mindee\V2\ClientOptions\BaseProductParameters;
+use Mindee\V2\ClientOptions\BaseRagDocumentUploadParameters;
 use Mindee\V2\ClientOptions\BaseSearchParameters;
 use Mindee\V2\Http\MindeeApiV2;
 use Mindee\V2\Parsing\BaseRagAnnotationResponse;
@@ -191,19 +192,16 @@ public function enqueueAndGetResult(
      * Add a document to the RAG database.
      *
      * @template T of BaseRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
      * @param LocalInputSource $inputSource Local file to upload.
-     * @param RagDocumentUploadParameters $params Upload parameters.
+     * @param BaseRagDocumentUploadParameters<T> $params Upload parameters.
      * @return T
      */
     public function uploadRagDocument(
-        string $responseClass,
         LocalInputSource $inputSource,
-        RagDocumentUploadParameters $params
+        BaseRagDocumentUploadParameters $params
     ): BaseRagAnnotationResponse {
         error_log("Adding a document to the RAG database");
-        return $this->mindeeApi->reqPostRagDocument($responseClass, $inputSource, $params);
+        return $this->mindeeApi->reqPostRagDocument($inputSource, $params);
     }
 
     /**
@@ -226,16 +224,13 @@ public function getRagDocument(string $responseClass, string $documentId): BaseR
      * Update a document's annotations in the RAG database.
      *
      * @template T of BaseRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
-     * @param BaseAnnotationParameters $params Annotation parameters including the document ID and fields to update.
+     * @param BaseAnnotationParameters<T> $params Annotation parameters including the document ID and fields to update.
      * @return T
      */
     public function updateRagAnnotation(
-        string $responseClass,
         BaseAnnotationParameters $params
     ): BaseRagAnnotationResponse {
-        return $this->mindeeApi->reqPatchRagAnnotation($responseClass, $params);
+        return $this->mindeeApi->reqPatchRagAnnotation($params);
     }
 
     /**
@@ -280,27 +275,29 @@ public function searchModels(?string $modelName = null, ?string $modelType = nul
      * Add a document to the RAG database and return the initial annotation.
      *
      * @template T of BaseRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
      * @param LocalInputSource $inputSource Local file to upload.
-     * @param RagDocumentUploadParameters $params Upload parameters.
+     * @param BaseRagDocumentUploadParameters<T> $params Upload parameters.
      * @param PollingOptions|null $pollingOptions Options to apply to the polling.
      * @param CancellationToken|null $cancellationToken CancellationToken to check for cancellation.
      * @return T
      * @throws MindeeException Throws if upload fails or polling times out.
      */
     public function uploadAndGetRagDocumentPoll(
-        string $responseClass,
         LocalInputSource $inputSource,
-        RagDocumentUploadParameters $params,
+        BaseRagDocumentUploadParameters $params,
         ?PollingOptions $pollingOptions = null,
         ?CancellationToken $cancellationToken = null
     ): BaseRagAnnotationResponse {
         if (!$pollingOptions) {
             $pollingOptions = new PollingOptions();
         }
-        $initialResponse = $this->uploadRagDocument($responseClass, $inputSource, $params);
-        return $this->pollForRagDocument($responseClass, $initialResponse, $pollingOptions, $cancellationToken);
+        $initialResponse = $this->uploadRagDocument($inputSource, $params);
+        return $this->pollForRagDocument(
+            $params->getResponseClass(),
+            $initialResponse,
+            $pollingOptions,
+            $cancellationToken
+        );
     }
 
     /**
@@ -335,28 +332,30 @@ public function getReadyRagDocumentPoll(
      * Update a document's annotations in the RAG database.
      *
      * @template T of ExtractionRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
-     * @param BaseAnnotationParameters $params Annotation parameters including the document ID and fields to update.
+     * @param BaseAnnotationParameters<T> $params Annotation parameters including the document ID and fields to update.
      * @param PollingOptions|null $pollingOptions Options to apply to the polling.
      * @param CancellationToken|null $cancellationToken CancellationToken to check for cancellation.
      * @throws MindeeException Throws if polling times out.
      */
     public function updateAndGetRagAnnotationPoll(
-        string $responseClass,
         BaseAnnotationParameters $params,
         ?PollingOptions $pollingOptions = null,
         ?CancellationToken $cancellationToken = null
     ): BaseRagAnnotationResponse {
         error_log("Updating RAG document ID: " . $params->documentId);
-        $initialResponse = $this->updateRagAnnotation($responseClass, $params);
+        $initialResponse = $this->updateRagAnnotation($params);
         if ($initialResponse->status !== "Processing") {
             return $initialResponse;
         }
         if (!$pollingOptions) {
             $pollingOptions = new PollingOptions();
         }
-        return $this->pollForRagDocument($responseClass, $initialResponse, $pollingOptions, $cancellationToken);
+        return $this->pollForRagDocument(
+            $params->getResponseClass(),
+            $initialResponse,
+            $pollingOptions,
+            $cancellationToken
+        );
     }
 
     /**

src/V2/ClientOptions/BaseAnnotationParameters.php

@@ -4,17 +4,36 @@
 
 namespace Mindee\V2\ClientOptions;
 
+use Mindee\V2\Parsing\BaseRagAnnotationResponse;
+
 /**
  * Base parameters for annotation operations.
+ * @template TAnnotationResponse of BaseRagAnnotationResponse
  */
 abstract class BaseAnnotationParameters
 {
     /**
-     * @param string $documentId Unique identifier of the document to annotate.
+     * @var class-string<TAnnotationResponse> $responseClass Response class.
+     */
+    protected static string $responseClass;
+
+    /**
+     * @param string $documentId UUID of the annotated document.
      */
     public function __construct(public readonly string $documentId) {}
 
     /**
+     * Gets the response class associated with the parameters.
+     *
+     * @return class-string<TAnnotationResponse> Response class.
+     */
+    public function getResponseClass(): string
+    {
+        return static::$responseClass;
+    }
+
+    /**
+     * Gets the request parameters for the upload request.
      * @return array<string, mixed> Request parameters.
      */
     abstract public function getRequestParameters(): array;

src/V2/ClientOptions/BaseProductParameters.php

@@ -42,9 +42,10 @@ public function __construct(public string $modelId, ?string $alias, ?array $webh
     }
 
     /**
-     * @return array<string, string> Hash representation.
+     * Gets the request parameters for the enqueue request.
+     * @return array<string, string> Request parameters.
      */
-    public function asHash(): array
+    public function getRequestParameters(): array
     {
         $outHash = ['model_id' => $this->modelId];
         if (isset($this->alias)) {

src/V2/ClientOptions/BaseRagDocumentUploadParameters.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\ClientOptions;
+
+use InvalidArgumentException;
+use Mindee\V2\Parsing\BaseRagAnnotationResponse;
+
+/**
+ *  Base parameters for annotation operations.
+ * @template TAnnotationResponse of BaseRagAnnotationResponse
+ */
+abstract class BaseRagDocumentUploadParameters
+{
+    /**
+     * @var class-string<TAnnotationResponse> $responseClass Response class.
+     */
+    protected static string $responseClass;
+
+    /**
+     * @param string $modelId UUID of the extraction model that the uploaded RAG document is linked to.
+     */
+    public function __construct(public readonly string $modelId) {}
+
+    /**
+     * Gets the response class associated with the parameters.
+     *
+     * @return class-string<TAnnotationResponse> Response class.
+     */
+    public function getResponseClass(): string
+    {
+        return static::$responseClass;
+    }
+
+    /**
+     * Gets the request parameters for the upload request.
+     * @return array<string, string> Request parameters.
+     */
+    public function getRequestParameters(): array
+    {
+        if (empty($this->modelId)) {
+            throw new InvalidArgumentException("ModelId is required in RagDocumentsParameters");
+        }
+
+        return ['model_id' => $this->modelId];
+    }
+}

src/V2/Http/MindeeApiV2.php

@@ -19,6 +19,7 @@
 use Mindee\Input\UrlInputSource;
 use Mindee\V2\ClientOptions\BaseAnnotationParameters;
 use Mindee\V2\ClientOptions\BaseProductParameters;
+use Mindee\V2\ClientOptions\BaseRagDocumentUploadParameters;
 use Mindee\V2\ClientOptions\BaseSearchParameters;
 use Mindee\V2\Error\MindeeV2HttpException;
 use Mindee\V2\Error\MindeeV2HttpUnknownException;
@@ -337,7 +338,7 @@ private function documentEnqueuePost(
         BaseProductParameters $params
     ): array {
         $ch = $this->initChannel();
-        $postFields = $params->asHash();
+        $postFields = $params->getRequestParameters();
 
         if ($inputSource instanceof UrlInputSource) {
             $postFields['url'] = $inputSource->url;
@@ -384,17 +385,14 @@ private function checkValidResponse(array $result): void
      * Uploads a local document to the RAG database.
      *
      * @template T of BaseRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
      * @param LocalInputSource $inputSource Local file to upload.
-     * @param RagDocumentUploadParameters $params Upload parameters.
+     * @param BaseRagDocumentUploadParameters<T> $params Upload parameters.
      * @return T
      * @throws MindeeException Throws if the cURL operation fails.
      */
     public function reqPostRagDocument(
-        string $responseClass,
         LocalInputSource $inputSource,
-        RagDocumentUploadParameters $params
+        BaseRagDocumentUploadParameters $params
     ): BaseRagAnnotationResponse {
         $ch = $this->initChannel();
         $postFields = $params->getRequestParameters();
@@ -418,7 +416,7 @@ public function reqPostRagDocument(
         }
 
         /** @var T $response */
-        $response = $this->deserializeResponse($responseClass, $resp);
+        $response = $this->deserializeResponse($params->getResponseClass(), $resp);
         return $response;
     }
 
@@ -490,19 +488,16 @@ public function reqGetRagAnnotation(string $responseClass, string $documentId):
      * Updates a RAG document annotation using the provided parameters.
      *
      * @template T of BaseRagAnnotationResponse
-     * @param string $responseClass The response class to construct.
-     * @phpstan-param class-string<T> $responseClass
-     * @param BaseAnnotationParameters $params Annotation parameters including the document ID and fields to update.
+     * @param BaseAnnotationParameters<T> $params Annotation parameters including the document ID and fields to update.
      * @return T
      */
     public function reqPatchRagAnnotation(
-        string $responseClass,
         BaseAnnotationParameters $params
     ): BaseRagAnnotationResponse {
         $url = $this->baseUrl . "/v2/products/extraction/rag-documents/{$params->documentId}";
         $response = $this->sendPatchRequest($url, $params->getRequestParameters());
         /** @var T $result */
-        $result = $this->deserializeResponse($responseClass, $response);
+        $result = $this->deserializeResponse($params->getResponseClass(), $response);
         return $result;
     }
 

src/V2/Product/Extraction/Params/ExtractionParameters.php

@@ -65,9 +65,9 @@ public function __construct(
     /**
      * @return array<string, integer|float|string|bool|null|array<mixed>> Hash representation.
      */
-    public function asHash(): array
+    public function getRequestParameters(): array
     {
-        $outHash = parent::asHash();
+        $outHash = parent::getRequestParameters();
         if (isset($this->rag)) {
             $outHash['rag'] = $this->rag ? 'true' : 'false';
         }

src/V2/Product/Extraction/RagDocuments/Params/RagDocumentAnnotationParameters.php

@@ -7,13 +7,15 @@
 use InvalidArgumentException;
 use Mindee\Error\MindeeInputException;
 use Mindee\V2\ClientOptions\BaseAnnotationParameters;
+use Mindee\V2\Product\Extraction\RagDocuments\ExtractionRagAnnotationResponse;
 use Mindee\V2\Product\Extraction\RagDocuments\RagAnnotation;
 
 use function is_array;
 use function is_string;
 
 /**
  * Annotation parameters for RAG documents.
+ * @extends BaseAnnotationParameters<ExtractionRagAnnotationResponse>
  */
 class RagDocumentAnnotationParameters extends BaseAnnotationParameters
 {
@@ -22,6 +24,11 @@ class RagDocumentAnnotationParameters extends BaseAnnotationParameters
      */
     public ?RagAnnotation $annotation;
 
+    /**
+     * @var class-string<ExtractionRagAnnotationResponse> Response class.
+     */
+    protected static string $responseClass = ExtractionRagAnnotationResponse::class;
+
     /**
      * @param string $documentId Unique identifier of the document.
      * @param string|null $status New public status to apply to the document.

src/V2/Product/Extraction/RagDocuments/Params/RagDocumentUploadParameters.php

@@ -4,28 +4,17 @@
 
 namespace Mindee\V2\Product\Extraction\RagDocuments\Params;
 
-use InvalidArgumentException;
+use Mindee\V2\ClientOptions\BaseRagDocumentUploadParameters;
+use Mindee\V2\Product\Extraction\RagDocuments\ExtractionRagAnnotationResponse;
 
 /**
  * Upload parameters for RAG documents.
+ * @extends BaseRagDocumentUploadParameters<ExtractionRagAnnotationResponse>
  */
-class RagDocumentUploadParameters
+class RagDocumentUploadParameters extends BaseRagDocumentUploadParameters
 {
     /**
-     * @param string $modelId UUID of the extraction model that the uploaded RAG document is linked to.
+     * @var class-string<ExtractionRagAnnotationResponse> Response class.
      */
-    public function __construct(public readonly string $modelId) {}
-
-    /**
-     * @return array<string, string> Request parameters.
-     * @throws InvalidArgumentException Throws if the model ID is missing.
-     */
-    public function getRequestParameters(): array
-    {
-        if (empty($this->modelId)) {
-            throw new InvalidArgumentException("ModelId is required in RagDocumentsParameters");
-        }
-
-        return ['model_id' => $this->modelId];
-    }
+    protected static string $responseClass = ExtractionRagAnnotationResponse::class;
 }

tests/V2/ClientOptions/BaseProductParametersTest.php

@@ -15,7 +15,7 @@ public function testAsHashShouldSerializeMultipleWebhookIdsAsIndexedFields(): vo
             public static string $slug = 'test';
         };
 
-        $hash = $params->asHash();
+        $hash = $params->getRequestParameters();
 
         self::assertArrayHasKey('model_id', $hash);
         self::assertArrayHasKey('webhook_ids', $hash);

tests/V2/Product/Extraction/RagDocumentsFunctional.php

@@ -37,7 +37,6 @@ public function testRagDocumentLifecycleMustSucceed(): void
         $parameters = new RagDocumentUploadParameters(modelId: $this->extractionModelId);
 
         $postResponse = $this->client->uploadAndGetRagDocumentPoll(
-            ExtractionRagAnnotationResponse::class,
             $inputSource,
             $parameters
         );
@@ -57,7 +56,6 @@ public function testRagDocumentLifecycleMustSucceed(): void
         $postAnnotation->fields->getSimpleField('invoice_number')->guidelines = "koo koo katchoo!";
 
         $patchAnnotationResponse = $this->client->updateRagAnnotation(
-            ExtractionRagAnnotationResponse::class,
             new RagDocumentAnnotationParameters(
                 documentId: $documentId,
                 annotation: $postAnnotation
@@ -98,7 +96,6 @@ public function testRagDocumentLifecycleMustSucceed(): void
         self::assertTrue($getAnnotation->fields->getSimpleField('invoice_number')->selected);
 
         $patchStatusResponse = $this->client->updateRagAnnotation(
-            ExtractionRagAnnotationResponse::class,
             new RagDocumentAnnotationParameters(
                 documentId: $documentId,
                 status: "Active"