Files
archie/internal/domain/image/contract.go
T

146 lines
4.8 KiB
Go

// Package image defines the image generation provider contract.
package image
import (
"context"
"errors"
"time"
)
// Sentinel errors every provider wraps with fmt.Errorf("%w: %s", ...) so
// callers can errors.Is regardless of backend.
var (
// ErrUnavailable means the provider cannot serve right now (missing
// credential, backend down). Per the epic: this must degrade the
// capability to a reported error, never prevent Archie from starting
// or break text chat.
ErrUnavailable = errors.New("image provider unavailable")
// ErrUnsupported means the request needs a capability (e.g. Edit, or
// Mask) the provider does not declare.
ErrUnsupported = errors.New("image capability unsupported by provider")
// ErrInputTooLarge means an input image exceeded a limit the provider
// itself enforces. Caller-side limits are the routing layer's concern,
// not this contract's — see the design doc.
ErrInputTooLarge = errors.New("image input exceeds configured limit")
// ErrTimeout means the provider's own deadline elapsed, distinct from
// the caller's ctx being canceled.
ErrTimeout = errors.New("image request timed out")
// ErrCanceled means the caller's ctx was canceled.
ErrCanceled = errors.New("image request canceled")
)
// ProviderClass distinguishes hosted (spends money/quota per call) from
// local (spends host GPU/time). Selection and config validation key off
// this, never off Name, so a new provider cannot silently slip through the
// hosted-cost gate under an unrecognized name.
type ProviderClass string
const (
ClassHosted ProviderClass = "hosted"
ClassLocal ProviderClass = "local"
)
// Capability declares what one provider supports, discoverable before a
// request is built so a caller can reject an unsupported combination (e.g.
// edit-with-mask on a generate-only provider) instead of sending it and
// parsing a provider-specific error back out.
type Capability struct {
Generate bool
// Edit requires at least one input image. MaxInputs bounds how many.
Edit bool
MaxInputs int
// Mask reports whether Edit supports restricting the edited region to
// a mask image.
Mask bool
// Sizes lists provider-declared output sizes (e.g. "1024x1024"). Empty
// means the provider does not constrain size.
Sizes []string
}
// Validate checks that a declared Capability is internally consistent:
// Edit implies at least one allowed input, and Mask cannot be declared
// without Edit.
func (c Capability) Validate() error {
if c.Edit && c.MaxInputs < 1 {
return errors.New("image capability: edit requires MaxInputs >= 1")
}
if c.Mask && !c.Edit {
return errors.New("image capability: mask requires edit")
}
return nil
}
// ImageData carries image bytes in-process, never a path or URL: the
// domain layer must not assume a filesystem or a fetchable location.
type ImageData struct {
Bytes []byte
MIMEType string
}
// GenerateRequest asks a provider to create images from a prompt alone.
type GenerateRequest struct {
Prompt string
// Size is a provider-declared value from Capability.Sizes, or "" for
// the provider's default.
Size string
// N is the number of images requested. Zero means 1.
N int
// Options carries provider-specific overflow (e.g. "quality"),
// deliberately untyped so the contract does not grow a field per
// provider.
Options map[string]string
}
// Validate checks the fields every provider needs regardless of backend.
func (r GenerateRequest) Validate() error {
if r.Prompt == "" {
return errors.New("image generate request: prompt must not be empty")
}
return nil
}
// EditRequest asks a provider to edit one or more input images per a
// prompt, optionally restricted to a masked region.
type EditRequest struct {
Prompt string
Inputs []ImageData
// Mask restricts the edited region. Only valid when the provider's
// Capability.Mask is true.
Mask *ImageData
Size string
N int
Options map[string]string
}
// Validate checks the fields every provider needs regardless of backend.
// Capability-specific bounds (MaxInputs, Mask support) are the provider's
// own responsibility to enforce against its declared Capability.
func (r EditRequest) Validate() error {
if r.Prompt == "" {
return errors.New("image edit request: prompt must not be empty")
}
if len(r.Inputs) == 0 {
return errors.New("image edit request: at least one input image is required")
}
return nil
}
// Result is what a provider returns from Generate or Edit.
type Result struct {
Images []ImageData
Provider string
Model string
CreatedAt time.Time
}
// Provider is the typed contract every image backend implements — hosted
// (gpt-image-2-class) or local (GPU recipe).
type Provider interface {
Name() string
Class() ProviderClass
Capability() Capability
Generate(ctx context.Context, req GenerateRequest) (Result, error)
Edit(ctx context.Context, req EditRequest) (Result, error)
}