rasa-pro 3.12.0.dev1__py3-none-any.whl

rasa/shared/providers/_configs/utils.py

@@ -0,0 +1,117 @@
+import structlog
+from rasa.shared.utils.io import raise_deprecation_warning
+
+structlogger = structlog.get_logger()
+
+
+def resolve_aliases(config: dict, deprecated_alias_mapping: dict) -> dict:
+    """
+    Resolve aliases in the configuration to standard keys.
+
+    Args:
+        config: Dictionary containing the configuration.
+        deprecated_alias_mapping: Dictionary mapping aliases to
+            their standard keys.
+
+    Returns:
+        New dictionary containing the processed configuration.
+    """
+    config = config.copy()
+
+    for alias, standard_key in deprecated_alias_mapping.items():
+        # We check for the alias instead of the standard key because our goal is to
+        # update the standard key when the alias is found. Since the standard key is
+        # always included in the default component configurations, we overwrite it
+        # with the alias value if the alias exists.
+        if alias in config:
+            config[standard_key] = config.pop(alias)
+
+    return config
+
+
+def raise_deprecation_warnings(config: dict, deprecated_alias_mapping: dict) -> None:
+    """
+    Raises warnings for deprecated keys in the configuration.
+
+    Args:
+        config: Dictionary containing the configuration.
+        deprecated_alias_mapping: Dictionary mapping deprecated keys to
+            their standard keys.
+
+    Raises:
+        DeprecationWarning: If any deprecated key is found in the config.
+    """
+    for alias, standard_key in deprecated_alias_mapping.items():
+        if alias in config:
+            raise_deprecation_warning(
+                message=(
+                    f"'{alias}' is deprecated and will be removed in "
+                    f"4.0.0. Use '{standard_key}' instead."
+                )
+            )
+
+
+def validate_required_keys(config: dict, required_keys: list) -> None:
+    """
+    Validates that the passed config contains all the required keys.
+
+    Args:
+        config: Dictionary containing the configuration.
+        required_keys: List of keys that must be present in the config.
+
+    Raises:
+        ValueError: If any required key is missing.
+    """
+    missing_keys = [key for key in required_keys if key not in config]
+    if missing_keys:
+        message = f"Missing required keys '{missing_keys}' for configuration."
+        structlogger.error(
+            "validate_required_keys",
+            message=message,
+            missing_keys=missing_keys,
+            config=config,
+        )
+        raise ValueError(message)
+
+
+def validate_forbidden_keys(config: dict, forbidden_keys: list) -> None:
+    """
+    Validates that the passed config doesn't contain any forbidden keys.
+
+    Args:
+        config: Dictionary containing the configuration.
+        forbidden_keys: List of keys that are forbidden in the config.
+
+    Raises:
+        ValueError: If any forbidden key is present.
+    """
+    forbidden_keys_in_config = set(config.keys()).intersection(set(forbidden_keys))
+
+    if forbidden_keys_in_config:
+        message = (
+            f"Forbidden keys '{forbidden_keys_in_config}' present "
+            f"in the configuration."
+        )
+        structlogger.error(
+            "validate_forbidden_keys",
+            message=message,
+            forbidden_keys=forbidden_keys_in_config,
+            config=config,
+        )
+        raise ValueError(message)
+
+
+def get_provider_prefixed_model_name(provider: str, model: str) -> str:
+    """
+    Returns the model name with the provider prefixed.
+
+    Args:
+        provider: The provider of the model.
+        model: The model name.
+
+    Returns:
+        The model name with the provider prefixed.
+    """
+    if model and f"{provider}/" not in model:
+        return f"{provider}/{model}"
+    return model

rasa/shared/providers/_ssl_verification_utils.py

