Skip to main content

switchyard_llm_client/
openai_decisions.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! OpenAI Decisions calls using the provider-neutral decision IR.
5
6use std::collections::BTreeMap;
7use std::time::Duration;
8
9use async_trait::async_trait;
10use reqwest::{Url, header::HeaderValue};
11use serde::Deserialize;
12use serde_json::{Value, json};
13use switchyard_protocol::{
14    BooleanEstimate, DecisionAnswer, DecisionKind, DecisionRequest, DecisionResponse,
15    DecisionValue, ModelId, Probability, ProviderConfidence, RoutedDecisionClient, ScoreValue,
16    Usage,
17};
18
19use crate::client::convert_reqwest_error;
20use crate::{LlmClientError, Result, metrics};
21
22/// Serves typed questions through OpenAI's Decisions API.
23pub struct OpenAiDecisionClient {
24    client: reqwest::Client,
25    endpoint: Url,
26    api_key: String,
27}
28
29impl OpenAiDecisionClient {
30    /// `endpoint` includes `/v1/decisions`. Each call makes one attempt, with
31    /// `timeout` covering both the request and response body.
32    pub fn new(endpoint: Url, api_key: String, timeout: Duration) -> Result<Self> {
33        if HeaderValue::try_from(format!("Bearer {api_key}")).is_err() {
34            return Err(LlmClientError::Configuration {
35                message: "OpenAI Decisions API key cannot be encoded as an HTTP header".into(),
36            });
37        }
38        let client = reqwest::Client::builder()
39            .timeout(timeout)
40            .redirect(reqwest::redirect::Policy::none())
41            .build()
42            .map_err(convert_reqwest_error)?;
43        Ok(Self {
44            client,
45            endpoint,
46            api_key,
47        })
48    }
49}
50
51#[async_trait]
52impl RoutedDecisionClient for OpenAiDecisionClient {
53    async fn call(&self, request: DecisionRequest) -> Result<DecisionResponse> {
54        let builder = self
55            .client
56            .post(self.endpoint.clone())
57            .bearer_auth(&self.api_key)
58            .json(&encode(&request)?);
59        let mut response = async {
60            let request = builder.build()?;
61            if let Some(body) = request.body().and_then(reqwest::Body::as_bytes) {
62                crate::payload_capture::record("request", || String::from_utf8_lossy(body));
63            }
64            self.client.execute(request).await
65        }
66        .await
67        .inspect_err(|_| metrics::record_upstream_attempt(None))
68        .map_err(convert_reqwest_error)?;
69        let status = response.status();
70        let headers = std::mem::take(response.headers_mut());
71        let body = response
72            .bytes()
73            .await
74            .inspect_err(|_| metrics::record_upstream_attempt(None))
75            .map_err(convert_reqwest_error)?;
76        metrics::record_upstream_attempt(Some(status.as_u16()));
77        if !status.is_success() {
78            return Err(LlmClientError::UpstreamHttp {
79                status,
80                body: String::from_utf8_lossy(&body).replace(&self.api_key, "[REDACTED]"),
81                headers: Box::new(headers),
82            });
83        }
84        crate::payload_capture::record("response", || String::from_utf8_lossy(&body));
85        let response: WireResponse =
86            serde_json::from_slice(&body).map_err(|source| LlmClientError::InvalidResponse {
87                source: Box::new(source),
88            })?;
89        let mut questions = request.questions;
90        let mut answers = BTreeMap::new();
91        for answer in response.answers {
92            let invalid = || {
93                LlmClientError::ResponseTranslation(format!(
94                    "OpenAI Decisions answer {:?} has an unexpected question name, kind, or value",
95                    answer.name,
96                ))
97            };
98            let question = questions.remove(&answer.name).ok_or_else(invalid)?;
99            let value = match (&question.kind, answer.value) {
100                (DecisionKind::Boolean { .. }, WireValue::Predicate { probability }) => {
101                    DecisionValue::Boolean(BooleanEstimate::ProbabilityTrue(probability))
102                }
103                (
104                    DecisionKind::Choice { options },
105                    WireValue::Choice {
106                        choice,
107                        probabilities,
108                    },
109                ) => {
110                    let count = probabilities.len();
111                    let probabilities: BTreeMap<_, _> = probabilities
112                        .into_iter()
113                        .map(|p| (p.value, p.probability))
114                        .collect();
115                    if count != options.len()
116                        || probabilities.len() != options.len()
117                        || !options.iter().any(|option| option.id == choice)
118                        || options
119                            .iter()
120                            .any(|option| !probabilities.contains_key(&option.id))
121                    {
122                        return Err(invalid());
123                    }
124                    DecisionValue::Choice {
125                        selected: choice,
126                        probabilities: Some(probabilities),
127                    }
128                }
129                (
130                    DecisionKind::Score { levels },
131                    WireValue::Score {
132                        score,
133                        probabilities,
134                    },
135                ) => {
136                    let mut probabilities = probabilities;
137                    probabilities.sort_by_key(|p| p.value);
138                    if levels.is_empty()
139                        || !(0.0..=(levels.len() - 1) as f64).contains(&score.0)
140                        || probabilities.len() != levels.len()
141                        || probabilities
142                            .iter()
143                            .enumerate()
144                            .any(|(index, p)| p.value != index)
145                    {
146                        return Err(invalid());
147                    }
148                    DecisionValue::Score {
149                        value: score,
150                        probabilities: Some(
151                            probabilities.into_iter().map(|p| p.probability).collect(),
152                        ),
153                    }
154                }
155                (_, WireValue::Refusal) => {
156                    return Err(LlmClientError::ResponseTranslation(format!(
157                        "OpenAI Decisions refused question {:?}",
158                        answer.name,
159                    )));
160                }
161                _ => return Err(invalid()),
162            };
163            answers.insert(
164                answer.name,
165                DecisionAnswer {
166                    value,
167                    provider_confidence: answer.confidence,
168                },
169            );
170        }
171        if !questions.is_empty() {
172            return Err(LlmClientError::ResponseTranslation(
173                "OpenAI Decisions answer names do not match the requested question keys".into(),
174            ));
175        }
176        let usage = response.usage;
177        let cached = usage.input_tokens_details.cached_tokens;
178        let created = usage.input_tokens_details.cache_write_tokens;
179        Ok(DecisionResponse {
180            id: None,
181            model: Some(response.model),
182            answers,
183            usage: Usage {
184                input_tokens: Some(
185                    usage
186                        .input_tokens
187                        .saturating_sub(cached)
188                        .saturating_sub(created),
189                ),
190                cache: Usage::cache_details(Some(cached), Some(created)),
191                output_tokens: Some(usage.output_tokens),
192                total_tokens: Some(usage.total_tokens),
193                reasoning_tokens: Some(usage.output_tokens_details.reasoning_tokens),
194                ..Usage::default()
195            },
196        })
197    }
198}
199
200fn encode(request: &DecisionRequest) -> Result<Value> {
201    let model = request
202        .model
203        .as_ref()
204        .ok_or_else(|| LlmClientError::InvalidRequest {
205            message: "OpenAI Decisions requires a selected model".into(),
206        })?;
207    let questions: Vec<_> = request
208        .questions
209        .iter()
210        .map(|(name, question)| {
211            let mut wire = json!({"name": name, "instructions": text(&question.instructions)});
212            match &question.kind {
213                DecisionKind::Boolean {
214                    true_description,
215                    false_description,
216                } => {
217                    wire["type"] = json!("predicate");
218                    if true_description.is_some() || false_description.is_some() {
219                        wire["instructions"] = json!(
220                            json!({
221                                "instructions": question.instructions,
222                                "true": true_description, "false": false_description,
223                            })
224                            .to_string()
225                        );
226                    }
227                }
228                DecisionKind::Choice { options } => {
229                    wire["type"] = json!("choice");
230                    wire["choices"] = Value::Array(
231                        options
232                            .iter()
233                            .map(|option| {
234                                let mut choice = json!({"value": option.id});
235                                if let Some(description) = &option.description {
236                                    choice["description"] = json!(text(description));
237                                }
238                                choice
239                            })
240                            .collect(),
241                    );
242                }
243                DecisionKind::Score { levels } => {
244                    wire["type"] = json!("score");
245                    wire["levels"] = Value::Array(
246                        levels
247                            .iter()
248                            .map(|level| json!({"label": text(level)}))
249                            .collect(),
250                    );
251                }
252            }
253            wire
254        })
255        .collect();
256    // OpenAI Decisions accepts a string or its own message items. Sending the
257    // input as text avoids translating each message and tool block.
258    Ok(json!({"model": model, "input": text(&request.input), "questions": questions}))
259}
260
261// OpenAI requires text; retain structured IR content as JSON rather than dropping it.
262fn text(value: &Value) -> String {
263    value
264        .as_str()
265        .map(str::to_owned)
266        .unwrap_or_else(|| value.to_string())
267}
268
269#[derive(Deserialize)]
270struct WireResponse {
271    model: ModelId,
272    answers: Vec<WireAnswer>,
273    usage: WireUsage,
274}
275
276#[derive(Deserialize)]
277struct WireAnswer {
278    name: String,
279    #[serde(flatten)]
280    value: WireValue,
281    confidence: Option<ProviderConfidence>,
282}
283
284#[derive(Deserialize)]
285#[serde(tag = "type", rename_all = "snake_case")]
286enum WireValue {
287    Predicate {
288        probability: Probability,
289    },
290    Choice {
291        choice: String,
292        probabilities: Vec<WireProbability<String>>,
293    },
294    Score {
295        score: ScoreValue,
296        probabilities: Vec<WireProbability<usize>>,
297    },
298    Refusal,
299}
300
301#[derive(Deserialize)]
302struct WireProbability<T> {
303    value: T,
304    probability: Probability,
305}
306
307#[derive(Deserialize)]
308struct WireUsage {
309    input_tokens: u64,
310    output_tokens: u64,
311    total_tokens: u64,
312    input_tokens_details: InputTokenDetails,
313    output_tokens_details: OutputTokenDetails,
314}
315
316#[derive(Deserialize)]
317struct InputTokenDetails {
318    cached_tokens: u64,
319    cache_write_tokens: u64,
320}
321
322#[derive(Deserialize)]
323struct OutputTokenDetails {
324    reasoning_tokens: u64,
325}