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