Contributing to Spyre Inference¶
Thank you for your interest in contributing to the Spyre plugin for vLLM! There are several ways you can contribute:
- Identify and report any issues or bugs.
- Suggest or implement new features.
- Improve documentation or contribute a how-to guide.
Developing¶
Follow the Installation Guide to get the base package installed, then install the dev dependency group:
This includes pytest, pyyaml, and the spyre-testing-plugin for running the test suite.
If you already have a local torch-spyre checkout installed (e.g. editable, for torch-spyre development), a plain uv sync will rebuild and reinstall the pinned git rev from pyproject.toml, discarding it. To keep your local install instead:
--no-install-package torch-spyre skips resolving and rebuilding the pinned rev; --inexact stops uv from uninstalling the now-unreferenced local package. Note this only affects uv sync itself — any subsequent plain uv run will still re-sync and revert it, so use uv run --no-sync … for those (see CLAUDE.md's "Iterating on a Local torch-spyre Checkout" section).
One venv for both repos¶
To work on a torch-spyre bug and validate against both test suites, build on this repo's venv — it already carries the pinned torch and vllm — then add your torch-spyre checkout and its dev dependencies:
cd spyre-inference
uv sync --group dev --no-install-package torch-spyre --inexact
uv pip install -e ~/torch-spyre
uv pip install --group ~/torch-spyre/pyproject.toml:dev
spyre-testing-plugin is scoped to this repo — it is activated by an addopts entry in our pyproject.toml rather than a global pytest11 entry point — so pytest inside torch-spyre behaves exactly as it does without spyre-inference installed. Run each suite from its own checkout.
Linting¶
When submitting a PR, please make sure your code passes all linting checks. We use prek with a .pre-commit-config.yaml file to run checks on every commit.
The format.sh script will run prek from an isolated virtual environment using uvx. The only requirement is that you have uv installed.
Alternatively, you can install prek and set up a git hook to run it on every commit with:
Testing¶
The project includes both local tests (located in tests/) for spyre-inference specific functionality, and upstream vLLM tests automatically cloned from the vLLM repository at the commit specified in pyproject.toml, for compatibility verification.
Test Markers¶
The test suite uses pytest markers to categorize tests:
markers = [
"distributed: Tests requiring multiple spyre cards",
"upstream: Tests coming from upstream vLLM",
"attention: SpyreAttentionImpl tests (tests/attention/test_spyre_attn.py, tests/attention/test_spyre_encoder_attn.py); slow, runs in its own CI job",
"encoder_attention: encoder-attention subset (tests/attention/test_spyre_encoder_attn.py); also marked attention, split into its own CI job",
"compile: torch.compile end-to-end tests (tests/e2e/test_compile.py); slow, runs in its own CI job",
"rotary: Spyre RoPE custom-op tests (tests/custom_ops/test_rotary_embedding.py)",
"fp8: FP8 quantization tests (tests/custom_ops/test_fp8.py)",
]
Upstream vLLM tests are opt-in: they are cloned and collected only when the -m expression names the upstream marker, or --upstream is passed. A negative mention doesn't count, so -m "not upstream" and -m "attention and not upstream" skip the clone entirely.
# Run only local tests (no vLLM clone)
pytest
# Run all upstream tests
pytest -m upstream
# Run upstream attention tests only (see tests/plugin/spyre_testing_plugin/upstream_tests.yaml for markers on upstream tests)
pytest -m "attention and upstream"
# Run local AND upstream attention tests: --upstream adds them to a marker
# expression that doesn't name `upstream` itself
pytest --upstream -m "attention"
Upstream Test Integration¶
Upstream tests are cloned from the vLLM repository at the commit pinned in pyproject.toml, fetching only the tests/ directory. The clone happens on demand, the first time a run asks for upstream tests (see the marker gate above). Cloned tests are cached in ~/.cache/vllm-upstream-tests (or $XDG_CACHE_HOME/vllm-upstream-tests) with separate worktrees per commit, allowing multiple vLLM versions to be tested simultaneously. All upstream tests run with VLLM_PLUGINS=spyre_inference,spyre_inference_ops set automatically. Pointing the plugin at a vLLM checkout instead of the cache is the one case that still needs the flag by hand: pytest -p spyre_testing_plugin.pytest_plugin -m upstream from the checkout root. See tests/plugin/spyre_testing_plugin/pytest_plugin.py for implementation details.
Configuration¶
--upstream: Collect upstream tests even when the -m expression doesn't name the upstream marker.
SKIP_UPSTREAM_TESTS: Skip upstream tests entirely, overriding both the -m expression and --upstream. Accepts 1, true, or yes.
VLLM_COMMIT: Override the vLLM commit SHA from pyproject.toml.
VLLM_REPO_URL: Override the vLLM repository URL. Defaults to https://github.com/vllm-project/vllm.
UPSTREAM_TESTS_PATHS: Not currently consumed by the plugin — the set of upstream test paths is auto-derived from the rel_path entries in tests/plugin/spyre_testing_plugin/upstream_tests.yaml.
Tip
Environment variables can be passed directly to the pytest command, e.g. VLLM_COMMIT=abc123def456 pytest -m upstream.
Docs¶
Install MkDocs along with the plugins used in the Spyre Inference documentation.
Note
Ensure that your Python version is compatible with the plugins (e.g., mkdocs-awesome-nav requires Python 3.10+)
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yaml configuration file and run:
Open up http://127.0.0.1:8000/ in your browser to see a live preview. For additional features and advanced configurations, refer to the official MkDocs Documentation.
Issues¶
If you encounter a bug or have a feature request, please search existing issues first to see if it has already been reported. If not, please create a new issue, by using our issue templates:
- 🐛 Bug Report: For reporting bugs and unexpected behavior
- 🚀 Feature Request: For suggesting new features or improvements
You can also reach out for support in the #sig-spyre channel in the vLLM Slack workspace.
Pull Requests¶
DCO and Signed-off-by¶
When contributing, you must agree to the DCO. Commits must include a Signed-off-by: header which certifies agreement with the terms of the DCO.
Using -s with git commit will automatically add this header.
Additional Resources¶
License¶
See LICENSE.