Basic Examples

Simple examples to get started with elsai Guardrails.

Overview

Example	Feature	Integration
1–3	Core LLM + guardrails	`LLMRails`
4–5	Input/output checks	`GuardrailSystem`
6–8	Conversations, async, providers	`LLMRails`
9–10	Off-topic, SQL validation	`LLMRails`
11	Combined content checks	`LLMRails`
12	Token budget enforcement	`LLMRails`
13	PII/PHI detection	YAML policy
14	Tool authorization	`GuardrailSystem` hooks
15	Rate limiting	`GuardrailSystem` hooks
16	Data exfiltration detection	`GuardrailSystem` output checks
17	ARMS storage	`GuardrailSystem` + Backend API

For agent framework integrations, see Integration Examples. For complex patterns, see Advanced Examples.

Example 1: Basic Generation

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: true
  output_checks: true
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

response = rails.generate(
    messages=[{"role": "user", "content": "What is artificial intelligence?"}]
)
print(response)

Example 2: Using Configuration File

config.yml:

yaml

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

guardrails:
  input_checks: true
  output_checks: true

Python:

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

response = rails.generate(
    messages=[{"role": "user", "content": "Hello!"}]
)

Example 3: Detailed Results

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: true
  output_checks: true
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

result = rails.generate(
    messages=[{"role": "user", "content": "test input"}],
    return_details=True
)

print(f"Blocked: {result['blocked']}")
print(f"Block Reason: {result.get('block_reason', 'N/A')}")
print(f"Final Response: {result['final_response']}")

if result.get('input_check'):
    print(f"\nInput Check:")
    print(f"  Passed: {result['input_check'].passed}")
    print(f"  Message: {result['input_check'].message}")
    print(f"  Toxicity: {result['input_check'].toxicity}")
    print(f"  Sensitive Data: {result['input_check'].sensitive_data}")
    print(f"  Semantic Class: {result['input_check'].semantic_class}")

Example 4: Input Validation Only

python

from elsai_guardrails.guardrails import GuardrailSystem, GuardrailConfig

config = GuardrailConfig(
    check_toxicity=True,
    check_sensitive_data=True,
    check_semantic=True
)
guardrail = GuardrailSystem(config=config)

user_input = "My email is user@example.com"
result = guardrail.check_input(user_input)

print(f"Input: {user_input}")
print(f"Passed: {result.passed}")
print(f"Message: {result.message}")
print(f"Sensitive Data: {result.sensitive_data.get('predicted_labels', [])}")

Example 5: Output Validation Only

python

from elsai_guardrails.guardrails import GuardrailSystem, GuardrailConfig

config = GuardrailConfig()
guardrail = GuardrailSystem(config=config)

llm_output = "Here is some information about your query."
result = guardrail.check_output(llm_output)

print(f"Output: {llm_output}")
print(f"Passed: {result.passed}")
print(f"Message: {result.message}")

Example 6: Conversation with Multiple Messages

python

from elsai_guardrails.guardrails import LLMRails, 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)
rails = LLMRails(config=config)

messages = [
    {"role": "user", "content": "What is AI?"},
    {"role": "assistant", "content": "AI stands for Artificial Intelligence..."},
    {"role": "user", "content": "Can you give me more details?"}
]

response = rails.generate(messages=messages)
print(response)

Example 7: Async Generation

python

import asyncio
from elsai_guardrails.guardrails import LLMRails, RailsConfig

async def main():
    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)
    rails = LLMRails(config=config)
    
    result = await rails.generate_async(
        messages=[{"role": "user", "content": "Hello!"}]
    )
    
    print(result)

asyncio.run(main())

Example 8: Different LLM Providers

OpenAI

python

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

Azure OpenAI

python

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

Anthropic

python

yaml_content = """
llm:
  engine: "anthropic"
  model: "claude-3-sonnet-20240229"
  api_key: "sk-ant-..."
"""

Gemini

python

yaml_content = """
llm:
  engine: "gemini"
  model: "gemini-pro"
  api_key: "AIza..."
"""

AWS Bedrock

python

yaml_content = """
llm:
  engine: "bedrock"
  aws_access_key: "AKIA..."
  aws_secret_key: "wJalr..."
  aws_region: "us-east-1"
  model_id: "anthropic.claude-v2"
"""

Example 9: Off-Topic Detection

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: true
  output_checks: true
  check_off_topic: true
  block_off_topic: true
  allowed_topics:
    - name: "Customer Support"
      description: "Questions about products, orders, shipping, and customer service"
    - name: "Technical Help"
      description: "Installation, troubleshooting, technical issues, and error messages"
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

# On-topic input - will pass
response1 = rails.generate(
    messages=[{"role": "user", "content": "How do I track my order?"}]
)
print("On-topic response:", response1)

# Off-topic input - will be blocked
response2 = rails.generate(
    messages=[{"role": "user", "content": "What's the weather today?"}]
)
print("Off-topic response:", response2)

