Skip to main content

switchyard_translation/codecs/openai_chat/
buffered.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Buffered codec for OpenAI Chat Completions request and response JSON.
5
6use serde_json::{Map, Value, json};
7use switchyard_protocol::MAX_IR_TEMPERATURE;
8
9use super::MAX_TEMPERATURE;
10use crate::codecs::common::{
11    first_nonempty_string, is_known_role_name, provider_extensions, reasoning_text_from_blocks,
12    reasoning_text_from_details, scale_temperature, text_from_blocks,
13};
14use crate::codecs::openai_media::{
15    ImagePayload, file_payload, file_source_text, image_payload, image_source_text,
16};
17use crate::codecs::structured_output::{decode_openai_schema_enforcement, encode_openai_format};
18use crate::codecs::{
19    DecodedRequest, DecodedResponse, EncodedRequest, EncodedResponse, FormatCodec,
20};
21use crate::diagnostic::TranslationDiagnostic;
22use crate::error::{Result, TranslationError};
23use crate::format::{FormatId, WireFormat};
24use crate::llm::{
25    AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,
26    MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,
27    SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
28};
29use crate::policy::{DeterministicIdPolicy, TranslationPolicy};
30use crate::util::{
31    capture_request_preservation, capture_response_preservation, embed_preservation,
32    exact_preserved_request, exact_preserved_response, json_string, object, push_lossy,
33    reject_responses_native_input_item, stable_id, string_value, validate_request_capabilities,
34};
35
36/// Format codec for OpenAI Chat Completions payloads.
37pub struct OpenAiChatCodec;
38
39impl FormatCodec for OpenAiChatCodec {
40    fn format(&self) -> FormatId {
41        WireFormat::OpenAiChat.into()
42    }
43
44    fn decode_request(&self, body: &Value, policy: &TranslationPolicy) -> Result<DecodedRequest> {
45        let body = object(body, "$")?;
46        if let Some(n) = body.get("n") {
47            let n = n.as_u64().ok_or_else(|| TranslationError::InvalidValue {
48                path: "$.n".to_string(),
49                message: "expected a non-negative integer".to_string(),
50            })?;
51            if n > 1 {
52                return Err(TranslationError::InvalidValue {
53                    path: "$.n".to_string(),
54                    message: "multiple OpenAI Chat choices are not supported; set `n` to 1"
55                        .to_string(),
56                });
57            }
58        }
59        let mut diagnostics = Vec::new();
60        let mut request = LlmRequest {
61            model: body
62                .get("model")
63                .and_then(Value::as_str)
64                .filter(|model| !model.is_empty())
65                .map(ToOwned::to_owned),
66            stream: body.get("stream").and_then(Value::as_bool).unwrap_or(false),
67            sampling: SamplingParams {
68                temperature: body
69                    .get("temperature")
70                    .and_then(Value::as_f64)
71                    .map(|value| scale_temperature(value, MAX_TEMPERATURE, MAX_IR_TEMPERATURE)),
72                top_p: body.get("top_p").and_then(Value::as_f64),
73                top_k: None,
74            },
75            output: OutputParams {
76                max_output_tokens: body
77                    .get("max_completion_tokens")
78                    .or_else(|| body.get("max_tokens"))
79                    .and_then(Value::as_u64),
80                response_format: body.get("response_format").cloned(),
81                is_schema_enforced: decode_openai_schema_enforcement(body.get("response_format")),
82            },
83            reasoning: ReasoningParams {
84                effort: body
85                    .get("reasoning_effort")
86                    .and_then(Value::as_str)
87                    .map(ToOwned::to_owned),
88                raw: None,
89            },
90            preservation: capture_request_preservation(
91                WireFormat::OpenAiChat,
92                &Value::Object(body.clone()),
93                policy,
94            ),
95            ..LlmRequest::default()
96        };
97
98        if let Some(messages) = body.get("messages") {
99            let messages = messages
100                .as_array()
101                .ok_or_else(|| TranslationError::InvalidType {
102                    path: "$.messages".to_string(),
103                    expected: "array",
104                })?;
105            let mut generated_id = 0;
106            for (index, message) in messages.iter().enumerate() {
107                let Some(message) = message.as_object() else {
108                    push_lossy(
109                        &mut diagnostics,
110                        policy,
111                        format!("OpenAI message at index {index} is not an object"),
112                    )?;
113                    continue;
114                };
115                let role = role_from_openai(
116                    message.get("role").and_then(Value::as_str),
117                    &format!("$.messages[{index}].role"),
118                )?;
119                let mut content = decode_openai_content(
120                    message.get("content").unwrap_or(&Value::Null),
121                    WireFormat::OpenAiChat,
122                    &mut diagnostics,
123                    policy,
124                    format!("$.messages[{index}].content"),
125                )?;
126                prepend_openai_reasoning_blocks(&mut content, message);
127                if role == Role::Assistant
128                    && let Some(tool_calls) = message.get("tool_calls").and_then(Value::as_array)
129                {
130                    if is_empty_text_only(&content) {
131                        content.clear();
132                    }
133                    for tool_call in tool_calls {
134                        generated_id += 1;
135                        if let Some(call) =
136                            decode_openai_tool_call(tool_call, generated_id, policy)?
137                        {
138                            content.push(ContentBlock::ToolCall(call));
139                        }
140                    }
141                }
142                if role == Role::Tool {
143                    let text = content
144                        .iter()
145                        .filter_map(|block| match block {
146                            ContentBlock::Text { text } => Some(text.as_str()),
147                            _ => None,
148                        })
149                        .collect::<Vec<_>>()
150                        .join("\n");
151                    let tool_call_id = message
152                        .get("tool_call_id")
153                        .and_then(Value::as_str)
154                        .unwrap_or_default()
155                        .to_string();
156                    request.messages.push(Message::new(
157                        Role::User,
158                        vec![ContentBlock::ToolResult(ToolResult {
159                            tool_call_id,
160                            content: vec![ContentBlock::Text { text }],
161                            is_error: message.get("is_error").and_then(Value::as_bool),
162                        })],
163                    ));
164                    continue;
165                }
166                // Leading system and developer messages are top-level instructions.
167                // Later ones stay in place as messages.
168                if matches!(role, Role::System | Role::Developer) && request.messages.is_empty() {
169                    request
170                        .instructions
171                        .push(InstructionBlock { role, content });
172                } else {
173                    request.messages.push(Message::new(role, content));
174                }
175            }
176        }
177
178        request.tools = decode_openai_tools(body.get("tools"), &mut diagnostics, policy)?
179            .into_iter()
180            .map(Tool::from)
181            .collect();
182        request.tool_choice = body.get("tool_choice").map(decode_openai_tool_choice);
183        request.extensions.fields = provider_extensions(
184            body,
185            &[
186                "model",
187                "messages",
188                "stream",
189                "temperature",
190                "top_p",
191                "max_completion_tokens",
192                "max_tokens",
193                "response_format",
194                "reasoning_effort",
195                "tools",
196                "tool_choice",
197            ],
198        );
199
200        Ok(DecodedRequest {
201            request,
202            diagnostics,
203        })
204    }
205
206    fn encode_request(
207        &self,
208        request: &LlmRequest,
209        policy: &TranslationPolicy,
210    ) -> Result<EncodedRequest> {
211        if let Some(body) =
212            exact_preserved_request(&request.preservation, WireFormat::OpenAiChat, policy)
213        {
214            return Ok(EncodedRequest {
215                body,
216                diagnostics: Vec::new(),
217            });
218        }
219        let mut diagnostics = Vec::new();
220        validate_request_capabilities(request, &mut diagnostics, policy)?;
221        let allowed = match &request.tool_choice {
222            Some(ToolChoice::Raw(choice))
223                if choice.get("type").and_then(Value::as_str) == Some("allowed_tools")
224                    && choice.get("allowed_tools").is_some() =>
225            {
226                None
227            }
228            _ => crate::codecs::common::allowed_function_tools(request)?,
229        };
230        let (tools, tool_choice) = allowed.as_ref().map_or(
231            (request.tools.as_slice(), request.tool_choice.as_ref()),
232            |(tools, choice)| (tools.as_slice(), Some(choice)),
233        );
234        let mut body = Map::new();
235        if let Some(model) = &request.model {
236            body.insert("model".to_string(), Value::String(model.clone()));
237        }
238
239        let mut messages = Vec::new();
240        for instruction in &request.instructions {
241            let role = match instruction.role {
242                Role::Developer => "developer",
243                _ => "system",
244            };
245            messages.push(json!({
246                "role": role,
247                "content": text_from_blocks(&instruction.content, "\n\n"),
248            }));
249        }
250        for message in &request.messages {
251            messages.extend(encode_message_to_openai(message, &mut diagnostics, policy)?);
252        }
253        body.insert("messages".to_string(), Value::Array(messages));
254
255        if !tools.is_empty() {
256            body.insert("tools".to_string(), encode_openai_tools(tools)?);
257            if let Some(choice) = tool_choice {
258                body.insert("tool_choice".to_string(), encode_openai_tool_choice(choice));
259            }
260        }
261        if let Some(value) = request.output.max_output_tokens {
262            body.insert("max_completion_tokens".to_string(), json!(value));
263        }
264        if let Some(value) = request.sampling.temperature {
265            let value = scale_temperature(value, MAX_IR_TEMPERATURE, MAX_TEMPERATURE);
266            body.insert("temperature".to_string(), json!(value));
267        }
268        if let Some(value) = request.sampling.top_p {
269            body.insert("top_p".to_string(), json!(value));
270        }
271        if request.stream {
272            body.insert("stream".to_string(), Value::Bool(true));
273        }
274        if let Some(effort) = &request.reasoning.effort {
275            body.insert(
276                "reasoning_effort".to_string(),
277                Value::String(effort.clone()),
278            );
279        }
280        if let Some(format) = encode_openai_format(&request.output, &mut diagnostics, policy)? {
281            body.insert("response_format".to_string(), format);
282        }
283        copy_openai_chat_request_extensions(&mut body, &request.extensions.fields);
284
285        let body = embed_preservation(Value::Object(body), &request.preservation, policy);
286        Ok(EncodedRequest { body, diagnostics })
287    }
288
289    fn decode_response(
290        &self,
291        body: &Value,
292        _policy: &TranslationPolicy,
293    ) -> Result<DecodedResponse> {
294        let object = object(body, "$")?;
295        // `abort`, `error` and `repetition` mean the generation did not complete.
296        if let Some(reason @ ("abort" | "error" | "repetition")) = object
297            .get("choices")
298            .and_then(Value::as_array)
299            .and_then(|choices| choices.first())
300            .and_then(|choice| choice.get("finish_reason"))
301            .and_then(Value::as_str)
302        {
303            return Err(TranslationError::UpstreamFailure {
304                error: json!({ "message": format!("provider finished with finish_reason \"{reason}\"") }),
305            });
306        }
307        let mut response = AggLlmResponse {
308            id: object
309                .get("id")
310                .and_then(Value::as_str)
311                .map(ToOwned::to_owned),
312            model: object
313                .get("model")
314                .and_then(Value::as_str)
315                .map(ToOwned::to_owned),
316            outputs: Vec::new(),
317            usage: decode_openai_usage(object.get("usage")),
318            extensions: ProviderExtensions {
319                fields: provider_extensions(object, &["id", "model", "choices", "usage"]),
320            },
321            preservation: capture_response_preservation(
322                WireFormat::OpenAiChat,
323                &Value::Object(object.clone()),
324                _policy,
325            ),
326        };
327        if let Some(choice) = object
328            .get("choices")
329            .and_then(Value::as_array)
330            .and_then(|choices| choices.first())
331            .and_then(Value::as_object)
332        {
333            let message = choice
334                .get("message")
335                .and_then(Value::as_object)
336                .cloned()
337                .unwrap_or_default();
338            let refusal = message
339                .get("refusal")
340                .and_then(Value::as_str)
341                .filter(|text| !text.is_empty());
342            let mut content = match message.get("content") {
343                // decode_openai_content would turn absent response text into an empty text block.
344                None | Some(Value::Null) => Vec::new(),
345                Some(content) => decode_openai_content(
346                    content,
347                    WireFormat::OpenAiChat,
348                    &mut Vec::new(),
349                    &TranslationPolicy::default(),
350                    "$.choices[0].message.content",
351                )?,
352            };
353            prepend_openai_reasoning_blocks(&mut content, &message);
354            if let Some(text) = refusal {
355                content.push(ContentBlock::Refusal {
356                    text: text.to_string(),
357                });
358            }
359            if let Some(tool_calls) = message.get("tool_calls").and_then(Value::as_array) {
360                for (index, tool_call) in tool_calls.iter().enumerate() {
361                    if let Some(call) = decode_openai_tool_call(
362                        tool_call,
363                        index + 1,
364                        &TranslationPolicy::default(),
365                    )? {
366                        content.push(ContentBlock::ToolCall(call));
367                    }
368                }
369            }
370            let finish_reason = choice.get("finish_reason").and_then(Value::as_str);
371            let stop_reason = if refusal.is_some() && matches!(finish_reason, Some("stop") | None) {
372                StopReason::ContentFilter
373            } else {
374                map_openai_finish_reason(finish_reason)
375            };
376            response.outputs.push(ResponseOutput {
377                url_citations: message
378                    .get("annotations")
379                    .and_then(Value::as_array)
380                    .into_iter()
381                    .flatten()
382                    .filter(|annotation| annotation["type"] == "url_citation")
383                    .filter_map(|annotation| {
384                        serde_json::from_value(annotation["url_citation"].clone()).ok()
385                    })
386                    .collect(),
387                role: Role::Assistant,
388                content,
389                stop_reason: Some(stop_reason),
390            });
391        }
392
393        Ok(DecodedResponse {
394            response,
395            diagnostics: Vec::new(),
396        })
397    }
398
399    fn encode_response(
400        &self,
401        response: &AggLlmResponse,
402        _policy: &TranslationPolicy,
403    ) -> Result<EncodedResponse> {
404        super::super::responses::validate_response_output(response, WireFormat::OpenAiChat)?;
405        if let Some(body) =
406            exact_preserved_response(&response.preservation, WireFormat::OpenAiChat, _policy)
407        {
408            return Ok(EncodedResponse {
409                body,
410                diagnostics: Vec::new(),
411            });
412        }
413        let output = response.first_output();
414        let mut content = String::new();
415        let mut refusal = None::<String>;
416        let mut url_citations = output
417            .map(|output| output.url_citations.clone())
418            .unwrap_or_default();
419        let mut content_offset = 0;
420        if let Some(output) = output {
421            for block in &output.content {
422                match block {
423                    ContentBlock::Text { text } => {
424                        content.push_str(text);
425                        content_offset += text.chars().count();
426                    }
427                    ContentBlock::Refusal { text } => {
428                        refusal.get_or_insert_with(String::new).push_str(text);
429                        let refusal_len = text.chars().count();
430                        // IR offsets include refusal text; Chat content excludes it.
431                        for citation in &mut url_citations {
432                            citation.start_index -= refusal_len
433                                .min(citation.start_index.saturating_sub(content_offset));
434                            citation.end_index -=
435                                refusal_len.min(citation.end_index.saturating_sub(content_offset));
436                        }
437                        url_citations.retain(|citation| citation.start_index < citation.end_index);
438                    }
439                    ContentBlock::Unknown { raw, .. } => {
440                        if let Some(text) = raw.as_str() {
441                            content.push_str(text);
442                            content_offset += text.chars().count();
443                        }
444                    }
445                    _ => {}
446                }
447            }
448        }
449        let tool_calls = output
450            .map(|output| {
451                output
452                    .content
453                    .iter()
454                    .filter_map(|block| match block {
455                        ContentBlock::ToolCall(call) => Some(json!({
456                            "id": call.id,
457                            "type": "function",
458                            "function": {
459                                "name": call.name,
460                                "arguments": json_string(&call.arguments),
461                            },
462                        })),
463                        _ => None,
464                    })
465                    .collect::<Vec<_>>()
466            })
467            .unwrap_or_default();
468        let mut message = json!({
469            "role": "assistant",
470            "content": if content.is_empty() && (!tool_calls.is_empty() || refusal.is_some()) {
471                Value::Null
472            } else {
473                Value::String(content)
474            },
475        });
476        if let Some(refusal) = refusal {
477            message["refusal"] = Value::String(refusal);
478        }
479        if !url_citations.is_empty() {
480            message["annotations"] = Value::Array(
481                url_citations
482                    .iter()
483                    .map(|citation| json!({"type": "url_citation", "url_citation": citation}))
484                    .collect(),
485            );
486        }
487        if let Some(reasoning) = output
488            .map(|output| reasoning_text_from_blocks(&output.content, "\n"))
489            .filter(|reasoning| !reasoning.is_empty())
490        {
491            message["reasoning_content"] = Value::String(reasoning);
492        }
493        if let Some(details) = output
494            .map(|output| reasoning_details_from_blocks(&output.content))
495            .filter(|details| !details.is_empty())
496        {
497            message["reasoning_details"] = Value::Array(details);
498        }
499        if !tool_calls.is_empty() {
500            message["tool_calls"] = Value::Array(tool_calls);
501        }
502
503        let body = json!({
504            "id": response.id.clone().unwrap_or_else(|| "chatcmpl_switchyard".to_string()),
505            "object": "chat.completion",
506            "created": 0,
507            "model": response.model.clone().unwrap_or_else(|| "unknown".to_string()),
508            "choices": [{
509                "index": 0,
510                "message": message,
511                "finish_reason": output
512                    .and_then(|output| output.stop_reason)
513                    .map(openai_finish_reason)
514                    .unwrap_or("stop"),
515            }],
516            "usage": encode_openai_usage(&response.usage),
517        });
518        Ok(EncodedResponse {
519            body: embed_preservation(body, &response.preservation, _policy),
520            diagnostics: Vec::new(),
521        })
522    }
523}
524
525// Pulls OpenAI-compatible reasoning fields into private reasoning IR blocks.
526fn prepend_openai_reasoning_blocks(content: &mut Vec<ContentBlock>, object: &Map<String, Value>) {
527    if let Some(details) = object
528        .get("reasoning_details")
529        .and_then(Value::as_array)
530        .filter(|details| !details.is_empty())
531    {
532        let text = reasoning_text_from_details(details)
533            .or_else(|| {
534                first_nonempty_string(object, &["reasoning_content", "reasoning"])
535                    .map(ToOwned::to_owned)
536            })
537            .unwrap_or_default();
538        let signature = details.iter().find_map(|detail| {
539            detail
540                .get("signature")
541                .and_then(Value::as_str)
542                .filter(|signature| !signature.is_empty())
543                .map(ToOwned::to_owned)
544        });
545        content.insert(
546            0,
547            ContentBlock::Reasoning {
548                text,
549                signature,
550                details: details.clone(),
551            },
552        );
553        return;
554    }
555
556    if let Some(text) = first_nonempty_string(object, &["reasoning_content", "reasoning"]) {
557        content.insert(
558            0,
559            ContentBlock::Reasoning {
560                text: text.to_string(),
561                signature: None,
562                details: Vec::new(),
563            },
564        );
565    }
566}
567
568// Returns structured reasoning details in their original order.
569fn reasoning_details_from_blocks(content: &[ContentBlock]) -> Vec<Value> {
570    content
571        .iter()
572        .filter_map(|block| match block {
573            ContentBlock::Reasoning { details, .. } => Some(details.as_slice()),
574            _ => None,
575        })
576        .flatten()
577        .cloned()
578        .collect()
579}
580
581/// Decodes OpenAI role strings into normalized roles.
582///
583/// Unknown role strings are rejected with [`TranslationError::InvalidValue`] so
584/// the router returns the same `invalid_value` error the provider would, rather
585/// than silently coercing an invalid role to `user`. A missing role and
586/// known-but-unmapped roles (e.g. the legacy `function` role) keep their
587/// historical mapping to `user`. `path` points at the offending field.
588pub(crate) fn role_from_openai(role: Option<&str>, path: &str) -> Result<Role> {
589    match role {
590        Some("system") => Ok(Role::System),
591        Some("developer") => Ok(Role::Developer),
592        Some("assistant") => Ok(Role::Assistant),
593        Some("tool") => Ok(Role::Tool),
594        None => Ok(Role::User),
595        Some(other) if is_known_role_name(other) => Ok(Role::User),
596        Some(other) => Err(TranslationError::unsupported_role(path, other)),
597    }
598}
599
600/// Decodes OpenAI-style content into normalized content blocks.
601pub(crate) fn decode_openai_content(
602    content: &Value,
603    provider: WireFormat,
604    diagnostics: &mut Vec<TranslationDiagnostic>,
605    policy: &TranslationPolicy,
606    path: impl Into<String>,
607) -> Result<Vec<ContentBlock>> {
608    let path = path.into();
609    match content {
610        Value::Null => Ok(vec![ContentBlock::Text {
611            text: String::new(),
612        }]),
613        Value::String(text) => Ok(vec![ContentBlock::Text { text: text.clone() }]),
614        Value::Array(blocks) => {
615            let mut content = Vec::new();
616            for (index, block) in blocks.iter().enumerate() {
617                let Some(block) = block.as_object() else {
618                    push_lossy(
619                        diagnostics,
620                        policy,
621                        format!("content block at {path}[{index}] is not an object"),
622                    )?;
623                    continue;
624                };
625                match block.get("type").and_then(Value::as_str) {
626                    Some("text") | Some("input_text") | Some("output_text") => {
627                        content.push(ContentBlock::Text {
628                            text: block
629                                .get("text")
630                                .and_then(Value::as_str)
631                                .unwrap_or_default()
632                                .to_string(),
633                        });
634                    }
635                    Some("refusal") => {
636                        content.push(ContentBlock::Refusal {
637                            text: block
638                                .get("refusal")
639                                .and_then(Value::as_str)
640                                .unwrap_or_default()
641                                .to_string(),
642                        });
643                    }
644                    Some("image_url") | Some("input_image") => {
645                        if let Some(source) = decode_image_source(block) {
646                            content.push(ContentBlock::Image { source });
647                        }
648                    }
649                    Some("input_audio") => content.push(ContentBlock::Audio {
650                        source: MediaSource::Raw(Value::Object(block.clone())),
651                    }),
652                    Some("file") | Some("input_file") => {
653                        content.push(ContentBlock::File {
654                            source: decode_file_source(block),
655                        });
656                    }
657                    _ => content.push(ContentBlock::Unknown {
658                        provider: provider.into(),
659                        raw: Value::Object(block.clone()),
660                    }),
661                }
662            }
663            if content.is_empty() {
664                Ok(vec![ContentBlock::Text {
665                    text: String::new(),
666                }])
667            } else {
668                Ok(content)
669            }
670        }
671        other => Ok(vec![ContentBlock::Text {
672            text: string_value(other).unwrap_or_default(),
673        }]),
674    }
675}
676
677/// Decodes OpenAI image block shapes into normalized image sources.
678pub(crate) fn decode_image_source(block: &Map<String, Value>) -> Option<ImageSource> {
679    if let Some(image_url) = block.get("image_url") {
680        if let Some(url) = image_url.as_str() {
681            return Some(ImageSource::Url {
682                url: url.to_string(),
683                detail: block
684                    .get("detail")
685                    .and_then(Value::as_str)
686                    .map(ToOwned::to_owned),
687            });
688        }
689        if let Some(payload) = image_url.as_object() {
690            return payload
691                .get("url")
692                .and_then(Value::as_str)
693                .map(|url| ImageSource::Url {
694                    url: url.to_string(),
695                    detail: payload
696                        .get("detail")
697                        .or_else(|| block.get("detail"))
698                        .and_then(Value::as_str)
699                        .map(ToOwned::to_owned),
700                });
701        }
702    }
703    if let Some(image_url) = block.get("image_url").and_then(Value::as_str) {
704        return Some(ImageSource::Url {
705            url: image_url.to_string(),
706            detail: block
707                .get("detail")
708                .and_then(Value::as_str)
709                .map(ToOwned::to_owned),
710        });
711    }
712    Some(ImageSource::Raw(Value::Object(block.clone())))
713}
714
715/// Decodes OpenAI file block shapes into normalized file sources.
716///
717/// Accepts both the Chat shape, which nests the payload under a `file` object,
718/// and the Responses shape, which carries `file_id`/`file_data`/`filename`
719/// directly on the block. Returns `FileSource::Raw` when neither shape carries a
720/// field this can normalize.
721pub(crate) fn decode_file_source(block: &Map<String, Value>) -> FileSource {
722    if let Some(file) = block.get("file").and_then(Value::as_object) {
723        if let Some(file_id) = file.get("file_id").and_then(Value::as_str) {
724            return FileSource::FileId(file_id.to_string());
725        }
726        if let Some(file_data) = file.get("file_data").and_then(Value::as_str) {
727            return FileSource::FileData {
728                data: file_data.to_string(),
729                filename: file
730                    .get("filename")
731                    .and_then(Value::as_str)
732                    .map(ToOwned::to_owned),
733            };
734        }
735        return FileSource::Raw(Value::Object(file.clone()));
736    }
737    // A Chat block never reaches here with these keys, having matched the nested
738    // branch above.
739    if let Some(file_id) = block.get("file_id").and_then(Value::as_str) {
740        return FileSource::FileId(file_id.to_string());
741    }
742    if let Some(file_data) = block.get("file_data").and_then(Value::as_str) {
743        return FileSource::FileData {
744            data: file_data.to_string(),
745            filename: block
746                .get("filename")
747                .and_then(Value::as_str)
748                .map(ToOwned::to_owned),
749        };
750    }
751    FileSource::Raw(Value::Object(block.clone()))
752}
753
754/// Decodes one OpenAI tool call into a normalized tool call.
755pub(crate) fn decode_openai_tool_call(
756    tool_call: &Value,
757    generated_counter: usize,
758    policy: &TranslationPolicy,
759) -> Result<Option<ToolCall>> {
760    let Some(tool_call) = tool_call.as_object() else {
761        return Ok(None);
762    };
763    let function = tool_call
764        .get("function")
765        .and_then(Value::as_object)
766        .cloned()
767        .unwrap_or_default();
768    let id = tool_call
769        .get("id")
770        .and_then(Value::as_str)
771        .filter(|id| !id.is_empty())
772        .map(ToOwned::to_owned)
773        .unwrap_or_else(|| match &policy.deterministic_ids {
774            DeterministicIdPolicy::GenerateStable { prefix } => {
775                stable_id(prefix, generated_counter)
776            }
777            DeterministicIdPolicy::Preserve => String::new(),
778        });
779    // A custom (freeform) call has `custom.name` and a raw `custom.input` string. Carry the
780    // input as the single `input` argument, the same way Responses custom calls are carried.
781    let custom = tool_call.get("custom").and_then(Value::as_object);
782    let arguments = match custom {
783        Some(custom) => json!({
784            crate::codex_custom_tools::INPUT_ARGUMENT:
785                custom.get("input").and_then(Value::as_str).unwrap_or_default()
786        }),
787        None => function
788            .get("arguments")
789            .map(parse_arguments)
790            .unwrap_or_else(|| json!({})),
791    };
792    let name = custom
793        .unwrap_or(&function)
794        .get("name")
795        .and_then(Value::as_str)
796        .unwrap_or_default()
797        .to_string();
798    Ok(Some(ToolCall {
799        id,
800        name,
801        arguments,
802    }))
803}
804
805/// Parses stringified tool-call arguments when possible.
806pub(crate) fn parse_arguments(value: &Value) -> Value {
807    match value {
808        Value::String(text) => serde_json::from_str(text).unwrap_or_else(|_| json!({"raw": text})),
809        other => other.clone(),
810    }
811}
812
813/// Decodes OpenAI tool definitions into normalized tool definitions.
814pub(crate) fn decode_openai_tools(
815    tools: Option<&Value>,
816    _diagnostics: &mut Vec<TranslationDiagnostic>,
817    _policy: &TranslationPolicy,
818) -> Result<Vec<ToolDefinition>> {
819    let Some(tools) = tools.and_then(Value::as_array) else {
820        return Ok(Vec::new());
821    };
822    let mut definitions = Vec::new();
823    for tool in tools {
824        let Some(tool) = tool.as_object() else {
825            continue;
826        };
827        let function = tool
828            .get("function")
829            .and_then(Value::as_object)
830            .cloned()
831            .unwrap_or_else(|| tool.clone());
832        let name = function
833            .get("name")
834            .and_then(Value::as_str)
835            .unwrap_or_default()
836            .to_string();
837        if name.is_empty() {
838            continue;
839        }
840        definitions.push(ToolDefinition {
841            name,
842            description: function
843                .get("description")
844                .and_then(Value::as_str)
845                .map(ToOwned::to_owned),
846            parameters: function
847                .get("parameters")
848                .cloned()
849                .unwrap_or_else(|| json!({})),
850            strict: function.get("strict").and_then(Value::as_bool),
851        });
852    }
853    Ok(definitions)
854}
855
856/// Decodes OpenAI tool-choice values into normalized policy.
857pub(crate) fn decode_openai_tool_choice(value: &Value) -> ToolChoice {
858    match value {
859        Value::String(text) if text == "auto" => ToolChoice::Auto,
860        Value::String(text) if text == "required" => ToolChoice::Required,
861        Value::String(text) if text == "none" => ToolChoice::None,
862        Value::Object(object) => object
863            .get("function")
864            .and_then(Value::as_object)
865            .and_then(|function| function.get("name"))
866            .and_then(Value::as_str)
867            .map(|name| ToolChoice::Tool {
868                name: name.to_string(),
869            })
870            .unwrap_or_else(|| ToolChoice::Raw(value.clone())),
871        _ => ToolChoice::Raw(value.clone()),
872    }
873}
874
875/// Encodes one normalized message into one or more OpenAI messages.
876pub(crate) fn encode_message_to_openai(
877    message: &Message,
878    diagnostics: &mut Vec<TranslationDiagnostic>,
879    policy: &TranslationPolicy,
880) -> Result<Vec<Value>> {
881    if message_has_tool_results(message) {
882        return encode_message_with_tool_results_to_openai(message, diagnostics, policy);
883    }
884
885    Ok(vec![encode_message_without_tool_results_to_openai(
886        message,
887        diagnostics,
888        policy,
889    )?])
890}
891
892// Splits mixed content so OpenAI tool-result messages stay separate.
893fn encode_message_with_tool_results_to_openai(
894    message: &Message,
895    diagnostics: &mut Vec<TranslationDiagnostic>,
896    policy: &TranslationPolicy,
897) -> Result<Vec<Value>> {
898    let mut out = Vec::new();
899    let mut pending_content = Vec::new();
900
901    for block in &message.content {
902        if let ContentBlock::ToolResult(result) = block {
903            out.push(json!({
904                "role": "tool",
905                "tool_call_id": result.tool_call_id,
906                "content": text_from_blocks(&result.content, " "),
907            }));
908            let non_text = result
909                .content
910                .iter()
911                .filter(|block| {
912                    !matches!(
913                        block,
914                        ContentBlock::Text { .. } | ContentBlock::Refusal { .. }
915                    )
916                })
917                .cloned()
918                .collect::<Vec<_>>();
919            if !non_text.is_empty() {
920                push_lossy(
921                    diagnostics,
922                    policy,
923                    "OpenAI Chat tool messages only support text; non-text tool-result content was moved to a user message",
924                )?;
925                pending_content.extend(non_text);
926            }
927        } else {
928            pending_content.push(block.clone());
929        }
930    }
931
932    push_pending_openai_message(
933        &mut out,
934        message.role,
935        &mut pending_content,
936        diagnostics,
937        policy,
938    )?;
939    Ok(out)
940}
941
942// Flushes accumulated non-tool-result content as a normal OpenAI message.
943fn push_pending_openai_message(
944    out: &mut Vec<Value>,
945    role: Role,
946    pending_content: &mut Vec<ContentBlock>,
947    diagnostics: &mut Vec<TranslationDiagnostic>,
948    policy: &TranslationPolicy,
949) -> Result<()> {
950    if pending_content.is_empty() {
951        return Ok(());
952    }
953
954    let message = Message::new(role, std::mem::take(pending_content));
955    out.push(encode_message_without_tool_results_to_openai(
956        &message,
957        diagnostics,
958        policy,
959    )?);
960    Ok(())
961}
962
963// Encodes a normalized message that has no tool-result blocks.
964fn encode_message_without_tool_results_to_openai(
965    message: &Message,
966    diagnostics: &mut Vec<TranslationDiagnostic>,
967    policy: &TranslationPolicy,
968) -> Result<Value> {
969    let role = match message.role {
970        Role::System => "system",
971        Role::Developer => "developer",
972        Role::Assistant => "assistant",
973        Role::Tool => "tool",
974        Role::User => "user",
975    };
976    let tool_calls = message
977        .content
978        .iter()
979        .filter_map(|block| match block {
980            ContentBlock::ToolCall(call) => Some(json!({
981                "id": call.id,
982                "type": "function",
983                "function": {
984                    "name": call.name,
985                    "arguments": json_string(&call.arguments),
986                },
987            })),
988            _ => None,
989        })
990        .collect::<Vec<_>>();
991    let content_blocks = message
992        .content
993        .iter()
994        .filter(|block| {
995            !matches!(
996                block,
997                ContentBlock::ToolCall(_) | ContentBlock::Reasoning { .. }
998            )
999        })
1000        .cloned()
1001        .collect::<Vec<_>>();
1002    let mut message_json = json!({
1003        "role": role,
1004        "content": encode_openai_content(&content_blocks, message.role, diagnostics, policy)?,
1005    });
1006    encode_openai_message_reasoning(&mut message_json, &message.content);
1007    if !tool_calls.is_empty() {
1008        message_json["tool_calls"] = Value::Array(tool_calls);
1009        if message_json["content"] == Value::String(String::new()) {
1010            message_json["content"] = Value::Null;
1011        }
1012    }
1013    Ok(message_json)
1014}
1015
1016// Adds either plaintext reasoning or structured details to an OpenAI Chat message.
1017fn encode_openai_message_reasoning(message: &mut Value, content: &[ContentBlock]) {
1018    let details = reasoning_details_from_blocks(content);
1019    if details.is_empty() {
1020        encode_openai_message_plaintext_reasoning(message, content);
1021    } else {
1022        encode_openai_message_structured_reasoning(message, content, details);
1023    }
1024}
1025
1026// Adds reasoning blocks that have no structured provider representation.
1027fn encode_openai_message_plaintext_reasoning(message: &mut Value, content: &[ContentBlock]) {
1028    let reasoning = content
1029        .iter()
1030        .filter_map(|block| match block {
1031            ContentBlock::Reasoning {
1032                text,
1033                signature: None,
1034                ..
1035            } => Some(text.as_str()),
1036            _ => None,
1037        })
1038        .collect::<Vec<_>>()
1039        .join("\n");
1040    if !reasoning.is_empty() {
1041        message["reasoning"] = Value::String(reasoning);
1042    }
1043}
1044
1045// Adds exact provider details and text that cannot be recovered from those details.
1046fn encode_openai_message_structured_reasoning(
1047    message: &mut Value,
1048    content: &[ContentBlock],
1049    details: Vec<Value>,
1050) {
1051    message["reasoning_details"] = Value::Array(details);
1052    let fallback = content
1053        .iter()
1054        .filter_map(|block| match block {
1055            ContentBlock::Reasoning { text, details, .. }
1056                if !details.is_empty()
1057                    && reasoning_text_from_details(details).as_deref() != Some(text.as_str())
1058                    && !text.is_empty() =>
1059            {
1060                Some(text.as_str())
1061            }
1062            _ => None,
1063        })
1064        .collect::<Vec<_>>()
1065        .join("\n");
1066    if !fallback.is_empty() {
1067        message["reasoning"] = Value::String(fallback);
1068    }
1069}
1070
1071// Checks whether any block in a message is a tool result.
1072fn message_has_tool_results(message: &Message) -> bool {
1073    message
1074        .content
1075        .iter()
1076        .any(|block| matches!(block, ContentBlock::ToolResult(_)))
1077}
1078
1079// Copies Chat-compatible extension fields preserved in the IR.
1080fn copy_openai_chat_request_extensions(
1081    body: &mut Map<String, Value>,
1082    extensions: &Map<String, Value>,
1083) {
1084    for field in [
1085        // Template switches for llama.cpp, vLLM and SGLang, such as `enable_thinking`.
1086        "chat_template_kwargs",
1087        "metadata",
1088        "parallel_tool_calls",
1089        "prompt_cache_key",
1090        "prompt_cache_retention",
1091        "safety_identifier",
1092        "service_tier",
1093        "store",
1094        "stream_options",
1095        // `top_logprobs` is only valid alongside `logprobs`.
1096        "logprobs",
1097        "top_logprobs",
1098        "user",
1099    ] {
1100        if let Some(value) = extensions.get(field) {
1101            body.entry(field.to_string())
1102                .or_insert_with(|| value.clone());
1103        }
1104    }
1105    if let Some(stop_sequences) = extensions.get("stop_sequences") {
1106        body.entry("stop").or_insert_with(|| stop_sequences.clone());
1107    }
1108}
1109
1110// Detects placeholder empty text generated while decoding assistant tool calls.
1111fn is_empty_text_only(content: &[ContentBlock]) -> bool {
1112    matches!(content, [ContentBlock::Text { text }] if text.is_empty())
1113}
1114
1115/// Encodes normalized content into OpenAI Chat content JSON.
1116pub(crate) fn encode_openai_content(
1117    content: &[ContentBlock],
1118    role: Role,
1119    diagnostics: &mut Vec<TranslationDiagnostic>,
1120    policy: &TranslationPolicy,
1121) -> Result<Value> {
1122    if content
1123        .iter()
1124        .any(|block| matches!(block, ContentBlock::Mcp(_)))
1125    {
1126        return Err(TranslationError::LossyConversion(
1127            "MCP history encoding is not implemented".into(),
1128        ));
1129    }
1130    let has_non_text = content.iter().any(|block| {
1131        matches!(
1132            block,
1133            ContentBlock::Image { .. }
1134                | ContentBlock::Audio { .. }
1135                | ContentBlock::Video { .. }
1136                | ContentBlock::File { .. }
1137                | ContentBlock::Unknown { .. }
1138        )
1139    });
1140    if !has_non_text {
1141        return Ok(Value::String(text_from_blocks(content, "\n")));
1142    }
1143    if role != Role::User {
1144        for block in content {
1145            if let ContentBlock::Unknown { provider, raw } = block {
1146                reject_responses_native_input_item(provider, raw, WireFormat::OpenAiChat)?;
1147            }
1148        }
1149        push_lossy(
1150            diagnostics,
1151            policy,
1152            "OpenAI Chat only supports text content for non-user messages",
1153        )?;
1154        return Ok(Value::String(text_from_blocks(content, "\n")));
1155    }
1156    let mut blocks = Vec::new();
1157    for block in content {
1158        crate::codecs::openai_media::validate_media(block, WireFormat::OpenAiChat)?;
1159        match block {
1160            ContentBlock::Text { text } => blocks.push(json!({"type": "text", "text": text})),
1161            ContentBlock::Refusal { text } => blocks.push(json!({"type": "text", "text": text})),
1162            ContentBlock::Image { source } => match openai_image_part(source) {
1163                Some(part) => blocks.push(part),
1164                None => {
1165                    push_lossy(
1166                        diagnostics,
1167                        policy,
1168                        "OpenAI Chat codec could not map image content",
1169                    )?;
1170                    blocks.push(openai_text_part(&image_source_text(source)));
1171                }
1172            },
1173            ContentBlock::File { source } => match openai_file_part(source) {
1174                Some(part) => blocks.push(part),
1175                None => {
1176                    push_lossy(
1177                        diagnostics,
1178                        policy,
1179                        "OpenAI Chat codec could not map file content",
1180                    )?;
1181                    blocks.push(openai_text_part(&file_source_text(source)));
1182                }
1183            },
1184            ContentBlock::Audio { source } => {
1185                blocks.push(crate::codecs::openai_media::audio_part(source)?);
1186            }
1187            ContentBlock::Video { source } => {
1188                push_lossy(
1189                    diagnostics,
1190                    policy,
1191                    "OpenAI Chat codec does not have a stable video request mapping yet",
1192                )?;
1193                blocks.push(openai_text_part(&media_source_text(source)));
1194            }
1195            ContentBlock::Mcp(_) => {
1196                return Err(TranslationError::LossyConversion(
1197                    "MCP history encoding is not implemented".into(),
1198                ));
1199            }
1200            ContentBlock::Unknown { provider, raw } => {
1201                reject_responses_native_input_item(provider, raw, WireFormat::OpenAiChat)?;
1202                push_lossy(
1203                    diagnostics,
1204                    policy,
1205                    "unknown content block encoded as text for OpenAI Chat",
1206                )?;
1207                blocks.push(openai_text_part(&json_string(raw)));
1208            }
1209            ContentBlock::Reasoning { .. }
1210            | ContentBlock::ToolCall(_)
1211            | ContentBlock::ToolResult(_) => {}
1212        }
1213    }
1214    Ok(Value::Array(blocks))
1215}
1216
1217// Builds an OpenAI text content part.
1218fn openai_text_part(text: &str) -> Value {
1219    json!({"type": "text", "text": text})
1220}
1221
1222fn openai_image_part(source: &ImageSource) -> Option<Value> {
1223    let ImagePayload { url, detail } = image_payload(source)?;
1224    let mut image_url = json!({});
1225    image_url["url"] = Value::String(url);
1226    if let Some(detail) = detail {
1227        image_url["detail"] = Value::String(detail);
1228    }
1229    let mut part = json!({"type": "image_url"});
1230    part["image_url"] = image_url;
1231    Some(part)
1232}
1233
1234fn openai_file_part(source: &FileSource) -> Option<Value> {
1235    let mut part = json!({"type": "file"});
1236    part["file"] = Value::Object(file_payload(source)?);
1237    Some(part)
1238}
1239
1240// Converts unsupported media sources to deterministic text fallback content.
1241fn media_source_text(source: &MediaSource) -> String {
1242    match source {
1243        MediaSource::Url { url, media_type } => json_string(&json!({
1244            "url": url,
1245            "media_type": media_type,
1246        })),
1247        MediaSource::Base64 { media_type, data } => json_string(&json!({
1248            "media_type": media_type,
1249            "data": data,
1250        })),
1251        MediaSource::Raw(raw) => json_string(raw),
1252    }
1253}
1254
1255/// Encodes normalized tool definitions into OpenAI tool JSON.
1256pub(crate) fn encode_openai_tools(tools: &[Tool]) -> Result<Value> {
1257    let mut names = std::collections::HashSet::new();
1258    Ok(Value::Array(
1259        tools
1260            .iter()
1261            .map(|tool| {
1262                let tool = tool.function().ok_or_else(|| {
1263                    TranslationError::LossyConversion(
1264                        "MCP and provider tool encoding is not implemented".into(),
1265                    )
1266                })?;
1267                if !names.insert(tool.name.as_str()) {
1268                    return Err(TranslationError::InvalidValue {
1269                        path: "$.tools".to_string(),
1270                        message: format!("duplicate tool name: {:?}", tool.name),
1271                    });
1272                }
1273                let mut function = json!({
1274                    "name": tool.name,
1275                    "description": tool.description.clone().unwrap_or_default(),
1276                    "parameters": tool.parameters,
1277                });
1278                if let Some(strict) = tool.strict {
1279                    function["strict"] = Value::Bool(strict);
1280                }
1281                Ok(json!({"type": "function", "function": function}))
1282            })
1283            .collect::<Result<_>>()?,
1284    ))
1285}
1286
1287/// Encodes normalized tool choice into OpenAI Chat JSON.
1288pub(crate) fn encode_openai_tool_choice(choice: &ToolChoice) -> Value {
1289    match choice {
1290        ToolChoice::Auto => Value::String("auto".to_string()),
1291        ToolChoice::Required => Value::String("required".to_string()),
1292        ToolChoice::None => Value::String("none".to_string()),
1293        ToolChoice::Tool { name } => json!({"type": "function", "function": {"name": name}}),
1294        ToolChoice::Raw(value) => value.clone(),
1295    }
1296}
1297
1298/// Normalizes OpenAI usage fields.
1299pub(crate) fn decode_openai_usage(value: Option<&Value>) -> Usage {
1300    let Some(value) = value.and_then(Value::as_object) else {
1301        return Usage::default();
1302    };
1303    let cached_input_tokens = value
1304        .get("prompt_tokens_details")
1305        .and_then(|details| details.get("cached_tokens"))
1306        .and_then(Value::as_u64);
1307    let cache_creation_input_tokens = value
1308        .get("prompt_tokens_details")
1309        .and_then(|details| {
1310            details
1311                .get("cache_write_tokens")
1312                .or_else(|| details.get("cache_creation_tokens"))
1313        })
1314        .and_then(Value::as_u64);
1315    Usage {
1316        provider_cost: crate::codecs::common::provider_cost(value),
1317        input_tokens: value
1318            .get("prompt_tokens")
1319            .and_then(Value::as_u64)
1320            .map(|tokens| {
1321                tokens
1322                    .saturating_sub(cached_input_tokens.unwrap_or(0))
1323                    .saturating_sub(cache_creation_input_tokens.unwrap_or(0))
1324            }),
1325        cache: crate::codecs::common::cache_usage_details(
1326            value,
1327            cached_input_tokens,
1328            cache_creation_input_tokens,
1329        ),
1330        output_tokens: value.get("completion_tokens").and_then(Value::as_u64),
1331        total_tokens: value.get("total_tokens").and_then(Value::as_u64),
1332        reasoning_tokens: value
1333            .get("completion_tokens_details")
1334            .and_then(|details| details.get("reasoning_tokens"))
1335            .or_else(|| {
1336                value
1337                    .get("output_tokens_details")
1338                    .and_then(|details| details.get("reasoning_tokens"))
1339            })
1340            .and_then(Value::as_u64),
1341    }
1342}
1343
1344/// Encodes normalized usage into OpenAI Chat usage JSON.
1345pub(crate) fn encode_openai_usage(usage: &Usage) -> Value {
1346    let prompt_tokens = usage.input_tokens.unwrap_or(0)
1347        + usage.cached_input_tokens().unwrap_or(0)
1348        + usage.cache_creation_input_tokens().unwrap_or(0);
1349    let mut value = json!({
1350        "prompt_tokens": prompt_tokens,
1351        "completion_tokens": usage.output_tokens.unwrap_or(0),
1352        "total_tokens": usage
1353            .total_tokens
1354            .or_else(|| Some(prompt_tokens + usage.output_tokens.unwrap_or(0)))
1355            .unwrap_or(0),
1356    });
1357    if usage.cached_input_tokens().is_some() || usage.cache_creation_input_tokens().is_some() {
1358        value["prompt_tokens_details"] = json!({
1359            "cached_tokens": usage.cached_input_tokens().unwrap_or(0),
1360            "cache_write_tokens": usage.cache_creation_input_tokens().unwrap_or(0),
1361        });
1362    }
1363    if let Some(reasoning_tokens) = usage.reasoning_tokens {
1364        value["completion_tokens_details"] = json!({
1365            "reasoning_tokens": reasoning_tokens,
1366        });
1367    }
1368    crate::codecs::common::encode_usage_metadata(value, usage)
1369}
1370
1371/// Maps OpenAI finish reasons to normalized stop reasons.
1372pub(crate) fn map_openai_finish_reason(reason: Option<&str>) -> StopReason {
1373    match reason {
1374        Some("length") => StopReason::MaxTokens,
1375        Some("tool_calls") | Some("function_call") => StopReason::ToolUse,
1376        Some("content_filter") => StopReason::ContentFilter,
1377        Some("stop") | None => StopReason::EndTurn,
1378        _ => StopReason::Unknown,
1379    }
1380}
1381
1382/// Maps normalized stop reasons back to OpenAI's vocabulary.
1383pub(crate) fn openai_finish_reason(reason: StopReason) -> &'static str {
1384    match reason {
1385        StopReason::MaxTokens => "length",
1386        StopReason::ToolUse => "tool_calls",
1387        StopReason::ContentFilter => "content_filter",
1388        StopReason::EndTurn | StopReason::Unknown | StopReason::Error => "stop",
1389    }
1390}