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.mdindex 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 toit. 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 theAn aborted signal closes the Rust run and rejects promptly, including while`decide` is pending. Late callback results are ignored. Pass the same signal toyour 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.tsindex 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.rsindex 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.rsnew file mode 100644index 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}),+ )+}