dynamo.mocker

Mock engine used to run Dynamo workflows without a real GPU backend.
View as Markdown

dynamo.mocker publishes 12 classes and 18 functions. Source: components/src/dynamo/mocker/__init__.py

AIC model/backend identity used by native forward-pass estimates.

1from dynamo.mocker import AicEngineConfig
1AicEngineConfig(model_name: str, backend: str, system_name: str = 'h200_sxm', backend_version: Optional[str] = None, tp_size: int = 1, pp_size: int = 1, moe_tp_size: Optional[int] = None, moe_ep_size: Optional[int] = None, attention_dp_size: Optional[int] = None, model_arch: Optional[str] = None, weight_dtype: Optional[str] = None, moe_dtype: Optional[str] = None, activation_dtype: Optional[str] = None, kv_cache_dtype: Optional[str] = None, kv_block_size: Optional[int] = None, extra: Optional[dict[str, str]] = None) -> None

lib/bindings/python/src/dynamo/_core.pyi#L1721

Public methods

init

1__init__(model_name: str, backend: str, system_name: str = 'h200_sxm', backend_version: Optional[str] = None, tp_size: int = 1, pp_size: int = 1, moe_tp_size: Optional[int] = None, moe_ep_size: Optional[int] = None, attention_dp_size: Optional[int] = None, model_arch: Optional[str] = None, weight_dtype: Optional[str] = None, moe_dtype: Optional[str] = None, activation_dtype: Optional[str] = None, kv_cache_dtype: Optional[str] = None, kv_block_size: Optional[int] = None, extra: Optional[dict[str, str]] = None) -> None

No summary available.

source

Per-engine capacity result.

1from dynamo.mocker import EngineCapacity

lib/bindings/python/src/dynamo/_core.pyi#L1793

Request shape and SLA policy for find_engine_capacity_rps.

1from dynamo.mocker import EngineCapacityRequest
1EngineCapacityRequest(isl: int, osl: int, ttft_sla_ms: Optional[float] = None, itl_sla_ms: Optional[float] = None, e2e_latency_sla_ms: Optional[float] = None, kv_hit_rate: Optional[float] = None, optimization_target: OptimizationTarget = OptimizationTarget.Throughput) -> None

lib/bindings/python/src/dynamo/_core.pyi#L1778

Public methods

init

1__init__(isl: int, osl: int, ttft_sla_ms: Optional[float] = None, itl_sla_ms: Optional[float] = None, e2e_latency_sla_ms: Optional[float] = None, kv_hit_rate: Optional[float] = None, optimization_target: OptimizationTarget = OptimizationTarget.Throughput) -> None

No summary available.

source

Engine limits used by engine-level helper queries and default correction bounds.

1from dynamo.mocker import EnginePerfLimits
1EnginePerfLimits(max_num_batched_tokens: int = 8192, max_num_seqs: int = 512, max_kv_tokens: int = 2000000) -> None

lib/bindings/python/src/dynamo/_core.pyi#L1745

Public methods

init

1__init__(max_num_batched_tokens: int = 8192, max_num_seqs: int = 512, max_kv_tokens: int = 2000000) -> None

No summary available.

source

No summary available.

