TeamShared AutoRouter

1. Prefilter

   deterministic · latest user turn only · no model call

   The latest user turn is lowercased, stripped of punctuation and emoji, and whitespace-collapsed, then compared against two short word tables. Earlier turns are ignored on purpose: a thanks after a hard thread must not pay for a scoring hop or a frontier model. Size is measured over the whole request — system prompt, tool schemas, tool-call arguments, tool results, and 340 characters for every image — because the model has to read all of it whatever the user turn says.

   Latest user turn	Route	What the response says
   Empty, with no system or developer message carrying a task	Short-circuit: a one-word ok completion, no model called	prefilter: "empty" X-TeamShared-Attempts: 0 X-TeamShared-Upstream-Model: prefilter
   ping, healthz, status, ready and six more	Short-circuit	prefilter: "health"
   Tool results with no user text and no instructions anywhere	Short-circuit	prefilter: "tool_ping"
   Whole request over 160,000 characters	Rung 4, scoring skipped: a terse follow-up to a huge thread would otherwise score as easy	prefilter: "size-floor" reason: "large context"
   thanks, ok, lgtm, got it, np and the rest of the acknowledgement table	Rung 1, scoring skipped	prefilter: "ack" difficulty: 1
   Whole request over 32,000 characters	Scored as usual, then floored: a score below 3 becomes 3	bumped: true reason: "large context"
   Anything else	Scored	—

2. Classify

   one scoring hop · 2 s budget · cached 3,600 s

   The scored text is the latest user turn — its last 8,000 characters — plus up to 1,500 characters of earlier user turns, most recent first, so a follow-up like now do all of them still reads as one request. Images become the token [image] in the scored text only; what is forwarded upstream is untouched. With no user turn at all, an agent whose task lives in its system prompt is scored on that prompt instead. The classifier is asked for six things and never for a model id:

   {"difficulty": 3, "task": "code", "confidence": 0.8, "risk": "low", "needs_tools": false, "output": "medium"}

   difficulty is scored by the work involved, on the rubric printed with the ladder below. task is one of eleven kinds: chat, lookup, rewrite, translate, code, sql, math, security, research, creative, other. risk is the cost of a too-cheap route — high for security, irreversible, legal or medical work, or when the classifier is guessing. Which model scores is deployment configuration: a general model answering in JSON, a typed decision endpoint that returns a probability distribution over the five levels, or an in-process heuristic that costs nothing and makes no network call.

   A hop that overruns its 2-second budget, fails, or returns something unparseable does not guess. The request snaps to rung 3 with fallback: true and a reason of classifier unreachable or snapped to tier default. Successful scores are cached for 3,600 seconds against a whitespace- and case-insensitive hash of the scored text, 2,048 entries deep, so a retried or regenerated turn routes for free. A snapped fallback is never cached: it is not a decision worth repeating.

3. Gate

   no network · at most one rung

   An unsure score buys headroom rather than a coin flip. Each of the signals below moves the assignment up one rung, and one rung in total however many of them fire, capped at 5. A rung the prefilter assigned, or a snap to the middle because scoring failed outright, is left where it is. A bump is looked up in the roster again at the new rung, so a specialist that claims the task only at the lower rung gives way to whichever model claims it at the higher one.

   Signal	Effect	What the response says
   confidence below 0.55	Up one rung	bumped: true X-TeamShared-Route-Bumped: 1
   risk of high	Up one rung	as above
   Where the classifier returns a distribution: more than 0.15 of the probability mass sitting on scores cheaper than the winner	Up one rung	as above, plus the distribution itself under classifier_detail

