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:

• 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.
• 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 watch

2. Standard Installation

Install globally or in your virtual environment:

pip install raylings
raylings init
raylings doctor
raylings tour
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 watch

Interactive Learning Workflow

Raylings starts on the first exercise in exercises/01_basics/basics01.py.

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

Key CLI Commands

• 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 watch — Start continuous watching mode with keyboard shortcuts (n, p, r, h, q).
• 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.

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.
• 🤝 Contributing Guide — Exercise authoring standards, test suites, and contribution workflow.

License

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