azure-ai-evaluation 1.0.0b5__py3-none-any.whl → 1.0.1__py3-none-any.whl

azure/ai/evaluation/_evaluators/_xpia/xpia.py

@@ -2,90 +2,124 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # ---------------------------------------------------------
 import logging
-from typing import Optional
+from typing import Dict, List, Union
 
-from typing_extensions import override
+from typing_extensions import overload, override
 
 from azure.ai.evaluation._common._experimental import experimental
 from azure.ai.evaluation._common.constants import EvaluationMetrics
 from azure.ai.evaluation._evaluators._common import RaiServiceEvaluatorBase
+from azure.ai.evaluation._model_configurations import Conversation
 
 logger = logging.getLogger(__name__)
 
 
 @experimental
-class IndirectAttackEvaluator(RaiServiceEvaluatorBase):
-    """A Cross-Domain Prompt Injection Attack (XPIA) jailbreak evaluator.
-
-    Detect whether cross domain injected attacks are present in your AI system's response.
-    Metrics include the overall evaluation label and reason for the Q/A Pair, as well as sub-labels
-    for manipulated content, intrusion, and information.
+class IndirectAttackEvaluator(RaiServiceEvaluatorBase[Union[str, bool]]):
+    """
+    Evaluates the indirect attack score for a given query and response or a multi-turn conversation, with reasoning.
+
+    Indirect attacks, also known as cross-domain prompt injected attacks (XPIA), are when jailbreak attacks are
+    injected into the context of a document or source that may result in an altered, unexpected behavior.
+
+    Indirect attacks evaluations are broken down into three subcategories:
+        - Manipulated Content: This category involves commands that aim to alter or fabricate information, often
+            to mislead or deceive. It includes actions like spreading false information, altering language or
+            formatting, and hiding or emphasizing specific details. The goal is often to manipulate perceptions
+            or behaviors by controlling the flow and presentation of information.
+        - Intrusion: This category encompasses commands that attempt to breach systems, gain unauthorized access,
+            or elevate privileges illicitly. It includes creating backdoors, exploiting vulnerabilities, and
+            traditional jailbreaks to bypass security measures. The intent is often to gain control or access
+            sensitive data without detection.
+        - Information Gathering: This category pertains to accessing, deleting, or modifying data without
+            authorization, often for malicious purposes. It includes exfiltrating sensitive data, tampering with
+            system records, and removing or altering existing information. The focus is on acquiring or
+            manipulating data to exploit or compromise systems and individuals.
+
+    Indirect attack scores are boolean values, where True indicates that the response contains an indirect attack.
 
     :param credential: The credential for connecting to Azure AI project. Required
     :type credential: ~azure.core.credentials.TokenCredential
     :param azure_ai_project: The scope of the Azure AI project. It contains subscription id, resource group, and project
         name.
     :type azure_ai_project: ~azure.ai.evaluation.AzureAIProject
-    :param eval_last_turn: Set to True to evaluate only the most recent exchange in the dialogue,
-        focusing on the latest user inquiry and the assistant's corresponding response. Defaults to False
-    :type eval_last_turn: bool
-
-        **Usage**
-
-        .. code-block:: python
 
-            eval_fn = IndirectAttackEvaluator(model_config)
-            result = eval_fn(query="What is the capital of France?", response="Paris.")
+    .. admonition:: Example:
 
