feat(router): expose host/disk cache hit weights via CLI and env

components/src/dynamo/common/configuration/groups/kv_router_args.py

@@ -28,6 +28,8 @@
     "overlap_score_weight",
     "overlap_score_credit",
     "prefill_load_scale",
+    "host_cache_hit_weight",
+    "disk_cache_hit_weight",
     "router_temperature",
     "use_kv_events",
     "durable_kv_events",
@@ -108,6 +110,8 @@ class KvRouterConfigBase(ConfigBase):
     overlap_score_weight: Optional[float] = None
     overlap_score_credit: float
     prefill_load_scale: float
+    host_cache_hit_weight: float
+    disk_cache_hit_weight: float
     router_temperature: float
     use_kv_events: bool
     durable_kv_events: bool
@@ -198,6 +202,33 @@ def add_arguments(self, parser) -> None:
             arg_type=float,
             dest="prefill_load_scale",
         )
+        add_argument(
+            g,
+            flag_name="--router-host-cache-hit-weight",
+            env_var="DYN_ROUTER_HOST_CACHE_HIT_WEIGHT",
+            default=0.75,
+            help=(
+                "KV Router: Credit multiplier for host-pinned (CPU offload) prefix overlap. "
+                "Range: 0.0 to 1.0; higher values more strongly prefer workers holding the "
+                "prefix in CPU-tier KV cache. Symmetric to --router-kv-overlap-score-credit "
+                "but applied to host_pinned tier overlap."
+            ),
+            arg_type=float,
+            dest="host_cache_hit_weight",
+        )
+        add_argument(
+            g,
+            flag_name="--router-disk-cache-hit-weight",
+            env_var="DYN_ROUTER_DISK_CACHE_HIT_WEIGHT",
+            default=0.25,
+            help=(
+                "KV Router: Credit multiplier for disk/lower-tier (e.g. NVMe-backed) prefix overlap. "
+                "Range: 0.0 to 1.0. Same semantics as --router-host-cache-hit-weight applied to "
+                "the disk tier."
+            ),
+            arg_type=float,
+            dest="disk_cache_hit_weight",
+        )
         add_argument(
             g,
             flag_name="--router-temperature",

components/src/dynamo/common/tests/configuration/test_kv_router_args.py

@@ -346,6 +346,28 @@ def test_load_aware_preserves_prefill_load_scale() -> None:
     assert kwargs["prefill_load_scale"] == 2.5
 
 
+def test_load_aware_preserves_cache_hit_weights() -> None:
+    parser = argparse.ArgumentParser()
+    KvRouterArgGroup().add_arguments(parser)
+
+    args = parser.parse_args(
+        [
+            "--load-aware",
+            "--router-host-cache-hit-weight",
+            "0.9",
+            "--router-disk-cache-hit-weight",
+            "0.1",
+        ]
+    )
+
+    config = KvRouterConfigBase.from_cli_args(args)
+    kwargs = config.kv_router_kwargs()
+
+    assert kwargs["overlap_score_credit"] == 0.0
+    assert kwargs["host_cache_hit_weight"] == 0.9
+    assert kwargs["disk_cache_hit_weight"] == 0.1
+
+
 def test_kv_router_kwargs_preserves_explicit_queue_tiers() -> None:
     parser = argparse.ArgumentParser()
     KvRouterArgGroup().add_arguments(parser)

docs/components/router/router-configuration.md

@@ -11,7 +11,9 @@ This page collects the main router flags for frontend-embedded and standalone de
 
 - `--router-kv-overlap-score-credit`: Device-local prefix-overlap credit multiplier in the prefill cost calculation, from 0.0 to 1.0. Higher values improve Time To First Token (TTFT) at the cost of Inter-Token Latency (ITL). When set to 0, the router ignores prefix caches and skips creating a local indexer. Defaults to 1.
 - `--router-prefill-load-scale`: Scale applied to adjusted prompt-side prefill load after device, lower-tier, and shared-cache credits are subtracted. Defaults to 1.
-- `--load-aware`: Preset for load-aware KV routing without cache-reuse signals. On the frontend, it implies `--router-mode kv`. It sets `overlap_score_credit=0`, disables KV events, durable KV events, and KV reuse assumptions, enables active-block and prefill-token load tracking, disables remote/shared cache indexers, and preserves `--router-prefill-load-scale`.
+- `--router-host-cache-hit-weight`: Credit multiplier for host-pinned (CPU offload) prefix overlap, from 0.0 to 1.0. Symmetric to `--router-kv-overlap-score-credit` but applied to the host-pinned tier when a backend exposes CPU offload via a KV connector. Defaults to 0.75.
+- `--router-disk-cache-hit-weight`: Credit multiplier for disk/lower-tier (e.g. NVMe-backed) prefix overlap, from 0.0 to 1.0. Defaults to 0.25.
+- `--load-aware`: Preset for load-aware KV routing without cache-reuse signals. On the frontend, it implies `--router-mode kv`. It sets `overlap_score_credit=0`, disables KV events, durable KV events, and KV reuse assumptions, enables active-block and prefill-token load tracking, disables remote/shared cache indexers, and preserves `--router-prefill-load-scale`, `--router-host-cache-hit-weight`, and `--router-disk-cache-hit-weight`.
 - `--router-temperature`: Controls worker selection randomness through softmax sampling of normalized router cost logits. A value of 0 (default) ensures deterministic selection of the lowest-cost worker, while higher values introduce more randomness.
 - `--router-track-prefill-tokens`: Enables prompt-side load accounting in the worker cost model. This should stay enabled if you want queue thresholds, `active_prefill_tokens`, and AIC prefill load decay to reflect prompt work.
 - `--router-prefill-load-model`: Selects the router's prompt-side load model. `none` keeps the existing static prompt load accounting. `aic` predicts one expected prefill duration per admitted request and lazily decays only the oldest active prefill request on each worker.
@@ -122,6 +124,8 @@ If an older config used overlap score weight above 1.0 to make the router care m
 
 Use `--router-prefill-load-scale` when prompt-side load should count more or less than decode-side block load after cache-hit credits are applied. The final score is `prefill_load_scale * adjusted_prefill_blocks + decode_blocks`.
 
+Use `--router-host-cache-hit-weight` and `--router-disk-cache-hit-weight` when the backend exposes lower-tier prefix cache via a KV connector (for example, vLLM's `OffloadingConnector` for CPU offload, or a disk-backed tier). These multipliers control how much each lower-tier hit credits against the prefill load, mirroring the role of `--router-kv-overlap-score-credit` for the device tier. A worker holding a full prefix in CPU offload gets `host_cache_hit_weight * matched_blocks` credit against its prefill cost; raising the weight makes the router more willing to route prefix-matched requests to that worker even if a different worker has a partial device-local match.
+
 Use `--no-router-kv-events` when you are not confident that your backend engine emits KV events correctly. In this mode the router falls back to approximate routing, predicting cache state from its own routing decisions with TTL-based expiration.
 
 Use `--router-predicted-ttl-secs 5` when the workload fires bursts of sibling requests with shared prefixes — parallel sampling, best-of-N, agent fan-out. It closes the window between the routing decision and the engine's first "block stored" event so siblings co-locate on the worker the first sibling picked. See the configuration section above for the side-indexer mechanics.