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.

9.2 KB
Raw Blame
// 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;