Skip to main content

daimon_provider_openai/
lib.rs

1//! OpenAI model provider for the [Daimon](https://docs.rs/daimon) agent framework.
2//!
3//! This crate provides an implementation of the [`Model`] trait that connects
4//! to the OpenAI Chat Completions API. It supports configurable timeouts,
5//! retries with exponential backoff, response format constraints, and
6//! parallel tool calls.
7//!
8//! # Example
9//!
10//! ```ignore
11//! use daimon_provider_openai::OpenAi;
12//! use daimon_core::Model;
13//!
14//! let model = OpenAi::new("gpt-4o");
15//! ```
16
17use std::collections::HashMap;
18use std::time::Duration;
19
20use reqwest::Client;
21use serde::{Deserialize, Serialize};
22
23pub mod embedding;
24mod retry;
25
26use daimon_core::{
27    ChatRequest, ChatResponse, DaimonError, Message, Model, ResponseStream, Result, Role,
28    StopReason, StreamEvent, ToolCall, ToolSpec, Usage,
29};
30
31const DEFAULT_BASE_URL: &str = "https://api.openai.com/v1";
32
33pub const DEFAULT_MAX_RETRIES: u32 = 3;
34
35/// Default whole-request timeout applied to non-streaming `generate` calls.
36///
37/// Long completions can legitimately take minutes, so this is deliberately
38/// generous. Override with [`OpenAi::with_timeout`].
39const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(120);
40
41/// Default TCP/TLS connect timeout applied to the underlying HTTP client.
42///
43/// This bounds only connection establishment, so it is safe for the
44/// long-lived SSE streams produced by `generate_stream` (a whole-request
45/// timeout would kill a healthy stream mid-response).
46const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(30);
47
48fn build_client() -> Client {
49    Client::builder()
50        .connect_timeout(DEFAULT_CONNECT_TIMEOUT)
51        .build()
52        .expect("failed to build HTTP client")
53}
54
55/// OpenAI model provider for the Chat Completions API.
56///
57/// Supports configurable timeouts, retries, response format, and parallel tool calls.
58/// Use `new()` or `with_api_key()` to create, then chain builder methods as needed.
59pub struct OpenAi {
60    client: Client,
61    api_key: String,
62    model_id: String,
63    base_url: String,
64    timeout: Option<Duration>,
65    max_retries: u32,
66    response_format: Option<String>,
67    parallel_tool_calls: Option<bool>,
68}
69
70impl std::fmt::Debug for OpenAi {
71    /// Hand-written to avoid leaking the plaintext API key in logs or panic
72    /// output; a derived `Debug` would print `api_key` verbatim.
73    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
74        f.debug_struct("OpenAi")
75            .field("client", &self.client)
76            .field("api_key", &"[redacted]")
77            .field("model_id", &self.model_id)
78            .field("base_url", &self.base_url)
79            .field("timeout", &self.timeout)
80            .field("max_retries", &self.max_retries)
81            .field("response_format", &self.response_format)
82            .field("parallel_tool_calls", &self.parallel_tool_calls)
83            .finish()
84    }
85}
86
87impl OpenAi {
88    /// Create a new OpenAI client using the default model ID.
89    ///
90    /// Reads `OPENAI_API_KEY` from the environment. Use `with_api_key()` to
91    /// provide the key explicitly. The constructor never fails; if the
92    /// environment variable is unset or empty a warning is logged and
93    /// requests will fail with an auth error.
94    pub fn new(model_id: impl Into<String>) -> Self {
95        let api_key = std::env::var("OPENAI_API_KEY").unwrap_or_default();
96        if api_key.is_empty() {
97            tracing::warn!(
98                "OPENAI_API_KEY is not set or empty; OpenAI requests will fail authentication"
99            );
100        }
101        Self::with_api_key(model_id, api_key)
102    }
103
104    /// Create a new OpenAI client with an explicit API key.
105    pub fn with_api_key(model_id: impl Into<String>, api_key: impl Into<String>) -> Self {
106        Self {
107            client: build_client(),
108            api_key: api_key.into(),
109            model_id: model_id.into(),
110            base_url: DEFAULT_BASE_URL.to_string(),
111            timeout: None,
112            max_retries: DEFAULT_MAX_RETRIES,
113            response_format: None,
114            parallel_tool_calls: None,
115        }
116    }
117
118    /// Set a custom base URL (e.g. for proxies or local endpoints).
119    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
120        self.base_url = base_url.into();
121        self
122    }
123
124    /// Set a custom timeout for non-streaming HTTP requests (default: 120s).
125    ///
126    /// The timeout applies per-request to `generate`; `generate_stream` is a
127    /// long-lived SSE connection and is protected only by the client's
128    /// connect timeout, since a whole-request deadline would abort healthy
129    /// streams.
130    pub fn with_timeout(mut self, timeout: Duration) -> Self {
131        self.timeout = Some(timeout);
132        self
133    }
134
135    /// Set the maximum number of retries for failed requests (429 and 5xx).
136    pub fn with_max_retries(mut self, retries: u32) -> Self {
137        self.max_retries = retries;
138        self
139    }
140
141    /// Set the response format (e.g. `"json_object"` or `"text"`).
142    pub fn with_response_format(mut self, format: &str) -> Self {
143        self.response_format = Some(format.to_string());
144        self
145    }
146
147    /// Enable or disable parallel tool calls.
148    pub fn with_parallel_tool_calls(mut self, enabled: bool) -> Self {
149        self.parallel_tool_calls = Some(enabled);
150        self
151    }
152
153    fn build_request_body(&self, request: &ChatRequest) -> OpenAiRequest {
154        let messages: Vec<OpenAiMessage> = request.messages.iter().map(Into::into).collect();
155
156        let tools: Option<Vec<OpenAiTool>> = if request.tools.is_empty() {
157            None
158        } else {
159            Some(request.tools.iter().map(Into::into).collect())
160        };
161
162        OpenAiRequest {
163            model: self.model_id.clone(),
164            messages,
165            tools,
166            temperature: request.temperature,
167            // `max_completion_tokens` is the modern parameter; reasoning
168            // models reject the legacy `max_tokens`.
169            max_completion_tokens: request.max_tokens,
170            stream: false,
171            response_format: self
172                .response_format
173                .as_ref()
174                .map(|f| serde_json::json!({ "type": f })),
175            parallel_tool_calls: self.parallel_tool_calls,
176        }
177    }
178}
179
180impl Model for OpenAi {
181    fn model_id(&self) -> &str {
182        &self.model_id
183    }
184
185    #[tracing::instrument(skip_all, fields(model = %self.model_id))]
186    async fn generate(&self, request: &ChatRequest) -> Result<ChatResponse> {
187        let body = self.build_request_body(request);
188        let url = format!("{}/chat/completions", self.base_url);
189        let timeout = self.timeout.unwrap_or(DEFAULT_REQUEST_TIMEOUT);
190
191        tracing::debug!("sending chat completion request");
192
193        for attempt in 0..=self.max_retries {
194            let response = self
195                .client
196                .post(&url)
197                .timeout(timeout)
198                .header("Authorization", format!("Bearer {}", self.api_key))
199                .json(&body)
200                .send()
201                .await
202                .map_err(|e| DaimonError::Model(format!("OpenAI HTTP error: {e}")))?;
203
204            let status = response.status();
205
206            if status.is_success() {
207                tracing::debug!("received successful response");
208                let oai_response: OpenAiResponse = response
209                    .json()
210                    .await
211                    .map_err(|e| DaimonError::Model(format!("OpenAI response parse error: {e}")))?;
212                return parse_response(oai_response);
213            }
214
215            let retry_after = retry::parse_retry_after(response.headers());
216            let text = response.text().await.unwrap_or_default();
217            let is_retryable = status.as_u16() == 429 || status.is_server_error();
218
219            if is_retryable && attempt < self.max_retries {
220                let delay = retry::backoff_delay(attempt, retry_after);
221                tracing::debug!(
222                    status = %status,
223                    attempt = attempt + 1,
224                    max_retries = self.max_retries,
225                    delay_ms = delay.as_millis(),
226                    "retryable error, backing off"
227                );
228                tokio::time::sleep(delay).await;
229            } else {
230                return Err(DaimonError::Model(format!(
231                    "OpenAI API error ({status}): {text}"
232                )));
233            }
234        }
235
236        unreachable!("loop always returns or retries")
237    }
238
239    #[tracing::instrument(skip_all, fields(model = %self.model_id))]
240    async fn generate_stream(&self, request: &ChatRequest) -> Result<ResponseStream> {
241        let mut body = self.build_request_body(request);
242        body.stream = true;
243        let url = format!("{}/chat/completions", self.base_url);
244
245        // Retry only the initial POST/handshake — once the stream is
246        // established, mid-stream failures must never be retried (the
247        // consumer has already observed a partial response).
248        let mut response = None;
249        for attempt in 0..=self.max_retries {
250            tracing::debug!(attempt, "sending streaming chat completion request");
251            let resp = self
252                .client
253                .post(&url)
254                .header("Authorization", format!("Bearer {}", self.api_key))
255                .json(&body)
256                .send()
257                .await
258                .map_err(|e| DaimonError::Model(format!("OpenAI HTTP error: {e}")))?;
259            let status = resp.status();
260
261            if status.is_success() {
262                response = Some(resp);
263                break;
264            }
265
266            let retry_after = retry::parse_retry_after(resp.headers());
267            let text = resp.text().await.unwrap_or_default();
268            let is_retryable = status.as_u16() == 429 || status.is_server_error();
269
270            if is_retryable && attempt < self.max_retries {
271                let delay = retry::backoff_delay(attempt, retry_after);
272                tracing::debug!(status = %status, attempt, delay_ms = delay.as_millis(), "retryable error on stream handshake, backing off");
273                tokio::time::sleep(delay).await;
274            } else {
275                return Err(DaimonError::Model(format!(
276                    "OpenAI API error ({status}): {text}"
277                )));
278            }
279        }
280        let response = response.expect("loop breaks with a response or returns an error");
281
282        tracing::debug!("stream established, processing chunks");
283        let byte_stream = response.bytes_stream();
284
285        let stream = async_stream::try_stream! {
286            use futures::StreamExt;
287            use daimon_core::stream_util::LineBuffer;
288
289            let mut buffer = LineBuffer::new();
290            let mut state = OpenAiStreamState::default();
291            let mut stream = Box::pin(byte_stream);
292
293            while let Some(chunk) = stream.next().await {
294                let chunk = chunk.map_err(|e| DaimonError::Model(format!("OpenAI stream error: {e}")))?;
295                buffer.push(&chunk);
296
297                while let Some(line) = buffer.next_line() {
298                    for event in handle_openai_sse_line(&mut state, &line) {
299                        yield event;
300                    }
301                }
302            }
303
304            // A stream may end without a trailing newline, leaving a final SSE
305            // record buffered. Recover it through the identical parse path.
306            if let Some(line) = buffer.take_remaining() {
307                for event in handle_openai_sse_line(&mut state, &line) {
308                    yield event;
309                }
310            }
311        };
312
313        Ok(Box::pin(stream))
314    }
315}
316
317/// Streaming state for the OpenAI SSE parser.
318///
319/// OpenAI announces a tool call's `id` only on its first chunk; subsequent
320/// argument fragments carry just the array `index`. The map correlates the
321/// index back to the announced id, and `open_calls` tracks announcement order
322/// so `ToolCallEnd` can be emitted for every call when `finish_reason`
323/// arrives.
324#[derive(Default)]
325struct OpenAiStreamState {
326    index_to_id: HashMap<usize, String>,
327    open_calls: Vec<String>,
328}
329
330/// Parses one SSE line from an OpenAI chat-completions stream into
331/// [`StreamEvent`]s.
332///
333/// This is the single parse path shared by the main streaming loop and the
334/// end-of-stream remainder recovery, extracted (following the Anthropic
335/// provider's `handle_anthropic_stream_event` pattern) so it can be
336/// unit-tested without a live HTTP stream.
337///
338/// Behavior notes:
339/// - Tool-call ids are the provider-assigned `id` when present; the array
340///   index is only a fallback for servers that omit ids.
341/// - `finish_reason` closes all open tool calls with `ToolCallEnd`, and
342///   `content_filter` additionally surfaces an in-band [`StreamEvent::Error`]
343///   ([`StreamEvent::Done`] carries no stop reason, so the error event is the
344///   only channel that keeps a filtered termination from being silent).
345/// - The `data: [DONE]` sentinel yields `Done`.
346fn handle_openai_sse_line(state: &mut OpenAiStreamState, line: &str) -> Vec<StreamEvent> {
347    let line = line.trim();
348    let mut events = Vec::new();
349
350    if line.is_empty() {
351        return events;
352    }
353    if line == "data: [DONE]" {
354        // Defensive: close any calls the server never finished.
355        for id in state.open_calls.drain(..) {
356            events.push(StreamEvent::ToolCallEnd { id });
357        }
358        events.push(StreamEvent::Done);
359        return events;
360    }
361
362    let Some(data) = line.strip_prefix("data: ") else {
363        return events;
364    };
365    let chunk = match serde_json::from_str::<OpenAiStreamChunk>(data) {
366        Ok(chunk) => chunk,
367        Err(e) => {
368            tracing::debug!(error = %e, "dropping undeserializable OpenAI SSE event");
369            return events;
370        }
371    };
372
373    for choice in &chunk.choices {
374        if let Some(ref content) = choice.delta.content
375            && !content.is_empty()
376        {
377            events.push(StreamEvent::TextDelta(content.clone()));
378        }
379        if let Some(ref tool_calls) = choice.delta.tool_calls {
380            for tc in tool_calls {
381                let Some(ref func) = tc.function else {
382                    continue;
383                };
384                // Prefer the provider-assigned id; remember it so later
385                // fragments (which omit the id) resolve through the index.
386                let id = match tc.id.as_deref().filter(|id| !id.is_empty()) {
387                    Some(id) => {
388                        state.index_to_id.insert(tc.index, id.to_string());
389                        id.to_string()
390                    }
391                    None => state
392                        .index_to_id
393                        .get(&tc.index)
394                        .cloned()
395                        .unwrap_or_else(|| tc.index.to_string()),
396                };
397                if let Some(ref name) = func.name {
398                    state.open_calls.push(id.clone());
399                    events.push(StreamEvent::ToolCallStart {
400                        id: id.clone(),
401                        name: name.clone(),
402                    });
403                }
404                if let Some(ref args) = func.arguments
405                    && !args.is_empty()
406                {
407                    events.push(StreamEvent::ToolCallDelta {
408                        id,
409                        arguments_delta: args.clone(),
410                    });
411                }
412            }
413        }
414        if let Some(ref reason) = choice.finish_reason {
415            // The turn is complete: every announced tool call is now final.
416            for id in state.open_calls.drain(..) {
417                events.push(StreamEvent::ToolCallEnd { id });
418            }
419            if reason == "content_filter" {
420                events.push(StreamEvent::Error(
421                    "OpenAI blocked the response (finish_reason=content_filter)".to_string(),
422                ));
423            }
424        }
425    }
426
427    events
428}
429
430fn parse_response(response: OpenAiResponse) -> Result<ChatResponse> {
431    let choice = response
432        .choices
433        .into_iter()
434        .next()
435        .ok_or_else(|| DaimonError::Model("no choices in OpenAI response".into()))?;
436
437    let mut tool_calls = Vec::new();
438    for tc in choice.message.tool_calls.unwrap_or_default() {
439        // Malformed arguments must surface as an error: silently coercing
440        // them to null would run the tool with the corruption hidden.
441        let arguments = if tc.function.arguments.trim().is_empty() {
442            serde_json::Value::Object(serde_json::Map::new())
443        } else {
444            serde_json::from_str(&tc.function.arguments).map_err(|e| {
445                DaimonError::Model(format!(
446                    "OpenAI returned malformed JSON arguments for tool call '{}' (id {}): {e}",
447                    tc.function.name, tc.id
448                ))
449            })?
450        };
451        tool_calls.push(ToolCall {
452            id: tc.id,
453            name: tc.function.name,
454            arguments,
455        });
456    }
457
458    let stop_reason = match choice.finish_reason.as_deref() {
459        Some("tool_calls") => StopReason::ToolUse,
460        Some("length") => StopReason::MaxTokens,
461        Some("content_filter") => StopReason::ContentFiltered,
462        _ => StopReason::EndTurn,
463    };
464
465    let message = Message {
466        role: Role::Assistant,
467        content: choice.message.content,
468        tool_calls,
469        tool_call_id: None,
470    };
471
472    Ok(ChatResponse {
473        message,
474        stop_reason,
475        usage: response.usage.map(|u| Usage {
476            input_tokens: u.prompt_tokens,
477            output_tokens: u.completion_tokens,
478            cached_tokens: u
479                .prompt_tokens_details
480                .map(|d| d.cached_tokens)
481                .unwrap_or(0),
482        }),
483    })
484}
485
486// --- OpenAI API types ---
487
488#[derive(Serialize)]
489struct OpenAiRequest {
490    model: String,
491    messages: Vec<OpenAiMessage>,
492    #[serde(skip_serializing_if = "Option::is_none")]
493    tools: Option<Vec<OpenAiTool>>,
494    #[serde(skip_serializing_if = "Option::is_none")]
495    temperature: Option<f32>,
496    #[serde(skip_serializing_if = "Option::is_none")]
497    max_completion_tokens: Option<u32>,
498    stream: bool,
499    #[serde(skip_serializing_if = "Option::is_none")]
500    response_format: Option<serde_json::Value>,
501    #[serde(skip_serializing_if = "Option::is_none")]
502    parallel_tool_calls: Option<bool>,
503}
504
505#[derive(Serialize, Deserialize)]
506struct OpenAiMessage {
507    role: String,
508    #[serde(skip_serializing_if = "Option::is_none")]
509    content: Option<String>,
510    #[serde(skip_serializing_if = "Option::is_none")]
511    tool_calls: Option<Vec<OpenAiToolCall>>,
512    #[serde(skip_serializing_if = "Option::is_none")]
513    tool_call_id: Option<String>,
514}
515
516impl From<&Message> for OpenAiMessage {
517    fn from(msg: &Message) -> Self {
518        let role = match msg.role {
519            Role::System => "system",
520            Role::User => "user",
521            Role::Assistant => "assistant",
522            Role::Tool => "tool",
523        };
524
525        let tool_calls = if msg.tool_calls.is_empty() {
526            None
527        } else {
528            Some(
529                msg.tool_calls
530                    .iter()
531                    .map(|tc| OpenAiToolCall {
532                        id: tc.id.clone(),
533                        r#type: "function".to_string(),
534                        function: OpenAiFunction {
535                            name: tc.name.clone(),
536                            arguments: serde_json::to_string(&tc.arguments).unwrap_or_default(),
537                        },
538                        index: 0,
539                    })
540                    .collect(),
541            )
542        };
543
544        Self {
545            role: role.to_string(),
546            content: msg.content.clone(),
547            tool_calls,
548            tool_call_id: msg.tool_call_id.clone(),
549        }
550    }
551}
552
553#[derive(Serialize)]
554struct OpenAiTool {
555    r#type: String,
556    function: OpenAiToolFunction,
557}
558
559impl From<&ToolSpec> for OpenAiTool {
560    fn from(spec: &ToolSpec) -> Self {
561        Self {
562            r#type: "function".to_string(),
563            function: OpenAiToolFunction {
564                name: spec.name.clone(),
565                description: spec.description.clone(),
566                parameters: spec.parameters.clone(),
567            },
568        }
569    }
570}
571
572#[derive(Serialize)]
573struct OpenAiToolFunction {
574    name: String,
575    description: String,
576    parameters: serde_json::Value,
577}
578
579#[derive(Deserialize)]
580struct OpenAiResponse {
581    choices: Vec<OpenAiChoice>,
582    usage: Option<OpenAiUsage>,
583}
584
585#[derive(Deserialize)]
586struct OpenAiChoice {
587    message: OpenAiChoiceMessage,
588    finish_reason: Option<String>,
589}
590
591#[derive(Deserialize)]
592struct OpenAiChoiceMessage {
593    content: Option<String>,
594    tool_calls: Option<Vec<OpenAiToolCall>>,
595}
596
597#[derive(Serialize, Deserialize)]
598struct OpenAiToolCall {
599    #[serde(default)]
600    id: String,
601    #[serde(default)]
602    r#type: String,
603    #[serde(default)]
604    function: OpenAiFunction,
605    #[serde(default)]
606    index: usize,
607}
608
609#[derive(Serialize, Deserialize, Default)]
610struct OpenAiFunction {
611    #[serde(default)]
612    name: String,
613    #[serde(default)]
614    arguments: String,
615}
616
617#[derive(Deserialize)]
618struct OpenAiUsage {
619    prompt_tokens: u32,
620    completion_tokens: u32,
621    prompt_tokens_details: Option<OpenAiPromptTokensDetails>,
622}
623
624#[derive(Deserialize)]
625struct OpenAiPromptTokensDetails {
626    #[serde(default)]
627    cached_tokens: u32,
628}
629
630#[derive(Deserialize)]
631struct OpenAiStreamChunk {
632    choices: Vec<OpenAiStreamChoice>,
633}
634
635#[derive(Deserialize)]
636struct OpenAiStreamChoice {
637    delta: OpenAiStreamDelta,
638    #[serde(default)]
639    finish_reason: Option<String>,
640}
641
642#[derive(Deserialize)]
643struct OpenAiStreamDelta {
644    #[serde(default)]
645    content: Option<String>,
646    #[serde(default)]
647    tool_calls: Option<Vec<OpenAiStreamToolCall>>,
648}
649
650#[derive(Deserialize)]
651struct OpenAiStreamToolCall {
652    index: usize,
653    /// Provider-assigned id, present only on a call's first chunk.
654    #[serde(default)]
655    id: Option<String>,
656    function: Option<OpenAiStreamFunction>,
657}
658
659#[derive(Deserialize)]
660struct OpenAiStreamFunction {
661    name: Option<String>,
662    arguments: Option<String>,
663}
664
665#[cfg(test)]
666mod tests {
667    use super::*;
668
669    #[test]
670    fn test_message_conversion_user() {
671        let msg = Message::user("hello");
672        let oai: OpenAiMessage = (&msg).into();
673        assert_eq!(oai.role, "user");
674        assert_eq!(oai.content.as_deref(), Some("hello"));
675        assert!(oai.tool_calls.is_none());
676    }
677
678    #[test]
679    fn test_message_conversion_assistant_with_tools() {
680        let msg = Message::assistant_with_tool_calls(vec![ToolCall {
681            id: "tc_1".into(),
682            name: "calc".into(),
683            arguments: serde_json::json!({"x": 1}),
684        }]);
685        let oai: OpenAiMessage = (&msg).into();
686        assert_eq!(oai.role, "assistant");
687        assert!(oai.tool_calls.is_some());
688        assert_eq!(oai.tool_calls.unwrap().len(), 1);
689    }
690
691    #[test]
692    fn test_message_conversion_tool_result() {
693        let msg = Message::tool_result("tc_1", "42");
694        let oai: OpenAiMessage = (&msg).into();
695        assert_eq!(oai.role, "tool");
696        assert_eq!(oai.tool_call_id.as_deref(), Some("tc_1"));
697        assert_eq!(oai.content.as_deref(), Some("42"));
698    }
699
700    #[test]
701    fn test_tool_spec_conversion() {
702        let spec = ToolSpec {
703            name: "calc".into(),
704            description: "Calculator".into(),
705            parameters: serde_json::json!({"type": "object"}),
706        };
707        let oai: OpenAiTool = (&spec).into();
708        assert_eq!(oai.r#type, "function");
709        assert_eq!(oai.function.name, "calc");
710    }
711
712    #[test]
713    fn test_request_body_uses_max_completion_tokens() {
714        // Reasoning models reject the legacy `max_tokens` parameter; the
715        // request must carry `max_completion_tokens` instead.
716        let model = OpenAi::with_api_key("gpt-4o", "key");
717        let request = ChatRequest {
718            messages: vec![Message::user("hi")],
719            tools: vec![],
720            temperature: None,
721            max_tokens: Some(512),
722        };
723        let body = model.build_request_body(&request);
724        let json = serde_json::to_value(&body).unwrap();
725        assert_eq!(json["max_completion_tokens"], 512);
726        assert!(
727            json.get("max_tokens").is_none(),
728            "legacy max_tokens must not be sent"
729        );
730    }
731
732    #[test]
733    fn test_parse_response_end_turn() {
734        let raw = OpenAiResponse {
735            choices: vec![OpenAiChoice {
736                message: OpenAiChoiceMessage {
737                    content: Some("hello".into()),
738                    tool_calls: None,
739                },
740                finish_reason: Some("stop".into()),
741            }],
742            usage: Some(OpenAiUsage {
743                prompt_tokens: 10,
744                completion_tokens: 5,
745                prompt_tokens_details: None,
746            }),
747        };
748        let resp = parse_response(raw).unwrap();
749        assert_eq!(resp.text(), "hello");
750        assert_eq!(resp.stop_reason, StopReason::EndTurn);
751        assert!(!resp.has_tool_calls());
752        assert_eq!(resp.usage.unwrap().input_tokens, 10);
753    }
754
755    #[test]
756    fn test_parse_response_tool_use() {
757        let raw = OpenAiResponse {
758            choices: vec![OpenAiChoice {
759                message: OpenAiChoiceMessage {
760                    content: None,
761                    tool_calls: Some(vec![OpenAiToolCall {
762                        id: "tc_1".into(),
763                        r#type: "function".into(),
764                        function: OpenAiFunction {
765                            name: "calc".into(),
766                            arguments: r#"{"x":1}"#.into(),
767                        },
768                        index: 0,
769                    }]),
770                },
771                finish_reason: Some("tool_calls".into()),
772            }],
773            usage: None,
774        };
775        let resp = parse_response(raw).unwrap();
776        assert!(resp.has_tool_calls());
777        assert_eq!(resp.tool_calls()[0].name, "calc");
778        assert_eq!(resp.stop_reason, StopReason::ToolUse);
779    }
780
781    #[test]
782    fn test_parse_response_malformed_tool_arguments_is_error() {
783        // Previously malformed args were silently coerced to null via
784        // `unwrap_or_default`, hiding the corruption from the caller.
785        let raw = OpenAiResponse {
786            choices: vec![OpenAiChoice {
787                message: OpenAiChoiceMessage {
788                    content: None,
789                    tool_calls: Some(vec![OpenAiToolCall {
790                        id: "tc_1".into(),
791                        r#type: "function".into(),
792                        function: OpenAiFunction {
793                            name: "calc".into(),
794                            arguments: r#"{"x": not-json"#.into(),
795                        },
796                        index: 0,
797                    }]),
798                },
799                finish_reason: Some("tool_calls".into()),
800            }],
801            usage: None,
802        };
803        let err = parse_response(raw).unwrap_err();
804        assert!(
805            err.to_string().contains("malformed JSON arguments"),
806            "unexpected error: {err}"
807        );
808    }
809
810    #[test]
811    fn test_parse_response_empty_tool_arguments_maps_to_empty_object() {
812        // No-argument tools may come back with an empty arguments string;
813        // that is legitimate and maps to `{}`, not an error.
814        let raw = OpenAiResponse {
815            choices: vec![OpenAiChoice {
816                message: OpenAiChoiceMessage {
817                    content: None,
818                    tool_calls: Some(vec![OpenAiToolCall {
819                        id: "tc_1".into(),
820                        r#type: "function".into(),
821                        function: OpenAiFunction {
822                            name: "ping".into(),
823                            arguments: String::new(),
824                        },
825                        index: 0,
826                    }]),
827                },
828                finish_reason: Some("tool_calls".into()),
829            }],
830            usage: None,
831        };
832        let resp = parse_response(raw).unwrap();
833        assert_eq!(resp.tool_calls()[0].arguments, serde_json::json!({}));
834    }
835
836    #[test]
837    fn test_parse_response_content_filter_maps_to_content_filtered() {
838        let raw = OpenAiResponse {
839            choices: vec![OpenAiChoice {
840                message: OpenAiChoiceMessage {
841                    content: None,
842                    tool_calls: None,
843                },
844                finish_reason: Some("content_filter".into()),
845            }],
846            usage: None,
847        };
848        let resp = parse_response(raw).unwrap();
849        assert_eq!(resp.stop_reason, StopReason::ContentFiltered);
850    }
851
852    #[test]
853    fn test_parse_response_no_choices() {
854        let raw = OpenAiResponse {
855            choices: vec![],
856            usage: None,
857        };
858        let result = parse_response(raw);
859        assert!(result.is_err());
860    }
861
862    #[test]
863    fn test_openai_new_default() {
864        let model = OpenAi::new("gpt-4o");
865        assert_eq!(model.model_id, "gpt-4o");
866        assert_eq!(model.base_url, DEFAULT_BASE_URL);
867        assert_eq!(model.max_retries, DEFAULT_MAX_RETRIES);
868    }
869
870    #[test]
871    fn test_openai_with_base_url() {
872        let model = OpenAi::new("gpt-4o").with_base_url("http://localhost:8080");
873        assert_eq!(model.base_url, "http://localhost:8080");
874    }
875
876    #[test]
877    fn test_with_timeout() {
878        let model = OpenAi::new("gpt-4o").with_timeout(std::time::Duration::from_secs(60));
879        assert_eq!(model.timeout, Some(std::time::Duration::from_secs(60)));
880    }
881
882    #[test]
883    fn test_with_max_retries() {
884        let model = OpenAi::new("gpt-4o").with_max_retries(5);
885        assert_eq!(model.max_retries, 5);
886    }
887
888    #[test]
889    fn test_with_response_format() {
890        let model = OpenAi::new("gpt-4o").with_response_format("json_object");
891        assert_eq!(model.response_format.as_deref(), Some("json_object"));
892    }
893
894    #[test]
895    fn test_with_parallel_tool_calls() {
896        let model = OpenAi::new("gpt-4o").with_parallel_tool_calls(true);
897        assert_eq!(model.parallel_tool_calls, Some(true));
898    }
899
900    #[test]
901    fn test_debug_redacts_api_key() {
902        let model = OpenAi::with_api_key("gpt-4o", "sk-supersecret-key-value");
903        let dbg = format!("{model:?}");
904        assert!(
905            !dbg.contains("sk-supersecret-key-value"),
906            "Debug output must not contain the plaintext API key: {dbg}"
907        );
908        assert!(dbg.contains("[redacted]"));
909    }
910
911    // --- Streaming SSE-parser tests ---
912    //
913    // These exercise `handle_openai_sse_line` directly, feeding lines in the
914    // exact shapes OpenAI emits over SSE. This is the logic that previously
915    // lived (untested, duplicated) inside the `try_stream!` block and that
916    // used the chunk index ("0", "1") as the tool-call id.
917
918    fn feed(state: &mut OpenAiStreamState, lines: &[&str]) -> Vec<StreamEvent> {
919        let mut events = Vec::new();
920        for line in lines {
921            events.extend(handle_openai_sse_line(state, line));
922        }
923        events
924    }
925
926    #[test]
927    fn test_stream_text_delta_and_done() {
928        let mut state = OpenAiStreamState::default();
929        let events = feed(
930            &mut state,
931            &[
932                r#"data: {"choices":[{"delta":{"content":"Hel"}}]}"#,
933                r#"data: {"choices":[{"delta":{"content":"lo"}}]}"#,
934                r#"data: {"choices":[{"delta":{},"finish_reason":"stop"}]}"#,
935                "data: [DONE]",
936            ],
937        );
938        assert_eq!(events.len(), 3, "got {events:?}");
939        assert!(matches!(&events[0], StreamEvent::TextDelta(t) if t == "Hel"));
940        assert!(matches!(&events[1], StreamEvent::TextDelta(t) if t == "lo"));
941        assert!(matches!(&events[2], StreamEvent::Done));
942    }
943
944    #[test]
945    fn test_stream_tool_call_uses_real_id_and_emits_end() {
946        let mut state = OpenAiStreamState::default();
947        let events = feed(
948            &mut state,
949            &[
950                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_abc","function":{"name":"calc","arguments":""}}]}}]}"#,
951                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"x\":"}}]}}]}"#,
952                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"1}"}}]}}]}"#,
953                r#"data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}"#,
954                "data: [DONE]",
955            ],
956        );
957        assert_eq!(events.len(), 5, "got {events:?}");
958        assert!(matches!(&events[0], StreamEvent::ToolCallStart { id, name }
959            if id == "call_abc" && name == "calc"));
960        assert!(matches!(&events[1], StreamEvent::ToolCallDelta { id, .. } if id == "call_abc"));
961        assert!(matches!(&events[2], StreamEvent::ToolCallDelta { id, .. } if id == "call_abc"));
962        assert!(
963            matches!(&events[3], StreamEvent::ToolCallEnd { id } if id == "call_abc"),
964            "ToolCallEnd must be emitted when finish_reason arrives: {events:?}"
965        );
966        assert!(matches!(&events[4], StreamEvent::Done));
967    }
968
969    #[test]
970    fn test_stream_parallel_tool_calls_route_by_index() {
971        let mut state = OpenAiStreamState::default();
972        let events = feed(
973            &mut state,
974            &[
975                r#"data: {"choices":[{"delta":{"tool_calls":[
976                    {"index":0,"id":"call_a","function":{"name":"f","arguments":""}},
977                    {"index":1,"id":"call_b","function":{"name":"g","arguments":""}}]}}]}"#,
978                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":1,"function":{"arguments":"b"}}]}}]}"#,
979                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"a"}}]}}]}"#,
980                r#"data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}"#,
981            ],
982        );
983        assert!(matches!(&events[0], StreamEvent::ToolCallStart { id, .. } if id == "call_a"));
984        assert!(matches!(&events[1], StreamEvent::ToolCallStart { id, .. } if id == "call_b"));
985        assert!(matches!(&events[2],
986            StreamEvent::ToolCallDelta { id, arguments_delta } if id == "call_b" && arguments_delta == "b"));
987        assert!(matches!(&events[3],
988            StreamEvent::ToolCallDelta { id, arguments_delta } if id == "call_a" && arguments_delta == "a"));
989        let ends: Vec<&str> = events
990            .iter()
991            .filter_map(|e| match e {
992                StreamEvent::ToolCallEnd { id } => Some(id.as_str()),
993                _ => None,
994            })
995            .collect();
996        assert_eq!(ends, vec!["call_a", "call_b"]);
997    }
998
999    #[test]
1000    fn test_stream_tool_call_without_id_falls_back_to_index() {
1001        // Some OpenAI-compatible servers omit the id entirely; the index is
1002        // the documented fallback so deltas still correlate.
1003        let mut state = OpenAiStreamState::default();
1004        let events = feed(
1005            &mut state,
1006            &[
1007                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"name":"calc","arguments":""}}]}}]}"#,
1008                r#"data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{}"}}]}}]}"#,
1009            ],
1010        );
1011        assert!(matches!(&events[0], StreamEvent::ToolCallStart { id, .. } if id == "0"));
1012        assert!(matches!(&events[1], StreamEvent::ToolCallDelta { id, .. } if id == "0"));
1013    }
1014
1015    #[test]
1016    fn test_stream_content_filter_emits_error() {
1017        let mut state = OpenAiStreamState::default();
1018        let events = feed(
1019            &mut state,
1020            &[
1021                r#"data: {"choices":[{"delta":{},"finish_reason":"content_filter"}]}"#,
1022                "data: [DONE]",
1023            ],
1024        );
1025        assert_eq!(events.len(), 2, "got {events:?}");
1026        assert!(matches!(&events[0], StreamEvent::Error(msg) if msg.contains("content_filter")));
1027        assert!(matches!(&events[1], StreamEvent::Done));
1028    }
1029
1030    #[test]
1031    fn test_stream_undeserializable_line_is_dropped() {
1032        let mut state = OpenAiStreamState::default();
1033        let events = feed(&mut state, &["data: {not json", ": keep-alive comment", ""]);
1034        assert!(events.is_empty());
1035    }
1036}