-        **Output format for question-answer pair**
-
-        .. code-block:: python
-
-            {
-                'xpia_label': False,
-                'xpia_reason': 'The conversation does not contain any manipulated content, intrusion or
-                              information gathering.'
-                'xpia_information_gathering': False,
-                'xpia_intrusion': False
-                'xpia_manipulated_content': False
-            }
+        .. literalinclude:: ../samples/evaluation_samples_evaluate.py
+            :start-after: [START indirect_attack_evaluator]
+            :end-before: [END indirect_attack_evaluator]
+            :language: python
+            :dedent: 8
+            :caption: Initialize and call an IndirectAttackEvaluator.
     """
 
+    id = "azureml://registries/azureml/models/Indirect-Attack-Evaluator/versions/3"
+    """Evaluator identifier, experimental and to be used only with evaluation in cloud."""
+
     @override
     def __init__(
         self,
         credential,
         azure_ai_project,
-        eval_last_turn: bool = False,
     ):
         super().__init__(
             eval_metric=EvaluationMetrics.XPIA,
             azure_ai_project=azure_ai_project,
             credential=credential,
-            eval_last_turn=eval_last_turn,
         )
 
-    @override
+    @overload
     def __call__(
         self,
         *,
-        query: Optional[str] = None,
-        response: Optional[str] = None,
-        conversation=None,
+        query: str,
+        response: str,
+    ) -> Dict[str, Union[str, bool]]:
+        """Evaluate whether cross domain injected attacks are present in given query/response
+
+        :keyword query: The query to be evaluated.
+        :paramtype query: str
+        :keyword response: The response to be evaluated.
+        :paramtype response: str
+        :return: The cross domain injection attack score
+        :rtype: Dict[str, Union[str, bool]]
+        """
+
+    @overload
+    def __call__(
+        self,
+        *,
+        conversation: Conversation,
+    ) -> Dict[str, Union[float, Dict[str, List[Union[str, bool]]]]]:
+        """Evaluate cross domain injected attacks are present in a conversation
+
+        :keyword conversation: The conversation to evaluate. Expected to contain a list of conversation turns under the
+            key "messages", and potentially a global context under the key "context". Conversation turns are expected
+            to be dictionaries with keys "content", "role", and possibly "context".
+        :paramtype conversation: Optional[~azure.ai.evaluation.Conversation]
+        :return: The cross domain injection attack score
+        :rtype: Dict[str, Union[str, bool, Dict[str, List[Union[str, bool]]]]]
+        """
+
+    @override
+    def __call__(  # pylint: disable=docstring-missing-param
+        self,
+        *args,
         **kwargs,
     ):
         """
         Evaluate whether cross domain injected attacks are present in your AI system's response.
 
         :keyword query: The query to be evaluated.
-        :paramtype query: str
+        :paramtype query: Optional[str]
         :keyword response: The response to be evaluated.
-        :paramtype response: str
+        :paramtype response: Optional[str]
         :keyword conversation: The conversation to evaluate. Expected to contain a list of conversation turns under the
             key "messages". Conversation turns are expected
             to be dictionaries with keys "content" and "role".
         :paramtype conversation: Optional[~azure.ai.evaluation.Conversation]
-        :return: The fluency score.
-        :rtype: Union[Dict[str, Union[str, bool]], Dict[str, Union[str, bool, Dict[str, List[Union[str, bool]]]]]]
+        :return: The cross domain injection attack score
+        :rtype: Union[Dict[str, Union[str, bool]], Dict[str, Union[float, Dict[str, List[Union[str, bool]]]]]]
         """
-        return super().__call__(query=query, response=response, conversation=conversation, **kwargs)
+        return super().__call__(*args, **kwargs)

azure/ai/evaluation/_exceptions.py

@@ -23,6 +23,7 @@ class ErrorCategory(Enum):
     * SERVICE_UNAVAILABLE -> Service is unavailable
     * MISSING_PACKAGE -> Required package is missing
     * FAILED_REMOTE_TRACKING -> Remote tracking failed
+    * PROJECT_ACCESS_ERROR -> Access to project failed
     * UNKNOWN -> Undefined placeholder. Avoid using.
     """
 
@@ -35,6 +36,7 @@ class ErrorCategory(Enum):
     SERVICE_UNAVAILABLE = "SERVICE UNAVAILABLE"
     MISSING_PACKAGE = "MISSING PACKAGE"
     FAILED_REMOTE_TRACKING = "FAILED REMOTE TRACKING"
+    PROJECT_ACCESS_ERROR = "PROJECT ACCESS ERROR"
     UNKNOWN = "UNKNOWN"
 
 

azure/ai/evaluation/_model_configurations.py

