Provider pack schema v1#

A provider pack describes one provider integration as data: a single TOML file that a reviewed Gongbu engine runs. Adding a provider, a model or a price becomes a pack change instead of Rust code and a release.

Status. Schema v1 is defined, Gongbu validates and loads packs, and the sync_fixed and async_poll engines run them. Every shipped contract (Gemini and FLUX.2) runs from a verified pack in packs/verified/. The hubu provider commands that activate your own packs arrive in a later release.

Verified packs#

Verified packs live in packs/verified/ and are compiled into Gongbu. Each shipped contract in contracts/provider-contracts-v1.json whose target settings say type = "pack" is that pack's checked-in projection: the same provider_config_version, pricing version, review date and pricing rules, pinned to the pack's content digest. Gongbu's tests fail if a pack and its contract entries disagree, so a pack change ships with a matching contract update.

What a pack declares and what engines own#

A pack declares what a provider is. An engine decides how calls are made safely, and a pack can't change that.

Gongbu rejects a pack that sets an engine-owned field anywhere in the file, and the error names the field: retries, max_retries, generation_retries, retry, fallback, reconciliation, recovery, settlement, credential_hosts or idempotency_header. For example:

transport.max_retries: engine-owned field is not allowed in a pack; Gongbu never retries a provider mutation

Archetypes#

Example#

schema_version = 1
pack_id = "sandbox-image"
pack_version = "2026-10-19.1"
provider = "sandbox-image"
display_name = "Sandbox image provider"
billing_merchant = "merchant:sandbox-image"
capability = "capability:image:generate"
workload_type = "image_generation"
archetype = "sync_fixed"
pricing_trust = "verified"

[transport]
endpoint = "https://api.sandbox-image.test"
api_version = "v1"
allowed_hosts = ["api.sandbox-image.test"]
auth_header = "x-api-key"
credential = "sandbox_image"
timeout_ms = 30000

[[parameters]]
name = "prompt"
type = "string"
required = true
max_length = 4000

[[parameters]]
name = "image_count"
type = "integer"
field = "n"
min = 1
max = 4
default = 1
quantity = "image_count"

[[parameters]]
name = "quality"
type = "enum"
values = ["draft", "final"]
default = "draft"
selector = "quality"

[fixed]
response_format = "url"

[response]
provider_request_id = "/id"
usage = { images = "/data" }
artifact_items = "/data"
artifact_url = "/url"

[artifacts]
media_types = ["image/png"]
hosts = ["cdn.sandbox-image.test"]

[[models]]
model = "image-v1"
provider_config_version = "sandbox-image-v1-2026-10-19"
pricing_version = "sandbox-image-v1-usd-2026-10-19-v1"
pricing_reviewed_on = "2026-10-19"

[[models.pricing_rules]]
rule_id = "sandbox-image-v1-draft-2026-10-19"
currency = "USD"
selector = { quality = "draft" }
components = [
  { unit = "request", rate_numerator_minor = 1, rate_denominator = 10 },
  { unit = "image", rate_numerator_minor = 15, rate_denominator = 10 },
]

[[models.pricing_rules]]
rule_id = "sandbox-image-v1-final-2026-10-19"
currency = "USD"
selector = { quality = "final" }
components = [
  { unit = "request", rate_numerator_minor = 1, rate_denominator = 10 },
  { unit = "image", rate_numerator_minor = 6, rate_denominator = 1 },
]

With this pack, {"prompt": "a red circle", "image_count": 2, "quality": "final"} is held at exactly 0.1¢ + 2 × 6¢ = 12.1¢. The provider receives {"prompt": "a red circle", "n": 2, "quality": "final", "response_format": "url"}.

Fields#

Identity#

[transport]#

[request]#

Optional. Engines send one JSON POST to path on the endpoint; without [request], the path is /.

In a body template, a string that is exactly {{name}} becomes the typed value of parameter name, and {{model}} becomes the model ID. {{name|upper}} and {{name|lower}} change a string's case. A key whose placeholder has no value (an optional parameter with no default) is left out. A placeholder must be the whole string, so values are never spliced into text. With a template, [fixed] and field aren't used, and every parameter must appear in the template unless it is a constant (an integer with min = max, or an enum with one value):

[request]
path = "/v1beta/interactions"

[request.body]
model = "{{model}}"
input = [{ type = "text", text = "{{prompt}}" }]
response_format = { type = "image", image_size = "{{image_size|upper}}" }

