Skip to main content

cetai/
lib.rs

1//! Cetai(鲸语)— typed `prompt!` expressions and `#[ai]` functions for
2//! natural-language tasks over DeepSeek.
3//!
4//! ```ignore
5//! use cetai::{ai, prompt};
6//!
7//! #[ai]
8//! async fn summarize(article: String) -> cetai::Result<Summary> {
9//!     prompt!("总结 {article}")
10//! }
11//! ```
12//!
13//! Referenced bindings are serialized and sent to the configured third-party
14//! model service. See the repository `README.md` / `PLAN.md` for the security
15//! and privacy boundary.
16//!
17//! The HTTP transport layer is replaceable: the default `reqwest-transport`
18//! feature uses reqwest + tokio, while bevy, wasm and similar hosts can
19//! install their own [`Transport`] implementation via [`AiConfig::transport`].
20
21mod config;
22mod deepseek;
23mod error;
24mod prompt;
25mod schema;
26mod transport;
27mod usage;
28
29// Allows macro expansions inside this package (examples, tests) to keep
30// referring to the runtime as `::cetai`.
31extern crate self as cetai;
32
33use std::sync::OnceLock;
34
35pub use cetai_macros::{ai, prompt};
36pub use config::{AiConfig, Thinking};
37pub use error::{AiError, Result};
38pub use transport::{BoxFuture, Transport, TransportError, TransportRequest, TransportResponse};
39
40static CONFIG: OnceLock<AiConfig> = OnceLock::new();
41
42/// Initializes the global configuration.
43///
44/// The passed configuration is complete: no implicit environment merging
45/// happens. Configuration is immutable once set; calling `init` twice returns
46/// [`AiError::InvalidConfig`]. Without `init`, the first AI call lazily uses
47/// [`AiConfig::from_env`].
48pub fn init(config: AiConfig) -> Result<()> {
49    config.validate()?;
50    CONFIG
51        .set(config)
52        .map_err(|_| AiError::InvalidConfig("cetai::init was called more than once".to_string()))
53}
54
55fn global_config() -> Result<&'static AiConfig> {
56    if let Some(config) = CONFIG.get() {
57        return Ok(config);
58    }
59    let config = AiConfig::from_env()?;
60    // A racing initializer may win; either way the stored value is used.
61    let _ = CONFIG.set(config);
62    match CONFIG.get() {
63        Some(config) => Ok(config),
64        None => unreachable!("configuration was just initialized"),
65    }
66}
67
68/// Implementation details used by macro expansions. Not public API; no
69/// stability guarantees.
70#[doc(hidden)]
71pub mod __private {
72    use std::time::Instant;
73
74    use serde::de::DeserializeOwned;
75    use serde_json::{Map, Value};
76
77    use crate::config::MODEL_MAX_OUTPUT_TOKENS;
78    use crate::config::{default_max_tokens, AiConfig, Thinking, MAX_RETRIES};
79    use crate::deepseek::{ChatRequest, LogicalResponse};
80    use crate::error::{content_fingerprint, summarize};
81    use crate::schema::OutputContract;
82    use crate::usage::UsageStats;
83    use crate::{deepseek, prompt as layout, usage, AiError, Result};
84
85    pub use serde_json;
86
87    /// Per-call overrides set by `prompt!` options or `#[ai]` attributes.
88    #[derive(Debug, Default)]
89    pub struct CallOptions {
90        pub thinking: Option<Thinking>,
91        pub http_retries: Option<u32>,
92        pub repair_retries: Option<u32>,
93        pub max_tokens: Option<u32>,
94    }
95
96    /// Serializes one referenced binding by shared reference into an owned
97    /// JSON value. Errors are staged into the future, never panicked.
98    pub fn serialize_param<T: serde::Serialize + ?Sized>(value: &T) -> Result<Value> {
99        serde_json::to_value(value).map_err(|err| AiError::InputSerialization(err.to_string()))
100    }
101
102    /// Entry point for macro expansions: resolves the global configuration
103    /// (lazily from the process environment when `init` was not called).
104    pub async fn call<T>(
105        prompt: &'static str,
106        params: Map<String, Value>,
107        staged_error: Option<AiError>,
108        options: CallOptions,
109    ) -> Result<T>
110    where
111        T: DeserializeOwned + schemars::JsonSchema,
112    {
113        // The staged serialization error surfaces at first poll, before any
114        // configuration lookup or network activity.
115        if let Some(err) = staged_error {
116            return Err(err);
117        }
118        let config = crate::global_config()?;
119        call_with_config(config.clone(), prompt, params, options).await
120    }
121
122    /// Same as [`call`] but with an explicit configuration; used by tests and
123    /// by applications that manage configuration themselves.
124    pub async fn call_with_config<T>(
125        config: AiConfig,
126        prompt: &'static str,
127        params: Map<String, Value>,
128        options: CallOptions,
129    ) -> Result<T>
130    where
131        T: DeserializeOwned + schemars::JsonSchema,
132    {
133        config.validate()?;
134        let started = Instant::now();
135        let mut stats = UsageStats::default();
136        let result = run(&config, prompt, params, &options, &mut stats).await;
137        let status = if result.is_ok() { "ok" } else { "error" };
138        usage::emit(Some(&config.model), &stats, status, started.elapsed());
139        result
140    }
141
142    async fn run<T>(
143        config: &AiConfig,
144        prompt: &'static str,
145        params: Map<String, Value>,
146        options: &CallOptions,
147        stats: &mut UsageStats,
148    ) -> Result<T>
149    where
150        T: DeserializeOwned + schemars::JsonSchema,
151    {
152        let http_retries = effective("http_retries", options.http_retries, config.http_retries)?;
153        let repair_retries = effective(
154            "repair_retries",
155            options.repair_retries,
156            config.repair_retries,
157        )?;
158        let thinking = options.thinking.unwrap_or(config.thinking);
159        let max_tokens = match options.max_tokens.or(config.max_tokens) {
160            Some(value) if value == 0 || value > MODEL_MAX_OUTPUT_TOKENS => {
161                return Err(AiError::InvalidConfig(format!(
162                    "max_tokens must be in 1..={MODEL_MAX_OUTPUT_TOKENS}, got {value}"
163                )));
164            }
165            Some(value) => value,
166            // Automatic default follows the *effective* thinking level.
167            None => default_max_tokens(thinking),
168        };
169
170        let contract = OutputContract::build::<T>()?;
171        let base_url = config.normalized_base_url()?;
172        let mut messages = layout::build_messages(prompt, &contract, &params);
173
174        let mut round = 0;
175        loop {
176            stats.logical_requests += 1;
177            let request = ChatRequest::build(config, messages.clone(), thinking, max_tokens);
178            let response = deepseek::send(config, &base_url, &request, http_retries, stats).await?;
179            match process_response::<T>(response, &contract) {
180                Ok(value) => return Ok(value),
181                Err(ProcessFailure::Repairable {
182                    raw_output,
183                    summary,
184                    final_error,
185                }) => {
186                    if round >= repair_retries {
187                        return Err(final_error);
188                    }
189                    round += 1;
190                    stats.repair_rounds += 1;
191                    // Repair only appends; the existing prefix is untouched.
192                    messages.extend(layout::repair_messages(&raw_output, &summary));
193                }
194                Err(ProcessFailure::Final(err)) => return Err(err),
195            }
196        }
197    }
198
199    fn effective(name: &str, per_call: Option<u32>, configured: u32) -> Result<u32> {
200        let value = per_call.unwrap_or(configured);
201        if value > MAX_RETRIES {
202            return Err(AiError::InvalidConfig(format!(
203                "{name} must be in 0..={MAX_RETRIES}, got {value}"
204            )));
205        }
206        Ok(value)
207    }
208
209    enum ProcessFailure {
210        /// The model may fix its output in a follow-up request.
211        Repairable {
212            raw_output: String,
213            summary: String,
214            final_error: AiError,
215        },
216        /// Returned directly without entering the repair dialog.
217        Final(AiError),
218    }
219
220    fn process_response<T>(
221        response: LogicalResponse,
222        contract: &OutputContract,
223    ) -> std::result::Result<T, ProcessFailure>
224    where
225        T: DeserializeOwned,
226    {
227        if response.tool_calls_present {
228            return Err(ProcessFailure::Final(AiError::Api {
229                status: None,
230                request_id: response.request_id,
231                summary: "unexpected tool_calls in a non-tool request".to_string(),
232            }));
233        }
234
235        let request_id = response.request_id;
236        let content = response.content.unwrap_or_default();
237
238        if response.finish_reason.as_deref() == Some("content_filter") {
239            return Err(ProcessFailure::Final(AiError::Api {
240                status: None,
241                request_id,
242                summary: "finish_reason: content_filter".to_string(),
243            }));
244        }
245
246        if response.finish_reason.as_deref() == Some("length") {
247            return Err(ProcessFailure::Repairable {
248                raw_output: content.clone(),
249                summary: "output truncated (finish_reason: length)".to_string(),
250                final_error: AiError::JsonParse {
251                    request_id,
252                    content_len: content.len(),
253                    content_hash: content_fingerprint(&content),
254                    summary: "model output truncated (finish_reason: length)".to_string(),
255                },
256            });
257        }
258
259        // finish_reason `stop` (or an absent/unknown value): normal parsing.
260        if content.trim().is_empty() {
261            return Err(ProcessFailure::Repairable {
262                raw_output: content,
263                summary: "model returned empty content".to_string(),
264                final_error: AiError::EmptyContent { request_id },
265            });
266        }
267
268        let value: Value = match serde_json::from_str(&content) {
269            Ok(value) => value,
270            Err(err) => {
271                return Err(ProcessFailure::Repairable {
272                    raw_output: content.clone(),
273                    summary: format!(
274                        "output is not valid JSON: {}",
275                        summarize(&err.to_string(), 120)
276                    ),
277                    final_error: AiError::JsonParse {
278                        request_id,
279                        content_len: content.len(),
280                        content_hash: content_fingerprint(&content),
281                        summary: summarize(&err.to_string(), 200),
282                    },
283                });
284            }
285        };
286
287        if let Err(summary) = contract.validate(&value) {
288            return Err(ProcessFailure::Repairable {
289                raw_output: content.clone(),
290                summary: summary.clone(),
291                final_error: AiError::SchemaValidation {
292                    request_id,
293                    content_len: content.len(),
294                    content_hash: content_fingerprint(&content),
295                    summary,
296                },
297            });
298        }
299
300        // Schema passed; deserialization failure is not model-repairable.
301        let result = value.get("result").cloned().ok_or_else(|| {
302            ProcessFailure::Final(AiError::SchemaValidation {
303                request_id: request_id.clone(),
304                content_len: content.len(),
305                content_hash: content_fingerprint(&content),
306                summary: "validated envelope is missing `result`".to_string(),
307            })
308        })?;
309        serde_json::from_value::<T>(result).map_err(|err| {
310            ProcessFailure::Final(AiError::OutputDeserialization {
311                content_len: content.len(),
312                content_hash: content_fingerprint(&content),
313                summary: summarize(&err.to_string(), 200),
314            })
315        })
316    }
317}