README.md

---
license: mit
library_name: onnx
pipeline_tag: image-classification
base_model: OwenElliott/image-safety-classifier-s
tags:
- xyran
- content-moderation
- content-safety
- image-moderation
- image-safety
- nsfw
- nsfl
- image-classification
- onnx
- onnxruntime
- offline
- local-ai
- privacy
- not-for-all-audiences
---

# Xyran Image Safety

**Pinned ONNX image-safety model used by the Xyran local-first moderation SDK.**

Xyran is a Python content-moderation SDK designed for local inference: no Xyran
API key and no cloud moderation request are required.

- GitHub: https://github.com/mingshenhk/xyran
- PyPI: https://pypi.org/project/xyran/
- This model page: https://huggingface.co/MingSafeR/xyran-image-safety

## Recommended use: Xyran SDK

For most users, the supported integration is the Xyran package rather than
calling the ONNX file directly:

```bash
pip install xyran
xyran scan image.jpg
```

Python:

```python
from xyran import Moderator

mod = Moderator()
result = mod.scan("image.jpg")

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

Xyran also provides frame-aware animated GIF/WebP moderation, true ONNX batching,
one-shot Folder Scan, resumable Dataset Mode, JSON/Markdown/TXT/CSV folder
reports, and JSONL/CSV dataset manifests.

## Model provenance

The current Xyran free SDK uses a pinned ONNX model from:

```text
Upstream repository: OwenElliott/image-safety-classifier-s
Pinned commit: eb8b0b203952b70db191e990217174af4af39767
Upstream file: onnx/image-safety-classifier-s.onnx
Expected size: 23,701,765 bytes
SHA256: fef443ed68ae25ed693b6fef9e456071692ed3963cff4168acb39c3de6f017e7
Upstream license metadata: MIT
```

**The classifier was not authored or trained by the Xyran project.** Xyran pins,
verifies, redistributes, and integrates the model with its local SDK/runtime
layer. The upstream repository remains the authoritative source for the model's
original authorship.

## Task and outputs

The model is an image classifier with three output classes in this order:

```text
NSFL
NSFW
SFW
```

Xyran maps them to:

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

The SDK then applies configurable moderation thresholds and returns:

```text
ALLOW
REVIEW
BLOCK
```

Example result shape:

```json
{
  "scores": {
    "sexual": 0.08,
    "graphic": 0.02,
    "safe": 0.90
  },
  "decision": "ALLOW"
}
```

The numbers above are an example of the output structure, not a benchmark claim.

## Model input

The pinned ONNX graph expects:

```text
[batch, 3, 224, 224] float32
```

The Xyran SDK handles preprocessing and batching. For reproducible Xyran results,
use the SDK rather than reimplementing preprocessing from the model file alone.

Default Xyran preprocessing:

```text
BlurPad + Lanczos3
```

Optional Xyran preprocessing:

```text
Warp + Linear
```

## Dataset Mode in Xyran 1.3

Xyran 1.3 adds a dedicated large-dataset workflow:

```bash
xyran scan-dataset ./dataset --output ./runs/train-clean
```

It can provide:

- resumable SQLite state/cache;
- `stat` or SHA-256 file fingerprints;
- include/exclude patterns;
- extension filtering;
- deterministic sharding;
- offset/limit slicing;
- configurable batch sizes;
- checkpoints;
- retry/fail-fast controls;
- JSONL and CSV manifests.

Example:

```bash
xyran scan-dataset ./dataset \
  --output ./runs/train-clean \
  --batch-size 64 \
  --fingerprint sha256 \
  --manifest-formats jsonl csv
```

## Local runtime

Xyran supports CPU and NVIDIA CUDA ONNX Runtime on supported systems.

A fresh environment can preview the selected runtime with:

```bash
xyran setup-runtime --dry-run
```

Then install it:

```bash
xyran setup-runtime
```

For deterministic environments:

```bash
pip install "xyran[cpu]"
# or
pip install "xyran[gpu]"
```

The model itself is bundled in published Xyran release artifacts, so Xyran does
not need to download this model during inference.

## Intended uses

Potential uses include:

- local image moderation;
- image-upload pre-screening;
- dataset cleaning;
- AI-generated image pipelines;
- desktop or self-hosted applications;
- private/offline moderation workflows;
- community or bot moderation pipelines.

## Out-of-scope / limitations

This model is probabilistic and can make mistakes. It should not be treated as a
perfect determination of whether content is safe, legal, harmful, consensual, or
appropriate in a particular jurisdiction/context.

Performance can vary across:

- photography;
- anime and manga;
- illustrations;
- AI-generated images;
- unusual crops;
- heavily compressed images;
- ambiguous or adversarial content.

Xyran's animated-media smart sampling is also non-exhaustive for long GIF/WebP
files unless `sampling="all"` is explicitly selected.

For high-impact moderation decisions, evaluate on representative data, calibrate
thresholds, and use additional safeguards or human review where appropriate.

## Evaluation

The Xyran project does **not** currently publish invented or unverified accuracy
numbers for this model. A reproducible evaluation/benchmark workflow is planned
for a later Xyran release.

Until then, users should benchmark the model against data representative of
their own application.

## Licenses

### Model

The pinned upstream model repository reports **MIT** license metadata. Preserve
upstream attribution and license terms when redistributing the model.

### Xyran SDK

The Xyran SDK is a separate project licensed under **Apache-2.0**:

https://github.com/mingshenhk/xyran

## Reporting issues

SDK/runtime issues:

https://github.com/mingshenhk/xyran/issues

Please do not post private or sensitive media publicly just to demonstrate a
classification error.