providers.toml reference#

providers.toml is the explicit boundary between a no-provider local profile and chargeable live-provider execution. It selects immutable provider target revisions, freezes operator-verified pricing, sets a spend ceiling, and records the exact live-spend acknowledgement.

Potential charges: setting mode = "live" does not by itself perform work, but it prepares Gongbu to send requests to configured providers after the reviewed generation is active. Verify every provider value and price against current authoritative provider documentation.

Top-level fields#

schema_version#

This is the operator-owned source schema. The rendered Gongbu provider target and pricing documents use their own service-owned schema versions.

mode#

In disabled mode, omit catalog_version, maximum_spend_minor, live_spend_acknowledgement, every [[targets]] table, and every [[pricing_rules]] table.

schema_version = 1
mode = "disabled"

Live mode requires all remaining top-level fields, at least one complete target, and at least one complete pricing rule.

catalog_version#

Choose a label that identifies the exact prices and source date used to prepare the catalog, for example operator-verified-2026-08-24. Never reuse a catalog version for different content. The rendered catalog is canonicalized and digested so an execution can retain the exact pricing snapshot it used.

maximum_spend_minor#

This is the managed Gongbu provider configuration's explicit upper spend boundary. It is not a provider price and does not create a Hubu budget. Use a conservative ceiling appropriate for this local profile.

For USD, 25 means 25 cents and 2500 means 25 dollars. Read pricing, authorization, holds, and settlement before selecting it.

live_spend_acknowledgement#

live_spend_acknowledgement = "I_ACKNOWLEDGE_LIVE_PROVIDER_SPEND"

The exact string is a deliberate safety gate, not a customizable description. It acknowledges that a valid active target can transmit chargeable work. It does not replace Hubu authorization, a budget, or the provider account's controls.

[[targets]]#

Each target records one immutable provider configuration revision for a workload/provider/adapter/model key. Live mode requires at least one target. All target fields are required, including the booleans and settings table.

targets.provider_config_version#

Never reuse a version label with changed model, credential coordinates, activation flags, or adapter settings. Gongbu rejects a version reused with different canonical content.

targets.workload_type#

Defined by Gongbu's supported contract. Use image_generation for current image adapters. It is part of the stable target key and must be a valid identifier.

targets.provider#

Defined by the configured provider integration. Use the exact normalized provider ID expected by Gongbu and the matching pricing rules. This is not necessarily the provider's display name.

targets.adapter#

Defined by Gongbu's adapter registry. Current adapter IDs include:

• gemini_image for Google Vertex AI image generation;
• gemini_developer_image for the Gemini Developer API image path;
• flux2_api for the Flux 2 API adapter;
• ideogram_image for the Ideogram image adapter;
• fixture for test/local fixture execution only.

The adapter ID must agree with targets.settings.type. Do not infer one from provider marketing text.

targets.model#

Defined by the provider and selected adapter. Use the exact provider model ID sent on requests and repeat the identical value in each matching pricing rule. Verify availability, region, API version, and billing behavior with the provider.

targets.credential#

For [opaque.provider_image], use credential = "provider_image". Gongbu resolves the referenced service and account at execution time.

targets.active#

Required boolean. true makes this the active revision for its target key. Gongbu rejects more than one active revision for the same workload/provider/adapter/model key.

Use false to retain an immutable historical revision without selecting it for new work.

targets.execution_enabled#

Required boolean. true permits a selected active revision to execute new work. false is an independent emergency/operational gate. A revision must be both active and execution-enabled to accept new work.

targets.settings#

Required tagged adapter settings. settings.type selects the service-owned settings schema and must agree with targets.adapter. settings.config contains the adapter-specific non-secret transport configuration.

[targets.settings]
type = "gemini_developer_image"

[targets.settings.config]
endpoint = "https://provider.example"
api_version = "v1"
timeout_ms = 30000

Fixture settings use only type = "fixture" and no config table. Fixture execution is not a live provider substitute.

Adapter setting fields#

The selected gongbu-server production validator is authoritative. Unknown adapter-setting fields are rejected.

targets.settings.type#

Required tag. Allowed current values are gemini_image, gemini_developer_image, flux2_api, ideogram_image, and fixture. It must match targets.adapter.

targets.settings.config.endpoint#

Required for every non-fixture adapter. Defined by the provider integration. Use the expected HTTPS API origin or base endpoint, not a documentation page. Verify the exact path behavior in the adapter's operational guide.

targets.settings.config.api_version#

Required for every non-fixture adapter. Defined by the provider. Use the exact API version supported by the selected adapter and model.

targets.settings.config.timeout_ms#

