✨ add RAG search API

bin/V2/SearchModelsCommand.php

@@ -6,6 +6,7 @@
 
 use Exception;
 use Mindee\V2\Client;
+use Mindee\V2\ClientOptions\ModelSearchParameters;
 use Mindee\V2\Error\MindeeV2HttpException;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
@@ -83,7 +84,9 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $client = new Client($apiKey ?: null);
 
         try {
-            $response = $client->searchModels($name ?: null, $modelType ?: null);
+            $response = $client->searchModels(
+                new ModelSearchParameters($name ?: null, $modelType ?: null)
+            );
         } catch (MindeeV2HttpException $e) {
             $output->writeln('<error>' . $e->getMessage() . '</error>');
             return Command::FAILURE;

bin/V2/SearchRagDocumentsCommand.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\Cli\V2;
+
+use Exception;
+use Mindee\V2\Client;
+use Mindee\V2\ClientOptions\RagDocumentSearchParameters;
+use Mindee\V2\Error\MindeeV2HttpException;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * V2 `search-rag-docs` CLI command.
+ *
+ * Mirrors the canonical .NET implementation in
+ * `mindee-api-dotnet/src/Mindee.Cli/Commands/V2/SearchRagDocumentsCommand.cs`.
+ */
+class SearchRagDocumentsCommand extends Command
+{
+    /**
+     * @return void Configure command options/arguments.
+     */
+    protected function configure(): void
+    {
+        $this
+            ->setName('search-rag-docs')
+            ->setDescription('Search available RAG documents for a given model.')
+            ->addOption(
+                'api-key',
+                'k',
+                InputOption::VALUE_REQUIRED,
+                'Mindee V2 API key. Falls back to the MINDEE_V2_API_KEY environment variable.'
+            )
+            ->addOption(
+                'model-id',
+                'm',
+                InputOption::VALUE_REQUIRED,
+                'Filter by model ID.'
+            )
+            ->addOption(
+                'filename',
+                'f',
+                InputOption::VALUE_REQUIRED,
+                'Filter by file name partial match (case insensitive).'
+            )
+            ->addOption(
+                'raw-json',
+                'r',
+                InputOption::VALUE_NONE,
+                'Whether to output the raw JSON response.'
+            );
+    }
+
+    /**
+     * @param InputInterface $input CLI input.
+     * @param OutputInterface $output CLI output.
+     * @return integer Exit code.
+     */
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $apiKey = $input->getOption('api-key');
+        if (!$apiKey && !getenv('MINDEE_V2_API_KEY')) {
+            $output->writeln(
+                '<error>The Mindee V2 API key is missing. '
+                . "Please provide it via the '--api-key' option or the MINDEE_V2_API_KEY environment variable.</error>"
+            );
+            return Command::FAILURE;
+        }
+
+        $modelId = $input->getOption('model-id');
+        if (!$modelId) {
+            $output->writeln('<error>The --model-id option is required.</error>');
+            return Command::FAILURE;
+        }
+        $filename = $input->getOption('filename');
+        $raw = (bool) $input->getOption('raw-json');
+
+        $client = new Client($apiKey ?: null);
+
+        try {
+            $response = $client->searchRagDocuments(
+                new RagDocumentSearchParameters($modelId, $filename ?: null)
+            );
+        } catch (MindeeV2HttpException $e) {
+            $output->writeln('<error>' . $e->getMessage() . '</error>');
+            return Command::FAILURE;
+        } catch (Exception $e) {
+            $output->writeln("<error>Something went wrong, '" . $e->getMessage() . "' was raised.</error>");
+            return Command::FAILURE;
+        }
+
+        if ($raw) {
+            $output->writeln($response->getRawHttp());
+        } else {
+            $output->write((string) $response);
+        }
+        return Command::SUCCESS;
+    }
+}

bin/cli.php

@@ -15,13 +15,15 @@
 require __DIR__ . '/V2/OcrCommand.php';
 require __DIR__ . '/V2/SplitCommand.php';
 require __DIR__ . '/V2/SearchModelsCommand.php';
