use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use crate::response::{Citation, ContentBlock};
pub(crate) const BETA_FALLBACK_DEFAULT: &str = "server-side-fallback-2026-07-01";
pub(crate) const BETA_FALLBACK_LIST: &str = "server-side-fallback-2026-06-01";
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct MessagesRequest {
pub model: String,
pub max_tokens: u32,
pub messages: Vec<MessageParam>,
#[serde(skip_serializing_if = "Option::is_none")]
pub system: Option<System>,
#[serde(skip_serializing_if = "Option::is_none")]
pub thinking: Option<ThinkingConfig>,
#[serde(skip_serializing_if = "Option::is_none")]
pub output_config: Option<OutputConfig>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub tools: Vec<ToolDefinition>,
#[serde(skip_serializing_if = "Option::is_none")]
pub tool_choice: Option<ToolChoice>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub stop_sequences: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
#[serde(skip_serializing_if = "Option::is_none")]
pub fallbacks: Option<Fallbacks>,
#[serde(skip_serializing_if = "Option::is_none")]
pub stream: Option<bool>,
#[serde(skip)]
pub betas: Vec<String>,
#[serde(flatten)]
pub extra: Map<String, Value>,
}
impl MessagesRequest {
pub fn new(model: impl Into<String>, max_tokens: u32) -> MessagesRequest {
MessagesRequest {
model: model.into(),
max_tokens,
messages: Vec::new(),
system: None,
thinking: None,
output_config: None,
tools: Vec::new(),
tool_choice: None,
stop_sequences: Vec::new(),
cache_control: None,
fallbacks: None,
stream: None,
betas: Vec::new(),
extra: Map::new(),
}
}
pub fn system(mut self, text: impl Into<String>) -> Self {
self.system = Some(System::Text(text.into()));
self
}
pub fn system_cached(mut self, text: impl Into<String>) -> Self {
self.system = Some(System::Blocks(vec![SystemBlock { text: text.into(), cache_control: Some(CacheControl::ephemeral()) }]));
self
}
pub fn message(mut self, message: MessageParam) -> Self {
self.messages.push(message);
self
}
pub fn user(self, text: impl Into<String>) -> Self {
self.message(MessageParam::user_text(text))
}
pub fn thinking(mut self, thinking: ThinkingConfig) -> Self {
self.thinking = Some(thinking);
self
}
pub fn effort(mut self, effort: Effort) -> Self {
self.output_config.get_or_insert_with(OutputConfig::default).effort = Some(effort);
self
}
pub fn tool(mut self, tool: impl Into<ToolDefinition>) -> Self {
self.tools.push(tool.into());
self
}
pub fn tool_choice(mut self, choice: ToolChoice) -> Self {
self.tool_choice = Some(choice);
self
}
pub fn fallbacks(mut self, fallbacks: Fallbacks) -> Self {
self.fallbacks = Some(fallbacks);
self
}
pub fn beta(mut self, beta: impl Into<String>) -> Self {
self.betas.push(beta.into());
self
}
pub fn param(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
self.extra.insert(key.into(), value.into());
self
}
pub fn beta_header_values(&self) -> Vec<String> {
let mut out: Vec<String> = Vec::new();
let needed = match &self.fallbacks {
Some(Fallbacks::Default) => Some(BETA_FALLBACK_DEFAULT),
Some(Fallbacks::Models(_)) => Some(BETA_FALLBACK_LIST),
None => None,
};
for b in self.betas.iter().map(String::as_str).chain(needed) {
if !out.iter().any(|o| o == b) {
out.push(b.to_string());
}
}
out
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role {
User,
Assistant,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct MessageParam {
pub role: Role,
pub content: Content,
}
impl MessageParam {
pub fn user_text(text: impl Into<String>) -> MessageParam {
MessageParam { role: Role::User, content: Content::Text(text.into()) }
}
pub fn user(blocks: Vec<ContentBlockParam>) -> MessageParam {
MessageParam { role: Role::User, content: Content::Blocks(blocks) }
}
pub fn assistant(blocks: Vec<ContentBlockParam>) -> MessageParam {
MessageParam { role: Role::Assistant, content: Content::Blocks(blocks) }
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(untagged)]
pub enum Content {
Text(String),
Blocks(Vec<ContentBlockParam>),
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentBlockParam {
Text {
text: String,
#[serde(skip_serializing_if = "Option::is_none")]
citations: Option<Vec<Citation>>,
#[serde(skip_serializing_if = "Option::is_none")]
cache_control: Option<CacheControl>,
},
Image {
source: ImageSource,
#[serde(skip_serializing_if = "Option::is_none")]
cache_control: Option<CacheControl>,
},
Document {
source: DocumentSource,
#[serde(skip_serializing_if = "Option::is_none")]
title: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
context: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
citations: Option<CitationsConfig>,
#[serde(skip_serializing_if = "Option::is_none")]
cache_control: Option<CacheControl>,
},
ToolUse {
id: String,
name: String,
input: Value,
},
ToolResult {
tool_use_id: String,
content: ToolResultContent,
#[serde(skip_serializing_if = "Option::is_none")]
is_error: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
cache_control: Option<CacheControl>,
},
Thinking {
thinking: String,
signature: String,
},
RedactedThinking {
data: String,
},
#[serde(untagged)]
Raw(Value),
}
impl ContentBlockParam {
pub fn text(text: impl Into<String>) -> ContentBlockParam {
ContentBlockParam::Text { text: text.into(), citations: None, cache_control: None }
}
pub fn text_document(data: impl Into<String>, title: impl Into<String>) -> ContentBlockParam {
ContentBlockParam::Document {
source: DocumentSource::Text { media_type: "text/plain".into(), data: data.into() },
title: Some(title.into()),
context: None,
citations: None,
cache_control: None,
}
}
pub fn chunked_document(chunks: impl IntoIterator<Item = impl Into<String>>, title: impl Into<String>) -> ContentBlockParam {
let content = chunks.into_iter().map(|c| ContentBlockParam::text(c)).collect();
ContentBlockParam::Document {
source: DocumentSource::Content { content },
title: Some(title.into()),
context: None,
citations: None,
cache_control: None,
}
}
pub fn base64_pdf(data: impl Into<String>) -> ContentBlockParam {
ContentBlockParam::Document {
source: DocumentSource::Base64 { media_type: "application/pdf".into(), data: data.into() },
title: None,
context: None,
citations: None,
cache_control: None,
}
}
pub fn file_document(file_id: impl Into<String>) -> ContentBlockParam {
ContentBlockParam::Document {
source: DocumentSource::File { file_id: file_id.into() },
title: None,
context: None,
citations: None,
cache_control: None,
}
}
pub fn file_image(file_id: impl Into<String>) -> ContentBlockParam {
ContentBlockParam::Image { source: ImageSource::File { file_id: file_id.into() }, cache_control: None }
}
pub fn tool_result(tool_use_id: impl Into<String>, content: impl Into<String>, is_error: bool) -> ContentBlockParam {
ContentBlockParam::ToolResult {
tool_use_id: tool_use_id.into(),
content: ToolResultContent::Text(content.into()),
is_error: is_error.then_some(true),
cache_control: None,
}
}
pub fn with_citations(mut self) -> Self {
if let ContentBlockParam::Document { citations, .. } = &mut self {
*citations = Some(CitationsConfig { enabled: true });
}
self
}
pub fn with_context(mut self, text: impl Into<String>) -> Self {
if let ContentBlockParam::Document { context, .. } = &mut self {
*context = Some(text.into());
}
self
}
pub fn with_cache_control(mut self, cc: CacheControl) -> Self {
match &mut self {
ContentBlockParam::Text { cache_control, .. }
| ContentBlockParam::Image { cache_control, .. }
| ContentBlockParam::Document { cache_control, .. }
| ContentBlockParam::ToolResult { cache_control, .. } => *cache_control = Some(cc),
_ => {}
}
self
}
}
impl From<ContentBlock> for ContentBlockParam {
fn from(block: ContentBlock) -> ContentBlockParam {
match block {
ContentBlock::Text { text, citations } => {
ContentBlockParam::Text { text, citations: (!citations.is_empty()).then_some(citations), cache_control: None }
}
ContentBlock::Thinking { thinking, signature } => ContentBlockParam::Thinking { thinking, signature },
ContentBlock::RedactedThinking { data } => ContentBlockParam::RedactedThinking { data },
ContentBlock::ToolUse { id, name, input } => ContentBlockParam::ToolUse { id, name, input },
other => ContentBlockParam::Raw(serde_json::to_value(&other).unwrap_or(Value::Null)),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum DocumentSource {
Text { media_type: String, data: String },
Base64 { media_type: String, data: String },
Content { content: Vec<ContentBlockParam> },
Url { url: String },
File { file_id: String },
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ImageSource {
Base64 { media_type: String, data: String },
Url { url: String },
File { file_id: String },
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(untagged)]
pub enum ToolResultContent {
Text(String),
Blocks(Vec<ContentBlockParam>),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct CitationsConfig {
pub enabled: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CacheControl {
#[serde(rename = "type")]
pub kind: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub ttl: Option<String>,
}
impl CacheControl {
pub fn ephemeral() -> CacheControl {
CacheControl { kind: "ephemeral".into(), ttl: None }
}
pub fn one_hour() -> CacheControl {
CacheControl { kind: "ephemeral".into(), ttl: Some("1h".into()) }
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(untagged)]
pub enum System {
Text(String),
Blocks(Vec<SystemBlock>),
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename = "text")]
pub struct SystemBlock {
pub text: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ThinkingConfig {
Adaptive {
#[serde(skip_serializing_if = "Option::is_none")]
display: Option<ThinkingDisplay>,
},
Disabled,
Enabled { budget_tokens: u32 },
BetweenTools,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ThinkingDisplay {
Summarized,
Omitted,
Updates,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize)]
pub struct OutputConfig {
#[serde(skip_serializing_if = "Option::is_none")]
pub effort: Option<Effort>,
#[serde(skip_serializing_if = "Option::is_none")]
pub format: Option<Value>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Effort {
Low,
Medium,
High,
Xhigh,
Max,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Tool {
pub name: String,
pub description: String,
pub input_schema: Value,
#[serde(skip_serializing_if = "Option::is_none")]
pub strict: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub defer_loading: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
}
impl Tool {
pub fn new(name: impl Into<String>, description: impl Into<String>, input_schema: Value) -> Tool {
Tool { name: name.into(), description: description.into(), input_schema, strict: None, defer_loading: None, cache_control: None }
}
pub fn strict(mut self) -> Self {
self.strict = Some(true);
self
}
pub fn deferred(mut self) -> Self {
self.defer_loading = Some(true);
self
}
pub fn with_cache_control(mut self, cc: CacheControl) -> Self {
self.cache_control = Some(cc);
self
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(untagged)]
pub enum ToolDefinition {
Custom(Tool),
WebSearch(WebSearchTool),
WebFetch(WebFetchTool),
CodeExecution(CodeExecutionTool),
ToolSearch(ToolSearchTool),
Raw(Value),
}
impl From<Tool> for ToolDefinition {
fn from(t: Tool) -> ToolDefinition {
ToolDefinition::Custom(t)
}
}
impl From<WebSearchTool> for ToolDefinition {
fn from(t: WebSearchTool) -> ToolDefinition {
ToolDefinition::WebSearch(t)
}
}
impl From<WebFetchTool> for ToolDefinition {
fn from(t: WebFetchTool) -> ToolDefinition {
ToolDefinition::WebFetch(t)
}
}
impl From<CodeExecutionTool> for ToolDefinition {
fn from(t: CodeExecutionTool) -> ToolDefinition {
ToolDefinition::CodeExecution(t)
}
}
impl From<ToolSearchTool> for ToolDefinition {
fn from(t: ToolSearchTool) -> ToolDefinition {
ToolDefinition::ToolSearch(t)
}
}
impl From<Value> for ToolDefinition {
fn from(v: Value) -> ToolDefinition {
ToolDefinition::Raw(v)
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct WebSearchTool {
#[serde(rename = "type")]
pub kind: String,
pub name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_uses: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub allowed_domains: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub blocked_domains: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub user_location: Option<UserLocation>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
}
impl WebSearchTool {
pub fn new() -> WebSearchTool {
WebSearchTool::version("web_search_20260209")
}
pub fn basic() -> WebSearchTool {
WebSearchTool::version("web_search_20250305")
}
pub fn version(kind: impl Into<String>) -> WebSearchTool {
WebSearchTool {
kind: kind.into(),
name: "web_search".into(),
max_uses: None,
allowed_domains: None,
blocked_domains: None,
user_location: None,
cache_control: None,
}
}
pub fn max_uses(mut self, n: u32) -> Self {
self.max_uses = Some(n);
self
}
pub fn allowed_domains(mut self, domains: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.allowed_domains = Some(domains.into_iter().map(Into::into).collect());
self
}
pub fn blocked_domains(mut self, domains: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.blocked_domains = Some(domains.into_iter().map(Into::into).collect());
self
}
pub fn user_location(mut self, location: UserLocation) -> Self {
self.user_location = Some(location);
self
}
}
impl Default for WebSearchTool {
fn default() -> Self {
WebSearchTool::new()
}
}
#[derive(Debug, Clone, Default, PartialEq, Serialize)]
#[serde(tag = "type", rename = "approximate")]
pub struct UserLocation {
#[serde(skip_serializing_if = "Option::is_none")]
pub city: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub region: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub country: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub timezone: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct WebFetchTool {
#[serde(rename = "type")]
pub kind: String,
pub name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_uses: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub allowed_domains: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub blocked_domains: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub citations: Option<CitationsConfig>,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_content_tokens: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
}
impl WebFetchTool {
pub fn new() -> WebFetchTool {
WebFetchTool::version("web_fetch_20260209")
}
pub fn basic() -> WebFetchTool {
WebFetchTool::version("web_fetch_20250910")
}
pub fn version(kind: impl Into<String>) -> WebFetchTool {
WebFetchTool {
kind: kind.into(),
name: "web_fetch".into(),
max_uses: None,
allowed_domains: None,
blocked_domains: None,
citations: None,
max_content_tokens: None,
cache_control: None,
}
}
pub fn max_uses(mut self, n: u32) -> Self {
self.max_uses = Some(n);
self
}
pub fn allowed_domains(mut self, domains: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.allowed_domains = Some(domains.into_iter().map(Into::into).collect());
self
}
pub fn blocked_domains(mut self, domains: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.blocked_domains = Some(domains.into_iter().map(Into::into).collect());
self
}
pub fn with_citations(mut self) -> Self {
self.citations = Some(CitationsConfig { enabled: true });
self
}
pub fn max_content_tokens(mut self, n: u32) -> Self {
self.max_content_tokens = Some(n);
self
}
}
impl Default for WebFetchTool {
fn default() -> Self {
WebFetchTool::new()
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct CodeExecutionTool {
#[serde(rename = "type")]
pub kind: String,
pub name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache_control: Option<CacheControl>,
}
impl CodeExecutionTool {
pub fn new() -> CodeExecutionTool {
CodeExecutionTool::version("code_execution_20260521")
}
pub fn version(kind: impl Into<String>) -> CodeExecutionTool {
CodeExecutionTool { kind: kind.into(), name: "code_execution".into(), cache_control: None }
}
}
impl Default for CodeExecutionTool {
fn default() -> Self {
CodeExecutionTool::new()
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ToolSearchTool {
#[serde(rename = "type")]
pub kind: String,
pub name: String,
}
impl ToolSearchTool {
pub fn regex() -> ToolSearchTool {
ToolSearchTool { kind: "tool_search_tool_regex_20251119".into(), name: "tool_search_tool_regex".into() }
}
pub fn bm25() -> ToolSearchTool {
ToolSearchTool { kind: "tool_search_tool_bm25_20251119".into(), name: "tool_search_tool_bm25".into() }
}
}
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ToolChoice {
Auto {
#[serde(skip_serializing_if = "Option::is_none")]
disable_parallel_tool_use: Option<bool>,
},
None,
Any,
Tool {
name: String,
},
}
#[derive(Debug, Clone, PartialEq)]
pub enum Fallbacks {
Default,
Models(Vec<FallbackModel>),
}
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct FallbackModel {
pub model: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_tokens: Option<u32>,
}
impl Serialize for Fallbacks {
fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
match self {
Fallbacks::Default => s.serialize_str("default"),
Fallbacks::Models(models) => models.serialize(s),
}
}
}