Skip to main content

agent_framework_openai/
lib.rs

1//! # agent-framework-openai
2//!
3//! An OpenAI (and OpenAI-compatible) [`ChatClient`] for `agent-framework-rs`.
4//!
5//! Works against the OpenAI Chat Completions API and any compatible endpoint
6//! (Azure OpenAI, Ollama, together.ai, local servers, …) by overriding the
7//! base URL.
8//!
9//! ```no_run
10//! use agent_framework_openai::OpenAIChatCompletionClient;
11//! use agent_framework_core::prelude::*;
12//!
13//! # async fn demo() -> Result<()> {
14//! let client = OpenAIChatCompletionClient::new("sk-...", "gpt-4o-mini");
15//! let agent = Agent::builder(client)
16//!     .instructions("You are concise.")
17//!     .build();
18//! let reply = agent.run_once("Say hi").await?;
19//! println!("{}", reply.text());
20//! # Ok(())
21//! # }
22//! ```
23
24/// Conversion between framework types and the OpenAI chat-completions wire
25/// format.
26///
27/// This module is public (but hidden from docs) so that other
28/// OpenAI-wire-compatible clients in this workspace — currently
29/// `agent-framework-azure` — can reuse request/response conversion instead of
30/// duplicating it. It is not intended as a stable external API.
31#[doc(hidden)]
32pub mod convert;
33pub mod embeddings;
34
35pub mod responses;
36pub use embeddings::OpenAIEmbeddingClient;
37pub use responses::OpenAIChatClient;
38
39use std::collections::{HashMap, VecDeque};
40use std::sync::Arc;
41
42use agent_framework_core::client::{ChatClient, ChatStream};
43use agent_framework_core::error::{ContentFilterCategory, ContentFilterDetail, Error, Result};
44use agent_framework_core::streaming::Utf8StreamDecoder;
45use agent_framework_core::types::{
46    ChatOptions, ChatResponse, ChatResponseUpdate, Content, FinishReason, FunctionArguments,
47    FunctionCallContent, Message, Role, TextContent, UsageContent,
48};
49use futures::StreamExt;
50use serde_json::{json, Map, Value};
51
52pub(crate) const DEFAULT_BASE_URL: &str = "https://api.openai.com/v1";
53
54/// Parse a `Retry-After` header into a delay in seconds.
55///
56/// HTTP allows either a delay in seconds or an HTTP-date; OpenAI (and other
57/// rate limiters) use the integer/decimal-seconds form for `429`/`503`, which
58/// is what we honor. A date-form or unparseable value is treated as absent.
59/// Shared with [`responses`](crate::responses) so both OpenAI clients attach
60/// the same retry hint to [`Error::ServiceStatus`].
61pub(crate) fn parse_retry_after(headers: &reqwest::header::HeaderMap) -> Option<f64> {
62    headers
63        .get(reqwest::header::RETRY_AFTER)
64        .and_then(|v| v.to_str().ok())
65        .and_then(|s| s.trim().parse::<f64>().ok())
66        .filter(|s| s.is_finite() && *s >= 0.0)
67}
68
69/// Classify a non-success OpenAI-wire (Chat Completions / Responses) HTTP
70/// response into a granular [`Error`].
71///
72/// The single point of truth for status/body interpretation, used by every
73/// endpoint in this crate (`OpenAIChatCompletionClient::post` and [`responses`]) and reused
74/// by `agent-framework-azure` (Azure OpenAI is
75/// wire-compatible for Chat Completions and Responses), so the two stay
76/// identical rather than drifting.
77///
78/// Mirrors upstream's `openai/_chat_client.py` / `_responses_client.py`:
79///
80/// ```text
81/// except BadRequestError as ex:
82///     if ex.code == "content_filter":
83///         raise OpenAIContentFilterException(...)
84///     raise ServiceResponseException(...)
85/// ```
86///
87/// for the content-filter case, and extends upstream's exception
88/// *hierarchy* — `ServiceInvalidAuthError` / `ServiceInvalidRequestError`
89/// already exist in `agent_framework.exceptions`, even though today's Python
90/// OpenAI client folds every other status (auth failures included) into that
91/// same generic `ServiceResponseException` — to also classify by HTTP status:
92///
93/// * `401` / `403` -> [`Error::ServiceInvalidAuth`]
94/// * `400` / `404` / `422` -> [`Error::ServiceInvalidRequest`], unless the
95///   body signals a content-filter refusal (`error.code` or `error.type` ==
96///   `"content_filter"`, checked at the top level and inside a nested
97///   `innererror` for Azure OpenAI's shape) -> [`Error::ServiceContentFilter`]
98/// * anything else — notably `408` / `429` / `5xx`, which
99///   [`RetryOn::Default`](agent_framework_core::client::RetryOn::Default)
100///   depends on — -> [`Error::ServiceStatus`], unchanged
101///
102/// `body` is parsed leniently as JSON purely to look for the content-filter
103/// marker; a non-JSON or differently-shaped body just skips that check and
104/// falls through to the plain status-based classification, so this never
105/// panics or itself errors. `message` is used verbatim as the resulting
106/// error's text (callers already format a provider-specific "OpenAI API
107/// error 400: ..." string; this only picks the variant).
108pub fn classify_service_error(
109    status: u16,
110    body: &str,
111    message: impl Into<String>,
112    retry_after: Option<f64>,
113) -> Error {
114    let message = message.into();
115    match status {
116        401 | 403 => Error::service_invalid_auth(message),
117        400 | 404 | 422 => {
118            if body_signals_content_filter(body) {
119                match parse_content_filter_detail(body) {
120                    Some(detail) => Error::service_content_filter_with_detail(message, detail),
121                    None => Error::service_content_filter(message),
122                }
123            } else {
124                Error::service_invalid_request(message)
125            }
126        }
127        _ => Error::service_status(status, message, retry_after),
128    }
129}
130
131/// Whether an OpenAI/Azure-OpenAI-shaped error body signals a content-filter
132/// refusal.
133///
134/// Checks `error.code` — the field the OpenAI Python SDK's
135/// `BadRequestError.code` reads, and what upstream compares against
136/// `"content_filter"` — tolerantly falling back to `error.type` and to Azure
137/// OpenAI's nested `error.innererror` (`code`/`type`), since a
138/// `"content_filter"` marker has been observed in slightly different spots
139/// across OpenAI-wire-compatible providers. A non-JSON or unrecognized body
140/// shape is treated as "not a content filter" rather than erroring.
141fn body_signals_content_filter(body: &str) -> bool {
142    let Ok(value) = serde_json::from_str::<Value>(body) else {
143        return false;
144    };
145    let error = value.get("error").unwrap_or(&value);
146    is_content_filter_marker(error)
147        || error
148            .get("innererror")
149            .is_some_and(is_content_filter_marker)
150}
151
152/// Read Azure OpenAI's content-filter breakdown out of an error body.
153///
154/// Azure answers a filtered request with a nested `innererror` naming the
155/// policy that fired (`ResponsibleAIPolicyViolation`, `ContentFiltered`) and a
156/// `content_filter_result` map of category verdicts. Without it the caller has
157/// a message string and cannot tell a self-harm block from a jailbreak
158/// detection, or an input block from an output one — the distinctions an
159/// application acts on.
160///
161/// Returns `None` when the body carries nothing beyond the marker, so a plain
162/// OpenAI content-filter refusal stays a plain error rather than growing an
163/// empty detail. Every value is copied through verbatim: unlike upstream's
164/// enums, a code or severity Azure has not shipped yet arrives as itself
165/// instead of raising while classifying an error (upstream #8393 fixed that
166/// for the code; its severity parse still has it).
167fn parse_content_filter_detail(body: &str) -> Option<ContentFilterDetail> {
168    let value = serde_json::from_str::<Value>(body).ok()?;
169    let error = value.get("error").unwrap_or(&value);
170    let inner = error.get("innererror");
171
172    let code = inner
173        .and_then(|i| i.get("code"))
174        .or_else(|| inner.and_then(|i| i.get("type")))
175        .and_then(Value::as_str)
176        // The outer code is the *marker* (`content_filter`), not the policy,
177        // so it is never read as one.
178        .filter(|c| *c != CONTENT_FILTER_MARKER)
179        .map(String::from);
180    let param = error
181        .get("param")
182        .and_then(Value::as_str)
183        .filter(|p| !p.is_empty())
184        .map(String::from);
185
186    let mut categories = std::collections::BTreeMap::new();
187    let results = inner
188        .and_then(|i| i.get("content_filter_result"))
189        .or_else(|| error.get("content_filter_result"))
190        .and_then(Value::as_object);
191    if let Some(results) = results {
192        for (name, verdict) in results {
193            let Some(verdict) = verdict.as_object() else {
194                continue;
195            };
196            categories.insert(
197                name.clone(),
198                ContentFilterCategory {
199                    filtered: verdict
200                        .get("filtered")
201                        .and_then(Value::as_bool)
202                        .unwrap_or(false),
203                    detected: verdict.get("detected").and_then(Value::as_bool),
204                    severity: verdict
205                        .get("severity")
206                        .and_then(Value::as_str)
207                        .map(String::from),
208                },
209            );
210        }
211    }
212
213    if code.is_none() && param.is_none() && categories.is_empty() {
214        return None;
215    }
216    Some(ContentFilterDetail {
217        code,
218        param,
219        categories,
220    })
221}
222
223/// The wire marker that classifies an error as a content-filter refusal, as
224/// opposed to the *policy* code beside it.
225const CONTENT_FILTER_MARKER: &str = "content_filter";
226
227fn is_content_filter_marker(v: &Value) -> bool {
228    v.get("code").and_then(Value::as_str) == Some(CONTENT_FILTER_MARKER)
229        || v.get("type").and_then(Value::as_str) == Some(CONTENT_FILTER_MARKER)
230}
231
232/// An OpenAI (or OpenAI-compatible) chat client.
233#[derive(Clone)]
234pub struct OpenAIChatCompletionClient {
235    inner: Arc<Inner>,
236}
237
238#[derive(Clone)]
239struct Inner {
240    http: reqwest::Client,
241    api_key: String,
242    base_url: String,
243    model: String,
244    organization: Option<String>,
245}
246
247impl OpenAIChatCompletionClient {
248    /// Create a client for the given API key and default model.
249    pub fn new(api_key: impl Into<String>, model: impl Into<String>) -> Self {
250        Self {
251            inner: Arc::new(Inner {
252                http: reqwest::Client::new(),
253                api_key: api_key.into(),
254                base_url: DEFAULT_BASE_URL.to_string(),
255                model: model.into(),
256                organization: None,
257            }),
258        }
259    }
260
261    /// Build a client from the `OPENAI_API_KEY` (and optional
262    /// `OPENAI_BASE_URL`) environment variables.
263    pub fn from_env(model: impl Into<String>) -> Result<Self> {
264        let key = std::env::var("OPENAI_API_KEY")
265            .map_err(|_| Error::Configuration("OPENAI_API_KEY is not set".into()))?;
266        let mut client = Self::new(key, model);
267        if let Ok(base) = std::env::var("OPENAI_BASE_URL") {
268            client = client.with_base_url(base);
269        }
270        Ok(client)
271    }
272
273    /// Override the base URL (for Azure OpenAI or compatible servers).
274    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
275        Arc::make_mut(&mut self.inner).base_url = base_url.into();
276        self
277    }
278
279    /// Set the organization header.
280    pub fn with_organization(mut self, org: impl Into<String>) -> Self {
281        Arc::make_mut(&mut self.inner).organization = Some(org.into());
282        self
283    }
284
285    fn build_body(&self, messages: &[Message], options: &ChatOptions, stream: bool) -> Value {
286        let mut body = Map::new();
287        let model = options
288            .model
289            .clone()
290            .unwrap_or_else(|| self.inner.model.clone());
291        body.insert("model".into(), json!(model));
292        body.insert(
293            "messages".into(),
294            json!(convert::messages_to_openai(messages)),
295        );
296        convert::apply_options(&mut body, options);
297        let (tools, tool_choice) = convert::tools_to_openai(options);
298        if let Some(tools) = tools {
299            body.insert("tools".into(), tools);
300        }
301        if let Some(choice) = tool_choice {
302            body.insert("tool_choice".into(), choice);
303        }
304        if stream {
305            body.insert("stream".into(), json!(true));
306            body.insert("stream_options".into(), json!({ "include_usage": true }));
307        }
308        Value::Object(body)
309    }
310
311    async fn post(&self, body: &Value) -> Result<reqwest::Response> {
312        let url = format!(
313            "{}/chat/completions",
314            self.inner.base_url.trim_end_matches('/')
315        );
316        let mut req = self
317            .inner
318            .http
319            .post(&url)
320            .bearer_auth(&self.inner.api_key)
321            .json(body);
322        if let Some(org) = &self.inner.organization {
323            req = req.header("OpenAI-Organization", org);
324        }
325        let resp = req
326            .send()
327            .await
328            .map_err(|e| Error::service(format!("request failed: {e}")))?;
329        if !resp.status().is_success() {
330            let status = resp.status();
331            let retry_after = parse_retry_after(resp.headers());
332            let text = resp.text().await.unwrap_or_default();
333            return Err(classify_service_error(
334                status.as_u16(),
335                &text,
336                format!("OpenAI API error {status}: {text}"),
337                retry_after,
338            ));
339        }
340        Ok(resp)
341    }
342
343    /// The default model id.
344    pub fn model(&self) -> &str {
345        &self.inner.model
346    }
347}
348
349#[async_trait::async_trait]
350impl ChatClient for OpenAIChatCompletionClient {
351    async fn get_response(
352        &self,
353        messages: Vec<Message>,
354        options: ChatOptions,
355    ) -> Result<ChatResponse> {
356        let body = self.build_body(&messages, &options, false);
357        let resp = self.post(&body).await?;
358        let value: Value = resp
359            .json()
360            .await
361            .map_err(|e| Error::service(format!("invalid response json: {e}")))?;
362        Ok(convert::parse_response(&value))
363    }
364
365    async fn get_streaming_response(
366        &self,
367        messages: Vec<Message>,
368        options: ChatOptions,
369    ) -> Result<ChatStream> {
370        let body = self.build_body(&messages, &options, true);
371        let resp = self.post(&body).await?;
372        Ok(parse_sse_stream(resp).boxed())
373    }
374
375    fn model(&self) -> Option<&str> {
376        Some(&self.inner.model)
377    }
378}
379
380type ByteStream =
381    std::pin::Pin<Box<dyn futures::Stream<Item = reqwest::Result<bytes::Bytes>> + Send>>;
382
383/// Turn an SSE HTTP response into a stream of [`ChatResponseUpdate`]s.
384///
385/// Public (but hidden) so `agent-framework-azure` can reuse the exact same
386/// chat-completions SSE parsing for Azure OpenAI's wire-compatible stream.
387#[doc(hidden)]
388pub fn parse_sse_stream(
389    resp: reqwest::Response,
390) -> impl futures::Stream<Item = Result<ChatResponseUpdate>> + Send {
391    let byte_stream: ByteStream = Box::pin(resp.bytes_stream());
392    // `tool_ids` maps a streamed tool-call `index` to its `call_id`, so that
393    // continuation chunks (which carry only the index) can be resolved back to
394    // the id assigned in the first chunk.
395    futures::stream::unfold(
396        SseState {
397            byte_stream,
398            buffer: String::new(),
399            utf8: Utf8StreamDecoder::new(),
400            queued: VecDeque::new(),
401            tool_ids: HashMap::new(),
402            logprobs_content: Vec::new(),
403            done: false,
404        },
405        |mut state| async move {
406            loop {
407                if let Some(update) = state.queued.pop_front() {
408                    return Some((Ok(update), state));
409                }
410                if state.done {
411                    return None;
412                }
413                match state.byte_stream.next().await {
414                    Some(Ok(bytes)) => {
415                        let decoded = state.utf8.push(&bytes);
416                        state.buffer.push_str(&decoded);
417                        while let Some(pos) = state.buffer.find('\n') {
418                            let line = state.buffer[..pos].trim().to_string();
419                            state.buffer.drain(..=pos);
420                            if let Some(data) = line.strip_prefix("data:") {
421                                let data = data.trim();
422                                if data == "[DONE]" {
423                                    return drain_or_end(state);
424                                }
425                                if let Ok(value) = serde_json::from_str::<Value>(data) {
426                                    // Providers signal mid-stream failures (rate
427                                    // limits, content filter, billing) as an
428                                    // object with an `error` field; surface it.
429                                    if let Some(err) = value.get("error") {
430                                        let msg = err
431                                            .get("message")
432                                            .and_then(Value::as_str)
433                                            .unwrap_or("unknown stream error")
434                                            .to_string();
435                                        state.done = true;
436                                        return Some((Err(Error::service(msg)), state));
437                                    }
438                                    if let Some(mut update) =
439                                        parse_delta(&value, &mut state.tool_ids)
440                                    {
441                                        accumulate_logprobs(
442                                            &mut update,
443                                            &mut state.logprobs_content,
444                                        );
445                                        state.queued.push_back(update);
446                                    }
447                                }
448                            }
449                        }
450                    }
451                    Some(Err(e)) => {
452                        state.done = true;
453                        return Some((Err(Error::service(format!("stream error: {e}"))), state));
454                    }
455                    None => return drain_or_end(state),
456                }
457            }
458        },
459    )
460}
461
462/// State carried across `unfold` iterations while parsing the SSE stream.
463struct SseState {
464    byte_stream: ByteStream,
465    buffer: String,
466    utf8: Utf8StreamDecoder,
467    queued: VecDeque<ChatResponseUpdate>,
468    tool_ids: HashMap<i64, String>,
469    /// Every token entry seen under `logprobs.content` so far.
470    ///
471    /// Each chunk reports only its own tokens, and aggregation keeps the last
472    /// value it sees for a given `additional_properties` key — so without
473    /// this a streamed-then-aggregated response would carry the final chunk's
474    /// logprobs alone, where the same request made non-streaming returns
475    /// every token's. Two paths of one client answering the same question
476    /// differently, and silently. The running total is attached to the final
477    /// update (see `finish_logprobs`), which is the one aggregation keeps.
478    logprobs_content: Vec<Value>,
479    done: bool,
480}
481
482fn drain_or_end(mut state: SseState) -> Option<(Result<ChatResponseUpdate>, SseState)> {
483    match state.queued.pop_front() {
484        Some(update) => {
485            state.done = true;
486            Some((Ok(update), state))
487        }
488        None => None,
489    }
490}
491
492/// Fold this chunk's token log-probabilities into the running total, and put
493/// the whole total on the final update.
494///
495/// A chunk's `logprobs` describes only that chunk's tokens. Updates are
496/// aggregated by `ChatResponse::absorb_update`, which inserts whatever an
497/// update has under a given `additional_properties` key — so the last chunk
498/// to carry logprobs would be the only one left in the aggregate, while the
499/// same request made non-streaming returns an entry per token. That gap is
500/// invisible to a caller: the key is present either way, just far emptier.
501///
502/// So each update keeps its own chunk's logprobs (a caller reading the stream
503/// sees the deltas as they arrive, unchanged), and the update carrying
504/// `finish_reason` — the one aggregation ends on — carries the accumulated
505/// `content` array instead. Accumulating on *every* update would cost a full
506/// copy per chunk for no gain.
507///
508/// A deliberate divergence from upstream, which keeps only the most recent
509/// chunk's value in its aggregate (#8997 fixed a null chunk *clearing* that
510/// value, not the narrowing). Matching upstream here would mean shipping the
511/// inconsistency between this client's own two paths.
512fn accumulate_logprobs(update: &mut ChatResponseUpdate, running: &mut Vec<Value>) {
513    let key = convert::LOGPROBS_PROPERTY;
514    if let Some(entries) = update
515        .additional_properties
516        .get(key)
517        .and_then(|v| v.get("content"))
518        .and_then(Value::as_array)
519    {
520        running.extend(entries.iter().cloned());
521    }
522    // `finish_reason` marks the end of the choice, so this is the update whose
523    // value survives aggregation. A stream cut off before it leaves the
524    // per-chunk values in place, which is all that can be known.
525    if update.finish_reason.is_some() && !running.is_empty() {
526        update.additional_properties.insert(
527            key.to_string(),
528            serde_json::json!({ "content": std::mem::take(running) }),
529        );
530    }
531}
532
533/// Parse one streamed chunk (`chat.completion.chunk`) into an update, resolving
534/// tool-call ids from the index map.
535fn parse_delta(value: &Value, tool_ids: &mut HashMap<i64, String>) -> Option<ChatResponseUpdate> {
536    let mut update = ChatResponseUpdate {
537        response_id: value.get("id").and_then(Value::as_str).map(String::from),
538        model: value.get("model").and_then(Value::as_str).map(String::from),
539        ..Default::default()
540    };
541
542    let mut contents: Vec<Content> = Vec::new();
543
544    if let Some(choice) = value
545        .get("choices")
546        .and_then(|c| c.as_array())
547        .and_then(|a| a.first())
548    {
549        if let Some(delta) = choice.get("delta") {
550            if let Some(r) = delta.get("role").and_then(Value::as_str) {
551                update.role = Some(Role::new(r));
552            }
553            if let Some(text) = delta.get("content").and_then(Value::as_str) {
554                if !text.is_empty() {
555                    contents.push(Content::Text(TextContent::new(text)));
556                }
557            }
558            // A streamed refusal arrives on its own `delta.refusal` channel,
559            // fragmented like content. Without this it was dropped outright,
560            // so a streamed decline reached the caller as an empty response —
561            // and the non-streaming path's refusal marking had no streaming
562            // counterpart. Marked, so aggregation keeps it separate from
563            // ordinary text and `Message::text` withholds it.
564            if let Some(text) = delta.get("refusal").and_then(Value::as_str) {
565                if !text.is_empty() {
566                    contents.push(Content::Text(TextContent::refusal(text)));
567                }
568            }
569            // Streamed reasoning payload, on the same channel as the
570            // buffered one. See `convert::reasoning_details_of`.
571            if let Some(reasoning) = crate::convert::parse_reasoning_details(delta) {
572                contents.push(reasoning);
573            }
574            if let Some(calls) = delta.get("tool_calls").and_then(Value::as_array) {
575                for call in calls {
576                    let index = call.get("index").and_then(Value::as_i64).unwrap_or(0);
577                    let chunk_id = call.get("id").and_then(Value::as_str).unwrap_or_default();
578                    // The first chunk of a call carries its id; record it so
579                    // later index-only chunks resolve to the same call_id.
580                    let id = if chunk_id.is_empty() {
581                        tool_ids.get(&index).cloned().unwrap_or_default()
582                    } else {
583                        tool_ids.insert(index, chunk_id.to_string());
584                        chunk_id.to_string()
585                    };
586                    let func = call.get("function");
587                    let name = func
588                        .and_then(|f| f.get("name"))
589                        .and_then(Value::as_str)
590                        .unwrap_or_default()
591                        .to_string();
592                    let args = func
593                        .and_then(|f| f.get("arguments"))
594                        .and_then(Value::as_str)
595                        .unwrap_or_default()
596                        .to_string();
597                    contents.push(Content::FunctionCall(FunctionCallContent::new(
598                        id,
599                        name,
600                        Some(FunctionArguments::Raw(args)),
601                    )));
602                }
603            }
604        }
605        if let Some(fr) = choice.get("finish_reason").and_then(Value::as_str) {
606            update.finish_reason = Some(FinishReason::new(fr));
607        }
608        // Only when the chunk actually carries them. A chunk with
609        // `"logprobs": null` — which OpenAI sends freely mid-stream — must not
610        // overwrite the metadata gathered so far, and omitting the key is how
611        // that holds here: `ChatResponse::absorb_update` inserts only the keys
612        // an update has. See `convert::token_logprobs` (upstream #8997).
613        if let Some(logprobs) = convert::token_logprobs(choice) {
614            update
615                .additional_properties
616                .insert(convert::LOGPROBS_PROPERTY.to_string(), logprobs);
617        }
618    }
619
620    // The final chunk (with `stream_options.include_usage`) carries top-level
621    // `usage` and no choices; surface it so streamed runs accumulate token usage
622    // just like non-streaming responses.
623    if let Some(usage) = value.get("usage").filter(|u| u.is_object()) {
624        contents.push(Content::Usage(UsageContent {
625            details: convert::parse_usage(usage),
626        }));
627    }
628
629    if update.role.is_none() {
630        update.role = Some(Role::assistant());
631    }
632    update.contents = contents;
633    Some(update)
634}
635
636#[cfg(test)]
637mod tests {
638    use super::*;
639
640    // -- classify_service_error --------------------------------------------
641    //
642    // Canned status+body combinations run through the exact classification
643    // `OpenAIChatCompletionClient::post` and `responses::OpenAIChatClient::post`
644    // both delegate to.
645
646    #[test]
647    fn a_streamed_reasoning_payload_survives_to_the_aggregated_response() {
648        // The payload arrives on its own delta channel; the aggregated
649        // response is what the next request is built from, so it has to reach
650        // that far to be replayable at all.
651        let mut ids = HashMap::new();
652        let updates: Vec<_> = [
653            serde_json::json!({"choices": [{"delta": {"role": "assistant",
654                "reasoning_details": [{"type": "reasoning.text", "text": "think"}]}}]}),
655            serde_json::json!({"choices": [{"delta": {"content": "answer"}}]}),
656        ]
657        .iter()
658        .filter_map(|v| parse_delta(v, &mut ids))
659        .collect();
660        let resp = agent_framework_core::types::ChatResponse::from_updates(updates);
661        let wire = crate::convert::messages_to_openai(&resp.messages);
662        assert_eq!(
663            wire[0]["reasoning_details"],
664            serde_json::json!([{"type": "reasoning.text", "text": "think"}])
665        );
666    }
667
668    #[test]
669    fn streamed_logprobs_accumulate_across_chunks_and_survive_a_null_chunk() {
670        // Two things at once. Upstream #8997: a chunk with `"logprobs": null`
671        // — which OpenAI sends freely mid-stream, including on the finish
672        // chunk — must not clear what was gathered. And the aggregate must
673        // end up with *every* token's entry, not just the last chunk's:
674        // the same request made non-streaming returns one entry per token,
675        // and a caller cannot see which it got.
676        let first = serde_json::json!({
677            "content": [{ "token": "hel", "logprob": -0.1 }]
678        });
679        let latest = serde_json::json!({
680            "content": [{ "token": "lo", "logprob": -0.2 }]
681        });
682        let mut ids = HashMap::new();
683        let mut running = Vec::new();
684        let updates: Vec<_> = [
685            serde_json::json!({"choices": [{"delta": {"role": "assistant", "content": "hel"},
686                "logprobs": first}]}),
687            serde_json::json!({"choices": [{"delta": {"content": "lo"}, "logprobs": latest}]}),
688            // The finish chunk: text is done and logprobs are explicitly null.
689            serde_json::json!({"choices": [{"delta": {}, "logprobs": null,
690                "finish_reason": "stop"}]}),
691        ]
692        .iter()
693        .filter_map(|v| parse_delta(v, &mut ids))
694        .map(|mut u| {
695            accumulate_logprobs(&mut u, &mut running);
696            u
697        })
698        .collect();
699        assert_eq!(updates.len(), 3);
700
701        // Each non-final update still carries its own chunk, so a caller
702        // reading the stream sees the deltas as they arrive.
703        assert_eq!(
704            updates[0].additional_properties[crate::convert::LOGPROBS_PROPERTY],
705            first
706        );
707        assert_eq!(
708            updates[1].additional_properties[crate::convert::LOGPROBS_PROPERTY],
709            latest
710        );
711
712        // The aggregate has both tokens — the null finish chunk neither
713        // cleared them nor narrowed them to the last.
714        let resp = agent_framework_core::types::ChatResponse::from_updates(updates);
715        let content = resp.additional_properties[crate::convert::LOGPROBS_PROPERTY]["content"]
716            .as_array()
717            .expect("an accumulated content array")
718            .clone();
719        let tokens: Vec<&str> = content
720            .iter()
721            .map(|e| e["token"].as_str().unwrap())
722            .collect();
723        assert_eq!(tokens, vec!["hel", "lo"]);
724        assert_eq!(resp.text(), "hello");
725        assert_eq!(resp.finish_reason.map(|f| f.0).as_deref(), Some("stop"));
726    }
727
728    #[test]
729    fn a_stream_that_never_carries_logprobs_surfaces_no_key() {
730        // Negative control: the common case must not gain a `logprobs: null`
731        // entry it never had, which a guard written at the merge instead of
732        // the read would have produced.
733        let mut ids = HashMap::new();
734        let mut running = Vec::new();
735        let updates: Vec<_> = [
736            serde_json::json!({"choices": [{"delta": {"role": "assistant", "content": "hi"},
737                "logprobs": null}]}),
738            serde_json::json!({"choices": [{"delta": {}, "finish_reason": "stop"}]}),
739        ]
740        .iter()
741        .filter_map(|v| parse_delta(v, &mut ids))
742        .map(|mut u| {
743            accumulate_logprobs(&mut u, &mut running);
744            u
745        })
746        .collect();
747        let resp = agent_framework_core::types::ChatResponse::from_updates(updates);
748        assert!(!resp
749            .additional_properties
750            .contains_key(crate::convert::LOGPROBS_PROPERTY));
751    }
752
753    #[test]
754    fn a_streamed_chat_refusal_is_parsed_and_marked() {
755        // `delta.refusal` is its own channel, fragmented like content. It was
756        // not read at all, so a streamed decline vanished entirely.
757        let mut ids = HashMap::new();
758        let update = parse_delta(
759            &serde_json::json!({
760                "id": "chatcmpl-1",
761                "choices": [{ "delta": { "role": "assistant", "refusal": "I can't" } }],
762            }),
763            &mut ids,
764        )
765        .expect("a refusal delta must produce an update");
766        assert!(
767            matches!(&update.contents[0], Content::Text(t) if t.refusal && t.text == "I can't")
768        );
769
770        // Aggregated across fragments, and kept apart from ordinary text.
771        let mut ids = HashMap::new();
772        let updates: Vec<_> = [
773            serde_json::json!({"choices": [{"delta": {"content": "here: "}}]}),
774            serde_json::json!({"choices": [{"delta": {"refusal": "I can't "}}]}),
775            serde_json::json!({"choices": [{"delta": {"refusal": "help"}}]}),
776        ]
777        .iter()
778        .filter_map(|v| parse_delta(v, &mut ids))
779        .collect();
780        let resp = agent_framework_core::types::ChatResponse::from_updates(updates);
781        assert_eq!(
782            resp.messages[0].refusal_text().as_deref(),
783            Some("I can't help")
784        );
785        // `text()` withholds it rather than presenting the partial answer.
786        assert_eq!(resp.text(), "");
787    }
788
789    #[test]
790    fn classifies_401_and_403_as_invalid_auth() {
791        for status in [401, 403] {
792            let err = classify_service_error(status, "", format!("err {status}"), None);
793            assert!(
794                matches!(err, Error::ServiceInvalidAuth { .. }),
795                "status {status}: {err:?}"
796            );
797        }
798    }
799
800    #[test]
801    fn classifies_400_404_422_as_invalid_request_by_default() {
802        for status in [400, 404, 422] {
803            let body = r#"{"error":{"message":"nope","type":"invalid_request_error"}}"#;
804            let err = classify_service_error(status, body, format!("err {status}"), None);
805            assert!(
806                matches!(err, Error::ServiceInvalidRequest { .. }),
807                "status {status}: {err:?}"
808            );
809        }
810    }
811
812    #[test]
813    fn classifies_400_with_content_filter_code_as_content_filter() {
814        // Plain OpenAI shape: `error.code`.
815        let body = r#"{"error":{"message":"flagged","type":"invalid_request_error","code":"content_filter"}}"#;
816        let err = classify_service_error(400, body, "err", None);
817        assert!(matches!(err, Error::ServiceContentFilter { .. }), "{err:?}");
818    }
819
820    #[test]
821    fn classifies_azure_openai_content_filter_shape_with_innererror() {
822        // Azure OpenAI's shape: outer `error.code` is already "content_filter"
823        // (mirrors `openai/_exceptions.py`'s `OpenAIContentFilterException`,
824        // which is constructed once `ex.code == "content_filter"` is already
825        // known — the nested `innererror.code` carries the more specific
826        // `ResponsibleAIPolicyViolation` detail, not the marker itself), but
827        // this also tolerates the marker living only in `innererror`.
828        let body = r#"{"error":{"message":"The response was filtered","code":"content_filter","innererror":{"code":"ResponsibleAIPolicyViolation"}}}"#;
829        let err = classify_service_error(400, body, "err", None);
830        assert!(matches!(err, Error::ServiceContentFilter { .. }), "{err:?}");
831
832        let nested_only =
833            r#"{"error":{"message":"filtered","innererror":{"code":"content_filter"}}}"#;
834        let err = classify_service_error(400, nested_only, "err", None);
835        assert!(matches!(err, Error::ServiceContentFilter { .. }), "{err:?}");
836    }
837
838    #[test]
839    fn an_azure_content_filter_error_carries_which_category_fired() {
840        // The distinction an application acts on: a self-harm block is not a
841        // jailbreak detection, and a prompt block is not an output block.
842        // With only a message string, none of it is reachable.
843        let body = r#"{"error":{"message":"The response was filtered","code":"content_filter",
844            "param":"prompt","innererror":{"code":"ResponsibleAIPolicyViolation",
845            "content_filter_result":{
846                "hate":{"filtered":false,"severity":"safe"},
847                "self_harm":{"filtered":true,"severity":"medium"},
848                "jailbreak":{"filtered":false,"detected":true}}}}}"#;
849        let err = classify_service_error(400, body, "err", None);
850        let detail = err
851            .content_filter_detail()
852            .expect("an Azure content-filter body carries a breakdown");
853        assert_eq!(
854            detail.code.as_deref(),
855            Some(ContentFilterDetail::RESPONSIBLE_AI_POLICY_VIOLATION)
856        );
857        assert_eq!(detail.param.as_deref(), Some("prompt"));
858        assert_eq!(detail.filtered_categories(), vec!["jailbreak", "self_harm"]);
859        assert_eq!(
860            detail.categories["self_harm"].severity.as_deref(),
861            Some("medium")
862        );
863        assert!(!detail.categories["hate"].filtered);
864    }
865
866    #[test]
867    fn an_unrecognized_policy_code_or_severity_is_carried_rather_than_rejected() {
868        // Upstream parsed both into enums, so a value Azure had not shipped
869        // yet raised *while building the error* — #8393 fixed that for the
870        // code and left it for the severity. An open string has no such mode.
871        let body = r#"{"error":{"code":"content_filter","innererror":{
872            "code":"SomeFutureAzurePolicy",
873            "content_filter_result":{"novel_category":{"filtered":true,"severity":"extreme"}}}}}"#;
874        let err = classify_service_error(400, body, "err", None);
875        let detail = err.content_filter_detail().expect("still classified");
876        assert_eq!(detail.code.as_deref(), Some("SomeFutureAzurePolicy"));
877        assert_eq!(
878            detail.categories["novel_category"].severity.as_deref(),
879            Some("extreme")
880        );
881    }
882
883    #[test]
884    fn a_plain_openai_content_filter_error_grows_no_empty_breakdown() {
885        // Nothing beyond the marker: a detail full of `None` would suggest
886        // the provider reported something it did not.
887        let body = r#"{"error":{"message":"flagged","code":"content_filter"}}"#;
888        let err = classify_service_error(400, body, "err", None);
889        assert!(matches!(err, Error::ServiceContentFilter { .. }), "{err:?}");
890        assert!(err.content_filter_detail().is_none());
891    }
892
893    #[test]
894    fn the_outer_marker_is_never_read_as_the_policy_code() {
895        // `error.code` is "content_filter" on the Azure shape; the policy
896        // lives in `innererror.code`. Reading the marker as the policy would
897        // report every Azure refusal as the same one.
898        let body = r#"{"error":{"code":"content_filter","param":"prompt"}}"#;
899        let err = classify_service_error(400, body, "err", None);
900        let detail = err
901            .content_filter_detail()
902            .expect("param alone is a detail");
903        assert_eq!(detail.code, None);
904        assert_eq!(detail.param.as_deref(), Some("prompt"));
905    }
906
907    #[test]
908    fn non_json_or_unmarked_body_does_not_trigger_content_filter() {
909        let err = classify_service_error(400, "not json", "err", None);
910        assert!(
911            matches!(err, Error::ServiceInvalidRequest { .. }),
912            "{err:?}"
913        );
914
915        let err = classify_service_error(400, r#"{"error":{"code":"other"}}"#, "err", None);
916        assert!(
917            matches!(err, Error::ServiceInvalidRequest { .. }),
918            "{err:?}"
919        );
920    }
921
922    #[test]
923    fn leaves_retryable_statuses_as_service_status() {
924        // 408/429/5xx must stay `ServiceStatus` (carrying status +
925        // retry_after) exactly as before — the retry layer depends on it.
926        for status in [408, 429, 500, 503] {
927            let err = classify_service_error(status, "", format!("err {status}"), Some(2.0));
928            assert_eq!(err.status(), Some(status), "{err:?}");
929            assert_eq!(err.retry_after(), Some(2.0), "{err:?}");
930        }
931    }
932
933    #[test]
934    fn unclassified_4xx_stays_service_status() {
935        // e.g. 409 Conflict, 413 Payload Too Large: not in the
936        // auth/invalid-request/content-filter buckets, so this falls back to
937        // the generic status-carrying variant rather than guessing.
938        let err = classify_service_error(409, "", "err", None);
939        assert_eq!(err.status(), Some(409), "{err:?}");
940    }
941
942    #[test]
943    fn message_text_is_preserved_verbatim() {
944        let err = classify_service_error(401, "", "OpenAI API error 401: unauthorized", None);
945        assert_eq!(
946            err.to_string(),
947            "service error: OpenAI API error 401: unauthorized"
948        );
949    }
950}