# Glossary

> Definitions of the core AI Gateway concepts.

URL: https://boelabs.com/en/docs/ai-gateway/glossary
Language: English

This vocabulary is part of the project's contract. It must be used consistently across TypeScript,
SQL, OpenAPI, documentation, logs, and admin tooling.

## Public Endpoint

The route a client calls, with the exact contract of that API. Examples:
`/v1/chat/completions`, `/v1/responses`, `/v1/messages`, and `/v1/images/generations`.
A public endpoint does not determine the protocol used against the provider.

## Operation

The semantic product a model offers: `text.generate`, `image.generate`, `image.edit`,
`audio.transcribe`, `embedding.create`, etc. It is the stable vocabulary of the catalog and the admin
API. The presence of an operation in `catalogEntry.operations` declares support.

## Public Model

The name the client sends in `model`, for example `general` or `image-default`. All deployments with
the same `publicModel` automatically form its pool. There is no separate table or entity for that
pool: the router derives it from `model_deployments.public_model`.

Do not use **Model Group**. The correct concept is **Public Model**; when referring to its deployments
collectively you may say **deployment pool**.

## Deployment

An executable route to a provider. A `model_deployments` row holds `publicModel`, adapter,
`upstreamModel`, encrypted credentials, `transportOverrides`, status, weight, and limits. Retries and
cooldowns belong to the individual deployment.

## Routing Strategy

The algorithm the router uses to pick one deployment from a pool: `simple-shuffle`, `least-busy`,
`usage-based-tpm`, `usage-based-rpm`, `latency-based`, `throughput-based`, `price-based`, or
`health-aware`. Configured globally via `PUT /admin/router-settings`, not per-deployment or
per-request. See [Routing](https://boelabs.com/docs/ai-gateway/routing).

## Upstream Model

The exact identifier the adapter sends to the provider. It may differ from `publicModel`, and several
upstream models or providers may serve the same Public Model.

## Adapter

Code that implements canonical handlers and knows how to translate them to one or more upstream
transports. It declares `supportedCallTypes`, `transports`, and the available handlers. The provider's
catalog lives next to the adapter; if it is missing, that provider is not registered.

## Transport

The protocol an adapter uses against the provider: `chat_completions`, `responses`,
`generate_content`, `messages`, `images`, `audio_transcriptions`,
`azure_audio_transcriptions_legacy`, `embeddings`, `embed_content`, `openrouter_rerank`, or
`cohere_rerank`.
The type is `UpstreamTransport`, in `src/core/transport.ts`, and the execution context uses
`ctx.transport`.

`embeddings` is the OpenAI-compatible `/embeddings` transport; `embed_content` is Google Gemini's
native transport for `:embedContent` and `:batchEmbedContents`.

`openrouter_rerank` is OpenRouter's native `/rerank` contract; `cohere_rerank` is the internal
Cohere-compatible `/rerank` transport used by Vercel AI Gateway. Both normalize into one canonical
rerank operation.

`transportOverrides` lets you replace the adapter's default transport per operation. Do not use the
former names **wire** or **bindings**.

## Catalog Entry

A declarative 1:1 description of an upstream model: operations, profiles, reasoning, limits,
and pricing. A known model uses its adapter's `catalog.json`. A custom model
must send a complete `catalogEntry` when creating its deployment.

## Reasoning Spec

A catalog entry's declaration of *how* a model controls reasoning: `kind` (one of eight wire
mechanisms — `openai_effort`, `openai_body`, `anthropic_adaptive`, `anthropic_budget`, `gemini_level`,
`gemini_budget`, `chat_template_flag`, `fixed`), `levels` (which rungs of the canonical
`none < minimal < low < medium < high < xhigh < max` ladder it accepts), and kind-specific config
(`bodyField`, `chatTemplateFlag`, `budgets`, `upstreamEffortMap`). See [Reasoning](https://boelabs.com/docs/ai-gateway/reasoning).

## Parameter Policy

The operator-configured behavior (`unsupportedParameterStrategy`: `drop`, `error`, or `allow`) for a
request parameter a target deployment's catalog entry declares unsupported. Global, via
`PUT /admin/router-settings`; applies only to the chat-shaped endpoints. See
[Parameter policy](https://boelabs.com/docs/ai-gateway/parameter-policy).

## Operation Profile

The configuration of a specific operation within `catalogEntry.operations`. For example, an image
profile declares formats and sizes; a transcription profile declares response formats; a rerank
profile declares document modalities and request limits.

## Capabilities

The reserved name for the concrete feature flags of `text.generate`: `tools`, `strictTools`, `vision`,
`reasoning`, and `structuredOutputs`. `strictTools` specifically means that the provider guarantees
function arguments conform to their declared schema. It does not mean "list of operations" nor
"adapter handler".

## CallType

The internal category that connects executable operations with the router and the handlers.
It is not an admin contract nor a product name. New code should start from `Operation`; the runtime can
derive its `CallType` via `operations/registry.ts`.

## Canonical

The provider-agnostic internal representation in `src/core/canonical.ts`, `images.ts`, `audio.ts`, and
`embeddings.ts`, and `rerank.ts`. Public contracts are converted to canonical types; adapters convert between those
types and their Transport. Do not use **Unified**.

## Message State

Opaque provider state bound to an assistant turn rather than to one of its tool calls, such as a
Gemini signature on a text response or Claude's signed `thinking` blocks. Where a public endpoint has no native carrier for it, the
gateway seals it into a `reasoning` item whose `encrypted_content` starts with `bfrs_`; clients
replay it and nothing is stored. See [Provider-specific fields](https://boelabs.com/docs/ai-gateway/provider-specific-fields).

## Fallback Policy

An ordered chain of Public Models identified by `(primaryModel, reason)`. `reason` is `general`,
`context_window`, or `content_policy`; it is not an operation. Each target represents its deployment
pool and receives the same pool-wide retry budget as the primary.

Do not use the former field **kind** for fallbacks. `kind` is still valid in domains where it does
discriminate a variant, such as reasoning controls or canonical events.

## Virtual Key

A client credential with its own limits and budget. `allowedModels` holds the permitted Public Models;
`[]` means access to all of them.

## Flow

```text
Client -> Public Endpoint -> Canonical request
       -> Public Model -> deployment pool -> Deployment
       -> Transport -> provider -> Canonical response
       -> Public Endpoint contract -> client
```