mlos_bench.services.config_persistence
======================================

.. py:module:: mlos_bench.services.config_persistence

.. autoapi-nested-parse::

   Helper functions to load, instantiate, and serialize Python objects that encapsulate a
   benchmark :py:class:`.Environment`, :py:mod:`~mlos_bench.tunables`, :py:class:`.Service`
   functions, etc from JSON configuration files and strings.

   .. seealso::

      :py:obj:`mlos_bench.config`
          Overview of the configuration system.



Classes
-------

.. autoapisummary::

   mlos_bench.services.config_persistence.ConfigPersistenceService


Module Contents
---------------

.. py:class:: ConfigPersistenceService(config: dict[str, Any] | None = None, global_config: dict[str, Any] | None = None, parent: mlos_bench.services.base_service.Service | None = None, methods: dict[str, collections.abc.Callable] | list[collections.abc.Callable] | None = None)

   Bases: :py:obj:`mlos_bench.services.base_service.Service`, :py:obj:`mlos_bench.services.types.config_loader_type.SupportsConfigLoading`


   Collection of methods to deserialize the Environment, Service, and TunableGroups
   objects.

   Create a new instance of config persistence service.

   :param config: Free-format dictionary that contains parameters for the service.
                  (E.g., root path for config files, etc.)
   :type config: dict
   :param global_config: Free-format dictionary of global parameters.
   :type global_config: dict
   :param parent: An optional parent service that can provide mixin functions.
   :type parent: Service
   :param methods: New methods to register with the service.
   :type methods: dict[str, Callable] | list[Callable] | None


   .. py:method:: build_environment(config: dict[str, Any], tunables: mlos_bench.tunables.tunable_groups.TunableGroups, global_config: dict[str, Any] | None = None, parent_args: dict[str, mlos_bench.tunables.tunable_types.TunableValue] | None = None, service: mlos_bench.services.base_service.Service | None = None) -> mlos_bench.environments.base_environment.Environment

      Factory method for a new :py:class:`.Environment` with a given config.

      :param config:
                     A dictionary with three mandatory fields:
                         "name": Human-readable string describing the environment;
                         "class": FQN of a Python class to instantiate;
                         "config": Free-format dictionary to pass to the constructor.
      :type config: dict
      :param tunables: A (possibly empty) collection of groups of tunable parameters for
                       all environments.
      :type tunables: TunableGroups
      :param global_config: Global parameters to add to the environment config.
      :type global_config: dict
      :param parent_args: An optional reference of the parent CompositeEnv's const_args used to
                          expand dynamic config parameters from.
      :type parent_args: dict[str, TunableValue]
      :param service: An optional service object (e.g., providing methods to
                      deploy or reboot a VM, etc.).
      :type service: Service

      :returns: **env** -- An instance of the ``Environment`` class initialized with ``config``.
      :rtype: Environment



   .. py:method:: build_optimizer(*, tunables: mlos_bench.tunables.tunable_groups.TunableGroups, service: mlos_bench.services.base_service.Service, config: dict[str, Any], global_config: dict[str, Any] | None = None) -> mlos_bench.optimizers.base_optimizer.Optimizer

      Instantiation of :py:mod:`mlos_bench` :py:class:`.Optimizer` that depend on
      :py:class:`.Service` and :py:class:`.TunableGroups`.

      :param tunables: Tunable parameters of the environment. We need them to validate the
                       configurations of merged-in experiments and restored/pending trials.
      :type tunables: TunableGroups
      :param service: An optional service object (e.g., providing methods to load config files, etc.)
      :type service: Service
      :param config: Configuration of the class to instantiate, as loaded from JSON.
      :type config: dict
      :param global_config: Global configuration parameters (optional).
      :type global_config: dict

      :returns: **inst** -- A new instance of the `Optimizer` class.
      :rtype: Optimizer



   .. py:method:: build_scheduler(*, config: dict[str, Any], global_config: dict[str, Any], trial_runners: list[mlos_bench.schedulers.trial_runner.TrialRunner], optimizer: mlos_bench.optimizers.base_optimizer.Optimizer, storage: mlos_bench.storage.base_storage.Storage, root_env_config: str) -> mlos_bench.schedulers.base_scheduler.Scheduler

      Instantiation of mlos_bench :py:class:`.Scheduler`.

      :param config: Configuration of the class to instantiate, as loaded from JSON.
      :type config: dict
      :param global_config: Global configuration parameters.
      :type global_config: dict
      :param trial_runners: The TrialRunners (Environments) to use.
      :type trial_runners: List[TrialRunner]
      :param optimizer: The optimizer to use.
      :type optimizer: Optimizer
      :param storage: The storage to use.
      :type storage: Storage
      :param root_env_config: Path to the root environment configuration.
      :type root_env_config: str

      :returns: **inst** -- A new instance of the Scheduler.
      :rtype: Scheduler



   .. py:method:: build_service(config: dict[str, Any], global_config: dict[str, Any] | None = None, parent: mlos_bench.services.base_service.Service | None = None) -> mlos_bench.services.base_service.Service

      Factory method for a new service with a given config.

      :param config:
                     A dictionary with 2 mandatory fields:
                         "class": FQN of a Python class to instantiate;
                         "config": Free-format dictionary to pass to the constructor.
      :type config: dict
      :param global_config: Global parameters to add to the service config.
      :type global_config: dict
      :param parent: An optional reference of the parent service to mix in.
      :type parent: Service

      :returns: **svc** -- An instance of the `Service` class that is a combination of all
                services from the list plus the parent mix-in.
      :rtype: Service



   .. py:method:: build_storage(*, service: mlos_bench.services.base_service.Service, config: dict[str, Any], global_config: dict[str, Any] | None = None) -> mlos_bench.storage.base_storage.Storage

      Instantiation of mlos_bench :py:class:`.Storage` objects.

      :param service: An optional service object (e.g., providing methods to load config files, etc.)
      :type service: Service
      :param config: Configuration of the class to instantiate, as loaded from JSON.
      :type config: dict
      :param global_config: Global configuration parameters (optional).
      :type global_config: dict

      :returns: **inst** -- A new instance of the Storage class.
      :rtype: Storage



   .. py:method:: get_config_paths() -> list[str]

      Gets the list of config paths this service will search for config files.

      :rtype: list[str]



   .. py:method:: load_config(json: str, schema_type: mlos_bench.config.schemas.config_schemas.ConfigSchema | None) -> dict[str, Any]

      Load JSON config file or JSON string. Search for a file relative to
      :py:attr:`.config_paths` if the input path is not absolute. This method is
      exported to be used as a :py:class:`.SupportsConfigLoading` type
      :py:class:`.Service`.

      :param json: Path to the input config file or a JSON string.
      :type json: str
      :param schema_type: The schema type to validate the config against.
      :type schema_type: ConfigSchema | None

      :returns: **config** -- Free-format dictionary that contains the configuration.
      :rtype: dict | list[dict]



   .. py:method:: load_environment(json: str, tunables: mlos_bench.tunables.tunable_groups.TunableGroups, global_config: dict[str, Any] | None = None, parent_args: dict[str, mlos_bench.tunables.tunable_types.TunableValue] | None = None, service: mlos_bench.services.base_service.Service | None = None) -> mlos_bench.environments.base_environment.Environment

      Load and build new :py:class:`.Environment` from the config file or JSON string.

      :param json: The environment JSON configuration file or JSON string.
      :type json: str
      :param tunables: A (possibly empty) collection of tunables to add to the environment.
      :type tunables: TunableGroups
      :param global_config: Global parameters to add to the environment config.
      :type global_config: dict
      :param parent_args: An optional reference of the parent CompositeEnv's const_args used to
                          expand dynamic config parameters from.
      :type parent_args: dict[str, TunableValue]
      :param service: An optional reference of the parent service to mix in.
      :type service: Service

      :returns: **env** -- A new benchmarking environment.
      :rtype: Environment

      .. seealso::

         :py:obj:`mlos_bench.environments`
             Examples of environment configurations.



   .. py:method:: load_environment_list(json: str, tunables: mlos_bench.tunables.tunable_groups.TunableGroups, global_config: dict[str, Any] | None = None, parent_args: dict[str, mlos_bench.tunables.tunable_types.TunableValue] | None = None, service: mlos_bench.services.base_service.Service | None = None) -> list[mlos_bench.environments.base_environment.Environment]

      Load and build a list of Environments from the config file or JSON string.

      :param json: The environment JSON configuration file or a JSON string.
                   Can contain either one environment or a list of environments.
      :type json: str
      :param tunables: An (possibly empty) collection of tunables to add to the environment.
      :type tunables: TunableGroups
      :param global_config: Global parameters to add to the environment config.
      :type global_config: dict
      :param service: An optional reference of the parent service to mix in.
      :type service: Service
      :param parent_args: An optional reference of the parent CompositeEnv's const_args used to
                          expand dynamic config parameters from.
      :type parent_args: dict[str, TunableValue]

      :returns: **env** -- A list of new benchmarking environments.
      :rtype: list[Environment]

      .. seealso::

         :py:obj:`mlos_bench.environments`
             Examples of environment configurations.



   .. py:method:: load_services(jsons: collections.abc.Iterable[str], global_config: dict[str, Any] | None = None, parent: mlos_bench.services.base_service.Service | None = None) -> mlos_bench.services.base_service.Service

      Read the configuration files or JSON strings and bundle all Service methods from
      those configs into a single Service object.

      .. rubric:: Notes

      Order of the services in the list matters. If multiple Services export the
      same method, the last one in the list will be used.

      :param jsons: A list of service JSON configuration files or JSON strings.
      :type jsons: list of str
      :param global_config: Global parameters to add to the service config.
      :type global_config: dict
      :param parent: An optional reference of the parent service to mix in.
      :type parent: Service

      :returns: **service** -- A collection of service methods.
      :rtype: Service

      .. seealso::

         :py:obj:`mlos_bench.services`
             Examples of service configurations.



   .. py:method:: load_tunables(jsons: collections.abc.Iterable[str], parent: mlos_bench.tunables.tunable_groups.TunableGroups | None = None) -> mlos_bench.tunables.tunable_groups.TunableGroups

      Load a collection of tunable parameters from JSON files or strings into the
      parent TunableGroup.

      This helps allow standalone environment configs to reference
      overlapping tunable groups configs but still allow combining them into
      a single instance that each environment can reference.

      :param jsons: A list of JSON files or JSON strings to load.
      :type jsons: list of str
      :param parent: A (possibly empty) collection of tunables to add to the new collection.
      :type parent: TunableGroups

      :returns: **tunables** -- The larger collection of tunable parameters.
      :rtype: TunableGroups

      .. seealso::

         :py:obj:`mlos_bench.tunables`
             Examples of tunable parameter configurations.



   .. py:method:: prepare_class_load(config: dict[str, Any], global_config: dict[str, Any] | None = None, parent_args: dict[str, mlos_bench.tunables.tunable_types.TunableValue] | None = None) -> tuple[str, dict[str, Any]]

      Extract the class instantiation parameters from the configuration. Mix-in the
      global parameters and resolve the local file system paths, where it is required.

      :param config: Configuration of the optimizer.
      :type config: dict
      :param global_config: Global configuration parameters (optional).
      :type global_config: dict
      :param parent_args: An optional reference of the parent CompositeEnv's const_args used to
                          expand dynamic config parameters from.
      :type parent_args: dict[str, TunableValue]

      :returns: **(class_name, class_config)** -- Name of the class to instantiate and its configuration.
      :rtype: (str, dict)



   .. py:method:: resolve_path(file_path: str, extra_paths: collections.abc.Iterable[str] | None = None) -> str

      Resolves and prepends the suitable :py:attr:`.config_paths` to ``file_path`` if
      the latter is not absolute. If :py:attr:`.config_paths` is ``None`` or
      ``file_path`` is absolute, return ``file_path`` as is.

      :param file_path: Path to the input config file.
      :type file_path: str
      :param extra_paths: Additional directories to prepend to the list of
                          :py:attr:`.config_paths` search paths.
      :type extra_paths: Iterable[str]

      :returns: **path** -- An actual path to the config or script.
      :rtype: str



   .. py:attribute:: BUILTIN_CONFIG_PATH
      :value: ''


      A calculated path to the built-in configuration files shipped with the mlos_bench
      package.


   .. py:property:: config_paths
      :type: list[str]


      Gets the list of config paths this service will search for config files.

      :rtype: list[str]