From 7d120144567a10bc2fefdb3ab46a003602c46f7d Mon Sep 17 00:00:00 2001
From: tyler <tcr@enfuse.io>
Date: Fri, 28 Aug 2026 16:33:02 -0700
Subject: [PATCH] [Deps] Enable lmcache 0.5.4 with the kvaware router stack

Bumps the [lmcache] extra (lmcache 0.3.11 -> 0.5.4, vllm 0.13.0 -> 0.22.0),
the kvaware router base image (2025-05-27-v1 -> v0.5.4), and the tutorial-17
engine image (v0.3.9post2 -> v0.5.4), with comments documenting WHY the
pins must move in lockstep: the controller<->worker ZMQ messages are not a
stable protocol across lmcache versions, and kv-aware chunk hashes are
rooted in vLLM's NONE_HASH - a version mismatch on either axis makes every
KV lookup miss silently.

Router API surface verified against lmcache 0.5.4
(LMCacheControllerManager constructor, handle_orchestration_message,
start_all, LookupMsg, QueryInstMsg - all unchanged, two new optional
constructor params). Full router test suite passes (220/220).

Signed-off-by: tyler <tcr@enfuse.io>
---
 docker/Dockerfile.kvaware                |  7 ++++++-
 pyproject.toml                           | 14 +++++++++++---
 tutorials/assets/values-17-kv-aware.yaml |  2 +-
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/docker/Dockerfile.kvaware b/docker/Dockerfile.kvaware
index 01805b660..7402efaa4 100644
--- a/docker/Dockerfile.kvaware
+++ b/docker/Dockerfile.kvaware
@@ -1,4 +1,9 @@
-FROM lmcache/vllm-openai:2025-05-27-v1
+# The base image supplies the lmcache + vllm pair the router runs with.
+# It MUST match the engines' image versions: lmcache's controller<->worker
+# ZMQ messages are version-locked, and kv-aware chunk hashes are rooted in
+# vLLM's NONE_HASH - a mismatch on either side makes every KV lookup miss
+# silently (routing degrades to session/QPS with no error).
+FROM lmcache/vllm-openai:v0.5.4
 
 WORKDIR /app
 
diff --git a/pyproject.toml b/pyproject.toml
index 1d3d2d0af..45e41cec5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,13 +47,21 @@ semantic_cache = [
     "huggingface-hub==0.34.0",
 ]
 lmcache = [
-    "lmcache==0.3.11",
-    "vllm==0.13.0",
+    # lmcache's controller<->worker ZMQ messages are NOT a stable protocol
+    # across versions (a 0.3.x controller rejects a 0.4+/0.5+ worker's
+    # RegisterMsg as an unknown type), so the router-side lmcache MUST match
+    # the engines' lmcache exactly - keep this pin in lockstep with the
+    # engine images you deploy. vllm is required for hash parity: kv-aware
+    # chunk hashes are rooted in vLLM's NONE_HASH and hash fn, and a router
+    # without the engines' vllm derives a different chain (every lookup
+    # silently misses).
+    "lmcache==0.5.4",
+    "vllm==0.22.0",
 ]
 test = [
     "pytest>=8.3.4",
     "pytest-asyncio>=0.25.3",
-    "vllm==0.13.0"
+    "vllm==0.22.0"
 ]
 
 [build-system]
diff --git a/tutorials/assets/values-17-kv-aware.yaml b/tutorials/assets/values-17-kv-aware.yaml
index 124353fc9..7025e3ac8 100644
--- a/tutorials/assets/values-17-kv-aware.yaml
+++ b/tutorials/assets/values-17-kv-aware.yaml
@@ -3,7 +3,7 @@ servingEngineSpec:
   modelSpec:
   - name: "gpt-oss-20b"
     repository: "lmcache/vllm-openai"
-    tag: "v0.3.9post2"
+    tag: "v0.5.4"
     modelURL: "openai/gpt-oss-20b"
     replicaCount: 2
     requestCPU: 8