Address PR comments: refactor retriever-to-tool conversion

- Add abstract get_parameters() method to Retriever base class
- Add convert_to_tool() instance method to Retriever class
- Implement get_parameters() for all concrete retriever classes
- Remove automatic query_text injection in ToolsRetriever
- Update example to use new convert_to_tool() method
- Remove unnecessary description from ObjectParameter in example

Author: oskarhane

examples/retrieve/tools/multiple_tools_example.py

@@ -0,0 +1,151 @@
+#  Copyright (c) "Neo4j"
+#  Neo4j Sweden AB [https://neo4j.com]
+#  #
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#  #
+#      https://www.apache.org/licenses/LICENSE-2.0
+#  #
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+"""
+Example demonstrating how to create multiple domain-specific tools from retrievers.
+
+This example shows:
+1. How to create multiple tools from the same retriever type for different use cases
+2. How to provide custom parameter descriptions for each tool
+3. How type inference works automatically while descriptions are explicit
+"""
+
+import neo4j
+from typing import cast, Any, Optional
+from unittest.mock import MagicMock
+
+from neo4j_graphrag.retrievers.base import Retriever
+from neo4j_graphrag.types import RawSearchResult
+
+
+class MockVectorRetriever(Retriever):
+    """A mock vector retriever for demonstration purposes."""
+
+    VERIFY_NEO4J_VERSION = False
+
+    def __init__(self, driver: neo4j.Driver, index_name: str):
+        super().__init__(driver)
+        self.index_name = index_name
+
+    def get_search_results(
+        self,
+        query_vector: Optional[list[float]] = None,
+        query_text: Optional[str] = None,
+        top_k: int = 5,
+        effective_search_ratio: int = 1,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> RawSearchResult:
+        """Get vector search results (mocked for demonstration)."""
+        # Return empty results for demo
+        return RawSearchResult(records=[], metadata={"index": self.index_name})
+
+
+def main() -> None:
+    """Demonstrate creating multiple domain-specific tools from retrievers."""
+
+    # Create mock driver (in real usage, this would be actual Neo4j driver)
+    driver = cast(Any, MagicMock())
+
+    # Create retrievers for different domains using the same retriever type
+    # In practice, these would point to different vector indexes
+
+    # Movie recommendations retriever
+    movie_retriever = MockVectorRetriever(driver=driver, index_name="movie_embeddings")
+
+    # Product search retriever
+    product_retriever = MockVectorRetriever(
+        driver=driver, index_name="product_embeddings"
+    )
+
+    # Document search retriever
+    document_retriever = MockVectorRetriever(
+        driver=driver, index_name="document_embeddings"
+    )
+
+    # Convert each retriever to a domain-specific tool with custom descriptions
+
+    # 1. Movie recommendation tool
+    movie_tool = movie_retriever.convert_to_tool(
+        name="movie_search",
+        description="Find movie recommendations based on plot, genre, or actor preferences",
+        parameter_descriptions={
+            "query_text": "Movie title, plot description, genre, or actor name",
+            "query_vector": "Pre-computed embedding vector for movie search",
+            "top_k": "Number of movie recommendations to return (1-20)",
+            "filters": "Optional filters for genre, year, rating, etc.",
+            "effective_search_ratio": "Search pool multiplier for better accuracy",
+        },
+    )
+
+    # 2. Product search tool
+    product_tool = product_retriever.convert_to_tool(
+        name="product_search",
+        description="Search for products matching customer needs and preferences",
+        parameter_descriptions={
+            "query_text": "Product name, description, or customer need",
+            "query_vector": "Pre-computed embedding for product matching",
+            "top_k": "Maximum number of product results (1-50)",
+            "filters": "Filters for price range, brand, category, availability",
+            "effective_search_ratio": "Breadth vs precision trade-off for search",
+        },
+    )
+
+    # 3. Document search tool
+    document_tool = document_retriever.convert_to_tool(
+        name="document_search",
+        description="Find relevant documents and knowledge articles",
+        parameter_descriptions={
+            "query_text": "Question, keywords, or topic to search for",
+            "query_vector": "Semantic embedding for document retrieval",
+            "top_k": "Number of relevant documents to retrieve (1-10)",
+            "filters": "Document type, date range, or department filters",
+        },
+    )
+
+    # Demonstrate that each tool has distinct, meaningful descriptions
+    tools = [movie_tool, product_tool, document_tool]
+
+    for tool in tools:
+        print(f"\n=== {tool.get_name().upper()} ===")
+        print(f"Description: {tool.get_description()}")
+        print("Parameters:")
+
+        params = tool.get_parameters()
+        for param_name, param_def in params["properties"].items():
+            required = (
+                "required" if param_name in params.get("required", []) else "optional"
+            )
+            print(
+                f"  - {param_name} ({param_def['type']}, {required}): {param_def['description']}"
+            )
+
+    # Show how the same parameter type gets different contextual descriptions
+    print("\n=== PARAMETER COMPARISON ===")
+    print("Same parameter 'query_text' with different contextual descriptions:")
+
+    for tool in tools:
+        params = tool.get_parameters()
+        query_text_desc = params["properties"]["query_text"]["description"]
+        print(f"  {tool.get_name()}: {query_text_desc}")
+
+    print("\nSame parameter 'top_k' with different contextual descriptions:")
+    for tool in tools:
+        params = tool.get_parameters()
+        top_k_desc = params["properties"]["top_k"]["description"]
+        print(f"  {tool.get_name()}: {top_k_desc}")
+
+
+if __name__ == "__main__":
+    main()

examples/retrieve/tools/retriever_to_tool_example.py

@@ -17,8 +17,8 @@
 Example demonstrating how to convert a retriever to a tool.
 
 This example shows:
-1. How to convert a custom StaticRetriever to a Tool
-2. How to define parameters for the tool
+1. How to convert a custom StaticRetriever to a Tool using the convert_to_tool method
+2. How to define parameters for the tool in the retriever class
 3. How to execute the tool
 """
 
@@ -28,11 +28,6 @@
 
 from neo4j_graphrag.retrievers.base import Retriever
 from neo4j_graphrag.types import RawSearchResult
-from neo4j_graphrag.tools.tool import (
-    StringParameter,
-    ObjectParameter,
-)
-from neo4j_graphrag.tools.utils import convert_retriever_to_tool
 
 
 # Create a Retriever that returns static results about Neo4j
@@ -50,7 +45,15 @@ def __init__(self, driver: neo4j.Driver):
     def get_search_results(
         self, query_text: Optional[str] = None, **kwargs: Any
     ) -> RawSearchResult:
-        """Return static information about Neo4j regardless of the query."""
+        """Return static information about Neo4j regardless of the query.
+
+        Args:
+            query_text (Optional[str]): The query about Neo4j (any query will return general Neo4j information)
+            **kwargs (Any): Additional keyword arguments (not used)
+
+        Returns:
+            RawSearchResult: Static Neo4j information with metadata
+        """
         # Create formatted Neo4j information
         neo4j_info = (
             "# Neo4j Graph Database\n\n"
@@ -73,26 +76,16 @@ def get_search_results(
 
 
 def main() -> None:
-    # Convert a StaticRetriever to a tool with specific parameters
+    # Convert a StaticRetriever to a tool using the new convert_to_tool method
     static_retriever = StaticRetriever(driver=cast(Any, MagicMock()))
 
-    # Define parameters for the static retriever tool
-    static_parameters = ObjectParameter(
-        description="Parameters for the Neo4j information retriever",
-        properties={
-            "query_text": StringParameter(
-                description="The query about Neo4j (any query will return general Neo4j information)",
-                required=True,
-            ),
-        },
-    )
-
-    # Convert the retriever to a tool with specific parameters
-    static_tool = convert_retriever_to_tool(
-        retriever=static_retriever,
-        description="Get general information about Neo4j graph database",
-        parameters=static_parameters,
+    # Convert the retriever to a tool with custom parameter descriptions
+    static_tool = static_retriever.convert_to_tool(
         name="Neo4jInfoTool",
+        description="Get general information about Neo4j graph database",
+        parameter_descriptions={
+            "query_text": "Any query about Neo4j (the tool returns general information regardless)"
+        },
     )
 
     # Print tool information
@@ -107,7 +100,7 @@ def main() -> None:
         # Execute the static retriever tool
         print("\nExecuting the static retriever tool...")
         static_result = static_tool.execute(
-            query="What is Neo4j?",
+            query_text="What is Neo4j?",
         )
         print("Static Search Results:")
         for i, item in enumerate(static_result):