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
// 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');
});
});