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
fix(forge): read the model quality gate and the LLM lane from one env resolver
nirholasdb9fd6191a76
diff --git a/api/_lib/env.js b/api/_lib/env.jsindex fd41d704e..43243c866 100644--- a/api/_lib/env.js+++ b/api/_lib/env.js@@ -621,6 +621,17 @@ export const env = {return opt('SILICONFLOW_API_KEY');},+ // LLM7.io key (dash.llm7.io). This rung was added 2026-08-05 as a KEYLESS+ // anonymous tier; llm7.io retired that tier and the endpoint now answers+ // every unauthenticated request with 401 invalid_api_key (measured+ // 2026-09-02, including the "unused" token its docs used to accept). The+ // rung is therefore key-gated like every other optional one, so a+ // deployment without the key skips it instead of spending a guaranteed+ // round trip on it at the tail of the free chain.+ get LLM7_API_KEY() {+ return opt('LLM7_API_KEY');+ },+// Cloudflare account id for Workers AI (dash.cloudflare.com). The Workers// AI OpenAI-compatible URL embeds the account id, so the LLM rung needs// this AND CLOUDFLARE_AI_API_TOKEN; with either half missing the rung isdiff --git a/api/_lib/glb-quality.js b/api/_lib/glb-quality.jsindex f0f5356c0..7fb973ff4 100644--- a/api/_lib/glb-quality.js+++ b/api/_lib/glb-quality.js@@ -25,6 +25,13 @@ function intEnv(name, fallback) {return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;}+// Same, for a 0..1 ratio threshold that must keep its fractional part.+function ratioEnv(name, fallback) {+ const v = typeof process !== 'undefined' ? process.env?.[name] : null;+ const n = v == null || v === '' ? NaN : Number(v);+ return Number.isFinite(n) && n >= 0 && n <= 1 ? n : fallback;+}+export const QUALITY_THRESHOLDS = Object.freeze({// Below this triangle count the mesh is treated as degenerate (effectively empty).degenerateTriangles: intEnv('FORGE_QUALITY_MIN_TRIS', 80),@@ -33,6 +40,16 @@ export const QUALITY_THRESHOLDS = Object.freeze({// A bounding-box diagonal at or below this (in the mesh's own units) is a// collapsed / zero-volume result — the classic "black dot" TRELLIS failure.minBboxDiagonal: 1e-4,+ // At or below this flatness (thinnest extent / longest extent) the mesh is a+ // slab, not a solid. This is NOT degeneracy on its own: a plate, a coin, a rug+ // and a poster are all legitimately flat. It means the cheap scorer cannot+ // vouch for the result, so the mesh must escalate to vision QA rather than be+ // trusted. See the `planar` note on shouldEscalateToVisionQA.+ planarFlatness: ratioEnv('FORGE_QUALITY_PLANAR_FLATNESS', 0.2),+ // The same test for a mesh thin in X or Z rather than in Y. Upright subjects are+ // legitimately narrow front-to-back (a standing figure runs about 0.19), so this+ // bar is far stricter: only a sliver no solid object could be.+ sliverFlatness: ratioEnv('FORGE_QUALITY_SLIVER_FLATNESS', 0.05),});// Pull the per-attribute vertex count and union the POSITION bounding box across@@ -88,6 +105,17 @@ function summarizeGeometry(gltf) {? [max[0] - min[0], max[1] - min[1], max[2] - min[2]].map((d) => (Number.isFinite(d) ? Math.abs(d) : 0)): [0, 0, 0];const bboxDiagonal = Math.sqrt(size[0] ** 2 + size[1] ** 2 + size[2] ** 2);+ // Flatness = thinnest extent / longest extent. 1 is a cube, 0 is a plane.+ // The diagonal above measures how BIG the mesh is; this measures whether it+ // has any depth at all, which is the axis a collapsed reconstruction fails on+ // while staying large enough to look healthy by every other metric.+ const longest = Math.max(size[0], size[1], size[2]);+ const shortest = Math.min(size[0], size[1], size[2]);+ const flatness = haveBounds && longest > 0 ? shortest / longest : null;+ // Which axis is the thin one matters. glTF is Y-up, so a mesh thin in Y is a+ // pancake lying on the ground, while a mesh thin in X or Z is usually just a+ // slim upright subject (a standing figure is genuinely narrow front-to-back).+ const thinAxis = flatness == null ? null : ['x', 'y', 'z'][size.indexOf(shortest)];return {vertexCount,@@ -97,6 +125,8 @@ function summarizeGeometry(gltf) {texturedPrimitives,bbox: haveBounds ? { min, max, size } : null,bboxDiagonal: Number.isFinite(bboxDiagonal) ? bboxDiagonal : 0,+ flatness: Number.isFinite(flatness) ? flatness : null,+ thinAxis,};}@@ -241,6 +271,19 @@ export function scoreGlbQuality(buf, { allowPartial = false } = {}) {reasons.push('zero_volume');}+ // A slab-shaped result: large and dense enough to pass every check above, but+ // with no depth. An image-to-3D reconstruction that loses its conditioning+ // collapses to exactly this (a full-footprint relief), and it is otherwise the+ // highest-confidence output the scorer can produce. Recorded as a signal, not+ // a verdict: legitimately flat subjects exist, so vision QA makes the call.+ // Thin in Y is the shape a lost reconstruction takes (a pancake on the ground).+ // Thin in X or Z is usually a real slim upright subject, so it only counts when+ // it is so extreme that no solid object could have that profile.+ const planar =+ geo.flatness != null &&+ (geo.thinAxis === 'y' ? geo.flatness <= t.planarFlatness : geo.flatness <= t.sliverFlatness);+ if (planar) reasons.push('planar');+// Soft quality checks → flag low.let low = false;if (!degenerate && geo.triangleCount < t.lowTriangles) {@@ -279,6 +322,9 @@ export function scoreGlbQuality(buf, { allowPartial = false } = {}) {meshCount: base.meshCount,primitiveCount: geo.primitiveCount,bboxDiagonal: Math.round(geo.bboxDiagonal * 1e6) / 1e6,+ flatness: geo.flatness == null ? null : Math.round(geo.flatness * 1e6) / 1e6,+ thinAxis: geo.thinAxis ?? null,+ planar,hasMaterials: mat.hasMaterials,hasTextures: mat.hasTextures,materialCount: mat.materialCount,@@ -322,6 +368,13 @@ const ADAPTIVE_TRUST_SCORE = (() => {// • an `ok` mesh scoring below the trust threshold: structurally fine but// mediocre, the "valid but doesn't look like what I asked for" middle that// the structural scorer alone can't catch.+// • a `planar` mesh: dense, textured and large, but with no depth. An+// image-to-3D reconstruction that loses its conditioning collapses to a+// full-footprint slab that scores near the top of this scale (0.976 measured+// on a live free-lane result), so density and texture presence actively+// vouch for the one failure they cannot see. Flatness alone cannot convict+// it either, because plates, coins, rugs and posters are genuinely flat, so+// the decision belongs to the render-based judge.// A missing quality signal escalates (we cannot vouch for what we did not score).//// This is what lets the free lane gain a semantic quality floor without turning@@ -330,6 +383,7 @@ export function shouldEscalateToVisionQA(quality, { minScore = ADAPTIVE_TRUST_SCif (!quality || typeof quality !== 'object') return true;if (quality.flag !== 'ok') return true;if (quality.metrics && quality.metrics.hasTextures === false) return true;+ if (quality.metrics && quality.metrics.planar === true) return true;const score = Number(quality.score);if (!Number.isFinite(score)) return true;return score < minScore;diff --git a/api/_lib/llm.js b/api/_lib/llm.jsindex 432241e3d..95b8e2594 100644--- a/api/_lib/llm.js+++ b/api/_lib/llm.js@@ -126,11 +126,13 @@ const CLOUDFLARE_MODEL = '@cf/meta/llama-3.3-70b-instruct-fp8-fast';// of the free section; enable_thinking:false (extraBody below) keeps Qwen3's// reasoning mode off so message.content carries the actual answer.const SILICONFLOW_MODEL = 'Qwen/Qwen3-8B';-// LLM7.io keyless anonymous tier (api.llm7.io): community-run gateway, no-// key and no signup, about 30 req/min per IP. Free catalog probed live-// 2026-08-05; gemini-3.1-flash-lite returned real content there, while the-// gpt-oss route spends its token budget on reasoning and can hand back an-// empty content field, so it is deliberately not used.+// LLM7.io (api.llm7.io): community-run gateway, about 30 req/min per IP. Free+// catalog probed live 2026-08-05; gemini-3.1-flash-lite returned real content+// there, while the gpt-oss route spends its token budget on reasoning and can+// hand back an empty content field, so it is deliberately not used. Added as a+// KEYLESS rung; llm7.io has since retired its anonymous tier and answers every+// unauthenticated request with 401 invalid_api_key (measured 2026-09-02), so+// the rung is now gated on LLM7_API_KEY and skipped without one.const LLM7_MODEL = 'gemini-3.1-flash-lite';// Pollinations' keyless anonymous tier: also no key, routes to a hosted// gpt-oss-20b. Smaller than the 70B rungs above it, so it sits in the@@ -612,14 +614,18 @@ export function providerChain({ anthropicKey, anthropicModel, grokKey = null, grurl: 'https://text.pollinations.ai/openai',model: POLLINATIONS_MODEL,}));- // LLM7.io keyless anonymous tier: the third no-key rung. Sits with the- // step-down group (flash-lite class) right after Pollinations, so even a- // zero-env deployment has three independent keyless lanes to fall through.- chain.push(openaiCompatProvider({- name: 'llm7',- url: 'https://api.llm7.io/v1/chat/completions',- model: LLM7_MODEL,- }));+ // LLM7.io: sits with the step-down group (flash-lite class) right after+ // Pollinations. Skipped without a key, because an unauthenticated call here+ // is now a guaranteed 401: leaving it in the chain unconditionally spends a+ // round trip per exhaustion for an answer that cannot arrive.+ if (env.LLM7_API_KEY) {+ chain.push(openaiCompatProvider({+ name: 'llm7',+ key: env.LLM7_API_KEY,+ url: 'https://api.llm7.io/v1/chat/completions',+ model: LLM7_MODEL,+ }));+ }// SiliconFlow free tier: keyed 8B step-down on its own quota pool.// enable_thinking:false forces Qwen3 out of reasoning mode so the answer// lands in message.content instead of a reasoning field.diff --git a/docs/ar.md b/docs/ar.mdindex 0bd36268a..b5b4c218f 100644--- a/docs/ar.md+++ b/docs/ar.md@@ -497,4 +497,4 @@ the wild can load.- [Walk feature](/features/walk) — WebXR immersive walk mode (different from placement AR)- [Web component reference](/docs/web-component): full `<agent-3d>` attribute list- [Embedding guide](/docs/embedding) — iframe setup with XR permissions-- [Tutorial: Place your model in AR](/docs/tutorials/view-in-ar)+- [Tutorial: Place your model in AR](/tutorials/view-in-ar)diff --git a/docs/mcp-studio.md b/docs/mcp-studio.mdindex 8039cc911..dd0cf50ba 100644--- a/docs/mcp-studio.md+++ b/docs/mcp-studio.md@@ -154,11 +154,17 @@ carrying a pollable handle, and the job keeps running server-side."status": "pending","jobId": "f1.eyJwIjoiZ2NwIiw…","pollUrl": "https://three.ws/api/gpt-forge?job=f1.eyJwIjoiZ2NwIiw…",+ "stage": "mesh","etaRemainingSeconds": 42,"prompt": "a friendly round robot mascot, glossy white plastic"}```+`stage` names which half of the pipeline is still running, `mesh` or `rig`, so a+client that collects the job knows whether the GLB it gets back is a bare mesh+still to be rigged or the finished rig. It carries no identifier, so it costs the+data-minimization rule nothing.+`etaRemainingSeconds` is the live estimate for the lane actually running the job(its typical duration minus time already elapsed), so the assistant knows howlong to wait rather than retrying blind. Call `check_job` with that `jobId` to@@ -348,7 +354,15 @@ any surface that rides it. The agent-facing REST endpoints (`/api/3d/generate`,The inline widget loads Google's `<model-viewer>` from one pinned URL in[`api/_lib/model-viewer-cdn.js`](../api/_lib/model-viewer-cdn.js), which is alsothe origin the widget's `openai/widgetCSP` allowlists, so the script tag and its-CSP entry cannot drift apart. The `/api/ar` launcher no longer inlines a+CSP entry cannot drift apart. That module pins 3.5.0 for every server-rendered+embed, the build the rest of the platform's embeddable bundles ship, so a host+page that already loaded one three.ws embed reuses the same module instead of+registering a second, conflicting custom element. The standalone+[`/viewer`](../public/viewer.html) page and the Vite-bundled first-party pages+deliberately sit on 4.0.0 instead: they own their whole document and have no+custom-element collision to avoid. The header comment in+`api/_lib/model-viewer-cdn.js` names all three pins and why each surface takes+the build it takes. The `/api/ar` launcher no longer inlines a`<model-viewer>` of its own: Android gets a Scene Viewer intent, and every otherdevice (and every live avatar) is sent on to `/ar/view`, a Vite-bundled pagethat generates a real USDZ from the GLB on the device so iPhone gets genuine