How to Set Up a Development Environment for Switchyard

To set up a development environment for Switchyard, install Python 3.10+, Rust 1.96.1+, and the uv package manager, then run uv sync in the cloned repository to create a virtual environment with all Python and Rust dependencies.

Switchyard is a multi-language project that combines Rust libraries, a native server, and Python bindings. Setting up a development environment for Switchyard requires coordinating both the Rust toolchain and Python packaging tools, which is streamlined through the uv dependency manager. This guide walks through the complete setup process using the exact specifications found in the [INSTALLATION.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/INSTALLATION.md) and [DEVELOPMENT.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/DEVELOPMENT.md) files from the NVIDIA-NeMo/Switchyard repository.

Prerequisites

Before cloning the repository, ensure your system meets the following requirements documented in the source code.

Python 3.10 or Higher

The nemo-switchyard package requires Python 3.10+ to support the modern type hints and async features used in the codebase. Verify your version with python --version before proceeding.

Rust 1.96.1 or Higher

The native server and Rust crates in crates/libsy/ and crates/switchyard-py/ require Rust 1.96.1+. Install via rustup if you do not have a compatible toolchain.

uv Package Manager

uv is the preferred Python dependency manager for this project. It creates the .venv used for development and handles the build backend (maturin) that compiles Rust extensions. Install uv using the official installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Git

Required to clone the repository and install pre-commit hooks.

Clone the Repository

Fetch the source code from GitHub and navigate into the project directory:

git clone https://github.com/NVIDIA-NeMo/Switchyard.git
cd Switchyard

The repository contains the Rust workspace in crates/, Python bindings in crates/switchyard-py/, and the pyproject.toml file that defines the Python package metadata and dependency groups.

Create the Development Virtual Environment

Run uv sync to create the development virtual environment. This command reads the pyproject.toml file, resolves dependencies, creates a .venv directory, and installs the core package along with development tools.

uv sync

By default, uv sync installs the "dev" dependency group, which includes pytest, ruff, mypy, and pre-commit. Alternatively, specify the group explicitly:

uv sync --group dev

The sync process also triggers maturin to build the Rust extensions (powered by PyO3), compiling the switchyard-py crate into a native Python module available as switchyard.libsy.

Install Git Hooks (Optional but Recommended)

Maintain code quality by installing pre-commit hooks that run ruff linting and commitlint on every commit. Use uvx to execute the pre-commit tool without installing it globally:

uvx pre-commit install --install-hooks \
    --hook-type pre-commit --hook-type commit-msg

These hooks ensure the codebase stays clean and commit messages follow the project's conventional commit format before they reach the repository.

Activate the Environment and Verify the Build

Activate the virtual environment to access the compiled extensions and development tools:

source .venv/bin/activate

After activation, verify the installation by running the test suites and static analysis tools.

Run the Rust Test Suite

Execute the workspace tests to verify the core Rust libraries:

cargo test --workspace

This validates the routing algorithms and server logic defined in crates/libsy/ and related crates.

Run the Python Test Suite

Use uv run to execute pytest within the managed environment:

uv run pytest tests/ -v

Run Static Analysis

Check Python code quality with the configured linters:

uv run ruff check .
uv run mypy switchyard

Successful execution of these commands confirms that your development environment correctly builds both the Rust extensions and Python package.

Additional Development Workflows

Once the basic environment is functional, you can perform advanced development tasks.

Embed the Library in Python

To rebuild the Python bindings from source after modifying Rust code:

uv run maturin develop

You can then import and use the routing library:

from switchyard.libsy import LlmResponse, Step
from switchyard.libsy.algorithms import stage_router

algorithm = stage_router(
    "capable", "efficient",
    picker="efficient_first",
    confidence_threshold=0.5,
)

Run the Standalone Server

Install and run the native Rust server using Cargo:

cargo install --locked switchyard-server
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

Refer to the "Path 3" section of the README and docs/routing_algorithms/overview.md for TOML configuration examples and routing algorithm documentation.

Summary

• Install prerequisites: Python 3.10+, Rust 1.96.1+, uv, and Git.
• Clone the NVIDIA-NeMo/Switchyard repository and run uv sync to create the development virtual environment.
• Activate the environment with source .venv/bin/activate to access the switchyard Python package and compiled Rust extensions.
• Verify the setup by running cargo test --workspace, uv run pytest tests/, and the ruff/mypy linters.
• Optional: Install pre-commit hooks with uvx pre-commit install to enforce code quality on every commit.
• Develop: Use uv run maturin develop to rebuild Python bindings and cargo install --locked switchyard-server to test the standalone proxy.

Frequently Asked Questions

What is the minimum Rust version required for Switchyard development?

Switchyard requires Rust 1.96.1 or higher to compile the server and core libraries located in crates/libsy/ and crates/switchyard-py/. This version ensures compatibility with the async runtime and dependency crates used in the routing algorithms.

Why does Switchyard use uv instead of pip or conda?

The project uses uv because it is a fast Python dependency manager that also handles the creation of the .venv and coordinates with maturin to build Rust extensions. According to the pyproject.toml configuration, uv sync installs both Python dependencies (pytest, ruff, mypy) and triggers the compilation of the PyO3 bindings in a single command.

How do I run tests for both Python and Rust components?

Run cargo test --workspace from the repository root to test the Rust crates. For Python, execute uv run pytest tests/ -v or activate the virtual environment and run pytest directly. Both test suites should pass before submitting contributions to the codebase.

Can I develop Switchyard without installing the pre-commit hooks?

Yes, the pre-commit hooks are optional but strongly recommended. They automate ruff linting and commitlint checks to ensure code quality. If you skip them, you must manually run uv run ruff check . and ensure your commit messages follow the conventional format before opening a pull request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}