Skip to main content

rig_core/providers/anthropic/
wire.rs

1//! Configuration and wires for Messages-format completion, model listing,
2//! and credential verification. [`Dialect`] describes endpoint defaults and capabilities.
3//!
4//! ```no_run
5//! use rig_core::providers::anthropic::{Anthropic, completion::CLAUDE_SONNET_4_6};
6//!
7//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
8//! let wire = Anthropic::from_env()?.completion(CLAUDE_SONNET_4_6);
9//! # Ok(())
10//! # }
11//! ```
12
13use crate::catalog::ModelFacts;
14use crate::client::env::{self, EnvError};
15use crate::completion::options::FinalBody;
16use crate::completion::{CompletionRequest, ProviderCapabilities};
17use crate::error::EncodeError;
18use crate::operation::Completion;
19use crate::providers::internal::{credential_header, named_dialect};
20use crate::wire::{Body, Capabilities, Descriptor, Encoded, Framing, Mode, Secret, Wire};
21use serde::{Deserialize, Serialize};
22
23use super::completion::{
24    CacheTtl, default_max_tokens_for_model, document_source, image_source,
25    rejects_forced_tool_choice,
26};
27use super::streaming::MessagesDecoder;
28
29/// Endpoint defaults and capabilities for a Messages-format provider.
30/// Serializes by registered name. Serialization rejects modified or unregistered
31/// dialects; deserialization rejects unknown names.
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub struct Dialect {
34    /// The provider descriptor name, as records and telemetry spell it.
35    pub name: &'static str,
36    /// The default base URL.
37    pub base_url: &'static str,
38    /// The environment variable carrying the API key.
39    pub api_key_env: &'static str,
40    /// The environment variable overriding the base URL, when the provider
41    /// documents one.
42    pub base_url_env: Option<&'static str>,
43    /// The reply header carrying the provider's transport request id.
44    pub request_id_header: Option<&'static str>,
45    /// Everything that is not identity.
46    pub quirks: Quirks,
47}
48
49/// Token defaults, schema capabilities and request envelope for a
50/// Messages-format dialect.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52#[non_exhaustive]
53pub struct Quirks {
54    /// How `max_tokens` is defaulted when the caller sets none. Anthropic
55    /// requires the field, so a wire that cannot supply it fails the request
56    /// rather than sending one the API rejects.
57    pub max_tokens: MaxTokens,
58    /// Whether the provider implements Anthropic's constrained tool schemas.
59    /// A gateway that does not leaves Rig-generated tools unchanged.
60    pub strict_tool_schemas: bool,
61    /// Whether the provider takes thinking back without a signature, as
62    /// Kimi does. Elsewhere unsigned thinking
63    /// replays as text.
64    pub unsigned_thinking: bool,
65    /// How a request with tools asks the provider to stream tool input.
66    pub tool_input_streaming: ToolInputStreaming,
67    /// How the credential is sent.
68    pub auth: Auth,
69    /// The header every completion request carries a session id in: the
70    /// request's cache key when it has one, else a fresh id.
71    pub session_header: Option<&'static str>,
72    /// Whether `output_schema` maps to `output_config.format`. A dialect
73    /// that does not read it gets no schema, with a warning. An agent run
74    /// with tools then enforces the output through its output tool; one
75    /// without tools gets unconstrained output.
76    pub supports_output_format: bool,
77    /// Whether the catalog's per-token API prices apply to replies. A
78    /// server that is usually local has none.
79    pub catalog_priced: bool,
80    /// Whether a reply's cache writes are priced by the TTL split it
81    /// reports, at Anthropic's list rates: five-minute writes at the
82    /// catalog's write rate, one-hour writes at twice the input rate.
83    pub cache_ttl_pricing: bool,
84}
85
86/// How a Messages-format provider takes its credential.
87#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
88pub enum Auth {
89    /// The `x-api-key` header, always sent.
90    #[default]
91    ApiKey,
92    /// `Authorization: Bearer`, sent only when there is a credential, for a
93    /// local server that needs none and a hosted one that refuses
94    /// `x-api-key`.
95    OptionalBearer,
96}
97
98/// How a request with tools asks a Messages-format provider to stream each
99/// call's input as the model writes it. Without it, Anthropic holds a long
100/// argument value back and sends it in one burst. Unary requests ask too, so
101/// a tool definition, which a prompt cache keys on, is the same whether a
102/// turn streams.
103#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
104#[serde(rename_all = "snake_case")]
105pub enum ToolInputStreaming {
106    /// `eager_input_streaming: true` on each Rig tool definition.
107    #[default]
108    Eager,
109    /// The `fine-grained-tool-streaming-2025-05-14` beta flag, for a
110    /// provider that rejects the per-tool field.
111    BetaHeader,
112    /// Neither: the provider streams tool input as it chooses.
113    Off,
114}
115
116impl Quirks {
117    /// Anthropic's own contract.
118    pub const fn anthropic() -> Self {
119        Self {
120            max_tokens: MaxTokens::ByModel,
121            strict_tool_schemas: true,
122            unsigned_thinking: false,
123            tool_input_streaming: ToolInputStreaming::Eager,
124            auth: Auth::ApiKey,
125            session_header: None,
126            supports_output_format: true,
127            catalog_priced: true,
128            cache_ttl_pricing: true,
129        }
130    }
131
132    /// Default to 4096 output tokens without constrained tool schemas, with
133    /// eager tool input, which a Messages-format provider takes unless it is
134    /// known to reject it.
135    pub const fn gateway() -> Self {
136        Self {
137            max_tokens: MaxTokens::Fixed(4096),
138            strict_tool_schemas: false,
139            unsigned_thinking: false,
140            tool_input_streaming: ToolInputStreaming::Eager,
141            auth: Auth::ApiKey,
142            session_header: None,
143            supports_output_format: true,
144            catalog_priced: true,
145            cache_ttl_pricing: false,
146        }
147    }
148}
149
150/// Where a dialect's `max_tokens` default comes from.
151#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
152pub enum MaxTokens {
153    /// Anthropic's published per-model output limits.
154    ByModel,
155    /// One ceiling for every model, which is all a gateway documents.
156    Fixed(u64),
157}
158
159/// The API name the Messages wire reports for every dialect.
160pub(crate) const MESSAGES_API: &str = "anthropic.messages";
161
162/// Anthropic itself.
163pub const ANTHROPIC: Dialect = Dialect {
164    name: super::PROVIDER_NAME,
165    base_url: "https://api.anthropic.com",
166    api_key_env: "ANTHROPIC_API_KEY",
167    base_url_env: Some("ANTHROPIC_BASE_URL"),
168    request_id_header: Some("request-id"),
169    quirks: Quirks::anthropic(),
170};
171
172/// Registered Messages-format dialects in declaration order.
173const ALL: &[&Dialect] = &[
174    &ANTHROPIC,
175    &ZAI,
176    &MINIMAX,
177    &MOONSHOT,
178    &XIAOMIMIMO,
179    &OLLAMA,
180    &OPENCODE,
181    &OPENCODE_GO,
182];
183
184/// Every Messages-format dialect this build knows, in declaration order.
185pub fn all() -> impl Iterator<Item = &'static Dialect> {
186    ALL.iter().copied()
187}
188
189impl Dialect {
190    /// The dialect this crate ships under `name`.
191    pub fn by_name(name: &str) -> Option<Self> {
192        all().copied().find(|dialect| dialect.name == name)
193    }
194}
195
196impl Serialize for Dialect {
197    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
198        let registered = Self::by_name(self.name).as_ref() == Some(self);
199        named_dialect::serialize(serializer, "Anthropic", self.name, registered)
200    }
201}
202
203impl<'de> Deserialize<'de> for Dialect {
204    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
205        named_dialect::deserialize(deserializer, "Anthropic", Self::by_name)
206    }
207}
208
209/// Build a Messages-format dialect with `request-id` response headers and
210/// [`Quirks::gateway`] defaults. Only registered dialects support serialization.
211pub const fn compatible(
212    name: &'static str,
213    base_url: &'static str,
214    api_key_env: &'static str,
215    base_url_env: Option<&'static str>,
216) -> Dialect {
217    Dialect {
218        name,
219        base_url,
220        api_key_env,
221        base_url_env,
222        request_id_header: Some("request-id"),
223        quirks: Quirks::gateway(),
224    }
225}
226
227impl Dialect {
228    /// The `max_tokens` this dialect defaults `model` to, by the output
229    /// limit `facts` give it where the dialect defaults by model.
230    pub fn default_max_tokens(&self, facts: &ModelFacts, model: &str) -> Option<u64> {
231        match self.quirks.max_tokens {
232            MaxTokens::ByModel => default_max_tokens_for_model(facts, model),
233            MaxTokens::Fixed(tokens) => Some(tokens),
234        }
235    }
236}
237
238/// Z.AI's Anthropic-format endpoint.
239pub const ZAI: Dialect = compatible(
240    crate::providers::zai::PROVIDER_NAME,
241    crate::providers::zai::ANTHROPIC_API_BASE_URL,
242    "ZAI_API_KEY",
243    Some("ZAI_ANTHROPIC_API_BASE"),
244);
245
246/// MiniMax's Anthropic-format endpoint.
247pub const MINIMAX: Dialect = compatible(
248    crate::providers::minimax::PROVIDER_NAME,
249    crate::providers::minimax::GLOBAL_ANTHROPIC_API_BASE_URL,
250    "MINIMAX_API_KEY",
251    Some("MINIMAX_ANTHROPIC_API_BASE"),
252);
253
254/// Moonshot's Anthropic-format endpoint, which sends and takes back
255/// thinking without a signature.
256pub const MOONSHOT: Dialect = Dialect {
257    quirks: Quirks {
258        unsigned_thinking: true,
259        ..Quirks::gateway()
260    },
261    ..compatible(
262        crate::providers::moonshot::PROVIDER_NAME,
263        crate::providers::moonshot::ANTHROPIC_API_BASE_URL,
264        "MOONSHOT_API_KEY",
265        Some("MOONSHOT_ANTHROPIC_API_BASE"),
266    )
267};
268
269/// Xiaomi MiMo's Anthropic-format endpoint.
270pub const XIAOMIMIMO: Dialect = compatible(
271    crate::providers::xiaomimimo::PROVIDER_NAME,
272    crate::providers::xiaomimimo::ANTHROPIC_API_BASE_URL,
273    "XIAOMI_MIMO_API_KEY",
274    Some("XIAOMI_MIMO_ANTHROPIC_API_BASE"),
275);
276
277/// An Ollama daemon's Messages-format endpoint. A local daemon takes no
278/// credential; Ollama's cloud takes its key only as a bearer token. Its
279/// thinking carries no signature, and it constrains no output to a schema.
280/// It lists no models in Anthropic's shape: list them through the
281/// [`Ollama`](crate::providers::ollama::Ollama) client.
282pub const OLLAMA: Dialect = Dialect {
283    quirks: Quirks {
284        auth: Auth::OptionalBearer,
285        unsigned_thinking: true,
286        // Its `output_config` reads only `effort`.
287        supports_output_format: false,
288        // A daemon is usually local; the catalog's prices are Ollama Cloud's.
289        catalog_priced: false,
290        ..Quirks::gateway()
291    },
292    ..compatible(
293        crate::providers::ollama::PROVIDER_NAME,
294        "http://localhost:11434",
295        "OLLAMA_API_KEY",
296        Some("OLLAMA_API_BASE_URL"),
297    )
298};
299
300/// OpenCode Zen's Messages-format endpoint, for the models its catalog
301/// serves there.
302pub const OPENCODE: Dialect = compatible(
303    crate::providers::opencode::ZEN,
304    "https://opencode.ai/inference/anthropic",
305    "OPENCODE_API_KEY",
306    Some("OPENCODE_ANTHROPIC_BASE_URL"),
307);
308
309/// OpenCode Go's Messages-format endpoint, which refuses a request without
310/// an `x-opencode-session` header.
311pub const OPENCODE_GO: Dialect = Dialect {
312    quirks: Quirks {
313        session_header: Some(crate::providers::opencode::SESSION_HEADER),
314        ..Quirks::gateway()
315    },
316    ..compatible(
317        crate::providers::opencode::GO,
318        "https://opencode.ai/inference/go/anthropic",
319        "OPENCODE_API_KEY",
320        Some("OPENCODE_GO_ANTHROPIC_BASE_URL"),
321    )
322};
323
324/// The settings of a Messages-format provider: serializable, and the
325/// credential is never serialized. [`connect`](Self::connect) puts it on a
326/// transport as an [`Anthropic`](super::Anthropic) client.
327#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
328#[serde(deny_unknown_fields)]
329pub struct AnthropicConfig {
330    /// The API key, sent as the dialect's [`Auth`] says.
331    pub api_key: Secret,
332    /// The API root, without a trailing `/v1`.
333    pub base_url: String,
334    /// The `anthropic-version` header.
335    pub version: String,
336    /// The `anthropic-beta` flags, joined with commas when non-empty.
337    pub betas: Vec<String>,
338    /// Which Messages-format provider this is.
339    pub dialect: Dialect,
340    /// Where a request names its model and API version.
341    #[serde(default, skip_serializing_if = "Addressing::is_body")]
342    pub addressing: Addressing,
343}
344
345/// Where a Messages request names its model and API version.
346#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
347#[serde(rename_all = "snake_case")]
348pub enum Addressing {
349    /// `model` in the body and `version` as the `anthropic-version` header,
350    /// as Anthropic's own API takes them.
351    #[default]
352    Body,
353    /// No `model` in the body, because the URL names it, and `version` as
354    /// the body's `anthropic_version`, as cloud platforms take them. Such a
355    /// platform builds its URL with [`Messages::encode_with`].
356    Url,
357}
358
359impl Addressing {
360    /// Whether this is Anthropic's own [`Addressing::Body`].
361    fn is_body(&self) -> bool {
362        *self == Self::Body
363    }
364}
365
366impl AnthropicConfig {
367    /// Anthropic itself, with default settings.
368    pub fn new(api_key: impl Into<Secret>) -> Self {
369        Self::with_key(&ANTHROPIC, api_key)
370    }
371
372    /// `dialect` with `api_key`, at the dialect's default base URL and
373    /// with default settings. The base URL is normalized as
374    /// [`with_base_url`](Self::with_base_url) does.
375    pub fn with_key(dialect: &Dialect, api_key: impl Into<Secret>) -> Self {
376        Self {
377            api_key: api_key.into(),
378            base_url: normalize_base_url(dialect.base_url),
379            version: super::completion::ANTHROPIC_VERSION_LATEST.to_owned(),
380            betas: Vec::new(),
381            dialect: *dialect,
382            addressing: Addressing::Body,
383        }
384    }
385
386    /// Anthropic from `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL`.
387    pub fn from_env() -> Result<Self, EnvError> {
388        Self::from_env_with(&ANTHROPIC)
389    }
390
391    /// A Messages-format provider from the variables its dialect names. A
392    /// dialect whose credential is optional ([`Auth::OptionalBearer`]) takes
393    /// an unset key as none.
394    pub fn from_env_with(dialect: &Dialect) -> Result<Self, EnvError> {
395        let api_key = match dialect.quirks.auth {
396            Auth::ApiKey => env::required(dialect.api_key_env)?,
397            Auth::OptionalBearer => env::optional(dialect.api_key_env)?.unwrap_or_default(),
398        };
399        Self::from_env_with_credential(dialect, api_key)
400    }
401
402    /// `dialect` with `api_key` and the base URL its environment variable
403    /// names, if set.
404    pub(crate) fn from_env_with_credential(
405        dialect: &Dialect,
406        api_key: impl Into<Secret>,
407    ) -> Result<Self, EnvError> {
408        let mut provider = Self::with_key(dialect, api_key);
409        if let Some(name) = dialect.base_url_env
410            && let Some(base_url) = env::optional(name)?
411        {
412            provider.base_url = normalize_base_url(&base_url);
413        }
414        Ok(provider)
415    }
416
417    /// Pin the `anthropic-version` header.
418    pub fn with_version(mut self, version: impl Into<String>) -> Self {
419        self.version = version.into();
420        self
421    }
422
423    /// Request an `anthropic-beta` flag.
424    pub fn with_beta(mut self, beta: impl Into<String>) -> Self {
425        self.betas.push(beta.into());
426        self
427    }
428
429    /// Point the wire at another API root.
430    pub fn with_base_url(mut self, base_url: impl AsRef<str>) -> Self {
431        self.base_url = normalize_base_url(base_url.as_ref());
432        self
433    }
434
435    /// The Messages wire for `model`.
436    pub fn completion(&self, model: impl Into<String>) -> Messages {
437        let model = model.into();
438        Messages {
439            default_max_tokens: self
440                .dialect
441                .default_max_tokens(ModelFacts::builtin(), &model),
442            provider: self.clone(),
443            model,
444            prompt_caching: false,
445            static_prefix_cache_ttl: None,
446            strict_tools: false,
447            tool_input_streaming: self.dialect.quirks.tool_input_streaming,
448            facts: ModelFacts::default(),
449        }
450    }
451
452    /// The request headers every Messages-format endpoint takes.
453    pub(super) fn headers(&self, builder: http::request::Builder) -> http::request::Builder {
454        self.headers_with(builder, &self.betas)
455    }
456
457    /// [`Self::headers`], with `betas` as the `anthropic-beta` flags.
458    fn headers_with(
459        &self,
460        builder: http::request::Builder,
461        betas: &[String],
462    ) -> http::request::Builder {
463        let builder = match self.dialect.quirks.auth {
464            Auth::ApiKey => credential_header(builder, "x-api-key", self.api_key.expose()),
465            Auth::OptionalBearer if self.api_key.is_empty() => builder,
466            Auth::OptionalBearer => credential_header(
467                builder,
468                "authorization",
469                &format!("Bearer {}", self.api_key.expose()),
470            ),
471        };
472        let builder = builder.header("anthropic-version", &self.version);
473        if betas.is_empty() {
474            builder
475        } else {
476            builder.header("anthropic-beta", betas.join(","))
477        }
478    }
479
480    /// The configured `anthropic-beta` flags, then each of `extra` not
481    /// among them.
482    fn betas_with(&self, extra: &[&str]) -> Vec<String> {
483        let mut betas = self.betas.clone();
484        for extra in extra {
485            if !betas.iter().any(|beta| beta == extra) {
486                betas.push((*extra).to_owned());
487            }
488        }
489        betas
490    }
491}
492
493/// Trim the suffixes a user may paste from the API docs, so a base URL that
494/// already names the endpoint does not produce `/v1/messages/v1/messages`.
495pub fn normalize_base_url(base_url: &str) -> String {
496    let trimmed = base_url.trim_end_matches('/');
497    for suffix in ["/v1/messages", "/messages", "/v1"] {
498        if let Some(stripped) = trimmed.strip_suffix(suffix) {
499            return stripped.to_owned();
500        }
501    }
502    trimmed.to_owned()
503}
504
505/// The Messages wire: `POST /v1/messages`, SSE when streamed.
506#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
507pub struct Messages {
508    /// The provider this wire speaks to.
509    pub provider: AnthropicConfig,
510    /// The model to address.
511    pub model: String,
512    /// What `max_tokens` defaults to when the caller sets none. Anthropic
513    /// requires the field; `None` means a request without one is rejected
514    /// here rather than by the API.
515    pub default_max_tokens: Option<u64>,
516    /// Manual prompt caching: `cache_control` breakpoints on the system
517    /// prompt, the last tool definition, and the last content block of the
518    /// last message. The request's
519    /// [`cache`](crate::completion::GenerationOptions::cache) sets the
520    /// top-level marker and its TTL.
521    pub prompt_caching: bool,
522    /// TTL for the static prefix (tools + system), independent of the
523    /// conversation tail. `None` inherits the top-level TTL.
524    pub static_prefix_cache_ttl: Option<CacheTtl>,
525    /// Whether Rig-generated tools request the provider's strict validation.
526    pub strict_tools: bool,
527    /// How a request with tools asks for tool input as it is written; the
528    /// dialect's by default.
529    #[serde(default)]
530    pub tool_input_streaming: ToolInputStreaming,
531    /// The model facts the encoder reads and replies are priced by.
532    #[serde(skip)]
533    pub facts: ModelFacts,
534}
535
536impl Messages {
537    /// The same wire, encoding with `facts` and pricing its replies by
538    /// them. The `max_tokens` a request without one defaults to becomes the
539    /// dialect's default for the model under `facts`.
540    pub fn with_facts(mut self, facts: ModelFacts) -> Self {
541        self.default_max_tokens = self
542            .provider
543            .dialect
544            .default_max_tokens(&facts, &self.model);
545        self.facts = facts;
546        self
547    }
548
549    /// The `max_tokens` a request to `model` sends: its own, else the
550    /// dialect's default for another model than the wire's, else the wire's.
551    pub(super) fn max_tokens(&self, request: &CompletionRequest, model: &str) -> Option<u64> {
552        let other_model = (model != self.model).then_some(model);
553        request
554            .max_tokens
555            .or_else(|| {
556                other_model.and_then(|m| self.provider.dialect.default_max_tokens(&self.facts, m))
557            })
558            .or(self.default_max_tokens)
559    }
560
561    /// Enable cache breakpoints on the system prompt, final tool, and final message block.
562    /// With a request [`cache`](crate::completion::GenerationOptions::cache), the
563    /// provider owns the moving message breakpoint and the markers take its TTL.
564    /// Existing tool markers are preserved and count toward the four-breakpoint budget.
565    pub fn with_prompt_caching(mut self) -> Self {
566        self.prompt_caching = true;
567        self
568    }
569
570    /// Cache the static prefix (tool definitions and system prompt) at its
571    /// own TTL, independent of the conversation tail's.
572    ///
573    /// Mark the final tool definition and system prompt at `ttl` without
574    /// changing the conversation tail's TTL.
575    ///
576    /// ```no_run
577    /// use rig_core::providers::anthropic::completion::{CLAUDE_SONNET_4_6, CacheTtl};
578    /// use rig_core::providers::anthropic::Anthropic;
579    ///
580    /// # fn run() -> Result<(), Box<dyn std::error::Error>> {
581    /// let mut messages = Anthropic::from_env()?.completion(CLAUDE_SONNET_4_6);
582    /// messages.wire = messages.wire.with_static_prefix_cache_ttl(CacheTtl::OneHour);
583    /// # Ok(())
584    /// # }
585    /// ```
586    ///
587    /// One-hour markers must precede five-minute markers. A five-minute
588    /// prefix under a request with
589    /// [`CacheRetention::Long`](crate::completion::CacheRetention::Long) fails
590    /// during encoding.
591    /// Each marker must meet the model's minimum cacheable prompt length.
592    pub fn with_static_prefix_cache_ttl(mut self, ttl: CacheTtl) -> Self {
593        self.static_prefix_cache_ttl = Some(ttl);
594        self
595    }
596
597    /// Request Anthropic's strict tool use for every Rig-generated tool.
598    ///
599    /// Anthropic constrains tool inputs to the supported JSON Schema subset
600    /// when `strict: true` is present on a tool definition. Rig sanitizes
601    /// each generated schema for that subset and leaves provider-specific
602    /// tools supplied through `additional_params` unchanged. Unsupported
603    /// validation keywords are retained only as model guidance in schema
604    /// descriptions; neither Anthropic nor Rig enforces them, so validate
605    /// tool inputs before execution when those constraints matter.
606    ///
607    /// Anthropic caches compiled schemas for up to 24 hours: do not include
608    /// PHI in schema property names, enum or const values, or regex
609    /// patterns. A dialect that does not implement constrained tool schemas
610    /// ignores this.
611    pub fn with_strict_tools(mut self) -> Self {
612        self.strict_tools = true;
613        self
614    }
615
616    /// Choose how a request with tools asks for tool input as the model
617    /// writes it, for a gateway whose support differs from its dialect's:
618    /// [`ToolInputStreaming::BetaHeader`] for one that rejects the per-tool
619    /// field, [`ToolInputStreaming::Off`] for one that rejects both.
620    ///
621    /// ```no_run
622    /// use rig_core::providers::anthropic::{Anthropic, completion::CLAUDE_SONNET_4_6};
623    /// use rig_core::providers::anthropic::ToolInputStreaming;
624    ///
625    /// # fn run() -> Result<(), Box<dyn std::error::Error>> {
626    /// let mut messages = Anthropic::from_env()?.completion(CLAUDE_SONNET_4_6);
627    /// messages.wire = messages.wire.with_tool_input_streaming(ToolInputStreaming::BetaHeader);
628    /// # Ok(())
629    /// # }
630    /// ```
631    pub fn with_tool_input_streaming(mut self, streaming: ToolInputStreaming) -> Self {
632        self.tool_input_streaming = streaming;
633        self
634    }
635}
636
637/// A Messages request encoded but not yet addressed or authenticated: what
638/// a platform serving the Messages API under its own envelope sends.
639#[derive(Debug, Clone, PartialEq)]
640#[non_exhaustive]
641pub struct Prepared {
642    /// The model the request addresses.
643    pub model: String,
644    /// The request body.
645    pub body: FinalBody,
646    /// The `anthropic-beta` flags: the configured ones, then the ones the
647    /// request needs.
648    pub betas: Vec<String>,
649}
650
651impl Messages {
652    /// Encode `request` as [`Wire::encode`] does, with `envelope` building
653    /// the HTTP request in place of `POST /v1/messages` with an API key.
654    /// The framing and request-id header stay this wire's, so a platform
655    /// that serves the Messages API at another address, with other
656    /// credentials or another body envelope, reads replies as this wire
657    /// does.
658    ///
659    /// # Errors
660    ///
661    /// When the request does not encode, or `envelope` fails.
662    pub fn encode_with(
663        &self,
664        request: CompletionRequest,
665        mode: Mode,
666        envelope: impl FnOnce(Prepared) -> Result<http::Request<Body>, EncodeError>,
667    ) -> Result<Encoded, EncodeError> {
668        let model = request.model.clone().unwrap_or_else(|| self.model.clone());
669        let fine_grained = !request.tools.is_empty()
670            && self.tool_input_streaming == ToolInputStreaming::BetaHeader;
671        let body = super::completion::body(self, &request, mode)?;
672        let betas: Vec<&str> = [
673            body.get("thinking")
674                .and_then(|thinking| thinking.get("block_binding"))
675                .is_some_and(serde_json::Value::is_object)
676                .then_some(super::completion::THINKING_BINDING_BETA),
677            fine_grained.then_some(super::completion::FINE_GRAINED_TOOL_STREAMING_BETA),
678        ]
679        .into_iter()
680        .flatten()
681        .collect();
682        crate::providers::internal::trace_json(
683            crate::providers::internal::LogTarget::Completions,
684            "Anthropic completion request",
685            &body,
686        );
687        let request = envelope(Prepared {
688            model,
689            body,
690            betas: self.provider.betas_with(&betas),
691        })?;
692        Ok(Encoded::new(
693            request,
694            match mode {
695                Mode::Unary => Framing::Whole,
696                Mode::Streaming => Framing::Sse,
697            },
698        )
699        .with_request_id_header(self.provider.dialect.request_id_header))
700    }
701}
702
703impl Wire for Messages {
704    type Op = Completion;
705    type Payload = crate::wire::Encoded;
706    type Frame = crate::wire::WireFrame;
707    type Event = super::streaming::MessagesEvent;
708    type Decoder<'id> = MessagesDecoder;
709    type Reassembler = super::streaming::document::Message;
710
711    /// Constrained output decoding does not suppress strict tool calls. A
712    /// dialect that reads no output format leaves the output to the agent's
713    /// tool.
714    fn describe(&self) -> Descriptor<'_> {
715        Descriptor::new(self.provider.dialect.name)
716            .model(self.model.as_str())
717            .facts(&self.facts)
718            .capabilities(Capabilities::completion(
719                ProviderCapabilities::default()
720                    .with_native_output_tool_composition(
721                        self.provider.dialect.quirks.supports_output_format,
722                    )
723                    .with_forced_tool_choice_rejected(rejects_forced_tool_choice(
724                        &self.facts,
725                        &self.model,
726                    )),
727            ))
728            .replay(self)
729    }
730
731    fn encode(&self, request: CompletionRequest, mode: Mode) -> Result<Encoded, EncodeError> {
732        let session = self.provider.dialect.quirks.session_header.map(|name| {
733            let id = crate::providers::internal::request_session_id(&request);
734            (name, id)
735        });
736        self.encode_with(request, mode, |prepared| {
737            let mut builder = self
738                .provider
739                .headers_with(
740                    http::Request::post(format!("{}/v1/messages", self.provider.base_url)),
741                    &prepared.betas,
742                )
743                .header(http::header::CONTENT_TYPE, "application/json");
744            if let Some((name, id)) = session {
745                builder = builder.header(name, id);
746            }
747            Ok(builder.body(prepared.body.into_body())?)
748        })
749    }
750
751    fn decoder<'id>(&self) -> Self::Decoder<'id> {
752        MessagesDecoder::new(self.provider.dialect.quirks)
753    }
754}
755
756impl crate::completion::ReplayTarget for Messages {
757    /// Whether the catalog prices this dialect's replies
758    /// ([`Quirks::catalog_priced`]).
759    fn catalog_priced(&self) -> bool {
760        self.provider.dialect.quirks.catalog_priced
761    }
762
763    /// Section 6.1 of the typed-options design, by dialect and model class.
764    fn map_options(
765        &self,
766        request: &CompletionRequest,
767        fields: crate::completion::options::OptionFields<'_>,
768    ) -> crate::completion::options::OptionMap {
769        super::options::map_options(self, request, fields)
770    }
771
772    fn facts(&self) -> Option<&ModelFacts> {
773        Some(&self.facts)
774    }
775
776    fn api(&self) -> crate::message::Api {
777        crate::message::Api::from_static(MESSAGES_API)
778    }
779
780    fn provider(&self) -> &str {
781        self.provider.dialect.name
782    }
783
784    fn model(&self) -> &str {
785        &self.model
786    }
787
788    /// Messages takes images in user turns and tool results, never in
789    /// assistant turns, on models that read images: every Claude model, and
790    /// on another dialect each model its catalog entry lists as reading
791    /// them, or for a model the catalog does not list each dialect's
792    /// documented vision naming.
793    fn accepts(&self, model: &str) -> crate::completion::Accepts {
794        let rule: Option<fn(&str) -> bool> = match self.provider.dialect.name {
795            name if name == ANTHROPIC.name => None,
796            name if name == ZAI.name => Some(crate::providers::zai::reads_images),
797            name if name == MOONSHOT.name => Some(crate::providers::moonshot::reads_images),
798            name if name == MINIMAX.name => Some(crate::providers::minimax::reads_images),
799            name if name == XIAOMIMIMO.name => Some(crate::providers::xiaomimimo::reads_images),
800            _ => Some(|_| true),
801        };
802        let images = rule.is_none_or(|rule| {
803            self.facts
804                .reads_images_or(self.provider.dialect.name, model, rule)
805        });
806        crate::completion::Accepts {
807            user_images: images,
808            assistant_images: false,
809            tool_result_images: images,
810            tools: true,
811            // Thinking replays only with its signature.
812            foreign_reasoning: false,
813        }
814    }
815
816    /// The encoder carries images by typed base64, URL or file id in user
817    /// turns and tool results, and documents by file id, PDF data or URL,
818    /// or the text they hold. Assistant images, audio and video it never
819    /// carries.
820    fn encodes(&self, _model: &str, media: crate::completion::Media<'_>) -> bool {
821        use crate::completion::{Media, Place};
822        match media {
823            Media::Image(image, Place::User | Place::ToolResult) => image_source(image).is_some(),
824            Media::Document(document) => document_source(document).is_some(),
825            Media::Image(_, Place::Assistant) | Media::Audio(_) | Media::Video(_) => false,
826        }
827    }
828
829    /// Anthropic takes call ids of `[a-zA-Z0-9_-]`, at most 64 long.
830    fn normalize_tool_call_id(
831        &self,
832        id: &str,
833        _model: &str,
834        _source: Option<&crate::message::Origin>,
835    ) -> String {
836        crate::providers::internal::wire_ids::legal_call_id(id, 64)
837    }
838
839    /// An edited call keeps the `caller` that ties it to the code
840    /// execution that made it.
841    fn identity(&self, item: &serde_json::Value) -> serde_json::Map<String, serde_json::Value> {
842        item.get("caller")
843            .filter(|_| item.get("type").and_then(serde_json::Value::as_str) == Some("tool_use"))
844            .map(|caller| serde_json::Map::from_iter([("caller".to_owned(), caller.clone())]))
845            .unwrap_or_default()
846    }
847
848    /// A model that takes no system message inside `messages` gets every
849    /// one folded into the leading system prompt.
850    fn later_system(&self, model: &str) -> crate::completion::LaterSystem {
851        if super::completion::takes_mid_conversation_system(&self.facts, model) {
852            crate::completion::LaterSystem::InPlace
853        } else {
854            crate::completion::LaterSystem::Leading
855        }
856    }
857
858    /// A container item is request state, never content, and unsigned
859    /// thinking that is redacted or blank has nothing to send.
860    /// Claude models whose thinking binds to the tools and system prompt it
861    /// was made under.
862    fn binds_context(&self, model: &str) -> bool {
863        self.provider.dialect.name == ANTHROPIC.name
864            && super::completion::binds_context(&self.facts, model)
865    }
866
867    /// A request in adaptive thinking asks Anthropic to drop a block bound
868    /// to another context (`drop_block`), so its turns replay verbatim.
869    /// The thinking read is what the body sends: the mapped `reasoning`,
870    /// with `additional_params` over it.
871    fn drops_unbound_items(&self, request: &CompletionRequest) -> bool {
872        let model = request.model.as_deref().unwrap_or(&self.model);
873        let thinking = crate::completion::options::param(self, request, "thinking");
874        super::completion::drops_unbound_thinking(self, model, thinking.as_ref())
875    }
876
877    /// What the encoder sends for the block, so the two never disagree.
878    fn sends_alone(&self, block: &crate::message::AssistantContent) -> bool {
879        let ids = crate::providers::internal::wire_ids::WireIds::default();
880        super::completion::assistant_part(block, self, &ids).is_some()
881    }
882
883    fn call_id_slot(&self) -> Option<&'static str> {
884        Some("/id")
885    }
886
887    fn blob_slots(&self) -> &'static [&'static str] {
888        &["/signature", "/data"]
889    }
890
891    /// A server tool's use (`server_tool_use`, `mcp_tool_use`) and the
892    /// `*_tool_result` that answers it by `tool_use_id`.
893    fn hosted_pair(
894        &self,
895        item: &serde_json::Value,
896    ) -> Option<(crate::completion::Pairing, String)> {
897        use crate::completion::Pairing;
898        let kind = item.get("type")?.as_str()?;
899        let (side, key) = if kind.ends_with("_tool_use") {
900            (Pairing::Use, "id")
901        } else if kind.ends_with("_tool_result") {
902            (Pairing::Result, "tool_use_id")
903        } else {
904            return None;
905        };
906        Some((side, item.get(key)?.as_str()?.to_owned()))
907    }
908}
909
910#[cfg(test)]
911mod tests;