1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
//! Salvor LLM: an asynchronous Rust client for the Anthropic Messages API.
//!
//! This crate is the shared Messages API client for the Salvor agent runtime.
//! It was extracted from cargo-mentor's provider module (`mentor-provider`);
//! cargo-mentor will consume this crate in turn once it is published. The
//! crate holds no product logic from either project: only the typed wire
//! protocol, an async [`Client`], retry behaviour, and errors.
//!
//! # What it does
//!
//! [`Client::send_message`] sends a [`MessageRequest`] to `POST
//! {base_url}/v1/messages` and returns a typed [`MessageResponse`]. The client
//! is built from a [`Config`] that sets the base URL, an optional API key, a
//! retry cap, and a timeout. Retryable failures (`429`, `500`, `529`, and
//! transport errors) are retried with exponential backoff and jitter, honouring
//! a `retry-after` header when the server sends one.
//!
//! # Role in Salvor
//!
//! The agent loop calls this client for every model turn, and
//! the runtime's budget enforcement consumes the [`Usage`] reported with each
//! response, which is why [`Usage`] is public and central. Tool use is
//! first-class because the loop's tool dispatch reads
//! [`ContentBlock::ToolUse`] blocks and answers them with
//! [`Message::tool_result`].
//!
//! # Authentication
//!
//! Two schemes are supported, selected by [`Config::auth_kind`]. The default
//! [`AuthKind::ApiKey`] sends a standard API key (`sk-ant-api...`) as the
//! `x-api-key` header. [`AuthKind::Bearer`] sends the key as `Authorization:
//! Bearer <key>` and adds `anthropic-beta: oauth-2025-04-20`, which is what an
//! Anthropic subscription OAuth token (`sk-ant-oat...`, minted by `ant auth`)
//! requires: such a token is rejected on `x-api-key` and accepted only under
//! the bearer scheme. In bearer mode `x-api-key` is never sent. When
//! [`Config::api_key`] is `None`, no auth header is sent under either scheme.
//!
//! # Local endpoints
//!
//! LM Studio (0.4.1+) and Ollama (0.14+) speak the same Messages wire protocol.
//! Point [`Config::base_url`] at the local server and leave [`Config::api_key`]
//! unset; the client omits the `x-api-key` header when no key is configured.
//! Talking to a local model is a configuration change, not a code path.
//!
//! # Forward compatibility
//!
//! Responses are deserialized tolerantly. Unknown content-block types are kept
//! verbatim in [`ContentBlock::Unknown`], unknown stop reasons in
//! [`StopReason::Other`], and unknown top-level fields are ignored. A response
//! that grows new fields never fails to parse.
//!
//! # Streaming
//!
//! [`Client::stream_message`] sends the request with `stream: true` and returns
//! a [`MessageStream`] over the server-sent-events response. Pull typed
//! [`StreamEvent`]s one at a time with [`MessageStream::next_event`] for a live
//! consumer (a token or cost ticker), or fold the whole stream into a
//! [`MessageResponse`] with [`MessageStream::get_final_message`]. Streaming does
//! not change what a recording consumer stores: the assembled final message is
//! byte-for-byte equal in content and usage to what [`Client::send_message`]
//! returns for the same request, so which path produced it does not matter.
//! Only the initial connection is retried; once bytes flow, errors are surfaced
//! rather than retried, and an `error` event becomes an [`Error`].
//!
//! # Not yet included
//!
//! The request struct is kept minimal: tuning parameters such as `thinking` and
//! `temperature` are not sent, because current Claude models reject several of
//! them and the defaults are correct. They are expected to arrive in a later
//! version, additively.
//!
//! # Example
//!
//! ```no_run
//! use salvor_llm::{Client, Config, Message, MessageRequest};
//!
//! # async fn run() -> Result<(), salvor_llm::Error> {
//! let client = Client::new(Config::from_env())?;
//! let request = MessageRequest::new("claude-opus-4-8", 1024)
//! .push_message(Message::user("Explain the `?` operator in Rust."));
//! let response = client.send_message(&request).await?;
//! println!("{}", response.text());
//! # Ok(())
//! # }
//! ```
pub use ;
pub use ;
pub use ;
pub use ;