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