@@ -0,0 +1,124 @@
+import os
+from typing import Optional, Union
+
+import httpx
+import litellm
+from rasa.shared.constants import (
+    RASA_CA_BUNDLE_ENV_VAR,
+    REQUESTS_CA_BUNDLE_ENV_VAR,
+    RASA_SSL_CERTIFICATE_ENV_VAR,
+    LITELLM_SSL_VERIFY_ENV_VAR,
+    LITELLM_SSL_CERTIFICATE_ENV_VAR,
+)
+
+import structlog
+
+from rasa.shared.utils.io import raise_deprecation_warning
+
+structlogger = structlog.get_logger()
+
+
+def ensure_ssl_certificates_for_litellm_non_openai_based_clients() -> None:
+    """
+    Ensure SSL certificates configuration for LiteLLM based on environment
+    variables for clients that are not utilizing OpenAI's clients from
+    `openai` library.
+    """
+    ssl_verify = _get_ssl_verify()
+    ssl_certificate = _get_ssl_cert()
+
+    structlogger.debug(
+        "ensure_ssl_certificates_for_litellm_non_openai_based_clients",
+        ssl_verify=ssl_verify,
+        ssl_certificate=ssl_certificate,
+    )
+
+    if ssl_verify is not None:
+        litellm.ssl_verify = ssl_verify
+    if ssl_certificate is not None:
+        litellm.ssl_certificate = ssl_certificate
+
+
+def ensure_ssl_certificates_for_litellm_openai_based_clients() -> None:
+    """
+    Ensure SSL certificates configuration for LiteLLM based on environment
+    variables for clients that are utilizing OpenAI's clients from
+    `openai` library.
+
+    The ssl configuration is ensured by setting `litellm.client_session` and
+    `litellm.aclient_session` if not previously set.
+    """
+    client_args = {}
+
+    ssl_verify = _get_ssl_verify()
+    ssl_certificate = _get_ssl_cert()
+
+    structlogger.debug(
+        "ensure_ssl_certificates_for_litellm_openai_based_clients",
+        ssl_verify=ssl_verify,
+        ssl_certificate=ssl_certificate,
+    )
+
+    if ssl_verify is not None:
+        client_args["verify"] = ssl_verify
+    if ssl_certificate is not None:
+        client_args["cert"] = ssl_certificate
+
+    if client_args and not isinstance(litellm.aclient_session, httpx.AsyncClient):
+        litellm.aclient_session = httpx.AsyncClient(**client_args)
+    if client_args and not isinstance(litellm.client_session, httpx.Client):
+        litellm.client_session = httpx.Client(**client_args)
+
+
+def _get_ssl_verify() -> Optional[Union[bool, str]]:
+    """
+    Environment variable priority (ssl verify):
+    1. `RASA_CA_BUNDLE`: Preferred for SSL verification.
+    2. `REQUESTS_CA_BUNDLE`: Deprecated; use `RASA_CA_BUNDLE_ENV_VAR` instead.
+    3. `SSL_VERIFY`: Fallback for SSL verification.
+
+    Returns:
+        Path to a self-signed SSL certificate or None if no SSL certificate is found.
+    """
+    if os.environ.get(REQUESTS_CA_BUNDLE_ENV_VAR) and os.environ.get(
+        RASA_CA_BUNDLE_ENV_VAR
+    ):
+        raise_deprecation_warning(
+            "Both REQUESTS_CA_BUNDLE and RASA_CA_BUNDLE environment variables are set. "
+            "RASA_CA_BUNDLE will be used as the SSL verification path.\n"
+            "Support of the REQUESTS_CA_BUNDLE environment variable is deprecated and "
+            "will be removed in Rasa Pro 4.0.0. Please set the RASA_CA_BUNDLE "
+            "environment variable instead."
+        )
+    elif os.environ.get(REQUESTS_CA_BUNDLE_ENV_VAR):
+        raise_deprecation_warning(
+            "Support of the REQUESTS_CA_BUNDLE environment variable is deprecated and "
+            "will be removed in Rasa Pro 4.0.0. Please set the RASA_CA_BUNDLE "
+            "environment variable instead."
+        )
+
+    return (
+        os.environ.get(RASA_CA_BUNDLE_ENV_VAR)
+        # Deprecated
+        or os.environ.get(REQUESTS_CA_BUNDLE_ENV_VAR)
+        # From LiteLLM, use as a fallback
+        or os.environ.get(LITELLM_SSL_VERIFY_ENV_VAR)
+        or None
+    )
+
+
+def _get_ssl_cert() -> Optional[str]:
+    """
+    Environment variable priority (ssl certificate):
+    1. `RASA_SSL_CERTIFICATE`: Preferred for client certificate.
+    2. `SSL_CERTIFICATE`: Fallback for client certificate.
+
+    Returns:
+        Path to a SSL certificate or None if no SSL certificate is found.
+    """
+    return (
+        os.environ.get(RASA_SSL_CERTIFICATE_ENV_VAR)
+        # From LiteLLM, use as a fallback
+        or os.environ.get(LITELLM_SSL_CERTIFICATE_ENV_VAR)
+        or None
+    )

