[TRTLLM-17271][refactor] Read trtllm-serve environment variables through one typed module

.github/CODEOWNERS

@@ -121,6 +121,7 @@
 /tensorrt_llm/commands/__init__.py @NVIDIA/trt-llm-runtime-devs
 /tensorrt_llm/commands/serve.py @NVIDIA/trt-llm-runtime-devs
 /tensorrt_llm/commands/utils.py @NVIDIA/trt-llm-runtime-devs
+/tensorrt_llm/commands/serve_cli @NVIDIA/trt-llm-runtime-devs
 /tensorrt_llm/executor @NVIDIA/trt-llm-runtime-devs
 /tensorrt_llm/grpc @NVIDIA/trt-llm-runtime-devs
 /tensorrt_llm/grpc/openengine @NVIDIA/trt-llm-runtime-devs @NVIDIA/trt-llm-dynamo-devs

.pre-commit-config.yaml

@@ -334,6 +334,7 @@ common-files: &common_files |
         tensorrt_llm/commands/bench.py |
         tensorrt_llm/commands/eval.py |
         tensorrt_llm/commands/serve.py |
+        tensorrt_llm/commands/serve_cli/_net.py |
         tensorrt_llm/evaluate/__init__.py |
         tensorrt_llm/evaluate/cnn_dailymail.py |
         tensorrt_llm/evaluate/interface.py |
@@ -1058,6 +1059,7 @@ legacy-files: &legacy_files |
         tensorrt_llm/commands/bench.py |
         tensorrt_llm/commands/eval.py |
         tensorrt_llm/commands/serve.py |
+        tensorrt_llm/commands/serve_cli/_net.py |
         tensorrt_llm/evaluate/__init__.py |
         tensorrt_llm/evaluate/cnn_dailymail.py |
         tensorrt_llm/evaluate/interface.py |

legacy-files.txt

@@ -312,6 +312,7 @@ tensorrt_llm/commands/__init__.py
 tensorrt_llm/commands/bench.py
 tensorrt_llm/commands/eval.py
 tensorrt_llm/commands/serve.py
+tensorrt_llm/commands/serve_cli/_net.py
 tensorrt_llm/evaluate/__init__.py
 tensorrt_llm/evaluate/cnn_dailymail.py
 tensorrt_llm/evaluate/interface.py

pyproject.toml

