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(node): expose buffered translation (#1234)

Alex Fournier4000d0a37846
diff --git a/bindings/typescript/README.md b/bindings/typescript/README.md
index 29d435cd6..c94131e0a 100644
--- a/bindings/typescript/README.md
+++ b/bindings/typescript/README.md
@@ -1,8 +1,9 @@
# Switchyard libsy for Node.js
-TypeScript bindings for composite routing. Rust builds a Decision request and uses
-the caller's answer with local tool signals to select a model. The caller handles
-classifier calls, completion requests, and branch state.
+TypeScript bindings for composite routing and buffered JSON translation.
+Composite routing uses the caller's decision response and local tool signals to
+select a model. The caller handles classifier calls, completion requests, and
+branch state.
Capable-first routing defaults to pinning the efficient tier after switching to
it. Set `stage.efficient_hold_turns: 0` to disable this hold. Efficient-first
@@ -107,3 +108,32 @@ tier or uses the stage default. An answer without a usable probability for the
An aborted signal closes the Rust run and rejects promptly, including while
`decide` is pending. Late callback results are ignored. Pass the same signal to
your classifier client to cancel its work too.
+
+## Buffered JSON translation
+
+Translate complete OpenAI Chat Completions, OpenAI Responses, and Anthropic
+Messages bodies with the built-in codecs and default policy:
+
+```ts
+import { TranslationEngine, WireFormat } from "@switchyard/libsy";
+
+const engine = new TranslationEngine();
+const { request, diagnostics } = engine.decodeRequest(WireFormat.OPENAI_CHAT, {
+ model: "example",
+ messages: [{ role: "user", content: "Hello" }],
+});
+const { body } = engine.encodeRequest(WireFormat.ANTHROPIC_MESSAGES, request);
+```
+
+`decodeRequest` and `decodeResponse` return normalized JSON under `request` or
+`response`, plus `diagnostics`. `encodeRequest`, `encodeResponse`,
+`translateRequest`, and `translateResponse` return `body` and `diagnostics`.
+Inputs must be JSON objects. Translation failures raise `TranslationError` with
+`kind` and `details`; invalid normalized input has code `ERR_INVALID_REQUEST`.
+
+Calls retain no request context. To restore request-specific tool names, pass
+decoded `request.extensions` as the third argument to `encodeResponse` or the
+fourth argument to `translateResponse`. Decoded values also retain provider data
+for same-format replay, so editing normalized fields does not automatically
+replace that saved body. This API handles buffered JSON; HTTP transport and SSE
+streams remain with the caller.
diff --git a/bindings/typescript/src/index.ts b/bindings/typescript/src/index.ts
index e82f35ade..a714a5f84 100644
--- a/bindings/typescript/src/index.ts
+++ b/bindings/typescript/src/index.ts
@@ -3,6 +3,8 @@
import { createRequire } from "node:module";
+export { TranslationEngine, TranslationError, WireFormat } from "./translation.js";
+
/** Opaque routing state. Store it unchanged and pass it back on the same branch. */
export type CompositeState = { readonly [key: string]: unknown };
diff --git a/bindings/typescript/src/translation.ts b/bindings/typescript/src/translation.ts
new file mode 100644
index 000000000..b10175893
--- /dev/null
+++ b/bindings/typescript/src/translation.ts
@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { createRequire } from "node:module";
+
+/** Built-in provider JSON formats. */
+export enum WireFormat {
+ OPENAI_CHAT = "openai_chat",
+ OPENAI_RESPONSES = "openai_responses",
+ ANTHROPIC_MESSAGES = "anthropic_messages",
+}
+
+/** Translation failure with a stable kind and variant-specific details. */
+export class TranslationError extends Error {
+ constructor(message: string, readonly kind: string, readonly details: Record<string, unknown>) {
+ super(message);
+ this.name = "TranslationError";
+ }
+}
+
+interface NativeTranslationEngine {
+ decodeRequest(source: string, body: string): string;
+ encodeRequest(target: string, request: string): string;
+ decodeResponse(source: string, body: string): string;
+ encodeResponse(target: string, response: string, requestExtensions: string | null): string;
+ translateRequest(source: string, target: string, body: string): string;
+ translateResponse(source: string, target: string, body: string, requestExtensions: string | null): string;
+}
+
+const native: { NativeTranslationEngine: new () => NativeTranslationEngine } =
+ createRequire(import.meta.url)("./switchyard.node");
+
+function json(value: Record<string, unknown>): string {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ throw new TypeError("Expected a JSON object");
+ }
+ return JSON.stringify(value);
+}
+
+/** Buffered provider JSON translation using the default policy. Calls retain no request context. */
+export class TranslationEngine {
+ readonly #native = new native.NativeTranslationEngine();
+
+ /** Decode a provider request into normalized JSON and diagnostics. */
+ decodeRequest(source: WireFormat | string, body: Record<string, unknown>): {
+ request: Record<string, unknown>; diagnostics: unknown[];
+ } {
+ return this.#call(() => this.#native.decodeRequest(source, json(body)));
+ }
+
+ /** Encode normalized request JSON into a provider body and diagnostics. */
+ encodeRequest(target: WireFormat | string, request: Record<string, unknown>): {
+ body: Record<string, unknown>; diagnostics: unknown[];
+ } {
+ return this.#call(() => this.#native.encodeRequest(target, json(request)));
+ }
+
+ /** Decode a complete provider response into normalized JSON and diagnostics. */
+ decodeResponse(source: WireFormat | string, body: Record<string, unknown>): {
+ response: Record<string, unknown>; diagnostics: unknown[];
+ } {
+ return this.#call(() => this.#native.decodeResponse(source, json(body)));
+ }
+
+ /** Encode a response, optionally restoring tool details from request extensions. */
+ encodeResponse(
+ target: WireFormat | string,
+ response: Record<string, unknown>,
+ requestExtensions?: Record<string, unknown> | null,
+ ): { body: Record<string, unknown>; diagnostics: unknown[] } {
+ return this.#call(() => this.#native.encodeResponse(
+ target, json(response), requestExtensions == null ? null : json(requestExtensions),
+ ));
+ }
+
+ /** Translate a provider request, returning its body and diagnostics. */
+ translateRequest(source: WireFormat | string, target: WireFormat | string, body: Record<string, unknown>): {
+ body: Record<string, unknown>; diagnostics: unknown[];
+ } {
+ return this.#call(() => this.#native.translateRequest(source, target, json(body)));
+ }
+
+ /** Translate a response, optionally restoring tool details from request extensions. */
+ translateResponse(
+ source: WireFormat | string,
+ target: WireFormat | string,
+ body: Record<string, unknown>,
+ requestExtensions?: Record<string, unknown> | null,
+ ): { body: Record<string, unknown>; diagnostics: unknown[] } {
+ return this.#call(() => this.#native.translateResponse(
+ source, target, json(body), requestExtensions == null ? null : json(requestExtensions),
+ ));
+ }
+
+ #call<T>(run: () => string): T {
+ try {
+ return JSON.parse(run());
+ } catch (error) {
+ if (error instanceof Error && error.message.startsWith("ERR_TRANSLATION: ")) {
+ const { message, kind, details } = JSON.parse(error.message.slice("ERR_TRANSLATION: ".length));
+ throw new TranslationError(message, kind, details);
+ }
+ if (error instanceof Error && error.message.startsWith("ERR_INVALID_REQUEST: ")) {
+ throw Object.assign(new Error(error.message.slice("ERR_INVALID_REQUEST: ".length)), { code: "ERR_INVALID_REQUEST" });
+ }
+ throw error;
+ }
+ }
+}
diff --git a/bindings/typescript/test/translation.test.mjs b/bindings/typescript/test/translation.test.mjs
new file mode 100644
index 000000000..263962991
--- /dev/null
+++ b/bindings/typescript/test/translation.test.mjs
@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { TranslationEngine, TranslationError, WireFormat } from "../dist/index.js";
+
+const requests = {
+ openai_chat: { model: "example", messages: [{ role: "user", content: "Hello" }], max_completion_tokens: 64 },
+ openai_responses: { model: "example", input: "Hello", max_output_tokens: 64 },
+ anthropic_messages: { model: "example", messages: [{ role: "user", content: "Hello" }], max_tokens: 64 },
+};
+const responses = {
+ openai_chat: {
+ id: "response-1", model: "example",
+ choices: [{ message: { role: "assistant", content: "Hello" }, finish_reason: "stop" }],
+ },
+ openai_responses: {
+ id: "response-1", model: "example", status: "completed",
+ output: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "Hello" }] }],
+ },
+ anthropic_messages: {
+ id: "response-1", model: "example", type: "message", role: "assistant",
+ content: [{ type: "text", text: "Hello" }], stop_reason: "end_turn",
+ },
+};
+
+test("buffered methods accept plain JSON objects across the three formats", () => {
+ const engine = new TranslationEngine();
+ const formats = Object.values(WireFormat);
+ for (const [index, format] of formats.entries()) {
+ const request = engine.decodeRequest(format, requests[format]);
+ const response = engine.decodeResponse(format, responses[format]);
+ assert.deepEqual([request.diagnostics, response.diagnostics], [[], []]);
+ assert.deepEqual(engine.encodeRequest(format, JSON.parse(JSON.stringify(request.request))), {
+ body: requests[format], diagnostics: [],
+ });
+ assert.deepEqual(engine.encodeResponse(format, JSON.parse(JSON.stringify(response.response))), {
+ body: responses[format], diagnostics: [],
+ });
+ const target = formats[(index + 1) % formats.length];
+ const translatedRequest = engine.translateRequest(format, target, requests[format]);
+ const translatedResponse = engine.translateResponse(format, target, responses[format]);
+ assert.deepEqual([translatedRequest.diagnostics, translatedResponse.diagnostics], [[], []]);
+ assert.equal(engine.decodeRequest(target, translatedRequest.body).request.messages[0].content[0].text, "Hello");
+ assert.equal(engine.decodeResponse(target, translatedResponse.body).response.outputs[0].content[0].text, "Hello");
+ }
+});
+
+test("response encoding and translation restore request tool extensions only when supplied", () => {
+ const engine = new TranslationEngine();
+ const { request } = engine.decodeRequest(WireFormat.OPENAI_RESPONSES, {
+ input: "Search documentation and list files",
+ tools: [{ type: "namespace", name: "mcp__docs", tools: [{ type: "function", name: "search", parameters: {} }] }],
+ });
+ const wireResponse = {
+ id: "response-1", model: "example", choices: [{ message: {
+ role: "assistant", tool_calls: [
+ { id: "call-1", type: "function", function: { name: "mcp__docs__search", arguments: '{"query":"streaming"}' } },
+ ],
+ }, finish_reason: "tool_calls" }],
+ };
+ const { response } = engine.decodeResponse(WireFormat.OPENAI_CHAT, wireResponse);
+ for (const convert of [
+ (...extensions) => engine.encodeResponse(WireFormat.OPENAI_RESPONSES, response, ...extensions),
+ (...extensions) => engine.translateResponse(WireFormat.OPENAI_CHAT, WireFormat.OPENAI_RESPONSES, wireResponse, ...extensions),
+ ]) {
+ const plain = convert();
+ assert.equal(plain.body.output[0].name, "mcp__docs__search");
+ assert.equal(plain.body.output[0].namespace, undefined);
+ const restored = convert(JSON.parse(JSON.stringify(request.extensions)));
+ assert.deepEqual(restored.diagnostics, []);
+ const [search] = restored.body.output;
+ assert.equal(search.name, "search");
+ assert.equal(search.namespace, "mcp__docs");
+ for (const extensions of [undefined, null, {}]) assert.deepEqual(convert(extensions), plain);
+ assert.deepEqual(convert(), plain);
+ }
+});
+
+test("diagnostics and structured translation errors match the Python boundary", () => {
+ const engine = new TranslationEngine();
+ assert.deepEqual(engine.translateRequest(WireFormat.OPENAI_CHAT, WireFormat.ANTHROPIC_MESSAGES, {
+ model: "example", messages: [42],
+ }).diagnostics, [{
+ severity: "Warning", code: "lossy_conversion", message: "OpenAI message at index 0 is not an object",
+ source: "openai_chat", target: "anthropic_messages", path: null,
+ }]);
+ assert.throws(() => engine.translateRequest(WireFormat.OPENAI_CHAT, WireFormat.OPENAI_RESPONSES, {
+ messages: {},
+ }), (error) => {
+ assert.ok(error instanceof TranslationError);
+ assert.equal(error.message, "expected array at $.messages");
+ assert.equal(error.kind, "InvalidType");
+ assert.deepEqual(error.details, { path: "$.messages", expected: "array" });
+ return true;
+ });
+ assert.throws(() => engine.decodeRequest(WireFormat.OPENAI_CHAT, "{}"), TypeError);
+ assert.throws(() => engine.encodeRequest(WireFormat.OPENAI_CHAT, { messages: "not a list" }), { code: "ERR_INVALID_REQUEST" });
+});
diff --git a/crates/switchyard-node/src/lib.rs b/crates/switchyard-node/src/lib.rs
index 94c632782..af8a6d152 100644
--- a/crates/switchyard-node/src/lib.rs
+++ b/crates/switchyard-node/src/lib.rs
@@ -1,7 +1,9 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
-//! Composite routing with caller-owned decision calls and state.
+//! Node bindings for composite routing and buffered JSON translation.
+
+mod translation;
use std::future::ready;
use std::sync::Arc;
diff --git a/crates/switchyard-node/src/translation.rs b/crates/switchyard-node/src/translation.rs
new file mode 100644
index 000000000..1cc34cb73
--- /dev/null
+++ b/crates/switchyard-node/src/translation.rs
@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Buffered provider JSON translation using the default translation policy.
+
+use napi_derive::napi;
+use serde_json::{Value, json};
+use switchyard_translation::{
+ AggLlmResponse, LlmRequest, ProviderExtensions, TranslationEngine, TranslationError,
+ TranslationOutput, TranslationPolicy,
+};
+
+use crate::{error, parse};
+
+#[napi]
+#[derive(Default)]
+pub struct NativeTranslationEngine {
+ inner: TranslationEngine,
+ policy: TranslationPolicy,
+}
+
+#[napi]
+impl NativeTranslationEngine {
+ #[napi(constructor)]
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ #[napi]
+ pub fn decode_request(&self, source: String, body_json: String) -> napi::Result<String> {
+ let body: Value = parse(&body_json)?;
+ let output = self
+ .inner
+ .decode_request(source.as_str(), &body, &self.policy)
+ .map_err(translation_error)?;
+ Ok(json!({"request": output.request, "diagnostics": output.diagnostics}).to_string())
+ }
+
+ #[napi]
+ pub fn encode_request(&self, target: String, request_json: String) -> napi::Result<String> {
+ let request: LlmRequest = parse(&request_json)?;
+ translation_output(
+ self.inner
+ .encode_request(target.as_str(), &request, &self.policy),
+ )
+ }
+
+ #[napi]
+ pub fn decode_response(&self, source: String, body_json: String) -> napi::Result<String> {
+ let body: Value = parse(&body_json)?;
+ let output = self
+ .inner
+ .decode_response(source.as_str(), &body, &self.policy)
+ .map_err(translation_error)?;
+ Ok(json!({"response": output.response, "diagnostics": output.diagnostics}).to_string())
+ }
+
+ #[napi]
+ pub fn encode_response(
+ &self,
+ target: String,
+ response_json: String,
+ request_extensions_json: Option<String>,
+ ) -> napi::Result<String> {
+ let response: AggLlmResponse = parse(&response_json)?;
+ let extensions: ProviderExtensions = request_extensions_json
+ .as_deref()
+ .map(parse)
+ .transpose()?
+ .unwrap_or_default();
+ translation_output(self.inner.encode_response_with_extensions(
+ target.as_str(),
+ &response,
+ &extensions,
+ &self.policy,
+ ))
+ }
+
+ #[napi]
+ pub fn translate_request(
+ &self,
+ source: String,
+ target: String,
+ body_json: String,
+ ) -> napi::Result<String> {
+ let body: Value = parse(&body_json)?;
+ translation_output(self.inner.translate_request(
+ source.as_str(),
+ target.as_str(),
+ &body,
+ &self.policy,
+ ))
+ }
+
+ #[napi]
+ pub fn translate_response(
+ &self,
+ source: String,
+ target: String,
+ body_json: String,
+ request_extensions_json: Option<String>,
+ ) -> napi::Result<String> {
+ let body: Value = parse(&body_json)?;
+ let extensions: ProviderExtensions = request_extensions_json
+ .as_deref()
+ .map(parse)
+ .transpose()?
+ .unwrap_or_default();
+ translation_output(self.inner.translate_response_with_extensions(
+ source.as_str(),
+ target.as_str(),
+ &body,
+ &extensions,
+ &self.policy,
+ ))
+ }
+}
+
+fn translation_output(result: Result<TranslationOutput, TranslationError>) -> napi::Result<String> {
+ let output = result.map_err(translation_error)?;
+ Ok(json!({"body": output.body, "diagnostics": output.diagnostics}).to_string())
+}
+
+fn translation_error(cause: TranslationError) -> napi::Error {
+ let details = match &cause {
+ TranslationError::InvalidJson(error) => json!({
+ "message": error.to_string(),
+ "line": error.line(),
+ "column": error.column(),
+ }),
+ TranslationError::InvalidType { path, expected } => {
+ json!({"path": path, "expected": expected})
+ }
+ TranslationError::UnsupportedTranslation { from, to } => json!({"from": from, "to": to}),
+ TranslationError::LossyConversion(message) | TranslationError::Other(message) => {
+ json!({"message": message})
+ }
+ TranslationError::UnknownField { path } => json!({"path": path}),
+ TranslationError::InvalidValue { path, message } => {
+ json!({"path": path, "message": message})
+ }
+ TranslationError::UpstreamFailure { error } => json!({"error": error}),
+ };
+ error(
+ "ERR_TRANSLATION",
+ json!({"message": cause.to_string(), "kind": cause.kind(), "details": details}),
+ )
+}