dgenerate-ultralytics-headless 8.3.253__py3-none-any.whl

ultralytics/utils/callbacks/platform.py

@@ -0,0 +1,453 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+import os
+import platform
+import re
+import socket
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from time import time
+
+from ultralytics.utils import ENVIRONMENT, GIT, LOGGER, PYTHON_VERSION, RANK, SETTINGS, TESTS_RUNNING, colorstr
+
+PREFIX = colorstr("Platform: ")
+
+
+def slugify(text):
+    """Convert text to URL-safe slug (e.g., 'My Project 1' -> 'my-project-1')."""
+    if not text:
+        return text
+    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9\s-]", "", str(text).lower()).replace(" ", "-")).strip("-")[:128]
+
+
+try:
+    assert not TESTS_RUNNING  # do not log pytest
+    assert SETTINGS.get("platform", False) is True or os.getenv("ULTRALYTICS_API_KEY") or SETTINGS.get("api_key")
+    _api_key = os.getenv("ULTRALYTICS_API_KEY") or SETTINGS.get("api_key")
+    assert _api_key  # verify API key is present
+
+    import requests
+
+    from ultralytics.utils.logger import ConsoleLogger, SystemLogger
+    from ultralytics.utils.torch_utils import model_info_for_loggers
+
+    _executor = ThreadPoolExecutor(max_workers=10)  # Bounded thread pool for async operations
+
+except (AssertionError, ImportError):
+    _api_key = None
+
+
+def resolve_platform_uri(uri, hard=True):
+    """Resolve ul:// URIs to signed URLs by authenticating with Ultralytics Platform.
+
+    Formats:
+        ul://username/datasets/slug  -> Returns signed URL to NDJSON file
+        ul://username/project/model  -> Returns signed URL to .pt file
+
+    Args:
+        uri (str): Platform URI starting with "ul://".
+        hard (bool): Whether to raise an error if resolution fails (FileNotFoundError only).
+
+    Returns:
+        (str | None): Signed URL on success, None if not found and hard=False.
+
+    Raises:
+        ValueError: If API key is missing/invalid or URI format is wrong.
+        PermissionError: If access is denied.
+        RuntimeError: If resource is not ready (e.g., dataset still processing).
+        FileNotFoundError: If resource not found and hard=True.
+        ConnectionError: If network request fails and hard=True.
+    """
+    import requests
+
+    path = uri[5:]  # Remove "ul://"
+    parts = path.split("/")
+
+    api_key = os.getenv("ULTRALYTICS_API_KEY") or SETTINGS.get("api_key")
+    if not api_key:
+        raise ValueError(f"ULTRALYTICS_API_KEY required for '{uri}'. Get key at https://alpha.ultralytics.com/settings")
+
+    base = "https://alpha.ultralytics.com/api/webhooks"
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    # ul://username/datasets/slug
+    if len(parts) == 3 and parts[1] == "datasets":
+        username, _, slug = parts
+        url = f"{base}/datasets/{username}/{slug}/export"
+
+    # ul://username/project/model
+    elif len(parts) == 3:
+        username, project, model = parts
+        url = f"{base}/models/{username}/{project}/{model}/download"
+
+    else:
+        raise ValueError(f"Invalid platform URI: {uri}. Use ul://user/datasets/name or ul://user/project/model")
+
+    try:
+        r = requests.head(url, headers=headers, allow_redirects=False, timeout=30)
+
+        # Handle redirect responses (301, 302, 303, 307, 308)
+        if 300 <= r.status_code < 400 and "location" in r.headers:
+            return r.headers["location"]  # Return signed URL
+
+        # Handle error responses
+        if r.status_code == 401:
+            raise ValueError(f"Invalid ULTRALYTICS_API_KEY for '{uri}'")
+        if r.status_code == 403:
+            raise PermissionError(f"Access denied for '{uri}'. Check dataset/model visibility settings.")
+        if r.status_code == 404:
+            if hard:
+                raise FileNotFoundError(f"Not found on platform: {uri}")
+            LOGGER.warning(f"Not found on platform: {uri}")
+            return None
+        if r.status_code == 409:
+            raise RuntimeError(f"Resource not ready: {uri}. Dataset may still be processing.")
+
+        # Unexpected response
+        r.raise_for_status()
+        raise RuntimeError(f"Unexpected response from platform for '{uri}': {r.status_code}")
+
+    except requests.exceptions.RequestException as e:
+        if hard:
+            raise ConnectionError(f"Failed to resolve {uri}: {e}") from e
+        LOGGER.warning(f"Failed to resolve {uri}: {e}")
+        return None
+
+
+def _interp_plot(plot, n=101):
+    """Interpolate plot curve data from 1000 to n points to reduce storage size."""
+    import numpy as np
+
+    if not plot.get("x") or not plot.get("y"):
+        return plot  # No interpolation needed (e.g., confusion_matrix)
+
+    x, y = np.array(plot["x"]), np.array(plot["y"])
+    if len(x) <= n:
+        return plot  # Already small enough
+
+    # New x values (101 points gives clean 0.01 increments: 0, 0.01, 0.02, ..., 1.0)
+    x_new = np.linspace(x[0], x[-1], n)
+
+    # Interpolate y values (handle both 1D and 2D arrays)
+    if y.ndim == 1:
+        y_new = np.interp(x_new, x, y)
+    else:
+        y_new = np.array([np.interp(x_new, x, yi) for yi in y])
+
+    # Also interpolate ap if present (for PR curves)
+    result = {**plot, "x": x_new.tolist(), "y": y_new.tolist()}
+    if "ap" in plot:
+        result["ap"] = plot["ap"]  # Keep AP values as-is (per-class scalars)
+
+    return result
+
+
+def _send(event, data, project, name, model_id=None):
+    """Send event to Platform endpoint. Returns response JSON on success."""
+    try:
+        payload = {"event": event, "project": project, "name": name, "data": data}
+        if model_id:
+            payload["modelId"] = model_id
+        r = requests.post(
+            "https://alpha.ultralytics.com/api/webhooks/training/metrics",
+            json=payload,
+            headers={"Authorization": f"Bearer {_api_key}"},
+            timeout=10,
+        )
+        r.raise_for_status()
+        return r.json()
+    except Exception as e:
+        LOGGER.debug(f"Platform: Failed to send {event}: {e}")
+        return None
+
+
+def _send_async(event, data, project, name, model_id=None):
+    """Send event asynchronously using bounded thread pool."""
+    _executor.submit(_send, event, data, project, name, model_id)
+
+
+def _upload_model(model_path, project, name):
+    """Upload model checkpoint to Platform via signed URL."""
+    try:
+        model_path = Path(model_path)
+        if not model_path.exists():
+            return None
+
+        # Get signed upload URL
+        response = requests.post(
+            "https://alpha.ultralytics.com/api/webhooks/models/upload",
+            json={"project": project, "name": name, "filename": model_path.name},
+            headers={"Authorization": f"Bearer {_api_key}"},
+            timeout=10,
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # Upload to GCS
+        with open(model_path, "rb") as f:
+            requests.put(
+                data["uploadUrl"],
+                data=f,
+                headers={"Content-Type": "application/octet-stream"},
+                timeout=600,  # 10 min timeout for large models
+            ).raise_for_status()
+
+        # url = f"https://alpha.ultralytics.com/{project}/{name}"
+        # LOGGER.info(f"{PREFIX}Model uploaded to {url}")
+        return data.get("gcsPath")
+
+    except Exception as e:
+        LOGGER.debug(f"Platform: Failed to upload model: {e}")
+        return None
+
+
+def _upload_model_async(model_path, project, name):
+    """Upload model asynchronously using bounded thread pool."""
+    _executor.submit(_upload_model, model_path, project, name)
+
+
+def _get_environment_info():
+    """Collect comprehensive environment info using existing ultralytics utilities."""
+    import shutil
+
+    import psutil
+    import torch
+
+    from ultralytics import __version__
+    from ultralytics.utils.torch_utils import get_cpu_info, get_gpu_info
+
+    # Get RAM and disk totals
+    memory = psutil.virtual_memory()
+    disk_usage = shutil.disk_usage("/")
+
+    env = {
+        "ultralyticsVersion": __version__,
+        "hostname": socket.gethostname(),
+        "os": platform.platform(),
+        "environment": ENVIRONMENT,
+        "pythonVersion": PYTHON_VERSION,
+        "pythonExecutable": sys.executable,
+        "cpuCount": os.cpu_count() or 0,
+        "cpu": get_cpu_info(),
+        "command": " ".join(sys.argv),
+        "totalRamGb": round(memory.total / (1 << 30), 1),  # Total RAM in GB
+        "totalDiskGb": round(disk_usage.total / (1 << 30), 1),  # Total disk in GB
+    }
+
+    # Git info using cached GIT singleton (no subprocess calls)
+    try:
+        if GIT.is_repo:
+            if GIT.origin:
+                env["gitRepository"] = GIT.origin
+            if GIT.branch:
+                env["gitBranch"] = GIT.branch
+            if GIT.commit:
+                env["gitCommit"] = GIT.commit[:12]  # Short hash
+    except Exception:
+        pass
+
+    # GPU info
+    try:
+        if torch.cuda.is_available():
+            env["gpuCount"] = torch.cuda.device_count()
+            env["gpuType"] = get_gpu_info(0) if torch.cuda.device_count() > 0 else None
+    except Exception:
+        pass
+
+    return env
+
+
+def _get_project_name(trainer):
+    """Get slugified project and name from trainer args."""
+    raw = str(trainer.args.project)
+    parts = raw.split("/", 1)
+    project = f"{parts[0]}/{slugify(parts[1])}" if len(parts) == 2 else slugify(raw)
+    return project, slugify(str(trainer.args.name or "train"))
+
+
+def on_pretrain_routine_start(trainer):
+    """Initialize Platform logging at training start."""
+    if RANK not in {-1, 0} or not trainer.args.project:
+        return
+
+    # Per-trainer state to isolate concurrent training runs
+    trainer._platform_model_id = None
+    trainer._platform_last_upload = time()
+
+    project, name = _get_project_name(trainer)
+    url = f"https://alpha.ultralytics.com/{project}/{name}"
+    LOGGER.info(f"{PREFIX}Streaming to {url}")
+
+    # Create callback to send console output to Platform
+    def send_console_output(content, line_count, chunk_id):
+        """Send batched console output to Platform webhook."""
+        _send_async(
+            "console_output",
+            {"chunkId": chunk_id, "content": content, "lineCount": line_count},
+            project,
+            name,
+            getattr(trainer, "_platform_model_id", None),
+        )
+
+    # Start console capture with batching (5 lines or 5 seconds)
+    trainer._platform_console_logger = ConsoleLogger(batch_size=5, flush_interval=5.0, on_flush=send_console_output)
+    trainer._platform_console_logger.start_capture()
+
+    # Collect environment info (W&B-style metadata)
+    environment = _get_environment_info()
+
+    # Build trainArgs - callback runs before get_dataset() so args.data is still original (e.g., ul:// URIs)
+    # Note: model_info is sent later in on_fit_epoch_end (epoch 0) when the model is actually loaded
+    train_args = {k: str(v) for k, v in vars(trainer.args).items()}
+
+    # Send synchronously to get modelId for subsequent webhooks
+    response = _send(
+        "training_started",
+        {
+            "trainArgs": train_args,
+            "epochs": trainer.epochs,
+            "device": str(trainer.device),
+            "environment": environment,
+        },
+        project,
+        name,
+    )
+    if response and response.get("modelId"):
+        trainer._platform_model_id = response["modelId"]
+
+
+def on_fit_epoch_end(trainer):
+    """Log training and system metrics at epoch end."""
+    if RANK not in {-1, 0} or not trainer.args.project:
+        return
+
+    project, name = _get_project_name(trainer)
+    metrics = {**trainer.label_loss_items(trainer.tloss, prefix="train"), **trainer.metrics}
+
+    if trainer.optimizer and trainer.optimizer.param_groups:
+        metrics["lr"] = trainer.optimizer.param_groups[0]["lr"]
+
+    # Extract model info at epoch 0 (sent as separate field, not in metrics)
+    model_info = None
+    if trainer.epoch == 0:
+        try:
+            info = model_info_for_loggers(trainer)
+            model_info = {
+                "parameters": info.get("model/parameters", 0),
+                "gflops": info.get("model/GFLOPs", 0),
+                "speedMs": info.get("model/speed_PyTorch(ms)", 0),
+            }
+        except Exception:
+            pass
+
+    # Get system metrics (cache SystemLogger on trainer for efficiency)
+    system = {}
+    try:
+        if not hasattr(trainer, "_platform_system_logger"):
+            trainer._platform_system_logger = SystemLogger()
+        system = trainer._platform_system_logger.get_metrics(rates=True)
+    except Exception:
+        pass
+
+    payload = {
+        "epoch": trainer.epoch,
+        "metrics": metrics,
+        "system": system,
+        "fitness": trainer.fitness,
+        "best_fitness": trainer.best_fitness,
+    }
+    if model_info:
+        payload["modelInfo"] = model_info
+
+    _send_async(
+        "epoch_end",
+        payload,
+        project,
+        name,
+        getattr(trainer, "_platform_model_id", None),
+    )
+
+
+def on_model_save(trainer):
+    """Upload model checkpoint (rate limited to every 15 min)."""
+    if RANK not in {-1, 0} or not trainer.args.project:
+        return
+
+    # Rate limit to every 15 minutes (900 seconds)
+    if time() - getattr(trainer, "_platform_last_upload", 0) < 900:
+        return
+
+    model_path = trainer.best if trainer.best and Path(trainer.best).exists() else trainer.last
+    if not model_path:
+        return
+
+    project, name = _get_project_name(trainer)
+    _upload_model_async(model_path, project, name)
+    trainer._platform_last_upload = time()
+
+
+def on_train_end(trainer):
+    """Log final results, upload best model, and send validation plot data."""
+    if RANK not in {-1, 0} or not trainer.args.project:
+        return
+
+    project, name = _get_project_name(trainer)
+
+    # Stop console capture
+    if hasattr(trainer, "_platform_console_logger") and trainer._platform_console_logger:
+        trainer._platform_console_logger.stop_capture()
+        trainer._platform_console_logger = None
+
+    # Upload best model (blocking to ensure it completes)
+    model_path = None
+    model_size = None
+    if trainer.best and Path(trainer.best).exists():
+        model_size = Path(trainer.best).stat().st_size
+        model_path = _upload_model(trainer.best, project, name)
+
+    # Collect plots from trainer and validator, deduplicating by type
+    plots_by_type = {}
+    for info in getattr(trainer, "plots", {}).values():
+        if info.get("data") and info["data"].get("type"):
+            plots_by_type[info["data"]["type"]] = info["data"]
+    for info in getattr(getattr(trainer, "validator", None), "plots", {}).values():
+        if info.get("data") and info["data"].get("type"):
+            plots_by_type.setdefault(info["data"]["type"], info["data"])  # Don't overwrite trainer plots
+    plots = [_interp_plot(p) for p in plots_by_type.values()]  # Interpolate curves to reduce size
+
+    # Get class names
+    names = getattr(getattr(trainer, "validator", None), "names", None) or (trainer.data or {}).get("names")
+    class_names = list(names.values()) if isinstance(names, dict) else list(names) if names else None
+
+    _send(
+        "training_complete",
+        {
+            "results": {
+                "metrics": {**trainer.metrics, "fitness": trainer.fitness},
+                "bestEpoch": getattr(trainer, "best_epoch", trainer.epoch),
+                "bestFitness": trainer.best_fitness,
+                "modelPath": model_path or (str(trainer.best) if trainer.best else None),
+                "modelSize": model_size,
+            },
+            "classNames": class_names,
+            "plots": plots,
+        },
+        project,
+        name,
+        getattr(trainer, "_platform_model_id", None),
+    )
+    url = f"https://alpha.ultralytics.com/{project}/{name}"
+    LOGGER.info(f"{PREFIX}View results at {url}")
+
+
+callbacks = (
+    {
+        "on_pretrain_routine_start": on_pretrain_routine_start,
+        "on_fit_epoch_end": on_fit_epoch_end,
+        "on_model_save": on_model_save,
+        "on_train_end": on_train_end,
+    }
+    if _api_key
+    else {}
+)

ultralytics/utils/callbacks/raytune.py

@@ -0,0 +1,42 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+from ultralytics.utils import SETTINGS
+
+try:
+    assert SETTINGS["raytune"] is True  # verify integration is enabled
+    import ray
+    from ray import tune
+    from ray.air import session
+
+except (ImportError, AssertionError):
+    tune = None
+
+
+def on_fit_epoch_end(trainer):
+    """Report training metrics to Ray Tune at epoch end when a Ray session is active.
+
+    Captures metrics from the trainer object and sends them to Ray Tune with the current epoch number, enabling
+    hyperparameter tuning optimization. Only executes when within an active Ray Tune session.
+
+    Args:
+        trainer (ultralytics.engine.trainer.BaseTrainer): The Ultralytics trainer object containing metrics and epochs.
+
+    Examples:
+        >>> # Called automatically by the Ultralytics training loop
+        >>> on_fit_epoch_end(trainer)
+
+    References:
+        Ray Tune docs: https://docs.ray.io/en/latest/tune/index.html
+    """
+    if ray.train._internal.session.get_session():  # check if Ray Tune session is active
+        metrics = trainer.metrics
+        session.report({**metrics, **{"epoch": trainer.epoch + 1}})
+
+
+callbacks = (
+    {
+        "on_fit_epoch_end": on_fit_epoch_end,
+    }
+    if tune
+    else {}
+)

ultralytics/utils/callbacks/tensorboard.py

@@ -0,0 +1,123 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+from ultralytics.utils import LOGGER, SETTINGS, TESTS_RUNNING, colorstr, torch_utils
+
+try:
+    assert not TESTS_RUNNING  # do not log pytest
+    assert SETTINGS["tensorboard"] is True  # verify integration is enabled
+    WRITER = None  # TensorBoard SummaryWriter instance
+    PREFIX = colorstr("TensorBoard: ")
+
+    # Imports below only required if TensorBoard enabled
+    from copy import deepcopy
+
+    import torch
+    from torch.utils.tensorboard import SummaryWriter
+
+except (ImportError, AssertionError, TypeError, AttributeError):
+    # TypeError for handling 'Descriptors cannot not be created directly.' protobuf errors in Windows
+    # AttributeError: module 'tensorflow' has no attribute 'io' if 'tensorflow' not installed
+    SummaryWriter = None
+
+
+def _log_scalars(scalars: dict, step: int = 0) -> None:
+    """Log scalar values to TensorBoard.
+
+    Args:
+        scalars (dict): Dictionary of scalar values to log to TensorBoard. Keys are scalar names and values are the
+            corresponding scalar values.
+        step (int): Global step value to record with the scalar values. Used for x-axis in TensorBoard graphs.
+
+    Examples:
+        Log training metrics
+        >>> metrics = {"loss": 0.5, "accuracy": 0.95}
+        >>> _log_scalars(metrics, step=100)
+    """
+    if WRITER:
+        for k, v in scalars.items():
+            WRITER.add_scalar(k, v, step)
+
+
+def _log_tensorboard_graph(trainer) -> None:
+    """Log model graph to TensorBoard.
+
+    This function attempts to visualize the model architecture in TensorBoard by tracing the model with a dummy input
+    tensor. It first tries a simple method suitable for YOLO models, and if that fails, falls back to a more complex
+    approach for models like RTDETR that may require special handling.
+
+    Args:
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer object containing the model to visualize. Must
+            have attributes model and args with imgsz.
+
+    Notes:
+        This function requires TensorBoard integration to be enabled and the global WRITER to be initialized.
+        It handles potential warnings from the PyTorch JIT tracer and attempts to gracefully handle different
+        model architectures.
+    """
+    # Input image
+    imgsz = trainer.args.imgsz
+    imgsz = (imgsz, imgsz) if isinstance(imgsz, int) else imgsz
+    p = next(trainer.model.parameters())  # for device, type
+    im = torch.zeros((1, 3, *imgsz), device=p.device, dtype=p.dtype)  # input image (must be zeros, not empty)
+
+    # Try simple method first (YOLO)
+    try:
+        trainer.model.eval()  # place in .eval() mode to avoid BatchNorm statistics changes
+        WRITER.add_graph(torch.jit.trace(torch_utils.unwrap_model(trainer.model), im, strict=False), [])
+        LOGGER.info(f"{PREFIX}model graph visualization added ✅")
+        return
+    except Exception as e1:
+        # Fallback to TorchScript export steps (RTDETR)
+        try:
+            model = deepcopy(torch_utils.unwrap_model(trainer.model))
+            model.eval()
+            model = model.fuse(verbose=False)
+            for m in model.modules():
+                if hasattr(m, "export"):  # Detect, RTDETRDecoder (Segment and Pose use Detect base class)
+                    m.export = True
+                    m.format = "torchscript"
+            model(im)  # dry run
+            WRITER.add_graph(torch.jit.trace(model, im, strict=False), [])
+            LOGGER.info(f"{PREFIX}model graph visualization added ✅")
+        except Exception as e2:
+            LOGGER.warning(f"{PREFIX}TensorBoard graph visualization failure: {e1} -> {e2}")
+
+
+def on_pretrain_routine_start(trainer) -> None:
+    """Initialize TensorBoard logging with SummaryWriter."""
+    if SummaryWriter:
+        try:
+            global WRITER
+            WRITER = SummaryWriter(str(trainer.save_dir))
+            LOGGER.info(f"{PREFIX}Start with 'tensorboard --logdir {trainer.save_dir}', view at http://localhost:6006/")
+        except Exception as e:
+            LOGGER.warning(f"{PREFIX}TensorBoard not initialized correctly, not logging this run. {e}")
+
+
+def on_train_start(trainer) -> None:
+    """Log TensorBoard graph."""
+    if WRITER:
+        _log_tensorboard_graph(trainer)
+
+
+def on_train_epoch_end(trainer) -> None:
+    """Log scalar statistics at the end of a training epoch."""
+    _log_scalars(trainer.label_loss_items(trainer.tloss, prefix="train"), trainer.epoch + 1)
+    _log_scalars(trainer.lr, trainer.epoch + 1)
+
+
+def on_fit_epoch_end(trainer) -> None:
+    """Log epoch metrics at end of training epoch."""
+    _log_scalars(trainer.metrics, trainer.epoch + 1)
+
+
+callbacks = (
+    {
+        "on_pretrain_routine_start": on_pretrain_routine_start,
+        "on_train_start": on_train_start,
+        "on_fit_epoch_end": on_fit_epoch_end,
+        "on_train_epoch_end": on_train_epoch_end,
+    }
+    if SummaryWriter
+    else {}
+)