Skip to main content

rig_core/providers/zai/
extension.rs

1//! Z.AI's typed request options and reply extras. One entry serves its
2//! OpenAI-format API (<https://docs.z.ai/api-reference/llm/chat-completion>)
3//! and its Anthropic-format Messages API, which takes no Z.AI field of its
4//! own.
5//!
6//! ```
7//! use rig_core::completion::CompletionRequest;
8//! use rig_core::providers::zai::extension::ZaiOptions;
9//!
10//! let options = ZaiOptions::new().user_id("user-1");
11//! let request = CompletionRequest::new("hi").provider_option(options);
12//! # let _ = request;
13//! ```
14
15use serde::Serialize;
16use serde_json::Value;
17
18use crate::completion::provider_options::reply_field;
19use crate::completion::{ExtensionOptions, ProviderExtension, ReplyExtras};
20use crate::message::Api;
21use crate::providers::anthropic::extension::MessagesStop;
22
23/// Z.AI's extension marker.
24#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
25pub struct ZaiExt;
26
27impl ProviderExtension for ZaiExt {
28    const PROVIDER: &'static str = super::PROVIDER_NAME;
29    type Options = ZaiOptions;
30    type Extras = ZaiExtras;
31}
32
33/// Z.AI's request options, by route. The field setters here write the
34/// same field as [`chat`](Self::chat), which replaces every field set
35/// before it; the Messages API takes none of them.
36#[non_exhaustive]
37#[derive(Clone, Debug, Default, PartialEq, Serialize)]
38pub struct ZaiOptions {
39    /// Sent on the OpenAI-format API only.
40    #[serde(rename = "openai.chat")]
41    pub chat: ZaiChat,
42}
43
44impl ZaiOptions {
45    /// No option set.
46    pub fn new() -> Self {
47        Self::default()
48    }
49
50    /// Send `chat` on the OpenAI-format API.
51    pub fn chat(mut self, chat: ZaiChat) -> Self {
52        self.chat = chat;
53        self
54    }
55
56    /// Apply `set` to the OpenAI-format section.
57    fn with_chat(mut self, set: impl FnOnce(ZaiChat) -> ZaiChat) -> Self {
58        self.chat = set(std::mem::take(&mut self.chat));
59        self
60    }
61
62    /// Whether to sample, on the OpenAI-format API, as
63    /// [`ZaiChat::do_sample`].
64    pub fn do_sample(self, sample: bool) -> Self {
65        self.with_chat(|chat| chat.do_sample(sample))
66    }
67
68    /// Identify the request as `id`, on the OpenAI-format API, as
69    /// [`ZaiChat::request_id`].
70    pub fn request_id(self, id: impl Into<String>) -> Self {
71        self.with_chat(|chat| chat.request_id(id))
72    }
73
74    /// Name the end user, on the OpenAI-format API, as
75    /// [`ZaiChat::user_id`].
76    pub fn user_id(self, id: impl Into<String>) -> Self {
77        self.with_chat(|chat| chat.user_id(id))
78    }
79
80    /// Whether earlier turns' thinking is dropped from context, on the
81    /// OpenAI-format API, as [`ZaiChat::clear_thinking`].
82    pub fn clear_thinking(self, clear: bool) -> Self {
83        self.with_chat(|chat| chat.clear_thinking(clear))
84    }
85}
86
87impl ExtensionOptions for ZaiOptions {
88    type Ext = ZaiExt;
89}
90
91/// The fields Z.AI's OpenAI-format API takes.
92#[non_exhaustive]
93#[derive(Clone, Debug, Default, PartialEq, Serialize)]
94pub struct ZaiChat {
95    /// Whether to sample; `false` decodes greedily.
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub do_sample: Option<bool>,
98    /// The caller's id for the request.
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub request_id: Option<String>,
101    /// A stable id of the end user.
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub user_id: Option<String>,
104    /// Thinking fields sent beside the mapped thinking type.
105    #[serde(skip_serializing_if = "ZaiThinking::is_empty")]
106    pub thinking: ZaiThinking,
107}
108
109/// The `thinking` fields Z.AI takes beside the type the generation options
110/// map.
111#[non_exhaustive]
112#[derive(Clone, Debug, Default, PartialEq, Serialize)]
113pub struct ZaiThinking {
114    /// Whether earlier turns' thinking is dropped from context.
115    #[serde(skip_serializing_if = "Option::is_none")]
116    pub clear_thinking: Option<bool>,
117}
118
119impl ZaiThinking {
120    fn is_empty(&self) -> bool {
121        self.clear_thinking.is_none()
122    }
123}
124
125impl ZaiChat {
126    /// No option set.
127    pub fn new() -> Self {
128        Self::default()
129    }
130
131    /// Whether to sample.
132    pub fn do_sample(mut self, sample: bool) -> Self {
133        self.do_sample = Some(sample);
134        self
135    }
136
137    /// Identify the request as `id`.
138    pub fn request_id(mut self, id: impl Into<String>) -> Self {
139        self.request_id = Some(id.into());
140        self
141    }
142
143    /// Name the end user.
144    pub fn user_id(mut self, id: impl Into<String>) -> Self {
145        self.user_id = Some(id.into());
146        self
147    }
148
149    /// Whether earlier turns' thinking is dropped from context.
150    pub fn clear_thinking(mut self, clear: bool) -> Self {
151        self.thinking.clear_thinking = Some(clear);
152        self
153    }
154}
155
156/// Z.AI's reply fields. Each is `None` when the reply lacks it.
157#[non_exhaustive]
158#[derive(Clone, Debug, Default, PartialEq)]
159pub struct ZaiExtras {
160    /// The request's id. OpenAI-format API only.
161    pub request_id: Option<String>,
162    /// `stop_reason`, verbatim. Messages route.
163    pub stop_reason: Option<String>,
164    /// `stop_sequence`: the stop sequence the turn ended on. Messages route.
165    pub stop_sequence: Option<String>,
166}
167
168impl ReplyExtras for ZaiExtras {
169    fn from_reply(api: &Api, raw: &Value) -> Result<Self, serde_json::Error> {
170        if let Some(stop) = MessagesStop::of(api, raw)? {
171            return Ok(Self {
172                stop_reason: stop.stop_reason,
173                stop_sequence: stop.stop_sequence,
174                ..Self::default()
175            });
176        }
177        if api.as_str() != "openai.chat" {
178            return Ok(Self::default());
179        }
180        Ok(Self {
181            request_id: reply_field(raw, "/request_id")?,
182            ..Self::default()
183        })
184    }
185}
186
187#[cfg(test)]
188mod tests;