BedrockRuntime / Client / apply_guardrail

apply_guardrail#

BedrockRuntime.Client.apply_guardrail(**kwargs)#

The action to apply a guardrail.

For troubleshooting some of the common errors you might encounter when using the ApplyGuardrail API, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide

See also: AWS API Documentation

Request Syntax

response = client.apply_guardrail(
    guardrailIdentifier='string',
    guardrailVersion='string',
    source='INPUT'|'OUTPUT',
    content=[
        {
            'text': {
                'text': 'string',
                'qualifiers': [
                    'grounding_source'|'query'|'guard_content',
                ]
            },
            'image': {
                'format': 'png'|'jpeg',
                'source': {
                    'bytes': b'bytes'
                }
            }
        },
    ]
)
Parameters:

  • guardrailIdentifier (string) –

    [REQUIRED]

    The guardrail identifier used in the request to apply the guardrail.

  • guardrailVersion (string) –

    [REQUIRED]

    The guardrail version used in the request to apply the guardrail.

  • source (string) –

    [REQUIRED]

    The source of data used in the request to apply the guardrail.

  • content (list) –

    [REQUIRED]

    The content details used in the request to apply the guardrail.

    • (dict) –

      The content block to be evaluated by the guardrail.

      Note

      This is a Tagged Union structure. Only one of the following top level keys can be set: text, image.

      • text (dict) –

        Text within content block to be evaluated by the guardrail.

        • text (string) – [REQUIRED]

          The input text details to be evaluated by the guardrail.

        • qualifiers (list) –

          The qualifiers describing the text block.

          • (string) –

      • image (dict) –

        Image within guardrail content block to be evaluated by the guardrail.

        • format (string) – [REQUIRED]

          The format details for the file type of the image blocked by the guardrail.

        • source (dict) – [REQUIRED]

          The image source (image bytes) details of the image blocked by the guardrail.

          Note

          This is a Tagged Union structure. Only one of the following top level keys can be set: bytes.

          • bytes (bytes) –

            The bytes details of the guardrail image source. Object used in independent api.

Return type:

dict

Returns:

Response Syntax

