Skip to content

strands.types.guardrails

Guardrail-related type definitions for the SDK.

These types are modeled after the Bedrock API.

  • Bedrock docs: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Types_Amazon_Bedrock_Runtime.html

ContentFilter

Bases: TypedDict

The content filter for a guardrail.

Attributes:

Name Type Description
action Literal['BLOCKED']

Action to take when content is detected.
confidence Literal['NONE', 'LOW', 'MEDIUM', 'HIGH']

Confidence level of the detection.
type Literal['INSULTS', 'HATE', 'SEXUAL', 'VIOLENCE', 'MISCONDUCT', 'PROMPT_ATTACK']

The type of content to filter.
Source code in strands/types/guardrails.py 
53
54
55
56
57
58
59
60
61
62
63
64
class ContentFilter(TypedDict):
    """The content filter for a guardrail.

    Attributes:
        action: Action to take when content is detected.
        confidence: Confidence level of the detection.
        type: The type of content to filter.
    """

    action: Literal["BLOCKED"]
    confidence: Literal["NONE", "LOW", "MEDIUM", "HIGH"]
    type: Literal["INSULTS", "HATE", "SEXUAL", "VIOLENCE", "MISCONDUCT", "PROMPT_ATTACK"]

ContentPolicy

Bases: TypedDict

An assessment of a content policy for a guardrail.

Attributes:

Name Type Description
filters List[ContentFilter]

List of content filters to apply.
Source code in strands/types/guardrails.py 
67
68
69
70
71
72
73
74
class ContentPolicy(TypedDict):
    """An assessment of a content policy for a guardrail.

    Attributes:
        filters: List of content filters to apply.
    """

    filters: List[ContentFilter]

ContextualGroundingFilter

Bases: TypedDict

Filter for ensuring responses are grounded in provided context.

Attributes:

Name Type Description
action Literal['BLOCKED', 'NONE']

Action to take when the threshold is not met.
score float

The score generated by contextual grounding filter (range [0, 1]).
threshold float

Threshold used by contextual grounding filter to determine whether the content is grounded or not.
type Literal['GROUNDING', 'RELEVANCE']

The contextual grounding filter type.
Source code in strands/types/guardrails.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
class ContextualGroundingFilter(TypedDict):
    """Filter for ensuring responses are grounded in provided context.

    Attributes:
        action: Action to take when the threshold is not met.
        score: The score generated by contextual grounding filter (range [0, 1]).
        threshold: Threshold used by contextual grounding filter to determine whether the content is grounded or not.
        type: The contextual grounding filter type.
    """

    action: Literal["BLOCKED", "NONE"]
    score: float
    threshold: float
    type: Literal["GROUNDING", "RELEVANCE"]

ContextualGroundingPolicy

Bases: TypedDict

The policy assessment details for the guardrails contextual grounding filter.

Attributes:

Name Type Description
filters List[ContextualGroundingFilter]

The filter details for the guardrails contextual grounding filter.
Source code in strands/types/guardrails.py 
205
206
207
208
209
210
211
212
class ContextualGroundingPolicy(TypedDict):
    """The policy assessment details for the guardrails contextual grounding filter.

    Attributes:
        filters: The filter details for the guardrails contextual grounding filter.
    """

    filters: List[ContextualGroundingFilter]

CustomWord

Bases: TypedDict

Definition of a custom word to be filtered.

Attributes:

Name Type Description
action Literal['BLOCKED']

Action to take when the word is detected.
match str

The word or phrase to match.
Source code in strands/types/guardrails.py 
77
78
79
80
81
82
83
84
85
86
class CustomWord(TypedDict):
    """Definition of a custom word to be filtered.

    Attributes:
        action: Action to take when the word is detected.
        match: The word or phrase to match.
    """

    action: Literal["BLOCKED"]
    match: str

GuardrailAssessment

Bases: TypedDict

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

Attributes:

Name Type Description
contentPolicy ContentPolicy

