fix(vllm): declare a weight version only when a caller supplies one

Review found that a successful update omitting weight_version still
recorded the synthetic "unknown" placeholder, so get_weight_version could
answer version_declared: true for a version nobody chose. The routes still
respond "unknown" to keep the response shape stable, but only a
caller-supplied tag now counts as a declaration.

Also drop the defensive getattr in get_weight_version and initialize
_weight_version in the test constructor that bypasses __init__, and
describe the route in the RL guide as reporting the last version declared
rather than the version being served.

Regenerate the Python API reference pages. The freshness gate attributes
drift to any branch touching components/src, which this branch does; the
drift itself came from main (this branch's own head regenerates clean, and
the four stale pages carry no vLLM or RL content). The generated output is
byte-identical at the CI base and at current main, so regenerating settles
it rather than racing the next merge.

Signed-off-by: svc-glamr@nvidia.com <svc-glamr@nvidia.com>

Author: glamr-agent

components/src/dynamo/vllm/handlers.py

@@ -1731,10 +1731,13 @@ async def abort_request(self, body: dict) -> dict:
             return {"status": "error", "message": str(e)}
 
     def _declare_weight_version(self, version: Any) -> None:
-        """Record the weight version this worker is now serving.
+        """Record the weight version a caller has declared for this worker.
 
-        The single writer for the tracked version: both /engine weight-update
-        routes and the set_weight_version declaration route come through here.
+        The single writer for the tracked version: the set_weight_version
+        declaration route and both /engine weight-update routes come through
+        here. The update routes call it only when the request carried a
+        weight_version, so an update that declares nothing leaves the surface
+        undeclared rather than recording the placeholder they respond with.
         """
         self._weight_version = version
 
@@ -1754,7 +1757,7 @@ async def get_weight_version(self, body: dict) -> dict:
                 "status": "error",
                 "message": "request body must be a JSON object",
             }
-        version = getattr(self, "_weight_version", _WEIGHT_VERSION_UNDECLARED)
+        version = self._weight_version
         declared = version is not _WEIGHT_VERSION_UNDECLARED
         return {
             "status": "ok",
@@ -1820,7 +1823,12 @@ async def update_weights_from_disk(self, body: dict) -> dict:
                 # weights is now stale and must not be reused. Invalidate it
                 # while still holding _pause_lock (generation is paused).
                 await self.engine_client.reset_prefix_cache()
-                self._declare_weight_version(version)
+                # Only a caller-supplied tag counts as a declaration. The
+                # "unknown" default is a response placeholder, not something a
+                # caller declared, and recording it would make version_declared
+                # true while get_weight_version reports a version nobody chose.
+                if "weight_version" in body:
+                    self._declare_weight_version(version)
                 logger.info(
                     f"[RL] Weights loaded from {path} (version={version}, rpc={rpc})"
                 )
@@ -1883,7 +1891,10 @@ async def update_weights_from_distributed(self, body: dict) -> dict:
                     # Weights changed: stale prefix/KV cache must be invalidated
                     # before resume so it is not reused under the new weights.
                     await self.engine_client.reset_prefix_cache()
-                self._declare_weight_version(version)
+                # See update_weights_from_disk: the "unknown" default is a
+                # response placeholder, not a declaration.
+                if "weight_version" in body:
+                    self._declare_weight_version(version)
                 logger.info(
                     f"[RL] Weights received via distributed "
                     f"(version={version}, rpc={rpc})"

components/src/dynamo/vllm/tests/test_vllm_worker_handler.py

@@ -98,6 +98,8 @@ def _make_handler(
     # BaseWorkerHandler.__init__ is bypassed above; the decode generate path
     # registers per-request deferred-abort guards here.
     handler._deferred_aborts = {}
+    # Likewise the weight-version surface starts undeclared.
+    handler._weight_version = mod._WEIGHT_VERSION_UNDECLARED
     return handler
 
 
@@ -1857,6 +1859,35 @@ async def test_set_weight_version_rejects_a_missing_version(self):
         # A rejected declaration must not leave the surface claiming knowledge.
         assert (await handler.get_weight_version({}))["version_declared"] is False
 
+    @pytest.mark.asyncio
+    async def test_update_without_a_version_declares_nothing(self):
+        """An update that carries no ``weight_version`` leaves the surface
+        undeclared. The routes answer ``"unknown"`` so the response shape is
+        stable, but that placeholder is the route's, not the caller's, and
+        recording it would report a version nobody chose as declared.
+        """
+        handler = self._make_rl_handler()
+
+        distributed = await handler.update_weights_from_distributed(
+            {
+                "allow_unpaused": True,
+                "reset_prefix_cache": False,
+                "engine_rpc": "update_weights",
+            }
+        )
+        handler._paused = True
+        disk = await handler.update_weights_from_disk(
+            {"model_path": "/models/checkpoint-42"}
+        )
+
+        assert distributed == {"status": "ok", "version": "unknown"}
+        assert disk == {"status": "ok", "version": "unknown"}
+        assert await handler.get_weight_version({}) == {
+            "status": "ok",
+            "version": None,
+            "version_declared": False,
+        }
+
     @pytest.mark.asyncio
     async def test_init_weights_update_group_succeeds_within_timeout(self):
         handler = _make_handler()

docs/fern/pages/reference/api/python/README.mdx

@@ -7,14 +7,14 @@ subtitle: Public Python surfaces on the Dynamo distributed runtime, statically d
 
 {/* GENERATED by docs/fern/scripts/gen_python_api.py -- do not edit. */}
 
-Dynamo publishes 11 Python modules with 362 public class and function symbols under `dynamo.*`.
+Dynamo publishes 11 Python modules with 365 public class and function symbols under `dynamo.*`.
 
 <CardGroup cols={2}>
-<Card title="dynamo._core" href="python/_core">88 symbols. Rust-backed distributed runtime, KV router, and endpoint bindings.</Card>
+<Card title="dynamo._core" href="python/_core">89 symbols. Rust-backed distributed runtime, KV router, and endpoint bindings.</Card>
 <Card title="dynamo.runtime" href="python/runtime">17 symbols. Decorators and re-exports for defining Dynamo workers and endpoints.</Card>
-<Card title="dynamo.llm" href="python/llm">46 symbols. High-level LLM primitives for building request pipelines.</Card>
+<Card title="dynamo.llm" href="python/llm">47 symbols. High-level LLM primitives for building request pipelines.</Card>
 <Card title="dynamo.frontend" href="python/frontend">43 symbols. OpenAI-compatible HTTP frontend, argument parsing, and pre/post-processing.</Card>
-<Card title="dynamo.common" href="python/common">79 symbols. Shared configuration groups, storage adapters, and utility helpers.</Card>
+<Card title="dynamo.common" href="python/common">80 symbols. Shared configuration groups, storage adapters, and utility helpers.</Card>
 <Card title="dynamo.health_check" href="python/health_check">2 symbols. Health-check payload types and environment-driven configuration.</Card>
 <Card title="dynamo.logits_processing" href="python/logits_processing">4 symbols. Custom logits processors for LLM token generation.</Card>
 <Card title="dynamo.planner" href="python/planner">36 symbols. Scaling connectors, decision types, and Planner configuration.</Card>