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
// Forge backend registry — registration + default-routing contract.
//
// Focuses on the free NVIDIA NIM lane (free-first platform policy): it is the
// default for draft AND standard tiers on text prompts WHEN configured, must
// never disturb other tiers or the geometry path, and must stay fully
// selectable. The provider module / live behavior is covered separately.
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import {
BACKENDS,
OUTPUTS,
resolveBackendId,
backendIsConfigured,
outputIsConfigured,
buildCatalog,
} from '../../api/_lib/forge-tiers.js';
describe('forge-tiers — NVIDIA NIM backend registration', () => {
const prevKey = process.env.NVIDIA_API_KEY;
const prevHf = process.env.HF_TOKEN;
// Default routing now consults free-lane config (NVIDIA + HF). Start every test
// with HF unset so the "no free image lane → paid last resort" assertions are
// deterministic; tests that exercise the HF default opt in explicitly.
beforeEach(() => {
delete process.env.HF_TOKEN;
});
afterEach(() => {
if (prevKey === undefined) delete process.env.NVIDIA_API_KEY;
else process.env.NVIDIA_API_KEY = prevKey;
if (prevHf === undefined) delete process.env.HF_TOKEN;
else process.env.HF_TOKEN = prevHf;
});
it('registers a platform-keyed, free image-path backend', () => {
const nv = BACKENDS.nvidia;
expect(nv).toBeTruthy();
expect(nv.provider).toBe('nvidia');
expect(nv.byok).toBe(false);
expect(nv.paths).toEqual(['image']);
expect(nv.requiresEnv).toEqual(['NVIDIA_API_KEY']);
expect(nv.free).toBe(true);
expect(nv.credits).toBeNull();
expect(nv.baseEta).toBeGreaterThan(0);
});
it('is configured only when NVIDIA_API_KEY is present', () => {
delete process.env.NVIDIA_API_KEY;
expect(backendIsConfigured('nvidia')).toBe(false);
process.env.NVIDIA_API_KEY = 'nvapi-test';
expect(backendIsConfigured('nvidia')).toBe(true);
});
describe('free-tier default routing', () => {
it('falls to the paid TRELLIS last resort only when no free image lane is configured', () => {
delete process.env.NVIDIA_API_KEY;
delete process.env.HF_TOKEN;
expect(resolveBackendId({ path: 'image', tier: 'draft', country: 'US' })).toBe('trellis');
expect(resolveBackendId({ path: 'image', tier: 'standard', country: 'US' })).toBe('trellis');
expect(resolveBackendId({ path: 'image', tier: 'high', country: 'US' })).toBe('trellis');
});
it('routes draft and standard tiers to the free NIM lane when configured', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
expect(resolveBackendId({ path: 'image', tier: 'draft', country: 'US' })).toBe('nvidia');
expect(resolveBackendId({ path: 'image', tier: 'standard', country: 'US' })).toBe('nvidia');
});
it('routes the high tier to the free textured engine, geometry stays BYOK Meshy', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.HF_TOKEN = 'hf_test';
// High is free-for-us too — the higher-quality HuggingFace engine, not paid Replicate.
expect(resolveBackendId({ path: 'image', tier: 'high', country: 'US' })).toBe('huggingface');
expect(resolveBackendId({ path: 'geometry', tier: 'draft', country: 'US' })).toBe('meshy');
expect(resolveBackendId({ path: 'geometry', tier: 'standard', country: 'US' })).toBe('meshy');
});
});
it('stays selectable at any tier when explicitly named', () => {
delete process.env.NVIDIA_API_KEY;
expect(resolveBackendId({ path: 'image', tier: 'standard', backend: 'nvidia', country: 'US' })).toBe('nvidia');
expect(resolveBackendId({ path: 'image', tier: 'high', backend: 'nvidia', country: 'US' })).toBe('nvidia');
});
it('keeps other backends selectable on the draft tier even when NIM is the default', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
expect(resolveBackendId({ path: 'image', tier: 'draft', backend: 'trellis', country: 'US' })).toBe('trellis');
});
it('surfaces the backend in the public catalog with honest estimates', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
process.env.HF_TOKEN = 'hf_test';
const cat = buildCatalog();
const nv = cat.backends.find((b) => b.id === 'nvidia');
expect(nv).toBeTruthy();
expect(nv.free).toBe(true);
expect(nv.configured).toBe(true);
expect(nv.byok).toBeNull();
const draftEst = nv.estimates.image.find((e) => e.tier === 'draft');
expect(draftEst.eta_seconds).toBeGreaterThan(0);
expect(draftEst.credits).toBeNull();
// The catalog is CDN-cached and country-agnostic, so it advertises the
// fail-closed default: a Tencent-model lane (HuggingFace Spaces) is never
// listed as a tier default because the requester's territory is unknown.
// With only NVIDIA + HuggingFace configured, NVIDIA is the one lane left.
expect(cat.default_backend_for_tier.draft.image).toBe('nvidia');
expect(cat.default_backend_for_tier.standard.image).toBe('nvidia');
expect(cat.default_backend_for_tier.high.image).toBe('nvidia');
});
// NVIDIA's hosted TRELLIS preview is text-only (rejects every user-image
// input — see tasks/nvidia-nim/probes/trellis.md). Photo submissions must
// never default onto it.
it('routes photo submissions to the standing image backend, not the text-only free lane', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
// Photo uploads at draft and standard must route to trellis (NVIDIA is text-only).
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: true, country: 'US' })).toBe('trellis');
expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: true, country: 'US' })).toBe('trellis');
// Prompt-only drafts and standard requests still get the free lane.
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: false, country: 'US' })).toBe('nvidia');
expect(resolveBackendId({ path: 'image', tier: 'draft', country: 'US' })).toBe('nvidia');
expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: false, country: 'US' })).toBe('nvidia');
expect(resolveBackendId({ path: 'image', tier: 'standard', country: 'US' })).toBe('nvidia');
});
it('honors an explicit nvidia selection in resolution (the handler owns the rejection)', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
expect(resolveBackendId({ path: 'image', tier: 'draft', backend: 'nvidia', userImages: true, country: 'US' })).toBe('nvidia');
});
it('declares the text-only capability in the public catalog', () => {
process.env.NVIDIA_API_KEY = 'nvapi-test';
const cat = buildCatalog();
expect(cat.backends.find((b) => b.id === 'nvidia').user_images).toBe(false);
expect(cat.backends.find((b) => b.id === 'trellis').user_images).toBe(true);
expect(cat.backends.find((b) => b.id === 'meshy').user_images).toBe(true);
});
});
// The free HuggingFace Spaces lane is the free option for PHOTO input — the
// counterpart to the text-only NVIDIA lane. It must surface in the catalog as a
// free, image-capable, platform-keyed engine gated on HF_TOKEN, and be an
// explicit opt-in (never the silent auto-default).
describe('forge-tiers — HuggingFace free image lane', () => {
const prev = process.env.HF_TOKEN;
const prevNv = process.env.NVIDIA_API_KEY;
beforeEach(() => {
delete process.env.NVIDIA_API_KEY;
});
afterEach(() => {
if (prev === undefined) delete process.env.HF_TOKEN;
else process.env.HF_TOKEN = prev;
if (prevNv === undefined) delete process.env.NVIDIA_API_KEY;
else process.env.NVIDIA_API_KEY = prevNv;
});
it('registers a free, platform-keyed image backend that accepts user photos', () => {
const hf = BACKENDS.huggingface;
expect(hf).toBeTruthy();
expect(hf.provider).toBe('huggingface');
expect(hf.byok).toBe(false);
expect(hf.paths).toEqual(['image']);
expect(hf.requiresEnv).toEqual(['HF_TOKEN']);
expect(hf.free).toBe(true);
expect(hf.userImages).toBe(true);
expect(hf.credits).toBeNull();
expect(hf.baseEta).toBeGreaterThan(0);
});
it('is configured only when HF_TOKEN is present', () => {
delete process.env.HF_TOKEN;
expect(backendIsConfigured('huggingface')).toBe(false);
process.env.HF_TOKEN = 'hf_test';
expect(backendIsConfigured('huggingface')).toBe(true);
});
it('surfaces in the catalog as a free, photo-capable, selectable engine', () => {
process.env.HF_TOKEN = 'hf_test';
const hf = buildCatalog().backends.find((b) => b.id === 'huggingface');
expect(hf).toBeTruthy();
expect(hf.free).toBe(true);
expect(hf.user_images).toBe(true);
expect(hf.byok).toBeNull();
expect(hf.configured).toBe(true);
const est = hf.estimates.image.find((e) => e.tier === 'standard');
expect(est.eta_seconds).toBeGreaterThan(0);
expect(est.credits).toBeNull();
});
it('stays selectable when explicitly named on the image path with photos', () => {
expect(
resolveBackendId({ path: 'image', tier: 'standard', backend: 'huggingface', userImages: true, country: 'US' }),
).toBe('huggingface');
});
// Free-for-us routing: the HF lane is the auto default for the cases NVIDIA's
// text-only preview can't serve — photo submissions at any tier, and the
// higher-quality High tier — so a free deployment never falls onto the paid
// Replicate lane for them.
it('becomes the auto default for photo submissions and the high tier when configured', () => {
process.env.HF_TOKEN = 'hf_test';
delete process.env.NVIDIA_API_KEY;
expect(resolveBackendId({ path: 'image', tier: 'draft', userImages: true, country: 'US' })).toBe('huggingface');
expect(resolveBackendId({ path: 'image', tier: 'standard', userImages: true, country: 'US' })).toBe('huggingface');
expect(resolveBackendId({ path: 'image', tier: 'high', country: 'US' })).toBe('huggingface');
expect(resolveBackendId({ path: 'image', tier: 'high', userImages: true, country: 'US' })).toBe('huggingface');
});
it('falls back to the paid lane only when no free engine is configured', () => {
delete process.env.HF_TOKEN;
delete process.env.NVIDIA_API_KEY;
expect(resolveBackendId({ path: 'image', tier: 'standard', country: 'US' })).toBe('trellis');
expect(resolveBackendId({ path: 'image', tier: 'high', country: 'US' })).toBe('trellis');
});
});
// The Hunyuan3D lane runs on its own Cloud Run worker. It must never report
// configured off the avatar pipeline's GCP_RECONSTRUCTION_URL — that service's
// face pipeline rejects every non-face image, so the lane looked live in the
// catalog while failing 100% of general prompts (prod incident 2026-06-12).
describe('forge-tiers — Hunyuan3D self-host configuration', () => {
const saved = {};
const VARS = ['GCP_HUNYUAN3D_URL', 'GCP_RECONSTRUCTION_URL', 'GCP_RECONSTRUCTION_KEY'];
beforeEach(() => {
for (const v of VARS) {
saved[v] = process.env[v];
delete process.env[v];
}
});
afterEach(() => {
for (const v of VARS) {
if (saved[v] === undefined) delete process.env[v];
else process.env[v] = saved[v];
}
});
it('requires the dedicated worker URL, not the avatar pipeline URL', () => {
expect(BACKENDS.hunyuan3d.requiresEnv).toEqual(['GCP_HUNYUAN3D_URL', 'GCP_RECONSTRUCTION_KEY']);
});
it('stays unconfigured when only the avatar pipeline is deployed', () => {
process.env.GCP_RECONSTRUCTION_URL = 'https://avatar-reconstruction.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
expect(backendIsConfigured('hunyuan3d')).toBe(false);
expect(buildCatalog().backends.find((b) => b.id === 'hunyuan3d').configured).toBe(false);
});
it('reports configured once its own worker URL and key are set', () => {
process.env.GCP_HUNYUAN3D_URL = 'https://hunyuan3d.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
expect(backendIsConfigured('hunyuan3d')).toBe(true);
expect(buildCatalog().backends.find((b) => b.id === 'hunyuan3d').configured).toBe(true);
});
});
// Game-Ready is a post-generation export option (not a generation backend). It
// must appear in the public catalog's `outputs` with honest ETA + price fields
// so the result view can advertise it, and report configured only when the
// remesh worker env is present.
describe('forge-tiers — Game-Ready export output', () => {
const saved = {};
const VARS = ['GCP_REMESH_URL', 'GCP_RECONSTRUCTION_KEY'];
beforeEach(() => {
for (const v of VARS) {
saved[v] = process.env[v];
delete process.env[v];
}
});
afterEach(() => {
for (const v of VARS) {
if (saved[v] === undefined) delete process.env[v];
else process.env[v] = saved[v];
}
});
it('registers a remesh-worker-backed export with quad + tri topologies and GLB/FBX formats', () => {
const gr = OUTPUTS.gameready;
expect(gr).toBeTruthy();
expect(gr.topologies).toEqual(['quad', 'tri']);
expect(gr.formats).toEqual(['glb', 'fbx']);
expect(gr.requiresEnv).toEqual(['GCP_REMESH_URL', 'GCP_RECONSTRUCTION_KEY']);
expect(gr.baseEta).toBeGreaterThan(0);
expect(gr.priceUsdcAtomics).toBeGreaterThan(0);
expect(gr.polyPresets.length).toBeGreaterThan(0);
});
it('reports configured only when the remesh worker URL and key are set', () => {
expect(outputIsConfigured('gameready')).toBe(false);
process.env.GCP_REMESH_URL = 'https://remesh.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
expect(outputIsConfigured('gameready')).toBe(true);
});
it('advertises the option in the public catalog with valid ETA + cost fields', () => {
process.env.GCP_REMESH_URL = 'https://remesh.example.run.app';
process.env.GCP_RECONSTRUCTION_KEY = 'secret';
const cat = buildCatalog();
expect(Array.isArray(cat.outputs)).toBe(true);
const gr = cat.outputs.find((o) => o.id === 'gameready');
expect(gr).toBeTruthy();
expect(gr.label).toBe('Game-Ready');
expect(gr.topologies).toEqual(['quad', 'tri']);
expect(gr.formats).toEqual(['glb', 'fbx']);
expect(gr.eta_seconds).toBeGreaterThan(0);
expect(gr.price_usdc_atomics).toBeGreaterThan(0);
expect(gr.price_usdc).toMatch(/^\d+\.\d{2}$/);
expect(gr.poly_presets.length).toBeGreaterThan(0);
expect(gr.configured).toBe(true);
});
it('reports the catalog output as not configured when the worker env is absent', () => {
const gr = buildCatalog().outputs.find((o) => o.id === 'gameready');
expect(gr.configured).toBe(false);
});
});