osprey-optimizer 2026.11.0__tar.gz

osprey_optimizer-2026.11.0/.gitignore

@@ -0,0 +1,226 @@
+# Scratch notes (local idea capture)
+scratch/
+
+# NFS temporary files
+.nfs*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+/build/
+develop-eggs/
+/dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage*
+.cache
+nosetests.xml
+coverage.xml
+coverage.json
+*.cover
+.hypothesis/
+
+# CI diagnostics drop (per-worker event logs, stack dumps, container logs).
+# Written by _harness/ci_diagnostics.py and .github/actions/capture-ci-diagnostics
+# whenever OSPREY_CI_DIAG_DIR is set; uploaded as an artifact, never committed.
+/ci-diag/
+.pytest_cache/
+.mypy_cache/
+# The import graph lint-imports (import-linter) caches between runs.
+.import_linter_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment directories
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Data, models, and results
+!data/.gitkeep
+# models/ - Removed this to allow tracking model_config.py
+!models/.gitkeep
+results/
+!results/.gitkeep
+# Any source dir named results/ is SOURCE, not ML output — the broad unanchored
+# results/ ignore above must not swallow it (this negation is deliberately
+# path-independent: pinning it to one package broke when the bluesky-web
+# sidecar moved services/ -> interfaces/, silently dropping the panel from the move).
+!src/**/results/
+# Benchmark model-matrix run exhaust (#259) — regenerable from scripts/benchmark/.
+# All generated artifacts (dashboard.html, results_box/, live_updater.log) live
+# under one output dir co-located with the tooling, keeping the repo root clean.
+scripts/benchmark/_out/
+*.h5
+*.pkl
+*.pt
+*.pth
+*.onnx
+*.mlmodel
+
+# Logs
+logs/
+*.log
+!tests/deployment/fixtures/*.log
+tensorboard/
+
+# Temporary files
+tmp/
+temp/
+
+*.jpg
+*.gif
+*.bmp
+*.tiff
+*.ico
+# The demo template's CANOPY screens ship their images.
+!src/osprey/templates/apps/demo/data/canopy/library/screens/**/images/*.jpg
+
+# Landing-page demo video: recorded takes are never committed; the docs build
+# downloads the MP4s from the release manifest.json names. The posters and
+# manifest.json are committed, so the posters must override the `*.jpg` rule.
+docs/demo-video/
+docs/source/_static/demo/*.mp4
+!docs/source/_static/demo/*-poster.jpg
+
+# Credentials
+.env
+
+delete_me*
+valves.json
+*.code-workspace
+
+# Agent data directories
+_agent_data/*
+# Track only the Codex marketplace manifest; never Codex plugin state.
+.agents/*
+!.agents/plugins/
+.agents/plugins/*
+!.agents/plugins/marketplace.json
+
+# Local coding-agent guidance (kept out of git; see /CLAUDE.md below)
+AGENTS.md
+
+# Sample logbook data (large JSONL files)
+logbook_*.jsonl
+
+# Auto-generated documentation
+_autosummary/
+docs/build/
+
+# PID files
+*.pid
+
+# Development services and applications (keep locally but not in git)
+/.claude
+_ISSUES
+/CLAUDE.md
+.mcp.json
+
+# Git worktrees
+.worktrees/
+
+# Generated benchmark databases
+data/benchmarks/cross_paradigm/tier*/
+
+# OSPREY workspace (runtime data, not tracked — now covered by _agent_data/* above)
+
+# Vendor assets (fetched at build time via `osprey vendor fetch`)
+src/osprey/interfaces/artifacts/static/js/vendor/
+src/osprey/interfaces/artifacts/static/css/vendor/
+src/osprey/interfaces/web_terminal/static/vendor/*
+# The dock engine is tracked: vendored from CANOPY's screen runtime at a pinned commit.
+!src/osprey/interfaces/web_terminal/static/vendor/dock-engine.mjs
+!src/osprey/interfaces/web_terminal/static/vendor/dock-engine.d.mts
+src/osprey/interfaces/bluesky_web/panels/bluesky/vendor/
+src/osprey/interfaces/optimizer_web/panels/optimizer/vendor/
+# The okf panel's own vendored marked.min.js is tracked; only DOMPurify is fetched.
+src/osprey/interfaces/okf_panel/static/vendor/purify.min.js
+tests/e2e/claude_code/benchmark_results/
+
+# Model files staged by hand for hosts that cannot reach the model host. They
+# reach the qmd sidecar over the read-only mount `services.qmd.models_dir`
+# names, never through a build context — but the staging directory itself can
+# sit anywhere, this tree included. Gigabytes of GGUF, never source — keep them
+# out of git and out of the build (see also the hatch exclude in pyproject.toml)
+**/prefetched-models/
+
+# Playwright MCP browser-session cache (page snapshots, console logs)
+.playwright-mcp/
+
+# Node.js (dev-only JS toolchain; not part of the Python wheel)
+node_modules/
+
+# Working directory gitlab-ci-local writes when the deploy goldens are checked
+# against a real pipeline parser. Created wherever the check is run from.
+.gitlab-ci-local/
+
+# Version stamp written by the hatch-vcs build hook. Committing it would recreate
+# the stale-literal problem the git-derived version exists to remove. It is still
+# packaged into the wheel and sdist — the hook registers it as a build artifact.
+src/osprey/_version.py
+packages/osprey-connectors/src/osprey_connectors/_version.py
+packages/osprey-optimizer/src/osprey_optimizer/_version.py
+packages/pyaml-cs-osprey/src/pyaml_cs_osprey/_version.py
+
+# feature-scaffolding logs (not committed)
+.claude/.logs/
+
+# Process scaffolding — never committed (specs/plans live here uncommitted)
+docs/superpowers/
+
+# Locally scaffolded deployment project. Carries a real .env, build output and
+# run data; belongs to the working copy, never to the repo. Anchored to the root
+# so the pattern cannot swallow a same-named path elsewhere in the tree.
+/my-control-assistant/
+/osprey-demo/

