elsai

Appearance

Release Notes ​

Version 0.1.5 (July 2026) ​

New Features ​

ARMS Storage (Multi-Database) ​

Persist guardrail run data through the ARMS Backend API with automatic routing to MongoDB, DynamoDB, or ClickHouse — whichever database your ARMS deployment uses.

What's New:

  • Backend-mediated persistence via POST /api/v1/guardrails/{db_type}
  • Automatic database type discovery via GET /api/v1/db_type
  • Supported backends: mongodb, dynamodb, clickhouse
  • ARMS correlation with link_arms(), link_run_context(), or environment variables
  • Buffered event collection for input/output checks, generate results, tool authorization, and rate limiting
  • Optional text redaction with store_raw_text: false (SHA-256 digests)
  • Fail-soft and fail-hard write modes

Configuration:

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

Environment (shared with ARMS):

bash
export API_BASE_URL=https://your-arms-backend
export ELSAI_ARMS_API_KEY=your-api-key
export GUARDRAILS_ARMS_RUN_ID=abc123      # optional correlation
export GUARDRAILS_ARMS_PROJECT_ID=proj-456  # optional correlation

Python API:

python
rails = LLMRails.from_config("config.yml")
rails.guardrail_system.link_arms(arms)  # or link_run_context(...)
rails.generate(messages=[...])
rails.guardrail_system.end_run()

Full Documentation →

Data Exfiltration Detection ​

Output-side guardrail that detects credentials, bulk sensitive data, and export-style payloads in LLM responses.

What's New:

  • Three detectors: secrets, bulk sensitive data, and abnormal output patterns
  • Risk scoring with configurable warn and block thresholds
  • Warn action masks sensitive spans; block action stops the response
  • Regex-based secret detection plus optional detect-secrets plugin integration
  • Bulk detection for emails, phone numbers, SSNs, and AWS keys
  • Abnormal pattern detection for CSV/JSON exports, Base64 blocks, and high-entropy payloads
  • Results on GuardrailResult.exfiltration and persisted in ARMS storage runs

Configuration:

yaml
guardrails:
  output_checks: true

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

Python API:

python
result = guardrail.check_output(response_text)
if result.exfiltration and result.exfiltration["action"] == "block":
    print("Blocked:", result.message)

Full Documentation →

Breaking Changes ​

Direct Database Storage Removed ​

Direct guardrails-to-database storage (guardrails.storage.backend: mongodb|dynamodb|clickhouse with connection strings) was removed. All persistence now goes through the ARMS Backend.

Migration:

yaml
# Removed — storage is disabled with a warning if still present
guardrails:
  storage:
    backend: mongodb

# Replace with ARMS Backend storage
guardrails:
  storage:
    enabled: true
    project: my-app
    arms_correlation: true
# Set API_BASE_URL and ELSAI_ARMS_API_KEY in the environment

Configuration Updates ​

New Configuration Sections:

  • guardrails.storage — ARMS Backend persistence settings
  • guardrails.data_exfiltration — Output exfiltration detection policy

Backward Compatibility: Data exfiltration and storage are disabled by default. Existing guardrail check configurations continue to work without changes. Only deployments using removed direct-database storage need to migrate.

Documentation Updates ​

New Documentation:

Updated Documentation:

Migration Guide ​

From v0.1.4 to v0.1.5 ​

No breaking changes for standard guardrail configurations. All v0.1.4 YAML policies work in v0.1.5 without modification.

If you used direct database storage, migrate to ARMS Backend storage (see breaking change above).

To use new features, opt in:

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

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

Version 0.1.4 (June 2026) ​

New Features ​

Tool Authorization ​

Policy-driven tool access control for agent frameworks. Ensure agents can access only approved tools and operations, and prevent unauthorized actions such as database modifications or external API misuse.

What's New:

  • YAML policy with denied_tools, sensitive_tools, and role-based allowed_tools
  • Role-based access control (RBAC) with per-role tool allowlists
  • Sensitive tool gating requiring explicit approval metadata
  • Agent hooks via before_tool_call() for pre-execution authorization
  • LangGraph integration pattern with authorization nodes

Configuration:

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

Sample code: toolauth/config.yaml, toolauth/agent_langgraph.py

Full Documentation →

Rate Limiting & Abuse Prevention ​

Protect systems from excessive requests, infinite loops, and denial-of-wallet attacks by restricting requests, tool calls, and execution time per session.

What's New:

  • Per-session request limits (max_requests_per_session)
  • Per-session tool call quotas (max_tool_calls_per_session)
  • Cumulative tool execution time limits (max_tool_execution_seconds)
  • Session management with create_session() and get_session()
  • Agent hooks: before_request(), check_tool_call_limit(), record_tool_call()
  • Execution timers via start_execution_timer() and end_execution_timer()

Configuration:

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

Sample code: ratelimit/config.yaml, ratelimit/agent_langgraph.py

Full Documentation →

Improvements ​

Token Budget Enforcement ​

  • Added optional block_on_exceeded policy flag
  • When block_on_exceeded: true, requests exceeding the token budget are blocked
  • When block_on_exceeded: false, a warning is emitted and processing continues

