♻️ cleanup and uniformize RAG search implementation with other SDKs

docs/v2/client_options.rst

@@ -1,8 +1,14 @@
 V2 Client Options
 #################
 
-Base Parameters
-===============
-.. autoclass:: mindee.v2.client_options.base_parameters.BaseParameters
+Base Product Parameters
+=======================
+.. autoclass:: mindee.v2.client_options.base_product_parameters.BaseProductParameters
+    :members:
+    :inherited-members:
+
+Base Search Parameters
+======================
+.. autoclass:: mindee.v2.client_options.base_search_parameters.BaseSearchParameters
     :members:
     :inherited-members:

docs/v2/index.rst

@@ -10,6 +10,7 @@ V2 Utilities
     ./mindee_http
     ./parsing/index
     ./product/index
+    ./search
 
 
 

docs/v2/mindee_http.rst

@@ -6,9 +6,3 @@ Mindee API V2
 .. autoclass:: mindee.v2.mindee_http.mindee_api_v2.MindeeAPIV2
     :members:
     :inherited-members:
-
-Response Validation V2
-======================
-.. automodule:: mindee.v2.mindee_http.response_validation_v2
-    :members:
-    :inherited-members:

docs/v2/parsing/search.rst

@@ -28,9 +28,20 @@ Search Models
     :members:
     :inherited-members:
 
+Search RAG Document
+###################
+.. autoclass:: mindee.v2.parsing.search.search_rag_document.SearchRagDocument
+    :members:
+    :inherited-members:
+
+Search RAG Documents
+####################
+.. autoclass:: mindee.v2.parsing.search.search_rag_documents.SearchRagDocuments
+    :members:
+    :inherited-members:
+
 Search Response
 ###############
 .. autoclass:: mindee.v2.parsing.search.search_response.SearchResponse
     :members:
     :inherited-members:
-

docs/v2/search.rst

@@ -0,0 +1,26 @@
+V2 Search
+#########
+
+Model Search Parameters
+=======================
+.. autoclass:: mindee.v2.search.models.model_search_parameters.ModelSearchParameters
+    :members:
+    :inherited-members:
+
+Model Search Response
+=====================
+.. autoclass:: mindee.v2.search.models.model_search_response.ModelSearchResponse
+    :members:
+    :inherited-members:
+
+RAG Document Search Parameters
+==============================
+.. autoclass:: mindee.v2.search.rag_documents.rag_document_search_parameters.RagDocumentSearchParameters
+    :members:
+    :inherited-members:
+
+RAG Document Search Response
+============================
+.. autoclass:: mindee.v2.search.rag_documents.rag_document_search_response.RagDocumentSearchResponse
+    :members:
+    :inherited-members:

mindee/cli.py

@@ -63,9 +63,9 @@ def main() -> None:
     """Run the Command Line Interface.
 
     The unified ``mindee`` binary exposes V2 inference commands and the
-    ``search-models`` utility at the root, with all V1 product commands
-    wrapped under a ``v1`` subcommand — mirroring the canonical
-    ``mindee-api-dotnet`` CLI.
+    ``search-models`` and ``search-rag-docs`` utilities at the root, with
+    all V1 product commands wrapped under a ``v1`` subcommand — mirroring
+    the canonical ``mindee-api-dotnet`` CLI.
 
     Pass ``--verbose`` (or ``-v``) to enable diagnostic logging; repeat
     the flag (``--verbose --verbose``) for debug-level output.

mindee/v2/client_options/base_search_parameters.py

@@ -31,9 +31,9 @@ def get_request_parameters(self) -> dict[str, str | list[str]]:
         """
         data: dict[str, str | list[str]] = {}
 
-        if self.page is not None:
+        if self.page is not None and self.page > 0:
             data["page"] = str(self.page)
-        if self.per_page is not None:
+        if self.per_page is not None and self.per_page > 0:
             data["per_page"] = str(self.per_page)
 
         return data

mindee/v2/commands/__init__.py

@@ -6,6 +6,7 @@
 from mindee.v2.commands.ocr_command import OcrCommand
 from mindee.v2.commands.output_type import OutputType
 from mindee.v2.commands.search_models_command import SearchModelsCommand
+from mindee.v2.commands.search_rag_documents_command import SearchRagDocumentsCommand
 from mindee.v2.commands.split_command import SplitCommand
 
 __all__ = [
@@ -18,5 +19,6 @@
     "OcrCommand",
     "OutputType",
     "SearchModelsCommand",
+    "SearchRagDocumentsCommand",
     "SplitCommand",
 ]

mindee/v2/commands/cli_parser.py

