feat: Allow tuner warm start and custom constraint objective value (#235)

Exposes `OptunaSearch`'s `points_to_evaluate` for warm-starting the
tuner, extends `ConstraintError` to allow specifying a custom fallback
objective value when a constraint is breached, and updates the
documentation accordingly.

# Summary

Three related tuner enhancements:
1. **Warm start**: Pass initial parameter guesses to `OptunaSearch` via
`points_to_evaluate` — useful in large or heavily constrained search
spaces where finding a feasible solution from scratch is slow.
2. **Custom constraint penalty**: `ConstraintError` now accepts an
`objective_value` keyword arg, giving users control over the fallback
metric value on constraint violation.
3. **Documentation**: The "Tuning a process" tutorial tip box on
`ConstraintError` has been updated to mention the custom objective value
feature.

# Changes

- **`OptunaSpec`** (`plugboard-schemas/plugboard_schemas/tune.py`):
Added `points_to_evaluate: list[dict[str, Any]] | None = None`, passed
through to `OptunaSearch` automatically.

- **`ConstraintError`** (`plugboard/exceptions/__init__.py`): Added
`objective_value: float | None = None` keyword argument — fully backward
compatible.

- **`Tuner._build_objective`** (`plugboard/tune/tune.py`): When catching
`ConstraintError`, uses `objective_value` from the first exception if
set; falls back to ±∞ otherwise.

- **`docs/examples/tutorials/tuning-a-process.md`**: Expanded the
`ConstraintError` tip box to document the `objective_value` argument
with a code example.

```python
# Warm start
tuner = Tuner(
    ...,
    algorithm=OptunaSpec(
        points_to_evaluate=[{"component.model.arg.lr": 0.01, "component.model.arg.depth": 4}]
    ),
)

# Custom constraint penalty instead of -inf
class MyComponent(Component):
    async def step(self) -> None:
        if self.value > threshold:
            raise ConstraintError("Exceeded threshold", objective_value=0.0)
        ...
```

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>feat: Allow tuner to accept an initial guess to give it a
'warm start'</issue_title>
> <issue_description>### Summary
> 
> The `OptunaSearch` algo supports a `points_to_evaluate` argument,
which can be populated with an initial guess. This is particularly
useful when exploring large and heavily constrained search spaces, where
it otherwise takes a long time for the tuner to find a feasible
solution.
> 
> Feature request to to expose this argument, and update docs where
necessary.
> 
> ### Example
> 
> _No response_
> 
> ### Alternatives
> 
> _No response_</issue_description>
> 
> <agent_instructions>Also implement a mechanism to set the objective to
a value other than plus or minus infinity when a constraint is breached.
This could be done by extending the ConstraintError class, allowing the
user to pass in a value that they would like to give the objective. Make
sure to preserve backwards compatibility with the current t behaviour.
</agent_instructions>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #231

<!-- START COPILOT CODING AGENT TIPS -->
---

⌨️ Start Copilot coding agent tasks without leaving your editor —
available in [VS Code](https://gh.io/cca-vs-code-docs), [Visual
Studio](https://gh.io/cca-visual-studio-docs), [JetBrains
IDEs](https://gh.io/cca-jetbrains-docs) and
[Eclipse](https://gh.io/cca-eclipse-docs).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: toby-coleman <13170610+toby-coleman@users.noreply.github.com>
Co-authored-by: Toby Coleman <toby@tobycoleman.com>

Author: Copilot

docs/examples/tutorials/tuning-a-process.md

@@ -61,6 +61,12 @@ Running this code will execute an optimisation job and print out information on
 !!! tip
     You can impose arbitary constraints on variables within a `Process`. In your `step` method you can raise a [`ConstraintError`][plugboard.exceptions.ConstraintError] to indicate to the `Tuner` that a constraint has been breached. This will cause the trial to be stopped, and the optimisation will continue trying to find parameters that don't cause the constraint violation.
 
+    By default, the objective is set to ±∞ (depending on the optimisation direction) when a constraint is breached. You can override this by passing an `objective_value` to `ConstraintError`:
+    ```python
+    raise ConstraintError("Value too high", objective_value=0.0)
+    ```
+    This is useful when you want violated trials to receive a specific penalty value rather than infinity.
+
 !!! tip
     You can optimise over process parameters if you have them in your model. Set `object_type="process"` and `field_type="parameter"` when specifying your tunable parameter.
 

plugboard-schemas/plugboard_schemas/tune.py

@@ -23,12 +23,16 @@ class OptunaSpec(PlugboardBaseModel):
             the `ProcessSpec` will be passed to it.
         study_name: Optional; The name of the study.
         storage: Optional; The storage URI to save the optimisation results to.
+        points_to_evaluate: Optional; A list of initial parameter configurations to evaluate
+            first. Each entry is a dict mapping parameter full names to values. Useful for
+            providing a warm start when exploring large or heavily constrained search spaces.
     """
 
     type: _t.Literal["ray.tune.search.optuna.OptunaSearch"] = "ray.tune.search.optuna.OptunaSearch"
     space: str | None = None
     study_name: str | None = None
     storage: str | None = None
+    points_to_evaluate: list[dict[str, _t.Any]] | None = None
 
 
 class BaseFieldSpec(PlugboardBaseModel, ABC):

plugboard/exceptions/__init__.py

@@ -98,9 +98,18 @@ class ValidationError(Exception):
 
 
 class ConstraintError(Exception):
-    """Raised when a constraint is violated."""
-
-    pass
+    """Raised when a constraint is violated.
+
+    Args:
+        *args: Standard exception arguments.
+        objective_value: Optional; A custom value to assign to the objective when this constraint
+            is violated. If not provided, the tuner will assign plus or minus infinity depending
+            on the optimisation direction.
+    """
+
+    def __init__(self, *args: object, objective_value: float | None = None) -> None:
+        super().__init__(*args)
+        self.objective_value = objective_value
 
 
 class ProcessStatusError(Exception):

plugboard/tune/tune.py

@@ -289,14 +289,19 @@ def fn(config: dict[str, _t.Any]) -> dict[str, _t.Any]:  # pragma: no cover
                 result = {
                     obj.full_name: self._get_objective(process, obj) for obj in self._objective
                 }
-            except* ConstraintError as e:
+            except* ConstraintError as eg:
                 modes = self._mode if isinstance(self._mode, list) else [self._mode]
                 self._logger.warning(
                     "Constraint violated during optimisation, stopping early",
-                    constraint_error=str(e),
+                    constraint_error=str(eg),
                 )
+                first_exc = _t.cast(ConstraintError, eg.exceptions[0]) if eg.exceptions else None
                 result = {
-                    obj.full_name: math.inf if mode == "min" else -math.inf
+                    obj.full_name: (
+                        first_exc.objective_value
+                        if first_exc is not None and first_exc.objective_value is not None
+                        else (math.inf if mode == "min" else -math.inf)
+                    )
                     for obj, mode in zip(self._objective, modes)
                 }
 

tests/integration/test_tuner.py

@@ -34,6 +34,16 @@ async def step(self) -> None:
         await super().step()
 
 
+class ConstrainedBWithObjectiveValue(B):
+    """Component with a constraint that provides a custom objective value."""
+
+    async def step(self) -> None:
+        """Override step to apply a constraint with a custom objective value."""
+        if self.in_1 > 10:
+            raise ConstraintError("Input must not be greater than 10", objective_value=0.0)
+        await super().step()
+
+
 class DynamicListComponent(ComponentTestHelper):
     """Component with a dynamic list parameter for tuning."""
 
@@ -294,6 +304,55 @@ async def test_tune_with_constraint(config: dict, ray_ctx: None) -> None:
     )
 
 
+@pytest.mark.tuner
+@pytest.mark.asyncio
+async def test_tune_with_constraint_objective_value(config: dict, ray_ctx: None) -> None:
+    """Tests that a ConstraintError with objective_value uses that value instead of infinity."""
+    spec = ConfigSpec.model_validate(config)
+    process_spec = spec.plugboard.process
+    # Replace component B with a version that provides a custom objective value on constraint
+    process_spec.args.components[
+        1
+    ].type = "tests.integration.test_tuner.ConstrainedBWithObjectiveValue"
+    tuner = Tuner(
+        objective=ObjectiveSpec(
+            object_type="component",
+            object_name="c",
+            field_type="field",
+            field_name="in_1",
+        ),
+        parameters=[
+            IntParameterSpec(
+                object_type="component",
+                object_name="a",
+                field_type="arg",
+                field_name="iters",
+                lower=5,
+                upper=15,
+            )
+        ],
+        num_samples=12,
+        mode="max",
+        max_concurrent=2,
+        algorithm=OptunaSpec(),
+    )
+    best_result = tuner.run(
+        spec=process_spec,
+    )
+    result = tuner.result_grid
+    # There must be no failed trials
+    assert not any(t.error for t in result)
+    # Optimum must be at or below 10 (constraint threshold)
+    assert best_result.metrics["component.c.field.in_1"] <= 10
+    # When constraint is violated the custom objective_value (0.0) must be used, not -inf
+    # The constraint raises when in_1 > 10; in_1 = iters - 1, so iters > 11 violates it
+    assert all(
+        t.metrics["component.c.field.in_1"] == 0.0
+        for t in result
+        if t.config["component.a.arg.iters"] > 11
+    )
+
+
 @pytest.mark.tuner
 @pytest.mark.asyncio
 @pytest.mark.parametrize("space_func", [custom_space, custom_space_with_process_spec])

tests/unit/test_tuner.py

@@ -8,6 +8,7 @@
 import pytest
 from ray.tune.search.optuna import OptunaSearch
 
+from plugboard.exceptions import ConstraintError
 from plugboard.schemas import (
     CategoricalParameterSpec,
     ConfigSpec,
@@ -131,3 +132,58 @@ def test_optuna_storage_uri_conversion(temp_dir: str) -> None:
         tuner.run(spec=MagicMock())
         passed_alg = mock_tuner_cls.call_args.kwargs["tune_config"].search_alg
         assert isinstance(passed_alg, OptunaSearch)
+
+
+def test_optuna_points_to_evaluate(config: dict) -> None:
+    """Test that points_to_evaluate is passed through to the OptunaSearch algorithm."""
+    spec = ConfigSpec.model_validate(config)
+    process_spec = spec.plugboard.process
+    points = [{"component.a.arg.x": 7, "component.a.arg.y": 0.3}]
+    tuner = Tuner(
+        objective=ObjectiveSpec(
+            object_type="component",
+            object_name="c",
+            field_type="field",
+            field_name="in_1",
+        ),
+        parameters=[
+            IntParameterSpec(
+                object_type="component",
+                object_name="a",
+                field_type="arg",
+                field_name="x",
+                lower=6,
+                upper=8,
+            ),
+            FloatParameterSpec(
+                object_type="component",
+                object_name="a",
+                field_type="arg",
+                field_name="y",
+                lower=0.1,
+                upper=0.5,
+            ),
+        ],
+        num_samples=3,
+        mode="max",
+        algorithm=OptunaSpec(points_to_evaluate=points),
+    )
+    with patch("ray.tune.Tuner") as mock_tuner_cls:
+        tuner.run(spec=process_spec)
+        search_alg = mock_tuner_cls.call_args.kwargs["tune_config"].search_alg
+        # The underlying OptunaSearch must have received the points_to_evaluate
+        assert isinstance(search_alg, OptunaSearch)
+        assert search_alg._points_to_evaluate == points
+
+
+def test_constraint_error_objective_value() -> None:
+    """Test that ConstraintError stores an optional objective_value."""
+    # Default (no objective_value): backward compatible usage
+    err = ConstraintError("constraint violated")
+    assert err.objective_value is None
+    assert str(err) == "constraint violated"
+
+    # With objective_value keyword argument
+    err_with_value = ConstraintError("constraint violated", objective_value=5.0)
+    assert err_with_value.objective_value == 5.0
+    assert str(err_with_value) == "constraint violated"