alchemist-nrel 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

alchemist_nrel-0.3.1.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: alchemist-nrel
+Version: 0.3.1
+Summary: Active learning and optimization toolkit for chemical and materials research
+Author-email: Caleb Coatney <caleb.coatney@nrel.gov>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/NREL/ALchemist
+Project-URL: Documentation, https://nrel.github.io/ALchemist/
+Project-URL: Source, https://github.com/NREL/ALchemist
+Project-URL: Bug Tracker, https://github.com/NREL/ALchemist/issues
+Project-URL: Changelog, https://github.com/NREL/ALchemist/releases
+Keywords: active learning,bayesian optimization,gaussian processes,materials science,chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: mplcursors
+Requires-Dist: scikit-learn
+Requires-Dist: scikit-optimize
+Requires-Dist: botorch
+Requires-Dist: torch
+Requires-Dist: gpytorch
+Requires-Dist: ax-platform
+Requires-Dist: customtkinter
+Requires-Dist: tksheet
+Requires-Dist: tabulate
+Requires-Dist: ctkmessagebox
+Requires-Dist: joblib
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: requests
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-anyio>=0.0.0; extra == "test"
+Requires-Dist: httpx>=0.25.0; extra == "test"
+Requires-Dist: requests>=2.31.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-anyio>=0.0.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+<img src="docs/assets/NEW_LOGO_LIGHT.png" alt="ALchemist" width="50%" />
+
+**ALchemist: Active Learning Toolkit for Chemical and Materials Research**
+
+ALchemist is a modular Python toolkit that brings active learning and Bayesian optimization to experimental design in chemical and materials research. It is designed for scientists and engineers who want to efficiently explore or optimize high-dimensional variable spaces—using intuitive graphical interfaces, programmatic APIs, or autonomous optimization workflows.
+
+**NLR Software Record:** SWR-25-102
+
+---
+
+## Documentation
+
+Full user guide and documentation:  
+[https://nrel.github.io/ALchemist/](https://nrel.github.io/ALchemist/)
+
+---
+
+## Overview
+
+**Key Features:**
+
+- **Flexible variable space definition**: Real, integer, and categorical variables with bounds or discrete values
+- **Probabilistic surrogate modeling**: Gaussian process regression via BoTorch or scikit-learn backends
+- **Advanced acquisition strategies**: Efficient sampling using qEI, qPI, qUCB, and qNegIntegratedPosteriorVariance
+- **Modern web interface**: React-based UI with FastAPI backend for seamless active learning workflows
+- **Desktop GUI**: CustomTkinter desktop application for offline optimization
+- **Session management**: Save/load optimization sessions with audit logs for reproducibility
+- **Multiple interfaces**: No-code GUI, Python Session API, or REST API for different use cases
+- **Autonomous optimization**: Human-out-of-the-loop operation for real-time process control
+- **Experiment tracking**: CSV logging, reproducible random seeds, and comprehensive audit trails
+- **Extensibility**: Abstract interfaces for models and acquisition functions enable future backend and workflow expansion
+**Architecture:**
+
+ALchemist is built on a clean, modular architecture:
+
+- **Core Session API**: Headless Bayesian optimization engine (`alchemist_core`) that powers all interfaces
+- **Desktop Application**: CustomTkinter GUI using the Core Session API, designed for human-in-the-loop and offline optimization
+- **REST API**: FastAPI server providing a thin wrapper around the Core Session API for remote access
+- **Web Application**: React UI consuming the REST API, supporting both interactive and autonomous optimization workflows
+
+Session files (JSON format) are fully interoperable between desktop and web applications, enabling seamless workflow transitions.
+
+---
+
+## Use Cases
+
+- **Interactive Optimization**: Use desktop or web GUI for manual experiment design and human-in-the-loop optimization
+- **Programmatic Workflows**: Import the Session API in Python scripts or Jupyter notebooks for batch processing
+- **Autonomous Optimization**: Use the REST API to integrate ALchemist with automated laboratory equipment for real-time process control
+- **Remote Monitoring**: Web dashboard provides read-only monitoring mode when ALchemist is being remote-controlled
+
+For detailed application examples, see [Use Cases](https://nrel.github.io/ALchemist/use_cases/) in the documentation.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.11 or higher
+
+**Recommended (Optional):** We recommend using [Anaconda](https://www.anaconda.com/products/distribution) to manage Python environments:
+
+```bash
+conda create -n alchemist-env python=3.11
+conda activate alchemist-env
+```
+
+**Basic Installation:**
+
+```bash
+pip install alchemist-nrel
+```
+
+**From GitHub:**
+> *Note: This installs the latest unreleased version. The web application is not pre-built with this method because static build files are not included in the repository.*
+
+```bash
+pip install git+https://github.com/NREL/ALchemist.git
+```
+
+For advanced installation options, Docker deployment, and development setup, see the [Advanced Installation Guide](https://nrel.github.io/ALchemist/#advanced-installation) in the documentation.
+
+---
+
+## Running ALchemist
+
+**Web Application:**
+```bash
+alchemist-web
+```
+Opens at [http://localhost:8000/app](http://localhost:8000/app)
+
+**Desktop Application:**
+```bash
+alchemist
+```
+
+For detailed usage instructions, see [Getting Started](https://nrel.github.io/ALchemist/) in the documentation.
+
+---
+
+## Development Status
+
+ALchemist is under active development at NLR as part of the DataHub project within the ChemCatBio consortium.
+
+---
+
+## Issues & Troubleshooting
+
+If you encounter any issues or have questions, please [open an issue on GitHub](https://github.com/NREL/ALchemist/issues) or contact ccoatney@nrel.gov.
+
+For the latest known issues and troubleshooting tips, see the [Issues & Troubleshooting Log](docs/ISSUES_LOG.md).
+
+We appreciate your feedback and bug reports to help improve ALchemist!
+
+---
+
+## License
+
+This project is licensed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Repository
+
+[https://github.com/NREL/ALchemist](https://github.com/NREL/ALchemist)
+

{alchemist_nrel-0.3.0.dist-info → alchemist_nrel-0.3.1.dist-info}/RECORD

@@ -1,52 +1,52 @@
 main.py,sha256=3sAO2QZxxibs4WRT82i2w6KVBBFmYEMNUoGiMYFowOw,126
-run_api.py,sha256=-oxrFnDztyI0rfvZv0-QTBAbgW3OcCArdqg3c5l18qs,1849
 alchemist_core/__init__.py,sha256=jYIygJyhCXUmX3oAaxw687uLLQcRSuxNRQrMeuWuuuI,2023
 alchemist_core/audit_log.py,sha256=s8h3YKBgvcu_tgIrjP69rNr6yOnbks5J2RR_m2bwB4Q,22531
 alchemist_core/config.py,sha256=Sk5eM1okktO5bUMlMPv9yzF2fpuiyGr9LUtlCWIBDc8,3366
 alchemist_core/events.py,sha256=ty9nRzfZGHzk6b09dALIwrMY_5PYSv0wMaw94JLDjSk,6717
-alchemist_core/session.py,sha256=UCjMEWTWPY9ywsuS1meWGF9hqVse7DaFFnhr2oW9qwc,48228
+alchemist_core/session.py,sha256=OraGE2y78s9cbhfpxr4jllfet-GclCfTj0yV1D9S_2M,55330
 alchemist_core/acquisition/__init__.py,sha256=3CYGI24OTBS66ETrlGFyHCNpfS6DBMP41MZDhvjFEzg,32
 alchemist_core/acquisition/base_acquisition.py,sha256=s51vGx0b0Nt91lSCiVwYP9IClugVg2VJ21dn2n_4LIs,483
-alchemist_core/acquisition/botorch_acquisition.py,sha256=dGzXY7XMbrRzOIFC4UoA6mMYEDplKgb58ym_TzmiMss,31332
+alchemist_core/acquisition/botorch_acquisition.py,sha256=r2Z510UIrPZCS-uXWZzgtaNhmCUh0CsTrAJQCWdevxA,31401
 alchemist_core/acquisition/skopt_acquisition.py,sha256=YRdANqgiN3GWd4sn16oruN6jVnI4RLmvLhBMUfYyLp4,13115
 alchemist_core/data/__init__.py,sha256=wgEb03x0RzVCi0uJXOzEKXkbA2oNHom5EgSB3tKgl1E,256
-alchemist_core/data/experiment_manager.py,sha256=gyccrEq9ddTdKZ4zmCfGXB2bK7zZaCjL9a0FzZ9-eoY,8723
+alchemist_core/data/experiment_manager.py,sha256=LujWfFRlOSP7rok8sxTc6NTjetN7u7RnsOo5W2I5o-w,9013
 alchemist_core/data/search_space.py,sha256=oA9YEF3JRWpRklHzSo_Uxlmfy7bHwZfLZFDf4_nl4ew,6230
 alchemist_core/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-alchemist_core/models/ax_model.py,sha256=Fnu19Et376WxLXpApZSalIbWHQE9OQnMk41_PW69XnQ,6040
 alchemist_core/models/base_model.py,sha256=gIpC2eoTZcp4ozI0Rctcxt_4bLhgaE6ALYCzvuIrMZw,3145
 alchemist_core/models/botorch_model.py,sha256=VbZjggt8PszTJeG0x1A1vGGM1kT95Bjset3HWT6PQEM,42263
-alchemist_core/models/sklearn_model.py,sha256=iCwZ-ZWZuYgFpRQDoWwaIBBWz9dPdf-6wNGPdUHM9cU,36698
+alchemist_core/models/sklearn_model.py,sha256=XEr2yAQtVQd3beGAoQnuNmt_inzEsKAwpGo-Gfdp2vY,38059
 alchemist_core/utils/__init__.py,sha256=oQsvUqukRng8GgiZSPMM-xmB-Lv46XveJzYQr2MdkOc,99
 alchemist_core/utils/doe.py,sha256=hnrhIzm3Nz0qZBW4PXaNQ6pTDgiLn_lUhbMPmWmk_6Y,7110
-alchemist_nrel-0.3.0.dist-info/licenses/LICENSE,sha256=wdIWWEj59ztfQViDuT_9wG3L1K8afUpRSygimXw36wY,1511
+alchemist_nrel-0.3.1.dist-info/licenses/LICENSE,sha256=wdIWWEj59ztfQViDuT_9wG3L1K8afUpRSygimXw36wY,1511
 api/__init__.py,sha256=ODc6pq4OSImgK4xvhX_zMhqUjIc7JvLfqxKF_-Ubw7g,49
 api/dependencies.py,sha256=sF1YYjnFRaw7nj7Y7URKLF2Ek-EfaXqjOyV1Zbktz2g,1090
-api/example_client.py,sha256=aZMNuJmt00hpNEkijn5RnVEV7ZPfKzwQxucSasTrrdw,6645
-api/main.py,sha256=OHs00UruREujnNT2h1lXtK_ZiNz14lwYH67kqH8o78o,4215
+api/example_client.py,sha256=RjEOvZItzgmGdP6V5j106LQqmQg0WIEr72xf4oMJZHo,6924
+api/main.py,sha256=Fee_u_dvNcLzNE-kRhoinfEYnIf5e-i71ZwdNOHu7hY,4301
+api/run_api.py,sha256=YGyLUJNbdsDGEKsd_EsrA1gGheGW53etn8F3ku44q1g,1993
 api/middleware/__init__.py,sha256=WM4JEg3DibymvEvQ6hx_FJkv8lKLjHD48qNouSORGxA,313
 api/middleware/error_handlers.py,sha256=k5hNo6W5QDjGRHUY8Le-t7ubWkwSZBFpsTKcEF0nweI,4545
 api/models/__init__.py,sha256=YFtp8989mH9Zjzvd8W6pXklQJXTf8zWj4I2YWnLegDQ,1204
-api/models/requests.py,sha256=Hez7Pnk1Mm7hjsbsG1Kv7pX7imsIkqovroGRmUaIL38,9938
-api/models/responses.py,sha256=5jzoIm7HiLWJPJ2U_iL3ACeixWdIuFwjMnhVNE9vCRE,12789
+api/models/requests.py,sha256=SvAL36-WcuaibKkI2hsNPDEpptZHw88_Oj961dD37vE,10853
+api/models/responses.py,sha256=58oWYfKcQpUpa3oF_VY-QfNTaLxGu_O1cgBHB-Banjs,13704
 api/routers/__init__.py,sha256=Mhg62NdA6iaPy-L5HLVp_dd9aUHmJ72KtMSRyO2kusA,180
-api/routers/acquisition.py,sha256=7c9ifuCFeDj8osWRHgCjAwbXjhd3iEBlVLW23FOAZXI,5710
-api/routers/experiments.py,sha256=q7mgGmzHqe9wr9njSbUw5gmWt2kGoSv86-qbSakSNe0,9467
+api/routers/acquisition.py,sha256=GzncAXsQzhldB-gngpMcUa5choaoAqMqLrpqszRjMFc,6683
+api/routers/experiments.py,sha256=h4UI96MwSVL5VmibI-ebdsOl0f332edcifmdNL8OVFg,10329
 api/routers/models.py,sha256=32Ln0MtlnCEjfN3Q6Io_EBwwwGoJXb73UbQEMIcVGjI,3651
-api/routers/sessions.py,sha256=5yvNNgQzZadEq6MU-rjV1DFgtH6awyxYne5UTVZ7NCU,15541
+api/routers/sessions.py,sha256=3h9veIWxx4F1bP_YgWwOCtuKIDe2e8VcaBCjQxmZT7c,19073
 api/routers/variables.py,sha256=TiByX1ITabBDdTSMGAPa1lGd0LBipNgDfmPsbvTEAdE,10108
 api/routers/visualizations.py,sha256=QPe1PkgGtzb4Oe4YYgFoi7J1oHJGS5pa1g75KKBDqUM,24180
+api/routers/websocket.py,sha256=AnENOTSk8LOZ5XD_5O29srOfdQ8U136Yzw6dwMca9t4,4361
 api/services/__init__.py,sha256=0jw0tkL-8CtChv5ytdXRFeIz1OTVz7Vw1UaaDo86PQs,106
-api/services/session_store.py,sha256=bVzRaf4YFoNKkXuSmzs76F1qaIl_6lUUI3KZJJgVc3U,16255
+api/services/session_store.py,sha256=BIGJUAiOEQ3uH40wUXuzqd7djy60SE6PQDKVBquJS9Y,18989
 api/static/NEW_ICON.ico,sha256=V4zY86qhPT24SSYK8VL5Ax5AezWxOfvfeHWBXisudOU,247870
 api/static/NEW_ICON.png,sha256=7UUPRgQ6-Ncv1xvB_57QMfrMY8xxHn16mLHc_zUGmCE,62788
 api/static/NEW_LOGO_DARK.png,sha256=O4p2tfTBuChSSPRl-Fzue1qoQdLkqXHBofNyiEzRNLs,128146
 api/static/NEW_LOGO_LIGHT.png,sha256=XBcv5-snGDTpjCrk7UfuJiFbSqrsGRafk7vNBj9eJnM,131686
-api/static/index.html,sha256=P9QXmIzDTIx7ybgXS7xZXUpvYsmc19j2zaXVFgIJQjQ,499
+api/static/index.html,sha256=ttWE08A9TQ0ai63juHHo0SvcPWczYg4ANob2GB4ZQ5Q,499
 api/static/vite.svg,sha256=SnSK_UQ5GLsWWRyDTEAdrjPoeGGrXbrQgRw6O0qSFPs,1497
 api/static/assets/api-vcoXEqyq.js,sha256=LDSOiSvi1Zc7SRry3ldpA__egc6GAFbzQt9QzBzbTIQ,303
-api/static/assets/index-C0_glioA.js,sha256=PDlXBE-WtR6W_pMcuQepY5R62Ih_mQC6GLf0FuszNks,5741783
-api/static/assets/index-CB4V1LI5.css,sha256=s-fUWesYGl8kRqel4-sVfuc-xgbVvoJkjocPZFG1y7k,19867
+api/static/assets/index-DWfIKU9j.js,sha256=raGrwAEmx2gqVz8E7HlQ8KiqOFPYOQuHpKI4rqYdydw,5745850
+api/static/assets/index-sMIa_1hV.css,sha256=1-xNuB1JVE5hK0YzdpYb6ys1dMNJMDgx6IMv712yryI,20007
 ui/__init__.py,sha256=H4kWlVey7KKf3iPQi74zuM7FSOg5Gh-ii3UwSTuIp8A,1203
 ui/acquisition_panel.py,sha256=zF-mQDrs-Y7sf2GXYF-bPlO9UXZMTzYRMDN-Wn5FyWw,39647
 ui/custom_widgets.py,sha256=UXNv4DiTw3tFC0VaN1Qtcf_-9umX34uDn46-cEA6cs0,3812
@@ -59,8 +59,8 @@ ui/ui_utils.py,sha256=yud2-9LvT4XBcjTyfwUX5tYGNZRlAUVlu2YpcNY1HKA,658
 ui/utils.py,sha256=m19YFFkEUAY46YSj6S5RBmfUFjIWOk7F8CB4oKDRRZw,1078
 ui/variables_setup.py,sha256=6hphCy66uLsjIX7FjFtY6-fBfZ6cgfpviXXX9JBhuc4,23618
 ui/visualizations.py,sha256=FCpuehMi2Cf3Jpuycqoj43oJoCU-QAr8-6Sp6LCO4hE,70371
-alchemist_nrel-0.3.0.dist-info/METADATA,sha256=lkBbue0m5K4jyGYvhygJixkTlQhFvQ3oaQHiETdZcEs,7450
-alchemist_nrel-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-alchemist_nrel-0.3.0.dist-info/entry_points.txt,sha256=asivtbePfGKa57dNbOe43lVbfN51S9cuJwfUoaE9TOs,69
-alchemist_nrel-0.3.0.dist-info/top_level.txt,sha256=-T0oWa1AfOHigC-CJFatoYBZapTpqTBVccZ7eelT5jY,35
-alchemist_nrel-0.3.0.dist-info/RECORD,,
+alchemist_nrel-0.3.1.dist-info/METADATA,sha256=SxYr-5UGvB6fL_O_OvopkBMkM4QsBSWBhi_t88t0nFw,7122
+alchemist_nrel-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+alchemist_nrel-0.3.1.dist-info/entry_points.txt,sha256=e2QcTxh-pidX_eJlQRk9yE3hLMYA0YnUzSh3sxqvdzY,73
+alchemist_nrel-0.3.1.dist-info/top_level.txt,sha256=dwh-oxj7H6oAGYchcUDyfiu9UxxzCn4hUDx1oeM2k-8,27
+alchemist_nrel-0.3.1.dist-info/RECORD,,

{alchemist_nrel-0.3.0.dist-info → alchemist_nrel-0.3.1.dist-info}/entry_points.txt

@@ -1,3 +1,3 @@
 [console_scripts]
 alchemist = main:main
-alchemist-web = run_api:main
+alchemist-web = api.run_api:main

{alchemist_nrel-0.3.0.dist-info → alchemist_nrel-0.3.1.dist-info}/top_level.txt

@@ -1,5 +1,4 @@
 alchemist_core
 api
 main
-run_api
 ui

api/example_client.py

@@ -90,8 +90,13 @@ def main():
         json={"experiments": experiments}
     )
     response.raise_for_status()
-    n_added = response.json()["n_added"]
-    print(f"   ✓ Added {n_added} experiments")
+    batch_result = response.json()
+    n_added = batch_result.get("n_added", len(experiments))
+    total_experiments = batch_result.get("n_experiments")
+    if total_experiments is not None and total_experiments >= n_added:
+        print(f"   ✓ Added {n_added} experiments (total: {total_experiments})")
+    else:
+        print(f"   ✓ Added {n_added} experiments")
     
     # Get data summary
     response = requests.get(f"{BASE_URL}/sessions/{session_id}/experiments/summary")

api/main.py

@@ -16,7 +16,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
-from .routers import sessions, variables, experiments, models, acquisition, visualizations
+from .routers import sessions, variables, experiments, models, acquisition, visualizations, websocket
 from .middleware.error_handlers import add_exception_handlers
 import logging
 
@@ -64,6 +64,7 @@ app.include_router(experiments.router, prefix="/api/v1/sessions", tags=["Experim
 app.include_router(models.router, prefix="/api/v1/sessions", tags=["Models"])
 app.include_router(acquisition.router, prefix="/api/v1/sessions", tags=["Acquisition"])
 app.include_router(visualizations.router, prefix="/api/v1/sessions", tags=["Visualizations"])
+app.include_router(websocket.router, prefix="/api/v1", tags=["WebSocket"])
 
 
 @app.get("/")

api/models/requests.py

@@ -93,13 +93,17 @@ class AddExperimentRequest(BaseModel):
     inputs: Dict[str, Union[float, int, str]] = Field(..., description="Variable values")
     output: Optional[float] = Field(None, description="Target/output value")
     noise: Optional[float] = Field(None, description="Measurement uncertainty")
+    iteration: Optional[int] = Field(None, description="Iteration number (auto-assigned if None)")
+    reason: Optional[str] = Field(None, description="Reason for this experiment")
     
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
                 "inputs": {"temperature": 350, "catalyst": "A"},
                 "output": 0.85,
-                "noise": 0.02
+                "noise": 0.02,
+                "iteration": 1,
+                "reason": "Initial Design"
             }
         }
     )
@@ -271,3 +275,22 @@ class LockDecisionRequest(BaseModel):
             }
         }
     )
+
+
+# ============================================================
+# Session Lock Models
+# ============================================================
+
+class SessionLockRequest(BaseModel):
+    """Request to lock a session for programmatic control."""
+    locked_by: str = Field(..., description="Identifier of the client locking the session")
+    client_id: Optional[str] = Field(None, description="Optional unique client identifier")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "locked_by": "Reactor Controller v1.2",
+                "client_id": "lab-3-workstation"
+            }
+        }
+    )