osprey_optimizer-2026.11.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

osprey_optimizer-2026.11.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: osprey-optimizer
+Version: 2026.11.0
+Summary: Xopt-driven machine optimization service for OSPREY
+License: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: osprey-connectors>=2026.11.11
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: service
+Requires-Dist: botorch==0.17.2; extra == 'service'
+Requires-Dist: fastapi>=0.141.1; extra == 'service'
+Requires-Dist: gpytorch==1.15.2; extra == 'service'
+Requires-Dist: joblib>=1.5.2; extra == 'service'
+Requires-Dist: numpy>=2.2.6; extra == 'service'
+Requires-Dist: pandas>=2.2.3; extra == 'service'
+Requires-Dist: polars>=2.0.0; extra == 'service'
+Requires-Dist: python-multipart>=0.0.32; extra == 'service'
+Requires-Dist: redis>=5.0.4; extra == 'service'
+Requires-Dist: scikit-learn>=1.8.0; extra == 'service'
+Requires-Dist: starlette; extra == 'service'
+Requires-Dist: torch==2.13.0; extra == 'service'
+Requires-Dist: uvicorn[standard]>=0.52.1; extra == 'service'
+Requires-Dist: xopt==3.1.2; extra == 'service'
+Description-Content-Type: text/markdown
+
+# osprey-optimizer
+
+The OSPREY optimizer service: Xopt-driven tuning runs against a control
+system, with every write going through an OSPREY connector, so the write
+switch, channel limits and `max_step` apply to each one. An optimization
+environment is a YAML file of setpoint/readback channels and observables;
+Python environments register on the `osprey.optimizer.environments`
+entry-point group and are opt-in: the service loads only those named in
+`OPTIMIZER_PLUGINS` (comma-separated). A plugin must reach the machine through
+`ConnectorInterface`; that is not yet enforced for plugin code.
+
+## Install
+
+```
+pip install osprey-optimizer             # models and environment files only
+pip install "osprey-optimizer[service]"  # the engine and its HTTP service
+```
+
+The base install is what the OSPREY framework imports: the request, config
+and status models, and the environment-file format. It does not load the
+search stack. The `service` extra adds Xopt, PyTorch, BoTorch, Redis and
+FastAPI, and is what the optimizer's container image installs. For a
+CPU-only PyTorch, add `--extra-index-url https://download.pytorch.org/whl/cpu`.
+
+The service app is `osprey_optimizer.api.main:app`.

