Files
archie/docs/prds/image-capability-contract.md
T
sam 45b183b325 docs(image): point the hosted-provider bead at ai-sdk's existing image facility
ai-sdk (already a dependency) has a provider-agnostic image.Provider,
core.GenerateImage, and registry.RegisterImage -- three backends
(azure/togetherai/xai) implement it, OpenAI doesn't yet. The next
bead should adapt that instead of a raw HTTP client, mirroring how
curatorLLMRunner adapts runtime.Runtime for chat. Noted the one real
gap (no edit/mask support in ai-sdk's request type) for that bead to
resolve at its own design step.
2026-09-02 20:23:14 +10:00

12 KiB

Image capability contract and configuration

Epic: archie-core-1786748942120-1-6636e629 ("Image generation capability: hosted API baseline plus local GPU workflows"). Scope: archie-core-1786748942147-2-47cd5bd1 — the contract and configuration only. Hosted provider implementation (gpt-image-2), local GPU backend, /image routing, and delivery are separate, dependent beads and are not built here.

Problem

Archie needs a provider-neutral boundary for image generation/editing so a hosted API (gpt-image-2-class) and a future local GPU backend can both implement it without either one leaking into the domain contract. Nothing in the repo defines this today (grep -ri image over internal/domain and internal/config returns nothing image-specific).

Design

Follows the plugin engine family shape already established by internal/domain/curator and internal/domain/memory (ARCHITECTURE.md "plugin engine rule strict"): a typed contract with real domain operations, an owning Registry (register/get/names, no start/stop lifecycle — see below), and narrow host access via a Registrar.

Package: internal/domain/image

Why no Lifecycle (Start/Health/Stop): curator and memory engines are long-running — they hold a background cadence or a persistent connection worth health-checking. An image provider is call-scoped: it either serves a Generate/Edit request or it does not. Health here means "is this provider usable right now", which is exactly what Generate/Edit returning a typed ErrUnavailable already communicates — a separate Health() poll would just duplicate that. Registry still owns registration and lookup, so provider selection is testable with fakes per the acceptance criteria, but there is no Start/Stop to orchestrate.

// 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        bool // edit requires at least one input image
    Mask        bool // edit supports a mask restricting the edited region
    MaxInputs   int  // 0 = Edit unsupported
    Sizes       []string // provider-declared output sizes, e.g. "1024x1024"
}

// Provider is the typed contract every image backend implements — hosted
// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is
// call-scoped, not long-running (see design doc rationale).
type Provider interface {
    Name() string
    // Class distinguishes hosted (spends money/quota per call) from local
    // (spends host GPU/time). Selection logic 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.
    Class() ProviderClass
    Capability() Capability
    Generate(ctx context.Context, req GenerateRequest) (Result, error)
    Edit(ctx context.Context, req EditRequest) (Result, error)
}

type ProviderClass string

const (
    ClassHosted ProviderClass = "hosted"
    ClassLocal  ProviderClass = "local"
)

Request/result types (provider-neutral, no OpenAI types):

type GenerateRequest struct {
    Prompt string
    Size   string        // "" = provider default
    N      int           // number of images; 0 = 1
    Options map[string]string // provider-specific overflow (e.g. "quality"),
                              // deliberately untyped so the contract does not
                              // grow a field per provider
}

type EditRequest struct {
    Prompt string
    Inputs []ImageData // 1..Capability.MaxInputs
    Mask   *ImageData  // nil unless Capability.Mask
    Size   string
    N      int
    Options map[string]string
}

// ImageData carries image bytes in-process, never a path or URL: the
// domain layer must not assume a filesystem or a fetchable location (mirrors
// why curator's Registrar never receives *daemon.Daemon — no ambient host
// access smuggled in through a "just a string" field).
type ImageData struct {
    Bytes    []byte
    MIMEType string
}

type Result struct {
    Images    []ImageData
    Provider  string
    Model     string
    CreatedAt time.Time
}

Error taxonomy

var (
    ErrUnavailable   = errors.New("image provider unavailable") // missing credential, backend down
    ErrUnsupported   = errors.New("image capability unsupported by provider") // e.g. Edit on generate-only
    ErrInputTooLarge = errors.New("image input exceeds configured limit")
    ErrTimeout       = errors.New("image request timed out")
    ErrCanceled      = errors.New("image request canceled")
)

Every provider wraps these with fmt.Errorf("%w: %s", ErrX, detail) so callers can errors.Is regardless of backend. ErrUnavailable is the explicit instruction from the epic: "a missing credential or unavailable backend must make the capability unavailable with a useful user-facing error, not prevent Archie from starting or break text chat" — Register never rejects the daemon's boot, only marks that one provider absent from Registry.Names().

Registry

type Registry struct { /* map[string]Provider, mutex, sorted Names() */ }

func NewRegistry() *Registry
func (r *Registry) Register(p Provider) error // ErrDuplicate on name clash
func (r *Registry) Get(name string) (Provider, bool)
func (r *Registry) Names() []string
func (r *Registry) ByClass(class ProviderClass) []string

No Registrar/host-injection type: unlike curator (needs LLM, Skills, Conversations) and memory (needs Clock, Events), an image provider's dependencies (HTTP client, API key, local backend handle) are entirely its own construction-time concern in internal/infrastructure/image/*, not daemon services it needs injected. Introducing an empty Registrar now would be exactly the "field nobody sets" pattern to avoid.

