Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.rsnew file mode 100644index 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.rsindex 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 clientpub 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 requestpub 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 requestpub 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 requestpub 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 bodypub 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 bytespub 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(¶ms).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 responselet 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 responselet bytes = response.bytes().await@@ -1056,13 +651,11 @@ impl HttpClient {return Err(Error::Api(error_msg));}- // Download the file contentlet bytes = response.bytes().await.map_err(|e| Error::Network(format!("Failed to read response bytes: {}", e)))?;- // Determine target pathlet 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 existsif let Some(parent) = final_path.parent() {std::fs::create_dir_all(parent)?;}- // Write filestd::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.rsindex 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.rsindex 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.rsindex 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.mdindex 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 updatesov 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.mdindex 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 executionsviking://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.mdindex 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.mdindex 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.pynew file mode 100644index 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.pyindex 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 datetimefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Dict, Optional+from openviking.core.path_variables import CalendarVariableProviderfrom openviking.prompts import render_promptfrom openviking.storage.viking_fs import get_viking_fsfrom 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 namesmedia_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.pyindex 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_uriif effective_parent_uri:- # Parent URI must exist and be a directory+ # Parent URI must exist and be a directory, or create it if requestedtry:+ # 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 resultstat_result = await viking_fs.stat(effective_parent_uri, ctx=ctx)+ except FileNotFoundError:+ # Re-raise without wrapping+ raiseexcept 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.pyindex 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, Queryfrom fastapi.responses import Response as FastAPIResponsefrom pydantic import BaseModel, ConfigDict+from openviking.core.path_variables import resolve_path_variablesfrom openviking.core.uri_validation import validate_viking_urifrom openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundErrorfrom 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_trackerfrom 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.pyindex 266f36efd..d406576cc 100644--- a/openviking/server/routers/debug.py+++ b/openviking/server/routers/debug.py@@ -12,6 +12,7 @@ from typing import Optionalfrom fastapi import APIRouter, Depends, Query+from openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_servicefrom openviking.server.identity import RequestContext@@ -50,6 +51,8 @@ async def debug_vector_scroll(filter_expr = Noneif 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 nowdiff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.pyindex 5ffc21507..13530ce5f 100644--- a/openviking/server/routers/filesystem.py+++ b/openviking/server/routers/filesystem.py@@ -7,6 +7,7 @@ from typing import Optionalfrom fastapi import APIRouter, Depends, Queryfrom pydantic import BaseModel+from openviking.core.path_variables import resolve_path_variablesfrom openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundErrorfrom openviking.server.auth import get_request_contextfrom 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 errorserr_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 exceptionserr_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.pyindex b9477c2e6..17592ca59 100644--- a/openviking/server/routers/maintenance.py+++ b/openviking/server/routers/maintenance.py@@ -7,6 +7,7 @@ import asynciofrom fastapi import APIRouter, Bodyfrom pydantic import BaseModel+from openviking.core.path_variables import resolve_path_variablesfrom openviking.core.uri_validation import validate_viking_urifrom openviking.server.auth import require_rolefrom openviking.server.dependencies import get_service@@ -48,7 +49,8 @@ async def reindex(from openviking.service.task_tracker import get_task_trackerfrom 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 existsdiff --git a/openviking/server/routers/pack.py b/openviking/server/routers/pack.pyindex eb3ec2c72..88b26a995 100644--- a/openviking/server/routers/pack.py+++ b/openviking/server/routers/pack.py@@ -10,6 +10,7 @@ from fastapi.responses import FileResponsefrom pydantic import BaseModel, ConfigDictfrom starlette.background import BackgroundTask+from openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_context, require_auth_root_or_adminfrom openviking.server.dependencies import get_servicefrom 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 exporttemp_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.pyindex 4aa75506e..ce9b533f6 100644--- a/openviking/server/routers/relations.py+++ b/openviking/server/routers/relations.py@@ -7,11 +7,20 @@ from typing import List, Unionfrom fastapi import APIRouter, Depends, Queryfrom pydantic import BaseModel+from openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_servicefrom openviking.server.identity import RequestContextfrom 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.pyindex b1c16882e..dca02760e 100644--- a/openviking/server/routers/resources.py+++ b/openviking/server/routers/resources.py@@ -7,6 +7,7 @@ from typing import Any, Optionalfrom fastapi import APIRouter, Depends, File, Form, Request, UploadFilefrom pydantic import BaseModel, ConfigDict, model_validator+from openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_servicefrom 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] = Noneto: Optional[str] = Noneparent: Optional[str] = None+ create_parent: bool = Falsereason: 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 Noneasync 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.pyindex 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, Unionfrom fastapi import APIRouter, Dependsfrom pydantic import BaseModel+from openviking.core.path_variables import resolve_path_variablesfrom openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundErrorfrom openviking.server.auth import get_request_contextfrom 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 exceptionserr_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")raiseexcept 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 excraise@@ -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 exceptionserr_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")raiseexcept 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.pyindex 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, Optionalfrom fastapi import APIRouter, Body, Depends, Path, Query, Requestfrom pydantic import BaseModel, Field, model_validator+from openviking.core.path_variables import resolve_path_variablesfrom openviking.message.part import TextPart, part_from_dictfrom openviking.server.auth import get_request_contextfrom 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.pyindex 43d0a8274..0d4328591 100644--- a/openviking/service/resource_service.py+++ b/openviking/service/resource_service.py@@ -10,6 +10,7 @@ import jsonimport timefrom typing import TYPE_CHECKING, Any, Dict, List, Optional+from openviking.core.path_variables import resolve_path_variablesfrom openviking.core.uri_validation import validate_optional_viking_urifrom openviking.server.identity import RequestContextfrom 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.pyindex 64de7b14c..3f4e63a50 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -1173,7 +1173,7 @@ class VikingFS:raise mapped from excraise# 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.pyindex 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.uridiff --git a/tests/unit/test_path_variables.py b/tests/unit/test_path_variables.pynew file mode 100644index 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"