cencori 1.4.0

Official Rust SDK for Cencori - AI Infrastructure for Production
Documentation
/// Main client for the Cencori SDK.
use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

use reqwest::header::{HeaderMap, HeaderValue, CONTENT_TYPE};

use crate::agents::AgentsModule;
use crate::ai::AIModule;
use crate::api_keys::APIKeysModule;
use crate::error::CencoriError;
use crate::memory::MemoryModule;
use crate::metrics::MetricsModule;
use crate::projects::ProjectsModule;
use crate::sessions::SessionsModule;
use crate::telemetry::TelemetryModule;
use crate::vision::VisionModule;
use crate::voice::VoiceModule;
use crate::documents::DocumentsModule;
use serde_json::Value;

const DEFAULT_BASE_URL: &str = "https://api.cencori.com";
const MAX_RETRIES: u32 = 3;

/// Shared inner state for the Cencori client.
#[derive(Debug, Clone)]
pub struct InnerClient {
    pub(crate) api_key: String,
    pub(crate) base_url: String,
    #[allow(dead_code)]
    pub(crate) headers: HashMap<String, String>,
    pub(crate) http_client: reqwest::Client,
    pub(crate) blocking_client: reqwest::blocking::Client,
}

impl InnerClient {
    fn new(
        api_key: String,
        base_url: String,
        headers: HashMap<String, String>,
        timeout: Duration,
    ) -> Result<Self, CencoriError> {
        let mut default_headers = HeaderMap::new();
        default_headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));

        let api_key_header_val = HeaderValue::from_str(&api_key)
            .map_err(|e| CencoriError::config(format!("Invalid API key header: {e}")))?;
        default_headers.insert("CENCORI_API_KEY", api_key_header_val);

        // Add any custom headers
        for (key, val) in &headers {
            if let Ok(v) = HeaderValue::from_str(val) {
                if let Ok(header_name) = reqwest::header::HeaderName::from_bytes(key.as_bytes()) {
                    default_headers.insert(header_name, v);
                }
            }
        }

        let http_client = reqwest::Client::builder()
            .default_headers(default_headers.clone())
            .timeout(timeout)
            .build()
            .map_err(CencoriError::Http)?;

        let blocking_client = reqwest::blocking::Client::builder()
            .default_headers(default_headers)
            .timeout(timeout)
            .build()
            .map_err(CencoriError::Http)?;

        Ok(Self {
            api_key,
            base_url,
            headers,
            http_client,
            blocking_client,
        })
    }

    /// Build the full URL for an API endpoint.
    pub(crate) fn url(&self, endpoint: &str) -> String {
        format!("{}{}", self.base_url, endpoint)
    }
}

// =============================================================================
// Coming Soon Modules
// =============================================================================

/// Compute module - Serverless functions & GPU access. 🚧 Coming Soon
#[derive(Debug, Clone)]
pub struct ComputeModule;

impl ComputeModule {
    pub fn run(&self, _function_name: &str) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Compute module coming soon".into(),
        ))
    }

    pub async fn async_run(&self, _function_name: &str) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Compute module coming soon".into(),
        ))
    }
}

/// Workflow module - AI pipelines & orchestration. 🚧 Coming Soon
#[derive(Debug, Clone)]
pub struct WorkflowModule;

impl WorkflowModule {
    pub fn trigger(&self, _workflow_id: &str) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Workflow module coming soon".into(),
        ))
    }

    pub async fn async_trigger(&self, _workflow_id: &str) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Workflow module coming soon".into(),
        ))
    }
}

/// Storage module - Vector database, knowledge base, RAG. 🚧 Coming Soon
#[derive(Debug, Clone, Default)]
pub struct StorageModule {
    pub vectors: VectorsSubmodule,
}

impl StorageModule {
    pub fn new() -> Self {
        Self::default()
    }
}

/// Vector storage submodule. 🚧 Coming Soon
#[derive(Debug, Clone, Default)]
pub struct VectorsSubmodule;

impl VectorsSubmodule {
    pub fn search(&self, _query: &str) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Storage module coming soon".into(),
        ))
    }

    pub fn upsert(&self, _vectors: Value) -> Result<(), CencoriError> {
        Err(CencoriError::NotImplemented(
            "Storage module coming soon".into(),
        ))
    }
}

// =============================================================================
// Main Client
// =============================================================================

/// Cencori SDK client.
///
/// One SDK for AI Gateway, Compute, Workflow, and Storage.
/// Every operation is secured, logged, and tracked.
#[derive(Debug, Clone)]
pub struct Cencori {
    pub(crate) inner: Arc<InnerClient>,

    /// AI module for chat completions, embeddings, streaming, and more.
    pub ai: AIModule,

    /// Vision module for analyze / describe / OCR / classify on images.
    pub vision: VisionModule,

    /// Voice module for text-to-speech and speech-to-text.
    pub voice: VoiceModule,

    /// Documents module for extract / summarize / query on PDFs and images.
    pub documents: DocumentsModule,

