modotte-python

A universal Python package for accessing and using all AI models trained by Modotte.

Installation

Install from PyPI

Install the latest stable version directly from PyPI:

pip install modotte

Then import Modotte in your Python project:

from modotte import Audio, Image

Upgrade to the latest version

pip install --upgrade modotte

---

Install from GitHub

You can also install the latest development version directly from GitHub:

pip install git+https://github.com/Modotte/modotte-python.git

Clone the repository

If you want to develop or modify Modotte locally:

git clone https://github.com/Modotte/modotte-python.git
cd modotte-python

---

Project Structure

modotte-python/
├── 📄 .gitignore
├── 📄 CONTRIBUTION.md
├── 📄 LICENSE
├── 📄 README.md
├── 📄 pyproject.toml
└── 📁 src/
    └── 📁 modotte/
        ├── 📄 AIRealNet.py
        ├── 📄 __init__.py
        ├── 📄 _common.py        ← internal (model registry, validation, download)
        ├── 📄 _formats.py       ← internal
        ├── 📄 audio.py          ← public API
        └── 📄 image.py          ← public API

Hugging Face Token (Optional, Recommended)

The models are downloaded from the Hugging Face Hub on first use.

Without a token, you may see:

Warning: You are sending unauthenticated requests to the HF Hub

Unauthenticated requests are subject to lower rate limits. A free Hugging Face token can provide higher rate limits and more reliable downloads.

Create a token from:

https://huggingface.co/settings/tokens

There are three ways to provide it.

1. Pass the token directly

from modotte import Audio, Image

detector = Audio(model_name="Modotte/AIRealNet-Audio", hf_token="hf_xxxxxxxxxxxxxxxx")
detector = Image(model_name="Modotte/AIRealNet-2", hf_token="hf_xxxxxxxxxxxxxxxx")

2. Set the HF_TOKEN environment variable

Windows PowerShell — current session

$env:HF_TOKEN = "hf_xxxxxxxxxxxxxxxx"

Windows — permanent

setx HF_TOKEN "hf_xxxxxxxxxxxxxxxx"

Open a new terminal after running setx.

macOS / Linux

export HF_TOKEN="hf_xxxxxxxxxxxxxxxx"

3. Log in using the Hugging Face CLI

hf auth login

An explicit hf_token= argument takes priority over the HF_TOKEN environment variable.

The token is only used for downloading models. Modotte does not store or print your token.

Models are downloaded once and subsequently loaded from their local folder in ~/Modotte (see below).

---

Supported Models & Local Storage

Only models from the Modotte organization are supported:

Class	model_name
Image	Modotte/AIRealNet
Image	Modotte/AIRealNet-2
Audio	Modotte/AIRealNet-Audio

model_name is required. Anything else (a model from another organization, an unknown Modotte model, or an audio model passed to Image / an image model passed to Audio) raises ValueError; a non-string raises TypeError. Nothing is downloaded or created on disk when a name is rejected.

On first use a Modotte folder is created inside your home directory, and each model is downloaded into its own sub-folder named after the model:

~/Modotte/
├── AIRealNet/
├── AIRealNet-2/
└── AIRealNet-Audio/

If a model's folder already exists, it is loaded from disk and not downloaded again.

Choosing the wrong model

The model_name is validated before anything is downloaded or created:

from modotte.AIRealNet import Image

Image(model_name="openai/clip-vit-base-patch32")
# ValueError: Unsupported model 'openai/clip-vit-base-patch32'. Only models from
# the 'Modotte' organization are supported (format: 'Modotte/<model>'). ...

Image(model_name="Modotte/AIRealNet-Audio")
# ValueError: 'Modotte/AIRealNet-Audio' is an audio model and cannot be loaded
# by Image. Use Audio instead.

Problem	Error
Model from another organization / no Modotte/	ValueError
Unknown Modotte/... model	ValueError
Image model passed to Audio (or vice versa)	ValueError
model_name is not a string	TypeError

Names are matched case-insensitively (modotte/airealnet-2 works) and always stored under the canonical folder name (AIRealNet-2).

Custom location

By default models live in ~/Modotte/<model>. To store a model somewhere else, pass model_dir (the exact folder for that one model):

detector = Image(model_name="Modotte/AIRealNet-2", model_dir="D:/models/AIRealNet-2")

Upgrading from an earlier version