api/models/responses.py

@@ -434,3 +434,26 @@ class LockDecisionResponse(BaseModel):
             }
         }
     )
+
+
+# ============================================================
+# Session Lock Models
+# ============================================================
+
+class SessionLockResponse(BaseModel):
+    """Response for session lock operations."""
+    locked: bool = Field(..., description="Whether the session is locked")
+    locked_by: Optional[str] = Field(None, description="Identifier of who locked the session")
+    locked_at: Optional[str] = Field(None, description="When the session was locked")
+    lock_token: Optional[str] = Field(None, description="Token for unlocking (only on lock)")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "locked": True,
+                "locked_by": "Reactor Controller v1.2",
+                "locked_at": "2025-12-04T16:30:00",
+                "lock_token": "550e8400-e29b-41d4-a716-446655440000"
+            }
+        }
+    )

api/routers/acquisition.py

@@ -59,6 +59,31 @@ async def suggest_next_experiments(
     # Convert to list of dicts
     suggestions = suggestions_df.to_dict('records')
     
+    # Record acquisition in audit log
+    if suggestions:
+        # Get current max iteration from experiments
+        iteration = None
+        if not session.experiment_manager.df.empty and 'Iteration' in session.experiment_manager.df.columns:
+            iteration = int(session.experiment_manager.df['Iteration'].max()) + 1
+        
+        # Build parameters dict with only fields that exist
+        acq_params = {
+            "goal": request.goal,
+            "n_suggestions": request.n_suggestions
+        }
+        if request.xi is not None:
+            acq_params["xi"] = request.xi
+        if request.kappa is not None:
+            acq_params["kappa"] = request.kappa
+        
+        session.audit_log.lock_acquisition(
+            strategy=request.strategy,
+            parameters=acq_params,
+            suggestions=suggestions,
+            iteration=iteration,
+            notes=f"Suggested {len(suggestions)} point(s) using {request.strategy}"
+        )
+    
     logger.info(f"Generated {len(suggestions)} suggestions for session {session_id} using {request.strategy}")
     
     return AcquisitionResponse(

api/routers/experiments.py

@@ -51,31 +51,47 @@ async def add_experiment(
     session.add_experiment(
         inputs=experiment.inputs,
         output=experiment.output,
-        noise=experiment.noise
+        noise=experiment.noise,
+        iteration=experiment.iteration,
+        reason=experiment.reason
     )
     
     n_experiments = len(session.experiment_manager.df)
     logger.info(f"Added experiment to session {session_id}. Total: {n_experiments}")
     
-    # Auto-train if requested
+    # Auto-train if requested (need at least 5 points to train)
     model_trained = False
     training_metrics = None
     
-    if auto_train and n_experiments >= 5:  # Minimum data for training
+    if auto_train and n_experiments >= 5:
         try:
             # Use previous config or provided config
             backend = training_backend or (session.model_backend if session.model else "sklearn")
             kernel = training_kernel or "rbf"
             
+            # Note: Input/output transforms are now automatically applied by core Session.train_model()
+            # for BoTorch models. No need to specify them here unless overriding defaults.
             result = session.train_model(backend=backend, kernel=kernel)
             model_trained = True
             metrics = result.get("metrics", {})
+            hyperparameters = result.get("hyperparameters", {})
             training_metrics = {
                 "rmse": metrics.get("rmse"),
                 "r2": metrics.get("r2"),
                 "backend": backend
             }
             logger.info(f"Auto-trained model for session {session_id}: {training_metrics}")
+            
+            # Record in audit log if this is an optimization iteration
+            if experiment.iteration is not None and experiment.iteration > 0:
+                session.audit_log.lock_model(
+                    backend=backend,
+                    kernel=kernel,
+                    hyperparameters=hyperparameters,
+                    cv_metrics=metrics,
+                    iteration=experiment.iteration,
+                    notes=f"Auto-trained after iteration {experiment.iteration}"
+                )
         except Exception as e:
             logger.error(f"Auto-train failed for session {session_id}: {e}")
             # Don't fail the whole request, just log it

api/routers/sessions.py

@@ -4,11 +4,14 @@ Sessions router - Session lifecycle management.
 
 from fastapi import APIRouter, HTTPException, status, UploadFile, File, Depends
 from fastapi.responses import Response, FileResponse, JSONResponse
-from ..models.requests import UpdateMetadataRequest, LockDecisionRequest
+from typing import Optional
+from ..models.requests import UpdateMetadataRequest, LockDecisionRequest, SessionLockRequest
 from ..models.responses import (
     SessionCreateResponse, SessionInfoResponse, SessionStateResponse,
-    SessionMetadataResponse, AuditLogResponse, AuditEntryResponse, LockDecisionResponse
+    SessionMetadataResponse, AuditLogResponse, AuditEntryResponse, LockDecisionResponse,
+    SessionLockResponse
 )
+from .websocket import broadcast_to_session
 from ..services import session_store
 from ..dependencies import get_session
 from alchemist_core.session import OptimizationSession
@@ -463,3 +466,109 @@ async def upload_session(file: UploadFile = File(...)):
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=f"Failed to upload session: {str(e)}"
         )
+
+
+# ============================================================
+# Session Locking Endpoints
+# ============================================================
+
+@router.post("/sessions/{session_id}/lock", response_model=SessionLockResponse)
+async def lock_session(
+    session_id: str,
+    request: SessionLockRequest
+):
+    """
+    Lock a session for external programmatic control.
+    
+    When locked, the web UI should enter monitor-only mode.
+    Returns a lock_token that must be used to unlock.
+    """
+    try:
+        result = session_store.lock_session(
+            session_id=session_id,
+            locked_by=request.locked_by,
+            client_id=request.client_id
+        )
+        
+        # Broadcast lock event to WebSocket clients
+        await broadcast_to_session(session_id, {
+            "event": "lock_status_changed",
+            "locked": True,
+            "locked_by": request.locked_by,
+            "locked_at": result["locked_at"]
+        })
+        
+        return SessionLockResponse(**result)
+    except KeyError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found or expired"
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to lock session: {str(e)}"
+        )
+
+
+@router.delete("/sessions/{session_id}/lock", response_model=SessionLockResponse)
+async def unlock_session(
+    session_id: str,
+    lock_token: Optional[str] = None
+):
+    """
+    Unlock a session.
+    
+    Optionally provide lock_token for verification.
+    If no token provided, forcibly unlocks (use with caution).
+    """
+    try:
+        result = session_store.unlock_session(session_id=session_id, lock_token=lock_token)
+        
+        # Broadcast unlock event to WebSocket clients
+        await broadcast_to_session(session_id, {
+            "event": "lock_status_changed",
+            "locked": False,
+            "locked_by": None,
+            "locked_at": None
+        })
+        
+        return SessionLockResponse(**result)
+    except KeyError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found or expired"
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=str(e)
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to unlock session: {str(e)}"
+        )
+
+
+@router.get("/sessions/{session_id}/lock", response_model=SessionLockResponse)
+async def get_lock_status(session_id: str):
+    """
+    Get current lock status of a session.
+    
+    Used by web UI to detect when external controller has taken control
+    and automatically enter monitor mode.
+    """
+    try:
+        result = session_store.get_lock_status(session_id=session_id)
+        return SessionLockResponse(**result)
+    except KeyError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session {session_id} not found or expired"
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get lock status: {str(e)}"
+        )