Raylings ⚡

Master distributed AI, Ray Core actors, and scalable clusters from scratch through small, interactive, hands-on Python exercises.

Inspired by the pedagogical brilliance of rustlings and ziglings, Raylings guides engineers through self-paced, iterative exercises. You will fix broken distributed tasks, construct stateful actor pools, eliminate object store memory bottlenecks, configure custom placement groups, build fault-tolerant streaming pipelines, coordinate PyTorch FSDP & DeepSpeed ZeRO training, serve LLMs with vLLM tensor parallelism, orchestrate KubeRay clusters on Kubernetes, and deploy domain-specific financial analytics packs.

Pedagogical Philosophy

Learning distributed computing and Ray from static documentation or raw copy-pasted boilerplate is difficult because distributed error messages are complex and feedback loops are slow. Raylings solves this through guided, test-driven micro-learning:

1. Active Debugging & Iteration: Every exercise starts in a broken or incomplete state with clear # TODO: instructions and # WHY: architectural rationale. You read the problem description, inspect the failure, and edit the code until it passes all verification checks.
2. Instant Feedback Loop & Interactive Hotkeys: An automated watcher observes file modifications in real time (< 50ms). When an exercise passes, press n or Enter to advance, p to revisit previous exercises, h to reveal progressive hints, r to force a rerun, l to list exercises, or q to quit.
3. Dual-Mode Learning (Offline WASM & Live Cluster):
   • Offline WASM Mode: Zero cluster setup required. The pure-Python WebAssembly simulator validates tasks, actors, object store references, and dataset transformations directly in-memory or in your browser.
   • Live Cluster Mode: Seamlessly connect to a local Ray session, remote Ray cluster, or multi-node Kubernetes KubeRay cluster (ray://localhost:10001). Exercises provision real actors and verify distributed execution across nodes.
4. Progressive Hints: When stuck, multi-tiered hints (raylings hint <exercise>) nudge you in the right direction without spoiling the answer.

Architecture

                                  +-----------------------+
                                  |     User Terminal     |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |   Raylings CLI (Typer)|
                                  +-----------+-----------+
                                              |
                     +------------------------+------------------------+
                     |                                                 |
                     v                                                 v
         +-----------------------+                         +-----------------------+
         |  File Watcher Engine  |                         | Rich UI & TUI Engine  |
         |      (watchfiles)     |                         |  (split-pane / top)   |
         +-----------+-----------+                         +-----------------------+
                     |
                     v
         +-----------------------+
         |  Curriculum Manifest  |  (18 Chapters / 81 Exercises)
         +-----------+-----------+
                     |
                     v
         +-----------------------+
         |   Exercise Runner     |
         +-----------+-----------+
                     |
        +------------+------------+
        |                         |
        v                         v
+----------------+       +-------------------+
| Pure-Python    |       | Live Ray Cluster  |
| In-Memory WASM |  OR   | & KubeRay Multi-  |
| Ray Simulator  |       | Node Adapter      |
+----------------+       +-------------------+

Quickstart & Installation

Try in Browser (Zero Installation)

Test Raylings directly inside your web browser without installing any tools or starting a local daemon:

👉 ⚡ Try in Browser — Run Python 3.12, Monaco Editor, and in-memory Ray simulation 100% client-side via Pyodide WebAssembly.

Prerequisites

• Python >= 3.10
• uv (recommended) or pip / pipx
• Optional (for multi-node KubeRay exercises): kubectl, helm, and a local cluster (kind, minikube, or k3d)

Running Instantly (No Clone Needed)

You can run Raylings anywhere using uvx or pipx:

# Launch the interactive guided onboarding tour
uvx raylings tour

# Run preflight system & cluster diagnostics
uvx raylings doctor

# Initialize exercises in your current folder
uvx raylings init

# Launch the full-screen interactive TUI
uvx raylings tui

# Or start the background file watcher
uvx raylings watch

Or install globally:

pipx install raylings
raylings tour
raylings init
raylings watch

📖 New to Raylings? Check out the Complete Onboarding & Learner's Guide for a visual step-by-step tutorial!

Local Development Installation

Clone the repository and install dependencies in editable mode:

Using uv (Fastest)

git clone https://github.com/dnf0/raylings.git
cd raylings
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Using Standard pip

git clone https://github.com/dnf0/raylings.git
cd raylings
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify your installation:

raylings --help

Interactive Learning Commands

1. Interactive Onboarding Tour (raylings tour)

Launch the rich, 5-step terminal walkthrough with live environment probes, workflow introduction, and guided basics01 resolution:

raylings tour
# or run non-interactively / output json
raylings tour --non-interactive
raylings tour --step 3
raylings tour --json

2. Interactive Full-Screen Split-Pane TUI (raylings tui)

Explore the curriculum, preview syntax-highlighted code with line numbers, inspect live telemetry, and trigger evaluations inside a split-pane full-screen terminal interface:

raylings tui

3. Live Background Watcher (raylings watch)

Start the interactive development loop. Whenever you save an exercise in exercises/, Raylings immediately evaluates your changes (< 50ms):

raylings watch

Interactive Hotkeys:

• n / Enter : Advance to next exercise
• p : Navigate to previous exercise
• h : Reveal progressive hint tier
• r : Force rerun current exercise
• l : List curriculum exercises
• q : Exit watcher

4. Cluster Health & Telemetry Inspector (raylings top)

Inspect your local Ray cluster's live Plasma memory allocations, object spill rates, CPU/GPU core saturation, and instantiated actor tables in real time:

raylings top --interval 0.5
# or output a one-shot JSON snapshot:
raylings top --json

5. Preflight System & Ray Diagnostics (raylings doctor)

Audit your local environment, Python runtime, Ray installation, shared memory (/dev/shm), and cluster connectivity:

raylings doctor
# or output machine-readable json
raylings doctor --json

6. Exercise Scaffolding Tool (raylings new)

Generate new exercise and solution boilerplate matching Raylings pedagogical standards with a single command:

raylings new 15 vllm05 --title "Speculative Decoding" --description "Coordinate draft model worker actors."

7. Pluggable Curriculum Extension Registry (raylings plugins)

Discover, inspect, and validate external domain-specific curriculum packs (e.g., Chapter 18 Quantitative Finance):

# List all registered curriculum plugins
raylings plugins list

# Inspect detailed metadata and syllabus of a plugin
raylings plugins info finance

# Validate custom plugin pack manifests and exercise code
raylings plugins validate path/to/my_plugin.py

8. Cloud & KubeRay Multi-Node Testing (scripts/kuberay/)

Deploy ephemeral 3-node KinD clusters and verify distributed execution across real Kubernetes worker pods:

# 1. Provision 3-node KinD cluster & KubeRay operator
bash scripts/kuberay/setup-kuberay.sh up

# 2. Forward Ray client (10001) and dashboard (8265) ports
bash scripts/kuberay/setup-kuberay.sh forward

# 3. Run exercises or watch against the remote Kubernetes cluster
RAY_ADDRESS=ray://localhost:10001 raylings run exercises/14_kuberay/kuberay01.py

# 4. Run the multi-node end-to-end integration test suite
RAY_ADDRESS=ray://localhost:10001 uv run pytest tests/test_kuberay_e2e.py -v

# 5. Teardown cluster
bash scripts/kuberay/setup-kuberay.sh down

9. Run a Single Exercise (raylings run)

Execute and evaluate a single exercise directly:

raylings run basics01

10. Progressive Hints (raylings hint)

Get step-by-step clues for any exercise:

raylings hint basics01

11. List All Chapters & Progress (raylings list & raylings progress)

Browse the entire curriculum syllabus or check your completion progress:

raylings list
raylings progress

12. Test Reference Solutions (raylings test)

Run built-in automated verification across all 81 reference solutions:

raylings test

VS Code & Cursor Extension 💻

Raylings provides an official extension for Visual Studio Code and Cursor that turns your editor into a fully integrated distributed AI learning IDE.

✨ Extension Features

• 🗺️ Interactive Welcome Walkthrough: Built-in editor walkthrough (Raylings: Open Welcome Walkthrough) guiding you through curriculum navigation, preflight diagnostics, and first exercise resolution.
• 📚 Activity Bar Curriculum Tree View: Browse all 18 chapters and 81 exercises directly from the sidebar with real-time pass/fail status and chapter completion counters.
• 📊 Status Bar Progress Indicator: Persistent status bar item showing your total completion percentage, current progress, and next active exercise. Click to jump straight to the code.
• ⚡ On-Save Diagnostics: Automatic in-editor validation whenever you save an exercise (exercises/**/*.py), surfacing distributed exceptions, assertion failures, or Raylet deadlocks.
• 💡 Code Actions & Quick Fixes: Lightbulb quick fixes directly on errors to:
  • Reveal Hint: Display progressive hints in the editor without spoiling the answer.
  • Compare with Reference Solution: Instantly open a side-by-side diff comparing your exercise code against the official reference solution.
• 🔍 Solution Diffing: Interactive diff viewer (raylings.showSolutionDiff) for visual code comparison.
• 💻 Integrated Terminal Watch Mode: Launch raylings watch or raylings tui into a dedicated integrated terminal with a single click.

📦 Extension Installation

Via Command Line (VSIX)

# For VS Code
code --install-extension dist/raylings-vscode.vsix

# For Cursor
cursor --install-extension dist/raylings-vscode.vsix

Via Editor UI (VSIX)

1. Open the Extensions view (Ctrl+Shift+X / Cmd+Shift+X).
2. Click the ... (Views and More Actions) menu in the top-right corner of the Extensions pane.
3. Select Install from VSIX... and choose dist/raylings-vscode.vsix (available from the repository root after packaging or downloaded from GitHub Releases).

Curriculum & Syllabus

Raylings covers 18 structured chapters with 81 practical exercises:

🌐 The *lings Ecosystem

If you enjoy the hands-on, terminal-driven learning loop of Raylings, explore the other interactive platforms in our *lings suite:

• ☸️ Kubelings – Master Kubernetes from scratch through interactive YAML manifests, operators, sidecars, and cluster incident drills.
• 🏗️ Terralings – Master Terraform and OpenTofu through interactive infrastructure-as-code exercises.
• 🇪🇸 Spanglings – Developer-grade CLI & interactive TUI for learning intermediate-to-advanced Spanish (B1–C1).
• ⚡ Raylings – Learn distributed AI, Ray Core actors, and scalable clusters through hands-on Python exercises.

All projects in the *lings suite are deeply inspired by the pioneering terminal-based pedagogy of Rustlings and Ziglings.

Contributing

We welcome contributions, new exercises, bug fixes, and documentation improvements! Please check out CONTRIBUTING.md for local development setup, exercise authoring standards, and test instructions.

License

Raylings is distributed under the terms of the Apache-2.0 license.