The content policy.
contextualGroundingPolicy ContextualGroundingPolicy

The contextual grounding policy used for the guardrail assessment.
sensitiveInformationPolicy SensitiveInformationPolicy

The sensitive information policy.
topicPolicy TopicPolicy

The topic policy.
wordPolicy WordPolicy

The word policy.
Source code in strands/types/guardrails.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
class GuardrailAssessment(TypedDict):
    """A behavior assessment of the guardrail policies used in a call to the Converse API.

    Attributes:
        contentPolicy: The content policy.
        contextualGroundingPolicy: The contextual grounding policy used for the guardrail assessment.
        sensitiveInformationPolicy: The sensitive information policy.
        topicPolicy: The topic policy.
        wordPolicy: The word policy.
    """

    contentPolicy: ContentPolicy
    contextualGroundingPolicy: ContextualGroundingPolicy
    sensitiveInformationPolicy: SensitiveInformationPolicy
    topicPolicy: TopicPolicy
    wordPolicy: WordPolicy

GuardrailConfig

Bases: TypedDict

Configuration for content filtering guardrails.

Attributes:

Name Type Description
guardrailIdentifier str

Unique identifier for the guardrail.
guardrailVersion str

Version of the guardrail to apply.
streamProcessingMode Optional[Literal['sync', 'async']]

Processing mode.
trace Literal['enabled', 'disabled']

The trace behavior for the guardrail.
Source code in strands/types/guardrails.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class GuardrailConfig(TypedDict, total=False):
    """Configuration for content filtering guardrails.

    Attributes:
        guardrailIdentifier: Unique identifier for the guardrail.
        guardrailVersion: Version of the guardrail to apply.
        streamProcessingMode: Processing mode.
        trace: The trace behavior for the guardrail.
    """

    guardrailIdentifier: str
    guardrailVersion: str
    streamProcessingMode: Optional[Literal["sync", "async"]]
    trace: Literal["enabled", "disabled"]

GuardrailTrace

Bases: TypedDict

Trace information from guardrail processing.

Attributes:

Name Type Description
inputAssessment Dict[str, GuardrailAssessment]

Assessment of input content against guardrail policies, keyed by input identifier.
modelOutput List[str]

The original output from the model before guardrail processing.
outputAssessments Dict[str, List[GuardrailAssessment]]

Assessments of output content against guardrail policies, keyed by output identifier.
Source code in strands/types/guardrails.py 
233
234
235
236
237
238
239
240
241
242
243
244
class GuardrailTrace(TypedDict):
    """Trace information from guardrail processing.

    Attributes:
        inputAssessment: Assessment of input content against guardrail policies, keyed by input identifier.
        modelOutput: The original output from the model before guardrail processing.
        outputAssessments: Assessments of output content against guardrail policies, keyed by output identifier.
    """

    inputAssessment: Dict[str, GuardrailAssessment]
    modelOutput: List[str]
    outputAssessments: Dict[str, List[GuardrailAssessment]]

ManagedWord

Bases: TypedDict

Definition of a managed word to be filtered.

Attributes:

Name Type Description
action Literal['BLOCKED']

Action to take when the word is detected.
match str

The word or phrase to match.
type Literal['PROFANITY']

Type of the word.
Source code in strands/types/guardrails.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
class ManagedWord(TypedDict):
    """Definition of a managed word to be filtered.

    Attributes:
        action: Action to take when the word is detected.
        match: The word or phrase to match.
        type: Type of the word.
    """

    action: Literal["BLOCKED"]
    match: str
    type: Literal["PROFANITY"]

PIIEntity

Bases: TypedDict

Definition of a Personally Identifiable Information (PII) entity to be filtered.

Attributes:

Name Type Description
action Literal['ANONYMIZED', 'BLOCKED']

Action to take when PII is detected.
match str

The specific PII instance to match.
type Literal['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']

