Audit log¶

Session metadata and the audit trail.

audit_log ¶

Audit Log - Append-only logging for reproducible optimization workflows.

This module provides structured logging of optimization decisions to ensure research reproducibility and traceability. The audit log captures: - Experimental data lock-ins - Model training decisions - Acquisition function choices

Users can explore freely without spamming the log; only explicit "lock-in" actions create audit entries.

SessionMetadata `dataclass` ¶

SessionMetadata(session_id: str, name: str, created_at: str, last_modified: str, description: str = '', author: str = '', tags: List[str] = list())

Session metadata for user-friendly session management.

Attributes:

Name	Type	Description
`session_id`	`str`	Unique session identifier (UUID)
`name`	`str`	User-friendly session name
`created_at`	`str`	ISO timestamp of session creation
`last_modified`	`str`	ISO timestamp of last modification
`description`	`str`	Optional detailed description
`author`	`str`	Optional author name
`tags`	`List[str]`	Optional list of tags for organization

create `staticmethod` ¶

create(name: str = 'Untitled Session', description: str = '', tags: Optional[List[str]] = None) -> SessionMetadata

Create new session metadata.

Parameters:

Name	Type	Description	Default
`name`	`str`	User-friendly session name	`'Untitled Session'`
`description`	`str`	Optional description	`''`
`tags`	`Optional[List[str]]`	Optional tags for organization	`None`

Returns:

Type	Description
`SessionMetadata`	SessionMetadata instance

update_modified ¶

update_modified()

Update last_modified timestamp to now.

to_dict ¶

to_dict() -> Dict[str, Any]

Export to dictionary.

from_dict `staticmethod` ¶

from_dict(data: Dict[str, Any]) -> SessionMetadata

Import from dictionary.

AuditEntry `dataclass` ¶

AuditEntry(timestamp: str, entry_type: str, parameters: Dict[str, Any], hash: str, notes: str = '')

Single audit log entry.

Attributes:

Name	Type	Description
`timestamp`	`str`	ISO timestamp of entry creation
`entry_type`	`str`	Type of decision ('data_locked', 'model_locked', 'acquisition_locked')
`parameters`	`Dict[str, Any]`	Complete snapshot of decision parameters
`hash`	`str`	Reproducibility checksum (SHA256 of parameters)
`notes`	`str`	Optional user notes

create `staticmethod` ¶

create(entry_type: str, parameters: Dict[str, Any], notes: str = '') -> AuditEntry

Create new audit entry with auto-generated timestamp and hash.

Parameters:

Name	Type	Description	Default
`entry_type`	`str`	Type of entry ('data_locked', 'model_locked', 'acquisition_locked')	required
`parameters`	`Dict[str, Any]`	Parameters to log	required
`notes`	`str`	Optional user notes	`''`

Returns:

Type	Description
`AuditEntry`	AuditEntry instance

to_dict ¶

to_dict() -> Dict[str, Any]

Export to dictionary.

from_dict `staticmethod` ¶

from_dict(data: Dict[str, Any]) -> AuditEntry

Import from dictionary.

AuditLog ¶

AuditLog()

Append-only audit log for optimization decisions.

This class maintains a complete, immutable history of optimization decisions to ensure reproducibility and traceability. Only explicit "lock-in" actions add entries, preventing log spam from exploration activities.

The audit log is structured with: - Search space definition (set once) - Experimental data table (updated with each lock) - Optimization iterations (model + acquisition per iteration)

Initialize empty audit log.

set_search_space ¶

set_search_space(variables: List[Dict[str, Any]])

Set the search space definition (should only be called once).

Parameters:

Name	Type	Description	Default
`variables`	`List[Dict[str, Any]]`	List of variable definitions	required

lock_data ¶

lock_data(experiment_data: DataFrame, notes: str = '', extra_parameters: Optional[Dict[str, Any]] = None) -> AuditEntry

Lock in experimental data snapshot.

Parameters:

Name	Type	Description	Default
`experiment_data`	`DataFrame`	DataFrame with all experimental data including Iteration and Reason	required
`notes`	`str`	Optional user notes	`''`

Returns:

Type	Description
`AuditEntry`	Created AuditEntry

lock_model ¶

lock_model(backend: str, kernel: str, hyperparameters: Dict[str, Any], cv_metrics: Optional[Dict[str, float]] = None, iteration: Optional[int] = None, notes: str = '') -> AuditEntry

Lock in trained model configuration.

Parameters:

Name	Type	Description	Default
`backend`	`str`	Model backend ('sklearn', 'botorch')	required
`kernel`	`str`	Kernel type	required
`hyperparameters`	`Dict[str, Any]`	Learned hyperparameters	required
`cv_metrics`	`Optional[Dict[str, float]]`	Cross-validation metrics (optional)	`None`
`iteration`	`Optional[int]`	Iteration number (optional)	`None`
`notes`	`str`	Optional user notes	`''`

Returns:

Type	Description
`AuditEntry`	Created AuditEntry

lock_acquisition ¶

lock_acquisition(strategy: str, parameters: Dict[str, Any], suggestions: List[Dict[str, Any]], iteration: Optional[int] = None, notes: str = '') -> AuditEntry

Lock in acquisition function decision.

Parameters:

Name	Type	Description	Default
`strategy`	`str`	Acquisition strategy name	required
`parameters`	`Dict[str, Any]`	Acquisition function parameters	required
`suggestions`	`List[Dict[str, Any]]`	Suggested next experiments	required
`iteration`	`Optional[int]`	Iteration number (optional)	`None`
`notes`	`str`	Optional user notes	`''`

Returns:

Type	Description
`AuditEntry`	Created AuditEntry

log_event ¶

log_event(entry_type: str, parameters: Dict[str, Any], notes: str = '') -> AuditEntry

Append a generic audit entry.

Unlike the lock_* helpers this records an arbitrary event type. Used for cross-cutting provenance events such as objective-label changes.

log_config_change ¶

log_config_change(component: str, old: Dict[str, Any], new: Dict[str, Any], iteration: Optional[int] = None) -> AuditEntry

Record a mid-campaign optimizer-config change for provenance.

component: 'model' or 'acquisition' (opaque label; ALchemist-generic). old/new: config snapshots before/after the applied change. iteration: ALchemist iteration counter (no reactor-cycle concept here).

get_entries ¶

get_entries(entry_type: Optional[str] = None) -> List[AuditEntry]

Get audit entries, optionally filtered by type.

Parameters:

Name	Type	Description	Default
`entry_type`	`Optional[str]`	Optional filter ('data_locked', 'model_locked', 'acquisition_locked')	`None`

Returns:

Type	Description
`List[AuditEntry]`	List of AuditEntry objects

get_latest ¶

get_latest(entry_type: str) -> Optional[AuditEntry]

Get most recent entry of specified type.

Parameters:

Name	Type	Description	Default
`entry_type`	`str`	Entry type to find	required

Returns:

Type	Description
`Optional[AuditEntry]`	Latest AuditEntry or None if not found

clear ¶

clear()

Clear all entries (use with caution - breaks immutability contract).

This should only be used when starting a completely new optimization campaign within the same session.

to_dict ¶

to_dict() -> List[Dict[str, Any]]

Export audit log to dictionary format.

Returns:

Type	Description
`List[Dict[str, Any]]`	Dictionary with search_space, experiment_data, and entries

from_dict ¶

from_dict(data: Union[List[Dict[str, Any]], Dict[str, Any]])

Import audit log from dictionary format.

Parameters:

Name	Type	Description	Default
`data`	`Union[List[Dict[str, Any]], Dict[str, Any]]`	Dictionary with entries (and optionally search_space and experiment_data) or legacy list of entry dictionaries	required

to_markdown ¶

to_markdown(session_metadata: Optional[Dict[str, Any]] = None) -> str

Export audit log to markdown format for publications.

Parameters:

Name	Type	Description	Default
`session_metadata`	`Optional[Dict[str, Any]]`	Optional dictionary of session metadata (name, description, tags, created_at, etc.)	`None`

Returns:

Type	Description
`str`	Markdown-formatted audit trail with session metadata, search space, data table, and iterations

Audit log¶

audit_log ¶

SessionMetadata dataclass ¶

create staticmethod ¶

update_modified ¶

to_dict ¶

from_dict staticmethod ¶

AuditEntry dataclass ¶

create staticmethod ¶

to_dict ¶

from_dict staticmethod ¶

AuditLog ¶

set_search_space ¶

lock_data ¶

lock_model ¶

lock_acquisition ¶

log_event ¶

log_config_change ¶

get_entries ¶

get_latest ¶

clear ¶

to_dict ¶

from_dict ¶

to_markdown ¶

SessionMetadata `dataclass` ¶

create `staticmethod` ¶

from_dict `staticmethod` ¶

AuditEntry `dataclass` ¶

create `staticmethod` ¶

from_dict `staticmethod` ¶