Synthesize User Workload

Synthesize User Workload

<!--
SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

Create the durable workload contract and user-provided baseline DGD that every later optimization role receives. Do not search for or select a recipe, deploy, benchmark, or propose tuning changes.

Inputs

Require:

• the user's initial optimization request exactly as received;
• the user-provided DGD as an attachment, local file path, or pasted YAML, when one exists; otherwise the ladder-confirmed baseline manifest handed over by user-interviewer with its confirmation record;
• any attached workload descriptions, traces, or other local file paths;
• an optional caller-supplied EXP_ID or EXP_ROOT; and
• an existing user_workload.yaml only when the user is refining the interview before downstream work begins.

Read agent-docs/rules/execution/user-workload.md, agent-docs/rules/execution/run-artifacts.md, and agent-docs/references/definitions.md before interviewing or writing the file.

Extract Before Asking

Build a fact table from the initial request and attachments. Record only facts the user supplied or that a referenced artifact proves. Keep the source of each fact while interviewing, but do not copy private conversation text into the final YAML.

Resolve these blocking fields:

• one concrete baseline DynamoGraphDeployment: either user-provided, or produced by the baseline-source ladder (agents/user-interviewer/AGENTS.md) and explicitly confirmed by the user;
• workload profile name, type, and a concrete description of the serving traffic;
• exact model source and revision when the user fixes one, plus the fallback policy when the requested revision may be unsupported by the available engine or weights (fall back to a named alternative and mark the target blocked, or halt);
• the user's current production deployment configuration when one exists (path or paste): it anchors every later comparison and seeds topology priors; when unavailable, record that explicitly as a known comparison limitation;
• allowed hardware type and count, including heterogeneous allocations;
• Kubernetes context and existing namespace; and
• either an exact trace or enough traffic-shape information to configure a defensible benchmark. A parametric description is a first-class option between presets and traces: AIPerf synthesizes static shapes (ISL/OSL mean and stddev, prefix reuse via the prefix-prompt pool and length controls) and multiturn sessions (session count, turns per session mean/stddev, per-turn delay) in a single command — offer "describe your workload" whenever the user has neither a matching preset nor a trace, and record the elicited parameters in the contract.

Objectives, SLOs, framework, precision, topology, storage class, and exact token or load values may remain unspecified when the user explicitly has no constraint or preference. Represent those values with the schema's empty value; do not invent defaults.

Interview Minimally

Ask only for blocking facts that remain unknown or contradictory after reading all supplied context.

• Group related questions into one concise turn.
• Prefer a bounded choice only when the available choices are supported by the repository or user context.
• Explain why a requested fact blocks DGD handoff or reproducible measurement.
• Accept natural-language answers; do not make the user author YAML.
• Do not ask for secret values, kubeconfig contents, registry credentials, or Kubernetes Secret data.
• Do not add a ceremonial confirmation round when the user's message already provides an unambiguous value.
• When the user supplies resource limits — a ceiling on total concurrent GPU use, or knobs they forbid changing — record them in the contract's resources block. Ask about limits only when the run's scope makes them blocking (for example, when architectural changes such as replica scaling or disaggregation are in scope and the ceiling determines what may be proposed). Candidates run serially under the current iteration model; parallel candidate execution is not supported.
• If the user has not stated budgets, ask for them in the same interview batch — GPU-hours, wall clock, and failed-deploy limit — proposing sensible defaults for this engagement's scope; record the answers verbatim in the contract's budgets block, and null for any limit the user declines to state (a null budget leaves that limit ungated).
• When the user's production deployment shape differs from the unit under test (for example, fleet-level traffic numbers but a single-replica test deployment), derive the per-unit load explicitly and confirm it with the user before recording it.

Before writing the contract, enumerate every fact the downstream roles (deployer, benchmarker, hypothesis loop, analyzer) will require, and ask all still-missing ones in the single upfront batch: a question that first surfaces after the optimization loop has started is an interview defect. Record any fact the user defers as an explicit assumption in the contract so the loop can proceed non-blockingly.

If blocking facts remain, return the questions to the parent and stop without handing work to a downstream role.

Establish The Experiment Root

Use the exact caller-supplied EXP_ROOT when present. Otherwise create one unused directory under runs/ using a stable, filesystem-safe EXP_ID derived from the UTC creation timestamp and workload profile slug. Never reuse or overwrite an existing experiment directory.

The user interviewer owns creation of EXP_ROOT; downstream roles must receive its exact path rather than infer it from directory order or modification time. Create <EXP_ROOT>/manifest.yaml alongside it with the session metadata run-artifacts.md defines (timestamps, repo commit, cluster context name, agent versions when known).

Capture The User-Provided DGD

Create the canonical baseline input:

<EXP_ROOT>/inputs/user_provided_dgd.yaml

• When the user supplies a file, copy its bytes without editing the source or canonical copy.
• When the user pastes YAML, materialize that YAML without changing its configuration.
• When the baseline came from the ladder (rung 2 adapted recipe or rung 3 authored draft), materialize the exact manifest the user confirmed - byte-for-byte as confirmed, including any user amendments - and record the matching origin and origin_source.
• Parse the canonical copy as YAML and require exactly one mapping document whose kind is DynamoGraphDeployment; reject a file containing zero or multiple such documents, since a multi-DGD file leaves recipe-deployer without a deterministic baseline.
• Reject embedded secret values or Kubernetes Secret resources; references to pre-existing Secret names are allowed.
• Reject a recipe directory, catalog choice, generated substitute, or inferred default in place of the user's DGD. A specific manifest the user explicitly presents OR confirms as their baseline is a user-provided baseline, whatever its origin; the rejection targets substitutes the user never confirmed. Record the provenance in the contract: deployment.origin (user, recipe-confirmed, or agent-authored) and deployment.origin_source per the schema.
• Do not patch cluster compatibility or performance settings during capture.
• Compute the canonical copy's SHA256 before writing the workload contract.
• If the DGD contradicts an explicit workload constraint, return the contradiction as a blocking question; do not silently choose which input wins.

Never overwrite the canonical DGD after it is captured. A changed user DGD starts a new experiment.