raylings 0.1.0__py3-none-any.whl

raylings/__init__.py

@@ -0,0 +1,3 @@
+"""Raylings package initialization."""
+
+__version__ = "0.1.0"

raylings/cli.py

@@ -0,0 +1,331 @@
+"""Command-line interface entrypoint for the Raylings learning framework."""
+
+from pathlib import Path
+
+from rich.table import Table
+import typer
+
+from raylings import __version__
+from raylings.daemon import RayDaemon
+from raylings.manifest import get_exercise_by_name, get_manifest
+from raylings.models import Exercise
+from raylings.runner import ExerciseRunner
+from raylings.ui import (
+    console,
+    render_banner,
+    render_cluster_status,
+    render_hint,
+    render_progress,
+    render_result,
+)
+from raylings.watcher import ExerciseWatcher
+
+app = typer.Typer(
+    name="raylings",
+    help="Interactive Ray learning CLI inspired by Rustlings.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Callback for --version CLI option."""
+    if value:
+        render_banner()
+        console.print(
+            f"[bold cyan]raylings[/bold cyan] version [bold green]{__version__}[/bold green]\n"
+        )
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show raylings version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Raylings CLI main entrypoint callback."""
+
+
+@app.command(name="version")
+def version_command() -> None:
+    """Display raylings branding banner and current version."""
+    render_banner()
+    console.print(
+        f"[bold cyan]raylings[/bold cyan] version [bold green]{__version__}[/bold green]\n"
+    )
+
+
+@app.command(name="init")
+def init_command(
+    target_dir: Path = typer.Option(
+        Path("."),
+        "--directory",
+        "-d",
+        help="Target directory to initialize raylings exercises in (defaults to current working directory)",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing exercise files if they already exist",
+    ),
+) -> None:
+    """Initialize a fresh Raylings workspace by extracting bundled exercises."""
+    import importlib.resources
+    import shutil
+
+    render_banner()
+    exercises_dest = target_dir / "exercises"
+
+    if exercises_dest.exists() and not force:
+        console.print(
+            f"[bold yellow]Directory '{exercises_dest}' already exists.[/bold yellow]\n"
+            "Use [bold cyan]raylings init --force[/bold cyan] to overwrite, or run [bold green]raylings watch[/bold green] to continue learning."
+        )
+        raise typer.Exit(0)
+
+    try:
+        bundled_pkg = importlib.resources.files("raylings")
+        bundled_exercises = bundled_pkg / "exercises"
+
+        if hasattr(bundled_exercises, "is_dir") and bundled_exercises.is_dir():
+            if exercises_dest.exists() and force:
+                shutil.rmtree(exercises_dest)
+            shutil.copytree(str(bundled_exercises), str(exercises_dest))
+        else:
+            # Fallback to local source tree if running in editable dev mode
+            repo_exercises = Path(__file__).parent.parent.parent / "exercises"
+            if repo_exercises.exists():
+                if exercises_dest.exists() and force:
+                    shutil.rmtree(exercises_dest)
+                shutil.copytree(str(repo_exercises), str(exercises_dest))
+            else:
+                console.print(
+                    "[bold red]Failed to locate bundled exercises in raylings package.[/bold red]"
+                )
+                raise typer.Exit(1)
+
+        console.print(
+            f"[bold green]✨ Raylings workspace initialized successfully in [white]{target_dir.resolve()}[/white]![/bold green]\n\n"
+            "To begin your Ray learning journey, run:\n"
+            "  [bold cyan]raylings watch[/bold cyan]\n"
+        )
+    except Exception as e:
+        console.print(f"[bold red]Error initializing workspace:[/bold red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command(name="list")
+def list_command() -> None:
+    """List all 14 curriculum chapters and exercises with status breakdown."""
+    render_banner()
+    manifest = get_manifest()
+    runner = ExerciseRunner()
+
+    completed_count = 0
+    for ex in manifest.all_exercises:
+        if ex.file_path.exists() and not runner.check_marker(ex.file_path):
+            res = runner.run_exercise(ex, timeout=10.0)
+            if res.passed:
+                completed_count += 1
+
+    render_progress(manifest, completed_count=completed_count)
+
+
+@app.command(name="run")
+def run_command(
+    exercise_name: str = typer.Argument(
+        ...,
+        help="Exercise name (e.g. basics01) or direct file path to execute",
+    ),
+    timeout: float = typer.Option(
+        30.0,
+        "--timeout",
+        "-t",
+        help="Subprocess timeout in seconds",
+    ),
+) -> None:
+    """Run an exercise or solution once and display evaluation diagnostics."""
+    ex = get_exercise_by_name(exercise_name)
+    if ex is None:
+        target_path = Path(exercise_name)
+        if target_path.exists():
+            ex = Exercise(
+                name=target_path.stem,
+                title=target_path.stem,
+                path=str(target_path),
+                chapter_name=target_path.parent.name,
+            )
+        else:
+            console.print(f"[bold red]Exercise '{exercise_name}' not found.[/bold red]")
+            raise typer.Exit(1)
+
+    runner = ExerciseRunner()
+    res = runner.run_exercise(ex, timeout=timeout)
+    render_result(res)
+    if not res.passed:
+        raise typer.Exit(1)
+
+
+@app.command(name="hint")
+def hint_command(
+    exercise_name: str = typer.Argument(
+        "",
+        help="Name of exercise (e.g. basics01). Defaults to current incomplete exercise.",
+    ),
+    level: int = typer.Option(
+        0,
+        "--level",
+        "-l",
+        help="Progressive hint level index (0-indexed)",
+    ),
+) -> None:
+    """Display progressive hints for an exercise."""
+    target_ex: Exercise | None = None
+    if not exercise_name:
+        watcher = ExerciseWatcher()
+        target_ex = watcher.find_current_exercise()
+        if target_ex is None:
+            console.print("[yellow]No incomplete exercises found in curriculum.[/yellow]")
+            raise typer.Exit(0)
+    else:
+        target_ex = get_exercise_by_name(exercise_name)
+
+    if target_ex is None:
+        console.print(f"[bold red]Exercise '{exercise_name}' not found.[/bold red]")
+        raise typer.Exit(1)
+
+    render_hint(target_ex, hint_level=level)
+
+
+@app.command(name="test")
+def test_command(
+    exercise_name: str = typer.Argument(
+        "",
+        help="Optional specific exercise name to test solution for",
+    ),
+    all_solutions: bool = typer.Option(
+        True,
+        "--all",
+        help="Execute all canonical reference solutions",
+    ),
+) -> None:
+    """Execute canonical reference solutions and verify correctness."""
+    render_banner()
+    runner = ExerciseRunner()
+    manifest = get_manifest()
+
+    if exercise_name:
+        ex = get_exercise_by_name(exercise_name)
+        if ex is None:
+            console.print(f"[bold red]Exercise '{exercise_name}' not found.[/bold red]")
+            raise typer.Exit(1)
+        res = runner.run_solution(ex)
+        render_result(res)
+        if not res.passed:
+            raise typer.Exit(1)
+        return
+
+    exercises = manifest.all_exercises
+    if not exercises:
+        console.print("[yellow]No exercises found in curriculum manifest.[/yellow]")
+        return
+
+    passed_count = 0
+    failed_count = 0
+    console.print(f"[bold cyan]Testing {len(exercises)} reference solutions...[/bold cyan]\n")
+
+    table = Table(
+        title="Solution Verification Summary",
+        border_style="dim",
+        header_style="bold magenta",
+    )
+    table.add_column("Exercise", style="bold cyan", width=16)
+    table.add_column("Solution Path", style="dim white")
+    table.add_column("Result", justify="center", width=10)
+
+    for ex in exercises:
+        res = runner.run_solution(ex)
+        if res.passed:
+            passed_count += 1
+            table.add_row(ex.name, str(ex.solution_path), "[bold green]PASS[/bold green]")
+        else:
+            failed_count += 1
+            table.add_row(ex.name, str(ex.solution_path), "[bold red]FAIL[/bold red]")
+
+    console.print(table)
+    console.print(
+        f"\n[bold]Summary:[/bold] [bold green]{passed_count} passed[/bold green], "
+        f"[bold red]{failed_count} failed[/bold red]\n"
+    )
+
+    if failed_count > 0:
+        raise typer.Exit(1)
+
+
+@app.command(name="daemon")
+def daemon_command(
+    action: str = typer.Argument(
+        "status",
+        help="Action to perform: start | stop | status | restart",
+    ),
+) -> None:
+    """Manage the background Python Ray session daemon."""
+    daemon = RayDaemon()
+    action_lower = action.lower()
+
+    if action_lower == "status":
+        info = daemon.get_cluster_info()
+        render_cluster_status(info)
+    elif action_lower == "start":
+        console.print("[cyan]Starting Ray daemon session...[/cyan]")
+        daemon.start()
+        info = daemon.get_cluster_info()
+        render_cluster_status(info)
+    elif action_lower == "stop":
+        console.print("[yellow]Stopping Ray daemon session...[/yellow]")
+        daemon.stop()
+        console.print("[green]Ray daemon stopped successfully.[/green]")
+    elif action_lower == "restart":
+        console.print("[cyan]Restarting Ray daemon session...[/cyan]")
+        daemon.stop()
+        daemon.start()
+        info = daemon.get_cluster_info()
+        render_cluster_status(info)
+    else:
+        console.print(
+            f"[bold red]Unknown daemon action: '{action}'. "
+            "Supported actions: start, stop, status, restart.[/bold red]"
+        )
+        raise typer.Exit(1)
+
+
+@app.command(name="watch")
+def watch_command(
+    ctx: typer.Context,
+    warm_daemon: bool = typer.Option(
+        True,
+        "--warm-daemon/--no-warm-daemon",
+        help="Pre-warm Ray daemon session before watching",
+    ),
+    exercise_dir: Path = typer.Option(
+        Path("exercises"),
+        "--dir",
+        "-d",
+        help="Root directory containing curriculum exercises",
+    ),
+) -> None:
+    """Interactive watcher mode: continuously monitors files and advances upon completion."""
+    daemon = RayDaemon() if warm_daemon else None
+    watcher = ExerciseWatcher(daemon=daemon)
+    watcher.watch_loop(exercise_dir=exercise_dir)
+
+
+if __name__ == "__main__":
+    app()

raylings/daemon.py

@@ -0,0 +1,112 @@
+"""Ray session daemon and lifecycle manager for interactive exercise execution."""
+
+import gc
+import logging
+from typing import Any
+
+import ray
+
+logger = logging.getLogger("raylings.daemon")
+
+
+class RayDaemon:
+    """Lifecycle manager for the background Python Ray session."""
+
+    def __init__(
+        self,
+        num_cpus: int = 2,
+        object_store_memory: int = 100 * 1024 * 1024,
+    ) -> None:
+        """Initialize RayDaemon with default cluster configuration parameters.
+
+        Args:
+            num_cpus: Default number of logical CPUs to allocate if starting a local cluster.
+            object_store_memory: Default size in bytes for the Plasma object store (100MB default).
+        """
+        self.num_cpus = num_cpus
+        self.object_store_memory = object_store_memory
+
+    def is_running(self) -> bool:
+        """Return True if Ray runtime is initialized and active."""
+        return bool(ray.is_initialized())
+
+    def start(
+        self,
+        num_cpus: int | None = None,
+        object_store_memory: int | None = None,
+    ) -> bool:
+        """Start or connect to the local Ray cluster session.
+
+        Args:
+            num_cpus: Number of CPUs to allocate (overrides instance default if provided).
+            object_store_memory: Object store memory in bytes (overrides instance default).
+
+        Returns:
+            bool: True if Ray is running and initialized.
+        """
+        cpus = num_cpus if num_cpus is not None else self.num_cpus
+        mem = object_store_memory if object_store_memory is not None else self.object_store_memory
+
+        if not ray.is_initialized():
+            logger.info("Initializing Ray daemon with %d CPUs and %d bytes object store", cpus, mem)
+            ray.init(
+                ignore_reinit_error=True,
+                num_cpus=cpus,
+                object_store_memory=mem,
+                include_dashboard=False,
+                log_to_driver=False,
+            )
+        return self.is_running()
+
+    def stop(self) -> bool:
+        """Shut down the active Ray cluster session if running.
+
+        Returns:
+            bool: True if Ray is no longer running.
+        """
+        if ray.is_initialized():
+            logger.info("Shutting down Ray daemon session")
+            ray.shutdown()
+        return not self.is_running()
+
+    def reset_state(self) -> None:
+        """Safely clean up runtime state and garbage collect between exercise runs."""
+        if ray.is_initialized():
+            gc.collect()
+
+    def get_cluster_info(self) -> dict[str, Any]:
+        """Return cluster metadata, address, node count, and resource statistics.
+
+        Returns:
+            dict containing cluster status, gcs address, node count, and resource maps.
+        """
+        if not self.is_running():
+            return {
+                "is_running": False,
+                "address": None,
+                "node_count": 0,
+                "cluster_resources": {},
+                "available_resources": {},
+            }
+
+        ctx = ray.get_runtime_context()
+        return {
+            "is_running": True,
+            "address": getattr(ctx, "gcs_address", None),
+            "node_count": len(ray.nodes()),
+            "cluster_resources": ray.cluster_resources(),
+            "available_resources": ray.available_resources(),
+        }
+
+    # Compatibility aliases
+    def ensure_started(self) -> bool:
+        """Ensure the daemon is running, starting it if necessary."""
+        return self.start()
+
+    def shutdown(self) -> bool:
+        """Alias for stop()."""
+        return self.stop()
+
+    def cleanup_session(self) -> None:
+        """Alias for reset_state()."""
+        self.reset_state()

raylings/exercises/01_basics/basics01.py

@@ -0,0 +1,48 @@
+# I AM NOT DONE
+"""Chapter 1: Ray Core Foundations - Exercise 1: Ray Init & First Remote Task.
+
+Welcome to Raylings!
+
+Ray is an open-source unified framework for scaling AI and Python applications.
+At its core, Ray turns standard Python functions into asynchronous, distributed
+tasks executed across worker processes.
+
+Key Concepts:
+1. `ray.init(ignore_reinit_error=True)`: Connects your Python script to a local
+   Ray cluster or starts one automatically if not already running.
+2. `@ray.remote`: A decorator that designates a Python function as a distributed
+   remote task.
+3. `func.remote(*args)`: Invoking a remote function returns an `ObjectRef` (a future),
+   submitting the task to the Ray scheduler without blocking.
+4. `ray.get(object_ref)`: Blocks until the task completes and retrieves the computed result.
+
+Your Task:
+- Initialize Ray using `ray.init(ignore_reinit_error=True)`.
+- Decorate the `square` function with `@ray.remote`.
+- Call `square.remote(7)` and retrieve the result using `ray.get()`.
+"""
+
+import ray
+
+
+# TODO: Decorate this function with @ray.remote
+def square(x: int) -> int:
+    return x * x
+
+
+def verify() -> None:
+    # TODO: Initialize Ray
+    # ray.init(ignore_reinit_error=True)
+
+    # TODO: Invoke the remote task and get the ObjectRef
+    # result_ref = square.remote(7)
+    # result = ray.get(result_ref)
+    result = None
+
+    assert ray.is_initialized(), "Ray should be initialized"
+    assert result == 49, f"Expected 49, but got {result}"
+    print("✓ basics01 verified: Ray initialized and remote task executed successfully!")
+
+
+if __name__ == "__main__":
+    verify()

raylings/exercises/01_basics/basics02.py

@@ -0,0 +1,49 @@
+# I AM NOT DONE
+"""Chapter 1: Ray Core Foundations - Exercise 2: ObjectRefs and ray.get().
+
+In Ray, calling a remote function does NOT return the computed value directly.
+Instead, it immediately returns an `ObjectRef`—a lightweight identifier representing
+a future value that will be computed asynchronously on a cluster worker.
+
+Key Concepts:
+1. `ObjectRef`: A 28-byte unique identifier representing an object residing in Ray's
+   distributed object store.
+2. `ray.get(object_ref)`: Blocks until the object is available and deserializes it.
+3. Batch `ray.get([ref1, ref2, ...])`: Ray can wait on and retrieve an entire list of
+   `ObjectRef`s in parallel with a single call, which is much more efficient than calling
+   `ray.get()` one by one.
+
+Your Task:
+- Define a remote function `multiply(a: int, b: int) -> int`.
+- Launch 5 parallel tasks calculating `i * 10` for `i` in `range(5)`.
+- Store the list of `ObjectRef`s.
+- Retrieve all 5 results in a single `ray.get(refs)` call.
+"""
+
+import ray
+from ray import ObjectRef
+
+
+# TODO: Define a remote function named `multiply` that takes two integers and returns their product.
+def multiply(a: int, b: int) -> int:
+    return a * b
+
+
+def verify() -> None:
+    ray.init(ignore_reinit_error=True)
+
+    # TODO: Launch 5 remote tasks to compute [0*10, 1*10, 2*10, 3*10, 4*10]
+    # and collect their ObjectRefs in `refs`.
+    refs: list[ObjectRef] = []
+
+    # TODO: Use a single ray.get() call to retrieve all results into `results`.
+    results: list[int] = []
+
+    expected = [0, 10, 20, 30, 40]
+    assert len(refs) == 5, f"Expected 5 ObjectRefs, got {len(refs)}"
+    assert results == expected, f"Expected {expected}, but got {results}"
+    print("✓ basics02 verified: ObjectRefs collected and fetched in batch successfully!")
+
+
+if __name__ == "__main__":
+    verify()

raylings/exercises/01_basics/basics03.py

@@ -0,0 +1,86 @@
+# I AM NOT DONE
+"""Chapter 1: Ray Core Foundations - Exercise 3: Parallel Pipeline Execution.
+
+A very common mistake when learning Ray is calling `ray.get()` immediately after
+launching each remote task inside a loop:
+
+    # ❌ ANTI-PATTERN (Sequential Execution):
+    results = []
+    for x in data:
+        ref = slow_task.remote(x)
+        results.append(ray.get(ref))  # Blocks immediately! No parallelism!
+
+Calling `ray.get()` blocks the driver until that single task finishes, forcing tasks
+to run sequentially one after another.
+
+    # ✓ PROPER PATTERN (Parallel Execution):
+    refs = [slow_task.remote(x) for x in data]  # Launch all tasks concurrently
+    results = ray.get(refs)                     # Wait for all tasks in parallel
+
+Key Concepts:
+1. Ray tasks run asynchronously in background workers as soon as `.remote()` is called.
+2. Collecting `ObjectRef`s allows the Ray scheduler to distribute work concurrently
+   across available CPU cores.
+
+Your Task:
+- Refactor the sequential loop in `run_parallel()` to launch all 4 tasks concurrently.
+- Fetch all results with a single `ray.get(refs)` call.
+- The total parallel execution time must be significantly less than sequential time!
+"""
+
+import time
+import ray
+
+
+@ray.remote
+def simulate_work(duration: float, task_id: int) -> int:
+    time.sleep(duration)
+    return task_id * 2
+
+
+def run_sequential(durations: list[float]) -> tuple[list[int], float]:
+    """Runs tasks sequentially by calling ray.get() inside the loop."""
+    start = time.perf_counter()
+    results = []
+    for i, d in enumerate(durations):
+        ref = simulate_work.remote(d, i)
+        results.append(ray.get(ref))  # Serialized!
+    elapsed = time.perf_counter() - start
+    return results, elapsed
+
+
+def run_parallel(durations: list[float]) -> tuple[list[int], float]:
+    """TODO: Fix this function to run all tasks concurrently in parallel."""
+    start = time.perf_counter()
+
+    # TODO: 1. Launch all simulate_work.remote(d, i) tasks into a list of ObjectRefs
+    # TODO: 2. Call ray.get() on the list of ObjectRefs once
+    results: list[int] = []
+
+    elapsed = time.perf_counter() - start
+    return results, elapsed
+
+
+def verify() -> None:
+    ray.init(ignore_reinit_error=True)
+
+    durations = [0.08, 0.08, 0.08, 0.08]
+
+    seq_results, seq_time = run_sequential(durations)
+    par_results, par_time = run_parallel(durations)
+
+    expected = [0, 2, 4, 6]
+    assert seq_results == expected
+    assert par_results == expected, f"Expected {expected}, got {par_results}"
+
+    # Parallel time should be significantly faster than sequential time
+    # Sequential ~ 0.32s; Parallel ~ 0.08s - 0.18s
+    print(f"Sequential time: {seq_time:.3f}s | Parallel time: {par_time:.3f}s")
+    assert par_time < seq_time * 0.75, (
+        f"Parallel execution ({par_time:.3f}s) was not significantly faster than sequential ({seq_time:.3f}s)"
+    )
+    print("✓ basics03 verified: Parallel task execution pipeline confirmed!")
+
+
+if __name__ == "__main__":
+    verify()