cetai 0.1.1

Typed prompt! expressions and #[ai] functions for natural-language tasks over DeepSeek.
Documentation
//! Cetai(鲸语)— typed `prompt!` expressions and `#[ai]` functions for
//! natural-language tasks over DeepSeek.
//!
//! ```ignore
//! use cetai::{ai, prompt};
//!
//! #[ai]
//! async fn summarize(article: String) -> cetai::Result<Summary> {
//!     prompt!("总结 {article}")
//! }
//! ```
//!
//! Referenced bindings are serialized and sent to the configured third-party
//! model service. See the repository `README.md` / `PLAN.md` for the security
//! and privacy boundary.
//!
//! The HTTP transport layer is replaceable: the default `reqwest-transport`
//! feature uses reqwest + tokio, while bevy, wasm and similar hosts can
//! install their own [`Transport`] implementation via [`AiConfig::transport`].

mod config;
mod deepseek;
mod error;
mod prompt;
mod schema;
mod transport;
mod usage;

// Allows macro expansions inside this package (examples, tests) to keep
// referring to the runtime as `::cetai`.
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();

/// Initializes the global configuration.
///
/// The passed configuration is complete: no implicit environment merging
/// happens. Configuration is immutable once set; calling `init` twice returns
/// [`AiError::InvalidConfig`]. Without `init`, the first AI call lazily uses
/// [`AiConfig::from_env`].
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()?;
    // A racing initializer may win; either way the stored value is used.
    let _ = CONFIG.set(config);
    match CONFIG.get() {
        Some(config) => Ok(config),
        None => unreachable!("configuration was just initialized"),
    }
}

/// Implementation details used by macro expansions. Not public API; no
/// stability guarantees.
#[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;

    /// Per-call overrides set by `prompt!` options or `#[ai]` attributes.
    #[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>,
    }

    /// Serializes one referenced binding by shared reference into an owned
    /// JSON value. Errors are staged into the future, never panicked.
    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()))
    }

    /// Entry point for macro expansions: resolves the global configuration
    /// (lazily from the process environment when `init` was not called).
    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,
    {
        // The staged serialization error surfaces at first poll, before any
        // configuration lookup or network activity.
        if let Some(err) = staged_error {
            return Err(err);
        }
        let config = crate::global_config()?;
        call_with_config(config.clone(), prompt, params, options).await
    }

    /// Same as [`call`] but with an explicit configuration; used by tests and
    /// by applications that manage configuration themselves.
    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,
            // Automatic default follows the *effective* thinking level.
            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, &params);

        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;
                    // Repair only appends; the existing prefix is untouched.
                    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 {
        /// The model may fix its output in a follow-up request.
        Repairable {
            raw_output: String,
            summary: String,
            final_error: AiError,
        },
        /// Returned directly without entering the repair dialog.
        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(),
                },
            });
        }

        // finish_reason `stop` (or an absent/unknown value): normal parsing.
        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,
                },
            });
        }

        // Schema passed; deserialization failure is not model-repairable.
        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),
            })
        })
    }
}