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
// The model: one streaming round against any OpenAI-compatible
// chat-completions endpoint, with the tool list the local agent built.
//
// Two providers:
// three-ws <origin>/api/v1, the metered endpoint billed to the account's
// credits. The request carries `tools`, so the endpoint answers as
// a plain tool-calling model and the tools run HERE, on this
// machine. The key needs the `inference` scope.
// openai any base URL that speaks the same wire format (a local
// llama.cpp / Ollama / vLLM server, or a hosted lane) with its own key.
import { ApiError, errorOf, request, USER_AGENT } from './http.js';
import { THREE_WS_MODEL } from './config.js';
const ROUND_TIMEOUT_MS = 180_000;
/** Resolve the endpoint, key and model id the config names. Throws a readable error when something is missing. */
export function resolveModelTarget(config, credential, vars = process.env) {
const m = config.model || {};
if (m.provider === 'openai') {
if (!m.baseUrl) throw new ApiError('model.baseUrl is not set. Run `/model openai <base-url> <model>` or set THREE_WS_AGENT_BASE_URL.', { code: 'model_unconfigured' });
const key = m.apiKey || (m.apiKeyEnv ? vars[m.apiKeyEnv] : null) || vars.THREE_WS_AGENT_API_KEY || vars.OPENAI_API_KEY || null;
if (!m.model) throw new ApiError('model.model is not set. Run `/model openai <base-url> <model>` or set THREE_WS_AGENT_MODEL.', { code: 'model_unconfigured' });
return { provider: 'openai', baseUrl: m.baseUrl.replace(/\/+$/, ''), key, model: m.model, headers: {}, label: `${m.model} @ ${new URL(m.baseUrl).host}` };
}
if (!credential?.token) {
throw new ApiError('Not signed in to three.ws. Run `three-ws-agent login` (or set THREE_WS_API_KEY), or point the agent at your own model with `/model openai <base-url> <model>`.', { code: 'not_signed_in' });
}
const headers = config.agentId ? { 'x-three-agent': config.agentId } : {};
return { provider: 'three-ws', baseUrl: `${config.origin}/api/v1`, key: credential.token, model: m.model || THREE_WS_MODEL, headers, label: `${m.model || THREE_WS_MODEL} (three.ws credits)` };
}
/** Parse an OpenAI SSE body. Calls onContent per text delta; resolves the accumulated round. */
export async function readSse(body, { onContent, signal } = {}) {
const reader = body.getReader();
const decoder = new TextDecoder();
let buf = '';
let content = '';
let usage = null;
let billing = null;
let finishReason = null;
const toolCalls = [];
const onAbort = () => reader.cancel().catch(() => {});
signal?.addEventListener('abort', onAbort, { once: true });
try {
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
let nl;
while ((nl = buf.indexOf('\n')) >= 0) {
const line = buf.slice(0, nl).trim();
buf = buf.slice(nl + 1);
if (!line.startsWith('data:')) continue;
const payload = line.slice(5).trim();
if (payload === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(payload);
} catch {
continue;
}
if (evt.error) throw new ApiError(`model stream error: ${evt.error.message || JSON.stringify(evt.error)}`, { code: 'stream_error' });
if (evt.usage) usage = evt.usage;
if (evt.billing) billing = evt.billing;
const choice = evt.choices?.[0];
if (!choice) continue;
if (choice.finish_reason) finishReason = choice.finish_reason;
const delta = choice.delta || {};
if (typeof delta.content === 'string' && delta.content) {
content += delta.content;
onContent?.(delta.content);
}
for (const tc of delta.tool_calls || []) {
const idx = tc.index ?? toolCalls.length;
if (!toolCalls[idx]) toolCalls[idx] = { id: tc.id || `call_${idx}`, type: 'function', function: { name: '', arguments: '' } };
if (tc.id) toolCalls[idx].id = tc.id;
if (tc.function?.name) toolCalls[idx].function.name += tc.function.name;
if (tc.function?.arguments) toolCalls[idx].function.arguments += tc.function.arguments;
}
}
}
} finally {
signal?.removeEventListener('abort', onAbort);
}
if (signal?.aborted) throw new ApiError('interrupted', { code: 'aborted' });
return { content, toolCalls: toolCalls.filter(Boolean), usage, billing, finishReason };
}
function friendlyModelError(status, code, message, target) {
if (status === 402 || code === 'insufficient_credits') {
return `${message} Top up at ${target.baseUrl.replace(/\/api\/v1$/, '')}/credits, or switch to your own model with /model openai <base-url> <model>.`;
}
if (code === 'insufficient_scope') return `${message} Run \`three-ws-agent login\` to mint a key with the inference scope.`;
if (status === 401) return `${message} Run \`three-ws-agent login\` again.`;
return message;
}
/**
* Build the model client for a config + credential.
* `round` resolves `{ content, toolCalls, usage, billing }`.
*/
export function createModel(config, credential, { fetchImpl, vars } = {}) {
const target = resolveModelTarget(config, credential, vars);
let sendUsageOption = true;
async function round({ messages, tools, signal, onContent }) {
const body = {
model: target.model,
messages,
stream: true,
max_tokens: config.model?.maxTokens || 4096,
temperature: config.model?.temperature ?? 0.3,
};
if (sendUsageOption) body.stream_options = { include_usage: true };
if (tools?.length) {
body.tools = tools;
body.tool_choice = 'auto';
}
const headers = { accept: 'text/event-stream', ...target.headers };
if (target.key) headers.authorization = `Bearer ${target.key}`;
const doRequest = fetchImpl
? () => fetchImpl(`${target.baseUrl}/chat/completions`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json', 'user-agent': USER_AGENT }, body: JSON.stringify(body), signal })
: () => request(`${target.baseUrl}/chat/completions`, { method: 'POST', headers, json: body, timeoutMs: ROUND_TIMEOUT_MS, signal });
const res = await doRequest();
if (!res.ok) {
const text = await res.text().catch(() => '');
let data = null;
try {
data = JSON.parse(text);
} catch {
data = null;
}
const { code, message } = errorOf(data, text, res);
// Some OpenAI-compatible hosts reject the usage option; drop it once and retry.
if (res.status === 400 && sendUsageOption && /stream_options/i.test(message)) {
sendUsageOption = false;
return round({ messages, tools, signal, onContent });
}
throw new ApiError(friendlyModelError(res.status, code, message, target), { status: res.status, code, body: data });
}
if (!res.body) throw new ApiError('the model returned an empty response', { code: 'empty_response' });
return readSse(res.body, { onContent, signal });
}
async function listModels() {
const headers = { ...target.headers };
if (target.key) headers.authorization = `Bearer ${target.key}`;
const res = await request(`${target.baseUrl}/models`, { headers, timeoutMs: 15_000 });
const data = await res.json().catch(() => null);
if (!res.ok) throw new ApiError(`${res.status}: ${errorOf(data, '', res).message}`, { status: res.status });
return (data?.data || []).map((m) => ({ id: m.id, owner: m.owned_by || null, description: m.description || null }));
}
return { target, label: target.label, round, listModels };
}