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

ibm_watsonx_gov/utils/python_utils.py

@@ -0,0 +1,425 @@
+# ----------------------------------------------------------------------------------------------------
+# 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 enum
+import inspect
+import json
+import os
+from functools import reduce
+from inspect import signature
+from typing import (Any, Callable, Dict, List, Optional, TypeVar, Union,
+                    get_args, get_origin)
+import time
+from contextlib import contextmanager, asynccontextmanager
+
+import pandas as pd
+from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
+from pydantic import BaseModel
+
+from ibm_watsonx_gov.utils.authenticator import Authenticator
+from ibm_watsonx_gov.utils.gov_sdk_logger import GovSDKLogger
+
+try:
+    from langchain_core.tools import BaseTool
+    from langchain_core.utils.function_calling import \
+        convert_to_openai_function
+except ImportError:
+    pass
+
+logger = GovSDKLogger.get_logger(__name__)
+
+def convert_df_to_list(df: pd.DataFrame, features: list):
+    """
+        Method to convert pandas df to 2d array
+    """
+    if len(features) > 0:
+        return df[features].values.tolist()
+    else:
+        return df.values.tolist()
+
+
+def convert_to_list_of_lists(value):
+    """Method to convert a dataframe column to list of lists
+
+    Args:
+        value (_type_): DataFrame column
+
+    Returns:
+        _type_: _description_
+    """
+    if isinstance(value, list):
+        # Check if it's already a list of lists
+        if all(isinstance(i, list) for i in value):
+            return value
+        # If it's a list of strings, wrap it to make it a list of lists
+        elif all(isinstance(i, str) for i in value):
+            return [value]
+    # Return empty list if value is None or 'NULL' string
+    return []
+
+
+def get(dictionary, keys: str, default=None):
+    return reduce(lambda d, key: d.get(key, default) if isinstance(d, dict) else default, keys.split("."), dictionary)
+
+
+def find_instance(dict_: dict, class_type: Any) -> Any:
+    """
+    Find the first instance of a class in a dictionary.
+
+    Args:
+        dict_ (dict): The dictionary to search.
+        class_type (Any): The class type to find.
+
+    Returns:
+        Any: The first instance of the class found in the dictionary, or None if no instance is found.
+    """
+    values = [value for value in dict_.values(
+    ) if isinstance(value, class_type)]
+    return values[0] if len(values) > 0 else None
+
+
+def get_argument_value(func: Callable, args: tuple, kwargs: dict, param_name: str) -> Any:
+    """
+    Gets an argument value from the arguments or keyword arguments of a function.
+
+    Args:
+        func (Callable): The function to get the argument value from.
+        args (tuple): The arguments of the function.
+        kwargs (dict): The keyword arguments of the function.
+        param_name (str): The parameter name to get the value for.
+
+    Raises:
+        ValueError: If the parameter name is not found in the function signature.
+        Exception: If any TypeError is found while getting the argument
+
+    Returns:
+        Any: The argument value
+    """
+    try:
+        sig = signature(func)
+        bound_args = sig.bind(*args, **kwargs)
+        bound_args.apply_defaults()
+
+        # 0. Check if one of the arguments is an instance of EvaluationState
+        from ..entities.state import EvaluationState
+        state_var = find_instance(dict_=bound_args.arguments,
+                                  class_type=EvaluationState)
+        if state_var is not None:
+            if not hasattr(state_var, param_name):
+                raise ValueError(
+                    f"'{param_name}' attribute missing from the state.")
+            return getattr(state_var, param_name)
+
+        # 1. Check if one of the arguments is named "state"
+        if "state" in bound_args.arguments:
+            state_var = bound_args.arguments.get("state")
+
+        #   1.1 If yes, check if the argument type is a BaseModel or Dict
+        #   1.1.1.1 If BaseModel, get the argument value from state's attribute. If not present, throw error.
+            if isinstance(state_var, BaseModel):
+                if not hasattr(state_var, param_name):
+                    raise ValueError(
+                        f"'{param_name}' attribute missing from the state.")
+                return getattr(state_var, param_name)
+        #   1.1.1.2 If Dict, get the argument value from state's key. If not present, throw error.
+            if isinstance(state_var, dict):
+                if param_name not in state_var:
+                    raise ValueError(
+                        f"'{param_name}' key missing from the state.")
+                return state_var[param_name]
+        #   1.1.1 If not, no-op. Continue below
+
+        # 2. Check if the argument is passed as a keyword argument. If not present, throw error.
+        if param_name not in bound_args.arguments:
+            raise ValueError(
+                f"{param_name} argument missing from the function.")
+
+        return bound_args.arguments.get(param_name)
+    except TypeError as te:
+        raise Exception(
+            f"Got an error while getting {param_name} argument.") from te
+
+
+T = TypeVar("T")
+
+
+def add_if_unique(obj: T, obj_list: List[T], keys: List[str], aggregate_keys: Optional[List] = None) -> None:
+    """
+    Add an object to a list only if there is no existing object that matches all the specified keys.
+    If a matching object exists, it aggregates values from the provided `aggregate_keys`
+    into the existing object, rather than adding a new entry.
+
+    Args:
+        obj: The object to potentially add to the list
+        obj_list: The list to which the object may be added
+        keys: A list of attribute names to check for uniqueness
+        aggregate_keys: A list of attribute names for which values from the `obj` will be aggregated into the existing object
+
+    """
+    # Check if any existing object matches all keys
+    for existing_obj in obj_list:
+        matches_all_keys = True
+        for key in keys:
+            if not hasattr(obj, key) or not hasattr(existing_obj, key):
+                matches_all_keys = False
+                break
+            if getattr(obj, key) != getattr(existing_obj, key):
+                matches_all_keys = False
+                break
+
+        if matches_all_keys:
+            # Found a match, don't add the object
+            # If list of aggregated keys are provided, add the values to existing object
+            if aggregate_keys:
+                for agg_key in aggregate_keys:
+                    if hasattr(existing_obj, agg_key) and hasattr(obj, agg_key):
+                        new_value = getattr(obj, agg_key)
+                        existing_value = getattr(existing_obj, agg_key)
+
+                        # Handle cases values are stored as a list, set or single value
+                        if isinstance(existing_value, list):
+                            # if isinstance(new_value, list):
+                            #     existing_value.extend(new_value)
+                            # else:
+                            #     existing_value.append(new_value)
+                            # TODO: ensure uniqueness
+                            pass
+                        elif isinstance(existing_value, set):
+                            if isinstance(new_value, (list, set)):
+                                existing_value.update(new_value)
+                            else:
+                                existing_value.add(new_value)
+                        else:
+                            setattr(existing_obj, agg_key, new_value)
+            return
+
+    # No match found, add the object to the list
+    obj_list.append(obj)
+
+
+def transform_str_to_list(input_str: str) -> list[str]:
+    """
+    Parse the context columns correctly and make sure it is a list and not a string. This is intended
+    to be used with pd.DataFrame.apply() method. Specifically, in some cased where values are read from
+    csv files and cells are intended to contain a list, pandas will parse them as strings, this helper
+    would parse them as expected
+
+    Args:
+        input_str (str): the cell content
+
+    Returns:
+        list of strings
+
+    """
+    contexts_list = []
+    # The input is a list already, no need to update it
+    if isinstance(input_str, list):
+        contexts_list = input_str
+
+    # The input is parsed as a string, check if it is lateral array and parse it, other wise add it to a list and return it
+    elif isinstance(input_str, str):
+        try:
+            contexts_list = json.loads(input_str)
+        except json.decoder.JSONDecodeError:
+            # The user only gave one context column
+            contexts_list = [input_str]
+
+    return contexts_list if contexts_list else [""]
+
+
+def build_openai_schema(tool_instance):
+    schema = tool_instance.args_schema.schema()
+    return {
+        "name": tool_instance.name,
+        "description": tool_instance.description or inspect.getdoc(tool_instance.__class__),
+        "parameters": schema
+    }
+
+
+def parse_functions_to_openai_schema(func: Callable) -> dict:
+    """
+    Converts a callable function into a structured schema for LLM tool calling.
+
+    Extracts function metadata including name, description, parameters, parameter types,
+    and required parameters.
+    Returns the schema in OpenAI-compatible format with 'type': 'function' and nested structure.
+    """
+    try:
+        if isinstance(func, BaseTool):
+            cur_openai_tool = convert_to_openai_function(func.args_schema)
+            properties = get(cur_openai_tool, "parameters.properties", {})
+            required = get(cur_openai_tool, "parameters.required", [])
+
+            return {
+                "type": "function",
+                "function": {
+                    "name": func.name,
+                    "description": func.description,
+                    "parameters": {
+                        "type": "object",
+                        "properties": properties,
+                        "required": required,
+                    }
+                }
+            }
+
+        elif callable(func):
+            sig = signature(func)
+            properties = {}
+            required = []
+
+            for name, param in sig.parameters.items():
+                param_schema = {"type": "string"}  # default fallback
+
+                if param.annotation != param.empty:
+                    param_schema = convert_python_type_to_openai_schema(
+                        param.annotation)
+
+                properties[name] = param_schema
+
+                # Identify required parameters (not Optional and no default)
+                origin = get_origin(param.annotation)
+                args = get_args(param.annotation)
+                if not (origin is Union and type(None) in args) and param.default is param.empty:
+                    required.append(name)
+
+            return {
+                "type": "function",
+                "function": {
+                    "name": func.__name__,
+                    "description": func.__doc__ or "No description available",
+                    "parameters": {
+                        "type": "object",
+                        "properties": properties,
+                        "required": required,
+                    }
+                }
+            }
+
+        else:
+            raise ValueError(f"Unsupported tool type: {type(func)}")
+
+    except Exception as ex:
+        raise Exception(f"Error while parsing {func}: {ex}")
+
+
+def convert_python_type_to_openai_schema(param_type):
+    """Convert a Python type into an OpenAPI-like schema."""
+    if param_type == str:
+        return {"type": "string"}
+    elif param_type == int:
+        return {"type": "integer"}
+    elif param_type == float:
+        return {"type": "number"}
+    elif param_type == bool:
+        return {"type": "boolean"}
+    elif isinstance(param_type, type) and issubclass(param_type, enum.Enum):
+        return {
+            "type": "string",
+            "enum": [e.value for e in param_type],
+        }
+    else:
+        origin = get_origin(param_type)
+        args = get_args(param_type)
+
+        if origin is Union:
+            # Handle Optional[X] == Union[X, NoneType]
+            non_none_args = [arg for arg in args if arg is not type(None)]
+            if len(non_none_args) == 1:
+                return convert_python_type_to_openai_schema(non_none_args[0])
+            else:
+                # Complex unions; fallback to string
+                return {"type": "string"}
+        elif origin in (list, List):
+            # Handle lists
+            # Assume list of strings if unspecified
+            item_type = args[0] if args else str
+            return {
+                "type": "array",
+                "items": convert_python_type_to_openai_schema(item_type),
+            }
+        elif origin in (dict, Dict):
+            # Handle dicts (simplified: assume dict[str, Any])
+            return {
+                "type": "object"
+            }
+        else:
+            # Unknown complex type
+            return {"type": "string"}
+
+
+def get_environment_variable_value(possible_env_variables: list, default=None) -> str | None:
+    """
+    Helper to get environment variable based on list of option. This will return the first
+    found value, otherwise None
+
+    Args:
+        possible_env_variables (list[str]): list of environment variable to find
+    Returns:
+        str | None: the first found value, otherwise None
+    """
+    for env_key in possible_env_variables:
+        env_value = os.getenv(env_key)
+
+        if env_value:
+            return env_value
+    return default
+
+
+def replace_none_with_empty_string(a_list: list):
+    """
+    Recursively replaces all None values in a nested list structure with empty strings.
+
+   Args:
+        a_list (list): The input list that may contain None values and nested lists.
+                      Can be None itself (function will handle this case).
+
+    Returns:
+        list: The modified list with all None values replaced by empty strings.
+              Returns None if the input list is None.
+    """
+    if a_list is not None:
+        for i, n in enumerate(a_list):
+            if isinstance(n, list):
+                n = replace_none_with_empty_string(n)
+            if n is None:
+                a_list[i] = ""
+    return a_list
+
+
+def get_authenticator_token(authenticator: Authenticator) -> str:
+    """
+    Helper to retrieve the authenticator token.
+
+    Args:
+        authenticator: Authenticator object from ibm_cloud_sdk_core.
+
+    Returns:
+        Bearer token string.
+    """
+    if isinstance(authenticator, BearerTokenAuthenticator):
+        return authenticator.bearer_token
+    else:
+        try:
+            return authenticator.token_manager.get_token()
+        except Exception as e:
+            raise Exception(f"Failed to get token from authenticator. {e}")
+
+@contextmanager
+def track_duration(name: str):
+    """
+    Track execution duration
+    """
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        elapsed = time.perf_counter() - start
+        logger.info(f"Computed {name} in {elapsed:.3f}s")
+

