Implementation:BerriAI Litellm Guardrail Types

Attribute	Value
Sources	litellm/types/guardrails.py
Domains	Guardrails, Safety, Content Filtering, PII Detection, Proxy Configuration
Last Updated	2026-02-15 16:00 GMT

Overview

Pydantic models, TypedDicts, and enums that define the complete type system for configuring, managing, and invoking guardrail integrations on the LiteLLM proxy.

Description

This module contains the full set of type definitions used by LiteLLM's guardrail subsystem. It covers:

• SupportedGuardrailIntegrations -- An enum listing every supported guardrail provider (Aporia, Bedrock, Lakera, Presidio, Zscaler, etc.).
• GuardrailItem / GuardrailItemSpec -- Models representing individual guardrail entries as configured in the proxy.
• Provider-specific config models -- Pydantic models for each guardrail provider (PresidioConfigModel, BedrockGuardrailConfigModel, LakeraV2GuardrailConfigModel, LassoGuardrailConfigModel, PillarGuardrailConfigModel, NomaGuardrailConfigModel, ZscalerAIGuardConfigModel, JavelinGuardrailConfigModel, ContentFilterConfigModel, and more).
• LitellmParams -- A combined Pydantic model inheriting from all provider-specific config models, representing the complete set of parameters for any guardrail.
• Guardrail / guardrailConfig -- TypedDicts for the YAML config structure.
• GuardrailEventHooks -- Enum defining when guardrails execute (pre_call, post_call, during_call, logging_only, pre_mcp_call, during_mcp_call).
• PII types -- Enums and mappings for PII entity types, entity categories, and actions (BLOCK/MASK) used by Presidio.
• API request/response models -- GuardrailInfoResponse, ListGuardrailsResponse, ApplyGuardrailRequest, ApplyGuardrailResponse, PatchGuardrailRequest.

Usage

Import from this module when:

• Configuring guardrails in the LiteLLM proxy YAML configuration.
• Building custom guardrail integrations that need to conform to LiteLLM's type contracts.
• Making API calls to the proxy's guardrail management endpoints.
• Implementing PII detection or content filtering logic that uses the defined entity types and actions.

Code Reference

Source Location

litellm/types/guardrails.py (810 lines)

Key Types

Type Name	Kind	Description
SupportedGuardrailIntegrations	Enum	All supported guardrail provider names (aporia, bedrock, lakera, presidio, etc.)
Role	Enum	Message roles: system, assistant, user
GuardrailItemSpec	TypedDict	Spec for a guardrail item with callbacks, default_on, logging_only, enabled_roles
GuardrailItem	BaseModel	Pydantic model for a guardrail item with name, callbacks, enabled roles
PresidioConfigModel	BaseModel	Config for Presidio PII masking (entities, score thresholds, ad-hoc recognizers)
BedrockGuardrailConfigModel	BaseModel	Config for AWS Bedrock guardrails (identifier, version, AWS credentials)
LakeraV2GuardrailConfigModel	BaseModel	Config for Lakera AI v2 (api_key, api_base, project_id, on_flagged action)
LassoGuardrailConfigModel	BaseModel	Config for Lasso guardrail (user_id, conversation_id, mask)
PillarGuardrailConfigModel	BaseModel	Config for Pillar Security (on_flagged_action, async_mode, persist_session)
NomaGuardrailConfigModel	BaseModel	Config for Noma Security (application_id, monitor_mode, block_failures)
ZscalerAIGuardConfigModel	BaseModel	Config for Zscaler AI Guard (policy_id, header flags)
JavelinGuardrailConfigModel	BaseModel	Config for Javelin (guard_name, api_version, metadata)
ContentFilterConfigModel	BaseModel	Config for content filtering (patterns, blocked_words, categories)
BaseLitellmParams	BaseModel	Base params shared across all guardrails (api_key, api_base, mode flags, PII controls)
LitellmParams	BaseModel	Combined model inheriting all provider configs plus guardrail and mode fields
Guardrail	TypedDict	YAML config entry: guardrail_name, litellm_params, guardrail_info
guardrailConfig	TypedDict	Top-level YAML config holding a list of Guardrail entries
GuardrailEventHooks	str, Enum	Execution hooks: pre_call, post_call, during_call, logging_only, pre_mcp_call, during_mcp_call
PiiAction	str, Enum	PII actions: BLOCK, MASK
PiiEntityType	str, Enum	PII entity types (CREDIT_CARD, EMAIL_ADDRESS, US_SSN, etc.)
PiiEntityCategory	str, Enum	PII entity categories by country/region (General, Finance, USA, UK, etc.)
ContentFilterAction	str, Enum	Content filter actions: BLOCK, MASK
BlockedWord	BaseModel	A blocked keyword with action and optional description
ContentFilterPattern	BaseModel	A content filter pattern (prebuilt or custom regex) with action
GuardrailInfoResponse	BaseModel	API response for guardrail info queries
ListGuardrailsResponse	BaseModel	API response listing all guardrails
ApplyGuardrailRequest	BaseModel	Request to apply a guardrail to text
ApplyGuardrailResponse	BaseModel	Response after applying a guardrail
PatchGuardrailRequest	BaseModel	Request to patch/update an existing guardrail

