chore(llm): deprecate nemoguardrails.llm.params module in favor of direct parameter passing (#1471)

Author: Pouyanpi

nemoguardrails/llm/params.py

@@ -17,20 +17,48 @@
 Module for providing a context manager to temporarily adjust parameters of a language model.
 
 Also allows registration of custom parameter managers for different language model types.
+
+.. deprecated:: 0.17.0
+    This module is deprecated and will be removed in version 0.19.0.
+    Instead of using the context manager approach, pass parameters directly to `llm_call()`
+    using the `llm_params` argument:
+
+    Old way (deprecated):
+        from nemoguardrails.llm.params import llm_params
+        with llm_params(llm, temperature=0.7):
+            result = await llm_call(llm, prompt)
+
+    New way (recommended):
+        result = await llm_call(llm, prompt, llm_params={"temperature": 0.7})
+
+    See: https://github.com/NVIDIA/NeMo-Guardrails/issues/1387
 """
 
 import logging
+import warnings
 from typing import Dict, Type
 
 from langchain.base_language import BaseLanguageModel
 
 log = logging.getLogger(__name__)
 
+_DEPRECATION_MESSAGE = (
+    "The nemoguardrails.llm.params module is deprecated and will be removed in version 0.19.0. "
+    "Instead of using llm_params context manager, pass parameters directly to llm_call() "
+    "using the llm_params argument. "
+    "See: https://github.com/NVIDIA/NeMo-Guardrails/issues/1387"
+)
+
 
 class LLMParams:
-    """Context manager to temporarily modify the parameters of a language model."""
+    """Context manager to temporarily modify the parameters of a language model.
+
+    .. deprecated:: 0.17.0
+        Use llm_call() with llm_params argument instead.
+    """
 
     def __init__(self, llm: BaseLanguageModel, **kwargs):
+        warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
         self.llm = llm
         self.altered_params = kwargs
         self.original_params = {}
@@ -82,13 +110,22 @@ def __exit__(self, type, value, traceback):
 
 
 def register_param_manager(llm_type: Type[BaseLanguageModel], manager: Type[LLMParams]):
-    """Register a parameter manager."""
+    """Register a parameter manager.
+
+    .. deprecated:: 0.17.0
+        This function is deprecated and will be removed in version 0.19.0.
+    """
+    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
     _param_managers[llm_type] = manager
 
 
 def llm_params(llm: BaseLanguageModel, **kwargs):
-    """Returns a parameter manager for the given language model."""
+    """Returns a parameter manager for the given language model.
 
+    .. deprecated:: 0.17.0
+        Use llm_call() with llm_params argument instead.
+    """
+    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
     _llm_params = _param_managers.get(llm.__class__, LLMParams)
 
     return _llm_params(llm, **kwargs)

tests/test_llm_params.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 
 import unittest
+import warnings
 from typing import Any, Dict
 from unittest.mock import AsyncMock, MagicMock
 
@@ -224,6 +225,57 @@ class UnregisteredLLM(BaseModel):
         self.assertIsInstance(llm_params(UnregisteredLLM()), LLMParams)
 
 
+class TestLLMParamsDeprecation(unittest.TestCase):
+    """Test deprecation warnings for llm_params module."""
+
+    def test_llm_params_function_raises_deprecation_warning(self):
+        """Test that llm_params function raises DeprecationWarning."""
+        llm = FakeLLM(param3="value3", model_kwargs={"param1": "value1"})
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            with llm_params(llm, param1="new_value1"):
+                pass
+
+            self.assertGreaterEqual(len(w), 1)
+            self.assertTrue(
+                any(issubclass(warning.category, DeprecationWarning) for warning in w)
+            )
+            self.assertTrue(
+                any(
+                    "0.19.0" in str(warning.message)
+                    and "llm_call()" in str(warning.message)
+                    for warning in w
+                )
+            )
+
+    def test_llm_params_class_raises_deprecation_warning(self):
+        """Test that LLMParams class raises DeprecationWarning."""
+        llm = FakeLLM(param3="value3", model_kwargs={"param1": "value1"})
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            params = LLMParams(llm, param1="new_value1")
+
+            self.assertGreaterEqual(len(w), 1)
+            self.assertTrue(issubclass(w[0].category, DeprecationWarning))
+            self.assertIn("0.19.0", str(w[0].message))
+
+    def test_register_param_manager_raises_deprecation_warning(self):
+        """Test that register_param_manager function raises DeprecationWarning."""
+
+        class CustomLLMParams(LLMParams):
+            pass
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            register_param_manager(FakeLLM, CustomLLMParams)
+
+            self.assertGreaterEqual(len(w), 1)
+            self.assertTrue(issubclass(w[0].category, DeprecationWarning))
+            self.assertIn("0.19.0", str(w[0].message))
+
+
 class TestLLMParamsMigration(unittest.TestCase):
     """Test migration from context manager to direct parameter passing."""
 

tests/test_llm_params_e2e.py

@@ -17,6 +17,7 @@
 
 import os
 import tempfile
+import warnings
 from pathlib import Path
 
 import pytest