@routerlab/core

@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 { BudgetAwareRouter, 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.fallbacks) console.log("fallback:", fb.model.model);
for (const sk of decision.skipped)  console.log("skipped:",  sk.model.model, sk.reason);

Budget-aware agent loops

const budget = new BudgetAwareRouter({
  maxBudgetUsd: 0.25,
  warnAt: 0.8,
  degradedQualityBar: 0.65,
});

while (!done) {
  const step = budget.routeStep({
    task: "reasoning",
    prompt: agentContext,
    qualityBar: 0.85,
  });

  const response = await callYourModel(step.decision.chosen.model, agentContext);

  budget.recordActualUsage({
    model: step.decision.chosen.model,
    usage: {
      inputTokens: response.usage.prompt_tokens,
      outputTokens: response.usage.completion_tokens,
    },
  });
}

routeStep() caps the next decision by the remaining chain budget. After the provider call, recordActualUsage() prices the real usage with Tokenometer's runtime usage-pricing primitive. If a provider does not return usage, call recordEstimatedStep(step.decision) to account for the selected estimate.

RouteDecision shape

type RouteDecision = {
  chosen: RoutePick | null;     // null when no candidate passes the filters
  fallbacks: 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.
• BudgetAwareRouter — stateful task budget controller for multi-step agent loops. It preflights each step with routerlab and records actual or estimated spend after each call.
• 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.