BBramaDocs

Brama core contract: index

Core functionality contract

The root README defines Brama's outcomes. Core is the part of Brama that makes those outcomes executable and that no integration is allowed to redefine: secure HTTP ingress and exact client and agent binding, provider-neutral model, message, tool, usage and error contracts, the canonical route, alias, selector, billing-target and bounded-attempt policy, the final-use capability redemption seams, append-only retirement and quality state, and the build identity, health, statistics, CLI and read-only MCP boundaries.

Two rules run through every page below. An alias resolves to exactly one route, so when that route refuses, the refusal is the answer the caller receives. Every request ends in one result or one classified error, and the number of provider attempts behind it is stated in advance.

What this section contains

  • Wire formats and streaming — what core owns versus what integrations implement, the three accepted chat request formats, and the commit boundary that decides whether a streamed answer can still be refused.
  • Public workflows — the four ways a request reaches a provider (direct route or alias, account-owned API key, exact agent subscription, selectors), the four alias states, and task-quality collection.
  • State and failures — who owns each piece of state, the public error envelope and code table, attempt counts, completion and cancellation, resource ceilings, and how the contract evolves.
  • Authorization and observability — what startup configuration and the route registry document must satisfy, how identities and secrets are handled, and the bounded fields a routing event records.
  • HTTP API — the endpoint reference, including GET /v1/aliases and the admin route endpoints.
  • brama routes migrate — how an existing registry document reaches the current shape.
  • Errors — the full public error reference.
  • Architecture — how these seams are built inside the gateway.