Skip to main content

daimon_provider_anthropic/
lib.rs

1//! Anthropic Claude model provider for the [Daimon](https://docs.rs/daimon) agent framework.
2//!
3//! This crate provides integration with the Anthropic API for chat completions,
4//! streaming, and tool use. Configure via builder methods for timeout, retries,
5//! and prompt caching.
6//!
7//! # Example
8//!
9//! ```ignore
10//! use daimon_provider_anthropic::Anthropic;
11//! use daimon_core::Model;
12//!
13//! let model = Anthropic::new("claude-sonnet-4-20250514");
14//! ```
15
16use std::collections::HashMap;
17use std::time::Duration;
18
19use reqwest::Client;
20use serde::{Deserialize, Serialize};
21
22mod retry;
23
24use daimon_core::{
25    ChatRequest, ChatResponse, DaimonError, Message, Model, ResponseStream, Result, Role,
26    StopReason, StreamEvent, ToolCall, ToolSpec, Usage,
27};
28
29const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
30const API_VERSION: &str = "2023-06-01";
31
32/// Default `max_tokens` sent when the request does not specify one.
33///
34/// The Anthropic API requires `max_tokens` on every request; 4096 is a
35/// conservative ceiling that every Claude model supports.
36const DEFAULT_MAX_TOKENS: u32 = 4096;
37
38/// Default whole-request timeout applied to non-streaming `generate` calls.
39///
40/// Long completions can legitimately take minutes, so this is deliberately
41/// generous. Override with [`Anthropic::with_timeout`].
42const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(120);
43
44/// Default TCP/TLS connect timeout applied to the underlying HTTP client.
45///
46/// This bounds only connection establishment, so it is safe for the
47/// long-lived SSE streams produced by `generate_stream` (a whole-request
48/// timeout would kill a healthy stream mid-response).
49const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(30);
50
51fn build_client() -> Client {
52    Client::builder()
53        .connect_timeout(DEFAULT_CONNECT_TIMEOUT)
54        .build()
55        .expect("failed to build HTTP client")
56}
57
58/// Anthropic Claude model provider for the Daimon agent framework.
59///
60/// Supports chat completions, streaming, tool use, and configurable timeout,
61/// retries, and prompt caching.
62pub struct Anthropic {
63    client: Client,
64    api_key: String,
65    model_id: String,
66    base_url: String,
67    timeout: Option<Duration>,
68    max_retries: u32,
69    use_prompt_caching: bool,
70}
71
72impl std::fmt::Debug for Anthropic {
73    /// Hand-written to avoid leaking the plaintext API key in logs or panic
74    /// output; a derived `Debug` would print `api_key` verbatim.
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        f.debug_struct("Anthropic")
77            .field("client", &self.client)
78            .field("api_key", &"[redacted]")
79            .field("model_id", &self.model_id)
80            .field("base_url", &self.base_url)
81            .field("timeout", &self.timeout)
82            .field("max_retries", &self.max_retries)
83            .field("use_prompt_caching", &self.use_prompt_caching)
84            .finish()
85    }
86}
87
88impl Anthropic {
89    /// Creates a new Anthropic client using `ANTHROPIC_API_KEY` from the environment.
90    ///
91    /// The constructor never fails; if the environment variable is unset or
92    /// empty a warning is logged and requests will fail with an auth error.
93    pub fn new(model_id: impl Into<String>) -> Self {
94        let api_key = std::env::var("ANTHROPIC_API_KEY").unwrap_or_default();
95        if api_key.is_empty() {
96            tracing::warn!(
97                "ANTHROPIC_API_KEY is not set or empty; Anthropic requests will fail authentication"
98            );
99        }
100        Self::with_api_key(model_id, api_key)
101    }
102
103    /// Creates a new Anthropic client with an explicit API key.
104    pub fn with_api_key(model_id: impl Into<String>, api_key: impl Into<String>) -> Self {
105        Self {
106            client: build_client(),
107            api_key: api_key.into(),
108            model_id: model_id.into(),
109            base_url: DEFAULT_BASE_URL.to_string(),
110            timeout: None,
111            max_retries: 3,
112            use_prompt_caching: false,
113        }
114    }
115
116    /// Sets a custom base URL for the API (e.g. for proxies or testing).
117    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
118        self.base_url = base_url.into();
119        self
120    }
121
122    /// Sets a timeout for non-streaming HTTP requests (default: 120s).
123    ///
124    /// The timeout applies per-request to `generate`; `generate_stream` is a
125    /// long-lived SSE connection and is protected only by the client's
126    /// connect timeout, since a whole-request deadline would abort healthy
127    /// streams.
128    pub fn with_timeout(mut self, timeout: Duration) -> Self {
129        self.timeout = Some(timeout);
130        self
131    }
132
133    /// Sets the maximum number of retries for retriable errors (429, 529, 5xx).
134    pub fn with_max_retries(mut self, retries: u32) -> Self {
135        self.max_retries = retries;
136        self
137    }
138
139    /// Enables prompt caching by attaching `cache_control` breakpoints.
140    ///
141    /// Prompt caching is generally available; the request needs no
142    /// `anthropic-beta` header, only the `cache_control` blocks this enables.
143    pub fn with_prompt_caching(mut self) -> Self {
144        self.use_prompt_caching = true;
145        self
146    }
147
148    fn build_request_body(&self, request: &ChatRequest) -> AnthropicRequest {
149        let mut system: Option<serde_json::Value> = None;
150        let mut messages = Vec::new();
151
152        for msg in &request.messages {
153            match msg.role {
154                Role::System => {
155                    if let Some(ref text) = msg.content {
156                        if self.use_prompt_caching {
157                            system = Some(serde_json::json!([{
158                                "type": "text",
159                                "text": text,
160                                "cache_control": {"type": "ephemeral"}
161                            }]));
162                        } else {
163                            system = Some(serde_json::Value::String(text.clone()));
164                        }
165                    }
166                }
167                Role::User => {
168                    messages.push(AnthropicMessage {
169                        role: "user".to_string(),
170                        content: AnthropicContent::Text(msg.content.clone().unwrap_or_default()),
171                    });
172                }
173                Role::Assistant => {
174                    if !msg.tool_calls.is_empty() {
175                        // Preserve any assistant text that accompanied the tool
176                        // calls. Anthropic requires the text block to precede
177                        // the tool_use blocks; dropping it (the previous
178                        // behavior) loses the model's reasoning and can break
179                        // multi-turn continuity.
180                        let mut blocks: Vec<AnthropicContentBlock> = Vec::new();
181                        if let Some(ref text) = msg.content
182                            && !text.is_empty()
183                        {
184                            blocks.push(AnthropicContentBlock::Text { text: text.clone() });
185                        }
186                        blocks.extend(msg.tool_calls.iter().map(|tc| {
187                            AnthropicContentBlock::ToolUse {
188                                id: tc.id.clone(),
189                                name: tc.name.clone(),
190                                input: tc.arguments.clone(),
191                            }
192                        }));
193                        messages.push(AnthropicMessage {
194                            role: "assistant".to_string(),
195                            content: AnthropicContent::Blocks(blocks),
196                        });
197                    } else {
198                        messages.push(AnthropicMessage {
199                            role: "assistant".to_string(),
200                            content: AnthropicContent::Text(
201                                msg.content.clone().unwrap_or_default(),
202                            ),
203                        });
204                    }
205                }
206                Role::Tool => {
207                    messages.push(AnthropicMessage {
208                        role: "user".to_string(),
209                        content: AnthropicContent::Blocks(vec![
210                            AnthropicContentBlock::ToolResult {
211                                tool_use_id: msg.tool_call_id.clone().unwrap_or_default(),
212                                content: msg.content.clone().unwrap_or_default(),
213                            },
214                        ]),
215                    });
216                }
217            }
218        }
219
220        let tools: Option<Vec<AnthropicTool>> = if request.tools.is_empty() {
221            None
222        } else {
223            let mut tool_list: Vec<AnthropicTool> = request.tools.iter().map(Into::into).collect();
224            if self.use_prompt_caching
225                && let Some(last) = tool_list.last_mut()
226            {
227                last.cache_control = Some(serde_json::json!({"type": "ephemeral"}));
228            }
229            Some(tool_list)
230        };
231
232        AnthropicRequest {
233            model: self.model_id.clone(),
234            system,
235            messages,
236            tools,
237            max_tokens: request.max_tokens.unwrap_or(DEFAULT_MAX_TOKENS),
238            temperature: request.temperature,
239            stream: false,
240        }
241    }
242}
243
244impl Model for Anthropic {
245    fn model_id(&self) -> &str {
246        &self.model_id
247    }
248
249    #[tracing::instrument(skip_all, fields(model = %self.model_id))]
250    async fn generate(&self, request: &ChatRequest) -> Result<ChatResponse> {
251        let body = self.build_request_body(request);
252        let url = format!("{}/v1/messages", self.base_url);
253
254        tracing::debug!("building request for non-streaming generate");
255        let timeout = self.timeout.unwrap_or(DEFAULT_REQUEST_TIMEOUT);
256        let mut attempt = 0u32;
257
258        loop {
259            let req_builder = self
260                .client
261                .post(&url)
262                .timeout(timeout)
263                .header("x-api-key", &self.api_key)
264                .header("anthropic-version", API_VERSION)
265                .header("content-type", "application/json")
266                .json(&body);
267
268            tracing::debug!(attempt = attempt, "sending request to Anthropic API");
269            let response = req_builder
270                .send()
271                .await
272                .map_err(|e| DaimonError::Model(format!("Anthropic HTTP error: {e}")))?;
273            let status = response.status();
274            let retry_after = retry::parse_retry_after(response.headers());
275            let text = response.text().await.unwrap_or_default();
276
277            if status.is_success() {
278                tracing::debug!("request succeeded, parsing response");
279                let api_response: AnthropicResponse =
280                    serde_json::from_str(&text).map_err(DaimonError::Serialization)?;
281                return parse_response(api_response);
282            }
283
284            let code = status.as_u16();
285            let is_retriable = code == 429 || code == 529 || (500..600).contains(&code);
286
287            if is_retriable && attempt < self.max_retries {
288                let delay = retry::backoff_delay(attempt, retry_after);
289                tracing::debug!(
290                    status = %status,
291                    attempt = attempt,
292                    delay_ms = delay.as_millis(),
293                    "retriable error, backing off"
294                );
295                tokio::time::sleep(delay).await;
296                attempt += 1;
297            } else {
298                return Err(DaimonError::Model(format!(
299                    "Anthropic API error ({status}): {text}"
300                )));
301            }
302        }
303    }
304
305    #[tracing::instrument(skip_all, fields(model = %self.model_id))]
306    async fn generate_stream(&self, request: &ChatRequest) -> Result<ResponseStream> {
307        let mut body = self.build_request_body(request);
308        body.stream = true;
309        let url = format!("{}/v1/messages", self.base_url);
310
311        tracing::debug!("building request for streaming generate");
312        // Retry only the initial POST/handshake — once the stream is
313        // established, mid-stream failures must never be retried (the
314        // consumer has already observed a partial response).
315        let mut response = None;
316        for attempt in 0..=self.max_retries {
317            let req_builder = self
318                .client
319                .post(&url)
320                .header("x-api-key", &self.api_key)
321                .header("anthropic-version", API_VERSION)
322                .header("content-type", "application/json")
323                .json(&body);
324
325            tracing::debug!(attempt, "sending streaming request to Anthropic API");
326            let resp = req_builder
327                .send()
328                .await
329                .map_err(|e| DaimonError::Model(format!("Anthropic HTTP error: {e}")))?;
330            let status = resp.status();
331
332            if status.is_success() {
333                response = Some(resp);
334                break;
335            }
336
337            let retry_after = retry::parse_retry_after(resp.headers());
338            let text = resp.text().await.unwrap_or_default();
339            let code = status.as_u16();
340            let is_retriable = code == 429 || code == 529 || (500..600).contains(&code);
341
342            if is_retriable && attempt < self.max_retries {
343                let delay = retry::backoff_delay(attempt, retry_after);
344                tracing::debug!(status = %status, attempt, delay_ms = delay.as_millis(), "retriable error on stream handshake, backing off");
345                tokio::time::sleep(delay).await;
346            } else {
347                return Err(DaimonError::Model(format!(
348                    "Anthropic API error ({status}): {text}"
349                )));
350            }
351        }
352        let response = response.expect("loop breaks with a response or returns an error");
353
354        tracing::debug!("stream established, processing events");
355        let byte_stream = response.bytes_stream();
356
357        let stream = async_stream::try_stream! {
358            use futures::StreamExt;
359            use daimon_core::stream_util::LineBuffer;
360
361            // Byte-accurate line buffer: a multi-byte UTF-8 character can be
362            // split across two network chunks; only complete lines are decoded.
363            let mut buffer = LineBuffer::new();
364            // Maps an Anthropic content-block `index` to the tool_use id opened
365            // at that index. The streaming spec correlates `content_block_delta`
366            // (partial_json) and `content_block_stop` events to their block only
367            // via this index — the id is present just once, at
368            // `content_block_start`.
369            let mut index_to_id: HashMap<u64, String> = HashMap::new();
370            let mut stream = Box::pin(byte_stream);
371            // Reused across the whole stream so the parse path allocates no
372            // per-event Vec; drained after each event.
373            let mut events: Vec<StreamEvent> = Vec::new();
374
375            while let Some(chunk) = stream.next().await {
376                let chunk = chunk.map_err(|e| DaimonError::Model(format!("Anthropic stream error: {e}")))?;
377                buffer.push(&chunk);
378
379                while let Some(line) = buffer.next_line() {
380                    let line = line.trim();
381
382                    if line.is_empty() {
383                        continue;
384                    }
385
386                    if let Some(data) = line.strip_prefix("data: ") {
387                        match serde_json::from_str::<AnthropicStreamEvent>(data) {
388                            Ok(event) => {
389                                // Fill the reusable buffer (no per-event Vec
390                                // allocation), then drain it into the stream.
391                                handle_anthropic_stream_event_into(&mut index_to_id, event, &mut events);
392                                for stream_event in events.drain(..) {
393                                    yield stream_event;
394                                }
395                            }
396                            Err(e) => {
397                                tracing::debug!(error = %e, "dropping undeserializable Anthropic SSE event");
398                            }
399                        }
400                    }
401                }
402            }
403
404            // A stream can terminate without a trailing newline on its final
405            // `data:` line. `next_line` only yields newline-terminated lines, so
406            // that last event would otherwise be silently dropped. Drain the
407            // buffered remainder and run it through the identical SSE parse path.
408            if let Some(line) = buffer.take_remaining()
409                && let Some(data) = line.strip_prefix("data: ") {
410                    match serde_json::from_str::<AnthropicStreamEvent>(data) {
411                        Ok(event) => {
412                            handle_anthropic_stream_event_into(&mut index_to_id, event, &mut events);
413                            for stream_event in events.drain(..) {
414                                yield stream_event;
415                            }
416                        }
417                        Err(e) => {
418                            tracing::debug!(error = %e, "dropping undeserializable Anthropic SSE event");
419                        }
420                    }
421                }
422        };
423
424        Ok(Box::pin(stream))
425    }
426}
427
428/// Test-facing wrapper around [`handle_anthropic_stream_event_into`] that
429/// returns the produced events; the streaming loop reuses one buffer via the
430/// `_into` variant instead, avoiding a fresh `Vec` allocation per SSE event.
431#[cfg(test)]
432fn handle_anthropic_stream_event(
433    index_to_id: &mut HashMap<u64, String>,
434    event: AnthropicStreamEvent,
435) -> Vec<StreamEvent> {
436    let mut events = Vec::new();
437    handle_anthropic_stream_event_into(index_to_id, event, &mut events);
438    events
439}
440
441/// Advances the Anthropic streaming state machine by one SSE event, appending
442/// the [`StreamEvent`]s it produces (in order) to `events`.
443///
444/// This is the correctness-critical core of `generate_stream`: it maintains the
445/// `index -> tool_use id` correlation map so that `content_block_delta`
446/// (partial JSON arguments) and `content_block_stop` events — which carry only
447/// a block `index`, never the id — are attributed to the tool call opened at
448/// that index by the earlier `content_block_start`. Extracted from the
449/// `async_stream::try_stream!` block so it can be unit-tested without a live
450/// HTTP stream; the streaming loop drains whatever this appends.
451///
452/// Terminal handling: `message_delta` carries the final `stop_reason` and
453/// usage. [`StreamEvent::Done`] cannot carry either, so usage is logged at
454/// debug level and abnormal stop reasons (`refusal`, `pause_turn`) surface as
455/// an in-band [`StreamEvent::Error`] — the only channel that keeps them from
456/// ending the stream indistinguishably from a normal turn. Server-sent
457/// `{"type":"error"}` events (e.g. `overloaded_error` mid-stream) also become
458/// [`StreamEvent::Error`] items instead of being silently dropped.
459fn handle_anthropic_stream_event_into(
460    index_to_id: &mut HashMap<u64, String>,
461    event: AnthropicStreamEvent,
462    events: &mut Vec<StreamEvent>,
463) {
464    match event.r#type.as_str() {
465        "content_block_start" => {
466            if let Some(block) = event.content_block
467                && block.r#type == "tool_use"
468            {
469                let id = block.id.unwrap_or_default();
470                if let Some(idx) = event.index {
471                    index_to_id.insert(idx, id.clone());
472                }
473                events.push(StreamEvent::ToolCallStart {
474                    id,
475                    name: block.name.unwrap_or_default(),
476                });
477            }
478        }
479        "content_block_delta" => {
480            if let Some(delta) = event.delta {
481                if let Some(text) = delta.text {
482                    events.push(StreamEvent::TextDelta(text));
483                }
484                if let Some(json) = delta.partial_json {
485                    // Resolve the id from the block index so the consumer keys
486                    // accumulation to the right tool call.
487                    let id = event
488                        .index
489                        .and_then(|idx| index_to_id.get(&idx).cloned())
490                        .unwrap_or_default();
491                    events.push(StreamEvent::ToolCallDelta {
492                        id,
493                        arguments_delta: json,
494                    });
495                }
496            }
497        }
498        "content_block_stop" => {
499            if let Some(idx) = event.index
500                && let Some(id) = index_to_id.remove(&idx)
501            {
502                events.push(StreamEvent::ToolCallEnd { id });
503            }
504        }
505        "message_delta" => {
506            if let Some(usage) = event.usage {
507                tracing::debug!(
508                    output_tokens = usage.output_tokens,
509                    "Anthropic stream usage (message_delta)"
510                );
511            }
512            match event.delta.as_ref().and_then(|d| d.stop_reason.as_deref()) {
513                Some("refusal") => {
514                    events.push(StreamEvent::Error(
515                        "Anthropic ended the stream with stop_reason=refusal (the model declined to answer)"
516                            .to_string(),
517                    ));
518                }
519                Some("pause_turn") => {
520                    events.push(StreamEvent::Error(
521                        "Anthropic paused the turn (stop_reason=pause_turn); continue it with a follow-up request"
522                            .to_string(),
523                    ));
524                }
525                _ => {}
526            }
527        }
528        "error" => {
529            // Mid-stream server errors (e.g. overloaded_error) arrive as SSE
530            // events with HTTP 200; dropping them ended streams silently.
531            let detail = event
532                .error
533                .map(|e| e.to_string())
534                .unwrap_or_else(|| "unknown error".to_string());
535            events.push(StreamEvent::Error(format!(
536                "Anthropic stream error event: {detail}"
537            )));
538        }
539        "message_stop" => {
540            events.push(StreamEvent::Done);
541        }
542        other => {
543            tracing::debug!(
544                event_type = other,
545                "ignoring unhandled Anthropic SSE event type"
546            );
547        }
548    }
549}
550
551fn parse_response(response: AnthropicResponse) -> Result<ChatResponse> {
552    let mut text_content = String::new();
553    let mut tool_calls = Vec::new();
554
555    for block in &response.content {
556        match block {
557            AnthropicResponseBlock::Text { text } => {
558                text_content.push_str(text);
559            }
560            AnthropicResponseBlock::ToolUse { id, name, input } => {
561                tool_calls.push(ToolCall {
562                    id: id.clone(),
563                    name: name.clone(),
564                    arguments: input.clone(),
565                });
566            }
567        }
568    }
569
570    let stop_reason = match response.stop_reason.as_deref() {
571        Some("tool_use") => StopReason::ToolUse,
572        Some("max_tokens") => StopReason::MaxTokens,
573        Some("refusal") => StopReason::Refusal,
574        Some("pause_turn") => StopReason::PauseTurn,
575        _ => StopReason::EndTurn,
576    };
577
578    let message = if tool_calls.is_empty() {
579        Message::assistant(text_content)
580    } else {
581        Message {
582            role: Role::Assistant,
583            content: if text_content.is_empty() {
584                None
585            } else {
586                Some(text_content)
587            },
588            tool_calls,
589            tool_call_id: None,
590        }
591    };
592
593    Ok(ChatResponse {
594        message,
595        stop_reason,
596        usage: response.usage.map(|u| {
597            if u.cache_creation_input_tokens > 0 || u.cache_read_input_tokens > 0 {
598                tracing::debug!(
599                    cache_write = u.cache_creation_input_tokens,
600                    cache_read = u.cache_read_input_tokens,
601                    "prompt caching stats"
602                );
603            }
604            Usage {
605                input_tokens: u.input_tokens,
606                output_tokens: u.output_tokens,
607                cached_tokens: u.cache_read_input_tokens,
608            }
609        }),
610    })
611}
612
613// --- Anthropic API types ---
614
615#[derive(Serialize)]
616struct AnthropicRequest {
617    model: String,
618    #[serde(skip_serializing_if = "Option::is_none")]
619    system: Option<serde_json::Value>,
620    messages: Vec<AnthropicMessage>,
621    #[serde(skip_serializing_if = "Option::is_none")]
622    tools: Option<Vec<AnthropicTool>>,
623    max_tokens: u32,
624    #[serde(skip_serializing_if = "Option::is_none")]
625    temperature: Option<f32>,
626    stream: bool,
627}
628
629#[derive(Serialize)]
630struct AnthropicMessage {
631    role: String,
632    content: AnthropicContent,
633}
634
635#[derive(Serialize)]
636#[serde(untagged)]
637enum AnthropicContent {
638    Text(String),
639    Blocks(Vec<AnthropicContentBlock>),
640}
641
642#[derive(Serialize)]
643#[serde(tag = "type")]
644enum AnthropicContentBlock {
645    #[serde(rename = "text")]
646    Text { text: String },
647    #[serde(rename = "tool_use")]
648    ToolUse {
649        id: String,
650        name: String,
651        input: serde_json::Value,
652    },
653    #[serde(rename = "tool_result")]
654    ToolResult {
655        tool_use_id: String,
656        content: String,
657    },
658}
659
660#[derive(Serialize)]
661struct AnthropicTool {
662    name: String,
663    description: String,
664    input_schema: serde_json::Value,
665    #[serde(skip_serializing_if = "Option::is_none")]
666    cache_control: Option<serde_json::Value>,
667}
668
669impl From<&ToolSpec> for AnthropicTool {
670    fn from(spec: &ToolSpec) -> Self {
671        Self {
672            name: spec.name.clone(),
673            description: spec.description.clone(),
674            input_schema: spec.parameters.clone(),
675            cache_control: None,
676        }
677    }
678}
679
680#[derive(Deserialize)]
681struct AnthropicResponse {
682    content: Vec<AnthropicResponseBlock>,
683    stop_reason: Option<String>,
684    usage: Option<AnthropicUsage>,
685}
686
687#[derive(Deserialize)]
688#[serde(tag = "type")]
689enum AnthropicResponseBlock {
690    #[serde(rename = "text")]
691    Text { text: String },
692    #[serde(rename = "tool_use")]
693    ToolUse {
694        id: String,
695        name: String,
696        input: serde_json::Value,
697    },
698}
699
700#[derive(Deserialize)]
701struct AnthropicUsage {
702    input_tokens: u32,
703    output_tokens: u32,
704    #[serde(default)]
705    cache_creation_input_tokens: u32,
706    #[serde(default)]
707    cache_read_input_tokens: u32,
708}
709
710#[derive(Deserialize)]
711struct AnthropicStreamEvent {
712    r#type: String,
713    /// Content-block index. Present on `content_block_start`,
714    /// `content_block_delta`, and `content_block_stop`; correlates deltas to
715    /// the block (and thus the tool_use id) they belong to.
716    #[serde(default)]
717    index: Option<u64>,
718    content_block: Option<AnthropicStreamBlock>,
719    delta: Option<AnthropicStreamDelta>,
720    /// Cumulative usage, present on `message_delta`.
721    #[serde(default)]
722    usage: Option<AnthropicStreamUsage>,
723    /// Error payload, present on `{"type":"error"}` events.
724    #[serde(default)]
725    error: Option<serde_json::Value>,
726}
727
728#[derive(Deserialize)]
729struct AnthropicStreamBlock {
730    r#type: String,
731    id: Option<String>,
732    name: Option<String>,
733}
734
735#[derive(Deserialize)]
736struct AnthropicStreamDelta {
737    text: Option<String>,
738    partial_json: Option<String>,
739    /// Final stop reason, present on `message_delta`.
740    #[serde(default)]
741    stop_reason: Option<String>,
742}
743
744#[derive(Deserialize)]
745struct AnthropicStreamUsage {
746    #[serde(default)]
747    output_tokens: u32,
748}
749
750#[cfg(test)]
751mod tests {
752    use super::*;
753
754    #[test]
755    fn test_parse_response_text() {
756        let raw = AnthropicResponse {
757            content: vec![AnthropicResponseBlock::Text {
758                text: "hello world".into(),
759            }],
760            stop_reason: Some("end_turn".into()),
761            usage: Some(AnthropicUsage {
762                input_tokens: 10,
763                output_tokens: 5,
764                cache_creation_input_tokens: 0,
765                cache_read_input_tokens: 0,
766            }),
767        };
768        let resp = parse_response(raw).unwrap();
769        assert_eq!(resp.text(), "hello world");
770        assert_eq!(resp.stop_reason, StopReason::EndTurn);
771        assert!(!resp.has_tool_calls());
772    }
773
774    #[test]
775    fn test_parse_response_tool_use() {
776        let raw = AnthropicResponse {
777            content: vec![AnthropicResponseBlock::ToolUse {
778                id: "tu_1".into(),
779                name: "calc".into(),
780                input: serde_json::json!({"expr": "2+2"}),
781            }],
782            stop_reason: Some("tool_use".into()),
783            usage: None,
784        };
785        let resp = parse_response(raw).unwrap();
786        assert!(resp.has_tool_calls());
787        assert_eq!(resp.tool_calls()[0].name, "calc");
788        assert_eq!(resp.stop_reason, StopReason::ToolUse);
789    }
790
791    #[test]
792    fn test_parse_response_mixed_content() {
793        let raw = AnthropicResponse {
794            content: vec![
795                AnthropicResponseBlock::Text {
796                    text: "Let me calculate".into(),
797                },
798                AnthropicResponseBlock::ToolUse {
799                    id: "tu_1".into(),
800                    name: "calc".into(),
801                    input: serde_json::json!({}),
802                },
803            ],
804            stop_reason: Some("tool_use".into()),
805            usage: None,
806        };
807        let resp = parse_response(raw).unwrap();
808        assert!(resp.has_tool_calls());
809        assert_eq!(resp.message.content.as_deref(), Some("Let me calculate"));
810    }
811
812    #[test]
813    fn test_anthropic_new_default() {
814        let model = Anthropic::new("claude-sonnet-5");
815        assert_eq!(model.model_id, "claude-sonnet-5");
816        assert_eq!(model.base_url, DEFAULT_BASE_URL);
817    }
818
819    #[test]
820    fn test_with_timeout_sets_timeout() {
821        let timeout = std::time::Duration::from_secs(60);
822        let model = Anthropic::with_api_key("test", "key").with_timeout(timeout);
823        assert_eq!(model.timeout, Some(timeout));
824    }
825
826    #[test]
827    fn test_with_max_retries_sets_retries() {
828        let model = Anthropic::with_api_key("test", "key").with_max_retries(5);
829        assert_eq!(model.max_retries, 5);
830    }
831
832    #[test]
833    fn test_with_prompt_caching_enables_caching() {
834        let model = Anthropic::with_api_key("test", "key").with_prompt_caching();
835        assert!(model.use_prompt_caching);
836    }
837
838    #[test]
839    fn test_builder_chain_preserves_all_options() {
840        let timeout = std::time::Duration::from_secs(30);
841        let model = Anthropic::with_api_key("test", "key")
842            .with_base_url("https://custom.example.com")
843            .with_timeout(timeout)
844            .with_max_retries(2)
845            .with_prompt_caching();
846        assert_eq!(model.model_id, "test");
847        assert_eq!(model.base_url, "https://custom.example.com");
848        assert_eq!(model.timeout, Some(timeout));
849        assert_eq!(model.max_retries, 2);
850        assert!(model.use_prompt_caching);
851    }
852
853    #[test]
854    fn test_tool_spec_conversion() {
855        let spec = ToolSpec {
856            name: "search".into(),
857            description: "Web search".into(),
858            parameters: serde_json::json!({"type": "object"}),
859        };
860        let tool: AnthropicTool = (&spec).into();
861        assert_eq!(tool.name, "search");
862        assert_eq!(tool.description, "Web search");
863    }
864
865    #[test]
866    fn test_message_conversion_preserves_system_prompt() {
867        let model = Anthropic::new("test");
868        let request = ChatRequest {
869            messages: vec![Message::system("Be helpful"), Message::user("hi")],
870            tools: vec![],
871            temperature: None,
872            max_tokens: None,
873        };
874        let body = model.build_request_body(&request);
875        assert_eq!(body.system.as_ref().unwrap().as_str(), Some("Be helpful"));
876        assert_eq!(body.messages.len(), 1);
877    }
878
879    #[test]
880    fn test_prompt_caching_system_block() {
881        let model = Anthropic::with_api_key("test", "key").with_prompt_caching();
882        let request = ChatRequest {
883            messages: vec![Message::system("Be helpful"), Message::user("hi")],
884            tools: vec![],
885            temperature: None,
886            max_tokens: None,
887        };
888        let body = model.build_request_body(&request);
889        let sys = body.system.unwrap();
890        assert!(
891            sys.is_array(),
892            "system should be array when caching enabled"
893        );
894        let blocks = sys.as_array().unwrap();
895        assert_eq!(blocks[0]["type"], "text");
896        assert_eq!(blocks[0]["text"], "Be helpful");
897        assert!(blocks[0]["cache_control"].is_object());
898    }
899
900    #[test]
901    fn test_assistant_text_preserved_with_tool_call() {
902        // An assistant history message carrying both text and a tool call must
903        // serialize a leading text block followed by the tool_use block.
904        let model = Anthropic::new("test");
905        let assistant = Message {
906            role: Role::Assistant,
907            content: Some("Let me look that up.".to_string()),
908            tool_calls: vec![ToolCall {
909                id: "toolu_1".into(),
910                name: "search".into(),
911                arguments: serde_json::json!({"q": "rust"}),
912            }],
913            tool_call_id: None,
914        };
915        let request = ChatRequest {
916            messages: vec![Message::user("hi"), assistant],
917            tools: vec![],
918            temperature: None,
919            max_tokens: None,
920        };
921        let body = model.build_request_body(&request);
922        // Serialize and inspect the assistant message content blocks.
923        let json = serde_json::to_value(&body).unwrap();
924        let blocks = json["messages"][1]["content"].as_array().unwrap();
925        assert_eq!(blocks.len(), 2, "text block + tool_use block");
926        assert_eq!(blocks[0]["type"], "text");
927        assert_eq!(blocks[0]["text"], "Let me look that up.");
928        assert_eq!(blocks[1]["type"], "tool_use");
929        assert_eq!(blocks[1]["id"], "toolu_1");
930        assert_eq!(blocks[1]["name"], "search");
931    }
932
933    #[test]
934    fn test_assistant_tool_call_without_text_has_no_text_block() {
935        let model = Anthropic::new("test");
936        let assistant = Message::assistant_with_tool_calls(vec![ToolCall {
937            id: "toolu_1".into(),
938            name: "search".into(),
939            arguments: serde_json::json!({}),
940        }]);
941        let request = ChatRequest {
942            messages: vec![assistant],
943            tools: vec![],
944            temperature: None,
945            max_tokens: None,
946        };
947        let body = model.build_request_body(&request);
948        let json = serde_json::to_value(&body).unwrap();
949        let blocks = json["messages"][0]["content"].as_array().unwrap();
950        assert_eq!(blocks.len(), 1, "only the tool_use block");
951        assert_eq!(blocks[0]["type"], "tool_use");
952    }
953
954    #[test]
955    fn test_prompt_caching_tool_cache_control() {
956        let model = Anthropic::with_api_key("test", "key").with_prompt_caching();
957        let request = ChatRequest {
958            messages: vec![Message::user("hi")],
959            tools: vec![
960                ToolSpec {
961                    name: "a".into(),
962                    description: "first".into(),
963                    parameters: serde_json::json!({"type": "object"}),
964                },
965                ToolSpec {
966                    name: "b".into(),
967                    description: "second".into(),
968                    parameters: serde_json::json!({"type": "object"}),
969                },
970            ],
971            temperature: None,
972            max_tokens: None,
973        };
974        let body = model.build_request_body(&request);
975        let tools = body.tools.unwrap();
976        assert!(
977            tools[0].cache_control.is_none(),
978            "only last tool gets cache_control"
979        );
980        assert!(
981            tools[1].cache_control.is_some(),
982            "last tool should have cache_control"
983        );
984    }
985
986    // --- Streaming state-machine tests ---
987    //
988    // These exercise `handle_anthropic_stream_event` directly, feeding events
989    // deserialized from the exact JSON shapes Anthropic emits over SSE. This is
990    // the logic that previously lived (untested) inside the `try_stream!` block
991    // and that emitted tool-call argument deltas with an empty id before the
992    // `index -> id` correlation map was added.
993
994    /// Deserializes one SSE event payload the way the streaming loop does.
995    fn event(json: &str) -> AnthropicStreamEvent {
996        serde_json::from_str(json).expect("valid AnthropicStreamEvent JSON")
997    }
998
999    #[test]
1000    fn test_stream_event_tool_use_start_maps_index_to_id() {
1001        let mut idx = HashMap::new();
1002        let out = handle_anthropic_stream_event(
1003            &mut idx,
1004            event(
1005                r#"{"type":"content_block_start","index":0,
1006                    "content_block":{"type":"tool_use","id":"toolu_A","name":"f","input":{}}}"#,
1007            ),
1008        );
1009        assert_eq!(out.len(), 1);
1010        match &out[0] {
1011            StreamEvent::ToolCallStart { id, name } => {
1012                assert_eq!(id, "toolu_A");
1013                assert_eq!(name, "f");
1014            }
1015            other => panic!("expected ToolCallStart, got {other:?}"),
1016        }
1017        // The start must record the index so later deltas resolve to it.
1018        assert_eq!(idx.get(&0).map(String::as_str), Some("toolu_A"));
1019    }
1020
1021    #[test]
1022    fn test_stream_event_deltas_carry_correlated_id_and_concatenate() {
1023        let mut idx = HashMap::new();
1024        handle_anthropic_stream_event(
1025            &mut idx,
1026            event(
1027                r#"{"type":"content_block_start","index":0,
1028                    "content_block":{"type":"tool_use","id":"toolu_A","name":"f","input":{}}}"#,
1029            ),
1030        );
1031
1032        let mut assembled = String::new();
1033        for fragment in [r#"{\"x\":"#, "1}"] {
1034            let json = format!(
1035                r#"{{"type":"content_block_delta","index":0,
1036                     "delta":{{"type":"input_json_delta","partial_json":"{fragment}"}}}}"#
1037            );
1038            let out = handle_anthropic_stream_event(&mut idx, event(&json));
1039            assert_eq!(out.len(), 1);
1040            match &out[0] {
1041                StreamEvent::ToolCallDelta {
1042                    id,
1043                    arguments_delta,
1044                } => {
1045                    // Every delta must carry the correlated id, not "".
1046                    assert_eq!(
1047                        id, "toolu_A",
1048                        "delta must resolve to the opening block's id"
1049                    );
1050                    assembled.push_str(arguments_delta);
1051                }
1052                other => panic!("expected ToolCallDelta, got {other:?}"),
1053            }
1054        }
1055        assert_eq!(assembled, r#"{"x":1}"#);
1056    }
1057
1058    #[test]
1059    fn test_stream_event_stop_emits_end_and_clears_mapping() {
1060        let mut idx = HashMap::new();
1061        handle_anthropic_stream_event(
1062            &mut idx,
1063            event(
1064                r#"{"type":"content_block_start","index":0,
1065                    "content_block":{"type":"tool_use","id":"toolu_A","name":"f","input":{}}}"#,
1066            ),
1067        );
1068        let out = handle_anthropic_stream_event(
1069            &mut idx,
1070            event(r#"{"type":"content_block_stop","index":0}"#),
1071        );
1072        assert_eq!(out.len(), 1);
1073        match &out[0] {
1074            StreamEvent::ToolCallEnd { id } => assert_eq!(id, "toolu_A"),
1075            other => panic!("expected ToolCallEnd, got {other:?}"),
1076        }
1077        // The mapping is consumed on stop so a reused index can't leak the id.
1078        assert!(idx.is_empty(), "index mapping must be cleared on stop");
1079    }
1080
1081    #[test]
1082    fn test_stream_event_full_tool_call_lifecycle() {
1083        let mut idx = HashMap::new();
1084        let mut events = Vec::new();
1085        for json in [
1086            r#"{"type":"message_start"}"#,
1087            r#"{"type":"content_block_start","index":0,
1088                "content_block":{"type":"tool_use","id":"toolu_A","name":"f","input":{}}}"#,
1089            r#"{"type":"content_block_delta","index":0,
1090                "delta":{"type":"input_json_delta","partial_json":"{\"x\":"}}"#,
1091            r#"{"type":"content_block_delta","index":0,
1092                "delta":{"type":"input_json_delta","partial_json":"1}"}}"#,
1093            r#"{"type":"content_block_stop","index":0}"#,
1094            r#"{"type":"message_delta"}"#,
1095            r#"{"type":"message_stop"}"#,
1096        ] {
1097            events.extend(handle_anthropic_stream_event(&mut idx, event(json)));
1098        }
1099        // message_start / message_delta produce nothing; the rest form the
1100        // ordered lifecycle: Start, Delta, Delta, End, Done.
1101        assert_eq!(events.len(), 5, "got {events:?}");
1102        assert!(matches!(&events[0], StreamEvent::ToolCallStart { id, name }
1103            if id == "toolu_A" && name == "f"));
1104        assert!(matches!(&events[1], StreamEvent::ToolCallDelta { id, .. } if id == "toolu_A"));
1105        assert!(matches!(&events[2], StreamEvent::ToolCallDelta { id, .. } if id == "toolu_A"));
1106        assert!(matches!(&events[3], StreamEvent::ToolCallEnd { id } if id == "toolu_A"));
1107        assert!(matches!(&events[4], StreamEvent::Done));
1108    }
1109
1110    #[test]
1111    fn test_stream_event_text_block_index_not_confused_with_tool() {
1112        // A text block occupies index 0; a tool_use opens at index 1. The text
1113        // index must never be mapped to a tool id, and the tool's deltas at
1114        // index 1 must resolve to that tool's id.
1115        let mut idx = HashMap::new();
1116
1117        // Text block at index 0 — start is a no-op for the tool map.
1118        let start_text = handle_anthropic_stream_event(
1119            &mut idx,
1120            event(
1121                r#"{"type":"content_block_start","index":0,
1122                     "content_block":{"type":"text","text":""}}"#,
1123            ),
1124        );
1125        assert!(
1126            start_text.is_empty(),
1127            "text block start yields no StreamEvent"
1128        );
1129        assert!(
1130            idx.is_empty(),
1131            "text block index must not be mapped to a tool id"
1132        );
1133
1134        // Text delta at index 0.
1135        let text_delta = handle_anthropic_stream_event(
1136            &mut idx,
1137            event(
1138                r#"{"type":"content_block_delta","index":0,
1139                     "delta":{"type":"text_delta","text":"hi"}}"#,
1140            ),
1141        );
1142        assert!(matches!(text_delta.as_slice(), [StreamEvent::TextDelta(t)] if t == "hi"));
1143
1144        // tool_use opens at index 1.
1145        handle_anthropic_stream_event(
1146            &mut idx,
1147            event(
1148                r#"{"type":"content_block_start","index":1,
1149                     "content_block":{"type":"tool_use","id":"toolu_B","name":"g","input":{}}}"#,
1150            ),
1151        );
1152        let tool_delta = handle_anthropic_stream_event(
1153            &mut idx,
1154            event(
1155                r#"{"type":"content_block_delta","index":1,
1156                     "delta":{"type":"input_json_delta","partial_json":"{}"}}"#,
1157            ),
1158        );
1159        assert!(
1160            matches!(tool_delta.as_slice(), [StreamEvent::ToolCallDelta { id, .. }] if id == "toolu_B"),
1161            "tool delta at index 1 must resolve to toolu_B, got {tool_delta:?}"
1162        );
1163    }
1164
1165    #[test]
1166    fn test_parse_response_refusal_maps_to_refusal() {
1167        let raw = AnthropicResponse {
1168            content: vec![],
1169            stop_reason: Some("refusal".into()),
1170            usage: None,
1171        };
1172        let resp = parse_response(raw).unwrap();
1173        assert_eq!(resp.stop_reason, StopReason::Refusal);
1174    }
1175
1176    #[test]
1177    fn test_parse_response_pause_turn_maps_to_pause_turn() {
1178        let raw = AnthropicResponse {
1179            content: vec![],
1180            stop_reason: Some("pause_turn".into()),
1181            usage: None,
1182        };
1183        let resp = parse_response(raw).unwrap();
1184        assert_eq!(resp.stop_reason, StopReason::PauseTurn);
1185    }
1186
1187    #[test]
1188    fn test_debug_redacts_api_key() {
1189        let model = Anthropic::with_api_key("claude-sonnet-5", "sk-ant-supersecret-key");
1190        let dbg = format!("{model:?}");
1191        assert!(
1192            !dbg.contains("sk-ant-supersecret-key"),
1193            "Debug output must not contain the plaintext API key: {dbg}"
1194        );
1195        assert!(dbg.contains("[redacted]"));
1196    }
1197
1198    #[test]
1199    fn test_stream_event_error_is_surfaced() {
1200        // {"type":"error"} events (e.g. overloaded_error mid-stream) were
1201        // previously dropped by the `_ => {}` arm, ending streams silently.
1202        let mut idx = HashMap::new();
1203        let out = handle_anthropic_stream_event(
1204            &mut idx,
1205            event(r#"{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}"#),
1206        );
1207        assert_eq!(out.len(), 1, "got {out:?}");
1208        assert!(
1209            matches!(&out[0], StreamEvent::Error(msg) if msg.contains("overloaded_error")),
1210            "expected an in-band Error event, got {out:?}"
1211        );
1212    }
1213
1214    #[test]
1215    fn test_stream_message_delta_refusal_emits_error() {
1216        let mut idx = HashMap::new();
1217        let out = handle_anthropic_stream_event(
1218            &mut idx,
1219            event(
1220                r#"{"type":"message_delta","delta":{"stop_reason":"refusal"},"usage":{"output_tokens":3}}"#,
1221            ),
1222        );
1223        assert_eq!(out.len(), 1, "got {out:?}");
1224        assert!(matches!(&out[0], StreamEvent::Error(msg) if msg.contains("refusal")));
1225    }
1226
1227    #[test]
1228    fn test_stream_message_delta_pause_turn_emits_error() {
1229        let mut idx = HashMap::new();
1230        let out = handle_anthropic_stream_event(
1231            &mut idx,
1232            event(r#"{"type":"message_delta","delta":{"stop_reason":"pause_turn"}}"#),
1233        );
1234        assert_eq!(out.len(), 1, "got {out:?}");
1235        assert!(matches!(&out[0], StreamEvent::Error(msg) if msg.contains("pause_turn")));
1236    }
1237
1238    #[test]
1239    fn test_stream_message_delta_normal_stop_is_silent() {
1240        // end_turn / tool_use terminations are the normal path; message_stop
1241        // provides the Done, so message_delta must not add events.
1242        let mut idx = HashMap::new();
1243        let out = handle_anthropic_stream_event(
1244            &mut idx,
1245            event(
1246                r#"{"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}"#,
1247            ),
1248        );
1249        assert!(out.is_empty(), "got {out:?}");
1250    }
1251
1252    #[test]
1253    fn test_stream_event_interleaved_tool_blocks_route_by_index() {
1254        // Two tool_use blocks open at indices 0 and 1; deltas addressed to each
1255        // index must route to the correct id even when interleaved.
1256        let mut idx = HashMap::new();
1257        for json in [
1258            r#"{"type":"content_block_start","index":0,
1259                "content_block":{"type":"tool_use","id":"toolu_A","name":"f","input":{}}}"#,
1260            r#"{"type":"content_block_start","index":1,
1261                "content_block":{"type":"tool_use","id":"toolu_B","name":"g","input":{}}}"#,
1262        ] {
1263            handle_anthropic_stream_event(&mut idx, event(json));
1264        }
1265
1266        let d0 = handle_anthropic_stream_event(
1267            &mut idx,
1268            event(
1269                r#"{"type":"content_block_delta","index":0,
1270                     "delta":{"type":"input_json_delta","partial_json":"a"}}"#,
1271            ),
1272        );
1273        let d1 = handle_anthropic_stream_event(
1274            &mut idx,
1275            event(
1276                r#"{"type":"content_block_delta","index":1,
1277                     "delta":{"type":"input_json_delta","partial_json":"b"}}"#,
1278            ),
1279        );
1280        let d0b = handle_anthropic_stream_event(
1281            &mut idx,
1282            event(
1283                r#"{"type":"content_block_delta","index":0,
1284                     "delta":{"type":"input_json_delta","partial_json":"c"}}"#,
1285            ),
1286        );
1287
1288        assert!(matches!(d0.as_slice(),
1289            [StreamEvent::ToolCallDelta { id, arguments_delta }] if id == "toolu_A" && arguments_delta == "a"));
1290        assert!(matches!(d1.as_slice(),
1291            [StreamEvent::ToolCallDelta { id, arguments_delta }] if id == "toolu_B" && arguments_delta == "b"));
1292        assert!(matches!(d0b.as_slice(),
1293            [StreamEvent::ToolCallDelta { id, arguments_delta }] if id == "toolu_A" && arguments_delta == "c"));
1294    }
1295}