Skip to content

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.

13.5 KB
Raw Blame
// Every rung of the free chain must be REACHABLE, proven by failing the rungs
// above it at the transport level.
//
// Why transport level specifically: this repo has already shipped a fallback
// that only caught parse errors, so it was bypassed exactly when the provider
// failed (a dead socket, a DNS failure, an abort) rather than when it returned
// a bad body. A chain tested only with `errResp(500)` looks healthy while the
// real failure mode walks straight past it. Each case here kills the rungs
// above with a thrown fetch (ECONNRESET / abort), the way a provider actually
// dies, and asserts the next rung answers.
//
// The free chain is not a degradation path any more, it is production: the
// OpenAI account is billing-dead (429 billing_not_active) and the OpenRouter
// platform key's balance is spent, so these rungs carry the traffic.

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

vi.mock('../../api/_lib/gcp-auth.js', () => ({
	getGcpAccessToken: async () => 'fake-vertex-token',
}));

const HOSTS = {
	groq: 'api.groq.com',
	cerebras: 'api.cerebras.ai',
	openrouter: 'openrouter.ai',
	nvidia: 'integrate.api.nvidia.com',
	sambanova: 'api.sambanova.ai',
	mistral: 'api.mistral.ai',
	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',
	pollinations: 'text.pollinations.ai',
	llm7: 'api.llm7.io',
	siliconflow: 'api.siliconflow.com',
};

