Configuration and Settings#

LensKit supports reading configuration files (lenskit.toml, lenskit.local.toml) for configuration. This is automatically done by the CLI, but can be manually done in your own programs as well.

Initializing Configuration#

Accessing Configuration#

lenskit.config.lenskit_config()#

Get the LensKit configuration.

If no configuration has been specified, returns a default settings object.

Return type:

LenskitSettings

Configuration Model#

class lenskit.config.LenskitSettings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, *, random=RandomSettings(seed=None), parallel=ParallelSettings(num_cpus=0, use_ray=False, num_batch_jobs=0, num_procs=0, num_threads=0, num_backend_threads=0), machine=None, prometheus=PrometheusSettings(url=None), machines={}, tuning=TuneSettings(jobs=None, gpu_mult=1.0, max_points=None), **values)#

Bases: BaseSettings

Definition of LensKit settings.

LensKit supports loading various settings from configuration files and the environment as a consistent way to control LensKit’s various control surfaces.

Stability:

Experimental

Parameters:

  • _case_sensitive (bool | None)

  • _nested_model_default_partial_update (bool | None)

  • _env_prefix (str | None)

  • _env_prefix_target (EnvPrefixTarget | None)

  • _env_file (DotenvType | None)

  • _env_file_encoding (str | None)

  • _env_ignore_empty (bool | None)

  • _env_nested_delimiter (str | None)

  • _env_nested_max_split (int | None)

  • _env_parse_none_str (str | None)

  • _env_parse_enums (bool | None)

  • _cli_prog_name (str | None)

  • _cli_parse_args (bool | list[str] | tuple[str, ...] | None)

  • _cli_settings_source (CliSettingsSource[Any] | None)

  • _cli_parse_none_str (str | None)

  • _cli_hide_none_type (bool | None)

  • _cli_avoid_json (bool | None)

  • _cli_enforce_required (bool | None)

  • _cli_use_class_docs_for_groups (bool | None)

  • _cli_exit_on_error (bool | None)

  • _cli_prefix (str | None)

  • _cli_flag_prefix_char (str | None)

  • _cli_implicit_flags (bool | Literal['dual', 'toggle'] | None)

  • _cli_ignore_unknown_args (bool | None)

  • _cli_kebab_case (bool | Literal['all', 'no_enums'] | None)

  • _cli_shortcuts (Mapping[str, str | list[str]] | None)

  • _secrets_dir (PathType | None)

  • _build_sources (tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None)

  • random (RandomSettings)

  • parallel (ParallelSettings)

  • machine (str | None)

  • prometheus (PrometheusSettings)

  • machines (dict[str, MachineSettings])

  • tuning (TuneSettings)

  • values (Any)

random: RandomSettings#

Random number generator configuration.

machine: str | None#

The name of the machine running experiments.

This is usually set in lenskit.local.toml or the LK_MACHINE environment variable.

prometheus: PrometheusSettings#

Prometheus settings for task metric collection.

machines: dict[str, MachineSettings]#

Description of different machines used in the experiment(s), to support things like collecting power metrics.

tuning: TuneSettings#

LensKit tuning settings.

classmethod settings_customise_sources(settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings)#

Define the sources and their order for loading the settings values.

Parameters:

  • settings_cls – The Settings class.

  • init_settings – The InitSettingsSource instance.

  • env_settings – The EnvSettingsSource instance.

  • dotenv_settings – The DotEnvSettingsSource instance.

  • file_secret_settings – The SecretsSettingsSource instance.

Returns:

A tuple containing the sources and their order for loading the settings values.

finish_setup()#

Finalize settings, resolving default values etc. as needed.

class lenskit.config.RandomSettings(*, seed=None)#

Bases: BaseModel

Random number generator configuration.

Parameters:

seed (int | None)

seed: int | None#

The root RNG seed.

class lenskit.config.ParallelSettings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, *, num_cpus=0, use_ray=False, num_batch_jobs=0, num_procs=0, num_threads=0, num_backend_threads=0)#

Bases: BaseSettings

Configuration for LensKit’s parallel processing. These settings are in the [parallel] table in lenskit.toml.

See also

Configuring Parallelism

Parameters:

  • _case_sensitive (bool | None)

  • _nested_model_default_partial_update (bool | None)

  • _env_prefix (str | None)

  • _env_prefix_target (EnvPrefixTarget | None)

  • _env_file (DotenvType | None)

  • _env_file_encoding (str | None)

  • _env_ignore_empty (bool | None)

  • _env_nested_delimiter (str | None)

  • _env_nested_max_split (int | None)

  • _env_parse_none_str (str | None)

  • _env_parse_enums (bool | None)

  • _cli_prog_name (str | None)

  • _cli_parse_args (bool | list[str] | tuple[str, ...] | None)

  • _cli_settings_source (CliSettingsSource[Any] | None)

  • _cli_parse_none_str (str | None)

  • _cli_hide_none_type (bool | None)

  • _cli_avoid_json (bool | None)

  • _cli_enforce_required (bool | None)

  • _cli_use_class_docs_for_groups (bool | None)

  • _cli_exit_on_error (bool | None)

  • _cli_prefix (str | None)

  • _cli_flag_prefix_char (str | None)

  • _cli_implicit_flags (bool | Literal['dual', 'toggle'] | None)

  • _cli_ignore_unknown_args (bool | None)

  • _cli_kebab_case (bool | Literal['all', 'no_enums'] | None)

  • _cli_shortcuts (Mapping[str, str | list[str]] | None)

  • _secrets_dir (PathType | None)

  • _build_sources (tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None)

  • num_cpus (int)

  • use_ray (bool)

  • num_batch_jobs (int)

  • num_procs (int)

  • num_threads (int)

  • num_backend_threads (int)

num_cpus: int#

The number of CPUs LensKit should consider using. This is auto-detected from the system environment, and should only be configured manually if you want to override LensKit’s CPU detection for some reason. Note that the auto-detected values do account for operating system scheduling affinities and CPU limits.

This value is not used directly as a limit, but is used to derive the default values for the other concurrency controls (threads, etc.).

use_ray: bool#

Use Ray to parallelize batch operations, hyperparameter tuning, etc.

num_batch_jobs: int#

Number of batch inference jobs to run in parallel. Can be overridden with the LK_NUM_BATCH_JOBS environment variable.

num_procs: int#

Number of processes to use.

num_threads: int#

Number of threads to use. Can be overridden with the LK_NUM_THREADS environment variable. Specify -1 to use all available threads.

num_backend_threads: int#

Number of threads for compute backends to use. Can be overridden with the LK_NUM_BACKEND_THREADS environment variable. Specify -1 to leave threading limits unmodified.

resolve_defaults()#

Resolve default values for thread/process counts.

env_vars()#

Get the parallel configuration as a set of environment variables to configure a child process. The set also includes OMP_NUM_THREADS and related variables for BLAS and MKL to configure OMP early.

Return type:

dict[str, str]

class lenskit.config.TuneSettings(*, jobs=None, gpu_mult=1.0, max_points=None)#

Bases: BaseModel

LensKit hyperparameter tuning settings.

Parameters:
jobs: int | None#

Number of allowed hyperparameter tuning jobs.

gpu_mult: Annotated[float, Gt(0), Le(1.0)]#

Multiplier for tuning job GPU requirements. This is to coarsely adapt GPU requirements from configuration files to the local machine. If a tuning specificataion requires 1 GPU, but your machine has enough capacity to run two jobs in parallel on a single GPU, you can set this to 0.5 to modify the tuning jobs to require 0.5 GPUs each.

max_points: int | None#

Maximum number of search points for hyperparameter tuning.

class lenskit.config.PrometheusSettings(*, url=None)#

Bases: BaseModel

Prometheus configuration settings.

LensKit’s task logging supports querying Prometheus for task-related metrics such as power consumption.

Parameters:

url (str | None)

class lenskit.config.MachineSettings(*, description=None, power_queries={}, **extra_data)#

Bases: BaseModel

Definition for a single machine.

A “machine” is a computer (or cluster) that is in use for running LensKit experiments. Many users won’t use this, but if you want to use the power consumption monitoring, you will need to define how to measure power for the different machines in use.

Parameters:

  • description (str | None)

  • power_queries (PowerQueries)

  • extra_data (Any)

description: str | None#

Short description for this machine.

power_queries: PowerQueries#

Prometheus queries to collect power metrics for this machine.