ai-lcr 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# 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 each model to its own cheapest provider — Gemini to Kunavo, DeepSeek to OpenRouter, Seedream to fal, Flux Schnell to Runware — and falls back on failure" width="820">
+</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](https://en.wikipedia.org/wiki/Least-cost_routing) for decades.
+
+## Install
+
+```bash
+npm install ai-lcr
+```
+
+`ai` (the Vercel AI SDK) is a peer dependency.
+
+## Quick start
+
+```ts
+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.35, output: 2.1 } },
+      { 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.
+
+## How it routes
+
+1. **Cheapest first.** Providers are tried in order — list them cheapest-first, or set `autoSort: true` to order them by `cost` automatically.
+2. **Fall through on failure.** On a retryable error (rate limit, 5xx, timeout) it advances to the next provider, streaming-safe. Hard errors (400, 401, 403, 422) pass through immediately.
+3. **Recover.** After an idle window (`resetIntervalMs`, default 60s) it snaps back to the cheapest provider.
+
+<p align="center">
+  <img src="assets/ai-lcr-routing.svg" alt="routing diagram: cheapest first, fallback on failure, recover after idle" width="820">
+</p>
+
+## Supported providers
+
+Any OpenAI-compatible endpoint works.
+
+- **Text:** [OpenRouter](https://openrouter.ai) (widest coverage, list pricing) · [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) (**30% off** every model)
+- **Image / video:** [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) (**30% off**) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — routing on the roadmap
+
+## Text model pricing
+
+USD per 1M tokens, input / output. Official rates as of 2026-05 — verify current rates with each provider. OpenRouter passes list price through; Kunavo is a flat 30% off the official rate.
+
+| Model | Official (in / out) | OpenRouter | [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) | Cheapest |
+|---|---|---|---|---|
+| Gemini 3 Flash | $0.50 / $3.00 | no discount | −30% | ⭐ Kunavo |
+| Gemini 3 Pro / 3.1 Pro | $2.00 / $12.00 | no discount | −30% | ⭐ Kunavo |
+| Gemini 2.5 Pro | $1.25 / $10.00 | no discount | −30% | ⭐ Kunavo |
+| Gemini 2.5 Flash | $0.30 / $2.50 | no discount | −30% | ⭐ Kunavo |
+| Claude Sonnet 4.6 | $3.00 / $15.00 | no discount | −30% | ⭐ Kunavo |
+| Claude Haiku 4.5 | $1.00 / $5.00 | no discount | −30% | ⭐ Kunavo |
+| DeepSeek V4 | $0.43 / $0.87 | no discount | not carried | ⭐ OpenRouter |
+
+Kunavo carries Anthropic + Google. DeepSeek / OpenAI / Grok / Mistral route to OpenRouter — one config can mix them all.
+
+## Image model pricing
+
+USD per image, as of 2026-05 (provider list / retail; verify current rates). Kunavo is 30% off official. fal and Runware are compute providers — `ai-lcr` picks the cheapest per model (⭐).
+
+| Model | fal.ai | Runware | [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) | Cheapest |
+|---|---|---|---|---|
+| Nano Banana 2 | $0.080 | $0.069 | $0.047 | ⭐ Kunavo |
+| Nano Banana Pro | $0.080 | — | $0.094 | ⭐ fal |
+| GPT-Image-2 | $0.210 | $0.094 | $0.089 | ⭐ Kunavo |
+| Imagen 4 Ultra | $0.060 | $0.060 | — | ⭐ fal / Runware |
+| Ideogram V3 | $0.060 | $0.060 | — | ⭐ fal / Runware |
+| Seedream 4 | $0.030 | — | — | ⭐ fal |
+| Flux 1.1 Pro | $0.040 | $0.040 | — | ⭐ fal / Runware |
+| Flux Dev | $0.025 | $0.025 | — | ⭐ fal / Runware |
+| Flux Schnell | $0.0030 | $0.0013 | — | ⭐ Runware |
+| Qwen-Image | — | $0.0038 | — | ⭐ Runware |
+| FLUX.2 Klein 4B | — | $0.0006 | — | ⭐ Runware |
+
+## Video model pricing
+
+USD per second, as of 2026-05 — verify current rates. Video billing differs by provider, so a clean cross-provider table isn't apples-to-apples: fal.ai and Runware charge per second, while Kunavo's Veo is per clip (Fast ~$0.28 / Lite ~$0.168 / Quality ~$1.34). Below are fal.ai's per-second rates (the video workhorse in testing); a normalized fal / Runware / Kunavo comparison is a TODO.
+
+| Model | fal.ai ($/s) |
+|---|---|
+| Seedance Lite | $0.036 |
+| Hailuo 02 Standard | $0.045 |
+| LTX-2 | $0.060 |
+| Kling 2.6 Pro | $0.070 |
+| WAN 2.2 | $0.080 |
+| Veo 3.1 Lite | $0.080 |
+| Kling V3 Pro | $0.112 |
+| Seedance Pro | $0.124 |
+| Veo 3.1 (audio-on) | $0.400 |
+
+## Roadmap
+
+- [x] Own failover engine — cheapest-first routing + streaming-safe fallback, no external routing dependency
+- [x] Real per-call cost accounting (`onCost`)
+- [x] Auto cheapest-first ordering (`autoSort`) from per-provider `cost`
+- [ ] Bundled price table for zero-config pricing (drop the manual `cost` numbers)
+- [ ] Provider-quirk middleware (transparently patch known per-provider request quirks)
+- [ ] Offline capability probe (tool-calling / caching / streaming) → trust matrix
+- [ ] Image & video model routing (fal.ai / Runware / Kunavo)
+
+## Affiliate disclosure
+
+`ai-lcr` is provider-neutral and works with any OpenAI-compatible endpoint. The author holds an affiliate arrangement with **[Kunavo](https://kunavo.com/?ref=hJ2uT3iW)**, which — at 30% off official rates — is often (not always) the cheapest option, as the tables above show. Signing up through that link may earn the author a share. You're never required to use it; bring your own providers and routing works identically.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test          # mocked routing/failover tests + live Kunavo tests
+```
+
+The suite covers cheapest-first routing, failover on retryable errors (and *not* failing over on a 400), exhausting the whole chain, and a real broken-provider → Kunavo recovery. Live tests run only when `KUNAVO_API_KEY` is set in the environment; otherwise they're skipped.
+
+## Credits
+
+The streaming-safe failover approach is adapted from [`ai-fallback`](https://github.com/remorses/ai-fallback) (MIT) — reimplemented in-house so ai-lcr owns its engine and layers cost accounting + routing directly into it. Built on the [Vercel AI SDK](https://ai-sdk.dev).
+
+## License
+
+[MIT](./LICENSE) © Victor

package/README.zh-CN.md

@@ -0,0 +1,167 @@
+# AI-LCR — AI 最低成本路由（Least Cost Routing）
+
+<p align="center">
+  <a href="./README.md">English</a> · <b>简体中文</b>
+</p>
+
+<p align="center">
+  <b>LLM 调用的自动最低成本路由。一行代码，降低 AI 账单。</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 把每个模型路由到各自最便宜的 provider——Gemini 走 Kunavo，DeepSeek 走 OpenRouter，Seedream 走 fal，Flux Schnell 走 Runware——失败时自动 fallback" width="820">
+</p>
+
+同一个模型在不同 provider 上的价格不同——而且没有任何单一 provider 在所有模型上都最便宜。`ai-lcr` 为每个模型维护一份「最便宜优先」的列表，路由到其中最便宜且健康的 provider（下表中的 ⭐），失败时向下穿透——这正是电话运营商几十年来一直在做的 [最低成本路由（Least Cost Routing）](https://en.wikipedia.org/wiki/Least-cost_routing)。
+
+## 安装
+
+```bash
+npm install ai-lcr
+```
+
+`ai`（Vercel AI SDK）是 peer dependency。
+
+## 快速开始
+
+```ts
+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, // 按 `cost` 把每个模型的 provider 排成最便宜优先
+  models: {
+    // 一个逻辑模型，跨多个 provider 最便宜优先地提供服务。
+    "gemini-3-flash": [
+      { model: kunavo("gemini-3-flash"), label: "kunavo", cost: { input: 0.35, output: 2.1 } },
+      { model: openrouter("google/gemini-3-flash-preview"), label: "openrouter", cost: { input: 0.5, output: 3.0 } },
+    ],
+  },
+  // 看清每次调用的实际花费，以及由哪个 provider 提供。
+  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` 和 `label` 都是可选的——如果你不需要成本核算或 `autoSort`，可以直接传裸模型（`kunavo("gemini-3-flash")`）。`lcr("gemini-3-flash")` 返回一个标准的 AI SDK 模型，因此可与 `generateText`、`streamText`、`generateObject`、工具调用和 agent 一起使用。
+
+## 它如何路由
+
+1. **最便宜优先。** provider 按顺序依次尝试——把它们排成最便宜优先，或设置 `autoSort: true` 让它按 `cost` 自动排序。
+2. **失败时向下穿透。** 遇到可重试的错误（限流、5xx、超时）时，前进到下一个 provider，且对流式安全。硬错误（400、401、403、422）会直接透传，不做重试。
+3. **恢复。** 在一段空闲窗口（`resetIntervalMs`，默认 60s）之后，自动回到最便宜的 provider。
+
+<p align="center">
+  <img src="assets/ai-lcr-routing.svg" alt="路由示意图：最便宜优先、失败时 fallback、空闲后恢复" width="820">
+</p>
+
+## 支持的 provider
+
+任何 OpenAI 兼容的 endpoint 都可用。
+
+- **文本：** [OpenRouter](https://openrouter.ai)（覆盖最广，列表定价）· [Kunavo](https://kunavo.com/?ref=hJ2uT3iW)（**全模型 7 折**）
+- **图像 / 视频：** [Kunavo](https://kunavo.com/?ref=hJ2uT3iW)（**7 折**）· [fal.ai](https://fal.ai) · [Runware](https://runware.ai) —— 路由功能在路线图中
+
+## 文本模型价格
+
+单位为每 100 万 token 的美元价格，input / output。官方价格截至 2026-05——请向各 provider 核对当前价格。OpenRouter 直接透传列表价；Kunavo 在官方价基础上统一 7 折。
+
+| 模型 | 官方价（in / out） | OpenRouter | [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) | 最便宜 |
+|---|---|---|---|---|
+| Gemini 3 Flash | $0.50 / $3.00 | 无折扣 | −30% | ⭐ Kunavo |
+| Gemini 3 Pro / 3.1 Pro | $2.00 / $12.00 | 无折扣 | −30% | ⭐ Kunavo |
+| Gemini 2.5 Pro | $1.25 / $10.00 | 无折扣 | −30% | ⭐ Kunavo |
+| Gemini 2.5 Flash | $0.30 / $2.50 | 无折扣 | −30% | ⭐ Kunavo |
+| Claude Sonnet 4.6 | $3.00 / $15.00 | 无折扣 | −30% | ⭐ Kunavo |
+| Claude Haiku 4.5 | $1.00 / $5.00 | 无折扣 | −30% | ⭐ Kunavo |
+| DeepSeek V4 | $0.43 / $0.87 | 无折扣 | 未提供 | ⭐ OpenRouter |
+
+Kunavo 提供 Anthropic + Google。DeepSeek / OpenAI / Grok / Mistral 路由到 OpenRouter——一份配置即可混用全部。
+
+## 图像模型价格
+
+单位为每张图的美元价格，截至 2026-05（provider 列表价 / 零售价；请核对当前价格）。Kunavo 为官方价 7 折。fal 与 Runware 是算力 provider——`ai-lcr` 为每个模型挑选最便宜的那个（⭐）。
+
+| 模型 | fal.ai | Runware | [Kunavo](https://kunavo.com/?ref=hJ2uT3iW) | 最便宜 |
+|---|---|---|---|---|
+| Nano Banana 2 | $0.080 | $0.069 | $0.047 | ⭐ Kunavo |
+| Nano Banana Pro | $0.080 | — | $0.094 | ⭐ fal |
+| GPT-Image-2 | $0.210 | $0.094 | $0.089 | ⭐ Kunavo |
+| Imagen 4 Ultra | $0.060 | $0.060 | — | ⭐ fal / Runware |
+| Ideogram V3 | $0.060 | $0.060 | — | ⭐ fal / Runware |
+| Seedream 4 | $0.030 | — | — | ⭐ fal |
+| Flux 1.1 Pro | $0.040 | $0.040 | — | ⭐ fal / Runware |
+| Flux Dev | $0.025 | $0.025 | — | ⭐ fal / Runware |
+| Flux Schnell | $0.0030 | $0.0013 | — | ⭐ Runware |
+| Qwen-Image | — | $0.0038 | — | ⭐ Runware |
+| FLUX.2 Klein 4B | — | $0.0006 | — | ⭐ Runware |
+
+## 视频模型价格
+
+单位为每秒的美元价格，截至 2026-05——请核对当前价格。视频计费方式因 provider 而异，因此无法做严格对等的跨 provider 表格：fal.ai 和 Runware 按秒计费，而 Kunavo 的 Veo 按段计费（Fast ~$0.28 / Lite ~$0.168 / Quality ~$1.34）。下表为 fal.ai 的每秒价格（测试中的视频主力）；fal / Runware / Kunavo 的归一化对比是一个 TODO。
+
+| 模型 | fal.ai（$/s） |
+|---|---|
+| Seedance Lite | $0.036 |
+| Hailuo 02 Standard | $0.045 |
+| LTX-2 | $0.060 |
+| Kling 2.6 Pro | $0.070 |
+| WAN 2.2 | $0.080 |
+| Veo 3.1 Lite | $0.080 |
+| Kling V3 Pro | $0.112 |
+| Seedance Pro | $0.124 |
+| Veo 3.1（audio-on） | $0.400 |
+
+## 路线图
+
+- [x] 自有 failover 引擎——最便宜优先路由 + 流式安全的 fallback，不依赖外部路由库
+- [x] 真实的逐次调用成本核算（`onCost`）
+- [x] 基于各 provider `cost` 的自动最便宜优先排序（`autoSort`）
+- [ ] 内置价格表，实现零配置定价（省去手填 `cost` 数字）
+- [ ] provider 怪癖中间件（透明地修补已知的各 provider 请求怪癖）
+- [ ] 离线能力探测（工具调用 / 缓存 / 流式）→ 信任矩阵
+- [ ] 图像与视频模型路由（fal.ai / Runware / Kunavo）
+
+## 联盟（Affiliate）披露
+
+`ai-lcr` 是 provider 中立的，可与任何 OpenAI 兼容的 endpoint 配合使用。作者与 **[Kunavo](https://kunavo.com/?ref=hJ2uT3iW)** 之间存在联盟（affiliate）关系——在官方价 7 折的情况下，它往往（但并非总是）是最便宜的选项，正如上面的表格所示。通过该链接注册可能会让作者获得一份分成。你完全不必使用它；自带 provider，路由功能照常工作。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test          # mock 的路由 / failover 测试 + 真实 Kunavo 测试
+```
+
+测试套件覆盖了：最便宜优先路由、可重试错误时的 failover（以及遇到 400 时*不*做 failover）、穷尽整条链路，以及一次真实的「provider 故障 → Kunavo 恢复」。真实测试仅在环境变量 `KUNAVO_API_KEY` 设置时运行，否则跳过。
+
+## 致谢
+
+流式安全的 failover 方案改编自 [`ai-fallback`](https://github.com/remorses/ai-fallback)（MIT）——在内部重新实现，使 ai-lcr 拥有自己的引擎，并把成本核算 + 路由直接融入其中。基于 [Vercel AI SDK](https://ai-sdk.dev) 构建。
+
+## 许可证
+
+[MIT](./LICENSE) © Victor

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { LanguageModelV3 } from '@ai-sdk/provider';
+
+/**
+ * Owned failover engine for ai-lcr.
+ *
+ * A LanguageModelV3 that wraps an ordered, cheapest-first list of providers:
+ * it serves from the first healthy one, switches to the next on a retryable
+ * error (streaming-safe), and snaps back to the cheapest after an idle window.
+ * It also computes per-call cost from each provider's price and fires `onCost`.
+ *
+ * The switching loop is adapted from `ai-fallback` (MIT, © remorses) — its
+ * streaming-safe fallback approach — reimplemented here so ai-lcr owns its core
+ * engine and can layer cost accounting + provider quirks directly into it.
+ */
+
+/** USD per 1M tokens. */
+interface ProviderCost {
+    input: number;
+    output: number;
+}
+interface CostEvent {
+    /** Logical model name (the key in createLCR's `models`). */
+    model: string;
+    /** Which provider actually served the request. */
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Computed from the serving provider's `cost`; 0 if no price was given. */
+    costUsd: number;
+}
+
+/**
+ * ai-lcr — Least Cost Routing for LLMs.
+ *
+ * Route each model to the cheapest provider that can serve it, fall back
+ * automatically on failure, and report real per-call cost. Built on its own
+ * failover engine (see ./fallback) — no external routing dependency.
+ *
+ * Roadmap (see README): provider-quirk middleware, offline capability probe,
+ * a bundled price table for zero-config cheapest-first ordering.
+ */
+
+/**
+ * A provider for a model: either a bare AI SDK model (e.g.
+ * `createOpenAICompatible(...)("id")`), or that model wrapped with price/label
+ * metadata to unlock cost accounting and cheapest-first auto-sorting.
+ */
+type ProviderEntry = LanguageModelV3 | {
+    model: LanguageModelV3;
+    /** USD per 1M tokens. Enables `onCost` and `autoSort`. */
+    cost?: ProviderCost;
+    /** Label used in cost events / logs. Defaults to the model's provider id. */
+    label?: string;
+};
+interface LCRConfig {
+    /**
+     * Map of logical model name -> providers to try, cheapest-first.
+     * Order is priority order unless `autoSort` is set.
+     */
+    models: Record<string, ProviderEntry[]>;
+    /** Sort each model's providers cheapest-first by `cost` before routing. */
+    autoSort?: boolean;
+    /** Idle window after which routing snaps back to the cheapest provider. Default 60s. */
+    resetIntervalMs?: number;
+    /** Called when a provider errors and routing falls through to the next. */
+    onError?: (error: Error, provider: string) => void;
+    /** Called after each successful call with the serving provider, tokens, and cost. */
+    onCost?: (event: CostEvent) => void;
+}
+/** Resolve a logical model name to a routed model. */
+type LCRRouter = (modelName: string) => LanguageModelV3;
+/**
+ * Build a Least Cost Router. Returns a function that resolves a logical model
+ * name to a routed model usable anywhere in the Vercel AI SDK (generateText,
+ * streamText, generateObject, tools, agents).
+ */
+declare function createLCR(config: LCRConfig): LCRRouter;
+
+export { type CostEvent, type LCRConfig, type LCRRouter, type ProviderCost, type ProviderEntry, createLCR };

package/dist/index.js

@@ -0,0 +1,224 @@
+// src/fallback.ts
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([401, 403, 408, 409, 413, 429, 498, 500]);
+var RETRYABLE_PATTERNS = [
+  "overloaded",
+  "service unavailable",
+  "bad gateway",
+  "too many requests",
+  "internal server error",
+  "gateway timeout",
+  "rate_limit",
+  "ratelimit",
+  "rate limit",
+  "capacity",
+  "timeout",
+  "server_error",
+  "502",
+  "503",
+  "504",
+  "429"
+];
+function isRetryableError(error) {
+  const e = error;
+  const status = e?.statusCode ?? e?.status;
+  if (typeof status === "number" && (RETRYABLE_STATUS.has(status) || status > 500)) {
+    return true;
+  }
+  const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
+  return RETRYABLE_PATTERNS.some((p) => text.includes(p));
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+var LcrFallbackModel = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (opts.providers.length === 0) {
+      throw new Error(`ai-lcr: model "${opts.modelName}" has no providers`);
+    }
+    this.resetIntervalMs = opts.resetIntervalMs ?? 6e4;
+  }
+  opts;
+  specificationVersion = "v3";
+  index = 0;
+  lastReset = Date.now();
+  resetIntervalMs;
+  get current() {
+    return this.opts.providers[this.index];
+  }
+  get modelId() {
+    return this.current.model.modelId;
+  }
+  get provider() {
+    return this.current.model.provider;
+  }
+  get supportedUrls() {
+    return this.current.model.supportedUrls;
+  }
+  checkReset() {
+    if (this.index !== 0 && Date.now() - this.lastReset >= this.resetIntervalMs) {
+      this.index = 0;
+    }
+    this.lastReset = Date.now();
+  }
+  switchNext() {
+    this.index = (this.index + 1) % this.opts.providers.length;
+  }
+  shouldRetry(error) {
+    return (this.opts.shouldRetry ?? isRetryableError)(error);
+  }
+  emitCost(provider, usage) {
+    const onCost = this.opts.onCost;
+    if (!onCost) return;
+    const inputTokens = usage?.inputTokens?.total ?? 0;
+    const outputTokens = usage?.outputTokens?.total ?? 0;
+    const costUsd = provider.cost ? inputTokens / 1e6 * provider.cost.input + outputTokens / 1e6 * provider.cost.output : 0;
+    onCost({
+      model: this.opts.modelName,
+      provider: provider.label,
+      inputTokens,
+      outputTokens,
+      costUsd
+    });
+  }
+  async doGenerate(options) {
+    this.checkReset();
+    const start = this.index;
+    let lastError;
+    for (; ; ) {
+      const provider = this.current;
+      try {
+        const result = await provider.model.doGenerate(options);
+        this.emitCost(provider, result.usage);
+        return result;
+      } catch (error) {
+        lastError = error;
+        if (!this.shouldRetry(error)) throw error;
+        this.opts.onError?.(error, provider.label);
+        this.switchNext();
+        if (this.index === start) throw lastError;
+      }
+    }
+  }
+  async doStream(options) {
+    this.checkReset();
+    const self = this;
+    const start = this.index;
+    let result;
+    let serving;
+    for (; ; ) {
+      serving = this.current;
+      try {
+        result = await serving.model.doStream(options);
+        break;
+      } catch (error) {
+        if (!this.shouldRetry(error)) throw error;
+        this.opts.onError?.(error, serving.label);
+        this.switchNext();
+        if (this.index === start) throw error;
+      }
+    }
+    const servingProvider = serving;
+    let usage;
+    let streamedAny = false;
+    const stream = new ReadableStream({
+      async start(controller) {
+        let reader = null;
+        try {
+          reader = result.stream.getReader();
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (!streamedAny && value && typeof value === "object" && "error" in value) {
+              const err = value.error;
+              if (self.shouldRetry(err)) throw err;
+            }
+            if (done) break;
+            if (value.type === "finish") usage = value.usage;
+            controller.enqueue(value);
+            if (value.type !== "stream-start") streamedAny = true;
+          }
+          self.emitCost(servingProvider, usage);
+          controller.close();
+        } catch (error) {
+          self.opts.onError?.(error, servingProvider.label);
+          if (!streamedAny) {
+            self.switchNext();
+            if (self.index === start) {
+              controller.error(error);
+              return;
+            }
+            try {
+              const next = await self.doStream(options);
+              const nextReader = next.stream.getReader();
+              try {
+                for (; ; ) {
+                  const { done, value } = await nextReader.read();
+                  if (done) break;
+                  controller.enqueue(value);
+                }
+                controller.close();
+              } finally {
+                nextReader.releaseLock();
+              }
+            } catch (nextError) {
+              controller.error(nextError);
+            }
+            return;
+          }
+          controller.error(error);
+        } finally {
+          reader?.releaseLock();
+        }
+      }
+    });
+    return { ...result, stream };
+  }
+};
+
+// src/index.ts
+function isLanguageModel(entry) {
+  return typeof entry.doGenerate === "function";
+}
+function normalize(entry) {
+  if (isLanguageModel(entry)) {
+    return { model: entry, label: entry.provider };
+  }
+  return {
+    model: entry.model,
+    label: entry.label ?? entry.model.provider,
+    cost: entry.cost
+  };
+}
+function priceKey(p) {
+  return p.cost ? p.cost.input + p.cost.output : Number.POSITIVE_INFINITY;
+}
+function createLCR(config) {
+  const { models, autoSort = false, resetIntervalMs, onError, onCost } = config;
+  const routed = /* @__PURE__ */ new Map();
+  for (const [name, entries] of Object.entries(models)) {
+    let providers = entries.map(normalize);
+    if (autoSort) {
+      providers = [...providers].sort((a, b) => priceKey(a) - priceKey(b));
+    }
+    routed.set(
+      name,
+      new LcrFallbackModel({ modelName: name, providers, resetIntervalMs, onError, onCost })
+    );
+  }
+  return (modelName) => {
+    const model = routed.get(modelName);
+    if (!model) {
+      throw new Error(
+        `ai-lcr: unknown model "${modelName}" \u2014 add it to createLCR({ models })`
+      );
+    }
+    return model;
+  };
+}
+export {
+  createLCR
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "ai-lcr",
+  "version": "0.0.1",
+  "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
+  "keywords": [
+    "ai",
+    "llm",
+    "vercel-ai-sdk",
+    "ai-sdk",
+    "router",
+    "least-cost-routing",
+    "lcr",
+    "fallback",
+    "openrouter",
+    "cost-optimization",
+    "openai-compatible"
+  ],
+  "license": "MIT",
+  "author": "Victor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victorzhrn/ai-lcr.git"
+  },
+  "homepage": "https://github.com/victorzhrn/ai-lcr#readme",
+  "bugs": {
+    "url": "https://github.com/victorzhrn/ai-lcr/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.0",
+    "@ai-sdk/provider": "^3.0.0",
+    "@types/node": "^25.9.1",
+    "ai": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}