Skip to content

INSTALLATION.md

Latest commit

 

History

History
187 lines (130 loc) · 4.25 KB

INSTALLATION.md

File metadata and controls

187 lines (130 loc) · 4.25 KB
Raw

Installation Guide

Switchyard supports modular installation based on your use case. Install only the dependencies you need.

System Requirements

  • Linux x86_64 wheels require an x86-64-v3 / AVX2-class CPU (post 2013).
  • Linux aarch64 wheels require a Neoverse N1-class CPU (post 2020).

Core Installation (Library Only)

For applications that use Switchyard as a Python library for routing and recipe composition:

pip install nemo-switchyard

Includes:

  • Core routing logic
  • All recipe factories (Passthrough, RandomRouting, etc.)
  • Format translation engine (Anthropic ↔ OpenAI)
  • Request/response processors

Does NOT include:

  • FastAPI / Uvicorn (server)
  • prompt-toolkit (CLI launcher)

Use case: Library users, middleware plugins, embedded integrations.

Optional Extras

[server] — Run as a Proxy Server

Add FastAPI and Uvicorn to run Switchyard as a standalone HTTP proxy:

pip install nemo-switchyard[server]

Adds:

  • FastAPI
  • Uvicorn with standard extras
  • sse-starlette (for SSE streaming)

Use case: Deploying Switchyard as a service, e2e proxy operations.

[cli] — Claude Code Launcher

Add terminal UI support for the switchyard launch claude command:

pip install nemo-switchyard[cli]

Adds:

  • prompt-toolkit (terminal UI framework for the interactive launch TUI)

Use case: Running Claude Code with Switchyard routing.

Combined Extras

Full Installation

All optional dependencies for complete feature set:

pip install nemo-switchyard[all]

Equivalent to: nemo-switchyard[server,cli,tracing,intake,affinity-redis]

Common Combinations

Middleware plugin (no server/CLI):

pip install nemo-switchyard                  # Core only

Proxy server without launcher:

pip install nemo-switchyard[server]

Full Claude Code integration:

pip install nemo-switchyard[cli]             # Includes core

Production deployment with all features:

pip install nemo-switchyard[all]

Dependency Structure

Core (Always Installed)

- openai>=2.34.0,<3.0
- anthropic>=0.99.0,<1.0
- httpx>=0.28.1,<1.0
- pydantic>=2.13.3,<3.0

Optional Dependencies

Extra Size Purpose
[server] ~50 MB HTTP proxy (FastAPI + Uvicorn)
[cli] ~5 MB Terminal UI (prompt-toolkit)

Embedding in Your Own Application

For Custom Applications

Embed Switchyard with minimal overhead:

from switchyard import PassthroughProfileConfig, ProfileSwitchyard

# Core library only — no server/CLI dependencies
switchyard = ProfileSwitchyard(PassthroughProfileConfig(
    api_key="sk-...",
    base_url="https://api.openai.com/v1",
).build())

Troubleshooting

Import Error: "No module named 'fastapi'"

You're trying to run the HTTP server without the [server] extra:

# Install with server support
pip install nemo-switchyard[server]
from switchyard import Switchyard                                       # OK (core)
from switchyard.server.switchyard_app import build_switchyard_app   # needs [server]

Import Error: "No module named 'prompt_toolkit'"

You're trying to run the CLI launcher without the [cli] extra:

# Install CLI support
pip install nemo-switchyard[cli]
from switchyard import Switchyard                                  # OK (core)
from switchyard.cli.launchers.claude_code_launcher import launch_claude  # needs [cli]

Development

For development with all testing tools, use uv (recommended):

uv sync                  # core + dev tooling (dev is uv's default group)
uv sync --all-extras     # add every user-facing extra as well

Or with pip ≥ 25.1 from a checkout:

pip install -e ".[all]"
pip install --group dev .

This includes:

  • Core + all optional extras
  • pytest, ruff, mypy, respx for testing

Note: dev tooling lives in a PEP 735 dependency group, not an extra, so pip install nemo-switchyard[dev] is not supported and dev tooling never appears in the published wheel's METADATA (it's invisible to downstream vulnerability scans).

Version Compatibility

Switchyard requires Python 3.12 or later.

Supported versions:

  • Python 3.12
  • Python 3.13