Configuration

Follows MinimaxConfig's hosted-cost-guard convention exactly: absent config or absent explicit enabled = true per provider means that provider does not register, not "registers but errors on first call".

// ImageConfig configures the image generation capability.
type ImageConfig struct {
    // Default selects which registered provider name /image uses when the
    // request/session has not already picked one. Empty means /image must
    // always ask (the epic's stated default UX) — an empty Default is valid
    // and is not a misconfiguration.
    Default string `toml:"default"`
    Hosted  map[string]ImageHostedProvider `toml:"hosted"`  // keyed by provider name
    Local   map[string]ImageLocalProvider  `toml:"local"`   // keyed by recipe name
}

// ImageHostedProvider configures one hosted (paid) provider. Mirrors
// MinimaxConfig: Enabled defaults false, spending real credits requires an
// explicit opt-in, never an inferred one from the presence of a key alone.
type ImageHostedProvider struct {
    Enabled   bool             `toml:"enabled"`
    Class     string           `toml:"class"`      // "openai" today; provider-neutral field name
    APIKeyEnv string           `toml:"api_key_env"`
    APIKey    secret.SecretRef `toml:"api_key" json:"-"`
    BaseURL   string           `toml:"base_url"`
}

// ImageLocalProvider configures one local GPU recipe. Enabled defaults
// false too: a local backend can still saturate the host GPU/CPU, which is
// its own kind of unwanted cost, so it gets the same explicit gate as a
// hosted provider rather than an on-by-default WebFetch-style treatment.
type ImageLocalProvider struct {
    Enabled bool   `toml:"enabled"`
    Backend string `toml:"backend"` // recipe identifier, defined by the local-backend bead
}

Validation (internal/infrastructure/configuration/validate.go, alongside validateMemory):

  • Default, if set, must name a provider present (enabled) in Hosted or Local — rejects a config that silently falls back to "always ask" when the operator thought they'd pinned one.
  • A Hosted entry with Enabled = true must have Class non-empty and either APIKeyEnv or a resolvable APIKey — the same shape check Provider (chat) already gets, not a new invention.
  • No cross-field surprise: an absent [image] section is valid and produces zero registered providers, matching the epic's non-goal ("silently selecting a paid hosted provider" must never happen by omission either).

Capability discovery

Registry.Names() / ByClass() plus Provider.Capability() give a caller (the future /image routing bead) everything needed to ask "what can I offer this user" without a type switch on provider identity — this is the whole point of the contract being provider-neutral.

Timeouts, size limits, cancellation

  • Every Provider.Generate/Edit call takes the caller's ctx; a provider that ignores cancellation is a provider bug, not a contract gap — mirrors every other Lifecycle-less call in the codebase (chat's runtime.Chat).
  • ImageData size limits are enforced by the caller (the future routing bead) before constructing a request, using a configured max — not by this contract, which has no config surface for "current caller's limit". This package only defines ErrInputTooLarge so a provider that discovers an oversized input itself (rather than trusting the caller) has a typed way to say so.

Testing

  • internal/domain/image/{contract,registry}_test.go mirror memory's test suite shape: registration (duplicate, nil provider), Names/ByClass filtering, Get miss, table-driven Capability checks via a fake provider.
  • internal/infrastructure/configuration/validate_test.go gains cases for ImageConfig: absent section, valid hosted+local, missing Class, missing credential, Default naming an unregistered/disabled provider.
  • No provider implementation exists yet, so no live-call tests — those belong to the hosted/local provider beads.

Non-goals (deferred to sibling beads)

  • Implementing any real Provider (hosted or local).
  • /image clarification/routing flow and session-scoped mechanism selection.
  • Delivery through channel abstractions.
  • Wiring Registry into bootstrap.go (nothing to wire until a real provider exists to register).

Note for the hosted-provider bead (archie-core-1786748942169-3-ae7cfaea)

github.com/samcharles93/ai-sdk (already a repo dependency) has its own provider-agnostic image facility: image.Provider (Name, GenerateImage(ctx, GenerateImageRequest) (GenerateImageResponse, error)), image.Client/core.GenerateImage, and registry.Registry.RegisterImage/ .Image(name) — the same shape chat model registration already uses. Three backends implement it today (azure, togetherai, xai); OpenAI does not yet.

The hosted-provider bead should adapt this instead of writing a raw HTTP client, the same way curatorLLMRunner (internal/app/archied/main.go) adapts runtime.Runtime for chat rather than the domain layer talking to ai-sdk directly — internal/infrastructure/image.<name>Provider wraps an ai-sdk/image.Provider (or a new ai-sdk/provider/openai image implementation, upstream, if one is added) behind this package's Provider interface.

One real gap: ai-sdk's image.GenerateImageRequest has no input-image or mask fields — text-to-image only. EditRequest/Capability.Edit in this contract has nothing to adapt to yet. The hosted-provider bead needs either an upstream ai-sdk change (adding edit support to the image package) or a direct, non-ai-sdk client for the edit endpoint specifically, with generation still going through ai-sdk. Decide and record which at that bead's own design-doc step; this doc takes no position since editing was out of scope here.