Example 10: SQL Syntax Validation

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: false
  output_checks: true
  check_sql_syntax: true
  sql_dialect: "postgresql"
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

# Ask LLM to generate SQL query
response = rails.generate(
    messages=[{
        "role": "user",
        "content": "Write a SQL query to get all users over age 25"
    }]
)

# The SQL in the response is automatically validated
print("SQL Query Response:", response)

Example 11: Combined New Features

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: true
  output_checks: true
  
  # Enable all checks
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
  check_off_topic: true
  check_sql_syntax: true
  
  # Configure new features
  block_off_topic: true
  allowed_topics:
    - name: "Database Queries"
      description: "Questions about SQL queries, database operations, and data analysis"
  
  sql_dialect: "mysql"
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

# This combines off-topic detection and SQL validation
response = rails.generate(
    messages=[{
        "role": "user",
        "content": "Generate a SQL query to find all active users"
    }]
)
print(response)

Example 12: Token Budget Enforcement

Token budget runs automatically when enabled in your config. Use return_details=True to inspect budget check results.

python

from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  input_checks: true
  output_checks: true
  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
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
rails = LLMRails(config=config)

messages = [{"role": "user", "content": "Hello"}]
result = rails.generate(messages, return_details=True)

if result["blocked"]:
    print(result["block_reason"])   # token_budget_input | token_budget_output
    print(result.get("token_budget_input_check"))
    print(result.get("token_budget_output_check"))
else:
    print(result["final_response"])

See Token Budget Enforcement for standalone TokenBudgetEnforcer usage.

Example 13: PII/PHI Detection

Requires the spaCy model: python -m spacy download en_core_web_lg

python

from elsai_guardrails.guardrails import GuardrailSystem
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

guardrails = GuardrailSystem(
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)

user_input = "Contact John at john@example.com or call 555-123-4567"
result = guardrails.check_input(user_input)

print(f"Passed: {result.passed}")
print(f"Message: {result.message}")

config.yaml:

yaml

guardrails:
  pii:
    enabled: true
    input_checks: true
    default_confidence_threshold: 0.5
    default_action: flag
    default_mask: true
    enable_phi_detection: true
    entity_types:
      - PERSON
      - EMAIL_ADDRESS
      - PHONE_NUMBER
      - US_SSN
    entity_policies:
      US_SSN:
        action: block
        mask: true
      EMAIL_ADDRESS:
        action: flag
        mask: true

See PII/PHI Detection for full configuration.

Example 14: Tool Authorization

Tool authorization uses agent hooks — call before_tool_call() before executing a tool.

python

from elsai_guardrails.guardrails import GuardrailSystem
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

guardrails = GuardrailSystem(
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)

# Allowed: analyst + calculator
result = guardrails.before_tool_call(
    tool_name="calculator",
    user_role="analyst",
    raise_on_block=False,
)
print(f"calculator / analyst: {'ALLOWED' if result.passed else 'BLOCKED'}")

# Blocked: execute_shell is globally denied
result = guardrails.before_tool_call(
    tool_name="execute_shell",
    user_role="admin",
    raise_on_block=False,
)
print(f"execute_shell / admin: {'ALLOWED' if result.passed else 'BLOCKED'}")
# Blocked — denied_tools overrides role allowlist

# Blocked: sensitive tool without approval
result = guardrails.before_tool_call(
    tool_name="delete_record",
    user_role="engineer",
    metadata={"approved": False},
    raise_on_block=False,
)
print(f"delete_record / engineer: {'ALLOWED' if result.passed else 'BLOCKED'}")

config.yaml (see toolauth/config.yaml in the repository):

yaml

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

Full LangGraph sample: toolauth/agent_langgraph.py. See Tool Authorization.

Example 15: Rate Limiting

Rate limiting tracks per-session request and tool call quotas via hooks.

python

from elsai_guardrails.guardrails import GuardrailSystem
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

guardrails = GuardrailSystem(
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)

session = guardrails.create_session()
session_id = session.session_id

# Before each LLM call
result = guardrails.before_request(session_id, raise_on_block=False)
if result.passed:
    print(f"Request allowed ({result.current_count}/{result.limit})")
    # ... invoke LLM ...
else:
    print(f"Request blocked: {result.error}")

# Before tool execution (peek — does not increment counter)
result = guardrails.check_tool_call_limit(session_id, raise_on_block=False)
if result.passed:
    # Inside the tool, record the call when it actually runs:
    guardrails.record_tool_call(session_id)
    t = guardrails.start_execution_timer()
    # ... tool logic ...
    guardrails.end_execution_timer(t)

# Inspect session metrics
session = guardrails.get_session(session_id)
print(f"requests={session.request_count}  tool_calls={session.tool_call_count}")

config.yaml (see ratelimit/config.yaml in the repository):

yaml

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

Full LangGraph sample: ratelimit/agent_langgraph.py. See Rate Limiting.

Example 16: Data Exfiltration Detection

Scan LLM output for credential leaks and bulk sensitive data. Runs on output only — use check_output() or enable in LLMRails with output_checks: true.

