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.

test(forge): pin the two-rung author chain behind restyle and the MCP material tools

nirholas90f27fc85705
diff --git a/tests/api/material-studio-store.test.js b/tests/api/material-studio-store.test.js
index d96107949..b38949181 100644
--- a/tests/api/material-studio-store.test.js
+++ b/tests/api/material-studio-store.test.js
@@ -76,7 +76,20 @@ vi.mock('../../api/_lib/watsonx.js', () => ({
})),
}));
+// The second rung of the restyle author chain. Granite leads, but a deployment
+// with no IBM key must still restyle through the shared free-first chain rather
+// than answering a dead 503. That is the behaviour the two fallback tests pin.
+vi.mock('../../api/_lib/llm.js', () => ({
+ llmComplete: vi.fn(async () => ({
+ text: JSON.stringify(watsonxReply),
+ model: 'free-chain/test-model',
+ })),
+}));
+
beforeEach(() => {
+ // Call counts leak across tests otherwise, and the author-chain tests below
+ // assert exactly which rung ran. mockClear keeps the factory implementations.
+ vi.clearAllMocks();
uploadedObjects = [];
fixtureBytes = readFileSync(FIXTURE_GLB_PATH);
watsonxReply = {
@@ -148,12 +161,38 @@ describe('restyleMaterialFromInstruction', () => {
expect(result.lineage[0].glbUrl).toBe(FIXTURE_URL);
});
- it('surfaces a not_configured error when watsonx has no credentials, without persisting anything', async () => {
+ it('restyles through the free-first LLM chain when watsonx has no credentials', async () => {
+ const { watsonxConfig, watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ watsonxConfig.mockReturnValueOnce({ configured: false });
+ const { restyleMaterialFromInstruction } = await import('../../api/_lib/material-studio-store.js');
+ const result = await restyleMaterialFromInstruction({ glbUrl: FIXTURE_URL, instruction: 'chrome' });
+ // Granite is skipped entirely, the fallback rung answers, and a real
+ // restyled GLB is persisted, with no 503 on a deployment lacking an IBM key.
+ expect(watsonxChatComplete).not.toHaveBeenCalled();
+ expect(llmComplete).toHaveBeenCalledTimes(1);
+ expect(result.glbUrl).toMatch(persistedGlbUrl('material-studio/restyle'));
+ expect(uploadedObjects).toHaveLength(1);
+ });
+
+ it('falls back to the LLM chain when watsonx is configured but throws', async () => {
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ watsonxChatComplete.mockRejectedValueOnce(new Error('watsonx 502'));
+ const { restyleMaterialFromInstruction } = await import('../../api/_lib/material-studio-store.js');
+ const result = await restyleMaterialFromInstruction({ glbUrl: FIXTURE_URL, instruction: 'chrome' });
+ expect(llmComplete).toHaveBeenCalledTimes(1);
+ expect(result.glbUrl).toMatch(persistedGlbUrl('material-studio/restyle'));
+ });
+
+ it('errors with no_provider only when BOTH author rungs are unavailable, without persisting anything', async () => {
const { watsonxConfig } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
watsonxConfig.mockReturnValueOnce({ configured: false });
- const { restyleMaterialFromInstruction, MaterialStudioError } = await import('../../api/_lib/material-studio-store.js');
+ llmComplete.mockRejectedValueOnce(new Error('no provider is configured'));
+ const { restyleMaterialFromInstruction } = await import('../../api/_lib/material-studio-store.js');
await expect(restyleMaterialFromInstruction({ glbUrl: FIXTURE_URL, instruction: 'chrome' })).rejects.toMatchObject({
- code: 'not_configured',
+ code: 'no_provider',
status: 503,
});
expect(uploadedObjects).toHaveLength(0);
diff --git a/tests/api/mcp3d-material-author-chain.test.js b/tests/api/mcp3d-material-author-chain.test.js
new file mode 100644
index 000000000..e4e533df4
--- /dev/null
+++ b/tests/api/mcp3d-material-author-chain.test.js
@@ -0,0 +1,121 @@
+/**
+ * Tests for the authoring-model chain behind the 3D Studio MCP's two
+ * language-model tools: generate_material and direct_prompt
+ * (api/_mcp3d/tools/studio.js).
+ *
+ * Both tools used to hard-throw "IBM watsonx.ai is not configured" whenever
+ * WATSONX_API_KEY was unset, which made them permanently dead on production
+ * even though the shared free-first chain (llmComplete) was one call away.
+ * These tests pin the replacement contract: Granite leads where configured, the
+ * free chain answers when it is not (or when it fails), and only an exhausted
+ * chain is an error.
+ *
+ * watsonx and llmComplete are the credential boundary and are mocked; the real
+ * tool handlers, real input schemas, and real JSON parsing run.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../api/_lib/rate-limit.js', () => ({
+ limits: { mcp3dGenerate: async () => ({ success: true, limit: 60, remaining: 59, reset: Date.now() + 60_000 }) },
+ clientIp: () => '203.0.113.9',
+}));
+
+const GRANITE_JSON = JSON.stringify({
+ name: 'Granite chrome',
+ pbrMetallicRoughness: { baseColorFactor: [0.8, 0.8, 0.8, 1], metallicFactor: 1, roughnessFactor: 0.05 },
+});
+const FALLBACK_JSON = JSON.stringify({
+ name: 'Fallback chrome',
+ prompt: 'A polished chrome sphere on a plain background.',
+ pbrMetallicRoughness: { baseColorFactor: [0.7, 0.7, 0.7, 1], metallicFactor: 1, roughnessFactor: 0.1 },
+});
+
+let watsonxConfigured = true;
+vi.mock('../../api/_lib/watsonx.js', () => ({
+ watsonxConfig: vi.fn(() => ({ configured: watsonxConfigured, chatModel: 'ibm/granite-3-8b-instruct' })),
+ watsonxChatComplete: vi.fn(),
+}));
+
+vi.mock('../../api/_lib/llm.js', () => ({
+ llmComplete: vi.fn(),
+}));
+
+// The handlers read auth.userId for the rate-limit key; a signed-out MCP caller
+// arrives with a rateKey instead. Either shape is valid, so pin the anonymous one.
+const AUTH = { userId: null, rateKey: 'test-caller' };
+
+async function toolNamed(name) {
+ const { toolDefs } = await import('../../api/_mcp3d/tools/studio.js');
+ const def = toolDefs.find((t) => t.name === name);
+ expect(def, `tool ${name} should exist`).toBeTruthy();
+ return def;
+}
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ watsonxConfigured = true;
+ // clearAllMocks resets call history but not a queued mockRejectedValueOnce,
+ // so a failure injected by one test would otherwise fire in the next. Re-pin
+ // both rungs' default implementations explicitly.
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ watsonxChatComplete.mockReset();
+ llmComplete.mockReset();
+ watsonxChatComplete.mockImplementation(async () => ({ text: GRANITE_JSON, model: 'ibm/granite-3-8b-instruct' }));
+ llmComplete.mockImplementation(async () => ({ text: FALLBACK_JSON, model: 'free-chain/test-model' }));
+});
+
+describe('generate_material author chain', () => {
+ it('uses IBM Granite when watsonx is configured', async () => {
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ const def = await toolNamed('generate_material');
+ const out = await def.handler({ description: 'polished chrome' }, AUTH);
+ expect(watsonxChatComplete).toHaveBeenCalledTimes(1);
+ expect(llmComplete).not.toHaveBeenCalled();
+ expect(out.structuredContent.material.name).toBe('Granite chrome');
+ });
+
+ it('answers through the free-first chain when watsonx has no credentials', async () => {
+ watsonxConfigured = false;
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ const def = await toolNamed('generate_material');
+ const out = await def.handler({ description: 'polished chrome' }, AUTH);
+ expect(watsonxChatComplete).not.toHaveBeenCalled();
+ expect(llmComplete).toHaveBeenCalledTimes(1);
+ expect(out.structuredContent.material.name).toBe('Fallback chrome');
+ });
+
+ it('falls back to the free-first chain when watsonx throws', async () => {
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ watsonxChatComplete.mockRejectedValueOnce(new Error('watsonx 502'));
+ const def = await toolNamed('generate_material');
+ const out = await def.handler({ description: 'polished chrome' }, AUTH);
+ expect(llmComplete).toHaveBeenCalledTimes(1);
+ expect(out.structuredContent.material.name).toBe('Fallback chrome');
+ });
+
+ it('errors only when BOTH rungs are unavailable, naming the real reason', async () => {
+ watsonxConfigured = false;
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ llmComplete.mockRejectedValueOnce(new Error('every provider refused'));
+ const def = await toolNamed('generate_material');
+ await expect(def.handler({ description: 'polished chrome' }, AUTH)).rejects.toThrow(/every provider refused/);
+ });
+});
+
+describe('direct_prompt author chain', () => {
+ it('answers through the free-first chain when watsonx has no credentials', async () => {
+ watsonxConfigured = false;
+ const { watsonxChatComplete } = await import('../../api/_lib/watsonx.js');
+ const { llmComplete } = await import('../../api/_lib/llm.js');
+ const def = await toolNamed('direct_prompt');
+ const out = await def.handler({ idea: 'a chrome sphere' }, AUTH);
+ expect(watsonxChatComplete).not.toHaveBeenCalled();
+ expect(llmComplete).toHaveBeenCalledTimes(1);
+ expect(out.structuredContent.optimized_prompt).toBe('A polished chrome sphere on a plain background.');
+ });
+});