+require __DIR__ . '/V2/SearchRagDocumentsCommand.php';
 
 use Exception;
 use Mindee\Cli\V2\ClassificationCommand;
 use Mindee\Cli\V2\CropCommand;
 use Mindee\Cli\V2\ExtractionCommand;
 use Mindee\Cli\V2\OcrCommand;
 use Mindee\Cli\V2\SearchModelsCommand;
+use Mindee\Cli\V2\SearchRagDocumentsCommand;
 use Mindee\Cli\V2\SplitCommand;
 use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Input\ArgvInput;
@@ -139,8 +141,9 @@ function mindeeRewriteArgvForV1Compat(array $argv, array $knownTopLevelCommands)
     $cli->add($command);
 }
 $cli->add(new SearchModelsCommand());
+$cli->add(new SearchRagDocumentsCommand());
 
-$knownTopLevelCommands = ['v1', 'search-models', 'list', 'help', 'completion'];
+$knownTopLevelCommands = ['v1', 'search-models', 'search-rag-docs', 'list', 'help', 'completion'];
 foreach ($v2InferenceCommands as $command) {
     $knownTopLevelCommands[] = $command->getName();
 }

src/Parsing/DateHelper.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\Parsing;
+
+use DateTime;
+use DateTimeImmutable;
+use Exception;
+
+/**
+ * Utility class to parse date strings returned by the API.
+ */
+class DateHelper
+{
+    /**
+     * Parse a date string into a DateTime object.
+     *
+     * @param string|null $dateString Date string to parse.
+     * @return DateTime|null Parsed date, or null if empty/invalid.
+     */
+    public static function parseDate(?string $dateString): ?DateTime
+    {
+        if (empty($dateString)) {
+            return null;
+        }
+        try {
+            return new DateTime($dateString);
+        } catch (Exception) {
+            return null;
+        }
+    }
+
+    /**
+     * Parse a date string into a DateTimeImmutable object.
+     *
+     * @param string|null $dateString Date string to parse.
+     * @return DateTimeImmutable|null Parsed date, or null if empty/invalid.
+     */
+    public static function parseDateImmutable(?string $dateString): ?DateTimeImmutable
+    {
+        if (empty($dateString)) {
+            return null;
+        }
+        try {
+            return new DateTimeImmutable($dateString);
+        } catch (Exception) {
+            return null;
+        }
+    }
+}

src/V2/Client.php

@@ -10,10 +10,13 @@
 use Mindee\Http\CancellationToken;
 use Mindee\Input\InputSource;
 use Mindee\V2\ClientOptions\BaseParameters;
+use Mindee\V2\ClientOptions\ModelSearchParameters;
+use Mindee\V2\ClientOptions\RagDocumentSearchParameters;
 use Mindee\V2\Http\MindeeApiV2;
 use Mindee\V2\Parsing\Inference\BaseResponse;
 use Mindee\V2\Parsing\Job\JobResponse;
-use Mindee\V2\Parsing\Search\SearchResponse;
+use Mindee\V2\Parsing\Search\ModelSearchResponse;
+use Mindee\V2\Parsing\Search\RagDocumentSearchResponse;
 
 /**
  * Mindee Client V2.
@@ -165,13 +168,22 @@ public function enqueueAndGetResult(
     }
 
     /**
-     * Searches for a list of available models for the given API key.
-     * @param string|null $modelName Optional model name to filter by.
-     * @param string|null $modelType Optional model type to filter by.
-     * @return SearchResponse The list of models matching the criteria.
+     * Searches for a list of available models matching the given criteria.
+     * @param ModelSearchParameters|null $params Search parameters (name, model type, pagination).
+     * @return ModelSearchResponse The list of models matching the criteria.
      */
