agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/integrations/botorch/finite_qlognehvi.py

@@ -0,0 +1,190 @@
+"""Numerically stable qNEHVI over a sealed finite candidate pool."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import botorch
+import gpytorch
+import torch
+from botorch.acquisition.multi_objective.logei import (
+    qLogNoisyExpectedHypervolumeImprovement,
+)
+from botorch.fit import fit_gpytorch_mll
+from botorch.models import SingleTaskGP
+from botorch.models.transforms.outcome import Standardize
+from botorch.optim import optimize_acqf_discrete
+from botorch.sampling.normal import SobolQMCNormalSampler
+from gpytorch.mlls import ExactMarginalLogLikelihood
+
+from agent_evolve.ports.finite_acquisition import (
+    FiniteAcquisitionDecision,
+    FiniteAcquisitionRequest,
+    FiniteAcquisitionSelection,
+)
+from agent_evolve.integrations.botorch.finite_qlognehvi_identity import (
+    POLICY_DEFINITION_SHA256,
+    POLICY_ID,
+    POLICY_VERSION,
+)
+
+
+def _training_tensors(
+    request: FiniteAcquisitionRequest,
+    *,
+    dtype: torch.dtype,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    train_x = torch.tensor(
+        [value.features for value in request.observations],
+        dtype=dtype,
+        device=torch.device("cpu"),
+    )
+    axis_by_metric = {value.metric_id: value for value in request.objectives}
+    train_y = torch.tensor(
+        [
+            [
+                axis_by_metric[metric_id].maximize_value(raw_value)
+                for metric_id, raw_value in observation.objectives
+            ]
+            for observation in request.observations
+        ],
+        dtype=dtype,
+        device=train_x.device,
+    )
+    # Current benchmark evaluators are deterministic but numerically finite.
+    # A small declared observation variance avoids treating floating-point
+    # objective resolution as mathematical exactness.
+    train_yvar = torch.full_like(train_y, 1.0e-6)
+    return train_x, train_y, train_yvar
+
+
+@dataclass(frozen=True, slots=True)
+class BotorchQLogNehviFiniteAcquisition:
+    """Fit one past-only GP and select an exact unique finite batch."""
+
+    mc_samples: int = 128
+    maximum_optimizer_batch_size: int = 2048
+    policy_id: str = POLICY_ID
+    policy_version: int = POLICY_VERSION
+    definition_sha256: str = POLICY_DEFINITION_SHA256
+
+    def __post_init__(self) -> None:
+        if type(self.mc_samples) is not int or self.mc_samples < 16:
+            raise ValueError("mc_samples must be an exact integer of at least 16")
+        if (
+            type(self.maximum_optimizer_batch_size) is not int
+            or self.maximum_optimizer_batch_size < 1
+        ):
+            raise ValueError("maximum_optimizer_batch_size must be positive")
+        if (
+            self.policy_id != POLICY_ID
+            or self.policy_version != POLICY_VERSION
+            or self.definition_sha256 != POLICY_DEFINITION_SHA256
+        ):
+            raise ValueError("qLogNEHVI policy identity drifted")
+
+    def select(self, request: FiniteAcquisitionRequest) -> FiniteAcquisitionDecision:
+        self.__post_init__()
+        if type(request) is not FiniteAcquisitionRequest:
+            raise TypeError("request must be an exact FiniteAcquisitionRequest")
+        request.__post_init__()
+        dtype = torch.double
+        train_x, train_y, train_yvar = _training_tensors(request, dtype=dtype)
+        model = SingleTaskGP(
+            train_X=train_x,
+            train_Y=train_y,
+            train_Yvar=train_yvar,
+            outcome_transform=Standardize(m=len(request.objectives)),
+        )
+        mll = ExactMarginalLogLikelihood(model.likelihood, model)
+        fit_gpytorch_mll(mll)
+        model.eval()
+        sampler = SobolQMCNormalSampler(
+            sample_shape=torch.Size([self.mc_samples]),
+            seed=request.seed,
+        )
+        acquisition = qLogNoisyExpectedHypervolumeImprovement(
+            model=model,
+            ref_point=torch.zeros(
+                len(request.objectives),
+                dtype=dtype,
+                device=train_x.device,
+            ),
+            X_baseline=train_x,
+            sampler=sampler,
+            prune_baseline=True,
+            cache_root=True,
+        )
+        choices = torch.tensor(
+            [value.features for value in request.candidates],
+            dtype=dtype,
+            device=train_x.device,
+        )
+        selected_x, acquisition_values = optimize_acqf_discrete(
+            acq_function=acquisition,
+            q=request.batch_size,
+            choices=choices,
+            max_batch_size=self.maximum_optimizer_batch_size,
+            unique=True,
+            return_acq_values=True,
+        )
+        candidate_by_features = {
+            value.features: value for value in request.candidates
+        }
+        selected_rows = []
+        flat_values = acquisition_values.detach().cpu().reshape(-1).tolist()
+        if len(flat_values) == 1 and request.batch_size > 1:
+            flat_values = flat_values * request.batch_size
+        if len(flat_values) != request.batch_size:
+            raise RuntimeError("BoTorch returned an unexpected acquisition shape")
+        for feature_tensor, acquisition_value in zip(
+            selected_x.detach().cpu(),
+            flat_values,
+            strict=True,
+        ):
+            feature_key = tuple(float(value) for value in feature_tensor.tolist())
+            candidate = candidate_by_features.get(feature_key)
+            if candidate is None:
+                raise RuntimeError("BoTorch selected a row outside the finite pool")
+            value = float(acquisition_value)
+            if not math.isfinite(value):
+                raise RuntimeError("BoTorch returned a non-finite acquisition value")
+            selected_rows.append(
+                FiniteAcquisitionSelection(
+                    candidate_id=candidate.candidate_id,
+                    configuration_sha256=candidate.configuration_sha256,
+                    acquisition_value=value,
+                )
+            )
+        if len({value.candidate_id for value in selected_rows}) != request.batch_size:
+            raise RuntimeError("BoTorch did not return a unique exact batch")
+        return FiniteAcquisitionDecision(
+            request_sha256=request.request_sha256,
+            policy_id=self.policy_id,
+            policy_version=self.policy_version,
+            policy_definition_sha256=self.definition_sha256,
+            selected=tuple(selected_rows),
+            diagnostics=tuple(
+                sorted(
+                    (
+                        ("botorch_version", str(botorch.__version__)),
+                        ("candidate_pool_size", str(len(request.candidates))),
+                        ("feature_dimension", str(train_x.shape[-1])),
+                        ("gpytorch_version", str(gpytorch.__version__)),
+                        ("mc_samples", str(self.mc_samples)),
+                        ("objective_count", str(train_y.shape[-1])),
+                        ("observation_count", str(train_x.shape[-2])),
+                        ("torch_version", str(torch.__version__)),
+                    )
+                )
+            ),
+        )
+
+
+__all__ = [
+    "BotorchQLogNehviFiniteAcquisition",
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+]

agent_evolve/integrations/botorch/finite_qlognehvi_batch.py

@@ -0,0 +1,155 @@
+"""Common-realization qLogNEHVI values for sealed finite slates."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import botorch
+import gpytorch
+import torch
+from botorch.acquisition.multi_objective.logei import (
+    qLogNoisyExpectedHypervolumeImprovement,
+)
+from botorch.fit import fit_gpytorch_mll
+from botorch.models import SingleTaskGP
+from botorch.models.transforms.outcome import Standardize
+from botorch.sampling.normal import SobolQMCNormalSampler
+from gpytorch.mlls import ExactMarginalLogLikelihood
+
+from agent_evolve.integrations.botorch.finite_qlognehvi import _training_tensors
+from agent_evolve.integrations.botorch.finite_qlognehvi_batch_identity import (
+    POLICY_DEFINITION_SHA256,
+    POLICY_ID,
+    POLICY_VERSION,
+)
+from agent_evolve.ports.finite_acquisition_batch import (
+    FiniteAcquisitionBatchScoreDecision,
+    FiniteAcquisitionBatchScoreRequest,
+    FiniteAcquisitionSlateScore,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BotorchQLogNehviFiniteBatchScorePolicy:
+    """Fit once and score every supplied slate under one acquisition object."""
+
+    mc_samples: int = 128
+    maximum_score_batch_size: int = 512
+    policy_id: str = POLICY_ID
+    policy_version: int = POLICY_VERSION
+    definition_sha256: str = POLICY_DEFINITION_SHA256
+
+    def __post_init__(self) -> None:
+        if type(self.mc_samples) is not int or self.mc_samples < 16:
+            raise ValueError("mc_samples must be an exact integer of at least 16")
+        if (
+            type(self.maximum_score_batch_size) is not int
+            or self.maximum_score_batch_size < 1
+        ):
+            raise ValueError("maximum_score_batch_size must be positive")
+        if (
+            self.policy_id != POLICY_ID
+            or self.policy_version != POLICY_VERSION
+            or self.definition_sha256 != POLICY_DEFINITION_SHA256
+        ):
+            raise ValueError("qLogNEHVI batch-score policy identity drifted")
+
+    def score(
+        self,
+        request: FiniteAcquisitionBatchScoreRequest,
+    ) -> FiniteAcquisitionBatchScoreDecision:
+        self.__post_init__()
+        if type(request) is not FiniteAcquisitionBatchScoreRequest:
+            raise TypeError("request must be exact")
+        request.__post_init__()
+        dtype = torch.double
+        # GP fitting may use torch randomness internally.  The worker process is
+        # isolated, but explicitly seeding here also makes direct invocations
+        # replayable and keeps every compared slate on one fitted realization.
+        torch.manual_seed(request.seed)
+        train_x, train_y, train_yvar = _training_tensors(request, dtype=dtype)
+        model = SingleTaskGP(
+            train_X=train_x,
+            train_Y=train_y,
+            train_Yvar=train_yvar,
+            outcome_transform=Standardize(m=len(request.objectives)),
+        )
+        mll = ExactMarginalLogLikelihood(model.likelihood, model)
+        fit_gpytorch_mll(mll)
+        model.eval()
+        sampler = SobolQMCNormalSampler(
+            sample_shape=torch.Size([self.mc_samples]),
+            seed=request.seed,
+        )
+        acquisition = qLogNoisyExpectedHypervolumeImprovement(
+            model=model,
+            ref_point=torch.zeros(
+                len(request.objectives),
+                dtype=dtype,
+                device=train_x.device,
+            ),
+            X_baseline=train_x,
+            sampler=sampler,
+            prune_baseline=True,
+            cache_root=True,
+        )
+        candidate_by_id = {value.candidate_id: value for value in request.candidates}
+        scores: list[FiniteAcquisitionSlateScore] = []
+        for start in range(0, len(request.slates), self.maximum_score_batch_size):
+            slate_chunk = request.slates[
+                start : start + self.maximum_score_batch_size
+            ]
+            rows = torch.tensor(
+                [
+                    [candidate_by_id[value].features for value in slate.candidate_ids]
+                    for slate in slate_chunk
+                ],
+                dtype=dtype,
+                device=train_x.device,
+            )
+            with torch.no_grad():
+                values = acquisition(rows).detach().cpu().reshape(-1).tolist()
+            if len(values) != len(slate_chunk):
+                raise RuntimeError("BoTorch returned an unexpected slate-score shape")
+            for slate, raw in zip(slate_chunk, values, strict=True):
+                value = float(raw)
+                if not math.isfinite(value):
+                    raise RuntimeError("BoTorch returned a non-finite slate score")
+                scores.append(
+                    FiniteAcquisitionSlateScore(
+                        slate=slate,
+                        log_acquisition_value=value,
+                    )
+                )
+        return FiniteAcquisitionBatchScoreDecision(
+            request_sha256=request.request_sha256,
+            policy_id=self.policy_id,
+            policy_version=self.policy_version,
+            policy_definition_sha256=self.definition_sha256,
+            scores=tuple(scores),
+            diagnostics=tuple(
+                sorted(
+                    (
+                        ("botorch_version", str(botorch.__version__)),
+                        ("candidate_count", str(len(request.candidates))),
+                        ("feature_dimension", str(train_x.shape[-1])),
+                        ("gpytorch_version", str(gpytorch.__version__)),
+                        ("mc_samples", str(self.mc_samples)),
+                        ("objective_count", str(train_y.shape[-1])),
+                        ("observation_count", str(train_x.shape[-2])),
+                        ("slate_count", str(len(request.slates))),
+                        ("slate_size", str(request.batch_size)),
+                        ("torch_version", str(torch.__version__)),
+                    )
+                )
+            ),
+        )
+
+
+__all__ = [
+    "BotorchQLogNehviFiniteBatchScorePolicy",
+    "POLICY_DEFINITION_SHA256",
+    "POLICY_ID",
+    "POLICY_VERSION",
+]

agent_evolve/integrations/botorch/finite_qlognehvi_batch_identity.py

@@ -0,0 +1,20 @@
+"""Dependency-free identity of the direct qLogNEHVI batch scorer."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+POLICY_ID = "botorch_finite_qlognehvi_batch_score"
+POLICY_VERSION = 1
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:botorch-finite-qlognehvi-batch-score:v1;"
+    b"model=independent-output-singletask-gp-standardized;"
+    b"noise=declared-1e-6;acquisition=qlognehvi;"
+    b"reference=normalized-zero-vector;sampler=sobol-common-seed;"
+    b"input=sealed-equal-cardinality-slates;selection=false;"
+    b"all-slates-scored-under-one-fit-and-sampler=true;cpu-double=true"
+).hexdigest()
+
+
+__all__ = ["POLICY_DEFINITION_SHA256", "POLICY_ID", "POLICY_VERSION"]

agent_evolve/integrations/botorch/finite_qlognehvi_batch_worker.py

@@ -0,0 +1,55 @@
+"""Isolated JSON worker for common-realization qLogNEHVI slate scoring."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from agent_evolve.integrations.botorch.finite_qlognehvi_batch import (
+    BotorchQLogNehviFiniteBatchScorePolicy,
+)
+from agent_evolve.ports.finite_acquisition_batch_json import (
+    finite_acquisition_batch_score_request_from_record,
+)
+
+
+WORKER_SCHEMA_VERSION = 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--request", required=True, type=Path)
+    parser.add_argument("--response", required=True, type=Path)
+    parser.add_argument("--mc-samples", required=True, type=int)
+    parser.add_argument("--maximum-score-batch-size", required=True, type=int)
+    return parser
+
+
+def main() -> None:
+    arguments = _parser().parse_args()
+    payload = json.loads(arguments.request.read_text(encoding="ascii"))
+    request = finite_acquisition_batch_score_request_from_record(payload)
+    policy = BotorchQLogNehviFiniteBatchScorePolicy(
+        mc_samples=arguments.mc_samples,
+        maximum_score_batch_size=arguments.maximum_score_batch_size,
+    )
+    decision = policy.score(request)
+    response = {
+        "schema_version": WORKER_SCHEMA_VERSION,
+        "decision": decision.to_record(),
+    }
+    arguments.response.write_text(
+        json.dumps(
+            response,
+            allow_nan=False,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ),
+        encoding="ascii",
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised as a child process
+    main()

agent_evolve/integrations/botorch/finite_qlognehvi_identity.py

@@ -0,0 +1,22 @@
+"""Dependency-free identity for the optional BoTorch qLogNEHVI expert."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+POLICY_ID = "botorch_finite_qlognehvi"
+POLICY_VERSION = 1
+POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:botorch-finite-qlognehvi:v1;"
+    b"model=independent-single-task-gp-known-noise-1e-6;"
+    b"outcome-transform=standardize;input-frame=adapter-normalized-unit-cube;"
+    b"objective-frame=fixed-affine-reference-zero-ideal-one;"
+    b"acquisition=qlog-noisy-expected-hypervolume-improvement;"
+    b"optimizer=exact-finite-discrete-unique;"
+    b"real-observations=prior-cutoff-only;"
+    b"configuration-materialization=outside-policy;workload-branches=false"
+).hexdigest()
+
+
+__all__ = ["POLICY_DEFINITION_SHA256", "POLICY_ID", "POLICY_VERSION"]

agent_evolve/integrations/botorch/finite_qlognehvi_worker.py

@@ -0,0 +1,55 @@
+"""Isolated JSON worker for the optional BoTorch finite acquisition policy."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from agent_evolve.integrations.botorch.finite_qlognehvi import (
+    BotorchQLogNehviFiniteAcquisition,
+)
+from agent_evolve.ports.finite_acquisition_json import (
+    finite_acquisition_request_from_record,
+)
+
+
+WORKER_SCHEMA_VERSION = 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--request", required=True, type=Path)
+    parser.add_argument("--response", required=True, type=Path)
+    parser.add_argument("--mc-samples", required=True, type=int)
+    parser.add_argument("--maximum-optimizer-batch-size", required=True, type=int)
+    return parser
+
+
+def main() -> None:
+    arguments = _parser().parse_args()
+    payload = json.loads(arguments.request.read_text(encoding="ascii"))
+    request = finite_acquisition_request_from_record(payload)
+    policy = BotorchQLogNehviFiniteAcquisition(
+        mc_samples=arguments.mc_samples,
+        maximum_optimizer_batch_size=arguments.maximum_optimizer_batch_size,
+    )
+    decision = policy.select(request)
+    response = {
+        "schema_version": WORKER_SCHEMA_VERSION,
+        "decision": decision.to_record(),
+    }
+    arguments.response.write_text(
+        json.dumps(
+            response,
+            allow_nan=False,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ),
+        encoding="ascii",
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised as a child process
+    main()