ibm-watsonx-gov 1.3.3__cp313-cp313-macosx_11_0_arm64.whl

ibm_watsonx_gov/tools/ootb/rag/answer_relevance_detector_tool.py

@@ -0,0 +1,119 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+from typing import Annotated, List, Optional, Type
+
+from langchain.callbacks.manager import CallbackManagerForToolRun
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+import ibm_watsonx_gov.tools.clients.detector_client as dc
+
+
+class AnswerRelevanceInput(BaseModel):
+    """
+        Model that can be used for setting input args for answer relevance tool
+    """
+    input: Annotated[str,
+                     Field(..., description="The original user input/question.")]
+    generated_text: Annotated[str,
+                     Field(..., description="The response generated by the LLM.")]
+    threshold: Annotated[Optional[float], Field(
+        0.7, description="Threshold for answer relevance detection, values range from 0.0 to 1.0")]
+    
+    
+class AnswerRelevanceConfig(BaseModel):
+    """
+        Model that can be used for setting config args for answer relevance tool
+    """
+    threshold: Annotated[Optional[float], Field(
+        0.7, description="Threshold for answer relevance detection, values range from 0.0 to 1.0")]
+
+
+class AnswerRelevanceDetectorTool(BaseTool):
+    """
+    Tool to detect answer relevance for given input and response from LLM
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                answer_relevance_detector = class AnswerRelevanceDetectorTool(BaseTool)()
+                answer_relevance_detector.invoke({"input":"<USER_INPUT>","generated_text":"<LLM response>"})
+    """
+    name: str = "answer_relevance_detector"
+    description: str = (
+        "Tool that analyzes whether the generated text meaningfully and directly addresses the user's input."\
+        "It compares the user input and generated text to return a boolean flag and a numeric score indicating the degree of relevance.")
+    args_schema: Type[BaseModel] = AnswerRelevanceInput
+
+    _url: any = PrivateAttr()
+    _threshold: any = PrivateAttr()
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        config = AnswerRelevanceConfig(**kwargs)
+        self._threshold = config.threshold
+        self._url = dc.DETECTIONS_GENRATE_URL.format(dc.get_base_url())
+
+    # Define Answer relevace tool
+    def _run(self,
+             input: str,
+             generated_text: str,
+             run_manager: Optional[CallbackManagerForToolRun] = None,
+             **kwargs) -> List[str]:
+        """
+        Sample Response:
+            {
+                "detections": [
+                    {
+                        "detection_type": "risk",
+                        "detector_id": "granite_guardian_3_2_5b",
+                        "score": 0.03726182132959366
+                    }
+                ],
+                "is_answer_relevant":True
+            }
+        """
+        threshold = kwargs.get("threshold",self._threshold)
+
+        #set payload
+        base_payload = dc.get_base_payload(dc.GRANITE_GUADIAN,
+                                           detector_params={
+                                                                "risk_name": "answer_relevance",
+                                                                "threshold": 0.0
+                                                            })
+        ar_payload = {
+            "prompt":input,
+            "generated_text": generated_text
+        }
+
+        payload = {**base_payload,**ar_payload}
+        detections_response = dc.call_detections(self._url, payload)
+
+        #Remove unwanted properties
+        detections = detections_response.get("detections",[])
+        for detection in detections:
+            detection.pop("detection",None)
+        score = detections[0].get("score")
+
+        #Propogate a boolen to get a intutive response
+        is_answer_relevant = False if score > threshold else True
+
+        detections_response["detections"] = detections
+        detections_response["is_answer_relevant"] = is_answer_relevant
+        return detections_response
+    
+    async def _arun(self,
+                    input: str,
+                    generated_text: str,
+                    run_manager: Optional[CallbackManagerForToolRun] = None,
+                    **kwargs) -> List[str]:
+        
+        return self._run(input , generated_text, kwargs)

ibm_watsonx_gov/tools/ootb/rag/context_relevance_detector_tool.py

