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

api/models/responses.py

@@ -88,6 +88,31 @@ class SessionInfoResponse(BaseModel):
     )
 
 
+class SessionStateResponse(BaseModel):
+    """Current state of an optimization session for monitoring."""
+    session_id: str
+    n_variables: int
+    n_experiments: int
+    model_trained: bool
+    model_backend: Optional[str] = None
+    last_suggestion: Optional[Dict[str, Any]] = None
+    last_acquisition_value: Optional[float] = None
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "session_id": "550e8400-e29b-41d4-a716-446655440000",
+                "n_variables": 2,
+                "n_experiments": 15,
+                "model_trained": True,
+                "model_backend": "botorch",
+                "last_suggestion": {"temperature": 385.2, "flow_rate": 4.3},
+                "last_acquisition_value": 0.025
+            }
+        }
+    )
+
+
 # ============================================================
 # Variable Models
 # ============================================================
@@ -112,6 +137,11 @@ class ExperimentResponse(BaseModel):
     """Response when adding an experiment."""
     message: str = "Experiment added successfully"
     n_experiments: int
+    model_trained: bool = Field(default=False, description="Whether model was auto-trained")
+    training_metrics: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Training metrics if auto-train was enabled"
+    )
 
 
 class ExperimentsListResponse(BaseModel):
@@ -146,6 +176,30 @@ class ExperimentsSummaryResponse(BaseModel):
     )
 
 
+# ============================================================
+# Initial Design (DoE) Models
+# ============================================================
+
+class InitialDesignResponse(BaseModel):
+    """Response containing generated initial design points."""
+    points: List[Dict[str, Any]] = Field(..., description="Generated experimental points")
+    method: str = Field(..., description="Sampling method used")
+    n_points: int = Field(..., description="Number of points generated")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "points": [
+                    {"temperature": 350.2, "flow_rate": 2.47},
+                    {"temperature": 421.8, "flow_rate": 7.92}
+                ],
+                "method": "lhs",
+                "n_points": 2
+            }
+        }
+    )
+
+
 # ============================================================
 # Model Training Models
 # ============================================================
@@ -290,3 +344,116 @@ class ErrorResponse(BaseModel):
             }
         }
     )
+
+
+# ============================================================
+# Audit Log & Session Management Responses
+# ============================================================
+
+class SessionMetadataResponse(BaseModel):
+    """Response containing session metadata."""
+    session_id: str
+    name: str
+    created_at: str
+    last_modified: str
+    description: str
+    tags: List[str]
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "session_id": "550e8400-e29b-41d4-a716-446655440000",
+                "name": "Catalyst_Screening_Nov2025",
+                "created_at": "2025-11-19T09:00:00",
+                "last_modified": "2025-11-19T14:30:00",
+                "description": "Pt/Pd ratio optimization",
+                "tags": ["catalyst", "CO2"]
+            }
+        }
+    )
+
+
+class AuditEntryResponse(BaseModel):
+    """Response containing a single audit log entry."""
+    timestamp: str
+    entry_type: str
+    parameters: Dict[str, Any]
+    hash: str
+    notes: str
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "timestamp": "2025-11-19T09:15:00",
+                "entry_type": "data_locked",
+                "parameters": {
+                    "n_experiments": 15,
+                    "variables": [],
+                    "data_hash": "abc123"
+                },
+                "hash": "a1b2c3d4",
+                "notes": "Initial screening dataset"
+            }
+        }
+    )
+
+
+class AuditLogResponse(BaseModel):
+    """Response containing complete audit log."""
+    entries: List[AuditEntryResponse]
+    n_entries: int
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "entries": [],
+                "n_entries": 0
+            }
+        }
+    )
+
+
+class LockDecisionResponse(BaseModel):
+    """Response after locking a decision."""
+    success: bool
+    entry: AuditEntryResponse
+    message: str
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "success": True,
+                "entry": {
+                    "timestamp": "2025-11-19T09:15:00",
+                    "entry_type": "data_locked",
+                    "parameters": {},
+                    "hash": "a1b2c3d4",
+                    "notes": ""
+                },
+                "message": "Data decision locked successfully"
+            }
+        }
+    )
+
+
+# ============================================================
+# 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

@@ -2,9 +2,14 @@
 Experiments router - Experimental data management.
 """
 
-from fastapi import APIRouter, Depends, UploadFile, File
-from ..models.requests import AddExperimentRequest, AddExperimentsBatchRequest
-from ..models.responses import ExperimentResponse, ExperimentsListResponse, ExperimentsSummaryResponse
+from fastapi import APIRouter, Depends, UploadFile, File, Query
+from ..models.requests import AddExperimentRequest, AddExperimentsBatchRequest, InitialDesignRequest
+from ..models.responses import (
+    ExperimentResponse, 
+    ExperimentsListResponse, 
+    ExperimentsSummaryResponse,
+    InitialDesignResponse
+)
 from ..dependencies import get_session
 from ..middleware.error_handlers import NoVariablesError
 from alchemist_core.session import OptimizationSession
@@ -12,6 +17,7 @@ import logging
 import pandas as pd
 import tempfile
 import os
+from typing import Optional
 
 logger = logging.getLogger(__name__)
 
@@ -22,6 +28,9 @@ router = APIRouter()
 async def add_experiment(
     session_id: str,
     experiment: AddExperimentRequest,
+    auto_train: bool = Query(False, description="Auto-train model after adding data"),
+    training_backend: Optional[str] = Query(None, description="Model backend (sklearn/botorch)"),
+    training_kernel: Optional[str] = Query(None, description="Kernel type (rbf/matern)"),
     session: OptimizationSession = Depends(get_session)
 ):
     """