@@ -16,6 +16,7 @@
 from mindee.v2.commands.extraction_command import ExtractionCommand
 from mindee.v2.commands.ocr_command import OcrCommand
 from mindee.v2.commands.search_models_command import SearchModelsCommand
+from mindee.v2.commands.search_rag_documents_command import SearchRagDocumentsCommand
 from mindee.v2.commands.split_command import SplitCommand
 from mindee.v2.error.mindee_api_v2_error import MindeeAPIV2Error
 
@@ -51,7 +52,7 @@ class MindeeParser:
 
     * V2 inference commands are exposed at the root level
       (``classification``, ``crop``, ``extraction``, ``ocr``, ``split``).
-    * The ``search-models`` utility is also at the root.
+    * The ``search-models`` and ``search-rag-docs`` utilities are also at the root.
     * V1 product commands are wrapped under a ``v1`` subcommand.
     """
 
@@ -60,6 +61,7 @@ class MindeeParser:
     _client_factory: Callable[[str | None], Client]
     _inference_commands: dict[str, BaseInferenceCommand]
     _search_models_command: SearchModelsCommand
+    _search_rag_documents_command: SearchRagDocumentsCommand
 
     def __init__(
         self,
@@ -76,6 +78,7 @@ def __init__(
             cmd.name: cmd for cmd in _build_inference_commands()
         }
         self._search_models_command = SearchModelsCommand()
+        self._search_rag_documents_command = SearchRagDocumentsCommand()
         if parsed_args is None:
             self._build_parser()
             self.parsed_args = self.parser.parse_args()
@@ -95,27 +98,33 @@ def call_parse(self) -> int:
             self.parser.print_help()
             return 1
         try:
-            if cmd == "v1":
-                v1_parser = V1MindeeParser(parsed_args=self.parsed_args)
-                v1_parser.call_parse()
-                return 0
-            if cmd == self._search_models_command.name:
-                return self._search_models_command.execute(
-                    self.parsed_args, self._client_factory
-                )
-            inference_command = self._inference_commands.get(cmd)
-            if inference_command is None:
-                raise ValueError(f"Unknown command: {cmd}")
-            return inference_command.execute(self.parsed_args, self._client_factory)
+            return self._execute_command(cmd)
         except MindeeAPIV2Error as exc:
             return _report_api_key_error(exc, "V2", "MINDEE_V2_API_KEY")
         except MindeeAPIError as exc:
             return _report_api_key_error(exc, "V1", "MINDEE_API_KEY")
 
+    def _execute_command(self, cmd: str) -> int:
+        """Execute a parsed subcommand."""
+        if cmd == "v1":
+            v1_parser = V1MindeeParser(parsed_args=self.parsed_args)
+            v1_parser.call_parse()
+            return 0
+        if cmd == self._search_models_command.name:
+            return self._search_models_command.execute(
+                self.parsed_args, self._client_factory
+            )
+        if cmd == self._search_rag_documents_command.name:
+            return self._search_rag_documents_command.execute(
+                self.parsed_args, self._client_factory
+            )
+
+        inference_command = self._inference_commands.get(cmd)
+        if inference_command is None:
+            raise ValueError(f"Unknown command: {cmd}")
+        return inference_command.execute(self.parsed_args, self._client_factory)
+
     def _build_parser(self) -> None:
-        # ``--verbose`` / ``-v`` are pre-consumed in ``mindee.cli.main``
-        # (mirroring the .NET ``args.Contains("--verbose")`` pattern); we
-        # still register them here for ``--help`` discoverability.
         self.parser.add_argument(
             "-v",
             "--verbose",
@@ -129,6 +138,7 @@ def _build_parser(self) -> None:
             cmd.register(subparsers)
 
         self._search_models_command.register(subparsers)
+        self._search_rag_documents_command.register(subparsers)
 
         v1_parser = subparsers.add_parser(
             "v1",

mindee/v2/commands/search_models_command.py

@@ -2,6 +2,7 @@
 from collections.abc import Callable
 
 from mindee.v2.client import Client
+from mindee.v2.search.models.model_search_parameters import ModelSearchParameters
 
 _AVAILABLE_MODEL_TYPES: list[str] = [
     "extraction",
@@ -74,9 +75,11 @@ def execute(
     ) -> int:
         """Run the search and print the result."""
         client = client_factory(getattr(parsed_args, "api_key", None))
-        response = client.search_models(
-            name=getattr(parsed_args, "name", None),
-            model_type=getattr(parsed_args, "model_type", None),
+        response = client.search(
+            ModelSearchParameters(
+                name=getattr(parsed_args, "name", None),
+                model_type=getattr(parsed_args, "model_type", None),
+            )
         )
         if getattr(parsed_args, "raw_json", False):
             print(response.raw_http)

mindee/v2/commands/search_rag_documents_command.py

@@ -0,0 +1,76 @@
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+from collections.abc import Callable
+
+from mindee.v2.client import Client
+from mindee.v2.search.rag_documents.rag_document_search_parameters import (
+    RagDocumentSearchParameters,
+)
+
+
+class SearchRagDocumentsCommand:
+    """Builder + handler for the V2 ``search-rag-docs`` subcommand.
+
+    Mirrors ``Mindee.Cli.Commands.V2.SearchRagDocumentsCommand`` from the
+    .NET SDK.
+    """
+
+    name = "search-rag-docs"
+    description = "Search available RAG documents for a given model."
+
+    def register(self, subparsers: _SubParsersAction) -> ArgumentParser:
+        """Register this command on the given subparsers action."""
+        parser = subparsers.add_parser(
+            self.name,
+            help=self.description,
+            description=self.description,
+        )
+        parser.add_argument(
+            "-k",
+            "--api-key",
+            dest="api_key",
+            help="Mindee V2 API key.",
+            required=False,
+            default=None,
+        )
+        parser.add_argument(
+            "-m",
+            "--model-id",
+            dest="model_id",
+            help="Filter by model ID",
+            required=True,
+        )
+        parser.add_argument(
+            "-f",
+            "--filename",
+            dest="filename",
+            help="Filter by file name partial match (case insensitive).",
+            required=False,
+            default=None,
+        )
+        parser.add_argument(
+            "-r",
+            "--raw-json",
+            dest="raw_json",
+            action="store_true",
+            help="Whether to output the raw JSON response.",
+        )
+        return parser
+
+    def execute(
+        self,
+        parsed_args: Namespace,
+        client_factory: Callable[[str | None], Client],
+    ) -> int:
+        """Run the search and print the result."""
+        client = client_factory(getattr(parsed_args, "api_key", None))
+        response = client.search(
+            RagDocumentSearchParameters(
+                model_id=parsed_args.model_id,
+                filename=getattr(parsed_args, "filename", None),
+            )
+        )
+        if getattr(parsed_args, "raw_json", False):
+            print(response.raw_http)
+        else:
+            print(response)
+        return 0

mindee/v2/parsing/inference/inference_active_options.py

@@ -17,25 +17,16 @@ class InferenceActiveOptions:
     """Active options for the inference."""
 
     raw_text: bool
-    """
-    Whether the Raw Text feature was activated.
-    When this feature is activated, the raw text extracted from the document is returned in the result.
-    """
+    """Extract the full text content from the document as strings, and fill the ``raw_text`` attribute."""
     polygon: bool
-    """
-    Whether the polygon feature was activated.
-    When this feature is activated, the bounding-box polygon(s) for each field is returned in the result.
-    """
+    """Calculate bounding box polygons for all fields, and fill their ``locations`` attribute."""
     confidence: bool
     """