@@ -0,0 +1,118 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+from typing import Annotated, List, Optional, Type
+
+from langchain.callbacks.manager import CallbackManagerForToolRun
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+import ibm_watsonx_gov.tools.clients.detector_client as dc
+
+
+class ContextRelevanceInput(BaseModel):
+    """
+        Model that can be used for setting input args for context relevance tool
+    """
+    input: Annotated[str,
+                     Field(..., description="The original user input/question.")]
+    context: Annotated[str,
+                     Field(..., description="The retrieved or provided context to validate")]
+    threshold: Annotated[Optional[float], Field(
+        0.7, description="Threshold for answer relevance detection, values range from 0.0 to 1.0")]
+    
+    
+class ContextRelevanceConfig(BaseModel):
+    """
+        Model that can be used for setting config args for context relevance tool
+    """
+    threshold: Annotated[Optional[float], Field(
+        0.7, description="Threshold for answer relevance detection, values range from 0.0 to 1.0")]
+
+
+class ContextRelevanceDetectorTool(BaseTool):
+    """
+    Tool to detect answer relevance for given input and response from LLM
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                context_relevance_detector = class ContextRelevanceDetectorTool(BaseTool)()
+                context_relevance_detector.invoke({"input":"<USER_INPUT>","context":"<context retrieved>"})
+    """
+    name: str = "context_relevance_detector"
+    description: str = ("Tool that analyzes whether the user input is relevant to the given context." \
+    "It compares the input with the provided context and outputs a boolean along with a relevance score. ")
+    args_schema: Type[BaseModel] = ContextRelevanceInput
+    _url: any = PrivateAttr()
+    _threshold: any = PrivateAttr()
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        config = ContextRelevanceConfig(**kwargs)
+        self._threshold = config.threshold
+        self._url = dc.DETECTIONS_CONTEXT_URL.format(dc.get_base_url())
+
+    # Define Answer relevace tool
+    def _run(self,
+             input: str,
+             context: str,
+             run_manager: Optional[CallbackManagerForToolRun] = None,
+             **kwargs) -> List[str]:
+        """
+        Sample Response:
+            {
+                "detections": [
+                    {
+                        "detection_type": "risk",
+                        "detector_id": "granite_guardian_3_2_5b",
+                        "score": 0.03726182132959366
+                    }
+                ],
+                "is_context_relevant":True
+            }
+        """
+        threshold = kwargs.get("threshold",self._threshold)
+
+        #Get payload
+        base_payload = dc.get_base_payload(dc.GRANITE_GUADIAN,
+                                           detector_params={
+                                                                "risk_name": "context_relevance",
+                                                                "threshold": 0.0
+                                                            })
+        cr_payload = {
+            "input":input,
+            "context_type": "docs",
+            "context": [context]
+        }
+
+        payload = {**base_payload,**cr_payload}
+        detections_response = dc.call_detections(self._url, payload)
+
+        #Remove unwanted properties
+        detections = detections_response.get("detections",[])
+        for detection in detections:
+            detection.pop("detection",None)
+        score = detections[0].get("score")
+
+        #Propogate a boolen to get a intutive response
+        is_context_relevant = False if score > threshold else True
+
+        detections_response["detections"] = detections
+        detections_response["is_context_relevant"] = is_context_relevant
+        return detections_response
+    
+    async def _arun(self,
+                    input: str,
+                    context: str,
+                    run_manager: Optional[CallbackManagerForToolRun] = None,
+                    **kwargs) -> List[str]:
+        
+        return self._run(input , context, kwargs)

ibm_watsonx_gov/tools/ootb/search/__init__.py

@@ -0,0 +1,8 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------

ibm_watsonx_gov/tools/ootb/search/duckduckgo_search_tool.py

@@ -0,0 +1,62 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+from typing import List, Optional, Type
+
+from langchain.callbacks.manager import CallbackManagerForToolRun
+from langchain.tools import BaseTool
+from pydantic import BaseModel, PrivateAttr
+
+from ...schemas.search_tool_schema import SearchToolConfig, SearchToolInput
+
+
+class DuckDuckGoSearchTool(BaseTool):
+    """
+    Tool to search and get results using duckduckgo search engine
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                duckduckgosearch_tool = DuckDuckGoSearchTool()
+                duckduckgosearch_tool.invoke({"query":"What is RAG?"})
+    """
+    name: str = "duckduckgo_search_tool"
+    description: str = "Search using duckduckgo search engine and return the top-k results.Default :3"
+    args_schema: Type[BaseModel] = SearchToolInput
+    _top_k_results = PrivateAttr()
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        from ibm_watsonx_gov.tools.utils.package_utils import \
+            install_and_import_packages
+
+        install_and_import_packages(["ddgs"])
+        config = SearchToolConfig(**kwargs)
+        self._top_k_results = config.top_k_results
+
+    def _run(self,
+             query: str,
+             top_k_results: int = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None,
+             **kwargs) -> List[str]:
+        """Use DuckDuckGo Search and return the top-k results."""
+        if top_k_results is None:
+            top_k_results = self._top_k_results
+
+        from langchain_community.utilities import DuckDuckGoSearchAPIWrapper
+        results = DuckDuckGoSearchAPIWrapper().results(
+            query=query, max_results=top_k_results)
+
+        # Ensure results are in string format
+        if isinstance(results, list):
+            # Extract snippets
+            return [res["snippet"] for res in results if "snippet" in res]
+
+        return [str(results)]  # Send list if the response is not a list

ibm_watsonx_gov/tools/ootb/search/google_search_tool.py