@@ -392,6 +392,7 @@ exclude = [
     "tensorrt_llm/commands/bench.py",
     "tensorrt_llm/commands/eval.py",
     "tensorrt_llm/commands/serve.py",
+    "tensorrt_llm/commands/serve_cli/_net.py",
     "tensorrt_llm/evaluate/__init__.py",
     "tensorrt_llm/evaluate/cnn_dailymail.py",
     "tensorrt_llm/evaluate/interface.py",

ruff-legacy.toml

@@ -329,6 +329,7 @@ include = [
     "tensorrt_llm/commands/bench.py",
     "tensorrt_llm/commands/eval.py",
     "tensorrt_llm/commands/serve.py",
+    "tensorrt_llm/commands/serve_cli/_net.py",
     "tensorrt_llm/evaluate/__init__.py",
     "tensorrt_llm/evaluate/cnn_dailymail.py",
     "tensorrt_llm/evaluate/interface.py",

scripts/generate_trtllm_serve_schemas.py

@@ -195,7 +195,7 @@ def dwdp_fields(required: tuple[str, ...] = (), **values: object) -> dict:
 
 def generate_serve_schema() -> dict:
     """Describe the YAML fragment merged with ordinary serving CLI arguments."""
-    from tensorrt_llm.llmapi.disagg_utils import DisaggClusterConfig, InternalRequestAuthKey
+    from tensorrt_llm.commands.serve_cli._serve_options import LIVE_OBJECT_PATHS, yaml_options
     from tensorrt_llm.llmapi.llm_args import (
         SERVE_CONFIG_ALIASES,
         MoeLoadBalancerConfig,
@@ -210,12 +210,14 @@ def generate_serve_schema() -> dict:
     properties = schema["properties"]
     for alias, name in SERVE_CONFIG_ALIASES.items():
         properties[alias] = copy.deepcopy(properties[name])
-    # Keep server-only fields aligned with serve.py.
-    properties.update(
-        allow_request_chat_template={"type": "boolean", "default": False},
-        internal_request_auth_key=_schema_for(InternalRequestAuthKey),
-        disagg_cluster=_nullable(_schema_for(DisaggClusterConfig, schema)),
-    )
+    # Server-only keys and live objects are declared in
+    # tensorrt_llm/commands/serve_cli/_serve_options.py.
+    for option in yaml_options("serve"):
+        if option.yaml_json_schema is not None:
+            key_schema = copy.deepcopy(dict(option.yaml_json_schema))
+        else:
+            key_schema = _schema_for(option.yaml_type, schema)
+        properties[option.yaml_key] = _nullable(key_schema) if option.yaml_nullable else key_schema
     # Serving treats null as unset before constructing the non-optional telemetry model.
     properties["telemetry_config"] = _nullable(properties["telemetry_config"])
     # Keep accepted forms aligned with TorchLlmArgs.validate_load_balancer(): a mapping
@@ -282,18 +284,15 @@ def generate_serve_schema() -> dict:
         {"properties": {name: {"const": 0} for name in pair}},
         {"properties": {name: {"minimum": 1} for name in pair}, "required": list(pair)},
     ]
-    # These object/Any annotations are Python API hooks, not arbitrary YAML mappings.
-    # Update these restrictions when hooks are added or gain YAML construction support.
-    for name in ("batched_logits_processor", "checkpoint_loader", "_mpi_session"):
-        properties[name] = {
-            "type": "null",
-            "description": "Live objects require the Python LLM API.",
-        }
+    # Live objects are Python API hooks, not arbitrary YAML mappings; their paths
+    # and schema fragments are declared next to the server-only options.
+    for live in LIVE_OBJECT_PATHS:
+        if live.schema_model is None:
+            holder = properties
+        else:
+            holder = schema["$defs"][live.schema_model]["properties"]
+        holder[live.schema_property] = copy.deepcopy(dict(live.json_schema))
     schema["allOf"] = _dwdp_launch_rules()
-    schema["$defs"]["RayPlacementConfig"]["properties"]["placement_groups"] = {"type": "null"}
-    user_draft = schema["$defs"]["UserProvidedDecodingConfig"]["properties"]
-    user_draft["drafter"] = {"not": {}, "description": "A Drafter requires the Python LLM API."}
-    user_draft["resource_manager"] = {"type": "null"}
     # Update this mapping exception when the YAML loader changes legacy DecodingConfig support.
     properties["decoding_config"] = {"type": ["object", "null"]}
     return schema

tensorrt_llm/commands/AGENTS.md

@@ -0,0 +1,6 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+Rules for the trtllm-serve CLI (`commands/serve.py`) are in `tensorrt_llm/serve/AGENTS.md`.

tensorrt_llm/commands/CLAUDE.md

@@ -0,0 +1,2 @@
+# In ./CLAUDE.md
+@AGENTS.md

tensorrt_llm/commands/_config_overrides.py

@@ -26,6 +26,8 @@
 import yaml
 from pydantic import BaseModel
 
+from tensorrt_llm.commands.serve_cli._serve_options import reserved_set_paths
+
 _PATH_COMPONENT_RE = re.compile(r"^[a-z_][A-Za-z0-9_]*$")
 _MAX_VALUE_DEPTH = 64
 _MAX_VALUE_NODES = 10_000
@@ -42,21 +44,9 @@ class ConfigOverrideError(ValueError):
     """A safe-to-display error in a configuration override."""
 
 
-_RESERVED_PATH_REASONS = {
-    ("model",): "use the MODEL positional argument",
-    ("backend",): "use --backend",
-    ("telemetry_config",): "use --telemetry or --no-telemetry",
-    ("env_overrides",): "set environment overrides in the YAML config",
-    ("internal_request_auth_key",): "keep authentication keys in the YAML config",
-    ("allow_request_chat_template",): "use --allow_request_chat_template",
-    ("disagg_cluster",): "use --disagg_cluster_uri or the YAML config",
-    ("batched_logits_processor",): "use the Python LLM API for live objects",
-    ("checkpoint_loader",): "use the Python LLM API for live objects",
-    ("mpi_session",): "use the Python LLM API for live objects",
-    ("ray_placement_config", "placement_groups"): "use the Python LLM API for live objects",
-    ("speculative_config", "drafter"): "use the Python LLM API for live objects",
-    ("speculative_config", "resource_manager"): "use the Python LLM API for live objects",
-}
+# CLI-owned paths, the server-only YAML keys and the live-object paths, each with
+# the reason shown when --set names it; declared in serve_cli/_serve_options.py.
+_RESERVED_PATH_REASONS = reserved_set_paths()
 
 
 def _format_path(path: Sequence[str]) -> str: