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.

5.2 KB
Raw Blame
// forge-run.js: drive ONE text to 3D generation on a FREE lane and report each
// real pipeline stage as it happens.
//
// This is the same zero-cost path the `forge_free` MCP tool and the /forge web
// page use: POST /api/forge with backend:'nvidia', path:'image' (no payment, no
// key), then poll /api/forge?job=<id> to a terminal state. The request names the
// free NVIDIA NIM (Microsoft TRELLIS) lane, but the API's free-first router may
// serve a different FREE engine (our self-host TRELLIS or Hunyuan3D worker, the
// HuggingFace lane) when NIM is down or a cheaper-for-us lane is warm. The lane
// that actually ran comes back as `backend` on every response, so the narration
// and the final frame name the real engine instead of the requested one. No
// fabricated progress: every onStage() call is fed by a real job/poll response.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// The API reports a scale-to-zero GPU worker's spin-up budget as
// `cold_start_seconds`; the shared narration reads it as `cold_seconds` (see
// src/shared/forge-frames.js). Translate here, exactly as the in-browser twin
// does in src/agent-screen.js, so both surfaces say "Waking up the … GPU worker"
// on the same signal instead of one of them going silent through the boot.
function stageState(data, extra = {}) {
	return {
		...data,
		cold_seconds: data?.cold_start_seconds,
		...extra,
	};
}

function shape(data, base) {
	const glbUrl = data.glb_url;
	return {
		glbUrl,
		viewerUrl: `${base}/viewer?src=${encodeURIComponent(glbUrl)}`,
		tier: data.tier || null,
		backend: data.backend || null,
		durable: Boolean(data.durable),
	};
}

// Run a single forge. Calls onStage(state) on each distinct real state, where
// `state` is the /api/forge response ({ status, backend, eta_seconds, … }) with
// `cold_seconds` translated in. Resolves to
// { glbUrl, viewerUrl, tier, backend, durable } or throws a holder-readable
// Error. `budgetMs` bounds the total poll time; `pollMs` is the interval.
//
// The caller owns the 'submitting' narration (it fires before this function is
// reached, so the screen is never blank while the POST is in flight); this
// function starts narrating at the first state the API actually reports.
export async function runForge({
	base,
	prompt,
	tier = 'draft',
	onStage,
	budgetMs = 180_000,
	pollMs = 3_000,
	fetchImpl = fetch,
}) {
	let submitRes;
	try {
		submitRes = await fetchImpl(`${base}/api/forge`, {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			// Ask for the free NVIDIA NIM (TRELLIS) lane. The API's free-first
			// router may serve another FREE engine instead; the response names it.
			body: JSON.stringify({ prompt, tier, backend: 'nvidia', path: 'image' }),
		});
	} catch (err) {
		throw new Error(`free 3D lane unreachable: ${err?.message || err}`);
	}
	const submit = await submitRes.json().catch(() => ({}));
	if (submitRes.status === 503) throw new Error(submit.message || 'the free 3D lane is not configured on this deployment');
	if (submitRes.status === 429) throw new Error(submit.message || 'free 3D lane busy, try again shortly');
	// The High tier is $THREE hold-or-pay gated (api/forge.js, feature
	// 'forge.high'), and this worker submits unauthenticated, so a 402 here is a
	// tier choice, not an outage. Name the recovery instead of leaking a raw
	// paywall message into the live screen.
	if (submitRes.status === 402) {
		throw new Error(
			`${submit.message || 'this tier is gated'} Run this worker at FORGE_TIER=draft or standard, which are ungated.`,
		);
	}

	// A warm lane can finish inside the submit window: accept a synchronous done.
	if (submit.status === 'done' && submit.glb_url) {
		onStage?.(stageState(submit));
		return shape(submit, base);
	}
	if (!submitRes.ok || !submit.job_id) {
		throw new Error(submit.message || `forge returned ${submitRes.status}`);
	}

	// Narrate the accepted job with everything the submit response knows: which
	// free engine took it, and whether a scale-to-zero GPU worker has to boot
	// first. Without these the line degrades to a lane-agnostic "Queued" and the
	// cold-start wait reads as a stall.
	onStage?.(stageState(submit));

	const deadline = Date.now() + budgetMs;
	let lastStatus = 'queued';
	while (Date.now() < deadline) {
		await sleep(pollMs);
		let res;
		try {
			res = await fetchImpl(`${base}/api/forge?job=${encodeURIComponent(submit.job_id)}`, {
				headers: { accept: 'application/json' },
			});
		} catch {
			continue; // transient network blip, keep polling within the budget
		}
		const data = await res.json().catch(() => ({}));
		if (!res.ok) {
			if (res.status >= 500) continue;
			throw new Error(data.message || `forge poll returned ${res.status}`);
		}
		if (data.status && data.status !== lastStatus) {
			lastStatus = data.status;
			// The poll response repeats `backend` from the job record, so a lane
			// that only reveals itself after a failover still gets named.
			onStage?.(stageState(data, { backend: data.backend ?? submit.backend }));
		}
		if (data.status === 'done' && data.glb_url) return shape(data, base);
		if (data.status === 'failed') throw new Error(data.error || 'generation failed, try a more concrete prompt');
	}
	throw new Error(`generation did not finish within ${Math.round(budgetMs / 1000)}s`);
}