@@ -0,0 +1,105 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+
+from typing import List, Optional, Type
+
+import requests
+from langchain.callbacks.manager import CallbackManagerForToolRun
+from langchain.tools import BaseTool
+from pydantic import BaseModel, PrivateAttr
+from ibm_watsonx_gov.utils.python_utils import get
+from ...schemas.search_tool_schema import GoogleSearchToolConfig, SearchToolInput
+
+
+class GoogleSearchTool(BaseTool):
+    """
+    Tool to search and get results using google search engine
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                google_search_tool = GoogleSearchTool()
+                google_search_tool.invoke({"query":"What is RAG?"})
+    """
+    name: str = "google_search_tool"
+    description: str = (
+        "Search Google using SerpAPI and return top-k results, "
+        "Default top-k :3"
+    )
+    args_schema: Type[BaseModel] = SearchToolInput
+
+    _top_k_results: any = PrivateAttr()
+
+    _serpapi_key: str = PrivateAttr()
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._headers = {"User-Agent": "Mozilla/5.0"}
+        from ibm_watsonx_gov.tools.utils.package_utils import \
+            install_and_import_packages
+
+        install_and_import_packages(["bs4", "google-search-results"])
+
+        # Load args into config
+        config = GoogleSearchToolConfig(**kwargs)
+        self._top_k_results = config.top_k_results
+        self._serpapi_key = config.serpapi_key
+
+
+    def _fetch_page_content(self, url: str, max_chars: int = 5000) -> str:
+        try:
+            from bs4 import BeautifulSoup
+            response = requests.get(url, timeout=10, headers={"User-Agent": "Mozilla/5.0"})
+            soup = BeautifulSoup(response.text, "html.parser")
+
+            # Remove JS scripts & css styles
+            for script in soup(["script", "style"]):
+                script.extract()
+
+            # Join text with newlines between paragraphs
+            paragraphs = [para.get_text(strip=True) for para in soup.find_all("p")]
+            text = "".join(paragraphs)
+
+            return text
+        except Exception as e:
+           print(f"Skipping {url}: {e}")
+           return ""
+
+    # Define Google Search Tool Without API Key
+    def _run(self,
+             query: str,
+             top_k_results: int = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None,
+             **kwargs) -> List[str]:
+        """Performs a Google search and extracts content from the top results."""
+        from bs4 import BeautifulSoup
+        from serpapi import GoogleSearch
+
+        if top_k_results is None:
+            top_k_results = self._top_k_results
+
+        search_results = GoogleSearch({
+            "q": query,
+            "api_key": self._serpapi_key
+        })
+        search_results = search_results.get_dict()
+
+        organic_results = get(search_results, "organic_results", default=[])
+
+        results = []
+        for res in organic_results[:top_k_results]:
+            link = res.get("link")
+            if link:
+                # Extract text from the webpage
+                content = self._fetch_page_content(link)
+                results.append(content)
+
+        return results

ibm_watsonx_gov/tools/ootb/search/weather_tool.py

@@ -0,0 +1,95 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+
+from typing import Annotated, Any, Optional, Type
+
+import requests
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class WeatherInput(BaseModel):
+    location: Annotated[str, Field(description="Name of the location")]
+    country: Annotated[Optional[str], Field(
+        description="Name of the country", default=None)]
+
+
+class WeatherTool(BaseTool):
+    """
+    Tool for retrieving the weather of a location.
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                weather_tool = WeatherTool()
+                weather_tool.invoke({"location":"London"})
+    """
+
+    name: str = "weather_tool"
+    description: str = "Find the weather for a location or a city and country."
+    args_schema: Type[BaseModel] = WeatherInput
+
+    def _run(self, location: str, country: str = None, **kwargs: Any) -> Any:
+        """Performs weather search based on location and country"""
+
+        coordinates = self.__get_coordinates(location, country)
+        coord = f"latitude={coordinates['latitude']}&longitude={coordinates['longitude']}"
+        current = "current=temperature_2m,rain,relative_humidity_2m,wind_speed_10m"
+        url = f"https://api.open-meteo.com/v1/forecast?{coord}&{current}"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        }
+        response = requests.get(url, headers=headers)
+        if response.status_code >= 400:
+            raise Exception(
+                f"Unexpected response from Weather tool {response.text}")
+
+        response_json = response.json()
+
+        fullLocation = location
+        if country:
+            fullLocation = f"{fullLocation}, {country}"
+
+        current = response_json['current']
+        current_units = response_json['current_units']
+        result = f"""Current weather in {fullLocation}
+    Temperature: {current['temperature_2m']}{current_units['temperature_2m']}
+    Rain: {current['rain']}{current_units['rain']}
+    Relative humidity: {current['relative_humidity_2m']}{current_units['relative_humidity_2m']}
+    Wind: {current['wind_speed_10m']}{current_units['wind_speed_10m']}
+    """
+
+        return result
+
+    def __get_coordinates(self, location, country):
+        params = f"name={location}"
+        if country:
+            params = f"{params}&country={country}"
+
+        url = f"https://geocoding-api.open-meteo.com/v1/search?{params}&count=1&language=en&format=json"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        }
+        response = requests.get(url, headers=headers)
+        if response.status_code >= 400:
+            raise Exception(
+                f"Unable to get coordinates for location from Weather tool {response.text}")
+
+        results = response.json()
+        if "results" not in results:
+            raise Exception(
+                "Unable to find weather for location {}.".format(location))
+        return {
+            "latitude": results["results"][0]["latitude"],
+            "longitude": results["results"][0]["longitude"]
+        }

