direct

package
v0.107.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

README

Direct synchronous adapters — Goal04 static implementation

Current integration: ordinary provider-derived targets and expanded model/alias selection are documented in Provider-backed image targets. That path permits configured OpenAI generate/reference/edit/mask and Google generate/reference/edit, with model-specific Google aspect ratio/resolution schemas, without claiming live verification. The standalone verification rules described below remain in force for legacy targets.

This directory contains authored protocol fixtures and offline tests, not provider receipts. Synthetic PNGs are generated in tests. No credentials were read and no generation, upload, account query or paid API was called.

Registry integration

Import github.com/Stack-Cairn/K-brain/internal/imaging/adapters/direct.

  • NewOpenAI(Options) (*Adapter, error) — ID openai-images, version 1; base URL includes /v1.
  • NewGoogle(Options) (*Adapter, error) — ID google-generate-content-image, version 1; base URL includes /v1beta.
  • NewVolcengine(Options) (*Adapter, error) — ID volcengine-ark-image, version 1; base URL includes /api/v3.
  • (*Adapter).Profile() Profile returns independent copies of capability/parameter metadata. It is not TargetVerification and does not register/enable anything. Google ContractComplete=false. All profiles have LiveVerified=false, no continuation/preview/cancel/reconcile. Poll/Cancel/Reconcile return imaging.ErrUnsupported without network access.

Options requires an injected HTTPClient, BaseURL, SecretResolver, Scope, and SecretRef; optional Limits only tighten local bounds. Optional CustomHeaders map[string]string is defensively copied and validated: only OpenAI-Organization, OpenAI-Project and restricted X-* names; auth/token/key/secret, idempotency, forwarding, proxy, method and transport-control names are rejected, as are case-duplicate names and control characters. At most 32 headers / 16 KiB total / 4 KiB per value. Host, Content-Length, Content-Type, Accept and all adapter auth headers cannot be overridden. This supports safe inherited provider_ref extension headers; assembly maps SecretRefs["apiKey"] to SecretRef and checks AuthKind (bearer for OpenAI/Ark, api_key_header for Google) before construction. Client/transport pooling and CloseIdleConnections remain owned by assembly, not by per-submit adapter code. Auth ownership: the backend resolver owns secrets at rest; the adapter resolves the scoped ref on each Submit and writes either Authorization: Bearer ... or x-goog-api-key. The adapter never reads env credentials. The caller owns network/proxy/egress policy and must supply a trusted transport without retries, injected auth, request logging or hidden redirects. The adapter copies the client, removes its cookie jar, refuses redirects, removes GetBody replay support and sends no idempotency header. HTTPS is required except loopback HTTP for httptest.

Call Submit with an explicit TargetSnapshot (adapter ID, version 1, kind model, RemoteID), one item (Request.Count=1), and authorized ResolvedAssets in exactly the same order/identity as Request.Inputs. The engine already reduces batch items to count=1. Request.Parameters uses native snake_case names for OpenAI/Ark; Ark's flat optimize_prompt_options.mode maps to the native nested object. Legacy verification uses a minimal Google profile without optional parameters. Provider-backed Google models expose validated aspectRatio and conditional imageSize via ModelParameters, mapped into generationConfig.imageConfig. Unexpected parameters, continuation, model families, and count are rejected before HTTP. Explicit Ark ep-* is accepted only on the integration assumption that registry evidence binds it to Seedream 5.0 pro; registry must enforce that binding.

Legacy verification examples: OpenAI gpt-image-2 / gpt-image-2-2026-04-21; Google gemini-nano-banana-2.1; Ark doubao-seedream-5-0-pro-260628 or an explicitly verified endpoint ID. Ordinary image model families (including GPT Image 1/1.5/2/2.5) are recognized by ImageModelAdapter; private aliases require explicit provider model metadata. Names alone do not establish compatibility for arbitrary image APIs.

Implemented restrictions

  • OpenAI: JSON generations and official multipart edits with ordered image[] files and optional PNG mask; n=1; selected size/quality/output format/compression/background fields. Provider-backed GPT Image 2/2.5 models expose aspectRatio + imageSize via ModelParameters, mapped to one validated size (see Provider-backed image targets). Generic provider-backed requests outside the official api.openai.com host also reinforce an explicit pixel canvas in the outgoing prompt, giving the selected size precedence over conflicting prompt framing. Official-host detection uses the parsed hostname, ignoring case and an explicit port; lookalike prefix/suffix hosts remain generic providers. Automatic framing (no resolved pixel size), stored prompts and vendor profiles stay unchanged. The 32,000-codepoint ceiling includes the canvas instruction. Multipart field/file bodies are bounded before HTTP, file MIME and bytes are preserved after validation, and requests have no replayable GetBody. No Files API or stream. Mask uses a multipart PNG mask file, applies to the first image (must be the source), requires matching PNG dimensions and a fully transparent region. Alpha is unchanged. This is guidance to the model, not exact pixel locking. Local maximum is 16 total inputs including mask (stricter than 16 images plus mask).
  • Google: single-turn generateContent, canonical camelCase contents/inlineData and responseModalities TEXT+IMAGE; up to 14 ordered PNG/JPEG/WebP references; semantic edit, no mask. Final non-thought images across candidates/parts are retained, at most 16; STOP and model role required. Text/signature history is not retained because current RemoteResult has no continuation/text storage contract. Thus continuation is disabled even though the provider supports conversation history. MAX_TOKENS/unknown finish reasons conservatively become unknown; partial valid images in a malformed/incomplete response are not returned. These limits are local and do not claim a provider candidateCount limit. Legacy verified-target contract remains incomplete; provider-derived targets use the separate provider_configured execution path without claiming verified status.
  • Ark: Seedream 5.0 pro ordinary single image generation/reference/semantic edit; ordered image array; response_format defaults locally to b64_json; size tiers 1K/1.5K/2K or validated pixel dimensions, png/jpeg output, watermark and optimization mode. No n, group generation fields, layer decomposition, background, mask, tools or stream.

