lmcache-cli 0.4.8.dev24__py3-none-any.whl → 0.4.8.dev38__py3-none-any.whl

lmcache/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.8.dev24'
-__version_tuple__ = version_tuple = (0, 4, 8, 'dev24')
+__version__ = version = '0.4.8.dev38'
+__version_tuple__ = version_tuple = (0, 4, 8, 'dev38')
 
-__commit_id__ = commit_id = 'gf52b174ca'
+__commit_id__ = commit_id = 'ge1fdbc634'

lmcache/cli/commands/bench/engine_bench/command.py

@@ -33,7 +33,10 @@ from lmcache.cli.commands.bench.engine_bench.stats import (
     FinalStats,
     StatsCollector,
 )
-from lmcache.cli.commands.bench.engine_bench.workloads import create_workload
+from lmcache.cli.commands.bench.engine_bench.workloads import (
+    create_workload,
+    validate_max_output_length_supported,
+)
 from lmcache.logging import init_logger
 
 if TYPE_CHECKING:
@@ -42,6 +45,10 @@ if TYPE_CHECKING:
 
 logger = init_logger(__name__)
 
+# Default for --ldqa-max-output-length; centralized so the "max output length
+# explicitly set" check stays in sync with the parser.
+_LDQA_MAX_OUTPUT_LENGTH_DEFAULT = 128
+
 
 # ---------------------------------------------------------------------------
 # Parser registration
@@ -147,6 +154,15 @@ def register_engine_parser(
         action="store_true",
         help="Suppress real-time progress display.",
     )
