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#

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_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 | None)

  • _cli_ignore_unknown_args (bool | None)

  • _cli_kebab_case (bool | None)

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

  • _secrets_dir (PathType | None)

  • random (RandomSettings)

  • machine (str | None)

  • prometheus (PrometheusSettings)

  • machines (dict[str, MachineSettings])

  • tune (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.

tune: 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.

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.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.

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

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.