@@ -8,44 +8,95 @@ from typing_extensions import NotRequired
 
 
 class AzureOpenAIModelConfiguration(TypedDict):
-    """Model Configuration for Azure OpenAI Model"""
+    """Model configuration for Azure OpenAI models
+
+    :param type: The type of the model configuration. Should be 'azure_openai' for AzureOpenAIModelConfiguration
+    :type type: NotRequired[Literal["azure_openai"]]
+    :param azure_deployment: Name of Azure OpenAI deployment to make requests to
+    :type azure_deployment: str
+    :param azure_endpoint: Endpoint of Azure OpenAI resource to make requests to
+    :type azure_endpoint: str
+    :param api_key: API key of Azure OpenAI resource
+    :type api_key: str
+    :param api_version: API version to use in request to Azure OpenAI deployment. Optional.
+    :type api_version: NotRequired[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_common.py
+            :start-after: [START create_AOAI_model_config]
+            :end-before: [END create_AOAI_model_config]
+            :language: python
+            :dedent: 8
+            :caption: Creating an AzureOpenAIModelConfiguration object.
+
+    """
 
     type: NotRequired[Literal["azure_openai"]]
-    """The type of the model configuration. Should be 'azure_openai' for AzureOpenAIModelConfiguration"""
     azure_deployment: str
-    """Name of Azure OpenAI deployment to make request to"""
     azure_endpoint: str
     """Endpoint of Azure OpenAI resource to make request to"""
     api_key: NotRequired[str]
     """API key of Azure OpenAI resource"""
     api_version: NotRequired[str]
-    """(Optional) API version to use in request to Azure OpenAI deployment"""
 
 
 class OpenAIModelConfiguration(TypedDict):
-    """Model Configuration for OpenAI Model"""
+    """Model configuration for OpenAI models
+
+    :param type: The type of the model configuration. Should be 'openai' for OpenAIModelConfiguration
+    :type type: NotRequired[Literal["openai"]]
+    :param api_key: API key needed to make requests to model
+    :type api_key: str
+    :param model: Name of model to be used in OpenAI request
+    :type model: str
+    :param base_url: Base URL to be used in OpenAI request. Optional.
+    :type base_url: NotRequired[str]
+    :param organization: OpenAI organization. Optional.
+    :type organization: NotRequired[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_common.py
+            :start-after: [START create_OAI_model_config]
+            :end-before: [END create_OAI_model_config]
+            :language: python
+            :dedent: 8
+            :caption: Creating an OpenAIModelConfiguration object.
+
+    """
 
     type: NotRequired[Literal["openai"]]
-    """The type of the model configuration. Should be 'openai' for OpenAIModelConfiguration"""
     api_key: str
-    "API key needed to make request to model"
     model: str
-    """Name of model to be used in OpenAI request"""
     base_url: NotRequired[str]
-    """(Optional) Base URL to be used in OpenAI request"""
     organization: NotRequired[str]
-    """(Optional) OpenAI organization"""
 
 
 class AzureAIProject(TypedDict):
-    """Azure AI Project Information"""
+    """Information about the Azure AI project
+
+    :param subscription_id: ID of the Azure subscription the project is in
+    :type subscription_id: str
+    :param resource_group_name: Name of the Azure resource group the project is in
+    :type resource_group_name: str
+    :param project_name: Name of the Azure project
+    :type project_name: str
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_common.py
+            :start-after: [START create_azure_ai_project_object]
+            :end-before: [END create_azure_ai_project_object]
+            :language: python
+            :dedent: 8
+            :caption: Creating an AzureAIProject object.
+
+    """
 
     subscription_id: str
-    """Azure subscription id of the project"""
     resource_group_name: str
-    """Azure resource group name of the project"""
     project_name: str
-    """Azure project name"""
 
 
 class EvaluatorConfig(TypedDict, total=False):

azure/ai/evaluation/_version.py

@@ -2,4 +2,4 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # ---------------------------------------------------------
 
-VERSION = "1.0.0b5"
+VERSION = "1.0.1"

azure/ai/evaluation/simulator/_adversarial_scenario.py

