Merge branch 'main' into tools-retriever-3

Author: oskarhane

CHANGELOG.md

@@ -7,6 +7,29 @@
 - Added a `ToolsRetriever` retriever that uses an LLM to decide on what tools to use to find the relevant data.
 - Added `convert_to_tool` method to the `Retriever` interface to convert a Retriever to a Tool so it can be used within the ToolsRetriever. This is useful when you might want to have both a VectorRetriever and a Text2CypherRetreiver as a fallback.
 
+### Fixed
+
+- Fixed an edge case where the LLM can output a property with type 'map', which was causing errors during import as it is not a valid property type in Neo4j.
+
+## 1.9.1
+
+### Fixed
+
+- Fixed documentation for PdfLoader
+- Fixed a bug where the `format` argument for `OllamaLLM` was not propagated to the client.
+- Fixed `AttributeError` in `SchemaFromTextExtractor` when filtering out node/relationship types with no labels.
+- Fixed an import error in `VertexAIEmbeddings`.
+
+## 1.9.0
+
+### Fixed
+
+- Fixed a bug where Session nodes were duplicated.
+
+## Added
+
+- Added automatic rate limiting with retry logic and exponential backoff for all LLM providers using tenacity. The `RateLimitHandler` interface allows for custom rate limiting strategies, including the ability to disable rate limiting entirely.
+
 
 ## 1.8.0
 

docs/source/api.rst

@@ -347,6 +347,28 @@ MistralAILLM
     :members:
 
 
+Rate Limiting
+=============
+
+RateLimitHandler
+----------------
+
+.. autoclass:: neo4j_graphrag.llm.rate_limit.RateLimitHandler
+    :members:
+
+RetryRateLimitHandler
+---------------------
+
+.. autoclass:: neo4j_graphrag.llm.rate_limit.RetryRateLimitHandler
+    :members:
+
+NoOpRateLimitHandler
+--------------------
+
+.. autoclass:: neo4j_graphrag.llm.rate_limit.NoOpRateLimitHandler
+    :members:
+
+
 PromptTemplate
 ==============
 
@@ -473,6 +495,8 @@ Errors
 
   * :class:`neo4j_graphrag.exceptions.LLMGenerationError`
 
+    * :class:`neo4j_graphrag.exceptions.RateLimitError`
+
   * :class:`neo4j_graphrag.exceptions.SchemaValidationError`
 
   * :class:`neo4j_graphrag.exceptions.PdfLoaderError`
@@ -597,6 +621,13 @@ LLMGenerationError
    :show-inheritance:
 
 
+RateLimitError
+==============
+
+.. autoclass:: neo4j_graphrag.exceptions.RateLimitError
+   :show-inheritance:
+
+
 SchemaValidationError
 =====================
 

docs/source/user_guide_kg_builder.rst

@@ -583,7 +583,7 @@ This package currently supports text extraction from PDFs:
     from neo4j_graphrag.experimental.components.pdf_loader import PdfLoader
 
     loader = PdfLoader()
-    await loader.run(path=Path("my_file.pdf"))
+    await loader.run(filepath=Path("my_file.pdf"))
 
 To implement your own loader, use the `DataLoader` interface:
 
@@ -783,16 +783,16 @@ Here is a code block illustrating these concepts:
             NodeType(
                 label="Person",
                 properties=[
-                    SchemaProperty(name="name", type="STRING"),
-                    SchemaProperty(name="place_of_birth", type="STRING"),
-                    SchemaProperty(name="date_of_birth", type="DATE"),
+                    PropertyType(name="name", type="STRING"),
+                    PropertyType(name="place_of_birth", type="STRING"),
+                    PropertyType(name="date_of_birth", type="DATE"),
                 ],
             ),
             NodeType(
                 label="Organization",
                 properties=[
-                    SchemaProperty(name="name", type="STRING"),
-                    SchemaProperty(name="country", type="STRING"),
+                    PropertyType(name="name", type="STRING"),
+                    PropertyType(name="country", type="STRING"),
                 ],
             ),
         ],

docs/source/user_guide_pipeline.rst