    /// Agents module for creating and managing AI agents.
    pub agents: AgentsModule,

    /// Projects module for managing Cencori projects.
    pub projects: ProjectsModule,

    /// API Keys module for managing API keys.
    pub api_keys: APIKeysModule,

    /// Metrics module for fetching usage metrics.
    pub metrics: MetricsModule,

    /// Memory module for vector storage, RAG, and semantic search.
    pub memory: MemoryModule,

    /// Telemetry module for reporting web traffic.
    pub telemetry: TelemetryModule,

    /// Sessions module for durable execution and pause/resume workflows.
    pub sessions: SessionsModule,

    /// Compute module - Serverless functions & GPU access. 🚧 Coming Soon
    pub compute: ComputeModule,

    /// Workflow module - AI pipelines & orchestration. 🚧 Coming Soon
    pub workflow: WorkflowModule,

    /// Storage module - Vector database, knowledge base, RAG. 🚧 Coming Soon
    pub storage: StorageModule,
}

impl Cencori {
    /// Create a new Cencori client.
    ///
    /// # Arguments
    ///
    /// * `api_key` - Optional API key. Falls back to `CENCORI_API_KEY` env var.
    /// * `base_url` - Optional base URL (default: "https://api.cencori.com").
    /// * `timeout_secs` - Optional timeout in seconds (default: 30.0).
    ///
    /// # Errors
    ///
    /// Returns `CencoriError::Config` if no API key is found.
    pub fn new(
        api_key: Option<&str>,
        base_url: Option<&str>,
        timeout_secs: Option<f64>,
    ) -> Result<Self, CencoriError> {
        let api_key = match api_key {
            Some(k) => k.to_string(),
            None => std::env::var("CENCORI_API_KEY").map_err(|_| {
                CencoriError::config(
                    "Cencori API key is required. Pass it via Cencori::new(\"csk_...\", None, None) \
                     or set the CENCORI_API_KEY environment variable.",
                )
            })?,
        };

        let base_url = base_url
            .unwrap_or(DEFAULT_BASE_URL)
            .trim_end_matches('/')
            .to_string();

        let timeout_secs = timeout_secs.unwrap_or(30.0);
        let timeout = Duration::from_secs_f64(timeout_secs);

        let inner = Arc::new(InnerClient::new(
            api_key,
            base_url,
            HashMap::new(),
            timeout,
        )?);

        Ok(Self {
            ai: AIModule::new(Arc::clone(&inner)),
            vision: VisionModule::new(Arc::clone(&inner)),
            voice: VoiceModule::new(Arc::clone(&inner)),
            documents: DocumentsModule::new(Arc::clone(&inner)),
            agents: AgentsModule::new(Arc::clone(&inner)),
            projects: ProjectsModule::new(Arc::clone(&inner)),
            api_keys: APIKeysModule::new(Arc::clone(&inner)),
            metrics: MetricsModule::new(Arc::clone(&inner)),
            memory: MemoryModule::new(Arc::clone(&inner)),
            telemetry: TelemetryModule::new(Arc::clone(&inner)),
            sessions: SessionsModule::new(Arc::clone(&inner)),
            compute: ComputeModule,
            workflow: WorkflowModule,
            storage: StorageModule::new(),
            inner,
        })
    }

    /// Get the base URL for API calls.
    pub fn get_base_url(&self) -> &str {
        &self.inner.base_url
    }

    /// Get the API key (raw, unmasked).
    pub fn get_api_key(&self) -> &str {
        &self.inner.api_key
    }

    /// Get the current configuration with masked API key hint.
    pub fn get_config(&self) -> std::collections::HashMap<String, String> {
        let key = &self.inner.api_key;
        let hint = if key.len() > 10 {
            format!("{}...{}", &key[..6], &key[key.len() - 4..])
        } else {
            "...".to_string()
        };

        let mut config = std::collections::HashMap::new();
        config.insert("base_url".to_string(), self.inner.base_url.clone());
        config.insert("api_key_hint".to_string(), hint);
        config
    }
}

// =============================================================================
// Response Handling
// =============================================================================

/// Parse an HTTP response body, dispatching errors by status code.
pub(crate) fn parse_response(
    status: reqwest::StatusCode,
    body_str: &str,
) -> Result<Value, CencoriError> {
    if status == 401 {
        return Err(CencoriError::Authentication);
    }

    if status == 429 {
        return Err(CencoriError::RateLimit);
    }

    let body: Value = serde_json::from_str(body_str).map_err(CencoriError::Json)?;

    if status == 400 {
        if let Some(reasons) = body.get("reasons").and_then(|r| r.as_array()) {
            let reasons: Vec<String> = reasons
                .iter()
                .filter_map(|r| r.as_str().map(String::from))
                .collect();
            return Err(CencoriError::safety(reasons));
        }
    }

    if !status.is_success() {
        let message = body
            .get("error")
            .and_then(|e| e.as_str())
            .unwrap_or("Request failed")
            .to_string();
        return Err(CencoriError::api(status.as_u16(), message));
    }

    Ok(body)
}