Worldlabs Topology Viz

World Labs Fantastical Topology Visualization Skill

Version: 1.0.0 Feature: 122-worldlabs-topology-viz Status: Active

Overview

Produces an AI-augmented, explorable 3D "world" visualization of a real network topology, built on top of the existing spec 121 topology-diagram-mcp pipeline. World Labs' Marble API is a generative world model — it does not accept structured/graph input and has no mechanism for precise node placement, so this is explicitly a decorative, companion visualization, never a replacement for the accurate topology diagram. The real, structurally-correct diagram (produced by the existing, unmodified topology-diagram-mcp/render_structural tool) remains the authoritative artifact and is always referenced alongside any result this skill produces.

Two distinct modes:

1. Preview — free, instant, no World Labs call, repeatable with a different theme.
2. Generate — spends real World Labs credits (~5 minutes per world), and only runs after an explicit, separate user confirmation, enforced both conversationally and by the worldlabs-marble-mcp tool itself (it will not proceed without user_confirmed=true).

Prerequisites

• WLT_API_KEY in .env — your World Labs API key (platform.worldlabs.ai/api-keys), with a funded account (platform.worldlabs.ai/billing). Required only for the generate mode — preview needs no credential at all.
• The worldlabs-marble-mcp server (mcp-servers/worldlabs-marble-mcp/), registered in config/openclaw.json.
• The existing topology-diagram-mcp server (spec 121), already registered — reused unmodified.

Topology sources

Any topology snapshot already normalized into the devices/links shape topology-diagram-mcp accepts (CML, pyATS, or any of NetClaw's other topology-of-record integrations, or a freeform description).

Workflow: Free Preview (User Story 1)

Zero cost, instant, repeatable with a different theme. No call to worldlabs-marble-mcp is ever made in this workflow.

1. Obtain the topology snapshot (devices/links) from whatever source the operator named (or a freeform description), normalized into the shape topology-diagram-mcp/render_structural already accepts: devices: [{"hostname","role","state"}], links: [{"a","b","label"}].
2. Call topology-diagram-mcp/render_structural(snapshot_id, devices, links) — reused unmodified. This tool has two existing failure modes that MUST both be surfaced clearly, distinctly, and before anything else in this workflow runs (FR-012 and its Edge Cases correction):
   • Empty topology (devices is empty): the tool raises "devices list is empty — nothing to render". Report exactly that — this topology has nothing to preview. Do not attempt to fabricate a prompt or a result.
   • Too many devices (over the working-resolution density ceiling, 60 devices): the tool raises a message naming the ceiling. Report that specific reason (e.g. "this topology has N devices, exceeding the 60-device legibility ceiling — narrow the scope and try again"), not a generic failure.
   • A single device with zero links is NOT a failure — render_structural already supports it (a one-node layout), and this workflow proceeds normally.
3. On success, build a topology_model.TopologySnapshot from the same devices/links data (via topology_model.Device/Link), and call fantastical_prompt_builder.build_prompt(snapshot, theme=<operator-specified theme, or None for the default>).
4. Present the result to the operator:
   • The reference diagram (render_structural's image_base64, or a note of where it's shown).
   • The composed text prompt from step 3.
   • topology_model.DECORATIVE_LABEL, verbatim, every single time (FR-009) — this is a preview of what could be generated, not a claim about what a generated world will precisely look like (Marble is non-deterministic).
   • An explicit statement that no credits were spent and no call was made to World Labs.

Workflow: Confirm and Generate (User Story 2)

This is the one part of this skill that spends real money. Only run this after Workflow: Free Preview has already produced a reference diagram and prompt for the same topology snapshot.

1. State plainly, as its own message, separate from anything else: "Generating this world will spend World Labs credits and typically takes about 5 minutes. Proceed?" Do not combine this with the preview step's output, and do not proceed without an explicit affirmative reply (FR-004). This conversational check is the first of two independent layers — see step 2.
2. Only once the operator has explicitly confirmed, call worldlabs-marble-mcp/generate_world(text_prompt=<from the preview's composed prompt>, display_name=<derived from the snapshot's identity, max 64 chars>, user_confirmed=true). Do NOT pass image_base64 (research.md R9/R10, corrected 2026-09-03 after live evidence from six real production generations): attaching the reference diagram as an image gets pasted flat and unchanged into the generated scene instead of being used as structural guidance, and is also measurably less reliable (3 of 4 image-bearing attempts failed; 4 of 4 text-only attempts succeeded on the first try). fantastical_prompt_builder.build_prompt already describes every real device and every real link individually in the text — that is the thing that actually carries real data into the result, not the image. The user_confirmed=true argument is the second, code-level layer (FR-016) — generate_world itself refuses to make any outbound call without it, so this is not optional plumbing to skip.
3. Immediately after that call returns (success, failure, or a confirmation_required rejection — which should never happen if step 1 was actually followed, but is handled the same way if it does), record a GAIT entry via gait_record_turn (Constitution Principle IV, FR-015): user_text names the topology snapshot's identity/theme and that the operator confirmed; assistant_text names the operation_id and, once known, the world_id/world_marble_url/cost.total_credits or the failure category; artifacts is empty or references the reference diagram's identity only — never the API key, never raw device data beyond hostname/role identity. This step is required for every confirmed attempt, not optional, and is distinct from any end-of-session GAIT summary.
4. Report the result:
   • Success: the operation_id (tell the operator to note it — nothing server-side tracks it, Clarifications Q1), and that status can be checked later.
   • confirmation_required: this means step 1/2 were skipped — report it and restart from step 1, do not retry the call with the flag silently added.
   • authentication_failure: tell the operator to check WLT_API_KEY — never repeat the key value itself.
   • insufficient_credits: pass through World Labs' own message (it already names the fix — add credits or enable auto-refill).
   • rate_limited: tell the operator to wait and retry later — do not resubmit automatically.
   • generic_failure: pass through the provider's message.
5. To check status later, call worldlabs-marble-mcp/check_generation_status(operation_id).
   • done: false — still in progress; report that plainly.
   • done: true with a response — completed. Report world_marble_url (the viewer link), assets, and cost.total_credits, plus topology_model.DECORATIVE_LABEL verbatim, every time (FR-009) — a completed generation is exactly the case someone could mistake for an accurate diagram, so this label matters most here.
   • done: true with an error — the generation itself failed after starting; report the error plainly, and do not retry automatically.
   • not_found_or_expired — the operation record itself expired (they carry a roughly one-hour expires_at). If an earlier poll's metadata included a world_id, fall back to worldlabs-marble-mcp/get_world(world_id) instead of reporting a hard failure — the world itself is not necessarily gone just because the operation record is. Include DECORATIVE_LABEL here too if get_world succeeds.