---
name: elsai-guardrails
description: Guide for elsai Guardrails (elsai-guardrails) — LLMRails, GuardrailSystem, YAML config, and safety checks
allowed-tools: Read Write Edit Bash
metadata:
  version: "0.1.5"
  install: "pip install --extra-index-url https://elsai-core-package.optisolbusiness.com/root/elsai-guardrails/ elsai-guardrails==0.1.5"
---

# elsai Guardrails — Developer Skill

Use this skill whenever the developer adds **elsai Guardrails** (`elsai-guardrails`) — toxicity, sensitive data, semantic checks, off-topic, SQL, PII, or ARMS storage.

---

# elsai Guardrails

You are an expert in **elsai Guardrails** (`elsai-guardrails`). Use the real package APIs for input/output rails — do not invent rail names or fake helper modules.

## Installation

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

Requires Python **3.10+**.

For PII/PHI detection, also install the spaCy model:

```bash
python -m spacy download en_core_web_lg
```

## Package layout

```
elsai_guardrails.guardrails
├── LLMRails / RailsConfig     # LLM generate + rails (YAML-driven)
├── GuardrailSystem            # standalone check_input / check_output
├── GuardrailConfig            # Python config for GuardrailSystem
└── GuardrailResult            # passed, toxicity, sensitive_data, …
```

## LLMRails (generate with rails)

```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
  toxicity_threshold: 0.7
  block_toxic: true
  block_sensitive_data: true
"""

config = RailsConfig.from_content(yaml_content=yaml_content)
# or: RailsConfig.from_content(config_path="config.yml")
rails = LLMRails(config=config)

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

# Detailed result
result = rails.generate(messages=[...], return_details=True)
if result["blocked"]:
    print(result["block_reason"], result["final_response"])
```

## GuardrailSystem (checks 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)

result = guardrail.check_input("My email is user@example.com")
# result.passed, result.toxicity, result.sensitive_data, result.semantic_class
```

## Common YAML guardrail flags

Enable only what you need:

| Flag / block | Purpose |
|---|---|
| `input_checks` / `output_checks` | Run input or output rails |
| `check_toxicity` / `block_toxic` | Toxicity |
| `check_sensitive_data` / `block_sensitive_data` | Sensitive data |
| `check_semantic` | Jailbreak / injection-style classification |
| `check_off_topic` / `allowed_topics` | Topic focus |
| `check_sql_syntax` / `sql_dialect` | SQL validation |
| `data_exfiltration` | Credential / bulk-export leaks in output |
| `storage` | Persist runs via ARMS Backend |

ARMS storage env (when `storage.enabled`):

```bash
export API_BASE_URL=https://your-arms-backend
export ELSAI_ARMS_API_KEY=your-api-key
```

Encoder for semantic checks: if unset, HuggingFace encoder is the default (local, no API key). Optional `ENCODER_TYPE` and related vars are documented under Guardrails installation.

## Do / don't

- **Do** use `LLMRails` + `RailsConfig` for generate-with-rails; `GuardrailSystem` for validate-only
- **Do** load LLM API keys from env — not committed YAML if avoidable
- **Do** install `en_core_web_lg` when enabling PII/PHI
- **Don't** invent rail classes or import paths outside `elsai_guardrails.guardrails`
- **Don't** skip documenting which checks are enabled in examples

## Docs

- Overview: `/guardrails/overview`
- Installation: `/guardrails/getting-started/installation`
- Quick start: `/guardrails/getting-started/quick-start`
- Configuration: `/guardrails/configuration/overview`
- Python API: `/guardrails/python-api/overview`
- Library: `/guardrails/guardrails-library/overview`