4. Constrain

   no network · capability walk · size floor · sticky loops

   What the request needs is read from the body, not guessed: tools when a tools list is present and tool_choice is not "none", or when the history already carries tool traffic; images when any content part is one; structured outputs for response_format of type json_schema and JSON mode for json_object; and a context estimate of one token per four characters plus the max_tokens you sent, or 4,096 when you sent none. A rung fits when it has every capability and estimated input plus output is at most 0.9 of its context window.

   Before the walk, the number and the task have already been resolved to one model, in a fixed order: a per-task routing table entry, when one is configured, wins and says so with table_hit: true; otherwise the roster specialist that declares that task at that rung; otherwise the rung's generalist. The response names the row that won with role. The walk starts at that model and moves up the ladder, then down — never to a cheaper model first. A specialist sits beside its rung rather than on it, so one that cannot take the request hands it to its own rung's generalist, which then walks as usual: the math specialist has no image input, so a math question with a chart in it is answered by rung 3's generalist with capability_bump: "images". Where the walk lands is reported as capability_bump, naming what the assigned model lacked: tools, images, structured outputs, json mode or context. When nothing on the ladder fits, the answer is 400 no_capable_model rather than a quietly truncated prompt.

   A request that continues a tool loop — its last message is a tool result, or an assistant turn carrying tool_calls — reuses the model that answered the loop's first turn instead of re-scoring every step. The loop is keyed on the caller, the chat id and every message up to the last user turn, and the pin lives 1,800 seconds. If the loop's context has grown past what that model can take, the pin is dropped with reason: "sticky broken: context"; otherwise the response carries sticky: true and X-TeamShared-Sticky: 1.

5. Complete

   one upstream call · connect 5 s · read 120 s · HTTP/2

   Your original messages go to the chosen model with your bearer swapped for the router's own provider key; your token never leaves this host. Before the first byte, a connect failure or a 408, 429, 500, 502, 503 or 504 is retried 1 more time with backoff capped at 2 seconds — an upstream Retry-After is honoured up to the same cap — and then the next model is tried: a specialist falls back to its rung's generalist, a generalist to the adjacent rung — one up, or one down from rung 5. After the first byte nothing is replayed. X-TeamShared-Attempts counts every try, and X-TeamShared-Assigned-Model names the model that actually answered.

   A non-streamed answer is then checked before it is returned. Five things make it unusable:

   Kind	Test
   empty	No text and no tool calls, with finish_reason of stop
   truncated	finish_reason of length below the max_tokens you asked for
   bad_tool_call	A call to a function you did not declare, or arguments that are not JSON
   bad_json	A json_object or json_schema answer that does not parse, or misses a required key of the schema
   refusal	A refusal field, or a short answer opening I'm sorry, I can't help, As an AI

   An unusable answer buys one more completion one rung up for the same task — the next rung's specialist when one claims the task there, else its generalist — or one down when it was already at the top. If the second passes it is returned with X-TeamShared-Escalated naming the kind that failed; if it does not, the first answer comes back as it was. A stream is already flushing by the time any of this could be known, so it is returned as it stands — its routing rides on the response headers, and stream_options.include_usage is added so it is metered like everything else.

One scoring hop, then one completion — a second only when the first will not answer or comes back unusable. This is a completions gateway, not an agent loop: nothing here runs tools, keeps memory, or calls a model twice on your behalf beyond that.

This is gating, not voting: once the score and the task are known exactly one model is asked. A per-task routing table entry wins when one is configured; otherwise a specialist that declares that task at that rung; otherwise the rung's generalist. A specialist at rung 3 answers the tasks it declares when they score 3, and nothing that scores 2 or 4. The classifier never sees this table — it describes the request, and the router picks the model — so editing the roster never requires re-tuning the classifier. The Basis column is the honest part: declared means the role and its strength are a prior written into the roster by hand, not a measurement. scripts/build_labels.py --roster runs a labelled prompt set through all ten models and judges each answer, and scripts/build_quality.py turns the passes into per-task, per-difficulty pass rates that outvote the declaration as they accumulate. The response names the row that answered: router.role and X-TeamShared-Role carry the specialist's role, and are empty and absent when a generalist answered.

The rubric on the left is the one the classifier is scored against, verbatim. Both tables are generated from the ladder and the roster this deployment routes on, not written by hand, and the prices are list, per million tokens, from the model catalog the router ships and refreshes. What you are billed is the cost the upstream reports for your own call, which is the number the ledger records. Neither table is an allowlist: any model the router carries still routes by explicit id whether or not it has a row.

Every routed request also writes one structured decision line on the router's side. Your prompt is never written to it verbatim: it is hashed after lowercasing and collapsing whitespace, and the request is otherwise described by counts, lengths and the decision itself. The one field to know about is reason, which is copied from the classifier's own output — a classifier that quotes the prompt back puts that quote in the line.

OpenRouter's own model fallbacks pass through: send models as a list of router ids — openrouter/google/gemma-4-31b-it:free then openrouter/deepseek/deepseek-v4-flash, say — and OpenRouter tries them in order when the first rate-limits or is down. The router strips the prefix, drops ids on other prefixes, and drops the list entirely for non-OpenRouter upstreams.