Custom Detectors

You can write custom Detectors that run your own detection logic inside a Guard. A custom Detector is a Python class that subclasses DetectionMethod and registers itself under a category and a name. Once registered, you refer to it in a configuration exactly like a built-in Detector.

Detection Categories

Category	Use Case
`DetectionCategory.Security`	Adversarial attacks, prompt injection, jailbreaks
`DetectionCategory.Moderation`	Harmful content and toxicity
`DetectionCategory.Privacy`	PII, secrets, and sensitive data
`DetectionCategory.Integrity`	Hallucination and factual consistency
`DetectionCategory.Generic`	Anything else
`DetectionCategory.Policy`	Content checks against written policy

The category determines which Guard types can use your Detector, and which Guardrail it can therefore run in. A Guard with type = "security" can only reference Detectors registered under DetectionCategory.Security.

Write a Detector

Subclass DetectionMethod

Accept your configuration options as constructor arguments. Dome passes any keys you set in the Detector’s configuration table to this constructor.

Implement Detect

The detect method is asynchronous and receives a DomePayload. Coerce the payload, then read query_string for the text to inspect.

Return a Detection Result

A DetectionResult is a tuple of (hit, metadata), where hit is True or False and metadata is a dictionary. Return True for content the Guard must flag.

from typing import Dict
from vijil_dome.detectors import (
    DetectionCategory,
    DetectionMethod,
    DetectionResult,
    register_method,
)
from vijil_dome.types import DomePayload

CUSTOM_LENGTH_DETECTOR = "custom-length-detector"


@register_method(DetectionCategory.Security, CUSTOM_LENGTH_DETECTOR)
class CustomLengthDetector(DetectionMethod):
    def __init__(self, min_length: int = 10, max_length: int = 1000):
        super().__init__()
        self.min_length = min_length
        self.max_length = max_length
        self.blocked_response_string = (
            f"Method:{CUSTOM_LENGTH_DETECTOR}. "
            "The request was outside the accepted length range."
        )

    async def detect(self, dome_input: DomePayload) -> DetectionResult:
        dome_input = DomePayload.coerce(dome_input)
        query_string = dome_input.query_string

        length = len(query_string)
        hit = length < self.min_length or length > self.max_length

        return hit, {
            "type": str(type(self)),
            "length": length,
            "query_string": query_string,
            "response_string": self.blocked_response_string
            if hit
            else query_string,
        }

Metadata Fields

The metadata dictionary can carry any values you want to record in the trace. Dome reads three of them:

Field	Purpose
`query_string`	Original content passed to the Detector, recorded in the trace
`response_string`	Content the Guard returns when this Detector decides the outcome, either a blocked message or the original or sanitized text
`score`	Optional float that feeds `ScanResult.detection_score`

DomePayload.coerce() accepts a plain string as well as a payload object, so your Detector keeps working when a caller passes raw text.

Use a Custom Detector

Reference the registered name in the methods list of a Guard whose type matches the category you registered, exactly as you would a built-in Detector. Constructor arguments go in a table named after the Detector:

from vijil_dome import Dome

config = {
    "input-guards": ["length-check"],
    "length-check": {
        "type": "security",
        "methods": [CUSTOM_LENGTH_DETECTOR],
        CUSTOM_LENGTH_DETECTOR: {
            "min_length": 5,
            "max_length": 4000,
        },
    },
}

dome = Dome(config)

Import the module that defines your Detector before you create the Dome instance. The @register_method decorator must run before Dome parses the configuration, otherwise Dome raises a ValueError for an unknown detection method.

Control Concurrency

Dome caps the number of concurrent calls a Detector makes during batch scanning. Set max_batch_concurrency in the Detector configuration when your Detector calls an external service with its own rate limits:

[length-check.custom-length-detector]
max_batch_concurrency = 2

Handle Errors

When detect raises an exception, Dome records the Detector in ScanResult.errored_methods and logs a warning rather than propagating the exception. The Guard’s on-error policy then decides the outcome: fail_closed treats the error as a block, and fail_open allows the content through. Raise exceptions freely and set on-error to match the risk you accept.

Work in Progress

The programmatic protection capabilities and Dome integrations are currently in private preview and subject to change.

Next Steps

Configure Guardrails

Use custom Detectors in configurations

Use Guardrails

Runtime integration patterns

Observability

Monitor custom Detector performance

Detection Methods

Built-in Detector reference

Get Started

Evaluate Agents

Protect Agents

Reference

Custom Detectors

Detection Categories

Write a Detector

Metadata Fields

Use a Custom Detector

Control Concurrency

Handle Errors

Work in Progress

Next Steps

Configure Guardrails

Use Guardrails

Observability

Detection Methods

​Detection Categories

​Write a Detector

​Metadata Fields

​Use a Custom Detector

​Control Concurrency

​Handle Errors

Work in Progress

​Next Steps

Configure Guardrails

Use Guardrails

Observability

Detection Methods

Detection Categories

Write a Detector

Metadata Fields

Use a Custom Detector

Control Concurrency

Handle Errors

Next Steps