OptimizationConfig
==================

YAML configuration loader for optimization runs.

Loads and validates optimization configuration from YAML files,
supporting parameter spaces, recipe references, and settings.

See ADR-011 for architecture decisions.

Classes
-------

.. py:class:: ParameterSpec

   Specification for a parameter to optimize.
   
   Supports int, float, and categorical parameter types with
   ranges, steps, and choices.

   **Methods:**

   .. py:method:: from_dict()

      Create ParameterSpec from config dictionary.


.. py:class:: RecipeSpec

   Specification for a recipe to optimize.


.. py:class:: OptimizationConfig

   Complete optimization configuration.
   
   Loaded from YAML config files, this class contains all settings
   needed to run an optimization study.
   
   Example YAML:
       version: "1.0"
       name: "Tumor Optimization"
       settings:
         n_trials: 100
         sampler: "tpe"
         pruner: "hyperband"
       recipes:
         - path: "recipes/brain_tumor_1.py"
           gold_standard: "gold_standards/tumor.seg.nrrd"
       parameter_space:
         global:
           edge_sensitivity: {type: int, range: [20, 80], step: 10}

   **Methods:**

   .. py:method:: load()

      Load configuration from YAML file.

   .. py:method:: validate()

      Validate configuration.

   .. py:method:: to_dict()

      Convert to dictionary for serialization.

   .. py:method:: save()

      Save configuration to YAML file.


Functions
---------

.. py:function:: from_dict()

   Create ParameterSpec from config dictionary.
   
   Args:
       name: Parameter name.
       spec: Dictionary with type, range/choices, etc.
   
   Returns:
       ParameterSpec instance.

.. py:function:: load()

   Load configuration from YAML file.
   
   Args:
       config_path: Path to YAML config file.
   
   Returns:
       Loaded OptimizationConfig.
   
   Raises:
       FileNotFoundError: If config file doesn't exist.
       ValueError: If config is invalid.
       ImportError: If PyYAML is not installed.

.. py:function:: validate()

   Validate configuration.
   
   Returns:
       List of validation error messages (empty if valid).

.. py:function:: to_dict()

   Convert to dictionary for serialization.
   
   Returns:
       Configuration as dictionary.

.. py:function:: save()

   Save configuration to YAML file.
   
   Args:
       output_path: Path where to save config.
   
   Raises:
       ImportError: If PyYAML is not installed.

.. py:function:: create_default_config()

   Create a default optimization configuration.
   
   Returns:
       Default OptimizationConfig with reasonable settings.