cencori 1.4.0

Official Rust SDK for Cencori - AI Infrastructure for Production
Documentation
/// Vision module — analyze, describe, OCR, and classify images.
///
/// # Example
///
/// ```rust,no_run
/// use cencori::Cencori;
/// use cencori::vision::VisionParams;
///
/// let cencori = Cencori::new(Some("csk_..."), None, None).unwrap();
/// let params = VisionParams::from_url("https://example.com/photo.jpg")
///     .with_prompt("What breed of dog is this?");
/// let result = cencori.vision.analyze(&params).unwrap();
/// println!("{}", result.analysis);
/// ```
use std::sync::Arc;

use serde::{Deserialize, Serialize};
use serde_json::{json, Value};

use crate::client::{parse_response, InnerClient};
use crate::error::CencoriError;

/// A single image spec used inside `VisionParams::images`.
#[derive(Debug, Clone, Serialize)]
pub struct VisionImage {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub base64: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mime_type: Option<String>,
}

impl VisionImage {
    pub fn from_url(url: impl Into<String>) -> Self {
        Self { url: Some(url.into()), base64: None, mime_type: None }
    }
    pub fn from_base64(base64: impl Into<String>, mime_type: impl Into<String>) -> Self {
        Self { url: None, base64: Some(base64.into()), mime_type: Some(mime_type.into()) }
    }
}

/// Vision request parameters. Provide one of `image_url`, `image_base64`, or `images`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct VisionParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub image_base64: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mime_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub images: Option<Vec<VisionImage>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub model: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
}

impl VisionParams {
    /// Build params from an image URL (http(s):// or data:).
    pub fn from_url(url: impl Into<String>) -> Self {
        Self {
            image_url: Some(url.into()),
            ..Default::default()
        }
    }

    /// Build params from raw base64 bytes and a mime type.
    pub fn from_base64(base64: impl Into<String>, mime_type: impl Into<String>) -> Self {
        Self {
            image_base64: Some(base64.into()),
            mime_type: Some(mime_type.into()),
            ..Default::default()
        }
    }

    pub fn with_prompt(mut self, prompt: impl Into<String>) -> Self {
        self.prompt = Some(prompt.into());
        self
    }

    pub fn with_model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    pub fn with_max_tokens(mut self, max_tokens: u32) -> Self {
        self.max_tokens = Some(max_tokens);
        self
    }

    pub fn with_temperature(mut self, temperature: f64) -> Self {
        self.temperature = Some(temperature);
        self
    }

    pub fn with_response_format(mut self, response_format: impl Into<String>) -> Self {
        self.response_format = Some(response_format.into());
        self
    }

    /// Build multi-image params.
    pub fn from_images(images: Vec<VisionImage>) -> Self {
        Self { images: Some(images), ..Default::default() }
    }

    /// Add another image to the request.
    pub fn with_image(mut self, image: VisionImage) -> Self {
        self.images.get_or_insert_with(Vec::new).push(image);
        self
    }

