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. 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.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.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 .. 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.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] .. 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 .. 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 .. py:method:: prepare_class_load(config: dict[str, Any], global_config: dict[str, Any] | None = None, parent_args: dict[str, mlos_bench.tunables.tunable.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]