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
// POST /api/agents/:id/embed
// Generates a text embedding. Used by AgentMemory.recall() for semantic
// similarity search.
//
// Provider policy is NOT restated here: it is delegated to api/_lib/embeddings.js,
// the platform's single embedder registry (free NVIDIA NIM nemotron-3-embed-1b first,
// then the GCP-credit-funded Vertex lane, then OpenAI as the paid backstop). That
// module exists to prevent one specific trap: embeddings from different models are
// different vector spaces, and comparing across them yields plausible-looking
// garbage. So the response carries the registry's `embedder` tag (model + dim,
// e.g. "nvidia/nemotron-3-embed-1b@2048"). Callers that persist a vector must persist
// that tag beside it and only compare vectors sharing one.
//
// `inputType` matters for the same reason: NIM's retrieval models are asymmetric.
// Search strings embed as 'query' (the default, matching recall()); corpus text
// being stored for later retrieval embeds as 'passage'.
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../../_lib/auth.js';
import { cors, json, method, readJson, error, rateLimited } from '../../_lib/http.js';
import { limits } from '../../_lib/rate-limit.js';
import { sql } from '../../_lib/db.js';
import {
embedWith,
embedderInfo,
defaultIngestEmbedderTag,
embedderConfigured,
} from '../../_lib/embeddings.js';
export async function handleEmbed(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
if (!session && !bearer) return error(res, 401, 'unauthorized', 'sign in required');
// Match the sibling per-agent sub-resources (nfts.js / pumpfun.js): a bearer
// token must carry an appropriate scope to drive the embeddings API.
if (bearer && !hasScope(bearer.scope, 'mcp') && !hasScope(bearer.scope, 'profile')) {
return error(res, 403, 'insufficient_scope', 'requires mcp or profile scope');
}
const userId = session?.id || bearer?.userId;
// This route is namespaced per-agent and burns shared platform embedding
// keys, so it must enforce ownership of :id exactly like every other
// /api/agents/:id sub-resource — never embed against an agent the caller
// doesn't own.
const [agent] = await sql`
select id from agent_identities
where id = ${id} and user_id = ${userId} and deleted_at is null
limit 1
`;
if (!agent) return error(res, 404, 'not_found', 'agent not found');
const rl = await limits.embedUser(userId);
if (!rl.success) return rateLimited(res, rl);
const body = await readJson(req);
const text = body?.text;
if (!text || typeof text !== 'string' || !text.trim()) {
return error(res, 400, 'validation_error', 'text is required');
}
if (text.length > 8192) {
return error(res, 400, 'validation_error', 'text exceeds 8192 character limit');
}
const inputType = body?.inputType ?? 'query';
if (inputType !== 'query' && inputType !== 'passage') {
return error(res, 400, 'validation_error', "inputType must be 'query' or 'passage'");
}
// An explicit `embedder` lets a caller re-embed into the same space its stored
// vectors already live in, which is the whole point of tagging them.
const requested = body?.embedder;
let tag;
if (requested) {
if (!embedderInfo(requested)) {
return error(res, 400, 'validation_error', `unknown embedder: ${requested}`);
}
if (!embedderConfigured(requested)) {
return error(res, 503, 'not_configured', `embedder ${requested} is not configured on this server`);
}
tag = requested;
} else {
tag = defaultIngestEmbedderTag();
if (!tag) {
return error(res, 503, 'not_configured',
'No embedding provider configured. Set NVIDIA_API_KEY (free), GOOGLE_CLOUD_PROJECT, or OPENAI_API_KEY.');
}
}
const info = embedderInfo(tag);
let vector;
try {
[vector] = await embedWith(tag, [text.trim()], inputType);
} catch (err) {
console.error('[embed] provider failed', tag, err?.message);
return error(res, 502, 'upstream_error', `embedding service unavailable (${info.provider})`);
}
return json(res, 200, {
embedding: Array.from(vector),
embedder: info.tag,
model: info.model,
provider: info.provider,
dim: info.dim,
inputType,
});
}