ibm-watsonx-orchestrate 1.0.0__py3-none-any.whl

ibm_watsonx_orchestrate/client/client_errors.py

@@ -0,0 +1,359 @@
+#  -----------------------------------------------------------------------------------------
+#  (C) Copyright IBM Corp. 2023-2024.
+#  https://opensource.org/licenses/BSD-3-Clause
+#  -----------------------------------------------------------------------------------------
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+import logging
+import sys
+import re
+
+if TYPE_CHECKING:
+    from requests import Response
+
+__all__ = [
+    "ClientError",
+    "MissingValue",
+    "MissingMetaProp",
+    "NotUrlNorID",
+    "NoCredentialsProvided",
+    "ApiRequestFailure",
+    "UnexpectedType",
+    "ForbiddenActionForPlan",
+    "NoVirtualDeploymentSupportedForICP",
+    "MissingArgument",
+    "WrongEnvironmentVersion",
+    "CannotAutogenerateBedrockUrl",
+    "WrongMetaProps",
+    "CannotSetProjectOrSpace",
+    "ForbiddenActionForGitBasedProject",
+    "CannotInstallLibrary",
+    "DataStreamError",
+    "WrongLocationProperty",
+    "WrongFileLocation",
+    "EmptyDataSource",
+    "SpaceIDandProjectIDCannotBeNone",
+    "ParamOutOfRange",
+    "InvalidMultipleArguments",
+    "ValidationError",
+    "InvalidValue",
+    "PromptVariablesError",
+    "UnsupportedOperation",
+    "MissingExtension",
+    "InvalidCredentialsError",
+]
+
+
+class ClientError(Exception):
+    def __init__(
+        self,
+        error_msg: str,
+        reason: str | list | None = None,
+        logg_messages: bool = True,
+    ):
+        # Check if URL contains `internal` or `private` in host part of URL and hide it
+        pattern = (
+            r"\b((?:[a-z][\w-]+:(?:/{1,3}|[a-z0-9%])|www\d{0,3}[.]|[a-z0-9.\-]+[.][a-z]{2,4}/)"
+            r"(?:[\w.-]*(internal|private)[^\s]*))"
+        )
+        self.error_msg = re.sub(
+            pattern,
+            lambda m: f"[{m.group(2).capitalize()} URL]",
+            str(error_msg),
+            re.IGNORECASE,
+        )
+        self.reason = reason
+        if logg_messages:
+            logging.getLogger(__name__).warning(self.__str__())
+            logging.getLogger(__name__).debug(
+                str(self.error_msg)
+                + (
+                    "\nReason: " + str(self.reason)
+                    if sys.exc_info()[0] is not None
+                    else ""
+                )
+            )
+
+    def __str__(self) -> str:
+        return str(self.error_msg) + (
+            "\nReason: " + str(self.reason) if self.reason is not None else ""
+        )
+
+
+class MissingValue(ClientError, ValueError):
+    def __init__(self, value_name: str, reason: str | None = None):
+        ClientError.__init__(self, 'No "' + value_name + '" provided.', reason)
+
+
+class MissingMetaProp(MissingValue):
+    def __init__(self, name: str, reason: str | None = None):
+        ClientError.__init__(
+            self, "Missing meta_prop with name: '{}'.".format(name), reason
+        )
+
+
+class NotUrlNorID(ClientError, ValueError):
+    def __init__(self, value_name: str, value: str, reason: str | None = None):
+        ClientError.__init__(
+            self,
+            "Invalid value of '{}' - it is not url nor id: '{}'".format(
+                value_name, value
+            ),
+            reason,
+        )
+
+
+class NoCredentialsProvided(MissingValue):
+    def __init__(self, reason: str | None = None):
+        MissingValue.__init__(self, "WML credentials", reason)
+
+
+class ApiRequestFailure(ClientError):
+    def __init__(self, error_msg: str, response: Response, reason: str | None = None):
+        self.response = response
+        if str(response.status_code) == "404" and "DOCTYPE" in str(response.content):
+            raise MissingWMLComponent()
+
+        elif str(
+            response.status_code
+        ) == "400" and "Invalid content. You cannot include any tags in the HTTP request." in str(
+            response.content
+        ):
+            ClientError.__init__(
+                self,
+                f"Please check if any parameter that you provided include HTTP tag. "
+                f"If yes, please remove it and try again.",
+                reason=str(response.content),
+            )
+
+        else:
+            ClientError.__init__(
+                self,
+                "{} ({} {})\nStatus code: {}, body: {}".format(
+                    error_msg,
+                    response.request.method,
+                    response.request.url,
+                    response.status_code,
+                    (
+                        response.text
+                        if response.apparent_encoding is not None
+                        else "[binary content, "
+                        + str(len(response.content))
+                        + " bytes]"
+                    ),
+                ),
+                reason,
+            )
+
+
+class UnexpectedType(ClientError, ValueError):
+    def __init__(self, el_name: str, expected_type: type, actual_type: type):
+        ClientError.__init__(
+            self,
+            "Unexpected type of '{}', expected: {}, actual: '{}'.".format(
+                el_name,
+                (
+                    "'{}'".format(expected_type)
+                    if type(expected_type) == type
+                    else expected_type
+                ),
+                actual_type,
+            ),
+        )
+
+
+class ForbiddenActionForPlan(ClientError):
+    def __init__(self, operation_name: str, expected_plans: list, actual_plan: str):
+        ClientError.__init__(
+            self,
+            "Operation '{}' is available only for {} plan, while this instance has '{}' plan.".format(
+                operation_name,
+                (
+                    (
+                        "one of {} as".format(expected_plans)
+                        if len(expected_plans) > 1
+                        else "'{}'".format(expected_plans[0])
+                    )
+                    if type(expected_plans) is list
+                    else "'{}'".format(expected_plans)
+                ),
+                actual_plan,
+            ),
+        )
+
+
+class NoVirtualDeploymentSupportedForICP(MissingValue):
+    def __init__(self, reason: str | None = None):
+        MissingValue.__init__(self, "No Virtual deployment supported for ICP", reason)
+
+
+class MissingArgument(ClientError, ValueError):
+    def __init__(self, value_name: str, reason: str | None = None):
+        ClientError.__init__(self, f"Argument: {value_name} missing.", reason)
+
+
+class WrongEnvironmentVersion(ClientError, ValueError):
+    def __init__(
+        self, used_version: str, environment_name: str, supported_versions: tuple
+    ):
+        ClientError.__init__(
+            self,
+            "Version used in credentials not supported in this environment",
+            reason=f"Version {used_version} isn't supported in "
+            f"{environment_name} environment, "
+            f"select from {supported_versions}",
+        )
+
+
+class CannotAutogenerateBedrockUrl(ClientError, ValueError):
+    def __init__(self, e1: Exception, e2: Exception):
+        ClientError.__init__(
+            self,
+            "Attempt of generating `bedrock_url` automatically failed. "
+            "If iamintegration=True, please provide `bedrock_url` in credentials. "
+            "If iamintegration=False, please validate your credentials.",
+            reason=[e1, e2],
+        )
+
+
+class WrongMetaProps(MissingValue):
+    def __init__(self, reason: str | None = None):
+        ClientError.__init__(self, "Wrong metaprops.", reason)
+
+
+class MissingWMLComponent(ClientError):
+    def __init__(self) -> None:
+        ClientError.__init__(
+            self,
+            f"Missing WML Component",
+            reason=f"It appears that WML component is not installed on your environment. "
+            f"Contact your cluster administrator.",
+        )
+
+
+class CannotSetProjectOrSpace(ClientError):
+    def __init__(self, reason: str):
+        ClientError.__init__(self, f"Cannot set Project or Space", reason=reason)
+
+
+class ForbiddenActionForGitBasedProject(ClientError):
+    def __init__(self, reason: str):
+        ClientError.__init__(
+            self, f"This action is not supported for git based project.", reason=reason
+        )
+
+
+class CannotInstallLibrary(ClientError, ValueError):
+    def __init__(self, lib_name: str, reason: str):
+        ClientError.__init__(
+            self,
+            f"Library '{lib_name}' cannot be installed! Please install it manually.",
+            reason,
+        )
+
+
+class DataStreamError(ClientError, ConnectionError):
+    def __init__(self, reason: str):
+        ClientError.__init__(
+            self, "Cannot fetch data via Flight Service. Try again.", reason
+        )
+
+
+class WrongLocationProperty(ClientError, ConnectionError):
+    def __init__(self, reason: str):
+        ClientError.__init__(
+            self, "Cannot fetch data via Flight Service. Try again.", reason
+        )
+
+
+class WrongFileLocation(ClientError, ValueError):
+    def __init__(self, reason: str):
+        ClientError.__init__(
+            self, "Cannot fetch data via Flight Service. Try again.", reason
+        )
+
+
+class EmptyDataSource(ClientError, ValueError):
+    def __init__(self) -> None:
+        ClientError.__init__(
+            self,
+            "Cannot fetch data via Flight Service. "
+            "Verify if data were saved under data connection and try again.",
+        )
+
+
+class SpaceIDandProjectIDCannotBeNone(ClientError, ValueError):
+    def __init__(self, reason: str):
+        ClientError.__init__(self, f"Missing 'space_id' or 'project_id'.", reason)
+
+
+class ParamOutOfRange(ClientError, ValueError):
+    def __init__(
+        self, param_name: str, value: int | float, min: int | float, max: int | float
+    ):
+        ClientError.__init__(
+            self,
+            f"Value of parameter `{param_name}`, {value}, is out of expected range - between {min} and {max}.",
+        )
+
+
+class InvalidMultipleArguments(ClientError, ValueError):
+    def __init__(self, params_names_list: list, reason: str | None = None):
+        ClientError.__init__(
+            self, f"One of {params_names_list} parameters should be set.", reason
+        )
+
+
+class ValidationError(ClientError, KeyError):
+    def __init__(self, key: str, additional_msg: str | None = None):
+        msg = (
+            f"Invalid prompt template; check for"
+            f" mismatched or missing input variables."
+            f" Missing input variable: {key}."
+        )
+        if additional_msg is not None:
+            msg += "\n" + additional_msg
+        ClientError.__init__(self, msg)
+
+
+class PromptVariablesError(ClientError, KeyError):
+    def __init__(self, key: str):
+        ClientError.__init__(
+            self,
+            (
+                f"Prompt template contains input variables."
+                f" Missing {key} in `prompt_variables`"
+            ),
+        )
+
+
+class InvalidValue(ClientError, ValueError):
+    def __init__(self, value_name: str, reason: str | None = None):
+        ClientError.__init__(
+            self, 'Inappropriate value of "' + value_name + '"', reason
+        )
+
+
+class UnsupportedOperation(ClientError):
+    def __init__(self, reason: str):
+        ClientError.__init__(
+            self, f"Operation is unsupported for this release.", reason
+        )
+
+
+class MissingExtension(ClientError, ImportError):
+    def __init__(self, extension_name: str):
+        ClientError.__init__(
+            self,
+            f"Could not import {extension_name}: Please install `{extension_name}` extension.",
+        )
+
+
+class InvalidCredentialsError(ClientError):
+    def __init__(self, reason: str | Response, logg_messages: bool = True):
+        ClientError.__init__(
+            self,
+            f"Attempt of authenticating connection to service failed, please validate your credentials. Error: {reason}",
+            logg_messages=logg_messages,
+        )

