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