1from dynamo.mocker import MockEngineArgs
1MockEngineArgs(engine_type: str = 'vllm', num_gpu_blocks: Optional[int] = None, block_size: int = 0, max_num_seqs: Optional[int] = 256, max_num_batched_tokens: Optional[int] = 8192, enable_prefix_caching: bool = True, enable_chunked_prefill: bool = True, speedup_ratio: float = 1.0, decode_speedup_ratio: float = 1.0, dp_size: int = 1, startup_time: Optional[float] = None, worker_type: str = 'aggregated', planner_profile_data: Optional[str | os.PathLike[str]] = None, aic_backend: Optional[str] = None, aic_system: Optional[str] = None, aic_backend_version: Optional[str] = None, aic_tp_size: Optional[int] = None, aic_model_path: Optional[str] = None, aic_moe_tp_size: Optional[int] = None, aic_moe_ep_size: Optional[int] = None, aic_attention_dp_size: Optional[int] = None, aic_nextn: Optional[int] = None, aic_nextn_accept_rates: Optional[str] = None, aic_mtp_seed: int = 42, aic_gemm_dtype: Optional[str] = None, aic_moe_dtype: Optional[str] = None, aic_fmha_dtype: Optional[str] = None, aic_kv_cache_dtype: Optional[str] = None, aic_comm_dtype: Optional[str] = None, gpu_memory_utilization: Optional[float] = None, mem_fraction_static: Optional[float] = None, free_gpu_memory_fraction: Optional[float] = None, enable_local_indexer: bool = False, bootstrap_port: Optional[int] = None, handoff_session_timeout_ms: int = 300000, kv_bytes_per_token: Optional[int] = None, kv_transfer_bandwidth: Optional[float] = None, kv_transfer_timing_mode: str = 'full_prompt', reasoning: Optional[ReasoningConfig] = None, response_replay_trace_path: Optional[str | os.PathLike[str]] = None, zmq_kv_events_port: Optional[int] = None, zmq_replay_port: Optional[int] = None, preemption_mode: str = 'lifo', router_queue_policy: Optional[str] = None, sglang: Optional[SglangArgs] = None, trtllm: Optional[TrtllmArgs] = None, num_g2_blocks: Optional[int] = None, num_g3_blocks: Optional[int] = None, offload_batch_size: Optional[int] = None, bandwidth_g1_to_g2_gbps: Optional[float] = None, bandwidth_g2_to_g1_gbps: Optional[float] = None, bandwidth_g2_to_g3_gbps: Optional[float] = None, bandwidth_g3_to_g2_gbps: Optional[float] = None, enable_g4_storage: bool = False, bandwidth_g2_to_g4_gbps: Optional[float] = None, bandwidth_g4_to_g2_gbps: Optional[float] = None, max_model_len: Optional[int] = None, g1_backend: Optional[str] = None) -> None

lib/bindings/python/src/dynamo/_core.pyi#L2038

Public methods

init

1__init__(engine_type: str = 'vllm', num_gpu_blocks: Optional[int] = None, block_size: int = 0, max_num_seqs: Optional[int] = 256, max_num_batched_tokens: Optional[int] = 8192, enable_prefix_caching: bool = True, enable_chunked_prefill: bool = True, speedup_ratio: float = 1.0, decode_speedup_ratio: float = 1.0, dp_size: int = 1, startup_time: Optional[float] = None, worker_type: str = 'aggregated', planner_profile_data: Optional[str | os.PathLike[str]] = None, aic_backend: Optional[str] = None, aic_system: Optional[str] = None, aic_backend_version: Optional[str] = None, aic_tp_size: Optional[int] = None, aic_model_path: Optional[str] = None, aic_moe_tp_size: Optional[int] = None, aic_moe_ep_size: Optional[int] = None, aic_attention_dp_size: Optional[int] = None, aic_nextn: Optional[int] = None, aic_nextn_accept_rates: Optional[str] = None, aic_mtp_seed: int = 42, aic_gemm_dtype: Optional[str] = None, aic_moe_dtype: Optional[str] = None, aic_fmha_dtype: Optional[str] = None, aic_kv_cache_dtype: Optional[str] = None, aic_comm_dtype: Optional[str] = None, gpu_memory_utilization: Optional[float] = None, mem_fraction_static: Optional[float] = None, free_gpu_memory_fraction: Optional[float] = None, enable_local_indexer: bool = False, bootstrap_port: Optional[int] = None, handoff_session_timeout_ms: int = 300000, kv_bytes_per_token: Optional[int] = None, kv_transfer_bandwidth: Optional[float] = None, kv_transfer_timing_mode: str = 'full_prompt', reasoning: Optional[ReasoningConfig] = None, response_replay_trace_path: Optional[str | os.PathLike[str]] = None, zmq_kv_events_port: Optional[int] = None, zmq_replay_port: Optional[int] = None, preemption_mode: str = 'lifo', router_queue_policy: Optional[str] = None, sglang: Optional[SglangArgs] = None, trtllm: Optional[TrtllmArgs] = None, num_g2_blocks: Optional[int] = None, num_g3_blocks: Optional[int] = None, offload_batch_size: Optional[int] = None, bandwidth_g1_to_g2_gbps: Optional[float] = None, bandwidth_g2_to_g1_gbps: Optional[float] = None, bandwidth_g2_to_g3_gbps: Optional[float] = None, bandwidth_g3_to_g2_gbps: Optional[float] = None, enable_g4_storage: bool = False, bandwidth_g2_to_g4_gbps: Optional[float] = None, bandwidth_g4_to_g2_gbps: Optional[float] = None, max_model_len: Optional[int] = None, g1_backend: Optional[str] = None) -> None