// The free chain in providerChain() order, with the env each rung needs. Groq
// appears THREE times on purpose: Groq meters tokens per model id, so each id is
// an independent 8k-tokens/minute bucket. The 27B lane leads, the 120B lane sits
// right behind it to widen the burst Groq absorbs, and the 20B instant lane is
// the last free rung, so reaching it means every rung between was tried and
// skipped.
const FREE_CHAIN = [
	{ provider: 'groq', host: HOSTS.groq, model: 'qwen/qwen3.8-27b' },
	{ provider: 'groq#120b', host: HOSTS.groq, model: 'openai/gpt-oss-120b' },
	{ provider: 'cerebras', host: HOSTS.cerebras, model: 'llama-3.3-70b' },
	{ provider: 'openrouter', host: HOSTS.openrouter, model: 'google/gemma-4-31b-it:free' },
	// A saturated free model 429s every key at once, so the lane also rotates
	// across alternate ':free' models, each on its own upstream pool.
	{ provider: 'openrouter:nemotron-3-super-120b-a12b', host: HOSTS.openrouter, model: 'nvidia/nemotron-3-super-120b-a12b:free' },
	{ provider: 'openrouter:qwen3.8-27b', host: HOSTS.openrouter, model: 'qwen/qwen3.8-27b:free' },
	// 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' },
	{ provider: 'cloudflare', host: HOSTS.cloudflare, model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast' },
	// 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: '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' },
];

const ENV_KEYS = [
	'GROQ_API_KEY',
	'CEREBRAS_API_KEY',
	'OPENROUTER_API_KEY',
	'OPENROUTER_FALLBACK_KEYS',
	'NVIDIA_API_KEY',
	'NVIDIA_FALLBACK_KEYS',
	'HF_TOKEN',
	'HF_FALLBACK_TOKENS',
	'SAMBANOVA_API_KEY',
	'MISTRAL_API_KEY',
	'ZAI_API_KEY',
	'CLOUDFLARE_ACCOUNT_ID',
	'CLOUDFLARE_AI_API_TOKEN',
	'SILICONFLOW_API_KEY',
	'LLM7_API_KEY',
	'KILO_API_KEY',
	'GEMINI_API_KEY',
	'GOOGLE_CLOUD_PROJECT',
	'GOOGLE_CLOUD_LOCATION_GEMINI',
	'ANTHROPIC_API_KEY',
	'OPENAI_API_KEY',
	'GROK_API_KEY',
	'VERTEX_CLAUDE_ENABLED',
	'VERTEX_CLAUDE_PRIMARY',
	'OPENROUTER_CLAUDE_MIRROR_MODEL',
	'NVIDIA_LANE_TIMEOUT_MS',
];

const saved = {};
let llm;

// Every free key configured, so the whole free chain is present in one run.
function configureFreeLanes() {
	process.env.GROQ_API_KEY = 'g';
	process.env.CEREBRAS_API_KEY = 'c';
	process.env.OPENROUTER_API_KEY = 'or';
	process.env.NVIDIA_API_KEY = 'nvapi-x';
	process.env.NVIDIA_FALLBACK_KEYS = 'nvapi-y';
	process.env.HF_TOKEN = 'hf-a';
	process.env.HF_FALLBACK_TOKENS = 'hf-b';
	process.env.SAMBANOVA_API_KEY = 'sn';
	process.env.MISTRAL_API_KEY = 'mi';
	process.env.ZAI_API_KEY = 'z';
	process.env.CLOUDFLARE_ACCOUNT_ID = 'cf-acct';
	process.env.CLOUDFLARE_AI_API_TOKEN = 'cf-token';
	process.env.SILICONFLOW_API_KEY = 'sf';
	process.env.LLM7_API_KEY = 'l7';
	process.env.GEMINI_API_KEY = 'gem';
	process.env.GOOGLE_CLOUD_PROJECT = 'test-project';
	// The NIM lane's own cap is floored at 2s; keep it there so a transport
	// failure test never waits on it.
	process.env.NVIDIA_LANE_TIMEOUT_MS = '2000';
}

const okOpenAiShape = (content, model) => ({
	ok: true,
	status: 200,
	json: async () => ({ choices: [{ message: { content } }], usage: { prompt_tokens: 5, completion_tokens: 7 }, model }),
	text: async () => '{}',
});

// How a provider dies for real: the socket drops, or the attempt is aborted.
// Neither produces a response object, so a fallback that only inspects a parsed
// body never runs.
function transportFailure(kind) {
	if (kind === 'abort') return Object.assign(new Error('The operation was aborted'), { name: 'AbortError' });
	return Object.assign(new Error('fetch failed: ECONNRESET'), { cause: { code: 'ECONNRESET' } });
}

beforeEach(async () => {
	for (const k of ENV_KEYS) {
		saved[k] = process.env[k];
		delete process.env[k];
	}
	vi.resetModules();
	llm = await import('../../api/_lib/llm.js');
});

afterEach(() => {
	for (const k of ENV_KEYS) {
		if (saved[k] === undefined) delete process.env[k];
		else process.env[k] = saved[k];
	}
	vi.restoreAllMocks();
});

describe('free chain: every rung is reachable through a transport-level failure', () => {
	it('lists the rungs in the documented order with every free key set', () => {
		configureFreeLanes();
		const names = llm.providerChain().map((p) => p.name);
		expect(names).toEqual(FREE_CHAIN.map((r) => r.provider));
	});

	// One case per rung: kill every rung above it the way a provider actually
	// dies (thrown fetch, not a 500 with a body), and require this rung to serve.
	for (const [i, rung] of FREE_CHAIN.entries()) {
		it(`reaches ${rung.provider} when the ${i} rung(s) above it fail at the transport level`, async () => {
			configureFreeLanes();
			const tried = [];

			globalThis.fetch = vi.fn(async (url, opts) => {
				const u = String(url);
				// The two Groq rungs share a host, so a rung is identified by
				// host AND requested model. Matching on host alone would make the 70B
				// lane and the instant lane indistinguishable, which is exactly the
				// pair this suite has to tell apart.
				const requested = JSON.parse(opts.body).model;
				// Multi-key rungs share host AND model, so the key tells them apart.
				const auth = opts.headers?.authorization;
				const idx = FREE_CHAIN.findIndex(
					(r) => u.includes(r.host) && r.model === requested && (!r.auth || auth === `Bearer ${r.auth}`),
				);
				expect(idx, `unexpected fetch: ${u} (${requested})`).toBeGreaterThanOrEqual(0);
				tried.push(FREE_CHAIN[idx].provider);
				// A rung above the target dies at the transport level. Alternate the
				// two shapes so both a dropped socket and an abort are covered, but
				// never abort a rung that SHARES the target's host. llmComplete treats
				// an abort as a host stall and then skips every later rung on that
				// host, which is deliberate (three Groq rungs must not each burn the
				// budget while api.groq.com is hanging) and would make this case
				// measure the stall guard instead of chain reachability.
				// Same reasoning for any host that serves more than one rung (the
				// OpenRouter models, the NIM and Hugging Face keys): aborting one
				// would skip its siblings as a stalled host.
				const sharedHost = FREE_CHAIN.filter((r) => r.host === FREE_CHAIN[idx].host).length > 1;
				if (idx < i) throw transportFailure(!sharedHost && idx % 2 === 1 ? 'abort' : 'reset');
				return okOpenAiShape(`served by ${FREE_CHAIN[idx].provider}`, rung.model);
			});

			const out = await llm.llmComplete({ system: 's', user: 'u', timeoutMs: 30_000 });
			expect(out.provider).toBe(rung.provider);
			expect(out.model).toBe(rung.model);
			expect(out.text).toBe(`served by ${rung.provider}`);
			// Every rung above it was actually attempted, so this is a real failover
			// and not an accidental reordering of the chain.
			expect(tried.length).toBeGreaterThanOrEqual(i + 1);
		}, 30_000);
	}

	// A rung that dies at the transport level must not take its own retry budget
	// with it: the chain records the attempt and keeps going, and the thrown
	// error names every rung when nothing survives.
	it('reports every rung when the whole free chain dies at the transport level', async () => {
		configureFreeLanes();
		globalThis.fetch = vi.fn(async () => {
			throw transportFailure('reset');
		});
		const err = await llm.llmComplete({ user: 'u', timeoutMs: 20_000 }).catch((e) => e);
		expect(err.status).toBe(502);
		const reported = err.attempts.map((a) => a.provider);
		for (const rung of FREE_CHAIN) expect(reported).toContain(rung.provider);
		// Each attempt carries its own transport error, not a shared last-error.
		expect(err.attempts.every((a) => a.skipped || /unreachable/.test(a.error))).toBe(true);
	}, 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 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);
			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('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 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, opts) => {
			const u = String(url);
			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 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');
	});
});