Xyran V1

Fast, local-first content safety for Python.

Xyran is an offline image moderation SDK with bundled Owen-S ONNX inference. After installation, inference requires no API key, cloud moderation service, telemetry, Hugging Face login, or model download.

V1 uses the MIT-licensed OwenElliott/image-safety-classifier-s ONNX model and ships the pinned ONNX file inside the Python wheel.

Install

pip install xyran

On Windows x64 and Linux x86_64, the package intentionally installs onnxruntime-gpu[cuda,cudnn] so NVIDIA CUDA can work out of the box while the same runtime can fall back to CPU. On macOS and non-x64 Windows/Linux targets, the CPU ONNX Runtime package is selected.

ONNX Runtime's CPU and GPU Python distributions share the same import namespace. Use a clean virtual environment for the most predictable install.

30-second usage

from xyran import Moderator

mod = Moderator()  # model/session resident by default
result = mod.scan("image.jpg")

print(result.decision)      # ALLOW / REVIEW / BLOCK
print(result.scores.sexual)
print(result.scores.graphic)
print(result.scores.safe)
print(result.provider)

Reuse one Moderator instance for repeated scans:

from xyran import Moderator

mod = Moderator()

for path in ["1.jpg", "2.jpg", "3.jpg"]:
    result = mod.scan(path)
    print(path, result.decision, result.scores)

mod.close()

V1 defaults

preprocess     BlurPad + Lanczos3
input          224 x 224 (generated internally)
tiling         disabled
resident       true
device         auto
runtime        ONNX Runtime
network        not required after pip install
telemetry      disabled
cloud API      none

The default BlurPad + Lanczos3 preprocessing preserves the source aspect ratio, places the fitted sharp image over a blurred full-canvas background, and sends a single 224x224 image to Owen-S. It was selected from Xyran's internal preprocessing experiments; this is not a claim that it is universally optimal for every dataset.

Optional Warp Linear path

The final benchmark kept a second preprocessing path because its error pattern was complementary on some hard cases:

mod = Moderator(preprocess="warp")

Mappings:

blurpad -> BlurPad + Lanczos3  (default)
warp    -> pyvips Warp + Linear

No tiling is used in V1 inference.

Model residency

Default:

mod = Moderator(resident=True)

The ONNX session is created once and remains resident until close()/unload(). This is recommended for servers, desktop apps and repeated scanning.

Memory-sensitive mode:

mod = Moderator(resident=False)

The model is loaded for an operation and released afterwards.

Explicit lifecycle:

mod.load()
mod.unload()
mod.close()

Context-manager use is supported:

with Moderator() as mod:
    result = mod.scan("image.jpg")

Device selection

Moderator(device="auto")  # default: CUDA when it really works, otherwise CPU
Moderator(device="cpu")   # strict CPU
Moderator(device="cuda")  # strict CUDA; raises if CUDA is unusable

device="auto" is resilient: session creation and runtime inference can fall back to CPU if CUDA is visible but unusable.

Inputs

scan() accepts:

• local file paths (str / pathlib.Path)
• encoded image bytes (bytes / bytearray)
• PIL.Image.Image

EXIF orientation is applied. The default image backend is libvips/pyvips.

Policy

The classifier produces:

NSFL -> graphic
NSFW -> sexual
SFW  -> safe

V1 development defaults:

sexual REVIEW >= 0.35
sexual BLOCK  >= 0.85
graphic REVIEW >= 0.35
graphic BLOCK  >= 0.85

These thresholds are not universal safety policy. Real moderation policy is application-specific. The model author also notes that NSFW judgments are subjective/contextual and that the NSFL class is underrepresented in training.

Customize policy:

from xyran import Moderator, ModerationPolicy

policy = ModerationPolicy(
    sexual_review=0.40,
    sexual_block=0.90,
    graphic_review=0.35,
    graphic_block=0.85,
)

mod = Moderator(policy=policy)

CLI

xyran doctor
xyran scan image.jpg
xyran scan image.jpg --json
xyran scan image.jpg --preprocess warp
xyran scan image.jpg --device cpu
xyran scan image.jpg --no-resident

Bundled model

Xyran V1 pins:

Repository: OwenElliott/image-safety-classifier-s
Source commit: eb8b0b203952b70db191e990217174af4af39767
File: onnx/image-safety-classifier-s.onnx
Size: 23,701,765 bytes
SHA256: fef443ed68ae25ed693b6fef9e456071692ed3963cff4168acb39c3de6f017e7
License metadata: MIT

See THIRD_PARTY_NOTICES.md and package xyran/third_party/.

Offline guarantee

After pip install xyran finishes successfully:

model download during inference: NO
API key:                         NO
cloud moderation API:           NO
telemetry:                       NO
network required for inference: NO

Notes

This SDK helps classify image-safety risk. It is not a guarantee that every unsafe image will be detected, nor that every flagged image is unsafe. For high-stakes moderation, use human review and dataset-specific evaluation.