@@ -29,6 +38,11 @@ async def add_experiment(
     
     The experiment must include values for all defined variables.
     Output value is optional for candidate experiments.
+    
+    Args:
+        auto_train: If True, retrain model after adding data
+        training_backend: Model backend (uses last if None)
+        training_kernel: Kernel type (uses last or 'rbf' if None)
     """
     # Check if variables are defined
     if len(session.search_space.variables) == 0:
@@ -37,15 +51,56 @@ 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 (need at least 5 points to train)
+    model_trained = False
+    training_metrics = None
+    
+    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
+    
     return ExperimentResponse(
         message="Experiment added successfully",
-        n_experiments=n_experiments
+        n_experiments=n_experiments,
+        model_trained=model_trained,
+        training_metrics=training_metrics
     )
 
 
@@ -53,12 +108,20 @@ async def add_experiment(
 async def add_experiments_batch(
     session_id: str,
     batch: AddExperimentsBatchRequest,
+    auto_train: bool = Query(False, description="Auto-train model after adding data"),
+    training_backend: Optional[str] = Query(None, description="Model backend (sklearn/botorch)"),
+    training_kernel: Optional[str] = Query(None, description="Kernel type (rbf/matern)"),
     session: OptimizationSession = Depends(get_session)
 ):
     """
     Add multiple experiments at once.
     
     Useful for bulk data import or initialization.
+    
+    Args:
+        auto_train: If True, retrain model after adding data
+        training_backend: Model backend (uses last if None)
+        training_kernel: Kernel type (uses last or 'rbf' if None)
     """
     # Check if variables are defined
     if len(session.search_space.variables) == 0:
@@ -74,9 +137,74 @@ async def add_experiments_batch(
     n_experiments = len(session.experiment_manager.df)
     logger.info(f"Added {len(batch.experiments)} experiments to session {session_id}. Total: {n_experiments}")
     
+    # Auto-train if requested
+    model_trained = False
+    training_metrics = None
+    
+    if auto_train and n_experiments >= 5:  # Minimum data for training
+        try:
+            backend = training_backend or (session.model_backend if session.model else "sklearn")
+            kernel = training_kernel or "rbf"
+            
+            result = session.train_model(backend=backend, kernel=kernel)
+            model_trained = True
+            metrics = result.get("metrics", {})
+            training_metrics = {
+                "rmse": metrics.get("rmse"),
+                "r2": metrics.get("r2"),
+                "backend": backend
+            }
+            logger.info(f"Auto-trained model for session {session_id}: {training_metrics}")
+        except Exception as e:
+            logger.error(f"Auto-train failed for session {session_id}: {e}")
+    
     return ExperimentResponse(
         message=f"Added {len(batch.experiments)} experiments successfully",
-        n_experiments=n_experiments
+        n_experiments=n_experiments,
+        model_trained=model_trained,
+        training_metrics=training_metrics
+    )
+
+
+@router.post("/{session_id}/initial-design", response_model=InitialDesignResponse)
+async def generate_initial_design(
+    session_id: str,
+    request: InitialDesignRequest,
+    session: OptimizationSession = Depends(get_session)
+):
+    """
+    Generate initial experimental design (DoE) for autonomous operation.
+    
+    Generates space-filling experimental designs before Bayesian optimization begins.
+    Useful for autonomous controllers to get initial points to evaluate.
+    
+    Methods:
+    - random: Random sampling
+    - lhs: Latin Hypercube Sampling (space-filling)
+    - sobol: Sobol sequence (quasi-random)
+    - halton: Halton sequence (quasi-random)
+    - hammersly: Hammersly sequence (quasi-random)
+    
+    Returns list of experiments (input combinations) to evaluate.
+    """
+    # Check if variables are defined
+    if len(session.search_space.variables) == 0:
+        raise NoVariablesError("No variables defined. Add variables to search space first.")
+    
+    # Generate design
+    design_points = session.generate_initial_design(
+        method=request.method,
+        n_points=request.n_points,
+        random_seed=request.random_seed,
+        lhs_criterion=request.lhs_criterion
+    )
+    
+    logger.info(f"Generated {len(design_points)} initial design points using {request.method} for session {session_id}")
+    
+    return InitialDesignResponse(
+        points=design_points,
+        method=request.method,
+        n_points=len(design_points)
     )