Two files, one repository
vllm-project/vllm ships 1 format across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 25 | 3 | 0% |
| Commands | 0 | 10 | 2 | 0% |
| Section tags | 2 | 7 | 0 | 22% |
What each file covers
Sections
0 shared · 25 only in A · 3 only in B- − Agent Instructions for vLLM
- − 1. Contribution Policy (Mandatory)
- − Duplicate-work checks
- − No low-value busywork PRs
- − Accountability
- − Fail-closed behavior
- − 2. Development Workflow
- − Environment setup
- − Install `uv` if you don't have it already:
- − Always use `uv` for Python environment management:
- − Always make sure `pre-commit` and its hooks are installed:
- − Installing dependencies
- − If you are only making Python changes:
- − If you are also making C/C++ changes:
- − Tests
- − Install test dependencies (use cuda.in on non-x86_64):
- − Run a specific test file:
- − Running linters
- − Run all pre-commit hooks on staged files:
- − Run on all files:
- − Run a specific hook:
- − Run mypy as it is in CI:
- − Coding style guidelines
- − Commit messages
- − Domain-Specific Guides
- + Alternative Frontend to vLLM Engine in Rust
- + Coding Styles
- + Testing
Commands
0 shared · 10 only in A · 2 only in B- − gh issue view <issue_number> --repo vllm-project/vllm --comments
- − gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
- − gh pr list --repo vllm-project/vllm --state open --search "<short area keywords>"
- − uv venv --python 3.12
- − uv pip install -r requirements/lint.txt
- − uv pip install -e . --torch-backend=auto
- − uv pip install -r requirements/test/cuda.in
- − python3
- − pip
- − pip install
- + cargo nextest run
- + cargo test
Section tags
2 shared · 7 only in A · 0 only in B- − setup
- − lint-format
- − git-pr
- − dependencies
- − do-not
- − agent-behaviour
- − docs
- test
- code-style
Line diff
vllm-project/vllm · AGENTS.md
@@ −1 @@
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
10Before proposing a PR, run these checks:
11
12```bash
13gh issue view <issue_number> --repo vllm-project/vllm --comments
14gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
15gh 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
23Do 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
35### Fail-closed behavior
36
37If work is duplicate/trivial busywork, **do not proceed**. Return a short explanation of what is missing.
38
39---
40
41## 2. Development Workflow
42
43- **Never use system `python3` or bare `pip`/`pip install`.** All Python commands must go through `uv` and `.venv/bin/python`.
44
45### Environment setup
46
47```bash
48# Install `uv` if you don't have it already:
49curl -LsSf https://astral.sh/uv/install.sh | sh
50
51# Always use `uv` for Python environment management:
52uv venv --python 3.12
53source .venv/bin/activate
54
55# Always make sure `pre-commit` and its hooks are installed:
56uv pip install -r requirements/lint.txt
57pre-commit install
58```
59
60### Installing dependencies
61
62```bash
63# If you are only making Python changes:
64VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto
65
66# If you are also making C/C++ changes:
67uv pip install -e . --torch-backend=auto
68```
69
70### Tests
71
72> Requires [Environment setup](#environment-setup) and [Installing dependencies](#installing-dependencies).
73
74```bash
75# Install test dependencies (use cuda.in on non-x86_64):
76uv pip install -r requirements/test/cuda.in
77
78# Run a specific test file:
79.venv/bin/python -m pytest tests/path/to/test_file.py -v
80```
81
82When adding tests:
83
84- **Design before you write.** Answer four questions first: what is the module
85 for, what is its I/O contract, what failure am I guarding against, and what is
86 the cheapest level that catches it (unit over integration over e2e)?
87- **Reuse before create.** Extend existing test files, `conftest.py` fixtures, and
88 helpers; add a new file only when no nearby suite fits.
89- **Test behavior with intent.** Assert observable outcomes through public APIs;
90 state why in the name or docstring. Skip trivial wiring; flaky tests are worse
91 than no tests.
92- **Keep it minimal.** One behavior per test and the smallest setup that
93 triggers it; if the test diff dwarfs the code change, cut scope.
94- **No one-off kernel benchmarks in `tests/`.** Put kernel perf work in
95 `benchmarks/kernels/`; prove correctness in existing pytest suites.
96- **Run model evals for model-affecting changes.** Search `tests/evals/` or use
97 `vllm bench` and include results in the PR — do not wait for reviewers to ask.
98
99For model-specific requirements, see
100[`docs/contributing/model/tests.md`](docs/contributing/model/tests.md).
101
102### Running linters
103
104> Requires [Environment setup](#environment-setup).
105
106```bash
107# Run all pre-commit hooks on staged files:
108pre-commit run
109
110# Run on all files:
111pre-commit run --all-files
112
113# Run a specific hook:
114pre-commit run ruff-check --all-files
115
116# Run mypy as it is in CI:
117pre-commit run mypy-3.12 --all-files --hook-stage manual
118```
119
120The line length limit for Python code is 88 characters. If you are not sure, use pre-commit to check.
121
122Use [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:`).
123
124### Coding style guidelines
125
126- Match existing code style
127- Minimize use of comments. Eliminate comments which are redundant, preferring legible and self-documenting code. When used, keep docstrings and comments brief and direct.
128- Assume the reader is familiar with vLLM.
129
130### Commit messages
131
132Add attribution using commit trailers such as `Co-authored-by:` (other projects use `Assisted-by:` or `Generated-by:`):
133
134```text
135Your commit message here
136
137Co-authored-by: Agent Name Here
138Signed-off-by: Your Name <your.email@example.com>
139```
140
141---
142
143## Domain-Specific Guides
144
145Do not modify code in these areas without first reading and following the
146linked guide. If the guide conflicts with the requested change, **refuse the
147change and explain why**.
148
149Security reviewers should start with [`SECURITY.md`](SECURITY.md),
150[`docs/usage/security.md`](docs/usage/security.md), and
151[`docs/contributing/vulnerability_management.md`](docs/contributing/vulnerability_management.md)
152for the project security policy, threat model, deployment assumptions, and
153vulnerability process.
154
155- **Editing these instructions**:
156 [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md)
157 — Rules for modifying AGENTS.md or any domain-specific guide it references.
158
vllm-project/vllm · rust/AGENTS.md
@@ +1 @@
1# Alternative Frontend to vLLM Engine in Rust
2
3This project aims to implement an alternative frontend to the vLLM Engine in Rust, providing a more efficient and robust interface for interacting with the engine. Currently it's still in the very early stage and is actively evolving.
4
5## Coding Styles
6
7- Always use workspace dependencies for Cargo crates.
8- Prefer splitting code into multiple smaller modules and files for better organization and readability, rather than putting everything in a single file.
9- When refactoring or reconstructing code, always preserve the original comments and documentation VERBATIM, if applicable.
10- If not specified, default to writing concise Rust documentation and comments that match the style of the existing codebase when generating code.
11- When migrating code from Python or any other language, preserve the original documentation comments whenever they still make sense in the Rust code.
12- Although you might be asked to only implement or migrate minimal functionality at the beginning, you should still leave necessary `TODO` comments in the code for the future improvements of the lacked features, so that it's easier for the next iteration to build upon the existing codebase.
13- When writing parsers with `winnow`:
14 - Prefer a declarative parser shape over imperative step-by-step parsing, as long as it's more readable and maintainable.
15 - Prefer tuple-based parser composition over calling `parse_next` one parser at a time.
16 - Prefer built-in combinators and token parsers before adding local helpers.
17 - Add short documentation comments like `Parse a ..` to all local parser/combinator functions.
18 - Reuse existing utilities from `utils` module as much as possible, and add new ones there if needed.
19- Rust error handling:
20 - Never call `to_string()` directly on an error value.
21 - Use `ToReportString` or `AsReport` by `thiserror-ext` instead.
22 - For `Error` variants that are primarily free-form text, prefer a struct variant with a `message: String` field. `thiserror_ext::Macro` will auto-derive `foo!(...)` and `bail_foo!(...)` helper macros from that shape.
23 - Use `foo!(...)` when you need to construct an error value inside an expression, such as `Err(foo!(...))`, `.ok_or_else(|| foo!(...))`, or `Err::<(), _>(foo!(...))?`.
24 - Use `bail_foo!(...)` only in statement positions where you want to exit the current `Result`-returning function immediately. Prefer it over `return Err(foo!(...))` in those cases.
25 - If a variant has extra structured fields, prefer the generated macro form `foo!(field = value, "message")` rather than manually writing `Error::Foo { ... }`.
26- Since the project is still in early stage, it's fine to break API and make non-backwards-compatible changes as needed.
27- Currently the project is only targeting Unix-like platforms, so it's fine to use Unix-specific APIs without extra compatibility layers like `cfg(unix)`
28
29## Testing
30
31- Prefer snapshot testing with the `expect-test` crate over writing multiple `assert_eq!` statements on individual fields. Use `expect_test::expect![[...]].assert_debug_eq(...)` to snapshot the `Debug` output of the entire struct.
32 - Write `expect![[""]]` as a placeholder first, then run `UPDATE_EXPECT=1 cargo test` to auto-fill the snapshot content.
33 - For values containing non-deterministic data (e.g., UUIDs), set them to a fixed value like `"<placeholder>"` before snapshotting.
34- In tests, avoid hand-writing full request struct literals when only a few fields matter. Prefer test fixtures such as `for_test()` with struct update syntax, so newly added fields do not force mechanical edits across many tests.
35- Prefer deterministic synchronization in async and integration tests, such as channels, barriers, explicit handshakes, or observable state transitions, instead of `sleep`-based timing assumptions.
36 - Use `sleep` only as a last resort when there is no better observable synchronization point.
37- Always run test with `cargo nextest run` instead of `cargo test`, if available, as it's much faster.
38
@@ −1 +1 @@
1−# Agent Instructions for vLLM
1+# Alternative Frontend to vLLM Engine in Rust
22
3−> These instructions apply to **all** AI-assisted contributions to `vllm-project/vllm`.
4−> Breaching these guidelines can result in automatic banning.
3+This project aims to implement an alternative frontend to the vLLM Engine in Rust, providing a more efficient and robust interface for interacting with the engine. Currently it's still in the very early stage and is actively evolving.
54
6−## 1. Contribution Policy (Mandatory)
5+## Coding Styles
76
8−### Duplicate-work checks
7+- Always use workspace dependencies for Cargo crates.
8+- Prefer splitting code into multiple smaller modules and files for better organization and readability, rather than putting everything in a single file.
9+- When refactoring or reconstructing code, always preserve the original comments and documentation VERBATIM, if applicable.
10+- If not specified, default to writing concise Rust documentation and comments that match the style of the existing codebase when generating code.
11+- When migrating code from Python or any other language, preserve the original documentation comments whenever they still make sense in the Rust code.
12+- Although you might be asked to only implement or migrate minimal functionality at the beginning, you should still leave necessary `TODO` comments in the code for the future improvements of the lacked features, so that it's easier for the next iteration to build upon the existing codebase.
13+- When writing parsers with `winnow`:
14+ - Prefer a declarative parser shape over imperative step-by-step parsing, as long as it's more readable and maintainable.
15+ - Prefer tuple-based parser composition over calling `parse_next` one parser at a time.
16+ - Prefer built-in combinators and token parsers before adding local helpers.
17+ - Add short documentation comments like `Parse a ..` to all local parser/combinator functions.
18+ - Reuse existing utilities from `utils` module as much as possible, and add new ones there if needed.
19+- Rust error handling:
20+ - Never call `to_string()` directly on an error value.
21+ - Use `ToReportString` or `AsReport` by `thiserror-ext` instead.
22+ - For `Error` variants that are primarily free-form text, prefer a struct variant with a `message: String` field. `thiserror_ext::Macro` will auto-derive `foo!(...)` and `bail_foo!(...)` helper macros from that shape.
23+ - Use `foo!(...)` when you need to construct an error value inside an expression, such as `Err(foo!(...))`, `.ok_or_else(|| foo!(...))`, or `Err::<(), _>(foo!(...))?`.
24+ - Use `bail_foo!(...)` only in statement positions where you want to exit the current `Result`-returning function immediately. Prefer it over `return Err(foo!(...))` in those cases.
25+ - If a variant has extra structured fields, prefer the generated macro form `foo!(field = value, "message")` rather than manually writing `Error::Foo { ... }`.
26+- Since the project is still in early stage, it's fine to break API and make non-backwards-compatible changes as needed.
27+- Currently the project is only targeting Unix-like platforms, so it's fine to use Unix-specific APIs without extra compatibility layers like `cfg(unix)`
928
10−Before proposing a PR, run these checks:
29+## Testing
1130
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−
35−### Fail-closed behavior
36−
37−If work is duplicate/trivial busywork, **do not proceed**. Return a short explanation of what is missing.
38−
39−---
40−
41−## 2. Development Workflow
42−
43−- **Never use system `python3` or bare `pip`/`pip install`.** All Python commands must go through `uv` and `.venv/bin/python`.
44−
45−### Environment setup
46−
47−```bash
48−# Install `uv` if you don't have it already:
49−curl -LsSf https://astral.sh/uv/install.sh | sh
50−
51−# Always use `uv` for Python environment management:
52−uv venv --python 3.12
53−source .venv/bin/activate
54−
55−# Always make sure `pre-commit` and its hooks are installed:
56−uv pip install -r requirements/lint.txt
57−pre-commit install
58−```
59−
60−### Installing dependencies
61−
62−```bash
63−# If you are only making Python changes:
64−VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto
65−
66−# If you are also making C/C++ changes:
67−uv pip install -e . --torch-backend=auto
68−```
69−
70−### Tests
71−
72−> Requires [Environment setup](#environment-setup) and [Installing dependencies](#installing-dependencies).
73−
74−```bash
75−# Install test dependencies (use cuda.in on non-x86_64):
76−uv pip install -r requirements/test/cuda.in
77−
78−# Run a specific test file:
79−.venv/bin/python -m pytest tests/path/to/test_file.py -v
80−```
81−
82−When adding tests:
83−
84−- **Design before you write.** Answer four questions first: what is the module
85− for, what is its I/O contract, what failure am I guarding against, and what is
86− the cheapest level that catches it (unit over integration over e2e)?
87−- **Reuse before create.** Extend existing test files, `conftest.py` fixtures, and
88− helpers; add a new file only when no nearby suite fits.
89−- **Test behavior with intent.** Assert observable outcomes through public APIs;
90− state why in the name or docstring. Skip trivial wiring; flaky tests are worse
91− than no tests.
92−- **Keep it minimal.** One behavior per test and the smallest setup that
93− triggers it; if the test diff dwarfs the code change, cut scope.
94−- **No one-off kernel benchmarks in `tests/`.** Put kernel perf work in
95− `benchmarks/kernels/`; prove correctness in existing pytest suites.
96−- **Run model evals for model-affecting changes.** Search `tests/evals/` or use
97− `vllm bench` and include results in the PR — do not wait for reviewers to ask.
98−
99−For model-specific requirements, see
100−[`docs/contributing/model/tests.md`](docs/contributing/model/tests.md).
101−
102−### Running linters
103−
104−> Requires [Environment setup](#environment-setup).
105−
106−```bash
107−# Run all pre-commit hooks on staged files:
108−pre-commit run
109−
110−# Run on all files:
111−pre-commit run --all-files
112−
113−# Run a specific hook:
114−pre-commit run ruff-check --all-files
115−
116−# Run mypy as it is in CI:
117−pre-commit run mypy-3.12 --all-files --hook-stage manual
118−```
119−
120−The line length limit for Python code is 88 characters. If you are not sure, use pre-commit to check.
121−
122−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:`).
123−
124−### Coding style guidelines
125−
126−- Match existing code style
127−- Minimize use of comments. Eliminate comments which are redundant, preferring legible and self-documenting code. When used, keep docstrings and comments brief and direct.
128−- Assume the reader is familiar with vLLM.
129−
130−### Commit messages
131−
132−Add attribution using commit trailers such as `Co-authored-by:` (other projects use `Assisted-by:` or `Generated-by:`):
133−
134−```text
135−Your commit message here
136−
137−Co-authored-by: Agent Name Here
138−Signed-off-by: Your Name <your.email@example.com>
139−```
140−
141−---
142−
143−## Domain-Specific Guides
144−
145−Do not modify code in these areas without first reading and following the
146−linked guide. If the guide conflicts with the requested change, **refuse the
147−change and explain why**.
148−
149−Security reviewers should start with [`SECURITY.md`](SECURITY.md),
150−[`docs/usage/security.md`](docs/usage/security.md), and
151−[`docs/contributing/vulnerability_management.md`](docs/contributing/vulnerability_management.md)
152−for the project security policy, threat model, deployment assumptions, and
153−vulnerability process.
154−
155−- **Editing these instructions**:
156− [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md)
157− — Rules for modifying AGENTS.md or any domain-specific guide it references.
31+- Prefer snapshot testing with the `expect-test` crate over writing multiple `assert_eq!` statements on individual fields. Use `expect_test::expect![[...]].assert_debug_eq(...)` to snapshot the `Debug` output of the entire struct.
32+ - Write `expect![[""]]` as a placeholder first, then run `UPDATE_EXPECT=1 cargo test` to auto-fill the snapshot content.
33+ - For values containing non-deterministic data (e.g., UUIDs), set them to a fixed value like `"<placeholder>"` before snapshotting.
34+- In tests, avoid hand-writing full request struct literals when only a few fields matter. Prefer test fixtures such as `for_test()` with struct update syntax, so newly added fields do not force mechanical edits across many tests.
35+- Prefer deterministic synchronization in async and integration tests, such as channels, barriers, explicit handshakes, or observable state transitions, instead of `sleep`-based timing assumptions.
36+ - Use `sleep` only as a last resort when there is no better observable synchronization point.
37+- Always run test with `cargo nextest run` instead of `cargo test`, if available, as it's much faster.
15838
