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
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.jsindex 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.jsnew file mode 100644index 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.');+ });+});