Skip to Content
ZeroLeaksDocs
Shield SDK

Local models

Install the model runtime, load local artifacts, and use them in detection and provider wrappers.

@zeroleaks/shield/model runs a transformer classifier inside your process. The root hosted detect export does not load this module. Use the Shield API when you want the hosted release, or configure local artifacts when you own the deployment.

Shield Small S15e is available as int8 ONNX weights under CC BY-NC 4.0 for noncommercial use. The repository includes a standalone Python example. Commercial use of the weights requires a separate license; the SDK code's MIT license does not cover the weights.

The current hosted shield-large is an ensemble of the larger classifier and Base. The local SHIELD_MODEL_LARGE convenience constant identifies a single-model repository; it does not by itself reproduce that ensemble. Public artifact publication and the hosted API are separate releases.

Install the dependencies

The model entry point uses @huggingface/transformers version 3, an optional peer dependency that brings ONNX Runtime and Sharp. Version 4 is not supported. Use a current security-patched Node.js 22 release (22.23.3 or later) or Bun 1.4.2 or later for the configuration below.

Merge this override into your application's root package.json before installing:

{
  "overrides": {
    "sharp": "0.35.4"
  }
}

Then install the SDK and Transformers 3.8.1:

bun add --exact @zeroleaks/shield @huggingface/transformers@3.8.1

Commit the updated lockfile. Transformers 3.8.1 requests Sharp 0.34.x, so its normal version range cannot select the fixes in Sharp 0.35.4 for the libvips and libheif advisories. If your application also declares Sharp directly, align that dependency with the override. The override belongs to the consuming application; installing Shield alone does not apply it.

Sharp 0.35.4 requires a Node-API v9 compatible runtime, such as Node.js 20.9.0 or later. Shield's hosted client and local rules do not install or load these optional native dependencies.

Load local files

Supply the model, tokenizer, and configuration files that belong together:

shield-small/
  config.json
  tokenizer.json
  tokenizer_config.json
  onnx/model_quantized.onnx
import { detectAsync } from "@zeroleaks/shield/local";
import { createModelDetector } from "@zeroleaks/shield/model";

const model = createModelDetector({
  localPath: "/srv/models/shield-small",
  allowDownload: false,
  dtype: "q8",
  maxTokens: 256,
  windows: { stride: 192, max: 32 },
});
await model.load();

const result = await detectAsync(text, model.options());

Create one detector and reuse it. Each instance loads its own model. model.options() keeps the local rule layer and uses the model instead of the built-in classifier for text the rules did not flag. Supply the release's rule configuration explicitly when reproducing its results.

The convenience defaults select an earlier small-model profile. Set the model ID, tokenizer, dtype, window settings, and rules to match the artifacts you are serving. A matching architecture or repository name is not enough to reproduce a particular release.

Use a model in provider wrappers

Pass model.options() as the detection options:

import OpenAI from "openai";
import { shieldOpenAI } from "@zeroleaks/shield/openai";

const client = shieldOpenAI(new OpenAI(), {
  detect: model.options(),
  scanToolResults: model.options(),
});

The same options work with shieldLanguageModelMiddleware, which awaits model checks. The lower-level shieldMiddleware requires await wrapParamsAsync(...) for model-backed options. A model failure rejects the check; keep that error distinct from a clean verdict.

Combine models

tiered(small, large, options?) runs the first detector and calls the second when the first score is at least from (default 0.01) and below to (default 0.97). Its default decision threshold is 0.5.

import { createModelDetector, tiered } from "@zeroleaks/shield/model";

const staged = tiered(
  createModelDetector({ localPath: "/srv/models/first", allowDownload: false }),
  createModelDetector({
    model: "your-org/second-classifier",
    localPath: "/srv/models/second",
    allowDownload: false,
    maxTokens: 512,
    windows: { stride: 384, max: 16 },
  })
);
await staged.load();

This is a custom local configuration, not a claim of parity with hosted shield-tiered. The hosted release also specifies exact weights, ensemble components, and rules.

Options

OptionDescription
modelModel identifier reported in matches and used to select a profile. Default: zeroleaks/shield-small.
revisionExplicit repository revision when downloads are enabled. Pin a commit to reproduce a release.
localPathDirectory containing model and tokenizer files. Uses local files instead of downloading.
allowDownloadDefaults to true; use false to require local or already cached files.
cacheDirWritable cache directory when downloads are enabled.
labelInjection label in the model's id2label; defaults to INJECTION.
thresholdDecision threshold; defaults to 0.5.
dtypeONNX format, such as fp32, q8, or q4; must match the available file.
maxTokensTokens per window, including special tokens.
windows{ stride, max } for overlapping windows, or false for only the first window.
htmlDefaults to true; extracts agent-visible HTML text before scoring.
threadsONNX Runtime inference threads. Tune on the serving hardware.

Window defaults depend on the model profile. Long inputs can exceed the window budget; head and tail sampling does not cover every token in an arbitrarily long document. The hosted response exposes coverage explicitly.

Detector methods

MethodMeaning
score(text)Model score from 0 to 1 without applying the decision threshold.
load()Load at startup rather than on the first request.
options(extra?)Detection options that replace the built-in classifier with this model.
escalate(minScore?)Check text whose built-in classifier score reaches minScore.

As a callable detector, it returns a DetectResult when the score reaches its threshold, or null otherwise. A detection includes category model, the configured model name, and its score. A result from local detectAsync also incorporates local rules.

Errors

CodeCause
MODEL_DEPENDENCY_MISSINGThe optional runtime is absent. Loading rejects.
MODEL_LABEL_MISSINGThe configured injection label is absent.

Missing files, invalid artifacts, and inference errors also reject the call.

Measure latency and accuracy with the exact artifacts, rule revision, tokenizer, and window configuration you deploy.

On this page