Routing Rules
Since v0.2A router decides, for each request, which path it takes: which model, which tools, whether to search the web. Those decisions are usually spread through code as keyword lists, regular expressions and magic numbers. Written as LODE instead, the whole rule table becomes one typed, fingerprinted value: every change to a keyword, weight or rule order produces a new identifier, and the same file is read by every service that routes.
The files on this page are in the repository under examples/routing/.
Shape
- A snapshot has an id, an optional parent fingerprint, named text normalizers, and an ordered list of stages (one per decision point).
- A stage has a mode (
first_match,max_weight, …), integer constants (thresholds in basis points, caps), an ordered list of rules and a default outcome. - A rule has a stable
id, awhenpredicate, an optionalunlesspredicate, and what it emits (a decision, a weight in basis points, an ordered tool list).
Weights are integers in basis points, regexes are { "source", "flags" } strings, and every sequence whose order matters is a list<T>. Keyword sets are string[], so their order does not affect the fingerprint.
Schema
{
"schema": "lode",
"version": 1,
"name": "RoutingSnapshot",
"types": {
"SnapshotKind": { "kind": "enum", "values": ["routing-snapshot"] },
"StageId": {
"kind": "enum",
"values": [
"vision_need", "content_type", "agent_intent", "agent_tools", "agent_directives",
"skill_inject", "movie_stage_skill", "chitchat", "search_intent", "image_tool",
"tool_family", "reasoning_effort", "media_url_route"
]
},
"StageMode": {
"kind": "enum",
"values": ["first_match", "collect_distinct", "max_weight", "additive_score", "lookup", "layered"]
},
"NormalizerKind": {
"kind": "enum",
"values": ["lowercase", "trim", "slug", "regex_replace", "regex_mask"]
},
"Normalizer": {
"kind": "record",
"fields": [
{ "id": 1, "name": "kind", "type": "NormalizerKind" },
{ "id": 2, "name": "source", "type": "string", "required": false },
{ "id": 3, "name": "flags", "type": "string", "required": false },
{ "id": 4, "name": "replacement", "type": "string", "required": false },
{ "id": 5, "name": "setsFlag", "type": "string", "required": false }
]
},
"Regex": {
"kind": "record",
"fields": [
{ "id": 1, "name": "source", "type": "string" },
{ "id": 2, "name": "flags", "type": "string" }
]
},
"ImageUrl": {
"kind": "record",
"fields": [{ "id": 1, "name": "exts", "type": "string[]" }]
},
"Eq": {
"kind": "record",
"fields": [
{ "id": 1, "name": "field", "type": "string" },
{ "id": 2, "name": "value", "type": "string" }
]
},
"CountGe": {
"kind": "record",
"fields": [
{ "id": 1, "name": "field", "type": "string" },
{ "id": 2, "name": "n", "type": "int", "min": 0 }
]
},
"JefQuestion": {
"kind": "record",
"fields": [
{ "id": 1, "name": "type", "type": "string" },
{ "id": 2, "name": "instructions", "type": "string" },
{ "id": 3, "name": "criteria", "type": "list<string>" },
{ "id": 4, "name": "floorBp", "type": "int", "min": 0, "max": 10000 }
]
},
"Predicate": {
"kind": "variant",
"fields": [
{ "id": 1, "name": "anyKeyword", "type": "string[]" },
{ "id": 2, "name": "regex", "type": "Regex" },
{ "id": 3, "name": "imageUrl", "type": "ImageUrl" },
{ "id": 4, "name": "flag", "type": "string" },
{ "id": 5, "name": "eq", "type": "Eq" },
{ "id": 6, "name": "countGe", "type": "CountGe" },
{ "id": 7, "name": "all", "type": "list<Predicate>" },
{ "id": 8, "name": "any", "type": "list<Predicate>" },
{ "id": 9, "name": "not", "type": "Predicate" },
{ "id": 10, "name": "jefQuestion", "type": "JefQuestion" }
]
},
"ToolRef": {
"kind": "record",
"fields": [{ "id": 1, "name": "tool", "type": "string" }]
},
"PipelineRef": {
"kind": "record",
"fields": [{ "id": 1, "name": "pipeline", "type": "string" }]
},
"Emit": {
"kind": "record",
"fields": [
{ "id": 1, "name": "decision", "type": "string", "required": false },
{ "id": 2, "name": "flag", "type": "string", "required": false },
{ "id": 3, "name": "weightBp", "type": "int", "required": false, "min": -10000, "max": 10000 },
{ "id": 4, "name": "reason", "type": "string", "required": false },
{ "id": 5, "name": "tools", "type": "list<ToolRef>", "required": false },
{ "id": 6, "name": "fields", "type": "map<string,string>", "required": false }
]
},
"Rule": {
"kind": "record",
"fields": [
{ "id": 1, "name": "id", "type": "string" },
{ "id": 2, "name": "when", "type": "Predicate" },
{ "id": 3, "name": "emit", "type": "Emit" },
{ "id": 4, "name": "unless", "type": "Predicate", "required": false },
{ "id": 5, "name": "note", "type": "string", "required": false }
]
},
"Stage": {
"kind": "record",
"fields": [
{ "id": 1, "name": "stage", "type": "StageId" },
{ "id": 2, "name": "mode", "type": "StageMode" },
{ "id": 3, "name": "input", "type": "string[]" },
{ "id": 4, "name": "normalize", "type": "list<PipelineRef>" },
{ "id": 5, "name": "constants", "type": "map<string,int>" },
{ "id": 6, "name": "rules", "type": "list<Rule>" },
{ "id": 7, "name": "default", "type": "Emit" }
]
}
},
"fields": [
{ "id": 1, "name": "schema", "type": "SnapshotKind" },
{ "id": 2, "name": "schemaVersion", "type": "int", "min": 1, "max": 1 },
{ "id": 3, "name": "id", "type": "string" },
{ "id": 4, "name": "parent", "type": "string", "required": false },
{ "id": 5, "name": "normalizers", "type": "map<string,Normalizer>" },
{ "id": 6, "name": "stages", "type": "list<Stage>" }
]
}Source
{
"schema": "routing-snapshot",
"schemaVersion": 1,
"id": "rules-v0",
"normalizers": {
"lower": { "kind": "lowercase" },
"trim": { "kind": "trim" },
"mask_quotes": { "kind": "regex_mask", "source": "\"[^\"]*\"", "flags": "g" },
"strip_now": {
"kind": "regex_replace",
"source": "\\b(right now|today)\\b",
"flags": "gi",
"replacement": "",
"setsFlag": "mentions_now"
}
},
"stages": [
{
"stage": "vision_need",
"mode": "first_match",
"input": ["prompt", "attachments"],
"normalize": [{ "pipeline": "trim" }, { "pipeline": "lower" }],
"constants": {},
"rules": [
{
"id": "vision.image_attachment",
"when": { "countGe": { "field": "attachments.image", "n": 1 } },
"emit": { "decision": "vision", "reason": "image attached" }
},
{
"id": "vision.describe_phrase",
"when": { "regex": { "source": "\\b(what(?:'s| is) in (?:this|the) (?:image|picture|photo)|describe (?:this|the) (?:image|picture))\\b", "flags": "i" } },
"emit": { "decision": "vision", "reason": "asks about an image" }
}
],
"default": { "decision": "text" }
},
{
"stage": "content_type",
"mode": "lookup",
"input": ["contentType"],
"normalize": [{ "pipeline": "lower" }],
"constants": {},
"rules": [
{ "id": "ct.text", "when": { "eq": { "field": "contentType", "value": "text" } }, "emit": { "decision": "prompt" } },
{
"id": "ct.think",
"when": { "eq": { "field": "contentType", "value": "think" } },
"emit": { "decision": "prompt", "fields": { "reasoning_effort": "high" } }
},
{ "id": "ct.image", "when": { "eq": { "field": "contentType", "value": "image" } }, "emit": { "decision": "image" } },
{ "id": "ct.music", "when": { "eq": { "field": "contentType", "value": "music" } }, "emit": { "decision": "music" } }
],
"default": { "decision": "prompt" }
},
{
"stage": "agent_tools",
"mode": "first_match",
"input": ["message"],
"normalize": [{ "pipeline": "lower" }, { "pipeline": "mask_quotes" }],
"constants": { "maxTools": 4 },
"rules": [
{
"id": "tools.build_app",
"when": {
"all": [
{ "anyKeyword": ["build", "create", "make"] },
{ "anyKeyword": ["app", "website", "landing page"] }
]
},
"unless": { "anyKeyword": ["explain", "what is"] },
"emit": {
"decision": "build",
"tools": [{ "tool": "code_sandbox" }, { "tool": "file_write" }, { "tool": "preview" }]
}
},
{
"id": "tools.edit_image_url",
"when": {
"all": [
{ "imageUrl": { "exts": ["png", "jpg", "jpeg", "webp"] } },
{ "not": { "anyKeyword": ["describe", "caption"] } }
]
},
"emit": { "decision": "image_edit", "tools": [{ "tool": "image_edit" }, { "tool": "image_upscale" }] },
"note": "an image URL plus anything but a description request is an edit"
}
],
"default": { "decision": "chat", "tools": [{ "tool": "web_search" }] }
},
{
"stage": "search_intent",
"mode": "max_weight",
"input": ["prompt"],
"normalize": [{ "pipeline": "strip_now" }, { "pipeline": "lower" }],
"constants": { "floorBp": 8000, "ambiguousLowBp": 5000, "ambiguousHighBp": 7000 },
"rules": [
{
"id": "search.live_value",
"when": { "anyKeyword": ["price of", "weather in", "score of", "exchange rate"] },
"emit": { "decision": "search", "weightBp": 9500 }
},
{
"id": "search.news",
"when": { "any": [{ "anyKeyword": ["latest", "breaking"] }, { "flag": "mentions_now" }] },
"emit": { "decision": "search", "weightBp": 8500 }
},
{
"id": "search.no_web",
"when": { "anyKeyword": ["don't search", "without searching", "no web"] },
"emit": { "decision": "no_search", "weightBp": 10000 }
},
{
"id": "search.ask_classifier",
"when": {
"jefQuestion": {
"type": "binary",
"instructions": "Does answering this message need information that changes over time?",
"criteria": ["mentions a current event or live value", "asks for something after the model's training data", "otherwise answer no"],
"floorBp": 8000
}
},
"emit": { "decision": "search", "weightBp": 8000 }
}
],
"default": { "decision": "no_search", "weightBp": 0 }
}
]
}Compile and identify
lodec check rules-v0.json -s routing-snapshot-v1.lode
lodec canonical rules-v0.json -s routing-snapshot-v1.lode -o rules-v0.canonical.json
lodec fingerprint rules-v0.json -s routing-snapshot-v1.lode --id rules-v0
# → rules-v0@5a316e4bf6d7rules-v0.canonical.json is the exact typed JSON a router loads: keys sorted, rule and tool order kept, keyword sets sorted, absent optional fields omitted. Reversing two rules, reordering a tool list or changing one weight gives a different id; reordering a keyword set does not.
Evaluating
LODE does not evaluate rules; the router does. Keep the evaluator small and generic (first match, maximum weight, lookup), and keep every keyword, regex, weight and tool list in the snapshot. A router should:
- Load the snapshot once at start-up, run
check, compile the regexes, and refuse to start on any error. - Log the snapshot id (
rules-v0@5a316e4bf6d7) with every decision, together with theidof the rule that fired. - Treat a new snapshot as a new version: give it a new id and set
parentto the previous fingerprint.