A TypeScript library that routes a request across LLM providers, checks each answer against your schema, and tells the model which rule it broke before retrying or moving to the next model.
Falling back to a cheaper model is easy. Falling back safely is not: the weaker model returns prose where JSON was asked for, or drops a required field, and the failure lands in your application. So the hold line here protects your code from the model, not the other way round. An answer reaches the caller only after it has passed the contract.
Plays the six stages below in order, about 45 seconds. Scroll or press Esc to stop.
safeParse, or a plain functionFallback is the repo's own example, output verbatim. Refused is a short script I ran against the built library with mock providers. No key ran with no key in the environment, the second command in an empty project that installed only the packed library; stack traces are trimmed and paths shortened. No model was called for real anywhere on this page.
Every model in the chain carries a tier: frontier, balanced or compact. The tier decides how much scaffolding its request gets, so the same complete() call produces a different request for each model.
The asymmetry is deliberate. A compact model given a terse prompt returns prose; a frontier model given all the hand-holding does worse, because the scaffolding crowds out the task.
One contract, three requests
System prompt for compact, at temperature 0
You produce a single JSON value conforming to the "sentiment" schema.
JSON Schema:
{"type":"object","properties":{"sentiment":{"type":"string","enum":["positive","negative","neutral"]},"score":{"type":"number","minimum":0,"maximum":1}},"required":["sentiment","score"]}- Return only the JSON object. No prose before or after it. - Do not wrap the JSON in markdown code fences. - Include every required field. Do not invent fields that are not in the schema. - If a value is genuinely unknown, use the schema's allowed representation for it rather than omitting the field.
An example of the required shape. Copy the structure, not the values:
{
"sentiment": "positive",
"score": 0
}buildSystemPrompt output for the example's sentiment contract; the schema is shown on one line here. Re-running the README's example and reading what the mocks recorded: the router sent the frontier model 395 characters at temperature 0.2 and the compact model 814 at 0. No paid calls.Each call runs under its own deadline, 30 seconds by default. When a call fails, the adapter has already translated the vendor's error into one small vocabulary, so the routing logic never sees a vendor error.
maxCostUsd.apiKey option or the vendor's environment variable. A missing key fails when the provider is created, before any request.What a failed call becomes
classifyStatus, with the status codes its tests check, and the descriptions are the code's own. The run underneath is my script against the built library: the primary is a mock that never answers and the timeout is 20 ms, so the router moves on. Mock providers, no paid calls.Telling a model to return only JSON doesn't make it so, and the weaker the model the less it holds. So the parser tries the readings in order, cheapest first, and keeps the first that parses.
{…}, then the first balanced […].{"note":"}"} the first closing brace is inside a string.Seven replies Illustrative input
extractJson and its candidate generator, and the readings tried, the values and the messages are its real output. marks a line break.This is the hold line, and it protects your code: nothing a model says gets past it unless it satisfies the contract. A contract is two things, a schema the model is shown and a validate function that decides.
safeParse fits, or a hand-written function, because the interface is structural. The library depends on no validator; its tests use real zod 4 and a hand-written contract.path: message lines, because “invalid input” gives a model nothing to fix.One reply at the hold line
The model's reply, parsed Illustrative input
Kept for the repair prompt
These constraints were not met:
None. Every field passed.
Your code
Exit taken
fromSafeParser, run on these values. No model was called.A rejected answer never crosses. The model is told what it produced and exactly which constraints it broke, then asked once more. Asking again without that just re-rolls the same mistake.
One test says it in its name: the router “tells the model what was wrong, not just that it was wrong”.
What the router sent back Illustrative input
provider.calls): Repair works re-runs the README's example, Repair fails is my script where the primary repeats its mistake. Attempt lines are printed in the example's format. Mock providers, no paid calls.ClearedOnly an answer that passed the contract crosses here. Everything above happens inside the router; below this line is your code, which gets typed data or a typed failure, never a malformed answer.
Your code gets { ok: true, data, meta } with the data typed and validated, or { ok: false, error, meta } where the error is chain_exhausted, budget_exceeded or configuration. meta matters most when it failed, so it travels in the result rather than on an exception.
meta.attempts lists every call: model, tier, repair number, outcome, failure kind, problems, tokens, cost and latency.degraded means a model other than the primary served it; repairs counts repair calls. Two fields, two signals.costUsd sums every attempt, repairs and abandoned models included, so a fallback can cost more than the primary alone.Four runs, four results
meta.costUsd $0.000000
The repo's example scripts two mock providers: a primary that rate-limits, and a backup whose first answer breaks the contract. Hover or focus a line of its output to see which part of the script caused it.
examples/degrade.ts, lines 48 to 60
npm run example
Hover or focus a line above.
The repo documents no benchmarks, so none are quoted here. These numbers come from running the project's own code with mock providers on my machine.
The total counts every call, repairs and abandoned models included.
A failed repair on the expensive model plus a fallback came to about twice the primary alone. The README says as much: you are buying a valid answer with extra round trips. Mock token counts, the example's prices.
maxCostUsd is checked before each call, against what has already been spent.
So a run stops at the first check after reaching the budget, and can pass it by up to one call. Measured: a $0.005000 budget returned budget_exceeded after $0.005250. No call starts once the budget is reached.
Packed from the repo and installed into an empty project, offline.
The vendor SDKs are optional peer dependencies behind their own entry points. Importing the Anthropic adapter without its SDK fails at import with Cannot find package '@anthropic-ai/sdk', naming what to install.
Every provider is a mock or a fake client. CI sets no provider key at all, so the suite passing there shows nothing reaches a real API.
repairsPerModel: 0, and keeps degraded and repairs separate.CI runs build, typecheck, lint, the tests, coverage and the README example on Node 22 and 24.
withPricing.git clone https://github.com/ahmed-hashim-pro/llm-contract-router.git cd llm-contract-router npm ci npm run check # build, typecheck, lint, 105 tests npm run example # the fallback run, no key needed # It isn't on npm. To use it in an app, pack the build: npm pack cd ../your-app npm i ../llm-contract-router/llm-contract-router-0.1.0.tgz npm i @anthropic-ai/sdk # only for llm-contract-router/anthropic
npm pack ships the dist/ folder that npm run check builds, so run that first. Installing straight from GitHub won't work: dist/ isn't committed and no install script builds it. Keys are read only from the apiKey option or ANTHROPIC_API_KEY and OPENAI_API_KEY.