No summary available.

source

from_json

1from_json(config_json: str) -> MockEngineArgs

No summary available.

source

copy

1copy() -> MockEngineArgs

No summary available.

source

is_prefill

1is_prefill() -> bool

No summary available.

source

is_decode

1is_decode() -> bool

No summary available.

source

with_overrides

1with_overrides(bootstrap_port: Optional[int] = None, zmq_kv_events_port: Optional[int] = None, zmq_replay_port: Optional[int] = None, kv_bytes_per_token: Optional[int] = None, num_gpu_blocks: Optional[int] = None, aic_backend: Optional[str] = None, aic_system: Optional[str] = None, aic_backend_version: Optional[str] = None, aic_tp_size: Optional[int] = None, aic_model_path: Optional[str] = None, aic_moe_tp_size: Optional[int] = None, aic_moe_ep_size: Optional[int] = None, aic_attention_dp_size: Optional[int] = None, aic_nextn: Optional[int] = None, aic_nextn_accept_rates: Optional[str] = None, aic_mtp_seed: Optional[int] = None, aic_gemm_dtype: Optional[str] = None, aic_moe_dtype: Optional[str] = None, aic_fmha_dtype: Optional[str] = None, aic_kv_cache_dtype: Optional[str] = None, aic_comm_dtype: Optional[str] = None, gpu_memory_utilization: Optional[float] = None, mem_fraction_static: Optional[float] = None, free_gpu_memory_fraction: Optional[float] = None, enable_prefix_caching: Optional[bool] = None, worker_type: Optional[str] = None) -> MockEngineArgs

No summary available.

source

No summary available.

1from dynamo.mocker import OptimizationTarget

lib/bindings/python/src/dynamo/_core.pyi#L1774

Result of processing —planner-profile-data argument. Cleans up tmpdir on deletion.

1from dynamo.mocker.args import ProfileDataResult
1ProfileDataResult(npz_path: Path | None, tmpdir: tempfile.TemporaryDirectory | None)

components/src/dynamo/mocker/args.py#L51

Public methods

init

1__init__(npz_path: Path | None, tmpdir: tempfile.TemporaryDirectory | None)

No summary available.

source

No summary available.

1from dynamo.mocker import ReasoningConfig
1ReasoningConfig(start_thinking_token_id: int, end_thinking_token_id: int, thinking_ratio: float) -> None

lib/bindings/python/src/dynamo/_core.pyi#L2010

Public methods

init

1__init__(start_thinking_token_id: int, end_thinking_token_id: int, thinking_ratio: float) -> None

No summary available.

source

Engine-level performance model backed by AIC forward-pass modeling.

1from dynamo.mocker import RustEnginePerfModel

lib/bindings/python/src/dynamo/_core.pyi#L1802

Public methods

best_available

1best_available(*, engine_args: Optional[MockEngineArgs] = None, aic_config: Optional[AicEngineConfig] = None, worker_type: Optional[str] = None, limits: Optional[EnginePerfLimits] = None, options: Optional[RustEnginePerfOptions] = None, bootstrap_fpms: Optional[Any] = None) -> RustEnginePerfModel

Build from all available inputs; explicit AIC config is preferred, then engine args, then regression-only.

source

from_regression

1from_regression(*, worker_type: str, limits: EnginePerfLimits, options: Optional[RustEnginePerfOptions] = None, bootstrap_fpms: Optional[Any] = None) -> RustEnginePerfModel

Build a regression-only model that learns from observed FPM wall times.

source

from_native

1from_native(*, aic_config: AicEngineConfig, worker_type: str, limits: EnginePerfLimits, options: Optional[RustEnginePerfOptions] = None, bootstrap_fpms: Optional[Any] = None) -> RustEnginePerfModel

Build a strict native AIC model; unsupported AIC configs raise an error.

source

estimate_forward_pass_time

