Where it goes
Contoso keeps dev-claude-sonnet in models/dev-claude-sonnet.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Model resources.
Limits
A Model change goes through a proposal like any other change. A new Model, added markings, or a changed region, provider or route widens access, so the security officer approves it.
Fields
The keys under spec. Nested shapes follow ModelSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
kind | Required | enum: chat, embedding, reranker, decision, extraction, evaluation, planner |
provider | Required | kebab |
model | Required | string |
version | Required | string |
region | Required | kebab |
markings | Required | markingList |
audiences | Optional | principalList |
priority | Optional | integer |
rpm | Optional | integer |
tpm | Optional | integer |
reasoning | Optional | enum: none, low, medium, high |
timeout | Optional | duration |
price | Optional | object |
caps | Optional | object |
fallback | Optional | array |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
10.5 Model (the approved model matrix)
Which model may receive which evidence is part of the security model, so the approved model matrix (F13) is GOL: one Model per entry, a flat resource with a kebab name, referenced as model:<name> by a Capability's models, a deployment's model pins and the kill switch. A model change is a proposal like any other: owners approve it, the security officer approves it when it widens, and it takes effect when a version that carries it is published and deployed. Decided 2026-09-23 (Waseem).
kind: Model
metadata: { name: eu-gpt-5-2026-08, title: GPT-5 (EU), owners: ["team:platform"] }
spec:
kind: chat # chat | embedding | reranker | decision | extraction | evaluation (Drift's judge) | planner
provider: openai
model: eu-gpt # the gateway's route name
version: gpt-5-2026-08 # the exact provider model, never an alias
region: eu
markings: ["marking:legal", "marking:pii"] # what it may receive; evidence with any other marking never reaches it
audiences: ["audience:emea-procurement"] # optional; empty means everyone
priority: 30 # lowest routes first; the first embedding Model is the pinned embedding entry
rpm: 60
tpm: 600000
reasoning: none # optional: none | low | medium | high, how hard a thinking model reasons
timeout: PT3S # optional, a reranker's time bound (3 s when left out)
price: { input: 0.002, output: 0.008 } # EUR per 1,000 tokens; optional cacheRead, cacheWrite
caps: { "department:procurement": 500 } # department spend caps; the smallest any approved Model names applies
fallback: ["model:dev-claude-sonnet"] # tried in order when this one fails before its first token
A Model of kind: reranker is a cross-encoder that re-orders the top authorised documents of a retrieval (100 by
default, one passage each, the server's GLUON_RERANK_CANDIDATES) through the gateway's /rerank route, when the
request's Capability and deployment pins allow it. A passage is sent only when the Model's markings cover all of the
passage's markings, and only as the masked text the answer model would see; any other passage keeps its rank. A failed
call or one over the Model's timeout (3 s when left out; decided 2026-10-22, Waseem, for a self-hosted reranker over
100 documents) keeps the retrieval order and the trace says why. With no reranker Model, retrieval is unchanged (F29,
2026-10-17).
- Prompt cache prices (decided 2026-10-22):
price.cacheReadandprice.cacheWriteare EUR per 1,000 prompt tokens read from and written to the provider's prompt cache. Left out, a read is charged atinputand a write at 1.25 xinput, so spend is never under-reported. Gluon marks cache breakpoints only for providers that cache (Anthropic, directly or through the gateway). - Extraction (decided 2026-09-23) is its own kind: the models a miner's governed extraction (
/api/mining/extract,docs/features/Mining.md) may send corpus text to in bulk, approved apart from the chat models. It routes like chat: markings, pins, kill switch and holds. - Reasoning (decided 2026-10-17, F28 decision 19) tells a thinking model how hard to reason:
noneturns thinking off (notoff, a YAML 1.1 boolean,GLN-E005); the gateway sends it as the OpenAIreasoning_effort, which Ollama, vLLM and LiteLLM read too; a provider without the setting ignores it. Left out, the provider's default holds.nonelets a thinking model answer or grade without spending its token budget on thinking. - Evaluation (decided 2026-10-15, F28) is its own kind: the models Drift's judge, model verifier and conflict detector call to grade answers, under the department
department:driftand the same marking rules as any call. Pick one from another model family than the one answering, so no model grades itself. Without an approved evaluation Model, the judged Drift metrics are not applicable. - Planner (decided 2026-10-22, Waseem) is its own kind: the answer's planning calls (the search queries, the wide pick, the search loop's turns and the Fast-to-Accurate sufficiency check, plus the context planner and the claims judge) go to an approved planner Model, so a cheap model can plan while the answer stays on the chat model. It takes the connections chat takes and routes like chat: markings, pins, kill switch and holds. A planning call tries
planner, thendecision, thenchat, each when the one before has no Model approved for the request and every marking of the prompt; without a planner Model, planning runs as before. A Capability that namesmodelsmust list the planner Model too, or it never routes for that Capability's answers. - Markings are a set, not a rank. "The highest marking it may receive" is the set of markings it may receive: markings are not ordered, so a fallback with an "equal or higher" marking is one whose
markingsinclude every marking of this Model. A fallback to anything else isGLN-E591; a fallback to itself or to another kind of model isGLN-E592. Both are security errors a convention cannot lower. - Routing takes the first available entry (priority, then name) that serves the audience, is in the request's pins, is not held by the kill switch or a shadow-run hold, and may receive every marking of the evidence; then only the fallbacks that entry names, filtered the same way. Nothing outside the set is ever tried.
- Widening (pass 7,
GLN-W651, the security officer approves): a new Model, including aproposedorretiredone becoming routable; markings added; a changed region, provider or gateway route (evidence would reach another jurisdiction, processor or upstream); audiences added, or emptied (everyone). A newversionis not widening, but the runtime holds a changed or new entry (provider, version or route) from routing until the running gateway serves it and a shadow run scored the deployed matrix after that, and routes an entry only while the running gateway maps its route to exactly itsprovider/version. - What is served: the Models of the newest version any live deployment in the environment's namespace serves (one matrix per namespace, as each namespace serves its own package); before anything is deployed, the served package's.
proposedandretiredModels never route. providernames an AI connection when one exists with that name (an admin-console setting, not GOL: the service type, its endpoint and a key-service reference to its credential,docs/features/Gateway.md). The gateway then serves the Model at the connection type's upstream (ollama_chat/<version>,azure/<deployment>, ...); a Model whose connection is disabled, keyless or in another residency is not served. Without a connection,provideris the upstream's own prefix, as before.- Not in GOL: provider keys and endpoints. Keys stay key-service references, held by the AI connection or in the gateway's environment. The gateway's route table is pushed from the connections and the approved Models, or generated from the Models into a config file (
gluon gateway-config) for air-gapped installs, with no retries, fallbacks or logging of its own either way, so nothing routes around the matrix.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.
