1use super::message::{AssistantContent, DocumentMediaType, Reasoning, ReasoningContent, ToolCall};
13use crate::error::ProviderError;
14use crate::message::ToolChoice;
15use crate::{
16 json_utils,
17 message::{Message, ToolName, UserContent},
18};
19
20use serde::{Deserialize, Serialize};
21use std::collections::HashMap;
22use std::ops::{Add, AddAssign};
23
24#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
25pub struct Document {
26 pub id: String,
28 pub text: String,
30 #[serde(flatten)]
32 pub additional_props: HashMap<String, String>,
33}
34
35impl std::fmt::Display for Document {
36 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
37 write!(
38 f,
39 concat!("<file id: {}>\n", "{}\n", "</file>\n"),
40 self.id,
41 if self.additional_props.is_empty() {
42 self.text.clone()
43 } else {
44 let mut sorted_props = self.additional_props.iter().collect::<Vec<_>>();
45 sorted_props.sort_by(|a, b| a.0.cmp(b.0));
46 let metadata = sorted_props
47 .iter()
48 .map(|(k, v)| format!("{k}: {v:?}"))
49 .collect::<Vec<_>>()
50 .join(" ");
51 format!("<metadata {} />\n{}", metadata, self.text)
52 }
53 )
54 }
55}
56
57#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
58pub struct ToolDefinition {
59 pub name: String,
61 pub description: String,
63 pub parameters: serde_json::Value,
65}
66
67impl ToolDefinition {
68 pub fn new(
71 name: ToolName,
72 description: impl Into<String>,
73 parameters: serde_json::Value,
74 ) -> Self {
75 Self {
76 name: name.into(),
77 description: description.into(),
78 parameters,
79 }
80 }
81}
82
83#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
88pub struct ProviderToolDefinition {
89 #[serde(rename = "type")]
91 pub kind: String,
92 #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
94 pub config: serde_json::Map<String, serde_json::Value>,
95}
96
97impl ProviderToolDefinition {
98 pub fn new(kind: impl Into<String>) -> Self {
100 Self {
101 kind: kind.into(),
102 config: serde_json::Map::new(),
103 }
104 }
105
106 pub fn with_config(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
108 self.config.insert(key.into(), value);
109 self
110 }
111}
112
113#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
117#[serde(rename_all = "snake_case")]
118pub enum FinishReason {
119 Stop,
121 Length,
123 ToolCalls,
125 ContentFilter,
127 Other(String),
130}
131
132impl FinishReason {
133 pub fn reconcile_with_output(self, has_tool_call: bool) -> Self {
137 if has_tool_call && matches!(self, Self::Stop) {
138 Self::ToolCalls
139 } else {
140 self
141 }
142 }
143
144 pub fn truncated_output(&self) -> bool {
148 matches!(self, Self::Length | Self::ContentFilter)
149 }
150
151 pub fn no_answer_message(&self) -> String {
154 let remedy = match self {
155 Self::Length => {
156 "the turn ran out of output budget before producing one — \
157 raise max_tokens for this request"
158 }
159 Self::ContentFilter => {
160 "the provider filtered the response — the content, not the \
161 budget, is what it objected to"
162 }
163 _ => "the turn ended before producing one",
164 };
165 format!(
166 "the model produced no answer and stopped with \
167 finish_reason={self:?}; {remedy}"
168 )
169 }
170}
171
172#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
179#[serde(from = "CompletionResponseRepr")]
180pub struct CompletionResponse {
181 pub choice: Vec<AssistantContent>,
183 pub usage: Usage,
185 #[serde(default)]
188 pub message_id: Option<String>,
189 #[serde(default)]
192 pub response_id: Option<String>,
193 #[serde(default, skip_serializing_if = "Option::is_none")]
196 pub provider_request_id: Option<String>,
197 #[serde(default)]
200 finish_reason: Option<FinishReason>,
201 pub provider: String,
205 #[serde(default)]
210 pub model: Option<String>,
211 pub raw: serde_json::Value,
215}
216
217#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
220pub struct ResponseIdentity {
221 #[serde(default, skip_serializing_if = "Option::is_none")]
223 pub message_id: Option<String>,
224 #[serde(default, skip_serializing_if = "Option::is_none")]
226 pub response_id: Option<String>,
227 #[serde(default, skip_serializing_if = "Option::is_none")]
229 pub provider_request_id: Option<String>,
230}
231
232impl CompletionResponse {
233 pub fn new(
237 choice: Vec<AssistantContent>,
238 usage: Usage,
239 provider: impl Into<String>,
240 raw: serde_json::Value,
241 ) -> Self {
242 Self {
243 choice,
244 usage,
245 message_id: None,
246 response_id: None,
247 provider_request_id: None,
248 finish_reason: None,
249 provider: provider.into(),
250 model: None,
251 raw,
252 }
253 }
254
255 pub fn finish_reason(&self) -> Option<FinishReason> {
257 self.finish_reason.clone()
258 }
259
260 pub fn identity(&self) -> ResponseIdentity {
262 ResponseIdentity {
263 message_id: self.message_id.clone(),
264 response_id: self.response_id.clone(),
265 provider_request_id: self.provider_request_id.clone(),
266 }
267 }
268
269 pub fn with_finish_reason(self, finish_reason: FinishReason) -> Self {
272 self.with_optional_finish_reason(Some(finish_reason))
273 }
274
275 pub fn text(&self) -> String {
277 self.choice
278 .iter()
279 .filter_map(|part| match part {
280 AssistantContent::Text(text) => Some(text.text.as_str()),
281 _ => None,
282 })
283 .collect()
284 }
285
286 pub fn reasoning(&self) -> String {
289 self.choice
290 .iter()
291 .filter_map(|part| match part {
292 AssistantContent::Reasoning(reasoning) => {
293 reasoning.open(reasoning.issuer()).map(reasoning_text)
294 }
295 _ => None,
296 })
297 .collect()
298 }
299
300 pub fn message(&self) -> Option<Message> {
303 if self.choice.is_empty() {
304 return None;
305 }
306 Some(Message::Assistant {
307 id: self.message_id.clone(),
308 content: self.choice.clone(),
309 })
310 }
311
312 pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
314 self.choice.iter().filter_map(|part| match part {
315 AssistantContent::ToolCall(call) => Some(call),
316 _ => None,
317 })
318 }
319
320 pub fn with_optional_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
322 let has_tool_call = self
323 .choice
324 .iter()
325 .any(|content| matches!(content, AssistantContent::ToolCall(_)));
326 self.finish_reason =
327 finish_reason.map(|reason| reason.reconcile_with_output(has_tool_call));
328 self
329 }
330}
331
332pub(crate) fn reasoning_text(reasoning: &Reasoning) -> String {
334 reasoning
335 .content
336 .iter()
337 .filter_map(|content| match content {
338 ReasoningContent::Text { text, .. } => Some(text.as_str()),
339 ReasoningContent::Summary(summary) => Some(summary.as_str()),
340 ReasoningContent::Encrypted(_) | ReasoningContent::Redacted { .. } => None,
341 })
342 .collect()
343}
344
345#[derive(Deserialize)]
348struct CompletionResponseRepr {
349 choice: Vec<AssistantContent>,
350 usage: Usage,
351 #[serde(default)]
352 message_id: Option<String>,
353 #[serde(default)]
354 response_id: Option<String>,
355 #[serde(default)]
356 provider_request_id: Option<String>,
357 #[serde(default)]
358 finish_reason: Option<FinishReason>,
359 provider: String,
360 #[serde(default)]
361 model: Option<String>,
362 raw: serde_json::Value,
363}
364
365impl From<CompletionResponseRepr> for CompletionResponse {
366 fn from(repr: CompletionResponseRepr) -> Self {
367 let CompletionResponseRepr {
368 choice,
369 usage,
370 message_id,
371 response_id,
372 provider_request_id,
373 finish_reason,
374 provider,
375 model,
376 raw,
377 } = repr;
378 use crate::provider_response::reported;
379 let mut response =
380 Self::new(choice, usage, provider, raw).with_optional_finish_reason(finish_reason);
381 response.message_id = reported(message_id);
382 response.response_id = reported(response_id);
383 response.provider_request_id = reported(provider_request_id);
384 response.model = reported(model);
385 response
386 }
387}
388
389#[derive(Debug, Default, PartialEq, Eq, Clone, Copy, Serialize, Deserialize)]
404pub struct Usage {
405 #[serde(default, skip_serializing_if = "Option::is_none")]
408 pub input_tokens: Option<u64>,
409 #[serde(default, skip_serializing_if = "Option::is_none")]
411 pub output_tokens: Option<u64>,
412 #[serde(default, skip_serializing_if = "Option::is_none")]
414 pub total_tokens: Option<u64>,
415 #[serde(default, skip_serializing_if = "Option::is_none")]
417 pub cached_input_tokens: Option<u64>,
418 #[serde(default, skip_serializing_if = "Option::is_none")]
420 pub cache_creation_input_tokens: Option<u64>,
421 #[serde(default, skip_serializing_if = "Option::is_none")]
423 pub tool_use_prompt_tokens: Option<u64>,
424 #[serde(default, skip_serializing_if = "Option::is_none")]
427 pub reasoning_tokens: Option<u64>,
428}
429
430impl Usage {
431 pub fn is_reported(&self) -> bool {
433 *self != Self::default()
434 }
435}
436
437fn add_counter(lhs: Option<u64>, rhs: Option<u64>) -> Option<u64> {
440 match (lhs, rhs) {
441 (None, None) => None,
442 (lhs, rhs) => Some(lhs.unwrap_or(0) + rhs.unwrap_or(0)),
443 }
444}
445
446impl Add for Usage {
447 type Output = Self;
448
449 fn add(mut self, other: Self) -> Self::Output {
450 self += other;
451 self
452 }
453}
454
455impl AddAssign for Usage {
456 fn add_assign(&mut self, other: Self) {
457 self.input_tokens = add_counter(self.input_tokens, other.input_tokens);
458 self.output_tokens = add_counter(self.output_tokens, other.output_tokens);
459 self.total_tokens = add_counter(self.total_tokens, other.total_tokens);
460 self.cached_input_tokens = add_counter(self.cached_input_tokens, other.cached_input_tokens);
461 self.cache_creation_input_tokens = add_counter(
462 self.cache_creation_input_tokens,
463 other.cache_creation_input_tokens,
464 );
465 self.tool_use_prompt_tokens =
466 add_counter(self.tool_use_prompt_tokens, other.tool_use_prompt_tokens);
467 self.reasoning_tokens = add_counter(self.reasoning_tokens, other.reasoning_tokens);
468 }
469}
470
471#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
474pub struct ProviderCapabilities {
475 pub composes_native_output_with_tools: bool,
478 #[serde(default, skip_serializing_if = "crate::json_utils::is_false")]
482 pub rejects_forced_tool_choice: bool,
483}
484
485impl ProviderCapabilities {
486 pub const fn new() -> Self {
488 Self {
489 composes_native_output_with_tools: false,
490 rejects_forced_tool_choice: false,
491 }
492 }
493
494 pub const fn with_native_output_tool_composition(mut self, supported: bool) -> Self {
496 self.composes_native_output_with_tools = supported;
497 self
498 }
499
500 pub const fn with_forced_tool_choice_rejected(mut self, rejected: bool) -> Self {
502 self.rejects_forced_tool_choice = rejected;
503 self
504 }
505}
506
507#[derive(Debug, Clone, Serialize, Deserialize)]
509pub struct CompletionRequest {
510 pub model: Option<String>,
512 pub chat_history: Vec<Message>,
520 pub documents: Vec<Document>,
522 pub tools: Vec<ToolDefinition>,
524 pub temperature: Option<f64>,
526 pub max_tokens: Option<u64>,
528 pub tool_choice: Option<ToolChoice>,
530 pub additional_params: Option<serde_json::Value>,
532 pub output_schema: Option<schemars::Schema>,
535 #[serde(skip)]
542 pub record_telemetry_content: bool,
543}
544
545impl CompletionRequest {
546 pub fn system_instructions(&self) -> Option<&str> {
550 match self.chat_history.first() {
551 Some(Message::System { content }) => Some(content.as_str()),
552 _ => None,
553 }
554 }
555
556 pub fn validate_message_content(&self) -> Result<(), ProviderError> {
576 if self.chat_history.is_empty() {
577 return Err(ProviderError::request(
578 "request has an empty chat history; providers require at least one message",
579 ));
580 }
581
582 let empty_message = |role: &str, index: usize| {
583 ProviderError::request(format!(
584 "{role} message at index {index} has no content; \
585 providers reject empty content blocks"
586 ))
587 };
588
589 for (index, message) in self.chat_history.iter().enumerate() {
590 match message {
591 Message::System { .. } => {}
592 Message::Assistant { content, .. } => {
593 if content.is_empty() {
594 return Err(empty_message("assistant", index));
595 }
596 }
597 Message::User { content } => {
598 if content.is_empty() {
599 return Err(empty_message("user", index));
600 }
601 for (position, item) in content.iter().enumerate() {
602 match item {
605 UserContent::ToolResult(result) if result.content.is_empty() => {
606 let name = &result.name;
607 return Err(ProviderError::request(format!(
608 "tool result for `{name}` at index {position} of the user \
609 message at index {index} has no content; providers \
610 reject empty content blocks"
611 )));
612 }
613 UserContent::ToolResult(_)
614 | UserContent::Text(_)
615 | UserContent::Image(_)
616 | UserContent::Audio(_)
617 | UserContent::Video(_)
618 | UserContent::Document(_) => {}
619 }
620 }
621 }
622 }
623 }
624
625 Ok(())
626 }
627
628 pub fn replayable_to(
635 mut self,
636 issuers: &[crate::message::Issuer],
637 ) -> Result<Self, crate::error::EncodeError> {
638 self.chat_history
639 .retain(|message| message.replays_to(issuers));
640 if self.chat_history.is_empty() {
641 return Err(crate::error::EncodeError::request(
642 "no message is left once reasoning another service issued is left out",
643 ));
644 }
645 Ok(self)
646 }
647
648 pub fn output_schema_name(&self) -> Option<String> {
651 self.output_schema.as_ref().map(|schema| {
652 schema
653 .as_object()
654 .and_then(|o| o.get("title"))
655 .and_then(|v| v.as_str())
656 .unwrap_or("response_schema")
657 .to_string()
658 })
659 }
660
661 pub fn normalized_documents(&self) -> Option<Message> {
665 Self::normalized_documents_from(&self.documents)
666 }
667
668 fn normalized_documents_from(documents: &[Document]) -> Option<Message> {
669 if documents.is_empty() {
670 return None;
671 }
672
673 let content = documents
674 .iter()
675 .map(|doc| UserContent::document(doc.to_string(), Some(DocumentMediaType::TXT)))
676 .collect();
677
678 Some(Message::User { content })
679 }
680
681 pub(crate) fn chat_history_with_documents(&self) -> Vec<Message> {
682 let mut chat_history = self.chat_history.clone();
683 if let Some(documents) = self.normalized_documents() {
684 insert_after_leading_system(&mut chat_history, documents);
685 }
686 chat_history
687 }
688}
689
690fn insert_after_leading_system(chat_history: &mut Vec<Message>, message: Message) {
694 let insert_at = chat_history
695 .iter()
696 .position(|message| !matches!(message, Message::System { .. }))
697 .unwrap_or(chat_history.len());
698 chat_history.insert(insert_at, message);
699}
700
701fn merge_provider_tools_into_additional_params(
702 additional_params: Option<serde_json::Value>,
703 provider_tools: Vec<ProviderToolDefinition>,
704) -> Option<serde_json::Value> {
705 if provider_tools.is_empty() {
706 return additional_params;
707 }
708
709 let mut provider_tools_json = provider_tools
710 .into_iter()
711 .map(|ProviderToolDefinition { kind, mut config }| {
712 config.insert("type".to_string(), serde_json::Value::String(kind));
714 serde_json::Value::Object(config)
715 })
716 .collect::<Vec<_>>();
717
718 let mut params_map = match additional_params {
719 Some(serde_json::Value::Object(map)) => map,
720 Some(serde_json::Value::Bool(stream)) => {
721 let mut map = serde_json::Map::new();
722 map.insert("stream".to_string(), serde_json::Value::Bool(stream));
723 map
724 }
725 _ => serde_json::Map::new(),
726 };
727
728 let mut merged_tools = match params_map.remove("tools") {
729 Some(serde_json::Value::Array(existing)) => existing,
730 _ => Vec::new(),
731 };
732 merged_tools.append(&mut provider_tools_json);
733 params_map.insert("tools".to_string(), serde_json::Value::Array(merged_tools));
734 Some(serde_json::Value::Object(params_map))
735}
736
737impl CompletionRequest {
738 pub fn new(prompt: impl Into<Message>) -> Self {
759 Self::conversation(vec![prompt.into()])
760 }
761
762 fn conversation(chat_history: Vec<Message>) -> Self {
764 Self {
765 model: None,
766 chat_history,
767 documents: Vec::new(),
768 tools: Vec::new(),
769 temperature: None,
770 max_tokens: None,
771 tool_choice: None,
772 additional_params: None,
773 output_schema: None,
774 record_telemetry_content: false,
775 }
776 }
777
778 pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
781 self.chat_history
782 .insert(0, Message::system(preamble.into()));
783 self
784 }
785
786 pub fn model<S: Into<String>>(mut self, model: impl Into<Option<S>>) -> Self {
788 self.model = model.into().map(Into::into);
789 self.warn_if_shadowed("model", self.model.is_some());
790 self
791 }
792
793 pub fn message(self, message: Message) -> Self {
796 self.messages([message])
797 }
798
799 pub fn messages(mut self, messages: impl IntoIterator<Item = Message>) -> Self {
802 let prompt = self.chat_history.pop();
803 self.chat_history.extend(messages);
804 self.chat_history.extend(prompt);
805 self
806 }
807
808 pub fn document(mut self, document: Document) -> Self {
810 self.documents.push(document);
811 self
812 }
813
814 pub fn documents(mut self, documents: impl IntoIterator<Item = Document>) -> Self {
816 self.documents.extend(documents);
817 self
818 }
819
820 pub fn tool(self, tool: ToolDefinition) -> Self {
822 self.tools(vec![tool])
823 }
824
825 pub fn tools(mut self, tools: Vec<ToolDefinition>) -> Self {
827 let first = self.tools.is_empty();
828 self.tools.extend(tools);
829 self.warn_if_shadowed("tools", first && !self.tools.is_empty());
830 self
831 }
832
833 pub fn provider_tool(self, tool: ProviderToolDefinition) -> Self {
837 self.provider_tools(vec![tool])
838 }
839
840 pub fn provider_tools(mut self, tools: Vec<ProviderToolDefinition>) -> Self {
843 self.additional_params =
844 merge_provider_tools_into_additional_params(self.additional_params.take(), tools);
845 self
846 }
847
848 pub fn additional_params(
852 mut self,
853 additional_params: impl Into<Option<serde_json::Value>>,
854 ) -> Self {
855 let additional_params = additional_params.into();
856 for key in shadowed_typed_fields(
857 additional_params.as_ref(),
858 &[
859 ("temperature", self.temperature.is_some()),
860 ("max_tokens", self.max_tokens.is_some()),
861 ("tool_choice", self.tool_choice.is_some()),
862 ("model", self.model.is_some()),
863 ("tools", !self.tools.is_empty()),
864 ("response_format", self.output_schema.is_some()),
865 ],
866 ) {
867 warn_shadowed(key);
868 }
869 self.additional_params =
870 json_utils::merge_params(self.additional_params.take(), additional_params);
871 self
872 }
873
874 pub fn temperature(mut self, temperature: impl Into<Option<f64>>) -> Self {
876 self.temperature = temperature.into();
877 self.warn_if_shadowed("temperature", self.temperature.is_some());
878 self
879 }
880
881 pub fn max_tokens(mut self, max_tokens: impl Into<Option<u64>>) -> Self {
884 self.max_tokens = max_tokens.into();
885 self.warn_if_shadowed("max_tokens", self.max_tokens.is_some());
886 self
887 }
888
889 pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
891 self.tool_choice = Some(tool_choice);
892 self.warn_if_shadowed("tool_choice", true);
893 self
894 }
895
896 pub fn output_schema(mut self, schema: impl Into<Option<schemars::Schema>>) -> Self {
900 self.output_schema = schema.into();
901 self.warn_if_shadowed("response_format", self.output_schema.is_some());
902 self
903 }
904
905 pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
908 self.record_telemetry_content = enabled;
909 self
910 }
911
912 pub fn messages_for_telemetry(&self) -> Vec<Message> {
915 self.chat_history_with_documents()
916 }
917
918 fn warn_if_shadowed(&self, key: &'static str, set: bool) {
920 if !shadowed_typed_fields(self.additional_params.as_ref(), &[(key, set)]).is_empty() {
921 warn_shadowed(key);
922 }
923 }
924}
925
926fn warn_shadowed(key: &str) {
927 if matches!(key, "tools" | "response_format") {
928 tracing::warn!(
929 key,
930 "additional_params also carries `{key}`; the provider decides how it combines with the typed field"
931 );
932 } else {
933 tracing::warn!(
934 key,
935 "additional_params overrides the typed `{key}` field set on the same request"
936 );
937 }
938}
939
940impl From<&str> for CompletionRequest {
941 fn from(prompt: &str) -> Self {
942 Self::new(prompt)
943 }
944}
945
946impl From<String> for CompletionRequest {
947 fn from(prompt: String) -> Self {
948 Self::new(prompt)
949 }
950}
951
952impl From<Message> for CompletionRequest {
953 fn from(prompt: Message) -> Self {
954 Self::new(prompt)
955 }
956}
957
958impl From<Vec<Message>> for CompletionRequest {
961 fn from(chat_history: Vec<Message>) -> Self {
962 Self::conversation(chat_history)
963 }
964}
965
966pub(crate) fn shadowed_typed_fields<'a>(
971 additional_params: Option<&serde_json::Value>,
972 typed: &[(&'a str, bool)],
973) -> Vec<&'a str> {
974 let Some(serde_json::Value::Object(params)) = additional_params else {
975 return Vec::new();
976 };
977 typed
978 .iter()
979 .filter(|(key, set)| *set && params.contains_key(*key))
980 .map(|(key, _)| *key)
981 .collect()
982}
983
984#[cfg(test)]
985mod tests;
986
987#[cfg(test)]
988mod response_identity_tests;
989
990#[cfg(test)]
991mod plain_value_tests;