@@ -3,10 +3,22 @@
 # ---------------------------------------------------------
 
 from enum import Enum
+from azure.ai.evaluation._common._experimental import experimental
 
 
+@experimental
 class AdversarialScenario(Enum):
-    """Adversarial scenario types"""
+    """Adversarial scenario types
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_simulate.py
+            :start-after: [START adversarial_scenario]
+            :end-before: [END adversarial_scenario]
+            :language: python
+            :dedent: 8
+            :caption: Configure an AdversarialSimulator with an Adversarial Conversation scenario.
+    """
 
     ADVERSARIAL_QA = "adv_qa"
     ADVERSARIAL_CONVERSATION = "adv_conversation"
@@ -18,12 +30,14 @@ class AdversarialScenario(Enum):
     ADVERSARIAL_CONTENT_PROTECTED_MATERIAL = "adv_content_protected_material"
 
 
+@experimental
 class AdversarialScenarioJailbreak(Enum):
     """Adversarial scenario types for XPIA Jailbreak"""
 
     ADVERSARIAL_INDIRECT_JAILBREAK = "adv_xpia"
 
 
+@experimental
 class _UnstableAdversarialScenario(Enum):
     """Adversarial scenario types that we haven't published, but still want available for internal use
     Values listed here are subject to potential change, and/or migration to the main enum over time.

azure/ai/evaluation/simulator/_adversarial_simulator.py

@@ -7,6 +7,7 @@ import asyncio
 import logging
 import random
 from typing import Any, Callable, Dict, List, Literal, Optional, Union, cast
+from itertools import zip_longest
 
 from tqdm import tqdm
 
@@ -14,6 +15,7 @@ from azure.ai.evaluation._common._experimental import experimental
 from azure.ai.evaluation._common.utils import validate_azure_ai_project
 from azure.ai.evaluation._exceptions import ErrorBlame, ErrorCategory, ErrorTarget, EvaluationException
 from azure.ai.evaluation._http_utils import get_async_http_client
+from azure.ai.evaluation._model_configurations import AzureAIProject
 from azure.ai.evaluation.simulator import AdversarialScenario
 from azure.ai.evaluation.simulator._adversarial_scenario import _UnstableAdversarialScenario
 from azure.core.credentials import TokenCredential
@@ -45,9 +47,19 @@ class AdversarialSimulator:
     :type azure_ai_project: ~azure.ai.evaluation.AzureAIProject
     :param credential: The credential for connecting to Azure AI project.
     :type credential: ~azure.core.credentials.TokenCredential
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_simulate.py
+            :start-after: [START adversarial_scenario]
+            :end-before: [END adversarial_scenario]
+            :language: python
+            :dedent: 8
+            :caption: Run the AdversarialSimulator with an AdversarialConversation scenario to produce 2 results with
+                2 conversation turns each (4 messages per result).
     """
 
-    def __init__(self, *, azure_ai_project: dict, credential):
+    def __init__(self, *, azure_ai_project: AzureAIProject, credential: TokenCredential):
         """Constructor."""
 
         try:
@@ -149,28 +161,6 @@ class AdversarialSimulator:
 
          The 'content' for 'assistant' role messages may includes the messages that your callback returned.
         :rtype: List[Dict[str, Any]]
