Configuration Overview

elsai Guardrails uses YAML-based configuration for easy setup and customization.

Configuration Structure

The configuration consists of two main sections:

LLM Configuration: Settings for the language model
Guardrails Configuration: Settings for safety checks

Basic Configuration

yaml

llm:
  engine: "openai"
  model: "gpt-4o-mini"
  api_key: "your-api-key"
  temperature: 0.7

guardrails:
  input_checks: true
  output_checks: true
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
  toxicity_threshold: 0.7
  block_toxic: true
  block_sensitive_data: true

LLM Configuration

Supported Engines

openai - OpenAI API
azure_openai - Azure OpenAI Service
anthropic - Anthropic Claude
gemini - Google Gemini
bedrock - AWS Bedrock

OpenAI Configuration

yaml

llm:
  engine: "openai"
  model: "gpt-4o-mini"
  api_key: "sk-..."
  temperature: 0.7

Azure OpenAI Configuration

yaml

llm:
  engine: "azure_openai"
  endpoint: "https://your-endpoint.openai.azure.com"
  api_version: "2024-02-15-preview"
  api_key: "your-api-key"
  model: "gpt-4"
  temperature: 0.7

Anthropic Configuration

yaml

llm:
  engine: "anthropic"
  model: "claude-3-sonnet-20240229"
  api_key: "your-api-key"

Gemini Configuration

yaml

llm:
  engine: "gemini"
  model: "gemini-pro"
  api_key: "your-api-key"

AWS Bedrock Configuration

yaml

llm:
  engine: "bedrock"
  aws_access_key: "your-access-key"
  aws_secret_key: "your-secret-key"
  aws_region: "us-east-1"
  model_id: "anthropic.claude-v2"
  max_tokens: 500
  temperature: 0.7

Guardrails Configuration

Basic Options

yaml

guardrails:
  # Enable/disable input/output checks
  input_checks: true
  output_checks: true
  
  # Enable/disable specific checks
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
  
  # Toxicity settings
  toxicity_threshold: 0.7  # Threshold for blocking (0.0-1.0)
  block_toxic: true        # Block toxic content
  
  # Sensitive data settings
  block_sensitive_data: true  # Block sensitive data

PII/PHI Detection and Data Masking

Requires the spaCy model: python -m spacy download en_core_web_lg. See Installation.

yaml

guardrails:
  pii:
    enabled: true
    input_checks: true
    output_checks: true
    language: en
    default_confidence_threshold: 0.5
    below_threshold_action: flag
    default_action: flag
    default_mask: true
    enable_phi_detection: true
    entity_types:
      - PERSON
      - LOCATION
      - EMAIL_ADDRESS
      - PHONE_NUMBER
      - CREDIT_CARD
      - NRP
      - MEDICAL_LICENSE
      - US_SSN
      - IBAN_CODE
      - IP_ADDRESS
    entity_thresholds:
      PERSON: 0.7
    entity_policies:
      CREDIT_CARD:
        action: block
        mask: true
      US_SSN:
        action: block
        mask: true
      EMAIL_ADDRESS:
        action: flag
        mask: true
      PHONE_NUMBER:
        action: flag
        mask: true
      PHI_MRN:
        action: review
        mask: true
      PHI_PATIENT_ID:
        action: review
        mask: true

See PII/PHI Detection for full details.

Token Budget Enforcement

yaml

guardrails:
  token_budget:
    enabled: true
    input_checks: true
    output_checks: true
    max_request_tokens: 50
    max_run_tokens: 80
    reserved_output_tokens: 10
    block_on_exceeded: true   # true = block; false = warn only

See Token Budget Enforcement for full details.

Tool Authorization

Enforced via agent hooks (before_tool_call()). See Tool Authorization.

yaml

guardrails:
  tool_authorization:
    enabled: true
    denied_tools:
      - execute_shell
    sensitive_tools:
      - delete_record
    roles:
      analyst:
        allowed_tools:
          - search_web
          - calculator

Rate Limiting

Enforced via agent hooks (before_request(), check_tool_call_limit()). See Rate Limiting.

yaml

guardrails:
  rate_limit:
    enabled: true
    max_requests_per_session: 5
    max_tool_calls_per_session: 50
    max_tool_execution_seconds: 60

Data Exfiltration Detection

Output-only guardrail for credential leaks and bulk data exports. See Data Exfiltration Detection.

yaml

guardrails:
  data_exfiltration:
    enabled: true
    action_thresholds:
      warn: 20
      block: 80
    detectors:
      secrets: true
      bulk_sensitive: true
      abnormal_patterns: true

ARMS Storage

Persist guardrail runs via the ARMS Backend (MongoDB, DynamoDB, or ClickHouse). See ARMS Storage.

yaml