rasa/shared/providers/_utils.py

@@ -0,0 +1,79 @@
+import structlog
+
+from rasa.shared.constants import (
+    AWS_ACCESS_KEY_ID_ENV_VAR,
+    AWS_ACCESS_KEY_ID_CONFIG_KEY,
+    AWS_SECRET_ACCESS_KEY_ENV_VAR,
+    AWS_SECRET_ACCESS_KEY_CONFIG_KEY,
+    AWS_REGION_NAME_ENV_VAR,
+    AWS_REGION_NAME_CONFIG_KEY,
+    AWS_SESSION_TOKEN_CONFIG_KEY,
+    AWS_SESSION_TOKEN_ENV_VAR,
+)
+from rasa.shared.exceptions import ProviderClientValidationError
+from litellm import validate_environment
+from rasa.shared.providers.embedding._base_litellm_embedding_client import (
+    _VALIDATE_ENVIRONMENT_MISSING_KEYS_KEY,
+)
+
+structlogger = structlog.get_logger()
+
+
+def validate_aws_setup_for_litellm_clients(
+    litellm_model_name: str, litellm_call_kwargs: dict, source_log: str
+) -> None:
+    """Validates the AWS setup for LiteLLM clients to ensure all required
+    environment variables or corresponding call kwargs are set.
+
+    Args:
+        litellm_model_name (str): The name of the LiteLLM model being validated.
+        litellm_call_kwargs (dict): Additional keyword arguments passed to the client,
+            which may include configuration values for AWS credentials.
+        source_log (str): The source log identifier for structured logging.
+
+    Raises:
+        ProviderClientValidationError: If any required AWS environment variable
+            or corresponding configuration key is missing.
+    """
+
+    # Mapping of environment variable names to their corresponding config keys
+    envs_to_args = {
+        AWS_ACCESS_KEY_ID_ENV_VAR: AWS_ACCESS_KEY_ID_CONFIG_KEY,
+        AWS_SECRET_ACCESS_KEY_ENV_VAR: AWS_SECRET_ACCESS_KEY_CONFIG_KEY,
+        AWS_REGION_NAME_ENV_VAR: AWS_REGION_NAME_CONFIG_KEY,
+        AWS_SESSION_TOKEN_ENV_VAR: AWS_SESSION_TOKEN_CONFIG_KEY,
+    }
+
+    # Validate the environment setup for the model
+    validation_info = validate_environment(litellm_model_name)
+    missing_environment_variables = validation_info.get(
+        _VALIDATE_ENVIRONMENT_MISSING_KEYS_KEY, []
+    )
+    # Filter out missing environment variables that have been set trough arguments
+    # in extra parameters
+    missing_environment_variables = [
+        missing_env_var
+        for missing_env_var in missing_environment_variables
+        if litellm_call_kwargs.get(envs_to_args.get(missing_env_var)) is None
+    ]
+
+    if missing_environment_variables:
+        missing_environment_details = [
+            (
+                f"'{missing_env_var}' environment variable or "
+                f"'{envs_to_args.get(missing_env_var)}' config key"
+            )
+            for missing_env_var in missing_environment_variables
+        ]
+        event_info = (
+            f"The following environment variables or configuration keys are "
+            f"missing: "
+            f"{', '.join(missing_environment_details)}. "
+            f"These settings are required for API calls."
+        )
+        structlogger.error(
+            f"{source_log}.validate_aws_environment_variables",
+            event_info=event_info,
+            missing_environment_variables=missing_environment_variables,
+        )
+        raise ProviderClientValidationError(event_info)

