Skip to main content

rig_core/providers/openai/responses_api/
mod.rs

1//! Request and response types for the OpenAI Responses API.
2//! Endpoint and dialect configuration lives in [`wire`].
3//!
4//! ```no_run
5//! use rig_core::providers::openai::{self, OpenAI};
6//!
7//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
8//! let model = OpenAI::from_env()?.responses(openai::GPT_5_2);
9//! # let _ = model;
10//! # Ok(())
11//! # }
12//! ```
13
14use crate::completion::history::Replay;
15use crate::completion::options::{
16    BaseInput, CacheRetention, FinalBody, RawAt, Rewrite, request_params,
17};
18use crate::error::EncodeError;
19use crate::json_utils;
20use crate::json_utils::Lenient;
21use crate::message::{
22    AssistantContent, DocumentContent, DocumentData, DocumentMediaType, DocumentSourceKind,
23    Message, MimeType, ToolResultContent, UserContent,
24};
25use crate::providers::internal::object;
26use crate::providers::internal::wire_ids::WireIds;
27use crate::wire::Mode;
28use crate::{completion, message};
29use serde::{Deserialize, Serialize, Serializer};
30use serde_json::{Map, Value, json};
31use std::sync::Arc;
32
33pub mod streaming;
34pub mod websocket;
35pub mod wire;
36
37/// The `input_image` part `image` goes as: a data URL for typed base64
38/// data, its URL, or its file id. `None` for any other source, which
39/// [`wire::Responses`] tells the adapter it does not carry.
40fn image_part(image: &message::Image) -> Option<Value> {
41    let (key, source) = match &image.data {
42        DocumentSourceKind::Base64(data) => (
43            "image_url",
44            format!(
45                "data:{};base64,{data}",
46                image.media_type.as_ref()?.to_mime_type()
47            ),
48        ),
49        DocumentSourceKind::Url(url) => ("image_url", url.clone()),
50        DocumentSourceKind::FileId(file_id) => ("file_id", file_id.clone()),
51        _ => return None,
52    };
53    let mut part =
54        json!({"type": "input_image", "detail": image.detail.clone().unwrap_or_default()});
55    set(&mut part, key, Value::String(source));
56    Some(part)
57}
58
59/// The content part `document` goes as: an `input_file` for a file id, a URL
60/// or base64 PDF data, and its text for a text document. `None` for any other
61/// form; the adapter sends a text document's text instead.
62fn document_part(document: &DocumentContent) -> Option<Value> {
63    let source = match &document.data {
64        DocumentData::Text(text) => return Some(json!({"type": "input_text", "text": text})),
65        DocumentData::File(source) => source,
66    };
67    Some(match source {
68        DocumentSourceKind::FileId(file_id) => json!({"type": "input_file", "file_id": file_id}),
69        // `input_file` reads the type of a file it fetches itself.
70        DocumentSourceKind::Url(url) => json!({"type": "input_file", "file_url": url}),
71        DocumentSourceKind::Base64(data) if document.media_type == Some(DocumentMediaType::PDF) => {
72            object! {
73                "type": "input_file",
74                "file_data": format!("data:application/pdf;base64,{data}"),
75                "filename": "document.pdf",
76            }
77        }
78        _ => return None,
79    })
80}
81
82/// `value` with `key` set to `field`, when `value` is an object.
83fn set(value: &mut Value, key: &str, field: Value) {
84    if let Some(fields) = value.as_object_mut() {
85        fields.insert(key.to_owned(), field);
86    }
87}
88
89/// The refusal for a part a request was not prepared to carry.
90fn unsendable(part: &str) -> EncodeError {
91    EncodeError::request(format!(
92        "the Responses API cannot carry this {part}; prepare the request first"
93    ))
94}
95
96/// A tool result's `output`: one text as a string, anything else as its
97/// ordered parts.
98fn result_output(content: &[ToolResultContent]) -> Result<Value, EncodeError> {
99    let mut parts = content
100        .iter()
101        .map(|part| match part {
102            ToolResultContent::Text(text) => Ok(json!({"type": "input_text", "text": text.text})),
103            ToolResultContent::Json { value } => {
104                Ok(json!({"type": "input_text", "text": value.to_string()}))
105            }
106            ToolResultContent::Image(image) => {
107                image_part(image).ok_or_else(|| unsendable("tool-result image"))
108            }
109        })
110        .collect::<Result<Vec<_>, _>>()?;
111    Ok(match parts.as_mut_slice() {
112        [part] if part.str("type") == Some("input_text") => {
113            part.get_mut("text").map(Value::take).unwrap_or_default()
114        }
115        _ => Value::Array(parts),
116    })
117}
118
119/// The custom tools of a request: a call to one is a `custom_tool_call`,
120/// answered by a `custom_tool_call_output`, decided by name. A result
121/// answering a call the request sends takes that call's kind.
122struct Custom {
123    /// The custom tools the request declares.
124    tools: std::collections::HashSet<String>,
125    /// Whether each call id the request sends is a custom call.
126    calls: std::collections::HashMap<String, bool>,
127}
128
129/// The input items of `history` for `target`, which addresses `model`. A
130/// turn the target model produced keeps its provider items (the adapter
131/// cleared the rest): a current item verbatim with its call id spelled, an
132/// edited block rebuilt under its item's identity, and any other block
133/// rebuilt as another model's turn is: text as
134/// a completed output message under a synthetic id, and a call with no
135/// item id. Reasoning only its item can carry goes only with its identity.
136/// A `stateless` request resolves no stored item, so on an endpoint that
137/// returns ciphertext, reasoning without it is left out and the block after
138/// it is rebuilt with no item id, as another model's turn is. Elsewhere a
139/// reasoning item carries its own text and goes as any other item.
140fn input(
141    history: &[Arc<Message>],
142    target: &wire::Responses,
143    model: &str,
144    custom: &mut Custom,
145    stateless: bool,
146) -> Result<(Vec<Value>, Layout), EncodeError> {
147    let ids = WireIds::for_target(history, target, model);
148    let mut items = Vec::new();
149    let mut layout = Layout::default();
150    for (position, message) in history.iter().enumerate() {
151        if layout.after.is_empty() && !matches!(&**message, Message::System { .. }) {
152            layout.after.push(items.len());
153        }
154        let mut parts = Vec::new();
155        match &**message {
156            Message::System { content } => items.push(json!({
157                "type": "message",
158                "role": target.provider.dialect.quirks.responses.system_role,
159                "content": [{"type": "input_text", "text": content}],
160            })),
161            Message::User { content } => {
162                for part in content {
163                    parts.push(items.len());
164                    let part = match part {
165                        // Blank text says nothing, and some backends reject it.
166                        UserContent::Text(text) if text.text.trim().is_empty() => continue,
167                        UserContent::Text(text) => json!({"type": "input_text", "text": text.text}),
168                        // A function output has no error field: a failed
169                        // result says so in its text.
170                        UserContent::ToolResult(result) => {
171                            let call_id = ids.spell(&result.call);
172                            let output = result_output(&result.content)?;
173                            items.push(
174                                if custom.calls.get(&call_id).copied().unwrap_or_else(|| {
175                                    custom.tools.contains(result.name.as_str())
176                                }) {
177                                    object! {"type": "custom_tool_call_output", "call_id": call_id, "output": output}
178                                } else {
179                                    object! {"type": "function_call_output", "call_id": call_id, "output": output, "status": "completed"}
180                                },
181                            );
182                            continue;
183                        }
184                        UserContent::Image(image) => {
185                            image_part(image).ok_or_else(|| unsendable("image"))?
186                        }
187                        UserContent::Document(document) => {
188                            document_part(document).ok_or_else(|| unsendable("document"))?
189                        }
190                        UserContent::Audio(_) => return Err(unsendable("audio")),
191                        UserContent::Video(_) => return Err(unsendable("video")),
192                    };
193                    items.push(object! {"type": "message", "role": "user", "content": vec![part]});
194                }
195            }
196            Message::Assistant(turn) => {
197                let mut texts = 0usize;
198                let mut unpaired = false;
199                for block in &turn.content {
200                    parts.push(items.len());
201                    let mut replay = block.replay(target, &ids);
202                    if unpaired && !matches!(block, AssistantContent::Reasoning(_)) {
203                        unpaired = false;
204                        replay = Replay::Rebuild;
205                    }
206                    let ciphertext = |item: &Map<String, Value>| {
207                        item.get("encrypted_content")
208                            .and_then(Value::as_str)
209                            .is_some_and(|cipher| !cipher.is_empty())
210                    };
211                    let unresolvable = stateless
212                        && target
213                            .provider
214                            .dialect
215                            .quirks
216                            .responses
217                            .reasoning_ciphertext
218                        && matches!(block, AssistantContent::Reasoning(_))
219                        && match &replay {
220                            Replay::Item(item) => !item.as_object().is_some_and(ciphertext),
221                            Replay::Identity(identity) => !ciphertext(identity),
222                            Replay::Rebuild => false,
223                        };
224                    if unresolvable {
225                        unpaired = true;
226                        continue;
227                    }
228                    let identity = match replay {
229                        Replay::Item(item) => {
230                            if let Some(call_id) = item.str("call_id") {
231                                let kind = item.str("type");
232                                if matches!(kind, Some("custom_tool_call" | "function_call")) {
233                                    custom.calls.insert(
234                                        call_id.to_owned(),
235                                        kind == Some("custom_tool_call"),
236                                    );
237                                }
238                            }
239                            items.push(item.into_owned());
240                            continue;
241                        }
242                        Replay::Identity(identity) => identity,
243                        Replay::Rebuild => Map::new(),
244                    };
245                    let id = |prefix: &str| {
246                        identity
247                            .get("id")
248                            .and_then(Value::as_str)
249                            .filter(|id| !id.is_empty() && id.starts_with(prefix) && id.len() <= 64)
250                            .map(str::to_owned)
251                    };
252                    let item = match block {
253                        AssistantContent::Text(text) => {
254                            let synthetic = match texts {
255                                0 => format!("msg_rig_{position}"),
256                                n => format!("msg_rig_{position}_{n}"),
257                            };
258                            texts += 1;
259                            let mut item = json!({
260                                "type": "message",
261                                "role": "assistant",
262                                "content": [{"type": "output_text", "text": text.text, "annotations": []}],
263                                "status": "completed",
264                                "id": id("").unwrap_or(synthetic),
265                            });
266                            if let Some(phase) =
267                                identity.get("phase").filter(|phase| phase.is_string())
268                            {
269                                set(&mut item, "phase", phase.clone());
270                            }
271                            items.push(item);
272                            continue;
273                        }
274                        AssistantContent::ToolCall(call) => {
275                            let call_id = ids.spell(&call.id);
276                            let name = call.function.name.as_str();
277                            let kind = identity.get("type").and_then(Value::as_str);
278                            let arguments = || {
279                                serde_json::to_string(&call.function.arguments).unwrap_or_default()
280                            };
281                            let (kind, key, payload, prefix) = if kind == Some("custom_tool_call")
282                                || (kind.is_none() && custom.tools.contains(name))
283                            {
284                                custom.calls.insert(call_id.clone(), true);
285                                let input =
286                                    call.function.arguments.get("input").and_then(Value::as_str);
287                                let input = input.map_or_else(arguments, str::to_owned);
288                                ("custom_tool_call", "input", input, "ctc_")
289                            } else {
290                                custom.calls.insert(call_id.clone(), false);
291                                ("function_call", "arguments", arguments(), "fc_")
292                            };
293                            let mut item = json!({"type": kind, "call_id": call_id, "name": name});
294                            set(&mut item, key, Value::String(payload));
295                            if let Some(id) = id(prefix) {
296                                set(&mut item, "id", json!(id));
297                            }
298                            item
299                        }
300                        // An edited reasoning block keeps its item's id and
301                        // ciphertext, so the items after it stay paired.
302                        AssistantContent::Reasoning(reasoning) => {
303                            let Some(rs) = id("") else {
304                                continue;
305                            };
306                            let summary: Vec<Value> = (!reasoning.text.is_empty())
307                                .then(|| json!({"type": "summary_text", "text": reasoning.text}))
308                                .into_iter()
309                                .collect();
310                            let mut item =
311                                object! {"type": "reasoning", "id": rs, "summary": summary};
312                            if let Some(ciphertext) = identity.get("encrypted_content") {
313                                set(&mut item, "encrypted_content", ciphertext.clone());
314                            }
315                            item
316                        }
317                        AssistantContent::Opaque(opaque) if opaque.replay => opaque.item.clone(),
318                        AssistantContent::Opaque(_) => continue,
319                        AssistantContent::Image(_) => return Err(unsendable("assistant image")),
320                    };
321                    items.push(item);
322                }
323            }
324        }
325        if !matches!(&**message, Message::System { .. }) {
326            layout.after.push(items.len());
327            layout.parts.push(parts);
328        }
329    }
330    if layout.after.is_empty() {
331        layout.after.push(items.len());
332    }
333    Ok((items, layout))
334}
335
336/// Where the request's user and assistant messages (system messages not
337/// counted) fall among the input items, for its cache points.
338#[derive(Default)]
339struct Layout {
340    /// The item count after the first `n` messages, at `n`. At 0, the
341    /// count before the first message.
342    after: Vec<usize>,
343    /// For each message, the item count before each of its content items.
344    parts: Vec<Vec<usize>>,
345}
346
347impl Layout {
348    /// The item count the prefix `point` ends after, if the request has one.
349    fn boundary(&self, point: completion::CachePoint) -> Option<usize> {
350        use completion::CachePoint;
351        match point {
352            CachePoint::Tools => None,
353            CachePoint::System => self.after.first().copied(),
354            CachePoint::Messages(turns) => self.after.get(turns).copied(),
355            CachePoint::Within { message, items: 0 } => self.after.get(message).copied(),
356            CachePoint::Within { message, items } => self
357                .parts
358                .get(message)
359                .and_then(|parts| parts.get(items))
360                .or_else(|| self.after.get(message.checked_add(1)?))
361                .copied(),
362        }
363    }
364}
365
366/// The JSON of a tool choice.
367fn tool_choice(choice: message::ToolChoice) -> Result<Value, EncodeError> {
368    Ok(match choice {
369        message::ToolChoice::Auto => json!("auto"),
370        message::ToolChoice::None => json!("none"),
371        message::ToolChoice::Required => json!("required"),
372        message::ToolChoice::Specific { function_names } => match function_names.as_slice() {
373            [] => {
374                return Err(EncodeError::request(
375                    "ToolChoice::Specific requires at least one function name",
376                ));
377            }
378            [name] => json!({"type": "function", "name": name}),
379            names => json!({
380                "type": "allowed_tools",
381                "mode": "required",
382                "tools": names.iter().map(|name| json!({"type": "function", "name": name})).collect::<Vec<_>>(),
383            }),
384        },
385    })
386}
387
388/// Ask for the reasoning ciphertext, without which reasoning replays only
389/// from stored state.
390pub(crate) fn include_ciphertext(body: &mut Map<String, Value>) {
391    const CIPHERTEXT: &str = "reasoning.encrypted_content";
392    let mut include = body
393        .get("include")
394        .and_then(Value::as_array)
395        .cloned()
396        .unwrap_or_default();
397    if !include.iter().any(|item| item == CIPHERTEXT) {
398        include.push(json!(CIPHERTEXT));
399    }
400    body.insert("include".to_owned(), Value::Array(include));
401}
402
403/// Where a Responses body goes: the HTTP endpoint in a mode, or a WebSocket
404/// session's `response.create` event.
405#[derive(Clone, Copy, Debug, PartialEq, Eq)]
406pub(crate) enum Delivery {
407    /// `POST /responses`, streamed or not.
408    Http(Mode),
409    /// A WebSocket session, which ignores `stream` and `background`.
410    WebSocket,
411}
412
413impl wire::Responses {
414    /// The Responses request body this wire sends: its encoding of the
415    /// request, then the mapped options, then the provider options, then
416    /// `additional_params`, merged by [`request_params`], then the post-merge
417    /// rewrites. The WebSocket session calls it too, so both transports send
418    /// one body.
419    pub(crate) fn responses_request(
420        &self,
421        request: &completion::CompletionRequest,
422        delivery: Delivery,
423    ) -> Result<FinalBody, EncodeError> {
424        let codex =
425            self.provider.dialect.quirks.responses.contract == wire::ResponsesContract::Codex;
426        let mut rewrites = Vec::new();
427        match delivery {
428            Delivery::Http(Mode::Streaming) => rewrites.push(Rewrite::Stream(true)),
429            Delivery::Http(Mode::Unary) | Delivery::WebSocket => rewrites.push(Rewrite::NoStream),
430        }
431        if delivery == Delivery::WebSocket {
432            rewrites.push(Rewrite::NoBackground);
433        }
434        if codex {
435            rewrites.push(Rewrite::CodexStore);
436        }
437        // Reasoning replays without stored state only with its ciphertext.
438        if self.provider.dialect.quirks.responses.reasoning_ciphertext {
439            rewrites.push(Rewrite::ReasoningCiphertext(codex));
440        }
441        // The fields that stay the same turn to turn first, then the
442        // conversation, then the output cap, which one call may change: a
443        // request that appended to the conversation starts with the bytes
444        // of the one before, as the provider reads its prompt.
445        rewrites.push(Rewrite::MoveLast("input"));
446        rewrites.push(Rewrite::MoveLast("max_output_tokens"));
447        let body = request_params(
448            self,
449            request,
450            |layers| self.base(request, codex, layers),
451            RawAt::Top,
452            &rewrites,
453        )?;
454        crate::providers::openai::options::check_body(
455            self,
456            &self.facts,
457            request,
458            body,
459            crate::providers::openai::options::Endpoint::Responses,
460        )
461    }
462
463    /// This wire's own encoding of `request`: model, input, instructions,
464    /// tools and the typed fields the dialect takes. The Codex backend takes
465    /// no `max_output_tokens`, `temperature` or structured output, so it
466    /// gets none of them.
467    fn base(
468        &self,
469        request: &completion::CompletionRequest,
470        codex: bool,
471        layers: &mut BaseInput<'_>,
472    ) -> Result<Map<String, Value>, EncodeError> {
473        let model = request.model.clone().unwrap_or_else(|| self.model.clone());
474        let mut tools: Vec<ResponsesToolDefinition> = request
475            .tools
476            .iter()
477            .map(|tool| ResponsesToolDefinition::from(completion::ToolDefinition::clone(tool)))
478            .collect();
479        let extra = layers.raw_tools()?;
480        if !extra.is_empty() {
481            tools.extend(
482                crate::json_utils::from_value::<Vec<ResponsesToolDefinition>>(&Value::Array(extra))
483                    .map_err(|err| {
484                        EncodeError::request(format!(
485                            "Invalid OpenAI Responses tools payload in additional_params: {err}"
486                        ))
487                    })?,
488            );
489        }
490        tools.extend(self.tools.iter().cloned());
491        if self.strict_tools {
492            tools = tools
493                .into_iter()
494                .map(ResponsesToolDefinition::with_strict)
495                .collect();
496        }
497        let mut custom = Custom {
498            tools: tools
499                .iter()
500                .filter(|tool| tool.kind == "custom")
501                .map(|tool| tool.name.clone())
502                .collect(),
503            calls: Default::default(),
504        };
505        let store = self.store.map(Value::Bool);
506        let stateless = codex || layers.param("store").or(store.as_ref()) == Some(&json!(false));
507        let caller = match layers.claim("input") {
508            None | Some(Value::Null) => Vec::new(),
509            Some(Value::Array(items)) => items,
510            Some(other) => {
511                return Err(EncodeError::request(format!(
512                    "the OpenAI Responses `input` option must be an array of items, got {other}"
513                )));
514            }
515        };
516        // A result answering a held call takes that call's kind.
517        for item in &caller {
518            if let (Some(kind @ ("function_call" | "custom_tool_call")), Some(call_id)) =
519                (item.str("type"), item.str("call_id"))
520            {
521                custom
522                    .calls
523                    .insert(call_id.to_owned(), kind == "custom_tool_call");
524            }
525        }
526        let (items, layout) = input(&request.chat_history, self, &model, &mut custom, stateless)?;
527
528        let system = |item: &Value| {
529            (item.str("role") == Some(self.provider.dialect.quirks.responses.system_role)).then(
530                || {
531                    item.at("/content/0/text")
532                        .and_then(Value::as_str)
533                        .unwrap_or_default()
534                        .to_owned()
535                },
536            )
537        };
538        let lift: Vec<bool> = match self.system_instructions {
539            // The leading run of system messages, unless it is the whole
540            // request, which then keeps them in `input` so it is not empty.
541            SystemInstructionsPlacement::Instructions => {
542                let leading = items
543                    .iter()
544                    .take_while(|item| system(item).is_some())
545                    .count();
546                let leading = if leading < items.len() || !caller.is_empty() {
547                    leading
548                } else {
549                    0
550                };
551                (0..items.len()).map(|at| at < leading).collect()
552            }
553            SystemInstructionsPlacement::AllInstructions => {
554                items.iter().map(|item| system(item).is_some()).collect()
555            }
556            SystemInstructionsPlacement::InputSystemMessages => vec![false; items.len()],
557        };
558        let mut lifted = Vec::new();
559        let mut sent = caller;
560        let offset = sent.len();
561        for (item, lift) in items.into_iter().zip(&lift) {
562            if *lift {
563                lifted.extend(system(&item));
564            } else {
565                sent.push(item);
566            }
567        }
568        if sent.is_empty() {
569            return Err(EncodeError::request(if lifted.is_empty() {
570                "OpenAI Responses request input must contain at least one item"
571            } else {
572                "OpenAI Responses request input must contain at least one non-system item \
573             (system messages were lifted into the top-level `instructions` field)"
574            }));
575        }
576        if self.marks_cache_points(&model) && layers.cache() != Some(CacheRetention::None) {
577            // An item count of the request's own encoding, as one of `sent`.
578            let at =
579                |count: usize| offset + lift.iter().take(count).filter(|lifted| !**lifted).count();
580            let points = request
581                .cache_points
582                .iter()
583                .filter_map(|point| layout.boundary(*point))
584                .map(at);
585            mark_cache_points(&mut sent, offset, points);
586        }
587        let lifted: Vec<&str> = lifted
588            .iter()
589            .map(|text| text.trim())
590            .filter(|text| !text.is_empty())
591            .collect();
592        let lifted = lifted.join("\n\n");
593        // A gateway's own instructions go ahead of the caller's, once.
594        let instructions = match &self.provider.instructions {
595            Some(gateway) if lifted.is_empty() => Some(gateway.clone()),
596            Some(gateway) if !lifted.contains(gateway.as_str()) => {
597                Some(format!("{gateway}\n\n{lifted}"))
598            }
599            _ => (!lifted.is_empty()).then_some(lifted),
600        };
601        let text = request
602            .output_schema
603            .clone()
604            .filter(|_| !codex)
605            .map(|schema| {
606                let (name, schema) = super::structured_output_schema(schema);
607                json!({"format": {"type": "json_schema", "name": name, "schema": schema, "strict": true}})
608            });
609
610        Ok(crate::providers::internal::set_fields([
611            ("model", Some(Value::String(model))),
612            ("store", store),
613            ("input", Some(Value::Array(sent))),
614            ("instructions", instructions.map(Value::from)),
615            (
616                "max_output_tokens",
617                request.max_tokens.filter(|_| !codex).map(Value::from),
618            ),
619            (
620                "temperature",
621                request.temperature.filter(|_| !codex).map(Value::from),
622            ),
623            (
624                "tool_choice",
625                request.tool_choice.clone().map(tool_choice).transpose()?,
626            ),
627            ("tools", (!tools.is_empty()).then(|| json!(tools))),
628            ("text", text),
629        ]))
630    }
631}
632
633impl wire::Responses {
634    /// Whether this wire places [`completion::CompletionRequest::cache_points`]
635    /// for `model`: OpenAI's own API, from GPT-5.6 on.
636    fn marks_cache_points(&self, model: &str) -> bool {
637        self.provider.dialect.name == super::wire::OPENAI.name
638            && super::options::caches_by_options(&self.facts, model)
639    }
640}
641
642/// Mark the end of each prefix in `ends` (item counts of `items`) with a
643/// `prompt_cache_breakpoint` on the last input part at or before it. The
644/// first `held` items are the caller's and are never changed. Every point
645/// is marked: the provider writes the latest few and looks up the rest.
646fn mark_cache_points(items: &mut [Value], held: usize, ends: impl Iterator<Item = usize>) {
647    for end in ends {
648        let last = (held..end.min(items.len()))
649            .rev()
650            .find(|at| items.get(*at).is_some_and(markable));
651        if let Some(item) = last.and_then(|at| items.get_mut(at)) {
652            mark(item);
653        }
654    }
655}
656
657/// The field of `item` holding input parts that can carry a breakpoint: a
658/// user, system or developer message's content, or a tool's output.
659fn parts_field(item: &Value) -> Option<&'static str> {
660    match item.str("type") {
661        Some("message") if item.str("role") != Some("assistant") => Some("content"),
662        Some("function_call_output" | "custom_tool_call_output") => Some("output"),
663        _ => None,
664    }
665}
666
667/// Whether `part` is an input part that takes a breakpoint.
668fn takes_breakpoint(part: &Value) -> bool {
669    part.str("type")
670        .is_some_and(|kind| ["input_text", "input_image", "input_file"].contains(&kind))
671}
672
673/// The parts of `item` that take a breakpoint. A string `content` has none.
674fn breakpoint_parts(item: &Value) -> impl Iterator<Item = &Value> {
675    parts_field(item)
676        .and_then(|field| item.get(field))
677        .and_then(Value::as_array)
678        .into_iter()
679        .flatten()
680        .filter(|part| takes_breakpoint(part))
681}
682
683/// Whether `item` can carry a breakpoint: it has a part that takes one, or
684/// is a tool output given as one text.
685fn markable(item: &Value) -> bool {
686    breakpoint_parts(item).next().is_some()
687        || (parts_field(item) == Some("output") && item.str("output").is_some())
688}
689
690/// Put a breakpoint on the last part of `item` that takes one. A tool output
691/// given as one text becomes that text's part, which the provider caches as
692/// the same prefix.
693fn mark(item: &mut Value) {
694    if parts_field(item) == Some("output")
695        && let Some(text) = item.str("output").map(str::to_owned)
696    {
697        set(
698            item,
699            "output",
700            json!([{"type": "input_text", "text": text}]),
701        );
702    }
703    parts_field(item)
704        .and_then(|field| item.get_mut(field))
705        .and_then(Value::as_array_mut)
706        .into_iter()
707        .filter_map(|parts| parts.iter_mut().rev().find(|part| takes_breakpoint(part)))
708        .for_each(|part| set(part, "prompt_cache_breakpoint", json!({"mode": "explicit"})));
709}
710
711/// A function or hosted tool available to a Responses request.
712#[derive(Debug, Deserialize, Clone, PartialEq)]
713pub struct ResponsesToolDefinition {
714    /// The type of tool.
715    #[serde(rename = "type")]
716    pub kind: String,
717    /// Tool name
718    #[serde(default)]
719    pub name: String,
720    /// The parameters' JSON schema. A strict function tool keeps to OpenAI's
721    /// strict schema subset.
722    #[serde(default)]
723    pub parameters: serde_json::Value,
724    /// Whether to use strict mode. Disabled by default; opt in with [`Self::with_strict`]
725    /// or [`wire::Responses::with_strict_tools`].
726    ///
727    /// Always serialized on a function tool: the Responses API treats an omitted `strict`
728    /// as "attempt strict mode", so `false` must reach the wire for non-strict tools to
729    /// actually be non-strict. Never serialized on a hosted tool, which answers the field
730    /// with a 400 (`Unknown parameter: 'tools[0].strict'`).
731    #[serde(default, deserialize_with = "json_utils::null_or_default")]
732    pub strict: bool,
733    /// Tool description.
734    #[serde(default, deserialize_with = "json_utils::null_or_default")]
735    pub description: String,
736    /// Additional provider-specific configuration for hosted tools.
737    #[serde(flatten, default)]
738    pub config: Map<String, Value>,
739}
740
741impl Serialize for ResponsesToolDefinition {
742    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
743    where
744        S: Serializer,
745    {
746        use serde::ser::SerializeMap;
747
748        let mut map = serializer.serialize_map(None)?;
749        map.serialize_entry("type", &self.kind)?;
750        if !self.name.is_empty() {
751            map.serialize_entry("name", &self.name)?;
752        }
753        if !self.parameters.is_null() {
754            map.serialize_entry("parameters", &self.parameters)?;
755        }
756        if self.kind == "function" {
757            map.serialize_entry("strict", &self.strict)?;
758        }
759        if !self.description.is_empty() {
760            map.serialize_entry("description", &self.description)?;
761        }
762        for (key, value) in &self.config {
763            map.serialize_entry(key, value)?;
764        }
765        map.end()
766    }
767}
768
769impl ResponsesToolDefinition {
770    /// Creates a function tool definition with strict mode disabled.
771    pub fn function(
772        name: impl Into<String>,
773        description: impl Into<String>,
774        parameters: serde_json::Value,
775    ) -> Self {
776        Self {
777            kind: "function".to_string(),
778            name: name.into(),
779            parameters,
780            strict: false,
781            description: description.into(),
782            config: Map::new(),
783        }
784    }
785
786    /// Creates a strict function tool definition.
787    ///
788    /// The schema is sanitized to OpenAI's strict subset (`additionalProperties: false`
789    /// added and every property forced into `required`).
790    pub fn strict_function(
791        name: impl Into<String>,
792        description: impl Into<String>,
793        parameters: serde_json::Value,
794    ) -> Self {
795        Self::function(name, description, parameters).with_strict()
796    }
797
798    /// Enables strict mode for this function tool.
799    ///
800    /// Function schemas are sanitized to OpenAI's strict subset. Hosted tools are
801    /// returned unchanged because strict mode only applies to function tools.
802    pub fn with_strict(mut self) -> Self {
803        if self.kind == "function" {
804            super::sanitize_schema(&mut self.parameters);
805            self.strict = true;
806        }
807        self
808    }
809
810    /// Creates a hosted tool definition for an arbitrary hosted tool type.
811    pub fn hosted(kind: impl Into<String>) -> Self {
812        Self {
813            kind: kind.into(),
814            name: String::new(),
815            parameters: Value::Null,
816            strict: false,
817            description: String::new(),
818            config: Map::new(),
819        }
820    }
821
822    /// Creates a hosted `web_search` tool definition.
823    pub fn web_search() -> Self {
824        Self::hosted("web_search")
825    }
826
827    /// Creates a hosted `file_search` tool definition.
828    pub fn file_search() -> Self {
829        Self::hosted("file_search")
830    }
831
832    /// Creates a hosted `computer_use` tool definition.
833    pub fn computer_use() -> Self {
834        Self::hosted("computer_use")
835    }
836
837    /// Adds hosted-tool configuration fields.
838    pub fn with_config(mut self, key: impl Into<String>, value: Value) -> Self {
839        self.config.insert(key.into(), value);
840        self
841    }
842}
843
844impl From<completion::ToolDefinition> for ResponsesToolDefinition {
845    fn from(value: completion::ToolDefinition) -> Self {
846        // The annotations are the host's: never sent.
847        let completion::ToolDefinition {
848            name,
849            parameters,
850            description,
851            annotations: _,
852        } = value;
853
854        Self::function(name, description, parameters)
855    }
856}
857
858/// Controls where Rig system instructions are placed in an OpenAI Responses request.
859///
860/// Serialized because it is a field of the [`wire::Responses`] wire, which is
861/// data a host may store.
862#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
863#[serde(rename_all = "snake_case")]
864pub enum SystemInstructionsPlacement {
865    /// Send the leading run of system instructions (the preamble and any system
866    /// messages that open the conversation) through the official top-level
867    /// `instructions` field. Mid-conversation system messages keep their
868    /// position in `input`.
869    #[default]
870    Instructions,
871    /// Send every system message through the top-level `instructions` field,
872    /// including mid-conversation ones.
873    ///
874    /// Use this for backends that reject the `system` role in `input` entirely.
875    AllInstructions,
876    /// Send system instructions as `system` messages in `input`.
877    ///
878    /// Use this only for OpenAI-compatible providers that do not support top-level
879    /// `instructions`.
880    InputSystemMessages,
881}
882
883#[cfg(test)]
884mod history_tests;
885#[cfg(test)]
886mod tests;