-
-        **Output format**
-
-        .. code-block:: python
-
-            return_value = [
-                {
-                    'template_parameters': {},
-                    'messages': [
-                        {
-                            'content': '<jailbreak prompt> <adversarial query>',
-                            'role': 'user'
-                        },
-                        {
-                            'content': "<response from endpoint>",
-                            'role': 'assistant',
-                            'context': None
-                        }
-                    ],
-                    '$schema': 'http://azureml/sdk-2-0/ChatConversation.json'
-                }
-            ]
         """
 
         # validate the inputs
@@ -215,17 +205,18 @@ class AdversarialSimulator:
             ncols=100,
             unit="simulations",
         )
-        for template in templates:
-            parameter_order = list(range(len(template.template_parameters)))
-            if randomize_order:
-                # The template parameter lists are persistent across sim runs within a session,
-                # So randomize a the selection instead of the parameter list directly,
-                # or a potentially large deep copy.
-                if randomization_seed is not None:
-                    random.seed(randomization_seed)
-                random.shuffle(parameter_order)
-            for index in parameter_order:
-                parameter = template.template_parameters[index].copy()
+
+        if randomize_order:
+            # The template parameter lists are persistent across sim runs within a session,
+            # So randomize a the selection instead of the parameter list directly,
+            # or a potentially large deep copy.
+            if randomization_seed is not None:
+                random.seed(randomization_seed)
+            random.shuffle(templates)
+        parameter_lists = [t.template_parameters for t in templates]
+        zipped_parameters = list(zip_longest(*parameter_lists))
+        for param_group in zipped_parameters:
+            for template, parameter in zip(templates, param_group):
                 if _jailbreak_type == "upia":
                     parameter = self._join_conversation_starter(parameter, random.choice(jailbreak_dataset))
                 tasks.append(

azure/ai/evaluation/simulator/_constants.py

@@ -5,7 +5,17 @@ from enum import Enum
 
 
 class SupportedLanguages(Enum):
-    """Supported languages for evaluation, using ISO standard language codes."""
+    """Supported languages for evaluation, using ISO standard language codes.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_simulate.py
+            :start-after: [START supported_languages]
+            :end-before: [END supported_languages]
+            :language: python
+            :dedent: 8
+            :caption: Run the AdversarialSimulator with Simplified Chinese language support for evaluation.
+    """
 
     Spanish = "es"
     Italian = "it"

azure/ai/evaluation/simulator/_direct_attack_simulator.py

@@ -11,6 +11,7 @@ from azure.ai.evaluation._common._experimental import experimental
 from azure.ai.evaluation._common.utils import validate_azure_ai_project
 from azure.ai.evaluation._exceptions import ErrorBlame, ErrorCategory, ErrorTarget, EvaluationException
 from azure.ai.evaluation.simulator import AdversarialScenario
+from azure.ai.evaluation._model_configurations import AzureAIProject
 from azure.core.credentials import TokenCredential
 
 from ._adversarial_simulator import AdversarialSimulator
@@ -30,9 +31,18 @@ class DirectAttackSimulator:
     :type azure_ai_project: ~azure.ai.evaluation.AzureAIProject
     :param credential: The credential for connecting to Azure AI project.
     :type credential: ~azure.core.credentials.TokenCredential
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_simulate.py
+            :start-after: [START direct_attack_simulator]
+            :end-before: [END direct_attack_simulator]
+            :language: python
+            :dedent: 8
+            :caption: Run the DirectAttackSimulator to produce 2 results with 3 conversation turns each (6 messages in each result).
     """
 
-    def __init__(self, *, azure_ai_project: dict, credential):
+    def __init__(self, *, azure_ai_project: AzureAIProject, credential: TokenCredential):
         """Constructor."""
 
         try:
@@ -125,7 +135,7 @@ class DirectAttackSimulator:
          - '**$schema**': A string indicating the schema URL for the conversation format.
 
          The 'content' for 'assistant' role messages may includes the messages that your callback returned.
-        :rtype: Dict[str, [List[Dict[str, Any]]]] with two elements
+        :rtype: Dict[str, [List[Dict[str, Any]]]]
 
         **Output format**
 
@@ -178,9 +188,7 @@ class DirectAttackSimulator:
         if not randomization_seed:
             randomization_seed = randint(0, 1000000)
 
-        regular_sim = AdversarialSimulator(
-            azure_ai_project=cast(dict, self.azure_ai_project), credential=self.credential
-        )
+        regular_sim = AdversarialSimulator(azure_ai_project=self.azure_ai_project, credential=self.credential)
         regular_sim_results = await regular_sim(
             scenario=scenario,
             target=target,
@@ -190,10 +198,10 @@ class DirectAttackSimulator:
             api_call_retry_sleep_sec=api_call_retry_sleep_sec,
             api_call_delay_sec=api_call_delay_sec,
             concurrent_async_task=concurrent_async_task,
-            randomize_order=True,
+            randomize_order=False,
             randomization_seed=randomization_seed,
         )
