♻️ cleanup and uniformize RAG search implementation with other SDKs

.pylintrc

@@ -120,7 +120,7 @@ argument-naming-style=snake_case
 # Regular expression matching correct argument names. Overrides argument-
 # naming-style. If left empty, argument names will be checked with the set
 # naming style.
-#argument-rgx=
+argument-rgx=[a-z_][a-z0-9_]{2,}$
 
 # Naming style matching correct attribute names.
 attr-naming-style=snake_case
@@ -189,6 +189,7 @@ function-naming-style=snake_case
 good-names=i,
            j,
            k,
+           e,
            ex,
            Run,
            _
@@ -249,7 +250,7 @@ variable-naming-style=snake_case
 # Regular expression matching correct variable names. Overrides variable-
 # naming-style. If left empty, variable names will be checked with the set
 # naming style.
-#variable-rgx=
+variable-rgx=[a-z_][a-z0-9_]{2,}$
 
 
 [CLASSES]

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

@@ -9,32 +9,18 @@
 
 
 def _find_v1_dashv_boundary(argv: list[str]) -> int | None:
-    """Locate the position after which ``-v`` belongs to V1 ``custom`` /
-    ``generated``.
-
-    These two V1 products register ``-v/--version``; tokens at or beyond
-    the returned index must be left alone by the verbose pre-scan.
-    """
+    """Find the index after which -v means --version for V1 custom/generated."""
     for i, token in enumerate(argv):
         if token == "v1" and i + 1 < len(argv) and argv[i + 1] in _V1_DASHV_PRODUCTS:
             return i + 2
     return None
 
 
 def _extract_verbose_level(argv: list[str]) -> tuple[int, list[str]]:
-    """Pre-scan ``argv`` for ``--verbose`` / ``-v`` flags.
-
-    Mirrors ``mindee-api-dotnet``'s ``args.Contains("--verbose")`` check:
-    the flag is consumed before argparse runs so it can appear anywhere
-    on the command line.
-
-    * ``--verbose`` is consumed at any position (no conflict).
-    * ``-v`` is consumed at any position *except* after a ``v1 custom``
-      or ``v1 generated`` invocation, where it is the V1 product's own
-      ``--version`` option.
+    """
+    Consume --verbose / -v flags before argparse runs.
 
-    :returns: ``(level, remaining_argv)`` where ``level`` counts the number
-        of recognized verbose-flag occurrences.
+    :return: The verbose level and the remaining arguments.
     """
     level = 0
     remaining: list[str] = []
@@ -51,7 +37,7 @@ def _extract_verbose_level(argv: list[str]) -> tuple[int, list[str]]:
 
 
 def _configure_logging(verbose_level: int) -> None:
-    """Set the ``mindee`` logger level based on the verbose count."""
+    """Set the Mindee logger level based on the verbose count."""
     if verbose_level <= 0:
         return
     target = logging.INFO if verbose_level == 1 else logging.DEBUG
@@ -60,16 +46,7 @@ def _configure_logging(verbose_level: int) -> None:
 
 
 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.
-
-    Pass ``--verbose`` (or ``-v``) to enable diagnostic logging; repeat
-    the flag (``--verbose --verbose``) for debug-level output.
-    """
+    """Run the Command Line Interface."""
 
     stdout = cast(io.TextIOWrapper, sys.stdout)
     stdout_encoding = str(stdout.encoding)

mindee/pdf/pdf_utils.py