osprey_optimizer-2026.11.0/README.md

@@ -0,0 +1,25 @@
+# osprey-optimizer
+
+The OSPREY optimizer service: Xopt-driven tuning runs against a control
+system, with every write going through an OSPREY connector, so the write
+switch, channel limits and `max_step` apply to each one. An optimization
+environment is a YAML file of setpoint/readback channels and observables;
+Python environments register on the `osprey.optimizer.environments`
+entry-point group and are opt-in: the service loads only those named in
+`OPTIMIZER_PLUGINS` (comma-separated). A plugin must reach the machine through
+`ConnectorInterface`; that is not yet enforced for plugin code.
+
+## Install
+
+```
+pip install osprey-optimizer             # models and environment files only
+pip install "osprey-optimizer[service]"  # the engine and its HTTP service
+```
+
+The base install is what the OSPREY framework imports: the request, config
+and status models, and the environment-file format. It does not load the
+search stack. The `service` extra adds Xopt, PyTorch, BoTorch, Redis and
+FastAPI, and is what the optimizer's container image installs. For a
+CPU-only PyTorch, add `--extra-index-url https://download.pytorch.org/whl/cpu`.
+
+The service app is `osprey_optimizer.api.main:app`.

osprey_optimizer-2026.11.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "osprey-optimizer"
+dynamic = ["version"]
+description = "Xopt-driven machine optimization service for OSPREY"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "BSD-3-Clause"}
+# The base is the optimizer's contracts: the request, config and status models
+# and the environment-file format. The framework imports these (MCP tool
+# schemas, approval previews, the build-time environment check), so they must
+# load without the search stack below.
+dependencies = [
+    "osprey-connectors>=2026.11.11",
+    "pydantic>=2.12.5",
+    "PyYAML>=6.0.2",
+]
+
+[project.optional-dependencies]
+# The engine and its HTTP service: installed only in the optimizer's own image.
+# Torch and the BoTorch stack are gigabytes. The workspace resolves torch from
+# the CPU wheel index (root pyproject.toml, tool.uv.sources); a pip install from
+# PyPI has to pass that index itself.
+service = [
+    "xopt==3.1.2",
+    "torch==2.13.0",
+    "botorch==0.17.2",
+    "gpytorch==1.15.2",
+    "polars>=2.0.0",
+    "pandas>=2.2.3",
+    "numpy>=2.2.6",
+    "scikit-learn>=1.8.0",
+    "joblib>=1.5.2",
+    "redis>=5.0.4",
+    "fastapi>=0.141.1",
+    "starlette",  # imported directly by the app (middleware, responses)
+    "uvicorn[standard]>=0.52.1",
+    # FastAPI parses the model upload's form body with it and refuses to build
+    # that route without it, so the app does not import.
+    "python-multipart>=0.0.32",
+]
+
+[tool.hatch.version]
+source = "vcs"
+# Versions with the framework's calendar stream from the same v-tags (unlike
+# osprey-connectors, which has its own osprey-connectors-v* stream): one tag
+# builds the framework and optimizer wheels, and they carry the same number.
+raw-options = { root = "../..", version_scheme = "post-release", git_describe_command = "git describe --dirty --tags --long --abbrev=40 --match v[0-9]*" }
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/osprey_optimizer/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/osprey_optimizer"]

osprey_optimizer-2026.11.0/src/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-2026.11.0/src/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-2026.11.0/src/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-2026.11.0/src/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)