Defaults: 64 MiB encoded request/response, 20 MiB per image, 40 MP. Google entire encoded request is further limited to 20,000,000 bytes; OpenAI multipart uploads remain subject to the shared request/image ceilings; Ark inputs to 36 MP, both edges >14 pixels, ratio 1/16..16. Byte and pixel caps are local intersections, not claims that providers accept every format or size. Prompt ceiling 32,000 Unicode codepoints is a local restriction for all profiles (OpenAI documented limit; stricter local policy for others).

Responses are bounded before parsing. Strict canonical base64 (including pad bits and rejecting CR/LF), real MIME, pixel bounds and full image decode are checked via offline imaging.DecodeImageContent. Only bytes or internal OutputSource{Kind:"url"} leave the adapter. The official OpenAI profile remains base64-only; provider-backed OpenAI-compatible targets and the Ark, RollDek and Agnes profiles also accept HTTPS URL results. URLs remain untrusted until the engine's image downloader validates public egress, downloads, decodes and atomically saves them. RemoteResult.State=completed means provider response complete, not a persisted successful job. No URL download occurs in this package.

imaging.Usage only represents money. Provider token/image usage cannot populate it, so Usage is nil even when native token counts exist; no fabricated 0 amount. Empty/text-only/blocked responses fail with NO_IMAGE_OUTPUT. Sent request transport failures, lost/truncated/invalid responses, redirect, 408/499/5xx, and unstructured 409/429 become DeliveryUncertain + unknown. Explicit 409/429 error envelopes are rejected; ordinary 400/401/403/404 are rejected. No raw body, prompt, auth, URL, provider message or wrapped transport cause is exposed in errors. No retries are performed.

Source verification and gaps (2026-10-11)

The requested web.run tool was not available in this agent. Actual public browser requests were made instead, without login or API calls:

  • OpenAI official https://developers.openai.com/api/reference/resources/images/methods/edit returned 403 FORBIDDEN. Official alternate https://platform.openai.com/docs/api-reference/images/createEdit returned a Cloudflare block page. Consequently OpenAI implementation relies on the existing repository research docs/research/image-studio-2026-10-11/openai.md; not newly/currently confirmed by this implementation run. Its static ContractComplete follows that research's restricted contract, not successful new verification. Registry must preserve this evidence gap and keep targets disabled until genuine connection/model verification.
  • https://ai.google.dev/api/generate-content?hl=en loaded successfully: confirmed v1beta path, required model/contents, generationConfig, candidates/content/parts, usageMetadata, promptFeedback. https://ai.google.dev/gemini-api/docs/generate-content/image-generation?hl=en navigation initially timed out; subsequently loaded page text was successfully read, including hidden REST samples: confirmed x-goog-api-key, model name, inlineData, TEXT/IMAGE modalities, 14 reference images and thought image distinction. No independent HTTP status receipt was captured. Existing responseFormat enum/model support discrepancies from google.md remain unresolved; this package deliberately omits those fields.
  • https://docs.volcengine.com/docs/ark/image-generation-api?lang=zh initially showed only its shell, then loaded; visible and public collapsed text were read. Confirmed Beijing v3 path, Bearer sample, 5.0 pro model, ordinary single-image/no stream/no group generation, image data URLs and array, max 10 refs, image/size bounds, response_format, output_format, watermark, usage/error fields. Page displayed update 2026.10.10 22:39:45. No API debugging controls were activated.

All account entitlement, region reachability, live generation/edit/mask quality, actual usage/errors and persistence/download integration remain unverified. Static httptest is not live acceptance. Registry should bind trusted evidence to connection ID/target revision separately. No files outside this direct package were edited.

Validation

Run from the K-brain checkout, after clearing LIVEAGENT_HOME/K_BRAIN_HOME and setting HOME and USERPROFILE to the workspace .liveagent/image-studio-test-home:

$env:LIVEAGENT_HOME = $null
$env:K_BRAIN_HOME = $null
$env:HOME = 'D:\Documents\Projects\Web\LiveAgent\.liveagent\image-studio-test-home'
$env:USERPROFILE = $env:HOME
mise exec -- gofmt -w internal/imaging/adapters/direct/adapter.go internal/imaging/adapters/direct/request.go internal/imaging/adapters/direct/provider_framing_test.go
mise exec -- go test ./internal/imaging/adapters/direct -count=1
mise exec -- go vet ./internal/imaging/adapters/direct

Only httptest/fake transports and synthetic small PNGs are used. Test fixtures are hand-authored schema examples, never official responses. Tests assert the actual Submit HTTP method/path/auth/body, edit/reference order, mask rules, reader closure, model/parameter/input limits, mixed final/thought output, invalid MIME/base64/image bodies, absent monetary usage, bounded responses/requests, no URL fetching, no redirect or replay, dropped responses, cancellation, error sanitation and unsupported methods.

Documentation

Overview

Package direct implements restricted, synchronous image provider protocols. It does not register or enable targets, persist assets, download output URLs, retry paid submissions, or provide provider-side idempotency guarantees.

Index

Constants

View Source
const (
	OpenAIID     = "openai-images"
	GoogleID     = "google-generate-content-image"
	VolcengineID = "volcengine-ark-image"
	Version      = "1"
)

Variables

This section is empty.

Functions

func AgnesParameters

func AgnesParameters() []imaging.ParameterSpec

AgnesParameters is the tiered size/ratio contract of Agnes Image; exact pixel sizes are normalized server-side, so only tiers are offered. Keys reuse the Google names clients already render; the request maps them to size/ratio.

func ImageModelAdapter

func ImageModelAdapter(id string) string

ImageModelAdapter is deliberately conservative: image INPUT support, display names and generic "image" substrings do not identify an image generation model.

func ModelParameters

func ModelParameters(adapter, model string) []imaging.ParameterSpec

ModelParameters returns fresh schema slices for the implemented model-specific wire contract. It does not claim live verification or change legacy evidence.

func ProfileForBaseURL

func ProfileForBaseURL(base string) string

ProfileForBaseURL names the vendor dialect behind an OpenAI-compatible base URL. Only exact official endpoints qualify; proxies keep the standard OpenAI contract.

func ValidImageModelID

func ValidImageModelID(id string) bool

ValidImageModelID excludes path/query injection in Google's model URL. Unknown aliases require explicit model metadata; names alone never establish a protocol.

func ValidateCustomHeaders

func ValidateCustomHeaders(in map[string]string) error

ValidateCustomHeaders checks the same offline header contract used by adapter construction. It does not resolve secrets or make network requests.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

func NewGoogle

func NewGoogle(o Options) (*Adapter, error)

func NewOpenAI

func NewOpenAI(o Options) (*Adapter, error)

func NewVolcengine

func NewVolcengine(o Options) (*Adapter, error)

func (*Adapter) Cancel

func (a *Adapter) Cancel(context.Context, string) error

func (*Adapter) Poll

func (*Adapter) Profile

func (a *Adapter) Profile() Profile

func (*Adapter) Reconcile

func (*Adapter) Submit

type Limits

type Limits struct {
	MaxRequestBytes  int64
	MaxResponseBytes int64
	MaxImageBytes    int64
	MaxPixels        int64
}

Limits may tighten, but never enlarge, the local hard ceilings. Zero uses defaults. Google additionally limits the entire encoded request to 20 MB.

type Options

type Options struct {
	HTTPClient     *http.Client
	BaseURL        string
	SecretResolver imaging.SecretResolver
	Scope          imaging.Scope
	SecretRef      string
	// CustomHeaders is copied and validated at construction. Only restricted
	// X-* extension headers and OpenAI-Organization/OpenAI-Project are allowed.
	// Authentication, HTTP controls, forwarding and idempotency are reserved.
	CustomHeaders map[string]string
	Limits        Limits
	Profile       string
}

Options are backend-only. The adapter owns the authentication header: it resolves SecretRef in Scope for each submit, never from environment variables. HTTPClient must have a trusted transport that does not retry, inject auth, log sensitive payloads, or redirect requests itself. Network/proxy policy is owned by the caller. A client copy disables redirects and its cookie jar. BaseURL includes the API prefix (/v1, /v1beta, /api/v3 respectively). Plain HTTP is accepted only for loopback httptest servers.

type Profile

type Profile struct {
	Adapter          string
	Version          string
	ContractComplete bool
	LiveVerified     bool
	RemoteIDs        []string
	Capabilities     imaging.TargetCapabilities
	Parameters       []imaging.ParameterSpec
}

Profile is static implementation metadata, never TargetVerification. Registry owners must bind real evidence to the connection/revision; no live timestamps or enabled targets are manufactured here. RemoteIDs are frozen verification examples; ImageModelAdapter also recognizes ordinary image model families. Explicit provider metadata may bind aliases. Ark additionally accepts bound ep-* IDs.

func ProtocolProfile

func ProtocolProfile(adapter string) Profile

ProtocolProfile describes implemented wire capabilities without claiming live verification or provider-specific support. Callers may restrict this profile.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL