Implementation:LMCache LMCache Lookup Client Factory

Knowledge Sources	LMCache
Domains	Lookup Client, Factory Pattern
Last Updated	2026-02-09 00:00 GMT

Overview

Factory class that creates the appropriate lookup client and server instances based on the LMCache engine configuration.

Description

LookupClientFactory provides static factory methods for constructing lookup clients and servers. The create_lookup_client method selects the appropriate client implementation based on configuration: external lookup clients (e.g., Mooncake) when external_lookup_client URI is set, bypass lookup clients when enable_scheduler_bypass_lookup is enabled with an engine, async clients when enable_async_loading is set, or the standard synchronous client as default. The factory then optionally wraps the client with HitLimitLookupClient (when hit_miss_ratio is configured) and ChunkStatisticsLookupClient (when enable_chunk_statistics is set). The create_lookup_server method creates the corresponding server-side component, supporting both sync and async variants, with worker ID filtering based on configuration. External URI parsing supports a scheme-based routing system (currently mooncakestore:// scheme).

Usage

Use LookupClientFactory.create_lookup_client during scheduler initialization to create the lookup client, and LookupClientFactory.create_lookup_server during worker initialization to create the server. The factory handles all configuration-based decisions, so callers do not need to know the specific client/server implementations.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/lookup_client/factory.py
• Lines: 1-187

Signature

class LookupClientFactory:
    @staticmethod
    def create_lookup_client(
        config: LMCacheEngineConfig,
        metadata: LMCacheMetadata,
        lmcache_engine: Optional[LMCacheEngine] = None,
    ) -> LookupClientInterface: ...

    @staticmethod
    def create_lookup_server(
        lmcache_engine: LMCacheEngine,
        metadata: LMCacheMetadata,
    ) -> Optional[Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]]: ...

    @staticmethod
    def _create_external_lookup_client(
        external_lookup_uri: str,
        config: LMCacheEngineConfig,
        metadata: LMCacheMetadata,
    ) -> LookupClientInterface: ...

    @staticmethod
    def _create_mooncake_lookup_client(
        master_address: str,
        config: LMCacheEngineConfig,
        metadata: LMCacheMetadata,
    ) -> "MooncakeLookupClient": ...

Import

from lmcache.v1.lookup_client.factory import LookupClientFactory

I/O Contract

Inputs

Name	Type	Required	Description
config	LMCacheEngineConfig	Yes	Engine configuration controlling which client/server type to create
metadata	LMCacheMetadata	Yes	Engine metadata (engine_id, world_size, kv_connector_extra_config, worker_id)
lmcache_engine	Optional[LMCacheEngine]	No	Engine instance; required for bypass lookup client and server creation
external_lookup_uri	str	Yes (internal)	URI in format <scheme>://<address> for external clients

Outputs

Name	Type	Description
client	LookupClientInterface	Configured lookup client instance (possibly wrapped with decorators)
server	Optional[LMCacheLookupServer or LMCacheAsyncLookupServer]	Lookup server instance, or None if the worker should not run a server

Usage Examples

from lmcache.v1.lookup_client.factory import LookupClientFactory

# Create lookup client (scheduler side)
client = LookupClientFactory.create_lookup_client(
    config=engine_config,
    metadata=engine_metadata,
)

# Create lookup server (worker side)
server = LookupClientFactory.create_lookup_server(
    lmcache_engine=engine,
    metadata=engine_metadata,
)

# With bypass lookup (scheduler has direct engine access)
bypass_client = LookupClientFactory.create_lookup_client(
    config=engine_config,
    metadata=engine_metadata,
    lmcache_engine=engine,
)

# Use the client
result = client.lookup(token_ids=[1, 2, 3, 4], lookup_id="req-001")
client.close()