1estimate_forward_pass_time(metrics_by_rank: Any) -> Optional[float]

Estimate one scheduled forward-pass iteration in seconds from current-version FPMs.

source

tune_with_fpms

1tune_with_fpms(iterations: Any) -> None

Tune with current-version observed FPMs: outer list is iterations, inner list is attention-DP ranks.

source

diagnostics

1diagnostics() -> str

Return AIC diagnostics as a JSON string.

source

get_min_correction_factor

1get_min_correction_factor() -> Optional[float]

Return the minimum ready native correction factor, or None if no factor is ready.

source

get_max_correction_factor

1get_max_correction_factor() -> Optional[float]

Return the maximum ready native correction factor, or None if no factor is ready.

source

get_avg_correction_factor

1get_avg_correction_factor() -> Optional[float]

Return the average ready native correction factor, or None if no factor is ready.

source

get_queued_prefill_time

1get_queued_prefill_time(metrics_by_rank: Any) -> Optional[float]

Estimate queued prefill drain time; adjust queued tokens outside the shim for KV reuse.

source

get_scheduled_decode_itl

1get_scheduled_decode_itl(metrics_by_rank: Any) -> Optional[float]

Estimate scheduled decode ITL in seconds; aggregated workers include scheduled or learned average prefill load.

source

find_engine_capacity_rps

1find_engine_capacity_rps(request: EngineCapacityRequest) -> Optional[EngineCapacity]

Search sustainable per-engine RPS; inspect eligible to see whether eligible SLA metrics passed.

source

Online tuning options for RustEnginePerfModel.

1from dynamo.mocker import RustEnginePerfOptions
1RustEnginePerfOptions(max_observations: int = 64, min_observations: int = 5, bucket_count: int = 16, max_num_tokens: int = 8192, max_batch_size: int = 512, max_kv_tokens: int = 2000000) -> None

lib/bindings/python/src/dynamo/_core.pyi#L1760

Public methods

init

1__init__(max_observations: int = 64, min_observations: int = 5, bucket_count: int = 16, max_num_tokens: int = 8192, max_batch_size: int = 512, max_kv_tokens: int = 2000000) -> None

No summary available.

source

No summary available.

1from dynamo.mocker import SglangArgs
1SglangArgs(schedule_policy: Optional[str] = None, page_size: Optional[int] = None, max_prefill_tokens: Optional[int] = None, chunked_prefill_size: Optional[int] = None, clip_max_new_tokens: Optional[int] = None, schedule_conservativeness: Optional[float] = None) -> None

lib/bindings/python/src/dynamo/_core.pyi#L2019

Public methods

init

1__init__(schedule_policy: Optional[str] = None, page_size: Optional[int] = None, max_prefill_tokens: Optional[int] = None, chunked_prefill_size: Optional[int] = None, clip_max_new_tokens: Optional[int] = None, schedule_conservativeness: Optional[float] = None) -> None

No summary available.

source

No summary available.

1from dynamo.mocker import TrtllmArgs
1TrtllmArgs(capacity_scheduler_policy: Optional[str] = None) -> None

lib/bindings/python/src/dynamo/_core.pyi#L2031

Public methods

init

1__init__(capacity_scheduler_policy: Optional[str] = None) -> None

No summary available.

source

No summary available.

1from dynamo.mocker.config import apply_worker_engine_args_overrides
1apply_worker_engine_args_overrides(engine_args: MockEngineArgs, *, kv_bytes_per_token: int | None = None, bootstrap_port: int | None = None, zmq_kv_events_port: int | None = None, zmq_replay_port: int | None = None, aic_mtp_seed: int | None = None) -> MockEngineArgs

components/src/dynamo/mocker/config.py#L333

No summary available.

1from dynamo.mocker.config import build_mocker_engine_args
1build_mocker_engine_args(args: argparse.Namespace) -> MockEngineArgs

components/src/dynamo/mocker/config.py#L216

No summary available.

1from dynamo.mocker.config import build_runtime_config
1build_runtime_config(engine_args: MockEngineArgs) -> tuple[int, ModelRuntimeConfig]

components/src/dynamo/mocker/config.py#L351

Compute the stagger delay based on worker count to give the frontend time to process registrations. Returns the delay in seconds between worker launches.