ibm_watsonx_orchestrate/client/connections/__init__.py

@@ -0,0 +1,10 @@
+from .connections_client import (
+    ConnectionAuthType,
+    ConnectionSecurityScheme,
+    ConnectionType
+)
+
+from .utils import (
+    get_connections_client,
+    get_connection_type
+)

ibm_watsonx_orchestrate/client/connections/connections_client.py

@@ -0,0 +1,162 @@
+from typing import List
+
+from pydantic import BaseModel, ValidationError
+from typing import Optional
+
+from ibm_watsonx_orchestrate.client.base_api_client import BaseAPIClient, ClientAPIException
+from ibm_watsonx_orchestrate.agent_builder.connections.types import ConnectionEnvironment, ConnectionPreference, ConnectionAuthType, ConnectionSecurityScheme, IdpConfigData, AppConfigData, ConnectionType
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+class ListConfigsResponse(BaseModel):
+    connection_id: str = None,
+    app_id: str = None
+    name: str = None
+    security_scheme: ConnectionSecurityScheme | None = None,
+    auth_type: ConnectionAuthType | None = None,
+    environment:  ConnectionEnvironment | None = None,
+    preference: ConnectionPreference | None = None,
+    credentials_entered: bool | None = False
+
+class GetConfigResponse(BaseModel):
+    config_id: str = None
+    tenant_id: str = None
+    app_id: str = None
+    environment: ConnectionEnvironment = None
+    preference: ConnectionPreference = None
+    auth_type: ConnectionAuthType | None = None
+    sso: bool = None
+    security_scheme: ConnectionSecurityScheme = None
+    server_url: str | None = None
+    idp_config_data: Optional[IdpConfigData] = None
+    app_config_data: Optional[AppConfigData] = None
+
+class GetConnectionResponse(BaseModel):
+    connection_id: str = None
+    app_id: str = None
+    tenant_id: str = None
+
+
+
+class ConnectionsClient(BaseAPIClient):
+    """
+    Client to handle CRUD operations for Connections endpoint
+    """
+    # POST api/v1/connections/applications
+    def create(self, payload: dict) -> None:
+        self._post("/connections/applications", data=payload)
+
+    # DELETE api/v1/connections/applications/{app_id}
+    def delete(self, app_id: str) -> dict:
+        return self._delete(f"/connections/applications/{app_id}")
+    
+    # GET /api/v1/connections/applications/{app_id}
+    def get(self, app_id: str) -> GetConnectionResponse:
+        try:
+            return GetConnectionResponse.model_validate(self._get(f"/connections/applications/{app_id}"))
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                return None
+            raise e
+    
+
+    # GET api/v1/connections/applications
+    def list(self) -> List[ListConfigsResponse]:
+        try:
+            res = self._get(f"/connections/applications")
+            return [ListConfigsResponse.model_validate(conn) for conn in res.get("applications", [])]
+        except ValidationError as e:
+            logger.error("Recieved unexpected response from server")
+            raise e
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                return []
+            raise e
+
+    
+    # POST /api/v1/connections/applications/{app_id}/configurations
+    def create_config(self, app_id: str, payload: dict) -> None:
+        self._post(f"/connections/applications/{app_id}/configurations", data=payload)
+    
+    # PATCH /api/v1/connections/applications/{app_id}/configurations/{env}
+    def update_config(self, app_id: str, env: ConnectionEnvironment, payload: dict) -> None:
+        self._patch(f"/connections/applications/{app_id}/configurations/{env}", data=payload)
+    
+    # `GET /api/v1/connections/applications/{app_id}/configurations/{env}'
+    def get_config(self, app_id: str, env: ConnectionEnvironment) -> GetConfigResponse:
+        try:
+            res = self._get(f"/connections/applications/{app_id}/configurations/{env}")
+            return GetConfigResponse.model_validate(res)
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                return None
+            raise e
+    
+    # POST /api/v1/connections/applications/{app_id}/configs/{env}/credentials
+    # POST /api/v1/connections/applications/{app_id}/configs/{env}/runtime_credentials
+    def create_credentials(self, app_id: str, env: ConnectionEnvironment, payload: dict, use_sso: bool) -> None:
+        if use_sso:
+            self._post(f"/connections/applications/{app_id}/configs/{env}/credentials", data=payload)
+        else:
+            self._post(f"/connections/applications/{app_id}/configs/{env}/runtime_credentials", data=payload)
+    
+    # PATCH /api/v1/connections/applications/{app_id}/configs/{env}/credentials
+    # PATCH /api/v1/connections/applications/{app_id}/configs/{env}/runtime_credentials
+    def update_credentials(self, app_id: str, env: ConnectionEnvironment, payload: dict, use_sso: bool) -> None:
+        if use_sso:
+            self._patch(f"/connections/applications/{app_id}/configs/{env}/credentials", data=payload)
+        else:
+            self._patch(f"/connections/applications/{app_id}/configs/{env}/runtime_credentials", data=payload)
+    
+    # GET /api/v1/connections/applications/{app_id}/configs/credentials?env={env}
+    # GET /api/v1/connections/applications/{app_id}/configs/runtime_credentials?env={env}
+    def get_credentials(self, app_id: str, env: ConnectionEnvironment, use_sso: bool) -> dict:
+        try:
+            if use_sso:
+                return self._get(f"/connections/applications/{app_id}/credentials?env={env}")
+            else:
+                return self._get(f"/connections/applications/{app_id}/configs/runtime_credentials?env={env}")
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                return None
+            raise e
+    
+    # DELETE /api/v1/connections/applications/{app_id}/configs/{env}/credentials
+    # DELETE /api/v1/connections/applications/{app_id}/configs/{env}/runtime_credentials
+    def delete_credentials(self, app_id: str, env: ConnectionEnvironment, use_sso: bool) -> None:
+        if use_sso:
+            self._delete(f"/connections/applications/{app_id}/configs/{env}/credentials")
+        else:
+            self._delete(f"/connections/applications/{app_id}/configs/{env}/runtime_credentials")
+    
+    def get_draft_by_app_id(self, app_id: str) -> GetConnectionResponse:
+        return self.get(app_id=app_id)
+
+    def get_draft_by_app_ids(self, app_ids: List[str]) -> List[GetConnectionResponse]:
+        connections = []
+        for app_id in app_ids:
+            connection = self.get_draft_by_app_id(app_id)
+            if connection:
+                connections += connection
+        return connections
+    
+    def get_draft_by_id(self, conn_id) -> str:
+        """Retrieve the app ID for a given connection ID."""
+        if conn_id is None:
+            return ""
+        try:
+            connections = self.list()
+        except ClientAPIException as e:
+            if e.response.status_code == 404:
+                logger.warning(f"Connections not found. Returning connection ID: {conn_id}")
+                return conn_id 
+            raise
+
+        app_id = next((conn.app_id for conn in connections if conn.connection_id == conn_id), None)
+
+        if app_id is None:
+            logger.warning(f"Connection with ID {conn_id} not found. Returning connection ID.")
+            return conn_id  
+        return app_id

