osprey-optimizer 2026.11.0__py3-none-any.whl

osprey_optimizer/__init__.py

@@ -0,0 +1,16 @@
+"""Optimizer service: Xopt-driven tuning jobs behind a FastAPI job API.
+
+Ported from tuning_scripts at commit 1bac27a1.
+
+The base install carries the contracts: ``models`` and ``environments`` load
+with pydantic, PyYAML and osprey-connectors only, and the OSPREY framework
+imports them. The search stack (xopt, torch, botorch, polars, redis, fastapi)
+is the ``service`` extra, installed only in the optimizer's image.
+
+Sub-packages:
+- models: request/response models, environment protocols, enums
+- environments: environment files and the connector-driven environment
+- api: FastAPI app, routers, job tracking and control (needs ``service``)
+- optimization: phase runner, evaluator, Xopt backend, custom generators
+- services: execution and orchestration inside the job worker
+"""

osprey_optimizer/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2026.11.0'
+__version_tuple__ = version_tuple = (2026, 11, 0)
+
+__commit_id__ = commit_id = None

osprey_optimizer/api/__init__.py

@@ -0,0 +1,12 @@
+"""The optimizer's HTTP service. Needs the ``service`` extra."""
+
+import importlib.util
+
+_SERVICE_ROOTS = ("fastapi", "redis", "polars", "xopt", "torch")
+
+_missing = [name for name in _SERVICE_ROOTS if importlib.util.find_spec(name) is None]
+if _missing:
+    raise ImportError(
+        f"osprey_optimizer.api needs the optimizer's service extra (missing: {', '.join(_missing)}). "
+        'Install it with: pip install "osprey-optimizer[service]"'
+    )

osprey_optimizer/api/dependencies.py

