Skip to manual
gluon

GOL language

Model

A Model is one entry in the approved model matrix: provider, region, the markings it may receive and its fallbacks.

Model author or developer

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.

FieldPresenceShape
kindRequiredenum: chat, embedding, reranker, decision, extraction, evaluation, planner
providerRequiredkebab
modelRequiredstring
versionRequiredstring
regionRequiredkebab
markingsRequiredmarkingList
audiencesOptionalprincipalList
priorityOptionalinteger
rpmOptionalinteger
tpmOptionalinteger
reasoningOptionalenum: none, low, medium, high
timeoutOptionalduration
priceOptionalobject
capsOptionalobject
fallbackOptionalarray

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

GOL · YAML
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.cacheRead and price.cacheWrite are EUR per 1,000 prompt tokens read from and written to the provider's prompt cache. Left out, a read is charged at input and a write at 1.25 x input, 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: none turns thinking off (not off, a YAML 1.1 boolean, GLN-E005); the gateway sends it as the OpenAI reasoning_effort, which Ollama, vLLM and LiteLLM read too; a provider without the setting ignores it. Left out, the provider's default holds. none lets 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:drift and 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, then decision, then chat, 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 names models must 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 markings include every marking of this Model. A fallback to anything else is GLN-E591; a fallback to itself or to another kind of model is GLN-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 a proposed or retired one 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 new version is 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 its provider/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. proposed and retired Models never route.
  • provider names 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, provider is 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

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

Contoso's dev-claude-sonnet Model in the designer's YAML pane, with its validation status.
Contoso's dev-claude-sonnet Model in the designer's YAML pane, with its validation status.