cencori 1.4.0

Official Rust SDK for Cencori - AI Infrastructure for Production
Documentation
/// Documents module — extract text from PDFs and images, summarize, and query.
///
/// # Example
///
/// ```rust,no_run
/// use cencori::documents::DocumentParams;
/// use cencori::Cencori;
///
/// let cencori = Cencori::new(None, None, None).unwrap();
///
/// let result = cencori
///     .documents
///     .extract(&DocumentParams::from_url("https://example.com/contract.pdf"))
///     .unwrap();
/// println!("{}", result.text);
/// ```
use std::sync::Arc;

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

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

/// Document request parameters.
#[derive(Debug, Clone, Default, Serialize)]
pub struct DocumentParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub document_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub document_base64: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mime_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filename: Option<String>,
    #[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>,
    /// Only used by `query()`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub question: Option<String>,
}

impl DocumentParams {
    pub fn from_url(url: impl Into<String>) -> Self {
        Self { document_url: Some(url.into()), ..Default::default() }
    }

    pub fn from_base64(base64: impl Into<String>, mime_type: impl Into<String>) -> Self {
        Self {
            document_base64: Some(base64.into()),
            mime_type: Some(mime_type.into()),
            ..Default::default()
        }
    }

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

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

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

    fn validate(&self) -> Result<(), CencoriError> {
        if self.document_url.is_none() && self.document_base64.is_none() {
            return Err(CencoriError::config(
                "documents request requires document_url or document_base64",
            ));
        }
        Ok(())
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct DocumentUsage {
    #[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 DocumentCost {
    #[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 DocumentExtractResponse {
    pub text: String,
    #[serde(rename = "pageCount")]
    pub page_count: u32,
    pub kind: String,
    pub method: String,
    pub model: Option<String>,
    pub provider: Option<String>,
    pub metadata: Option<Value>,
    pub usage: Option<DocumentUsage>,
    pub cost: Option<DocumentCost>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct DocumentSummarizeResponse {
    pub summary: String,
    pub text: String,
    #[serde(rename = "pageCount")]
    pub page_count: u32,
    pub model: String,
    pub provider: String,
    #[serde(rename = "extractMethod")]
    pub extract_method: String,
    pub usage: DocumentUsage,
    pub cost: DocumentCost,
}

#[derive(Debug, Clone, Deserialize)]
pub struct DocumentQueryResponse {
    pub answer: String,
    pub question: String,
    #[serde(rename = "pageCount")]
    pub page_count: u32,
    pub model: String,
    pub provider: String,
    #[serde(rename = "extractMethod")]
    pub extract_method: String,
    pub usage: DocumentUsage,
    pub cost: DocumentCost,
}

#[derive(Debug, Clone)]
pub struct DocumentsModule {
    pub(crate) inner: Arc<InnerClient>,
}

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

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

    pub fn extract(&self, params: &DocumentParams) -> Result<DocumentExtractResponse, CencoriError> {
        self.post_sync("/api/ai/documents/extract", params)
    }

    pub fn summarize(&self, params: &DocumentParams) -> Result<DocumentSummarizeResponse, CencoriError> {
        self.post_sync("/api/ai/documents/summarize", params)
    }

    pub fn query(&self, params: &DocumentParams) -> Result<DocumentQueryResponse, CencoriError> {
        if params.question.as_deref().unwrap_or("").is_empty() {
            return Err(CencoriError::config("documents.query requires a question"));
        }
        self.post_sync("/api/ai/documents/query", params)
    }

    pub async fn async_extract(&self, params: &DocumentParams) -> Result<DocumentExtractResponse, CencoriError> {
        self.post_async("/api/ai/documents/extract", params).await
    }

    pub async fn async_summarize(&self, params: &DocumentParams) -> Result<DocumentSummarizeResponse, CencoriError> {
        self.post_async("/api/ai/documents/summarize", params).await
    }

    pub async fn async_query(&self, params: &DocumentParams) -> Result<DocumentQueryResponse, CencoriError> {
        if params.question.as_deref().unwrap_or("").is_empty() {
            return Err(CencoriError::config("documents.query requires a question"));
        }
        self.post_async("/api/ai/documents/query", params).await
    }

    fn post_sync<T: serde::de::DeserializeOwned>(
        &self,
        path: &str,
        params: &DocumentParams,
    ) -> 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: &DocumentParams,
    ) -> 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)
    }
}