ibm_watsonx_gov/utils/rest_util.py

@@ -0,0 +1,73 @@
+# ----------------------------------------------------------------------------------------------------
+# 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.
+# ----------------------------------------------------------------------------------------------------
+
+# Supress info and warning logs from requests and urllib3
+import logging
+from http import HTTPStatus
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+logging.getLogger("requests").setLevel(logging.CRITICAL)
+logging.getLogger("urllib3").setLevel(logging.CRITICAL)
+
+
+class RestUtil:
+
+    RETRY_COUNT = 6
+    BACK_OFF_FACTOR = 0.5
+    RETRY_AFTER_STATUS_CODES = (
+        HTTPStatus.BAD_GATEWAY,
+        HTTPStatus.SERVICE_UNAVAILABLE,
+        HTTPStatus.GATEWAY_TIMEOUT)
+
+    @staticmethod
+    def override_response_encoding(r, *args, **kwargs):
+        if r.encoding is None:
+            r.encoding = 'utf-8'
+        return r
+
+    @classmethod
+    def request_with_retry(cls, session=None, method_list=[], retry_count=RETRY_COUNT, **kwargs):
+        session = session or requests.Session()
+        session.hooks['response'].append(RestUtil.override_response_encoding)
+        if kwargs.get("verify_ssl") is False:
+            session.verify = False
+
+        # some requests might want to pass other status on which they have to be retried.
+        # such status should be passed as a tuple
+        additional_retry_status_codes = kwargs.get(
+            "additional_retry_status_codes", None)
+        if additional_retry_status_codes:
+            cls.RETRY_AFTER_STATUS_CODES = cls.RETRY_AFTER_STATUS_CODES + \
+                additional_retry_status_codes
+        # Get connection retry count from arguments. If not provided, default to retry_count.
+        connect_retry_count = kwargs.get(
+            "connect_retry_count", retry_count)
+        #  Construct an iterable set of method to retry.
+        method_list = {item for item in method_list +
+                       list(Retry.DEFAULT_ALLOWED_METHODS)}
+
+        back_off_factor = cls.BACK_OFF_FACTOR
+        if kwargs.get("back_off_factor") is not None:
+            back_off_factor = kwargs.get("back_off_factor")
+        retry = Retry(
+            total=retry_count,
+            read=retry_count,
+            connect=connect_retry_count,
+            allowed_methods=method_list,
+            # Time delay between requests is calculated using
+            # {backoff factor} * (2 ^ ({number of total retries} - 1)) seconds
+            backoff_factor=back_off_factor,
+            status_forcelist=cls.RETRY_AFTER_STATUS_CODES,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        session.mount("https://", adapter)
+        return session

ibm_watsonx_gov/utils/segment_batch_manager.py

@@ -0,0 +1,162 @@
+# ----------------------------------------------------------------------------------------------------
+# 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 asyncio
+import atexit
+import os
+import threading
+import time
+from typing import Dict, List
+
+from ibm_watsonx_gov.clients.segment_client import SegmentClient
+from ibm_watsonx_gov.utils.async_util import (gather_with_concurrency,
+                                              run_in_event_loop)
+from ibm_watsonx_gov.utils.gov_sdk_logger import GovSDKLogger
+
+logger = GovSDKLogger.get_logger(__name__)
+
+SEGMENT_BATCH_LIMIT = 10
+SEGMENT_BATCH_INTERVAL = 5  # seconds
+
+
+class SegmentBatchManager:
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls, api_client=None):
+        """Ensure singleton instance across evaluators."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._instance._initialize(api_client)
+            return cls._instance
+
+    def _initialize(self, api_client=None):
+        self.api_client = api_client
+        self.queue: asyncio.Queue[Dict] | None = None
+        self._stop_event = asyncio.Event()
+        self._thread = None
+        self._thread_loop: asyncio.AbstractEventLoop | None = None
+        # Start a background worker thread
+        self._start_background_worker()
+
+        # Auto-stop on process exit
+        atexit.register(self._shutdown)
+
+    def _start_background_worker(self):
+        """
+        Start a background thread with its own event loop to batch and send events.
+        This allows non-blocking event tracking from the other event tasks.
+        """
+
+        def runner():
+            """
+            Start a new event loop in a separate thread.
+            """
+            loop = asyncio.new_event_loop()
+            self._thread_loop = loop
+            asyncio.set_event_loop(loop)
+
+            self.queue = asyncio.Queue()
+            self._stop_event = asyncio.Event()
+
+            # Run the worker until stopped
+            loop.run_until_complete(self.worker())
+
+        # Start the thread as a daemon
+        self._thread = threading.Thread(target=runner, daemon=True)
+        self._thread.start()
+
+    async def track_event(self, event: Dict):
+        """Add event to queue."""
+
+        if os.getenv("WATSONX_SERVER") in ["WXO", "WXAI", "WXGOV"]:
+            return
+
+        if self.api_client is None:
+            return
+
+        if self.api_client.is_cpd:
+            return
+
+        if not hasattr(self.api_client, "wos_client"):
+            return
+
+        if not hasattr(self.api_client.wos_client, "service_instance_id"):
+            return
+
+        data = {
+            "event": "API Call",
+            "properties": {
+                "productCodeType": "WWPC",
+                "ut30": "30A5Q",
+                "productTitle": "watsonx governance",
+                "productCode": "WW0170",
+                "custom.triggered_by": "watsonx gov sdk",
+                "region": self.api_client.credentials.region or "us-south",
+                "instanceID": self.api_client.wos_client.service_instance_id,
+                "productPlan": self.api_client.wos_client.plan_name,
+                **event
+            },
+            "integrations": {
+                "Amplitude": {
+                    "groups": {
+                        "Instance": self.api_client.wos_client.service_instance_id
+                    }
+                }
+            }
+        }
+
+        # Thread-safe submission to background loop
+        if self._thread_loop and self.queue:
+            fut = asyncio.run_coroutine_threadsafe(
+                self.queue.put(data), self._thread_loop
+            )
+            await asyncio.wrap_future(fut)
+
+    def _shutdown(self):
+        """Stop worker at process exit."""
+        if self._thread_loop and self._stop_event:
+            self._thread_loop.call_soon_threadsafe(self._stop_event.set)
+
+    async def worker(self):
+        """Background loop: batch and send events."""
+        buffer: List[Dict] = []
+        last_flush = time.time()
+
+        while True:
+            # Exit when stop event set and queue empty
+            if self._stop_event.is_set() and self.queue.empty():
+                break
+
+            try:
+                event = await self.queue.get()
+                buffer.append(event)
+            except asyncio.TimeoutError:
+                pass  # loop back and check stop_event
+
+            if buffer and (
+                len(buffer) >= SEGMENT_BATCH_LIMIT
+                or time.time() - last_flush >= SEGMENT_BATCH_INTERVAL
+            ):
+                success = await self._flush_async(buffer)
+                if success:
+                    buffer.clear()
+                    last_flush = time.time()
+
+        if buffer:
+            success = await self._flush_async(buffer)
+            if success:
+                buffer.clear()
+
+    async def _flush_async(self, events: List[Dict]):
+        if not events:
+            return True
+        logger.info(f"Flushing {len(events)} events")
+        segment_client = SegmentClient(self.api_client.wos_client)
+        return await segment_client.trigger_segment_endpoint(segment_data=events)

ibm_watsonx_gov/utils/singleton_meta.py

@@ -0,0 +1,25 @@
+# ----------------------------------------------------------------------------------------------------
+# 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 threading import Lock
+
+from pydantic._internal._model_construction import ModelMetaclass
+
+
+class SingletonMeta(ModelMetaclass):
+    _instances = {}
+    _lock: Lock = Lock()
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            with cls._lock:
+                if cls not in cls._instances:
+                    instance = super().__call__(*args, **kwargs)
+                    cls._instances[cls] = instance
+        return cls._instances[cls]