Do not force users to implement _invoke/_ainvoke to prevent breaking changes + add deprecation warning

Author: stellasia

docs/source/user_guide_rag.rst

@@ -265,21 +265,17 @@ Here's an example using the Python Ollama client:
 
     import ollama
     from neo4j_graphrag.llm import LLMInterface, LLMResponse
+    from neo4j_graphrag.types import LLMMessage
 
     class OllamaLLM(LLMInterface):
 
-        def invoke(self, input: str) -> LLMResponse:
-            response = ollama.chat(model=self.model_name, messages=[
-              {
-                'role': 'user',
-                'content': input,
-              },
-            ])
+        def _invoke(self, input: list[LLMMessage]) -> LLMResponse:
+            response = ollama.chat(model=self.model_name, messages=input)
             return LLMResponse(
                 content=response["message"]["content"]
             )
 
-        async def ainvoke(self, input: str) -> LLMResponse:
+        async def _ainvoke(self, input: list[LLMMessage]) -> LLMResponse:
             return self.invoke(input)  # TODO: implement async with ollama.AsyncClient
 
 

src/neo4j_graphrag/llm/base.py

@@ -14,7 +14,7 @@
 #  limitations under the License.
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
+import warnings
 from typing import Any, List, Optional, Sequence, Union
 
 from pydantic import ValidationError
@@ -36,7 +36,7 @@
 from ..exceptions import LLMGenerationError
 
 
-class LLMInterface(ABC):
+class LLMInterface:
     """Interface for large language models.
 
     Args:
@@ -68,6 +68,16 @@ def invoke(
         message_history: Optional[Union[List[LLMMessage], MessageHistory]] = None,
         system_instruction: Optional[str] = None,
     ) -> LLMResponse:
+        if message_history:
+            warnings.warn(
+                "Using 'message_history' in the llm.invoke method is deprecated. Please use invoke(list[LLMMessage]) instead.",
+                DeprecationWarning,
+            )
+        if system_instruction:
+            warnings.warn(
+                "Using 'system_instruction' in the llm.invoke method is deprecated. Please use invoke(list[LLMMessage]) instead.",
+                DeprecationWarning,
+            )
         try:
             messages = legacy_inputs_to_messages(
                 input, message_history, system_instruction
@@ -76,7 +86,6 @@ def invoke(
             raise LLMGenerationError("Input validation failed") from e
         return self._invoke(messages)
 
-    @abstractmethod
     def _invoke(
         self,
         input: list[LLMMessage],
@@ -92,6 +101,7 @@ def _invoke(
         Raises:
             LLMGenerationError: If anything goes wrong.
         """
+        raise NotImplementedError()
 
     @async_rate_limit_handler
     async def ainvoke(
@@ -100,10 +110,19 @@ async def ainvoke(
         message_history: Optional[Union[List[LLMMessage], MessageHistory]] = None,
         system_instruction: Optional[str] = None,
     ) -> LLMResponse:
+        if message_history:
+            warnings.warn(
+                "Using 'message_history' in the llm.ainvoke method is deprecated. Please use invoke(list[LLMMessage]) instead.",
+                DeprecationWarning,
+            )
+        if system_instruction:
+            warnings.warn(
+                "Using 'system_instruction' in the llm.ainvoke method is deprecated. Please use invoke(list[LLMMessage]) instead.",
+                DeprecationWarning,
+            )
         messages = legacy_inputs_to_messages(input, message_history, system_instruction)
         return await self._ainvoke(messages)
 
-    @abstractmethod
     async def _ainvoke(
         self,
         input: list[LLMMessage],
@@ -119,6 +138,7 @@ async def _ainvoke(
         Raises:
             LLMGenerationError: If anything goes wrong.
         """
+        raise NotImplementedError()
 
     @rate_limit_handler
     def invoke_with_tools(

tests/unit/llm/test_base.py

@@ -20,16 +20,11 @@
 
 @fixture(scope="module")  # type: ignore[misc]
 def llm_interface() -> Generator[Type[LLMInterface], None, None]:
-    real_abstract_methods = LLMInterface.__abstractmethods__
-    LLMInterface.__abstractmethods__ = frozenset()
-
     class CustomLLMInterface(LLMInterface):
         pass
 
     yield CustomLLMInterface
 
-    LLMInterface.__abstractmethods__ = real_abstract_methods
-
 
 @patch("neo4j_graphrag.llm.base.legacy_inputs_to_messages")
 def test_base_llm_interface_invoke_with_input_as_str(
@@ -52,7 +47,8 @@ def test_base_llm_interface_invoke_with_input_as_str(
     system_instruction = "You are a genius."
 
     with patch.object(llm, "_invoke") as mock_invoke:
-        llm.invoke(question, message_history, system_instruction)
+        with pytest.warns(DeprecationWarning) as record:
+            llm.invoke(question, message_history, system_instruction)
         mock_invoke.assert_called_once_with(
             [
                 LLMMessage(
@@ -66,6 +62,15 @@ def test_base_llm_interface_invoke_with_input_as_str(
         message_history,
         system_instruction,
     )
+    assert len(record) == 2
+    assert (
+        "Using 'message_history' in the llm.invoke method is deprecated"
+        in record[0].message.args[0]  # type: ignore[union-attr]
+    )
+    assert (
+        "Using 'system_instruction' in the llm.invoke method is deprecated"
+        in record[1].message.args[0]  # type: ignore[union-attr]
+    )
 
 
 @patch("neo4j_graphrag.llm.base.legacy_inputs_to_messages")