Updated configuration:

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

Full Documentation →

Configuration Updates ​

New Configuration Sections:

  • guardrails.tool_authorization — Tool allowlists, denylists, and role-based permissions
  • guardrails.rate_limit — Session request, tool call, and execution time limits

Updated Configuration:

  • guardrails.token_budget.block_on_exceeded — Control block vs warn behavior

Backward Compatibility: All new features are disabled by default. Existing configurations continue to work without any changes.

Documentation Updates ​

New Documentation:

Updated Documentation:

Migration Guide ​

From v0.1.3 to v0.1.4 ​

No breaking changes. All v0.1.3 configurations work in v0.1.4 without modification.

To use new features, opt in:

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

  rate_limit:
    enabled: true
    max_requests_per_session: 5
    max_tool_calls_per_session: 50

Version 0.1.3 (June 2026) ​

New Features ​

PII/PHI Detection and Data Masking ​

A comprehensive guardrail for identifying sensitive personal and health information, applying policy-driven actions, and masking detected values before downstream processing.

What's New:

  • Entity-based PII detection using Microsoft Presidio Analyzer as pre-processing middleware
  • Support for PERSON, LOCATION, EMAIL_ADDRESS, PHONE_NUMBER, CREDIT_CARD, NRP, MEDICAL_LICENSE, US_SSN, IBAN_CODE, and IP_ADDRESS entity types
  • Configurable confidence thresholds with per-entity overrides
  • Policy-based actions: flag, block, review, or pass downstream for processing
  • Data masking for detected entities
  • Regex-based PHI pattern detection for healthcare identifiers
  • Audit logging with entity type, confidence score, action taken, session ID, and timestamp

Setup:

After installing the package, download the required spaCy model for PII/PHI detection:

bash
python -m spacy download en_core_web_lg

Configuration:

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

Use Cases:

  • Healthcare applications requiring PHI detection and masking
  • Financial services with strict PII handling policies
  • Compliance-driven audit logging for sensitive data access
  • Applications needing per-entity-type policy control

Full Documentation →

Token Budget Enforcement ​

Compute token usage across the full request context and reject oversized requests before LLM processing.

What's New:

  • Full-context token calculation including system prompts, history, and user input
  • Configurable per-request and per-run token limits
  • Reserved output token allocation
  • Automatic rejection of requests exceeding configured budgets

Configuration:

yaml
guardrails:
  token_budget:
    enabled: true
    input_checks: true
    output_checks: true
    max_request_tokens: 50
    max_run_tokens: 80
    reserved_output_tokens: 10

Use Cases:

  • Cost control for high-volume LLM applications
  • Enforcing model context window limits
  • Session-level token caps for multi-turn conversations
  • Preventing runaway context growth

Full Documentation →

Configuration Updates ​

New Configuration Sections:

  • guardrails.pii — PII/PHI detection and data masking policy
  • guardrails.token_budget — Token budget enforcement policy

Backward Compatibility: All new features are disabled by default. Existing configurations continue to work without any changes.

Documentation Updates ​

New Documentation:

Updated Documentation:

Migration Guide ​

From v0.1.2 to v0.1.3 ​

No breaking changes. All v0.1.2 configurations work in v0.1.3 without modification.

To use new features, opt in:

yaml
guardrails:
  # Your existing config continues to work
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true

  # Optionally add new features
  pii:
    enabled: true
    default_mask: true
    entity_types:
      - EMAIL_ADDRESS
      - PHONE_NUMBER

  token_budget:
    enabled: true
    max_request_tokens: 50
    max_run_tokens: 80
    reserved_output_tokens: 10

Version 0.1.2 (May 2026) ​

Bug Fixes ​

  • Fixed bugs in off-topic detection

Improvements ​

  • Added large text processing support for toxicity detection
  • Added large text processing support for sensitive data detection
  • Added support for elsai-model 2.0.0

Migration Guide ​

From v0.1.1 to v0.1.2 ​

No breaking changes. All v0.1.1 configurations work in v0.1.2 without modification.

Version 0.1.1 (January 2026) ​

New Features ​

Off-Topic Detection ​

A powerful new guardrail that helps maintain focused conversations by detecting when user input deviates from allowed topics.

What's New:

  • Configure multiple allowed topics with names and descriptions
  • Semantic similarity matching for intelligent topic detection
  • Flexible blocking modes (block or detect-only)
  • Perfect for specialized chatbots and domain-specific assistants

Configuration:

yaml
guardrails:
  check_off_topic: true
  block_off_topic: true
  allowed_topics:
    - name: "Customer Support"
      description: "Product questions, order help, and customer service"
    - name: "Technical Issues"
      description: "Installation, troubleshooting, and technical problems"

Python API:

python
config = GuardrailConfig(
    check_off_topic=True,
    block_off_topic=True,
    allowed_topics=[
        {"name": "Support", "description": "Customer support topics"}
    ]
)