    fn validate(&self) -> Result<(), CencoriError> {
        let has_multi = self.images.as_ref().is_some_and(|v| !v.is_empty());
        if self.image_url.is_none() && self.image_base64.is_none() && !has_multi {
            return Err(CencoriError::config(
                "vision request requires image_url, image_base64, or images",
            ));
        }
        Ok(())
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionUsage {
    #[serde(rename = "promptTokens")]
    pub prompt_tokens: u32,
    #[serde(rename = "completionTokens")]
    pub completion_tokens: u32,
    #[serde(rename = "totalTokens")]
    pub total_tokens: u32,
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionCost {
    #[serde(rename = "providerCostUsd")]
    pub provider_cost_usd: f64,
    #[serde(rename = "cencoriChargeUsd")]
    pub cencori_charge_usd: f64,
    #[serde(rename = "markupPercentage")]
    pub markup_percentage: f64,
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionResponse {
    pub analysis: String,
    pub model: String,
    pub provider: String,
    pub usage: VisionUsage,
    pub cost: VisionCost,
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionDescribeResponse {
    pub description: String,
    pub model: String,
    pub provider: String,
    pub usage: VisionUsage,
    pub cost: VisionCost,
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionOcrResponse {
    pub text: String,
    pub model: String,
    pub provider: String,
    pub usage: VisionUsage,
    pub cost: VisionCost,
}

#[derive(Debug, Clone, Deserialize)]
pub struct VisionClassifyResponse {
    /// Parsed JSON classification when the model returned valid JSON, else raw string.
    pub classification: Value,
    pub raw: String,
    pub model: String,
    pub provider: String,
    pub usage: VisionUsage,
    pub cost: VisionCost,
}

/// Vision module for image analysis, description, OCR, and classification.
#[derive(Debug, Clone)]
pub struct VisionModule {
    pub(crate) inner: Arc<InnerClient>,
}

impl VisionModule {
    pub(crate) fn new(inner: Arc<InnerClient>) -> Self {
        Self { inner }
    }

    fn payload(params: &VisionParams) -> Result<Value, CencoriError> {
        params.validate()?;
        Ok(json!(params))
    }

    // =========================================================================
    // Synchronous
    // =========================================================================

    /// Analyze an image with an optional custom prompt.
    pub fn analyze(&self, params: &VisionParams) -> Result<VisionResponse, CencoriError> {
        self.post_sync("/api/ai/vision", params)
    }

    /// Describe an image in rich detail.
    pub fn describe(&self, params: &VisionParams) -> Result<VisionDescribeResponse, CencoriError> {
        self.post_sync("/api/ai/vision/describe", params)
    }

    /// Extract all text visible in the image.
    pub fn ocr(&self, params: &VisionParams) -> Result<VisionOcrResponse, CencoriError> {
        self.post_sync("/api/ai/vision/ocr", params)
    }

    /// Classify the image and return structured tags/categories.
    pub fn classify(&self, params: &VisionParams) -> Result<VisionClassifyResponse, CencoriError> {
        self.post_sync("/api/ai/vision/classify", params)
    }

    // =========================================================================
    // Asynchronous
    // =========================================================================

    /// Async version of `analyze`.
    pub async fn async_analyze(
        &self,
        params: &VisionParams,
    ) -> Result<VisionResponse, CencoriError> {
        self.post_async("/api/ai/vision", params).await
    }

    /// Async version of `describe`.
    pub async fn async_describe(
        &self,
        params: &VisionParams,
    ) -> Result<VisionDescribeResponse, CencoriError> {
        self.post_async("/api/ai/vision/describe", params).await
    }

    /// Async version of `ocr`.
    pub async fn async_ocr(
        &self,
        params: &VisionParams,
    ) -> Result<VisionOcrResponse, CencoriError> {
        self.post_async("/api/ai/vision/ocr", params).await
    }

    /// Async version of `classify`.
    pub async fn async_classify(
        &self,
        params: &VisionParams,
    ) -> Result<VisionClassifyResponse, CencoriError> {
        self.post_async("/api/ai/vision/classify", params).await
    }

    // =========================================================================
    // Internals
    // =========================================================================

    fn post_sync<T: serde::de::DeserializeOwned>(
        &self,
        path: &str,
        params: &VisionParams,
    ) -> Result<T, CencoriError> {
        let payload = Self::payload(params)?;
        let url = self.inner.url(path);
        let response = self
            .inner
            .blocking_client
            .post(&url)
            .json(&payload)
            .send()
            .map_err(CencoriError::Http)?;

        let status = response.status();
        let body = response.text().map_err(CencoriError::Http)?;
        let data = parse_response(status, &body)?;
        serde_json::from_value(data).map_err(CencoriError::Json)
    }

    async fn post_async<T: serde::de::DeserializeOwned>(
        &self,
        path: &str,
        params: &VisionParams,
    ) -> Result<T, CencoriError> {
        let payload = Self::payload(params)?;
        let url = self.inner.url(path);
        let response = self
            .inner
            .http_client
            .post(&url)
            .json(&payload)
            .send()
            .await
            .map_err(CencoriError::Http)?;

        let status = response.status();
        let body = response.text().await.map_err(CencoriError::Http)?;
        let data = parse_response(status, &body)?;
        serde_json::from_value(data).map_err(CencoriError::Json)
    }
}