Metadata-Version: 2.4
Name: modotte
Version: 1.0.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
├── 📄 LICENSE
├── 📄 README.md
├── 📄 pyproject.toml
└── 📁 src/
    └── 📁 modotte/
        ├── 📄 AIRealNet.py
        ├── 📄 __init__.py
        ├── 📄 _common.py        ← internal
        ├── 📄 _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(hf_token="hf_xxxxxxxxxxxxxxxx")
detector = Image(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 the local cache.

---

## Audio Classification

Import the audio detector:

```python
from modotte import Audio

detector = Audio()
```

On first use, Modotte checks for the model locally and downloads it if necessary.

You can optionally provide a Hugging Face token:

```python
detector = 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"])
```

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 import Image

detector = Image()
```

On first use, Modotte checks for the model locally and downloads it if necessary.

You can optionally provide a Hugging Face token:

```python
detector = Image(hf_token="hf_xxxxxxxxxxxxxxxx")
```

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

`Modotte/AIRealNet` is a binary SwinV2 Tiny classifier:

* 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()
image_detector = Image()

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.

---
## Authors

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

## License

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