Installation Guide

This guide will help you install elsai Guardrails and set up your development environment.

Prerequisites

• Python 3.10 or higher
• pip package manager

Installation

Basic Installation

pip install --extra-index-url https://elsai-core-package.optisolbusiness.com/root/elsai-guardrails/ elsai-guardrails==0.1.8

PII/PHI Detection Setup

If you plan to use PII/PHI Detection and Data Masking, download the required spaCy language model after installing the package:

python -m spacy download en_core_web_lg

This step is required for PII/PHI detection to work. Without this model, entity-based detection will not function correctly.

Optional Environment Variables

For semantic content classification (jailbreak detection, prompt injection, etc.), you can configure an embedding encoder. The encoder type is configured via the ENCODER_TYPE environment variable.

If encoder environment variables are not provided, the system will automatically use HuggingFace encoder as the default (local, no API key required).

Encoder Configuration

Set the encoder type:

export ENCODER_TYPE="openai"  # or any supported encoder from the table below

Supported Encoder Types

Encoder Type	API Key Required	Speed	Quality	Example Environment Variables
huggingface	No (default)	Medium	Good	No configuration needed
openai	Yes	Fast	Excellent	OPENAI_API_KEY
azure_openai	Yes	Fast	Excellent	AZURE_OPENAI_EMBEDDING_DEPLOYMENT AZURE_OPENAI_EMBEDDING_ENDPOINT AZURE_OPENAI_EMBEDDING_API_KEY AZURE_OPENAI_EMBEDDING_API_VERSION
cohere	Yes	Fast	Excellent	COHERE_API_KEY
google	Yes	Fast	Excellent	GOOGLE_API_KEY
fastembed	No	Very Fast	Good	No configuration needed
ollama	No	Medium	Good	OLLAMA_BASE_URL (optional)
mistral	Yes	Fast	Excellent	MISTRAL_API_KEY
voyage	Yes	Fast	Excellent	VOYAGE_API_KEY
jina	Yes	Fast	Excellent	JINA_API_KEY
bedrock	Yes	Fast	Excellent	AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION
bm25	No	Very Fast	Fair	No configuration needed
tfidf	No	Very Fast	Fair	No configuration needed
local	No	Medium	Variable	LOCAL_MODEL (model name)

Example: Using Azure OpenAI Encoder

export ENCODER_TYPE="azure_openai"
export AZURE_OPENAI_EMBEDDING_DEPLOYMENT="text-embedding-ada-002"
export AZURE_OPENAI_EMBEDDING_ENDPOINT="https://your-endpoint.openai.azure.com"
export AZURE_OPENAI_EMBEDDING_API_KEY="your-azure-api-key"
export AZURE_OPENAI_EMBEDDING_API_VERSION="2024-02-15-preview"

For complete encoder configuration details, see the Semantic Classification documentation.

ARMS Storage Setup (v0.1.5)

If you plan to use ARMS Storage, set Backend credentials (shared with ARMS):

export API_BASE_URL="https://your-arms-backend"
export ELSAI_ARMS_API_KEY="your-api-key"
# Optional correlation ids:
export GUARDRAILS_ARMS_RUN_ID="your-run-id"
export GUARDRAILS_ARMS_PROJECT_ID="your-project-id"

Enable storage in your guardrails policy:

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

Data Exfiltration Setup (v0.1.5)

If you plan to use Data Exfiltration Detection, enable it on output checks:

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

The optional detect-secrets package improves credential detection when installed:

pip install detect-secrets

Regex-based detection still runs when the plugin is not installed.

Agent Trust Setup (v0.1.7)

If you plan to use Agent Trust, no additional packages are required — attestation uses Python's standard library hmac/hashlib. What you do need is one environment variable per registered agent, holding that agent's HMAC signing secret.

Required environment variables — one per agent in guardrails.agent_trust.agents, matching whatever ${VAR} placeholder you reference for that agent's secret in policy YAML:

export PLANNER_AGENT_SECRET="<generate — see below>"
export EXECUTOR_AGENT_SECRET="<generate — see below>"
# ...one per agent_id you register

These are not issued by any provider — generate your own random value per agent:

python -c "import secrets; print(secrets.token_hex(32))"

Run this once per agent and assign each output to that agent's environment variable. Reference the variables from policy YAML with ${VAR} so real secrets never get committed to the file:

guardrails:
  agent_trust:
    enabled: true
    agents:
      - agent_id: planner-agent
        trust_level: trusted
        capabilities: [delegate_task]
        secret: ${PLANNER_AGENT_SECRET}
      - agent_id: executor-agent
        trust_level: restricted
        capabilities: [execute_tool]
        secret: ${EXECUTOR_AGENT_SECRET}

Optional: if you wire content_validator_from_guardrail_system() to reuse PII/toxicity/off-topic checks for independent output re-validation (Layer D), the environment requirements for those checks apply as well — see PII/PHI Detection Setup and the Semantic Classification encoder configuration above.

Never commit real agent secrets to source control or to policy YAML directly — keep them in .env (gitignored) or a secrets manager, and rotate with AgentRegistry.rotate_secret() if one is ever exposed.

Verify Installation

Check that the package is installed correctly:

pip show elsai-guardrails

Next Steps

• Quick Start Guide
• Configuration
• Python API Reference
• Editor Setup — Cursor, Copilot, and Claude Code configs for elsai-guardrails