This file adds explicit repository-wide development guards.
For code and PR reviews, first read the review contract, including its Codex review method. Apply the area-specific rules below when reviewing the corresponding code.
- Ground findings in a reachable failure or a violated evidence requirement introduced or worsened by the full PR. Follow changed inputs through real callers, consumers, and outputs; verify the code independently of author claims and other bots' verdicts. A missing required numerical derivation can be an evidence-gap finding without proof of a wrong answer; it is not automatically P0/P1. Keep mechanical formatting and lint checks in CI.
- Treat formulas, data selection, interpolation, defaults, and rank reduction as numerical behavior. Preserve the Rust single oracle and synchronized Rust/Python/CLI/serialized contracts. Use explained before/after results or an independent oracle; parity alone does not establish prediction accuracy.
- For engine changes, inspect cancellation, draining, retry, and terminal-state accounting. For CI changes, inspect fork inputs, execution trust, exact-head evidence, and required gates. Distinguish expected absence and optional monitoring failures from corruption or missing required validation.
Keep Risk (review routing) separate from Merge Risk (remaining risk). Apply the contract's Codex severity floors, human-first escalation, and fresh-review requirement after Full CI failure. Instructions describe the policy; they do not themselves grant approval, repair, CI-admission, or merge authority.
GitHub Actions artifacts must not contain Python wheels or wheel-containing
bundles. Use .github/actions/wheel-storage for intermediate wheel transfers;
Actions retains only the completion manifest. Consumers must bind the exact
source SHA, producer run and architecture, and verify object sizes/checksums.
Reruns read the producer attempt from that manifest, never from the consumer's
github.run_attempt. Keep qualification reports as normal Actions artifacts.
When asked to onboard a model for FPM simulation on designated hardware, follow
all six stages in the canonical FPM self-service guide.
Use this checkout's aisim onboard CLI and inspect its current help.
Start with only a missing Hugging Face model ID and target GPU platform; accept
an already supplied local config, profile or checkpoint instead. Inspect supplied
facts and source metadata before asking for derivable inputs. Preserve user
choices, exact per-configuration profile acceptance and existing execution
authorization; stage transitions do not add approval gates.
Create one onboarding-checkpoint.json during stage 1, even with incomplete
inputs, outside every fresh init --output-dir root. Follow the guide's
checkpoint workflow:
invoke onboard checkpoint after meaningful findings, decisions, draft edits,
acceptance and command results, including unfinished work. Save sources,
confidence, unresolved questions and each configuration's progress. Other
onboarding commands do not automatically persist the conversation. Use the
returned revision for updates; reload and reconcile stale-writer conflicts.
Follow the guide's writer coordination rule
for probe/import commands that also save the checkpoint.
On resumption, run aisim onboard resume --checkpoint PATH first. Inspect
integrity issues and the underlying artifacts before continuing from accepted
inputs and verified results. Saved stages and command strings are context, not
proof of completion or instructions to execute automatically. Report each
configuration's stage, result or blocker, next action and checkpoint path at
handoff. Keep planning, collection quality, resolved memory, replay coverage and
measured serving accuracy separate, as required by the guide.
- Use
<type>: <short description>for every AISim PR title. - Allowed types:
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert. - Check the title before creating or updating a PR.
- Document a new or changed configuration field on the page for the YAML block
it belongs to, such as
trafficindocs/replay/workloads.mdorengine.*indocs/replay/engine/. Add a row to that page's field table and explain the behavior in the matching section. - Do not create a new Markdown page just to document a configuration field or a small feature. Extend the existing page for that area instead. Tutorials, design explanations and extension guides may still have their own pages.
- Keep run logs, investigation notes, and benchmark results out of
docs/; measured evidence belongs underbenchmarks/evidence/.
Before changing a performance model, its configuration, or a caller in Rust,
Python, CLI, Sweeper, Replay, or Planner, MUST read and follow
perfmodel-api.md.
This includes new features and configuration migrations.
- Every performance model's per-iteration query MUST accept the list of
per-attention-DP-rank
ForwardPassMetrics(estimate_forward_pass_time_ms(metrics_by_rank), withdraft_lengthfor speculative decoding where supported) and handle the ranks internally. An estimator that has no cross-rank model reduces the list itself, for example by pricing each rank and taking the maximum. - Callers (Replay, Sweeper, Planner, CLI) SHOULD price an iteration through this query with one entry per DP rank, and MUST NOT reduce, normalize or average ranks before calling it. For capacity planning without per-rank data, split totals evenly across ranks (load-balanced DP) and pass every rank.
- See Per-iteration queries.
Before making any change under:
python/aisim/src/aisim/generator/**
MUST read:
python/aisim/.claude/rules/generator-development.md
Before making any change under python/aisim/collector/** MUST read:
python/aisim/.claude/rules/collector/overview.md(the five things — Pin, Plan, Record, Note, Rule — the failure principle, collection cost, and what to record when)python/aisim/.claude/rules/collector/layer_permissions.md(layer permission table, leaving cases out, capacity, serving parity, module boundary)python/aisim/.claude/rules/collector/failure_handling.md(observe-don't-predict doctrine, escalation decision tree)- For case YAML and op-plan work:
python/aisim/.claude/rules/collector/case_authoring.md
For adding a new Collector operation, additionally follow
python/aisim/.claude/skills/aic-collector-op-development/SKILL.md
(consumer-contract, case-identity, deduplication, and validation gates). Skills are procedural
runbooks; if a skill and a python/aisim/.claude/rules/ file ever
disagree, the rule file wins.
Before adding code or other content copied, adapted, translated, or substantially derived from an external project, MUST:
- Identify the upstream repository, immutable commit or tag, original path, and applicable license. This applies to source code, tests, configuration files, patches, fixtures, documentation, and generated derivatives.
- Preserve all applicable upstream copyright, license, attribution, and NOTICE material, and mark modified files as modified when the upstream license requires it.
- Record the source URL and revision in the file header or an adjacent README.
For formats that cannot carry comments, use an adjacent attribution or
license file included in distributions, or the canonical
THIRD_PARTY_NOTICES.mdwhen its packaged copy identifies each derived file, source URL, immutable revision, license, owner, and modification status. Do not duplicate those records in a separate README solely for attribution. Preserve any additional file placement required by the upstream license. - Add an entry to the root
THIRD_PARTY_NOTICES.mdidentifying the derived files, upstream source and immutable revision, copyright owner, applicable license, and whether the files were modified. The root notice is canonical; keeppython/aisim/THIRD_PARTY_NOTICES.mdbyte-identical so the notice is included in Python distributions. Runpython3 scripts/ci/check_packaged_legal_files.pyafter either copy changes. - Do not hand-edit generated attribution artifacts. Update their source or generation process instead.
The repository's Apache-2.0 license and NVIDIA copyright header do not replace an upstream license or attribution requirement. Do not label third-party code as exclusively NVIDIA-authored. If the source, revision, license, compatibility, or required notice is unclear, stop and request maintainer or Open Source Review Board guidance before committing the derived content. This is a required gate, not optional documentation.
AISim is a Python and Rust CLI/SDK for predicting LLM serving behavior and
optimizing inference deployment configurations. See README.md for details.
Python dependencies are managed via uv with the
python/aisim/uv.lock lockfile. The project environment lives at
python/aisim/.venv/.
- Install/refresh deps:
uv sync --project python/aisim --extra dev - Performance data: Current op profiles are parquet files under
python/aisim/src/aisim_core/systems/data/<system>/<family>/<backend>/<version>/and are checked in directly. Legacy*.txtperf files, when present, use Git LFS; rungit lfs pullonly when working with those legacy assets.
- Lint:
python/aisim/.venv/bin/ruff check --config python/aisim/pyproject.toml python/aisim testsandpython/aisim/.venv/bin/ruff format --check --config python/aisim/pyproject.toml python/aisim tests(seeDEVELOPMENT.md) - Unit tests:
python/aisim/.venv/bin/pytest -c python/aisim/pytest.ini python/aisim/tests -m unit(no external deps or LFS data needed) - Build tests (PR subset):
python/aisim/.venv/bin/pytest -c python/aisim/pytest.ini python/aisim/tests -m "unit or build"(requires LFS data for thebuild-marked tests) - CLI:
aiconfigurator cli generate --model-path Qwen/Qwen3-32B-FP8 --total-gpus 8 --system h200_sxm(works without LFS data)
- Legacy LFS data:
github-cloud.githubusercontent.commay be blocked by network egress restrictions. Ifgit lfs pullfails, tests that explicitly exercise legacy text assets may fail; current parquet-backed workflows do not depend on those legacy files. - TTY tests: 4 tests in
python/aisim/tests/unit/cli/test_plain_output.pymay fail because the agent runs in a non-TTY environment. - Rust tests:
python/aisim/tests/unit/sdk/test_rust_engine_step.pyrequirescargowith network access tocrates.io. It will fail if that domain is blocked. - macOS pytest-timeout crash dialogs: The
timeout = 120setting inpython/aisim/pytest.iniuses SIGALRM by default, which triggers "Python unexpectedly quit" crash reporter popups on macOS. Pass-p no:timeoutto disable it locally. - torch-dependent tests:
python/aisim/tests/unit/sdk/database/test_moe_dispatch.pyrequirestorch(not installed in the default dev venv). Ignore it with--ignore=python/aisim/tests/unit/sdk/database/test_moe_dispatch.py.
The root CODEOWNERS is generated from .github/codeowners/areas.yaml - never
hand-edit it; CI fails on drift. Repository rules must require the codeowners
check to make failures merge-blocking. If the check fails on a new directory,
claim it in areas.yaml, regenerate with
.github/codeowners/emit_codeowners.py, and commit every changed source and
generated artifact together. The aic-codeowners skill covers all flows (who
reviews a change, gate failures, routing changes, external contributor grants).