@@ -154,7 +154,7 @@ See :ref:`pipelineevent` and :ref:`taskevent` to see what is sent in each event
     import logging
 
     from neo4j_graphrag.experimental.pipeline import Pipeline
-    from neo4j_graphrag.experimental.pipeline.types import Event
+    from neo4j_graphrag.experimental.pipeline.notification import Event
 
     logger = logging.getLogger(__name__)
     logging.basicConfig()

docs/source/user_guide_rag.rst

@@ -125,15 +125,15 @@ To use VertexAI, instantiate the `VertexAILLM` class:
 
     generation_config = GenerationConfig(temperature=0.0)
     llm = VertexAILLM(
-        model_name="gemini-1.5-flash-001", generation_config=generation_config
+        model_name="gemini-2.5-flash", generation_config=generation_config
     )
     llm.invoke("say something")
 
 
 .. note::
 
     In order to run this code, the `google-cloud-aiplatform` Python package needs to be installed:
-    `pip install "neo4j_grpahrag[vertexai]"`
+    `pip install "neo4j_graphrag[google]"`
 
 
 See :ref:`vertexaillm`.
@@ -225,6 +225,7 @@ it can be queried using the following:
     from neo4j_graphrag.llm import OllamaLLM
     llm = OllamaLLM(
         model_name="orca-mini",
+        # model_params={"options": {"temperature": 0}, "format": "json"},
         # host="...",  # when using a remote server
     )
     llm.invoke("say something")
@@ -294,6 +295,91 @@ Here's an example using the Python Ollama client:
 See :ref:`llminterface`.
 
 
+Rate Limit Handling
+===================
+
+All LLM implementations include automatic rate limiting that uses retry logic with exponential backoff by default. This feature helps handle API rate limits from LLM providers gracefully by automatically retrying failed requests with increasing wait times between attempts.
+
+Default Rate Limit Handler
+--------------------------
+
+Rate limiting is enabled by default for all LLM instances with the following configuration:
+
+- **Max attempts**: 3
+- **Min wait**: 1.0 seconds
+- **Max wait**: 60.0 seconds
+- **Multiplier**: 2.0 (exponential backoff)
+
+.. code:: python
+
+    from neo4j_graphrag.llm import OpenAILLM
+
+    # Rate limiting is automatically enabled
+    llm = OpenAILLM(model_name="gpt-4o")
+
+    # The LLM will automatically retry on rate limit errors
+    response = llm.invoke("Hello, world!")
+
+.. note::
+
+   To change the default configuration of `RetryRateLimitHandler`:
+
+    .. code:: python
+
+        from neo4j_graphrag.llm import OpenAILLM
+        from neo4j_graphrag.llm.rate_limit import RetryRateLimitHandler
+
+        # Customize rate limiting parameters
+        llm = OpenAILLM(
+            model_name="gpt-4o",
+            rate_limit_handler=RetryRateLimitHandler(
+                max_attempts=10,    # Increase max retry attempts
+                min_wait=2.0,       # Increase minimum wait time
+                max_wait=120.0,     # Increase maximum wait time
+                multiplier=3.0      # More aggressive backoff
+            )
+        )
+
+Custom Rate Limiting
+--------------------
+
+You can customize the rate limiting behavior by creating your own rate limit handler:
+
+.. code:: python
+
+    from neo4j_graphrag.llm import AnthropicLLM
+    from neo4j_graphrag.llm.rate_limit import RateLimitHandler
+
+    class CustomRateLimitHandler(RateLimitHandler):
+        """Implement your custom rate limiting strategy."""
+        # Implement required methods: handle_sync, handle_async
+        pass
+
+    # Create custom rate limit handler and pass it to the LLM interface
+    custom_handler = CustomRateLimitHandler()
+
+    llm = AnthropicLLM(
+        model_name="claude-3-sonnet-20240229",
+        rate_limit_handler=custom_handler,
+    )
+
+Disabling Rate Limiting
+-----------------------
+
+For high-throughput applications or when you handle rate limiting externally, you can disable it:
+
+.. code:: python
+
+    from neo4j_graphrag.llm import CohereLLM, NoOpRateLimitHandler
+
+    # Disable rate limiting completely
+    llm = CohereLLM(
+        model_name="command-r-plus",
+        rate_limit_handler=NoOpRateLimitHandler(),
+    )
+    llm.invoke("Hello, world!")
+
+
 Configuring the Prompt
 ========================
 

