Back to the courseDownload Markdown

Step-by-step course guide

Audience: engineers who want to turn live ecosystem telemetry into 3D visualizations — probing the alien-monitor REST API, modelling its topology as a typed graph, and mapping oracle scenes to React Three Fiber. Languages: COURSE_LANG=en|ru|es|fr|zh · UI strings in i18n/ · this guide in English. Русский · Español · Français · 中文

Check against the current ecosystem

The labs use Alien Monitor’s /api/topology. The separate Service Mesh API exposes /health, /v1/stats, /v1/agents, and /v1/activity. For a live comparison, fetch Mesh stats and check tasks_24h and mesh_hops_24h. Its USD volume is Mesh telemetry for a 24-hour window. Build the Alien Monitor graph from its own response schema.

Why this course

alien-monitor is the live 3D map of the AIMarket ecosystem: a Hub, its federation peers, and a constellation of oracles, each rendered as an animated React Three Fiber scene. This course teaches the data layer behind that map. You learn to probe the monitor's REST API (/api/health, /api/topology, /api/reputation/*), model the responses as typed Python structures, rank nodes with the LUMEN PageRank/EigenTrust scores, and finally map each oracle slug to the camera, accent colour, and math-primitive metadata that the R3F front-end uses to draw its scene.

Every lab is deterministic and offline-friendly: if a live alien-monitor is not running on 127.0.0.1:9100, each lab auto-starts an in-process mock server with the same REST shape, so the whole course runs with no network and no API keys. Every lab also prints a Trace block so behaviour is inspectable rather than magic.

Table of contents

  1. Choose your track
  2. Setup (10 minutes)
  3. Module M1 — Monitor health & modes
  4. Module M2 — Topology graph model
  5. Module M3 — Federation reputation
  6. Module M4 — LUMEN PageRank scores
  7. Module M5 — R3F oracle scene mapping (advanced)
  8. Connect a live monitor
  9. Exercises & certificate
  10. Observability: the Trace block
  11. Self-check checklist
  12. Troubleshooting
  13. Next steps

Choose your track

Track Modules Time Live monitor Front-end
Basic M1 → M2 → M3 → M4 ~1.5 h Mock (auto) None — pure Python
Advanced Basic + M5 +30 min Mock or live Maps to R3F specs
Live bridge After M4 or M5 +30 min Real alien-monitor Optional

The mock server backs every track, so you never need a running monitor to finish the course. Read the Trace section after each lab — every script prints a Trace you can inspect.

Setup (10 minutes)

Step 1 — Clone and install

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/3d-data-viz-course
pip install -e ".[dev]"

[dev] is the only extra you need — the labs use the Python standard library for HTTP probing, so there are no heavy runtime dependencies. [dev] adds pytest for the test suite.

Step 2 — Verify tests

pytest -q

Expected: all tests pass (i18n parity across en/ru/es/fr/zh, graph parsing, R3F mapping, exercise checks).

Step 3 — Run the first lab

python labs/lab01_health_probe.py
python labs/run_exercises.py

The first command probes the monitor (mock if none is live); the second runs the DIY checks for all five modules.

Step 4 — Pick a language (optional)

export COURSE_LANG=ru   # or es, default en
python labs/lab01_health_probe.py

All module titles, concepts, labels, and exercise hints come from i18n/{en,ru,es,fr,zh}.json.

Step 5 — Colab alternative

  1. Open the course site → Open in Colab on any lab.
  2. Run the setup cell (clone + pip install -e ".[dev]").
  3. Set os.environ["COURSE_LANG"] = "ru" in the setup cell if needed.
  4. Run the lab cell — the mock server runs fine inside Colab.

Module M1 — Monitor health & modes

Concept: Probe /api/health and understand TEST vs REAL vs UNIVERSE modes. Lab: labs/lab01_health_probe.py · Time: ~15 min · Industry map: observability, SRE

Steps

  1. Open labs/lab01_health_probe.py and read the module docstring.

  2. Run locally:

    python labs/lab01_health_probe.py

  3. Read the output:

    • Live alien-monitor reachable: True/False — whether a real monitor was found on 127.0.0.1:9100.
    • result: status=ok mode=test — the parsed HealthStatus. The mode is the monitor's data source: test (mock fixtures), real (live ecosystem), or universe (federated multi-hub view).
    • If a mock was used, you'll see the "in-process mock server" note.
    • A trace line with the event count.

  4. Skim courselib/viz.py — find probe_health, HealthStatus, monitor_reachable, resolve_monitor_url.

What it proves / produces

A working REST probe and the resolve_monitor_url() pattern (live-or-mock) that every later lab reuses.

Self-check

Module M2 — Topology graph model

Concept: Parse nodes + links from /api/topology into typed graph structures. Lab: labs/lab02_topology_graph.py · Time: ~20 min · Prerequisites: M1 · Industry map: graph viz, React Flow

Steps

  1. Run python labs/lab02_topology_graph.py.
  2. Read the output: node and link counts, then up to six nodes printed as id, group, 3D position, and status.
  3. Note the Adjacency list: N directed edges line — TopologyGraph.adjacency() deduplicates edges and drops self-loops, the shape a force-directed renderer consumes.
  4. Open courselib/viz.py — study MonitorNode, MonitorLink, TopologyGraph, and Vec3.from_dict. Notice how from_api classmethods defensively coerce raw JSON into typed dataclasses.

What it proves / produces

