> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vijil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Detection Methods

> Reference for every registered Dome Detector, including configuration parameters, requirements, and execution options.

Dome registers 36 detection methods across Security, Moderation, Privacy,
Integrity, Generic, and Policy categories.

Each entry lists the extras it needs. See [Install Dome](https://docs.vijil.ai/developer-guide/protect/installation.md)
for the extras and environment variables, and [Configure Guardrails](https://docs.vijil.ai/developer-guide/protect/configuring-guardrails.md)
for how to place a Detector in a Guard.

## Security

Security Detectors identify prompt injections, jailbreak attempts, and
encoded or obfuscated payloads.

### `prompt-injection-deberta-v3-base`

DeBERTa v3 classifier for prompt injection detection.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `truncation` | `bool` | `True` | Truncate each model window to `max_length`. |
| `max_length` | `int` | `512` | Token limit per window. |
| `window_stride` | `int` | `256` | Token step between windows. |

* **Class:** `DebertaPromptInjectionModel`
* **Model:** [`protectai/deberta-v3-base-prompt-injection-v2`](https://huggingface.co/protectai/deberta-v3-base-prompt-injection-v2)

### `prompt-injection-deberta-finetuned-11122024`

Fine-tuned DeBERTa classifier for prompt injection detection.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `truncation` | `bool` | `True` | Truncate each model window to `max_length`. |
| `max_length` | `int` | `512` | Token limit per window. |
| `window_stride` | `int` | `256` | Token step between windows. |

* **Class:** `DebertaTuned60PromptInjectionModel`
* **Model:** [`vijil/pi_deberta_finetuned_11122024`](https://huggingface.co/vijil/pi_deberta_finetuned_11122024)

### `prompt-injection-mbert`

ModernBERT classifier for prompt injection detection.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_threshold` | `float` | `0.5` | Uncalibrated model score at or above which the Detector starts flagging content. |
| `truncation` | `bool` | `True` | Truncate each model window to `max_length`. |
| `max_length` | `int` | `8192` | Token limit per window. |
| `window_stride` | `int` | `4096` | Token step between windows. |

* **Class:** `MBertPromptInjectionModel`
* **Model:** [`vijil/prompt-injection-v5-20260827`](https://huggingface.co/vijil/prompt-injection-v5-20260827)
* **Text processor:** `answerdotai/ModernBERT-base`

The `score_threshold` value is a raw `softmax` score, not a calibrated
probability. Choose a threshold by testing traffic that resembles your
production inputs instead of relying on a fixed score range.

### `prompt-injection-mbert-safeguard`

Prompt injection classification through an OpenAI-compatible chat completions
endpoint. The default endpoint uses GPT-OSS-Safeguard-20B through the `groq`
provider.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** API-only detection; the Detector truncates oversize input by character count.
* **Requires:** The `local` extra for current registration and an API key.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str \| None` | `None` | API key; falls back to the environment variable named by `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Environment variable fallback for `api_key`. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | OpenAI-compatible base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Model sent to the endpoint. |
| `temperature` | `float` | `0.0` | Sampling temperature. |
| `max_tokens` | `int` | `2000` | Response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Reasoning setting; use `None` to omit it. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before the request; use `None` to disable it. |

> [!NOTE]
>
> Keep `max_tokens` large enough for reasoning models to return a verdict. The
> current parser treats an empty response as safe.

* **Class:** `PImbertSafeguard`

### `prompt-injection-mbert-hybrid`

Runs a fast ModernBERT stage first and sends low-confidence results to a
Safeguard endpoint. The fast stage can run locally or through a direct
inference endpoint.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Fast-stage classification with conditional API escalation.
* **Requires:** The `local` extra; Safeguard credentials are optional because the method falls back to the fast verdict.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str \| None` | `None` | `Vijil` inference base URL for the fast stage; `/v1/chat/completions` must return a numeric score. |
| `vijil_inference_model` | `str \| None` | `None` | Override the direct fast-stage model. |
| `vijil_inference_api_key` | `str \| None` | `None` | Direct inference key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `confidence_threshold` | `float` | `0.85` | Fast-stage confidence below which the Detector calls the Safeguard. |
| `score_threshold` | `float` | `0.5` | Uncalibrated fast-stage model score threshold. |
| `truncation` | `bool` | `True` | Truncate local fast-stage windows. |
| `max_length` | `int` | `8192` | Token limit per local fast-stage window. |
| `window_stride` | `int` | `4096` | Token step between local fast-stage windows. |
| `api_key` | `str \| None` | `None` | Safeguard key; falls back to `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Safeguard key environment variable. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | Safeguard base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Safeguard model. |
| `temperature` | `float` | `0.0` | Safeguard sampling temperature. |
| `max_tokens` | `int` | `2000` | Safeguard response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Safeguard reasoning setting. |
| `timeout_seconds` | `float` | `10.0` | Safeguard request timeout. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before escalation. |

* **Class:** `PImbertHybrid`
* **Local model:** [`vijil/prompt-injection-v5-20260827`](https://huggingface.co/vijil/prompt-injection-v5-20260827)

### `prompt-injection-mbert-remote`

Runs the ModernBERT prompt injection model through a `Vijil` inference
deployment. The client calls `/v1/chat/completions` and expects a numeric
score in the response message content.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Direct HTTP inference; this method does not use automatic routing.
* **Requires:** The `local` extra for current registration and `vijil_inference_url`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str` | Required | `Vijil` inference base URL. |
| `vijil_inference_model` | `str \| None` | `None` | Model override; otherwise uses the registered prompt injection model. |
| `vijil_inference_api_key` | `str \| None` | `None` | API key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `score_threshold` | `float` | `0.5` | Uncalibrated model score at or above which the Detector starts flagging content. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |

* **Class:** `MBertPromptInjectionRemote`
* **Default model:** [`vijil/prompt-injection-v5-20260827`](https://huggingface.co/vijil/prompt-injection-v5-20260827)

### `security-promptguard`

Meta Prompt Guard classifier for jailbreak and prompt injection detection.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model.
* **Requires:** The `local` extra.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_threshold` | `float` | `0.5` | Jailbreak probability at which the Detector starts flagging content. |
| `truncation` | `bool` | `True` | Truncate each model window. |
| `max_length` | `int` | `512` | Token limit per window. |
| `window_stride` | `int` | `256` | Token step between windows. |

* **Class:** `PromptGuardSecurityModel`
* **Model:** [`meta-llama/Prompt-Guard-86M`](https://huggingface.co/meta-llama/Prompt-Guard-86M)

### `security-llm`

Prompt-engineered security classification through LiteLLM.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra and credentials for the selected provider.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `hub_name` | `str` | `VIJIL_LLM_HUB` or `"openai"` | Provider: `openai`, `together`, or `groq`. |
| `model_name` | `str` | `VIJIL_LLM_MODEL` or `"gpt-4-turbo"` | Provider model name. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |

* **Class:** `LlmSecurity`

### `security-embeddings`

Compares content embeddings with a bundled corpus of known jailbreaks.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local embedding and nearest-neighbor search.
* **Requires:** The `local` extra. The `embeddings` extra is also required when `in_mem=False`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `engine` | `str` | `"SentenceTransformers"` | Embedding engine. |
| `model` | `str` | `"all-MiniLM-L6-v2"` | Embedding model. |
| `threshold` | `float` | `0.7` | Similarity above which the Detector flags content. |
| `in_mem` | `bool` | `True` | Use the in-memory index instead of Annoy. |

* **Class:** `JailbreakEmbeddingsDetector`

### `jb-length-per-perplexity`

Flags jailbreaks using the ratio between input length and GPT-2 perplexity.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local model heuristic.
* **Requires:** The `local` extra.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model_id` | `str` | `"gpt2-large"` | Hugging Face model used for perplexity. |
| `batch_size` | `int` | `16` | Stored batch-size setting. |
| `stride_length` | `int` | `512` | Stride used during perplexity calculation. |
| `threshold` | `float` | `89.79` | Length-to-perplexity threshold. |

* **Class:** `LengthPerPerplexityModel`

### `jb-prefix-suffix-perplexity`

Calculates perplexity separately for the beginning and end of the input.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local model heuristic.
* **Requires:** The `local` extra.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model_id` | `str` | `"gpt2-large"` | Hugging Face model used for perplexity. |
| `batch_size` | `int` | `16` | Stored batch-size setting. |
| `stride_length` | `int` | `512` | Stride used during perplexity calculation. |
| `prefix_threshold` | `float` | `1845.65` | Prefix perplexity threshold. |
| `suffix_threshold` | `float` | `1845.65` | Suffix perplexity threshold. |
| `prefix_length` | `int` | `20` | Number of prefix words. |
| `suffix_length` | `int` | `20` | Number of suffix words. |

* **Class:** `PrefixSuffixPerplexityModel`

### `encoding-heuristics`

Detects encoded or obfuscated payloads with local rules.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local rules.
* **Requires:** The core install.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `threshold_map` | `dict` | See below | Per-encoding threshold overrides. |

| Encoding Type | Default Threshold |
| - | - |
| `base64` | `0.7` |
| `rot13` | `0.7` |
| `ascii_escape` | `0.05` |
| `hex_encoding` | `0.15` |
| `url_encoding` | `0.15` |
| `cyrillic_homoglyphs` | `0.05` |
| `mixed_scripts` | `0.05` |
| `zero_width` | `0.01` |
| `excessive_whitespace` | `0.4` |

* **Class:** `EncodingHeuristicsDetector`

## Moderation

Moderation Detectors identify toxic, harmful, stereotyped, or otherwise
inappropriate content.

### `moderation-deberta`

DeBERTa classifier for toxicity scoring.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `truncation` | `bool` | `True` | Truncate each model window. |
| `max_length` | `int` | `208` | Token limit per window. |
| `window_stride` | `int` | `104` | Token step between windows. |
| `device` | `str \| None` | `None` | Torch device; automatically selects CUDA when available. |

* **Class:** `ToxicityDeberta`
* **Model:** [`cooperleong00/deberta-v3-large_toxicity-scorer`](https://huggingface.co/cooperleong00/deberta-v3-large_toxicity-scorer)

### `moderation-mbert`

ModernBERT classifier for toxic content.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_threshold` | `float` | `0.5` | Toxicity probability at which the Detector starts flagging content. |
| `truncation` | `bool` | `True` | Truncate each model window. |
| `max_length` | `int` | `8192` | Token limit per window. |
| `window_stride` | `int` | `4096` | Token step between windows. |

* **Class:** `MBertToxicContentModel`
* **Model:** `vijil/vijil_dome_toxic_content_detection`
* **Text processor:** `answerdotai/ModernBERT-base`

### `moderation-mbert-safeguard`

Toxicity classification through an OpenAI-compatible chat completions
endpoint. The default endpoint uses GPT-OSS-Safeguard-20B through the `groq`
provider.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** API-only detection; the Detector truncates oversize input by character count.
* **Requires:** The `local` extra for current registration and an API key.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str \| None` | `None` | API key; falls back to the environment variable named by `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Environment variable fallback for `api_key`. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | OpenAI-compatible base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Model sent to the endpoint. |
| `temperature` | `float` | `0.0` | Sampling temperature. |
| `max_tokens` | `int` | `2000` | Response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Reasoning setting; use `None` to omit it. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before the request; use `None` to disable it. |

> [!NOTE]
>
> Keep `max_tokens` large enough for reasoning models to return a verdict. The
> current parser treats an empty response as safe.

* **Class:** `ModerationMbertSafeguard`

### `moderation-mbert-hybrid`

Runs a fast ModernBERT toxicity stage first and sends low-confidence results
to a Safeguard endpoint. The fast stage can run locally or through a direct
inference endpoint.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Fast-stage classification with conditional API escalation.
* **Requires:** The `local` extra; Safeguard credentials are optional because the method falls back to the fast verdict.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str \| None` | `None` | `Vijil` inference base URL for the fast stage; `/v1/chat/completions` must return a numeric score. |
| `vijil_inference_model` | `str \| None` | `None` | Override the direct fast-stage model. |
| `vijil_inference_api_key` | `str \| None` | `None` | Direct inference key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `confidence_threshold` | `float` | `0.85` | Fast-stage confidence below which the Detector calls the Safeguard. |
| `score_threshold` | `float` | `0.5` | Fast-stage toxicity threshold. |
| `truncation` | `bool` | `True` | Truncate local fast-stage windows. |
| `max_length` | `int` | `8192` | Token limit per local fast-stage window. |
| `window_stride` | `int` | `4096` | Token step between local fast-stage windows. |
| `api_key` | `str \| None` | `None` | Safeguard key; falls back to `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Safeguard key environment variable. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | Safeguard base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Safeguard model. |
| `temperature` | `float` | `0.0` | Safeguard sampling temperature. |
| `max_tokens` | `int` | `2000` | Safeguard response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Safeguard reasoning setting. |
| `timeout_seconds` | `float` | `10.0` | Safeguard request timeout. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before escalation. |

* **Class:** `ModerationMbertHybrid`
* **Local model:** `vijil/vijil_dome_toxic_content_detection`

### `moderation-mbert-remote`

Runs the ModernBERT toxicity model through a `Vijil` inference deployment. The
client calls `/v1/chat/completions` and expects a numeric score in the
response message content.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Direct HTTP inference; this method does not use automatic routing.
* **Requires:** The `local` extra for current registration and `vijil_inference_url`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str` | Required | `Vijil` inference base URL. |
| `vijil_inference_model` | `str \| None` | `None` | Model override; otherwise uses the registered toxicity model. |
| `vijil_inference_api_key` | `str \| None` | `None` | API key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `score_threshold` | `float` | `0.5` | Score at which the Detector starts flagging content. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |

* **Class:** `MBertToxicContentRemote`
* **Default model:** `vijil/vijil_dome_toxic_content_detection`

### `moderations-oai-api`

Calls the OpenAI Moderation API and uses either the provider's flagged verdict
or configured per-category thresholds.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API.
* **Requires:** The `llm` extra and `OPENAI_API_KEY`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_threshold_dict` | `dict \| None` | `None` | Map provider category names to custom score thresholds. |

Without `score_threshold_dict`, the Detector uses the provider's `flagged`
value. Category keys must match those returned by the configured OpenAI
Moderation API.

* **Class:** `OpenAIModerations`
* **Default model:** `text-moderation-latest`

### `moderation-perspective-api`

Calls the Google Perspective API for toxicity and related attributes.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API.
* **Requires:** The `google` extra and a Perspective API key.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str \| None` | `None` | Google API key; falls back to `PERSPECTIVE_API_KEY`. |
| `attributes` | `dict` | `{"TOXICITY": {}}` | Attributes requested from Perspective. |
| `score_threshold` | `dict` | `{"TOXICITY": 0.5}` | Per-attribute thresholds. |

* **Class:** `PerspectiveAPI`

### `moderation-prompt-engineering`

Prompt-engineered moderation classification through LiteLLM.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra and credentials for the selected provider.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `hub_name` | `str` | `VIJIL_LLM_HUB` or `"openai"` | Provider: `openai`, `together`, or `groq`. |
| `model_name` | `str` | `VIJIL_LLM_MODEL` or `"gpt-4-turbo"` | Provider model name. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |

* **Class:** `LlmModerations`

### `moderation-flashtext`

Matches configured keywords and phrases with FlashText.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local keyword matching.
* **Requires:** The core install.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `banlist_filepaths` | `list[str] \| None` | `None` | Ban-list files; without a value, the Detector loads the bundled list. |

* **Class:** `KWBanList`

### `stereotype-eeoc-fast`

ModernBERT classifier for stereotypes and harmful generalizations about EEOC
protected classes. This Detector classifies one payload; it does not perform
counterfactual comparisons across a set of prompts.

* **Input:** Uses `prompt [SEP] response` when both fields are present; the Detector treats plain `text` as the prompt.
* **Execution:** Local chunked model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model_name` | `str` | `"vijil/stereotype-detector-v8-20260911"` | Classifier model. |
| `tokenizer_name` | `str` | `"answerdotai/ModernBERT-base"` | Text-processing model. |
| `score_threshold` | `float` | `0.6` | Raw model score at or above which the Detector starts flagging content. |
| `max_length` | `int` | `512` | Token limit per chunk. |

* **Class:** `StereotypeEEOCFast`
* **Model:** [`vijil/stereotype-detector-v8-20260911`](https://huggingface.co/vijil/stereotype-detector-v8-20260911)

### `stereotype-eeoc-safeguard`

EEOC stereotype classification through an OpenAI-compatible chat completions
endpoint. The default endpoint uses GPT-OSS-Safeguard-20B through the `groq`
provider.

* **Input:** Text or the complete structured payload query string.
* **Execution:** API-only detection; the Detector truncates oversize input by character count.
* **Requires:** The `local` extra for current registration and an API key.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str \| None` | `None` | API key; falls back to the environment variable named by `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Environment variable fallback for `api_key`. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | OpenAI-compatible base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Model sent to the endpoint. |
| `temperature` | `float` | `0.0` | Sampling temperature. |
| `max_tokens` | `int` | `2000` | Response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Reasoning setting; use `None` to omit it. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before the request; use `None` to disable it. |

> [!NOTE]
>
> Keep `max_tokens` large enough for reasoning models to return a verdict. The
> current parser treats an empty response as safe.

* **Class:** `StereotypeEEOCSafeguard`

### `stereotype-eeoc-hybrid`

Runs the fast EEOC classifier first and sends low-confidence results to a
Safeguard endpoint. The fast stage can run locally or through a direct
inference endpoint.

* **Input:** Uses the structured prompt and response when available.
* **Execution:** Fast-stage classification with conditional API escalation.
* **Requires:** The `local` extra; Safeguard credentials are optional because the method falls back to the fast verdict.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str \| None` | `None` | `Vijil` inference base URL for the fast stage; `/v1/chat/completions` must return a numeric score. |
| `vijil_inference_model` | `str \| None` | `None` | Override the direct fast-stage model. |
| `vijil_inference_api_key` | `str \| None` | `None` | Direct inference key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `confidence_threshold` | `float` | `0.85` | Fast-stage confidence below which the Detector calls the Safeguard. |
| `model_name` | `str` | `"vijil/stereotype-detector-v8-20260911"` | Local fast-stage model. |
| `tokenizer_name` | `str` | `"answerdotai/ModernBERT-base"` | Local fast-stage text processor. |
| `score_threshold` | `float` | `0.6` | Raw fast-stage model score threshold. |
| `max_length` | `int` | `512` | Token limit per local fast-stage chunk. |
| `api_key` | `str \| None` | `None` | Safeguard key; falls back to `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Safeguard key environment variable. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | Safeguard base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Safeguard model. |
| `temperature` | `float` | `0.0` | Safeguard sampling temperature. |
| `max_tokens` | `int` | `2000` | Safeguard response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Safeguard reasoning setting. |
| `timeout_seconds` | `float` | `10.0` | Safeguard request timeout. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before escalation. |

* **Class:** `StereotypeEEOCHybrid`
* **Local model:** [`vijil/stereotype-detector-v8-20260911`](https://huggingface.co/vijil/stereotype-detector-v8-20260911)

### `stereotype-eeoc-remote`

Runs the EEOC stereotype model through a `Vijil` inference deployment. The
client calls `/v1/chat/completions` and expects a numeric score in the
response message content.

* **Input:** Text or the complete structured payload query string.
* **Execution:** Direct HTTP inference; this method does not use automatic routing.
* **Requires:** The `local` extra for current registration and `vijil_inference_url`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `vijil_inference_url` | `str` | Required | `Vijil` inference base URL. |
| `vijil_inference_model` | `str \| None` | `None` | Model override; otherwise uses the registered stereotype model. |
| `vijil_inference_api_key` | `str \| None` | `None` | API key; falls back to `VIJIL_INFERENCE_API_KEY`. |
| `score_threshold` | `float` | `0.6` | Raw model score at or above which the Detector starts flagging content. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |

* **Class:** `StereotypeEEOCRemote`
* **Default model:** [`vijil/stereotype-detector-v8-20260911`](https://huggingface.co/vijil/stereotype-detector-v8-20260911)

### `prompt-harmfulness-fast`

ModernBERT classifier for prompts that request harmful, dangerous, or illegal
content. Use this Detector in input Guards.

* **Input:** Uses only `prompt` when present; otherwise uses `text`. The Detector ignores any `response` field.
* **Execution:** Local sliding-window model, or automatic inference routing.
* **Requires:** The `local` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model_name` | `str` | `"vijil/prompt-harmfulness-detector"` | Classifier model. |
| `tokenizer_name` | `str` | `"answerdotai/ModernBERT-base"` | Text-processing model. |
| `score_threshold` | `float` | `0.95` | Harmfulness probability at which the Detector starts flagging the prompt. |
| `max_length` | `int` | `512` | Token limit per window. |
| `window_stride` | `int` | `256` | Token step between windows. |

* **Class:** `PromptHarmfulnessFast`
* **Model:** `vijil/prompt-harmfulness-detector`

### `prompt-harmfulness-safeguard`

Prompt harmfulness classification through an OpenAI-compatible chat
completions endpoint. The default endpoint uses GPT-OSS-Safeguard-20B through
the `groq` provider. Use this Detector in input Guards.

* **Input:** Uses only `prompt` when present; otherwise uses `text`. The Detector ignores any `response` field.
* **Execution:** API-only detection; the Detector truncates oversize input by character count.
* **Requires:** The `local` extra for current registration and an API key.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `api_key` | `str \| None` | `None` | API key; falls back to the environment variable named by `api_key_name`. |
| `api_key_name` | `str` | `"GROQ_API_KEY"` | Environment variable fallback for `api_key`. |
| `base_url` | `str` | `"https://api.groq.com/openai/v1"` | OpenAI-compatible base URL. |
| `model` | `str` | `"openai/gpt-oss-safeguard-20b"` | Model sent to the endpoint. |
| `temperature` | `float` | `0.0` | Sampling temperature. |
| `max_tokens` | `int` | `2000` | Response token budget. |
| `reasoning_effort` | `str \| None` | `"low"` | Reasoning setting; use `None` to omit it. |
| `timeout_seconds` | `float` | `10.0` | Request timeout in seconds. |
| `max_input_chars` | `int \| None` | `400000` | Character limit before the request; use `None` to disable it. |

> [!NOTE]
>
> Keep `max_tokens` large enough for reasoning models to return a verdict. The
> current parser treats an empty response as safe.

* **Class:** `PromptHarmfulnessSafeguard`

## Privacy

Privacy Detectors identify PII and credentials. Both built-in Privacy
Detectors can sanitize content instead of leaving it flagged.

### `privacy-presidio`

Uses Microsoft Presidio for PII analysis and redaction.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local PII analysis, or automatic inference routing.
* **Requires:** The `pii` extra for local execution.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `score_threshold` | `float` | `0.5` | Confidence above which an entity is PII. |
| `anonymize` | `bool` | `True` | Return sanitized content instead of a flagged result. |
| `allow_list_files` | `list[str] \| None` | `None` | Files containing values excluded from detection. |
| `redaction_style` | `str` | `"labeled"` | `"labeled"` replacements or `"masked"` characters. |

When `anonymize=True`, the Detector returns the sanitized response with
`hit=False`. Set `anonymize=False` when the Guard must block detected PII.

* **Class:** `PresidioDetector`

### `detect-secrets`

Uses 25 Detect Secrets plugins to identify API keys, tokens, private keys,
and other credential formats.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Local pattern matching.
* **Requires:** The core install.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `censor` | `bool` | `True` | Return censored content instead of a flagged result. |

When `censor=True`, the Detector replaces detected values and returns
`hit=False`. Set `censor=False` when the Guard must block detected secrets.

* **Class:** `SecretDetector`

## Integrity

Integrity Detectors compare content with reference context. Pass context in
the Detector configuration or in `DomePayload.context`; the payload value
takes precedence.

### `hhem-hallucination`

Uses HHEM to score factual consistency between content and context.

* **Input:** Content plus reference context.
* **Execution:** Local model.
* **Requires:** The `local` extra and reference context.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `context` | `str` | `""` | Fallback reference context. |
| `factual_consistency_score_threshold` | `float` | `0.5` | The Detector flags scores below this value. |
| `trust_remote_code` | `bool` | `True` | Allow remote model code when loading the model. |

* **Class:** `HhemHallucinationModel`
* **Model:** [`vectara/hallucination_evaluation_model`](https://huggingface.co/vectara/hallucination_evaluation_model)
* **Text processor:** `google/flan-t5-base`

### `fact-check-roberta`

Uses RoBERTa to detect contradictions between content and reference context.
It does not flag unsupported claims unless the context contradicts them.

* **Input:** Content plus reference context.
* **Execution:** Local model.
* **Requires:** The `local` extra and reference context.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `context` | `str` | `""` | Fallback reference context. |

* **Class:** `RobertaFactCheckModel`
* **Model:** [`Dzeniks/roberta-fact-check`](https://huggingface.co/Dzeniks/roberta-fact-check)

### `hallucination-llm`

Uses a prompt-engineered LLM to assess content against reference context.

* **Input:** Content plus reference context.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra, provider credentials, and reference context.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `hub_name` | `str` | `VIJIL_LLM_HUB` or `"openai"` | Provider: `openai`, `together`, or `groq`. |
| `model_name` | `str` | `VIJIL_LLM_MODEL` or `"gpt-4-turbo"` | Provider model name. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |
| `context` | `str \| None` | `None` | Fallback reference context. |

* **Class:** `LlmHallucination`

### `fact-check-llm`

Uses a prompt-engineered LLM to fact-check content against reference context.

* **Input:** Content plus reference context.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra, provider credentials, and reference context.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `hub_name` | `str` | `VIJIL_LLM_HUB` or `"openai"` | Provider: `openai`, `together`, or `groq`. |
| `model_name` | `str` | `VIJIL_LLM_MODEL` or `"gpt-4-turbo"` | Provider model name. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |
| `context` | `str \| None` | `None` | Fallback reference context. |

* **Class:** `LlmFactcheck`

## Generic

Generic Detectors apply configurable LLM classification to use cases that do
not fit a specialized category.

### `generic-llm`

Uses a caller-provided system prompt and trigger words to classify content
through LiteLLM.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra and credentials for the selected provider.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `sys_prompt_template` | `str` | Required | System prompt template; use `$query_string` to insert the input. |
| `trigger_word_list` | `list[str]` | Required | Lowercase response text fragments that mark a hit. |
| `hub_name` | `str` | `VIJIL_LLM_HUB` or `"openai"` | Provider: `openai`, `together`, or `groq`. |
| `model_name` | `str` | `VIJIL_LLM_MODEL` or `"gpt-4-turbo"` | Provider model name. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |

* **Class:** `GenericLLMDetector`

### `policy-gpt-oss-safeguard`

Classifies content against one policy supplied as a Markdown file or inline
Markdown.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Provider API, or automatic inference routing.
* **Requires:** The `llm` extra, exactly one policy source, and provider credentials.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `policy_file` | `str \| None` | `None` | Path to policy Markdown. Mutually exclusive with `policy_content`. |
| `policy_content` | `str \| None` | `None` | Inline policy Markdown. Mutually exclusive with `policy_file`. |
| `hub_name` | `str` | `"groq"` | LLM provider. |
| `model_name` | `str` | `VIJIL_SAFEGUARD_MODEL` or `"openai/gpt-oss-safeguard-20b"` | Safeguard model. |
| `output_format` | `str` | `"policy_ref"` | `"binary"`, `"policy_ref"`, or `"with_rationale"`. |
| `reasoning_effort` | `str` | `"medium"` | `"low"`, `"medium"`, or `"high"`. |
| `api_key` | `str \| None` | `None` | Provider API key; `groq` falls back to `GROQ_API_KEY`. |
| `timeout` | `int` | `60` | Request timeout in seconds. |
| `max_retries` | `int` | `3` | Request retry limit. |
| `max_input_chars` | `int \| None` | `None` | Character limit before the request. |

* **Class:** `PolicyGptOssSafeguard`

## Policy

Policy Detectors check content against policy sections.

### `policy-sections`

Creates one `PolicyGptOssSafeguard` instance per matching section and checks
the sections concurrently. Callers can provide sections directly or load them
from S3.

* **Input:** Text or a structured payload flattened to its query string.
* **Execution:** Parallel provider API calls with optional FAISS retrieval.
* **Requires:** The `llm` extra. S3 loading requires `s3`; RAG requires `s3` and `embeddings`.

With RAG, the default OpenAI embedding engine reads `OPENAI_API_KEY`.
`SentenceTransformers` also requires the `local` extra. `FastEmbed` requires
a separate `pip install fastembed` because no Dome extra includes it.

Provide either `policy_sections` or both `policy_s3_bucket` and
`policy_s3_key`. Do not provide both sources.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `policy_s3_bucket` | `str \| None` | `None` | S3 bucket containing policy sections. |
| `policy_s3_key` | `str \| None` | `None` | S3 object key for the policy sections JSON. |
| `policy_sections` | `list[dict] \| None` | `None` | Direct section objects with `section_id`, `content`, and `applies_to`. |
| `applies_to` | `str \| list[str]` | `"input"` | Keep sections for `input`, `output`, or both. |
| `max_parallel_sections` | `int \| None` | `10` | Concurrent policy-section limit. |
| `model_name` | `str` | `VIJIL_SAFEGUARD_MODEL` or `"openai/gpt-oss-safeguard-20b"` | Model used for each section. |
| `reasoning_effort` | `str` | `"medium"` | `"low"`, `"medium"`, or `"high"`. |
| `hub_name` | `str` | `"groq"` | LLM provider used for each section. |
| `timeout` | `int \| None` | `60` | Request timeout in seconds. |
| `max_retries` | `int \| None` | `3` | Request retry limit. |
| `api_key` | `str \| None` | `None` | Provider API key. |
| `aws_access_key_id` | `str \| None` | `None` | Optional AWS access key override. |
| `aws_secret_access_key` | `str \| None` | `None` | Optional AWS secret key override. |
| `aws_session_token` | `str \| None` | `None` | Optional AWS session token. |
| `region_name` | `str \| None` | `None` | Optional AWS region override. |
| `cache_dir` | `str \| None` | `None` | Local cache directory; defaults under `~/.cache/vijil-dome`. |
| `use_rag` | `bool` | `False` | Retrieve relevant sections from a prebuilt FAISS index. |
| `faiss_s3_key` | `str \| None` | `None` | S3 key for the FAISS index; required with RAG. |
| `section_ids_s3_key` | `str \| None` | `None` | S3 key for the section-ID mapping; required with RAG. |
| `top_k` | `int` | `5` | RAG result limit. |
| `similarity_threshold` | `float` | `0.0` | RAG similarity lower bound. |
| `embedding_model` | `str` | `"text-embedding-ada-002"` | Query embedding model. |
| `embedding_engine` | `str` | `"OpenAI"` | `"OpenAI"`, `"FastEmbed"`, or `"SentenceTransformers"`. |

If RAG initialization fails, the current implementation logs a warning and
falls back to evaluating all matching sections.

* **Class:** `PolicySectionsDetector`

## Configuration Examples

> [!NOTE]
>
> Canonical methods marked for automatic inference routing accept
> `route = "auto" | "local" | "remote"`; `auto` is the default and uses
> `DOME_INFERENCE_URL` when configured. Without an explicit `route`,
> `DOME_LOCAL_DETECTORS` can keep a comma-separated list of method names local.
> Remote routing uses `threshold`, which defaults to `0.5`, while local methods
> use parameters such as `score_threshold`. Every method accepts
> `max_batch_concurrency`, which defaults to `5`. Explicit `*-remote` methods
> and hybrid fast stages use `vijil_inference_*` instead of this routing layer.

### Local Model

```toml theme={null}
[prompt-injection]
type = "security"
methods = ["prompt-injection-mbert"]

[prompt-injection.prompt-injection-mbert]
route = "local"
score_threshold = 0.7
max_batch_concurrency = 4
```

### Automatic Inference Service

Set `DOME_INFERENCE_URL`, then require remote execution for a
remote-capable canonical method:

```toml theme={null}
[prompt-injection]
type = "security"
methods = ["prompt-injection-mbert"]

[prompt-injection.prompt-injection-mbert]
route = "remote"
threshold = 0.7
```

This path calls `DOME_INFERENCE_URL/v1/detect`. It does not use the explicit
`prompt-injection-mbert-remote` method.

### Prompt Harmfulness

```python theme={null}
config = {
    "input-guards": ["harmful-prompt"],
    "harmful-prompt": {
        "type": "moderation",
        "methods": ["prompt-harmfulness-fast"],
        "prompt-harmfulness-fast": {
            "route": "local",
            "score_threshold": 0.95,
        },
    },
}
```

### Direct Policy Sections

```python theme={null}
config = {
    "input-guards": ["policy-input"],
    "policy-input": {
        "type": "policy",
        "methods": ["policy-sections"],
        "policy-sections": {
            "policy_sections": [
                {
                    "section_id": "customer-data",
                    "content": "Do not reveal customer personal data.",
                    "applies_to": ["input"],
                }
            ],
            "applies_to": "input",
            "hub_name": "groq",
        },
    },
}
```

## Sliding Window Behavior

Local DeBERTa, ModernBERT, Prompt Guard, and prompt harmfulness Detectors split
inputs that exceed their configured `max_length`:

* The Detector processes inputs that fit in one window unchanged.
* `window_stride` controls the token step and overlap between windows.
* Any positive window flags the complete input.
* Score-based Detectors report the highest score across windows.
* Optimized `detect_batch()` implementations flatten windows into one model
  call and then combine results for each original input.

The stereotype Detector uses its own `[SEP]`-centered chunking strategy and
does not expose `window_stride`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.