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.

13.1 KB
Raw Blame
/**
 * Agent Galaxy: a semantic 3D star-map of every published agent on three.ws,
 * positioned by IBM Granite embeddings (watsonx.ai) and grouped into Granite-named
 * constellations. When watsonx is unconfigured or failing, the platform's tagged
 * embedding lanes (NVIDIA NIM, Vertex AI, OpenAI) position the map instead, and the
 * payload's `model` names the space that actually served.
 *
 *   GET  /api/galaxy              : the full galaxy snapshot (cached server-side).
 *        ?refresh=1               : force a rebuild (re-embed changed agents,
 *                                   re-cluster, re-name constellations).
 *        ?limit=<n>               : cap agents (default 600, max 1200; busiest first).
 *
 *   POST /api/galaxy              : { "query": "trading bots" } semantic search.
 *                                   Embeds the query in the same vector space as the
 *                                   current snapshot, ranks published agents by cosine
 *                                   similarity against their stored vectors, returns
 *                                   the top matches.
 *
 * No mock path. Coordinates and rankings come from real embeddings; when no embedder
 * is configured at all the endpoint returns 503 with a machine-readable reason so the
 * viewer can explain the requirement instead of inventing a fake universe.
 */

import { sql } from './_lib/db.js';
import { cacheWrap } from './_lib/cache.js';
import { cors, json, method, readJson, wrap, error, rateLimited } from './_lib/http.js';
import { clampInt } from './_lib/http-params.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { thumbnailUrl } from './_lib/r2.js';
import { watsonxConfig, watsonxChatComplete } from './_lib/watsonx.js';
import {
	agentEmbedText,
	agentEmbedders,
	ensureAgentEmbeddings,
	readAgentVectors,
} from './_lib/agent-embeddings.js';
import { rankLexically } from './_lib/lexical-rank.js';
import {
	assembleGalaxy,
	rankBySimilarity,
	clusterNamePrompt,
	parseClusterName,
} from './_lib/galaxy.js';

// A served snapshot is reused for this long before a GET rebuilds it. The embedding
// cache (agent_embeddings) makes rebuilds cheap (only new/edited agents re-embed),
// so this mostly throttles the k Granite cluster-naming calls per rebuild.
const SNAPSHOT_TTL_MS = 6 * 60 * 60 * 1000; // 6h

// Coalesce concurrent rebuilds within a warm function instance so a burst of first
// visitors triggers one build, not N. Keyed by the build limit.
const building = new Map(); // limit → Promise<payload>

let _snapshotTableReady = null;
function ensureSnapshotTable() {
	if (_snapshotTableReady) return _snapshotTableReady;
	_snapshotTableReady = sql`
		CREATE TABLE IF NOT EXISTS galaxy_snapshots (
			id          bigserial PRIMARY KEY,
			model       text NOT NULL,
			agent_count int  NOT NULL,
			payload     jsonb NOT NULL,
			created_at  timestamptz NOT NULL DEFAULT now()
		)
	`.then(() => true);
	return _snapshotTableReady;
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	const rl = await limits.galaxyIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const cfg = watsonxConfig();
	const embedders = agentEmbedders(cfg);
	if (!embedders.length) {
		return error(
			res,
			503,
			'embeddings_unavailable',
			'The Agent Galaxy needs an embedding provider. Configure watsonx.ai ' +
				'(WATSONX_API_KEY and WATSONX_PROJECT_ID), NVIDIA_API_KEY, or GOOGLE_CLOUD_PROJECT.',
		);
	}

	if (req.method === 'POST') return handleSearch(req, res, embedders);
	return handleGalaxy(req, res, cfg, embedders);
});

// ── GET: the galaxy snapshot ────────────────────────────────────────────────

async function handleGalaxy(req, res, cfg, embedders) {
	const url = new URL(req.url, 'http://x');
	const refresh = url.searchParams.get('refresh') === '1';
	const limit = clampInt(url.searchParams.get('limit'), { max: 1200, fallback: 600 });

	await ensureSnapshotTable();

	if (!refresh) {
		const [snap] = await sql`
			SELECT payload, created_at FROM galaxy_snapshots ORDER BY created_at DESC LIMIT 1
		`;
		if (snap && Date.now() - new Date(snap.created_at).getTime() < SNAPSHOT_TTL_MS) {
			return json(res, 200, {
				...snap.payload,
				cached: true,
				generated_at: snap.created_at,
			});
		}
	}

	// Coalesce concurrent rebuilds in this warm instance.
	let job = building.get(limit);
	if (!job) {
		job = buildGalaxy(cfg, embedders, limit).finally(() => building.delete(limit));
		building.set(limit, job);
	}
	const payload = await job;

	return json(res, 200, { ...payload, cached: false, generated_at: new Date().toISOString() });
}

