Issue 248: optimized the DeprecationWarning (#397)

* del: actual deprecation implemented

Author: XiandaDu

src/rank_llm/rerank/listwise/rank_gemini.py

@@ -1,5 +1,4 @@
 import time
-from importlib.resources import files
 from typing import Any
 
 from tqdm import tqdm
@@ -32,9 +31,6 @@ def populate_generation_config(**kwargs) -> dict[str, Any]:
     return generation_config
 
 
-TEMPLATES = files("rank_llm.rerank.prompt_templates")
-
-
 class SafeGenai(ListwiseRankLLM):
     def __init__(
         self,
@@ -52,15 +48,6 @@ def __init__(
         max_passage_words: int = 300,
         **kwargs,
     ):
-        if not prompt_template_path:
-            if prompt_mode == PromptMode.RANK_GPT_APEER:
-                prompt_template_path = TEMPLATES / "rank_gpt_apeer_template.yaml"
-            elif prompt_mode == PromptMode.RANK_GPT:
-                prompt_template_path = TEMPLATES / "rank_zephyr_template.yaml"
-            else:
-                raise ValueError(
-                    "Either `prompt_mode` or `prompt_template_path` must be specified."
-                )
         super().__init__(
             model=model,
             context_size=context_size,
@@ -82,13 +69,6 @@ def __init__(
             keys = [keys]
         if not keys:
             raise ValueError("Please provide Genai API Keys.")
-        if prompt_mode and prompt_mode not in [
-            PromptMode.RANK_GPT_APEER,
-            PromptMode.RANK_GPT,
-        ]:
-            raise ValueError(
-                f"unsupported prompt mode for GEMINI models: {prompt_mode}, expected {PromptMode.RANK_GPT_APEER} or {PromptMode.RANK_GPT}."
-            )
         self._output_token_estimate = None
         self._keys = keys
         self._cur_key_id = key_start_id or 0

src/rank_llm/rerank/listwise/rank_gpt.py

@@ -1,7 +1,6 @@
 import asyncio
 import time
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from importlib.resources import files
 from typing import Any
 
 from tqdm import tqdm
@@ -22,8 +21,6 @@
 except ImportError:
     tiktoken = None
 
-TEMPLATES = files("rank_llm.rerank.prompt_templates")
-
 
 class SafeOpenai(ListwiseRankLLM):
     def __init__(
@@ -54,8 +51,8 @@ def __init__(
         Parameters:
         - model (str): The model identifier for the LLM (model identifier information can be found via OpenAI's model lists).
         - context_size (int): The maximum number of tokens that the model can handle in a single request.
-        - prompt_mode (PromptMode, optional): Specifies the mode of prompt generation, with the default set to RANK_GPT,
-         indicating that this class is designed primarily for listwise ranking tasks following the RANK_GPT methodology.
+        - prompt_mode (PromptMode, optional): Deprecated and ignored. Prompt behavior is driven by the YAML
+         template at prompt_template_path; passing prompt_mode only emits a deprecation warning.
         - num_few_shot_examples (int, optional): Number of few-shot learning examples to include in the prompt, allowing for
         the integration of example-based learning to improve model performance. Defaults to 0, indicating no few-shot examples
         by default.
@@ -70,7 +67,7 @@ def __init__(
         - api_version (str, optional): The API version, necessary for Azure AI integration.
 
         Raises:
-        - ValueError: If an unsupported prompt mode is provided or if no OpenAI API keys / invalid OpenAI API keys are supplied.
+        - ValueError: If no prompt_template_path is provided or if no OpenAI API keys / invalid OpenAI API keys are supplied.
 
         Note:
         - This class supports cycling between multiple OpenAI API keys to distribute quota usage or handle rate limiting.
@@ -86,26 +83,6 @@ def __init__(
         if not keys:
             raise ValueError("Please provide OpenAI Keys.")
 
-        if prompt_mode and prompt_mode not in [
-            PromptMode.RANK_GPT,
-            PromptMode.RANK_GPT_APEER,
-            PromptMode.LRL,
-        ]:
-            raise ValueError(
-                f"unsupported prompt mode for GPT models: {prompt_mode}, expected {PromptMode.RANK_GPT}, {PromptMode.RANK_GPT_APEER} or {PromptMode.LRL}."
-            )
-
-        if prompt_template_path is None:
-            if prompt_mode == PromptMode.RANK_GPT:
-                prompt_template_path = TEMPLATES / "rank_gpt_template.yaml"
-            elif prompt_mode == PromptMode.RANK_GPT_APEER:
-                prompt_template_path = TEMPLATES / "rank_gpt_apeer_template.yaml"
-            elif prompt_mode == PromptMode.LRL:
-                prompt_template_path = TEMPLATES / "rank_lrl_template.yaml"
-            else:
-                raise ValueError(
-                    "Either `prompt_mode` or `prompt_template_path` must be specified."
-                )
         super().__init__(
             model=model,
             context_size=context_size,

src/rank_llm/rerank/listwise/rank_listwise_os_llm.py

@@ -80,8 +80,8 @@ def __init__(
          Parameters:
          - model (str): Identifier for the language model to be used for ranking tasks.
          - context_size (int, optional): Maximum number of tokens that can be handled in a single prompt. Defaults to 4096.
-         - prompt_mode (PromptMode, optional): Specifies the mode of prompt generation, with the default set to RANK_GPT,
-         indicating that this class is designed primarily for listwise ranking tasks following the RANK_GPT methodology.
+         - prompt_mode (PromptMode, optional): Deprecated and ignored. Prompt behavior is driven by the YAML
+         template at prompt_template_path; passing prompt_mode only emits a deprecation warning.
          - num_few_shot_examples (int, optional): Number of few-shot learning examples to include in the prompt, allowing for
          the integration of example-based learning to improve model performance. Defaults to 0, indicating no few-shot examples
          by default.
@@ -102,7 +102,7 @@ def __init__(
 
          Raises:
          - AssertionError: If CUDA is specified as the device but is not available on the system.
-         - ValueError: If an unsupported prompt mode is provided.
+         - ValueError: If no prompt_template_path is provided and no default applies.
          - ValueError: If num_few_shot_examples > 0 but no valid file path is provided
 
          Note:
@@ -151,10 +151,6 @@ def __init__(
                     "Open-source listwise reranking with local backends requires PyTorch.",
                 )
             assert torch.cuda.is_available() and torch.cuda.device_count() >= num_gpus
-        if prompt_mode and prompt_mode != PromptMode.RANK_GPT:
-            raise ValueError(
-                f"Unsupported prompt mode: {prompt_mode}. The only prompt mode currently supported is a slight variation of {PromptMode.RANK_GPT} prompt."
-            )
 
         if sglang_batched:
             if Engine is None:

src/rank_llm/rerank/listwise/rank_litellm.py

@@ -1,6 +1,5 @@
 import asyncio
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from importlib.resources import files
 from typing import Any
 
 from tqdm import tqdm
@@ -16,8 +15,6 @@
 except ImportError:
     litellm = None
 
-TEMPLATES = files("rank_llm.rerank.prompt_templates")
-
 
 class SafeLiteLLM(ListwiseRankLLM):
     """Listwise reranker using LiteLLM for 100+ LLM providers.
@@ -55,28 +52,6 @@ def __init__(
                 "The LiteLLM reranker requires the litellm package.",
             )
 
-        if prompt_mode and prompt_mode not in [
-            PromptMode.RANK_GPT,
-            PromptMode.RANK_GPT_APEER,
-            PromptMode.LRL,
-        ]:
-            raise ValueError(
-                f"unsupported prompt mode for LiteLLM: {prompt_mode}, "
-                f"expected {PromptMode.RANK_GPT}, {PromptMode.RANK_GPT_APEER} or {PromptMode.LRL}."
-            )
-
-        if prompt_template_path is None:
-            if prompt_mode == PromptMode.RANK_GPT:
-                prompt_template_path = TEMPLATES / "rank_gpt_template.yaml"
-            elif prompt_mode == PromptMode.RANK_GPT_APEER:
-                prompt_template_path = TEMPLATES / "rank_gpt_apeer_template.yaml"
-            elif prompt_mode == PromptMode.LRL:
-                prompt_template_path = TEMPLATES / "rank_lrl_template.yaml"
-            else:
-                raise ValueError(
-                    "Either `prompt_mode` or `prompt_template_path` must be specified."
-                )
-
         super().__init__(
             model=model,
             context_size=context_size,

src/rank_llm/rerank/rankllm.py

@@ -2,6 +2,7 @@
 import json
 import logging
 import os
+import warnings
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Any
@@ -45,8 +46,21 @@ def __init__(
         self._few_shot_file = few_shot_file
 
         if prompt_mode:
-            print(
-                "PromptMode is deprecated and will be removed in v0.30.0. Please use the prompt_template_path argument with a valid template file instead."
+            warnings.warn(
+                "PromptMode is deprecated and will be removed in v0.30.0. "
+                "It is ignored: prompt behavior is now driven by YAML templates. "
+                "Please use the prompt_template_path argument with a valid YAML "
+                "template instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if not prompt_template_path:
+            raise ValueError(
+                "A YAML prompt template is required: pass prompt_template_path "
+                "(CLI: --prompt-template-path) pointing to a template under "
+                "src/rank_llm/rerank/prompt_templates/. The legacy prompt_mode "
+                "argument no longer selects a template."
             )
 
         try:

src/rank_llm/scripts/run_rank_llm.py

@@ -2,6 +2,7 @@
 
 import argparse
 import os
+import warnings
 from collections.abc import Sequence
 
 from rank_llm.cli.legacy import namespace_to_legacy_argv, translate_legacy_argv
@@ -10,18 +11,48 @@
 # Force spawn method to avoid "Cannot re-initialize CUDA in forked subprocess" error.
 os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
 
+# Flags accepted for backwards compatibility but not forwarded to the new CLI.
 _DROP_FLAGS = {"prompt_mode"}
 
+_PROMPT_MODE_DEPRECATION = (
+    "The --prompt_mode CLI flag is deprecated and will be removed in v0.30.0. "
+    "It is now ignored: prompt behavior is driven by YAML templates. "
+    "Pass --prompt-template-path pointing to a template under "
+    "src/rank_llm/rerank/prompt_templates/ instead "
+    "(see `rank-llm prompt --help` to list the available templates)."
+)
+
+
+def _warn_if_prompt_mode_present(args: argparse.Namespace | Sequence[str]) -> None:
+    """Emit a deprecation warning if the legacy --prompt_mode flag was supplied.
+
+    The flag is still accepted so old invocations do not break, but it no longer
+    affects behavior; YAML prompt templates replace it.
+    """
+    if isinstance(args, argparse.Namespace):
+        present = getattr(args, "prompt_mode", None) is not None
+    else:
+        present = any(
+            token in ("--prompt_mode", "--prompt-mode")
+            or token.startswith(("--prompt_mode=", "--prompt-mode="))
+            for token in args
+        )
+    if present:
+        warnings.warn(_PROMPT_MODE_DEPRECATION, DeprecationWarning, stacklevel=3)
+
 
 def main(args: argparse.Namespace | Sequence[str] | None = None) -> int:
     if isinstance(args, argparse.Namespace):
+        _warn_if_prompt_mode_present(args)
         argv = namespace_to_legacy_argv(args, drop_flags=_DROP_FLAGS)
     elif args is None:
         import sys
 
         argv = sys.argv[1:]
+        _warn_if_prompt_mode_present(argv)
     else:
         argv = list(args)
+        _warn_if_prompt_mode_present(argv)
 
     translated = translate_legacy_argv(argv, drop_flags=_DROP_FLAGS)
     return cli_main(["rerank", *translated])