Provider architecture

Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.

Product core and provider adapters

Noemad owns wallet identity, product API keys, model discovery, immutable quotes, payment authorization, usage attribution, receipts, and recovery. A provider adapter owns authentication to a model service, native request conversion, stream parsing, usage normalization, and safe error mapping.

The product is designed for all qualified models and modalities. Adding a provider is more than changing a base URL: authentication, content blocks, reasoning controls, tool semantics, asynchronous jobs, usage fields, and error envelopes can differ.

A modular adapter contract

type Provider interface {
    Discover(ctx Context, scope Scope) (Catalog, error)
    Quote(ctx Context, request NormalizedRequest) (PriceSpec, error)
    Invoke(ctx Context, request NormalizedRequest, out Stream) (Outcome, error)
    Lookup(ctx Context, ref ProviderReference) (Outcome, error)
    Health(ctx Context) (Observation, error)
}
// Conceptual interface. Capabilities and optional lookup support are explicit.

Keep credentials behind the product boundary

The operator’s provider key remains in server-side secret storage. A Noemad product key belongs to a wallet owner and must never be forwarded as a provider credential. A shared provider account does not make its balance, logs, files, jobs, or conversation data visible to every product user.

Every resource request is authorized against the product owner before it reaches the adapter. Provider-native IDs are mapped to owner-scoped product IDs. File and artifact access must not rely on an unguessable URL alone.

Bind the selected adapter to the quote

The quote records the provider ID, model ID, route, canonical body hash, rate snapshot, modifiers, conversion policy, enforced usage limits, maximum amount, chain, asset, merchant, allowed facilitator/proxy, and expiry. Accepted operations retain that snapshot when future rates change.

Keep the provider’s internal identity in trusted configuration. The public product is Noemad; no upstream provider is presented as its sole identity.

Preserve protocol behavior

Chat Completions, Responses, and Messages keep their documented JSON and streaming shapes. The adapter observes terminal events and usage while forwarding output; the service does not buffer an entire stream just to wait for settlement. The payment receipt is read separately after usage is final.

Distinguish first-byte, idle, and total deadlines. An HTTP 200 or a few streamed tokens do not prove complete delivery. Unknown usage cannot be billed as the approved maximum.

Fallback needs explicit permission and evidence

A new model, provider, or rate outside the approved snapshot needs a new quote. After output or a side effect is committed, or dispatch is ambiguous, do not silently repeat the operation. A request ID is useful for correlation but is not proof of provider idempotency.

Before supporting fallback, document which errors are definitively pre-dispatch, which operations can be looked up, and how costs and delivery guarantees are preserved.

Qualification checklist

1. Validate discovery with the actual scoped credential.
2. Test each endpoint, input type, supported parameter, and output limit.
3. Check JSON/SSE event order, tool history, terminal errors, and complete output.
4. Verify usage attribution and pricing, including cache and modality units.
5. Exercise disconnect, timeout, duplicate nonce, restart, and reconciliation cases.
6. Publish data handling and the exact enabled capability set.
7. Prove a second adapter can satisfy the contract without changing wallet/payment core.