adk-artifact 0.5.0

Binary artifact storage for Rust Agent Development Kit (ADK-Rust) agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use adk_core::{Part, Result};
use async_trait::async_trait;

/// Request to save a binary artifact.
#[derive(Debug, Clone)]
pub struct SaveRequest {
    /// Application namespace.
    pub app_name: String,
    /// Owning user.
    pub user_id: String,
    /// Session the artifact belongs to.
    pub session_id: String,
    /// Artifact filename (validated against path traversal).
    pub file_name: String,
    /// The binary content to store.
    pub part: Part,
    /// Explicit version to write, or `None` for auto-increment.
    pub version: Option<i64>,
}

/// Response from a successful save operation.
#[derive(Debug, Clone)]
pub struct SaveResponse {
    /// The version number that was written.
    pub version: i64,
}

/// Request to load an artifact.
#[derive(Debug, Clone)]
pub struct LoadRequest {
    /// Application namespace.
    pub app_name: String,
    /// Owning user.
    pub user_id: String,
    /// Session the artifact belongs to.
    pub session_id: String,
    /// Artifact filename.
    pub file_name: String,
    /// Specific version to load, or `None` for the latest.
    pub version: Option<i64>,
}

/// Response from a successful load operation.
#[derive(Debug, Clone)]
pub struct LoadResponse {
    /// The binary content that was stored.
    pub part: Part,
}

/// Request to delete an artifact.
#[derive(Debug, Clone)]
pub struct DeleteRequest {
    /// Application namespace.
    pub app_name: String,
    /// Owning user.
    pub user_id: String,
    /// Session the artifact belongs to.
    pub session_id: String,
    /// Artifact filename.
    pub file_name: String,
    /// Specific version to delete, or `None` to delete all versions.
    pub version: Option<i64>,
}

/// Request to list artifacts in a session.
#[derive(Debug, Clone)]
pub struct ListRequest {
    /// Application namespace.
    pub app_name: String,
    /// Owning user.
    pub user_id: String,
    /// Session to list artifacts from.
    pub session_id: String,
}

/// Response containing artifact filenames.
#[derive(Debug, Clone)]
pub struct ListResponse {
    /// Filenames of all artifacts in the session.
    pub file_names: Vec<String>,
}

/// Request to list versions of a specific artifact.
#[derive(Debug, Clone)]
pub struct VersionsRequest {
    /// Application namespace.
    pub app_name: String,
    /// Owning user.
    pub user_id: String,
    /// Session the artifact belongs to.
    pub session_id: String,
    /// Artifact filename.
    pub file_name: String,
}

/// Response containing available version numbers.
#[derive(Debug, Clone)]
pub struct VersionsResponse {
    /// Version numbers in ascending order.
    pub versions: Vec<i64>,
}

/// Trait for artifact storage backends.
///
/// Implementations must be thread-safe (`Send + Sync`) and support
/// versioned binary storage scoped by app, user, and session.
#[async_trait]
pub trait ArtifactService: Send + Sync {
    /// Store a binary artifact, returning the version that was written.
    async fn save(&self, req: SaveRequest) -> Result<SaveResponse>;
    /// Retrieve a stored artifact by filename and optional version.
    async fn load(&self, req: LoadRequest) -> Result<LoadResponse>;
    /// Delete an artifact (specific version or all versions).
    async fn delete(&self, req: DeleteRequest) -> Result<()>;
    /// List all artifact filenames in a session.
    async fn list(&self, req: ListRequest) -> Result<ListResponse>;
    /// List all available versions of a specific artifact.
    async fn versions(&self, req: VersionsRequest) -> Result<VersionsResponse>;

    /// Verify backend connectivity.
    ///
    /// The default implementation succeeds, which is appropriate for
    /// in-memory backends.
    async fn health_check(&self) -> Result<()> {
        Ok(())
    }
}