modotte 1.0.0__py3-none-any.whl

modotte/AIRealNet.py

@@ -0,0 +1,6 @@
+"""Entry point: ``from modotte.AIRealNet import Audio, Image``."""
+
+from .audio import Audio
+from .image import Image
+
+__all__ = ["Audio", "Image"]

modotte/__init__.py

@@ -0,0 +1,4 @@
+from .AIRealNet import Audio, Image
+
+__all__ = ["Audio", "Image"]
+__version__ = "1.0.0"

modotte/_common.py

@@ -0,0 +1,108 @@
+"""Shared helpers: model directory lookup, download and pipeline loading."""
+
+from __future__ import annotations
+
+import os
+import threading
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple, cast
+
+import torch
+
+_lock = threading.Lock()
+_cache: Dict[Tuple[str, str], Tuple[Any, str]] = {}
+
+
+def home_dir() -> Path:
+    try:
+        return Path.home()
+    except (RuntimeError, KeyError):
+        return Path(os.path.expanduser("~"))
+
+
+def model_exists(path: Path) -> bool:
+    return path.is_dir() and (path / "config.json").is_file()
+
+
+def detect_device() -> str:
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def resolve_hf_token(hf_token: Optional[str] = None) -> Optional[str]:
+    """Return the Hugging Face token to use, or ``None`` if there isn't one.
+
+    Order of precedence:
+      1. the ``hf_token`` argument passed by the caller,
+      2. the ``HF_TOKEN`` (or legacy ``HUGGING_FACE_HUB_TOKEN``) environment
+         variable, or a token saved with ``hf auth login``
+         (both handled by ``huggingface_hub.get_token``).
+    """
+    if hf_token is not None:
+        if not isinstance(hf_token, str):
+            raise TypeError(
+                f"hf_token must be a string, got {type(hf_token).__name__}."
+            )
+        hf_token = hf_token.strip()
+        if hf_token:
+            return hf_token
+
+    from huggingface_hub import get_token
+
+    return get_token() or None
+
+
+def download_model(
+    repo_id: str, model_dir: Path, hf_token: Optional[str] = None
+) -> None:
+    from huggingface_hub import snapshot_download
+
+    token = resolve_hf_token(hf_token)
+    if token is None:
+        print(
+            "[modotte] Tip: no Hugging Face token found. Set the HF_TOKEN "
+            "environment variable or pass hf_token=\"hf_...\" for higher rate "
+            "limits and faster downloads "
+            "(create one at https://huggingface.co/settings/tokens)."
+        )
+
+    model_dir.mkdir(parents=True, exist_ok=True)
+    print(f"[modotte] Model not found. Downloading {repo_id} to {model_dir} ...")
+    snapshot_download(repo_id=repo_id, local_dir=str(model_dir), token=token)
+
+
+def load_pipeline(
+    task: str,
+    repo_id: str,
+    model_dir: Path,
+    hf_token: Optional[str] = None,
+    **pipeline_kwargs,
+):
+    """Return (pipeline, device); download the model first if it is missing.
+
+    ``hf_token`` is only used for the download (the model is loaded from the
+    local ``model_dir``). Pipelines are cached per (task, model_dir), so the
+    check/download/load only happens the first time a class is initialized.
+    """
+    key = (task, str(model_dir))
+    with _lock:
+        if key in _cache:
+            return _cache[key]
+
+        if not model_exists(model_dir):
+            download_model(repo_id, model_dir, hf_token)
+            if not model_exists(model_dir):
+                raise RuntimeError(
+                    f"Download finished but no model was found in {model_dir}."
+                )
+
+        from transformers import pipeline
+
+        device = detect_device()
+        print(f"[modotte] Using device: {device}")
+        # `pipeline` is typed with one overload per literal task name, so a
+        # runtime `task` string can't match; cast to Any for the type checker.
+        pipe = cast(Any, pipeline)(
+            task, model=str(model_dir), device=device, **pipeline_kwargs
+        )
+        _cache[key] = (pipe, device)
+        return _cache[key]

modotte/_formats.py

