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/persona/extract
// Synthesizes a structured persona JSON from a short onboarding interview.
// Runs through the shared LLM helper (api/_lib/llm.js), which owns the ordered
// failover chain (free lanes first, the GCP-credits Vertex anchor behind them,
// the paid server keys last), so a single upstream 429/5xx falls through to the
// next provider instead of returning a hard 502. Do not restate the provider
// order here: providerChain() in api/_lib/llm.js is the only source of truth
// for it, and a copy of the list in this comment goes stale silently.
import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { limits } from '../_lib/rate-limit.js';
import { llmComplete, LlmUnavailableError, promptTokens } from '../_lib/llm.js';
const MAX_ANSWERS = 12;
const MAX_QA_CHARS = 1200;
async function resolveUser(req) {
const session = await getSessionUser(req);
if (session) return session.id;
const bearer = await authenticateBearer(extractBearer(req), { audience: undefined });
if (!bearer) return null;
if (!hasScope(bearer.scope, 'avatars:read') && !hasScope(bearer.scope, 'avatars:write')) {
return null;
}
return bearer.userId;
}
const MAX_FREEFORM_CHARS = 8000;
function validateInput(input) {
if (!input || typeof input !== 'object') {
throw Object.assign(new Error('body must be an object'), { status: 400 });
}
if (typeof input.freeform === 'string' && input.freeform.trim()) {
return { mode: 'freeform', text: input.freeform.trim().slice(0, MAX_FREEFORM_CHARS) };
}
const list = input.answers;
if (!Array.isArray(list) || list.length === 0) {
throw Object.assign(new Error('provide answers array or freeform text'), { status: 400 });
}
if (list.length > MAX_ANSWERS) {
throw Object.assign(new Error(`max ${MAX_ANSWERS} answers`), { status: 400 });
}
const cleaned = [];
for (const row of list) {
if (!row || typeof row !== 'object') {
throw Object.assign(new Error('each answer must be an object'), { status: 400 });
}
const q = typeof row.question === 'string' ? row.question.trim() : '';
const a = typeof row.answer === 'string' ? row.answer.trim() : '';
if (!q || !a) {
throw Object.assign(new Error('each answer needs question + answer'), { status: 400 });
}
cleaned.push({
question: q.slice(0, MAX_QA_CHARS),
answer: a.slice(0, MAX_QA_CHARS),
});
}
return { mode: 'interview', answers: cleaned };
}
const SYSTEM_PROMPT = `You are a persona-extraction analyst. You read a short interview between an onboarding system and a person, and you synthesize a compact persona profile that can later be used to shape an AI agent's voice on behalf of that person.
Return ONLY a single JSON object (no markdown fences, no prose) with EXACTLY these fields:
{
"tone": string // one-line summary of how this person sounds, 8-20 words
"vocabulary": string[] // 5-10 distinctive words or short phrases the user actually gravitates to, drawn from their answers when possible
"interests": string[] // 3-5 concrete topics/domains
"communication_style": "terse" | "detailed" | "playful" | "analytical" | "warm"
"dont_say": string[] // 1-3 phrases the agent should avoid (things the user explicitly dislikes, or that would clash with their voice)
"sample_greeting": string // one greeting (1-2 sentences) the agent would open with, written entirely in this persona's voice
}
Rules:
- "communication_style" MUST be exactly one of the five listed strings.
- Prefer evidence from the user's actual words over generic guesses.
- If the interview is sparse, infer conservatively rather than fabricate.
- No trailing commas. No comments. No markdown. JUST the JSON object.`;
const handler = wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const userId = await resolveUser(req);
if (!userId) {
return error(res, 401, 'unauthorized', 'Sign in to build your persona.');
}
// Validate BEFORE metering. The limiter exists to bound LLM spend (see below),
// and a rejected body spends nothing, so charging it against a 5/day budget
// just burns the user's quota on their own typos.
const body = await readJson(req);
const input = validateInput(body);
// Each call is a metered LLM completion, so meter per user as well: a
// free-signup loop must not be able to run up an unbounded bill (5/day,
// matching the sibling agents/:id/persona route).
const rl = await limits.personaExtract(userId);
if (!rl.success) return rateLimited(res, rl);
let userMessage;
if (input.mode === 'freeform') {
userMessage = `Analyze the following text and synthesize a persona JSON that captures the voice, personality, and communication patterns present in it.\n\n---\n${input.text}\n---`;
} else {
const interview = input.answers
.map((row, i) => `Q${i + 1}: ${row.question}\nA${i + 1}: ${row.answer}`)
.join('\n\n');
userMessage = `Here is the onboarding interview. Synthesize the persona JSON.\n\n${interview}`;
}
const t0 = Date.now();
let completion;
try {
completion = await llmComplete({
system: SYSTEM_PROMPT,
user: userMessage,
maxTokens: 800,
// Attribution for the spend ledger. Without it this lane's cost is
// invisible on the admin dashboard AND llmComplete skips its per-user
// daily USD cap, which only engages when a userId is known. The 5/day
// limiter above bounds the call COUNT; this bounds the bill.
track: { userId, tool: 'persona-extract' },
});
} catch (err) {
if (err instanceof LlmUnavailableError) {
// The caller cannot act on which server-side key is missing, and naming
// the env vars in a public response advertises our provider inventory.
// The operator sees the real cause in this log line.
console.error('[persona/extract] no LLM provider configured');
return error(res, 503, 'config_missing',
'Persona extraction is not available right now. Please try again later.');
}
if (err?.code === 'daily_spend_cap_exceeded') {
// A budget ceiling, not an outage: "try again" would be a lie for the
// rest of the day, so pass the real reason and reset window through.
return error(res, 429, 'daily_spend_cap_exceeded', err.message);
}
// Flat 502: every provider failure here is server-side, so the upstream's
// own status must not become the caller's (an expired key answering 401
// would otherwise read to the client as "your session ended").
console.error('[persona/extract] all providers failed', err?.status || '', err?.message);
return error(res, 502, 'upstream_error', 'Persona extraction is briefly unavailable. Please try again.');
}
// llmComplete prefers returning an empty-but-valid completion over throwing
// when every provider answered 200 with no content. That is a failure for this
// endpoint, not a persona, so surface it as a retryable 502 rather than
// letting JSON.parse('') report it as a malformed model response.
const raw = completion.text;
if (!raw) {
return error(res, 502, 'upstream_error', 'The model returned an empty response. Please try again.');
}
let persona;
try {
const stripped = raw
.trim()
.replace(/^```(?:json)?\s*/i, '')
.replace(/\s*```$/i, '')
.trim();
persona = JSON.parse(stripped);
} catch (err) {
console.error('[persona/extract] parse error', err, raw.slice(0, 500));
return error(res, 502, 'parse_error', 'model returned non-JSON');
}
const allowedStyles = ['terse', 'detailed', 'playful', 'analytical', 'warm'];
const normalized = {
tone: typeof persona.tone === 'string' ? persona.tone.trim().slice(0, 240) : '',
vocabulary: Array.isArray(persona.vocabulary)
? persona.vocabulary
.filter((x) => typeof x === 'string' && x.trim())
.map((x) => x.trim().slice(0, 80))
.slice(0, 10)
: [],
interests: Array.isArray(persona.interests)
? persona.interests
.filter((x) => typeof x === 'string' && x.trim())
.map((x) => x.trim().slice(0, 80))
.slice(0, 5)
: [],
communication_style: allowedStyles.includes(persona.communication_style)
? persona.communication_style
: 'detailed',
dont_say: Array.isArray(persona.dont_say)
? persona.dont_say
.filter((x) => typeof x === 'string' && x.trim())
.map((x) => x.trim().slice(0, 120))
.slice(0, 3)
: [],
sample_greeting:
typeof persona.sample_greeting === 'string'
? persona.sample_greeting.trim().slice(0, 400)
: '',
};
// Well-formed JSON with nothing usable in it (e.g. a bare `{}`) would otherwise
// render as a blank persona card the user cannot act on. communication_style
// is excluded from this check because it always defaults to a value.
if (!normalized.tone && !normalized.sample_greeting
&& !normalized.vocabulary.length && !normalized.interests.length) {
console.error('[persona/extract] model returned an empty persona', raw.slice(0, 500));
return error(res, 502, 'parse_error', 'The model returned an empty persona. Please try again.');
}
const usage = completion.usage;
return json(res, 200, {
persona: normalized,
model: completion.model,
tokens_used: promptTokens(usage) + usage.output,
tokens_in: promptTokens(usage),
tokens_out: usage.output,
latency_ms: Date.now() - t0,
});
});
export default handler;