Metadata-Version: 2.4
Name: modotte
Version: 1.1.0
Summary: A universal Python package for accessing and using all AI models trained by Modotte.
Author: Sujal Rajpoot, Parvesh Rawal
License: MIT License
        
        Copyright (c) 2026 modotte-python
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/Modotte/modotte-python
Project-URL: Issues, https://github.com/Modotte/modotte-python/issues
Keywords: ai,artificial-intelligence,machine-learning,deep-learning,models,modotte,pytorch,transformers
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: soundfile
Requires-Dist: pillow>=10.0
Requires-Dist: pillow-heif
Requires-Dist: cairosvg
Requires-Dist: av
Requires-Dist: torch
Requires-Dist: transformers
Requires-Dist: huggingface_hub
Dynamic: license-file

# 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:

```bash
pip install modotte
```

Then import Modotte in your Python project:

```python
from modotte import Audio, Image
```

### Upgrade to the latest version

```bash
pip install --upgrade modotte
```

---

## Install from GitHub

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

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

### Clone the repository

If you want to develop or modify Modotte locally:

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

---

## Project Structure

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

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

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

```powershell
$env:HF_TOKEN = "hf_xxxxxxxxxxxxxxxx"
```

#### Windows — permanent

```powershell
setx HF_TOKEN "hf_xxxxxxxxxxxxxxxx"
```

Open a new terminal after running `setx`.

#### macOS / Linux

```bash
export HF_TOKEN="hf_xxxxxxxxxxxxxxxx"
```

### 3. Log in using the Hugging Face CLI

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

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

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

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

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

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

### Detect Bonafide / Real Audio

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

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

### Detect Spoof / AI-Generated Audio

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

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

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

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

Run a prediction:

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

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

Example:

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

```python
from modotte import Audio, Image
```

and:

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

```bash
pip install modotte
```

You can immediately use the supported models:

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

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

Create a virtual environment:

```bash
python -m venv .venv
```

Activate it and install the package in editable mode:

```bash
pip install -e .
```

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

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

---
## Authors

- **Sujal Rajpoot** — [GitHub](https://github.com/sujalrajpoot)
- **Parvesh Rawal** — [GitHub](https://github.com/Parveshiiii)
---

## License

See the [LICENSE](LICENSE) file for licensing information.