Required invocation budget in milliseconds for every non-fixture adapter. The accepted range is 1..=270000 (up to 270 seconds). It covers the complete adapter operation described by its schema, which may include submission, polling, and artifact retrieval.

targets.settings.config.max_retries#

Optional unsigned integer; defaults to 0. The only currently accepted value is 0 for every non-fixture adapter; Gongbu rejects nonzero values during provider-profile validation. Provider-level retries are not enabled even when an adapter exposes an idempotency header.

targets.settings.config.headers#

Optional map of non-secret HTTP headers, defaulting to empty. Header names are normalized by Gongbu. Do not place authorization values or provider secrets here; use targets.credential and the owning secret resolver.

targets.settings.config.project#

Required only for gemini_image. Defined by the operator's Google Cloud environment. Identifies the Vertex AI project used by the adapter.

targets.settings.config.location#

Required only for gemini_image. Defined by the provider deployment. Use a location where the selected model and project are available.

targets.settings.config.approved_artifact_hosts#

Artifact-host allowlist for provider-referenced downloads. It is optional for gemini_image and defaults to empty. It is required and must contain at least one host for flux2_api and ideogram_image. Add only provider-controlled hosts required by the adapter response contract.

targets.settings.config.poll_interval_ms#

Optional for flux2_api; defaults to 500. It is the delay between provider operation-status polls and remains bounded by the overall timeout_ms.

targets.settings.config.idempotency_header#

Optional for flux2_api. Name of the provider-supported idempotency header. Configure it only when the provider documents durable idempotency semantics for the selected operation; it is not an arbitrary client header.

[[pricing_rules]]#

Live mode uses pricing catalog schema version 2 exclusively. Every rule is immutable within catalog_version and matches one provider/model plus an optional selector.

pricing_rules.rule_id#

Required unique, non-empty stable identifier. Choose a descriptive immutable ID such as provider-model-1k. Duplicate IDs are rejected.

pricing_rules.provider#

Required normalized provider ID. It must exactly match the target's provider value.

pricing_rules.model#

Required normalized model ID. It must exactly match the target's model value.

pricing_rules.currency#

Required currency code. Schema version 2 currently supports USD; it is normalized to uppercase.

pricing_rules.selector#

Optional inline table used to distinguish prices for the same provider/model. Current image pricing supports selector = { image_size = "1k" }, with normalized 1k, 2k, or 4k values.

A selector-qualified rule must contain exactly one image price component. Define one unambiguous rule for every enabled image size. Two rules with the same provider, model, and selector are rejected.

pricing_rules.selector.image_size#

Defined by the provider's billable resolution tier and the normalized request contract. Allowed current values are 1k, 2k, and 4k after normalization. Do not use pixel dimensions unless the provider contract maps them to one of these selectors.

pricing_rules.components#

Required non-empty array of price component tables. Each unit may appear at most once in a rule. Multi-component rules represent pricing such as one image charge plus input/output token charges.

pricing_rules.components.unit#

Required. Allowed values:

• image — quantity of generated images;
• input_token — billable input-token quantity;
• output_token — billable output-token quantity.

pricing_rules.components.rate_numerator_minor#

Required non-negative integer numerator of the exact price in currency minor units per unit. Do not pre-round a fractional provider rate.

pricing_rules.components.rate_denominator#

Required positive integer denominator of the exact price in currency minor units per unit.

For a provider price of USD $0.067 per image, cents are the minor unit and the exact rate is 6.7 cents:

components = [
  { unit = "image", rate_numerator_minor = 67, rate_denominator = 10 },
]

For USD $2.50 per million input tokens, the rate is 250 cents per 1,000,000 tokens:

components = [
  { unit = "input_token", rate_numerator_minor = 250, rate_denominator = 1000000 },
]

Gongbu computes an exact rational estimate and rounds conservatively when producing an integer authorization amount. Verify both the provider's unit and whether quoted prices include every billable component.

Matching and ambiguity rules#

• Every selectable live target needs a pricing rule for its exact provider/model and request selector.
• Rule IDs are globally unique within the catalog.
• Provider/model/selector combinations are unambiguous.
• Image selectors require one image component.
• Component units cannot repeat within one rule.
• Rates cannot be negative and denominators must be positive.
• Unsupported currencies, units, selectors, or old flat pricing shapes are rejected.

After changing providers.toml#

Run doctor and render. Review the changed source files, target versions, catalog version, and affected components. Stop the whole managed stack before activating the reviewed generation. Rendering or activation never contacts a provider or performs provider work; later execution through an active, execution-enabled live target may incur charges.