zai_rs/knowledge/
document_upload_file.rs

1use std::{collections::BTreeMap, path::PathBuf};
2
3use validator::Validate;
4
5use super::types::UploadFileResponse;
6use crate::client::ZaiClient;
7
8/// Slice type (knowledge_type)
9#[derive(Debug, Clone, Copy)]
10pub enum DocumentSliceType {
11    /// 1: Title-paragraph slicing (txt, doc, pdf, url, docx, ppt, pptx, md)
12    TitleParagraph = 1,
13    /// 2: Q&A slicing (txt, doc, pdf, url, docx, ppt, pptx, md)
14    QaPair = 2,
15    /// 3: Line slicing (xls, xlsx, csv)
16    Line = 3,
17    /// 5: Custom slicing (txt, doc, pdf, url, docx, ppt, pptx, md)
18    Custom = 5,
19    /// 6: Page slicing (pdf, ppt, pptx)
20    Page = 6,
21    /// 7: Single slice (xls, xlsx, csv)
22    Single = 7,
23}
24impl DocumentSliceType {
25    fn as_i64(self) -> i64 {
26        self as i64
27    }
28}
29
30/// Optional parameters for file upload
31#[derive(Debug, Clone, Default, Validate)]
32pub struct UploadFileOptions {
33    /// Document type; if omitted, the server parses dynamically
34    pub knowledge_type: Option<DocumentSliceType>,
35    /// Custom slicing rules; used when knowledge_type = 5
36    pub custom_separator: Option<Vec<String>>,
37    /// Custom slice size; used when knowledge_type = 5; valid range: 20..=2000
38    #[validate(range(min = 20, max = 2000))]
39    pub sentence_size: Option<u32>,
40    /// Whether to parse images
41    pub parse_image: Option<bool>,
42    /// Callback URL
43    #[validate(url)]
44    pub callback_url: Option<String>,
45    /// Callback headers
46    pub callback_header: Option<BTreeMap<String, String>>,
47    /// Document word number limit (must be numeric string per API)
48    pub word_num_limit: Option<String>,
49    /// Request id
50    #[validate(length(min = 1))]
51    pub req_id: Option<String>,
52}
53
54/// File upload request (multipart/form-data)
55///
56/// Credentials and transport live on the [`ZaiClient`], passed to
57/// [`send_via`](Self::send_via).
58pub struct DocumentUploadFileRequest {
59    knowledge_id: String,
60    files: Vec<PathBuf>,
61    options: UploadFileOptions,
62}
63
64impl DocumentUploadFileRequest {
65    /// Create a new request for a specific knowledge base id
66    pub fn new(knowledge_id: impl Into<String>) -> Self {
67        Self {
68            knowledge_id: knowledge_id.into(),
69            files: Vec::new(),
70            options: UploadFileOptions::default(),
71        }
72    }
73
74    /// Add a local file path to upload
75    pub fn add_file_path(mut self, path: impl Into<PathBuf>) -> Self {
76        self.files.push(path.into());
77        self
78    }
79
80    /// Set optional parameters
81    pub fn with_options(mut self, opts: UploadFileOptions) -> Self {
82        self.options = opts;
83        self
84    }
85
86    /// Mutable access to options for incremental configuration
87    pub fn options_mut(&mut self) -> &mut UploadFileOptions {
88        &mut self.options
89    }
90
91    /// Validate cross-field constraints not expressible via `validator`
92    fn validate_cross(&self) -> crate::ZaiResult<()> {
93        // When knowledge_type is Custom (5), sentence_size should be within 20..=2000
94        if let Some(DocumentSliceType::Custom) = self.options.knowledge_type {
95            // sentence_size recommended; API shows default 300; we ensure range if provided
96            if let Some(sz) = self.options.sentence_size
97                && !(20..=2000).contains(&sz)
98            {
99                return Err(crate::client::error::ZaiError::ApiError {
100                    code: crate::client::error::codes::SDK_VALIDATION,
101                    message: "sentence_size must be 20..=2000 when knowledge_type=Custom (5)"
102                        .to_string(),
103                });
104            }
105        }
106        if let Some(ref w) = self.options.word_num_limit
107            && !w.chars().all(|c| c.is_ascii_digit())
108        {
109            return Err(crate::client::error::ZaiError::ApiError {
110                code: crate::client::error::codes::SDK_VALIDATION,
111                message: "word_num_limit must be numeric string".to_string(),
112            });
113        }
114        if self.files.is_empty() {
115            return Err(crate::client::error::ZaiError::ApiError {
116                code: crate::client::error::codes::SDK_VALIDATION,
117                message: "at least one file path must be provided".to_string(),
118            });
119        }
120        Ok(())
121    }
122
123    /// Send the multipart request via a [`ZaiClient`] and parse the typed response.
124    pub async fn send_via(&self, client: &ZaiClient) -> crate::ZaiResult<UploadFileResponse> {
125        self.options.validate()?;
126        self.validate_cross()?;
127
128        let route = crate::client::routes::DOCUMENTS_UPLOAD;
129        let url = client
130            .endpoints()
131            .resolve_route(route, &[&self.knowledge_id])?;
132        let mut factory = crate::client::transport::multipart::MultipartBodyFactory::new();
133        if let Some(t) = self.options.knowledge_type {
134            factory = factory.field("knowledge_type", t.as_i64().to_string())?;
135        }
136        if let Some(seps) = self.options.custom_separator.as_ref() {
137            factory = factory.field("custom_separator", serde_json::to_string(seps)?)?;
138        }
139        if let Some(sz) = self.options.sentence_size {
140            factory = factory.field("sentence_size", sz.to_string())?;
141        }
142        if let Some(pi) = self.options.parse_image {
143            factory = factory.field("parse_image", pi.to_string())?;
144        }
145        if let Some(url) = self.options.callback_url.as_ref() {
146            factory = factory.field("callback_url", url.clone())?;
147        }
148        if let Some(header) = self.options.callback_header.as_ref() {
149            factory = factory.field("callback_header", serde_json::to_string(header)?)?;
150        }
151        if let Some(limit) = self.options.word_num_limit.as_ref() {
152            factory = factory.field("word_num_limit", limit.clone())?;
153        }
154        if let Some(req_id) = self.options.req_id.as_ref() {
155            factory = factory.field("req_id", req_id.clone())?;
156        }
157        for path in &self.files {
158            let part = crate::client::transport::multipart::FilePart::from_path(path)?;
159            factory = factory.file_named("files", part)?;
160        }
161        client
162            .send_multipart::<UploadFileResponse>(route.method(), url, &factory)
163            .await
164    }
165}
zai_rs/knowledge/document_upload_file.rs

zai_rs/knowledge/
document_upload_file.rs
