From f36f46b6bfc70e76b6fb798e679f2edd4079e509 Mon Sep 17 00:00:00 2001
From: Adnan <adnan@ad-group.com.au>
Date: Mon, 8 Jun 2026 20:24:29 +0600
Subject: [PATCH] feat(predictions): add warnings for callback_url and batch
 usage in image predictions

This update introduces a new private function `_warn_callback_requires_batch` to issue warnings when the `callback_url` and `batch` parameters are used incorrectly in image predictions. The function checks if `batch` is set to `True` for image predictions, which is unsupported, and warns the user accordingly. It also warns if `callback_url` is provided, as it is not applicable for synchronous image predictions. The warnings are integrated into the `ImagePredictions` and `FilePredictions` classes to enhance user experience and prevent confusion.

### Changes
- Added `_warn_callback_requires_batch` function to handle warning logic.
- Integrated warning calls in `ImagePredictions` and `FilePredictions` methods.
---
 vlmrun/client/predictions.py | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/vlmrun/client/predictions.py b/vlmrun/client/predictions.py
index 06b577f..22ce7d2 100644
--- a/vlmrun/client/predictions.py
+++ b/vlmrun/client/predictions.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 import json
+import warnings
 from pathlib import Path
 from typing import List, Optional, Union
 from PIL import Image
@@ -42,6 +43,37 @@ def get_response_model(
     return schema_response.response_model
 
 
+def _warn_callback_requires_batch(
+    callback_url: Optional[str], batch: bool, is_image: bool = False
+) -> None:
+    if is_image:
+        if batch:
+            warnings.warn(
+                "`batch=True` is not supported for image predictions. "
+                "Image predictions are processed synchronously; the `batch` flag will be ignored by the server.",
+                UserWarning,
+                stacklevel=3,
+            )
+        if callback_url:
+            warnings.warn(
+                "`callback_url` is not supported for image predictions. "
+                "Image predictions are synchronous and return the result directly; "
+                "the callback URL will be ignored.",
+                UserWarning,
+                stacklevel=3,
+            )
+        return
+
+    if callback_url and not batch:
+        warnings.warn(
+            "`callback_url` will be ignored because `batch=False`. "
+            "Webhook callbacks are only delivered for batched (async) predictions. "
+            "Set `batch=True` to receive callbacks.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+
 class SchemaCastMixin:
     """Mixin class to handle schema casting for predictions."""
 
@@ -230,6 +262,7 @@ def execute(
         Raises:
             ValueError: If neither images nor urls are provided, or if both are provided
         """
+        _warn_callback_requires_batch(callback_url, batch, is_image=True)
         images_data = self._handle_images_or_urls(images, urls)
         additional_kwargs = {}
         if config:
@@ -287,6 +320,7 @@ def generate(
         Raises:
             ValueError: If neither images nor urls are provided, or if both are provided
         """
+        _warn_callback_requires_batch(callback_url, batch, is_image=True)
         # Input validation
         if not images and not urls:
             raise ValueError("Either `images` or `urls` must be provided")
@@ -448,6 +482,7 @@ def generate(
             Returns:
                 PredictionResponse: Prediction response
             """
+            _warn_callback_requires_batch(callback_url, batch)
             is_url, file_or_url = self._handle_file_or_url(file, url)
 
             additional_kwargs = {}
@@ -517,6 +552,7 @@ def execute(
             Returns:
                 PredictionResponse: Prediction response
             """
+            _warn_callback_requires_batch(callback_url, batch)
             is_url, file_or_url = self._handle_file_or_url(file, url)
 
             additional_kwargs = {}