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.

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.js
index 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 is
diff --git a/api/_lib/glb-quality.js b/api/_lib/glb-quality.js
index 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_SC
if (!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.js
index 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, gr
url: '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.md
index 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.md
index 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 how
long 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 also
the 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 other
device (and every live avatar) is sent on to `/ar/view`, a Vite-bundled page
that generates a real USDZ from the GLB on the device so iPhone gets genuine