ibm_watsonx_orchestrate/client/connections/utils.py

@@ -0,0 +1,27 @@
+from ibm_watsonx_orchestrate.client.utils import instantiate_client, is_local_dev
+from ibm_watsonx_orchestrate.client.connections.connections_client import ConnectionsClient
+from ibm_watsonx_orchestrate.cli.config import Config, ENVIRONMENTS_SECTION_HEADER, CONTEXT_SECTION_HEADER, CONTEXT_ACTIVE_ENV_OPT, ENV_WXO_URL_OPT
+from ibm_watsonx_orchestrate.agent_builder.connections.types import ConnectionType, ConnectionAuthType, ConnectionSecurityScheme
+
+LOCAL_CONNECTION_MANAGER_PORT = 3001
+
+def _get_connections_manager_url() -> str:
+    cfg = Config()
+    active_env = cfg.get(CONTEXT_SECTION_HEADER, CONTEXT_ACTIVE_ENV_OPT)
+    url = cfg.get(ENVIRONMENTS_SECTION_HEADER, active_env, ENV_WXO_URL_OPT)
+
+    if is_local_dev(url):
+        url_parts = url.split(":")
+        url_parts[-1] = str(LOCAL_CONNECTION_MANAGER_PORT)
+        url = ":".join(url_parts)
+        url = url + "/api/v1"
+        return url
+    return None
+
+def get_connections_client() -> ConnectionsClient:
+    return instantiate_client(client=ConnectionsClient, url=_get_connections_manager_url())
+
+def get_connection_type(security_scheme: ConnectionSecurityScheme, auth_type: ConnectionAuthType) -> ConnectionType:
+    if security_scheme != ConnectionSecurityScheme.OAUTH2:
+        return ConnectionType(security_scheme)
+    return ConnectionType(auth_type)

