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

alchemist_core/utils/doe.py

@@ -0,0 +1,200 @@
+"""
+Design of Experiments (DoE) - Initial sampling strategies for Bayesian optimization.
+
+This module provides methods for generating initial experimental designs before
+starting the optimization loop. Supported methods:
+- Random sampling
+- Latin Hypercube Sampling (LHS)
+- Sobol sequences
+- Halton sequences
+- Hammersly sequences
+"""
+
+from typing import List, Dict, Optional, Literal, Any
+import numpy as np
+from skopt.sampler import Lhs, Sobol, Hammersly
+from skopt.space import Real, Integer, Categorical
+from alchemist_core.data.search_space import SearchSpace
+from alchemist_core.config import get_logger
+
+logger = get_logger(__name__)
+
+
+def generate_initial_design(
+    search_space: SearchSpace,
+    method: Literal["random", "lhs", "sobol", "halton", "hammersly"] = "lhs",
+    n_points: int = 10,
+    random_seed: Optional[int] = None,
+    lhs_criterion: str = "maximin"
+) -> List[Dict[str, Any]]:
+    """
+    Generate initial experimental design using specified sampling strategy.
+    
+    This function creates a set of experimental conditions to evaluate before
+    starting Bayesian optimization. Different methods provide different
+    space-filling properties:
+    
+    - **random**: Uniform random sampling
+    - **lhs**: Latin Hypercube Sampling (recommended for most cases)
+    - **sobol**: Sobol quasi-random sequences (low discrepancy)
+    - **halton**: Halton sequences (via Hammersly sampler)
+    - **hammersly**: Hammersly sequences (low discrepancy)
+    
+    Args:
+        search_space: SearchSpace object with defined variables
+        method: Sampling method to use
+        n_points: Number of points to generate
+        random_seed: Random seed for reproducibility (applies to random and lhs)
+        lhs_criterion: Criterion for LHS optimization ("maximin", "correlation", "ratio")
+    
+    Returns:
+        List of dictionaries, each containing variable names and values.
+        Does NOT include 'Output' column - experiments need to be evaluated.
+    
+    Raises:
+        ValueError: If search_space has no variables or method is unknown
+    
+    Example:
+        >>> from alchemist_core import SearchSpace
+        >>> from alchemist_core.utils.doe import generate_initial_design
+        >>> 
+        >>> # Define search space
+        >>> space = SearchSpace()
+        >>> space.add_variable('temperature', 'real', min=300, max=500)
+        >>> space.add_variable('pressure', 'real', min=1, max=10)
+        >>> 
+        >>> # Generate 10 LHS points
+        >>> points = generate_initial_design(space, method='lhs', n_points=10)
+        >>> 
+        >>> # Points ready for experimentation
+        >>> for point in points:
+        >>>     print(point)  # {'temperature': 350.2, 'pressure': 4.7}
+    """
+    # Validate inputs
+    if len(search_space.variables) == 0:
+        raise ValueError("SearchSpace has no variables. Define variables before generating initial design.")
+    
+    if n_points < 1:
+        raise ValueError(f"n_points must be >= 1, got {n_points}")
+    
+    # Set random seed if provided
+    if random_seed is not None:
+        np.random.seed(random_seed)
+        logger.info(f"Set random seed to {random_seed} for reproducibility")
+    
+    # Get skopt dimensions from SearchSpace
+    skopt_space = search_space.skopt_dimensions
+    
+    # Generate samples based on method
+    if method == "random":
+        samples = _random_sampling(skopt_space, n_points)
+    
+    elif method == "lhs":
+        samples = _lhs_sampling(skopt_space, n_points, lhs_criterion)
+    
+    elif method == "sobol":
+        samples = _sobol_sampling(skopt_space, n_points)
+    
+    elif method in ["halton", "hammersly"]:
+        samples = _hammersly_sampling(skopt_space, n_points)
+    
+    else:
+        raise ValueError(
+            f"Unknown sampling method: {method}. "
+            f"Choose from: random, lhs, sobol, halton, hammersly"
+        )
+    
+    # Convert samples to list of dicts
+    variable_names = [v['name'] for v in search_space.variables]
+    points = []
+    
+    for sample in samples:
+        point = {name: value for name, value in zip(variable_names, sample)}
+        points.append(point)
+    
+    logger.info(
+        f"Generated {len(points)} initial points using {method} method "
+        f"for {len(variable_names)} variables"
+    )
+    
+    return points
+
+
+def _random_sampling(skopt_space, n_points: int) -> list:
+    """
+    Generate random samples respecting variable types.
+    
+    Handles Real, Integer, and Categorical dimensions appropriately.
+    Returns list of lists to preserve mixed types.
+    """
+    samples_list = []
+    
+    for dim in skopt_space:
+        if isinstance(dim, Categorical):
+            # Random choice from categories
+            samples = np.random.choice(dim.categories, size=n_points)
+        
+        elif isinstance(dim, Integer):
+            # Random integers in [low, high] (inclusive)
+            # np.random.randint is [low, high), so add 1 to include upper bound
+            samples = np.random.randint(dim.low, dim.high + 1, size=n_points)
+        
+        elif isinstance(dim, Real):
+            # Random floats in [low, high]
+            samples = np.random.uniform(dim.low, dim.high, size=n_points)
+        
+        else:
+            raise ValueError(f"Unknown dimension type: {type(dim)}")
+        
+        samples_list.append(samples)
+    
+    # Transpose to get list of samples (each sample is a list of values)
+    # Don't use column_stack as it converts everything to same dtype
+    samples = [[samples_list[j][i] for j in range(len(samples_list))] 
+               for i in range(n_points)]
+    return samples
+
+
+def _lhs_sampling(skopt_space, n_points: int, criterion: str = "maximin") -> list:
+    """
+    Generate Latin Hypercube Sampling points.
+    
+    LHS provides good space-filling properties and is generally recommended
+    for initial designs in Bayesian optimization.
+    
+    Args:
+        criterion: Optimization criterion
+            - "maximin": maximize minimum distance between points (default)
+            - "correlation": minimize correlations between dimensions
+            - "ratio": minimize ratio of max to min distance
+    """
+    sampler = Lhs(lhs_type="classic", criterion=criterion)
+    samples = sampler.generate(skopt_space, n_points)
+    # skopt returns list of samples already
+    return samples
+
+
+def _sobol_sampling(skopt_space, n_points: int) -> list:
+    """
+    Generate Sobol quasi-random sequence points.
+    
+    Sobol sequences have low discrepancy properties, meaning they cover
+    the space more uniformly than random sampling.
+    """
+    sampler = Sobol()
+    samples = sampler.generate(skopt_space, n_points)
+    # skopt returns list of samples already
+    return samples
+
+
+def _hammersly_sampling(skopt_space, n_points: int) -> list:
+    """
+    Generate Hammersly sequence points.
+    
+    Hammersly and Halton sequences are low-discrepancy sequences similar
+    to Sobol, providing good space coverage.
+    """
+    sampler = Hammersly()
+    samples = sampler.generate(skopt_space, n_points)
+    # skopt returns list of samples already
+    return samples

