Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat: path variables and -p for add-resource (#1896)

MaojiaShengb9a8c4e120a9
diff --git a/crates/ov_cli/src/base_client.rs b/crates/ov_cli/src/base_client.rs
new file mode 100644
index 000000000..2b0d73b03
--- /dev/null
+++ b/crates/ov_cli/src/base_client.rs
@@ -0,0 +1,604 @@
+use reqwest::{Client as ReqwestClient, StatusCode};
+use serde::de::DeserializeOwned;
+use serde_json::Value;
+use std::fs::File;
+use std::path::Path;
+use std::str::FromStr;
+use tempfile::{Builder, NamedTempFile};
+use zip::CompressionMethod;
+use zip::write::FileOptions;
+
+use indicatif::{ProgressBar, ProgressStyle};
+
+use crate::error::{Error, Result};
+
+pub fn api_error_from_envelope(json: &Value, status: StatusCode) -> String {
+ let error_code = json
+ .get("error")
+ .and_then(|e| e.get("code"))
+ .and_then(|c| c.as_str());
+ let error_msg = json
+ .get("error")
+ .and_then(|e| e.get("message"))
+ .and_then(|m| m.as_str())
+ .map(|s| s.to_string())
+ .or_else(|| {
+ json.get("detail")
+ .and_then(|d| d.as_str())
+ .map(|s| s.to_string())
+ })
+ .unwrap_or_else(|| format!("HTTP error {}", status));
+
+ match error_code {
+ Some(code) => format!("[{}] {}", code, error_msg),
+ None => error_msg,
+ }
+}
+
+// ============ TimeoutConfig ============
+
+/// Dynamic timeout calculator based on file size
+#[derive(Debug, Clone, Copy)]
+pub struct TimeoutConfig {
+ min_timeout_secs: u64,
+ seconds_per_mb: f64,
+}
+
+impl TimeoutConfig {
+ pub const fn new(min_timeout_secs: u64, seconds_per_mb: f64) -> Self {
+ Self {
+ min_timeout_secs,
+ seconds_per_mb,
+ }
+ }
+
+ pub fn for_resource_processing() -> Self {
+ Self::new(60, 5.0)
+ }
+
+ pub fn for_upload() -> Self {
+ Self::new(60, 10.0)
+ }
+
+ pub fn calculate(&self, file_path: &Path) -> Result<std::time::Duration> {
+ let file_size = std::fs::metadata(file_path)?.len();
+ let file_size_mb = file_size as f64 / (1024.0 * 1024.0);
+ let calculated_timeout = (file_size_mb * self.seconds_per_mb).ceil() as u64;
+ let timeout_secs = std::cmp::max(self.min_timeout_secs, calculated_timeout);
+
+ Ok(std::time::Duration::from_secs(timeout_secs))
+ }
+}
+
+// ============ BaseClient ============
+
+/// Low-level HTTP client with timeout control and header management
+#[derive(Clone)]
+pub struct BaseClient {
+ pub(crate) http: ReqwestClient,
+ pub(crate) base_url: String,
+ pub(crate) api_key: Option<String>,
+ pub(crate) account: Option<String>,
+ pub(crate) user: Option<String>,
+ pub(crate) agent_id: Option<String>,
+ pub(crate) extra_headers: Option<std::collections::HashMap<String, String>>,
+}
+
+impl BaseClient {
+ pub fn new(
+ base_url: impl Into<String>,
+ api_key: Option<String>,
+ agent_id: Option<String>,
+ account: Option<String>,
+ user: Option<String>,
+ timeout_secs: f64,
+ extra_headers: Option<std::collections::HashMap<String, String>>,
+ ) -> Self {
+ let http = ReqwestClient::builder()
+ .timeout(std::time::Duration::from_secs_f64(timeout_secs))
+ .build()
+ .expect("Failed to build HTTP client");
+
+ Self {
+ http,
+ base_url: base_url.into().trim_end_matches('/').to_string(),
+ api_key,
+ account,
+ user,
+ agent_id,
+ extra_headers,
+ }
+ }
+
+ pub fn base_url(&self) -> &str {
+ &self.base_url
+ }
+
+ pub fn user_id(&self) -> Option<&str> {
+ self.user.as_deref()
+ }
+
+ pub fn agent_id(&self) -> Option<&str> {
+ self.agent_id.as_deref()
+ }
+
+ pub fn api_key(&self) -> Option<&str> {
+ self.api_key.as_deref()
+ }
+
+ pub fn build_headers(&self) -> reqwest::header::HeaderMap {
+ let mut headers = reqwest::header::HeaderMap::new();
+ headers.insert(
+ reqwest::header::CONTENT_TYPE,
+ reqwest::header::HeaderValue::from_static("application/json"),
+ );
+ if let Some(api_key) = &self.api_key {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(api_key) {
+ headers.insert("X-API-Key", value);
+ }
+ }
+ if let Some(agent_id) = &self.agent_id {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(agent_id) {
+ headers.insert("X-OpenViking-Agent", value);
+ }
+ }
+ if let Some(account) = &self.account {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(account) {
+ headers.insert("X-OpenViking-Account", value);
+ }
+ }
+ if let Some(user) = &self.user {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(user) {
+ headers.insert("X-OpenViking-User", value);
+ }
+ }
+ if let Some(extra_headers) = &self.extra_headers {
+ for (key, value) in extra_headers {
+ if let Ok(header_name) = reqwest::header::HeaderName::from_str(key) {
+ if let Ok(header_value) = reqwest::header::HeaderValue::from_str(value) {
+ headers.insert(header_name, header_value);
+ }
+ }
+ }
+ }
+ headers
+ }
+
+ pub(crate) async fn handle_response<T: DeserializeOwned>(&self, response: reqwest::Response) -> Result<T> {
+ let status = response.status();
+
+ if status == StatusCode::NO_CONTENT || status == StatusCode::ACCEPTED {
+ return serde_json::from_value(Value::Null)
+ .map_err(|e| Error::Parse(format!("Failed to parse empty response: {}", e)));
+ }
+
+ let bytes = response
+ .bytes()
+ .await
+ .map_err(|e| Error::Network(format!("Failed to read response body: {}", e)))?;
+
+ let json: Value = match serde_json::from_slice(&bytes) {
+ Ok(json) => json,
+ Err(e) => {
+ let body_str = String::from_utf8_lossy(&bytes);
+ return Err(Error::Network(format!(
+ "Failed to parse JSON response: {}\n\nRaw response body:\n{}",
+ e, body_str
+ )));
+ }
+ };
+
+ if !status.is_success() {
+ return Err(Error::Api(api_error_from_envelope(&json, status)));
+ }
+
+ if let Some(error) = json.get("error") {
+ if !error.is_null() {
+ let code = error
+ .get("code")
+ .and_then(|c| c.as_str())
+ .unwrap_or("UNKNOWN");
+ let message = error
+ .get("message")
+ .and_then(|m| m.as_str())
+ .unwrap_or("Unknown error");
+ return Err(Error::Api(format!("[{}] {}", code, message)));
+ }
+ }
+
+ let result = if let Some(result) = json.get("result") {
+ result.clone()
+ } else {
+ json.clone()
+ };
+
+ serde_json::from_value(result).map_err(|e| {
+ Error::Parse(format!(
+ "Failed to deserialize response: {}\n\nJSON that failed to parse:\n{}",
+ e, json
+ ))
+ })
+ }
+
+ pub(crate) fn create_client_with_timeout(&self, timeout: std::time::Duration) -> Result<ReqwestClient> {
+ ReqwestClient::builder()
+ .timeout(timeout)
+ .build()
+ .map_err(|e| Error::Network(format!("Failed to build HTTP client: {}", e)))
+ }
+
+ pub(crate) fn create_client_with_connect_timeout(
+ &self,
+ connect_timeout: std::time::Duration,
+ timeout: std::time::Duration,
+ ) -> Result<ReqwestClient> {
+ ReqwestClient::builder()
+ .connect_timeout(connect_timeout)
+ .timeout(timeout)
+ .build()
+ .map_err(|e| Error::Network(format!("Failed to build HTTP client: {}", e)))
+ }
+
+ pub async fn get<T: DeserializeOwned>(
+ &self,
+ path: &str,
+ params: &[(String, String)],
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let response = self
+ .http
+ .get(&url)
+ .headers(self.build_headers())
+ .query(params)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+
+ pub async fn post<B: serde::Serialize, T: DeserializeOwned>(
+ &self,
+ path: &str,
+ body: &B,
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let response = self
+ .http
+ .post(&url)
+ .headers(self.build_headers())
+ .json(body)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+
+ pub async fn post_with_timeout<B: serde::Serialize, T: DeserializeOwned>(
+ &self,
+ path: &str,
+ body: &B,
+ timeout: std::time::Duration,
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let client = self.create_client_with_timeout(timeout)?;
+
+ let response = client
+ .post(&url)
+ .headers(self.build_headers())
+ .json(body)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+
+ pub async fn put<B: serde::Serialize, T: DeserializeOwned>(
+ &self,
+ path: &str,
+ body: &B,
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let response = self
+ .http
+ .put(&url)
+ .headers(self.build_headers())
+ .json(body)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+
+ pub async fn delete<T: DeserializeOwned>(
+ &self,
+ path: &str,
+ params: &[(String, String)],
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let response = self
+ .http
+ .delete(&url)
+ .headers(self.build_headers())
+ .query(params)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+
+ pub async fn delete_with_body<B: serde::Serialize, T: DeserializeOwned>(
+ &self,
+ path: &str,
+ body: &B,
+ ) -> Result<T> {
+ let url = format!("{}{}", self.base_url, path);
+ let response = self
+ .http
+ .delete(&url)
+ .headers(self.build_headers())
+ .json(body)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
+
+ self.handle_response(response).await
+ }
+}
+
+// ============ FileUploader ============
+
+/// Handles file compression and upload logic
+pub struct FileUploader<'a> {
+ client: &'a BaseClient,
+ upload_mode: Option<String>,
+}
+
+impl<'a> FileUploader<'a> {
+ pub fn new(client: &'a BaseClient) -> Self {
+ Self {
+ client,
+ upload_mode: None,
+ }
+ }
+
+ pub fn with_upload_mode(mut self, upload_mode: Option<String>) -> Self {
+ self.upload_mode = upload_mode;
+ self
+ }
+
+ pub fn zip_directory(&self, dir_path: &Path) -> Result<NamedTempFile> {
+ if !dir_path.is_dir() {
+ return Err(Error::Network(format!(
+ "Path {} is not a directory",
+ dir_path.display()
+ )));
+ }
+
+ let temp_file = Builder::new().suffix(".zip").tempfile()?;
+ let file = File::create(temp_file.path())?;
+ let mut zip = zip::ZipWriter::new(file);
+ let options: FileOptions<'_, ()> =
+ FileOptions::default().compression_method(CompressionMethod::Deflated);
+
+ let walkdir = walkdir::WalkDir::new(dir_path);
+ for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
+ let path = entry.path();
+ if path.is_file() {
+ let name = path.strip_prefix(dir_path).unwrap_or(path);
+ let name_str = name.to_str().ok_or_else(|| {
+ Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
+ })?;
+ zip.start_file(name_str, options)?;
+ let mut file = File::open(path)?;
+ std::io::copy(&mut file, &mut zip)?;
+ }
+ }
+
+ zip.finish()?;
+ Ok(temp_file)
+ }
+
+ pub fn zip_directory_with_progress(
+ &self,
+ dir_path: &Path,
+ verbose: bool,
+ ) -> Result<NamedTempFile> {
+ if !dir_path.is_dir() {
+ return Err(Error::Network(format!(
+ "Path {} is not a directory",
+ dir_path.display()
+ )));
+ }
+
+ let temp_file = Builder::new().suffix(".zip").tempfile()?;
+ let file = File::create(temp_file.path())?;
+ let mut zip = zip::ZipWriter::new(file);
+ let options: FileOptions<'_, ()> =
+ FileOptions::default().compression_method(CompressionMethod::Deflated);
+
+ let mut total_size = 0u64;
+ let mut total_files = 0u64;
+ let walkdir = walkdir::WalkDir::new(dir_path);
+ for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
+ let path = entry.path();
+ if path.is_file() {
+ if let Ok(meta) = std::fs::metadata(path) {
+ total_size += meta.len();
+ total_files += 1;
+ }
+ }
+ }
+
+ let pb = if total_size > 0 {
+ let pb = ProgressBar::new(total_size);
+ pb.set_style(
+ ProgressStyle::default_bar()
+ .template("{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {bytes}/{total_bytes} ({eta}) {msg}")
+ .unwrap_or_else(|_| ProgressStyle::default_bar())
+ .progress_chars("#>-"),
+ );
+ pb.set_message(format!("Compressing {} files", total_files));
+ Some(pb)
+ } else {
+ let pb = ProgressBar::new_spinner();
+ pb.set_message("Compressing files...");
+ Some(pb)
+ };
+
+ let walkdir = walkdir::WalkDir::new(dir_path);
+ for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
+ let path = entry.path();
+ if path.is_file() {
+ let name = path.strip_prefix(dir_path).unwrap_or(path);
+ let name_str = name.to_str().ok_or_else(|| {
+ Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
+ })?;
+ if verbose {
+ eprintln!(" Adding: {}", name_str);
+ }
+ zip.start_file(name_str, options)?;
+ let mut file = File::open(path)?;
+ let file_size = std::io::copy(&mut file, &mut zip)?;
+
+ if let Some(pb) = &pb {
+ if pb.length().is_some() {
+ pb.inc(file_size);
+ }
+ }
+ }
+ }
+
+ zip.finish()?;
+
+ let zip_size = std::fs::metadata(temp_file.path())?.len();
+ let zip_size_mb = zip_size as f64 / 1024.0 / 1024.0;
+ let original_size_mb = if total_size > 0 {
+ total_size as f64 / 1024.0 / 1024.0
+ } else {
+ 0.0
+ };
+
+ if let Some(pb) = pb {
+ if total_size > 0 {
+ pb.finish_with_message(format!("Compression complete: {:.2} MiB → {:.2} MiB", original_size_mb, zip_size_mb));
+ } else {
+ pb.finish_with_message(format!("Compression complete: {:.2} MiB", zip_size_mb));
+ }
+ }
+
+ Ok(temp_file)
+ }
+
+ pub async fn upload_temp_file(&self, file_path: &Path) -> Result<String> {
+ let url = format!("{}/api/v1/resources/temp_upload", self.client.base_url);
+ let file_name = file_path
+ .file_name()
+ .and_then(|n| n.to_str())
+ .unwrap_or("temp_upload.zip");
+
+ let file_content = tokio::fs::read(file_path).await?;
+
+ let part = reqwest::multipart::Part::bytes(file_content).file_name(file_name.to_string());
+
+ let part = part
+ .mime_str("application/octet-stream")
+ .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;
+
+ let mut form = reqwest::multipart::Form::new().part("file", part);
+ if let Some(upload_mode) = &self.upload_mode {
+ form = form.text("upload_mode", upload_mode.clone());
+ }
+
+ let mut headers = self.client.build_headers();
+ headers.remove(reqwest::header::CONTENT_TYPE);
+
+ let upload_timeout = TimeoutConfig::for_upload().calculate(file_path)?;
+ let long_timeout_client = self.client.create_client_with_connect_timeout(
+ std::time::Duration::from_secs(30),
+ upload_timeout,
+ )?;
+
+ let response = long_timeout_client
+ .post(&url)
+ .headers(headers)
+ .multipart(form)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("File upload failed: {}", e)))?;
+
+ let result: Value = self.client.handle_response(response).await?;
+ result
+ .get("temp_file_id")
+ .and_then(|v| v.as_str())
+ .map(|s| s.to_string())
+ .ok_or_else(|| Error::Parse("Missing temp_file_id in response".to_string()))
+ }
+
+ pub async fn upload_temp_file_with_progress(
+ &self,
+ file_path: &Path,
+ verbose: bool,
+ ) -> Result<String> {
+ use indicatif::ProgressBar;
+
+ let url = format!("{}/api/v1/resources/temp_upload", self.client.base_url);
+ let file_name = file_path
+ .file_name()
+ .and_then(|n| n.to_str())
+ .unwrap_or("temp_upload.zip");
+
+ let file_content = tokio::fs::read(file_path).await?;
+ let file_size = file_content.len() as u64;
+
+ if verbose {
+ eprintln!("Uploading: {} ({:.2} MB)", file_name, file_size as f64 / 1024.0 / 1024.0);
+ }
+
+ let pb = ProgressBar::new_spinner();
+ pb.set_message(format!("Uploading {} ({:.2} MB)...", file_name, file_size as f64 / 1024.0 / 1024.0));
+ pb.enable_steady_tick(std::time::Duration::from_millis(100));
+
+ let part = reqwest::multipart::Part::bytes(file_content)
+ .file_name(file_name.to_string());
+
+ let part = part
+ .mime_str("application/octet-stream")
+ .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;
+
+ let mut form = reqwest::multipart::Form::new().part("file", part);
+ if let Some(upload_mode) = &self.upload_mode {
+ form = form.text("upload_mode", upload_mode.clone());
+ }
+
+ let mut headers = self.client.build_headers();
+ headers.remove(reqwest::header::CONTENT_TYPE);
+
+ let upload_timeout = TimeoutConfig::for_upload().calculate(file_path)?;
+ let long_timeout_client = self.client.create_client_with_connect_timeout(
+ std::time::Duration::from_secs(30),
+ upload_timeout,
+ )?;
+
+ let response = long_timeout_client
+ .post(&url)
+ .headers(headers)
+ .multipart(form)
+ .send()
+ .await
+ .map_err(|e| Error::Network(format!("File upload failed: {}", e)))?;
+
+ pb.finish_with_message("Upload complete");
+
+ let result: Value = self.client.handle_response(response).await?;
+ result
+ .get("temp_file_id")
+ .and_then(|v| v.as_str())
+ .map(|s| s.to_string())
+ .ok_or_else(|| Error::Parse("Missing temp_file_id in response".to_string()))
+ }
+}
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 351e753d0..2680f68ec 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -1,69 +1,21 @@
-use reqwest::{Client as ReqwestClient, StatusCode};
use serde::de::DeserializeOwned;
use serde_json::Value;
use std::env;
-use std::fs::File;
use std::path::Path;
-use std::str::FromStr;
-use tempfile::{Builder, NamedTempFile};
-use zip::CompressionMethod;
-use zip::write::FileOptions;
-use indicatif::{ProgressBar, ProgressStyle};
+pub use crate::base_client::{BaseClient, FileUploader, TimeoutConfig};
use crate::error::{Error, Result};
-fn api_error_from_envelope(json: &Value, status: StatusCode) -> String {
- let error_code = json
- .get("error")
- .and_then(|e| e.get("code"))
- .and_then(|c| c.as_str());
- let error_msg = json
- .get("error")
- .and_then(|e| e.get("message"))
- .and_then(|m| m.as_str())
- .map(|s| s.to_string())
- .or_else(|| {
- json.get("detail")
- .and_then(|d| d.as_str())
- .map(|s| s.to_string())
- })
- .unwrap_or_else(|| format!("HTTP error {}", status));
-
- match error_code {
- Some(code) => format!("[{}] {}", code, error_msg),
- None => error_msg,
- }
-}
+// ============ HttpClient ============
/// High-level HTTP client for OpenViking API
#[derive(Clone)]
pub struct HttpClient {
- http: ReqwestClient,
- base_url: String,
- api_key: Option<String>,
- account: Option<String>,
- user: Option<String>,
- agent_id: Option<String>,
- extra_headers: Option<std::collections::HashMap<String, String>>,
+ base: BaseClient,
}
impl HttpClient {
- fn upload_mode(&self) -> Option<String> {
- match env::var("OPENVIKING_UPLOAD_MODE") {
- Ok(value) => {
- let normalized = value.trim().to_ascii_lowercase();
- if normalized == "shared" || normalized == "local" {
- Some(normalized)
- } else {
- None
- }
- }
- Err(_) => None,
- }
- }
-
- /// Create a new HTTP client
pub fn new(
base_url: impl Into<String>,
api_key: Option<String>,
@@ -73,315 +25,99 @@ impl HttpClient {
timeout_secs: f64,
extra_headers: Option<std::collections::HashMap<String, String>>,
) -> Self {
- let http = ReqwestClient::builder()
- .timeout(std::time::Duration::from_secs_f64(timeout_secs))
- .build()
- .expect("Failed to build HTTP client");
-
Self {
- http,
- base_url: base_url.into().trim_end_matches('/').to_string(),
- api_key,
- account,
- user,
- agent_id,
- extra_headers,
+ base: BaseClient::new(base_url, api_key, agent_id, account, user, timeout_secs, extra_headers),
}
}
pub fn user_id(&self) -> Option<&str> {
- self.user.as_deref()
+ self.base.user_id()
}
pub fn agent_id(&self) -> Option<&str> {
- self.agent_id.as_deref()
+ self.base.agent_id()
}
pub fn api_key(&self) -> Option<&str> {
- self.api_key.as_deref()
+ self.base.api_key()
}
- /// Zip a directory to a temporary file
- fn zip_directory(&self, dir_path: &Path) -> Result<NamedTempFile> {
- if !dir_path.is_dir() {
- return Err(Error::Network(format!(
- "Path {} is not a directory",
- dir_path.display()
- )));
- }
-
- let temp_file = Builder::new().suffix(".zip").tempfile()?;
- let file = File::create(temp_file.path())?;
- let mut zip = zip::ZipWriter::new(file);
- let options: FileOptions<'_, ()> =
- FileOptions::default().compression_method(CompressionMethod::Deflated);
-
- let walkdir = walkdir::WalkDir::new(dir_path);
- for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
- let path = entry.path();
- if path.is_file() {
- let name = path.strip_prefix(dir_path).unwrap_or(path);
- let name_str = name.to_str().ok_or_else(|| {
- Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
- })?;
- zip.start_file(name_str, options)?;
- let mut file = File::open(path)?;
- std::io::copy(&mut file, &mut zip)?;
- }
- }
-
- zip.finish()?;
- Ok(temp_file)
- }
-
- /// Upload a temporary file and return the temp_file_id
- async fn upload_temp_file(&self, file_path: &Path) -> Result<String> {
- let url = format!("{}/api/v1/resources/temp_upload", self.base_url);
- let file_name = file_path
- .file_name()
- .and_then(|n| n.to_str())
- .unwrap_or("temp_upload.zip");
-
- // Read file content
- let file_content = tokio::fs::read(file_path).await?;
-
- // Create multipart form
- let part = reqwest::multipart::Part::bytes(file_content).file_name(file_name.to_string());
-
- let part = part
- .mime_str("application/octet-stream")
- .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;
-
- let mut form = reqwest::multipart::Form::new().part("file", part);
- if let Some(upload_mode) = self.upload_mode() {
- form = form.text("upload_mode", upload_mode);
- }
-
- let mut headers = self.build_headers();
- // Remove Content-Type: application/json, let reqwest set multipart/form-data automatically
- headers.remove(reqwest::header::CONTENT_TYPE);
-
- // Use a separate HTTP client with a long timeout for large file uploads
- // - Connect timeout: 30 seconds (to fail fast if server is unreachable)
- // - Total request timeout: 30 minutes (to allow large file transfers)
- let long_timeout_client = reqwest::Client::builder()
- .connect_timeout(std::time::Duration::from_secs(30))
- .timeout(std::time::Duration::from_secs(1800))
- .build()
- .map_err(|e| Error::Network(format!("Failed to build long-timeout HTTP client: {}", e)))?;
-
- let response = long_timeout_client
- .post(&url)
- .headers(headers)
- .multipart(form)
- .send()
- .await
- .map_err(|e| Error::Network(format!("File upload failed: {}", e)))?;
-
- let result: Value = self.handle_response(response).await?;
- result
- .get("temp_file_id")
- .and_then(|v| v.as_str())
- .map(|s| s.to_string())
- .ok_or_else(|| Error::Parse("Missing temp_file_id in response".to_string()))
- }
-
- fn build_headers(&self) -> reqwest::header::HeaderMap {
- let mut headers = reqwest::header::HeaderMap::new();
- headers.insert(
- reqwest::header::CONTENT_TYPE,
- reqwest::header::HeaderValue::from_static("application/json"),
- );
- if let Some(api_key) = &self.api_key {
- if let Ok(value) = reqwest::header::HeaderValue::from_str(api_key) {
- headers.insert("X-API-Key", value);
- }
- }
- if let Some(agent_id) = &self.agent_id {
- if let Ok(value) = reqwest::header::HeaderValue::from_str(agent_id) {
- headers.insert("X-OpenViking-Agent", value);
- }
- }
- if let Some(account) = &self.account {
- if let Ok(value) = reqwest::header::HeaderValue::from_str(account) {
- headers.insert("X-OpenViking-Account", value);
- }
- }
- if let Some(user) = &self.user {
- if let Ok(value) = reqwest::header::HeaderValue::from_str(user) {
- headers.insert("X-OpenViking-User", value);
- }
- }
- if let Some(extra_headers) = &self.extra_headers {
- for (key, value) in extra_headers {
- if let Ok(header_name) = reqwest::header::HeaderName::from_str(key) {
- if let Ok(header_value) = reqwest::header::HeaderValue::from_str(value) {
- headers.insert(header_name, header_value);
- }
+ fn upload_mode(&self) -> Option<String> {
+ match env::var("OPENVIKING_UPLOAD_MODE") {
+ Ok(value) => {
+ let normalized = value.trim().to_ascii_lowercase();
+ if normalized == "shared" || normalized == "local" {
+ Some(normalized)
+ } else {
+ None
}
}
+ Err(_) => None,
}
- headers
}
- /// Make a GET request
+ // ============ HTTP Methods ============
+
pub async fn get<T: DeserializeOwned>(
&self,
path: &str,
params: &[(String, String)],
) -> Result<T> {
- let url = format!("{}{}", self.base_url, path);
- let response = self
- .http
- .get(&url)
- .headers(self.build_headers())
- .query(params)
- .send()
- .await
- .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
-
- self.handle_response(response).await
+ self.base.get(path, params).await
}
- /// Make a POST request
pub async fn post<B: serde::Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T> {
- let url = format!("{}{}", self.base_url, path);
- let response = self
- .http
- .post(&url)
- .headers(self.build_headers())
- .json(body)
- .send()
- .await
- .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
-
- self.handle_response(response).await
+ self.base.post(path, body).await
}
- /// Make a PUT request
pub async fn put<B: serde::Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T> {
- let url = format!("{}{}", self.base_url, path);
- let response = self
- .http
- .put(&url)
- .headers(self.build_headers())
- .json(body)
- .send()
- .await
- .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
-
- self.handle_response(response).await
+ self.base.put(path, body).await
}
- /// Make a DELETE request
pub async fn delete<T: DeserializeOwned>(
&self,
path: &str,
params: &[(String, String)],
) -> Result<T> {
- let url = format!("{}{}", self.base_url, path);
- let response = self
- .http
- .delete(&url)
- .headers(self.build_headers())
- .query(params)
- .send()
- .await
- .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
-
- self.handle_response(response).await
+ self.base.delete(path, params).await
}
- /// Make a DELETE request with a JSON body
pub async fn delete_with_body<B: serde::Serialize, T: DeserializeOwned>(
&self,
path: &str,
body: &B,
) -> Result<T> {
- let url = format!("{}{}", self.base_url, path);
- let response = self
- .http
- .delete(&url)
- .headers(self.build_headers())
- .json(body)
- .send()
- .await
- .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;
-
- self.handle_response(response).await
+ self.base.delete_with_body(path, body).await
}
- async fn handle_response<T: DeserializeOwned>(&self, response: reqwest::Response) -> Result<T> {
- let status = response.status();
-
- // Handle empty response (204 No Content, etc.)
- if status == StatusCode::NO_CONTENT || status == StatusCode::ACCEPTED {
- return serde_json::from_value(Value::Null)
- .map_err(|e| Error::Parse(format!("Failed to parse empty response: {}", e)));
- }
+ // ============ File Helper Methods ============
- // First get the raw bytes/text to enable debugging when JSON parsing fails
- let bytes = response
- .bytes()
- .await
- .map_err(|e| Error::Network(format!("Failed to read response body: {}", e)))?;
-
- // Try to parse as JSON
- let json: Value = match serde_json::from_slice(&bytes) {
- Ok(json) => json,
- Err(e) => {
- // If parsing fails, try to convert bytes to string for debugging
- let body_str = String::from_utf8_lossy(&bytes);
- return Err(Error::Network(format!(
- "Failed to parse JSON response: {}\n\nRaw response body:\n{}",
- e, body_str
- )));
- }
- };
+ fn create_uploader(&self) -> FileUploader {
+ FileUploader::new(&self.base).with_upload_mode(self.upload_mode())
+ }
- // Handle HTTP errors
- if !status.is_success() {
- return Err(Error::Api(api_error_from_envelope(&json, status)));
- }
+ fn zip_directory(&self, dir_path: &Path) -> Result<tempfile::NamedTempFile> {
+ self.create_uploader().zip_directory(dir_path)
+ }
- // Handle API errors (status == success but body has error)
- if let Some(error) = json.get("error") {
- if !error.is_null() {
- let code = error
- .get("code")
- .and_then(|c| c.as_str())
- .unwrap_or("UNKNOWN");
- let message = error
- .get("message")
- .and_then(|m| m.as_str())
- .unwrap_or("Unknown error");
- return Err(Error::Api(format!("[{}] {}", code, message)));
- }
- }
+ fn zip_directory_with_progress(&self, dir_path: &Path, verbose: bool) -> Result<tempfile::NamedTempFile> {
+ self.create_uploader().zip_directory_with_progress(dir_path, verbose)
+ }
- // Extract result from wrapped response or use the whole response
- let result = if let Some(result) = json.get("result") {
- result.clone()
- } else {
- json.clone()
- };
+ async fn upload_temp_file(&self, file_path: &Path) -> Result<String> {
+ self.create_uploader().upload_temp_file(file_path).await
+ }
- serde_json::from_value(result)
- .map_err(|e| {
- // If final deserialization fails, include the JSON we were trying to parse
- Error::Parse(format!(
- "Failed to deserialize response: {}\n\nJSON that failed to parse:\n{}",
- e, json
- ))
- })
+ async fn upload_temp_file_with_progress(&self, file_path: &Path, verbose: bool) -> Result<String> {
+ self.create_uploader().upload_temp_file_with_progress(file_path, verbose).await
}
// ============ Content Methods ============
@@ -445,13 +181,14 @@ impl HttpClient {
/// Download file as raw bytes
pub async fn get_bytes(&self, uri: &str) -> Result<Vec<u8>> {
- let url = format!("{}/api/v1/content/download", self.base_url);
+ let url = format!("{}/api/v1/content/download", self.base.base_url);
let params = vec![("uri".to_string(), uri.to_string())];
let response = self
+ .base
.http
.get(&url)
- .headers(self.build_headers())
+ .headers(self.base.build_headers())
.query(&params)
.send()
.await
@@ -459,7 +196,6 @@ impl HttpClient {
let status = response.status();
if !status.is_success() {
- // Try to parse error message as JSON, but if that fails show raw response
let bytes = response
.bytes()
.await
@@ -658,6 +394,7 @@ impl HttpClient {
path: &str,
to: Option<String>,
parent: Option<String>,
+ parent_auto_create: Option<String>,
reason: &str,
instruction: &str,
wait: bool,
@@ -673,6 +410,14 @@ impl HttpClient {
) -> Result<serde_json::Value> {
let path_obj = Path::new(path);
+ // Determine effective parent and create_parent flag
+ let (effective_parent, create_parent) = match (parent, parent_auto_create) {
+ (Some(p), None) => (Some(p), false),
+ (None, Some(p)) => (Some(p), true),
+ (None, None) => (None, false),
+ (Some(_), Some(_)) => unreachable!("handled in cli"),
+ };
+
if path_obj.exists() {
if path_obj.is_dir() {
let source_name = path_obj
@@ -694,7 +439,8 @@ impl HttpClient {
"temp_file_id": temp_file_id,
"source_name": source_name,
"to": to,
- "parent": parent,
+ "parent": effective_parent,
+ "create_parent": create_parent,
"reason": reason,
"instruction": instruction,
"wait": wait,
@@ -707,7 +453,8 @@ impl HttpClient {
"watch_interval": watch_interval,
});
- self.post("/api/v1/resources", &body).await
+ let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(zip_file.path())?;
+ self.base.post_with_timeout("/api/v1/resources", &body, dynamic_timeout).await
} else if path_obj.is_file() {
let source_name = path_obj
.file_name()
@@ -723,7 +470,8 @@ impl HttpClient {
"temp_file_id": temp_file_id,
"source_name": source_name,
"to": to,
- "parent": parent,
+ "parent": effective_parent,
+ "create_parent": create_parent,
"reason": reason,
"instruction": instruction,
"wait": wait,
@@ -736,12 +484,14 @@ impl HttpClient {
"watch_interval": watch_interval,
});
- self.post("/api/v1/resources", &body).await
+ let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(path_obj)?;
+ self.base.post_with_timeout("/api/v1/resources", &body, dynamic_timeout).await
} else {
let body = serde_json::json!({
"path": path,
"to": to,
- "parent": parent,
+ "parent": effective_parent,
+ "create_parent": create_parent,
"reason": reason,
"instruction": instruction,
"wait": wait,
@@ -760,7 +510,8 @@ impl HttpClient {
let body = serde_json::json!({
"path": path,
"to": to,
- "parent": parent,
+ "parent": effective_parent,
+ "create_parent": create_parent,
"reason": reason,
"instruction": instruction,
"wait": wait,
@@ -777,164 +528,6 @@ impl HttpClient {
}
}
- /// Zip a directory to a temporary file with progress display
- fn zip_directory_with_progress(&self, dir_path: &Path, verbose: bool) -> Result<NamedTempFile> {
- if !dir_path.is_dir() {
- return Err(Error::Network(format!(
- "Path {} is not a directory",
- dir_path.display()
- )));
- }
-
- let temp_file = Builder::new().suffix(".zip").tempfile()?;
- let file = File::create(temp_file.path())?;
- let mut zip = zip::ZipWriter::new(file);
- let options: FileOptions<'_, ()> =
- FileOptions::default().compression_method(CompressionMethod::Deflated);
-
- // First, calculate total size and file count
- let mut total_size = 0u64;
- let mut total_files = 0u64;
- let walkdir = walkdir::WalkDir::new(dir_path);
- for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
- let path = entry.path();
- if path.is_file() {
- if let Ok(meta) = std::fs::metadata(path) {
- total_size += meta.len();
- total_files += 1;
- }
- }
- }
-
- // Now create progress bar and zip
- let pb = if total_size > 0 {
- let pb = ProgressBar::new(total_size);
- pb.set_style(
- ProgressStyle::default_bar()
- .template("{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {bytes}/{total_bytes} ({eta}) {msg}")
- .unwrap_or_else(|_| ProgressStyle::default_bar())
- .progress_chars("#>-"),
- );
- pb.set_message(format!("Compressing {} files", total_files));
- Some(pb)
- } else {
- let pb = ProgressBar::new_spinner();
- pb.set_message("Compressing files...");
- Some(pb)
- };
-
- let walkdir = walkdir::WalkDir::new(dir_path);
- for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
- let path = entry.path();
- if path.is_file() {
- let name = path.strip_prefix(dir_path).unwrap_or(path);
- let name_str = name.to_str().ok_or_else(|| {
- Error::InvalidPath(format!("Non-UTF-8 path: {}", name.to_string_lossy()))
- })?;
- if verbose {
- eprintln!(" Adding: {}", name_str);
- }
- zip.start_file(name_str, options)?;
- let mut file = File::open(path)?;
- let file_size = std::io::copy(&mut file, &mut zip)?;
-
- if let Some(pb) = &pb {
- if pb.length().is_some() {
- pb.inc(file_size);
- }
- }
- }
- }
-
- zip.finish()?;
-
- let zip_size = std::fs::metadata(temp_file.path())?.len();
- let zip_size_mb = zip_size as f64 / 1024.0 / 1024.0;
- let original_size_mb = if total_size > 0 {
- total_size as f64 / 1024.0 / 1024.0
- } else {
- 0.0
- };
-
- if let Some(pb) = pb {
- if total_size > 0 {
- pb.finish_with_message(format!("Compression complete: {:.2} MiB → {:.2} MiB", original_size_mb, zip_size_mb));
- } else {
- pb.finish_with_message(format!("Compression complete: {:.2} MiB", zip_size_mb));
- }
- }
-
- Ok(temp_file)
- }
-
- /// Upload a temporary file with progress display
- async fn upload_temp_file_with_progress(
- &self,
- file_path: &Path,
- verbose: bool,
- ) -> Result<String> {
- use indicatif::ProgressBar;
-
- let url = format!("{}/api/v1/resources/temp_upload", self.base_url);
- let file_name = file_path
- .file_name()
- .and_then(|n| n.to_str())
- .unwrap_or("temp_upload.zip");
-
- // Read file content
- let file_content = tokio::fs::read(file_path).await?;
- let file_size = file_content.len() as u64;
-
- if verbose {
- eprintln!("Uploading: {} ({:.2} MB)", file_name, file_size as f64 / 1024.0 / 1024.0);
- }
-
- // Create progress bar (spinner style)
- let pb = ProgressBar::new_spinner();
- pb.set_message(format!("Uploading {} ({:.2} MB)...", file_name, file_size as f64 / 1024.0 / 1024.0));
- pb.enable_steady_tick(std::time::Duration::from_millis(100));
-
- // Create multipart form
- let part = reqwest::multipart::Part::bytes(file_content)
- .file_name(file_name.to_string());
-
- let part = part
- .mime_str("application/octet-stream")
- .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;
-
- let mut form = reqwest::multipart::Form::new().part("file", part);
- if let Some(upload_mode) = self.upload_mode() {
- form = form.text("upload_mode", upload_mode);
- }
-
- let mut headers = self.build_headers();
- headers.remove(reqwest::header::CONTENT_TYPE);
-
- // Use a separate HTTP client with a long timeout for large file uploads
- let long_timeout_client = reqwest::Client::builder()
- .connect_timeout(std::time::Duration::from_secs(30))
- .timeout(std::time::Duration::from_secs(1800))
- .build()
- .map_err(|e| Error::Network(format!("Failed to build long-timeout HTTP client: {}", e)))?;
-
- let response = long_timeout_client
- .post(&url)
- .headers(headers)
- .multipart(form)
- .send()
- .await
- .map_err(|e| Error::Network(format!("File upload failed: {}", e)))?;
-
- pb.finish_with_message("Upload complete");
-
- let result: Value = self.handle_response(response).await?;
- result
- .get("temp_file_id")
- .and_then(|v| v.as_str())
- .map(|s| s.to_string())
- .ok_or_else(|| Error::Parse("Missing temp_file_id in response".to_string()))
- }
-
pub async fn add_skill(
&self,
data: &str,
@@ -953,7 +546,8 @@ impl HttpClient {
"wait": wait,
"timeout": timeout,
});
- self.post("/api/v1/skills", &body).await
+ let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(zip_file.path())?;
+ self.base.post_with_timeout("/api/v1/skills", &body, dynamic_timeout).await
} else if path_obj.is_file() {
let temp_file_id = self.upload_temp_file(path_obj).await?;
@@ -962,7 +556,8 @@ impl HttpClient {
"wait": wait,
"timeout": timeout,
});
- self.post("/api/v1/skills", &body).await
+ let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(path_obj)?;
+ self.base.post_with_timeout("/api/v1/skills", &body, dynamic_timeout).await
} else {
let body = serde_json::json!({
"data": data,
@@ -1017,11 +612,12 @@ impl HttpClient {
"uri": uri,
});
- let url = format!("{}/api/v1/pack/export", self.base_url);
+ let url = format!("{}/api/v1/pack/export", self.base.base_url);
let response = self
+ .base
.http
.post(&url)
- .headers(self.build_headers())
+ .headers(self.base.build_headers())
.json(&body)
.send()
.await
@@ -1029,7 +625,6 @@ impl HttpClient {
let status = response.status();
if !status.is_success() {
- // Try to parse error message as JSON, but if that fails show raw response
let bytes = response
.bytes()
.await
@@ -1056,13 +651,11 @@ impl HttpClient {
return Err(Error::Api(error_msg));
}
- // Download the file content
let bytes = response
.bytes()
.await
.map_err(|e| Error::Network(format!("Failed to read response bytes: {}", e)))?;
- // Determine target path
let to_path = Path::new(to);
let final_path = if to_path.is_dir() {
let base_name = uri
@@ -1077,12 +670,10 @@ impl HttpClient {
to_path.to_path_buf()
};
- // Ensure parent directory exists
if let Some(parent) = final_path.parent() {
std::fs::create_dir_all(parent)?;
}
- // Write file
std::fs::write(&final_path, bytes)?;
Ok(final_path.to_string_lossy().to_string())
@@ -1328,58 +919,34 @@ impl HttpClient {
#[cfg(test)]
mod tests {
- use super::{HttpClient, api_error_from_envelope};
+ use super::{BaseClient, HttpClient, TimeoutConfig};
+ use crate::base_client::api_error_from_envelope;
use reqwest::StatusCode;
use serde_json::json;
use std::collections::HashMap;
#[test]
- fn build_headers_includes_tenant_identity_headers() {
- let client = HttpClient::new(
- "http://localhost:1933",
- Some("test-key".to_string()),
- Some("assistant-1".to_string()),
- Some("acme".to_string()),
- Some("alice".to_string()),
- 5.0,
- None,
- );
+ fn timeout_config_calculation() {
+ let config = TimeoutConfig::new(60, 2.0);
- let headers = client.build_headers();
+ let temp_file = tempfile::NamedTempFile::new().unwrap();
+ std::fs::write(temp_file.path(), vec![0u8; 1024 * 1024]).unwrap();
- assert_eq!(
- headers
- .get("X-API-Key")
- .and_then(|value| value.to_str().ok()),
- Some("test-key")
- );
- assert_eq!(
- headers
- .get("X-OpenViking-Agent")
- .and_then(|value| value.to_str().ok()),
- Some("assistant-1")
- );
- assert_eq!(
- headers
- .get("X-OpenViking-Account")
- .and_then(|value| value.to_str().ok()),
- Some("acme")
- );
- assert_eq!(
- headers
- .get("X-OpenViking-User")
- .and_then(|value| value.to_str().ok()),
- Some("alice")
- );
+ let timeout = config.calculate(temp_file.path()).unwrap();
+ assert_eq!(timeout, std::time::Duration::from_secs(60));
+
+ std::fs::write(temp_file.path(), vec![0u8; 40 * 1024 * 1024]).unwrap();
+
+ let timeout = config.calculate(temp_file.path()).unwrap();
+ assert_eq!(timeout, std::time::Duration::from_secs(80));
}
#[test]
- fn build_headers_includes_extra_headers() {
+ fn build_headers_includes_extra_headers_for_base_client() {
let mut extra_headers = HashMap::new();
extra_headers.insert("X-Custom-Header".to_string(), "custom-value".to_string());
- extra_headers.insert("Authorization".to_string(), "Bearer token".to_string());
- let client = HttpClient::new(
+ let client = BaseClient::new(
"http://localhost:1933",
Some("test-key".to_string()),
Some("assistant-1".to_string()),
@@ -1392,12 +959,12 @@ mod tests {
let headers = client.build_headers();
assert_eq!(
- headers.get("X-Custom-Header").and_then(|value| value.to_str().ok()),
- Some("custom-value")
+ headers.get("X-API-Key").and_then(|value| value.to_str().ok()),
+ Some("test-key")
);
assert_eq!(
- headers.get("Authorization").and_then(|value| value.to_str().ok()),
- Some("Bearer token")
+ headers.get("X-Custom-Header").and_then(|value| value.to_str().ok()),
+ Some("custom-value")
);
}
@@ -1440,20 +1007,4 @@ mod tests {
"[PROCESSING_ERROR] Parse error: boom"
);
}
-
- #[test]
- fn successful_result_status_failed_stays_domain_status() {
- let envelope = json!({
- "status": "ok",
- "result": {
- "status": "failed",
- "task_id": "task-1",
- "error": "boom"
- }
- });
- let result = envelope.get("result").unwrap();
-
- assert_eq!(result["status"], "failed");
- assert_eq!(result["task_id"], "task-1");
- }
}
diff --git a/crates/ov_cli/src/commands/resources.rs b/crates/ov_cli/src/commands/resources.rs
index 5b4859b70..8b5c41307 100644
--- a/crates/ov_cli/src/commands/resources.rs
+++ b/crates/ov_cli/src/commands/resources.rs
@@ -7,6 +7,7 @@ pub async fn add_resource(
path: &str,
to: Option<String>,
parent: Option<String>,
+ parent_auto_create: Option<String>,
reason: String,
instruction: String,
wait: bool,
@@ -27,6 +28,7 @@ pub async fn add_resource(
path,
to,
parent,
+ parent_auto_create,
&reason,
&instruction,
wait,
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index afada572a..7c595a74b 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -10,6 +10,7 @@ pub async fn handle_add_resource(
mut path: String,
to: Option<String>,
parent: Option<String>,
+ parent_auto_create: Option<String>,
reason: String,
instruction: String,
wait: bool,
@@ -56,9 +57,14 @@ pub async fn handle_add_resource(
path = unescaped_path;
}
- // Check that only one of --to or --parent is set
- if to.is_some() && parent.is_some() {
- eprintln!("Error: Cannot specify both --to and --parent at the same time.");
+ // Check that only one of --to, --parent, or --parent-auto-create is set
+ let mut exclusive_count = 0;
+ if to.is_some() { exclusive_count += 1; }
+ if parent.is_some() { exclusive_count += 1; }
+ if parent_auto_create.is_some() { exclusive_count += 1; }
+
+ if exclusive_count > 1 {
+ eprintln!("Error: Cannot specify more than one of --to, --parent, or --parent-auto-create at the same time.");
std::process::exit(1);
}
@@ -89,6 +95,7 @@ pub async fn handle_add_resource(
&path,
to,
parent,
+ parent_auto_create,
reason,
instruction,
wait,
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index f86763a7c..b780c414d 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -1,3 +1,4 @@
+mod base_client;
mod client;
mod commands;
mod config;
@@ -184,6 +185,9 @@ enum Commands {
/// Target parent URI (must already exist and be a directory) (cannot be used with --to)
#[arg(long)]
parent: Option<String>,
+ /// Target parent URI (create parent directory if it does not exist) (cannot be used with --to or --parent)
+ #[arg(short = 'p', long = "parent-auto-create")]
+ parent_auto_create: Option<String>,
/// Reason for import
#[arg(long, default_value = "")]
reason: String,
@@ -983,6 +987,7 @@ async fn main() {
path,
to,
parent,
+ parent_auto_create,
reason,
instruction,
wait,
@@ -998,6 +1003,7 @@ async fn main() {
path,
to,
parent,
+ parent_auto_create,
reason,
instruction,
wait,
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index 1ea151925..e980e319f 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -136,8 +136,9 @@ This endpoint is the core entry point for resource management, supporting adding
|-----------|------|----------|---------|-------------|
| path | string | No | - | Remote resource URL (HTTP/HTTPS/Git). Mutually exclusive with `temp_file_id` |
| temp_file_id | string | No | - | Temporary upload file ID. Mutually exclusive with `path` |
-| to | string | No | - | Target Viking URI (exact location). Mutually exclusive with `parent` |
-| parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` |
+| to | string | No | - | Target Viking URI (exact location). Mutually exclusive with `parent` and `parent_auto_create` |
+| parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` and `parent_auto_create` |
+| create_parent | bool | No | False | Automatically create parent directory if it does not exist (server-side flag) |
| reason | string | No | "" | Reason for adding the resource (for documentation and relevance improvement, experimental feature) |
| instruction | string | No | "" | Processing instructions for semantic extraction (experimental feature) |
| wait | bool | No | False | Whether to wait for semantic processing and vectorization to complete before returning |
@@ -152,7 +153,7 @@ This endpoint is the core entry point for resource management, supporting adding
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
**Additional Notes**:
-- `to` and `parent` cannot be specified together
+- `to`, `parent`, and `parent_auto_create` cannot be specified together
- `path` and `temp_file_id` cannot be specified together
- Raw HTTP calls for local files require first uploading via [temp_upload](#temp_upload) to obtain `temp_file_id`
- When `to` is specified and the target already exists, triggers incremental update
@@ -252,6 +253,17 @@ ov add-resource https://github.com/example/repo.git --to viking://resources/guid
# Cancel scheduled updates
ov add-resource https://github.com/example/repo.git --to viking://resources/guide.md --watch-interval 0
+
+# Add with parent directory (parent must exist)
+ov add-resource ./documents/guide.md --parent viking://resources/docs
+
+# Add with parent directory (auto-create parent if it doesn't exist)
+ov add-resource ./documents/guide.md -p viking://resources/docs/2026/05/07
+# Or using full flag
+ov add-resource ./documents/guide.md --parent-auto-create viking://resources/docs/2026/05/07
+
+# Using path variables with auto-create
+ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}
```
**Response Example**
diff --git a/docs/en/concepts/04-viking-uri.md b/docs/en/concepts/04-viking-uri.md
index 870b9d322..95af0eb96 100644
--- a/docs/en/concepts/04-viking-uri.md
+++ b/docs/en/concepts/04-viking-uri.md
@@ -108,6 +108,81 @@ viking://session/{session_id}/tools/ # Tool executions
viking://session/{session_id}/history/ # Archived history
```
+## Path Variables
+
+Viking URI supports path variables for dynamic path generation. This is especially useful for organizing time-series data like emails, logs, daily reports, etc.
+
+### Variable Syntax
+
+```
+{namespace:key}
+```
+
+- **namespace**: Variable provider namespace (e.g., `calendar`, `env`, `user`)
+- **key**: Variable name within the namespace
+
+### Calendar Variables
+
+The `calendar` namespace provides date-related variables:
+
+| Variable | Description | Example (2026-05-07) |
+|----------|-------------|----------------------|
+| `{calendar:today}` | Full date path | `2026/05/07` |
+| `{calendar:yesterday}` | Yesterday's date path | `2026/05/06` |
+| `{calendar:tomorrow}` | Tomorrow's date path | `2026/05/08` |
+| `{calendar:year}` | Year | `2026` |
+| `{calendar:month}` | Month with leading zero | `05` |
+| `{calendar:day}` | Day with leading zero | `07` |
+| `{calendar:ym}` | Year/month | `2026/05` |
+| `{calendar:quarter}` | Quarter (Q1-Q4) | `Q2` |
+| `{calendar:yq}` | Year/quarter | `2026/Q2` |
+| `{calendar:week}` | ISO week number with leading zero | `18` |
+| `{calendar:yw}` | Year/ISO week | `2026/w18` |
+
+### Usage Examples
+
+```python
+# Organize emails by date
+viking://resources/emails/{calendar:today}/inbox
+# Renders to: viking://resources/emails/2026/05/07/inbox
+
+# View yesterday's logs
+viking://resources/logs/{calendar:yesterday}/app.log
+# Renders to: viking://resources/logs/2026/05/06/app.log
+
+# Pre-upload tomorrow's tasks
+viking://resources/tasks/{calendar:tomorrow}/todo.md
+# Renders to: viking://resources/tasks/2026/05/08/todo.md
+
+# Monthly logs
+viking://resources/logs/{calendar:year}/{calendar:month}/app.log
+# Renders to: viking://resources/logs/2026/05/app.log
+
+# Daily snapshots
+viking://resources/snapshots/{calendar:today}/
+# Renders to: viking://resources/snapshots/2026/05/07/
+```
+
+### Resolution
+
+Path variables are resolved **server-side** at the time of API execution. The CLI/SDK passes the URI template as-is, and the server renders it to a concrete path based on the current context (time, authenticated user, etc.).
+
+### Use with CLI
+
+```bash
+# Add today's emails, --parent-auto-create can be shortened to -p
+ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}/inbox" ./emails/*.eml
+
+# Read yesterday's log
+ov read "viking://resources/logs/{calendar:yesterday}/app.log"
+
+# Prep tomorrow's tasks
+ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "Plan the day"
+
+# Upload monthly report, --parent-auto-create can be shortened to -p
+ov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdf
+```
+
## Directory Structure
```
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index 862df7199..b0348daaf 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -131,8 +131,9 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
|------|------|------|--------|------|
| path | string | 否 | - | 远程资源 URL(HTTP/HTTPS/Git)。与 `temp_file_id` 二选一 |
| temp_file_id | string | 否 | - | 临时上传文件 ID。与 `path` 二选一 |
-| to | string | 否 | - | 目标 Viking URI(精确位置)。与 `parent` 二选一 |
-| parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 二选一 |
+| to | string | 否 | - | 目标 Viking URI(精确位置)。与 `parent` 和 `parent_auto_create` 互斥 |
+| parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 和 `parent_auto_create` 互斥 |
+| create_parent | bool | 否 | False | 如果父目录不存在,自动创建父目录(服务端标志) |
| reason | string | 否 | "" | 添加资源的原因(用于文档化和相关性提升,实验特性) |
| instruction | string | 否 | "" | 语义提取的处理指令(实验特性) |
| wait | bool | 否 | False | 是否等待语义处理和向量化完成才返回 |
@@ -147,7 +148,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
**补充说明**:
-- `to` 和 `parent` 都可用于指定目标路径,但不能同时使用;指定 `to` 且目标已存在时,触发增量更新。
+- `to`、`parent` 和 `parent_auto_create` 都可用于指定目标路径,但不能同时使用;指定 `to` 且目标已存在时,触发增量更新。
- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
- `watch_interval` 仅在指定 `to` 时生效
- 本地目录输入会遵循 `.gitignore`(根目录和子目录,标准 Git 语义);`ignore_dirs`、`include`、`exclude` 会在此基础上进一步过滤。
@@ -245,6 +246,17 @@ ov add-resource https://github.com/example/repo.git --to viking://resources/my_r
# 取消定时更新
ov add-resource https://github.com/example/repo.git --to viking://resources/my_repo --watch-interval 0
+
+# 添加到指定父目录(父目录必须存在)
+ov add-resource ./documents/guide.md --parent viking://resources/docs
+
+# 添加到指定父目录(父目录不存在时自动创建)
+ov add-resource ./documents/guide.md -p viking://resources/docs/2026/05/07
+# 或使用完整参数名
+ov add-resource ./documents/guide.md --parent-auto-create viking://resources/docs/2026/05/07
+
+# 使用路径变量配合自动创建父目录
+ov add-resource ./documents/guide.md -p viking://resources/docs/{calendar:today}
```
#### 4. 响应示例
diff --git a/docs/zh/concepts/04-viking-uri.md b/docs/zh/concepts/04-viking-uri.md
index 4d29781f0..f445fe924 100644
--- a/docs/zh/concepts/04-viking-uri.md
+++ b/docs/zh/concepts/04-viking-uri.md
@@ -107,6 +107,81 @@ viking://session/{session_id}/tools/ # 工具执行
viking://session/{session_id}/history/ # 归档历史
```
+## 路径变量
+
+Viking URI 支持路径变量用于动态路径生成。这对于按时间序列组织数据(如邮件、日志、日报等)特别有用。
+
+### 变量语法
+
+```
+{namespace:key}
+```
+
+- **namespace**: 变量提供者命名空间(如 `calendar`、`env`、`user`)
+- **key**: 命名空间内的变量名
+
+### 日历变量
+
+`calendar` 命名空间提供日期相关变量:
+
+| 变量 | 说明 | 示例(2026-05-07) |
+|------|------|----------------------|
+| `{calendar:today}` | 完整日期路径 | `2026/05/07` |
+| `{calendar:yesterday}` | 昨天的日期路径 | `2026/05/06` |
+| `{calendar:tomorrow}` | 明天的日期路径 | `2026/05/08` |
+| `{calendar:year}` | 年份 | `2026` |
+| `{calendar:month}` | 月份(带前导零) | `05` |
+| `{calendar:day}` | 日期(带前导零) | `07` |
+| `{calendar:ym}` | 年/月 | `2026/05` |
+| `{calendar:quarter}` | 季度(Q1-Q4) | `Q2` |
+| `{calendar:yq}` | 年/季度 | `2026/Q2` |
+| `{calendar:week}` | ISO 周数(带前导零) | `18` |
+| `{calendar:yw}` | 年/ISO 周 | `2026/w18` |
+
+### 使用示例
+
+```python
+# 按日期组织邮件
+viking://resources/emails/{calendar:today}/inbox
+# 渲染为:viking://resources/emails/2026/05/07/inbox
+
+# 查看昨天的日志
+viking://resources/logs/{calendar:yesterday}/app.log
+# 渲染为:viking://resources/logs/2026/05/06/app.log
+
+# 预上传明天的任务
+viking://resources/tasks/{calendar:tomorrow}/todo.md
+# 渲染为:viking://resources/tasks/2026/05/08/todo.md
+
+# 月度日志
+viking://resources/logs/{calendar:year}/{calendar:month}/app.log
+# 渲染为:viking://resources/logs/2026/05/app.log
+
+# 每日快照
+viking://resources/snapshots/{calendar:today}/
+# 渲染为:viking://resources/snapshots/2026/05/07/
+```
+
+### 解析过程
+
+路径变量在 API 执行时**服务器端**进行解析。CLI/SDK 原样传递 URI 模板,服务器根据当前上下文(时间、认证用户等)渲染为具体路径。
+
+### CLI 使用
+
+```bash
+# 添加今天的邮件 --parent-auto-create 可以简写为 -p
+ov add-resource --parent-auto-create "viking://resources/emails/{calendar:today}/inbox" ./emails/*.eml
+
+# 读取昨天的日志
+ov read "viking://resources/logs/{calendar:yesterday}/app.log"
+
+# 准备明天的任务
+ov write --uri "viking://resources/tasks/{calendar:tomorrow}/todo.md" --content "规划一天"
+
+# 上传月度报告 --parent-auto-create 可以简写为 -p
+ov add-resource --parent-auto-create "viking://resources/reports/{calendar:ym}" ./report.pdf
+```
+
## 目录结构
```
diff --git a/openviking/core/path_variables.py b/openviking/core/path_variables.py
new file mode 100644
index 000000000..e9bca53b1
--- /dev/null
+++ b/openviking/core/path_variables.py
@@ -0,0 +1,240 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Path Variable System for OpenViking.
+
+Provides URI template resolution with support for variables like {calendar:today}.
+"""
+
+import re
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from typing import Dict, Optional, Set
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+# Regex to match variables: {namespace:key}
+VARIABLE_PATTERN = re.compile(r"\{([a-zA-Z0-9_]+):([a-zA-Z0-9_]+)\}")
+
+
+class VariableProvider(ABC):
+ """Base class for variable providers."""
+
+ @property
+ @abstractmethod
+ def namespace(self) -> str:
+ """Get the namespace for this provider."""
+ pass
+
+ @abstractmethod
+ def get_variables(self) -> Dict[str, str]:
+ """Get all variables provided by this provider."""
+ pass
+
+ def resolve(self, key: str) -> Optional[str]:
+ """Resolve a variable key to its value."""
+ variables = self.get_variables()
+ return variables.get(key)
+
+
+class CalendarVariableProvider(VariableProvider):
+ """
+ Calendar-based variable provider.
+
+ Variables:
+ {calendar:today} - Full date path: 2026/05/07
+ {calendar:yesterday} - Yesterday's date path: 2026/05/06
+ {calendar:tomorrow} - Tomorrow's date path: 2026/05/08
+ {calendar:year} - Year: 2026
+ {calendar:month} - Month with leading zero: 05
+ {calendar:day} - Day with leading zero: 07
+ {calendar:ym} - Year/month: 2026/05
+ {calendar:quarter} - Quarter: Q1, Q2, Q3, Q4
+ {calendar:yq} - Year/quarter: 2026/Q2
+ {calendar:week} - ISO week number with leading zero: 18
+ {calendar:yw} - Year/ISO week: 2026/w18
+ """
+
+ @property
+ def namespace(self) -> str:
+ return "calendar"
+
+ def __init__(self, dt: Optional[datetime] = None):
+ self.dt = dt
+
+ def get_variables(self) -> Dict[str, str]:
+ dt = self.dt or datetime.now()
+ year = dt.year
+ month = f"{dt.month:02d}"
+ day = f"{dt.day:02d}"
+
+ # Quarter calculation
+ quarter = f"Q{(dt.month - 1) // 3 + 1}"
+
+ # ISO week number
+ iso_year, iso_week, _ = dt.isocalendar()
+ week = f"{iso_week:02d}"
+
+ # Helper to format date path
+ def format_date_path(target_dt: datetime) -> str:
+ return f"{target_dt.year}/{target_dt.month:02d}/{target_dt.day:02d}"
+
+ yesterday = dt - timedelta(days=1)
+ tomorrow = dt + timedelta(days=1)
+
+ return {
+ "today": format_date_path(dt),
+ "yesterday": format_date_path(yesterday),
+ "tomorrow": format_date_path(tomorrow),
+ "year": str(year),
+ "month": month,
+ "day": day,
+ "ym": f"{year}/{month}",
+ "quarter": quarter,
+ "yq": f"{year}/{quarter}",
+ "week": week,
+ "yw": f"{iso_year}/w{week}",
+ }
+
+
+class PathVariableResolver:
+ """
+ Resolves URI templates with path variables.
+
+ Example:
+ resolver = PathVariableResolver()
+ resolved = resolver.resolve("viking://resources/emails/{calendar:today}/inbox")
+ # Returns: "viking://resources/emails/2026/05/07/inbox"
+ """
+
+ def __init__(self, extra_providers: Optional[Dict[str, VariableProvider]] = None):
+ self._providers: Dict[str, VariableProvider] = {}
+
+ # Register default providers
+ self._register_provider(CalendarVariableProvider())
+
+ # Register extra providers
+ if extra_providers:
+ for _, provider in extra_providers.items():
+ self._register_provider(provider)
+
+ def _register_provider(self, provider: VariableProvider) -> None:
+ """Register a variable provider."""
+ if provider.namespace in self._providers:
+ logger.warning(
+ f"Provider for namespace '{provider.namespace}' already exists, overwriting"
+ )
+ self._providers[provider.namespace] = provider
+
+ def has_variables(self, uri_template: str) -> bool:
+ """Check if a URI template contains variables."""
+ return VARIABLE_PATTERN.search(uri_template) is not None
+
+ def extract_variables(self, uri_template: str) -> Set[str]:
+ """Extract all variables from a URI template."""
+ variables = set()
+ matches = VARIABLE_PATTERN.findall(uri_template)
+ for namespace, key in matches:
+ variables.add(f"{namespace}:{key}")
+ return variables
+
+ def resolve(self, uri_template: str, dt: Optional[datetime] = None) -> str:
+ """
+ Resolve variables in a URI template.
+
+ Args:
+ uri_template: URI template with variables (e.g., "viking://resources/{calendar:ym}/logs")
+ dt: Optional datetime to use for calendar variables (default: now)
+
+ Returns:
+ Resolved URI with variables replaced
+
+ Raises:
+ ValueError: If a variable cannot be resolved
+ """
+ if not self.has_variables(uri_template):
+ return uri_template
+
+ # If datetime is provided, create a resolver with that specific time
+ if dt is not None:
+ # Create a temporary resolver with the custom datetime
+ calendar_provider = CalendarVariableProvider(dt)
+ temp_providers = dict(self._providers)
+ temp_providers["calendar"] = calendar_provider
+ temp_resolver = PathVariableResolver(temp_providers)
+ return temp_resolver.resolve(uri_template)
+
+ result = uri_template
+ unresolved = set()
+
+ # Find all variables
+ matches = list(VARIABLE_PATTERN.finditer(uri_template))
+
+ for match in matches:
+ full_match = match.group(0)
+ namespace = match.group(1)
+ key = match.group(2)
+
+ provider = self._providers.get(namespace)
+ if not provider:
+ unresolved.add(full_match)
+ continue
+
+ value = provider.resolve(key)
+ if value is None:
+ unresolved.add(full_match)
+ continue
+
+ # Replace the variable in the result
+ result = result.replace(full_match, value)
+
+ if unresolved:
+ raise ValueError(
+ f"Cannot resolve variables in URI: {', '.join(sorted(unresolved))}. "
+ f"URI template: {uri_template}"
+ )
+
+ return result
+
+
+# Global resolver instance
+_default_resolver: Optional[PathVariableResolver] = None
+
+
+def get_path_variable_resolver() -> PathVariableResolver:
+ """Get the global path variable resolver instance."""
+ global _default_resolver
+ if _default_resolver is None:
+ _default_resolver = PathVariableResolver()
+ return _default_resolver
+
+
+def resolve_path_variables(uri_template: str, dt: Optional[datetime] = None) -> str:
+ """
+ Convenience function to resolve path variables in a URI template.
+
+ Args:
+ uri_template: URI template with variables
+ dt: Optional datetime to use for calendar variables
+
+ Returns:
+ Resolved URI
+ """
+ resolver = get_path_variable_resolver()
+ return resolver.resolve(uri_template, dt=dt)
+
+
+def has_path_variables(uri_template: str) -> bool:
+ """
+ Convenience function to check if a URI template contains variables.
+
+ Args:
+ uri_template: URI template to check
+
+ Returns:
+ True if the template contains variables
+ """
+ resolver = get_path_variable_resolver()
+ return resolver.has_variables(uri_template)
diff --git a/openviking/parse/parsers/media/utils.py b/openviking/parse/parsers/media/utils.py
index 86fd066e2..c745df3df 100644
--- a/openviking/parse/parsers/media/utils.py
+++ b/openviking/parse/parsers/media/utils.py
@@ -3,10 +3,10 @@
"""Media-related utilities for OpenViking."""
import asyncio
-from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Any, Dict, Optional
+from openviking.core.path_variables import CalendarVariableProvider
from openviking.prompts import render_prompt
from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.utils.config import get_openviking_config
@@ -87,13 +87,13 @@ def get_media_base_uri(media_type: str) -> str:
media_type: Media type ("image", "audio", "video")
Returns:
- Base URI like "viking://resources/images/20250219"
+ Base URI like "viking://resources/images/2025/02/19"
"""
# Map singular media types to plural directory names
media_dir_map = {"image": "images", "audio": "audio", "video": "video"}
media_dir = media_dir_map.get(media_type, media_type)
- # Get current date in YYYYMMDD format
- date_str = datetime.now().strftime("%Y%m%d")
+ # Use CalendarVariableProvider to get today's date in YYYY/MM/DD format
+ date_str = CalendarVariableProvider().get_variables()["today"]
return f"viking://resources/{media_dir}/{date_str}"
diff --git a/openviking/parse/tree_builder.py b/openviking/parse/tree_builder.py
index 96e4b666c..15a992be2 100644
--- a/openviking/parse/tree_builder.py
+++ b/openviking/parse/tree_builder.py
@@ -113,13 +113,15 @@ class TreeBuilder:
parent_uri: Optional[str] = None,
source_path: Optional[str] = None,
source_format: Optional[str] = None,
+ create_parent: bool = False,
) -> "BuildingTree":
"""
Finalize processing by moving from temp to AGFS.
Args:
to_uri: Exact target URI (must not exist)
- parent_uri: Target parent URI (must exist)
+ parent_uri: Target parent URI (must exist unless create_parent is True)
+ create_parent: Whether to automatically create parent directory if it doesn't exist
"""
viking_fs = get_viking_fs()
@@ -170,9 +172,27 @@ class TreeBuilder:
else:
effective_parent_uri = parent_uri or to_uri if use_to_as_parent else parent_uri
if effective_parent_uri:
- # Parent URI must exist and be a directory
+ # Parent URI must exist and be a directory, or create it if requested
try:
+ # First check if parent exists
+ parent_exists = await viking_fs.exists(effective_parent_uri, ctx=ctx)
+ if not parent_exists:
+ if create_parent:
+ # Automatically create parent directory
+ logger.info(
+ f"[TreeBuilder] Parent URI does not exist, creating: {effective_parent_uri}"
+ )
+ await viking_fs.mkdir(effective_parent_uri, exist_ok=True, ctx=ctx)
+ else:
+ raise FileNotFoundError(
+ f"Parent URI does not exist: {effective_parent_uri}. "
+ f"Use --parent-auto-create/-p to automatically create it."
+ )
+ # Now get stat result
stat_result = await viking_fs.stat(effective_parent_uri, ctx=ctx)
+ except FileNotFoundError:
+ # Re-raise without wrapping
+ raise
except Exception as e:
raise FileNotFoundError(
f"Parent URI does not exist: {effective_parent_uri}"
diff --git a/openviking/server/routers/content.py b/openviking/server/routers/content.py
index 5bc35a5ce..b3ac2f9f9 100644
--- a/openviking/server/routers/content.py
+++ b/openviking/server/routers/content.py
@@ -9,6 +9,7 @@ from fastapi import APIRouter, Body, Depends, Query
from fastapi.responses import Response as FastAPIResponse
from pydantic import BaseModel, ConfigDict
+from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_viking_uri
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.server.auth import get_request_context, require_role
@@ -55,6 +56,7 @@ async def read(
):
"""Read file content (L2)."""
service = get_service()
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.read(uri, ctx=_ctx, offset=offset, limit=limit)
except AGFSNotFoundError:
@@ -89,6 +91,7 @@ async def abstract(
):
"""Read L0 abstract."""
service = get_service()
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.abstract(uri, ctx=_ctx)
except AGFSNotFoundError:
@@ -109,6 +112,7 @@ async def overview(
):
"""Read L1 overview."""
service = get_service()
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.overview(uri, ctx=_ctx)
except AGFSNotFoundError:
@@ -129,6 +133,7 @@ async def download(
):
"""Download file as raw bytes (for images, binaries, etc.)."""
service = get_service()
+ uri = resolve_path_variables(uri)
try:
content = await service.fs.read_file_bytes(uri, ctx=_ctx)
except AGFSNotFoundError:
@@ -163,11 +168,12 @@ async def write(
):
"""Write text content to a file (replace, append, or create) and refresh semantics/vectors."""
service = get_service()
+ uri = resolve_path_variables(request.uri)
execution = await run_operation(
operation="content.write",
telemetry=request.telemetry,
fn=lambda: service.fs.write(
- uri=request.uri,
+ uri=uri,
content=request.content,
ctx=_ctx,
mode=request.mode,
@@ -191,7 +197,8 @@ async def reindex(
from openviking.service.task_tracker import get_task_tracker
from openviking.storage.viking_fs import get_viking_fs
- uri = validate_viking_uri(body.uri)
+ uri = resolve_path_variables(body.uri)
+ uri = validate_viking_uri(uri)
viking_fs = get_viking_fs()
if not await viking_fs.exists(uri, ctx=ctx):
diff --git a/openviking/server/routers/debug.py b/openviking/server/routers/debug.py
index 266f36efd..d406576cc 100644
--- a/openviking/server/routers/debug.py
+++ b/openviking/server/routers/debug.py
@@ -12,6 +12,7 @@ from typing import Optional
from fastapi import APIRouter, Depends, Query
+from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
@@ -50,6 +51,8 @@ async def debug_vector_scroll(
filter_expr = None
if uri:
+ # Resolve path variables before using URI
+ uri = resolve_path_variables(uri)
filter_expr = {"op": "must", "field": "uri", "conds": [uri]}
records, next_cursor = await proxy.scroll(filter=filter_expr, limit=limit, cursor=cursor)
@@ -86,6 +89,8 @@ async def debug_vector_count(
)
if uri:
+ # Resolve path variables before using URI
+ uri = resolve_path_variables(uri)
uri_filter = {"op": "must", "field": "uri", "conds": [uri]}
if filter_expr:
# For combining filters, we should use And from expr, but for simplicity, let's use RawDSL for now
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 5ffc21507..13530ce5f 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -7,6 +7,7 @@ from typing import Optional
from fastapi import APIRouter, Depends, Query
from pydantic import BaseModel
+from openviking.core.path_variables import resolve_path_variables
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
@@ -33,6 +34,8 @@ async def ls(
"""List directory contents."""
service = get_service()
actual_node_limit = limit if limit is not None else node_limit
+ # Resolve path variables
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.ls(
uri,
@@ -69,6 +72,8 @@ async def tree(
"""Get directory tree."""
service = get_service()
actual_node_limit = limit if limit is not None else node_limit
+ # Resolve path variables
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.tree(
uri,
@@ -97,6 +102,8 @@ async def stat(
):
"""Get resource status."""
service = get_service()
+ # Resolve path variables
+ uri = resolve_path_variables(uri)
try:
result = await service.fs.stat(uri, ctx=_ctx)
return Response(status="ok", result=result)
@@ -129,15 +136,17 @@ async def mkdir(
):
"""Create directory."""
service = get_service()
+ # Resolve path variables
+ uri = resolve_path_variables(request.uri)
try:
- await service.fs.mkdir(request.uri, ctx=_ctx, description=request.description)
+ await service.fs.mkdir(uri, ctx=_ctx, description=request.description)
except AGFSClientError as e:
# Handle common AGFS errors
err_msg = str(e).lower()
if "not found" in err_msg or "no such file or directory" in err_msg:
- raise NotFoundError(request.uri, "file")
+ raise NotFoundError(uri, "file")
raise
- return Response(status="ok", result={"uri": request.uri})
+ return Response(status="ok", result={"uri": uri})
@router.delete("")
@@ -148,6 +157,8 @@ async def rm(
):
"""Remove resource."""
service = get_service()
+ # Resolve path variables
+ uri = resolve_path_variables(uri)
try:
await service.fs.rm(uri, ctx=_ctx, recursive=recursive)
except AGFSNotFoundError:
@@ -179,14 +190,17 @@ async def mv(
):
"""Move resource."""
service = get_service()
+ # Resolve path variables
+ from_uri = resolve_path_variables(request.from_uri)
+ to_uri = resolve_path_variables(request.to_uri)
try:
- await service.fs.mv(request.from_uri, request.to_uri, ctx=_ctx)
+ await service.fs.mv(from_uri, to_uri, ctx=_ctx)
except AGFSNotFoundError:
- raise NotFoundError(request.from_uri, "file")
+ raise NotFoundError(from_uri, "file")
except AGFSClientError as e:
# Fallback for older versions without typed exceptions
err_msg = str(e).lower()
if "not found" in err_msg or "no such file or directory" in err_msg:
- raise NotFoundError(request.from_uri, "file")
+ raise NotFoundError(from_uri, "file")
raise
- return Response(status="ok", result={"from": request.from_uri, "to": request.to_uri})
+ return Response(status="ok", result={"from": from_uri, "to": to_uri})
diff --git a/openviking/server/routers/maintenance.py b/openviking/server/routers/maintenance.py
index b9477c2e6..17592ca59 100644
--- a/openviking/server/routers/maintenance.py
+++ b/openviking/server/routers/maintenance.py
@@ -7,6 +7,7 @@ import asyncio
from fastapi import APIRouter, Body
from pydantic import BaseModel
+from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_viking_uri
from openviking.server.auth import require_role
from openviking.server.dependencies import get_service
@@ -48,7 +49,8 @@ async def reindex(
from openviking.service.task_tracker import get_task_tracker
from openviking.storage.viking_fs import get_viking_fs
- uri = validate_viking_uri(body.uri)
+ uri = resolve_path_variables(body.uri)
+ uri = validate_viking_uri(uri)
viking_fs = get_viking_fs()
# Validate URI exists
diff --git a/openviking/server/routers/pack.py b/openviking/server/routers/pack.py
index eb3ec2c72..88b26a995 100644
--- a/openviking/server/routers/pack.py
+++ b/openviking/server/routers/pack.py
@@ -10,6 +10,7 @@ from fastapi.responses import FileResponse
from pydantic import BaseModel, ConfigDict
from starlette.background import BackgroundTask
+from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context, require_auth_root_or_admin
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
@@ -53,16 +54,19 @@ async def export_ovpack(
"""Export context as .ovpack file and stream it to client."""
service = get_service()
+ # Resolve path variables
+ uri = resolve_path_variables(body.uri)
+
# Create temp file for export
temp_dir = tempfile.gettempdir()
temp_file = os.path.join(temp_dir, f"export_{os.urandom(16).hex()}.ovpack")
try:
# Export to temp file
- await service.pack.export_ovpack(body.uri, temp_file, ctx=ctx)
+ await service.pack.export_ovpack(uri, temp_file, ctx=ctx)
# Determine filename from URI
- base_name = body.uri.strip().rstrip("/").split("/")[-1]
+ base_name = uri.strip().rstrip("/").split("/")[-1]
if not base_name:
base_name = "export"
filename = f"{base_name}.ovpack"
@@ -97,10 +101,14 @@ async def import_ovpack(
service = get_service()
store = TempUploadStore.build(request.app.state.config)
resolved = await store.resolve_for_consume(body.temp_file_id, ctx)
+
+ # Resolve path variables
+ parent = resolve_path_variables(body.parent)
+
try:
result = await service.pack.import_ovpack(
resolved.local_path,
- body.parent,
+ parent,
ctx=ctx,
force=body.force,
vectorize=body.vectorize,
@@ -112,4 +120,5 @@ async def import_ovpack(
await store.mark_consumed(resolved, ctx)
finally:
await resolved.cleanup()
+
return Response(status="ok", result={"uri": result})
diff --git a/openviking/server/routers/relations.py b/openviking/server/routers/relations.py
index 4aa75506e..ce9b533f6 100644
--- a/openviking/server/routers/relations.py
+++ b/openviking/server/routers/relations.py
@@ -7,11 +7,20 @@ from typing import List, Union
from fastapi import APIRouter, Depends, Query
from pydantic import BaseModel
+from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.server.models import Response
+
+def _resolve_uri_or_uris(uri: Union[str, List[str]]) -> Union[str, List[str]]:
+ """Resolve path variables in a single URI or list of URIs."""
+ if isinstance(uri, list):
+ return [resolve_path_variables(u) for u in uri]
+ return resolve_path_variables(uri)
+
+
router = APIRouter(prefix="/api/v1/relations", tags=["relations"])
@@ -37,6 +46,7 @@ async def relations(
):
"""Get relations for a resource."""
service = get_service()
+ uri = resolve_path_variables(uri)
result = await service.relations.relations(uri, ctx=_ctx)
return Response(status="ok", result=result)
@@ -48,8 +58,10 @@ async def link(
):
"""Create link between resources."""
service = get_service()
- await service.relations.link(request.from_uri, request.to_uris, ctx=_ctx, reason=request.reason)
- return Response(status="ok", result={"from": request.from_uri, "to": request.to_uris})
+ from_uri = resolve_path_variables(request.from_uri)
+ to_uris = _resolve_uri_or_uris(request.to_uris)
+ await service.relations.link(from_uri, to_uris, ctx=_ctx, reason=request.reason)
+ return Response(status="ok", result={"from": from_uri, "to": to_uris})
@router.delete("/link")
@@ -59,5 +71,7 @@ async def unlink(
):
"""Remove link between resources."""
service = get_service()
- await service.relations.unlink(request.from_uri, request.to_uri, ctx=_ctx)
- return Response(status="ok", result={"from": request.from_uri, "to": request.to_uri})
+ from_uri = resolve_path_variables(request.from_uri)
+ to_uri = resolve_path_variables(request.to_uri)
+ await service.relations.unlink(from_uri, to_uri, ctx=_ctx)
+ return Response(status="ok", result={"from": from_uri, "to": to_uri})
diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.py
index b1c16882e..dca02760e 100644
--- a/openviking/server/routers/resources.py
+++ b/openviking/server/routers/resources.py
@@ -7,6 +7,7 @@ from typing import Any, Optional
from fastapi import APIRouter, Depends, File, Form, Request, UploadFile
from pydantic import BaseModel, ConfigDict, model_validator
+from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
@@ -34,6 +35,8 @@ class AddResourceRequest(BaseModel):
If not specified, an auto-generated URI will be used.
parent: Parent URI under which the resource will be stored.
Cannot be used together with 'to'.
+ create_parent: Whether to automatically create the parent directory if it doesn't exist.
+ Default is False.
reason: Reason for adding the resource. Used for documentation and monitoring.
instruction: Processing instruction for semantic extraction.
Provides hints for how the resource should be processed.
@@ -65,6 +68,7 @@ class AddResourceRequest(BaseModel):
temp_file_id: Optional[str] = None
to: Optional[str] = None
parent: Optional[str] = None
+ create_parent: bool = False
reason: str = ""
instruction: str = ""
wait: bool = False
@@ -174,10 +178,15 @@ async def add_resource(
"exclude": request.exclude,
"directly_upload_media": request.directly_upload_media,
"watch_interval": request.watch_interval,
+ "create_parent": request.create_parent,
}
if request.preserve_structure is not None:
kwargs["preserve_structure"] = request.preserve_structure
+ # Resolve path variables before passing to service
+ to = resolve_path_variables(request.to) if request.to else None
+ parent = resolve_path_variables(request.parent) if request.parent else None
+
store = TempUploadStore.build(http_request.app.state.config) if resolved else None
async def _add() -> dict[str, Any]:
@@ -185,8 +194,8 @@ async def add_resource(
result = await service.resources.add_resource(
path=path,
ctx=_ctx,
- to=request.to,
- parent=request.parent,
+ to=to,
+ parent=parent,
reason=request.reason,
instruction=request.instruction,
wait=request.wait,
diff --git a/openviking/server/routers/search.py b/openviking/server/routers/search.py
index 7cbbc01f4..d1128c110 100644
--- a/openviking/server/routers/search.py
+++ b/openviking/server/routers/search.py
@@ -8,6 +8,7 @@ from typing import Any, Dict, List, Literal, Optional, Union
from fastapi import APIRouter, Depends
from pydantic import BaseModel
+from openviking.core.path_variables import resolve_path_variables
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
@@ -58,6 +59,13 @@ def _resolve_search_filter(
raise InvalidArgumentError(str(exc)) from exc
+def _resolve_uri_or_uris(uri: Union[str, List[str]]) -> Union[str, List[str]]:
+ """Resolve path variables in a single URI or list of URIs."""
+ if isinstance(uri, list):
+ return [resolve_path_variables(u) for u in uri]
+ return resolve_path_variables(uri)
+
+
class FindRequest(BaseModel):
"""Request model for find."""
@@ -126,13 +134,14 @@ async def find(
request.until,
request.time_field,
)
+ resolved_target_uri = _resolve_uri_or_uris(request.target_uri)
execution = await run_operation(
operation="search.find",
telemetry=request.telemetry,
fn=lambda: service.search.find(
query=request.query,
ctx=_ctx,
- target_uri=request.target_uri,
+ target_uri=resolved_target_uri,
limit=actual_limit,
score_threshold=request.score_threshold,
filter=effective_filter,
@@ -163,6 +172,7 @@ async def search(
request.until,
request.time_field,
)
+ resolved_target_uri = _resolve_uri_or_uris(request.target_uri)
async def _search():
session = None
@@ -172,7 +182,7 @@ async def search(
return await service.search.search(
query=request.query,
ctx=_ctx,
- target_uri=request.target_uri,
+ target_uri=resolved_target_uri,
session=session,
limit=actual_limit,
score_threshold=request.score_threshold,
@@ -202,26 +212,30 @@ async def grep(
):
"""Content search with pattern."""
service = get_service()
+ resolved_uri = resolve_path_variables(request.uri)
+ resolved_exclude_uri = None
+ if request.exclude_uri:
+ resolved_exclude_uri = resolve_path_variables(request.exclude_uri)
try:
result = await service.fs.grep(
- request.uri,
+ resolved_uri,
request.pattern,
ctx=_ctx,
- exclude_uri=request.exclude_uri,
+ exclude_uri=resolved_exclude_uri,
case_insensitive=request.case_insensitive,
node_limit=request.node_limit,
level_limit=request.level_limit,
)
except AGFSNotFoundError:
- raise NotFoundError(request.uri, "file")
+ raise NotFoundError(resolved_uri, "file")
except AGFSClientError as e:
# Fallback for older versions without typed exceptions
err_msg = str(e).lower()
if "not found" in err_msg or "no such file or directory" in err_msg:
- raise NotFoundError(request.uri, "file")
+ raise NotFoundError(resolved_uri, "file")
raise
except Exception as exc:
- mapped = map_exception(exc, resource=request.uri, resource_type="file")
+ mapped = map_exception(exc, resource=resolved_uri, resource_type="file")
if mapped is not None:
raise mapped from exc
raise
@@ -235,17 +249,18 @@ async def glob(
):
"""File pattern matching."""
service = get_service()
+ resolved_uri = resolve_path_variables(request.uri)
try:
result = await service.fs.glob(
- request.pattern, ctx=_ctx, uri=request.uri, node_limit=request.node_limit
+ request.pattern, ctx=_ctx, uri=resolved_uri, node_limit=request.node_limit
)
except AGFSNotFoundError:
- raise NotFoundError(request.uri or request.pattern, "file")
+ raise NotFoundError(resolved_uri or request.pattern, "file")
except AGFSClientError as e:
# Fallback for older versions without typed exceptions
err_msg = str(e).lower()
if "not found" in err_msg or "no such file or directory" in err_msg:
- raise NotFoundError(request.uri or request.pattern, "file")
+ raise NotFoundError(resolved_uri or request.pattern, "file")
raise
except Exception as exc:
mapped = map_exception(exc, resource=request.uri, resource_type="file")
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index 65d1cc8d2..08e662d4b 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -8,6 +8,7 @@ from typing import Any, Dict, List, Literal, Optional
from fastapi import APIRouter, Body, Depends, Path, Query, Request
from pydantic import BaseModel, Field, model_validator
+from openviking.core.path_variables import resolve_path_variables
from openviking.message.part import TextPart, part_from_dict
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
@@ -294,7 +295,21 @@ async def add_message(
role_id = _ctx.resolve_role_id(request.role, request.role_id)
if request.parts is not None:
- parts = [part_from_dict(p) for p in request.parts]
+ # Resolve path variables in URIs within parts
+ resolved_parts = []
+ for p in request.parts:
+ part_copy = dict(p)
+ # Resolve uri in context parts
+ if part_copy.get("type") == "context" and "uri" in part_copy:
+ part_copy["uri"] = resolve_path_variables(part_copy["uri"])
+ # Resolve tool_uri and skill_uri in tool parts
+ if part_copy.get("type") == "tool":
+ if "tool_uri" in part_copy:
+ part_copy["tool_uri"] = resolve_path_variables(part_copy["tool_uri"])
+ if "skill_uri" in part_copy:
+ part_copy["skill_uri"] = resolve_path_variables(part_copy["skill_uri"])
+ resolved_parts.append(part_copy)
+ parts = [part_from_dict(p) for p in resolved_parts]
else:
parts = [TextPart(text=request.content or "")]
@@ -324,7 +339,19 @@ async def record_used(
service = get_service()
session = service.sessions.session(_ctx, session_id)
await session.load()
- session.used(contexts=request.contexts, skill=request.skill)
+
+ # Resolve path variables in contexts
+ resolved_contexts = None
+ if request.contexts is not None:
+ resolved_contexts = [resolve_path_variables(uri) for uri in request.contexts]
+
+ # Resolve path variables in skill URI if present
+ resolved_skill = request.skill
+ if resolved_skill is not None and "uri" in resolved_skill:
+ resolved_skill = dict(resolved_skill)
+ resolved_skill["uri"] = resolve_path_variables(resolved_skill["uri"])
+
+ session.used(contexts=resolved_contexts, skill=resolved_skill)
return Response(
status="ok",
result={
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 43d0a8274..0d4328591 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -10,6 +10,7 @@ import json
import time
from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_optional_viking_uri
from openviking.server.identity import RequestContext
from openviking.server.local_input_guard import (
@@ -173,6 +174,12 @@ class ResourceService:
telemetry.set("resource.flags.watch_enabled", watch_enabled)
try:
+ # Resolve path variables before validation
+ if to:
+ to = resolve_path_variables(to)
+ if parent:
+ parent = resolve_path_variables(parent)
+
to = validate_optional_viking_uri(
to,
field_name="to",
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 64de7b14c..3f4e63a50 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -1173,7 +1173,7 @@ class VikingFS:
raise mapped from exc
raise
# Fallback to default if .abstract.md doesn't exist
- return f"# {uri}\n\n[Directory abstract is not ready]"
+ return f"# {uri} [Directory abstract is not ready]"
if self._encryptor:
real_ctx = self._ctx_or_default(ctx)
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index dadafe6b7..a3d6d6ac2 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -212,6 +212,7 @@ class ResourceProcessor:
parent_uri=parent,
source_path=parse_result.source_path,
source_format=parse_result.source_format,
+ create_parent=kwargs.get("create_parent", False),
)
if context_tree and context_tree.root:
result["root_uri"] = context_tree.root.uri
diff --git a/tests/unit/test_path_variables.py b/tests/unit/test_path_variables.py
new file mode 100644
index 000000000..3248df28a
--- /dev/null
+++ b/tests/unit/test_path_variables.py
@@ -0,0 +1,356 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Tests for path variable resolution."""
+
+from datetime import datetime
+
+import pytest
+
+from openviking.core.path_variables import (
+ CalendarVariableProvider,
+ PathVariableResolver,
+ has_path_variables,
+ resolve_path_variables,
+)
+
+
+class TestCalendarVariableProvider:
+ """Tests for calendar variable provider."""
+
+ @pytest.fixture
+ def sample_datetime(self):
+ """Sample datetime for testing: 2026-05-07."""
+ return datetime(2026, 5, 7, 14, 30, 0)
+
+ def test_get_variables_returns_all_keys(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert "today" in variables
+ assert "yesterday" in variables
+ assert "tomorrow" in variables
+ assert "year" in variables
+ assert "month" in variables
+ assert "day" in variables
+ assert "ym" in variables
+ assert "quarter" in variables
+ assert "yq" in variables
+ assert "week" in variables
+ assert "yw" in variables
+
+ def test_today_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["today"] == "2026/05/07"
+
+ def test_yesterday_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["yesterday"] == "2026/05/06"
+
+ def test_tomorrow_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["tomorrow"] == "2026/05/08"
+
+ def test_yesterday_crosses_month_boundary(self):
+ # Test with 2026-05-01 (yesterday is in April)
+ dt = datetime(2026, 5, 1)
+ provider = CalendarVariableProvider(dt)
+ variables = provider.get_variables()
+
+ assert variables["yesterday"] == "2026/04/30"
+
+ def test_tomorrow_crosses_month_boundary(self):
+ # Test with 2026-05-31 (tomorrow is in June)
+ dt = datetime(2026, 5, 31)
+ provider = CalendarVariableProvider(dt)
+ variables = provider.get_variables()
+
+ assert variables["tomorrow"] == "2026/06/01"
+
+ def test_year_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["year"] == "2026"
+
+ def test_month_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["month"] == "05"
+
+ def test_day_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["day"] == "07"
+
+ def test_ym_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["ym"] == "2026/05"
+
+ def test_quarter_q2(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ assert variables["quarter"] == "Q2"
+ assert variables["yq"] == "2026/Q2"
+
+ @pytest.mark.parametrize(
+ "month, expected_quarter",
+ [
+ (1, "Q1"),
+ (3, "Q1"),
+ (4, "Q2"),
+ (6, "Q2"),
+ (7, "Q3"),
+ (9, "Q3"),
+ (10, "Q4"),
+ (12, "Q4"),
+ ],
+ )
+ def test_quarter_bounds(self, month, expected_quarter):
+ dt = datetime(2026, month, 15)
+ provider = CalendarVariableProvider(dt)
+ variables = provider.get_variables()
+
+ assert variables["quarter"] == expected_quarter
+
+ def test_week_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ # 2026-05-07 is in week 19 (ISO week numbering)
+ assert variables["week"] == "19"
+
+ def test_yw_variable(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+ variables = provider.get_variables()
+
+ # 2026-05-07 is in week 19
+ assert variables["yw"] == "2026/w19"
+
+ def test_resolve_individual_key(self, sample_datetime):
+ provider = CalendarVariableProvider(sample_datetime)
+
+ assert provider.resolve("year") == "2026"
+ assert provider.resolve("month") == "05"
+ assert provider.resolve("day") == "07"
+ assert provider.resolve("nonexistent") is None
+
+ def test_namespace_property(self):
+ provider = CalendarVariableProvider()
+ assert provider.namespace == "calendar"
+
+ def test_default_provider_uses_current_time_each_call(self):
+ """Test that default provider (no fixed dt) gets current time each call."""
+ # Create provider without fixed dt
+ provider = CalendarVariableProvider()
+
+ # Get variables multiple times - each call uses current time
+ variables1 = provider.get_variables()
+ variables2 = provider.get_variables()
+
+ # Should return same date (since we call within same second)
+ assert variables1["today"] == variables2["today"]
+
+ def test_fixed_dt_provider_does_not_update(self):
+ """Test that provider with explicit dt always uses that date."""
+ fixed_dt = datetime(2026, 5, 7, 14, 30, 0)
+ provider = CalendarVariableProvider(fixed_dt)
+
+ variables1 = provider.get_variables()
+ assert variables1["today"] == "2026/05/07"
+
+ variables2 = provider.get_variables()
+ assert variables2["today"] == "2026/05/07"
+
+
+class TestPathVariableResolver:
+ """Tests for path variable resolver."""
+
+ @pytest.fixture
+ def sample_datetime(self):
+ """Sample datetime for testing: 2026-05-07."""
+ return datetime(2026, 5, 7, 14, 30, 0)
+
+ @pytest.fixture
+ def resolver(self):
+ """Resolver with default providers."""
+ return PathVariableResolver()
+
+ def test_resolve_no_variables_returns_unchanged(self, resolver):
+ uri = "viking://resources/docs/api.md"
+ assert resolver.resolve(uri) == uri
+
+ def test_resolve_single_calendar_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/emails/{calendar:year}/inbox"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/inbox"
+
+ def test_resolve_multiple_calendar_variables(self, resolver, sample_datetime):
+ uri = "viking://resources/logs/{calendar:year}/{calendar:month}/app.log"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/logs/2026/05/app.log"
+
+ def test_resolve_today_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/emails/{calendar:today}/inbox"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/05/07/inbox"
+
+ def test_resolve_yesterday_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/emails/{calendar:yesterday}/inbox"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/05/06/inbox"
+
+ def test_resolve_tomorrow_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/emails/{calendar:tomorrow}/inbox"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/05/08/inbox"
+
+ def test_resolve_ym_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/reports/{calendar:ym}/summary.pdf"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/reports/2026/05/summary.pdf"
+
+ def test_resolve_quarter_variables(self, resolver, sample_datetime):
+ uri = "viking://resources/quarterly/{calendar:yq}/report.pdf"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/quarterly/2026/Q2/report.pdf"
+
+ def test_resolve_week_variables(self, resolver, sample_datetime):
+ uri = "viking://resources/weekly/{calendar:yw}/summary.pdf"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/weekly/2026/w19/summary.pdf"
+
+ def test_resolve_unknown_namespace_raises_error(self, resolver):
+ uri = "viking://resources/{env:production}/config"
+
+ with pytest.raises(ValueError, match="Cannot resolve variables"):
+ resolver.resolve(uri)
+
+ def test_resolve_unknown_key_raises_error(self, resolver):
+ uri = "viking://resources/{calendar:nonexistent}/path"
+
+ with pytest.raises(ValueError, match="Cannot resolve variables"):
+ resolver.resolve(uri)
+
+ def test_has_variables_true(self, resolver):
+ assert resolver.has_variables("viking://resources/{calendar:year}/docs") is True
+ assert resolver.has_variables("{calendar:today}") is True
+
+ def test_has_variables_false(self, resolver):
+ assert resolver.has_variables("viking://resources/docs") is False
+ assert resolver.has_variables("") is False
+ assert resolver.has_variables("no variables here") is False
+
+ def test_extract_variables(self, resolver):
+ uri = "viking://resources/{calendar:year}/{calendar:month}/{calendar:day}"
+ variables = resolver.extract_variables(uri)
+
+ assert variables == {"calendar:year", "calendar:month", "calendar:day"}
+
+ def test_extract_variables_none(self, resolver):
+ uri = "viking://resources/docs/api.md"
+ variables = resolver.extract_variables(uri)
+
+ assert variables == set()
+
+ def test_multiple_occurrences_same_variable(self, resolver, sample_datetime):
+ uri = "viking://resources/{calendar:year}/backup/{calendar:year}/data"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/2026/backup/2026/data"
+
+
+class TestConvenienceFunctions:
+ """Tests for convenience functions."""
+
+ @pytest.fixture
+ def sample_datetime(self):
+ """Sample datetime for testing: 2026-05-07."""
+ return datetime(2026, 5, 7, 14, 30, 0)
+
+ def test_resolve_path_variables(self, sample_datetime):
+ uri = "viking://resources/emails/{calendar:today}/inbox"
+ resolved = resolve_path_variables(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/05/07/inbox"
+
+ def test_has_path_variables_true(self):
+ assert has_path_variables("viking://resources/{calendar:year}/docs") is True
+
+ def test_has_path_variables_false(self):
+ assert has_path_variables("viking://resources/docs") is False
+
+
+class TestRealWorldExamples:
+ """Tests for real-world usage patterns."""
+
+ @pytest.fixture
+ def sample_datetime(self):
+ """Sample datetime for testing: 2026-05-07."""
+ return datetime(2026, 5, 7, 14, 30, 0)
+
+ @pytest.fixture
+ def resolver(self):
+ """Resolver with default providers."""
+ return PathVariableResolver()
+
+ def test_email_organization(self, resolver, sample_datetime):
+ uri = "viking://resources/emails/{calendar:today}/inbox"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/emails/2026/05/07/inbox"
+
+ def test_log_rotation(self, resolver, sample_datetime):
+ uri = "viking://resources/logs/{calendar:year}/{calendar:month}/{calendar:day}/app.log"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/logs/2026/05/07/app.log"
+
+ def test_daily_backups(self, resolver, sample_datetime):
+ uri = "viking://resources/backups/{calendar:ym}/backup_{calendar:today}.zip"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/backups/2026/05/backup_2026/05/07.zip"
+
+ def test_quarterly_reports(self, resolver, sample_datetime):
+ uri = "viking://resources/reports/{calendar:yq}/summary.pdf"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/reports/2026/Q2/summary.pdf"
+
+ def test_weekly_summaries(self, resolver, sample_datetime):
+ uri = "viking://resources/summaries/{calendar:yw}/week.pdf"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/summaries/2026/w19/week.pdf"
+
+ def test_yesterday_logs(self, resolver, sample_datetime):
+ uri = "viking://resources/logs/{calendar:yesterday}/app.log"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/logs/2026/05/06/app.log"
+
+ def test_tomorrow_tasks(self, resolver, sample_datetime):
+ uri = "viking://resources/tasks/{calendar:tomorrow}/todo.md"
+ resolved = resolver.resolve(uri, dt=sample_datetime)
+
+ assert resolved == "viking://resources/tasks/2026/05/08/todo.md"