@@ -0,0 +1,58 @@
+"""FastAPI dependency callables for shared singletons.
+
+Each function reads from ``request.app.state``, which is populated by the
+lifespan handler in ``main.py``.  Use them with ``Depends()`` in endpoint
+signatures so that routers stay decoupled from initialization logic.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Depends, Query, Request
+
+from osprey_optimizer.api.job_status import load_job_meta
+from osprey_optimizer.api.job_tracker import JobMeta, JobTracker
+from osprey_optimizer.models.config import ControlTarget, ExecutionMode, machine_config
+from osprey_optimizer.services.plugin_registry import EnvironmentRegistry
+
+
+def get_job_tracker(request: Request) -> JobTracker:
+    return request.app.state.job_tracker  # type: ignore[no-any-return]
+
+
+def require_job_meta(job_id: str, tracker: JobTracker = Depends(get_job_tracker)) -> JobMeta:
+    """Resolve the path job's metadata once (404 if unknown, 500 if corrupt).
+
+    Endpoints under ``/jobs/{job_id}`` inject this instead of re-checking
+    existence and re-reading the record: FastAPI caches it for the request, so
+    the type/creation-time checks they used to make one call each now share a
+    single Redis read.
+    """
+    return load_job_meta(tracker, job_id)
+
+
+def get_environment_registry(request: Request) -> EnvironmentRegistry:
+    return request.app.state.environment_registry  # type: ignore[no-any-return]
+
+
+@dataclass(frozen=True)
+class Machine:
+    """The machine a request reaches, as the request named it."""
+
+    target: ControlTarget
+    execution_mode: ExecutionMode | None = None
+
+    def env_config(self) -> dict[str, Any]:
+        return machine_config(self.target, self.execution_mode)
+
+
+def require_machine(
+    target: ControlTarget = Query(
+        description="The machine this call reaches: va, standin or live. No default."
+    ),
+    execution_mode: ExecutionMode | None = Query(
+        default=None, description="readonly: reads only; every write is refused."
+    ),
+) -> Machine:
+    """Every endpoint that reaches a machine names it; there is no ambient target."""
+    return Machine(target=target, execution_mode=execution_mode)

osprey_optimizer/api/environment_ops.py

@@ -0,0 +1,294 @@
+"""Shared helpers for loading environments and reading/writing variables.
+
+Extracted from ``routers/environments.py`` so multiple routers (environments,
+run-config, results/restore) share one machine-access path and error mapping.
+"""
+
+import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from fastapi import HTTPException, status
+
+if TYPE_CHECKING:
+    from osprey_optimizer.api.job_tracker import JobTracker
+
+from osprey_optimizer.models.api import EnvironmentDetails, EnvironmentStatusResponse
+from osprey_optimizer.models.config import (
+    ControlTarget,
+    ExecutionMode,
+    Preset,
+    machine_config,
+)
+from osprey_optimizer.models.exceptions import ConnectionError as OptimizerConnectionError
+from osprey_optimizer.models.exceptions import TimeoutError as OptimizerTimeoutError
+from osprey_optimizer.models.exceptions import VariableOutOfBoundsError
+from osprey_optimizer.models.protocols import EnvironmentProtocol
+from osprey_optimizer.services.plugin_registry import EnvironmentRegistry
+
+logger = logging.getLogger(__name__)
+
+
+def require_known_environment(name: str, registry: EnvironmentRegistry) -> None:
+    """422 unless ``name`` is a discoverable environment."""
+    known = {e.name for e in registry.list_environments()}
+    if name not in known:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=f"Unknown environment '{name}'.",
+        )
+
+
+def environment_details(name: str, registry: EnvironmentRegistry) -> EnvironmentDetails:
+    """Assemble an environment's metadata — the single details builder.
+
+    Shared by the environments router and the current-environment reads so the
+    field set can't drift between endpoints.
+    """
+    env = load_environment(name, registry)
+    with env:
+        return EnvironmentDetails.from_environment(name, env)
+
+
+def probe_environment_health(
+    name: str, registry: EnvironmentRegistry, target: ControlTarget
+) -> EnvironmentStatusResponse:
+    """Probe an environment's connectivity on one target — the single health probe.
+
+    404 for an unknown name; any other probe failure degrades to
+    ``connected=None`` with the error message rather than a 5xx.
+    """
+    try:
+        env = lookup_environment(name, registry, machine_config(target))
+        with env:
+            connected = env.check_connection()
+        return EnvironmentStatusResponse(name=name, connected=connected, message=None)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.warning("Connectivity check failed for '%s': %s", name, e)
+        return EnvironmentStatusResponse(name=name, connected=None, message=str(e))
+
+
+def is_sim_target(target: ControlTarget) -> bool:
+    """True for the virtual accelerator, which no real-hardware safety gate applies to.
+
+    It gates restore-token safety and the health probe. The stand-in is not a
+    simulator here: it is where an operator rehearses real-machine behaviour.
+    """
+    return target == "va"
+
+
+def _environment_connected(name: str, registry: EnvironmentRegistry, target: ControlTarget) -> bool:
+    return probe_environment_health(name, registry, target).connected is True
+
+
+def _assert_healthy(
+    name: str, registry: EnvironmentRegistry, target: ControlTarget, override_unhealthy: bool
+) -> None:
+    if is_sim_target(target) or override_unhealthy:
+        return
+    if not _environment_connected(name, registry, target):
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Environment '{name}' is not reachable on '{target}'; pass override_unhealthy to proceed.",
+        )
+
+
+def guard_environment_write(
+    name: str,
+    target: ControlTarget,
+    tracker: "JobTracker",
+    registry: EnvironmentRegistry,
+    *,
+    override_unhealthy: bool,
+) -> None:
+    """Point-in-time precondition for a manual hardware write.
+
+    Requires no active job, and the environment healthy on ``target`` (or the
+    override). NOT a lock held across the write — a job may claim the slot after
+    this returns; that residual race is the accepted best-effort behavior. Whether
+    ``target`` may be written at all is the connector's decision, on every put.
+    """
+    if tracker.get_active_job() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="A job is active; manual writes are locked.",
+        )
+    _assert_healthy(name, registry, target, override_unhealthy)
+
+
+def guard_environment_start(
+    name: str, target: ControlTarget, registry: EnvironmentRegistry, *, override_unhealthy: bool
+) -> None:
+    """Point-in-time precondition for a job start: the environment healthy on its target.
+
+    The active-slot claim (claim_active_job) enforces the single-running-job
+    rule, so this does not check the active-job lock.
+    """
+    _assert_healthy(name, registry, target, override_unhealthy)
+
+
+def machine_env_config(
+    target: ControlTarget, execution_mode: ExecutionMode | None
+) -> dict[str, Any]:
+    """Environment config for a call that reaches ``target``."""
+    return machine_config(target, execution_mode)
+
+
+def lookup_environment(
+    name: str, registry: EnvironmentRegistry, env_config: dict[str, Any] | None = None
+) -> EnvironmentProtocol:
+    """Resolve an environment by name, mapping only the unknown-name case to 404.
+
+    Use this when the caller wants to handle other load failures itself (e.g.
+    ``/status`` degrades them to ``connected=False`` rather than a 500).
+    """
+    try:
+        return registry.load_environment(name, env_config or {})
+    except KeyError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Environment '{name}' not found",
+        ) from e
+
+
+def load_environment(
+    name: str, registry: EnvironmentRegistry, env_config: dict[str, Any] | None = None
+) -> EnvironmentProtocol:
+    """Load an environment by name, mapping failures to HTTP errors."""
+    try:
+        return lookup_environment(name, registry, env_config)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("Failed to load environment '%s'", name)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to load environment '{name}': {e}",
+        ) from e
+
+
+@contextmanager
+def read_errors(name: str, action: str) -> Iterator[None]:
+    """Map control-system read failures to HTTP errors.
+
+    ``action`` names the read (e.g. ``"get variables"``) and is interpolated
+    into the 500 detail. The 503 path is the catastrophic case where the CA
+    worker thread never answered (wedged or never started).
+
+    Wrap only the control-system call; keep name validation before the block
+    and value transforms after it so their errors are not misclassified.
+    """
+    try:
+        yield
+    except OptimizerTimeoutError as e:
+        logger.exception("CA worker unresponsive while reading from '%s'", name)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Control system worker unresponsive: {e}",
+        ) from e
+    except Exception as e:
+        logger.exception("Failed to %s from '%s'", action, name)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to {action}: {e}",
+        ) from e
+
+
+@contextmanager
+def write_errors(name: str, action: str) -> Iterator[None]:
+    """Map control-system write failures to HTTP errors.
+
+    ``action`` names the write (e.g. ``"set variables"``) and is interpolated
+    into the 500 detail. An out-of-bounds/unknown/non-finite value is a client
+    error (422); an unreachable or unresponsive control system is a 503.
+
+    Wrap only the control-system call; keep name validation before the block
+    and value transforms after it so their errors are not misclassified.
+    """
+    try:
+        yield
+    except VariableOutOfBoundsError as e:
+        # Unknown variable, out-of-bounds, or non-finite value: client error.
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=str(e),
+        ) from e
+    except (OptimizerConnectionError, OptimizerTimeoutError) as e:
+        logger.exception("Control system unreachable while trying to %s on '%s'", action, name)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Control system unavailable: {e}",
+        ) from e
+    except Exception as e:
+        logger.exception("Failed to %s on '%s'", action, name)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to {action}: {e}",
+        ) from e
+
+
+def validate_observable_names(names: list[str], env: EnvironmentProtocol) -> None:
+    """Raise 422 if any observable name is not in the environment metadata."""
+    unknown = [n for n in names if n not in env.observables]
+    if unknown:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=f"Unknown observable(s): {unknown}",
+        )
+
+
+def lookup_preset(registry: EnvironmentRegistry, name: str, preset: str) -> Preset:
+    """Environment ``name``'s preset ``preset``; 404 for either unknown, 422 for a bad declaration."""
+    presets = environment_presets(registry, name)
+    if preset not in presets:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Environment '{name}' has no preset '{preset}'. Available: {sorted(presets)}",
+        )
+    return presets[preset]
+
+
+def environment_presets(registry: EnvironmentRegistry, name: str) -> dict[str, Preset]:
+    """Environment ``name``'s presets; 404 when it is unknown, 422 for a bad declaration."""
+    try:
+        return registry.get_presets(name)
+    except KeyError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Environment '{name}' not found",
+        ) from e
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(e)) from e
+
+
+def validate_variable_names(
+    names: list[str],
+    env: EnvironmentProtocol,
+    field: str = "variable",
+) -> None:
+    """Raise 422 if any name is not in the environment metadata.
+
+    ``field`` labels the offending input so callers passing different fields
+    (e.g. ``overrides`` vs ``current_values``) get distinguishable messages.
+    """
+    unknown = [n for n in names if n not in env.variables]
+    if unknown:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=f"Unknown {field}(s): {unknown}",
+        )
+
+
+def apply_variables_to_environment(
+    env: EnvironmentProtocol, name: str, variables: dict[str, float]
+) -> None:
+    """Write variables to the machine, mapping control errors to HTTP errors.
+
+    Owns the environment context: pass a freshly-loaded (not already-open)
+    ``env`` from :func:`load_environment`; this opens and closes it.
+    """
+    with write_errors(name, "set variables"), env:
+        env.set_variables(variables)