Skip to main content

daimon_provider_openrouter/
lib.rs

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