-    Whether the confidence feature was activated.
-    When this feature is activated, a confidence score for each field is returned in the result.
+    Boost the precision and accuracy of all extractions.
+    Calculate confidence scores for all fields, and fill their ``confidence`` attribute.
     """
     rag: bool
-    """
-    Whether the Retrieval-Augmented Generation feature was activated.
-    When this feature is activated, the RAG pipeline is used to increase result accuracy.
-    """
+    """Enhance extraction accuracy with Retrieval-Augmented Generation."""
     text_context: bool
     """
     Whether the text context feature was activated.

mindee/v2/parsing/inference/rag_metadata.py

@@ -5,6 +5,7 @@ class RAGMetadata:
     """Metadata about the RAG operation."""
 
     retrieved_document_id: str | None
+    """The UUID of the matched document used during the RAG operation."""
 
     def __init__(self, raw_response: StringDict):
         self.retrieved_document_id = raw_response["retrieved_document_id"]

mindee/v2/parsing/search/base_search_response.py

@@ -9,15 +9,15 @@ class BaseSearchResponse(CommonResponse, ABC):
     """Base class for search responses."""
 
     pagination: PaginationMetadata
-    """Pagination metadata for the search results."""
+    """Pagination metadata."""
 
     def __init__(self, raw_response: StringDict) -> None:
         super().__init__(raw_response)
         self.pagination = PaginationMetadata(raw_response["pagination"])
 
     @abstractmethod
     def body_lines(self) -> list[str]:
-        """List of strings representing the search response."""
+        """Lines composing the response-specific body (header + items)."""
 
     def __str__(self) -> str:
         """

mindee/v2/parsing/search/model_webhook.py

@@ -1,5 +1,5 @@
 class ModelWebhook:
-    """Model webhook information."""
+    """Information about a model's webhook."""
 
     id: str
     """ID of the webhook."""