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

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.rs
index 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.md
index 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 policy
The examples above use `TranslationPolicy::default()`. A translation policy decides what happens
diff --git a/crates/switchyard-translation/src/engine.rs b/crates/switchyard-translation/src/engine.rs
index 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.rs
index 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.py
index 789a5bcd2..ac84a3bc1 100644
--- a/switchyard/translation.py
+++ b/switchyard/translation.py
@@ -28,22 +28,23 @@ failures raise TranslationError, whose kind and details attributes
identify 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.py
index 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.py
index 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)