1from dynamo.mocker.main import compute_stagger_delay
1compute_stagger_delay(num_workers: int, stagger_delay: float) -> float

components/src/dynamo/mocker/main.py#L104

Shutdown dynamo distributed runtime instances. The endpoints will be immediately invalidated so no new requests will be accepted.

1from dynamo.mocker.main import graceful_shutdown
1graceful_shutdown(runtimes: list)

components/src/dynamo/mocker/main.py#L34

Launch mocker worker(s) with isolated DistributedRuntime instances.

1from dynamo.mocker.main import launch_workers
1launch_workers(args: argparse.Namespace, base_engine_args)

Each worker gets its own DistributedRuntime, which means:

  • Separate etcd/NATS connections
  • Separate Component instances (no shared overhead)
  • Independent service registration and stats scraping
  • But still sharing the same tokio runtime (efficient)

components/src/dynamo/mocker/main.py#L126

No summary available.

1from dynamo.mocker.config import load_mocker_engine_args
1load_mocker_engine_args(args: argparse.Namespace) -> MockEngineArgs

components/src/dynamo/mocker/config.py#L321

No summary available.

1from dynamo.mocker.main import main
1main()

components/src/dynamo/mocker/main.py#L254

No summary available.

1from dynamo.mocker.args import non_negative_float
1non_negative_float(value: str) -> float

components/src/dynamo/mocker/args.py#L41

No summary available.

1from dynamo.mocker.args import non_negative_int
1non_negative_int(value: str) -> int

components/src/dynamo/mocker/args.py#L31

Parse command-line arguments for the Dynamo mocker engine.

1from dynamo.mocker.args import parse_args
1parse_args(argv: list[str] | None = None) -> argparse.Namespace

Returns

  • argparse.Namespace — argparse.Namespace: Parsed command-line arguments.

components/src/dynamo/mocker/args.py#L175

Parse comma-separated bootstrap ports string into list of integers.

1from dynamo.mocker.args import parse_bootstrap_ports
1parse_bootstrap_ports(ports_str: str | None) -> list[int]

components/src/dynamo/mocker/args.py#L168

No summary available.

1from dynamo.mocker.args import positive_int
1positive_int(value: str) -> int

components/src/dynamo/mocker/args.py#L21

Pre-fetch model from HuggingFace to avoid rate limiting with many workers.

1from dynamo.mocker.main import prefetch_model
1prefetch_model(model_path: str) -> None

components/src/dynamo/mocker/main.py#L45

Resolve —planner-profile-data to an NPZ file path.

1from dynamo.mocker.args import resolve_planner_profile_data
1resolve_planner_profile_data(planner_profile_data: Path | None) -> ProfileDataResult

Handles backward compatibility by accepting either:

  1. A mocker-format NPZ file (returned as-is)
  2. A profiler-style results directory (converted to mocker-format NPZ)

Parameters

planner_profile_data
Path | None

Path from —planner-profile-data argument.

Returns

  • ProfileDataResult — ProfileDataResult with npz_path and optional tmpdir for cleanup.

Raises

  • FileNotFoundError — If path doesn’t contain valid profile data in any supported format.

components/src/dynamo/mocker/args.py#L69

No summary available.

1from dynamo.mocker import run_mocker_trace_replay
1run_mocker_trace_replay(trace_files, extra_engine_args = None, router_config = None, num_workers = 1, replay_concurrency = None, router_mode = 'round_robin', arrival_speedup_ratio = 1.0, trace_block_size = None, trace_format = 'mooncake', trace_shared_prefix_ratio = 0.0, trace_num_prefix_groups = 0, model_name = None, sla_ttft_ms = None, sla_itl_ms = None, sla_e2e_ms = None)

components/src/dynamo/mocker/__init__.py#L41

Resolve disaggregation mode from —disaggregation-mode or legacy boolean flags. Raises ValueError if validation fails.

1from dynamo.mocker.args import validate_worker_type_args
1validate_worker_type_args(args: argparse.Namespace) -> None

components/src/dynamo/mocker/args.py#L122

Main worker function that launches mocker instances.

1from dynamo.mocker.main import worker
1worker()

Each mocker gets its own DistributedRuntime instance for true isolation, while still sharing the same event loop and tokio runtime.

components/src/dynamo/mocker/main.py#L63