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
// Unit tests for POST /api/watsonx/embed, the standalone Granite embedding
// endpoint behind the watsonx Constellation.
//
// No network: the watsonx client and the platform embedding chain are both
// stubbed, so these lock down the handler's own contract:
// - input validation returns JSON 4xx, never a stack trace
// - the Granite lane serves the batch when watsonx is configured
// - the process-local cache is reused on a repeat call (cachedHits)
// - a watsonx failure falls through to the platform chain and still 200s
// - the regression this file exists for: a provider that answers only PART
// of the batch used to be treated as success, so the response shipped
// `null` where a vector belonged and the fallback tier was never tried.
// Now a short batch is a failure, the next provider covers it, and a
// response never contains a null vector.
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { Readable } from 'node:stream';
const state = {
wxConfigured: true,
// How many leading vectors the watsonx lane answers with; null means "all".
wxCoverage: null,
wxError: null,
fallbackConfigured: true,
fallbackError: null,
};
vi.mock('../../api/_lib/rate-limit.js', () => ({
limits: {
watsonxEmbedIp: vi.fn(async () => ({ success: true })),
watsonxEmbedGlobal: vi.fn(async () => ({ success: true })),
},
clientIp: vi.fn(() => '127.0.0.1'),
}));
// Deterministic 4-dim "embeddings": vector i leans on axis i % 4, so a test can
// tell Granite output (leading 1) from fallback output (leading 2) by value.
const graniteVec = (i) => [1, i, 0, 0];
const fallbackVec = (i) => [2, i, 0, 0];
vi.mock('../../api/_lib/watsonx.js', () => ({
watsonxConfig: vi.fn(() =>
state.wxConfigured
? {
configured: true,
url: 'https://wx',
projectId: 'proj',
apiVersion: '2024-05-31',
embedModel: 'ibm/granite-embedding-278m-multilingual',
}
: { configured: false },
),
watsonxEmbed: vi.fn(async (_cfg, { inputs, model }) => {
if (state.wxError) throw new Error(state.wxError);
const cover = state.wxCoverage === null ? inputs.length : state.wxCoverage;
const vectors = inputs.map((_, i) => (i < cover ? graniteVec(i) : []));
return { model, vectors, dimensions: 4, inputCount: inputs.length };
}),
}));
vi.mock('../../api/_lib/embeddings.js', () => ({
embeddingsConfigured: vi.fn(() => state.fallbackConfigured),
defaultIngestEmbedderTag: vi.fn(() => 'nvidia/nv-embedqa-e5-v5@1024'),
embedderInfo: vi.fn(() => ({
tag: 'nvidia/nv-embedqa-e5-v5@1024',
provider: 'nim',
model: 'nvidia/nv-embedqa-e5-v5',
dim: 4,
})),
embedPassages: vi.fn(async (_tag, texts) => {
if (state.fallbackError) throw new Error(state.fallbackError);
return texts.map((_, i) => Float64Array.from(fallbackVec(i)));
}),
// The handler walks the whole free-first embedder order through this rather
// than pinning the preferred lane, so one throttled lane no longer fails the
// endpoint while other lanes sit idle. The mock mirrors that contract: it
// reports which lane answered alongside the vectors.
embedPassagesAny: vi.fn(async (_preferredTag, texts) => {
if (state.fallbackError) throw new Error(state.fallbackError);
return {
tag: 'nvidia/nv-embedqa-e5-v5@1024',
info: {
tag: 'nvidia/nv-embedqa-e5-v5@1024',
provider: 'nim',
model: 'nvidia/nv-embedqa-e5-v5',
dim: 4,
},
vectors: texts.map((_, i) => Float64Array.from(fallbackVec(i))),
};
}),
}));
import { limits } from '../../api/_lib/rate-limit.js';
import { watsonxEmbed } from '../../api/_lib/watsonx.js';
import { embedPassages, embedPassagesAny } from '../../api/_lib/embeddings.js';
const handler = (await import('../../api/watsonx/embed.js')).default;
// `rawBody` sends the exact bytes instead of JSON.stringify(body), so a test can
// post literal `null`: valid JSON that is not an object.
function makeReq({ method = 'POST', body = null, rawBody = null } = {}) {
const payload = rawBody ?? (body === null ? null : JSON.stringify(body));
const req = payload === null ? Readable.from([]) : Readable.from([Buffer.from(payload)]);
req.method = method;
req.url = '/api/watsonx/embed';
req.headers = {
host: 'localhost',
'content-type': 'application/json',
origin: 'http://localhost',
};
return req;
}
function makeRes() {
return {
statusCode: 200,
headers: {},
body: '',
writableEnded: false,
setHeader(k, v) {
this.headers[k.toLowerCase()] = v;
},
getHeader(k) {
return this.headers[k.toLowerCase()];
},
end(chunk) {
if (chunk !== undefined) this.body += chunk;
this.writableEnded = true;
},
};
}
async function invoke(opts) {
const res = makeRes();
await handler(makeReq(opts), res);
return { status: res.statusCode, body: res.body ? JSON.parse(res.body) : null, res };
}
// Fresh text per test: the handler's vector cache is process-local and lives for
// the whole module, so reusing a string across tests would leak cache hits.
let seq = 0;
const uniqueTexts = (n) => {
seq += 1;
return Array.from({ length: n }, (_, i) => `probe ${seq} item ${i}`);
};
beforeEach(() => {
vi.clearAllMocks();
limits.watsonxEmbedIp.mockResolvedValue({ success: true });
limits.watsonxEmbedGlobal.mockResolvedValue({ success: true });
state.wxConfigured = true;
state.wxCoverage = null;
state.wxError = null;
state.fallbackConfigured = true;
state.fallbackError = null;
});
describe('POST /api/watsonx/embed validation', () => {
it('rejects a non-POST method', async () => {
const { status } = await invoke({ method: 'GET' });
expect(status).toBe(405);
});
it('rejects a missing texts field with a JSON 400', async () => {
const { status, body } = await invoke({ body: {} });
expect(status).toBe(400);
expect(body.error).toBe('bad_request');
expect(body.error_description).toContain('texts must be an array');
});
it('rejects a literal null body without throwing', async () => {
const { status, body } = await invoke({ rawBody: 'null' });
expect(status).toBe(400);
expect(body.error).toBe('bad_request');
});
it('rejects an empty batch and an oversized batch', async () => {
const empty = await invoke({ body: { texts: [] } });
expect(empty.status).toBe(400);
const tooMany = await invoke({ body: { texts: uniqueTexts(97) } });
expect(tooMany.status).toBe(400);
expect(tooMany.body.error_description).toContain('1 to 96');
});
it('rejects non-string and blank entries', async () => {
expect((await invoke({ body: { texts: ['ok', 7] } })).status).toBe(400);
expect((await invoke({ body: { texts: [' '] } })).status).toBe(400);
});
it('503s with an actionable message when no provider is configured', async () => {
state.wxConfigured = false;
state.fallbackConfigured = false;
const { status, body } = await invoke({ body: { texts: uniqueTexts(1) } });
expect(status).toBe(503);
expect(body.error).toBe('embed_unconfigured');
expect(body.error_description).toContain('WATSONX_API_KEY');
expect(body.vectors).toBeUndefined();
});
});
describe('POST /api/watsonx/embed provider chain', () => {
it('serves the Granite lane and preserves input order', async () => {
const texts = uniqueTexts(3);
const { status, body } = await invoke({ body: { texts } });
expect(status).toBe(200);
expect(body.model).toBe('ibm/granite-embedding-278m-multilingual');
expect(body.dimensions).toBe(4);
expect(body.count).toBe(3);
expect(body.cachedHits).toBe(0);
expect(body.vectors).toEqual([graniteVec(0), graniteVec(1), graniteVec(2)]);
expect(embedPassages).not.toHaveBeenCalled();
});
it('honours a caller-supplied model id', async () => {
await invoke({ body: { texts: uniqueTexts(1), model: 'ibm/granite-embedding-107m-multilingual' } });
expect(watsonxEmbed).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ model: 'ibm/granite-embedding-107m-multilingual' }),
);
});
it('reuses the process-local cache on a repeat call', async () => {
const texts = uniqueTexts(2);
await invoke({ body: { texts } });
const second = await invoke({ body: { texts } });
expect(second.status).toBe(200);
expect(second.body.cachedHits).toBe(2);
expect(second.body.vectors).toEqual([graniteVec(0), graniteVec(1)]);
// One upstream call total: the repeat was served entirely from cache.
expect(watsonxEmbed).toHaveBeenCalledTimes(1);
});
it('falls through to the platform chain when watsonx fails', async () => {
state.wxError = 'watsonx.ai error (503): service unavailable';
const texts = uniqueTexts(2);
const { status, body } = await invoke({ body: { texts } });
expect(status).toBe(200);
expect(body.model).toBe('nvidia/nv-embedqa-e5-v5');
expect(body.vectors).toEqual([fallbackVec(0), fallbackVec(1)]);
});
it('skips watsonx entirely when it is not configured', async () => {
state.wxConfigured = false;
const { status, body } = await invoke({ body: { texts: uniqueTexts(1) } });
expect(status).toBe(200);
expect(watsonxEmbed).not.toHaveBeenCalled();
expect(body.model).toBe('nvidia/nv-embedqa-e5-v5');
});
it('treats a partially-covered batch as a failure and lets the fallback cover it', async () => {
// watsonx answers 1 of 3. The old code returned 200 with two nulls.
state.wxCoverage = 1;
const texts = uniqueTexts(3);
const { status, body } = await invoke({ body: { texts } });
expect(status).toBe(200);
expect(body.model).toBe('nvidia/nv-embedqa-e5-v5');
expect(body.count).toBe(3);
expect(body.vectors).toHaveLength(3);
expect(body.vectors.every((v) => Array.isArray(v) && v.length === 4)).toBe(true);
// One call covers the whole batch, through whichever lane answers.
expect(embedPassagesAny).toHaveBeenCalledTimes(1);
});
// Every tier failing at the network level is upstream weather, not a bad
// request, so the handler answers a retryable 503 + Retry-After rather than a
// 502 a caller reads as permanent. The cause still names the last provider.
it('503s with the upstream cause when every provider fails', async () => {
state.wxError = 'watsonx.ai error (401): unauthorized';
state.fallbackError = 'nim embedder unreachable';
const { status, body } = await invoke({ body: { texts: uniqueTexts(2) } });
expect(status).toBe(503);
expect(body.error).toBe('embed_unavailable');
expect(body.error_description).toContain('nim embedder unreachable');
expect(body.vectors).toBeUndefined();
});
it('never serves a null vector when both tiers answer short', async () => {
state.wxCoverage = 0;
state.fallbackError = 'nim embedder unreachable';
const { status, body } = await invoke({ body: { texts: uniqueTexts(2) } });
expect(status).toBe(503);
expect(body.vectors).toBeUndefined();
});
});
describe('POST /api/watsonx/embed rate limits', () => {
it('429s on the per-IP limit before touching a provider', async () => {
limits.watsonxEmbedIp.mockResolvedValue({ success: false, limit: 20, remaining: 0, reset: Date.now() + 1000 });
const { status } = await invoke({ body: { texts: uniqueTexts(1) } });
expect(status).toBe(429);
expect(watsonxEmbed).not.toHaveBeenCalled();
});
it('429s on the global ceiling', async () => {
limits.watsonxEmbedGlobal.mockResolvedValue({ success: false, limit: 500, remaining: 0, reset: Date.now() + 1000 });
const { status } = await invoke({ body: { texts: uniqueTexts(1) } });
expect(status).toBe(429);
expect(watsonxEmbed).not.toHaveBeenCalled();
});
});