Detectors
A Detector inspects an arbitrary value for a class of security threat.
The user sends a value, a key, and an operation name to the detector.
The detector returns a DetectionResult.
Construction
Create a detector with the Detector constructor:
from qarai_agent_guard import Detector
detector = Detector(name="pii", default_rules="pii")
All parameters are keyword-only.
The detector default name is "detector":
detector = Detector(default_rules="pii")
print(detector.name) # detector
Give every detector a unique name when you use several detectors in one guard.
Parameters
| Parameter | Type | Default | Role |
|---|---|---|---|
lang |
str |
"en" |
Language for language-dependent default rules. |
name |
str |
"detector" |
Unique detector name. |
patterns |
list[dict] |
None |
Inline regex rule definitions. |
pattern_paths |
list[Path] |
None |
Paths to YAML rule files. |
loader |
PatternLoader |
Default loader | Loads rules from files. |
detector_type |
DetectorType or str |
"regex" |
Selects the detection mode. |
default_rules |
DefaultRules or str |
None |
Library-provided rule set. |
model |
ModelConfig |
None |
Model configuration for model detection. |
provider |
ModelProviderName or str |
None |
Provider whose default model is resolved from default_rules. |
rule_strategy |
RuleStrategy or str |
"precedence" |
Resolves explicit rules and defaults. |
combination_strategy |
CombinationStrategy or str |
"any" |
Combines regex and model results in mixed mode. |
inference_engine |
InferenceEngine |
Default engine | Runs model inference. |
Raises ConfigurationError when:
detector_typeis not"regex","model", or"mixed".default_rulesis not one of"prompt_injection","pii","secrets", orNone.combination_strategyis not one of"any","all", or"precedence".rule_strategyis not"precedence"or"extend".provideris not"huggingface","api", orNone.modelis given but is not aModelConfig.providercontradictsmodel.provider.- A regex or mixed detector has no
patterns, nopattern_paths, and nodefault_rules. - A model or mixed detector has no
modeland nodefault_ruleswith a default model for the requested provider.
Detection Modes
The detector_type parameter selects the detection mode.
Regex Detection Mode
detector_type="regex" evaluates regex rules only.
This is the default mode.
from qarai_agent_guard import Detector
detector = Detector(name="pii", default_rules="pii")
print(detector.detector_type) # DetectorType.REGEX
Model Detection Mode
detector_type="model" performs model inference only.
Regex rules are not loaded.
The detector needs a model configuration.
HuggingFace Provider
For models hosted on HuggingFace, the default provider is "huggingface". You can use a library default model for HuggingFace:
detector = Detector(
name="model_prompt_injection",
detector_type="model",
default_rules="prompt_injection",
)
This uses the HuggingFace default model because the provider defaults to "huggingface".
You can also pass an explicit model configuration:
from qarai_agent_guard.core.models import resolve_default_model
detector = Detector(
name="model_prompt_injection",
detector_type="model",
model=resolve_default_model("prompt_injection"),
)
To explicitly specify the HuggingFace provider:
detector = Detector(
name="hf_prompt_injection",
detector_type="model",
default_rules="prompt_injection",
provider="huggingface",
)
API-Based Provider
For models accessed through API endpoints, you must specify provider="api". The library supports different API providers, including OpenRouter, vLLM, and Ollama.
API Detection Behaviour (Default)
The default API configuration (used with default_rules="prompt_injection" and provider="api") expects the model to answer with exactly one word: safe or unsafe.
When using an API-based model, the following default behaviour applies:
| Situation | Behaviour |
|---|---|
| The value is empty text | No request. matched=False and no metadata["model"]. |
The model answers unsafe |
matched=True with the model severity (defaults to CRITICAL for unsafe results). |
The model answers safe |
matched=False. |
| The endpoint fails | The provider exception leaves inspect. |
| The answer has no usable text | ModelOutputError leaves inspect. |
The guard wraps these errors in DetectorExecutionError. The fail_behavior setting then decides between ALLOW and BLOCK. See Security Modes and Runtime Behaviour.
Provider Rules
Before configuring specific providers, note the following rules:
provideraccepts"huggingface","api", orNone.- An unknown value raises
ConfigurationError. providermust matchmodel.providerwhen both are set.- A mismatch raises
ConfigurationError. provideronly selects the default model. It does not change the detection mode.- The
Detectorconstructor has noapi_keyparameter.
If you specify default_rules="pii" with provider="api" and no explicit model, this raises ConfigurationError because there is no API default model for the PII rule set.
The API key is optional. Set it for services that require authentication, such as OpenRouter. vLLM and Ollama can use the same provider without a key when their server allows unauthenticated requests.
OpenRouter
To use OpenRouter, specify the OpenRouter endpoint, model name, and your API key. The model must answer with safe or unsafe for the default behaviour:
import os
from qarai_agent_guard.core.models import ModelConfig
config = ModelConfig(
provider="api",
model="gpt-oss-120b",
task="text-generation",
threshold=0.5,
api_key=os.environ["OPENROUTER_API_KEY"],
model_options={
"endpoint": "https://openrouter.ai/api/v1",
"messages": [
{
"role": "system",
"content": "You are a security classifier. Answer with exactly one word: safe or unsafe.",
}
],
},
inference_options={
"temperature": 0.0,
"max_tokens": 256,
},
)
detector = Detector(
name="openrouter_prompt_injection",
detector_type="model",
model=config,
)
vLLM
To use a self-hosted vLLM server, specify the vLLM endpoint. You may not need an API key if running locally without authentication. Ensure the model follows the safe/unsafe response format:
from qarai_agent_guard.core.models import ModelConfig
config = ModelConfig(
provider="api",
model="meta-llama/Meta-Llama-3-8B-Instruct",
task="text-generation",
threshold=0.5,
model_options={
"endpoint": "http://localhost:8000/v1",
"messages": [
{
"role": "system",
"content": "You are a security classifier. Answer with exactly one word: safe or unsafe.",
}
],
},
inference_options={
"temperature": 0.0,
"max_tokens": 256,
},
)
detector = Detector(
name="vllm_prompt_injection",
detector_type="model",
model=config,
)
Ollama
To use Ollama, specify the Ollama OpenAI-compatible endpoint. Ollama typically does not require an API key. Ensure the model follows the safe/unsafe response format:
from qarai_agent_guard.core.models import ModelConfig
config = ModelConfig(
provider="api",
model="llama3.2",
task="text-generation",
threshold=0.5,
model_options={
"endpoint": "http://localhost:11434/v1",
"messages": [
{
"role": "system",
"content": "You are a security classifier. Answer with exactly one word: safe or unsafe.",
}
],
},
inference_options={
"temperature": 0.0,
"max_tokens": 256,
},
)
detector = Detector(
name="ollama_prompt_injection",
detector_type="model",
model=config,
)
Model and mixed modes both work with API-based models.
See Model-Based Detection for the ModelConfig reference and the full API-based provider reference.
Mixed Detection Mode
detector_type="mixed" performs regex detection and model inference.
The combination_strategy parameter combines the two results.
detector = Detector(
name="mixed_prompt_injection",
detector_type="mixed",
default_rules="prompt_injection",
combination_strategy="any",
)
Rule Sources
A detector gets its regex rules from three sources:
| Source | Parameter | Role |
|---|---|---|
| Inline patterns | patterns |
Rules defined directly in Python. |
| Pattern files | pattern_paths |
Rules loaded from YAML files. |
| Default rules | default_rules |
Rules shipped with the library. |
Inline patterns
Pass rules as a list of dictionaries:
detector = Detector(
name="project_codename",
patterns=[
{
"id": "unreleased_codename",
"name": "Unreleased Project Codename",
"severity": "medium",
"pattern": r"\b(?:Aurora|Phoenix|Nimbus)-?\d{0,4}\b",
},
{
"id": "confidential_marker",
"name": "Confidential Marker",
"severity": "high",
"pattern": r"\bTOP SECRET\b",
},
],
)
Each rule requires four fields:
| Field | Type | Role |
|---|---|---|
id |
str |
Stable rule identifier. |
name |
str |
Human-readable rule name. |
severity |
str |
One of info, low, medium, high, critical. |
pattern |
str |
The regex expression. |
Pattern files
Point a detector at one or more YAML files:
from pathlib import Path
detector = Detector(
name="custom",
pattern_paths=[Path("detector_rules.yaml")],
)
Default rules
default_rules selects a library-provided rule set.
| Value | Rule set |
|---|---|
"prompt_injection" |
Language rules plus XML injection rules. |
"pii" |
PII rules: cards, IBAN, email, phone, passport. |
"secrets" |
Secrets rules: API keys, tokens, credentials. |
See Detection Patterns for the full rule listings.
Rule Resolution
The rule_strategy parameter defines how the rule sources combine.
Each strategy accepts the enum member RuleStrategy.PRECEDENCE or RuleStrategy.EXTEND, or the strings "precedence" and "extend".
Precedence strategy
rule_strategy="precedence" uses the first explicit source in this order:
- Inline
patterns pattern_pathsdefault_rules
Rules from the earlier sources are used. Rules from the later sources are ignored.
Extend strategy
rule_strategy="extend" combines all sources in this order:
default_rules- Rules loaded from
pattern_paths - Inline
patterns
Example: combine the PII default rules with an extra rule:
detector = Detector(
name="pii_ext",
default_rules="pii",
rule_strategy="extend",
patterns=[{"id": "employee_id", "name": "Employee ID", "severity": "high", "pattern": r"\bEMP-\d{6}\b"}],
)
Languages
The lang parameter selects the language for language-dependent rules.
The prompt_injection default rule set loads the language file for the selected language.
Supported values:
| Value | Language |
|---|---|
"en" |
English (default) |
"fr" |
French |
"ar" |
Arabic |
fr_detector = Detector(
name="prompt_injection_fr",
default_rules="prompt_injection",
lang="fr",
)
ar_detector = Detector(
name="prompt_injection_ar",
default_rules="prompt_injection",
lang="ar",
)
Raises ValueError for an unsupported language code.
Inspect
inspect checks a value for configured threats.
result = detector.inspect(
key="payload",
value="Please store IBAN FR1420041010050500013M02606.",
operation="write",
)
Parameters:
| Parameter | Type | Role |
|---|---|---|
key |
str |
Logical name or path of the value. |
value |
Any |
The value to inspect. |
operation |
str |
The operation on the value, for example "write". |
The detector converts the value to text before detection.
Returns a DetectionResult with these fields:
| Field | Type | Role |
|---|---|---|
detector |
str |
The detector name. |
matched |
bool |
Whether any rule or model matched. |
message |
str |
A summary message. |
matches |
list[Match] |
The individual rule hits. |
metadata |
dict |
Extra context for policy evaluation. |
model_detection_result |
ModelDetectionResult or None |
The model outcome for model and mixed modes. |
A Match has these fields:
| Field | Type | Role |
|---|---|---|
pattern_id |
str |
The id of the matched rule. |
pattern_name |
str |
The name of the matched rule. |
severity |
str |
The rule severity. |
match |
str |
The matched text span. |
The metadata dictionary always contains:
| Key | Type | Role |
|---|---|---|
language |
str |
The detector language. |
operation |
str |
The operation name. |
hit_count |
int |
The number of rule hits. |
For model and mixed modes, metadata["model"] contains:
| Key | Type | Role |
|---|---|---|
provider |
str |
The model provider. It is "huggingface" or "api". |
name |
str |
The model identifier. |
score |
float |
The detection score. |
severity |
str |
The model severity. |
The key metadata["model"] is missing when the value is empty text.
The detector returns before it calls the model.
Raises:
TypeErrorifkeyoroperationis not a string.ValueErrorifkeyoroperationis empty.
Example with a PII detector:
from qarai_agent_guard import Detector
detector = Detector(name="pii", default_rules="pii")
result = detector.inspect(
key="payload",
value="Contact jhon.smith@yahoo.com to schedule the demo.",
operation="write",
)
print(result.matched) # True
print(result.message) # PII pattern detected in 'payload'
print(result.matches[0].pattern_id) # email
A value with no matches returns matched=False:
result = detector.inspect(
key="payload",
value="What is machine learning?",
operation="write",
)
print(result.matched) # False
Redact
redact replaces sensitive data with markers.
For regex rules, the detector replaces each match with a marker of this format:
[REDACTED:<rule_id>]
Example:
redacted = detector.redact(
"Contact jhon.smith@yahoo.com"
)
print(redacted)
# Contact [REDACTED:email]
The entities parameter adds model-detected entities:
| Parameter | Type | Default | Role |
|---|---|---|---|
value |
Any |
Required | The value to redact. |
entities |
list[dict], ModelDetectionResult, DetectionResult |
None |
Model entities to redact. |
Each entity must contain start and end offsets.
The detector uses entity_group as the label when available.
The detector replaces model entities in reverse positional order. Earlier replacements do not invalidate the offsets of later entities.
Example:
detector = Detector(name="model_pii", detector_type="model", default_rules="pii")
text = "My name is Jhon Smith and my email is jhon.smith@yahoo.com."
result = detector.inspect(key="profile", value=text, operation="write")
redacted = detector.redact(text, entities=result.model_detection_result)
The detector logs a warning when you call redact on a model-only detector without entities.
Messages
The message depends on the detection mode and the rule set in use.
Regex messages:
| Rule set | Message |
|---|---|
pii |
PII pattern detected in '<key>' |
secrets |
Secrets pattern detected in '<key>' |
prompt_injection |
Prompt injection pattern detected in '<key>' |
None (custom rules) |
Security check detected a possible issue in '<key>' |
Model messages:
Model detected a potential <default_rules with underscores replaced by spaces> in '<key>'
For example, with default_rules="prompt_injection":
Model detected a potential prompt injection in '<key>'
Mixed-mode messages:
| Condition | Message |
|---|---|
| Regex hits and model detection | Security issue detected in '<key>' |
| Regex hits only | The regex message for the rule set |
| Model detection only | The model message |
Complete Examples
Regex detector with PII rules:
from qarai_agent_guard import Detector
detector = Detector(name="pii", default_rules="pii")
Model detector with the default HuggingFace prompt-injection model:
detector = Detector(
name="model_prompt_injection",
detector_type="model",
default_rules="prompt_injection",
)
Mixed detector with custom patterns and a HuggingFace model:
from qarai_agent_guard.core.models import resolve_default_model
detector = Detector(
name="mixed_custom",
detector_type="mixed",
patterns=[
{
"id": "magic_token",
"name": "Magic Token",
"severity": "high",
"pattern": r"\bmagic-token-42\b",
},
],
model=resolve_default_model("prompt_injection"),
combination_strategy="any",
)
Model detector with a remote API model (example using OpenRouter):
import os
from qarai_agent_guard.core.models import ModelConfig
config = ModelConfig(
provider="api",
model="gpt-oss-120b",
task="text-generation",
threshold=0.5,
api_key=os.environ["OPENROUTER_API_KEY"],
model_options={
"endpoint": "https://openrouter.ai/api/v1",
"messages": [
{
"role": "system",
"content": "You are a security classifier. Answer with exactly one word: safe or unsafe.",
}
],
},
inference_options={
"temperature": 0.0,
"max_tokens": 256,
},
)
detector = Detector(
name="api_injection",
detector_type="model",
model=config,
)
Detector with a custom YAML pattern file:
from pathlib import Path
detector = Detector(
name="custom",
pattern_paths=[Path("detector_rules.yaml")],
)
Secret detector:
detector = Detector(name="secrets", default_rules="secrets")