Glossary

A short reference for terms used throughout the documentation. Page-level references are included where helpful.

A

Alias. The model field value sent by the client: smart-router, smart-router-flash, smart-router-pro, or smart-router-free. The gateway translates it to a real OpenRouter model ID.

Architecture freeze. A point in time at which the routing policy, the model registry, the topology, and the API surface are pinned. The v1.0.0 freeze ID is SGW-V3-DESIGN-FREEZE-2026-08-20-01. The policy freeze ID checked at runtime is SGW-BLUEPRINT-2026-08-18-01.

Auth tier. The highest identity tier: a non-empty bearer token of length > 10. v1.0.0 does not verify the token's value.

B

Budget cap. A spending limit on the gateway. Soft caps disable Pro; hard caps return STOP_FOR_HUMAN.

Budget ledger. The PostgreSQL row that tracks per-goal spend.

C

Cap. See Budget cap.

Complexity score. A 0..100 weighted score computed from eight task dimensions: reasoning_requirement, ambiguity, blast_radius, dependency_depth, tool_depth, verification_difficulty, runtime_failure, business_risk.

Cross-family fallback. An ordered list of senior solvers that substitute for Pro if Pro is unhealthy. v1.0.0 has GLM-5.2 first, then Claude 3.5 Sonnet, then GPT-4o.

D

De-escalation. The rule that the model chosen for the previous task does not become a requirement for the next subtask.

Degraded mode. A state in which PostgreSQL is unavailable and the gateway cannot enforce shared budget state. Privacy and hard rules remain; cross-request state is lost.

Decision. See Routing decision.

Dry-run. A call to /v1/route/decision that returns the routing decision without making an upstream call.

E

Emergency fallback. z-ai/glm-5.2, used only when a Pro call fails end to end after retries. Not exposed as an alias.

Explicit override. A request that forced a tier via alias, header, or marker. Wins over any non-hard rule.

F

Flash. deepseek/deepseek-v4-flash-0731. The default worker.

Free model. nvidia/nemotron-3-ultra-550b-a55b:free. Used only for the Scout and a small set of bounded public tasks.

Free-tier eligibility. The condition under which a request can be routed to the free model: non-sensitive, opt-in, and either in the gray zone (Scout) or a bounded public task kind.

Freeze ID. A string checked at startup; a mismatch prevents the gateway from booting. Two are in use: SGW-BLUEPRINT-2026-08-18-01 for the policy file and SGW-V3-DESIGN-FREEZE-2026-08-20-01 for the overall architecture.

G

Gateway. The Smart LLM Supervisor Gateway process.

Goal. A logical unit of work inside a session. Conveyed by X-Smart-Gateway-Goal or metadata.goal_id. Used to scope budget counters.

Gray zone. The complexity score band (46..64 by default) where the Scout is invoked (if non-sensitive) or a midpoint rule picks Flash / Pro (if sensitive).

H

Hard rule. A routing rule that cannot be overridden by a later, weaker rule. Includes privacy, health, budget hard caps, and high-risk task kinds.

Health state. One of HEALTHY, DEGRADED, UNHEALTHY, HALF_OPEN, DISABLED, STALE, QUARANTINE.

I

Identity tier. One of AUTHENTICATED, SIGNED_VIRTUAL, FINGERPRINT, STATELESS. Determines whether cross-request state is preserved.

Internal alias key. The gateway's namespace for models: deepseek_v4_flash, deepseek_v4_pro, nemotron_ultra, glm_5. Different from the public aliases (smart-router-flash, …) and from the real OpenRouter IDs.

L

LiteLLM. Optional upstream gateway. Not used in v1.0.0 production. Selected via MODEL_GATEWAY_BACKEND=litellm.

M

Marker. A substring that, when present in the instruction, forces Pro. Examples: /pro, [reasoning:high], "think deeply".

Model ID. The real OpenRouter ID. Not what clients should send; clients send aliases.

O

OpenRouter. The single upstream provider. Holds the four frozen model IDs.

Override. See Explicit override.

P

Privacy gate. src/smart_gateway/privacy_gate.py. Scans message content for secrets, redacts them, and upgrades sensitivity.

Pro. deepseek/deepseek-v4-pro-0813. The senior solver.

Provider. The upstream model host. In v1.0.0 only OpenRouter.

R

Real ID. See OpenRouter ID.

Request. A single HTTP call to /v1/chat/completions.

Routing decision. The structured object produced by policy.decide: action, model, purpose, cause, score, confidence, hard_rule, sensitive_block_applied, evidence, policy_version.

Runtime state. The signals extracted from the conversation history: attempts, flash_attempts, same_error_count, failure_class, files_touched, tool_depth.

S

Same error. Two errors with the same normalized signature (UUIDs, timestamps, line numbers stripped). Triggers hard Pro at 2.

Scout. The free Nemotron model invoked in the gray zone. Its recommendation is advisory only.

Sensitive. The default state for new requests. Free models cannot receive sensitive content.

Session. A logical coding session. Conveyed by X-Smart-Gateway-Session or metadata.session_id.

Scoring. See Complexity score.

Stop_for_human. A STOP_FOR_HUMAN routing decision; the gateway returns HTTP 403 with a detail that names the cause.

Streaming. Server-Sent Events from /v1/chat/completions when stream=true.

Structural failure. A failure class that indicates a parsing or interpretation problem (SyntaxError, ImportError, …). Triggers immediate hard Pro.

Subtask. A bounded unit of work inside a goal. Counters are reset between subtasks.

T

Task. A unit of work that can span multiple requests. Conveyed by X-Task-Id or metadata.task_id.

Task kind. One of CODING, DEBUG, ARCHITECTURE, SECURITY, AUTH, PAYMENT, DESTRUCTIVE_MIGRATION, TEST, SUMMARIZE, CLASSIFY, PUBLIC_REVIEW, RESEARCH, OTHER.

U

Upstream. OpenRouter.

Upstream ID. See OpenRouter ID.

V

v1.0.0. The first production release. Tagged on commit 7e0d24f. Architecture freeze SGW-V3-DESIGN-FREEZE-2026-08-20-01.

W

Worker. Flash.