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
feat(motion): author a motion score from a sentence, deterministic lane first
nirholas21d48abf9d40
diff --git a/api/_lib/motion-author.js b/api/_lib/motion-author.jsnew file mode 100644index 000000000..f27685a2a--- /dev/null+++ b/api/_lib/motion-author.js@@ -0,0 +1,215 @@+// Author a Motion Score from a sentence.+//+// Two lanes, and the fast one always runs first:+//+// 1. The deterministic composer in @three-ws/motion. It recognizes about+// twenty actions with their modifiers, costs nothing, answers in under a+// millisecond, and gives the same clip for the same prompt forever. Most+// of what people type at a motion box is "wave", "nod", "sit down".+// 2. A language model, given the score schema as a tool contract. This is+// what handles the other half: "she looks up from her desk, considers it,+// then shakes her head slowly". It runs on the free-first llmComplete+// chain, and a model that returns something the compiler rejects gets one+// repair attempt carrying the exact validation path that failed.+//+// If the model lane is unavailable or its output cannot be repaired, the+// composer's nearest match answers instead. The caller is always told which+// lane produced the score and why, because "the model wrote this" and "we+// recognized the word wave" are different enough that a UI should say so.++import {+ ACTION_NAMES,+ composeScore,+ describeScore,+ scoreSchema,+ validateScore,+} from '@three-ws/motion';+import { llmComplete, llmConfigured, LlmUnavailableError } from './llm.js';+import { extractJson } from './bounty-judge.js';++/** How many beats a model is asked for, so a clip stays a clip. */+const BEAT_BUDGET = { min: 2, max: 12 };++const SYSTEM = [+ 'You are a movement director. You write Motion Scores: a JSON description of',+ 'how a human body moves, in anatomy and timing, which a kinematics solver',+ 'turns into a real animation.',+ '',+ 'Rules that matter more than anything else you know about animation:',+ `- Answer with ONE JSON object matching the schema. No prose, no markdown fence.`,+ `- ${BEAT_BUDGET.min} to ${BEAT_BUDGET.max} beats. A beat is the body at one instant, not a span.`,+ '- Use ONLY the enum values in the schema. An invented posture, anchor, gaze,',+ ' expression or hand shape is rejected outright, so pick the closest one.',+ '- Start from a beat that establishes the body, end from one it can rest in.',+ '- `in` is seconds of travel INTO the beat; `hold` is seconds spent there.',+ '- Offsets are METRES on a human of about 1.7m. A hand width is 0.09m. Anything',+ ' over 0.4 is almost certainly wrong.',+ '- Angles are DEGREES. `lean` is positive forward, `twist` and `turn` positive',+ ' toward the body\'s own left, gaze `pitch` positive upward.',+ '- Effort is how it is performed, and it is not decoration: pick the preset',+ ' that matches the adverb in the request.',+ '- Every beat gets a short `label` saying what it is. A reader should be able',+ ' to follow the movement from the labels alone.',+ '',+ 'Think about what the body does that the words leave out. Weight shifts before',+ 'a step. The head leads a turn. A hand comes back to rest. Somebody who is',+ 'tired lowers themselves rather than dropping.',+].join('\n');++/**+ * Produce a validated Motion Score for a prompt.+ *+ * @param {string} prompt+ * @param {{+ * loop?: boolean,+ * effort?: string,+ * prefer?: 'auto'|'fast'|'model',+ * userId?: string|null,+ * timeoutMs?: number,+ * }} [opts]+ * `prefer` is 'auto' by default: the composer answers a phrase it recognizes,+ * and the model handles everything else. 'fast' never calls a model; 'model'+ * always tries one first.+ * @returns {Promise<{+ * score: object, lane: 'composer'|'model', matched: string|null,+ * provider: string|null, model: string|null, note: string|null,+ * }>}+ */+export async function authorScore(prompt, opts = {}) {+ const text = String(prompt ?? '').trim();+ if (!text) throw Object.assign(new Error('a motion needs a description'), { status: 400, code: 'empty_prompt' });++ const prefer = opts.prefer ?? 'auto';+ const fast = composeScore(text, { loop: opts.loop, effort: opts.effort });++ if (prefer === 'fast' || (prefer === 'auto' && fast.score)) {+ if (fast.score) {+ return { score: fast.score, lane: 'composer', matched: fast.matched, provider: null, model: null, note: null };+ }+ throw Object.assign(new Error(fast.reason), { status: 422, code: 'unrecognized_motion', actions: [...ACTION_NAMES] });+ }++ if (!llmConfigured()) {+ if (fast.score) {+ return {+ score: fast.score,+ lane: 'composer',+ matched: fast.matched,+ provider: null,+ model: null,+ note: 'No language model is reachable, so this is the nearest movement the built-in vocabulary knows.',+ };+ }+ throw Object.assign(+ new Error(`No language model is reachable, and "${text}" is not one of the movements this build can compose on its own.`),+ { status: 503, code: 'model_unavailable', actions: [...ACTION_NAMES] },+ );+ }++ try {+ const authored = await askModel(text, opts);+ return { ...authored, lane: 'model', matched: fast.matched };+ } catch (err) {+ if (fast.score) {+ return {+ score: fast.score,+ lane: 'composer',+ matched: fast.matched,+ provider: null,+ model: null,+ note: `The model lane failed (${err.message}), so this is the built-in movement closest to the request.`,+ };+ }+ if (err instanceof LlmUnavailableError) {+ throw Object.assign(new Error('No language model is reachable right now.'), { status: 503, code: 'model_unavailable' });+ }+ throw err;+ }+}++async function askModel(prompt, opts) {+ const schema = scoreSchema();+ const user = [+ `Movement to write: ${prompt}`,+ opts.loop ? 'It must LOOP: the last beat has to flow back into the first, so end where you began.' : '',+ opts.effort ? `Perform it with the "${opts.effort}" effort unless the request clearly says otherwise.` : '',+ '',+ 'Schema:',+ JSON.stringify(schema),+ ].filter(Boolean).join('\n');++ const first = await llmComplete({+ system: SYSTEM,+ user,+ maxTokens: 2400,+ timeoutMs: opts.timeoutMs ?? 25_000,+ track: { userId: opts.userId ?? null, tool: 'motion-author' },+ });++ const parsed = readScore(first.text);+ if (parsed.ok) {+ return { score: named(parsed.score, prompt, opts), provider: first.provider, model: first.model, note: null };+ }++ // One repair pass, carrying the exact path that failed. A model that wrote+ // `posture: "sitting"` fixes it immediately when told the word and the enum;+ // asking it to "try again" does not.+ const repair = await llmComplete({+ system: SYSTEM,+ user: [+ user,+ '',+ 'Your previous answer was rejected by the compiler:',+ ` ${parsed.error}`,+ 'Return the corrected JSON object. Change only what the error names.',+ '',+ 'Previous answer:',+ first.text.slice(0, 4000),+ ].join('\n'),+ maxTokens: 2400,+ timeoutMs: opts.timeoutMs ?? 25_000,+ track: { userId: opts.userId ?? null, tool: 'motion-author-repair' },+ });++ const second = readScore(repair.text);+ if (!second.ok) {+ throw Object.assign(new Error(`the model could not produce a valid score: ${second.error}`), { status: 502, code: 'invalid_score' });+ }+ return {+ score: named(second.score, prompt, opts),+ provider: repair.provider,+ model: repair.model,+ note: 'The first draft did not validate and was repaired in a second pass.',+ };+}++// Parse whatever the model returned and hold it to the compiler's own rules, so+// a score can never reach a solver in a shape the solver has to guess about.+function readScore(text) {+ let raw;+ try {+ raw = extractJson(text);+ } catch {+ raw = null;+ }+ if (!raw || typeof raw !== 'object') return { ok: false, error: 'the answer was not a JSON object' };+ if (Array.isArray(raw)) return { ok: false, error: 'the answer was an array, not a score object' };+ const result = validateScore(raw);+ if (!result.ok) return { ok: false, error: result.error.message };+ if (result.score.beats.length < BEAT_BUDGET.min) {+ return { ok: false, error: `score.beats: a movement needs at least ${BEAT_BUDGET.min} beats` };+ }+ // The normalized score is what the solver reads, but the raw one is what a+ // caller edits and re-submits, so both travel together.+ return { ok: true, score: raw };+}++function named(score, prompt, opts) {+ return {+ ...score,+ name: typeof score.name === 'string' && score.name.trim() ? score.name.trim() : prompt.slice(0, 120),+ loop: opts.loop === true || score.loop === true,+ };+}++export { describeScore, ACTION_NAMES };