Import

from litellm.types.guardrails import (
    SupportedGuardrailIntegrations,
    GuardrailItem,
    GuardrailItemSpec,
    LitellmParams,
    Guardrail,
    guardrailConfig,
    GuardrailEventHooks,
    PiiAction,
    PiiEntityType,
    PiiEntityCategory,
    ContentFilterAction,
    BlockedWord,
    ContentFilterPattern,
    GuardrailInfoResponse,
    ApplyGuardrailRequest,
    ApplyGuardrailResponse,
    PatchGuardrailRequest,
)

I/O Contract

Key Model: LitellmParams (Guardrail Configuration)

Inputs (required fields):

Field	Type	Description
guardrail	str	The guardrail provider to use (must match a SupportedGuardrailIntegrations value)
mode	Union[str, List[str], Mode]	When to apply the guardrail: "pre_call", "post_call", "during_call", "logging_only"

Inputs (commonly used optional fields):

Field	Type	Default	Description
api_key	Optional[str]	None	API key for the guardrail service
api_base	Optional[str]	None	Base URL for the guardrail service
default_on	Optional[bool]	False	Whether the guardrail is active by default
mask_request_content	Optional[bool]	None	Mask request content if guardrail modifies it
mask_response_content	Optional[bool]	None	Mask response content if guardrail modifies it
violation_message_template	Optional[str]	None	Custom message template for guardrail blocks

Key Model: ApplyGuardrailRequest

Field	Type	Description
guardrail_name	str	Name of the guardrail to apply
text	str	The text to check
language	Optional[str]	Language code for PII analysis
entities	Optional[List[PiiEntityType]]	PII entity types to detect

Key Model: ApplyGuardrailResponse

Field	Type	Description
response_text	str	The text after guardrail processing

Usage Examples

Defining a guardrail in YAML config

guardrails:
  - guardrail_name: "bedrock-pre-guard"
    litellm_params:
      guardrail: bedrock
      mode: "during_call"
      guardrailIdentifier: ff6ujrregl1q
      guardrailVersion: "DRAFT"
      default_on: true

Creating a GuardrailItem programmatically

from litellm.types.guardrails import GuardrailItem, Role

item = GuardrailItem(
    callbacks=["bedrock_guardrail_callback"],
    guardrail_name="bedrock-pre-guard",
    default_on=True,
    enabled_roles=[Role.USER, Role.ASSISTANT],
)

Configuring Presidio PII masking

from litellm.types.guardrails import (
    PresidioConfigModel,
    PiiEntityType,
    PiiAction,
)

presidio_config = PresidioConfigModel(
    presidio_analyzer_api_base="http://localhost:5001",
    presidio_anonymizer_api_base="http://localhost:5002",
    output_parse_pii=True,
    pii_entities_config={
        PiiEntityType.CREDIT_CARD: PiiAction.MASK,
        PiiEntityType.EMAIL_ADDRESS: PiiAction.BLOCK,
    },
)

Using PII entity category mappings

from litellm.types.guardrails import (
    PII_ENTITY_CATEGORIES_MAP,
    PiiEntityCategory,
)

# Get all USA-specific PII entity types
usa_entities = PII_ENTITY_CATEGORIES_MAP[PiiEntityCategory.USA]
# Returns: [US_BANK_NUMBER, US_DRIVER_LICENSE, US_ITIN, US_PASSPORT, US_SSN]

Applying a guardrail via API request

from litellm.types.guardrails import ApplyGuardrailRequest, PiiEntityType

request = ApplyGuardrailRequest(
    guardrail_name="presidio-pii",
    text="My SSN is 123-45-6789",
    language="en",
    entities=[PiiEntityType.US_SSN],
)

Related Pages

• Proxy Server -- The FastAPI proxy server that loads and enforces guardrail configurations.
• MCP Types -- MCP hook types that interact with guardrails via pre_mcp_call and during_mcp_call hooks.
• Service Types -- Service monitoring types used alongside guardrail logging.
• Content Filtering -- Content filter implementation that uses ContentFilterConfigModel and related types.