BBramaDocs

Brama core contract: public workflows

Public workflows

Four workflows carry a request to a provider. Each one names its inputs, the authority that decides which credential is redeemed, and the single result the caller receives. A fifth operator action, task-quality collection, produces the evidence the task: selector reads.

Workflow: direct route or alias

Inputs

  • one accepted bearer bound to a client identity;
  • an allowed logical alias or canonical provider/model route;
  • nonempty messages;
  • an optional max_tokens of at least one;
  • temperature and optional provider-neutral tool definitions.

Decision and result

Brama validates transport, bearer, allowlist, request shape, and limits before redeeming a provider capability. An alias resolves to the one deployment-owned canonical route the registry records for it. A generic canonical request with no caller-scoped fields uses Brama's direct provider capability and performs one provider attempt. The result is one buffered OpenAI-compatible response, one committed event stream, or one normalized error, as the request asked.

No subscription credential is eligible for this workflow.

Alias states

Resolution has four outcomes, reported identically by GET /v1/aliases, by brama aliases, and in the details of a refusal.

State Meaning Completion request
serving the alias names a route and that route can be redeemed proceeds
no_route the registry declares the alias without a usable destination 503 alias_unserviceable
capability_absent the route exists but no capability behind it can be redeemed 503 alias_unserviceable
routes_file_invalid the registry document was rejected, so no alias resolves 503 alias_unserviceable

Every 503 alias_unserviceable body carries details.state and details.route. An alias the registry never declared answers 404, whose details carry the same two fields. In each case the refusal is the caller's answer: the registry holds one route per alias, and no other route is attempted on its behalf. Repairing the alias is an operator action — see brama routes migrate for moving an existing registry document to the current shape, and brama adopt, which reviews one route per alias.

Workflow: account-owned API key

An authenticated Wisent user stores a remote provider credential with POST /v1/subscription-pool. The verified session determines the internal owner; account and agent identifiers in the request are neither accepted nor trusted. The provider must be a supported built-in adapter or an executable models.dev provider. local-openai is refused, because an account credential must never select the gateway host's loopback services.

The plaintext credential crosses only the request and the local Skarbiec write pipe. Brama returns its generated subscription ID, provider, status and optional label, never the key. A later canonical provider/model request made with the same Wisent session selects only active, non-retired credentials owned by that account. It never reaches the deployment's provider capability, and it never reaches another account's credential: when that account has no usable key, the request is refused. The same owner selection applies before buffered and streamed dispatch, and GET /v1/models marks availability from that account's keys.

Replacing a provider key writes the same account/provider coordinate. Deleting the returned subscription ID retires it immediately. API keys have no OAuth refresh path and no invented expiry; provider authentication, quota and rate-limit failures follow the same bounded credential-attempt policy as agent subscriptions.

Workflow: exact agent subscription

The caller supplies the three agent HMAC headers over the exact raw request body. The bearer-bound agent, signed agent, and path agent must agree where present.

The deployment alias best resolves to the one operator-selected subscription route recorded for it. It is accepted only for bearers whose model allowlist names best; the HMAC identity authenticates and attributes the caller. Eligible subscriptions come from the shared vault pool, not from per-agent provenance tags. The alias never authorizes a direct provider credential or a second route.

billingTarget contains providerId, accountId, and subscriptionId:

  • providerId must match the canonical route provider;
  • accountId is required as caller decision evidence but is not credential authority;
  • subscriptionId must resolve to an active non-retired resource in the shared subscription pool.

An explicit subscription route walks every eligible credential on that one route, ordered by what their plans have left: the maximum used fraction the provider itself reported across that credential's current windows, freest first, read from the ledger and costing no provider call. A window whose reset instant has passed counts as empty; a credential with no reading counts as free. The agent's pinned credential, when it has one that is eligible and not reporting a full window, is tried first within that same bound. A credential is redeemed immediately before each provider call. Authentication, quota, and rate-limit failures may rotate to the next eligible credential; other provider failures return immediately, because replay could duplicate cost or tool effects. Rotation stays inside the named route — it never changes which route serves the request.

Credential pinning

The credential that last served one agent on one provider is remembered in process and preferred for that agent's later requests until the earliest reset instant its windows reported — five hours when the provider named none, capped at 24 hours. The pin reorders eligible candidates and nothing else: it never adds a credential, never survives a block, a retirement, or a full reported window, and never overrides billingTarget.

Workflow: selectors

A selector is not an alias. An alias names one route; a selector asks Brama to rank eligible subscriptions in the shared pool and to try them in that order, within the bounds below.

any

Select active subscription-backed stateless routes, order them by the freest usable subscription behind each route, randomize exact ties, and try every model candidate in that order. Each candidate walks its eligible credentials until served or refused without rotation; routes of a provider whose whole pool refused are skipped unasked.

any-vision-capable

Apply the any contract after filtering to catalog models whose input modalities include image.

task:<task-name>

Use the latest active quality observation per active model. Sort by score highest first and observation time newest first; inside one score, order by plan headroom and randomize exact ties. Try every model candidate in that order.

Selectors stop at the first successful result. They do not infer task names, reuse another agent's evidence, or continue beyond the documented limits. When every candidate is exhausted, the last classified refusal is the caller's answer.

Task-quality collection

Collection is an explicit billable operator action. It requires:

  • one agent ID and task name;
  • a nonempty prompt;
  • an exact or substring expectation;
  • explicit provider-cost acknowledgement;
  • max_models named by the operator on every run, at least one;
  • explicit --persist before observations enter the journal.

Each selected model receives one request through the real agent subscription path. Collection reports per-model status and score, and stops at max_models.

Where to go next