ibm_watsonx_orchestrate/client/credentials.py

@@ -0,0 +1,123 @@
+#  -----------------------------------------------------------------------------------------
+#  (C) Copyright IBM Corp. 2024.
+#  https://opensource.org/licenses/BSD-3-Clause
+#  -----------------------------------------------------------------------------------------
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+class Credentials:
+    """This class encapsulate passed credentials and additional params.
+
+    :param url: URL of the service
+    :type url: str
+
+    :param api_key: service API key used in API key authentication
+    :type api_key: str, optional
+
+    :param token: service token, used in token authentication
+    :type token: str, optional
+
+    :param verify: certificate verification flag
+    :type verify: bool, optional
+    """
+
+    def __init__(
+            self,
+            *,
+            url: str | None = None,
+            iam_url: str | None = None,
+            api_key: str | None = None,
+            token: str | None = None,
+            verify: str | bool | None = None,
+            auth_type: str | None = None,
+    ) -> None:
+        env_credentials = Credentials._get_values_from_env_vars()
+        self.url = url
+        self.iam_url = iam_url if iam_url is not None else "https://iam.platform.saas.ibm.com"
+        self.api_key = api_key
+        self.token = token
+        self.local_global_token = None
+        self.verify = verify
+        self.auth_type = auth_type
+        self._is_env_token = token is None and "token" in env_credentials
+
+        for k, v in env_credentials.items():
+            if self.__dict__.get(k) is None:
+                self.__dict__[k] = v
+
+    @staticmethod
+    def from_dict(dict: dict) -> Credentials:
+        creds = Credentials()
+        for k, v in dict.items():
+            setattr(creds, k, v)
+
+        return creds
+
+    @staticmethod
+    def _get_values_from_env_vars() -> dict[str, Any]:
+        def get_value_from_file(filename: str) -> str:
+            with open(filename, "r") as f:
+                return f.read()
+
+        def get_verify_value(x: str) -> bool | str:
+            if x in ["True", "False"]:
+                return x == "True"
+            else:
+                return x
+
+        env_vars_mapping = {
+            "WXO_CLIENT_VERIFY_REQUESTS": lambda x: ("verify", get_verify_value(x)),
+            "USER_ACCESS_TOKEN": lambda x: ("token", x.replace("Bearer ", "")),
+            "RUNTIME_ENV_ACCESS_TOKEN_FILE": lambda x: (
+                "token",
+                get_value_from_file(x).replace("Bearer ", ""),
+            ),
+            "WXO_URL": lambda x: ("url", x),
+        }
+
+        return dict(
+            [
+                f(os.environ[k])
+                for k, f in env_vars_mapping.items()
+                if os.environ.get(k) is not None and os.environ.get(k) != ""
+            ]
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Get dictionary from the Credentials object.
+
+        :return: dictionary with credentials
+        :rtype: dict
+
+        **Example**
+
+        .. code-block:: python
+
+            from ibm_watsonx_orchestrate import Credentials
+
+            credentials = Credentials.from_dict({
+                'url': "<url>",
+                'apikey': "<api_key>"
+            })
+
+            credentials_dict = credentials.to_dict()
+
+        """
+        data = dict(
+            [
+                (k, v)
+                for k, v in self.__dict__.items()
+                if v is not None and not k.startswith("_")
+            ]
+        )
+        return data
+
+    def __getitem__(self, key: str) -> Any:
+        return self.to_dict()[key]
+
+    def get(self, key: str, default: Any | None = None) -> Any:
+        return self.to_dict().get(key, default)