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): reintroduce translation bindings (#1180)

David Gardnercfe43a4860db
diff --git a/Cargo.lock b/Cargo.lock
index 568393892..06b27d104 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2668,6 +2668,7 @@ dependencies = [
"switchyard-protocol",
"switchyard-runner",
"switchyard-server",
+ "switchyard-translation",
"tokio",
]
diff --git a/crates/switchyard-py/Cargo.toml b/crates/switchyard-py/Cargo.toml
index 550e7f9c9..b93810f18 100644
--- a/crates/switchyard-py/Cargo.toml
+++ b/crates/switchyard-py/Cargo.toml
@@ -27,4 +27,5 @@ serde_json.workspace = true
switchyard-protocol.workspace = true
switchyard-runner.workspace = true
switchyard-server.workspace = true
+switchyard-translation.workspace = true
tokio.workspace = true
diff --git a/crates/switchyard-py/src/lib.rs b/crates/switchyard-py/src/lib.rs
index 1749c9ce4..cb46762b9 100644
--- a/crates/switchyard-py/src/lib.rs
+++ b/crates/switchyard-py/src/lib.rs
@@ -7,11 +7,13 @@ mod errors;
mod libsy_bindings;
mod py_serde;
mod server_bindings;
+mod translation;
#[pymodule]
fn _switchyard_rust(module: &Bound<'_, PyModule>) -> PyResult<()> {
errors::register(module)?;
libsy_bindings::register(module)?;
server_bindings::register(module)?;
+ translation::register(module)?;
Ok(())
}
diff --git a/crates/switchyard-py/src/translation.rs b/crates/switchyard-py/src/translation.rs
new file mode 100644
index 000000000..972181f9e
--- /dev/null
+++ b/crates/switchyard-py/src/translation.rs
@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use pyo3::create_exception;
+use pyo3::exceptions::PyException;
+use pyo3::prelude::*;
+use pyo3::types::PyDict;
+use serde_json::{Value, json};
+use switchyard_translation::{
+ TranslationEngine, TranslationError as CoreTranslationError, TranslationOutput,
+ TranslationPolicy,
+};
+
+use crate::py_serde::{from_python, to_python};
+
+create_exception!(
+ switchyard.translation,
+ TranslationError,
+ PyException,
+ "Translation failed. Attributes: kind (stable variant name), details (variant fields)."
+);
+
+/// Translate buffered JSON requests and responses with the default policy.
+#[pyclass(name = "TranslationEngine", module = "switchyard.translation", frozen)]
+struct PyTranslationEngine {
+ inner: TranslationEngine,
+ default_policy: TranslationPolicy,
+}
+
+#[pymethods]
+impl PyTranslationEngine {
+ #[new]
+ fn new() -> Self {
+ Self {
+ inner: TranslationEngine::default(),
+ default_policy: TranslationPolicy::default(),
+ }
+ }
+
+ /// Translate a request dictionary, returning body and diagnostics.
+ fn translate_request(
+ &self,
+ py: Python<'_>,
+ source: &str,
+ target: &str,
+ body: &Bound<'_, PyDict>,
+ ) -> PyResult<Py<PyDict>> {
+ let body: Value = from_python(body.as_any())?;
+ let output = py.detach(|| {
+ self.inner
+ .translate_request(source, target, &body, &self.default_policy)
+ });
+ translation_output(py, output)
+ }
+
+ /// Translate a complete response dictionary, returning body and diagnostics.
+ fn translate_response(
+ &self,
+ py: Python<'_>,
+ source: &str,
+ target: &str,
+ body: &Bound<'_, PyDict>,
+ ) -> PyResult<Py<PyDict>> {
+ let body: Value = from_python(body.as_any())?;
+ let output = py.detach(|| {
+ self.inner
+ .translate_response(source, target, &body, &self.default_policy)
+ });
+ translation_output(py, output)
+ }
+}
+
+fn translation_output(
+ py: Python<'_>,
+ result: Result<TranslationOutput, CoreTranslationError>,
+) -> PyResult<Py<PyDict>> {
+ let output = match result {
+ Ok(output) => 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);
+ }
+ };
+ 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 {
+ match error {
+ CoreTranslationError::InvalidJson(error) => json!({
+ "message": error.to_string(),
+ "line": error.line(),
+ "column": error.column(),
+ }),
+ CoreTranslationError::InvalidType { path, expected } => {
+ json!({"path": path, "expected": expected})
+ }
+ CoreTranslationError::UnsupportedTranslation { from, to } => {
+ json!({"from": from, "to": to})
+ }
+ CoreTranslationError::LossyConversion(message) | CoreTranslationError::Other(message) => {
+ json!({"message": message})
+ }
+ CoreTranslationError::UnknownField { path } => json!({"path": path}),
+ CoreTranslationError::InvalidValue { path, message } => {
+ json!({"path": path, "message": message})
+ }
+ CoreTranslationError::UpstreamFailure { error } => json!({"error": error}),
+ }
+}
+
+pub(crate) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {
+ let translation = PyModule::new(module.py(), "translation")?;
+ translation.add_class::<PyTranslationEngine>()?;
+ translation.add(
+ "TranslationError",
+ module.py().get_type::<TranslationError>(),
+ )?;
+ module.add_submodule(&translation)
+}
diff --git a/switchyard/translation.py b/switchyard/translation.py
new file mode 100644
index 000000000..f8c13f22f
--- /dev/null
+++ b/switchyard/translation.py
@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Translate buffered provider requests and responses.
+
+ from switchyard.translation import TranslationEngine, WireFormat
+
+ engine = TranslationEngine()
+ result = engine.translate_request(
+ WireFormat.OPENAI_CHAT,
+ WireFormat.ANTHROPIC_MESSAGES,
+ {"model": "example", "messages": [{"role": "user", "content": "Hello"}]},
+ )
+ 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,
+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
+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.
+"""
+
+from switchyard_rust.translation import TranslationEngine, TranslationError, WireFormat
+
+__all__ = ["TranslationEngine", "TranslationError", "WireFormat"]
diff --git a/switchyard_rust/translation.py b/switchyard_rust/translation.py
new file mode 100644
index 000000000..230a22fb3
--- /dev/null
+++ b/switchyard_rust/translation.py
@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Native bindings for buffered request and response translation."""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any, final
+
+from switchyard_rust._native import load_native
+
+
+class WireFormat(str, Enum):
+ """Supported provider JSON formats."""
+
+ OPENAI_CHAT = "openai_chat"
+ OPENAI_RESPONSES = "openai_responses"
+ ANTHROPIC_MESSAGES = "anthropic_messages"
+
+
+if TYPE_CHECKING:
+
+ class TranslationError(Exception):
+ """Translation failure with a readable message and structured details."""
+
+ kind: str
+ details: dict[str, Any]
+
+ @final
+ class TranslationEngine:
+ """Translate buffered provider JSON using the default translation policy.
+
+ Calls are independent. Request context is not retained for responses.
+ """
+
+ def __init__(self) -> None: ...
+
+ def translate_request(
+ self, source: WireFormat | str, target: WireFormat | str, body: dict[str, Any]
+ ) -> dict[str, Any]:
+ """Return a dictionary with body and diagnostics entries."""
+ ...
+
+ def translate_response(
+ self, source: WireFormat | str, target: WireFormat | str, body: dict[str, Any]
+ ) -> dict[str, Any]:
+ """Translate a complete response, returning body and diagnostics."""
+ ...
+
+
+def __getattr__(name: str) -> object:
+ if name in {"TranslationEngine", "TranslationError"}:
+ native: Any = load_native()
+ return getattr(native.translation, name)
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["TranslationEngine", "TranslationError", "WireFormat"]
diff --git a/tests/test_no_stale_module_paths.py b/tests/test_no_stale_module_paths.py
index a102acd79..3a946ba54 100644
--- a/tests/test_no_stale_module_paths.py
+++ b/tests/test_no_stale_module_paths.py
@@ -16,7 +16,6 @@ _STALE_PATH_PATTERNS = (
"switchyard.server.",
"switchyard_rust.components",
"switchyard_rust.core",
- "switchyard_rust.translation",
"nemo_switchyard.",
"SwitchyardV2",
"switchyard_v2",
diff --git a/tests/test_translation.py b/tests/test_translation.py
new file mode 100644
index 000000000..3b3f66621
--- /dev/null
+++ b/tests/test_translation.py
@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exercise the public Python translation boundary against the native engine."""
+
+import pytest
+
+from switchyard.translation import TranslationEngine, TranslationError, WireFormat
+
+
+def test_translate_request() -> None:
+ body = {
+ "model": "example",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "max_completion_tokens": 64,
+ }
+ result = TranslationEngine().translate_request(
+ WireFormat.OPENAI_CHAT, "anthropic_messages", body
+ )
+ assert result == {
+ "body": {
+ "model": "example",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "max_tokens": 64,
+ },
+ "diagnostics": [],
+ }
+
+
+def test_translate_response() -> None:
+ body = {
+ "id": "response-1",
+ "model": "example",
+ "status": "completed",
+ "output": [
+ {
+ "type": "message",
+ "role": "assistant",
+ "content": [{"type": "output_text", "text": "Hello"}],
+ }
+ ],
+ }
+ result = TranslationEngine().translate_response(
+ "openai_responses", WireFormat.ANTHROPIC_MESSAGES, body
+ )
+ assert set(result) == {"body", "diagnostics"}
+ assert result["diagnostics"] == []
+ assert result["body"]["model"] == "example"
+ assert result["body"]["content"] == [{"type": "text", "text": "Hello"}]
+ 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]}
+ )
+ assert result["diagnostics"] == [
+ {
+ "severity": "Warning",
+ "code": "lossy_conversion",
+ "message": "OpenAI message at index 0 is not an object",
+ "source": "openai_chat",
+ "target": "anthropic_messages",
+ "path": None,
+ }
+ ]
+
+
+def test_invalid_format_type() -> None:
+ with pytest.raises(TypeError):
+ TranslationEngine().translate_request(42, "openai_chat", {})
+
+
+def test_unknown_format_raises_translation_error() -> None:
+ with pytest.raises(TranslationError) as caught:
+ TranslationEngine().translate_request("custom", "openai_chat", {})
+ 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": {}})
+
+ error = caught.value
+ assert error.kind == "InvalidType"
+ assert error.details == {"path": "$.messages", "expected": "array"}
+ assert error.args == ("expected array at $.messages",)
+ assert str(error) == error.args[0]