Appearance

Configuration Overview ​

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

Configuration Structure ​

The configuration consists of two main sections:

  1. LLM Configuration: Settings for the language model
  2. 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

See Token Budget Enforcement for full details.

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

Configuration Options ​

OptionTypeDefaultDescription
input_checksbooltrueEnable input validation
output_checksbooltrueEnable output validation
check_toxicitybooltrueEnable toxicity detection
check_sensitive_databooltrueEnable sensitive data detection
check_semanticbooltrueEnable content classification
toxicity_thresholdfloat0.7Threshold for blocking toxic content
block_toxicbooltrueBlock toxic content
block_sensitive_databooltrueBlock sensitive data
piidict—PII/PHI detection and data masking policy
token_budgetdict—Token budget enforcement policy

PII/PHI Options ​

OptionTypeDefaultDescription
pii.enabledboolfalseEnable PII/PHI detection
pii.input_checksbooltrueRun detection on user input
pii.output_checksbooltrueRun detection on model output
pii.languagestr"en"Language code for entity analysis
pii.default_confidence_thresholdfloat0.5Global minimum confidence for entity recognition
pii.below_threshold_actionstr"flag"Action for entities below their threshold (flag, block, review, pass)
pii.default_actionstr"flag"Default action when no entity policy is defined
pii.default_maskbooltrueMask detected values by default
pii.enable_phi_detectionbooltrueEnable regex-based PHI pattern detection
pii.entity_typeslist—Entity types to detect (see PII/PHI Detection)
pii.entity_thresholdsdict—Per-entity confidence overrides (e.g. PERSON: 0.7)
pii.entity_policiesdict—Per-entity rules with action and mask fields

Entity Policy Options ​

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

FieldTypeDescription
actionstrflag, block, review, or pass
maskboolWhether to mask the detected value before downstream processing

Token Budget Options ​

OptionTypeDefaultDescription
token_budget.enabledboolfalseEnable token budget enforcement
token_budget.input_checksbooltrueEnforce limits on incoming requests
token_budget.output_checksbooltrueEnforce limits on model output
token_budget.max_request_tokensint—Maximum tokens for a single request context
token_budget.max_run_tokensint—Maximum total tokens for an entire run
token_budget.reserved_output_tokensint—Tokens reserved for the model response

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 ​

Released under the MIT License.

Copyright © 2024 Elsai Foundry