DocumentationThe Agentic Code dataset generator creates synthetic multi-turn coding-agent traces for long-context and KV-cache benchmarking. It models shared prompt layers, session-specific repository context, incremental conversation growth, inter-turn delays, resets, and restart continuations.
The generator writes Mooncake trace JSONL, so the output can be replayed with
the existing mooncake_trace custom dataset loader.
Agentic Code traces divide each session’s prompt into cache-reuse layers:
Probabilistic resets and forced retires end a session; the next primary session gets fresh L2 and L3 blocks while still reusing any shared L1 and L1.5 blocks. Restart continuations are different: they split one logical run into Session A and Session B, and Session B carries the accumulated context and hash IDs from Session A so cache reuse is preserved across the split.
The generator has two turn-management modes.
Reset-driven mode is the default. The generator does not choose a fixed turn count up front. Instead, each session grows turn by turn until one of the end conditions fires.
Turn construction works as follows:
L1 + L1.5 + sampled L2.delay_ms = 0 and timestamp_ms = 0.new_tokens_per_turn.previous_input + previous_output + new_tokens.generation_length for output tokens and extend the
session’s L3 hash IDs.The JSONL output stores incremental turn input in input_length, even though
the in-memory SynthesizedTurn.input_length is cumulative. This is the Mooncake
trace format expected by AIPerf replay.
Reset-driven sessions can end in these ways:
max_prompt_tokens. The overflowing turn is not added.p = base_probability * (1 + (context_scaling - 1) * input_length / max_prompt_tokens).
If the draw succeeds, the session ends before adding that candidate turn.restart_turn_range.Restart splits are controlled by restart_initial_probability and
restart_turn_range. The restart probability decays linearly to zero over the
first 75% of primary sessions. When a split occurs:
restart_split.session_id, keeps the same group_id, and is marked
with is_restart on its first JSONL row.If the config sets turns, the generator switches to explicit turn-count mode.
In this mode it samples a target number of turns from the turns distribution
and attempts to build a session with exactly that many turns.
Explicit turn-count mode cannot be combined with reset or
restart_initial_probability; config validation rejects that combination. A
session that reaches the sampled target ends with target_turn_count.
If the sampled session would hit max_prompt_tokens before reaching the target:
allow_truncation: false, the generator retries the whole session up to
max_session_attempts, then raises an error if it still cannot fit.allow_truncation: true, the generator returns the partial session and
marks it as forced_retire.Create a dataset with the built-in default configuration:
Each run creates a timestamped directory:
The directory contains:
dataset.jsonl: Mooncake-compatible trace rows.manifest.json: seed, session count, config name, and generation parameters.quality.json: target-vs-observed distribution statistics.report.html: summary dashboard for generated sessions.cache_explorer.html: KV block reuse inspection view.simulation.html: browser-based KV cache pressure simulation.synthesize agentic-code validates the generated dataset.jsonl before it
prints the run summary. You can also validate a saved or edited trace directly:
Use the generated dataset.jsonl as a Mooncake trace:
For longer runs, use the same generated trace with the usual Mooncake replay controls:
dataset.jsonl contains one JSON object per request turn:
Important fields:
session_id: logical conversation identifier.input_length: new input tokens for this turn. Turn 0 includes the initial
cached prefix; later turns contain only incremental tokens.output_length: generated output tokens for the turn.hash_ids: KV-cache block IDs for the new input tokens.timestamp: absolute start time in milliseconds for turn 0.delay: delay in milliseconds before a later turn in the same session.group_id: shared-prefix group, emitted on turn 0.is_restart: present on turn 0 when the session continues from an earlier
split.Pass a bundled config name, a config JSON path, or a prior run manifest.
Currently, the only bundled runnable config is default.
The default config models long coding-agent sessions with:
max_prompt_tokens: 167000.block_size: 512 tokens.32000 token global L1 prefix shared by all sessions.layer1_5_tokens: 0,
num_groups: 1).15000 token mean.6000 token mean, capped at 10000.1000 token mean, capped at 1500.Use --max-isl and --max-osl for quick sequence-length overrides:
The config schema is generated at
src/aiperf/dataset/agentic_code_gen/configs/spec.json.