@@ -117,8 +117,8 @@ def _process_char(
 
     adjusted_box = _adjust_char_box(char_box, rotation, internal_height, internal_width)
     char_data_list: list[PDFCharData] = []
-    for c in char_info["char"] or " ":
-        if c in (
+    for char in char_info["char"] or " ":
+        if char in (
             "\n",
             "\r",
         ):  # Removes duplicated carriage returns in the PDF due to weird extraction.
@@ -129,7 +129,7 @@ def _process_char(
 
         char_data_list.append(
             PDFCharData(
-                char=c,
+                char=char,
                 left=int(adjusted_box[0]),
                 right=int(adjusted_box[1]),
                 top=int(adjusted_box[2]),
@@ -288,13 +288,13 @@ def _adjust_char_box(
     return left, right, top, bottom
 
 
-def lerp(start: float, end: float, t: float) -> float:
+def lerp(start: float, end: float, factor: float) -> float:
     """
     Performs linear interpolation between two numbers.
 
     :param start: The starting value.
     :param end: The ending value.
-    :param t: The interpolation factor (0 to 1).
+    :param factor: The interpolation factor (0 to 1).
     :return: The interpolated value.
     """
-    return start * (1 - t) + end * t
+    return start * (1 - factor) + end * factor

mindee/v1/commands/cli_parser.py

@@ -105,10 +105,7 @@ def add_custom_options(self) -> None:
 
 def register_v1_product_subparsers(parser: ArgumentParser) -> None:
     """
-    Register V1 product subparsers under the given ``parser``.
-
-    Used both by the legacy ``mindee`` binary and by the ``v1`` group of
-    the unified ``mindeeV2`` CLI.
+    Register V1 product subparsers under the given parser.
     """
     parse_product_subparsers = parser.add_subparsers(
         dest="product_name",

mindee/v2/client.py

@@ -1,3 +1,4 @@
+import warnings
 from time import sleep
 from typing import TypeVar
 
@@ -189,6 +190,11 @@ def search_models(
         """
         Deprecated. Use `search` instead.
         """
+        warnings.warn(
+            "search_models is deprecated, use search instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.mindee_api.req_get_search_models(name, model_type)
 
     def close(self) -> None:

mindee/v2/client_options/base_search_parameters.py

@@ -32,8 +32,12 @@ 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 <= 0:
+                raise ValueError("page must be a positive integer")
             data["page"] = str(self.page)
         if self.per_page is not None:
+            if self.per_page <= 0:
+                raise ValueError("per_page must be a positive integer")
             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/base_inference_command.py

@@ -16,24 +16,13 @@
 
 
 class BaseInferenceCommand:
-    """Abstract base class for V2 inference CLI commands.
-
-    Owns the options shared by every V2 inference product
-    (``path``, ``--model-id``, ``--api-key``, ``--alias``, ``--output``),
-    the input-source resolution, the client invocation, and the output
-    formatting. Each concrete subclass owns its own product-specific
-    options, builds the right :class:`BaseParameters` instance, and may
-    customize the human-readable output.
-
-    Mirrors the canonical PHP implementation in
-    ``mindee-api-php/bin/V2/BaseInferenceCommand.php``.
-    """
+    """Abstract base class for V2 inference CLI commands."""
 
     name: str
     """Name of the subcommand (also used as product key)."""
 
     description: str
-    """Human-readable description shown in ``--help``."""
+    """Human-readable description shown in the help."""
 
     def register(self, subparsers: _SubParsersAction) -> ArgumentParser:
         """Register this command on the given subparsers action."""
@@ -92,19 +81,14 @@ def register(self, subparsers: _SubParsersAction) -> ArgumentParser:
         return parser
 
     def configure_product_options(self, parser: ArgumentParser) -> None:
-        """Hook for subclasses to add product-specific options.
-
-        No-op by default. Override (for example in
-        :class:`~mindee.v2.commands.extraction_command.ExtractionCommand`)
-        to add flags only relevant to a single product.
-        """
+        """Hook for subclasses to add product-specific options."""
 
     def execute(
         self,
         parsed_args: Namespace,
         client_factory: Callable[[str | None], Client],
     ) -> int:
-        """Run the inference for ``parsed_args`` using ``client_factory``."""
+        """Run the inference and print the result."""
         api_key = getattr(parsed_args, "api_key", None)
         model_id = parsed_args.model_id
         webhook_ids = getattr(parsed_args, "webhook_ids", None)
@@ -152,11 +136,7 @@ def get_summary(self, response) -> str:
         return str(inference.result)
 
     def get_full_output(self, parsed_args: Namespace, response) -> str:
-        """Detailed representation of an inference response.
-
-        Defaults to the full inference dump; override to add
-        product-specific sections (raw text, RAG, ...).
-        """
+        """Detailed representation of an inference response."""
         del parsed_args
         inference = getattr(response, "inference", None)
         if inference is None: