Implementation:LMCache LMCache Config Base

Knowledge Sources	LMCache
Domains	Configuration Management, Software Architecture
Last Updated	2026-02-09 00:00 GMT

Overview

This module provides the base configuration infrastructure for all LMCache configuration systems, including dynamic class generation, environment/file/dict loading, and remote config support.

Description

The config_base.py module is the foundation of LMCache's configuration system. Its central function, create_config_class, dynamically generates dataclass-based configuration classes from declarative definitions, with built-in support for loading from environment variables, YAML files, dictionaries, and JSON. Each generated class tracks which keys were explicitly set by the user vs. defaulted, supports deprecated configuration aliases with migration warnings, and provides serialization methods. The module also includes: create_singleton_config for thread-safe singleton configuration access with double-checked locking; load_config_with_overrides for layered configuration loading (file -> env -> overrides); fetch_remote_config and apply_remote_configs for fetching and applying configuration from a remote config service; and various parsing utilities for converting strings to typed lists, booleans, and quoted strings.

Usage

This module is imported by lmcache.v1.config and lmcache.v1.cache_controller.config to define LMCacheEngineConfig and ControllerConfig respectively. It is used by calling create_config_class with configuration definitions, then using the resulting class's from_env(), from_file(), or from_defaults() factory methods.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/config_base.py
• Lines: 1-792

Signature

def create_config_class(
    config_name: str,
    config_definitions: dict[str, dict[str, Any]],
    config_aliases: Optional[dict[str, str]] = None,
    deprecated_configs: Optional[dict[str, str]] = None,
    namespace_extras: Optional[dict[str, Any]] = None,
    env_prefix: str = "LMCACHE_",
) -> type: ...

def create_singleton_config(
    getter_func_name: str,
    config_class,
    config_env_var: str = "LMCACHE_CONFIG_FILE",
) -> SingletonGetter: ...

def load_config_with_overrides(
    config_class,
    config_file_env_var: str = "LMCACHE_CONFIG_FILE",
    config_file_path: Optional[str] = None,
    overrides: Optional[Dict[str, Any]] = None,
) -> Any: ...

def parse_command_line_extra_params(extra_args: list[str]) -> dict[str, Any]: ...

def validate_and_set_config_value(
    config, config_key, value, override: bool = True
) -> bool: ...

def fetch_remote_config(
    remote_config_url: str,
    app_id: Optional[str],
    config: Any,
    timeout: int = 10,
) -> Optional[dict]: ...

def apply_remote_configs(config: Any, remote_response: dict) -> Any: ...

# Parsing utilities
def _parse_local_disk(local_disk) -> Optional[str]: ...
def _to_int_list(value) -> Optional[list[int]]: ...
def _to_float_list(value) -> Optional[list[float]]: ...
def _to_str_list(value) -> Optional[list[str]]: ...
def _to_bool(value) -> bool: ...
def _parse_quoted_string(value: str) -> str: ...
def _to_json(obj: Any) -> str: ...
def _from_json(cls, json_str: str): ...

Import

from lmcache.v1.config_base import (
    create_config_class,
    create_singleton_config,
    load_config_with_overrides,
    parse_command_line_extra_params,
    validate_and_set_config_value,
    fetch_remote_config,
    apply_remote_configs,
)

I/O Contract

Inputs

Name	Type	Required	Description
config_name	str	Yes	Name for the dynamically created configuration class
config_definitions	dict[str, dict[str, Any]]	Yes	Dictionary mapping config key names to their type, default, and env_converter
config_aliases	Optional[dict[str, str]]	No	Mapping of deprecated config names to their current equivalents
deprecated_configs	Optional[dict[str, str]]	No	Mapping of deprecated names to deprecation warning messages
env_prefix	str	No	Environment variable prefix (default "LMCACHE_")
config_file_path	Optional[str]	No	Path to a YAML configuration file
overrides	Optional[Dict[str, Any]]	No	Dictionary of configuration overrides to apply after loading
remote_config_url	str	Yes (for remote)	URL of the remote configuration service

Outputs

Name	Type	Description
config_class	type (dataclass)	Dynamically generated configuration dataclass with from_env, from_file, from_dict, from_defaults, to_dict, to_json, and from_json methods
SingletonGetter	callable	Thread-safe singleton getter function with a reset() method for testing
config	Any	Loaded configuration instance after overrides and validation
dict	dict	Parsed command-line extra parameters or remote configuration response

Usage Examples

from lmcache.v1.config_base import create_config_class, create_singleton_config

# Define configuration
MY_CONFIG_DEFINITIONS = {
    "host": {"type": str, "default": "localhost", "env_converter": str},
    "port": {"type": int, "default": 8080, "env_converter": int},
    "debug": {"type": bool, "default": False, "env_converter": lambda v: str(v).lower() == "true"},
}

# Create the config class
MyConfig = create_config_class("MyConfig", MY_CONFIG_DEFINITIONS)

# Load from environment variables
config = MyConfig.from_env()

# Load from YAML file
config = MyConfig.from_file("/path/to/config.yaml")

# Create a singleton accessor
get_config = create_singleton_config("get_my_config", MyConfig)
config = get_config()  # Thread-safe singleton