Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
docs: refresh contributor architecture guidance (#396)
Elias Shieh5fd83498a2d7
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.mdindex 81d5e1a4e..157c666e3 100644--- a/.github/ISSUE_TEMPLATE/feature_request.md+++ b/.github/ISSUE_TEMPLATE/feature_request.md@@ -20,8 +20,10 @@ What else did you try or consider? Why is the proposal preferable?## Scope notes-- Is this a new role/component in the chain (RequestProcessor / LLMBackend / ResponseProcessor / ResponseTranslator), or an extension of an existing one?-- Does it touch a public API listed in `switchyard/__init__.py.__all__`?+- Which surface owns the change: server API or configuration, routing algorithm,+ protocol type, translation codec, upstream client, skill-distillation contract,+ Python binding, or launcher?+- Does it change a public Rust, PyO3, Python, CLI, or deployment-TOML interface?- Backward-compatibility concerns?## Additional contextdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2e199e652..b4fd8983b 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -73,6 +73,11 @@ uv run mypy switchyard# Tests — no failuresuv run pytest tests/ -v++# Rust formatting, linting, and tests+cargo fmt --all --check+cargo clippy --workspace --all-targets -- -D warnings+cargo test --workspace```These commands run in CI on every push. **Fix linting errors locally before pushing:**@@ -130,6 +135,9 @@ feat(api)!: remove legacy route optionuv run ruff check .uv run mypy switchyarduv run pytest tests/ -v+ cargo fmt --all --check+ cargo clippy --workspace --all-targets -- -D warnings+ cargo test --workspace```4. **Push and open a PR** on GitHub. Include:@@ -152,6 +160,7 @@ workflows (commitlint, PR title) run on every PR but are advisory.```bashuv run pytest tests/ -v+cargo test --workspace```### Integration tests (requires API keys)@@ -167,19 +176,38 @@ The default unit test suite runs with no network access and no API keys. Live, e## Architecture-See [Agents](AGENTS.md) for the full architecture guide. Key points:--- **Typed requests/responses** — use `ChatRequest` and `ChatResponse` subtypes-- **Composable chain** — `RequestProcessor` → `LLMBackend` → `ResponseProcessor` → `TranslationEngine`-- **Profiles** — pre-built chains in `switchyard/lib/profiles/`+See [Architecture](docs/architecture.md) for the request lifecycle and+[Agents](AGENTS.md) for crate boundaries and repository conventions. The+supported serving path is native Rust:-When adding a new component:+```text+HTTP request+ → switchyard-server+ → switchyard-translation (decode)+ → libsy+ → libsy-llm-client+ → switchyard-translation (encode)+ → upstream model+```-1. Decide the role: `RequestProcessor`, `LLMBackend`, `ResponseProcessor`, or translation engine work.-2. Subclass the ABC from `switchyard/lib/roles.py`.-3. Put Python middleware in the matching subpackage (`switchyard/lib/processors/`, `switchyard/lib/backends/`) and provider translation logic in `crates/switchyard-translation`.-4. Add tests in `tests/`.-5. Export from the relevant `__init__.py` and from `switchyard/__init__.py`'s `__all__`.+Before making a change, identify the surface that owns it:++- Put routing algorithms and driver behavior in `crates/libsy`.+- Put provider-neutral request and response types in `crates/protocol`.+- Put translated HTTP calls in `crates/libsy-llm-client`.+- Put wire-format conversion in `crates/switchyard-translation`.+- Put HTTP serving and deployment configuration in `crates/switchyard-server`.+- Put source-neutral skill-distillation records and port traits in+ `crates/switchyard-skill-distillation`; that crate does not own workflow+ orchestration. Test its public contracts in+ `crates/switchyard-skill-distillation/tests/contracts.rs`.+- Put native Python bindings in `crates/switchyard-py`; keep Python wrappers in+ `switchyard/libsy` or `switchyard_rust`.+- Put launcher behavior in `switchyard/cli`.++Add Rust tests in the owning crate and Python tests in `tests/`. Export new+public symbols from the owning crate or package rather than the top-level+`switchyard` package unless that package owns the API.## Documentationdiff --git a/DEVELOPMENT.md b/DEVELOPMENT.mdindex e0826286b..e9fae8ba5 100644--- a/DEVELOPMENT.md+++ b/DEVELOPMENT.md@@ -5,7 +5,7 @@ Switchyard itself. If you only want to **use** the package, see[README](README.md).For deeper architectural docs, see [Agents](AGENTS.md) and-[Architecture](docs/ARCHITECTURE.md).+[Architecture](docs/architecture.md).## Setup@@ -40,30 +40,21 @@ uv sync --all-extras # everything (dev group is still included by default)## Project Structure```-switchyard/-├── switchyard/ # The package itself-│ ├── __init__.py # Public API exports (single source of truth)-│ ├── lib/ # Core library-│ │ ├── roles.py # RequestProcessor, LLMBackend, ResponseProcessor ABCs-│ │ ├── switchyard.py # Switchyard chain executor-│ │ ├── profiles/ # Profile configs/runtimes (passthrough, random_routing, …)-│ │ ├── proxy_context.py # ProxyContext — per-request state-│ │ ├── chat_request/ # Typed request hierarchy-│ │ ├── chat_response/ # Typed response hierarchy-│ │ ├── backends/ # LLMBackend implementations-│ │ ├── processors/ # RequestProcessor / ResponseProcessor implementations-│ │ ├── factories/ # MiddlewareFactory implementations + configs-│ │ └── endpoints/ # FastAPI endpoint wrappers (require [server])-│ ├── cli/ # CLI entry point (requires [cli])-│ └── server/ # FastAPI app factory + verify helpers (requires [server])-├── crates/-│ ├── switchyard-translation/ # Rust request/response/stream translation engine-│ └── switchyard-py/ # Thin PyO3 bindings plus Python convenience wrapper-├── tests/ # Pytest unit tests (no API keys required)-├── examples/ # Minimal usage examples-├── docs/ # Architecture, getting started, publication-├── secrets/ # Local credential template (git-ignored)-└── pyproject.toml+switchyard/ # Python package+├── cli/ # CLI and coding-agent launchers+└── libsy/ # Typed wrappers for libsy algorithms+switchyard_rust/ # Python facades over the PyO3 extension+crates/+├── libsy/ # Routing algorithms and driver+├── libsy-llm-client/ # Translated HTTP model calls+├── protocol/ # Provider-neutral protocol types+├── switchyard-py/ # PyO3 bindings for libsy and the server+├── switchyard-server/ # Native HTTP server and TOML configuration+├── switchyard-skill-distillation/ # Skill-distillation contracts+└── switchyard-translation/ # Request, response, and stream translation+tests/ # Python tests (no API keys required)+docs/ # User and architecture documentation+pyproject.toml # Python package and development tooling```## Development Workflow@@ -78,6 +69,11 @@ uv run pytest tests/ -v# Lint and type checkuv run ruff check .uv run mypy switchyard++# Rust formatting, linting, and tests+cargo fmt --all --check+cargo clippy --workspace --all-targets -- -D warnings+cargo test --workspace```> **Local Git hooks:** install both `pre-commit` and `commit-msg` hooks with