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
// The catalog quality gate: the code that decides whether a platform-generated
// asset is allowed into the public catalog at /characters and /objects.
//
// It shipped wired into api/cron/forge-seed-cron.js and running in production
// with no tests, which is a bad place to have none: every rejection is content a
// visitor never sees, and every false accept is a blob on the storefront. The
// module is deliberately built so the decisions are pure (its own words: "unit
// testable without a GPU, a browser, or a model"), so there is no excuse.
//
// Fixtures are REAL binary glTF 2.0, built the same way tests/glb-quality.test.js
// builds them, not mocks: the gate reads accessor counts, POSITION bounds and
// material/texture presence straight out of the JSON chunk, so a hand-built GLB
// exercises the actual code path. Only the vision transport is substituted, and
// only because the alternative is calling a paid model from a unit test.
import { describe, it, expect } from 'vitest';
import {
gateMesh,
decideVisionVerdict,
scoreMean,
evaluateSeedAsset,
buildRigReadinessPrompt,
SEED_MESH_BOUNDS,
SEED_JUDGE_THRESHOLDS,
SEED_GATE_VERSION,
} from '../api/_lib/seed-quality.js';
// Minimal-but-valid binary glTF. The JSON chunk carries everything the gate
// reads; the BIN chunk only exists to give the file a realistic byte size.
function buildGlb(gltf, { binBytes = 0 } = {}) {
const json = Buffer.from(JSON.stringify(gltf), 'utf8');
const jsonPad = (4 - (json.length % 4)) % 4;
const jsonChunk = Buffer.concat([json, Buffer.alloc(jsonPad, 0x20)]);
const binPad = (4 - (binBytes % 4)) % 4;
const binChunk = binBytes ? Buffer.alloc(binBytes + binPad, 0) : Buffer.alloc(0);
const headerLen = 12;
const total = headerLen + (8 + jsonChunk.length) + (binBytes ? 8 + binChunk.length : 0);
const out = Buffer.alloc(total);
out.writeUInt32LE(0x46546c67, 0); // 'glTF'
out.writeUInt32LE(2, 4);
out.writeUInt32LE(total, 8);
out.writeUInt32LE(jsonChunk.length, 12);
out.writeUInt32LE(0x4e4f534a, 16); // 'JSON'
jsonChunk.copy(out, 20);
if (binBytes) {
const off = 20 + jsonChunk.length;
out.writeUInt32LE(binChunk.length, off);
out.writeUInt32LE(0x004e4942, off + 4); // 'BIN\0'
binChunk.copy(out, off + 8);
}
return out;
}
/** The shape a healthy Forge avatar takes: dense, indexed, textured, one mesh. */
function healthyGltf({ verts = 12_000, meshes = 1, textured = true, bbox = [-1, 1] } = {}) {
const tris = verts * 2;
const accessors = [
{ componentType: 5126, count: verts, type: 'VEC3', min: [bbox[0], bbox[0], bbox[0]], max: [bbox[1], bbox[1], bbox[1]] },
{ componentType: 5125, count: tris * 3, type: 'SCALAR' },
];
const primitive = { attributes: { POSITION: 0 }, indices: 1, mode: 4, ...(textured ? { material: 0 } : {}) };
return {
asset: { version: '2.0', generator: 'TRELLIS' },
accessors,
meshes: Array.from({ length: meshes }, () => ({ primitives: [primitive] })),
...(textured
? {
materials: [{ pbrMetallicRoughness: { baseColorTexture: { index: 0 } } }],
textures: [{ source: 0 }],
images: [{ mimeType: 'image/png', bufferView: 0 }],
}
: { materials: [{ pbrMetallicRoughness: { baseColorFactor: [0.5, 0.5, 0.5, 1] } }] }),
nodes: Array.from({ length: meshes }, (_, i) => ({ mesh: i })),
};
}
const healthyGlb = (opts, glbOpts) => buildGlb(healthyGltf(opts), { binBytes: 60_000, ...glbOpts });
describe('gateMesh: the free, deterministic first stage', () => {
it('accepts a dense, textured, single-mesh avatar', () => {
const v = gateMesh(healthyGlb());
expect(v.pass, `unexpected reasons: ${v.reasons.join(', ')}`).toBe(true);
expect(v.reasons).toEqual([]);
expect(v.metrics.vertexCount).toBe(12_000);
});
it('rejects bytes that are not a glTF at all, without throwing', () => {
const v = gateMesh(Buffer.from('this is a PNG, not a mesh'));
expect(v.pass).toBe(false);
expect(v.reasons).toContain('not_valid_glb');
});
it('rejects a mesh under the vertex floor', () => {
const v = gateMesh(healthyGlb({ verts: SEED_MESH_BOUNDS.minVertices - 1 }));
expect(v.pass).toBe(false);
expect(v.reasons).toContain('vertices_below_floor');
});
it('rejects an untextured asset while the texture requirement is on', () => {
// Catalog content is stricter than the interactive flow on purpose: a flat
// grey mesh is a legitimate user result but a poor storefront entry.
expect(SEED_MESH_BOUNDS.requireTexture).toBe(true);
const v = gateMesh(healthyGlb({ textured: false }));
expect(v.pass).toBe(false);
expect(v.reasons).toContain('no_textures');
});
it('rejects a collapsed bounding box that would render as a speck', () => {
const v = gateMesh(healthyGlb({ bbox: [0, 0] }));
expect(v.pass).toBe(false);
expect(v.reasons).toContain('zero_volume');
});
it('rejects a scene-like pile of meshes as an avatar but allows it as an accessory', () => {
const glb = healthyGlb({ meshes: 12 });
expect(gateMesh(glb, { category: 'avatar' }).reasons).toContain('too_many_meshes_for_a_character');
// A prop may legitimately be a loose collection of parts.
expect(gateMesh(glb, { category: 'accessory' }).reasons).not.toContain('too_many_meshes_for_a_character');
});
it('rejects a file below the byte floor even when the mesh JSON looks fine', () => {
const v = gateMesh(buildGlb(healthyGltf(), { binBytes: 0 }));
expect(v.pass).toBe(false);
expect(v.reasons).toContain('file_too_small');
});
it('collects every failure at once rather than stopping at the first', () => {
// One pass over the asset should tell a tuner everything that is wrong.
const v = gateMesh(buildGlb(healthyGltf({ verts: 10, textured: false }), { binBytes: 0 }));
expect(v.pass).toBe(false);
expect(v.reasons).toEqual(expect.arrayContaining(['vertices_below_floor', 'no_textures', 'file_too_small']));
});
});
describe('decideVisionVerdict: the judge replies turned into a decision', () => {
const goodRealism = { photorealism: 7, geometryIntegrity: 7, textureFidelity: 7, promptAdherence: 7 };
const goodRig = { subjectPresent: true, singleSubject: true, complete: true, limbsSeparated: true, blob: false };
it('accepts a clean pair of replies', () => {
const v = decideVisionVerdict({ realism: goodRealism, rigReadiness: goodRig, category: 'avatar' });
expect(v.pass).toBe(true);
expect(v.reasons).toEqual([]);
expect(v.mean).toBe(7);
});
it.each([
['blob', { blob: true }, 'vision_blob'],
['a missing subject', { subjectPresent: false }, 'vision_subject_missing'],
['a crowd', { singleSubject: false }, 'vision_multiple_subjects'],
['a bust', { complete: false }, 'vision_incomplete_body'],
['fused limbs', { limbsSeparated: false }, 'vision_fused_limbs'],
])('rejects %s', (_label, patch, reason) => {
const v = decideVisionVerdict({ realism: goodRealism, rigReadiness: { ...goodRig, ...patch }, category: 'avatar' });
expect(v.pass).toBe(false);
expect(v.reasons).toContain(reason);
});
it('does not apply the separated-limbs rule to an accessory', () => {
// A sword has no limbs; failing it for fused ones would reject every prop.
const rig = { ...goodRig, limbsSeparated: false };
expect(decideVisionVerdict({ realism: goodRealism, rigReadiness: rig, category: 'accessory' }).reasons).not.toContain(
'vision_fused_limbs',
);
});
it('rejects below each score floor, naming which floor failed', () => {
const t = SEED_JUDGE_THRESHOLDS;
const geo = decideVisionVerdict({
realism: { ...goodRealism, geometryIntegrity: t.minGeometryIntegrity - 1 },
rigReadiness: goodRig,
category: 'avatar',
});
expect(geo.reasons).toContain('geometry_below_floor');
const adherence = decideVisionVerdict({
realism: { ...goodRealism, promptAdherence: t.minPromptAdherence - 1 },
rigReadiness: goodRig,
category: 'avatar',
});
expect(adherence.reasons).toContain('prompt_adherence_below_floor');
// Sits exactly ON the geometry and adherence floors, so the mean is the only
// thing that can fail: an asset can be structurally sound and prompt-faithful
// and still be too poor overall to earn a catalog slot.
const low = { photorealism: 1, geometryIntegrity: t.minGeometryIntegrity, textureFidelity: 1, promptAdherence: t.minPromptAdherence };
const mean = decideVisionVerdict({ realism: low, rigReadiness: goodRig, category: 'avatar' });
expect(scoreMean(low)).toBeLessThan(t.minMean);
expect(mean.reasons).toEqual(['mean_score_below_floor']);
});
it('passes when neither reply arrived, so a silent judge cannot reject content', () => {
// The caller decides what an unavailable judge means; this function must not
// invent a rejection out of missing data.
const v = decideVisionVerdict({ realism: null, rigReadiness: null, category: 'avatar' });
expect(v.pass).toBe(true);
expect(v.mean).toBeNull();
});
});
describe('scoreMean', () => {
it('averages the four judged dimensions', () => {
expect(scoreMean({ photorealism: 8, geometryIntegrity: 6, textureFidelity: 4, promptAdherence: 2 })).toBe(5);
});
it('treats a missing dimension as zero rather than NaN', () => {
expect(scoreMean({ photorealism: 8 })).toBe(2);
expect(scoreMean(null)).toBe(0);
});
});
describe('evaluateSeedAsset: mesh fails closed, vision fails soft', () => {
const okTransport = (overrides = {}) => ({
name: 'test',
render: async () => Buffer.from('png'),
judgeRealism: async () => ({ photorealism: 8, geometryIntegrity: 8, textureFidelity: 8, promptAdherence: 8 }),
judgeRigReadiness: async () => ({
subjectPresent: true, singleSubject: true, complete: true, limbsSeparated: true, blob: false,
}),
...overrides,
});
it('never renders or judges an asset the mesh stage already rejected', async () => {
let rendered = false;
const v = await evaluateSeedAsset({
glbBuffer: Buffer.from('not a glb'),
glbUrl: 'https://cdn.example/a.glb',
prompt: 'a knight',
transport: okTransport({ render: async () => { rendered = true; return Buffer.from('png'); } }),
});
expect(v.accepted).toBe(false);
// The whole point of ordering the stages: a blob must not cost a model call.
expect(rendered).toBe(false);
expect(v.vision.status).toBe('skipped');
expect(v.gateVersion).toBe(SEED_GATE_VERSION);
});
it('accepts a clean asset through both stages', async () => {
const v = await evaluateSeedAsset({
glbBuffer: healthyGlb(),
glbUrl: 'https://cdn.example/a.glb',
prompt: 'a knight in plate armour',
transport: okTransport(),
});
expect(v.accepted).toBe(true);
expect(v.vision.status).toBe('judged');
expect(v.vision.mean).toBe(8);
expect(v.transport).toBe('test');
});
it('publishes a mesh-clean asset when the judge is unreachable, and says so', async () => {
// An infrastructure outage must never be recorded as a quality rejection,
// or the accept-rate statistics quietly become fiction.
const v = await evaluateSeedAsset({
glbBuffer: healthyGlb(),
glbUrl: 'https://cdn.example/a.glb',
prompt: 'a knight',
transport: okTransport({ render: async () => { throw new Error('vertex 429 quota'); } }),
});
expect(v.accepted).toBe(true);
expect(v.vision.status).toBe('unavailable');
expect(v.vision.error).toMatch(/vertex 429 quota/);
expect(v.reasons).toEqual([]);
});
it('marks vision unavailable when there is no public URL to render', async () => {
const v = await evaluateSeedAsset({
glbBuffer: healthyGlb(),
glbUrl: null,
prompt: 'a knight',
transport: okTransport(),
});
expect(v.accepted).toBe(true);
expect(v.vision.status).toBe('unavailable');
expect(v.vision.error).toMatch(/no public glb url/);
});
it('runs mesh-only with no transport at all (the cron default)', async () => {
const v = await evaluateSeedAsset({ glbBuffer: healthyGlb(), prompt: 'a knight' });
expect(v.accepted).toBe(true);
expect(v.vision.status).toBe('skipped');
expect(v.transport).toBeNull();
});
it('rejects on the vision verdict and reports the reason', async () => {
const v = await evaluateSeedAsset({
glbBuffer: healthyGlb(),
glbUrl: 'https://cdn.example/a.glb',
prompt: 'a knight',
transport: okTransport({
judgeRigReadiness: async () => ({
subjectPresent: true, singleSubject: true, complete: false, limbsSeparated: true, blob: false,
}),
}),
});
expect(v.accepted).toBe(false);
expect(v.reasons).toContain('vision_incomplete_body');
expect(v.mesh.pass).toBe(true);
});
});
describe('buildRigReadinessPrompt', () => {
it('asks for a whole humanoid for an avatar', () => {
const p = buildRigReadinessPrompt({ prompt: 'a knight', category: 'avatar' });
expect(p).toMatch(/exactly one complete humanoid character/);
expect(p).toMatch(/a knight/);
expect(p).toMatch(/ONLY a JSON object/);
});
it('asks for an object, not a character, for an accessory', () => {
const p = buildRigReadinessPrompt({ prompt: 'a bronze sword', category: 'accessory' });
expect(p).toMatch(/NOT a character/);
});
});