@routerlab/core

The routing engine for routerlab — cost-quality routing for LLM APIs with open Pareto frontiers per task class.

@routerlab/core picks the cheapest LLM model that meets a quality bar (and any caller-supplied budget / latency caps) for a given task. Cost is grounded in atlas-calibrated empirical token economics rather than chars/4 proxies, and quality is predicted from a published per-task prior (or measured eval data when available).

This is the library; the @routerlab/cli package wraps it as the route command.

Install

bun add @routerlab/core
# or
npm install @routerlab/core

Quick API

import { route, predictQuality, estimateCost } from "@routerlab/core";

const decision = await route({
  task: "qa",
  prompt: "What's the capital of France?",
  qualityBar: 0.85,
  maxCostUsd: 0.005,      // optional hard budget cap
  maxLatencyMs: 2000,     // optional hard latency cap
});

console.log(decision.chosen?.model.model);
// e.g. "claude-sonnet-4-6"

for (const fb of decision.fallback) console.log("fallback:", fb.model.model);
for (const sk of decision.skipped)  console.log("skipped:",  sk.model.model, sk.reason);

RouteDecision shape

type RouteDecision = {
  chosen: RoutePick | null;     // null when no candidate passes the filters
  fallback: RouteFallback[];    // ordered cheapest-next
  skipped: RouteSkipped[];      // every dropped candidate, with a reason
  request: RouteRequest;        // echoed
};

See types.ts for the full shape. RoutePick carries expectedCost, expectedQuality, reasoning, and the underlying ModelCandidate.

What's in here

• route(req) — top-level routing entry point.
• predictQuality / predictQualityWithCI — quality predictor; serves measured eval data when present, falls back to the seeded prior table (Wilson 95% CI exposed via the WithCI variant).
• estimateCost / estimateCostBatch — atlas-calibrated cost estimation. This is the load-bearing differentiation versus prior open routers: token counts come from offline counters scaled by per-provider empirical correction factors from llm-tokens-atlas, not a chars/4 proxy.
• getDefaultCandidates() — current candidate pool.
• Types — ModelCandidate, RouteRequest, RouteDecision, TaskClass, Provider, etc.

Environment overrides

| Variable | Effect | | --------------------------------- | --------------------------------------------------------------------- | | ROUTERLAB_ATLAS_RESULTS_PATH | Atlas calibration file path (read by cost.ts) | | ROUTERLAB_QUALITY_TABLE_PATH | Measured quality table path (read by quality_predictor.ts) |

When unset, the engine falls back to seeded defaults shipped in the package.

Links

• Main repo: routerlab
• CLI: @routerlab/cli
• Cost-calibration dataset: llm-tokens-atlas

License

Apache-2.0. See LICENSE.