// Build a fresh galaxy: load published agents, ensure their embeddings, project +
// cluster, name the constellations with Granite, persist the snapshot.
async function buildGalaxy(cfg, embedders, limit) {
	const agents = await loadPublishedAgents(limit);

	if (agents.length === 0) {
		const empty = { count: 0, dims: 0, model: embedders[0].model, clusters: [], agents: [] };
		await persistSnapshot(empty);
		return empty;
	}

	const { vectors, dims, model } = await embedWithFailover(embedders, agents);

	const payload = await assembleGalaxy(agents, vectors, {
		dims,
		model,
		nameClusters: (clusters) => nameClustersWithGranite(cfg, clusters),
	});

	await persistSnapshot(payload);
	return payload;
}

// Embed the whole population with one embedder, walking the preference order when
// a lane fails. A map is only ever built from a single vector space: a lane that
// fails part-way is abandoned entirely and the next one embeds every agent.
async function embedWithFailover(embedders, agents) {
	let lastErr;
	for (const embedder of embedders) {
		try {
			return await ensureAgentEmbeddings(embedder, agents);
		} catch (err) {
			console.warn(`[galaxy] embedder ${embedder.model} failed: ${err?.message || err}`);
			lastErr = err;
		}
	}
	throw lastErr;
}

// Ask Granite to name each constellation from its members. One short chat call per
// cluster (k ≤ 8), run in parallel. Any failure or unparseable reply falls back to a
// member-derived label inside assembleGalaxy, so this never throws the whole build.
async function nameClustersWithGranite(cfg, clusters) {
	return Promise.all(
		clusters.map(async (cluster) => {
			try {
				const { text } = await watsonxChatComplete(cfg, {
					messages: [{ role: 'user', content: clusterNamePrompt(cluster.members) }],
					maxTokens: 120,
					temperature: 0.5,
				});
				return parseClusterName(text);
			} catch {
				return {};
			}
		}),
	);
}

async function persistSnapshot(payload) {
	try {
		await sql`
			INSERT INTO galaxy_snapshots (model, agent_count, payload)
			VALUES (${payload.model || 'unknown'}, ${payload.count || 0}, ${JSON.stringify(payload)}::jsonb)
		`;
		// Keep only the most recent few snapshots.
		await sql`
			DELETE FROM galaxy_snapshots
			WHERE id NOT IN (SELECT id FROM galaxy_snapshots ORDER BY created_at DESC LIMIT 5)
		`;
	} catch (err) {
		// A persistence failure must not fail the request: the caller still gets a
		// freshly computed payload; the next GET simply rebuilds instead of caching.
		console.error('[galaxy] persistSnapshot failed', err);
	}
}

// ── POST: semantic search ───────────────────────────────────────────────────

// The embedder whose space the served map lives in, so a query is compared
// against vectors from the same model. Falls back to the preferred embedder when
// no snapshot exists yet or its model is no longer configured.
async function snapshotEmbedder(embedders) {
	try {
		await ensureSnapshotTable();
		const [snap] = await sql`
			SELECT model FROM galaxy_snapshots WHERE agent_count > 0 ORDER BY created_at DESC LIMIT 1
		`;
		return embedders.find((e) => e.model === snap?.model) || embedders[0];
	} catch {
		return embedders[0];
	}
}