guardrails:
  storage:
    enabled: true
    project: my-app
    store_raw_text: true
    fail_soft: true
    arms_correlation: true

Requires API_BASE_URL and ELSAI_ARMS_API_KEY environment variables (shared with ARMS).

Complete Guardrail Policy Example

The following matches the reference config.yml guardrail policy:

yaml

# Guardrail policy configuration

guardrails:
  input_checks: true
  output_checks: true

  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
  toxicity_threshold: 0.7
  block_toxic: true
  block_sensitive_data: true

  # PII/PHI detection policy
  pii:
    enabled: true
    input_checks: true
    output_checks: true
    language: en
    default_confidence_threshold: 0.5
    below_threshold_action: flag
    default_action: flag
    default_mask: true
    enable_phi_detection: true
    entity_types:
      - PERSON
      - LOCATION
      - EMAIL_ADDRESS
      - PHONE_NUMBER
      - CREDIT_CARD
      - NRP
      - MEDICAL_LICENSE
      - US_SSN
      - IBAN_CODE
      - IP_ADDRESS
    entity_thresholds:
      PERSON: 0.7
    entity_policies:
      CREDIT_CARD:
        action: block
        mask: true
      US_SSN:
        action: block
        mask: true
      EMAIL_ADDRESS:
        action: flag
        mask: true
      PHONE_NUMBER:
        action: flag
        mask: true
      PHI_MRN:
        action: review
        mask: true
      PHI_PATIENT_ID:
        action: review
        mask: true

  # Token budget enforcement policy
  token_budget:
    enabled: true
    input_checks: true
    output_checks: true
    max_request_tokens: 50
    max_run_tokens: 80
    reserved_output_tokens: 10
    block_on_exceeded: true

  tool_authorization:
    enabled: true
    denied_tools:
      - execute_shell
    sensitive_tools:
      - delete_record
    roles:
      analyst:
        allowed_tools:
          - search_web
          - calculator

  rate_limit:
    enabled: true
    max_requests_per_session: 5
    max_tool_calls_per_session: 50
    max_tool_execution_seconds: 60

  data_exfiltration:
    enabled: true
    action_thresholds:
      warn: 20
      block: 80

  storage:
    enabled: true
    project: my-app
    arms_correlation: true

Configuration Options

Option	Type	Default	Description
`input_checks`	bool	`true`	Enable input validation
`output_checks`	bool	`true`	Enable output validation
`check_toxicity`	bool	`true`	Enable toxicity detection
`check_sensitive_data`	bool	`true`	Enable sensitive data detection
`check_semantic`	bool	`true`	Enable content classification
`toxicity_threshold`	float	`0.7`	Threshold for blocking toxic content
`block_toxic`	bool	`true`	Block toxic content
`block_sensitive_data`	bool	`true`	Block sensitive data
`pii`	dict	—	PII/PHI detection and data masking policy
`token_budget`	dict	—	Token budget enforcement policy
`tool_authorization`	dict	—	Tool access control policy
`rate_limit`	dict	—	Rate limiting and abuse prevention policy
`data_exfiltration`	dict	—	Output data exfiltration detection policy
`storage`	dict	—	ARMS Backend persistence policy

PII/PHI Options

Option	Type	Default	Description
`pii.enabled`	bool	`false`	Enable PII/PHI detection
`pii.input_checks`	bool	`true`	Run detection on user input
`pii.output_checks`	bool	`true`	Run detection on model output
`pii.language`	str	`"en"`	Language code for entity analysis
`pii.default_confidence_threshold`	float	`0.5`	Global minimum confidence for entity recognition
`pii.below_threshold_action`	str	`"flag"`	Action for entities below their threshold (`flag`, `block`, `review`, `pass`)
`pii.default_action`	str	`"flag"`	Default action when no entity policy is defined
`pii.default_mask`	bool	`true`	Mask detected values by default
`pii.enable_phi_detection`	bool	`true`	Enable regex-based PHI pattern detection
`pii.entity_types`	list	—	Entity types to detect (see PII/PHI Detection)
`pii.entity_thresholds`	dict	—	Per-entity confidence overrides (e.g. `PERSON: 0.7`)
`pii.entity_policies`	dict	—	Per-entity rules with `action` and `mask` fields

Entity Policy Options

Each key under entity_policies is an entity type. Supported policy fields:

Field	Type	Description
`action`	str	`flag`, `block`, `review`, or `pass`
`mask`	bool	Whether to mask the detected value before downstream processing

Token Budget Options

