make agentic warmup limits exclusive

Signed-off-by: Cam Quilici <cjquilici@gmail.com>

Author: cquil11

docs/cli-options.md

@@ -1125,12 +1125,12 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 
 #### `--agentic-cache-warmup-duration` `<float>`
 
-Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay.
+Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay. Mutually exclusive with --warmup-requests-per-lane.
 <br/>_Constraints: > 0_
 
 #### `--warmup-requests-per-lane` `<int>`
 
-Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Requires --agentic-cache-warmup-duration, which remains the safety deadline.
+Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Mutually exclusive with --agentic-cache-warmup-duration.
 <br/>_Constraints: > 0_
 
 #### `--agentic-warmup-grace-period` `<float>`
@@ -2660,12 +2660,12 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 
 #### `--agentic-cache-warmup-duration` `<float>`
 
-Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay.
+Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay. Mutually exclusive with --warmup-requests-per-lane.
 <br/>_Constraints: > 0_
 
 #### `--warmup-requests-per-lane` `<int>`
 
-Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Requires --agentic-cache-warmup-duration, which remains the safety deadline.
+Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Mutually exclusive with --agentic-cache-warmup-duration.
 <br/>_Constraints: > 0_
 
 #### `--agentic-warmup-grace-period` `<float>`

docs/tutorials/agentx-mvp.md

@@ -417,15 +417,16 @@ duration expires, it stops issuing new requests, drains requests already on
 the wire, snapshots each live root, subagent, and unresolved join, and starts
 profiling from that exact state.
 
-For repeatable warmup depth, also set
-`--warmup-requests-per-lane REQUESTS`. Each concurrency lane is
-then allowed exactly that many warmup wire requests, including its initial
-snapshot-priming requests. For example, `--concurrency 16` with
-`--warmup-requests-per-lane 10` targets 160 warmup requests,
-with a strict 10-request quota on every lane. The duration is still required as
-a safety deadline: issuance stops at the per-lane quotas or the duration,
-whichever comes first. If the duration wins, a slow run sends fewer than the
-configured request budget.
+For repeatable warmup depth, use
+`--warmup-requests-per-lane REQUESTS` instead. Each concurrency lane is allowed
+exactly that many warmup wire requests, including its initial snapshot-priming
+requests. For example, `--concurrency 16` with
+`--warmup-requests-per-lane 10` produces 160 warmup requests, with a strict
+10-request quota on every lane.
+
+`--agentic-cache-warmup-duration` and `--warmup-requests-per-lane` are mutually
+exclusive: choose a time-bounded warmup or a deterministic request-bounded
+warmup.
 
 These requests remain part of warmup, so they are excluded from exported
 request metrics.

src/aiperf/config/config.py

@@ -609,8 +609,8 @@ def validate_cache_bust_compatibility(self) -> Self:
     def validate_agentic_cache_warmup(self) -> Self:
         """Restrict accelerated cache warmup to the agentic_replay timing mode.
 
-        ``--agentic-cache-warmup-duration`` and its optional deterministic
-        request budget are consumed solely by
+        The mutually exclusive duration and deterministic request-budget modes
+        are consumed solely by
         ``aiperf.timing.config._build_agentic_warmup_config``, which only runs
         when the profiling phases resolve to AGENTIC_REPLAY. On any other run
         the value is silently dropped, so an unguarded flag is a no-op the user
@@ -644,12 +644,12 @@ def validate_agentic_cache_warmup(self) -> Self:
 
         if any(
             getattr(phase, "warmup_requests_per_lane", None) is not None
-            and getattr(phase, "agentic_cache_warmup_duration", None) is None
+            and getattr(phase, "agentic_cache_warmup_duration", None) is not None
             for phase in profiling_phases
         ):
             raise ValueError(
-                "--warmup-requests-per-lane requires "
-                "--agentic-cache-warmup-duration as a safety deadline."
+                "--warmup-requests-per-lane and "
+                "--agentic-cache-warmup-duration are mutually exclusive."
             )
 
         if self.scenario is not None:

src/aiperf/config/flags/cli_config.py

@@ -2280,7 +2280,8 @@ def url(self) -> str:
             "After the normal snapshot warmup drains, AIPerf continues the live "
             "trajectories without recorded idle delays and with one-token outputs, "
             "then drains and resumes profiling from the resulting trajectory state "
-            "using each live stream's residual next-turn delay.",
+            "using each live stream's residual next-turn delay. Mutually exclusive "
+            "with --warmup-requests-per-lane.",
         ),
         CLIParameter(
             name=("--agentic-cache-warmup-duration",),
@@ -2295,8 +2296,8 @@ def url(self) -> str:
             description="Deterministic agentic cache-pressure warmup request "
             "budget per concurrency lane. For example, 10 with concurrency 16 "
             "caps warmup at 160 wire requests, including initial snapshot "
-            "priming. Requires --agentic-cache-warmup-duration, which remains "
-            "the safety deadline.",
+            "priming. Mutually exclusive with "
+            "--agentic-cache-warmup-duration.",
         ),
         CLIParameter(
             name=("--warmup-requests-per-lane",),

src/aiperf/config/phases.py

@@ -360,7 +360,8 @@ class BasePhaseConfig(AdaptiveScalePhaseMixin, BaseConfig):
             "continues the live trajectories without recorded idle delays and with "
             "one-token outputs for this long, then drains and resumes profiling "
             "from the resulting trajectory state. Read off the profiling phase by "
-            "``timing.config._build_agentic_warmup_config``. None disables it.",
+            "``timing.config._build_agentic_warmup_config``. Mutually exclusive "
+            "with warmup_requests_per_lane. None disables it.",
         ),
     ]
 
@@ -373,8 +374,7 @@ class BasePhaseConfig(AdaptiveScalePhaseMixin, BaseConfig):
             "warmup request budget per concurrency lane. The total warmup "
             "wire-request cap is this value multiplied by the number of live "
             "trajectory lanes, including the initial snapshot-priming "
-            "requests. Requires agentic_cache_warmup_duration, which remains "
-            "the safety deadline; warmup stops when either limit is reached.",
+            "requests. Mutually exclusive with agentic_cache_warmup_duration.",
         ),
     ]