Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(llm): add Kilo's keyless Nemotron pool, NIM Ultra and Lightning rungs, and bring LLM7 back keyless
nirholasf52f31edd746
diff --git a/.env.example b/.env.exampleindex 859bd81c0..cc3dd67de 100644--- a/.env.example+++ b/.env.example@@ -140,12 +140,16 @@ ZAI_API_KEY=# https://siliconflow.comSILICONFLOW_API_KEY=-# LLM7.io: gemini-3.1-flash-lite on an OpenAI-compatible endpoint, about-# 30 req/min per IP. This was a keyless rung until llm7.io retired its-# anonymous tier; unauthenticated calls now answer 401 invalid_api_key, so the-# rung is skipped without this key. Free key at https://dash.llm7.io/#/api-keys+# LLM7.io: Gemma 4 31B on an OpenAI-compatible endpoint. The rung is KEYLESS+# (anonymous access reaches LLM7's turbo models); a free key only raises the+# rate limit. Free key at https://dash.llm7.io/#/api-keysLLM7_API_KEY=+# Kilo Code gateway: Nemotron 3 Ultra 550B and Super 120B on its free pool.+# The rungs are KEYLESS (about 200 req/hr anonymous) and only ever request+# ':free' models; a key from https://app.kilo.ai/profile only raises the limit.+KILO_API_KEY=+# Cloudflare Workers AI (free tier, 10,000 neurons/day): 70B-class Llama at# the edge. The rung needs BOTH values; the OpenAI-compatible URL embeds the# account id. Create a Workers AI scoped token at https://dash.cloudflare.comdiff --git a/api/_lib/env.js b/api/_lib/env.jsindex 6e8ebbdf6..afe5e30c0 100644--- a/api/_lib/env.js+++ b/api/_lib/env.js@@ -651,17 +651,21 @@ export const env = {return opt('SILICONFLOW_API_KEY');},- // LLM7.io key (dash.llm7.io). This rung was added 2026-08-05 as a KEYLESS- // anonymous tier; llm7.io retired that tier and the endpoint now answers- // every unauthenticated request with 401 invalid_api_key (measured- // 2026-09-02, including the "unused" token its docs used to accept). The- // rung is therefore key-gated like every other optional one, so a- // deployment without the key skips it instead of spending a guaranteed- // round trip on it at the tail of the free chain.+ // LLM7.io key (dash.llm7.io), optional. The rung is keyless: anonymous+ // access reaches LLM7's `turbo` models (it was briefly closed with 401s on+ // 2026-09-02 and answered keyless again on 2026-10-08). A free key only+ // raises the rate limit.get LLM7_API_KEY() {return opt('LLM7_API_KEY');},+ // Kilo Code gateway key (app.kilo.ai/profile), optional. The Kilo rungs+ // are keyless and only ever request ':free' models; a key only raises the+ // anonymous ~200 req/hr limit.+ get KILO_API_KEY() {+ return opt('KILO_API_KEY');+ },+// Cloudflare account id for Workers AI (dash.cloudflare.com). The Workers// AI OpenAI-compatible URL embeds the account id, so the LLM rung needs// this AND CLOUDFLARE_AI_API_TOKEN; with either half missing the rung isdiff --git a/api/_lib/llm-pricing.js b/api/_lib/llm-pricing.jsindex 049dd5b7d..22f9e1f08 100644--- a/api/_lib/llm-pricing.js+++ b/api/_lib/llm-pricing.js@@ -104,6 +104,8 @@ const FREE_PROVIDERS = new Set(['cloudflare','siliconflow','llm7',+ // Kilo Code gateway: keyless, and the chain only ever sends ':free' ids.+ 'kilo',// Inference Providers on each token's monthly included credit: the chain// never buys pre-paid credit, so an exhausted token 402s and fails over.'huggingface',diff --git a/api/_lib/llm.js b/api/_lib/llm.jsindex 4b2881b16..a1ab2fb19 100644--- a/api/_lib/llm.js+++ b/api/_lib/llm.js@@ -5,8 +5,9 @@// • FREE PROVIDERS FIRST, ALWAYS. Groq, Cerebras, OpenRouter (paid model,// then the :free variant on the same key), Gemini AI Studio, and NVIDIA// NIM are platform-funded free tiers — the server holds those keys and-// callers use them at zero marginal cost. OVH AI Endpoints and Pollinations-// need no key at all (anonymous/keyless tiers) and are always in the chain,+// callers use them at zero marginal cost. Kilo Code's free pool, OVH AI+// Endpoints, Pollinations, and LLM7.io need no key at all+// (anonymous/keyless tiers) and are always in the chain,// so llmConfigured() is never false even with zero env vars set. They form// the default chain, tried in order, 70B-class models before any capability// step-down, and every flow must survive on them alone: the paid keys in@@ -15,8 +16,10 @@//// • THE FREE TIER KEEPS GROWING. SambaNova, Mistral (Experiment tier),// Z.AI GLM Flash, Cloudflare Workers AI, and SiliconFlow are optional-// keyed rungs (each skipped when its env var is unset), and LLM7.io is a-// second keyless anonymous rung alongside OVH and Pollinations. Every new+// keyed rungs (each skipped when its env var is unset). NVIDIA NIM runs+// three Nemotron models (Super, Ultra, Lightning) on one key, each its+// own NIM function, so one model's throttle or retirement is not the+// lane's. Every new// free provider is an independent quota pool, so adding one raises the// ceiling of traffic the platform serves at zero marginal cost.//@@ -130,6 +133,30 @@ const NVIDIA_MODEL = 'nvidia/nemotron-3-super-120b-a12b';// twice as NVIDIA retired catalog entries, and each time a test restating it by// hand went red for a reason that had nothing to do with the code.export const NVIDIA_NEMOTRON_MODEL = 'nvidia/nemotron-3.5-lightning-30b-a3b';+// Nemotron 3 Ultra 550B on the same nvapi key: the largest free model in the+// chain (1.6s, clean content with thinking off, measured 2026-10-08). Every NIM+// model is its own NVCF function with its own queue and retirement date, and+// NVIDIA sizes the free rate limit by model, so a second model id behind the+// Super rung survives the Super function 429ing, 410ing, or queueing. The+// third-party models NIM also lists (DeepSeek, Kimi, GLM, Gemma) queued past+// 60s on the free tier the same day, so they are deliberately not rungs.+export const NVIDIA_ULTRA_MODEL = 'nvidia/nemotron-3-ultra-550b-a55b';+// Every NIM id the free chain pins, for /api/cron/free-model-audit.+export const NVIDIA_PINNED_MODELS = Object.freeze([NVIDIA_MODEL, NVIDIA_ULTRA_MODEL, NVIDIA_NEMOTRON_MODEL]);+// Kilo Code's gateway (api.kilo.ai) serves a free model pool with NO key and no+// signup, about 200 req/hr. Its free Nemotron routes run on Kilo's own NVIDIA+// capacity, so they are a quota pool independent of our nvapi key. Only+// ':free' ids are used, so the lane cannot bill even when KILO_API_KEY is set.+// Kilo routes these through reasoning by default and the answer then lands in+// the reasoning field; `reasoning.enabled: false` keeps it in `content`+// (Ultra 2.2s, Super 0.7s, both clean, measured 2026-10-08).+const KILO_URL = 'https://api.kilo.ai/api/gateway/chat/completions';+const KILO_RUNGS = Object.freeze([+ { name: 'kilo', model: 'nvidia/nemotron-3-ultra-550b-a55b:free' },+ { name: 'kilo:super', model: 'nvidia/nemotron-3-super-120b-a12b:free' },+]);+export const KILO_FREE_MODELS = Object.freeze(KILO_RUNGS.map((r) => r.model));+const KILO_NO_REASONING = Object.freeze({ reasoning: { enabled: false } });// nemotron-3 puts its reasoning in a separate field only when thinking is off;// with it on, the chain of thought leaks into `content` (verified 2026-08-27).const NVIDIA_NO_THINK = Object.freeze({ chat_template_kwargs: { enable_thinking: false } });@@ -164,14 +191,14 @@ const CLOUDFLARE_MODEL = '@cf/meta/llama-3.3-70b-instruct-fp8-fast';// of the free section; enable_thinking:false (extraBody below) keeps Qwen3's// reasoning mode off so message.content carries the actual answer.const SILICONFLOW_MODEL = 'Qwen/Qwen3-8B';-// LLM7.io (api.llm7.io): community-run gateway, about 30 req/min per IP. Free-// catalog probed live 2026-08-05; gemini-3.1-flash-lite returned real content-// there, while the gpt-oss route spends its token budget on reasoning and can-// hand back an empty content field, so it is deliberately not used. Added as a-// KEYLESS rung; llm7.io has since retired its anonymous tier and answers every-// unauthenticated request with 401 invalid_api_key (measured 2026-09-02), so-// the rung is now gated on LLM7_API_KEY and skipped without one.-const LLM7_MODEL = 'gemini-3.1-flash-lite';+// LLM7.io (api.llm7.io): community-run gateway with tiered models. Anonymous+// access is back for its `turbo` tier (it answered 401 to every keyless call on+// 2026-09-02, then 200 again on 2026-10-08), so the rung is keyless once more;+// LLM7_API_KEY only raises the rate limit. gemini-3.1-flash-lite, the old pin,+// moved to the paid `pro` tier. gemma4:31b is turbo and answered clean content+// in 0.9s; the gpt-oss route spends its budget on reasoning and returns empty+// content, so it is deliberately not used.+const LLM7_MODEL = 'gemma4:31b';// Pollinations' keyless anonymous tier: also no key, routes to a hosted// gpt-oss-20b. Smaller than the 70B rungs above it, so it sits in the// capability-step-down group alongside Groq's instant lane — an always-on@@ -331,6 +358,7 @@ export async function checkUserLlmSpendCap(userId, { anthropicKey, grokKey } = {-- Multi-key rungs (nvidia#2, huggingface#2) meter like their base lane.AND provider NOT LIKE 'nvidia%'AND provider NOT LIKE 'huggingface%'+ AND provider NOT LIKE 'kilo%'AND provider NOT IN ('cerebras', 'gemini', 'ovh', 'pollinations', 'sambanova', 'mistral', 'zai', 'cloudflare', 'siliconflow', 'llm7')AND created_at > NOW() - INTERVAL '24 hours'`;@@ -690,6 +718,18 @@ export function providerChain({ anthropicKey, anthropicModel, grokKey = null, grtimeoutMs: nvidiaLaneTimeoutMs(),}));});+ // Then Ultra on each key: a different NIM function, so it still answers when+ // the Super function above is throttled or retired.+ nvidiaKeys.forEach((key, i) => {+ chain.push(openaiCompatProvider({+ name: `${i === 0 ? 'nvidia' : `nvidia#${i + 1}`}:ultra`,+ key,+ url: 'https://integrate.api.nvidia.com/v1/chat/completions',+ model: NVIDIA_ULTRA_MODEL,+ extraBody: NVIDIA_NO_THINK,+ timeoutMs: nvidiaLaneTimeoutMs(),+ }));+ });// SambaNova's free tier: the same Llama 3.3 70B on a fourth independent// quota pool, so a day that exhausts Groq, Cerebras, and NVIDIA at once// still has a 70B-class free rung with budget left.@@ -745,6 +785,18 @@ export function providerChain({ anthropicKey, anthropicModel, grokKey = null, grmodel: HF_MODEL,}));});+ // Kilo Code's keyless free pool: Nemotron Ultra then Super on Kilo's own+ // NVIDIA capacity. Always present (no key needed), and ahead of OVH because+ // its 200 req/hr dwarfs OVH's 2 req/min.+ KILO_RUNGS.forEach(({ name, model }) => {+ chain.push(openaiCompatProvider({+ name,+ key: env.KILO_API_KEY,+ url: KILO_URL,+ model,+ extraBody: KILO_NO_REASONING,+ }));+ });// OVH AI Endpoints anonymous tier — no key required, always available.// Last of the 70B-class free rungs because its per-model anonymous quota// (2 req/min/IP) is the tightest in the chain; everything with a real key@@ -778,18 +830,15 @@ export function providerChain({ anthropicKey, anthropicModel, grokKey = null, grurl: 'https://text.pollinations.ai/openai',model: POLLINATIONS_MODEL,}));- // LLM7.io: sits with the step-down group (flash-lite class) right after- // Pollinations. Skipped without a key, because an unauthenticated call here- // is now a guaranteed 401: leaving it in the chain unconditionally spends a- // round trip per exhaustion for an answer that cannot arrive.- if (env.LLM7_API_KEY) {- chain.push(openaiCompatProvider({- name: 'llm7',- key: env.LLM7_API_KEY,- url: 'https://api.llm7.io/v1/chat/completions',- model: LLM7_MODEL,- }));- }+ // LLM7.io: keyless step-down right after Pollinations, so a zero-config+ // deployment still has a third anonymous rung. The key, when set, only+ // raises the rate limit.+ chain.push(openaiCompatProvider({+ name: 'llm7',+ key: env.LLM7_API_KEY,+ url: 'https://api.llm7.io/v1/chat/completions',+ model: LLM7_MODEL,+ }));// SiliconFlow free tier: keyed 8B step-down on its own quota pool.// enable_thinking:false forces Qwen3 out of reasoning mode so the answer// lands in message.content instead of a reasoning field.@@ -802,6 +851,20 @@ export function providerChain({ anthropicKey, anthropicModel, grokKey = null, grextraBody: { enable_thinking: false },}));}+ // NIM's compact Lightning model on the primary key: a third NIM function,+ // in the step-down group because it is a 30B. Skipped when a preferNvidia+ // caller already led the chain with this exact model.+ const nvidiaLedWithLightning = preferNvidia && (nvidiaModel || NVIDIA_NEMOTRON_MODEL) === NVIDIA_NEMOTRON_MODEL;+ if (env.NVIDIA_API_KEY && !nvidiaLedWithLightning) {+ chain.push(openaiCompatProvider({+ name: 'nvidia:lightning',+ key: env.NVIDIA_API_KEY,+ url: 'https://integrate.api.nvidia.com/v1/chat/completions',+ model: NVIDIA_NEMOTRON_MODEL,+ extraBody: NVIDIA_NO_THINK,+ timeoutMs: nvidiaLaneTimeoutMs(),+ }));+ }// Last free rung: Groq's instant lane. Smaller model (a capability// step-down), but its per-model quota is separate from the 70B lane and it// still beats erroring out or landing on a dead paid key.diff --git a/api/cron/free-model-audit.js b/api/cron/free-model-audit.jsindex b6caa4173..8cad8843c 100644--- a/api/cron/free-model-audit.js+++ b/api/cron/free-model-audit.js@@ -15,12 +15,26 @@// An EMPTY live list means OpenRouter itself was unreachable, not that the ids// died: mirror isLiveFreeModel()'s semantics, report status 'unknown', and flag// nothing dead. Never call a model dead on our own outage.+//+// The same audit covers the two other lanes that pin catalog ids: NVIDIA NIM+// (its Nemotron pin has been re-pinned twice after silent 410s) and the+// keyless Kilo Code gateway. Their catalogs are not authoritative (NIM lists+// models the account cannot call, Kilo's list lags what it serves), so an id+// missing from a listing is only reported dead after a live 1-token call to+// it answers 404 or 410.import { json, method, wrapCron } from '../_lib/http.js';import { MODEL_CATALOG, DEFAULT_FREE_MODEL, OPENROUTER_SIBLINGS } from '../_lib/chat-models.js';import { listFreeModels } from '../_lib/openrouter-free.js';import { sendOpsAlert } from '../_lib/alerts.js';import { requireCron } from '../_lib/cron-auth.js';+import { env } from '../_lib/env.js';+import { NVIDIA_PINNED_MODELS, KILO_FREE_MODELS } from '../_lib/llm.js';++const NIM_BASE = 'https://integrate.api.nvidia.com/v1';+const KILO_BASE = 'https://api.kilo.ai/api/gateway';+const LISTING_TIMEOUT_MS = 15_000;+const PROBE_TIMEOUT_MS = 30_000;/*** Every OpenRouter `:free` id hardcoded in the codebase, with the constants@@ -67,6 +81,71 @@ export function diffFreeModels(hardcodedIds, liveIds) {return { checked, live: checked - dead.length, dead, status: dead.length ? 'dead_rungs' : 'ok' };}+/**+ * Model ids from an OpenAI-compatible `/models` listing. An unreachable or+ * malformed listing returns [] so diffFreeModels reports 'unknown'.+ * @param {string} base+ * @param {string|null} key+ * @returns {Promise<string[]>}+ */+async function listCatalogIds(base, key) {+ try {+ const r = await fetch(`${base}/models`, {+ headers: key ? { authorization: `Bearer ${key}` } : {},+ signal: AbortSignal.timeout(LISTING_TIMEOUT_MS),+ });+ if (!r.ok) return [];+ const body = await r.json();+ return Array.isArray(body?.data) ? body.data.map((m) => m?.id).filter((id) => typeof id === 'string') : [];+ } catch {+ return [];+ }+}++/**+ * A catalog miss is only a retirement if the model itself says so: 404 or 410+ * on a 1-token completion. A 429, a 5xx, or a timeout is a busy lane, not a+ * dead id.+ * @param {string} base+ * @param {string|null} key+ * @param {string} model+ * @returns {Promise<boolean>}+ */+async function confirmRetired(base, key, model) {+ try {+ const r = await fetch(`${base}/chat/completions`, {+ method: 'POST',+ headers: { 'content-type': 'application/json', ...(key ? { authorization: `Bearer ${key}` } : {}) },+ body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] }),+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),+ });+ return r.status === 404 || r.status === 410;+ } catch {+ return false;+ }+}++/**+ * Audit one non-OpenRouter lane: diff its pins against the catalog, then+ * confirm each miss with a live call before calling it dead.+ * @param {{ lane: string, base: string, key: string|null, ids: readonly string[] }} spec+ */+export async function auditCatalogLane({ lane, base, key, ids }) {+ const result = diffFreeModels([...ids], await listCatalogIds(base, key));+ if (result.status !== 'dead_rungs') return { lane, ...result };+ const confirmed = [];+ for (const id of result.dead) {+ if (await confirmRetired(base, key, id)) confirmed.push(id);+ }+ return {+ lane,+ checked: result.checked,+ live: result.checked - confirmed.length,+ dead: confirmed,+ status: confirmed.length ? 'dead_rungs' : 'ok',+ };+}+export default wrapCron(async (req, res) => {if (!method(req, res, ['GET', 'POST'])) return;if (!requireCron(req, res)) return;@@ -95,10 +174,29 @@ export default wrapCron(async (req, res) => {console.warn('[free-model-audit] OpenRouter model list unreachable; skipping liveness verdict this run');}+ const lanes = [];+ if (env.NVIDIA_API_KEY) {+ lanes.push(await auditCatalogLane({ lane: 'nvidia', base: NIM_BASE, key: env.NVIDIA_API_KEY, ids: NVIDIA_PINNED_MODELS }));+ }+ lanes.push(await auditCatalogLane({ lane: 'kilo', base: KILO_BASE, key: env.KILO_API_KEY, ids: KILO_FREE_MODELS }));+ for (const l of lanes) {+ if (l.status === 'dead_rungs') {+ console.warn(`[free-model-audit] ${l.lane}: retired pinned id(s): ${l.dead.join(', ')}`);+ await sendOpsAlert(+ `⚠️ ${l.lane} retired ${l.dead.length} pinned model id(s)`,+ `${l.dead.join('\n')}\nreferenced by: api/_lib/llm.js (${l.lane === 'nvidia' ? 'NVIDIA_PINNED_MODELS' : 'KILO_RUNGS'})\nEach dead id fails its LLM chain rung until replaced.`,+ { signature: `llm:free-model-audit:${l.lane}` },+ );+ } else if (l.status === 'unknown') {+ console.warn(`[free-model-audit] ${l.lane} model list unreachable; skipping liveness verdict this run`);+ }+ }+return json(res, 200, {checked: result.checked,live: result.live,dead,status: result.status,+ lanes,});});diff --git a/docs/free-llm-providers.md b/docs/free-llm-providers.mdindex 7957deef3..fcaf51f63 100644--- a/docs/free-llm-providers.md+++ b/docs/free-llm-providers.md@@ -6,28 +6,32 @@ The chain lives in [`api/_lib/llm.js`](../api/_lib/llm.js) (`providerChain()` +## The chain, in order-Free rungs run first, 70B-class models before smaller ones. A keyed rung is skipped when its env var is unset; the two keyless rungs (OVH, Pollinations) are always present, so the chain can never be empty.+Free rungs run first, 70B-class models before smaller ones. A keyed rung is skipped when its env var is unset; the four keyless providers (Kilo Code, OVH, Pollinations, LLM7) are always present, so the chain can never be empty.| # | Rung | Model | Key | Free tier ||---|------|-------|-----|-----------|| 1 | Groq | `qwen/qwen3.8-27b` | `GROQ_API_KEY` | Per-minute and per-day caps, no card. Llama 3.x left Groq's catalog in August 2026; Qwen 3.8 27B is the fastest non-reasoning model left there. Groq meters tokens PER MODEL ID at 8,000 tokens/minute, so the ceiling is small and the fix is more model ids, not a bigger plan. [console.groq.com](https://console.groq.com) |-| 1b | Groq | `openai/gpt-oss-120b` | `GROQ_API_KEY` | Same key, a second independent 8,000 tok/min bucket. Added 2026-09-04 to widen the burst Groq absorbs before the chain leaves it. Do not reach for `groq/compound-mini` instead: it advertises 70,000 tok/min but routes internally to `llama-3.3-70b-versatile`, whose 100,000 tokens/DAY org cap makes it 429 while its own headers still read nearly full. |-| 2 | Cerebras | `llama-3.3-70b` | `CEREBRAS_API_KEY` | About 1M tokens/day. [cloud.cerebras.ai](https://cloud.cerebras.ai) |-| 3 | OpenRouter | `google/gemma-4-31b-it:free` | `OPENROUTER_API_KEY` (+ fallback keys) | `:free` models only; the platform key is never billed. OpenRouter retires `:free` slugs with no notice and a retired id 404s every rung built off it, so `/api/cron/free-model-audit` diffs the hardcoded ids against the live list every 6 hours. The extra keys widen nothing on their own when they belong to one account: the free-model cap (1,000 requests/day) is per ACCOUNT, not per key. [openrouter.ai](https://openrouter.ai) |-| 4 | NVIDIA NIM | `nvidia/nemotron-3-super-120b-a12b` | `NVIDIA_API_KEY` | Free developer tier, about 40 req/min. `meta/llama-3.x` on NIM reached end of life on 2026-08-26 (HTTP 410); Nemotron 3 is a reasoning family, so the rung sends `enable_thinking: false` to keep the answer in `content`. [build.nvidia.com](https://build.nvidia.com) |-| 5 | SambaNova | `Meta-Llama-3.3-70B-Instruct` | `SAMBANOVA_API_KEY` | About 20 req/min, 200K tokens/day per model, no card. [cloud.sambanova.ai](https://cloud.sambanova.ai) |-| 6 | Mistral | `mistral-small-latest` | `MISTRAL_API_KEY` | Experiment tier: about 1B tokens/month at 1 req/sec (account opts into data training). [console.mistral.ai](https://console.mistral.ai) |-| 7 | Z.AI | `glm-4.7-flash` | `ZAI_API_KEY` | Permanently free, rate-limited Flash models. [z.ai](https://z.ai), docs at [docs.z.ai](https://docs.z.ai) |-| 8 | Cloudflare Workers AI | `@cf/meta/llama-3.3-70b-instruct-fp8-fast` | `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_AI_API_TOKEN` | 10,000 neurons/day. [developers.cloudflare.com/workers-ai](https://developers.cloudflare.com/workers-ai/) |-| 9 | OVHcloud AI Endpoints | `Meta-Llama-3_3-70B-Instruct` | none (keyless) | Anonymous trial lane, 2 req/min per IP. |-| 10 | Gemini (AI Studio) | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` | AI Studio free tier, no card. [aistudio.google.com](https://aistudio.google.com) |-| 11 | Vertex Gemini | `google/gemini-2.5-flash` | GCP service account | The reliability anchor: billed to platform GCP credits, no third-party quota. |-| 12 | Pollinations | `openai-fast` | none (keyless) | Anonymous, always on. |-| 13 | LLM7.io | `gemini-3.1-flash-lite` | `LLM7_API_KEY` | About 30 req/min per IP. Was keyless until llm7.io retired its anonymous tier; unauthenticated calls answer 401 `invalid_api_key` (measured 2026-09-02), so the rung is skipped without a key. Free key at https://dash.llm7.io/#/api-keys |-| 14 | SiliconFlow | `Qwen/Qwen3-8B` | `SILICONFLOW_API_KEY` | Free-tier small model, own quota pool. [siliconflow.com](https://siliconflow.com) |-| 15 | Groq instant | `openai/gpt-oss-20b` | `GROQ_API_KEY` | Separate per-model quota from rung 1. |--After rung 15 come the paid backstops (Vertex Claude, Anthropic, OpenAI, Grok), which never lead and which no flow depends on.+| 2 | Groq | `openai/gpt-oss-120b` | `GROQ_API_KEY` | Same key, a second independent 8,000 tok/min bucket. Added 2026-09-04 to widen the burst Groq absorbs before the chain leaves it. Do not reach for `groq/compound-mini` instead: it advertises 70,000 tok/min but routes internally to `llama-3.3-70b-versatile`, whose 100,000 tokens/DAY org cap makes it 429 while its own headers still read nearly full. |+| 3 | Cerebras | `llama-3.3-70b` | `CEREBRAS_API_KEY` | About 1M tokens/day. [cloud.cerebras.ai](https://cloud.cerebras.ai) |+| 4 | OpenRouter | `google/gemma-4-31b-it:free`, then alternate `:free` models | `OPENROUTER_API_KEY` (+ fallback keys) | `:free` models only; the platform key is never billed. OpenRouter retires `:free` slugs with no notice and a retired id 404s every rung built off it, so `/api/cron/free-model-audit` diffs the hardcoded ids against the live list every 6 hours. The extra keys widen nothing on their own when they belong to one account: the free-model cap (1,000 requests/day) is per ACCOUNT, not per key. [openrouter.ai](https://openrouter.ai) |+| 5 | NVIDIA NIM | `nvidia/nemotron-3-super-120b-a12b` | `NVIDIA_API_KEY` (+ `NVIDIA_FALLBACK_KEYS`) | Free developer tier, about 40 req/min. `meta/llama-3.x` on NIM reached end of life on 2026-08-26 (HTTP 410); Nemotron 3 is a reasoning family, so the rung sends `enable_thinking: false` to keep the answer in `content`. [build.nvidia.com](https://build.nvidia.com) |+| 6 | NVIDIA NIM | `nvidia/nemotron-3-ultra-550b-a55b` | `NVIDIA_API_KEY` (+ fallback keys) | Same key. Added 2026-10-08: the largest free model in the chain (1.6s, clean output). Every NIM model is its own function with its own queue and retirement date, and NVIDIA sizes the free rate limit by model, so this rung keeps answering when the Super function above is throttled, queued, or retired. |+| 7 | SambaNova | `Meta-Llama-3.3-70B-Instruct` | `SAMBANOVA_API_KEY` | About 20 req/min, 200K tokens/day per model, no card. [cloud.sambanova.ai](https://cloud.sambanova.ai) |+| 8 | Mistral | `mistral-small-latest` | `MISTRAL_API_KEY` | Experiment tier: about 1B tokens/month at 1 req/sec (account opts into data training). [console.mistral.ai](https://console.mistral.ai) |+| 9 | Z.AI | `glm-4.7-flash` | `ZAI_API_KEY` | Permanently free, rate-limited Flash models. [z.ai](https://z.ai), docs at [docs.z.ai](https://docs.z.ai) |+| 10 | Cloudflare Workers AI | `@cf/meta/llama-3.3-70b-instruct-fp8-fast` | `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_AI_API_TOKEN` | 10,000 neurons/day, shared across every Workers AI model (so more Cloudflare models would add no quota). [developers.cloudflare.com/workers-ai](https://developers.cloudflare.com/workers-ai/) |+| 11 | Hugging Face Inference Providers | `meta-llama/Llama-3.3-70B-Instruct` | `HF_TOKEN` (+ `HF_FALLBACK_TOKENS`) | The token's small monthly included credit; an exhausted token answers 402 and the chain moves on. [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |+| 12 | Kilo Code | `nvidia/nemotron-3-ultra-550b-a55b:free`, then `nvidia/nemotron-3-super-120b-a12b:free` | none (keyless); `KILO_API_KEY` optional | Added 2026-10-08. About 200 req/hr with no key and no signup, on Kilo's own NVIDIA capacity (a quota pool separate from our nvapi key). Only `:free` ids are requested, so it cannot bill. The rungs send `reasoning: {enabled: false}`, without which the answer lands in the reasoning field. [kilo.ai](https://kilo.ai) |+| 13 | OVHcloud AI Endpoints | `Meta-Llama-3_3-70B-Instruct` | none (keyless) | Anonymous trial lane, 2 req/min per IP. |+| 14 | Gemini (AI Studio) | `gemini-2.5-flash-lite` | `GEMINI_API_KEY` | AI Studio free tier, no card. [aistudio.google.com](https://aistudio.google.com) |+| 15 | Vertex Gemini | `google/gemini-2.5-flash` | GCP service account | The reliability anchor: billed to platform GCP credits, no third-party quota. |+| 16 | Pollinations | `openai-fast` | none (keyless) | Anonymous, always on. |+| 17 | LLM7.io | `gemma4:31b` | none (keyless); `LLM7_API_KEY` optional | About 30 req/min per IP anonymously. Keyless again since 2026-10-08: the anonymous tier answered 401 on 2026-09-02 and has since reopened for LLM7's `turbo` models. The old pin, `gemini-3.1-flash-lite`, moved to the paid `pro` tier. A free key at https://dash.llm7.io/#/api-keys only raises the limit. |+| 18 | SiliconFlow | `Qwen/Qwen3-8B` | `SILICONFLOW_API_KEY` | Free-tier small model, own quota pool. [siliconflow.com](https://siliconflow.com) |+| 19 | NVIDIA NIM | `nvidia/nemotron-3.5-lightning-30b-a3b` | `NVIDIA_API_KEY` | Added 2026-10-08 as a step-down: a third NIM function on the primary key (0.7s). Skipped when a `preferNvidia` caller already led the chain with this model. |+| 20 | Groq instant | `openai/gpt-oss-20b` | `GROQ_API_KEY` | Separate per-model quota from rungs 1 and 2. |++After rung 20 come the paid backstops (Vertex Claude, Anthropic, OpenAI, Grok), which never lead and which no flow depends on.The interactive chat ladder (`/api/chat`) uses: groq → openrouter → nvidia → sambanova → mistral → zai → paid backstops, with the Vertex Gemini anchor always appended at the tail. SambaNova, Mistral, and Z.AI are also selectable as explicit `provider` values in the chat API, and anonymous callers may use them. When every anonymous-eligible free lane is throttled or in cooldown at once, `/api/chat` answers `503 rate_limited` ("The AI chat is at capacity right now") with a `Retry-After: 20` header and the `providers_tried` list, never a 401 asking a signed-out visitor to sign in for a throttle they cannot fix.@@ -35,9 +39,12 @@ The interactive chat ladder (`/api/chat`) uses: groq → openrouter → nvidiaEvery rung is an independent quota pool on independent infrastructure. Free tiers throttle, retire models without notice (OpenRouter dropped its whole `:free` Llama roster in one day, Groq and NVIDIA NIM both removed Llama 3.x in August 2026, GitHub Models was retired outright in 2026), and queue under load (NVIDIA NIM). One provider failing costs nothing; the chain moves on in under a second. The platform's baseline reliability is the product of how many independent free lanes stand between a request and an error.-Two providers were evaluated and deliberately excluded:+Providers and models evaluated and deliberately excluded:-- **GitHub Models**: in a scheduled retirement brownout (HTTP 410) as of August 2026; the product is being sunset.+- **Third-party models on NVIDIA NIM** (DeepSeek V4.1 Flash, Kimi K3, GLM 5.3, Gemma 4 31B, Muse Glimmer): listed in the NIM catalog on our key, but each queued past 60 seconds on the free tier when probed on 2026-10-08, while the Nemotron family answered in 0.6 to 1.6 seconds. A rung that stalls costs the chain its whole timeout.+- **Ollama Cloud, ModelScope, Aion Labs**: Ollama's free tier publishes no limits (session and weekly caps that reset on its schedule); ModelScope requires Alibaba Cloud real-name verification; Aion Labs caps at 20K tokens/day. None beats the rungs above.++- **GitHub Models**: retired. Brownouts (HTTP 410) began in August 2026, and by 2026-10-08 both `models.github.ai/catalog/models` and the inference endpoint answered a bare `OK` text body with no models and no completion.- **Cohere**: the free trial key is licensed for non-commercial use only, which three.ws does not satisfy.## Cost accounting@@ -47,6 +54,10 @@ All of these rungs are zero-marginal-cost, and the accounting knows it:- `FREE_PROVIDERS` in [`api/_lib/llm-pricing.js`](../api/_lib/llm-pricing.js) prices their traffic at $0 (vs "unpriced", which is an audit failure).- The per-user daily spend cap in `checkUserLlmSpendCap()` ([`api/_lib/llm.js`](../api/_lib/llm.js)) excludes them, so free traffic can never lock a user out.+## Keeping the pins alive++`/api/cron/free-model-audit` runs every 6 hours. It diffs the hardcoded OpenRouter `:free` ids against OpenRouter's live list, and the NVIDIA NIM pins (`NVIDIA_PINNED_MODELS`) and Kilo pins (`KILO_FREE_MODELS`) against their own catalogs. NIM's catalog lists models an account cannot call and Kilo's lags what it serves, so an id missing from those two listings is only reported dead after a live 1-token call answers 404 or 410. A dead id pages the ops channel with the constant to update.+## Adding the next provider1. Get the model id and OpenAI-compatible endpoint (nearly every free tier has one; probe it with `curl` before writing code).diff --git a/tests/api/llm-free-chain-reachability.test.js b/tests/api/llm-free-chain-reachability.test.jsindex 22bb30469..013453f1e 100644--- a/tests/api/llm-free-chain-reachability.test.js+++ b/tests/api/llm-free-chain-reachability.test.js@@ -29,6 +29,7 @@ const HOSTS = {zai: 'api.z.ai',cloudflare: 'api.cloudflare.com',huggingface: 'router.huggingface.co',+ kilo: 'api.kilo.ai',ovh: 'oai.endpoints.kepler.ai.cloud.ovh.net',gemini: 'generativelanguage.googleapis.com',vertex: 'aiplatform.googleapis.com',@@ -55,6 +56,10 @@ const FREE_CHAIN = [// One NIM rung per nvapi key; same host and model, told apart by the key.{ provider: 'nvidia', host: HOSTS.nvidia, model: 'nvidia/nemotron-3-super-120b-a12b', auth: 'nvapi-x' },{ provider: 'nvidia#2', host: HOSTS.nvidia, model: 'nvidia/nemotron-3-super-120b-a12b', auth: 'nvapi-y' },+ // Then Ultra on each key: a separate NIM function, so it answers while the+ // Super function is throttled or retired.+ { provider: 'nvidia:ultra', host: HOSTS.nvidia, model: 'nvidia/nemotron-3-ultra-550b-a55b', auth: 'nvapi-x' },+ { provider: 'nvidia#2:ultra', host: HOSTS.nvidia, model: 'nvidia/nemotron-3-ultra-550b-a55b', auth: 'nvapi-y' },{ provider: 'sambanova', host: HOSTS.sambanova, model: 'Meta-Llama-3.3-70B-Instruct' },{ provider: 'mistral', host: HOSTS.mistral, model: 'mistral-small-latest' },{ provider: 'zai', host: HOSTS.zai, model: 'glm-4.7-flash' },@@ -62,12 +67,16 @@ const FREE_CHAIN = [// Hugging Face Inference Providers, one rung per token's monthly credit.{ provider: 'huggingface', host: HOSTS.huggingface, model: 'meta-llama/Llama-3.3-70B-Instruct', auth: 'hf-a' },{ provider: 'huggingface#2', host: HOSTS.huggingface, model: 'meta-llama/Llama-3.3-70B-Instruct', auth: 'hf-b' },+ // Kilo Code's keyless free pool, Nemotron on Kilo's own NVIDIA capacity.+ { provider: 'kilo', host: HOSTS.kilo, model: 'nvidia/nemotron-3-ultra-550b-a55b:free' },+ { provider: 'kilo:super', host: HOSTS.kilo, model: 'nvidia/nemotron-3-super-120b-a12b:free' },{ provider: 'ovh', host: HOSTS.ovh, model: 'Meta-Llama-3_3-70B-Instruct' },{ provider: 'gemini', host: HOSTS.gemini, model: 'gemini-2.5-flash-lite' },{ provider: 'vertex-gemini', host: HOSTS.vertex, model: 'google/gemini-2.5-flash' },{ provider: 'pollinations', host: HOSTS.pollinations, model: 'openai-fast' },- { provider: 'llm7', host: HOSTS.llm7, model: 'gemini-3.1-flash-lite' },+ { provider: 'llm7', host: HOSTS.llm7, model: 'gemma4:31b' },{ provider: 'siliconflow', host: HOSTS.siliconflow, model: 'Qwen/Qwen3-8B' },+ { provider: 'nvidia:lightning', host: HOSTS.nvidia, model: 'nvidia/nemotron-3.5-lightning-30b-a3b', auth: 'nvapi-x' },{ provider: 'groq#instant', host: HOSTS.groq, model: 'openai/gpt-oss-20b' },];@@ -87,6 +96,7 @@ const ENV_KEYS = ['CLOUDFLARE_AI_API_TOKEN','SILICONFLOW_API_KEY','LLM7_API_KEY',+ 'KILO_API_KEY','GEMINI_API_KEY','GOOGLE_CLOUD_PROJECT','GOOGLE_CLOUD_LOCATION_GEMINI',@@ -227,50 +237,59 @@ describe('free chain: every rung is reachable through a transport-level failure'}, 30_000);// The keyless rungs are the floor of the platform: with zero env vars set the- // chain must still answer, and a transport failure on the first keyless rung- // must reach the second.- it('serves from Pollinations when OVH dies at the transport level and nothing is configured', async () => {- globalThis.fetch = vi.fn(async (url) => {+ // chain must still answer, and a transport failure on each keyless rung must+ // reach the next. Kilo (two models), OVH, Pollinations, then LLM7.+ it('walks every keyless rung in order when each dies at the transport level and nothing is configured', async () => {+ const order = [];+ globalThis.fetch = vi.fn(async (url, opts) => {const u = String(url);- if (u.includes(HOSTS.ovh)) throw transportFailure('reset');- if (u.includes(HOSTS.pollinations)) return okOpenAiShape('keyless floor', 'openai-fast');+ expect(opts.headers.authorization, `keyless rung sent auth: ${u}`).toBeUndefined();+ if (u.includes(HOSTS.kilo)) {+ order.push(`kilo:${JSON.parse(opts.body).model}`);+ throw transportFailure('reset');+ }+ if (u.includes(HOSTS.ovh)) { order.push('ovh'); throw transportFailure('reset'); }+ if (u.includes(HOSTS.pollinations)) { order.push('pollinations'); throw transportFailure('abort'); }+ if (u.includes(HOSTS.llm7)) { order.push('llm7'); return okOpenAiShape('keyless floor', 'gemma4:31b'); }throw new Error(`unexpected fetch: ${u}`);});const out = await llm.llmComplete({ user: 'u', timeoutMs: 20_000 });- expect(out.provider).toBe('pollinations');+ expect(out.provider).toBe('llm7');expect(out.text).toBe('keyless floor');+ expect(order).toEqual([+ 'kilo:nvidia/nemotron-3-ultra-550b-a55b:free',+ 'kilo:nvidia/nemotron-3-super-120b-a12b:free',+ 'ovh',+ 'pollinations',+ 'llm7',+ ]);}, 20_000);- // LLM7 was the third keyless rung until llm7.io retired its anonymous tier- // (401 invalid_api_key on every unauthenticated call, measured 2026-09-02),- // so it is key-gated now: with nothing configured it must NOT be dialled,- // because the answer cannot arrive and the round trip is pure latency on a- // chain that has already exhausted itself.- it('does not dial LLM7 with nothing configured, and reports the two keyless rungs it did try', async () => {- globalThis.fetch = vi.fn(async (url) => {- const u = String(url);- if (u.includes(HOSTS.llm7)) throw new Error('llm7 must not be dialled without a key');- throw transportFailure('reset');- });- await expect(llm.llmComplete({ user: 'u', timeoutMs: 20_000 })).rejects.toThrow(/ovh|pollinations/);- const dialled = globalThis.fetch.mock.calls.map(([u]) => String(u));- expect(dialled.some((u) => u.includes(HOSTS.ovh))).toBe(true);- expect(dialled.some((u) => u.includes(HOSTS.pollinations))).toBe(true);- expect(dialled.some((u) => u.includes(HOSTS.llm7))).toBe(false);- }, 20_000);-- // With the key present it is a normal rung again, behind the other two.- it('serves from LLM7 when OVH and Pollinations both die and the key is set', async () => {+ // LLM7 answered 401 to every keyless call on 2026-09-02 and serves keyless+ // again since 2026-10-08. The key is optional: when set it rides along as a+ // bearer token (higher rate limit), when unset no auth header is sent.+ it('sends the LLM7 key as a bearer token when one is configured', async () => {process.env.LLM7_API_KEY = 'l7';- globalThis.fetch = vi.fn(async (url) => {+ globalThis.fetch = vi.fn(async (url, opts) => {const u = String(url);- if (u.includes(HOSTS.ovh)) throw transportFailure('reset');- if (u.includes(HOSTS.pollinations)) throw transportFailure('abort');- if (u.includes(HOSTS.llm7)) return okOpenAiShape('keyed step-down', 'gemini-3.1-flash-lite');- throw new Error(`unexpected fetch: ${u}`);+ if (u.includes(HOSTS.llm7)) {+ expect(opts.headers.authorization).toBe('Bearer l7');+ return okOpenAiShape('keyed llm7', 'gemma4:31b');+ }+ throw transportFailure('reset');});const out = await llm.llmComplete({ user: 'u', timeoutMs: 20_000 });expect(out.provider).toBe('llm7');- expect(out.text).toBe('keyed step-down');+ expect(out.text).toBe('keyed llm7');}, 20_000);++ // A preferNvidia caller that leads with Lightning must not meet the same+ // model again as the step-down rung.+ it('does not repeat the Lightning rung when a preferNvidia caller already led with it', () => {+ configureFreeLanes();+ const led = llm.providerChain({ preferNvidia: true }).map((p) => `${p.name}|${p.model}`);+ expect(led.filter((r) => r.endsWith('nemotron-3.5-lightning-30b-a3b'))).toHaveLength(1);+ const other = llm.providerChain({ preferNvidia: true, nvidiaModel: 'nvidia/nemotron-3-ultra-550b-a55b' }).map((p) => p.name);+ expect(other).toContain('nvidia:lightning');+ });});diff --git a/tests/api/llm.test.js b/tests/api/llm.test.jsindex 47a1a1864..5474408fe 100644--- a/tests/api/llm.test.js+++ b/tests/api/llm.test.js@@ -48,6 +48,7 @@ const OPENAI_HOST = 'api.openai.com';const OVH_HOST = 'oai.endpoints.kepler.ai.cloud.ovh.net';const POLLINATIONS_HOST = 'text.pollinations.ai';const LLM7_HOST = 'api.llm7.io';+const KILO_HOST = 'api.kilo.ai';const openaiShape = (content) => okJson({choices: [{ message: { content } }],@@ -158,25 +159,60 @@ describe('llmComplete — free platform providers', () => {expect(calls[0].url).toContain(NVIDIA_HOST);});- it('serves from OVH (keyless, no Authorization header) when no provider keys are configured at all', async () => {- const calls = installFetch({ [OVH_HOST]: openaiShape('from ovh anonymous') });+ it('serves from Kilo (keyless, no Authorization header, :free only, reasoning off) when no provider keys are configured at all', async () => {+ const calls = installFetch({ [KILO_HOST]: openaiShape('from kilo anonymous') });const out = await llm.llmComplete({ system: 's', user: 'u' });- expect(out.provider).toBe('ovh');- expect(out.text).toBe('from ovh anonymous');+ expect(out.provider).toBe('kilo');+ expect(out.text).toBe('from kilo anonymous');// No key configured anywhere → no Authorization header sent at all, not// "Bearer undefined" — the keyless tiers reject a bogus auth header.expect(calls[0].headers.authorization).toBeUndefined();+ // A keyless gateway must only ever be asked for a ':free' model, and+ // with reasoning off, or the answer lands in the reasoning field.+ expect(calls[0].body.model).toMatch(/:free$/);+ expect(calls[0].body.reasoning).toEqual({ enabled: false });+ });++ it('serves from OVH (keyless) when both Kilo rungs are throttled and nothing is configured', async () => {+ const calls = installFetch({+ [KILO_HOST]: errResp(429, 'rate limited'),+ [OVH_HOST]: openaiShape('from ovh anonymous'),+ });+ const out = await llm.llmComplete({ system: 's', user: 'u' });+ expect(out.provider).toBe('ovh');+ expect(out.text).toBe('from ovh anonymous');+ expect(calls.map((c) => c.body.model)).toEqual([+ 'nvidia/nemotron-3-ultra-550b-a55b:free',+ 'nvidia/nemotron-3-super-120b-a12b:free',+ 'Meta-Llama-3_3-70B-Instruct',+ ]);+ expect(calls.at(-1).headers.authorization).toBeUndefined();});it('falls back to Pollinations (also keyless) when OVH errors and nothing else is configured', async () => {const calls = installFetch({+ [KILO_HOST]: errResp(429, 'rate limited'),[OVH_HOST]: errResp(429, 'API rate limit exceeded'),[POLLINATIONS_HOST]: openaiShape('from pollinations'),});const out = await llm.llmComplete({ system: 's', user: 'u' });expect(out.provider).toBe('pollinations');expect(out.text).toBe('from pollinations');- expect(calls.map((c) => (c.url.includes(OVH_HOST) ? 'ovh' : 'pollinations'))).toEqual(['ovh', 'pollinations']);+ const host = (u) => [KILO_HOST, OVH_HOST, POLLINATIONS_HOST].find((h) => u.includes(h));+ expect(calls.map((c) => host(c.url))).toEqual([KILO_HOST, KILO_HOST, OVH_HOST, POLLINATIONS_HOST]);+ });++ it('falls back to LLM7 keylessly when every other keyless rung is throttled', async () => {+ const calls = installFetch({+ [KILO_HOST]: errResp(429, 'rate limited'),+ [OVH_HOST]: errResp(429, 'API rate limit exceeded'),+ [POLLINATIONS_HOST]: errResp(429, 'queue full'),+ [LLM7_HOST]: openaiShape('from llm7 anonymous'),+ });+ const out = await llm.llmComplete({ system: 's', user: 'u' });+ expect(out.provider).toBe('llm7');+ expect(out.model).toBe('gemma4:31b');+ expect(calls.at(-1).headers.authorization).toBeUndefined();});});@@ -605,8 +641,8 @@ describe('llmComplete — failure modes', () => {},text: async () => 'not json',};- // Every reachable lane (groq + the two keyless rungs) returns garbage.- installFetch({ [GROQ_HOST]: badBody, [OVH_HOST]: badBody, [POLLINATIONS_HOST]: badBody, [LLM7_HOST]: badBody });+ // Every reachable lane (groq + the keyless rungs) returns garbage.+ installFetch({ [GROQ_HOST]: badBody, [KILO_HOST]: badBody, [OVH_HOST]: badBody, [POLLINATIONS_HOST]: badBody, [LLM7_HOST]: badBody });await expect(llm.llmComplete({ system: 's', user: 'u' })).rejects.toMatchObject({status: 502,code: 'upstream_bad_body',@@ -638,6 +674,7 @@ describe('llmComplete — failure modes', () => {installFetch({[GROQ_HOST]: openaiShape(''),[OPENROUTER_HOST]: openaiShape(''),+ [KILO_HOST]: openaiShape(''),[OVH_HOST]: openaiShape(''),[POLLINATIONS_HOST]: openaiShape(''),[LLM7_HOST]: openaiShape(''),diff --git a/tests/free-model-audit-lanes.test.js b/tests/free-model-audit-lanes.test.jsnew file mode 100644index 000000000..9e8b1816d--- /dev/null+++ b/tests/free-model-audit-lanes.test.js@@ -0,0 +1,62 @@+// The free-model audit's non-OpenRouter lanes (NVIDIA NIM, Kilo Code). Their+// catalogs are not authoritative, so the audit must only page ops for an id+// the model endpoint itself reports as gone (404/410), never for a catalog+// miss on a model that still answers, and never on our own outage.++import { describe, it, expect, afterEach, vi } from 'vitest';+import { auditCatalogLane } from '../api/cron/free-model-audit.js';++const BASE = 'https://catalog.example/v1';+const ids = ['vendor/alive', 'vendor/unlisted-but-serving', 'vendor/retired'];++function respond(status, body = {}) {+ return { ok: status >= 200 && status < 300, status, json: async () => body };+}++afterEach(() => vi.restoreAllMocks());++describe('auditCatalogLane', () => {+ it('flags only the catalog misses that answer 404/410 on a live call', async () => {+ const probed = [];+ globalThis.fetch = vi.fn(async (url, opts) => {+ if (String(url).endsWith('/models')) return respond(200, { data: [{ id: 'vendor/alive' }] });+ const { model, max_tokens } = JSON.parse(opts.body);+ probed.push(model);+ expect(max_tokens).toBe(1);+ return model === 'vendor/retired' ? respond(410) : respond(200);+ });+ const out = await auditCatalogLane({ lane: 'nvidia', base: BASE, key: 'k', ids });+ expect(out).toEqual({ lane: 'nvidia', checked: 3, live: 2, dead: ['vendor/retired'], status: 'dead_rungs' });+ // The listed id is never probed: the listing already vouched for it.+ expect(probed).toEqual(['vendor/unlisted-but-serving', 'vendor/retired']);+ });++ it('treats a busy or throttled model as alive, not retired', async () => {+ globalThis.fetch = vi.fn(async (url) => {+ if (String(url).endsWith('/models')) return respond(200, { data: [{ id: 'other/model' }] });+ return respond(429);+ });+ const out = await auditCatalogLane({ lane: 'kilo', base: BASE, key: null, ids });+ expect(out.status).toBe('ok');+ expect(out.dead).toEqual([]);+ });++ it('reports unknown and flags nothing when the catalog itself is unreachable', async () => {+ globalThis.fetch = vi.fn(async () => {+ throw new Error('fetch failed: ECONNRESET');+ });+ const out = await auditCatalogLane({ lane: 'kilo', base: BASE, key: null, ids });+ expect(out).toEqual({ lane: 'kilo', checked: 3, live: 0, dead: [], status: 'unknown' });+ });++ it('sends no Authorization header on a keyless lane', async () => {+ const headers = [];+ globalThis.fetch = vi.fn(async (url, opts) => {+ headers.push(opts?.headers || {});+ return respond(200, { data: ids.map((id) => ({ id })) });+ });+ const out = await auditCatalogLane({ lane: 'kilo', base: BASE, key: null, ids });+ expect(out.status).toBe('ok');+ expect(headers.every((h) => !('authorization' in h))).toBe(true);+ });+});diff --git a/tests/vertex-claude.test.js b/tests/vertex-claude.test.jsindex 691916784..b6f7a95d9 100644--- a/tests/vertex-claude.test.js+++ b/tests/vertex-claude.test.js@@ -169,13 +169,13 @@ describe('providerChain ordering under the four flag combinations', () => {// vertex-gemini reliability rung after the free lanes, plus groq#instant as// the free-tier capability step-down — both precede the paid backstops.it('off/off: no vertex-CLAUDE lane; free lanes → vertex-gemini → step-down → paid tail', () => {- expect(names()).toEqual(['groq', 'groq#120b', 'ovh', 'vertex-gemini', 'pollinations', 'groq#instant', 'anthropic']);+ expect(names()).toEqual(['groq', 'groq#120b', 'kilo', 'kilo:super', 'ovh', 'vertex-gemini', 'pollinations', 'llm7', 'groq#instant', 'anthropic']);});it('enabled/off: vertex claude is a paid backstop AHEAD of first-party anthropic, behind free lanes', () => {process.env.VERTEX_CLAUDE_ENABLED = '1';const n = names();- expect(n).toEqual(['groq', 'groq#120b', 'ovh', 'vertex-gemini', 'pollinations', 'groq#instant', 'vertex-anthropic', 'anthropic']);+ expect(n).toEqual(['groq', 'groq#120b', 'kilo', 'kilo:super', 'ovh', 'vertex-gemini', 'pollinations', 'llm7', 'groq#instant', 'vertex-anthropic', 'anthropic']);expect(n.indexOf('groq')).toBeLessThan(n.indexOf('vertex-anthropic'));expect(n.indexOf('vertex-anthropic')).toBeLessThan(n.indexOf('anthropic'));});@@ -192,7 +192,7 @@ describe('providerChain ordering under the four flag combinations', () => {it('primary flag alone (enabled unset) adds no vertex-claude lane', () => {process.env.VERTEX_CLAUDE_PRIMARY = '1';- expect(names()).toEqual(['groq', 'groq#120b', 'ovh', 'vertex-gemini', 'pollinations', 'groq#instant', 'anthropic']);+ expect(names()).toEqual(['groq', 'groq#120b', 'kilo', 'kilo:super', 'ovh', 'vertex-gemini', 'pollinations', 'llm7', 'groq#instant', 'anthropic']);});it('a caller BYOK key still leads even when vertex is primary', () => {