Glossary

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.

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, 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.

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.

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, vision, reasoning, and structuredOutputs. 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.

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

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