ai-lcr weekly downloads statistics

AI-LCR — AI Least Cost Routing

<p align="center"> <b>English</b> · <a href="./README.zh-CN.md">简体中文</a> </p> <p align="center"> <b>Automatic least-cost routing for LLM calls. One line to cut your AI bill.</b> </p> <p align="center"> <a href="https://www.npmjs.com/package/ai-lcr"><img src="https://img.shields.io/npm/v/ai-lcr.svg" alt="npm version"/></a> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"/> <a href="https://ai-sdk.dev"><img src="https://img.shields.io/badge/built%20for-Vercel%20AI%20SDK-black?logo=vercel&logoColor=white" alt="built for Vercel AI SDK"/></a> </p> <p align="center"> <img src="assets/ai-lcr-hero.svg" alt="ai-lcr routes DeepSeek V4.1 Flash through Tokenify at peak (50% less for fresh input), fails over to DeepSeek direct on error, and returns after recovery" width="720"> </p>

The same model costs different amounts on different providers — and no single provider is cheapest for everything. ai-lcr keeps a cheapest-first list per model, routes to the cheapest healthy one (⭐ below), and falls through on failure — the way phone carriers have done Least Cost Routing for decades.

Install

npm install ai-lcr

ai (the Vercel AI SDK) is a peer dependency.

Quick start

import { createLCR } from "ai-lcr";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const kunavo = createOpenAICompatible({
  name: "kunavo",
  baseURL: "https://api.kunavo.com/v1",
  apiKey: process.env.KUNAVO_API_KEY,
});
const openrouter = createOpenAICompatible({
  name: "openrouter",
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const lcr = createLCR({
  autoSort: true, // sort each model's providers cheapest-first by `cost`
  models: {
    // One logical model, served cheapest-first across providers.
    "gemini-3-flash": [
      { model: kunavo("gemini-3-flash"), label: "kunavo", cost: { input: 0.40, output: 2.40 } },
      { model: openrouter("google/gemini-3-flash-preview"), label: "openrouter", cost: { input: 0.5, output: 3.0 } },
    ],
  },
  // See exactly what each call cost, on whichever provider served it.
  onCost: ({ provider, costUsd }) => console.log(`${provider}: $${costUsd.toFixed(6)}`),
});

const { text } = await generateText({
  model: lcr("gemini-3-flash"),
  prompt: "Explain Least Cost Routing in one sentence.",
});

cost and label are optional — pass bare models (kunavo("gemini-3-flash")) if you don't need cost accounting or autoSort. lcr("gemini-3-flash") returns a standard AI SDK model, so it works with generateText, streamText, generateObject, tools, and agents.

Route to a model vendor's own API (native providers)

A "provider" doesn't have to be an aggregator. A model vendor's own official API is just another entry in the list. Any AI SDK provider package returns a standard model, so a vendor's native API and an OpenAI-compatible reseller sit side by side in the same list:

import { createLCR, DEFAULT_PROVIDERS } from "ai-lcr";
import { createDeepSeek } from "@ai-sdk/deepseek";          // DeepSeek's own API
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const deepseek = createDeepSeek({ apiKey: process.env.DEEPSEEK_API_KEY });
const tokenify = createOpenAICompatible({
  name: "tokenify",
  baseURL: DEFAULT_PROVIDERS.tokenify.baseURL,
  apiKey: process.env[DEFAULT_PROVIDERS.tokenify.apiKeyEnv],
});

const lcr = createLCR({
  models: {
    "deepseek-v4.1-flash": [
      { model: tokenify("deepseek/deepseek-v4.1-flash"), label: "tokenify" },
      { model: deepseek("deepseek-flash"), label: "deepseek" },
    ],
  },
});

DeepSeek's official rates change between peak and off-peak hours. The example above favors Tokenify for V4.1 Flash, with direct access as a fallback. To attach the right price to every request, use createTimeRoutedModel with isDeepSeekPeak and two createLCR configurations with the matching DEEPSEEK_PRICES values; see the copyable Tokenify setup. Static autoSort alone cannot select by time of day.

The same pattern works for any vendor's native SDK provider — @ai-sdk/anthropic, @ai-sdk/google, @ai-sdk/openai, @ai-sdk/xai, and so on. ProviderEntry accepts AnyLanguageModel — a duck-typed interface (doGenerate + doStream + provider + modelId) that any AI SDK model satisfies regardless of spec version (V2 or V3), so you never need as-casts at the integration boundary. Native APIs are narrow (only that vendor's models) but featureful; aggregators are broad.

If you prefer the same "no copied env-var names" style as DEFAULT_PROVIDERS, use the optional native-provider loader. Install only the official SDKs you route to:

npm i @ai-sdk/anthropic

import { createLCR, createOfficialProvider } from "ai-lcr";

const anthropic = await createOfficialProvider("anthropic");

const lcr = createLCR({
  autoPrice: true,
  models: {
    "claude-sonnet": [
      { model: anthropic("claude-sonnet-4-6"), label: "anthropic" },
    ],
  },
});

Supported native keys: anthropic, openai, google, xai, mistral, deepseek, cohere, groq, perplexity, fireworks, togetherai, cerebras, azure, google-vertex, and amazon-bedrock. Their packages are optional peer dependencies, so unused vendors add no runtime requirement.…