Raylings ⚡

An interactive, hands-on CLI learning environment for mastering Python Ray from scratch.

Inspired by the pedagogy of Rustlings and Ziglings, Raylings guides you through progressively challenging distributed computing exercises in Python. You will fix broken code, fill in missing distributed patterns, resolve performance bottlenecks, eliminate memory leaks, and build real-world distributed systems.

📚 Full Documentation Site: https://dnf0.github.io/raylings/
👉 New to Raylings? Read the Interactive Onboarding Guide for a deep dive into setup, preflight diagnostics, the tour engine, keyboard shortcuts, and troubleshooting.

What is Raylings?

Ray is a unified framework for scaling AI and Python applications from single laptops to massive multi-node clusters. While powerful, mastering Ray's mental models—futures, stateful actors, Plasma zero-copy memory, dynamic placement groups, and lineage-based fault tolerance—requires hands-on practice.

Raylings provides:

• Interactive Full-Screen TUI (raylings tui): Rich split-pane terminal UI with a live curriculum tree, syntax-highlighted code preview, hotkey execution ([r]), progressive hints ([h]), and telemetry overlays ([t]).
• Cluster Health & Telemetry Inspector (raylings top / raylings metrics): Real-time live dashboard monitoring Plasma object store memory, disk spill rates, node CPU/GPU saturation, and active actor tables.
• Exercise Scaffolding CLI (raylings new / raylings new-exercise): One-command generator creating boilerplate exercises, reference solutions, validation harnesses, and manifest registration snippets.
• Preflight Diagnostics (raylings doctor): Built-in environment & hardware diagnostics checking Python 3.10+, Ray installation, CPU/RAM capacity, and cluster health.
• Interactive Tour (raylings tour): 5-step interactive curriculum tour explaining distributed primitives, exercise workflow, and developer shortcuts.
• Interactive File Watcher (raylings watch): Edit exercises in your favorite editor; Raylings automatically re-runs and validates your changes on save.
• Sub-50ms Execution: Background Ray daemon re-uses a warm local cluster session for rapid turnaround.
• Multi-Node Kubernetes & KubeRay (scripts/kuberay/): Ephemeral 3-node KinD cluster harness and end-to-end integration test suite for testing Ray clusters, remote Ray client execution, and DDP training on real Kubernetes topology.
• 14 Chapters & 66 Exercises: From first remote tasks to distributed parameter servers, PyTorch DDP pipelines, Ray Serve DAGs, and KubeRay on Kubernetes.
• Progressive Hints & Solutions: Stuck on an exercise? Get layered hints without spoiling the answer, or inspect canonical solutions when finished.
• First-Class VS Code Extension: Dedicated sidebar tree view, status bar progress, on-save auto-evaluations, and built-in interactive walkthroughs.

Quickstart

Prerequisites

• Python 3.10, 3.11, or 3.12
• uv (recommended) or pipx / pip

1. Instant Run with uvx (No installation needed)

Initialize a workspace in any directory, run diagnostics, take the tour, and jump right in:

uvx raylings init
uvx raylings doctor
uvx raylings tour
uvx raylings tui       # Or launch watcher: uvx raylings watch

2. Standard Installation

Install globally or in your virtual environment:

pip install raylings
raylings init
raylings doctor
raylings tour
raylings tui           # Or launch watcher: raylings watch

3. From Source

Clone the repository and install in editable mode:

git clone https://github.com/dnf0/raylings.git
cd raylings
pip install -e ".[dev]"
raylings doctor
raylings tour
raylings tui

Interactive Learning Workflow

Raylings offers two ways to learn: the Full-Screen Split-Pane TUI and the Live Background Watcher.

1. Interactive Full-Screen TUI (raylings tui)

Launch the split-pane terminal interface to browse the entire curriculum, preview code with line numbers, run exercises, and reveal progressive hints with single keystrokes:

raylings tui

2. Live Background Watcher (raylings watch)

Prefer using your favorite code editor (VS Code, Cursor, Neovim)? Start the continuous background watcher:

1. Run 'raylings watch' in a terminal.
2. Open exercises/01_basics/basics01.py in your code editor.
3. Read the instructions, implement the Ray distributed calls, and remove '# I AM NOT DONE'.
4. Save the file. Raylings immediately tests your changes and advances to the next exercise.

3. Cluster Health & Telemetry Inspector (raylings top)

Inspect your local Ray cluster's live Plasma memory allocations, object spill rates, CPU/GPU core usage, and instantiated actor states:

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

4. Authoring New Exercises (raylings new)

Contribute new exercises to the Raylings curriculum with the built-in scaffolder:

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

Key CLI Commands

• raylings tui — Launch interactive full-screen split-pane TUI (-e, --non-interactive).
• raylings top / raylings metrics — Live cluster telemetry, memory inspector, and actor monitor (-i, --once, --json).
• raylings new / raylings new-exercise — Scaffold new exercise and solution templates (-t, -d, --dry-run, --json).
• raylings watch — Start continuous watching mode with keyboard shortcuts (n, p, r, h, q).
• raylings doctor — Run preflight system, Python, and Ray environment diagnostics.
• raylings tour — Launch the 5-step interactive onboarding tour (--step, -y, --json).
• raylings init — Extract bundled exercises into the current directory.
• raylings run <exercise_name> — Run and verify a specific exercise.
• raylings test — Run automated verification across all canonical reference solutions.
• raylings hint <exercise_name> — Show progressive hints for an exercise (--level).
• raylings list — View all chapters, exercises, and completion progress.
• raylings progress — Display progress summary and next recommended exercise.
• raylings daemon [status|start|stop|restart] — Manage the warm background Ray cluster session.

VS Code & IDE Integration

Raylings provides a first-class extension for VS Code and Cursor (editors/vscode):

• Welcome Walkthrough: Interactive onboarding via Help > Welcome > Walkthroughs > Welcome to Raylings.
• Exercise Explorer: Browse chapters and exercises with status badges in the Activity Bar.
• Auto-run on Save: Automatically evaluates exercises on file save.
• Status Bar: Live progress tracking and active exercise display.

Cloud & KubeRay Multi-Node Testing

Raylings provides automated scripts and test harnesses to deploy ephemeral multi-node Ray clusters on Kubernetes using KinD and the KubeRay Operator:

# 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

See the Cloud & KubeRay Guide for architecture diagrams, Helm configuration, and CI workflows.

Curriculum Map

Raylings covers 14 comprehensive chapters spanning core foundations to production ML engineering:

Documentation

The full documentation is available at https://dnf0.github.io/raylings/.

• 🚀 Getting Started — Prerequisites, installation methods (uv tool, pipx, editable), and first 5 minutes.
• 🧭 Interactive Onboarding Guide — Guided tour, doctor diagnostics, and VS Code integration.
• 📚 Curriculum Syllabus — Complete 14-chapter map covering all 66 exercises.
• ⌨️ CLI Reference Manual — Comprehensive reference for all CLI subcommands and JSON outputs.
• 🛠️ Troubleshooting Recipes — Diagnostic recipes for port conflicts, memory spilling, and DDP deadlocks.
• ☸️ Cloud & KubeRay Deployment — KinD multi-node clusters, KubeRay operator, remote execution, and E2E test suite.
• 🤝 Contributing Guide — Exercise authoring standards, test suites, and contribution workflow.

License

This project is licensed under the Apache License, Version 2.0.