ibm_watsonx_gov/tools/ootb/search/web_crawler_tool.py

@@ -0,0 +1,69 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+
+import json
+import re
+from typing import Annotated, Any, Optional, Type
+
+import requests
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class WebCrawlerInput(BaseModel):
+    url: Annotated[str, Field(description="Url of the website")]
+
+
+class WebCrawlerTool(BaseTool):
+    """
+    Tool for retrieving the content of the web url.
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                crawler_tool = WebCrawlerTool()
+                crawler_tool.invoke({"url":"https://edition.cnn.com/2025/03/31/sport/torpedo-bats-mlb-yankees-explained-spt/index.html"})
+    """
+    name: str = "webcrawler_tool"
+    description: str = "Retrieve the content of the Web url. Do not use for Web search."
+    args_schema: Type[BaseModel] = WebCrawlerInput
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        from ibm_watsonx_gov.tools.utils.package_utils import \
+            install_and_import_packages
+
+        install_and_import_packages(["bs4"])
+
+    def _run(self, url: str, **kwargs: Any) -> Any:
+        """Retrieve the content of the Web url."""
+
+        from bs4 import BeautifulSoup
+        url_pattern = "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
+        pattern = re.compile(url_pattern)
+        if not pattern.match(url):
+            raise Exception("Invalid URL passed to WebCrawlerTool ")
+
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        }
+        try:
+            response = requests.get(url, headers=headers)
+        except:
+            raise Exception(
+                f"Unable to connect to {url}. Check the url")
+        if response.status_code >= 400:
+            raise Exception(
+                f"Unexpected response from WebCrawlerTool {response.text}")
+
+        soup = BeautifulSoup(response.text, "html.parser")
+        return soup.get_text()

ibm_watsonx_gov/tools/ootb/search/wikipedia_search_tool.py

@@ -0,0 +1,63 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------
+
+
+from typing import List, Optional, Type
+
+from langchain.callbacks.manager import CallbackManagerForToolRun
+from langchain.tools import BaseTool
+from langchain_community.utilities import WikipediaAPIWrapper
+from pydantic import BaseModel, PrivateAttr
+
+from ...schemas.search_tool_schema import SearchToolConfig, SearchToolInput
+
+
+# Create a wrapper to call the tool
+class WikiPediaSearchTool(BaseTool):
+    """
+    Tool to search and get results using wikipedia search
+
+    Examples:
+        Basic usage
+            .. code-block:: python
+
+                wikipedia_search_tool = WikiPediaSearchTool()
+                wikipedia_search_tool.invoke({"query":"What is RAG?"})
+    """
+    name: str = "wikipedia_search_tool"
+    description: str = "Search Wikipedia and return the top-k results.Default :3"
+    args_schema: Type[BaseModel] = SearchToolInput
+
+    _top_k_results: any = PrivateAttr()
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        from ibm_watsonx_gov.tools.utils.package_utils import \
+            install_and_import_packages
+        install_and_import_packages(["wikipedia"])
+
+        config = SearchToolConfig(**kwargs)
+        self._top_k_results = config.top_k_results
+
+    def _run(self,
+             query: str,
+             top_k_results: int = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None,
+             **kwargs) -> List[str]:
+
+        if top_k_results is None:
+            top_k_results = self._top_k_results
+
+        search_results = WikipediaAPIWrapper(
+            top_k_results=top_k_results).run(query)
+
+        # return search_results
+        results = [para.strip()
+                   for para in search_results.split("\n\n") if para.strip()]
+        return results

ibm_watsonx_gov/tools/ootb/vectordb/__init__.py

@@ -0,0 +1,8 @@
+# ----------------------------------------------------------------------------------------------------
+# IBM Confidential
+# Licensed Materials - Property of IBM
+# 5737-H76, 5900-A3Q
+# © Copyright IBM Corp. 2025  All Rights Reserved.
+# US Government Users Restricted Rights - Use, duplication or disclosure restricted by
+# GSA ADPSchedule Contract with IBM Corp.
+# ----------------------------------------------------------------------------------------------------