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(python): expose translation encode and decode methods (#1202)
David Gardnerf979f6929f35
diff --git a/crates/switchyard-py/src/translation.rs b/crates/switchyard-py/src/translation.rsindex 972181f9e..e2e78fb11 100644--- a/crates/switchyard-py/src/translation.rs+++ b/crates/switchyard-py/src/translation.rs@@ -7,8 +7,8 @@ use pyo3::prelude::*;use pyo3::types::PyDict;use serde_json::{Value, json};use switchyard_translation::{- TranslationEngine, TranslationError as CoreTranslationError, TranslationOutput,- TranslationPolicy,+ AggLlmResponse, LlmRequest, ProviderExtensions, TranslationEngine,+ TranslationError as CoreTranslationError, TranslationOutput, TranslationPolicy,};use crate::py_serde::{from_python, to_python};@@ -37,6 +37,84 @@ impl PyTranslationEngine {}}+ /// Decode a provider request, returning request IR and diagnostics.+ fn decode_request(+ &self,+ py: Python<'_>,+ source: &str,+ body: &Bound<'_, PyDict>,+ ) -> PyResult<Py<PyDict>> {+ let body: Value = from_python(body.as_any())?;+ let output = py.detach(|| {+ self.inner+ .decode_request(source, &body, &self.default_policy)+ });+ let output = into_python_result(py, output)?;+ let result = PyDict::new(py);+ result.set_item("request", to_python(py, &output.request)?)?;+ result.set_item("diagnostics", to_python(py, &output.diagnostics)?)?;+ Ok(result.unbind())+ }++ /// Encode request IR, returning a provider body and diagnostics.+ fn encode_request(+ &self,+ py: Python<'_>,+ target: &str,+ request: &Bound<'_, PyDict>,+ ) -> PyResult<Py<PyDict>> {+ let request: LlmRequest = from_python(request.as_any())?;+ let output = py.detach(|| {+ self.inner+ .encode_request(target, &request, &self.default_policy)+ });+ translation_output(py, output)+ }++ /// Decode a complete provider response, returning response IR and diagnostics.+ fn decode_response(+ &self,+ py: Python<'_>,+ source: &str,+ body: &Bound<'_, PyDict>,+ ) -> PyResult<Py<PyDict>> {+ let body: Value = from_python(body.as_any())?;+ let output = py.detach(|| {+ self.inner+ .decode_response(source, &body, &self.default_policy)+ });+ let output = into_python_result(py, output)?;+ let result = PyDict::new(py);+ result.set_item("response", to_python(py, &output.response)?)?;+ result.set_item("diagnostics", to_python(py, &output.diagnostics)?)?;+ Ok(result.unbind())+ }++ /// Encode response IR, optionally restoring tool details from request extensions.+ #[pyo3(signature = (target, response, *, request_extensions=None))]+ fn encode_response(+ &self,+ py: Python<'_>,+ target: &str,+ response: &Bound<'_, PyDict>,+ request_extensions: Option<&Bound<'_, PyDict>>,+ ) -> PyResult<Py<PyDict>> {+ let response: AggLlmResponse = from_python(response.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.encode_response_with_extensions(+ target,+ &response,+ &request_extensions,+ &self.default_policy,+ )+ });+ translation_output(py, output)+ }+/// Translate a request dictionary, returning body and diagnostics.fn translate_request(&self,@@ -74,21 +152,25 @@ fn translation_output(py: Python<'_>,result: Result<TranslationOutput, CoreTranslationError>,) -> PyResult<Py<PyDict>> {- let output = match result {- Ok(output) => output,+ let output = into_python_result(py, result)?;+ let result = PyDict::new(py);+ result.set_item("body", to_python(py, &output.body)?)?;+ result.set_item("diagnostics", to_python(py, &output.diagnostics)?)?;+ Ok(result.unbind())+}++fn into_python_result<T>(py: Python<'_>, result: Result<T, CoreTranslationError>) -> PyResult<T> {+ match result {+ Ok(output) => Ok(output),Err(error) => {let exception = TranslationError::new_err(error.to_string());exception.value(py).setattr("kind", error.kind())?;exception.value(py).setattr("details", to_python(py, &error_details(&error))?)?;- return Err(exception);+ Err(exception)}- };- let result = PyDict::new(py);- result.set_item("body", to_python(py, &output.body)?)?;- result.set_item("diagnostics", to_python(py, &output.diagnostics)?)?;- Ok(result.unbind())+ }}fn error_details(error: &CoreTranslationError) -> Value {diff --git a/switchyard/translation.py b/switchyard/translation.pyindex f8c13f22f..9bf480e50 100644--- a/switchyard/translation.py+++ b/switchyard/translation.py@@ -14,18 +14,36 @@body = result["body"]diagnostics = result["diagnostics"]-Both methods accept a WireFormat member or its string value for each format.-Bodies must be dictionaries containing JSON-compatible values. Each result has-"body" and "diagnostics" keys. Diagnostics are dictionaries with severity (Info,+All methods accept a WireFormat member or its string value for each format.+Bodies and IR values must be dictionaries containing JSON-compatible values.+Translate and encode results have "body" and "diagnostics" keys. decode_request+returns "request" and "diagnostics" keys; decode_response returns "response" and+"diagnostics" keys. Diagnostics contain severity (Info,Warning, or Error), code, message, source, target, and path; the last three fieldsmay be None. The default policy allows lossy conversions with diagnostics.-Incorrect top-level argument types raise TypeError. Unknown formats and translation+Incorrect top-level argument types raise TypeError. Malformed IR dictionaries raise+ValueError during deserialization. Unknown formats and translationfailures raise TranslationError, whose kind and details attributesidentify the failure. str(error) provides a human-readable message.-Translation uses the default policy and handles complete requests and responses.-Calls do not retain request context for subsequent response translation.+To restore Responses tool namespaces and custom tool calls, pass the original+decoded request's extensions when encoding 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(+ source_format,+ decoded_response["response"],+ request_extensions=decoded_request["request"]["extensions"],+ )++request_extensions uses the IR shape {"fields": {...}}. Omitting it, passing None,+or passing an empty dictionary or {"fields": {}} all encode without request context."""from switchyard_rust.translation import TranslationEngine, TranslationError, WireFormatdiff --git a/switchyard_rust/translation.py b/switchyard_rust/translation.pyindex 230a22fb3..35ca80d03 100644--- a/switchyard_rust/translation.py+++ b/switchyard_rust/translation.py@@ -34,6 +34,34 @@ if TYPE_CHECKING:def __init__(self) -> None: ...+ def decode_request(+ self, source: WireFormat | str, body: dict[str, Any]+ ) -> dict[str, Any]:+ """Return request IR and diagnostics under request and diagnostics keys."""+ ...++ def encode_request(+ self, target: WireFormat | str, request: dict[str, Any]+ ) -> dict[str, Any]:+ """Encode request IR, returning body and diagnostics."""+ ...++ def decode_response(+ self, source: WireFormat | str, body: dict[str, Any]+ ) -> dict[str, Any]:+ """Return response IR and diagnostics under response and diagnostics keys."""+ ...++ def encode_response(+ self,+ target: WireFormat | str,+ response: dict[str, Any],+ *,+ request_extensions: dict[str, Any] | None = None,+ ) -> dict[str, Any]:+ """Return body and diagnostics, optionally using decoded request extensions."""+ ...+def translate_request(self, source: WireFormat | str, target: WireFormat | str, body: dict[str, Any]) -> dict[str, Any]:diff --git a/tests/test_translation.py b/tests/test_translation.pyindex 3b3f66621..2a293cad8 100644--- a/tests/test_translation.py+++ b/tests/test_translation.py@@ -3,6 +3,8 @@"""Exercise the public Python translation boundary against the native engine."""+import json+import pytestfrom switchyard.translation import TranslationEngine, TranslationError, WireFormat@@ -66,23 +68,34 @@ def test_lossy_conversion_returns_serialized_diagnostics() -> None:]-def test_invalid_format_type() -> None:+ "source,target,body",+ [+ pytest.param(42, "openai_chat", {}, id="invalid-format-type"),+ pytest.param(+ "openai_chat", "openai_responses", '{"messages": []}', id="non-dictionary-body"+ ),+ ],+)+def test_invalid_argument_types(source, target, body) -> None:with pytest.raises(TypeError):- TranslationEngine().translate_request(42, "openai_chat", {})+ TranslationEngine().translate_request(source, target, body)-def test_unknown_format_raises_translation_error() -> None:+ "method,args",+ [+ pytest.param("translate_request", ("custom", "openai_chat", {}), id="translate-request"),+ pytest.param("decode_response", ("custom", {}), id="decode-response"),+ ],+)+def test_unknown_format_raises_translation_error(method, args) -> None:with pytest.raises(TranslationError) as caught:- TranslationEngine().translate_request("custom", "openai_chat", {})+ getattr(TranslationEngine(), method)(*args)assert caught.value.kind == "Other"assert caught.value.details == {"message": "no codec registered for custom"}-def test_body_must_be_a_dictionary() -> None:- with pytest.raises(TypeError):- TranslationEngine().translate_request("openai_chat", "openai_responses", '{"messages": []}')--def test_translation_error_has_readable_message_and_structured_details() -> None:with pytest.raises(TranslationError) as caught:TranslationEngine().translate_request("openai_chat", "openai_responses", {"messages": {}})@@ -92,3 +105,109 @@ def test_translation_error_has_readable_message_and_structured_details() -> Noneassert error.details == {"path": "$.messages", "expected": "array"}assert error.args == ("expected array at $.messages",)assert str(error) == error.args[0]+++def test_request_ir_round_trip_and_edit() -> None:+ engine = TranslationEngine()+ body = {"model": "example", "messages": [{"role": "user", "content": "Hello"}]}+ decoded = engine.decode_request(WireFormat.OPENAI_CHAT, body)+ assert set(decoded) == {"request", "diagnostics"}+ assert decoded["diagnostics"] == []+ request = json.loads(json.dumps(decoded["request"]))+ assert request["messages"][0]["content"] == [{"type": "text", "text": "Hello"}]+ request["model"] = "edited"+ assert engine.encode_request("openai_chat", request) == {"body": body, "diagnostics": []}+ request["preservation"]["requests"].clear()+ encoded = engine.encode_request(WireFormat.OPENAI_CHAT, request)+ assert encoded["body"]["model"] == "edited"+ assert encoded["body"]["messages"] == body["messages"]+ assert encoded["diagnostics"] == []+++def test_response_ir_restores_request_tool_extensions() -> None:+ engine = TranslationEngine()+ request = engine.decode_request(+ "openai_responses",+ {+ "input": "Search documentation and list files",+ "tools": [+ {+ "type": "namespace",+ "name": "mcp__docs",+ "tools": [{"type": "function", "name": "search", "parameters": {}}],+ },+ {"type": "custom", "name": "exec", "format": {"type": "text"}},+ ],+ },+ )["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"}',+ },+ },+ {+ "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+ )+ 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["name"] == "search"+ assert search["namespace"] == "mcp__docs"+ assert custom["type"] == "custom_tool_call"+ 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=[])