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(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.rs
index 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.py
index 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 fields
may 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 translation
failures raise TranslationError, whose kind and details attributes
identify 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, WireFormat
diff --git a/switchyard_rust/translation.py b/switchyard_rust/translation.py
index 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.py
index 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 pytest
from 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() -> None
assert 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=[])