Skip to main content

switchyard_translation/
util.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Shared helpers for codec validation, diagnostics, and preservation metadata.
5
6use std::collections::BTreeMap;
7
8use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
9use serde_json::{Map, Value, json};
10use switchyard_protocol::ModelId;
11
12use crate::diagnostic::TranslationDiagnostic;
13use crate::error::{Result, TranslationError};
14use crate::format::{FormatId, WireFormat};
15use crate::llm::{ContentBlock, LlmRequest, Message, PreservationMetadata};
16use crate::policy::{LossyConversionPolicy, PreservationPolicy, TranslationPolicy};
17
18/// Metadata key used to embed exact preserved payloads in provider JSON.
19pub const SWITCHYARD_METADATA_KEY: &str = "_switchyard_translation";
20/// Public alias for the embedded preservation metadata key.
21pub const PRESERVATION_METADATA_KEY: &str = SWITCHYARD_METADATA_KEY;
22
23const ANTHROPIC_TOOL_ID_ENCODING_PREFIX: &str = "sy64_";
24
25/// Reads a JSON object or returns a typed translation error at the given path.
26pub fn object<'a>(value: &'a Value, path: &str) -> Result<&'a Map<String, Value>> {
27    value
28        .as_object()
29        .ok_or_else(|| TranslationError::InvalidType {
30            path: path.to_string(),
31            expected: "object",
32        })
33}
34
35/// Converts JSON scalars to Python-compatible string values where providers do so.
36pub fn string_value(value: &Value) -> Option<String> {
37    match value {
38        Value::String(text) => Some(text.clone()),
39        Value::Null => None,
40        other => Some(match other {
41            Value::Bool(value) => {
42                if *value {
43                    "True".to_string()
44                } else {
45                    "False".to_string()
46                }
47            }
48            _ => other.to_string(),
49        }),
50    }
51}
52
53/// Applies the lossy-conversion policy and records diagnostics when configured.
54pub fn push_lossy(
55    diagnostics: &mut Vec<TranslationDiagnostic>,
56    policy: &TranslationPolicy,
57    message: impl Into<String>,
58) -> Result<()> {
59    let message = message.into();
60    match policy.lossy_conversion_policy {
61        LossyConversionPolicy::AllowWithDiagnostics => {
62            diagnostics.push(TranslationDiagnostic::warning("lossy_conversion", message));
63            Ok(())
64        }
65        LossyConversionPolicy::Reject => Err(TranslationError::LossyConversion(message)),
66    }
67}
68
69// These Responses history items are valid only as top-level `input` items.
70pub(crate) fn is_responses_native_input_item(item: &Value) -> bool {
71    matches!(
72        item.get("type").and_then(Value::as_str),
73        Some(
74            "apply_patch_call"
75                | "apply_patch_call_output"
76                | "shell_call"
77                | "shell_call_output"
78                | "computer_call"
79                | "computer_call_output"
80                | "image_generation_call"
81                | "compaction_trigger"
82        )
83    )
84}
85
86// Prevent provider-specific input from being downgraded to target-visible prose.
87pub(crate) fn reject_responses_native_input_item(
88    provider: &FormatId,
89    item: &Value,
90    target: WireFormat,
91) -> Result<()> {
92    if provider.as_str() == WireFormat::OpenAiResponses.as_str()
93        && is_responses_native_input_item(item)
94    {
95        return Err(TranslationError::UnsupportedTranslation {
96            from: WireFormat::OpenAiResponses.into(),
97            to: target.into(),
98        });
99    }
100    Ok(())
101}
102
103/// Generates a stable, human-readable ID from a prefix and counter.
104pub fn stable_id(prefix: &str, counter: usize) -> String {
105    format!("{prefix}_{counter:08}")
106}
107
108/// Serializes JSON values into provider argument strings.
109pub fn json_string(value: &Value) -> String {
110    match value {
111        Value::String(text) => text.clone(),
112        other => serde_json::to_string(other).unwrap_or_else(|_| other.to_string()),
113    }
114}
115
116/// Checks a request against declared target capabilities.
117pub fn validate_request_capabilities(
118    request: &LlmRequest,
119    diagnostics: &mut Vec<TranslationDiagnostic>,
120    policy: &TranslationPolicy,
121) -> Result<()> {
122    if policy.target_capabilities.supports_tools == Some(false)
123        && (!request.tools.is_empty() || messages_have_tools(&request.messages))
124    {
125        push_lossy(
126            diagnostics,
127            policy,
128            "target format/profile does not support tools",
129        )?;
130    }
131    if policy.target_capabilities.supports_images == Some(false)
132        && messages_have_block(&request.messages, |block| {
133            matches!(block, ContentBlock::Image { .. })
134        })
135    {
136        push_lossy(
137            diagnostics,
138            policy,
139            "target format/profile does not support images",
140        )?;
141    }
142    if policy.target_capabilities.supports_audio == Some(false)
143        && messages_have_block(&request.messages, |block| {
144            matches!(block, ContentBlock::Audio { .. })
145        })
146    {
147        push_lossy(
148            diagnostics,
149            policy,
150            "target format/profile does not support audio",
151        )?;
152    }
153    if policy.target_capabilities.supports_video == Some(false)
154        && messages_have_block(&request.messages, |block| {
155            matches!(block, ContentBlock::Video { .. })
156        })
157    {
158        push_lossy(
159            diagnostics,
160            policy,
161            "target format/profile does not support video",
162        )?;
163    }
164    if policy.target_capabilities.supports_files == Some(false)
165        && messages_have_block(&request.messages, |block| {
166            matches!(block, ContentBlock::File { .. })
167        })
168    {
169        push_lossy(
170            diagnostics,
171            policy,
172            "target format/profile does not support files",
173        )?;
174    }
175    if policy.target_capabilities.supports_reasoning_effort == Some(false)
176        && request.reasoning.effort.is_some()
177    {
178        push_lossy(
179            diagnostics,
180            policy,
181            "target format/profile does not support reasoning effort",
182        )?;
183    }
184    if policy
185        .target_capabilities
186        .supports_json_schema_response_format
187        == Some(false)
188        && request.output.response_format.is_some()
189    {
190        push_lossy(
191            diagnostics,
192            policy,
193            "target format/profile does not support structured response formats",
194        )?;
195    }
196    Ok(())
197}
198
199// Detects whether any message carries tool calls or tool results.
200fn messages_have_tools(messages: &[Message]) -> bool {
201    messages_have_block(messages, |block| {
202        matches!(
203            block,
204            ContentBlock::ToolCall(_) | ContentBlock::ToolResult(_)
205        )
206    })
207}
208
209// Scans message content for a caller-provided block predicate.
210fn messages_have_block(
211    messages: &[Message],
212    mut predicate: impl FnMut(&ContentBlock) -> bool,
213) -> bool {
214    messages
215        .iter()
216        .any(|message| content_has_block(&message.content, &mut predicate))
217}
218
219// Scans content recursively because tool results can contain media blocks.
220fn content_has_block(
221    content: &[ContentBlock],
222    predicate: &mut impl FnMut(&ContentBlock) -> bool,
223) -> bool {
224    content.iter().any(|block| {
225        predicate(block)
226            || match block {
227                ContentBlock::ToolResult(result) => content_has_block(&result.content, predicate),
228                _ => false,
229            }
230    })
231}
232
233/// Captures an exact source request body according to preservation policy.
234pub fn capture_request_preservation(
235    format: impl Into<FormatId>,
236    body: &Value,
237    policy: &TranslationPolicy,
238) -> PreservationMetadata {
239    let mut preservation = extract_preservation(body);
240    if policy.preservation != PreservationPolicy::Disabled {
241        preservation.requests.insert(format.into(), body.clone());
242    }
243    preservation
244}
245
246/// Captures an exact source response body according to preservation policy.
247pub fn capture_response_preservation(
248    format: impl Into<FormatId>,
249    body: &Value,
250    policy: &TranslationPolicy,
251) -> PreservationMetadata {
252    let mut preservation = extract_preservation(body);
253    if policy.preservation != PreservationPolicy::Disabled {
254        preservation.responses.insert(format.into(), body.clone());
255    }
256    preservation
257}
258
259/// Returns an exact preserved request for the target format when available.
260pub fn exact_preserved_request(
261    preservation: &PreservationMetadata,
262    format: impl Into<FormatId>,
263    policy: &TranslationPolicy,
264) -> Option<Value> {
265    let format = format.into();
266    (policy.preservation != PreservationPolicy::Disabled)
267        .then(|| preservation.requests.get(&format).cloned())
268        .flatten()
269}
270
271/// Returns an exact preserved response for the target format when available.
272pub fn exact_preserved_response(
273    preservation: &PreservationMetadata,
274    format: impl Into<FormatId>,
275    policy: &TranslationPolicy,
276) -> Option<Value> {
277    let format = format.into();
278    (policy.preservation != PreservationPolicy::Disabled)
279        .then(|| preservation.responses.get(&format).cloned())
280        .flatten()
281}
282
283/// Applies a selected target model and optionally prepends its system prompt.
284///
285/// Preserved built-in bodies are updated in their native format when possible so exact replay
286/// keeps caller fields that are not represented in the normalized request.
287/// Call this once per candidate using a request that has not already received a target prompt.
288pub fn prepare_request_for_target(
289    request: &mut LlmRequest,
290    target: &ModelId,
291    prompt: Option<&str>,
292) {
293    let target = target.to_string();
294    request.model = Some(target.clone());
295    if let Some(prompt) = prompt {
296        crate::prepend_system_prompt(request, prompt);
297    }
298    request.preservation.requests.retain(|format, body| {
299        if ![
300            WireFormat::OpenAiChat.as_str(),
301            WireFormat::OpenAiResponses.as_str(),
302            WireFormat::AnthropicMessages.as_str(),
303        ]
304        .contains(&format.as_str())
305        {
306            return false;
307        }
308        let Some(body) = body.as_object_mut() else {
309            return false;
310        };
311        body.insert("model".to_string(), Value::String(target.clone()));
312        true
313    });
314}
315
316/// Embeds preservation metadata into a translated wire body when requested.
317pub fn embed_preservation(
318    mut body: Value,
319    preservation: &PreservationMetadata,
320    policy: &TranslationPolicy,
321) -> Value {
322    if policy.preservation != PreservationPolicy::Embed {
323        return body;
324    }
325    let Ok(envelope) = serde_json::to_value(preservation) else {
326        return body;
327    };
328    let metadata = json!({SWITCHYARD_METADATA_KEY: envelope});
329    if let Some(object) = body.as_object_mut() {
330        match object.get_mut("metadata") {
331            Some(Value::Object(existing)) => {
332                existing.insert(
333                    SWITCHYARD_METADATA_KEY.to_string(),
334                    metadata[SWITCHYARD_METADATA_KEY].clone(),
335                );
336            }
337            _ => {
338                object.insert("metadata".to_string(), metadata);
339            }
340        }
341    }
342    body
343}
344
345/// Extracts embedded preservation metadata from a provider wire body.
346pub fn extract_preservation(body: &Value) -> PreservationMetadata {
347    body.get("metadata")
348        .and_then(Value::as_object)
349        .and_then(|metadata| metadata.get(SWITCHYARD_METADATA_KEY))
350        .cloned()
351        .and_then(|value| serde_json::from_value(value).ok())
352        .unwrap_or_default()
353}
354
355/// Normalizes Anthropic tool-use IDs while keeping tool_use/tool_result pairs aligned.
356pub fn normalize_anthropic_tool_use_ids(value: Value) -> Value {
357    match value {
358        Value::Array(messages) => {
359            let mut id_map = BTreeMap::new();
360            let mut used_ids = BTreeMap::new();
361            Value::Array(
362                messages
363                    .into_iter()
364                    .map(|message| normalize_message_tool_ids(message, &mut id_map, &mut used_ids))
365                    .collect(),
366            )
367        }
368        other => other,
369    }
370}
371
372/// Converts an ID into a reversible Anthropic-safe representation.
373pub fn sanitize_anthropic_tool_use_id(raw: &str) -> String {
374    let is_safe = !raw.is_empty()
375        && raw
376            .bytes()
377            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-');
378    if is_safe && !raw.starts_with(ANTHROPIC_TOOL_ID_ENCODING_PREFIX) {
379        return raw.to_string();
380    }
381
382    format!(
383        "{ANTHROPIC_TOOL_ID_ENCODING_PREFIX}{}",
384        URL_SAFE_NO_PAD.encode(raw.as_bytes())
385    )
386}
387
388/// Restores an ID encoded by [`sanitize_anthropic_tool_use_id`].
389pub(crate) fn desanitize_anthropic_tool_use_id(encoded: &str) -> String {
390    let Some(payload) = encoded.strip_prefix(ANTHROPIC_TOOL_ID_ENCODING_PREFIX) else {
391        return encoded.to_string();
392    };
393
394    URL_SAFE_NO_PAD
395        .decode(payload)
396        .ok()
397        .and_then(|bytes| String::from_utf8(bytes).ok())
398        .unwrap_or_else(|| encoded.to_string())
399}
400
401// Normalizes every content block in one Anthropic message.
402fn normalize_message_tool_ids(
403    message: Value,
404    id_map: &mut BTreeMap<String, String>,
405    used_ids: &mut BTreeMap<String, String>,
406) -> Value {
407    let Value::Object(mut message) = message else {
408        return message;
409    };
410    let Some(content_value) = message.remove("content") else {
411        return Value::Object(message);
412    };
413    let Value::Array(content) = content_value else {
414        message.insert("content".to_string(), content_value);
415        return Value::Object(message);
416    };
417    let normalized = content
418        .into_iter()
419        .map(|block| normalize_tool_block(block, id_map, used_ids).unwrap_or_else(|block| block))
420        .collect::<Vec<_>>();
421    message.insert("content".to_string(), Value::Array(normalized));
422    Value::Object(message)
423}
424
425// Rewrites tool_use/tool_result IDs and leaves unrelated blocks untouched.
426fn normalize_tool_block(
427    block: Value,
428    id_map: &mut BTreeMap<String, String>,
429    used_ids: &mut BTreeMap<String, String>,
430) -> std::result::Result<Value, Value> {
431    let Value::Object(mut block_map) = block else {
432        return Err(block);
433    };
434    match block_map.get("type").and_then(Value::as_str) {
435        Some("tool_use") => {
436            let raw = block_map
437                .get("id")
438                .and_then(Value::as_str)
439                .unwrap_or_default()
440                .to_string();
441            let normalized = mapped_tool_id(&raw, id_map, used_ids);
442            if normalized != raw {
443                block_map.insert("id".to_string(), Value::String(normalized));
444                Ok(Value::Object(block_map))
445            } else {
446                Err(Value::Object(block_map))
447            }
448        }
449        Some("tool_result") => {
450            let raw = block_map
451                .get("tool_use_id")
452                .and_then(Value::as_str)
453                .unwrap_or_default()
454                .to_string();
455            let normalized = mapped_tool_id(&raw, id_map, used_ids);
456            if normalized != raw {
457                block_map.insert("tool_use_id".to_string(), Value::String(normalized));
458                Ok(Value::Object(block_map))
459            } else {
460                Err(Value::Object(block_map))
461            }
462        }
463        _ => Err(Value::Object(block_map)),
464    }
465}
466
467// Gives colliding raw IDs stable, deterministic suffixes.
468fn mapped_tool_id(
469    raw: &str,
470    id_map: &mut BTreeMap<String, String>,
471    used_ids: &mut BTreeMap<String, String>,
472) -> String {
473    if let Some(existing) = id_map.get(raw) {
474        return existing.clone();
475    }
476    let mut candidate = sanitize_anthropic_tool_use_id(raw);
477    if let Some(owner) = used_ids.get(&candidate)
478        && owner != raw
479    {
480        candidate = format!("{}_{}", candidate, stable_suffix(raw));
481    }
482    id_map.insert(raw.to_string(), candidate.clone());
483    used_ids.insert(candidate.clone(), raw.to_string());
484    candidate
485}
486
487// Stable FNV-1a suffix for collision disambiguation.
488fn stable_suffix(raw: &str) -> String {
489    let mut hash: u64 = 1469598103934665603;
490    for byte in raw.as_bytes() {
491        hash ^= u64::from(*byte);
492        hash = hash.wrapping_mul(1099511628211);
493    }
494    format!("{hash:08x}")
495}
496
497#[cfg(test)]
498mod tests {
499    use super::{desanitize_anthropic_tool_use_id, sanitize_anthropic_tool_use_id};
500
501    // Keeps ordinary provider IDs unchanged while making unsafe IDs reversible.
502    #[test]
503    fn anthropic_tool_id_encoding_round_trips() {
504        assert_eq!(
505            sanitize_anthropic_tool_use_id("call_abc-123"),
506            "call_abc-123"
507        );
508
509        for raw in ["", "functions.list_skills:0", "工具/lookup"] {
510            let encoded = sanitize_anthropic_tool_use_id(raw);
511            assert!(
512                encoded
513                    .bytes()
514                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-')
515            );
516            assert_eq!(desanitize_anthropic_tool_use_id(&encoded), raw);
517        }
518    }
519
520    // Escapes the reserved prefix and leaves malformed encoded values untouched.
521    #[test]
522    fn anthropic_tool_id_encoding_disambiguates_its_prefix() {
523        let raw = "sy64_Zm9v";
524        let encoded = sanitize_anthropic_tool_use_id(raw);
525        assert_ne!(encoded, raw);
526        assert_eq!(desanitize_anthropic_tool_use_id(&encoded), raw);
527        assert_eq!(desanitize_anthropic_tool_use_id("sy64_%%%"), "sy64_%%%");
528    }
529}