What is Brama¶

What is Brama, and what is the mental model for reading everything else in these docs? Brama is Wisent's serving-time LLM gateway: one OpenAI-compatible endpoint that owns client identities, logical model aliases, provider capabilities, and subscription entitlements, so callers never hold provider credentials or provider-specific clients. The whole product is three moving parts — identities and aliases that declare, provider capabilities and subscriptions that pay, and a bounded dispatch that records what happened.

Identities and aliases declare¶

Every request enters through one Axum ingress that validates transport, bearer, model allowlist, and request limits before any provider is considered. A client is a dedicated bearer bound to a client_id, an optional agent_id, and an optional exact model allowlist; a bearer the process does not recognise is resolved against Skarbiec, the authority that issued it, and desktop user sessions are resolved against Wisent Identity. The names callers use are deployment-owned: five exact wisent-backend/* aliases whose shapes are a promise (an embeddings alias is never handed a chat model), operator-invented aliases, the subscription alias best, and canonical provider/model routes. Agent callers may also use the selectors any, any-vision-capable, and task:<task-name>. The declarations are in concepts/client-identity and concepts/alias.

Capabilities and subscriptions pay¶

Brama holds no secret at rest. A direct provider credential is redeemed through the local Skarbiec capability socket immediately before the HTTP call, or read from a zeroizing in-memory map in standalone desktop deployments; subscription credentials form one shared vault pool, are discovered through the entitlements router by vault tags, and are redeemed at the same final-use boundary. Which account pays is explicit: a direct route spends the deployment's provider capability, best and the selectors spend an eligible subscription from the shared pool, and billingTarget names an exact subscription. Signed identity authenticates and attributes the caller; provenance tags govern retirement rather than restricting routing. An explicit target is never quietly replaced with another account. The two pools are concepts/capability and concepts/subscription; who may spend what is concepts/entitlement.

Bounded dispatch records¶

Candidate and credential selection follow the core request contract: a selector walks its ordered model candidates and each route's finite eligible credential list. Brama adds no elapsed-time cutoff. Once a stream commits, nothing is retried on any credential — a second attempt would double both the bill and the text. What happened is recorded: structured logs carry routing mode, selected route, attempts, and outcome in the fleet's wisent-errors envelope; the subscription usage ledger keeps measured tokens and the plan windows each provider itself reported; the append-only journal keeps retirement and task-quality records and never credential material. The contracts are in errors, concepts/envelope, and concepts/subscription.

What Brama is not¶

Brama routes model requests and nothing else. It does not run agent runtimes — Jeden is the runtime; Brama performs provider HTTP requests only. It does not decide where anything runs: Stado owns placement and stages the owner-only inference route snapshot Brama reloads per request. It is not a secret store: Skarbiec is the authority for credentials, and Brama receives only capability handles until the final-use seam. It is not an identity provider, billing ledger, or system of record for provider accounts, and it never infers task intent from prompt text — task: uses previously recorded, explicitly named quality evidence only. The boundaries and data flow are drawn in architecture.

The first three commands¶

brama detect

Reads local hardware and prints a model recommendation. It performs no provider request, reads no credential, creates no state, and costs nothing — the safe first command on any machine.

curl -s http://127.0.0.1:8080/health

Liveness only, and its body says so (dependencies: "not_probed"): it answers ok from a gateway whose every credential redemption is being refused.

curl -s http://127.0.0.1:8080/readyz

The one that answers whether the product works. It redeems one capability per configured provider and one credential per active subscription, and returns 503 naming what failed, with no secret in the body. The full path from nothing to a first completion is quick-start; the whole HTTP surface is http-api; an executed end-to-end scenario is walkthrough-subscriptions; and when something looks wrong, start from the runbook.