-    public function searchModels(?string $modelName = null, ?string $modelType = null): SearchResponse
+    public function searchModels(?ModelSearchParameters $params = null): ModelSearchResponse
     {
-        return $this->mindeeApi->searchModels($modelName, $modelType);
+        return $this->mindeeApi->searchModels($params ?? new ModelSearchParameters());
+    }
+
+    /**
+     * Searches for a list of RAG documents matching the given criteria.
+     * @param RagDocumentSearchParameters $params Search parameters.
+     * @return RagDocumentSearchResponse The list of RAG documents matching the criteria.
+     */
+    public function searchRagDocuments(RagDocumentSearchParameters $params): RagDocumentSearchResponse
+    {
+        return $this->mindeeApi->searchRagDocuments($params);
     }
 }

src/V2/ClientOptions/BaseSearchParameters.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\ClientOptions;
+
+/**
+ * Base parameters for searches.
+ */
+abstract class BaseSearchParameters
+{
+    /**
+     * @param integer|null $page 1-based page index.
+     * @param integer|null $perPage Number of items per page.
+     */
+    public function __construct(
+        public ?int $page = null,
+        public ?int $perPage = null
+    ) {}
+
+    /**
+     * Gets the query parameters for the search request.
+     *
+     * @return array<string, string> Query parameters.
+     */
+    public function getQueryParams(): array
+    {
+        $params = [];
+        if ($this->page !== null && $this->page > 0) {
+            $params['page'] = (string) $this->page;
+        }
+        if ($this->perPage !== null && $this->perPage > 0) {
+            $params['per_page'] = (string) $this->perPage;
+        }
+        return $params;
+    }
+}

src/V2/ClientOptions/ModelSearchParameters.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\ClientOptions;
+
+/**
+ * Search parameters for models.
+ */
+class ModelSearchParameters extends BaseSearchParameters
+{
+    /**
+     * @param string|null $name Case-insensitive search term for the model name.
+     * @param string|null $modelType Case-insensitive search term for the model type.
+     * @param integer|null $page 1-based page index.
+     * @param integer|null $perPage Number of items per page.
+     */
+    public function __construct(
+        public ?string $name = null,
+        public ?string $modelType = null,
+        ?int $page = null,
+        ?int $perPage = null
+    ) {
+        parent::__construct($page, $perPage);
+    }
+
+    /**
+     * @return array<string, string> Query parameters.
+     */
+    public function getQueryParams(): array
+    {
+        $params = parent::getQueryParams();
+        if (!empty($this->name)) {
+            $params['name'] = $this->name;
+        }
+        if (!empty($this->modelType)) {
+            $params['model_type'] = $this->modelType;
+        }
+        return $params;
+    }
+}

src/V2/ClientOptions/RagDocumentSearchParameters.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\ClientOptions;
+
+use Mindee\Error\ErrorCode;
+use Mindee\Error\MindeeException;
+
+/**
+ * Search parameters for RAG documents.
+ */
+class RagDocumentSearchParameters extends BaseSearchParameters
+{
+    /**
+     * @param string|null $modelId Model identifier to search in (required).
+     * @param string|null $filename Case-insensitive substring search on filename.
+     * @param integer|null $page 1-based page index.
+     * @param integer|null $perPage Number of items per page.
+     */
+    public function __construct(
+        public ?string $modelId = null,
+        public ?string $filename = null,
+        ?int $page = null,
+        ?int $perPage = null
+    ) {
+        parent::__construct($page, $perPage);
+    }
+
+    /**
+     * @return array<string, string> Query parameters.
+     * @throws MindeeException Throws if the model ID is not provided.
+     */
+    public function getQueryParams(): array
+    {
+        $params = parent::getQueryParams();
+        if (!empty($this->modelId)) {
+            $params['model_id'] = $this->modelId;
+        } else {
+            throw new MindeeException(
+                "ModelId is required in RagDocumentSearchParameters.",
+                ErrorCode::USER_INPUT_ERROR
+            );
+        }
+        if (!empty($this->filename)) {
+            $params['filename'] = $this->filename;
+        }
+        return $params;
+    }
+}