mod config;
mod deepseek;
mod error;
mod prompt;
mod schema;
mod transport;
mod usage;
extern crate self as cetai;
use std::sync::OnceLock;
pub use cetai_macros::{ai, prompt};
pub use config::{AiConfig, Thinking};
pub use error::{AiError, Result};
pub use transport::{BoxFuture, Transport, TransportError, TransportRequest, TransportResponse};
static CONFIG: OnceLock<AiConfig> = OnceLock::new();
pub fn init(config: AiConfig) -> Result<()> {
config.validate()?;
CONFIG
.set(config)
.map_err(|_| AiError::InvalidConfig("cetai::init was called more than once".to_string()))
}
fn global_config() -> Result<&'static AiConfig> {
if let Some(config) = CONFIG.get() {
return Ok(config);
}
let config = AiConfig::from_env()?;
let _ = CONFIG.set(config);
match CONFIG.get() {
Some(config) => Ok(config),
None => unreachable!("configuration was just initialized"),
}
}
#[doc(hidden)]
pub mod __private {
use std::time::Instant;
use serde::de::DeserializeOwned;
use serde_json::{Map, Value};
use crate::config::MODEL_MAX_OUTPUT_TOKENS;
use crate::config::{default_max_tokens, AiConfig, Thinking, MAX_RETRIES};
use crate::deepseek::{ChatRequest, LogicalResponse};
use crate::error::{content_fingerprint, summarize};
use crate::schema::OutputContract;
use crate::usage::UsageStats;
use crate::{deepseek, prompt as layout, usage, AiError, Result};
pub use serde_json;
#[derive(Debug, Default)]
pub struct CallOptions {
pub thinking: Option<Thinking>,
pub http_retries: Option<u32>,
pub repair_retries: Option<u32>,
pub max_tokens: Option<u32>,
}
pub fn serialize_param<T: serde::Serialize + ?Sized>(value: &T) -> Result<Value> {
serde_json::to_value(value).map_err(|err| AiError::InputSerialization(err.to_string()))
}
pub async fn call<T>(
prompt: &'static str,
params: Map<String, Value>,
staged_error: Option<AiError>,
options: CallOptions,
) -> Result<T>
where
T: DeserializeOwned + schemars::JsonSchema,
{
if let Some(err) = staged_error {
return Err(err);
}
let config = crate::global_config()?;
call_with_config(config.clone(), prompt, params, options).await
}
pub async fn call_with_config<T>(
config: AiConfig,
prompt: &'static str,
params: Map<String, Value>,
options: CallOptions,
) -> Result<T>
where
T: DeserializeOwned + schemars::JsonSchema,
{
config.validate()?;
let started = Instant::now();
let mut stats = UsageStats::default();
let result = run(&config, prompt, params, &options, &mut stats).await;
let status = if result.is_ok() { "ok" } else { "error" };
usage::emit(Some(&config.model), &stats, status, started.elapsed());
result
}
async fn run<T>(
config: &AiConfig,
prompt: &'static str,
params: Map<String, Value>,
options: &CallOptions,
stats: &mut UsageStats,
) -> Result<T>
where
T: DeserializeOwned + schemars::JsonSchema,
{
let http_retries = effective("http_retries", options.http_retries, config.http_retries)?;
let repair_retries = effective(
"repair_retries",
options.repair_retries,
config.repair_retries,
)?;
let thinking = options.thinking.unwrap_or(config.thinking);
let max_tokens = match options.max_tokens.or(config.max_tokens) {
Some(value) if value == 0 || value > MODEL_MAX_OUTPUT_TOKENS => {
return Err(AiError::InvalidConfig(format!(
"max_tokens must be in 1..={MODEL_MAX_OUTPUT_TOKENS}, got {value}"
)));
}
Some(value) => value,
None => default_max_tokens(thinking),
};
let contract = OutputContract::build::<T>()?;
let base_url = config.normalized_base_url()?;
let mut messages = layout::build_messages(prompt, &contract, ¶ms);
let mut round = 0;
loop {
stats.logical_requests += 1;
let request = ChatRequest::build(config, messages.clone(), thinking, max_tokens);
let response = deepseek::send(config, &base_url, &request, http_retries, stats).await?;
match process_response::<T>(response, &contract) {
Ok(value) => return Ok(value),
Err(ProcessFailure::Repairable {
raw_output,
summary,
final_error,
}) => {
if round >= repair_retries {
return Err(final_error);
}
round += 1;
stats.repair_rounds += 1;
messages.extend(layout::repair_messages(&raw_output, &summary));
}
Err(ProcessFailure::Final(err)) => return Err(err),
}
}
}
fn effective(name: &str, per_call: Option<u32>, configured: u32) -> Result<u32> {
let value = per_call.unwrap_or(configured);
if value > MAX_RETRIES {
return Err(AiError::InvalidConfig(format!(
"{name} must be in 0..={MAX_RETRIES}, got {value}"
)));
}
Ok(value)
}
enum ProcessFailure {
Repairable {
raw_output: String,
summary: String,
final_error: AiError,
},
Final(AiError),
}
fn process_response<T>(
response: LogicalResponse,
contract: &OutputContract,
) -> std::result::Result<T, ProcessFailure>
where
T: DeserializeOwned,
{
if response.tool_calls_present {
return Err(ProcessFailure::Final(AiError::Api {
status: None,
request_id: response.request_id,
summary: "unexpected tool_calls in a non-tool request".to_string(),
}));
}
let request_id = response.request_id;
let content = response.content.unwrap_or_default();
if response.finish_reason.as_deref() == Some("content_filter") {
return Err(ProcessFailure::Final(AiError::Api {
status: None,
request_id,
summary: "finish_reason: content_filter".to_string(),
}));
}
if response.finish_reason.as_deref() == Some("length") {
return Err(ProcessFailure::Repairable {
raw_output: content.clone(),
summary: "output truncated (finish_reason: length)".to_string(),
final_error: AiError::JsonParse {
request_id,
content_len: content.len(),
content_hash: content_fingerprint(&content),
summary: "model output truncated (finish_reason: length)".to_string(),
},
});
}
if content.trim().is_empty() {
return Err(ProcessFailure::Repairable {
raw_output: content,
summary: "model returned empty content".to_string(),
final_error: AiError::EmptyContent { request_id },
});
}
let value: Value = match serde_json::from_str(&content) {
Ok(value) => value,
Err(err) => {
return Err(ProcessFailure::Repairable {
raw_output: content.clone(),
summary: format!(
"output is not valid JSON: {}",
summarize(&err.to_string(), 120)
),
final_error: AiError::JsonParse {
request_id,
content_len: content.len(),
content_hash: content_fingerprint(&content),
summary: summarize(&err.to_string(), 200),
},
});
}
};
if let Err(summary) = contract.validate(&value) {
return Err(ProcessFailure::Repairable {
raw_output: content.clone(),
summary: summary.clone(),
final_error: AiError::SchemaValidation {
request_id,
content_len: content.len(),
content_hash: content_fingerprint(&content),
summary,
},
});
}
let result = value.get("result").cloned().ok_or_else(|| {
ProcessFailure::Final(AiError::SchemaValidation {
request_id: request_id.clone(),
content_len: content.len(),
content_hash: content_fingerprint(&content),
summary: "validated envelope is missing `result`".to_string(),
})
})?;
serde_json::from_value::<T>(result).map_err(|err| {
ProcessFailure::Final(AiError::OutputDeserialization {
content_len: content.len(),
content_hash: content_fingerprint(&content),
summary: summarize(&err.to_string(), 200),
})
})
}
}