Metadata-Version: 2.4
Name: xyran
Version: 1.0.0
Summary: Fast, local-first content safety SDK with bundled Owen-S ONNX inference.
Author: Xyran Contributors
License-Expression: Apache-2.0
Keywords: moderation,nsfw,content-safety,onnx,offline,image-classification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/xyran/third_party/OWEN_MODEL_MIT_LICENSE.txt
Requires-Dist: numpy<3,>=1.26
Requires-Dist: Pillow<13,>=10.4
Requires-Dist: pyvips[binary]<4,>=3.2
Requires-Dist: onnxruntime-gpu[cuda,cudnn]<2,>=1.29; (sys_platform == "win32" and platform_machine == "AMD64") or (sys_platform == "linux" and platform_machine == "x86_64")
Requires-Dist: onnxruntime<2,>=1.29; sys_platform == "darwin" or (sys_platform == "win32" and platform_machine != "AMD64") or (sys_platform == "linux" and platform_machine != "x86_64")
Dynamic: license-file

# 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

```bash
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

```python
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:

```python
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

```text
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:

```python
mod = Moderator(preprocess="warp")
```

Mappings:

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

No tiling is used in V1 inference.

## Model residency

Default:

```python
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:

```python
mod = Moderator(resident=False)
```

The model is loaded for an operation and released afterwards.

Explicit lifecycle:

```python
mod.load()
mod.unload()
mod.close()
```

Context-manager use is supported:

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

## Device selection

```python
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:

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

V1 development defaults:

```text
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:

```python
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

```bash
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:

```text
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:

```text
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.