[poll]#

Required for async_poll packs and rejected for the others. The engine submits once, checkpoints the job, and polls read-only until the job is ready, refused, or the transport deadline passes. Every poll URL is rebuilt from this declared shape; the engine never follows a provider-supplied URL as is.

A submission response with no status is treated as pending once it carries a job ID; one already ready is mapped without polling. A poll response whose job ID differs from the checkpoint's goes to reconciliation.

[poll]
job_id = "/id"
path = "/v1/get_result"
query = { id = "{{job_id}}" }
url = "/polling_url"
hosts = ["api.eu.example.com", "api.us.example.com"]
interval_ms = 500
status = "/status"
pending = ["pending", "generating"]
ready = ["ready"]
rejected = { "content moderated" = "provider_content_moderated", "error" = "provider_error" }
ambiguous = { "task not found" = "provider_task_not_found" }

Host patterns#

transport.allowed_hosts, poll.hosts and artifacts.hosts accept exact names or patterns with one * label that matches exactly one DNS label, such as delivery.*.example.com for per-region delivery hosts. The * can't stand in the last two labels. An artifact host pattern that could name any credential-bearing host is rejected.

[[parameters]]#

Parameters are the only values an agent can set. Input that names an undeclared parameter, or breaks a parameter's bounds, is rejected before any spend is reserved.

A parameter name may sit in one input group, such as options.seed: the agent sends it as {"options": {"seed": 7}}, and the template refers to it as {{options.seed}}. Grouped parameters need a body template. Grouped names such as options.output_width remain separate from the reserved output_width placeholder and cannot replace its certified value.

A priced parameter (quantity or selector) must be required or have a default. [fixed] fields are sent with every request and can't collide with a parameter's field.

[response]#

Every value is a response path: a JSON Pointer into the provider's JSON body whose segments may filter an array. /steps[type=model_output]/content[type=image] keeps the elements of steps whose type is model_output, then the elements of their content whose type is image.

Usage a pack doesn't map settles at the requested quantity, because a fixed-price call delivers what it was asked for. Map a usage path when the provider can return less, such as fewer images than requested; settlement then charges only what arrived.

Every required usage path must be present and have the expected shape. An unfiltered path must select one nonnegative integer or one array. A path whose last segment filters an array counts its matches, including zero matches; missing fields and non-array filter inputs still fail validation. Malformed or missing declared usage sends the response to reconciliation with its provider request ID, instead of treating it as zero or one unit.

For informational telemetry that a provider may omit, list the mapped keys in optional_usage, such as ["input_tokens", "output_tokens"] on an image-only pack. Missing optional values stay unreported; present values must still have the expected shape. Billed quantities, including zero-rate quantities frozen into a bundle, cannot be optional.

A response the mapping can't read arrives after the provider accepted the work, so the engine sends it to reconciliation and never releases the claim.

How the sync_fixed engine classifies outcomes#

How the async_poll engine classifies outcomes#

Submission follows the sync_fixed table, with 401, 402, 403 and 429 recorded as provider_authentication_failed, provider_insufficient_credit, provider_permission_denied and provider_rate_limited. Once the provider has accepted a job:

After a restart, the engine resumes from the checkpoint: it polls the checkpointed host under the original deadline and never resubmits.

[artifacts]#

[[models]]#

Every combination of selector parameter values must be priced by exactly one rule, and every priced unit must be set by a bounded parameter. Every explicit quantity binding must have a corresponding unit in every model's pricing rules, so it is retained in the frozen snapshot. A valid agent input can therefore never reach an unpriced or unbounded request.

For a flat per-request bundle, use ordinary bounded integer parameters without quantity bindings. If a bundled quantity must also be frozen and checked at settlement, give its component a zero rate and put the bundle price in the request component.

Integrity#

Gongbu computes a content digest over the validated pack; reformatting the file doesn't change it. Each model's target revision records the pack ID, version, digest and archetype. A target only binds to the exact pack it was frozen with, so editing a pack is a new revision, never a silent change to executions already in flight.

Binding also requires the runtime catalog's normalized rules for each pack target to match the pinned pack's rules exactly. The pack digest covers each model's pricing_version; a combined catalog can retain its own aggregate version without changing those per-model rules.

Related#

• Spend executor contract
• Gongbu execution
• providers.toml reference
• Upgrading to v0.2.5