Documentation
¶
Overview ¶
Package imagegen defines independent image generation and editing contracts. Provider implementations live in agentx-contrib. Images use model.Part so applications can pass them directly to conversations and tool results.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Tool ¶
Tool wraps a Generator as a normal Agent tool. When g also implements Editor and ResolveImage is configured, the same tool can edit images. It returns image parts and response metadata, and is neither read-only nor concurrent by default: generating images can incur charges and is not idempotent. options can enable the runtime's existing approval and scheduling policies.
Types ¶
type ArtifactError ¶
ArtifactError retains generated output when persistence fails. Applications can recover the images and already-saved references without paying for another generation. Err retains the storage error's identity through Unwrap.
func (*ArtifactError) Error ¶
func (e *ArtifactError) Error() string
func (*ArtifactError) Unwrap ¶
func (e *ArtifactError) Unwrap() error
type EditRequest ¶
type EditRequest struct {
Request
Images []model.Part `json:"images"`
Mask *model.Part `json:"mask,omitempty"`
Markup *model.Part `json:"markup,omitempty"`
}
EditRequest edits one or more images. Mask selects the editable area; Markup supplies a visual annotation. Providers may not support both together.
type EditStreamer ¶
type EditStreamer interface {
StreamEdit(ctx context.Context, req *EditRequest) iter.Seq2[*StreamEvent, error]
}
EditStreamer streams previews and a final response for an image edit.
type Editor ¶
type Editor interface {
Edit(ctx context.Context, req *EditRequest) (*Response, error)
}
Editor creates images from a prompt and existing images.
type Generator ¶
Generator creates images from text. Implementations must be safe for concurrent use.
type Image ¶
type Image struct {
Part model.Part `json:"part"`
RevisedPrompt string `json:"revised_prompt,omitempty"`
}
Image is a generated image and, when supplied, the provider's revised prompt.
type Request ¶
type Request struct {
Model string `json:"model,omitempty"`
Prompt string `json:"prompt"`
N int `json:"n,omitempty"`
Size string `json:"size,omitempty"`
// AspectRatio is used by providers with ratio-based image settings.
AspectRatio string `json:"aspect_ratio,omitempty"`
Quality string `json:"quality,omitempty"`
OutputFormat string `json:"output_format,omitempty"`
Background string `json:"background,omitempty"`
// OutputCompression is a percentage; nil leaves the provider default,
// while a pointer to zero explicitly requests zero compression quality.
OutputCompression *int `json:"output_compression,omitempty"`
SafetyIdentifier string `json:"safety_identifier,omitempty"`
// PartialImages requests a number of previews when streaming.
PartialImages int `json:"partial_images,omitempty"`
// ProviderOptions carries extra fields keyed by provider, as in model.Request.
// Implementations document which fields may override typed options.
ProviderOptions map[string]map[string]any `json:"provider_options,omitempty"`
}
Request describes image generation. Empty options leave provider defaults. A request and its referenced data must not be mutated during a call.
type Response ¶
type Response struct {
Provider string `json:"provider"`
Model string `json:"model"`
RequestID string `json:"request_id,omitempty"`
Created time.Time `json:"created,omitzero"`
Images []Image `json:"images"`
Size string `json:"size,omitempty"`
Quality string `json:"quality,omitempty"`
Background string `json:"background,omitempty"`
OutputFormat string `json:"output_format,omitempty"`
Usage *Usage `json:"usage,omitempty"`
}
Response contains complete images and the settings reported by the provider. Model is the selected model when the provider does not report a resolved name.
type StreamEvent ¶
type StreamEvent struct {
Image *Image `json:"image,omitempty"`
PartialIndex int `json:"partial_index,omitempty"`
Response *Response `json:"response,omitempty"`
}
StreamEvent contains either a preview Image or the final Response. A preview is not a completed result and must not be treated as one.
type Streamer ¶
type Streamer interface {
Stream(ctx context.Context, req *Request) iter.Seq2[*StreamEvent, error]
}
Streamer generates previews followed by exactly one final response. A non-nil error terminates the stream; stopping iteration cancels reading.
type ToolOptions ¶
type ToolOptions struct {
Name string
Description string
Request Request
// MaxImages limits output images per call; zero defaults to one.
MaxImages int
// ResolveImage maps application-owned references to input images, masks
// and markup. Without it, the tool only offers text-to-image generation.
// The application owns authorization, URL access and file loading.
ResolveImage func(context.Context, string) (model.Part, error)
// Artifacts optionally persists generated bytes. ArtifactScope is trusted
// application identity, never a model argument. A failure is returned without
// regenerating images; earlier writes in the same call remain stored.
Artifacts artifact.Store
ArtifactScope string
}
ToolOptions configures Tool. Request supplies trusted defaults: the model, safety identifier and provider options are never chosen by the agent.
type Usage ¶
type Usage struct {
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
TotalTokens int `json:"total_tokens"`
InputTextTokens int `json:"input_text_tokens"`
InputImageTokens int `json:"input_image_tokens"`
OutputTextTokens int `json:"output_text_tokens"`
OutputImageTokens int `json:"output_image_tokens"`
}
Usage preserves image and text token accounting. Absent usage is nil in Response.
Source Files