1mod config;
22mod deepseek;
23mod error;
24mod prompt;
25mod schema;
26mod transport;
27mod usage;
28
29extern 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
42pub 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 let _ = CONFIG.set(config);
62 match CONFIG.get() {
63 Some(config) => Ok(config),
64 None => unreachable!("configuration was just initialized"),
65 }
66}
67
68#[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 #[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 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 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 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 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 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, ¶ms);
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 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 Repairable {
212 raw_output: String,
213 summary: String,
214 final_error: AiError,
215 },
216 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 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 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}