python

from elsai_guardrails.guardrails import GuardrailSystem, GuardrailConfig
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

guardrails = GuardrailSystem(
    config=GuardrailConfig(
        check_toxicity=False,
        check_sensitive_data=False,
        check_semantic=False,
    ),
    output_checks=True,
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)

# Allow — low risk
result = guardrails.check_output("Here is a brief summary.")
print(result.passed, result.exfiltration["action"])  # True, allow

# Warn — masks sensitive spans, still passes
token = "ghp_" + "y" * 36
result = guardrails.check_output(f"Token: {token}")
print(result.passed, result.exfiltration["action"])  # True, warn
print(result.exfiltration["processed_text"])           # Token: [REDACTED]

# Block — high risk score
payload = "\n".join(["AKIAIOSFODNN7EXAMPLE", "AKIAI0SFODNN9EXAMPLE", "ghp_" + "x" * 36])
result = guardrails.check_output(payload)
print(result.passed, result.exfiltration["action"])  # False, block

config.yaml:

yaml

guardrails:
  output_checks: true
  check_toxicity: false
  check_sensitive_data: false
  check_semantic: false

  data_exfiltration:
    enabled: true
    action_thresholds:
      warn: 15
      block: 40
    detectors:
      secrets: true
      bulk_sensitive: true
      abnormal_patterns: false
    bulk_sensitive:
      threshold: 3
    use_detect_secrets_plugin: false

See Data Exfiltration Detection.

Example 17: ARMS Storage

Buffer guardrail events and flush them to the ARMS Backend (MongoDB, DynamoDB, or ClickHouse — auto-selected by your deployment).

python

import os
from elsai_guardrails.guardrails import GuardrailSystem, GuardrailConfig
from elsai_guardrails.guardrails.guardrail_policy import GuardrailPolicy

os.environ.setdefault("API_BASE_URL", "https://your-arms-backend")
os.environ.setdefault("ELSAI_ARMS_API_KEY", "your-api-key")

guardrails = GuardrailSystem(
    config=GuardrailConfig(),
    guardrail_policy=GuardrailPolicy.from_file("config.yaml"),
)._with_storage_hook()

# Link to an ARMS run (required for persistence)
guardrails.link_run_context(
    run_id="demo-run-001",
    project_id="demo-project-001",
    project="demo-app",
)

guardrails.begin_run(session_id="sess-1")
guardrails.check_input("Hello")
guardrails.check_output("Hi there!")
saved_run_id = guardrails.end_run()  # POST to Backend
print(f"Saved run_id={saved_run_id}")

With elsai_arms:

python

from elsai_arms import ElsaiARMS

arms = ElsaiARMS(project_name="demo-app")
guardrails.link_arms(arms)  # shares run_id / project_id automatically

config.yaml:

yaml

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

Environment:

bash

export API_BASE_URL=https://your-arms-backend
export ELSAI_ARMS_API_KEY=your-api-key
export GUARDRAILS_ARMS_RUN_ID=demo-run-001
export GUARDRAILS_ARMS_PROJECT_ID=demo-project-001

See ARMS Storage.

Next Steps

Advanced Examples - More complex use cases
Integration Examples - Framework and LangGraph integrations
Token Budget Enforcement
PII/PHI Detection
Tool Authorization
Rate Limiting
Data Exfiltration Detection
ARMS Storage
Off-Topic Detection Guide
SQL Syntax Validation Guide

Basic Examples ​

Overview ​

Example 1: Basic Generation ​

Example 2: Using Configuration File ​

Example 3: Detailed Results ​

Example 4: Input Validation Only ​

Example 5: Output Validation Only ​

Example 6: Conversation with Multiple Messages ​

Example 7: Async Generation ​

Example 8: Different LLM Providers ​

OpenAI ​

Azure OpenAI ​

Anthropic ​

Gemini ​

AWS Bedrock ​

Example 9: Off-Topic Detection ​

Example 10: SQL Syntax Validation ​

Example 11: Combined New Features ​

Example 12: Token Budget Enforcement ​

Example 13: PII/PHI Detection ​

Example 14: Tool Authorization ​

Example 15: Rate Limiting ​

Example 16: Data Exfiltration Detection ​

Example 17: ARMS Storage ​

Next Steps ​

Basic Examples

Overview

Example 1: Basic Generation

Example 2: Using Configuration File

Example 3: Detailed Results

Example 4: Input Validation Only

Example 5: Output Validation Only

Example 6: Conversation with Multiple Messages

Example 7: Async Generation

Example 8: Different LLM Providers

OpenAI

Azure OpenAI

Anthropic

Gemini

AWS Bedrock

Example 9: Off-Topic Detection

Example 10: SQL Syntax Validation

Example 11: Combined New Features

Example 12: Token Budget Enforcement

Example 13: PII/PHI Detection

Example 14: Tool Authorization

Example 15: Rate Limiting

Example 16: Data Exfiltration Detection

Example 17: ARMS Storage

Next Steps