Skip to main content

rig_core/providers/anthropic/
extension.rs

1//! Typed request options and reply extras for Anthropic's own Messages API.
2//! [`AnthropicExt`] keys them by [`PROVIDER_NAME`](super::PROVIDER_NAME); the
3//! Messages wire reads the entry only when its dialect is Anthropic, so a
4//! gateway speaking the same format never receives them.
5//!
6//! A field marked "+ beta" needs its `anthropic-beta` flag set on the
7//! provider with [`AnthropicConfig::with_beta`](super::AnthropicConfig::with_beta);
8//! without it the API rejects the request.
9//!
10//! ```
11//! use rig_core::completion::CompletionRequest;
12//! use rig_core::providers::anthropic::extension::{AnthropicOptions, InferenceGeo};
13//!
14//! let options = AnthropicOptions::default()
15//!     .metadata_user_id("user-7")
16//!     .inference_geo(InferenceGeo::Us);
17//! let request = CompletionRequest::new("hi").provider_option(options);
18//! # let _ = request;
19//! ```
20
21use serde::ser::SerializeMap;
22use serde::{Deserialize, Serialize, Serializer};
23use serde_json::Value;
24
25use super::completion::{CLAUDE_FABLE_5_2, CLAUDE_OPUS_4_8, CLAUDE_OPUS_5, CLAUDE_OPUS_5_5};
26use super::wire::MESSAGES_API;
27use crate::catalog::Sampling;
28use crate::completion::{
29    CompletionRequest, ExtensionOptions, ProviderExtension, ReplayTarget, ReplyExtras,
30};
31use crate::message::Api;
32
33/// The `anthropic-beta` flag fast mode needs.
34pub const FAST_MODE_BETA: &str = "fast-mode-2026-02-01";
35/// The `anthropic-beta` flag task budgets need.
36pub const TASK_BUDGETS_BETA: &str = "task-budgets-2026-03-13";
37/// The `anthropic-beta` flag [`Fallbacks::Default`] needs.
38pub const SERVER_SIDE_FALLBACK_BETA: &str = "server-side-fallback-2026-07-01";
39/// The `anthropic-beta` flag [`Fallbacks::Models`] needs.
40pub const SERVER_SIDE_FALLBACK_MODELS_BETA: &str = "server-side-fallback-2026-06-01";
41/// The `anthropic-beta` flag context editing needs.
42pub const CONTEXT_MANAGEMENT_BETA: &str = "context-management-2025-06-27";
43/// The `anthropic-beta` flag the MCP connector needs.
44pub const MCP_CLIENT_BETA: &str = "mcp-client-2025-11-20";
45/// The `anthropic-beta` flag cache diagnostics need.
46pub const CACHE_DIAGNOSIS_BETA: &str = "cache-diagnosis-2026-04-07";
47
48/// The models fast mode runs on.
49const FAST_MODELS: &[&str] = &[
50    CLAUDE_FABLE_5_2,
51    CLAUDE_OPUS_5_5,
52    CLAUDE_OPUS_5,
53    CLAUDE_OPUS_4_8,
54];
55
56/// Anthropic's typed options and extras.
57#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
58pub struct AnthropicExt;
59
60impl ProviderExtension for AnthropicExt {
61    const PROVIDER: &'static str = super::PROVIDER_NAME;
62    type Options = AnthropicOptions;
63    type Extras = AnthropicExtras;
64}
65
66/// Anthropic's request options. The Messages API is its one route, so every
67/// field sits in the shared section.
68#[non_exhaustive]
69#[derive(Clone, Debug, Default, PartialEq, Serialize)]
70pub struct AnthropicOptions {
71    /// The fields every route sends.
72    #[serde(rename = "*")]
73    pub shared: AnthropicShared,
74}
75
76/// The fields of [`AnthropicOptions`]. Each unset field is left out of the
77/// body.
78#[non_exhaustive]
79#[derive(Clone, Debug, Default, PartialEq)]
80pub struct AnthropicShared {
81    /// `top_k`: sample from the `k` most likely tokens. Refused on models
82    /// that fix their sampling.
83    pub top_k: Option<u32>,
84    /// `metadata.user_id`: an opaque id of the end user, at most 512
85    /// characters.
86    pub metadata_user_id: Option<String>,
87    /// `inference_geo`: where inference runs.
88    pub inference_geo: Option<InferenceGeo>,
89    /// `speed`. [`Speed::Fast`] + beta [`FAST_MODE_BETA`], on Claude Fable
90    /// 5.2, Opus 5.5, Opus 5 and Opus 4.8 only; refused on other listed
91    /// models.
92    pub speed: Option<Speed>,
93    /// `output_config.task_budget` + beta [`TASK_BUDGETS_BETA`].
94    pub task_budget: Option<TaskBudget>,
95    /// `fallbacks`: the models a refused request is re-run on, + beta
96    /// [`SERVER_SIDE_FALLBACK_BETA`] or [`SERVER_SIDE_FALLBACK_MODELS_BETA`].
97    pub fallbacks: Option<Fallbacks>,
98    /// `container`: the code-execution container to reuse, or the skills to
99    /// load into it. It replaces the container the history names.
100    pub container: Option<ContainerParam>,
101    /// `context_management` + beta [`CONTEXT_MANAGEMENT_BETA`].
102    pub context_management: Option<ContextManagement>,
103    /// `mcp_servers` + beta [`MCP_CLIENT_BETA`]. Each server also needs an
104    /// `mcp_toolset` tool naming it.
105    pub mcp_servers: Vec<McpServer>,
106    /// `diagnostics.previous_message_id` + beta [`CACHE_DIAGNOSIS_BETA`]:
107    /// `Some(None)` sends `null` on a conversation's first request,
108    /// `Some(Some(id))` the previous reply's id.
109    pub diagnostics_previous_message_id: Option<Option<String>>,
110}
111
112impl Serialize for AnthropicShared {
113    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
114        let Self {
115            top_k,
116            metadata_user_id,
117            inference_geo,
118            speed,
119            task_budget,
120            fallbacks,
121            container,
122            context_management,
123            mcp_servers,
124            diagnostics_previous_message_id,
125        } = self;
126        let mut map = serializer.serialize_map(None)?;
127        if let Some(top_k) = top_k {
128            map.serialize_entry("top_k", top_k)?;
129        }
130        if let Some(user_id) = metadata_user_id {
131            map.serialize_entry("metadata", &Nested("user_id", user_id))?;
132        }
133        if let Some(geo) = inference_geo {
134            map.serialize_entry("inference_geo", geo)?;
135        }
136        if let Some(speed) = speed {
137            map.serialize_entry("speed", speed)?;
138        }
139        if let Some(budget) = task_budget {
140            map.serialize_entry("output_config", &Nested("task_budget", budget))?;
141        }
142        if let Some(fallbacks) = fallbacks {
143            map.serialize_entry("fallbacks", fallbacks)?;
144        }
145        if let Some(container) = container {
146            map.serialize_entry("container", container)?;
147        }
148        if let Some(context_management) = context_management {
149            map.serialize_entry("context_management", context_management)?;
150        }
151        if !mcp_servers.is_empty() {
152            map.serialize_entry("mcp_servers", mcp_servers)?;
153        }
154        if let Some(previous) = diagnostics_previous_message_id {
155            map.serialize_entry("diagnostics", &Nested("previous_message_id", previous))?;
156        }
157        map.end()
158    }
159}
160
161/// A one-key object: `{key: value}`.
162pub(crate) struct Nested<'a, T>(pub(crate) &'static str, pub(crate) &'a T);
163
164impl<T: Serialize> Serialize for Nested<'_, T> {
165    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
166        let mut map = serializer.serialize_map(Some(1))?;
167        map.serialize_entry(self.0, self.1)?;
168        map.end()
169    }
170}
171
172impl AnthropicOptions {
173    /// Set [`AnthropicShared::top_k`].
174    pub fn top_k(mut self, top_k: u32) -> Self {
175        self.shared.top_k = Some(top_k);
176        self
177    }
178
179    /// Set [`AnthropicShared::metadata_user_id`].
180    pub fn metadata_user_id(mut self, user_id: impl Into<String>) -> Self {
181        self.shared.metadata_user_id = Some(user_id.into());
182        self
183    }
184
185    /// Set [`AnthropicShared::inference_geo`].
186    pub fn inference_geo(mut self, geo: InferenceGeo) -> Self {
187        self.shared.inference_geo = Some(geo);
188        self
189    }
190
191    /// Set [`AnthropicShared::speed`].
192    pub fn speed(mut self, speed: Speed) -> Self {
193        self.shared.speed = Some(speed);
194        self
195    }
196
197    /// Set [`AnthropicShared::task_budget`].
198    pub fn task_budget(mut self, budget: TaskBudget) -> Self {
199        self.shared.task_budget = Some(budget);
200        self
201    }
202
203    /// Set [`AnthropicShared::fallbacks`].
204    pub fn fallbacks(mut self, fallbacks: Fallbacks) -> Self {
205        self.shared.fallbacks = Some(fallbacks);
206        self
207    }
208
209    /// Set [`AnthropicShared::container`].
210    pub fn container(mut self, container: impl Into<ContainerParam>) -> Self {
211        self.shared.container = Some(container.into());
212        self
213    }
214
215    /// Set [`AnthropicShared::context_management`].
216    pub fn context_management(mut self, context_management: ContextManagement) -> Self {
217        self.shared.context_management = Some(context_management);
218        self
219    }
220
221    /// Add one server to [`AnthropicShared::mcp_servers`].
222    pub fn mcp_server(mut self, server: McpServer) -> Self {
223        self.shared.mcp_servers.push(server);
224        self
225    }
226
227    /// Set [`AnthropicShared::diagnostics_previous_message_id`].
228    pub fn diagnostics_previous_message_id(mut self, previous: Option<String>) -> Self {
229        self.shared.diagnostics_previous_message_id = Some(previous);
230        self
231    }
232}
233
234impl ExtensionOptions for AnthropicOptions {
235    type Ext = AnthropicExt;
236
237    /// `top_k` on a model that fixes its sampling, and fast mode on a
238    /// listed model that does not offer it. A model the catalog does not
239    /// list is sent everything.
240    fn unsupported(
241        &self,
242        target: &dyn ReplayTarget,
243        request: &CompletionRequest,
244    ) -> Vec<(&'static str, String)> {
245        let model = request
246            .model
247            .as_deref()
248            .filter(|model| !model.is_empty())
249            .unwrap_or_else(|| target.model());
250        let facts = target
251            .facts()
252            .unwrap_or_else(|| crate::catalog::ModelFacts::builtin());
253        let Some(spec) = facts.for_model(target.provider(), model) else {
254            return Vec::new();
255        };
256        let mut refused = Vec::new();
257        if self.shared.top_k.is_some() && spec.sampling == Some(Sampling::Never) {
258            refused.push(("top_k", "this model does not take `top_k`".to_owned()));
259        }
260        if self.shared.speed == Some(Speed::Fast) && !FAST_MODELS.contains(&spec.id.as_str()) {
261            refused.push((
262                "speed",
263                "fast mode runs on Claude Fable 5.2, Opus 5.5, Opus 5 and Opus 4.8 only".to_owned(),
264            ));
265        }
266        refused
267    }
268}
269
270/// Where inference runs.
271#[non_exhaustive]
272#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
273#[serde(rename_all = "lowercase")]
274pub enum InferenceGeo {
275    /// `"us"`: in the United States only.
276    Us,
277    /// `"global"`: anywhere.
278    Global,
279}
280
281/// The output speed.
282#[non_exhaustive]
283#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
284#[serde(rename_all = "lowercase")]
285pub enum Speed {
286    /// `"standard"`.
287    Standard,
288    /// `"fast"`: fast mode, at its own price.
289    Fast,
290}
291
292/// A token budget the model paces an agentic loop by, at least 20000
293/// tokens.
294#[non_exhaustive]
295#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
296#[serde(tag = "type", rename = "tokens")]
297pub struct TaskBudget {
298    /// The whole budget.
299    pub total: u32,
300    /// What is left of it, when history was rewritten and the server can no
301    /// longer count it. Unset, the server counts it.
302    #[serde(skip_serializing_if = "Option::is_none")]
303    pub remaining: Option<u32>,
304}
305
306impl TaskBudget {
307    /// A budget of `total` tokens the server counts down.
308    pub fn new(total: u32) -> Self {
309        Self {
310            total,
311            remaining: None,
312        }
313    }
314
315    /// `self` with `remaining` tokens left.
316    pub fn remaining(mut self, remaining: u32) -> Self {
317        self.remaining = Some(remaining);
318        self
319    }
320}
321
322/// The models a refused request is re-run on.
323#[non_exhaustive]
324#[derive(Clone, Debug, PartialEq, Eq)]
325pub enum Fallbacks {
326    /// `"default"`: Anthropic picks by refusal category. Beta
327    /// [`SERVER_SIDE_FALLBACK_BETA`].
328    Default,
329    /// `[{"model": ..}, ..]`: these models, in order. Beta
330    /// [`SERVER_SIDE_FALLBACK_MODELS_BETA`].
331    Models(Vec<String>),
332}
333
334impl Serialize for Fallbacks {
335    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
336        match self {
337            Self::Default => serializer.serialize_str("default"),
338            Self::Models(models) => {
339                serializer.collect_seq(models.iter().map(|model| Nested("model", model)))
340            }
341        }
342    }
343}
344
345/// The container a request runs code in.
346#[non_exhaustive]
347#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
348#[serde(untagged)]
349pub enum ContainerParam {
350    /// An existing container's id.
351    Id(String),
352    /// A container with skills loaded: `id` reuses one, unset starts one.
353    Skills {
354        /// The container to reuse.
355        #[serde(skip_serializing_if = "Option::is_none")]
356        id: Option<String>,
357        /// The skills to load.
358        skills: Vec<Skill>,
359    },
360}
361
362impl From<String> for ContainerParam {
363    fn from(id: String) -> Self {
364        Self::Id(id)
365    }
366}
367
368impl From<&str> for ContainerParam {
369    fn from(id: &str) -> Self {
370        Self::Id(id.to_owned())
371    }
372}
373
374/// A skill loaded into a container.
375#[non_exhaustive]
376#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
377pub struct Skill {
378    /// Who publishes it.
379    #[serde(rename = "type")]
380    pub kind: SkillKind,
381    /// Its id: a prebuilt skill's name (`"xlsx"`) or a custom skill's id.
382    pub skill_id: String,
383    /// Its version, such as `"latest"`. Unset, the latest.
384    #[serde(skip_serializing_if = "Option::is_none")]
385    pub version: Option<String>,
386}
387
388impl Skill {
389    /// The skill `skill_id` from `kind`, at its latest version.
390    pub fn new(kind: SkillKind, skill_id: impl Into<String>) -> Self {
391        Self {
392            kind,
393            skill_id: skill_id.into(),
394            version: None,
395        }
396    }
397
398    /// `self` at `version`.
399    pub fn version(mut self, version: impl Into<String>) -> Self {
400        self.version = Some(version.into());
401        self
402    }
403}
404
405/// Who publishes a skill.
406#[non_exhaustive]
407#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
408#[serde(rename_all = "lowercase")]
409pub enum SkillKind {
410    /// `"anthropic"`: a prebuilt skill.
411    Anthropic,
412    /// `"custom"`: one the organization uploaded.
413    Custom,
414}
415
416/// Context editing: the edits the server applies before the model reads the
417/// conversation.
418#[non_exhaustive]
419#[derive(Clone, Debug, Default, PartialEq, Serialize)]
420pub struct ContextManagement {
421    /// Each edit as the API spells it, such as
422    /// `{"type": "clear_tool_uses_20250919"}`. Edits are versioned server
423    /// types, so they are written as JSON.
424    pub edits: Vec<Value>,
425}
426
427impl ContextManagement {
428    /// The edits `edits`.
429    pub fn new(edits: Vec<Value>) -> Self {
430        Self { edits }
431    }
432}
433
434/// A remote MCP server the API connects to.
435#[non_exhaustive]
436#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
437#[serde(tag = "type", rename = "url")]
438pub struct McpServer {
439    /// The server's URL.
440    pub url: String,
441    /// The name an `mcp_toolset` tool refers to it by.
442    pub name: String,
443    /// An OAuth token the API sends to it.
444    #[serde(skip_serializing_if = "Option::is_none")]
445    pub authorization_token: Option<String>,
446}
447
448impl McpServer {
449    /// The server `name` at `url`, with no token.
450    pub fn new(url: impl Into<String>, name: impl Into<String>) -> Self {
451        Self {
452            url: url.into(),
453            name: name.into(),
454            authorization_token: None,
455        }
456    }
457
458    /// `self` with `token` sent to the server.
459    pub fn authorization_token(mut self, token: impl Into<String>) -> Self {
460        self.authorization_token = Some(token.into());
461        self
462    }
463}
464
465/// The fields of an Anthropic Messages reply rig does not normalize. Each
466/// is `None` when the reply leaves it out.
467#[non_exhaustive]
468#[derive(Clone, Debug, Default, PartialEq)]
469pub struct AnthropicExtras {
470    /// `stop_reason`, verbatim.
471    pub stop_reason: Option<String>,
472    /// `stop_sequence`: the stop sequence the turn ended on.
473    pub stop_sequence: Option<String>,
474    /// `stop_details`: why a refusal was declined.
475    pub stop_details: Option<StopDetails>,
476    /// `usage.cache_creation`: the cache writes per lifetime.
477    pub cache_creation: Option<CacheCreation>,
478    /// `usage.service_tier`: `standard`, `priority` or `batch`.
479    pub service_tier: Option<String>,
480    /// `usage.inference_geo`: where inference ran.
481    pub inference_geo: Option<String>,
482    /// `usage.speed`: the speed the reply ran at.
483    pub speed: Option<String>,
484    /// `usage.server_tool_use`: the server tools' request counts.
485    pub server_tool_use: Option<ServerToolUse>,
486    /// `container`: the code-execution container the reply ran in.
487    pub container: Option<Container>,
488    /// The model a leading `fallback` block switched to, when the request
489    /// was refused and re-run on another model.
490    pub fallback_model: Option<String>,
491}
492
493/// Why a reply was refused.
494#[non_exhaustive]
495#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
496pub struct StopDetails {
497    /// `type`: `"refusal"`.
498    #[serde(rename = "type", default)]
499    pub kind: String,
500    /// The policy category, such as `"cyber"`.
501    pub category: Option<String>,
502    /// A readable explanation.
503    pub explanation: Option<String>,
504}
505
506/// The input tokens written to the cache, per cache lifetime.
507#[non_exhaustive]
508#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
509pub struct CacheCreation {
510    /// Written with a five-minute lifetime.
511    #[serde(default)]
512    pub ephemeral_5m_input_tokens: u64,
513    /// Written with a one-hour lifetime.
514    #[serde(default)]
515    pub ephemeral_1h_input_tokens: u64,
516}
517
518/// How many requests the server tools made.
519#[non_exhaustive]
520#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
521pub struct ServerToolUse {
522    /// Web searches.
523    #[serde(default)]
524    pub web_search_requests: u64,
525    /// Web fetches.
526    #[serde(default)]
527    pub web_fetch_requests: u64,
528}
529
530/// A code-execution container.
531#[non_exhaustive]
532#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize)]
533pub struct Container {
534    /// Its id, which a later request reuses.
535    #[serde(default)]
536    pub id: String,
537    /// When it expires, as an RFC 3339 time.
538    #[serde(default)]
539    pub expires_at: String,
540}
541
542/// The reply fields [`AnthropicExtras`] reads.
543#[derive(Deserialize)]
544struct Reply {
545    stop_reason: Option<String>,
546    stop_sequence: Option<String>,
547    stop_details: Option<StopDetails>,
548    usage: Option<ReplyUsage>,
549    container: Option<Container>,
550    /// Read for its shape only; the first block is read from the reply.
551    #[serde(default, rename = "content")]
552    _content: Vec<serde::de::IgnoredAny>,
553}
554
555#[derive(Default, Deserialize)]
556struct ReplyUsage {
557    cache_creation: Option<CacheCreation>,
558    service_tier: Option<String>,
559    inference_geo: Option<String>,
560    speed: Option<String>,
561    server_tool_use: Option<ServerToolUse>,
562}
563
564impl ReplyExtras for AnthropicExtras {
565    fn from_reply(api: &Api, raw: &Value) -> Result<Self, serde_json::Error> {
566        if api.as_str() != MESSAGES_API {
567            return Err(serde::de::Error::custom(format!(
568                "Anthropic extras read a Messages reply, not one from `{api}`"
569            )));
570        }
571        let Reply {
572            stop_reason,
573            stop_sequence,
574            stop_details,
575            usage,
576            container,
577            _content,
578        } = crate::json_utils::from_value::<Reply>(raw)?;
579        let usage = usage.unwrap_or_default();
580        let fallback_model = raw
581            .pointer("/content/0")
582            .filter(|block| block.get("type").and_then(Value::as_str) == Some("fallback"))
583            .and_then(|block| block.pointer("/to/model"))
584            .and_then(Value::as_str)
585            .map(str::to_owned);
586        Ok(Self {
587            stop_reason,
588            stop_sequence,
589            stop_details,
590            cache_creation: usage.cache_creation,
591            service_tier: usage.service_tier,
592            inference_geo: usage.inference_geo,
593            speed: usage.speed,
594            server_tool_use: usage.server_tool_use,
595            container,
596            fallback_model,
597        })
598    }
599}
600
601/// The reply fields every Messages-format dialect returns, which the
602/// dialects' extras read on this route.
603#[derive(Deserialize)]
604pub(crate) struct MessagesStop {
605    pub(crate) stop_reason: Option<String>,
606    pub(crate) stop_sequence: Option<String>,
607}
608
609impl MessagesStop {
610    /// The stop fields of `raw`, or `None` when `api` is not the Messages API.
611    ///
612    /// # Errors
613    ///
614    /// When `raw` is a Messages reply but not an object.
615    pub(crate) fn of(api: &Api, raw: &Value) -> Result<Option<Self>, serde_json::Error> {
616        (api.as_str() == MESSAGES_API)
617            .then(|| crate::json_utils::from_value(raw))
618            .transpose()
619    }
620}
621
622#[cfg(test)]
623mod tests;