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
fix(translation): preserve URL citations between Chat and Responses (#730)
Graham King1ec9277173ac
diff --git a/crates/libsy/src/algorithms/advisor_gate/signals.rs b/crates/libsy/src/algorithms/advisor_gate/signals.rsindex 95f7549d1..9cb36f477 100644--- a/crates/libsy/src/algorithms/advisor_gate/signals.rs+++ b/crates/libsy/src/algorithms/advisor_gate/signals.rs@@ -89,6 +89,7 @@ mod tests {fn tool_call_agg() -> AggLlmResponse {AggLlmResponse {outputs: vec![ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::Text {diff --git a/crates/libsy/src/algorithms/advisor_gate/tests.rs b/crates/libsy/src/algorithms/advisor_gate/tests.rsindex a4f771fcb..72d39615b 100644--- a/crates/libsy/src/algorithms/advisor_gate/tests.rs+++ b/crates/libsy/src/algorithms/advisor_gate/tests.rs@@ -90,6 +90,7 @@ fn tool_call_turn() -> Response {name: "bash".to_string(),arguments: serde_json::json!({}),})],+ url_citations: Vec::new(),stop_reason: None,}],..AggLlmResponse::default()@@ -107,6 +108,7 @@ fn tool_use_stop_turn() -> Response {content: vec![ContentBlock::Text {text: "calling a tool".to_string(),}],+ url_citations: Vec::new(),stop_reason: Some(StopReason::ToolUse),}],..AggLlmResponse::default()@@ -126,6 +128,7 @@ fn reasoning_only_turn() -> Response {signature: None,details: Vec::new(),}],+ url_citations: Vec::new(),stop_reason: None,}],..AggLlmResponse::default()@@ -141,6 +144,7 @@ fn empty_turn() -> Response {outputs: vec![ResponseOutput {role: Role::Assistant,content: Vec::new(),+ url_citations: Vec::new(),stop_reason: None,}],..AggLlmResponse::default()@@ -837,6 +841,7 @@ async fn pattern_trigger_matches_on_tool_call_turns() {arguments: serde_json::json!({}),}),],+ url_citations: Vec::new(),stop_reason: Some(StopReason::ToolUse),}],..AggLlmResponse::default()diff --git a/crates/libsy/src/algorithms/noop.rs b/crates/libsy/src/algorithms/noop.rsindex 8ea0defea..4963b5b19 100644--- a/crates/libsy/src/algorithms/noop.rs+++ b/crates/libsy/src/algorithms/noop.rs@@ -32,6 +32,7 @@ impl Algorithm for Noop {id: Some("switchyard-noop".to_string()),model: Some(model_id.to_string()),outputs: vec![ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::Text {text: "OK".to_string(),diff --git a/crates/protocol/src/lib.rs b/crates/protocol/src/lib.rsindex fcf2b3782..663968ceb 100644--- a/crates/protocol/src/lib.rs+++ b/crates/protocol/src/lib.rs@@ -56,6 +56,7 @@ pub fn text_response(model: Option<String>, completion: impl Into<String>) -> AgAggLlmResponse {model,outputs: vec![ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::Text {text: completion.into(),diff --git a/crates/protocol/src/llm.rs b/crates/protocol/src/llm.rsindex 78a101f8e..7968faa85 100644--- a/crates/protocol/src/llm.rs+++ b/crates/protocol/src/llm.rs@@ -424,6 +424,19 @@ pub enum StopReason {Unknown,}+/// A source URL cited by generated text.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+pub struct UrlCitation {+ /// Start character offset in the concatenated text and refusal blocks.+ pub start_index: usize,+ /// Exclusive end character offset in the same text.+ pub end_index: usize,+ /// Source URL.+ pub url: String,+ /// Source title.+ pub title: String,+}+/// One assistant output item in a normalized response.#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]pub struct ResponseOutput {@@ -431,6 +444,9 @@ pub struct ResponseOutput {pub role: Role,/// Ordered output content.pub content: Vec<ContentBlock>,+ /// URL citations in the concatenated text and refusal blocks.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub url_citations: Vec<UrlCitation>,/// Why this output stopped, when known.pub stop_reason: Option<StopReason>,}diff --git a/crates/protocol/src/stream.rs b/crates/protocol/src/stream.rsindex e5152b52f..37bf123c8 100644--- a/crates/protocol/src/stream.rs+++ b/crates/protocol/src/stream.rs@@ -482,6 +482,7 @@ impl ResponseAccumulator {outputs: vec![ResponseOutput {role: Role::Assistant,content,+ url_citations: Vec::new(),stop_reason: self.stop_reason,}],usage: self.usage,@@ -702,6 +703,7 @@ mod tests {content: vec![ContentBlock::Text {text: "hello".to_string(),}],+ url_citations: Vec::new(),stop_reason: Some(StopReason::EndTurn),}],usage: Usage {@@ -736,6 +738,7 @@ mod tests {signature: None,details: details.clone(),}],+ url_citations: Vec::new(),stop_reason: Some(StopReason::EndTurn),}],..AggLlmResponse::default()diff --git a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs b/crates/switchyard-translation/src/codecs/anthropic/buffered.rsindex 2421cc4e6..6c68bf4b9 100644--- a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs+++ b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs@@ -318,6 +318,7 @@ impl FormatCodec for AnthropicMessagesCodec {.and_then(Value::as_str).map(ToOwned::to_owned),outputs: vec![ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content,stop_reason: Some(map_anthropic_stop_reason(diff --git a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rsindex bdbd4b60a..8793fc4dc 100644--- a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs+++ b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs@@ -307,6 +307,16 @@ impl FormatCodec for OpenAiChatCodec {}}response.outputs.push(ResponseOutput {+ url_citations: message+ .get("annotations")+ .and_then(Value::as_array)+ .into_iter()+ .flatten()+ .filter(|annotation| annotation["type"] == "url_citation")+ .filter_map(|annotation| {+ serde_json::from_value(annotation["url_citation"].clone()).ok()+ })+ .collect(),role: Role::Assistant,content,stop_reason: Some(map_openai_finish_reason(@@ -365,6 +375,15 @@ impl FormatCodec for OpenAiChatCodec {Value::String(content)},});+ if let Some(output) = output.filter(|output| !output.url_citations.is_empty()) {+ message["annotations"] = Value::Array(+ output+ .url_citations+ .iter()+ .map(|citation| json!({"type": "url_citation", "url_citation": citation}))+ .collect(),+ );+ }if let Some(reasoning) = output.map(|output| reasoning_text_from_blocks(&output.content, "\n")).filter(|reasoning| !reasoning.is_empty())diff --git a/crates/switchyard-translation/src/codecs/responses/buffered.rs b/crates/switchyard-translation/src/codecs/responses/buffered.rsindex 07c763c9d..2c5440abb 100644--- a/crates/switchyard-translation/src/codecs/responses/buffered.rs+++ b/crates/switchyard-translation/src/codecs/responses/buffered.rs@@ -294,12 +294,29 @@ impl FormatCodec for OpenAiResponsesCodec {let mut role = Role::Assistant;let mut stop_reason = None;let mut has_output = false;+ let mut url_citations = Vec::new();+ let mut text_offset = 0;if let Some(items) = body.get("output").and_then(Value::as_array) {for item in items {if let Some(output) = decode_responses_output_item(item, &mut diagnostics, policy)?{has_output = true;role = output.role;+ for mut citation in output.url_citations {+ citation.start_index += text_offset;+ citation.end_index += text_offset;+ url_citations.push(citation);+ }+ text_offset += output+ .content+ .iter()+ .map(|block| match block {+ ContentBlock::Text { text } | ContentBlock::Refusal { text } => {+ text.chars().count()+ }+ _ => 0,+ })+ .sum::<usize>();content.extend(output.content);if output.stop_reason.is_some() {stop_reason = output.stop_reason;@@ -319,12 +336,14 @@ impl FormatCodec for OpenAiResponsesCodec {}let outputs = vec![if has_output {ResponseOutput {+ url_citations,role,content,stop_reason,}} else {ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::Text {text: String::new(),@@ -1660,11 +1679,13 @@ fn decode_responses_output_item(};match item.get("type").and_then(Value::as_str) {Some("message") => Ok(Some(ResponseOutput {+ url_citations: decode_responses_url_citations(item.get("content")),role: role_from_responses(item.get("role").and_then(Value::as_str)),content: decode_responses_content(item.get("content").unwrap_or(&Value::Null)),stop_reason: Some(StopReason::EndTurn),})),Some("function_call") => Ok(Some(ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::ToolCall(ToolCall {id: item@@ -1682,6 +1703,7 @@ fn decode_responses_output_item(stop_reason: Some(StopReason::ToolUse),})),Some("custom_tool_call") => Ok(Some(ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![ContentBlock::ToolCall(ToolCall {id: item@@ -1702,6 +1724,7 @@ fn decode_responses_output_item(stop_reason: Some(StopReason::ToolUse),})),Some("reasoning") => Ok(Some(ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: decode_responses_reasoning_item(item),stop_reason: None,@@ -1710,6 +1733,39 @@ fn decode_responses_output_item(}}+fn decode_responses_url_citations(content: Option<&Value>) -> Vec<crate::UrlCitation> {+ let mut citations = Vec::new();+ let mut text_offset = 0;+ for part in content.and_then(Value::as_array).into_iter().flatten() {+ for annotation in part+ .get("annotations")+ .and_then(Value::as_array)+ .into_iter()+ .flatten()+ {+ if annotation["type"] == "url_citation"+ && let Ok(mut citation) =+ serde_json::from_value::<crate::UrlCitation>(annotation.clone())+ {+ citation.start_index += text_offset;+ citation.end_index += text_offset;+ citations.push(citation);+ }+ }+ let text = match part.get("type").and_then(Value::as_str) {+ Some("input_text" | "output_text" | "text") => part.get("text"),+ Some("refusal") => part.get("refusal"),+ _ => None,+ };+ text_offset += text+ .and_then(Value::as_str)+ .unwrap_or_default()+ .chars()+ .count();+ }+ citations+}+// Encodes normalized response outputs into Responses output items.fn encode_responses_output(outputs: &[ResponseOutput]) -> Value {Value::Array(@@ -1754,7 +1810,13 @@ fn encode_responses_output(outputs: &[ResponseOutput]) -> Value {"content": [{"type": "output_text","text": text,- "annotations": [],+ "annotations": output.url_citations.iter().map(|citation| json!({+ "type": "url_citation",+ "start_index": citation.start_index,+ "end_index": citation.end_index,+ "url": citation.url,+ "title": citation.title,+ })).collect::<Vec<_>>(),}],}));}diff --git a/crates/switchyard-translation/tests/extension_points.rs b/crates/switchyard-translation/tests/extension_points.rsindex d7db6f41d..0d78f07d2 100644--- a/crates/switchyard-translation/tests/extension_points.rs+++ b/crates/switchyard-translation/tests/extension_points.rs@@ -213,6 +213,7 @@ impl FormatCodec for MinimalCustomCodec {.and_then(Value::as_str).map(ToOwned::to_owned),outputs: vec![ResponseOutput {+ url_citations: Vec::new(),role: Role::Assistant,content: vec![switchyard_translation::ContentBlock::Text {text: bodydiff --git a/crates/switchyard-translation/tests/response_translation.rs b/crates/switchyard-translation/tests/response_translation.rsindex 73b885462..29e81eabb 100644--- a/crates/switchyard-translation/tests/response_translation.rs+++ b/crates/switchyard-translation/tests/response_translation.rs@@ -17,6 +17,88 @@ use common::{type TestResult = std::result::Result<(), Box<dyn std::error::Error + Send + Sync>>;+#[test]+fn url_citations_survive_chat_responses_translation() -> TestResult {+ let engine = TranslationEngine::default();+ let citation = json!({+ "start_index": 13, "end_index": 20,+ "url": "https://example.test/source", "title": "Example"+ });+ let chat_annotations = json!([{"type": "url_citation", "url_citation": citation}]);+ let mut flat_citation = citation;+ flat_citation["type"] = json!("url_citation");+ let responses_annotations = json!([flat_citation]);+ let chat = json!({+ "choices": [{"message": {+ "role": "assistant", "content": "According to Example.",+ "annotations": chat_annotations+ }, "finish_reason": "stop"}]+ });+ let responses = json!({+ "status": "completed",+ "output": [{"type": "message", "role": "assistant", "content": [{+ "type": "output_text", "text": "According to Example.",+ "annotations": responses_annotations+ }]}]+ });+ for policy in [TranslationPolicy::default(), normalized_policy()] {+ let output = engine+ .translate_response(+ WireFormat::OpenAiChat,+ WireFormat::OpenAiResponses,+ &chat,+ &policy,+ )?+ .body;+ assert_eq!(+ output["output"][0]["content"][0]["annotations"],+ responses_annotations+ );+ let output = engine+ .translate_response(+ WireFormat::OpenAiResponses,+ WireFormat::OpenAiChat,+ &responses,+ &policy,+ )?+ .body;+ assert_eq!(+ output["choices"][0]["message"]["annotations"],+ chat_annotations+ );++ // Responses text parts and messages are concatenated in Chat.+ let mut multipart = responses.clone();+ multipart["output"][0]["content"]+ .as_array_mut()+ .unwrap()+ .insert(0, json!({"type": "output_text", "text": "🌍 "}));+ multipart["output"].as_array_mut().unwrap().insert(+ 0,+ json!({"type": "message", "role": "assistant", "content": [+ {"type": "output_text", "text": "é"}+ ]}),+ );+ let output = engine+ .translate_response(+ WireFormat::OpenAiResponses,+ WireFormat::OpenAiChat,+ &multipart,+ &policy,+ )?+ .body;+ let mut shifted = chat_annotations.clone();+ shifted[0]["url_citation"]["start_index"] = json!(16);+ shifted[0]["url_citation"]["end_index"] = json!(23);+ assert_eq!(+ output["choices"][0]["message"]["content"],+ "é🌍 According to Example."+ );+ assert_eq!(output["choices"][0]["message"]["annotations"], shifted);+ }+ Ok(())+}+// Verifies OpenAI Chat responses map to Anthropic message responses.#[test]fn openai_chat_response_translates_to_anthropic_message() -> TestResult {