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): add usage examples and explain translation policy (#1067)
David Gardner1f436e30cbf4
diff --git a/crates/switchyard-translation/README.md b/crates/switchyard-translation/README.mdindex 10ed01f11..ad3255708 100644--- a/crates/switchyard-translation/README.md+++ b/crates/switchyard-translation/README.md@@ -6,6 +6,122 @@ request, response, and streaming formats.The crate translates through provider-neutral LLM types from `switchyard-protocol` and does notdepend on provider SDKs, HTTP servers, Python, or FFI bindings.+## Translate a request++```rust+use serde_json::json;+use switchyard_translation::{TranslationEngine, TranslationPolicy, WireFormat};++fn translate_request() -> Result<(), Box<dyn std::error::Error>> {+ let request = json!({+ "model": "switchyard",+ "input": "What's the weather in Paris?",+ "tools": [{+ "type": "function",+ "name": "get_weather",+ "parameters": {+ "type": "object",+ "properties": {+ "city": { "type": "string" }+ }+ }+ }]+ });++ let engine = TranslationEngine::default();+ let policy = TranslationPolicy::default();++ for destination in [WireFormat::OpenAiChat, WireFormat::AnthropicMessages] {+ let result = engine.translate_request(+ WireFormat::OpenAiResponses,+ destination,+ &request,+ &policy,+ )?;+ println!(+ "Responses -> {}\n{}\nDiagnostics: {}\n",+ destination.as_str(),+ serde_json::to_string_pretty(&result.body)?,+ serde_json::to_string_pretty(&result.diagnostics)?+ );+ }++ Ok(())+}+```++## Translate a response++```rust+use serde_json::json;+use switchyard_translation::{TranslationEngine, TranslationPolicy, WireFormat};++fn translate_response() -> Result<(), Box<dyn std::error::Error>> {+ let response = json!({+ "output": [{+ "type": "function_call",+ "call_id": "call_weather",+ "name": "get_weather",+ "arguments": "{\"city\":\"Paris\"}"+ }]+ });++ let engine = TranslationEngine::default();+ let policy = TranslationPolicy::default();++ for destination in [WireFormat::OpenAiChat, WireFormat::AnthropicMessages] {+ let result = engine.translate_response(+ WireFormat::OpenAiResponses,+ destination,+ &response,+ &policy,+ )?;+ println!(+ "Responses -> {}\n{}\nDiagnostics: {}\n",+ destination.as_str(),+ serde_json::to_string_pretty(&result.body)?,+ serde_json::to_string_pretty(&result.diagnostics)?+ );+ }++ Ok(())+}+```++## Translation policy++The examples above use `TranslationPolicy::default()`. A translation policy decides what happens+when an item cannot be translated exactly: keep it, warn about it, or return an error.++The default policy:++- Allows known information loss with warnings.+- Generates stable IDs when the source has none.+- Keeps the source payload in memory.+- Leaves target capabilities unspecified.++The `lossy_conversion_policy` field controls whether known conversions that lose+information are allowed. `LossyConversionPolicy` has two variants:++- `AllowWithDiagnostics` (default): continue translation and record a+ `lossy_conversion` warning in the result's `diagnostics` field.+- `Reject`: return `TranslationError::LossyConversion` when a known lossy conversion+ is encountered.++Calling `translate_request`/`translate_response` annotates every diagnostic with+source and target formats.++To reject known lossy conversions:++```rust+use switchyard_translation::{LossyConversionPolicy, TranslationPolicy};++let policy = TranslationPolicy {+ lossy_conversion_policy: LossyConversionPolicy::Reject,+ ..TranslationPolicy::default()+};+```+## LicenseLicensed under the Apache License, Version 2.0. See the