artifact

type ArtifactVersion struct {
	Version int64

	// CanonicalURI is a stable identity for the stored payload. Implementations
	// with a native scheme should use it, such as gs:// for Google Cloud Storage;
	// other implementations should define a stable service-specific scheme. It
	// is not necessarily a download endpoint or an authenticated HTTP URL.
	CanonicalURI string

	// Implementations must return a non-nil map containing only string values.
	// It is empty when no custom metadata was saved.
	CustomMetadata map[string]any

	// CreateTime is when this artifact version was created.
	CreateTime time.Time

	// MimeType is the media type associated with the stored part. It may be empty
	// when the part was saved without a media type.
	MimeType string
}

type DeleteRequest struct {
	AppName, UserID, SessionID, FileName string

	// Below are optional fields.
	Version int64
}

type GetArtifactVersionRequest struct {
	AppName, UserID, SessionID, FileName string

	// Below are optional fields.
	Version int64
}

type GetArtifactVersionResponse struct {
	ArtifactVersion *ArtifactVersion
}

type ListRequest struct {
	AppName, UserID, SessionID string
}

type ListResponse struct {
	FileNames []string
}

type LoadRequest struct {
	AppName, UserID, SessionID, FileName string

	// Below are optional fields.
	Version int64
}

type LoadResponse struct {
	// Part is the artifact stored.
	Part *genai.Part
}

type SaveRequest struct {
	AppName, UserID, SessionID, FileName string
	// Part is the artifact to store.
	Part *genai.Part

	// CustomMetadata contains caller-defined metadata persisted with the artifact.
	// Service implementations must convert each value to its string representation
	// when saving it and return the value as a string.
	CustomMetadata map[string]any

	// If set, the artifact will be saved with this version.
	// If unset, a new version will be created.
	Version int64
}

type SaveResponse struct {
	Version int64
}

type Service interface {
	// Save saves an artifact to the artifact service storage.
	// The artifact is a file identified by the app name, user ID, session ID, and fileName.
	// After saving the artifact, a revision ID is returned to identify the artifact version.
	// Implementations that assign versions optimistically may fail to claim one
	// while other writers save the same artifact; that failure is transient and
	// the call can be retried.
	Save(ctx context.Context, req *SaveRequest) (*SaveResponse, error)
	// Load loads an artifact from the storage.
	// The artifact is a file identified by the appName, userID, sessionID and fileName.
	Load(ctx context.Context, req *LoadRequest) (*LoadResponse, error)
	// Delete deletes an artifact. Deleting a non-existing entry is not an error.
	Delete(ctx context.Context, req *DeleteRequest) error
	// List lists all the artifact filenames within a session.
	List(ctx context.Context, req *ListRequest) (*ListResponse, error)
	// Versions lists all versions of an artifact.
	Versions(ctx context.Context, req *VersionsRequest) (*VersionsResponse, error)
	// GetArtifactVersion gets the metadata for a specific version of an artifact.
	GetArtifactVersion(ctx context.Context, req *GetArtifactVersionRequest) (*GetArtifactVersionResponse, error)
}

type VersionsRequest struct {
	AppName, UserID, SessionID, FileName string
}

type VersionsResponse struct {
	Versions []int64
}