A typed in-memory graph (nodes, links, adjacency(), node_ids(), oracle_slugs()) — the model M4 and M5 build on.

Self-check

Module M3 — Federation reputation

Concept: Enrich the trust graph with /api/reputation/peers from the Hub. Lab: labs/lab03_reputation_peers.py · Time: ~20 min · Prerequisites: M2 · Industry map: EigenTrust, federation

Steps

  1. Run python labs/lab03_reputation_peers.py.
  2. Read the output: Federation peers: N (mode) followed by each peer's name, trust_score, and url. A peer with no score prints —.
  3. Open courselib/viz.py — study ReputationPeer and ReputationPeers. The trust_score is float | None, so your visualization must handle missing data.

What it proves / produces

The federation layer of the graph: which external Hubs this monitor trusts, and by how much — the input to colour/size encodings of peer nodes.

Self-check

Module M4 — LUMEN PageRank scores

Concept: Call /api/reputation/lumen and bind scores to graph nodes. Lab: labs/lab04_lumen_scores.py · Time: ~20 min · Prerequisites: M2 · Industry map: reputation oracles

Steps

  1. Run python labs/lab04_lumen_scores.py.
  2. Read the output: nodes sorted by score, each with a █ bar chart and the score to 4 decimals, then PageRank iterations: N.
  3. If LUMEN is unavailable the lab prints a LUMEN error line instead of crashing — note the lumen.ok guard.
  4. Open courselib/viz.py — study LumenScores and by_id(), which zips ids with scores so you can join PageRank values onto the M2 node ids.

What it proves / produces

A node-id → reputation-weight map. LUMEN is the EigenTrust/PageRank power-iteration oracle; these weights drive node sizing in the live 3D map.

Self-check

Module M5 — R3F oracle scene mapping (advanced)

Concept: Map oracle slugs to camera, accent, and primitive metadata for Three.js scenes. Lab: labs/lab05_r3f_scenes.py · Time: ~30 min · Prerequisites: M2 · Industry map: React Three Fiber, WebGL

Steps

  1. Run python labs/lab05_r3f_scenes.py.
  2. Read the output: Oracle R3F scenes: N, then per scene the slug, kind (r3f or ambient), camera tuple, accent colour, and a truncated primitive description.
  3. Open courselib/viz.py — study ORACLE_SCENE_META, R3FSceneSpec.for_oracle, and map_graph_to_r3f_scenes. The metadata table is mirrored from alien-monitor/frontend/src/oracleScenes/meta.ts, so the Python spec and the front-end stay in sync.
  4. Notice TopologyGraph.oracle_slugs() — it strips the oracle- prefix or matches group == "oracle", then each slug looks up its camera/accent/primitive (with sensible fallbacks for unknown slugs).

What it proves / produces

A list of R3FSceneSpec objects — exactly the camera position, accent, and primitive a React Three Fiber <Canvas> needs to render each oracle. This closes the loop from REST telemetry to a 3D scene.

Self-check

Connect a live monitor

By default the labs run against the built-in mock. To probe a real alien-monitor:

# point the labs at any running monitor (default is http://127.0.0.1:9100)
export ALIEN_MONITOR_URL=http://127.0.0.1:9100
python labs/lab01_health_probe.py

When the monitor is reachable, resolve_monitor_url() skips the mock and Live alien-monitor reachable: True appears. The same five labs then visualize the real ecosystem — modes flip from test to real/universe, the topology shows live nodes, and LUMEN returns live PageRank scores.

Exercises & certificate

After the labs, run the DIY checks:

python labs/run_exercises.py             # run all five module checks
python labs/run_exercises.py --module m4 # run just one module

Each module's check (exercise_m1_health_ok … exercise_m5_r3f_mapping) asserts the property the lab taught — e.g. m1 asserts status == "ok" and a valid mode, m4 asserts len(scores) == len(ids).

Once all checks pass, generate the certificate:

python labs/run_exercises.py --certificate "Your Name" --lang en   # or ru / es

This writes certificate.html (credential ID derived from name + date). Open it in a browser and Print → Save as PDF for a PDF copy. Pass all module checks to unlock the certificate.

Observability: the Trace block

Concept: Every lab records a Trace so its behaviour is inspectable, not magic. Covered in: every lab · Time: ~5 min after each lab

Steps (repeat after M1–M5)

  1. Scroll to the trace (N events) line at the end of the lab output.
  2. Each lab logs structured events: M1 logs health, M2 logs one node per node, M3 logs peer, M4 logs lumen_score, M5 logs r3f_scene.
  3. Map each event back to a line you saw in stdout — the trace is the lab's "unit-test log" for what it probed and produced.

Self-check

Self-check checklist

After the basic track you should be able to:

After the advanced track add:

Troubleshooting

Problem Fix
ModuleNotFoundError: courselib Run from the repo root; labs prepend the parent dir to sys.path
Live alien-monitor reachable: False Expected with no live monitor — the in-process mock takes over automatically
Want to use a live monitor Start alien-monitor on 127.0.0.1:9100 or set ALIEN_MONITOR_URL
LUMEN error / empty scores Live monitor returned no LUMEN data; the lab guards on lumen.ok and keeps running
Empty RU/ES strings Set COURSE_LANG; check i18n/ru.json keys match en.json
pytest i18n parity failure Add the missing key to all three of en/ru/es.json
Colab running stale code Re-run the setup cell; pin the main branch

Next steps

Guides in docs/ are hand-maintained — update EN first, then the RU/ES mirrors.