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 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 body = response
71            .bytes()
72            .await
73            .inspect_err(|_| metrics::record_upstream_attempt(None))
74            .map_err(convert_reqwest_error)?;
75        metrics::record_upstream_attempt(Some(status.as_u16()));
76        if !status.is_success() {
77            return Err(LlmClientError::UpstreamHttp {
78                status,
79                body: String::from_utf8_lossy(&body).replace(&self.api_key, "[REDACTED]"),
80            });
81        }
82        crate::payload_capture::record("response", || String::from_utf8_lossy(&body));
83        let response: WireResponse =
84            serde_json::from_slice(&body).map_err(|source| LlmClientError::InvalidResponse {
85                source: Box::new(source),
86            })?;
87        let mut questions = request.questions;
88        let mut answers = BTreeMap::new();
89        for answer in response.answers {
90            let invalid = || {
91                LlmClientError::ResponseTranslation(format!(
92                    "OpenAI Decisions answer {:?} has an unexpected question name, kind, or value",
93                    answer.name,
94                ))
95            };
96            let question = questions.remove(&answer.name).ok_or_else(invalid)?;
97            let value = match (&question.kind, answer.value) {
98                (DecisionKind::Boolean { .. }, WireValue::Predicate { probability }) => {
99                    DecisionValue::Boolean(BooleanEstimate::ProbabilityTrue(probability))
100                }
101                (
102                    DecisionKind::Choice { options },
103                    WireValue::Choice {
104                        choice,
105                        probabilities,
106                    },
107                ) => {
108                    let count = probabilities.len();
109                    let probabilities: BTreeMap<_, _> = probabilities
110                        .into_iter()
111                        .map(|p| (p.value, p.probability))
112                        .collect();
113                    if count != options.len()
114                        || probabilities.len() != options.len()
115                        || !options.iter().any(|option| option.id == choice)
116                        || options
117                            .iter()
118                            .any(|option| !probabilities.contains_key(&option.id))
119                    {
120                        return Err(invalid());
121                    }
122                    DecisionValue::Choice {
123                        selected: choice,
124                        probabilities: Some(probabilities),
125                    }
126                }
127                (
128                    DecisionKind::Score { levels },
129                    WireValue::Score {
130                        score,
131                        probabilities,
132                    },
133                ) => {
134                    let mut probabilities = probabilities;
135                    probabilities.sort_by_key(|p| p.value);
136                    if levels.is_empty()
137                        || !(0.0..=(levels.len() - 1) as f64).contains(&score.0)
138                        || probabilities.len() != levels.len()
139                        || probabilities
140                            .iter()
141                            .enumerate()
142                            .any(|(index, p)| p.value != index)
143                    {
144                        return Err(invalid());
145                    }
146                    DecisionValue::Score {
147                        value: score,
148                        probabilities: Some(
149                            probabilities.into_iter().map(|p| p.probability).collect(),
150                        ),
151                    }
152                }
153                (_, WireValue::Refusal) => {
154                    return Err(LlmClientError::ResponseTranslation(format!(
155                        "OpenAI Decisions refused question {:?}",
156                        answer.name,
157                    )));
158                }
159                _ => return Err(invalid()),
160            };
161            answers.insert(
162                answer.name,
163                DecisionAnswer {
164                    value,
165                    provider_confidence: answer.confidence,
166                },
167            );
168        }
169        if !questions.is_empty() {
170            return Err(LlmClientError::ResponseTranslation(
171                "OpenAI Decisions answer names do not match the requested question keys".into(),
172            ));
173        }
174        let usage = response.usage;
175        let cached = usage.input_tokens_details.cached_tokens;
176        let created = usage.input_tokens_details.cache_write_tokens;
177        Ok(DecisionResponse {
178            id: None,
179            model: Some(response.model),
180            answers,
181            usage: Usage {
182                input_tokens: Some(
183                    usage
184                        .input_tokens
185                        .saturating_sub(cached)
186                        .saturating_sub(created),
187                ),
188                cache: Usage::cache_details(Some(cached), Some(created)),
189                output_tokens: Some(usage.output_tokens),
190                total_tokens: Some(usage.total_tokens),
191                reasoning_tokens: Some(usage.output_tokens_details.reasoning_tokens),
192                ..Usage::default()
193            },
194        })
195    }
196}
197
198fn encode(request: &DecisionRequest) -> Result<Value> {
199    let model = request
200        .model
201        .as_ref()
202        .ok_or_else(|| LlmClientError::InvalidRequest {
203            message: "OpenAI Decisions requires a selected model".into(),
204        })?;
205    let questions: Vec<_> = request
206        .questions
207        .iter()
208        .map(|(name, question)| {
209            let mut wire = json!({"name": name, "instructions": text(&question.instructions)});
210            match &question.kind {
211                DecisionKind::Boolean {
212                    true_description,
213                    false_description,
214                } => {
215                    wire["type"] = json!("predicate");
216                    if true_description.is_some() || false_description.is_some() {
217                        wire["instructions"] = json!(
218                            json!({
219                                "instructions": question.instructions,
220                                "true": true_description, "false": false_description,
221                            })
222                            .to_string()
223                        );
224                    }
225                }
226                DecisionKind::Choice { options } => {
227                    wire["type"] = json!("choice");
228                    wire["choices"] = Value::Array(
229                        options
230                            .iter()
231                            .map(|option| {
232                                let mut choice = json!({"value": option.id});
233                                if let Some(description) = &option.description {
234                                    choice["description"] = json!(text(description));
235                                }
236                                choice
237                            })
238                            .collect(),
239                    );
240                }
241                DecisionKind::Score { levels } => {
242                    wire["type"] = json!("score");
243                    wire["levels"] = Value::Array(
244                        levels
245                            .iter()
246                            .map(|level| json!({"label": text(level)}))
247                            .collect(),
248                    );
249                }
250            }
251            wire
252        })
253        .collect();
254    // OpenAI Decisions accepts a string or its own message items. Sending the
255    // input as text avoids translating each message and tool block.
256    Ok(json!({"model": model, "input": text(&request.input), "questions": questions}))
257}
258
259// OpenAI requires text; retain structured IR content as JSON rather than dropping it.
260fn text(value: &Value) -> String {
261    value
262        .as_str()
263        .map(str::to_owned)
264        .unwrap_or_else(|| value.to_string())
265}
266
267#[derive(Deserialize)]
268struct WireResponse {
269    model: ModelId,
270    answers: Vec<WireAnswer>,
271    usage: WireUsage,
272}
273
274#[derive(Deserialize)]
275struct WireAnswer {
276    name: String,
277    #[serde(flatten)]
278    value: WireValue,
279    confidence: Option<ProviderConfidence>,
280}
281
282#[derive(Deserialize)]
283#[serde(tag = "type", rename_all = "snake_case")]
284enum WireValue {
285    Predicate {
286        probability: Probability,
287    },
288    Choice {
289        choice: String,
290        probabilities: Vec<WireProbability<String>>,
291    },
292    Score {
293        score: ScoreValue,
294        probabilities: Vec<WireProbability<usize>>,
295    },
296    Refusal,
297}
298
299#[derive(Deserialize)]
300struct WireProbability<T> {
301    value: T,
302    probability: Probability,
303}
304
305#[derive(Deserialize)]
306struct WireUsage {
307    input_tokens: u64,
308    output_tokens: u64,
309    total_tokens: u64,
310    input_tokens_details: InputTokenDetails,
311    output_tokens_details: OutputTokenDetails,
312}
313
314#[derive(Deserialize)]
315struct InputTokenDetails {
316    cached_tokens: u64,
317    cache_write_tokens: u64,
318}
319
320#[derive(Deserialize)]
321struct OutputTokenDetails {
322    reasoning_tokens: u64,
323}