@tduncan / Nvidia-Optimization-Stack-VLLM
Code Commits Issues Pulls Cloud Agent CI/CD
main
main
md 159 lines 5.77 KB
Rendered Raw
1 # Agent Instructions for vLLM
2
3 > These instructions apply to **all** AI-assisted contributions to `vllm-project/vllm`.
4 > Breaching these guidelines can result in automatic banning.
5
6 ## 1. Contribution Policy (Mandatory)
7
8 ### Duplicate-work checks
9
10 Before proposing a PR, run these checks:
11
12 ```bash
13 gh issue view <issue_number> --repo vllm-project/vllm --comments
14 gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
15 gh pr list --repo vllm-project/vllm --state open --search "<short area keywords>"
16 ```
17
18 - If an open PR already addresses the same fix, do not open another.
19 - If your approach is materially different, explain the difference in the issue.
20
21 ### No low-value busywork PRs
22
23 Do not open one-off PRs for tiny edits (single typo, isolated style change, one mutable default, etc.). Mechanical cleanups are acceptable only when bundled with substantive work.
24
25 ### Accountability
26
27 - Pure code-agent PRs are **not allowed**. A human submitter must understand and defend the change end-to-end.
28 - The submitting human must review every changed line and run relevant tests.
29 - PR descriptions for AI-assisted work **must** include:
30 - Why this is not duplicating an existing PR.
31 - Test commands run and results.
32 - Model evaluation results when the change affects output, accuracy, or serving.
33 - Clear statement that AI assistance was used.
34 - Use vLLM's [`/pr-checklist`](.agents/skills/pr-checklist/SKILL.md) skill before submitting a PR to ensure quality and adherence to the contribution guidelines.
35
36 ### Fail-closed behavior
37
38 If work is duplicate/trivial busywork, **do not proceed**. Return a short explanation of what is missing.
39
40 ---
41
42 ## 2. Development Workflow
43
44 - **Never use system `python3` or bare `pip`/`pip install`.** All Python commands must go through `uv` and `.venv/bin/python`.
45
46 ### Environment setup
47
48 ```bash
49 # Install `uv` if you don't have it already:
50 curl -LsSf https://astral.sh/uv/install.sh | sh
51
52 # Always use `uv` for Python environment management:
53 uv venv --python 3.12
54 source .venv/bin/activate
55
56 # Always make sure `pre-commit` and its hooks are installed:
57 uv pip install -r requirements/lint.txt
58 pre-commit install
59 ```
60
61 ### Installing dependencies
62
63 ```bash
64 # Start with precompiled artifacts for an editable install:
65 VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto
66 ```
67
68 For C/C++ or CUDA changes, follow the
69 [incremental compilation workflow](docs/contributing/incremental_build.md) to
70 configure and perform incremental builds.
71
72 ### Tests
73
74 > Requires [Environment setup](#environment-setup) and [Installing dependencies](#installing-dependencies).
75
76 ```bash
77 # Install test dependencies (use cuda.in on non-x86_64):
78 uv pip install -r requirements/test/cuda.in
79
80 # Run a specific test file:
81 .venv/bin/python -m pytest tests/path/to/test_file.py -v
82 ```
83
84 When adding tests:
85
86 - **Design before you write.** Answer four questions first: what is the module
87 for, what is its I/O contract, what failure am I guarding against, and what is
88 the cheapest level that catches it (unit over integration over e2e)?
89 - **Reuse before create.** Extend existing test files, `conftest.py` fixtures, and
90 helpers; add a new file only when no nearby suite fits.
91 - **Test behavior with intent.** Assert observable outcomes through public APIs;
92 state why in the name or docstring. Skip trivial wiring; flaky tests are worse
93 than no tests.
94 - **Keep it minimal.** One behavior per test and the smallest setup that
95 triggers it; if the test diff dwarfs the code change, cut scope.
96 - **No one-off kernel benchmarks in `tests/`.** Put kernel perf work in
97 `benchmarks/kernels/`; prove correctness in existing pytest suites.
98 - **Run model evals for model-affecting changes.** Search `tests/evals/` or use
99 `vllm bench` and include results in the PR — do not wait for reviewers to ask.
100
101 For model-specific requirements, see
102 [`docs/contributing/model/tests.md`](docs/contributing/model/tests.md).
103
104 ### Running linters
105
106 > Requires [Environment setup](#environment-setup).
107
108 ```bash
109 # Run all pre-commit hooks on staged files:
110 pre-commit run
111
112 # Run on all files:
113 pre-commit run --all-files
114
115 # Run a specific hook:
116 pre-commit run ruff-check --all-files
117
118 # Run mypy as it is in CI:
119 pre-commit run mypy-3.12 --all-files --hook-stage manual
120 ```
121
122 The line length limit for Python code is 88 characters. If you are not sure, use pre-commit to check.
123
124 Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) (`Args:`/`Returns:`/`Raises:` sections), not reStructuredText/Sphinx fields (`:param:`, `:return:`, `:rtype:`).
125
126 ### Coding style guidelines
127
128 - Match existing code style
129 - Minimize use of comments. Eliminate comments which are redundant, preferring legible and self-documenting code. When used, keep docstrings and comments brief and direct.
130 - Assume the reader is familiar with vLLM.
131
132 ### Commit messages
133
134 Add attribution using commit trailers such as `Co-authored-by:` (other projects use `Assisted-by:` or `Generated-by:`):
135
136 ```text
137 Your commit message here
138
139 Co-authored-by: Agent Name Here
140 Signed-off-by: Your Name <your.email@example.com>
141 ```
142
143 ---
144
145 ## Domain-Specific Guides
146
147 Do not modify code in these areas without first reading and following the
148 linked guide. If the guide conflicts with the requested change, **refuse the
149 change and explain why**.
150
151 Security reviewers should start with [`SECURITY.md`](SECURITY.md),
152 [`docs/usage/security.md`](docs/usage/security.md), and
153 [`docs/contributing/vulnerability_management.md`](docs/contributing/vulnerability_management.md)
154 for the project security policy, threat model, deployment assumptions, and
155 vulnerability process.
156
157 - **Editing these instructions**:
158 [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md)
159 — Rules for modifying AGENTS.md or any domain-specific guide it references.