@@ -0,0 +1,180 @@
+"""File-format support: extension checks and audio/image decoding.
+
+Audio: MP3, WAV, AAC, FLAC, OGG, Opus, M4A, AIFF
+Image: JPG, JPEG, PNG, WebP, GIF, SVG, BMP, TIFF, AVIF, HEIC, HEIF
+
+Heavy optional decoders (soundfile, PyAV, cairosvg, pillow-heif) are imported
+lazily so that only the formats you actually use need them.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+from typing import Tuple, Union
+
+import numpy as np
+
+PathLike = Union[str, os.PathLike]
+
+AUDIO_EXTENSIONS: Tuple[str, ...] = (
+    ".mp3", ".wav", ".aac", ".flac", ".ogg", ".opus", ".m4a", ".aiff", ".aif",
+)
+IMAGE_EXTENSIONS: Tuple[str, ...] = (
+    ".jpg", ".jpeg", ".png", ".webp", ".gif", ".svg", ".bmp",
+    ".tif", ".tiff", ".avif", ".heic", ".heif",
+)
+
+AUDIO_FORMATS = "MP3, WAV, AAC, FLAC, OGG, Opus, M4A, AIFF"
+IMAGE_FORMATS = "JPG, JPEG, PNG, WebP, GIF, SVG, BMP, TIFF, AVIF, HEIC, HEIF"
+
+SVG_RENDER_WIDTH = 512
+
+
+def check_extension(path: PathLike, allowed: Tuple[str, ...], kind: str, formats: str) -> str:
+    ext = Path(path).suffix.lower()
+    if ext not in allowed:
+        raise ValueError(
+            f"Unsupported {kind} format '{ext or '(no extension)'}'. "
+            f"Supported formats: {formats}."
+        )
+    return ext
+
+
+# ----------------------------------------------------------------------
+# Audio
+# ----------------------------------------------------------------------
+def _decode_with_av(path: PathLike, target_sr: int) -> np.ndarray:
+    """Decode any ffmpeg-supported audio (AAC, M4A, ...) to mono float32."""
+    import av
+
+    container = av.open(str(path))
+    try:
+        stream = next((s for s in container.streams if s.type == "audio"), None)
+        if stream is None:
+            raise ValueError("No audio stream found in file.")
+
+        resampler = av.AudioResampler(format="flt", layout="mono", rate=target_sr)
+        parts = []
+
+        def collect(frames):
+            if frames is None:
+                return
+            if not isinstance(frames, (list, tuple)):
+                frames = [frames]
+            for f in frames:
+                parts.append(f.to_ndarray().reshape(-1))
+
+        for frame in container.decode(stream):
+            collect(resampler.resample(frame)) # type: ignore
+        collect(resampler.resample(None))  # flush
+    finally:
+        container.close()
+
+    if not parts:
+        return np.zeros(0, dtype=np.float32)
+    return np.concatenate(parts).astype(np.float32)
+
+
+def read_audio(path: PathLike, target_sr: int) -> np.ndarray:
+    """Read an audio file as mono float32 at ``target_sr``."""
+    check_extension(path, AUDIO_EXTENSIONS, "audio", AUDIO_FORMATS)
+
+    sf_error = None
+    try:
+        import soundfile as sf
+        from scipy.signal import resample_poly
+
+        audio, sr = sf.read(str(path), always_2d=False)
+        audio = np.asarray(audio, dtype=np.float32)
+        if audio.ndim == 2:
+            audio = audio.mean(axis=1)
+        if sr != target_sr:
+            audio = resample_poly(audio, target_sr, sr).astype(np.float32)
+        return audio
+    except Exception as exc:  # AAC/M4A (and some MP3 builds) land here
+        sf_error = exc
+
+    try:
+        return _decode_with_av(path, target_sr)
+    except ImportError as exc:
+        raise RuntimeError(
+            f"Could not decode '{Path(path).name}' with soundfile ({sf_error}) and "
+            f"PyAV is not installed. Install it with: pip install av"
+        ) from exc
+    except Exception as exc:
+        raise RuntimeError(
+            f"Could not decode '{Path(path).name}': soundfile error: {sf_error}; "
+            f"PyAV error: {exc}"
+        ) from exc
+
+
+# ----------------------------------------------------------------------
+# Images
+# ----------------------------------------------------------------------
+_plugins_registered = False
+
+
+def _register_image_plugins() -> None:
+    """Enable HEIC/HEIF/AVIF in Pillow when the plugins are installed."""
+    global _plugins_registered
+    if _plugins_registered:
+        return
+    _plugins_registered = True
+    try:
+        from pillow_heif import register_heif_opener
+
+        register_heif_opener()
+    except ImportError:
+        pass
+
+
+def flatten_to_rgb(img):
+    """Convert to RGB, compositing transparency onto white."""
+    from PIL import Image as PILImage
+
+    has_alpha = img.mode in ("RGBA", "LA", "PA") or (
+        img.mode == "P" and "transparency" in img.info
+    )
+    if has_alpha:
+        rgba = img.convert("RGBA")
+        background = PILImage.new("RGB", rgba.size, (255, 255, 255))
+        background.paste(rgba, mask=rgba.getchannel("A"))
+        return background
+    return img.convert("RGB")
+
+
+def read_image(path: PathLike):
+    """Open an image file of any supported format as an RGB PIL image."""
+    from PIL import Image as PILImage
+    from PIL import ImageOps
+
+    ext = check_extension(path, IMAGE_EXTENSIONS, "image", IMAGE_FORMATS)
+
+    if ext == ".svg":
+        try:
+            import cairosvg
+        except ImportError as exc:
+            raise RuntimeError(
+                "SVG support requires cairosvg. Install it with: pip install cairosvg"
+            ) from exc
+        png = cairosvg.svg2png(
+            url=str(path), output_width=SVG_RENDER_WIDTH, background_color="white"
+        )
+        with PILImage.open(io.BytesIO(png)) as img: # type: ignore
+            return flatten_to_rgb(img)
+
+    _register_image_plugins()
+    try:
+        with PILImage.open(path) as img:
+            img.seek(0)  # first frame of GIF / multi-page TIFF
+            img = ImageOps.exif_transpose(img)  # honour camera orientation
+            return flatten_to_rgb(img)
+    except PILImage.UnidentifiedImageError as exc:
+        hint = ""
+        if ext in (".heic", ".heif"):
+            hint = " Install HEIC/HEIF support with: pip install pillow-heif"
+        elif ext == ".avif":
+            hint = " Install AVIF support with: pip install pillow-heif (or Pillow >= 11.3)"
+        raise RuntimeError(f"Could not read image '{Path(path).name}'.{hint}") from exc

modotte/audio.py

@@ -0,0 +1,182 @@
+"""Audio classification: AI-generated vs. human voice."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import numpy as np
+
+from ._common import home_dir, load_pipeline
+from ._formats import AUDIO_EXTENSIONS, AUDIO_FORMATS, read_audio
+
+MODEL_ID = "Modotte/AIRealNet-Audio"
+MODEL_DIR_NAME = "AIRealNetAudio"
+SAMPLE_RATE = 16_000
+CHUNK_SECONDS = 12
+CHUNK_SAMPLES = SAMPLE_RATE * CHUNK_SECONDS
+DEFAULT_THRESHOLD = 0.50
+
+__all__ = ["Audio"]
+
+
+def _validate_threshold(threshold: Any) -> float:
+    """Threshold must be a float in the range 0.0 to 1.0 (inclusive)."""
+    if isinstance(threshold, bool) or not isinstance(threshold, (float, np.floating)):
+        raise TypeError(
+            f"threshold must be a float between 0.0 and 1.0, "
+            f"got {type(threshold).__name__}."
+        )
+    value = float(threshold)
+    if not (0.0 <= value <= 1.0):  # also rejects NaN
+        raise ValueError(f"threshold must be between 0.0 and 1.0, got {value}.")
+    return value
+
+
+class Audio:
+    """Audio classifier that scores speech as AI-generated or human.
+
+    On first initialization ``~/AIRealNetAudio`` is checked; if the model is
+    missing it is downloaded there. Runs on CUDA if available, else CPU.
+
+    ``hf_token`` (optional) is a Hugging Face access token used for the model
+    download, giving higher rate limits and faster downloads. If omitted, the
+    ``HF_TOKEN`` environment variable (or a token saved via ``hf auth login``)
+    is used when available.
+    """
+
+    SUPPORTED_FORMATS = AUDIO_FORMATS
+    SUPPORTED_EXTENSIONS = AUDIO_EXTENSIONS
+
+    def __init__(
+        self,
+        model_dir: Optional[Union[str, os.PathLike]] = None,
+        hf_token: Optional[str] = None,
+    ):
+        self.model_dir = Path(model_dir) if model_dir else home_dir() / MODEL_DIR_NAME
+        self._pipeline, self.device = load_pipeline(
+            "audio-classification",
+            MODEL_ID,
+            self.model_dir,
+            hf_token=hf_token,
+            trust_remote_code=True,
+        )
+
+    @staticmethod
+    def load_audio(path: Union[str, os.PathLike]) -> np.ndarray:
+        audio = read_audio(path, SAMPLE_RATE)
+
+        peak = float(np.max(np.abs(audio))) if audio.size else 0.0
+        if peak > 1.0:
+            audio = audio / peak
+
+        return audio
+
+    @staticmethod
+    def chunk_audio(audio: np.ndarray) -> List[np.ndarray]:
+        if len(audio) == 0:
+            raise ValueError("The audio file is empty.")
+
+        chunks = []
+        for start in range(0, len(audio), CHUNK_SAMPLES):
+            chunk = audio[start:start + CHUNK_SAMPLES]
+            # The model is trained on 12-second chunks; pad the last one.
+            if len(chunk) < CHUNK_SAMPLES:
+                chunk = np.pad(chunk, (0, CHUNK_SAMPLES - len(chunk)), mode="constant")
+            chunks.append(chunk.astype(np.float32))
+        return chunks
+
+    @staticmethod
+    def get_label_scores(result: List[Dict[str, Any]]) -> Tuple[float, float]:
+        ai = 0.0
+        human = 0.0
+
+        for item in result:
+            label = str(item["label"]).lower()
+            score = float(item["score"])
+
+            if (
+                label in {"aivoice", "ai", "fake", "spoof", "ai-generated"}
+                or "ai" in label
+                or "spoof" in label
+            ):
+                ai = score
+            elif (
+                label in {"humanvoice", "human", "real"}
+                or "human" in label
+                or "real" in label
+            ):
+                human = score
+
+        # Fallback for unexpected model labels.
+        if ai == 0.0 and human == 0.0 and result:
+            top = max(result, key=lambda x: x["score"])
+            top_label = str(top["label"]).lower()
+            if "ai" in top_label or "fake" in top_label or "spoof" in top_label:
+                ai = float(top["score"])
+                human = 1.0 - ai
+            else:
+                human = float(top["score"])
+                ai = 1.0 - human
+
+        return ai, human
+
+    def predict(
+        self,
+        path: Union[str, os.PathLike],
+        threshold: float = DEFAULT_THRESHOLD,
+    ) -> Dict[str, Any]:
+        """Classify an audio file.
+
+        Supported formats: MP3, WAV, AAC, FLAC, OGG, Opus, M4A, AIFF.
+
+        ``threshold`` must be a float from 0.0 to 1.0 (inclusive); other
+        types raise ``TypeError`` and out-of-range values raise ``ValueError``.
+
+        Returns ``label`` ("AI" or "Human"), ``is_ai``, ``confidence``,
+        ``ai_score``, ``human_score``, ``duration``, ``threshold``,
+        ``device`` and per-chunk ``chunks`` details.
+        """
+        threshold = _validate_threshold(threshold)
+
+        if not path:
+            raise ValueError("Please provide an audio file path.")
+        if not Path(path).is_file():
+            raise FileNotFoundError(f"Audio file not found: {path}")
+
+        audio = self.load_audio(path)
+        chunks = self.chunk_audio(audio)
+
+        ai_scores, human_scores, rows = [], [], []
+        for idx, chunk in enumerate(chunks, start=1):
+            result = self._pipeline({"array": chunk, "sampling_rate": SAMPLE_RATE})
+            ai, human = self.get_label_scores(result)
+            ai_scores.append(ai)
+            human_scores.append(human)
+            rows.append(
+                {
+                    "chunk": idx,
+                    "start": (idx - 1) * CHUNK_SECONDS,
+                    "ai_score": round(ai, 4),
+                    "human_score": round(human, 4),
+                }
+            )
+
+        ai_score = float(np.mean(ai_scores))
+        human_score = float(np.mean(human_scores))
+        is_ai = ai_score >= threshold
+
+        return {
+            "label": "AI" if is_ai else "Human",
+            "is_ai": is_ai,
+            "confidence": ai_score if is_ai else human_score,
+            "ai_score": ai_score,
+            "human_score": human_score,
+            "duration": len(audio) / SAMPLE_RATE,
+            "threshold": threshold,
+            "device": self.device,
+            "chunks": rows,
+        }
+
+    __call__ = predict