{alchemist_nrel-0.2.1.dist-info → alchemist_nrel-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alchemist-nrel
-Version: 0.2.1
+Version: 0.3.0
 Summary: Active learning and optimization toolkit for chemical and materials research
 Author-email: Caleb Coatney <caleb.coatney@nrel.gov>
 License: BSD-3-Clause
@@ -42,6 +42,7 @@ 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"
@@ -56,7 +57,7 @@ Requires-Dist: httpx>=0.25.0; extra == "dev"
 Requires-Dist: requests>=2.31.0; extra == "dev"
 Dynamic: license-file
 
-<img src="docs/assets/logo.png" alt="ALchemist" width="50%" />
+<img src="docs/assets/NEW_LOGO_LIGHT.png" alt="ALchemist" width="50%" />
 
 **ALchemist: Active Learning Toolkit for Chemical and Materials Research**
 
@@ -81,75 +82,91 @@ ALchemist accelerates discovery and optimization by combining:
 - **Probabilistic surrogate modeling:** Gaussian process regression via BoTorch or scikit-optimize 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.
+- **Autonomous optimization:** Human-out-of-the-loop optimization for real-time process control.
 - **Experiment tracking:** CSV logging, reproducible random seeds, and error tracking.
 - **Extensibility:** Abstract interfaces for models and acquisition functions enable future backend and workflow expansion.
 
+### Use Cases
+
+- **Interactive Optimization**: Desktop GUI or web UI for manual experiment design
+- **Programmatic Workflows**: Python Session API for scripts and notebooks
+- **Autonomous Operation**: REST API for real-time process control (reactors, synthesis, etc.)
+- **Remote Collaboration**: Web-based interface accessible from any device
+
 ---
 
 ## 🧭 Quick Start
 
-### Web Application (Recommended)
+### Installation
 
-**Development Mode:**
-```bash
-# Option 1: Manual start
-python run_api.py              # Terminal 1: Backend (port 8000)
-cd alchemist-web && npm run dev  # Terminal 2: Frontend (port 5173)
+**Requirements:** Python 3.11 or higher
 
-# Option 2: Automated start
-scripts\dev_start.bat    # Windows
-./scripts/dev_start.sh   # Linux/Mac
-```
+We recommend using [Anaconda](https://www.anaconda.com/products/distribution) to manage your Python environments.
 
-**Production Mode:**
+**1. Create a new environment:**
 ```bash
-# Build and run
-scripts\build_production.bat    # Windows
-./scripts/build_production.sh   # Linux/Mac
+conda create -n alchemist-env python=3.11
+conda activate alchemist-env
+```
 
-# Start production server
-python run_api.py --production
+**2. Install ALchemist:**
 
-# Access at: http://localhost:8000
+*Option A: From PyPI (recommended):*
+```bash
+pip install alchemist-nrel
 ```
 
-**Docker Deployment:**
+*Option B: From GitHub:*
 ```bash
-# Build frontend first
-cd alchemist-web && npm run build && cd ..
+pip install git+https://github.com/NREL/ALchemist.git
+```
 
-# Run with Docker Compose
-cd docker
-docker-compose up --build
+*Option C: Development install (for contributors):*
+```bash
+git clone https://github.com/NREL/ALchemist.git
+cd ALchemist
+pip install -e .
 ```
 
-### Python Package Installation
+All dependencies are specified in `pyproject.toml` and will be installed automatically.
 
-Requirements: Python 3.9 or higher
+**Note:** The web UI is pre-built and included in the package. You do **not** need Node.js/npm to use ALchemist unless you're developing the frontend.
 
-We recommend using [Anaconda](https://www.anaconda.com/products/distribution) to manage your Python environments.
+### Running ALchemist
 
-**1. Create a new environment:**
+**Web Application (Recommended):**
 ```bash
-conda create -n alchemist-env python=3.12
-conda activate alchemist-env
+alchemist-web
+# Opens at http://localhost:8000
 ```
 
-**2. Install ALchemist:**
-
-*Option A: Install directly from GitHub:*
+**Desktop Application:**
 ```bash
-python -m pip install git+https://github.com/NREL/ALchemist.git
+alchemist
+# Launches CustomTkinter GUI
 ```
 
-*Option B: Clone and install (recommended for development):*
+**Development Mode (Frontend Developers):**
 ```bash
-git clone https://github.com/NREL/ALchemist.git
-cd ALchemist
-python -m pip install -e .
+# Terminal 1: Backend with hot-reload
+python run_api.py
+
+# Terminal 2: Frontend with hot-reload
+cd alchemist-web
+npm install  # First time only
+npm run dev
+# Opens at http://localhost:5173
 ```
 
-All dependencies are specified in `pyproject.toml` and will be installed automatically.
+**Docker Deployment:**
+```bash
+docker pull ghcr.io/nrel/alchemist:latest
+docker run -p 8000:8000 ghcr.io/nrel/alchemist:latest
+
+# Or build from source:
+cd docker
+docker-compose up --build
+```
 
 For step-by-step instructions, see the [Getting Started](https://nrel.github.io/ALchemist/) section of the documentation.
 

alchemist_nrel-0.3.0.dist-info/RECORD

@@ -0,0 +1,66 @@
+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/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/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/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/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
+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/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/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/models.py,sha256=32Ln0MtlnCEjfN3Q6Io_EBwwwGoJXb73UbQEMIcVGjI,3651
+api/routers/sessions.py,sha256=5yvNNgQzZadEq6MU-rjV1DFgtH6awyxYne5UTVZ7NCU,15541
+api/routers/variables.py,sha256=TiByX1ITabBDdTSMGAPa1lGd0LBipNgDfmPsbvTEAdE,10108
+api/routers/visualizations.py,sha256=QPe1PkgGtzb4Oe4YYgFoi7J1oHJGS5pa1g75KKBDqUM,24180
+api/services/__init__.py,sha256=0jw0tkL-8CtChv5ytdXRFeIz1OTVz7Vw1UaaDo86PQs,106
+api/services/session_store.py,sha256=bVzRaf4YFoNKkXuSmzs76F1qaIl_6lUUI3KZJJgVc3U,16255
+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/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
+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
+ui/experiment_logger.py,sha256=dP3IGaQ31sURyz7awd_VrZBWaKLH2xXEeRalWZpvVcQ,8366
+ui/gpr_panel.py,sha256=rQYCKZr8UlXVL3DVXTq4ArlIodzvDOtZXkYrdotERtw,26465
+ui/notifications.py,sha256=hpUDo52_cQd7e8j7lOZikVRu1yLqRwlNR9vYNZdF5VM,35301
+ui/pool_viz.py,sha256=RwjggEfRSSEe-4nGjxc-I-1e5_aH64DgypT_YoubLIU,8765
+ui/ui.py,sha256=Lvg2H0_LrsrxJYFYFHr2LQsnbJWW5Q2fYqk63qVUJv4,101727
+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.2.1.dist-info → alchemist_nrel-0.3.0.dist-info}/entry_points.txt

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

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

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

api/main.py

@@ -32,14 +32,19 @@ logger = logging.getLogger(__name__)
 app = FastAPI(
     title="ALchemist API",
     description="REST API for Bayesian optimization and active learning",
-    version="0.1.0",
+    version="0.3.0",
     docs_url="/api/docs",
     redoc_url="/api/redoc",
     openapi_url="/api/openapi.json"
 )
 
 # CORS configuration - allows frontend in both dev and production
-ALLOWED_ORIGINS = os.getenv("ALLOWED_ORIGINS", "http://localhost:3000,http://localhost:5173").split(",")
+# Default origins include dev servers and common production patterns
+# Override with ALLOWED_ORIGINS environment variable for specific deployments
+ALLOWED_ORIGINS = os.getenv(
+    "ALLOWED_ORIGINS",
+    "http://localhost:3000,http://localhost:5173,http://localhost:5174,http://localhost:8000,http://127.0.0.1:8000"
+).split(",")
 
 app.add_middleware(
     CORSMiddleware,
@@ -82,8 +87,17 @@ async def health_check():
 
 
 # Mount static files for production (if they exist)
-static_dir = Path(__file__).parent / "static"
+# Priority order:
+# 1. api/static/ - Production (pip installed or built package)
+# 2. alchemist-web/dist/ - Development (after manual npm run build)
+api_static_dir = Path(__file__).parent / "static"
+dev_static_dir = Path(__file__).parent.parent / "alchemist-web" / "dist"
+
+# Use api/static if it exists (production), otherwise fall back to dev build
+static_dir = api_static_dir if api_static_dir.exists() else dev_static_dir
+
 if static_dir.exists():
+    logger.info(f"Serving static files from: {static_dir}")
     app.mount("/assets", StaticFiles(directory=str(static_dir / "assets")), name="assets")
     
     @app.get("/{full_path:path}")
@@ -104,6 +118,8 @@ if static_dir.exists():
             return FileResponse(index_path)
         
         return {"detail": "Not Found"}
+else:
+    logger.warning("Static files not found. Web UI will not be available. Run 'npm run build' in alchemist-web/ or install from built wheel.")
 
 
 if __name__ == "__main__":

api/models/requests.py

@@ -182,6 +182,36 @@ class FindOptimumRequest(BaseModel):
     )
 
 
+# ============================================================
+# Initial Design (DoE) Models
+# ============================================================
+
+class InitialDesignRequest(BaseModel):
+    """Request for generating initial experimental design."""
+    method: Literal["random", "lhs", "sobol", "halton", "hammersly"] = Field(
+        default="lhs",
+        description="Sampling method"
+    )
+    n_points: int = Field(default=10, ge=1, le=1000, description="Number of points to generate")
+    random_seed: Optional[int] = Field(None, description="Random seed for reproducibility")
+    lhs_criterion: str = Field(
+        default="maximin",
+        pattern="^(maximin|correlation|ratio)$",
+        description="Criterion for LHS method"
+    )
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "method": "lhs",
+                "n_points": 10,
+                "random_seed": 42,
+                "lhs_criterion": "maximin"
+            }
+        }
+    )
+
+
 # ============================================================
 # Prediction Models
 # ============================================================