+    parser.add_argument(
+        "--ignore-eos",
+        action="store_true",
+        help=(
+            "Force generation to run for the full output length by ignoring "
+            "the model's EOS token (vLLM sampling extension). Makes decode "
+            "throughput reproducible regardless of when the model would stop."
+        ),
+    )
     parser.add_argument(
         "--no-interactive",
         action="store_true",
@@ -223,6 +239,16 @@ def register_engine_parser(
         default=3,
         help="Max concurrent in-flight requests (default: 3).",
     )
+    group.add_argument(
+        "--ldqa-max-output-length",
+        type=int,
+        default=_LDQA_MAX_OUTPUT_LENGTH_DEFAULT,
+        help=(
+            f"Max tokens to generate per benchmark query "
+            f"(default: {_LDQA_MAX_OUTPUT_LENGTH_DEFAULT}). Combine with "
+            "--ignore-eos for a reproducible decode phase."
+        ),
+    )
 
     # --- Multi-round-chat workload args ---
     mrc_group = parser.add_argument_group(
@@ -410,6 +436,7 @@ def _export_config(
     state.set("workload", config.workload)
     state.set("kv_cache_volume", config.kv_cache_volume_gb)
     state.set("tokens_per_gb_kvcache", config.tokens_per_gb_kvcache)
+    state.set("ignore_eos", config.ignore_eos)
 
     # Workload-specific args from namespace
     for item in state.get_workload_items():
@@ -524,6 +551,11 @@ def run_engine_bench(command: "BaseCommand", args: argparse.Namespace) -> None:
     # 1. Parse config
     config = parse_args_to_config(args)
 
+    # 1a. A max output length can only be set for workloads that have a
+    # max-output-length parameter; reject it for any other workload.
+    if args.ldqa_max_output_length != _LDQA_MAX_OUTPUT_LENGTH_DEFAULT:
+        validate_max_output_length_supported(config.workload)
+
     # 1b. --export-config: save resolved config and exit
     export_path = getattr(args, "export_config", None)
     if export_path:
@@ -546,7 +578,11 @@ def run_engine_bench(command: "BaseCommand", args: argparse.Namespace) -> None:
     )
 
     # 3. Create request sender (callbacks wired after workload creation)
-    request_sender = RequestSender(config.engine_url, config.model)
+    request_sender = RequestSender(
+        config.engine_url,
+        config.model,
+        ignore_eos=config.ignore_eos,
+    )
 
     # 4. Create workload
     workload = create_workload(

lmcache/cli/commands/bench/engine_bench/config.py

@@ -39,6 +39,7 @@ class EngineBenchConfig:
     export_csv: bool
     export_json: bool
     quiet: bool
+    ignore_eos: bool = False
 
     def __post_init__(self) -> None:
         if not self.engine_url:
@@ -246,4 +247,5 @@ def parse_args_to_config(args: argparse.Namespace) -> EngineBenchConfig:
         export_csv=not args.no_csv,
         export_json=args.json,
         quiet=args.quiet,
+        ignore_eos=args.ignore_eos,
     )

lmcache/cli/commands/bench/engine_bench/interactive/schema.py

@@ -179,6 +179,18 @@ ALL_ITEMS: list[ConfigItem] = [
         default=100.0,
         phase=PHASE_GENERAL,
     ),
+    ConfigItem(
+        key="ignore_eos",
+        display_name="Ignore EOS",
+        description=(
+            "Force generation to run for the full output length by ignoring "
+            "the model's EOS token (vLLM extension). Makes decode throughput "
+            "reproducible."
+        ),
+        input_type="bool",
+        default=False,
+        phase=PHASE_GENERAL,
+    ),
     # ── Phase 3: long-doc-permutator ─────────────────────────────────
     ConfigItem(
         key="ldp_num_contexts",
@@ -266,6 +278,15 @@ ALL_ITEMS: list[ConfigItem] = [
         condition=_workload_is("long-doc-qa"),
         phase=PHASE_WORKLOAD,
     ),
+    ConfigItem(
+        key="ldqa_max_output_length",
+        display_name="Max output length (tokens)",
+        description="Max tokens to generate per benchmark query.",
+        input_type="int",
+        default=128,
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
     # ── Phase 3: multi-round-chat ─────────────────────────────────────
     ConfigItem(
         key="mrc_shared_prompt_length",

lmcache/cli/commands/bench/engine_bench/request_sender.py

@@ -73,10 +73,12 @@ class RequestSender:
         model: str,
         completions_mode: bool = False,
         on_finished: list[OnFinishedCallback] = [],  # noqa: B006
+        ignore_eos: bool = False,
     ) -> None:
         self._model = model
         self._completions_mode = completions_mode
         self._on_finished = list(on_finished)
+        self._ignore_eos = ignore_eos
 
         base_url = _normalize_url(engine_url)
         api_key = os.getenv("OPENAI_API_KEY", "")
@@ -220,7 +222,18 @@ class RequestSender:
         messages: list[dict[str, str]],
         max_tokens: int,
     ) -> collections.abc.AsyncIterator:
-        """Dispatch the streaming API call (chat or completions)."""
+        """Dispatch the streaming API call (chat or completions).
+
+        When ``ignore_eos`` is set on the sender, ``{"ignore_eos": true}`` is
+        added to the request body (a vLLM sampling extension) so generation
+        always runs for the full ``max_tokens`` instead of stopping at the
+        model's EOS token. This makes decode-throughput numbers reproducible.
+        """
+        # Attach extra_body only when ignore_eos is set; otherwise send the
+        # plain request so no vLLM-specific field reaches non-vLLM backends.
+        extra: dict[str, dict[str, bool]] = {}
+        if self._ignore_eos:
+            extra["extra_body"] = {"ignore_eos": True}
         if self._completions_mode:
             prompt = messages[0]["content"] if messages else ""
             return await self._client.completions.create(
@@ -230,6 +243,7 @@ class RequestSender:
                 max_tokens=max_tokens,
                 temperature=0.0,
                 stream_options={"include_usage": True},
+                **extra,
             )
         return await self._client.chat.completions.create(
             model=self._model,
@@ -238,4 +252,5 @@ class RequestSender:
             max_tokens=max_tokens,
             temperature=0.0,
             stream_options={"include_usage": True},
+            **extra,
         )

lmcache/cli/commands/bench/engine_bench/workloads/__init__.py

@@ -52,6 +52,7 @@ __all__ = [
     "RandomPrefillConfig",
     "RandomPrefillWorkload",
     "create_workload",
+    "validate_max_output_length_supported",
 ]
 
 _WORKLOAD_NAMES = (
@@ -62,6 +63,34 @@ _WORKLOAD_NAMES = (
     "random-prefill",
 )
 
+# Workloads that expose a user-configurable max output length, via a
+# ``max_output_length`` arg (``--ldqa-max-output-length`` / ``--mrc-output-length``).
+_WORKLOADS_WITH_MAX_OUTPUT_LENGTH: frozenset[str] = frozenset(
+    {"long-doc-qa", "multi-round-chat"}
+)
+
+
+def validate_max_output_length_supported(workload: str) -> None:
+    """Validate that a max output length can be specified for ``workload``.
+
+    Only workloads with a max-output-length parameter (``long-doc-qa``,
+    ``multi-round-chat``) support setting it; every other workload fixes its
+    generation length internally, so requesting one is rejected.
+
+    Args:
+        workload: The selected workload name (``EngineBenchConfig.workload``).
+
+    Raises:
+        ValueError: If ``workload`` has no max-output-length parameter.
+    """
+    if workload in _WORKLOADS_WITH_MAX_OUTPUT_LENGTH:
+        return
+    supported = ", ".join(sorted(_WORKLOADS_WITH_MAX_OUTPUT_LENGTH))
+    raise ValueError(
+        f"max output length cannot be specified for the {workload!r} workload: "
+        f"it has no max-output-length parameter. Supported workloads: {supported}."
+    )
+
 
 def create_workload(
     config: EngineBenchConfig,
@@ -114,6 +143,7 @@ def create_workload(
             query_per_document=args.ldqa_query_per_document,
             shuffle_policy=args.ldqa_shuffle_policy,
             num_inflight_requests=args.ldqa_num_inflight_requests,
+            max_output_length=args.ldqa_max_output_length,
         )
         return LongDocQAWorkload(
             config=ld_workload_config,

lmcache/cli/commands/bench/engine_bench/workloads/long_doc_qa.py

@@ -27,6 +27,7 @@ class LongDocQAConfig:
     num_documents: int = 1
     shuffle_policy: str = "random"
     num_inflight_requests: int = 3
+    max_output_length: int = 128
 
     def __post_init__(self) -> None:
         if self.document_length <= 0:
@@ -37,6 +38,10 @@ class LongDocQAConfig:
             raise ValueError(
                 f"query_per_document must be >= 1, got {self.query_per_document}"
             )
+        if self.max_output_length < 1:
+            raise ValueError(
+                f"max_output_length must be >= 1, got {self.max_output_length}"
+            )
         if self.num_inflight_requests < 1:
             raise ValueError(
                 f"num_inflight_requests must be >= 1, got {self.num_inflight_requests}"
@@ -56,6 +61,7 @@ class LongDocQAConfig:
         query_per_document: int = 2,
         shuffle_policy: str = "random",
         num_inflight_requests: int = 3,
+        max_output_length: int = 128,
     ) -> "LongDocQAConfig":
         """Create a config with ``num_documents`` computed from KV cache budget.
 
@@ -66,6 +72,7 @@ class LongDocQAConfig:
             query_per_document: Number of questions per document.
             shuffle_policy: Request ordering — ``"random"`` or ``"tile"``.
             num_inflight_requests: Max concurrent in-flight requests.
+            max_output_length: Max tokens to generate per benchmark query.
 
         Returns:
             A fully-resolved LongDocQAConfig with computed num_documents.
@@ -88,6 +95,7 @@ class LongDocQAConfig:
             num_documents=num_documents,
             shuffle_policy=shuffle_policy,
             num_inflight_requests=num_inflight_requests,
+            max_output_length=max_output_length,
         )
 
 
@@ -265,6 +273,7 @@ class LongDocQAWorkload(BaseWorkload):
             await self._request_sender.send_request(
                 request_id,
                 messages,
+                max_tokens=self._config.max_output_length,
             )
         finally:
             self._semaphore.release()

lmcache/cli/commands/coordinator.py

@@ -101,6 +101,24 @@ class CoordinatorCommand(BaseCommand):
                 "quota, 0.0 (exclusive) to 1.0 (default: 1.0)."
             ),
         )
+        parser.add_argument(
+            "--blend-chunk-size",
+            type=int,
+            default=None,
+            help=(
+                "Tokens per chunk for the global CacheBlend directory; must "
+                "equal the LMCache chunk size the blend servers use (default: 256)."
+            ),
+        )
+        parser.add_argument(
+            "--blend-probe-stride",
+            type=int,
+            default=None,
+            help=(
+                "Positions between CacheBlend match probes; 1 probes every "
+                "offset for full recall (default: 1)."
+            ),
+        )
 
     def execute(self, args: argparse.Namespace) -> None:
         """Build the coordinator config and serve the app with uvicorn.
@@ -145,6 +163,8 @@ class CoordinatorCommand(BaseCommand):
                 ("eviction_check_interval", args.eviction_check_interval),
                 ("eviction_ratio", args.eviction_ratio),
                 ("trigger_watermark", args.trigger_watermark),
+                ("blend_chunk_size", args.blend_chunk_size),
+                ("blend_probe_stride", args.blend_probe_stride),
             )
             if value is not None
         }

lmcache/cli/commands/tool/__init__.py

@@ -15,7 +15,7 @@ import sys
 
 # First Party
 from lmcache.cli.commands.base import BaseCommand
-from lmcache.cli.commands.tool import cache_simulator
+from lmcache.cli.commands.tool import cache_simulator, transfer_channel_benchmark
 
 
 class ToolCommand(BaseCommand):
@@ -46,9 +46,10 @@ class ToolCommand(BaseCommand):
         inner = parser.add_subparsers(
             dest="tool_name",
             required=True,
-            metavar="{cache-simulator}",
+            metavar="{cache-simulator,transfer-channel-benchmark}",
         )
         cache_simulator.register(inner)
+        transfer_channel_benchmark.register(inner)
 
     def execute(self, args: argparse.Namespace) -> None:
         """Dispatch is handled per-tool via parser.set_defaults(func=...).

lmcache/cli/commands/tool/transfer_channel_benchmark.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool transfer-channel-benchmark`` sub-subcommand wiring.
+
+Argument definitions and execution logic live in the benchmark module:
+
+* :func:`~lmcache.tools.transfer_channel_benchmark.benchmark.add_benchmark_arguments`
+* :func:`~lmcache.tools.transfer_channel_benchmark.benchmark.run_benchmark`
+"""
+
+# Standard
+import argparse
+import sys
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``transfer-channel-benchmark`` sub-subcommand.
+
+    Only the torch-free ``config`` module is imported here, so registering this
+    tool (which happens on every ``lmcache`` invocation) does not require torch
+    or the distributed runtime. Those are imported in ``execute``.
+
+    Args:
+        subparsers: The subparsers action from the ``lmcache tool`` parser.
+    """
+    # First Party
+    from lmcache.tools.transfer_channel_benchmark.config import (
+        add_benchmark_arguments,
+    )
+
+    parser = subparsers.add_parser(
+        "transfer-channel-benchmark",
+        help="Benchmark transfer channel read throughput (server/client).",
+        description=(
+            "Throughput benchmark for the LMCache transfer channel. Run one "
+            "process with --role server and another with --role client."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    add_benchmark_arguments(parser)
+    parser.set_defaults(func=execute)
+
+
+def execute(args: argparse.Namespace) -> None:
+    """Run the benchmark and exit non-zero on failure.
+
+    Args:
+        args: Parsed CLI arguments.
+    """
+    # First Party
+    from lmcache.tools.transfer_channel_benchmark.benchmark import run_benchmark
+
+    if not run_benchmark(args):
+        sys.exit(1)

lmcache/integration/vllm/vllm_multi_process_adapter.py

@@ -271,14 +271,21 @@ def _raise_server_unreachable(server_url: str, timeout: float) -> NoReturn:
 def send_ping(
     mq_client: MessageQueueClient,
     timeout: float,
+    instance_id: int | None = None,
 ) -> bool:
     """Send a PING request and return the result.
 
+    Args:
+        mq_client: The message queue client.
+        timeout: Seconds to wait for the server's response.
+        instance_id: The worker's instance ID so the server can refresh its
+            liveness, or None for an untracked prober (scheduler adapter).
+
     Returns:
         True if server is healthy, False on timeout or error.
     """
     try:
-        future = send_lmcache_request(mq_client, RequestType.PING, [])
+        future = send_lmcache_request(mq_client, RequestType.PING, [instance_id])
         return future.result(timeout=timeout)
     except TimeoutError:
         return False
@@ -389,6 +396,7 @@ class HeartbeatThread(PeriodicThread):
         mq_client: MessageQueueClient,
         health_event: threading.Event,
         interval: float = DEFAULT_HEARTBEAT_INTERVAL,
+        instance_id: int | None = None,
     ):
         """
         Args:
@@ -398,6 +406,9 @@ class HeartbeatThread(PeriodicThread):
                 Adapters check this event to decide whether to proceed
                 with operations or enter degraded mode.
             interval: Seconds between heartbeat pings and ping timeout.
+            instance_id: The worker's instance ID sent with each PING so the
+                server can refresh its liveness, or None for an untracked
+                prober (the scheduler adapter).
         """
         super().__init__(
             name="lmcache-heartbeat",
@@ -407,6 +418,7 @@ class HeartbeatThread(PeriodicThread):
         self._mq_client = mq_client
         self._health_event = health_event
         self._interval = interval
+        self._instance_id = instance_id
 
         # Optional callback invoked on the unhealthy->healthy edge,
         # before the health event is set. See register_recover_callback.
@@ -445,7 +457,9 @@ class HeartbeatThread(PeriodicThread):
         UNREGISTER must not re-register a ghost context.
         """
         was_healthy = self._health_event.is_set()
-        healthy = send_ping(self._mq_client, timeout=self._interval)
+        healthy = send_ping(
+            self._mq_client, timeout=self._interval, instance_id=self._instance_id
+        )
 
         if self.stop_requested:
             return ThreadRunSummary(
@@ -1170,7 +1184,7 @@ class LMCacheMPWorkerAdapter:
         ``last_seen``, so it is never reaped while alive -- no re-registration
         is needed at startup, and the first store/retrieve is not gated. The
         recover callback still re-registers on a genuine unhealthy->healthy
-        edge (server restart) and on freeze-gap recovery.
+        edge (server restart).
         """
         if self._heartbeat is not None:
             return
@@ -1181,6 +1195,7 @@ class LMCacheMPWorkerAdapter:
                 mq_client=self.mq_client,
                 health_event=self._health_event,
                 interval=self._heartbeat_interval,
+                instance_id=self.instance_id,
             )
             heartbeat.register_recover_callback(self._reregister_kv_caches_callback)
             heartbeat.start()

lmcache/tools/transfer_channel_benchmark/README.md

@@ -0,0 +1,128 @@
+# Transfer Channel Throughput Benchmark
+
+Measures read throughput (GB/s) of the LMCache **transfer channel**
+(`lmcache/v1/distributed/transfer_channel/`) for batched peer-to-peer reads.
+
+Unlike a raw-tensor microbenchmark, this tool uses LMCache's `L1MemoryManager`
+to initialize the registered memory region and to **allocate the transferred
+objects** on both sides, so it exercises the same memory path production uses.
+
+## How it works
+
+The benchmark runs as **two separate processes**:
+
+- **server** — uses an `L1MemoryManager` to allocate a registered L1 buffer and
+  a pool of source memory objects, registers the buffer with the transfer
+  channel, and publishes the source object catalog (`offset`/`size` per object)
+  over a small ZMQ side-channel.
+- **client** — fetches the catalog, allocates its own destination objects via an
+  `L1MemoryManager`, connects the transfer channel, and repeatedly reads a random
+  `--num-objects` subset of the source objects, then reports throughput.
+
+A side-channel is needed because the transfer channel handshake only exchanges
+the whole-buffer registration, not per-object offsets.
+
+> Only the `nixl` transfer channel type is registered today. The tool is generic
+> over `--transfer-channel-type`; an unknown type raises a clear error.
+
+## Usage
+
+Run via the module or the `lmcache` CLI. Start the server first.
+
+### `python -m`
+
+```bash
+# terminal 1 — server
+python -m lmcache.tools.transfer_channel_benchmark \
+  --role server --transfer-channel-type nixl \
+  --url 0.0.0.0:7600 --control-url 0.0.0.0:7610 \
+  --buffer-size 2GB --page-size 512KB --object-size 10MB
+
+# terminal 2 — client
+python -m lmcache.tools.transfer_channel_benchmark \
+  --role client --transfer-channel-type nixl \
+  --url 127.0.0.1:7600 --control-url 127.0.0.1:7610 \
+  --listen-url 0.0.0.0:7601 \
+  --page-size 512KB --object-size 10MB \
+  --num-objects 10 --iters 3 --warmup 1
+```
+
+### `lmcache tool`
+
+```bash
+lmcache tool transfer-channel-benchmark --role server  --url 0.0.0.0:7600 \
+  --control-url 0.0.0.0:7610 --buffer-size 2GB --object-size 10MB
+lmcache tool transfer-channel-benchmark --role client --url 127.0.0.1:7600 \
+  --control-url 127.0.0.1:7610 --object-size 10MB --num-objects 10
+```
+
+The server always writes a deterministic per-object byte pattern (object index
+mod 256) into its source objects, so adding `--verify` on the **client** checks
+the transferred bytes against that pattern (no `--verify` needed on the server).
+
+## Key options
+
+| Option | Role | Meaning |
+| --- | --- | --- |
+| `--role {server,client}` | both | Which side to run (required). |
+| `--transfer-channel-type` | both | Implementation to benchmark (default `nixl`). |
+| `--nixl-backend` | both | nixl backend, e.g. `UCX` (nixl-specific). |
+| `--url` | both | Server binds its transfer-channel server here; client dials it. |
+| `--listen-url` | client | Client's own (mandatory) transfer-channel server bind. |
+| `--control-url` | both | Catalog side-channel: server binds, client connects. |
+| `--buffer-size` | server | Registered L1 source buffer size (e.g. `8GB`). |
+| `--page-size` | both | Page / alignment size; **must match** on both sides. |
+| `--object-size` | both | Per-object size; multiple of `--page-size`. |
+| `--num-objects` | client | Objects transferred per read. |
+| `--num-source-objects` | server | Source pool size (default `5 * --num-objects`). |
+| `--iters` / `--warmup` | client | Measured / warmup read iterations. |
+| `--seed` | client | RNG seed for the read subset. |
+| `--verify` | client | Verify transferred bytes against the server's known pattern. |
+| `--use-lazy` | both | Use the lazy L1 allocator (experimental for registration). |
+| `--server-timeout` | server | Seconds to serve catalog requests before exiting. |
+
+## Notes
+
+- `--page-size` must be identical on server and client (enforced via the catalog
+  handshake) so remote page-index math lines up.
+- With the default (non-lazy) allocator the whole `--buffer-size` is allocated up
+  front and may be CUDA-pinned; keep it within available host memory.
+- Requires a working transfer channel runtime (for `nixl`, a UCX backend).
+
+## Performance: NUMA placement
+
+On a multi-NUMA host with NICs spread across nodes (e.g. an 8-NIC, 2-socket
+box), run **both** the server and client under `numactl --interleave=all`:
+
+```bash
+numactl --interleave=all \
+python -m lmcache.tools.transfer_channel_benchmark --role server ...
+```
+
+Without it the registered buffer is allocated on a single NUMA node, so only the
+rails local to that node reach full bandwidth and the rest are throttled by the
+cross-socket link — roughly halving throughput. In testing on a 2-NUMA / 8-rail
+host this was the difference between **~110 GB/s** (no interleave) and
+**~210 GB/s** (`--interleave=all`), with everything else identical. Page size
+only matters in the small regime (descriptor-bound below ~64KB); from ~128KB up
+the transfer is bandwidth-bound and flat.
+
+## Troubleshooting
+
+- **Client hangs after "connected" or during connect, then raises
+  `TimeoutError` after ~60s.** The transfer-channel handshake could not reach the
+  server. Check that `--url`/`--control-url` on the client point at the *server's*
+  reachable address (a common mistake is a typo such as a trailing dot:
+  `10.0.0.5.:7600`), that the server is running, and that the ports are open
+  between hosts:
+  ```bash
+  nc -vz <server-host> 7600   # transfer channel
+  nc -vz <server-host> 7610   # catalog side-channel
+  ```
+  The handshake has a fixed 60s timeout, so a misconfiguration fails with a clear
+  error instead of hanging forever.
+- **`page_size`/`object_size` mismatch error.** The client validates these against
+  the server's catalog; pass the same `--page-size` and `--object-size` on both.
+- **Allocation `RuntimeError` on the server.** The source pool
+  (`--num-source-objects` × `--object-size`) must fit in `--buffer-size`; increase
+  the buffer or reduce the pool/object size.

lmcache/tools/transfer_channel_benchmark/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

lmcache/tools/transfer_channel_benchmark/__main__.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``python -m lmcache.tools.transfer_channel_benchmark`` entry point."""
+
+# Standard
+import argparse
+import sys
+
+# First Party
+# Only the torch-free config module is imported eagerly so that `-h` works
+# without torch installed. The runtime (which needs torch) is imported after
+# arguments are parsed.
+from lmcache.tools.transfer_channel_benchmark.config import add_benchmark_arguments
+
+
+def main() -> int:
+    """Parse arguments and run the transfer channel benchmark.
+
+    Returns:
+        Process exit code (0 on success, 1 on failure).
+    """
+    parser = argparse.ArgumentParser(
+        prog="python -m lmcache.tools.transfer_channel_benchmark",
+        description="Throughput benchmark for the LMCache transfer channel.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    add_benchmark_arguments(parser)
+    args = parser.parse_args()
+
+    # Imported here (not at module load) so this entry point can show --help
+    # without requiring torch; importing it raises a clear error if torch is
+    # missing.
+    # First Party
+    from lmcache.tools.transfer_channel_benchmark.benchmark import run_benchmark
+
+    return 0 if run_benchmark(args) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())