modotte/image.py

@@ -0,0 +1,83 @@
+"""Image classification: AI-generated vs. real photographs."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import numpy as np
+from PIL import Image as PILImage
+
+from ._common import home_dir, load_pipeline
+from ._formats import IMAGE_EXTENSIONS, IMAGE_FORMATS, flatten_to_rgb, read_image
+
+MODEL_ID = "Modotte/AIRealNet"
+MODEL_DIR_NAME = "AIRealNetImage"
+
+ImageInput = Union[str, os.PathLike, PILImage.Image, np.ndarray]
+
+
+class Image:
+    """AIRealNet (SwinV2 Tiny) binary image classifier.
+
+    Class 0: AI-generated image ("artificial")
+    Class 1: Real human image ("real")
+
+    On first initialization ``~/AIRealNetImage`` is checked; if the model is
+    missing it is downloaded there. Runs on CUDA if available, else CPU.
+
+    ``hf_token`` (optional) is a Hugging Face access token used for the model
+    download, giving higher rate limits and faster downloads. If omitted, the
+    ``HF_TOKEN`` environment variable (or a token saved via ``hf auth login``)
+    is used when available.
+    """
+
+    SUPPORTED_FORMATS = IMAGE_FORMATS
+    SUPPORTED_EXTENSIONS = IMAGE_EXTENSIONS
+
+    def __init__(
+        self,
+        model_dir: Optional[Union[str, os.PathLike]] = None,
+        hf_token: Optional[str] = None,
+    ):
+        self.model_dir = Path(model_dir) if model_dir else home_dir() / MODEL_DIR_NAME
+        self._pipeline, self.device = load_pipeline(
+            "image-classification", MODEL_ID, self.model_dir, hf_token=hf_token
+        )
+
+    @staticmethod
+    def _to_pil(image: ImageInput) -> PILImage.Image:
+        if isinstance(image, PILImage.Image):
+            return flatten_to_rgb(image)
+        if isinstance(image, np.ndarray):
+            return flatten_to_rgb(PILImage.fromarray(image))
+        if not Path(image).is_file():
+            raise FileNotFoundError(f"Image file not found: {image}")
+        return read_image(image)
+
+    def predict(self, image: ImageInput) -> Dict[str, Any]:
+        """Classify an image (path, PIL image or numpy array).
+
+        Supported files: JPG, JPEG, PNG, WebP, GIF, SVG, BMP, TIFF, AVIF, HEIC, HEIF.
+
+        Returns ``label`` (top class, e.g. "artificial" or "real"),
+        ``confidence``, ``is_ai``, and ``scores`` such as
+        ``{'artificial': 0.94, 'real': 0.06}``.
+        """
+        if image is None:
+            raise ValueError("Please provide an image.")
+
+        results = self._pipeline(self._to_pil(image))
+        scores = {r["label"]: round(float(r["score"]), 3) for r in results}
+        label = max(results, key=lambda r: r["score"])["label"]
+
+        return {
+            "label": label,
+            "confidence": scores[label],
+            "is_ai": label.lower() in {"artificial", "ai", "fake"} or "artificial" in label.lower(),
+            "scores": scores,
+            "device": self.device,
+        }
+
+    __call__ = predict

modotte-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+modotte/AIRealNet.py,sha256=-EkQHhDe1vqUBOXYfcUvVAwh9rT3NpDQqO4sFPvo5Yg,148
+modotte/__init__.py,sha256=M51bKNoTjHjX9ivnY_XkF-r-BmzwEkUIRUNp16Tfh5A,88
+modotte/_common.py,sha256=0cR0QKEKD6-88dXj_70iTvd-hQnU6Fd2648XW7khO7s,3446
+modotte/_formats.py,sha256=oM0eD6RthKO3sAx3tmTx52MCSPRta1gtGXNhXIkt34I,6038
+modotte/audio.py,sha256=EIfVuw_xDKWBGKtVIRN40eg4h9o8nN3OsuX-m_r7fg4,6140
+modotte/image.py,sha256=j9X1jFzGzu0JkOk8tvZF58ENs3J-X6pXs_hUbxIiTzE,2897
+modotte-1.0.0.dist-info/licenses/LICENSE,sha256=MGQJ5agwuqNNKHU9qlSAhyV64mksKZRNoUlJ_MID5T8,1092
+modotte-1.0.0.dist-info/METADATA,sha256=D_n-CDdMXlUUD4DJv9d4vxwGQwK4pt1aBYiu8-ef5-s,8754
+modotte-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+modotte-1.0.0.dist-info/top_level.txt,sha256=sscqzIvtSNpW6yZ83-ym4_F4MpLARGG4P0yZuq0mM4E,8
+modotte-1.0.0.dist-info/RECORD,,

modotte-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modotte-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+modotte