@@ -200,3 +230,44 @@ class PredictionRequest(BaseModel):
             }
         }
     )
+
+
+# ============================================================
+# Audit Log & Session Management Models
+# ============================================================
+
+class UpdateMetadataRequest(BaseModel):
+    """Request to update session metadata."""
+    name: Optional[str] = Field(None, description="Session name")
+    description: Optional[str] = Field(None, description="Session description")
+    tags: Optional[List[str]] = Field(None, description="Session tags")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "name": "Catalyst_Screening_Nov2025",
+                "description": "Pt/Pd ratio optimization for CO2 reduction",
+                "tags": ["catalyst", "CO2", "electrochemistry"]
+            }
+        }
+    )
+
+
+class LockDecisionRequest(BaseModel):
+    """Request to lock in a decision to the audit log."""
+    lock_type: Literal["data", "model", "acquisition"] = Field(..., description="Type of decision to lock")
+    notes: Optional[str] = Field(None, description="Optional notes about this decision")
+    
+    # For acquisition lock
+    strategy: Optional[str] = Field(None, description="Acquisition strategy (required for acquisition lock)")
+    parameters: Optional[Dict[str, Any]] = Field(None, description="Acquisition parameters (required for acquisition lock)")
+    suggestions: Optional[List[Dict[str, Any]]] = Field(None, description="Suggested experiments (required for acquisition lock)")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "lock_type": "model",
+                "notes": "Best cross-validation performance: R²=0.93"
+            }
+        }
+    )