rasa/shared/providers/constants.py

@@ -0,0 +1,7 @@
+DEFAULT_AZURE_API_KEY_NAME = "AZURE_API_KEY"
+LITE_LLM_API_BASE_FIELD = "api_base"
+LITE_LLM_API_KEY_FIELD = "api_key"
+LITE_LLM_API_VERSION_FIELD = "api_version"
+LITE_LLM_MODEL_FIELD = "model"
+LITE_LLM_AZURE_AD_TOKEN_PROVIDER = "azure_ad_token_provider"
+LITE_LLM_AZURE_AD_TOKEN = "azure_ad_token"

rasa/shared/providers/embedding/_base_litellm_embedding_client.py

@@ -0,0 +1,243 @@
+import logging
+from abc import abstractmethod
+from typing import Any, Dict, List
+
+import litellm
+import structlog
+from litellm import aembedding, embedding, validate_environment
+
+from rasa.shared.constants import API_BASE_CONFIG_KEY, API_KEY
+from rasa.shared.exceptions import (
+    ProviderClientAPIException,
+    ProviderClientValidationError,
+)
+from rasa.shared.providers._ssl_verification_utils import (
+    ensure_ssl_certificates_for_litellm_non_openai_based_clients,
+    ensure_ssl_certificates_for_litellm_openai_based_clients,
+)
+from rasa.shared.providers.embedding.embedding_response import (
+    EmbeddingResponse,
+    EmbeddingUsage,
+)
+from rasa.shared.utils.io import suppress_logs, resolve_environment_variables
+
+structlogger = structlog.get_logger()
+
+_VALIDATE_ENVIRONMENT_MISSING_KEYS_KEY = "missing_keys"
+
+
+class _BaseLiteLLMEmbeddingClient:
+    """An abstract base class for LiteLLM embedding clients.
+
+    This class defines the interface and common functionality for all clients
+    based on LiteLLM.
+
+    The class is made private to prevent it from being part of the
+    public-facing interface, as it serves as an internal base class
+    for specific implementations of clients that are currently based on
+    LiteLLM.
+
+    By keeping it private, we ensure that only the derived, concrete
+    implementations are exposed to users, maintaining a cleaner and
+    more controlled API surface.
+    """
+
+    def __init__(self):  # type: ignore
+        self._ensure_certificates()
+
+    @property
+    @abstractmethod
+    def config(self) -> dict:
+        """Returns the configuration for that the embedding client in dict form."""
+        pass
+
+    @property
+    @abstractmethod
+    def _litellm_model_name(self) -> str:
+        """Returns the model name in LiteLLM format based on the Provider/API type."""
+        pass
+
+    @property
+    @abstractmethod
+    def _litellm_extra_parameters(self) -> Dict[str, Any]:
+        """Returns a dictionary of extra parameters which include model
+        parameters as well as LiteLLM specific input parameters.
+        By default, this returns an empty dictionary (no extra parameters).
+        """
+        return {}
+
+    @property
+    def _embedding_fn_args(self) -> Dict[str, Any]:
+        """Returns the arguments to be passed to the embedding function."""
+        return {
+            **self._litellm_extra_parameters,
+            "model": self._litellm_model_name,
+        }
+
+    def validate_client_setup(self) -> None:
+        """Perform client validation. By default only environment variables
+        are validated. Override this method to add more validation steps.
+
+        Raises:
+            ProviderClientValidationError if validation fails.
+        """
+        self._validate_environment_variables()
+
+    def _validate_environment_variables(self) -> None:
+        """Validate that the required environment variables are set."""
+        validation_info = validate_environment(
+            self._litellm_model_name,
+            api_key=self._litellm_extra_parameters.get(API_KEY),
+            api_base=self._litellm_extra_parameters.get(API_BASE_CONFIG_KEY),
+        )
+        if missing_environment_variables := validation_info.get(
+            _VALIDATE_ENVIRONMENT_MISSING_KEYS_KEY
+        ):
+            event_info = (
+                f"Environment variables: {missing_environment_variables} "
+                f"not set. Required for API calls."
+            )
+            structlogger.error(
+                "base_litellm_embedding_client.validate_environment_variables",
+                event_info=event_info,
+                missing_environment_variables=missing_environment_variables,
+            )
+            raise ProviderClientValidationError(event_info)
+
+    def validate_documents(self, documents: List[str]) -> None:
+        """Validates a list of documents to ensure they are suitable for embedding.
+
+        Args:
+            documents: List of documents to be validated.
+
+        Raises:
+            ValueError: If any document is invalid.
+        """
+        for doc in documents:
+            if not isinstance(doc, str):
+                raise ValueError("All documents must be strings.")
+            if not doc.strip():
+                raise ValueError("Documents cannot be empty or whitespace.")
+
+    @suppress_logs(log_level=logging.WARNING)
+    def embed(self, documents: List[str]) -> EmbeddingResponse:
+        """Embeds a list of documents synchronously.
+
+        Args:
+            documents: List of documents to be embedded.
+
+        Returns:
+            List of embedding vectors.
+
+        Raises:
+            ProviderClientAPIException: If API calls raised an error.
+        """
+        self.validate_documents(documents)
+        try:
+            arguments = resolve_environment_variables(self._embedding_fn_args)
+            response = embedding(input=documents, **arguments)
+            return self._format_response(response)
+        except Exception as e:
+            raise ProviderClientAPIException(
+                message="Failed to embed documents", original_exception=e
+            )
+
+    @suppress_logs(log_level=logging.WARNING)
+    async def aembed(self, documents: List[str]) -> EmbeddingResponse:
+        """Embeds a list of documents asynchronously.
+
+        Args:
+            documents: List of documents to be embedded.
+
+        Returns:
+            List of embedding vectors.
+
+        Raises:
+            ProviderClientAPIException: If API calls raised an error.
+        """
+        self.validate_documents(documents)
+        try:
+            arguments = resolve_environment_variables(self._embedding_fn_args)
+            response = await aembedding(input=documents, **arguments)
+            return self._format_response(response)
+        except Exception as e:
+            raise ProviderClientAPIException(
+                message="Failed to embed documents", original_exception=e
+            )
+
+    def _format_response(
+        self, response: litellm.EmbeddingResponse
+    ) -> EmbeddingResponse:
+        """Parses the LiteLLM EmbeddingResponse to Rasa format.
+
+        Raises:
+            ValueError: If any response data is None.
+        """
+        # If data is not available (None), raise a ValueError
+        if response.data is None:
+            message = (
+                "Failed to embed documents. Received 'None' " "instead of embeddings."
+            )
+            structlogger.error(
+                "base_litellm_client.format_response.data_is_none",
+                message=message,
+                response=response.to_dict(),
+            )
+            raise ValueError(message)
+
+        # Sort the embeddings by the "index" key
+        response.data.sort(key=lambda x: x["index"])
+        # Extract the embedding vectors
+        embeddings = [data["embedding"] for data in response.data]
+        formatted_response = EmbeddingResponse(
+            data=embeddings,
+            model=response.model,
+        )
+
+        # Process additional usage information if available
+        if response.usage:
+            completion_tokens = (
+                response.usage.completion_tokens
+                if hasattr(response.usage, "completion_tokens")
+                else 0
+            )
+            prompt_tokens = (
+                response.usage.prompt_tokens
+                if hasattr(response.usage, "prompt_tokens")
+                else 0
+            )
+            total_tokens = (
+                response.usage.total_tokens
+                if hasattr(response.usage, "total_tokens")
+                else 0
+            )
+
+            formatted_response.usage = EmbeddingUsage(
+                completion_tokens=completion_tokens,
+                prompt_tokens=prompt_tokens,
+                total_tokens=total_tokens,
+            )
+
+        # Log the response with masked data for brevity
+        log_response = formatted_response.to_dict()
+        log_response["data"] = "Embedding response data not shown here for brevity."
+        structlogger.debug(
+            "base_litellm_client.formatted_response",
+            formatted_response=log_response,
+        )
+        return formatted_response
+
+    @staticmethod
+    def _ensure_certificates() -> None:
+        """Configures SSL certificates for LiteLLM. This method is invoked during
+        client initialization.
+
+        LiteLLM may utilize `openai` clients or other providers that require
+        SSL verification settings through the `SSL_VERIFY` / `SSL_CERTIFICATE`
+        environment variables or the `litellm.ssl_verify` /
+        `litellm.ssl_certificate` global settings.
+
+        This method ensures proper SSL configuration for both cases.
+        """
+        ensure_ssl_certificates_for_litellm_non_openai_based_clients()
+        ensure_ssl_certificates_for_litellm_openai_based_clients()

