unify unpacking of obj. func. result into one place

Author: SimonBlanke

src/gradient_free_optimizers/_objective_adapter.py

@@ -1,8 +1,8 @@
-from ._result import Result
+from ._result import Result, unpack_objective_result
 
 
 class ObjectiveAdapter:
-    """Maps *pos* → (score, metrics, params)."""
+    """Maps *pos* → (Result, params)."""
 
     def __init__(self, conv, objective):
         self._conv = conv
@@ -13,11 +13,7 @@ def _call_objective(self, pos):
         params = self._conv.value2para(self._conv.position2value(pos))
         out = self._objective(params)
 
-        if isinstance(out, tuple):
-            score, metrics = out
-        else:
-            score, metrics = float(out), {}
-
+        score, metrics = unpack_objective_result(out)
         result = Result(score, metrics)
 
         return result, params

src/gradient_free_optimizers/_result.py

@@ -1,7 +1,67 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 
 @dataclass
 class Result:
+    """Internal result container used throughout the search pipeline."""
+
     score: float
     metrics: dict
+
+
+@dataclass
+class ObjectiveResult:
+    """Explicit return type for objective functions.
+
+    Avoids the ambiguity of bare tuples, which becomes critical when the
+    return value needs to carry structured data alongside the score (e.g.,
+    custom metrics). A plain ``(float, dict)`` tuple works today but
+    collides with future multi-objective returns like ``(float, float)``.
+
+    Parameters
+    ----------
+    score : float
+        The objective function score.
+    metrics : dict, optional
+        Custom metrics to record alongside the score.
+
+    Examples
+    --------
+    >>> def objective(params):
+    ...     loss = params["x"] ** 2
+    ...     return ObjectiveResult(score=-loss, metrics={"raw_loss": loss})
+    """
+
+    score: float
+    metrics: dict = field(default_factory=dict)
+
+
+def unpack_objective_result(raw) -> tuple[float, dict]:
+    """Extract score and metrics from an objective function's return value.
+
+    Single entry point for parsing objective output. All code paths that
+    receive raw objective returns (serial adapter, distributed unpacking,
+    minimization wrapper) should call this instead of doing their own
+    isinstance checks.
+
+    Supported return conventions (checked in this order):
+
+    1. ``ObjectiveResult`` instance (preferred, unambiguous)
+    2. ``(float, dict)`` tuple (legacy convention)
+    3. ``float`` (score only, no metrics)
+
+    Parameters
+    ----------
+    raw : float or tuple or ObjectiveResult
+        Raw return value from an objective function.
+
+    Returns
+    -------
+    tuple[float, dict]
+        The (score, metrics) pair.
+    """
+    if isinstance(raw, ObjectiveResult):
+        return raw.score, raw.metrics
+    if isinstance(raw, tuple):
+        return raw[0], raw[1]
+    return float(raw), {}

src/gradient_free_optimizers/search.py

@@ -17,7 +17,7 @@
 from ._objective_adapter import ObjectiveAdapter
 from ._print_info import print_summary
 from ._progress_bar import ProgressBarLVL0, ProgressBarLVL1
-from ._result import Result
+from ._result import Result, unpack_objective_result
 from ._results_manager import ResultsManager
 from ._search_statistics import SearchStatistics
 from ._stopping_conditions import OptimizationStopper
@@ -190,13 +190,10 @@ def _iteration_batch(self, batch_size):
     def _unpack_result(raw):
         """Separate a worker return value into score and metrics.
 
-        Objective functions may return a plain float or a (float, dict) tuple.
-        The backends pass through whatever the function returns, so we unpack
-        here at the boundary between worker results and the search loop.
+        Delegates to the centralized unpack_objective_result() which handles
+        ObjectiveResult, (float, dict) tuples, and plain floats.
         """
-        if isinstance(raw, tuple):
-            return raw[0], raw[1]
-        return raw, {}
+        return unpack_objective_result(raw)
 
     def _track_evaluation(self, pos, score, eval_time=0, iter_time=0, metrics=None):
         """Record a single evaluation result across all tracking systems."""
@@ -737,9 +734,8 @@ def _init_search(
 
             def _negate(params):
                 out = _obj(params)
-                if isinstance(out, tuple):
-                    return -out[0], out[1]
-                return -out
+                score, metrics = unpack_objective_result(out)
+                return (-score, metrics)
 
             self.objective_function = _negate
         else: