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.lockindex 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.tomlindex 550e7f9c9..b93810f18 100644--- a/crates/switchyard-py/Cargo.toml+++ b/crates/switchyard-py/Cargo.toml@@ -27,4 +27,5 @@ serde_json.workspace = trueswitchyard-protocol.workspace = trueswitchyard-runner.workspace = trueswitchyard-server.workspace = true+switchyard-translation.workspace = truetokio.workspace = truediff --git a/crates/switchyard-py/src/lib.rs b/crates/switchyard-py/src/lib.rsindex 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.rsnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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]