Skip to content

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(translation): publish Rust API documentation (#1072)

David Gardner34ca48efb9ab
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 3fda6c7bb..a6debccc3 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -13,6 +13,7 @@ on:
- "rust-toolchain.toml"
- "crates/libsy/**"
- "crates/protocol/**"
+ - "crates/switchyard-translation/**"
- ".github/workflows/docs.yml"
push:
branches: [main]
@@ -27,6 +28,7 @@ on:
- "rust-toolchain.toml"
- "crates/libsy/**"
- "crates/protocol/**"
+ - "crates/switchyard-translation/**"
- ".github/workflows/docs.yml"
# Cancel superseded PR runs; keep main builds so gh-pages writes don't race.
@@ -61,6 +63,7 @@ jobs:
cargo doc --locked --no-deps
--package switchyard-libsy
--package switchyard-protocol
+ --package switchyard-translation
- name: Add crate documentation to site
run: |
mkdir -p site/rust
diff --git a/crates/switchyard-translation/src/lib.rs b/crates/switchyard-translation/src/lib.rs
index 1285ffdc6..568959097 100644
--- a/crates/switchyard-translation/src/lib.rs
+++ b/crates/switchyard-translation/src/lib.rs
@@ -1,11 +1,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
-//! Pure Rust translation engine for Switchyard.
-//!
-//! The crate translates provider wire formats through a neutral Switchyard
-//! conversation IR. It intentionally has no dependency on provider SDKs, HTTP
-//! servers, Python objects, or FFI bindings.
+#![doc = include_str!("../README.md")]
pub mod codecs;
pub(crate) mod codex_custom_tools;
diff --git a/docs/core_concepts.md b/docs/core_concepts.md
index e91bcb80b..0d6997cae 100644
--- a/docs/core_concepts.md
+++ b/docs/core_concepts.md
@@ -109,4 +109,4 @@ selected target uses a different upstream protocol.
- [Architecture](architecture.md): follow a request through the server and Rust crates.
- [`switchyard-server`](../crates/switchyard-server/README.md): complete TOML schema, endpoints, and metrics.
- [`switchyard-libsy`](../crates/libsy/README.md): embed and extend routing algorithms in Rust.
-- [Rust API reference](reference/rust_api.md): generated libsy and protocol documentation.
+- [Rust API reference](reference/rust_api.md): generated libsy, protocol, and translation documentation.
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 7d5d91cff..1c47af2a1 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -390,7 +390,7 @@ For the request, response, and streaming types the steps carry, see
- [Core Concepts](core_concepts.md): LLM clients, targets, and routes
- [`switchyard-server`](../crates/switchyard-server/README.md): server configuration,
routing algorithms, TLS, and metrics
-- [Rust API reference](reference/rust_api.md): generated libsy and protocol
+- [Rust API reference](reference/rust_api.md): generated libsy, protocol, and translation
documentation, crate setup, and API boundaries
- [`switchyard-translation`](../crates/switchyard-translation/README.md):
request, response, and stream translation
diff --git a/docs/index.md b/docs/index.md
index 3cd51914a..b023ffdc1 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -23,7 +23,7 @@ The Server Path builds and runs the standalone `switchyard-server` binary.
- [Routing Algorithms](routing_algorithms/overview.md): choose how requests select a model
- [Architecture](architecture.md): understand the proxy and library components
- [Server CLI Reference](cli_reference.md): inspect `switchyard-server` commands and options
-- [Rust API](reference/rust_api.md): browse libsy and protocol crate documentation
+- [Rust API](reference/rust_api.md): browse libsy, protocol, and translation crate documentation
- [Context-Window Handling](operations/context_window.md): configure eviction and retry behavior
- [Tuning](tuning/index.md): the loop from verifying routing to recording a result
- [Troubleshooting](operations/troubleshooting.md): symptoms, silent misconfigurations, and fixes
@@ -33,6 +33,6 @@ The Server Path builds and runs the standalone `switchyard-server` binary.
- [`switchyard-server`](../crates/switchyard-server/README.md): server configuration, endpoints, and metrics
- [`switchyard-libsy`](reference/rust_api.md#switchyard-libsy): embeddable routing algorithms
- [`switchyard-protocol`](reference/rust_api.md#switchyard-protocol): provider-neutral API types
-- [`switchyard-translation`](../crates/switchyard-translation/README.md): protocol translation
+- [`switchyard-translation`](reference/rust_api.md#switchyard-translation): protocol translation
- [`switchyard-nemo-relay-plugin`](../crates/switchyard-nemo-relay-plugin/README.md): native plugin build and configuration
- [Dynamo / agentgateway](../examples/dynamo-preproc/README.md): Switchyard PreProc integration example
diff --git a/docs/reference/rust_api.md b/docs/reference/rust_api.md
index a6d14d99c..56f4b096d 100644
--- a/docs/reference/rust_api.md
+++ b/docs/reference/rust_api.md
@@ -1,7 +1,7 @@
# Rust API
Switchyard publishes generated API documentation for its embeddable routing
-library and provider-neutral protocol types.
+library, provider-neutral protocol types, and format translation.
## `switchyard-libsy`
@@ -17,9 +17,16 @@ clients, decisions, metadata, and wire-format identifiers.
<a href="../../rust/switchyard_protocol/">Open the generated protocol API documentation</a>
+## `switchyard-translation`
+
+Use translation to convert requests, responses, and streams between OpenAI Chat
+Completions, OpenAI Responses, and Anthropic Messages formats.
+
+<a href="../../rust/switchyard_translation/">Open the generated translation API documentation</a>
+
## Crate boundary
-Applications embedding libsy normally depend on both crates:
+Applications embedding libsy normally depend on the libsy and protocol crates:
```toml
[dependencies]
@@ -31,6 +38,10 @@ Import algorithms and orchestration types from `switchyard_libsy`. Import
requests, responses, metadata, decisions, and LLM client traits from
`switchyard_protocol`. Keep both dependencies on compatible versions.
+Add `switchyard-translation` when your application directly converts requests,
+responses, or streams between provider formats. Use a version compatible with
+your other Switchyard dependencies.
+
## CI previews
The Documentation workflow publishes a preview for same-repository pull