moderators 0.0.1__py3-none-any.whl

moderators/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

moderators/auto_model.py

@@ -0,0 +1,158 @@
+# auto_model.py
+"""
+AutoModerator Factory.
+
+This module contains the AutoModerator class, a factory that automatically selects and initializes the correct moderator
+class based on a model identifier from the Hugging Face Hub.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from typing import Any
+
+# We import BaseModerator only for type hinting.
+# This avoids potential circular dependency issues.
+from .integrations.base import BaseModerator
+
+
+def _load_config(identifier: str, *, local_files_only: bool = False) -> dict[str, Any]:
+    """Loads a config.json file from a local path or the Hugging Face Hub."""
+    p = Path(identifier)
+    if p.is_dir():
+        cfg_path = p / "config.json"
+        if not cfg_path.exists():
+            raise FileNotFoundError(f"config.json not found in local folder: {cfg_path}")
+        return json.loads(cfg_path.read_text(encoding="utf-8"))
+
+    # We lazy-import huggingface_hub only when needed to reduce initial import time.
+    from huggingface_hub import hf_hub_download
+
+    cfg_fp = hf_hub_download(
+        repo_id=identifier,
+        filename="config.json",
+        repo_type="model",
+        local_files_only=local_files_only,
+    )
+    return json.loads(Path(cfg_fp).read_text(encoding="utf-8"))
+
+
+def _is_transformers_cfg(cfg: dict[str, Any]) -> bool:
+    """Checks if the given configuration belongs to a Transformers model."""
+    # The `architectures` key alone is not enough; we confirm with other signatures.
+    has_tf_sig = any(k in cfg for k in ("transformers_version", "model_type", "id2label", "label2id"))
+    has_arch_list = isinstance(cfg.get("architectures"), list)
+    return has_arch_list and has_tf_sig
+
+
+def _infer_task(cfg: dict[str, Any]) -> str | None:
+    """Attempts to infer the model's task by inspecting its architecture or problem_type."""
+    archs = [str(a).lower() for a in cfg.get("architectures", [])]
+    if any("classification" in a for a in archs):
+        return "image-classification"
+
+    prob = str(cfg.get("problem_type", "")).lower()
+    if "classification" in prob:
+        return "image-classification"
+
+    return None
+
+
+class AutoModerator:
+    """
+    A factory class that loads the correct moderator using the `from_pretrained` method.
+
+    This class cannot be instantiated directly (its `__init__` method will raise an error).
+    Instead, it should be used like:
+    `AutoModerator.from_pretrained('username/my-model')`
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        """AutoModerator cannot be instantiated directly."""
+        raise OSError(
+            "AutoModerator is a factory class and cannot be instantiated directly. "
+            "Please use the `AutoModerator.from_pretrained('model_id')` method."
+        )
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        model_id: str,
+        config: dict | None = None,
+        local_files_only: bool = False,
+        **kwargs: Any,
+    ) -> BaseModerator:
+        """
+        Loads the appropriate moderator from a model ID on the Hub or a local path.
+
+        This method reads the `config.json` file, determines the model's architecture,
+        dynamically loads the corresponding moderator class, and returns an initialized instance of it.
+
+        Args:
+            model_id (str): The Hugging Face Hub ID of the model to load or a path to a
+                local directory.
+            config (dict, optional): If provided, this config will be used instead of
+                downloading one from the Hub.
+            local_files_only (bool, optional): If True, will not attempt to download files
+                and will only look at local cached files. Defaults to False.
+            **kwargs: Additional keyword arguments to be passed to the moderator
+                class's `__init__` method.
+
+        Returns:
+            BaseModerator: A loaded and ready-to-use moderator object.
+        """
+        # Step 1: Load the configuration
+        cfg = dict(config or _load_config(model_id, local_files_only=local_files_only))
+
+        # Step 2: Determine the model architecture
+        architecture = cfg.get("architecture")
+        if not architecture:
+            # If architecture is not specified, try to infer if it's a Transformers model
+            if _is_transformers_cfg(cfg):
+                cfg["architecture"] = "TransformersModerator"
+                # If the task is also not specified, try to infer it
+                if not cfg.get("task"):
+                    inferred_task = _infer_task(cfg)
+                    if inferred_task:
+                        cfg["task"] = inferred_task
+                    else:
+                        raise ValueError(
+                            "Could not infer 'task' from the Transformers config. "
+                            "Please specify 'task' in the model's config.json "
+                            "(e.g. 'image-classification')."
+                        )
+            else:
+                raise ValueError(
+                    f"Could not determine 'architecture' from config.json for model '{model_id}'. "
+                    "Please specify 'architecture' in the config file."
+                )
+
+        architecture = cfg["architecture"]
+
+        # Step 3: Dynamically load the correct moderator class based on the architecture
+        # For MVP, only TransformersModerator is implemented
+        if architecture != "TransformersModerator":
+            raise NotImplementedError(
+                f"'{architecture}' is not yet supported in this version of Moderators. "
+                "As of now, only 'TransformersModerator' is implemented."
+            )
+
+        module_name = architecture.replace("Moderator", "_moderator").lower()
+        module_path = f"moderators.integrations.{module_name}"
+
+        try:
+            module = importlib.import_module(module_path)
+            moderator_class = getattr(module, architecture)
+        except (ImportError, AttributeError) as e:
+            raise ImportError(
+                f"Could not find or import the class '{architecture}'. "
+                f"Please ensure it is defined in '{module_path}.py'. Error: {e}"
+            )
+
+        # Step 4: Initialize the moderator class and load its model
+        instance = moderator_class(model_id=model_id, config=cfg, **kwargs)
+        instance.load_model()
+
+        return instance

moderators/cli.py

@@ -0,0 +1,39 @@
+# src/moderators/cli.py
+import argparse
+import json
+from dataclasses import asdict, is_dataclass
+
+from moderators.auto_model import AutoModerator
+
+
+def _to_jsonable(obj):
+    """Convert objects to JSON-serializable format."""
+    if is_dataclass(obj):
+        return asdict(obj)
+    if isinstance(obj, (list, dict, str, int, float)) or obj is None:
+        return obj
+    return str(obj)
+
+
+def main():
+    """Run the moderators CLI."""
+    parser = argparse.ArgumentParser(prog="moderators", description="Moderators CLI")
+    parser.add_argument("model", nargs="?", help="Local model folder or HF model id")
+    parser.add_argument("input", nargs="?", help="Input text or file path")
+    parser.add_argument("--local-files-only", action="store_true", dest="local_files_only", help="Use only local files")
+    args = parser.parse_args()
+
+    if not args.model:
+        parser.print_help()
+        return 0
+
+    mod = AutoModerator.from_pretrained(args.model, local_files_only=args.local_files_only)
+    if args.input:
+        out = mod(args.input)
+        print(json.dumps([_to_jsonable(x) for x in out], ensure_ascii=False, indent=2))
+    else:
+        print("Model loaded. Provide the 'input' argument to run inference.")
+
+
+if __name__ == "__main__":
+    main()

moderators/integrations/__init__.py

@@ -0,0 +1 @@
+# Integration package init

moderators/integrations/base.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod  # added
+from dataclasses import dataclass, field
+from typing import Any
+
+from huggingface_hub import ModelHubMixin
+
+
+@dataclass
+class Box:
+    """
+    Represents a bounding box detection result.
+
+    Attributes:
+        xyxy: Bounding box coordinates as [x1, y1, x2, y2]
+        label: Classification label for the detected object
+        score: Confidence score for the detection
+    """
+
+    # xyxy: [x1, y1, x2, y2]
+    xyxy: list[float]
+    label: str
+    score: float
+
+
+@dataclass
+class PredictionResult:
+    """
+    Represents the output of a moderation prediction.
+
+    Attributes:
+        source_path: Context about the source (file path, URL, etc.)
+        classifications: Probability map for classification tasks
+        detections: List of bounding box detections
+        raw_output: Raw model output specific to the integration
+    """
+
+    # Context about the source (file path, URL, etc.)
+    source_path: str = ""
+    # Probability map for classification
+    classifications: dict[str, float] = field(default_factory=dict)
+    # Detection results
+    detections: list[Box] = field(default_factory=list)
+    # Raw output specific to models/integrations
+    raw_output: Any = None
+
+
+class BaseModerator(ABC, ModelHubMixin):
+    """
+    Base class for all moderator implementations.
+
+    Provides the core prediction flow and callback system for content moderation.
+    """
+
+    def __init__(self, config: dict[str, Any], model_id: str, **kwargs: Any) -> None:
+        """
+        Initialize the moderator.
+
+        Args:
+            config: Configuration dictionary for the moderator
+            model_id: Model identifier (HuggingFace Hub ID or local path)
+            **kwargs: Additional keyword arguments
+        """
+        self.config: dict[str, Any] = dict(config or {})
+        self.model_id: str = model_id
+        self.config.setdefault("model_id", self.model_id)
+        self.callbacks = self.get_default_callbacks()
+
+    @abstractmethod
+    def load_model(self) -> None:
+        """Load model/pipeline and any processors if present."""
+        pass
+
+    # Inference flow
+    def __call__(self, source: Any, **kwargs: Any):
+        """
+        Execute the full prediction pipeline.
+
+        Args:
+            source: Input source (text, image path, PIL Image, etc.)
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            List of PredictionResult objects
+        """
+        self.run_callbacks("on_predict_start")
+        processed_inputs = self._preprocess(source)
+        model_outputs = self._predict(processed_inputs)
+        results = self._postprocess(model_outputs)
+        self.run_callbacks("on_predict_end")
+        return results
+
+    @abstractmethod
+    def _preprocess(self, inputs: Any) -> Any:
+        """Convert inputs to model-ready format."""
+        pass
+
+    @abstractmethod
+    def _predict(self, processed_inputs: Any) -> Any:
+        """Run model inference."""
+        pass
+
+    @abstractmethod
+    def _postprocess(self, model_outputs: Any) -> Any:
+        """Convert outputs to PredictionResult format."""
+        pass
+
+    @abstractmethod
+    def save_pretrained(self, save_directory: str, **kwargs: Any) -> str:
+        """Save model and any processors to the given directory."""
+        raise NotImplementedError
+
+    # Callback system (simple MVP)
+    def get_default_callbacks(self) -> dict[str, list]:
+        """
+        Get the default callback configuration.
+
+        Returns:
+            Dictionary mapping event names to lists of callback functions
+        """
+        from moderators.utils.callbacks import DEFAULT_CALLBACKS
+
+        return {k: list(v) for k, v in DEFAULT_CALLBACKS.items()}
+
+    def run_callbacks(self, event_name: str) -> None:
+        """
+        Execute all callbacks for a given event.
+
+        Args:
+            event_name: Name of the event to trigger callbacks for
+        """
+        for func in self.callbacks.get(event_name, []):
+            try:
+                func(self)
+            except Exception:
+                # Do not break inference flow due to a callback failure
+                pass

moderators/integrations/transformers_moderator.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from moderators.utils import (
+    auto_install,
+    ensure_dl_framework,
+    ensure_pillow_for_task,
+    ensure_transformers,
+    preprocess_image_input,
+)
+
+from .base import BaseModerator, PredictionResult
+
+
+class TransformersModerator(BaseModerator):
+    """Moderator implementation using HuggingFace Transformers."""
+
+    def load_model(self) -> None:
+        """
+        Build a transformers pipeline deterministically:
+        - Validate task.
+        - Ensure deps (transformers, DL framework, Pillow for image tasks).
+        - Try AutoProcessor (if local `preprocessor_config.json` exists).
+        - Fallback order: AutoImageProcessor -> AutoFeatureExtractor.
+        - Also try AutoTokenizer when relevant.
+        - Pass only successfully loaded components (processor / image_processor / feature_extractor / tokenizer).
+        """
+        task = self.config.get("task")
+        if not task:
+            raise ValueError("TransformersModerator requires 'task' in config.json")
+
+        # Ensure transformers is available
+        try:
+            _transformers = ensure_transformers(auto_install)
+        except Exception as e:
+            raise ImportError(
+                "TransformersModerator requires the 'transformers' package. "
+                "Install with: uv pip install -e '.[transformers]' or: uv pip install transformers"
+            ) from e
+
+        pipeline = getattr(_transformers, "pipeline")
+
+        # Ensure a DL framework (pt/tf/flax)
+        framework = ensure_dl_framework(auto_install)
+
+        # Ensure Pillow for image tasks
+        ensure_pillow_for_task(task, auto_install)
+
+        model_id = self.model_id
+
+        processor = None
+        image_processor = None
+        feature_extractor = None
+        tokenizer = None
+
+        # Check local preprocessor_config.json
+        try:
+            p = Path(model_id)
+            has_local_preprocessor = p.is_dir() and (p / "preprocessor_config.json").exists()
+        except Exception:
+            has_local_preprocessor = False
+
+        # AutoProcessor (generic unified) first if local config hints it exists
+        if has_local_preprocessor:
+            try:
+                AutoProcessor = getattr(_transformers, "AutoProcessor", None)
+                if AutoProcessor:
+                    processor = AutoProcessor.from_pretrained(model_id)
+            except Exception:
+                processor = None  # soft fallback
+
+        # If no unified processor, attempt vision processors explicitly
+        if processor is None:
+            # Newer API
+            try:
+                AutoImageProcessor = getattr(_transformers, "AutoImageProcessor", None)
+                if AutoImageProcessor:
+                    image_processor = AutoImageProcessor.from_pretrained(model_id)
+            except Exception:
+                image_processor = None
+            # Legacy feature extractor
+            if image_processor is None:
+                try:
+                    AutoFeatureExtractor = getattr(_transformers, "AutoFeatureExtractor", None)
+                    if AutoFeatureExtractor:
+                        feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
+                except Exception:
+                    feature_extractor = None
+
+        # Tokenizer (independent of vision processors)
+        try:
+            AutoTokenizer = getattr(_transformers, "AutoTokenizer", None)
+            if AutoTokenizer:
+                tokenizer = AutoTokenizer.from_pretrained(model_id)
+        except Exception:
+            tokenizer = None
+
+        pipe_kwargs = {}
+        if processor is not None:
+            pipe_kwargs["processor"] = processor
+        else:
+            if image_processor is not None:
+                pipe_kwargs["image_processor"] = image_processor
+            elif feature_extractor is not None:
+                pipe_kwargs["feature_extractor"] = feature_extractor
+            if tokenizer is not None:
+                pipe_kwargs["tokenizer"] = tokenizer
+
+        self._pipe = pipeline(
+            task,
+            model=model_id,
+            framework=framework,
+            **pipe_kwargs,
+        )
+
+    def _preprocess(self, inputs: Any) -> Any:
+        task = str(self.config.get("task", "")).lower()
+        if "image" in task:
+            return preprocess_image_input(inputs, min_side=2)
+        return inputs
+
+    def _predict(self, processed_inputs: Any) -> Any:
+        return self._pipe(processed_inputs)
+
+    def _postprocess(self, model_outputs: Any) -> list[PredictionResult]:
+        # Pipelines typically return dict or list[dict]
+        outputs = model_outputs
+        if isinstance(outputs, dict):
+            outputs = [outputs]
+
+        results: list[PredictionResult] = []
+        for out in outputs:
+            classifications: dict[str, float] = {}
+            label = out.get("label")
+            score = out.get("score")
+            if label is not None and score is not None:
+                classifications[str(label)] = float(score)
+
+            results.append(
+                PredictionResult(
+                    source_path=str(self.config.get("source", "")),
+                    classifications=classifications,
+                    detections=[],
+                    raw_output=out,
+                )
+            )
+        return results
+
+    def save_pretrained(self, save_directory: str, **kwargs: Any) -> str:
+        """Saves model + tokenizer + (processor / image_processor / feature_extractor) and refreshes/creates a
+        config.json with required moderator metadata.
+        """
+        out_dir = Path(save_directory)
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        pipe = getattr(self, "_pipe", None)
+
+        model = getattr(pipe, "model", None) if pipe is not None else None
+        tokenizer = getattr(pipe, "tokenizer", None) if pipe is not None else None
+
+        # Unified vision processor resolution order:
+        # processor (generic) -> image_processor (newer HF) -> feature_extractor (legacy)
+        vision_processor = None
+        if pipe is not None:
+            vision_processor = (
+                getattr(pipe, "processor", None)
+                or getattr(pipe, "image_processor", None)
+                or getattr(pipe, "feature_extractor", None)
+            )
+
+        if model and hasattr(model, "save_pretrained"):
+            model.save_pretrained(out_dir)
+        if tokenizer and hasattr(tokenizer, "save_pretrained"):
+            tokenizer.save_pretrained(out_dir)
+        if vision_processor and hasattr(vision_processor, "save_pretrained"):
+            vision_processor.save_pretrained(out_dir)
+
+        cfg_path = out_dir / "config.json"
+        try:
+            cfg = json.loads(cfg_path.read_text(encoding="utf-8")) if cfg_path.exists() else {}
+        except Exception:
+            cfg = {}
+
+        cfg["architecture"] = "TransformersModerator"
+        if self.config.get("task"):
+            cfg["task"] = self.config["task"]
+
+        cfg_path.write_text(json.dumps(cfg, ensure_ascii=False, indent=2), encoding="utf-8")
+        return str(out_dir)

moderators/utils/__init__.py

@@ -0,0 +1,11 @@
+# filepath init for utils package
+from .deps import auto_install, ensure_dl_framework, ensure_pillow_for_task, ensure_transformers
+from .image import preprocess_image_input
+
+__all__ = [
+    "auto_install",
+    "ensure_transformers",
+    "ensure_dl_framework",
+    "ensure_pillow_for_task",
+    "preprocess_image_input",
+]

moderators/utils/callbacks.py

@@ -0,0 +1,30 @@
+from moderators.utils.events import events
+
+
+def on_predict_start(predictor):
+    """
+    Callback executed before prediction starts.
+
+    Enqueues analytics event with task and model_id information.
+    """
+    # Add analytics event
+    try:
+        cfg = {
+            "task": predictor.config.get("task", "unknown_task"),
+            "model_id": getattr(predictor, "model_id", None),
+        }
+        events(cfg)
+    except Exception:
+        # Callback should not break inference flow
+        pass
+
+
+def on_predict_end(predictor):
+    """Callback executed after prediction ends."""
+    pass
+
+
+DEFAULT_CALLBACKS = {
+    "on_predict_start": [on_predict_start],
+    "on_predict_end": [on_predict_end],
+}

moderators/utils/deps.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+
+
+def auto_install(packages: list[str]) -> bool:
+    """
+    Try to auto-install required packages using 'uv' if available, otherwise fall back to 'pip'.
+
+    Controlled by env var: MODERATORS_DISABLE_AUTO_INSTALL=1 to disable.
+    """
+    if str(os.environ.get("MODERATORS_DISABLE_AUTO_INSTALL", "")).lower() in ("1", "true", "yes"):
+        return False
+
+    uv = shutil.which("uv")
+    cmd = [uv, "pip", "install", *packages] if uv else [sys.executable, "-m", "pip", "install", *packages]
+
+    try:
+        subprocess.check_call(cmd)
+        return True
+    except Exception:
+        return False
+
+
+def ensure_transformers(install_fn: Callable[[list[str]], bool]):
+    """Ensure 'transformers' is importable; optionally auto-install and retry."""
+    try:
+        import transformers as _transformers  # noqa: F401
+
+        return _transformers
+    except Exception:
+        if not install_fn(["transformers"]):
+            raise
+        import transformers as _transformers  # type: ignore
+
+        return _transformers
+
+
+def ensure_dl_framework(install_fn: Callable[[list[str]], bool]) -> str:
+    """
+    Ensure at least one DL framework is available.
+
+    Preference: PyTorch ('pt'), TensorFlow ('tf'), JAX/Flax ('flax').
+    Tries to auto-install torch first.
+    """
+    try:
+        import torch  # noqa: F401
+
+        return "pt"
+    except Exception:
+        if install_fn(["torch"]):
+            try:
+                import torch  # noqa: F401
+
+                return "pt"
+            except Exception:
+                pass
+    try:
+        import tensorflow  # noqa: F401
+
+        return "tf"
+    except Exception:
+        pass
+    try:
+        import jax  # noqa: F401
+
+        return "flax"
+    except Exception:
+        pass
+    raise ImportError(
+        "A deep learning framework is required for transformers pipelines. Install PyTorch with: uv pip install torch"
+    )
+
+
+def ensure_pillow_for_task(task: str, install_fn: Callable[[list[str]], bool]) -> None:
+    """For image tasks, ensure Pillow is available; auto-install if missing."""
+    if "image" not in str(task).lower():
+        return
+    try:
+        import PIL  # noqa: F401
+    except Exception:
+        if not install_fn(["Pillow"]):
+            raise ImportError("This image task requires Pillow. Install with: uv pip install Pillow")
+        import PIL  # noqa: F401

moderators/utils/events.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+import requests
+
+
+def _robust_post_request(
+    url: str,
+    json_data: dict[str, Any],
+    retries: int = 3,
+    initial_wait: float = 1.0,
+    timeout: int = 5,
+) -> None:
+    """
+    Sends a POST request with JSON data to a URL, with retries on transient errors using an exponential backoff
+    strategy.
+
+    Args:
+        url (str): The URL to send the request to.
+        json_data (dict[str, Any]): The JSON data to send.
+        retries (int): The maximum number of retries for a failed request.
+        initial_wait (float): The initial wait time between retries in seconds.
+        timeout (int): The timeout for each individual request in seconds.
+    """
+    wait_time = initial_wait
+    for attempt in range(retries + 1):
+        try:
+            response = requests.post(url, json=json_data, timeout=timeout)
+            # 2xx status codes indicate success, exit the function.
+            if 200 <= response.status_code < 300:
+                return
+            # 4xx client errors are not worth retrying, break the loop.
+            if 400 <= response.status_code < 500:
+                break
+            # 5xx server errors are worth retrying.
+        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
+            # In case of a timeout or connection error, proceed to the next attempt.
+            pass
+
+        # Wait only if this is not the last attempt.
+        if attempt < retries:
+            time.sleep(wait_time)
+            wait_time *= 2  # Double the wait time for the next attempt.
+
+
+def _settings_path() -> Path:
+    base = Path.home() / ".moderators"
+    base.mkdir(parents=True, exist_ok=True)
+    return base / "settings.json"
+
+
+def _read_settings() -> dict[str, Any]:
+    path = _settings_path()
+    if not path.exists():
+        return {"sync": True}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {"sync": True}
+
+
+class Events:
+    """
+    Handles the collection and transmission of anonymous usage analytics.
+
+    Implemented as a queue with background sending and rate limiting.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Events analytics handler."""
+        self.url = (
+            "https://www.google-analytics.com/mp/collect?measurement_id=G-XDJCD0WJDW&api_secret=xgz_lUC6SK-u4-EDAUFcFg"
+        )
+        self.events: list[dict[str, Any]] = []
+        self.rate_limit_seconds = 30.0
+        self.last_sent_ts = 0.0
+        self.metadata = self._get_metadata()
+        self.enabled = self._is_enabled()
+
+    def __call__(self, cfg: dict[str, Any]) -> None:
+        """
+        Enqueue an analytics event.
+
+        Args:
+            cfg: Configuration dictionary containing task and model_id
+        """
+        if not self.enabled:
+            return
+        if len(self.events) > 25:
+            return
+
+        # Clean the event name by replacing hyphens with underscores
+        original_task_name = cfg.get("task", "unknown_task")
+        sanitized_event_name = original_task_name.replace("-", "_")
+
+        event_data = {
+            "name": sanitized_event_name,
+            "params": {**self.metadata, "model_id": cfg.get("model_id")},
+        }
+        self.events.append(event_data)
+
+        if (time.time() - self.last_sent_ts) > self.rate_limit_seconds:
+            self.send_events()
+
+    def send_events(self) -> None:
+        """Send queued analytics events in a background thread."""
+        if not self.events:
+            return
+
+        data_payload = {"client_id": self.metadata["user_id"], "events": self.events}
+        self.events = []
+        self.last_sent_ts = time.time()
+        threading.Thread(target=self._make_request, args=(data_payload,), daemon=True).start()
+
+    def _make_request(self, json_data: dict[str, Any]) -> None:
+        """
+        Makes a robust network request to send analytics data.
+
+        This method now uses a helper function with retry logic.
+        """
+        # We are now using the more robust helper function.
+        _robust_post_request(self.url, json_data)
+
+    def _get_metadata(self) -> dict[str, Any]:
+        user_id = self._get_or_create_user_id()
+        return {
+            "user_id": user_id,
+            "library": "moderators",
+            "library_version": self._get_version(),
+        }
+
+    def _get_or_create_user_id(self) -> str:
+        path = Path.home() / ".moderators" / "user.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            try:
+                data = json.loads(path.read_text())
+                if "user_id" in data:
+                    return str(data["user_id"])
+            except Exception:
+                pass
+        uid = str(uuid.uuid4())
+        try:
+            path.write_text(json.dumps({"user_id": uid}))
+        except Exception:
+            pass
+        return uid
+
+    def _is_enabled(self) -> bool:
+        settings = _read_settings()
+        return bool(settings.get("sync", True))
+
+    def _get_version(self) -> str:
+        try:
+            from moderators import __version__  # type: ignore
+
+            return str(__version__)
+        except Exception:
+            return "0"
+
+
+# Global singleton instance
+events = Events()

moderators/utils/image.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def preprocess_image_input(inputs: Any, min_side: int = 0) -> Any:
+    """
+    Preprocesses image inputs from Path, PIL Image, or a list/tuple (batch).
+
+    - Opens the image if the input is a path.
+    - Converts the image to RGB.
+    - (Optional) If min_side > 0, proportionally scales up small images.
+    Returns the input as is if Pillow is not installed or if the input type is unrecognized.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        return inputs
+
+    def _process(obj: Any):
+        # Path or string
+        if isinstance(obj, (str, Path)):
+            try:
+                img = Image.open(str(obj))
+            except (FileNotFoundError, OSError):
+                return obj
+        # PIL Image-like object
+        elif hasattr(obj, "mode") and hasattr(obj, "convert"):
+            img = obj
+        else:
+            return obj
+
+        # Ensure the image is in RGB mode
+        if img.mode != "RGB":
+            try:
+                img = img.convert("RGB")
+            except Exception:
+                return obj  # Return the original if conversion fails
+
+        # Optional resizing
+        if min_side and min_side > 0:
+            try:
+                w, h = img.size
+                if w < min_side or h < min_side:
+                    scale = max(min_side / w, min_side / h)
+                    new_w = int(round(w * scale))
+                    new_h = int(round(h * scale))
+                    resample = getattr(getattr(Image, "Resampling", Image), "BILINEAR")
+                    img = img.resize((new_w, new_h), resample)
+            except Exception:
+                pass
+
+        return img
+
+    if isinstance(inputs, (list, tuple)):
+        return [_process(x) for x in inputs]
+    return _process(inputs)

