> ## 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.

# Custom Detectors

> Build custom detection methods for Dome Guardrails.

Dome allows you to create custom [Detectors](/concepts/evaluation-components/detector) to implement domain-specific detection logic. This guide covers creating, registering, and using custom Detectors.

## Detection Categories

Register your Detector with one of these categories:

| Category                       | Use Case                        |
| ------------------------------ | ------------------------------- |
| `DetectionCategory.Security`   | Adversarial attacks, injections |
| `DetectionCategory.Moderation` | Harmful content, toxicity       |
| `DetectionCategory.Privacy`    | PII, secrets, sensitive data    |
| `DetectionCategory.Integrity`  | Data quality, format validation |
| `DetectionCategory.Generic`    | Anything else                   |

The category determines which Guard types can use your Detector.

## Detection Result Format

The `detect` method must return a tuple of `(flagged: bool, metadata: dict)`

<Note>
  Always include `query_string` and `response_string` in metadata for proper Guardrail operation.
</Note>

## Using Custom Detectors

* **Define before instantiation**: custom Detectors must be defined before creating the Dome instance.

* **Import from separate file**: for cleaner organization, define Detectors in a separate module.

<Warning>
  Import your custom Detector module before creating the Dome instance. The `@register_method` decorator must run before the config is parsed.
</Warning>

## Example Detectors

* **Rate Limiter**: Track request frequency per user

* **Regex Pattern Detector**: Block content matching patterns

* **External API Detector**: Call an external service for detection

* **Semantic Similarity Detector**: Block content similar to known bad examples

<Card title="Work in Progress" icon="pickaxe" badge="Private preview">
  The programmatic protection capabilities and Dome integrations are currently in private preview and subject to change.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Guardrails" icon="sliders-horizontal" href="/developer-guide/protect/configuring-guardrails">
    Use custom Detectors in configurations
  </Card>

  <Card title="Use Guardrails" icon="train-track" href="/developer-guide/protect/using-guardrails">
    Runtime integration patterns
  </Card>

  <Card title="Observability" icon="eye" href="/developer-guide/protect/observability">
    Monitor custom Detector performance
  </Card>

  <Card title="Protection Overview" icon="book" href="/developer-guide/protect/overview">
    Built-in Detectors reference
  </Card>
</CardGroup>