stealthbox-onnx-models

Stealthbox ONNX Models

Binary image-classification models exported to ONNX for use with the Stealthbox detector service (or any ONNX Runtime–compatible stack).
Each model estimates the probability that a target concept is present in an image (the positive class). A configurable threshold converts that probability into a pass/fail verdict.

---

Repository contents (artifacts at repo root)

stealthbox-onnx-models/
├── drugs.onnx
├── gore.onnx
├── hate_symbols.onnx
├── licit_substances.onnx
├── nudity.onnx
├── violence.onnx
└── weapons.onnx

Raw download URL pattern (repo root):

[https://huggingface.co/Stealthbox/stealthbox-onnx-models/resolve/main/](https://huggingface.co/Stealthbox/stealthbox-onnx-models/resolve/main/)<slug>.onnx

Slug definition (explicit, no ambiguity):

• The slug is exactly the filename without the .onnx extension.
  • Examples: drugs.onnx → slug drugs; hate_symbols.onnx → slug hate_symbols.
• Use lowercase letters, digits, and underscores.
• When a detector endpoint asks for a “slug”, provide only this base name (do not include .onnx and do not include folder paths).

---

Input contract (what the models expect)

• Image: JPEG or PNG bytes.
• Preprocessing (required):
  • Convert to RGB.
  • Resize to the model’s input size. If the ONNX input shape is dynamic/unspecified, use 224 × 224.
  • Normalize to float32 in [0, 1].
  • Layout: (1, 3, H, W) (batch size 1, channels-first).
• Input tensor name: read from the ONNX model at runtime (do not hard-code).

If either H or W is dynamic in the ONNX metadata, default to H = W = 224.

---

Output contract (what to read back)

• Use the model’s first output.
• If the output has shape (1, 1) → that single value is the positive probability.
• If the output has shape (1, N ≥ 2) → use index 1 as the positive probability
  (convention: class 0 = negative, class 1 = positive).
• Verdict rule (thresholded):
  • fail if probability ≥ threshold (model predicts positive).
  • pass if probability < threshold (model predicts negative).

Default threshold: 0.5 (can be set as a global default or overridden per request via a threshold parameter).

---

How detector services should use these models (high level, language-agnostic)

Stealthbox’s detector stores models on disk at /app/models/<slug>.onnx and exposes endpoints to manage and use them.

1. Make a model available locally (download by slug)

   • Choose a slug that matches the filename’s base name (see table below).
   • Use the model’s raw URL from this repository (pattern above).
   • Call the detector’s download endpoint with the slug and the raw URL.
   • The file is saved to /app/models/<slug>.onnx; any cached session for that slug is cleared.

2. List available models

   • Call the list endpoint; it returns the slugs of all *.onnx present under /app/models.

3. Run inference

   • Provide the slug and a JPEG/PNG image (multipart upload).
   • Optionally pass a threshold in [0,1]; if omitted, the detector uses its global default (typically 0.5).
   • The detector:
     • Loads or reuses the session for /app/models/<slug>.onnx.
     • Reads the model’s input shape; if dynamic, uses 224 × 224.
     • Preprocesses (RGB → resize → normalize [0,1] → CHW float32 → shape (1,3,H,W)).
     • Runs inference; extracts the positive probability (single value, or index 1 when there are ≥ 2 outputs).
     • Compares to the threshold; returns:

       { "slug": "<slug>", "verdict": "pass" | "fail", "confidence": <0..1> }
       

   • Fail-safe: if inference errors internally, the detector replies with "pass" and confidence: 0.

4. Health & deletion

   • Health: returns service status and available_models.
   • Delete: removes /app/models/<slug>.onnx and clears its cache.

---

Current training status & roadmap

• Each category is currently trained on ~1,000 images.
• The training pipeline is solid and fully containerized; Stealthbox will improve model quality by adding more labeled images, balancing classes, and diversifying negatives.
• Expect some false positives/negatives at this stage. Stealthbox recommends per-category threshold tuning for deployment contexts:
  • Too many false positives → increase threshold (e.g., 0.6–0.8).
  • Missed positives → decrease threshold (e.g., 0.3–0.4).

---

Updating a model artifact

• Upload a new .onnx here with the same filename as the existing one.
• In deployments, instruct the detector to re-download that slug from the raw URL (same pattern).
• The local file is overwritten and the next inference uses the updated session.

---

Slug ↔ file mapping (this repository)

Slug usage reminder: when a detector endpoint asks for a slug, provide the base name (e.g., hate_symbols), not the filename with .onnx and not a path.