moderators-0.0.1.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: moderators
+Version: 0.0.1
+Summary: Moderators: One package to moderate them all
+Project-URL: Homepage, https://github.com/viddexa/moderators
+Project-URL: Source, https://github.com/viddexa/moderators
+Project-URL: Bug Reports, https://github.com/viddexa/moderators/discussions/categories/q-a
+Project-URL: Changelog, https://github.com/viddexa/moderators/releases
+Author: Moderators Team
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: huggingface-hub>=0.22
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: docformatter; extra == 'dev'
+Requires-Dist: pillow>=9.0; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: torch; extra == 'dev'
+Provides-Extra: transformers
+Requires-Dist: transformers>=4.36; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+# Moderators
+
+[![CI](https://github.com/viddexa/moderators/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/viddexa/moderators/actions/workflows/ci.yml)
+
+# TODO: refactor readme to target users instead of maintainers
+
+This repository provides an extensible core skeleton for content moderation. Phase 1 includes:
+- Standard data classes (Box, PredictionResult)
+- BaseModerator flow (predict → _preprocess → _predict → _postprocess)
+- ModelHubMixin-based `AutoModerator` factory (reads `config.json` from HF Hub or local)
+- CLI: `moderators` (load and run inference)
+
+First integration: Transformers.
+
+## Installation
+
+Create Python environment (Python 3.10+ recommended):
+
+```bash
+uv venv --python 3.10
+source .venv/bin/activate
+```
+
+Install with pip:
+
+```bash
+pip install moderators[transformers]
+```
+
+Install with uv:
+
+```bash
+uv add "moderators[transformers]"
+```
+
+Install from source:
+
+```bash
+uv sync --extra transformers
+```
+
+## Quick Start
+
+```python
+from moderators.auto_model import AutoModerator
+
+moderator = AutoModerator.from_pretrained("org/model")  # or a local folder path
+results = moderator("some input")
+print(results)
+```
+
+`config.json` example (Transformers):
+```json
+{
+  "architecture": "TransformersModerator",
+  "task": "image-classification"
+}
+```
+
+- Naming convention: the `XyzModerator` class must be defined in `moderators/integrations/xyz_moderator.py`.
+- Note: `AutoModerator` is a factory class; it returns the actual integration instance.
+
+## Automatic dependency installation
+When using the Transformers integration, the library may auto-install missing dependencies at runtime:
+- transformers
+- A deep learning framework (PyTorch preferred: torch)
+- Pillow (for image tasks)
+
+It uses `uv` if available, otherwise falls back to `pip`. Disable auto-install via:
+```
+export MODERATORS_DISABLE_AUTO_INSTALL=1
+```
+
+## Usage Overview
+`AutoModerator.from_pretrained("org/model")` dynamically loads the correct integration class based on the `"architecture"` field in `config.json`.
+
+## Command Line (CLI)
+Run models directly from the terminal.
+
+Usage:
+```
+moderators <model_id_or_local_dir> <input> [--local-files-only]
+```
+
+Examples:
+- Text classification:
+```
+moderators distilbert/distilbert-base-uncased-finetuned-sst-2-english "I love this!"
+```
+
+- Image classification (Falconsai/nsfw_image_detection) with a local image:
+```
+moderators Falconsai/nsfw_image_detection /path/to/image.jpg
+```
+
+Notes:
+- The CLI prints JSON to stdout.
+- Use `--local-files-only` to force offline usage if all files are already cached.
+
+## Transformers config inference
+If `"architecture"` is missing but the config looks like a Transformers model (e.g., has `architectures`, `transformers_version`, `id2label`/`label2id`), the factory assumes:
+- `architecture = "TransformersModerator"`
+- It tries to infer `"task"` (e.g., classification). If it cannot infer, you must specify `"task"` explicitly (e.g., `"image-classification"`).
+
+## Callbacks
+Moderators run a minimal callback system around prediction:
+- `on_predict_start(moderator)` is called before prediction.
+- `on_predict_end(moderator)` is called after prediction.
+
+By default, `on_predict_start` enqueues a lightweight analytics event (see below). You can customize per-instance callbacks:
+```python
+mod = AutoModerator.from_pretrained("org/model")
+# Disable all start callbacks (including analytics)
+mod.callbacks["on_predict_start"].clear()
+# Or add your own callback
+def my_callback(m):
+    print("Starting inference for", m.model_id)
+mod.callbacks["on_predict_start"].append(my_callback)
+```
+
+## Anonymous Telemetry
+
+We believe in providing our users with full control over their data. By default, our package is configured to collect analytics to help improve the experience for all users. However, we respect that some users may prefer to opt out of this data collection.
+
+To opt out of sending analytics, you can simply create `~/.moderators/settings.json` file with `"sync": false`. This ensures that no data is transmitted from your machine to our analytics tools.
+
+## Limitations (Phase 1)
+- Only `TransformersModerator` is supported; other architectures raise `NotImplementedError`.
+- Image tasks require Pillow and at least one DL framework (preferably PyTorch). The library may attempt auto-install, otherwise it will raise an error.
+
+## Integrations
+- Transformers integration

moderators-0.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+moderators/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+moderators/auto_model.py,sha256=ZUX2ZjJJcW-2UelCggf7n9oUUvp7Tbr7TG7kaSgp2EE,6388
+moderators/cli.py,sha256=4N-NZaX56odysAoICrOnRfw5wH0hxWzlIDbw8_qdbWs,1263
+moderators/integrations/__init__.py,sha256=s0PG87w1yriVdi58mFpaVPyK3KS7eytvFhPJZ2S8pes,27
+moderators/integrations/base.py,sha256=6sqeQVT2CAQ2pMikEkH7UCa2GbM4jYmHnYZEe7r8ks0,4185
+moderators/integrations/transformers_moderator.py,sha256=axFzJAIUUAL-JYerU7ydO2iWdhu9BFyik4emcZIh7RE,7171
+moderators/utils/__init__.py,sha256=1qcESgxVGKkI-KPMVBzTyuh2QD2Tc98e1gyTMlG6Gfw,322
+moderators/utils/callbacks.py,sha256=qJ9fzJIsx9_Ei56xKyaQjr81h3oScWLArdBy37NPvh8,706
+moderators/utils/deps.py,sha256=_-3Mms_20BiZss0TTHnhNDfxIBVcIlOLX5Ht3Dj8pZU,2480
+moderators/utils/events.py,sha256=FBdfFESXp-PFj1d8SjGB8qSUElsPrINHHDos3AtK99M,5359
+moderators/utils/image.py,sha256=vr9N-JrfaFkxX9pt-DddjUAXmbLknl8EnxsHvsHmGDU,1856
+moderators-0.0.1.dist-info/METADATA,sha256=3DqAMPdeuW7OK5mJYadRiudtkN8ucFlN-c8PqTTSPA4,5304
+moderators-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+moderators-0.0.1.dist-info/entry_points.txt,sha256=x4tWXqjIbl_SyOAJm0PjW1GHBocMQPFlOGxmdCvK2D0,51
+moderators-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+moderators-0.0.1.dist-info/RECORD,,

moderators-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

moderators-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+moderators = moderators.cli:main

moderators-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.