{
    'usage': {
        'topicPolicyUnits': 123,
        'contentPolicyUnits': 123,
        'wordPolicyUnits': 123,
        'sensitiveInformationPolicyUnits': 123,
        'sensitiveInformationPolicyFreeUnits': 123,
        'contextualGroundingPolicyUnits': 123
    },
    'action': 'NONE'|'GUARDRAIL_INTERVENED',
    'outputs': [
        {
            'text': 'string'
        },
    ],
    'assessments': [
        {
            'topicPolicy': {
                'topics': [
                    {
                        'name': 'string',
                        'type': 'DENY',
                        'action': 'BLOCKED'
                    },
                ]
            },
            'contentPolicy': {
                'filters': [
                    {
                        'type': 'INSULTS'|'HATE'|'SEXUAL'|'VIOLENCE'|'MISCONDUCT'|'PROMPT_ATTACK',
                        'confidence': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'filterStrength': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'action': 'BLOCKED'
                    },
                ]
            },
            'wordPolicy': {
                'customWords': [
                    {
                        'match': 'string',
                        'action': 'BLOCKED'
                    },
                ],
                'managedWordLists': [
                    {
                        'match': 'string',
                        'type': 'PROFANITY',
                        'action': 'BLOCKED'
                    },
                ]
            },
            'sensitiveInformationPolicy': {
                'piiEntities': [
                    {
                        'match': 'string',
                        'type': 'ADDRESS'|'AGE'|'AWS_ACCESS_KEY'|'AWS_SECRET_KEY'|'CA_HEALTH_NUMBER'|'CA_SOCIAL_INSURANCE_NUMBER'|'CREDIT_DEBIT_CARD_CVV'|'CREDIT_DEBIT_CARD_EXPIRY'|'CREDIT_DEBIT_CARD_NUMBER'|'DRIVER_ID'|'EMAIL'|'INTERNATIONAL_BANK_ACCOUNT_NUMBER'|'IP_ADDRESS'|'LICENSE_PLATE'|'MAC_ADDRESS'|'NAME'|'PASSWORD'|'PHONE'|'PIN'|'SWIFT_CODE'|'UK_NATIONAL_HEALTH_SERVICE_NUMBER'|'UK_NATIONAL_INSURANCE_NUMBER'|'UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER'|'URL'|'USERNAME'|'US_BANK_ACCOUNT_NUMBER'|'US_BANK_ROUTING_NUMBER'|'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER'|'US_PASSPORT_NUMBER'|'US_SOCIAL_SECURITY_NUMBER'|'VEHICLE_IDENTIFICATION_NUMBER',
                        'action': 'ANONYMIZED'|'BLOCKED'
                    },
                ],
                'regexes': [
                    {
                        'name': 'string',
                        'match': 'string',
                        'regex': 'string',
                        'action': 'ANONYMIZED'|'BLOCKED'
                    },
                ]
            },
            'contextualGroundingPolicy': {
                'filters': [
                    {
                        'type': 'GROUNDING'|'RELEVANCE',
                        'threshold': 123.0,
                        'score': 123.0,
                        'action': 'BLOCKED'|'NONE'
                    },
                ]
            },
            'invocationMetrics': {
                'guardrailProcessingLatency': 123,
                'usage': {
                    'topicPolicyUnits': 123,
                    'contentPolicyUnits': 123,
                    'wordPolicyUnits': 123,
                    'sensitiveInformationPolicyUnits': 123,
                    'sensitiveInformationPolicyFreeUnits': 123,
                    'contextualGroundingPolicyUnits': 123
                },
                'guardrailCoverage': {
                    'textCharacters': {
                        'guarded': 123,
                        'total': 123
                    },
                    'images': {
                        'guarded': 123,
                        'total': 123
                    }
                }
            }
        },
    ],
    'guardrailCoverage': {
        'textCharacters': {
            'guarded': 123,
            'total': 123
        },
        'images': {
            'guarded': 123,
            'total': 123
        }
    }
}