rasa/shared/providers/embedding/_langchain_embedding_client_adapter.py

@@ -0,0 +1,74 @@
+from typing import List
+
+from langchain_core.embeddings.embeddings import Embeddings
+
+from rasa.shared.providers.embedding.embedding_client import EmbeddingClient
+
+
+class _LangchainEmbeddingClientAdapter(Embeddings):
+    """
+    Temporary adapter to bridge differences between LiteLLM and LangChain.
+
+    Clients instantiated with `embedder_factory` follow our new EmbeddingClient
+    protocol, but `langchain`'s vector stores require an `Embeddings` type
+    client. This adapter extracts and returns the necessary part of the output
+    from our LiteLLM-based clients.
+
+    This adapter will be removed in ticket:
+    https://rasahq.atlassian.net/browse/ENG-1220
+    """
+
+    def __init__(self, client: EmbeddingClient):
+        self._client = client
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Embed search docs.
+
+        Args:
+            texts: List of text to embed.
+
+        Returns:
+            List of embeddings.
+        """
+        response = self._client.embed(documents=texts)
+        embedding_vector = response.data
+        return embedding_vector
+
+    def embed_query(self, text: str) -> List[float]:
+        """Embed query text.
+
+        Args:
+            text: Text to embed.
+
+        Returns:
+            Embedding.
+        """
+        response = self._client.embed(documents=[text])
+        embedding_vector = response.data[0]
+        return embedding_vector
+
+    async def aembed_documents(self, texts: List[str]) -> List[List[float]]:
+        """Asynchronous Embed search docs.
+
+        Args:
+            texts: List of text to embed.
+
+        Returns:
+            List of embeddings.
+        """
+        response = await self._client.aembed(documents=texts)
+        embedding_vector = response.data
+        return embedding_vector
+
+    async def aembed_query(self, text: str) -> List[float]:
+        """Asynchronous Embed query text.
+
+        Args:
+            text: Text to embed.
+
+        Returns:
+            Embedding.
+        """
+        response = await self._client.aembed(documents=[text])
+        embedding_vector = response.data[0]
+        return embedding_vector