Earlier versions stored models in ~/AIRealNetImage and ~/AIRealNetAudio. Those folders are no longer used and models are not migrated automatically; they are downloaded again into ~/Modotte on first use. You can delete the old folders to free up disk space.

---

Audio Classification

Import the audio detector:

from modotte.AIRealNet import Audio

detector = Audio(
    model_name="Modotte/AIRealNet-Audio",  # Available: Modotte/AIRealNet-Audio
)

On first use, Modotte checks ~/Modotte/AIRealNet-Audio and downloads the model there if necessary.

You can optionally provide a Hugging Face token:

detector = Audio(model_name="Modotte/AIRealNet-Audio", hf_token="hf_xxxxxxxxxxxxxxxx")

Detect Bonafide / Real Audio

result = detector.predict("bonafide.wav", threshold=0.5)

print(result["label"])
print(result["confidence"])

Detect Spoof / AI-Generated Audio

result = detector.predict("spoof.wav", threshold=0.5)

print(result["label"])
print(result["confidence"])

result["label"] is "AI" (spoof / AI-generated) when the AI score is at or above threshold, otherwise "Human" (bonafide). result["confidence"] is the score of the winning label.

The threshold parameter must be a float between 0.0 and 1.0, inclusive.

Invalid types such as integers, strings, or booleans raise TypeError.

Values outside the range 0.0–1.0 raise ValueError.

---

Image Classification

Import the image detector:

from modotte.AIRealNet import Image

detector = Image(
    model_name="Modotte/AIRealNet-2",  # Available: Modotte/AIRealNet, Modotte/AIRealNet-2
)

On first use, Modotte checks ~/Modotte/AIRealNet-2 and downloads the model there if necessary.

You can optionally provide a Hugging Face token:

detector = Image(model_name="Modotte/AIRealNet-2", hf_token="hf_xxxxxxxxxxxxxxxx")

Both image models share the same API, so switching is just a different model_name (each is stored in its own folder, so they can be used side by side):

detector_v1 = Image(model_name="Modotte/AIRealNet")    # ~/Modotte/AIRealNet
detector_v2 = Image(model_name="Modotte/AIRealNet-2")  # ~/Modotte/AIRealNet-2

Run a prediction:

result = detector.predict("cat.jpg")

print(result["label"])
print(result["confidence"])
print(result["scores"])

Example:

{
    "label": "real",
    "confidence": 0.94,
    "scores": {
        "artificial": 0.06,
        "real": 0.94
    }
}

The image models (Modotte/AIRealNet, Modotte/AIRealNet-2) are binary classifiers:

• Class 0: AI-generated
• Class 1: Real human image

Both import styles are supported:

from modotte import Audio, Image

and:

from modotte.AIRealNet import Audio, Image

---

Supported file types

• Audio: MP3, WAV, AAC, FLAC, OGG, Opus, M4A, AIFF
• Image: JPG, JPEG, PNG, WebP, GIF, SVG, BMP, TIFF, AVIF, HEIC, HEIF

Other extensions raise ValueError. WAV/FLAC/OGG/Opus/AIFF/MP3 are decoded with soundfile; AAC and M4A (and any file soundfile can't read) fall back to PyAV, which bundles ffmpeg. HEIC/HEIF/AVIF need pillow-heif, and SVG needs cairosvg (which requires the Cairo library on some systems). GIF and multi-page TIFF use the first frame; transparent images are composited on white.

Models load on CUDA when available, otherwise CPU.

---

Quick Start

After installing Modotte:

pip install modotte

You can immediately use the supported models:

from modotte import Audio, Image

audio_detector = Audio(model_name="Modotte/AIRealNet-Audio")
image_detector = Image(model_name="Modotte/AIRealNet-2")

audio_result = audio_detector.predict("audio.wav")
image_result = image_detector.predict("image.jpg")

print(audio_result)
print(image_result)

---

Development

Clone the repository:

git clone https://github.com/Modotte/modotte-python.git
cd modotte-python

Create a virtual environment:

python -m venv .venv

Activate it and install the package in editable mode:

pip install -e .

After making changes to the source code, the changes will be available immediately in your environment.

See CONTRIBUTION.md for the full contributor guide, including how to add a new model.

---

Authors

• Sujal Rajpoot — GitHub
• Parvesh Rawal — GitHub

---

License

See the LICENSE file for licensing information.