service.go

Overview

This file defines the artifact package's core interface and data structures for managing artifacts—files identified by an application name, user ID, session ID, and filename. The package provides a standardized service interface (Service) to perform essential artifact operations: saving, loading, deleting, listing, and retrieving version information.

Artifacts support versioning, enabling multiple versions of the same artifact to coexist. The file also includes request and response types for each operation, along with validation logic to ensure required fields are present and valid before processing.

This module plays a foundational role in the broader Artifact Management topic, enabling agents and tools to persist and retrieve artifact data within multi-tenant and multi-session contexts.

Service Interface

type Service interface {
	Save(ctx context.Context, req *SaveRequest) (*SaveResponse, error)
	Load(ctx context.Context, req *LoadRequest) (*LoadResponse, error)
	Delete(ctx context.Context, req *DeleteRequest) error
	List(ctx context.Context, req *ListRequest) (*ListResponse, error)
	Versions(ctx context.Context, req *VersionsRequest) (*VersionsResponse, error)
}

The Service interface outlines the core artifact storage operations:

Each method receives a context and a request struct, returning either a response struct or an error.

Request and Response Types

SaveRequest

SaveRequest.Validate()

Checks that all required string fields are non-empty and that the Part is non-nil with either text or inline data set.

Example usage:

req := &SaveRequest{
	AppName:   "myapp",
	UserID:    "user123",
	SessionID: "sess456",
	FileName:  "file.txt",
	Part:      &genai.Part{Text: "content"},
}
if err := req.Validate(); err != nil {
	// handle error
}

SaveResponse

LoadRequest

LoadRequest.Validate()

Validates presence of required fields.

LoadResponse

DeleteRequest

DeleteRequest.Validate()

Checks required fields.

ListRequest

ListRequest.Validate()

Ensures required fields are populated.

ListResponse

VersionsRequest

VersionsRequest.Validate()

Validates required fields.

VersionsResponse

Validation Helper

The validateRequiredStrings function accepts a slice of requiredField structs, each specifying a field name and its value, and returns a slice of missing field names. This helper is used by all request structs' Validate methods to reduce duplication.

Implementation Details

Interactions with Other System Components

File Structure and Relationships Diagram

classDiagram
class Service {
<<interface>>
+Save()
+Load()
+Delete()
+List()
+Versions()
}
class SaveRequest {
+AppName: string
+UserID: string
+SessionID: string
+FileName: string
+Part: genai.Part
+Version: int64
+Validate()
}
class SaveResponse {
+Version: int64
}
class LoadRequest {
+AppName: string
+UserID: string
+SessionID: string
+FileName: string
+Version: int64
+Validate()
}
class LoadResponse {
+Part: genai.Part
}
class DeleteRequest {
+AppName: string
+UserID: string
+SessionID: string
+FileName: string
+Version: int64
+Validate()
}
class ListRequest {
+AppName: string
+UserID: string
+SessionID: string
+Validate()
}
class ListResponse {
+FileNames: []string
}
class VersionsRequest {
+AppName: string
+UserID: string
+SessionID: string
+FileName: string
+Validate()
}
class VersionsResponse {
+Versions: []int64
}
class requiredField {
-Name: string
-Value: string
}
SaveRequest --> "1" genai.Part
LoadResponse --> "1" genai.Part
SaveRequest ..> requiredField : uses
LoadRequest ..> requiredField : uses
DeleteRequest ..> requiredField : uses
ListRequest ..> requiredField : uses
VersionsRequest ..> requiredField : uses

Usage Example

func SaveArtifactExample(ctx context.Context, svc artifact.Service) error {
	req := &artifact.SaveRequest{
		AppName:   "myApp",
		UserID:    "user42",
		SessionID: "session99",
		FileName:  "report.txt",
		Part:      &genai.Part{Text: "Report content"},
	}

	if err := req.Validate(); err != nil {
		return err
	}

	resp, err := svc.Save(ctx, req)
	if err != nil {
		return err
	}

	fmt.Printf("Artifact saved at version: %d\n", resp.Version)
	return nil
}

This example demonstrates creating a valid save request, validating it, and calling the Save method on a Service implementation.

Relevant Topics