Option	Type	Default	Description
`token_budget.enabled`	bool	`false`	Enable token budget enforcement
`token_budget.input_checks`	bool	`true`	Enforce limits on incoming requests
`token_budget.output_checks`	bool	`true`	Enforce limits on model output
`token_budget.max_request_tokens`	int	—	Maximum tokens for a single request context
`token_budget.max_run_tokens`	int	—	Maximum total tokens for an entire run
`token_budget.reserved_output_tokens`	int	—	Tokens reserved for the model response
`token_budget.block_on_exceeded`	bool	`true`	Block when exceeded; `false` = warn only

Tool Authorization Options

Option	Type	Default	Description
`tool_authorization.enabled`	bool	`false`	Enable tool authorization
`tool_authorization.denied_tools`	list	—	Tools blocked for all roles
`tool_authorization.sensitive_tools`	list	—	Tools requiring approval metadata
`tool_authorization.roles`	dict	—	Role definitions with `allowed_tools`

Rate Limiting Options

Option	Type	Default	Description
`rate_limit.enabled`	bool	`false`	Enable rate limiting
`rate_limit.max_requests_per_session`	int	—	Maximum LLM requests per session
`rate_limit.max_tool_calls_per_session`	int	—	Maximum tool invocations per session
`rate_limit.max_tool_execution_seconds`	int	—	Maximum cumulative tool execution time

Data Exfiltration Options

Option	Type	Default	Description
`data_exfiltration.enabled`	bool	`false`	Enable output exfiltration detection
`data_exfiltration.action_thresholds.warn`	int	`20`	Score to mask sensitive spans
`data_exfiltration.action_thresholds.block`	int	`80`	Score to block the response

See Guardrails Configuration for all exfiltration detector options.

ARMS Storage Options

Option	Type	Default	Description
`storage.enabled`	bool	`false`	Enable ARMS Backend persistence
`storage.project`	str	`"default"`	Logical project name
`storage.store_raw_text`	bool	`true`	Store full text; `false` uses SHA-256 digests
`storage.arms_correlation`	bool	`true`	Auto-link ARMS run/project ids

Loading Configuration

From YAML String

python

from elsai_guardrails.guardrails import RailsConfig

yaml_content = """
llm:
  engine: "openai"
  model: "gpt-4o-mini"
  api_key: "sk-..."

guardrails:
  input_checks: true
  output_checks: true
"""

config = RailsConfig.from_content(yaml_content=yaml_content)

From File

python

config = RailsConfig.from_content(config_path="config.yml")

Programmatic Configuration

You can also create configuration programmatically:

python

from elsai_guardrails.guardrails import RailsConfig, GuardrailConfig

guardrail_config = GuardrailConfig(
    check_toxicity=True,
    check_sensitive_data=True,
    check_semantic=True,
    toxicity_threshold=0.7,
    block_toxic=True,
    block_sensitive_data=True
)

llm_config = {
    "engine": "openai",
    "model": "gpt-4o-mini",
    "api_key": "sk-...",
    "temperature": 0.7
}

config = RailsConfig(
    guardrail_config=guardrail_config,
    llm_config=llm_config,
    input_checks=True,
    output_checks=True
)

Next Steps

LLM Configuration - Detailed LLM setup
Guardrails Configuration - Detailed guardrails setup
YAML Configuration - Complete YAML reference

Configuration Overview ​

Configuration Structure ​

Basic Configuration ​

LLM Configuration ​

Supported Engines ​

OpenAI Configuration ​

Azure OpenAI Configuration ​

Anthropic Configuration ​

Gemini Configuration ​

AWS Bedrock Configuration ​

Guardrails Configuration ​

Basic Options ​

PII/PHI Detection and Data Masking ​

Token Budget Enforcement ​

Tool Authorization ​

Rate Limiting ​

Data Exfiltration Detection ​

ARMS Storage ​

Complete Guardrail Policy Example ​

Configuration Options ​

PII/PHI Options ​

Entity Policy Options ​

Token Budget Options ​

Tool Authorization Options ​

Rate Limiting Options ​

Data Exfiltration Options ​

ARMS Storage Options ​

Loading Configuration ​

From YAML String ​

From File ​

Programmatic Configuration ​

Next Steps ​

Configuration Overview

Configuration Structure

Basic Configuration

LLM Configuration

Supported Engines

OpenAI Configuration

Azure OpenAI Configuration

Anthropic Configuration

Gemini Configuration

AWS Bedrock Configuration

Guardrails Configuration

Basic Options

PII/PHI Detection and Data Masking

Token Budget Enforcement

Tool Authorization

Rate Limiting

Data Exfiltration Detection

ARMS Storage

Complete Guardrail Policy Example

Configuration Options

PII/PHI Options

Entity Policy Options

Token Budget Options

Tool Authorization Options

Rate Limiting Options

Data Exfiltration Options

ARMS Storage Options

Loading Configuration

From YAML String

From File

Programmatic Configuration

Next Steps