Plugin (Custom / External)#

Two L2 adapter types load an adapter class from a user-supplied Python module at startup, so you can point LMCache at your own storage backend without modifying LMCache source. This is the --l2-adapter analog of vLLM’s kv_connector_module_path.

  • plugin: loads a pure-Python class that implements L2AdapterInterface (the full L2 adapter contract).

  • native_plugin: loads a pybind-wrapped C++ connector exposing a six-method async batch contract and wraps it in NativeConnectorL2Adapter. Use this for native backends – see also Adding Native Backends.

plugin#

Dynamically imports module_path and instantiates class_name, which must be a subclass of L2AdapterInterface (validated at load time; a mismatch raises TypeError).

Required fields:

  • module_path (str): Dotted Python import path of the module containing the adapter class. The module must be importable by the LMCache process (installed, or on PYTHONPATH).

  • class_name (str): Name of the class inside module_path that implements L2AdapterInterface.

Optional fields:

  • adapter_params (dict, default {}): Arbitrary dict forwarded to the adapter constructor.

  • config_class_name (str): Name of a config class inside module_path that subclasses L2AdapterConfigBase. When set (or auto-discovered), the factory builds it via from_dict(adapter_params) and passes the config object – instead of the raw adapter_params dict – to the adapter constructor, matching the built-in adapter convention. Discovery order when omitted: <class_name>Config in the module, then a config_class_name attribute on the adapter class; otherwise the raw dict is passed.

Configuration examples:

# Raw-dict mode: adapter_params is passed straight to the constructor
--l2-adapter '{"type": "plugin", "module_path": "my_plugin.l2", "class_name": "MyL2Adapter", "adapter_params": {"host": "localhost"}}'

# Config-class mode: my_plugin.l2.MyL2AdapterConfig.from_dict(adapter_params) is built and passed
--l2-adapter '{"type": "plugin", "module_path": "my_plugin.l2", "class_name": "MyL2Adapter", "config_class_name": "MyL2AdapterConfig", "adapter_params": {"host": "localhost"}}'

See examples/lmc_external_l2_adapter/ for a complete reference plugin.

native_plugin#

Dynamically imports module_path, instantiates class_name with adapter_params as constructor keyword arguments, verifies the instance exposes the required async batch methods (event_fd, submit_batch_get, submit_batch_set, submit_batch_exists, drain_completions, close), and wraps it in NativeConnectorL2Adapter. An optional submit_batch_delete enables L2 eviction deletes; without it, deletes are a no-op (logged as a warning).

Required fields:

  • module_path (str): Dotted Python import path of the module containing the connector class.

  • class_name (str): Name of the connector class inside module_path.

Optional fields:

  • adapter_params (dict, default {}): Forwarded as keyword arguments to the connector constructor.

  • max_capacity_gb (float, default 0): Aggregate L2 capacity in GB for usage tracking / eviction. 0 disables aggregate eviction.

Configuration examples:

# Native pybind connector with constructor kwargs
--l2-adapter '{"type": "native_plugin", "module_path": "my_ext.connector", "class_name": "MyConnectorClient", "adapter_params": {"host": "localhost", "port": 1234}}'

See examples/lmc_external_native_connector/ for a complete reference native connector.