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(galaxy): keep the Agent Galaxy online through NIM, Vertex, and OpenAI when watsonx is down
nirholas53f420c74f46
diff --git a/api/_lib/agent-embeddings.js b/api/_lib/agent-embeddings.jsindex 4b8b0d65d..2ddb9dfab 100644--- a/api/_lib/agent-embeddings.js+++ b/api/_lib/agent-embeddings.js@@ -1,5 +1,5 @@-// agent-embeddings — a durable cache of IBM Granite embedding vectors for agent-// identities, the data layer behind the Agent Galaxy.+// agent-embeddings: a durable cache of embedding vectors for agent identities,+// the data layer behind the Agent Galaxy.//// Embedding every agent on every page load would be slow and wasteful, so each// agent's vector is persisted in Postgres keyed by a content hash of the exact@@ -8,17 +8,90 @@// cache. The same stored vectors power semantic search (query vector vs. agent// vectors) without a second embedding pass.//-// There is no mock path: vectors come from a real watsonx.ai embeddings call.-// When watsonx is unconfigured the caller checks watsonxConfig().configured and-// reports the feature unavailable rather than inventing data.+// IBM Granite on watsonx.ai is the preferred embedder. When watsonx is not+// configured, or fails, the platform's tagged embedding lanes (NVIDIA NIM,+// Vertex AI, OpenAI; see ./embeddings.js) serve instead. Every stored row+// records the exact model or lane tag that produced it, and reads always filter+// by that tag, so vectors from different spaces are never compared. There is no+// mock path: when no embedder is configured the caller reports the feature+// unavailable rather than inventing data.import { createHash } from 'node:crypto';import { sql } from './db.js';import { watsonxEmbed } from './watsonx.js';+import {+ NIM_EMBED_TAG,+ VERTEX_EMBED_TAG,+ OPENAI_EMBED_TAG,+ embedderConfigured,+ embedPassages,+ embedQuery,+} from './embeddings.js';// watsonx accepts many inputs per embeddings call; keep request bodies modest so// a large galaxy rebuild splits into a handful of calls instead of one giant one.-const EMBED_CHUNK = 96;+const WATSONX_EMBED_CHUNK = 96;+// Vertex caps a request at 20k input tokens and NIM at 512 tokens per input, so+// the platform lanes take smaller batches of the (up to 2000 char) agent texts.+const PLATFORM_EMBED_CHUNK = 16;++// Platform lanes in the same free-first order embeddings.js ingests with.+const PLATFORM_EMBED_TAGS = [NIM_EMBED_TAG, VERTEX_EMBED_TAG, OPENAI_EMBED_TAG];++function watsonxEmbedder(cfg, model = cfg.embedModel) {+ return {+ provider: 'watsonx',+ model,+ chunk: WATSONX_EMBED_CHUNK,+ async embed(inputs) {+ const { vectors } = await watsonxEmbed(cfg, { inputs, model });+ return vectors;+ },+ async embedQuery(text) {+ const { vectors } = await watsonxEmbed(cfg, { inputs: [text], model });+ return vectors[0] || null;+ },+ };+}++function platformEmbedder(tag) {+ return {+ provider: 'platform',+ model: tag,+ chunk: PLATFORM_EMBED_CHUNK,+ async embed(inputs) {+ // Float64Array serializes to an object in JSON, so store plain arrays.+ return (await embedPassages(tag, inputs)).map((v) => Array.from(v));+ },+ async embedQuery(text) {+ const vec = await embedQuery(tag, text);+ return vec ? Array.from(vec) : null;+ },+ };+}++/**+ * Every embedder able to serve right now, in preference order: watsonx Granite+ * first when configured, then each configured platform lane. Empty when none is.+ * `cfg` is a watsonxConfig() result.+ */+export function agentEmbedders(cfg) {+ const out = [];+ if (cfg?.configured) out.push(watsonxEmbedder(cfg));+ for (const tag of PLATFORM_EMBED_TAGS) {+ if (embedderConfigured(tag)) out.push(platformEmbedder(tag));+ }+ return out;+}++// Accept either an embedder from agentEmbedders() or a bare watsonxConfig()+// result (optionally with a Granite model override), which callers that only+// ever use Granite still pass.+function toEmbedder(cfgOrEmbedder, model) {+ return typeof cfgOrEmbedder?.embed === 'function'+ ? cfgOrEmbedder+ : watsonxEmbedder(cfgOrEmbedder, model || cfgOrEmbedder.embedModel);+}let _ready = null;@@ -56,15 +129,17 @@ function contentHash(text, model) {return createHash('sha256').update(`${model}\n${text}`).digest('hex');}-// Ensure every agent in `agents` has a current Granite embedding, re-embedding-// only those whose text changed since last time. Returns { vectors, model,-// dims, embedded } where `vectors` is aligned 1:1 with the input `agents`-// (agents with empty embeddable text are skipped — see `usable`).+// Ensure every agent in `agents` has a current embedding, re-embedding only+// those whose text changed since last time. Returns { vectors, model, dims,+// embedded } where `vectors` is aligned 1:1 with the input `agents` (agents with+// empty embeddable text are skipped, see `usable`).//-// `cfg` is a watsonxConfig() result; the caller guarantees cfg.configured.-export async function ensureAgentEmbeddings(cfg, agents, { model } = {}) {+// `cfgOrEmbedder` is an embedder from agentEmbedders(), or a watsonxConfig()+// result the caller guarantees is configured.+export async function ensureAgentEmbeddings(cfgOrEmbedder, agents, { model } = {}) {await ensureTable();- const embedModel = model || cfg.embedModel;+ const embedder = toEmbedder(cfgOrEmbedder, model);+ const embedModel = embedder.model;// Build the embed text + hash for each agent up front.const prepared = agents.map((a) => {@@ -96,13 +171,10 @@ export async function ensureAgentEmbeddings(cfg, agents, { model } = {}) {for (const c of cached.values()) if (c.vector?.length) dims = c.vector.length;// Re-embed stale agents in chunks, then upsert and merge into the cache map.- for (let i = 0; i < stale.length; i += EMBED_CHUNK) {- const batch = stale.slice(i, i + EMBED_CHUNK);- const { vectors, dimensions } = await watsonxEmbed(cfg, {- inputs: batch.map((p) => p.text),- model: embedModel,- });- dims = dimensions || dims;+ for (let i = 0; i < stale.length; i += embedder.chunk) {+ const batch = stale.slice(i, i + embedder.chunk);+ const vectors = await embedder.embed(batch.map((p) => p.text));+ dims = vectors[0]?.length || dims;const recs = [];for (let j = 0; j < batch.length; j++) {const vec = vectors[j];diff --git a/api/galaxy.js b/api/galaxy.jsindex 0ab2f8dcb..c9862b7f6 100644--- a/api/galaxy.js+++ b/api/galaxy.js@@ -1,7 +1,9 @@/*** 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.+ * 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,@@ -9,13 +11,14 @@* ?limit=<n> : cap agents (default 600, max 1200; busiest first).** POST /api/galaxy : { "query": "trading bots" } semantic search.- * Embeds the query with Granite, ranks published- * agents by cosine similarity against their stored- * Granite vectors, returns the top matches.+ * 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 watsonx.ai embeddings; when- * watsonx is unconfigured the endpoint returns 503 with a machine-readable reason so- * the viewer can explain the requirement instead of inventing a fake universe.+ * 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';@@ -24,8 +27,13 @@ import { cors, json, method, readJson, wrap, error, rateLimited } from './_lib/himport { clampInt } from './_lib/http-params.js';import { limits, clientIp } from './_lib/rate-limit.js';import { thumbnailUrl } from './_lib/r2.js';-import { watsonxConfig, watsonxEmbed, watsonxChatComplete } from './_lib/watsonx.js';-import { agentEmbedText, ensureAgentEmbeddings, readAgentVectors } from './_lib/agent-embeddings.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,@@ -66,23 +74,24 @@ export default wrap(async (req, res) => {if (!rl.success) return rateLimited(res, rl);const cfg = watsonxConfig();- if (!cfg.configured) {+ const embedders = agentEmbedders(cfg);+ if (!embedders.length) {return error(res,503,- 'watsonx_unavailable',- 'The Agent Galaxy is positioned by IBM Granite embeddings on watsonx.ai. ' +- 'Set WATSONX_API_KEY and WATSONX_PROJECT_ID (or WATSONX_SPACE_ID) to build it.',+ '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, cfg);- return handleGalaxy(req, res, cfg);+ 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) {+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 });@@ -105,7 +114,7 @@ async function handleGalaxy(req, res, cfg) {// Coalesce concurrent rebuilds in this warm instance.let job = building.get(limit);if (!job) {- job = buildGalaxy(cfg, limit).finally(() => building.delete(limit));+ job = buildGalaxy(cfg, embedders, limit).finally(() => building.delete(limit));building.set(limit, job);}const payload = await job;@@ -113,18 +122,18 @@ async function handleGalaxy(req, res, cfg) {return json(res, 200, { ...payload, cached: false, generated_at: new Date().toISOString() });}-// Build a fresh galaxy: load published agents, ensure their Granite embeddings,-// project + cluster, name the constellations with Granite, persist the snapshot.-async function buildGalaxy(cfg, limit) {+// 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: cfg.embedModel, clusters: [], agents: [] };+ const empty = { count: 0, dims: 0, model: embedders[0].model, clusters: [], agents: [] };await persistSnapshot(empty);return empty;}- const { vectors, dims, model } = await ensureAgentEmbeddings(cfg, agents);+ const { vectors, dims, model } = await embedWithFailover(embedders, agents);const payload = await assembleGalaxy(agents, vectors, {dims,@@ -136,6 +145,22 @@ async function buildGalaxy(cfg, limit) {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.@@ -174,30 +199,46 @@ async function persistSnapshot(payload) {}}-// ── POST: Granite semantic search ───────────────────────────────────────────+// ── 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, cfg) {+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 Granite model the agents were embedded with, so- // query and agent vectors share a space.+ // 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 Granite's space, so a vector+ // 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 { vectors } = await watsonxEmbed(cfg, { inputs: [query], model: cfg.embedModel });- queryVec = vectors[0]?.length ? vectors[0] : null;+ 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';@@ -220,7 +261,7 @@ async function handleSearch(req, res, cfg) {.filter(Boolean);return json(res, 200, {query,- model: cfg.embedModel,+ model: embedder.model,count: results.length,results,ranking: 'lexical',@@ -228,7 +269,7 @@ async function handleSearch(req, res, cfg) {});}- const vectorsById = await readAgentVectors([...byId.keys()], { model: cfg.embedModel });+ const vectorsById = await readAgentVectors([...byId.keys()], { model: embedder.model });const ranked = rankBySimilarity(queryVec, vectorsById, { topK });const results = ranked@@ -245,7 +286,7 @@ async function handleSearch(req, res, cfg) {}).filter(Boolean);- return json(res, 200, { query, model: cfg.embedModel, count: results.length, results, ranking: 'semantic' });+ return json(res, 200, { query, model: embedder.model, count: results.length, results, ranking: 'semantic' });}// ── Shared: published-agent population ──────────────────────────────────────diff --git a/data/pages.json b/data/pages.jsonindex 68196665a..2a57f1f0f 100644--- a/data/pages.json+++ b/data/pages.json@@ -1328,7 +1328,7 @@{"path": "/galaxy","title": "Agent Galaxy",- "description": "Every public agent embedded by IBM Granite on watsonx.ai into a navigable 3D constellation with natural-language semantic search.",+ "description": "Every public agent embedded by meaning (IBM Granite on watsonx.ai, with NIM and Vertex AI fallbacks) into a navigable 3D constellation with natural-language semantic search.","priority": 0.6,"changefreq": "weekly"},diff --git a/docs/galaxy.md b/docs/galaxy.mdindex 621285824..ecd67a1b4 100644--- a/docs/galaxy.md+++ b/docs/galaxy.md@@ -1,6 +1,6 @@# Agent Galaxy: every agent, mapped by meaning-Agent Galaxy is an explorable 3D star-map of every published agent on three.ws, positioned in space by what each agent *means*. Coordinates and semantic search are powered by IBM Granite embeddings on watsonx.ai: each agent becomes a vector, the vectors are projected into 3D, and agents cluster into named constellations. Type a natural-language query and the galaxy flies to the agents closest to your intent.+Agent Galaxy is an explorable 3D star-map of every published agent on three.ws, positioned in space by what each agent *means*. Coordinates and semantic search are powered by IBM Granite embeddings on watsonx.ai, with the platform's NVIDIA NIM, Vertex AI, and OpenAI embedding lanes serving when watsonx is unavailable: each agent becomes a vector, the vectors are projected into 3D, and agents cluster into named constellations. Type a natural-language query and the galaxy flies to the agents closest to your intent.Page: [/galaxy](https://three.ws/galaxy)API: `GET /api/galaxy` (build the map) · `POST /api/galaxy` (semantic search) · `GET /api/galaxy/flows` (live economy overlay)@@ -14,18 +14,18 @@ A flat directory of agents tells you what exists but nothing about how they relaThe page ([`pages/galaxy.html`](../pages/galaxy.html)) loads [`src/galaxy.js`](../src/galaxy.js), a Three.js scene. The map itself is assembled server-side and cached.1. **Collect agents.** `GET /api/galaxy` ([`api/galaxy.js`](../api/galaxy.js)) loads published agents from Postgres (`agent_identities` joined to `avatars`, filtered to published, described, named agents, ordered by chat count), default 600 and capped at 1200.-2. **Embed.** Each agent's text (name, description, tone tags) is embedded with IBM Granite through [`api/_lib/watsonx.js`](../api/_lib/watsonx.js). The default model is `ibm/granite-embedding-278m-multilingual`, called at `POST {WATSONX_URL}/ml/v1/text/embeddings` with an IAM bearer token minted from the watsonx API key (the IAM exchange is idempotent and gets three attempts at 10 s; an inference call gets one attempt with a 45 s deadline). Vectors are cached durably per agent (`agent_embeddings`), so only changed agents re-embed.+2. **Embed.** Each agent's text (name, description, tone tags) is embedded with the first embedder that answers (see **Embedding providers** below). The preferred one is IBM Granite through [`api/_lib/watsonx.js`](../api/_lib/watsonx.js). The default model is `ibm/granite-embedding-278m-multilingual`, called at `POST {WATSONX_URL}/ml/v1/text/embeddings` with an IAM bearer token minted from the watsonx API key (the IAM exchange is idempotent and gets three attempts at 10 s; an inference call gets one attempt with a 45 s deadline). Fallback lanes go through [`api/_lib/embeddings.js`](../api/_lib/embeddings.js). Vectors are cached durably per agent (`agent_embeddings`) under the model or lane tag that produced them, so only changed agents re-embed.3. **Project to 3D.** [`api/_lib/embedding-math.js`](../api/_lib/embedding-math.js) mean-centers the vectors, takes the top 3 principal components via power iteration (PCA, seeded and deterministic, not UMAP or t-SNE), whitens per axis, and maps them into a cube of half-width 120 world units. Determinism means cached rebuilds are stable.4. **Cluster into constellations.** Seeded k-means (Lloyd's with k-means++ seeding) over L2-normalized vectors groups agents into `clamp(round(n/8), 2, 8)` clusters. Each cluster is labeled by Granite chat (`ibm/granite-3-8b-instruct`, with a same-family OpenRouter fallback).5. **Render.** The client draws agents as a single `THREE.Points` cloud with a custom additive shader. Point size grows with chat count; a wealth glow (from real wallet net worth via `/api/agents/networth`) biases funded stars toward a violet tint. `OrbitControls` gives drag-to-orbit, scroll-to-zoom, and gentle auto-rotate that pauses on interaction. A raycaster powers hover tooltips.6. **Inspect.** Clicking a star opens an in-scene card with the agent's thumbnail, constellation, description, and meta chips (net worth, chat count, token), plus two actions: "View agent" and "Chat", both on the canonical `/agents/:id` route.-7. **Search.** The search box POSTs `{ query }` to `/api/galaxy`, which embeds the query with the same Granite model and ranks stored agent vectors by cosine similarity (`ranking: "semantic"`). The client highlights matches and flies the camera to the best one. When the embedder cannot answer (unreachable, or no vector returned) there is deliberately no other embedding lane to fall back to, because the stored vectors live in Granite's space and a vector from another model would be compared in a different geometry; instead the same corpus is ranked lexically ([`api/_lib/lexical-rank.js`](../api/_lib/lexical-rank.js)) and the response says so with `ranking: "lexical"` and `degraded: { reason: "embedder_unavailable", detail, retryable: true }`, so a search still returns useful matches rather than a `502`.+7. **Search.** The search box POSTs `{ query }` to `/api/galaxy`, which embeds the query with the model the current map was built with and ranks stored agent vectors by cosine similarity (`ranking: "semantic"`). The client highlights matches and flies the camera to the best one. When the embedder cannot answer (unreachable, or no vector returned) there is deliberately no other embedding lane to fall back to, because the stored vectors live in one model's space and a vector from another model would be compared in a different geometry; instead the same corpus is ranked lexically ([`api/_lib/lexical-rank.js`](../api/_lib/lexical-rank.js)) and the response says so with `ranking: "lexical"` and `degraded: { reason: "embedder_unavailable", detail, retryable: true }`, so a search still returns useful matches rather than a `502`.Only projected coordinates and cluster centroids are sent to the browser; raw high-dimensional vectors never leave the server.## Walkthrough-1. Open [/galaxy](https://three.ws/galaxy). The loading overlay reads "Mapping the agent universe" while Granite embeds the agents.+1. Open [/galaxy](https://three.ws/galaxy). The loading overlay reads "Mapping the agent universe" while the agents are embedded.2. Drag to orbit, scroll to zoom. Watch the constellations, each a color-coded cluster of related agents.3. Hover a star to see the agent name and its constellation; click it to open the inspect card.4. From the card, open the agent's profile ("View agent") or start a conversation ("Chat").@@ -46,7 +46,7 @@ curl 'https://three.ws/api/galaxy?limit=600'# "cached": true, "generated_at": "…"# }-# Semantic search: embed the query with Granite, rank agents by cosine similarity.+# Semantic search: embed the query in the map's vector space, rank agents by cosine similarity.curl -X POST 'https://three.ws/api/galaxy' \-H 'content-type: application/json' \-d '{ "query": "an agent that trades solana memecoins", "limit": 12 }'@@ -57,7 +57,7 @@ curl -X POST 'https://three.ws/api/galaxy' \# "results": [ { "id": "…", "name": "…", "description": "…", "thumbnail": "…", "score": 0.742 } ],# "ranking": "semantic"# }-# When Granite cannot embed the query the same call answers 200 with+# When the embedder cannot answer the query the same call answers 200 with# "ranking": "lexical", a "lexicalScore" per result, and# "degraded": { "reason": "embedder_unavailable", "detail": "…", "retryable": true }.```@@ -66,8 +66,8 @@ curl -X POST 'https://three.ws/api/galaxy' \## States and limits-- **No auth.** Both endpoints are public and read-only, guarded by a per-IP rate limit. Embedding cost is bounded by design: agents embed once into the durable cache and map builds are snapshot-cached, so only a search query triggers a fresh Granite call.-- **watsonx required.** With no credentials the endpoint returns `503 watsonx_unavailable` and the page shows "IBM Granite isn't connected" (no retry). Configure `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` to light it up. With credentials present but Granite failing on a search, the query degrades to lexical ranking as described above instead of erroring.+- **No auth.** Both endpoints are public and read-only, guarded by a per-IP rate limit. Embedding cost is bounded by design: agents embed once into the durable cache and map builds are snapshot-cached, so only a search query triggers a fresh embedding call.+- **Embedding providers.** IBM Granite on watsonx.ai (`WATSONX_API_KEY` plus `WATSONX_PROJECT_ID` or `WATSONX_SPACE_ID`) is preferred. When watsonx is unconfigured, or fails while building a map, the platform embedding lanes serve instead, in order: NVIDIA NIM `nvidia/nemotron-3-embed-1b@2048` (`NVIDIA_API_KEY`), Vertex AI `vertex/text-embedding-005@768` (`GOOGLE_CLOUD_PROJECT`), then OpenAI `text-embedding-3-small@256` (`OPENAI_API_KEY`). A map is always built from a single vector space, the response's `model` names the one that served, and search embeds the query with the model of the latest snapshot so it never compares vectors across spaces. Constellation names still come from Granite (watsonx, or OpenRouter-hosted Granite); with neither reachable they fall back to labels derived from each constellation's members. With no embedding provider at all the endpoint returns `503 embeddings_unavailable` and the page shows "No embedding provider is connected" (no retry). If the embedder fails on a search, the query degrades to lexical ranking as described above instead of erroring.- **Caching.** Three layers: a `galaxy_snapshots` server snapshot (6-hour TTL, with warm-instance rebuild coalescing), the durable per-agent `agent_embeddings` cache, and a 60-second cache on the published-agent query. Pass `?refresh=1` to bypass the snapshot.- **Population.** However many published agents exist, capped by the limit. There is no fixed count.- **Empty state.** With zero published agents the page shows "The galaxy is still forming" and a "Create an agent" CTA to `/create`.diff --git a/pages/galaxy.html b/pages/galaxy.htmlindex 5f9646793..ed45c70bf 100644--- a/pages/galaxy.html+++ b/pages/galaxy.html@@ -217,7 +217,7 @@<div class="gx-overlay-actions"><button class="gx-btn gx-btn-primary" id="gxRetry" type="button" data-i18n="galaxy.try_again">Try again</button><a class="gx-btn gx-btn-primary" id="gxErrorBrowse" href="/agents/" hidden data-i18n="galaxy.browse_every_agent">Browse every agent</a>- <a class="gx-btn gx-btn-ghost" href="/docs/ibm" data-i18n="galaxy.how_the_galaxy_is_built">How the galaxy is built</a>+ <a class="gx-btn gx-btn-ghost" href="/docs/galaxy" data-i18n="galaxy.how_the_galaxy_is_built">How the galaxy is built</a></div></div>diff --git a/public/features.json b/public/features.jsonindex 23a47427f..1612abe8d 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-16T19:49:26.734Z",+ "generated_at": "2026-09-16T20:04:21.849Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",@@ -1603,7 +1603,7 @@{"path": "/galaxy","title": "Agent Galaxy",- "description": "Every public agent embedded by IBM Granite on watsonx.ai into a navigable 3D constellation with natural-language semantic search.",+ "description": "Every public agent embedded by meaning (IBM Granite on watsonx.ai, with NIM and Vertex AI fallbacks) into a navigable 3D constellation with natural-language semantic search.","added": null,"auth": null,"indexable": true,diff --git a/public/llms-full.txt b/public/llms-full.txtindex 2344140c4..43a7b5a79 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -986,7 +986,7 @@ Global leaderboard for the walking avatar: distance walked, sites visited, and tURL: https://three.ws/galaxy-Every public agent embedded by IBM Granite on watsonx.ai into a navigable 3D constellation with natural-language semantic search.+Every public agent embedded by meaning (IBM Granite on watsonx.ai, with NIM and Vertex AI fallbacks) into a navigable 3D constellation with natural-language semantic search.### Agent Symphonydiff --git a/public/llms.txt b/public/llms.txtindex 9bd1017f7..5aea9156c 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -182,7 +182,7 @@ Experimental features actively shipping. Expect fast iteration.- [Rankings](https://three.ws/rankings): The cross-surface three.ws leaderboard: creators ranked by real creations, remixes received, coin launches, followers, and distance walked. Track your streak and earn badges for showing up.- [Daily Match](https://three.ws/daily-match): Which agent ships the most real output today? Live daily standings over real agent activity: actions, trades, skill sales, and coin launches. Resets at 00:00 UTC.- [Walk Leaderboard](https://three.ws/walk-leaderboard): Global leaderboard for the walking avatar: distance walked, sites visited, and time, ranked daily, weekly, and all-time.-- [Agent Galaxy](https://three.ws/galaxy): Every public agent embedded by IBM Granite on watsonx.ai into a navigable 3D constellation with natural-language semantic search.+- [Agent Galaxy](https://three.ws/galaxy): Every public agent embedded by meaning (IBM Granite on watsonx.ai, with NIM and Vertex AI fallbacks) into a navigable 3D constellation with natural-language semantic search.- [Agent Symphony](https://three.ws/symphony): The agent economy, played live as generative music. Every real payment, trade, launch and level-up on three.ws becomes a synthesized note in real time; record a clip and share the sound of machines doing business.- [Runway Lab](https://three.ws/economy-lab): A live digital twin of the three.ws x402 payment rail. Runs the exact admission-control code the production settle path runs, seeded with live production balances, so you can drag a knob and watch settlement survive or starve, then get the exact command that fixes it.- [Holo Sticker](https://three.ws/holo): A live holographic foil sticker rendered in your browser: tilt it with your pointer, peel the corner, switch foils, die-cut your own text, and download the frame as a PNG. Fully procedural, no assets.diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex 7f80112eb..79ed15f29 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -1330,7 +1330,7 @@<a href="/galaxy"><span class="sm-title">Agent Galaxy</span><span class="sm-path">/galaxy</span>- <span class="sm-desc">Every public agent embedded by IBM Granite on watsonx.ai into a navigable 3D constellation with natural-language semantic search.</span>+ <span class="sm-desc">Every public agent embedded by meaning (IBM Granite on watsonx.ai, with NIM and Vertex AI fallbacks) into a navigable 3D constellation with natural-language semantic search.</span></a></li><li>diff --git a/src/galaxy.js b/src/galaxy.jsindex b8c44abd6..9f85822ba 100644--- a/src/galaxy.js+++ b/src/galaxy.js@@ -1,13 +1,14 @@// Agent Galaxy — the interactive 3D star-map.//// Fetches the constellation snapshot from /api/galaxy (agents positioned by IBM-// Granite embeddings on watsonx.ai), renders it as a glowing point cloud with+// Granite embeddings on watsonx.ai, or the platform embedding lanes when watsonx is+// unavailable), renders it as a glowing point cloud with// Three.js, and wires the exploration UI: hover tooltips, click-to-inspect, a-// Granite-powered semantic search that lights up matching stars, and a legend that+// semantic search that lights up matching stars, and a legend that// flies the camera to each named constellation.//// All data is real (no mock path). When the backend can't build the galaxy — most-// often because watsonx isn't configured — the viewer explains rather than faking a+// often because no embedding provider is configured — the viewer explains rather than faking a// universe.import * as THREE from 'three';@@ -131,11 +132,11 @@ async function loadGalaxy(refresh) {const body = await res.json().catch(() => ({}));if (!res.ok) {- if (res.status === 503 && body.error === 'watsonx_unavailable') {+ if (res.status === 503 && body.error === 'embeddings_unavailable') {return showError(- 'IBM Granite isn’t connected',- 'The galaxy is positioned by IBM Granite embeddings on watsonx.ai. ' +- 'Once watsonx credentials are configured, the universe lights up here.',+ 'No embedding provider is connected',+ 'The galaxy positions agents by semantic embeddings. ' ++ 'Once an embedding provider is configured, the universe lights up here.',false,);}@@ -403,7 +404,7 @@ function toggleClusterFocus(clusterId) {if (c) flyToTarget(new THREE.Vector3(...c.centroid), 220);}-// ── Semantic search (Granite) ───────────────────────────────────────────────+// ── Semantic search ───────────────────────────────────────────────────────────let searchSeq = 0;// The search button's resting label is translated copy, so it is read off the// button rather than hardcoded. `SEARCH_BUSY` marks the in-flight state and isdiff --git a/tests/e2e/galaxy.spec.js b/tests/e2e/galaxy.spec.jsindex 81ecaa461..dd1a8e7b5 100644--- a/tests/e2e/galaxy.spec.js+++ b/tests/e2e/galaxy.spec.js@@ -10,7 +10,7 @@* State coverage:* - populated galaxy -> stars render, legend + stats fill in* - no agents -> empty overlay, with a way to create one- * - watsonx 503 -> unretryable error overlay, with a way onward+ * - embedder 503 -> unretryable error overlay, with a way onward* - transport failure -> retryable error overlay, retry recovers** Interaction coverage:@@ -91,7 +91,7 @@ async function routeGalaxy(page, mode = 'success') {await page.route('**/api/galaxy', async (route) => {if (route.request().method() === 'POST') {if (mode === 'unavailable') {- return route.fulfill({ status: 503, json: watsonx503() });+ return route.fulfill({ status: 503, json: embedder503() });}return route.fulfill({ json: fx.searchFor(0) });}@@ -103,7 +103,7 @@ async function routeGalaxy(page, mode = 'success') {json: { count: 0, dims: 0, model: null, clusters: [], agents: [], cached: false },});}- if (mode === 'unavailable') return route.fulfill({ status: 503, json: watsonx503() });+ if (mode === 'unavailable') return route.fulfill({ status: 503, json: embedder503() });if (mode === 'down') return route.abort('failed');return route.fallback();});@@ -113,12 +113,12 @@ async function routeGalaxy(page, mode = 'success') {await page.route('**/api/genome/edges**', (r) => r.fulfill({ json: { edges: [] } }));}-function watsonx503() {+function embedder503() {return {- error: 'watsonx_unavailable',+ error: 'embeddings_unavailable',error_description:- 'The Agent Galaxy is positioned by IBM Granite embeddings on watsonx.ai. ' +- 'Set WATSONX_API_KEY and WATSONX_PROJECT_ID (or WATSONX_SPACE_ID) to build it.',+ 'The Agent Galaxy needs an embedding provider. Configure watsonx.ai ' ++ '(WATSONX_API_KEY and WATSONX_PROJECT_ID), NVIDIA_API_KEY, or GOOGLE_CLOUD_PROJECT.',};}@@ -219,13 +219,13 @@ test.describe('Agent Galaxy', () => {test('an unconfigured embedder is a dead end for nobody', async ({ page }) => {await gotoGalaxy(page, 'unavailable');await expect(page.locator('#gxError')).toBeVisible();- await expect(page.locator('#gxErrorTitle')).toContainText('Granite');- await expect(page.locator('#gxErrorSub')).toContainText('watsonx');+ await expect(page.locator('#gxErrorTitle')).toContainText('embedding provider');+ await expect(page.locator('#gxErrorSub')).toContainText('embedding provider');// Retrying a configuration gap just fails again, so the retry is hidden and// two real onward paths take its place.await expect(page.locator('#gxRetry')).toBeHidden();await expect(page.locator('#gxErrorBrowse')).toBeVisible();- await expect(page.locator('#gxError a[href="/docs/ibm"]')).toBeVisible();+ await expect(page.locator('#gxError a[href="/docs/galaxy"]')).toBeVisible();// Nothing behind the overlay stays reachable by keyboard.const reachable = await page.evaluate(() =>