The type of PII to detect.
Source code in strands/types/guardrails.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
class PIIEntity(TypedDict):
    """Definition of a Personally Identifiable Information (PII) entity to be filtered.

    Attributes:
        action: Action to take when PII is detected.
        match: The specific PII instance to match.
        type: The type of PII to detect.
    """

    action: Literal["ANONYMIZED", "BLOCKED"]
    match: str
    type: Literal[
        "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",
    ]

Regex

Bases: TypedDict

Definition of a custom regex pattern for filtering sensitive information.

Attributes:

Name Type Description
action Literal['ANONYMIZED', 'BLOCKED']

Action to take when the pattern is matched.
match str

The regex filter match.
name str

Name of the regex pattern for identification.
regex str

The regex query.
Source code in strands/types/guardrails.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
class Regex(TypedDict):
    """Definition of a custom regex pattern for filtering sensitive information.

    Attributes:
        action: Action to take when the pattern is matched.
        match: The regex filter match.
        name: Name of the regex pattern for identification.
        regex: The regex query.
    """

    action: Literal["ANONYMIZED", "BLOCKED"]
    match: str
    name: str
    regex: str

SensitiveInformationPolicy

Bases: TypedDict

Policy defining sensitive information filtering rules.

Attributes:

Name Type Description
piiEntities List[PIIEntity]

List of Personally Identifiable Information (PII) entities to detect and handle.
regexes List[Regex]

The regex queries in the assessment.
Source code in strands/types/guardrails.py 
177
178
179
180
181
182
183
184
185
186
class SensitiveInformationPolicy(TypedDict):
    """Policy defining sensitive information filtering rules.

    Attributes:
        piiEntities: List of Personally Identifiable Information (PII) entities to detect and handle.
        regexes: The regex queries in the assessment.
    """

    piiEntities: List[PIIEntity]
    regexes: List[Regex]

Topic

Bases: TypedDict

Information about a topic guardrail.

Attributes:

Name Type Description
action Literal['BLOCKED']

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

The name for the guardrail.
type Literal['DENY']

The type behavior that the guardrail should perform when the model detects the topic.
Source code in strands/types/guardrails.py 
29
30
31
32
33
34
35
36
37
38
39
40
class Topic(TypedDict):
    """Information about a topic guardrail.

    Attributes:
        action: The action the guardrail should take when it intervenes on a topic.
        name: The name for the guardrail.
        type: The type behavior that the guardrail should perform when the model detects the topic.
    """

    action: Literal["BLOCKED"]
    name: str
    type: Literal["DENY"]

TopicPolicy

Bases: TypedDict

A behavior assessment of a topic policy.

Attributes:

Name Type Description
topics List[Topic]

The topics in the assessment.
Source code in strands/types/guardrails.py 
43
44
45
46
47
48
49
50
class TopicPolicy(TypedDict):
    """A behavior assessment of a topic policy.

    Attributes:
        topics: The topics in the assessment.
    """

    topics: List[Topic]

Trace

Bases: TypedDict

A Top level guardrail trace object.

Attributes:

Name Type Description
guardrail GuardrailTrace

Trace information from guardrail processing.
Source code in strands/types/guardrails.py 
247
248
249
250
251
252
253
254
class Trace(TypedDict):
    """A Top level guardrail trace object.

    Attributes:
        guardrail: Trace information from guardrail processing.
    """

    guardrail: GuardrailTrace

WordPolicy

Bases: TypedDict

The word policy assessment.

Attributes:

Name Type Description
customWords List[CustomWord]

List of custom words to filter.
managedWordLists List[ManagedWord]

List of managed word lists to filter.
Source code in strands/types/guardrails.py 
103
104
105
106
107
108
109
110
111
112
class WordPolicy(TypedDict):
    """The word policy assessment.

    Attributes:
        customWords: List of custom words to filter.
        managedWordLists: List of managed word lists to filter.
    """

    customWords: List[CustomWord]
    managedWordLists: List[ManagedWord]