async function handleSearch(req, res, embedders) {
	const body = await readJson(req).catch(() => ({}));
	const query = String(body.query || '').trim().slice(0, 200);
	if (!query) return error(res, 400, 'validation_error', 'query is required');

	const topK = clampInt(body.limit, { max: 30, fallback: 12 });

	// Embed the query with the same model the agents were embedded with, so query
	// and agent vectors share a space.
	//
	// There is no provider failover to reach for here, and that is not an
	// oversight: the stored agent vectors live in one model's space, so a vector
	// from another lane would be compared against them in a different geometry
	// and different dimension. The fallback is a different METHOD instead. When
	// the embedder cannot answer, the same corpus is ranked lexically and the
	// response says so, because a search page that returns keyword matches is
	// useful and a search page that returns 502 is not.
	const embedder = await snapshotEmbedder(embedders);
	let queryVec = null;
	let embedError = null;
	try {
		const vec = await embedder.embedQuery(query);
		queryVec = vec?.length ? vec : null;
		if (!queryVec) embedError = 'the embedder returned no vector for the query';
	} catch (err) {
		embedError = err?.message || 'the embedder is unreachable';
	}

	const agents = await loadPublishedAgents(1200);
	const byId = new Map(agents.map((a) => [a.id, a]));

	if (!queryVec) {
		const ranked = rankLexically(
			query,
			agents.map((a) => ({ id: a.id, text: agentEmbedText(a) || `${a.name || ''} ${a.description || ''}` })),
			{ limit: topK },
		);
		const results = ranked
			.map(({ id, score, lexicalScore: lex }) => {
				const a = byId.get(id);
				return a ? { id: a.id, name: a.name, description: a.description || '', thumbnail: a.thumbnail || null, score, lexicalScore: lex } : null;
			})
			.filter(Boolean);
		return json(res, 200, {
			query,
			model: embedder.model,
			count: results.length,
			results,
			ranking: 'lexical',
			degraded: { reason: 'embedder_unavailable', detail: embedError, retryable: true },
		});
	}

	const vectorsById = await readAgentVectors([...byId.keys()], { model: embedder.model });

	const ranked = rankBySimilarity(queryVec, vectorsById, { topK });
	const results = ranked
		.map(({ id, score }) => {
			const a = byId.get(id);
			if (!a) return null;
			return {
				id: a.id,
				name: a.name,
				description: a.description || '',
				thumbnail: a.thumbnail || null,
				score,
			};
		})
		.filter(Boolean);

	return json(res, 200, { query, model: embedder.model, count: results.length, results, ranking: 'semantic' });
}

// ── Shared: published-agent population ──────────────────────────────────────

// The galaxy and search share the same population: published, named, described
// agents (mirrors /api/characters' feed filter), busiest first so a `limit` keeps
// the most active agents. Wallet + token surface the on-chain identity layer in the
// viewer; both are public-safe.
async function loadPublishedAgents(limit) {
	// This is the same public feed for every viewer, and its `chat_count`
	// correlated subquery + `ORDER BY chat_count` forces a COUNT(*) over
	// usage_events for EVERY published agent on each load, the dominant cost
	// here. Cache the result for 60s so that expensive ranking runs at most once
	// a minute regardless of traffic.
	const rows = await cacheWrap(`galaxy:published:${limit}`, 60, async () => await sql`
		SELECT
			i.id,
			i.name,
			i.description,
			i.wallet_address,
			i.chain_id,
			i.meta,
			a.thumbnail_key AS avatar_thumbnail_key,
			a.visibility    AS avatar_visibility,
			COALESCE((
				SELECT COUNT(*)::int FROM usage_events ue
				WHERE ue.agent_id = i.id AND ue.kind = 'llm'
			), 0) AS chat_count
		FROM agent_identities i
		LEFT JOIN avatars a ON a.id = i.avatar_id AND a.deleted_at IS NULL
		WHERE i.deleted_at IS NULL
		  AND i.is_published = true
		  AND i.description IS NOT NULL
		  AND length(trim(i.name)) > 0
		ORDER BY chat_count DESC, i.created_at DESC
		LIMIT ${limit}
	`);

	return rows.map((row) => {
		const meta = row.meta || {};
		const thumbnail =
			row.avatar_thumbnail_key &&
			(row.avatar_visibility === 'public' || row.avatar_visibility === 'unlisted')
				? thumbnailUrl(row.avatar_thumbnail_key)
				: meta.profile_image_url || meta.thumbnail_url || meta.avatar_url || null;
		const token = meta.token || null;
		return {
			id: row.id,
			name: row.name,
			description: row.description,
			thumbnail,
			wallet: row.wallet_address || meta.solana_address || null,
			chain: row.chain_id || (meta.solana_address ? 'solana' : null),
			// Vanity pattern (if any) so the shared wallet chip can advertise the
			// address's honest rarity tier on the inspect card, matching every other
			// surface. Public, non-secret metadata.
			solana_vanity_prefix: meta.solana_vanity_prefix || null,
			solana_vanity_suffix: meta.solana_vanity_suffix || null,
			chat_count: row.chat_count,
			token: token
				? {
						symbol: token.symbol || null,
						mint: token.mint || null,
						market_cap_usd: token.market_cap_usd ?? token.usd_market_cap ?? null,
					}
				: null,
		};
	});
}