Response Structure

  • (dict) –

    • usage (dict) –

      The usage details in the response from the guardrail.

      • topicPolicyUnits (integer) –

        The topic policy units processed by the guardrail.

      • contentPolicyUnits (integer) –

        The content policy units processed by the guardrail.

      • wordPolicyUnits (integer) –

        The word policy units processed by the guardrail.

      • sensitiveInformationPolicyUnits (integer) –

        The sensitive information policy units processed by the guardrail.

      • sensitiveInformationPolicyFreeUnits (integer) –

        The sensitive information policy free units processed by the guardrail.

      • contextualGroundingPolicyUnits (integer) –

        The contextual grounding policy units processed by the guardrail.

    • action (string) –

      The action taken in the response from the guardrail.

    • outputs (list) –

      The output details in the response from the guardrail.

      • (dict) –

        The output content produced by the guardrail.

        • text (string) –

          The specific text for the output content produced by the guardrail.

    • assessments (list) –

      The assessment details in the response from the guardrail.

      • (dict) –

        A behavior assessment of the guardrail policies used in a call to the Converse API.

        • topicPolicy (dict) –

          The topic policy.

          • topics (list) –

            The topics in the assessment.

            • (dict) –

              Information about a topic guardrail.

              • name (string) –

                The name for the guardrail.

              • type (string) –

                The type behavior that the guardrail should perform when the model detects the topic.

              • action (string) –

                The action the guardrail should take when it intervenes on a topic.

        • contentPolicy (dict) –

          The content policy.

          • filters (list) –

            The content policy filters.

            • (dict) –

              The content filter for a guardrail.

              • type (string) –

                The guardrail type.

              • confidence (string) –

                The guardrail confidence.

              • filterStrength (string) –

                The filter strength setting for the guardrail content filter.

              • action (string) –

                The guardrail action.

        • wordPolicy (dict) –

          The word policy.

          • customWords (list) –

            Custom words in the assessment.

            • (dict) –

              A custom word configured in a guardrail.

              • match (string) –

                The match for the custom word.

              • action (string) –

                The action for the custom word.

          • managedWordLists (list) –

            Managed word lists in the assessment.

            • (dict) –

              A managed word configured in a guardrail.

              • match (string) –

                The match for the managed word.

              • type (string) –

                The type for the managed word.

              • action (string) –

                The action for the managed word.

        • sensitiveInformationPolicy (dict) –

          The sensitive information policy.

          • piiEntities (list) –

            The PII entities in the assessment.

            • (dict) –

              A Personally Identifiable Information (PII) entity configured in a guardrail.

              • match (string) –

                The PII entity filter match.

              • type (string) –

                The PII entity filter type.

              • action (string) –

                The PII entity filter action.

          • regexes (list) –

            The regex queries in the assessment.

            • (dict) –

              A Regex filter configured in a guardrail.

              • name (string) –

                The regex filter name.

              • match (string) –

                The regesx filter match.

              • regex (string) –

                The regex query.

              • action (string) –

                The region filter action.

        • contextualGroundingPolicy (dict) –

          The contextual grounding policy used for the guardrail assessment.

          • filters (list) –

            The filter details for the guardrails contextual grounding filter.

            • (dict) –

              The details for the guardrails contextual grounding filter.

              • type (string) –

                The contextual grounding filter type.

              • threshold (float) –

                The threshold used by contextual grounding filter to determine whether the content is grounded or not.

              • score (float) –

                The score generated by contextual grounding filter.

              • action (string) –

                The action performed by the guardrails contextual grounding filter.

        • invocationMetrics (dict) –

          The invocation metrics for the guardrail assessment.

          • guardrailProcessingLatency (integer) –

            The processing latency details for the guardrail invocation metrics.

          • usage (dict) –

            The usage details for the guardrail invocation metrics.

            • topicPolicyUnits (integer) –

              The topic policy units processed by the guardrail.

            • contentPolicyUnits (integer) –

              The content policy units processed by the guardrail.

            • wordPolicyUnits (integer) –

              The word policy units processed by the guardrail.

            • sensitiveInformationPolicyUnits (integer) –

              The sensitive information policy units processed by the guardrail.

            • sensitiveInformationPolicyFreeUnits (integer) –

              The sensitive information policy free units processed by the guardrail.

            • contextualGroundingPolicyUnits (integer) –

              The contextual grounding policy units processed by the guardrail.

          • guardrailCoverage (dict) –

            The coverage details for the guardrail invocation metrics.

            • textCharacters (dict) –

              The text characters of the guardrail coverage details.

              • guarded (integer) –

                The text characters that were guarded by the guardrail coverage.

              • total (integer) –

                The total text characters by the guardrail coverage.

            • images (dict) –

              The guardrail coverage for images (the number of images that guardrails guarded).

              • guarded (integer) –

                The count (integer) of images guardrails guarded.

              • total (integer) –

                Represents the total number of images (integer) that were in the request (guarded and unguarded).

    • guardrailCoverage (dict) –

      The guardrail coverage details in the apply guardrail response.

      • textCharacters (dict) –

        The text characters of the guardrail coverage details.

        • guarded (integer) –

          The text characters that were guarded by the guardrail coverage.

        • total (integer) –

          The total text characters by the guardrail coverage.

      • images (dict) –

        The guardrail coverage for images (the number of images that guardrails guarded).

        • guarded (integer) –

          The count (integer) of images guardrails guarded.

        • total (integer) –

          Represents the total number of images (integer) that were in the request (guarded and unguarded).

Exceptions