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
feat(translation): support request extensions in response translation (#1233)
David Gardner777129129350
diff --git a/crates/switchyard-py/src/translation.rs b/crates/switchyard-py/src/translation.rsindex 2740344b1..eb6465071 100644--- a/crates/switchyard-py/src/translation.rs+++ b/crates/switchyard-py/src/translation.rs@@ -138,18 +138,29 @@ impl PyTranslationEngine {translation_output(py, output)}- /// Translate a complete response dictionary, returning body and diagnostics.+ /// Translate a complete response, optionally restoring tool details from request extensions.+ #[pyo3(signature = (source, target, body, *, request_extensions=None))]fn translate_response(&self,py: Python<'_>,source: &str,target: &str,body: &Bound<'_, PyDict>,+ request_extensions: Option<&Bound<'_, PyDict>>,) -> PyResult<Py<PyDict>> {let body: Value = from_python(body.as_any())?;+ let request_extensions: ProviderExtensions = request_extensions+ .map(|extensions| from_python(extensions.as_any()))+ .transpose()?+ .unwrap_or_default();let output = py.detach(|| {- self.inner- .translate_response(source, target, &body, &self.default_policy)+ self.inner.translate_response_with_extensions(+ source,+ target,+ &body,+ &request_extensions,+ &self.default_policy,+ )});translation_output(py, output)}diff --git a/crates/switchyard-translation/README.md b/crates/switchyard-translation/README.mdindex ad3255708..edfdbeb1b 100644--- a/crates/switchyard-translation/README.md+++ b/crates/switchyard-translation/README.md@@ -88,6 +88,12 @@ fn translate_response() -> Result<(), Box<dyn std::error::Error>> {}```+To restore Responses tool namespaces and custom tool calls, use+`translate_response_with_extensions(source, target, body, request_extensions, policy)`.+Pass `&decoded_request.request.extensions` from the original request returned by+`decode_request`. Empty extensions preserve the behavior of `translate_response`.+Extensions apply after encoding, including when a same-format response is preserved.+## Translation policyThe examples above use `TranslationPolicy::default()`. A translation policy decides what happensdiff --git a/crates/switchyard-translation/src/engine.rs b/crates/switchyard-translation/src/engine.rsindex c0865313b..f70d06725 100644--- a/crates/switchyard-translation/src/engine.rs+++ b/crates/switchyard-translation/src/engine.rs@@ -230,14 +230,16 @@ impl TranslationEngine {policy: &TranslationPolicy,) -> Result<TranslationOutput> {let mut output = self.encode_response(target, response, policy)?;- crate::codex_namespaces::restore_qualified_tool_names(- &mut output.body,- &crate::codex_namespaces::qualified_tool_origins(request_extensions),- );- crate::codex_custom_tools::restore_custom_tool_calls(- &mut output.body,- &crate::codex_custom_tools::custom_tool_names(request_extensions),- );+ if !request_extensions.fields.is_empty() {+ crate::codex_namespaces::restore_qualified_tool_names(+ &mut output.body,+ &crate::codex_namespaces::qualified_tool_origins(request_extensions),+ );+ crate::codex_custom_tools::restore_custom_tool_calls(+ &mut output.body,+ &crate::codex_custom_tools::custom_tool_names(request_extensions),+ );+ }Ok(output)}@@ -248,6 +250,26 @@ impl TranslationEngine {target: impl Into<FormatId>,body: &Value,policy: &TranslationPolicy,+ ) -> Result<TranslationOutput> {+ self.translate_response_with_extensions(+ source,+ target,+ body,+ &ProviderExtensions::default(),+ policy,+ )+ }++ /// Translates a response while restoring details from the original request's extensions.+ ///+ /// Request extensions apply after encoding, including when the target body is preserved.+ pub fn translate_response_with_extensions(+ &self,+ source: impl Into<FormatId>,+ target: impl Into<FormatId>,+ body: &Value,+ request_extensions: &ProviderExtensions,+ policy: &TranslationPolicy,) -> Result<TranslationOutput> {let source = source.into();let target = target.into();@@ -255,10 +277,12 @@ impl TranslationEngine {.registry.codec(source.clone())?.decode_response(body, policy)?;- let encoded = self- .registry- .codec(target.clone())?- .encode_response(&decoded.response, policy)?;+ let encoded = self.encode_response_with_extensions(+ target.clone(),+ &decoded.response,+ request_extensions,+ policy,+ )?;Ok(TranslationOutput {body: encoded.body,diagnostics: with_formats(decoded.diagnostics, encoded.diagnostics, source, target),diff --git a/crates/switchyard-translation/tests/response_translation.rs b/crates/switchyard-translation/tests/response_translation.rsindex 7d3ce5df5..1c654fde5 100644--- a/crates/switchyard-translation/tests/response_translation.rs+++ b/crates/switchyard-translation/tests/response_translation.rs@@ -8,7 +8,8 @@ pub mod common;use pretty_assertions::assert_eq;use serde_json::json;use switchyard_translation::{- ContentBlock, PreservationPolicy, StopReason, TranslationEngine, TranslationPolicy, WireFormat,+ ContentBlock, PreservationPolicy, ProviderExtensions, StopReason, TranslationEngine,+ TranslationPolicy, WireFormat,};use common::{@@ -861,6 +862,12 @@ fn openai_chat_response_with_tool_call_translates_to_responses_output_item() ->"id": "call_1","type": "function","function": {"name": "lookup", "arguments": "{\"q\":\"rust\"}"}+ }, {+ "id": "call_2", "type": "function",+ "function": {"name": "mcp__docs__search", "arguments": "{\"query\":\"streaming\"}"}+ }, {+ "id": "call_3", "type": "function",+ "function": {"name": "exec", "arguments": "{\"input\":\"ls -la\"}"}}]},"finish_reason": "tool_calls"@@ -878,10 +885,17 @@ fn openai_chat_response_with_tool_call_translates_to_responses_output_item() ->.body;assert_eq!(output["object"], "response");- assert_eq!(output["output"][0]["type"], "function_call");- assert_eq!(output["output"][0]["call_id"], "call_1");- assert_eq!(output["output"][0]["name"], "lookup");- assert_eq!(output["output"][0]["arguments"], "{\"q\": \"rust\"}");+ assert_eq!(+ output["output"],+ json!([+ {"type": "function_call", "call_id": "call_1", "name": "lookup",+ "arguments": "{\"q\": \"rust\"}"},+ {"type": "function_call", "call_id": "call_2", "name": "mcp__docs__search",+ "arguments": "{\"query\": \"streaming\"}"},+ {"type": "function_call", "call_id": "call_3", "name": "exec",+ "arguments": "{\"input\": \"ls -la\"}"}+ ])+ );assert_eq!(output["usage"],json!({@@ -892,6 +906,83 @@ fn openai_chat_response_with_tool_call_translates_to_responses_output_item() ->"output_tokens_details": {"reasoning_tokens": 0}}));++ let policy = TranslationPolicy::default();+ let request = engine.decode_request(+ WireFormat::OpenAiResponses,+ &json!({+ "input": "Search and list files",+ "tools": [+ {"type": "namespace", "name": "mcp__docs", "tools": [+ {"type": "function", "name": "search", "parameters": {}}+ ]},+ {"type": "custom", "name": "exec", "format": {"type": "text"}}+ ]+ }),+ &policy,+ )?;+ let extensions = &request.request.extensions;+ let empty = ProviderExtensions::default();+ let mut restored = output.clone();+ restored["output"] = json!([+ {"type": "function_call", "call_id": "call_1", "name": "lookup",+ "arguments": "{\"q\": \"rust\"}"},+ {"type": "function_call", "call_id": "call_2", "name": "search",+ "namespace": "mcp__docs", "arguments": "{\"query\": \"streaming\"}"},+ {"type": "custom_tool_call", "call_id": "call_3", "name": "exec", "input": "ls -la"}+ ]);+ let anthropic = engine+ .translate_response(+ WireFormat::OpenAiChat,+ WireFormat::AnthropicMessages,+ &body,+ &policy,+ )?+ .body;+ let mut preserved = output.clone();+ preserved["output"][2]["id"] = json!("fc_custom");+ let mut restored_preserved = restored.clone();+ restored_preserved["output"][2]["id"] = json!("ctc_custom");++ for (name, source, target, body, extensions, expected) in [+ (+ "no extensions",+ WireFormat::OpenAiChat,+ WireFormat::OpenAiResponses,+ &body,+ &empty,+ &output,+ ),+ (+ "namespace and custom restored",+ WireFormat::OpenAiChat,+ WireFormat::OpenAiResponses,+ &body,+ extensions,+ &restored,+ ),+ (+ "Anthropic unchanged",+ WireFormat::OpenAiChat,+ WireFormat::AnthropicMessages,+ &body,+ extensions,+ &anthropic,+ ),+ (+ "preserved response restored",+ WireFormat::OpenAiResponses,+ WireFormat::OpenAiResponses,+ &preserved,+ extensions,+ &restored_preserved,+ ),+ ] {+ let translated =+ engine.translate_response_with_extensions(source, target, body, extensions, &policy)?;+ assert_eq!(&translated.body, expected, "{name}");+ assert!(translated.diagnostics.is_empty(), "{name}");+ }Ok(())}diff --git a/switchyard/translation.py b/switchyard/translation.pyindex 789a5bcd2..ac84a3bc1 100644--- a/switchyard/translation.py+++ b/switchyard/translation.py@@ -28,22 +28,23 @@ failures raise TranslationError, whose kind and details attributesidentify the failure. str(error) provides a human-readable message.To restore Responses tool namespaces and custom tool calls, pass the original-decoded request's extensions when encoding the response::+decoded request's extensions when translating the response::decoded_request = engine.decode_request(source_format, request_body)encoded = engine.encode_request(backend_format, decoded_request["request"])# Send encoded["body"] to the backend and receive backend_response.- decoded_response = engine.decode_response(backend_format, backend_response)-- result = engine.encode_response(+ result = engine.translate_response(+ backend_format,source_format,- decoded_response["response"],+ backend_response,request_extensions=decoded_request["request"]["extensions"],)+encode_response also accepts request_extensions when encoding an edited response IR.request_extensions uses the IR shape {"fields": {...}}. Omitting it, passing None,-or passing an empty dictionary or {"fields": {}} all encode without request context.+or passing an empty dictionary or {"fields": {}} all translate without request context.+Extensions apply after encoding, including when a same-format response is preserved.Use translate_stream to convert SSE byte chunks into provider event dictionaries::diff --git a/switchyard_rust/translation.py b/switchyard_rust/translation.pyindex 298aa4ca8..d1abdc3ec 100644--- a/switchyard_rust/translation.py+++ b/switchyard_rust/translation.py@@ -72,9 +72,14 @@ if TYPE_CHECKING:...def translate_response(- self, source: WireFormat | str, target: WireFormat | str, body: dict[str, Any]+ self,+ source: WireFormat | str,+ target: WireFormat | str,+ body: dict[str, Any],+ *,+ request_extensions: dict[str, Any] | None = None,) -> dict[str, Any]:- """Translate a complete response, returning body and diagnostics."""+ """Return body and diagnostics, optionally using decoded request extensions."""...def decode_stream(diff --git a/tests/test_translation.py b/tests/test_translation.pyindex 2a293cad8..dd903bf9a 100644--- a/tests/test_translation.py+++ b/tests/test_translation.py@@ -29,7 +29,17 @@ def test_translate_request() -> None:}-def test_translate_response() -> None:+ "kwargs",+ [+ pytest.param({}, id="omitted"),+ pytest.param({"request_extensions": None}, id="none"),+ pytest.param({"request_extensions": {}}, id="empty"),+ pytest.param({"request_extensions": {"fields": {}}}, id="empty-fields"),+ pytest.param({"request_extensions": {"fields": {"unrelated": True}}}, id="unrelated"),+ ],+)+def test_translate_response(kwargs) -> None:body = {"id": "response-1","model": "example",@@ -43,7 +53,7 @@ def test_translate_response() -> None:],}result = TranslationEngine().translate_response(- "openai_responses", WireFormat.ANTHROPIC_MESSAGES, body+ "openai_responses", WireFormat.ANTHROPIC_MESSAGES, body, **kwargs)assert set(result) == {"body", "diagnostics"}assert result["diagnostics"] == []@@ -52,17 +62,49 @@ def test_translate_response() -> None:assert result["body"]["stop_reason"] == "end_turn"-def test_lossy_conversion_returns_serialized_diagnostics() -> None:- result = TranslationEngine().translate_request(- "openai_chat", "anthropic_messages", {"model": "example", "messages": [42]}- )+ "method,args,kwargs,message,source,target",+ [+ pytest.param(+ "translate_request",+ ("openai_chat", "anthropic_messages", {"model": "example", "messages": [42]}),+ {},+ "OpenAI message at index 0 is not an object",+ "openai_chat",+ "anthropic_messages",+ id="request",+ ),+ pytest.param(+ "translate_response",+ ("openai_responses", "anthropic_messages", {"output": [42]}),+ {"request_extensions": {"fields": {"unrelated": True}}},+ "Responses output item is not an object",+ "openai_responses",+ "anthropic_messages",+ id="response",+ ),+ pytest.param(+ "decode_request",+ ("openai_chat", {"messages": [42]}),+ {},+ "OpenAI message at index 0 is not an object",+ None,+ None,+ id="decoded-request",+ ),+ ],+)+def test_lossy_conversion_returns_serialized_diagnostics(+ method, args, kwargs, message, source, target+) -> None:+ result = getattr(TranslationEngine(), method)(*args, **kwargs)assert result["diagnostics"] == [{"severity": "Warning","code": "lossy_conversion",- "message": "OpenAI message at index 0 is not an object",- "source": "openai_chat",- "target": "anthropic_messages",+ "message": message,+ "source": source,+ "target": target,"path": None,}]@@ -87,6 +129,11 @@ def test_invalid_argument_types(source, target, body) -> None:[pytest.param("translate_request", ("custom", "openai_chat", {}), id="translate-request"),pytest.param("decode_response", ("custom", {}), id="decode-response"),+ pytest.param(+ "translate_response",+ ("openai_chat", "custom", {"choices": []}),+ id="translate-response",+ ),],)def test_unknown_format_raises_translation_error(method, args) -> None:@@ -124,7 +171,8 @@ def test_request_ir_round_trip_and_edit() -> None:assert encoded["diagnostics"] == []-def test_response_ir_restores_request_tool_extensions() -> None:[email protected]("method", ["encode_response", "translate_response"])+def test_response_ir_restores_request_tool_extensions(method) -> None:engine = TranslationEngine()request = engine.decode_request("openai_responses",@@ -140,74 +188,100 @@ def test_response_ir_restores_request_tool_extensions() -> None:],},)["request"]- decoded = engine.decode_response(- WireFormat.OPENAI_CHAT,- {- "id": "response-1",- "model": "example",- "choices": [- {- "message": {- "role": "assistant",- "tool_calls": [- {- "id": "call-1",- "type": "function",- "function": {- "name": "mcp__docs__search",- "arguments": '{"query":"streaming"}',- },+ body = {+ "id": "response-1",+ "model": "example",+ "choices": [+ {+ "message": {+ "role": "assistant",+ "tool_calls": [+ {+ "id": "call-1",+ "type": "function",+ "function": {+ "name": "mcp__docs__search",+ "arguments": '{"query":"streaming"}',},- {- "id": "call-2",- "type": "function",- "function": {- "name": "exec",- "arguments": '{"input":"ls -la"}',- },+ },+ {+ "id": "call-2",+ "type": "function",+ "function": {+ "name": "exec",+ "arguments": '{"input":"ls -la"}',},- ],- },- "finish_reason": "tool_calls",- }- ],- },- )- assert set(decoded) == {"response", "diagnostics"}- assert decoded["diagnostics"] == []- response = json.loads(json.dumps(decoded["response"]))- plain = engine.encode_response("openai_responses", response)- for empty in (None, {}, {"fields": {}}):- assert (- engine.encode_response("openai_responses", response, request_extensions=empty) == plain+ },+ ],+ },+ "finish_reason": "tool_calls",+ }+ ],+ }+ extensions = request["extensions"]+ if method == "encode_response":+ response = engine.decode_response("openai_chat", body)["response"]+ restored = engine.encode_response(+ "openai_responses", response, request_extensions=extensions+ )+ else:+ restored = engine.translate_response(+ "openai_chat", "openai_responses", body, request_extensions=extensions)- plain_calls = plain["body"]["output"]- assert [call["type"] for call in plain_calls] == ["function_call", "function_call"]- assert plain_calls[0]["name"] == "mcp__docs__search"- assert "namespace" not in plain_calls[0]- restored = engine.encode_response(- WireFormat.OPENAI_RESPONSES,- response,- request_extensions=json.loads(json.dumps(request["extensions"])),- )assert restored["diagnostics"] == []search, custom = restored["body"]["output"]+ assert search["type"] == "function_call"+ assert search["call_id"] == "call-1"assert search["name"] == "search"assert search["namespace"] == "mcp__docs"+ assert json.loads(search["arguments"]) == {"query": "streaming"}assert custom["type"] == "custom_tool_call"+ assert custom["call_id"] == "call-2"assert custom["name"] == "exec"assert custom["input"] == "ls -la"assert "arguments" not in custom-def test_ir_boundary_diagnostics_and_errors() -> None:- engine = TranslationEngine()- decoded = engine.decode_request("openai_chat", {"messages": [42]})- assert decoded["diagnostics"][0]["code"] == "lossy_conversion"- assert decoded["diagnostics"][0]["severity"] == "Warning"- with pytest.raises(ValueError):- engine.encode_request("openai_chat", {"messages": "not a list"})- with pytest.raises(ValueError):- engine.encode_response("openai_chat", {}, request_extensions={"fields": 42})- with pytest.raises(TypeError):- engine.encode_response("openai_chat", {}, request_extensions=[])+ "method,args,kwargs,error",+ [+ pytest.param(+ "encode_request",+ ("openai_chat", {"messages": "not a list"}),+ {},+ ValueError,+ id="request",+ ),+ pytest.param(+ "encode_response",+ ("openai_chat", {}),+ {"request_extensions": {"fields": 42}},+ ValueError,+ id="encode-invalid-fields",+ ),+ pytest.param(+ "encode_response",+ ("openai_chat", {}),+ {"request_extensions": []},+ TypeError,+ id="encode-invalid-type",+ ),+ pytest.param(+ "translate_response",+ ("openai_chat", "openai_responses", {"choices": []}),+ {"request_extensions": {"fields": 42}},+ ValueError,+ id="translate-invalid-fields",+ ),+ pytest.param(+ "translate_response",+ ("openai_chat", "openai_responses", {"choices": []}),+ {"request_extensions": []},+ TypeError,+ id="translate-invalid-type",+ ),+ ],+)+def test_ir_boundary_errors(method, args, kwargs, error) -> None:+ with pytest.raises(error):+ getattr(TranslationEngine(), method)(*args, **kwargs)