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

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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>) -> Ag
AggLlmResponse {
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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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: body
diff --git a/crates/switchyard-translation/tests/response_translation.rs b/crates/switchyard-translation/tests/response_translation.rs
index 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 {