examples/customize/embeddings/vertexai_embeddings.py

@@ -4,6 +4,6 @@
 
 from neo4j_graphrag.embeddings import VertexAIEmbeddings
 
-embeder = VertexAIEmbeddings(model="text-embedding-004")
+embeder = VertexAIEmbeddings(model="text-embedding-005")
 res = embeder.embed_query("my question")
 print(res[:10])

examples/customize/llms/custom_llm.py

@@ -1,8 +1,13 @@
 import random
 import string
-from typing import Any, List, Optional, Union
+from typing import Any, Awaitable, Callable, List, Optional, TypeVar, Union
 
 from neo4j_graphrag.llm import LLMInterface, LLMResponse
+from neo4j_graphrag.llm.rate_limit import (
+    RateLimitHandler,
+    # rate_limit_handler,
+    # async_rate_limit_handler,
+)
 from neo4j_graphrag.message_history import MessageHistory
 from neo4j_graphrag.types import LLMMessage
 
@@ -13,6 +18,8 @@ def __init__(
     ):
         super().__init__(model_name, **kwargs)
 
+    # Optional: Apply rate limit handling to synchronous invoke method
+    # @rate_limit_handler
     def invoke(
         self,
         input: str,
@@ -24,6 +31,8 @@ def invoke(
         )
         return LLMResponse(content=content)
 
+    # Optional: Apply rate limit handling to asynchronous ainvoke method
+    # @async_rate_limit_handler
     async def ainvoke(
         self,
         input: str,
@@ -33,6 +42,33 @@ async def ainvoke(
         raise NotImplementedError()
 
 
-llm = CustomLLM("")
+llm = CustomLLM(
+    ""
+)  # if rate_limit_handler and async_rate_limit_handler decorators are used, the default rate limit handler will be applied automatically (retry with exponential backoff)
 res: LLMResponse = llm.invoke("text")
 print(res.content)
+
+# If rate_limit_handler and async_rate_limit_handler decorators are used and you want to use a custom rate limit handler
+# Type variables for function signatures used in rate limit handlers
+F = TypeVar("F", bound=Callable[..., Any])
+AF = TypeVar("AF", bound=Callable[..., Awaitable[Any]])
+
+
+class CustomRateLimitHandler(RateLimitHandler):
+    def __init__(self) -> None:
+        super().__init__()
+
+    def handle_sync(self, func: F) -> F:
+        # error handling here
+        return func
+
+    def handle_async(self, func: AF) -> AF:
+        # error handling here
+        return func
+
+
+llm_with_custom_rate_limit_handler = CustomLLM(
+    "", rate_limit_handler=CustomRateLimitHandler()
+)
+result: LLMResponse = llm_with_custom_rate_limit_handler.invoke("text")
+print(result.content)

examples/customize/llms/ollama_llm.py

@@ -6,6 +6,7 @@
 
 llm = OllamaLLM(
     model_name="<model_name>",
+    # model_params={"options": {"temperature": 0}, "format": "json"},
     # host="...",  # if using a remote server
 )
 res: LLMResponse = llm.invoke("What is the additive color model?")

examples/customize/llms/vertexai_llm.py

@@ -1,12 +1,15 @@
 from neo4j_graphrag.llm import LLMResponse, VertexAILLM
 from vertexai.generative_models import GenerationConfig
 
-generation_config = GenerationConfig(temperature=0.0)
+generation_config = GenerationConfig(temperature=1.0)
 llm = VertexAILLM(
-    model_name="gemini-1.5-flash-001",
+    model_name="gemini-2.0-flash-001",
     generation_config=generation_config,
     # add here any argument that will be passed to the
     # vertexai.generative_models.GenerativeModel client
 )
-res: LLMResponse = llm.invoke("say something")
+res: LLMResponse = llm.invoke(
+    "say something",
+    system_instruction="You are living in 3000 where AI rules the world",
+)
 print(res.content)