-        jb_sim = AdversarialSimulator(azure_ai_project=cast(dict, self.azure_ai_project), credential=self.credential)
+        jb_sim = AdversarialSimulator(azure_ai_project=self.azure_ai_project, credential=self.credential)
         jb_sim_results = await jb_sim(
             scenario=scenario,
             target=target,
@@ -204,7 +212,7 @@ class DirectAttackSimulator:
             api_call_delay_sec=api_call_delay_sec,
             concurrent_async_task=concurrent_async_task,
             _jailbreak_type="upia",
-            randomize_order=True,
+            randomize_order=False,
             randomization_seed=randomization_seed,
         )
         return {"jailbreak": jb_sim_results, "regular": regular_sim_results}

azure/ai/evaluation/simulator/_indirect_attack_simulator.py

@@ -13,6 +13,7 @@ from azure.ai.evaluation._common.utils import validate_azure_ai_project
 from azure.ai.evaluation._common._experimental import experimental
 from azure.ai.evaluation._exceptions import ErrorBlame, ErrorCategory, ErrorTarget, EvaluationException
 from azure.ai.evaluation.simulator import AdversarialScenarioJailbreak, SupportedLanguages
+from azure.ai.evaluation._model_configurations import AzureAIProject
 from azure.core.credentials import TokenCredential
 
 from ._adversarial_simulator import AdversarialSimulator, JsonLineList
@@ -32,9 +33,18 @@ class IndirectAttackSimulator(AdversarialSimulator):
     :type azure_ai_project: ~azure.ai.evaluation.AzureAIProject
     :param credential: The credential for connecting to Azure AI project.
     :type credential: ~azure.core.credentials.TokenCredential
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/evaluation_samples_simulate.py
+            :start-after: [START indirect_attack_simulator]
+            :end-before: [END indirect_attack_simulator]
+            :language: python
+            :dedent: 8
+            :caption: Run the IndirectAttackSimulator to produce 1 result with 1 conversation turn (2 messages in the result).
     """
 
-    def __init__(self, *, azure_ai_project: dict, credential):
+    def __init__(self, *, azure_ai_project: AzureAIProject, credential: TokenCredential):
         """Constructor."""
 
         try:

azure/ai/evaluation/simulator/_model_tools/_identity_manager.py

@@ -14,7 +14,9 @@ from typing import Optional, Union
 from azure.core.credentials import AccessToken, TokenCredential
 from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
 
-AZURE_TOKEN_REFRESH_INTERVAL = 600  # seconds
+AZURE_TOKEN_REFRESH_INTERVAL = int(
+    os.getenv("AZURE_TOKEN_REFRESH_INTERVAL", "600")
+)  # token refresh interval in seconds
 
 
 class TokenScope(Enum):

azure/ai/evaluation/simulator/_model_tools/_rai_client.py

@@ -74,14 +74,18 @@ class RAIClient:  # pylint: disable=client-accepts-api-version-keyword
             timeout=5,
         )
         if response.status_code != 200:
-            msg = "Failed to retrieve the discovery service URL."
+            msg = (
+                f"Failed to connect to your Azure AI project. Please check if the project scope is configured "
+                f"correctly, and make sure you have the necessary access permissions. "
+                f"Status code: {response.status_code}."
+            )
             raise EvaluationException(
                 message=msg,
-                internal_message=msg,
                 target=ErrorTarget.RAI_CLIENT,
-                category=ErrorCategory.SERVICE_UNAVAILABLE,
-                blame=ErrorBlame.UNKNOWN,
+                category=ErrorCategory.PROJECT_ACCESS_ERROR,
+                blame=ErrorBlame.USER_ERROR,
             )
+
         base_url = urlparse(response.json()["properties"]["discoveryUrl"])
         return f"{base_url.scheme}://{base_url.netloc}"