Skip to content

Choose categories & levels

Goal: pick the right set of categories and the right max_level for your use case, so you scan what matters without paying for what you don't.

Pick categories by use case

Use case Suggested categories
Prompt firewall (block injections) injection, threat
DLP / leak prevention dlp, pii, sensitive_document
Open-vocabulary PII extraction dynamic-pii (+ pii for validated identifiers)
Agent tool-use guard injection, tool_class, tool_action, tool_tags
Request router routing

Scan only what you will act on — each category adds work. See Categories for what each one classifies and which layers back it.

Pick a level

max_level is the hard ceiling on escalation:

max_level Use when
l1 You want asset-free, always-offline, rule-based coverage only. Runtime still depends on input size and enabled rules.
l2 You want learned classification but never the transformer cost. Great default for high-throughput paths.
l3 You want maximum accuracy and can afford occasional transformer inference on promoted requests. 
scanner = SecurityGateway(
    categories=["injection", "threat"],
    max_level="l2",          # learned classifiers, no L3
    download_files=True,
    download_categories=["injection", "threat"],
)
scanner.warmup()

use patronus_ark::{SecurityCategory, SecurityGateway, SecurityLevel};

let mut scanner = SecurityGateway::with_download_categories(
    vec![SecurityCategory::Injection, SecurityCategory::Threat],
    SecurityLevel::L2,       // learned classifiers, no L3
    None,
    true,                    // download_files
    Some(vec![SecurityCategory::Injection, SecurityCategory::Threat]),
);
scanner.warmup().expect("warmup");

Consider the offline implications

  • pii, dlp → native L1, no assets ever.
  • injection, threat → native L1 works without assets; L2/L3 need assets.
  • sensitive_document, tool_*, routing → model-only; with no cached assets they produce no verdict.
  • dynamic-pii → L3-only; needs its GLiNER bundle or it cannot run.

If you need guaranteed coverage in an air-gapped environment, prefer categories with a native L1 stage or pre-cache assets (see Offline & air-gapped).

Download only what you use

Enable downloads for just the categories you configured with download_categories:

scanner = SecurityGateway(
    categories=["injection", "dlp", "pii"],
    max_level="l2",
    download_files=True,
    download_categories=["injection"],   # dlp/pii are native; only injection downloads
)

Turn levels or detectors off per request

Use execution gates to disable a level or a specific detector below the ceiling, without rebuilding the gateway:

scanner.set_execution_gates({"levels": {"l1": True, "l2": True, "l3": False}})
# ... later ...
scanner.set_execution_gates(None)   # reset to all enabled

use patronus_ark::ScanGateMatrix;

scanner.set_execution_gates(ScanGateMatrix::levels(true, true, false));
// ... later ...
scanner.set_execution_gates(ScanGateMatrix::all_enabled());   // reset

Running classifiers with L3 only

With L2 disabled and L3 enabled, requested classifier categories are sent directly to L3; L2 promotion is not required. The canonical tokenizer splits the full input into 256-token model inputs (254 content tokens plus two special tokens). Model and L3 conditional gates still apply. L3 assets and the configured local or remote inference service must be ready. Native-only categories do not acquire an L3 model. Without L2 fallback results, a positive classifier may stop its own head early, but does not skip the other requested classifier heads. Dedicated L3 startup still requires its NTDB package metadata for label mappings; disabling L2 skips its inference, not that existing asset prerequisite. Unified L3-only startup does not require NTDB L2 packages.