modotte 1.0.0__tar.gz

modotte-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+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.

modotte-1.0.0/PKG-INFO

@@ -0,0 +1,360 @@
+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.

modotte-1.0.0/README.md

@@ -0,0 +1,305 @@
+# 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.