Use Cases:

  • Customer service bots focused on specific products
  • Educational assistants maintaining subject boundaries
  • HR assistants handling specific policy areas
  • Domain-specific tools with clear functional scope

Full Documentation →

SQL Syntax Validation ​

Validate SQL query syntax before execution, catching errors early and improving application reliability.

What's New:

  • Support for 7 major SQL dialects
  • Syntax validation for user input or LLM-generated queries
  • Prevent malformed queries from reaching your database
  • Essential for text-to-SQL and query builder applications

Supported Dialects:

  • PostgreSQL
  • MySQL/MariaDB
  • Microsoft SQL Server
  • SQLite
  • MongoDB
  • Oracle Database
  • Amazon Redshift

Configuration:

yaml
guardrails:
  check_sql_syntax: true
  sql_dialect: "postgresql"  # Choose your database dialect

Python API:

python
config = GuardrailConfig(
    check_sql_syntax=True,
    sql_dialect="mysql"
)

Use Cases:

  • Text-to-SQL applications with natural language queries
  • SQL query builders and validation tools
  • Database migration script validation
  • Query validation APIs and services

Full Documentation →

Configuration Updates ​

New GuardrailConfig Fields:

python
class GuardrailConfig:
    check_off_topic: bool = False          # Enable off-topic detection
    check_sql_syntax: bool = False         # Enable SQL syntax validation
    block_off_topic: bool = True           # Block off-topic inputs
    allowed_topics: list[dict[str, str]] | None = None  # Allowed topics list
    sql_dialect: str = "mysql"             # SQL dialect for validation

Backward Compatibility: All new features are disabled by default. Existing configurations continue to work without any changes.

Documentation Updates ​

New Documentation:

Updated Documentation:

Migration Guide ​

From v0.1.0 to v0.1.1 ​

No breaking changes! All v0.1.0 configurations work in v0.1.1 without modification.

To use new features, simply opt-in:

yaml
# Your existing config continues to work
guardrails:
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true

# Optionally add new features
  check_off_topic: true
  allowed_topics:
    - name: "Support"
      description: "Customer support topics"
  
  check_sql_syntax: true
  sql_dialect: "postgresql"

Configuration Recommendations ​

For Customer Support Bots:

yaml
guardrails:
  check_toxicity: true
  check_sensitive_data: true
  check_off_topic: true  # Keep conversations focused
  block_off_topic: true
  allowed_topics:
    - name: "Product Support"
      description: "Questions about products and services"

For Text-to-SQL Applications:

yaml
guardrails:
  input_checks: false
  output_checks: true
  check_sql_syntax: true  # Validate generated SQL
  sql_dialect: "postgresql"

For General Purpose Assistants:

yaml
guardrails:
  check_toxicity: true
  check_sensitive_data: true
  check_semantic: true
  # Leave new features disabled for unrestricted conversation

Examples ​

Off-Topic Detection Example ​

python
from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  check_off_topic: true
  block_off_topic: true
  allowed_topics:
    - name: "Travel Planning"
      description: "Questions about destinations, itineraries, bookings, and travel tips"
    - name: "Hotel Recommendations"
      description: "Advice on accommodations, hotel reviews, and booking options"
"""

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

# On-topic: passes
response = rails.generate(
    messages=[{"role": "user", "content": "What are the best hotels in Paris?"}]
)

# Off-topic: blocked
response = rails.generate(
    messages=[{"role": "user", "content": "How do I fix my computer?"}]
)

SQL Syntax Validation Example ​

python
from elsai_guardrails.guardrails import LLMRails, RailsConfig

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

guardrails:
  output_checks: true
  check_sql_syntax: true
  sql_dialect: "mysql"
"""

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

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

# Generated SQL is automatically validated
if response.output_result.passed:
    print("Valid SQL:", response.response)
else:
    print("Invalid SQL detected:", response.output_result.message)

Bug Fixes ​

None - this is a feature release.

Performance Improvements ​

  • Optimized semantic similarity calculations for off-topic detection
  • Efficient SQL parsing with minimal overhead
  • Improved overall guardrail processing speed

Dependencies ​

No new external dependencies required. All new features use existing infrastructure.

Resources ​

Version 0.1.0 ​

Version 0.1.0 (Initial Release) ​

Core Features:

  • Toxicity detection with configurable thresholds
  • Sensitive data detection (PII, emails, phone numbers, etc.)
  • Semantic classification for jailbreak and injection attempts
  • Multi-LLM support (OpenAI, Anthropic, Gemini, AWS Bedrock)
  • Flexible YAML-based configuration
  • Python API with sync and async support
  • Separate input/output validation
  • Detailed result reporting

LLM Providers Supported:

  • OpenAI (GPT-3.5, GPT-4)
  • Azure OpenAI
  • Anthropic Claude
  • Google Gemini
  • AWS Bedrock

Documentation:

  • Complete API reference
  • Configuration guides
  • Integration examples
  • Best practices

Support ​

For questions, issues, or feature requests:

Latest Version: 0.1.5 | Release Date: July 2026

Copyright © 2026 elsai foundry.

Built with VitePress