rarg-ray-patterns 0.0.1__tar.gz

rarg_ray_patterns-0.0.1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

rarg_ray_patterns-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: Continuous Integration
+
+on:
+  push: { branches: [main], tags: ["*"] }
+  pull_request:
+  schedule: [{ cron: '30 2 * * 1,4' }]  # Every Monday and Thursday @ 2h30am UTC
+
+jobs:
+  test:
+    uses: ratt-ru/rarg-gh-workflows/.github/workflows/python-ci.yml@main
+    with:
+      os-matrix: '["ubuntu-24.04"]'  # Add other OS (macos-15) if necessary
+      install-command: 'pip install --group test .'
+
+  deploy:
+    needs: ["test"]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rarg-ray-patterns
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/setup-python@v6
+        with: { python-version: '3.13' }
+      - uses: actions/checkout@v6
+      - run: pip install -U pip build && python -m build --sdist --wheel
+      - name: Publish distribution 📦 to PyPI
+        if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1

rarg_ray_patterns-0.0.1/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

rarg_ray_patterns-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+# Run `pre-commit autoupdate` after scaffolding to pin current hook revs.
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.3
+    hooks:
+    -   id: ruff
+        # Handle imports, see
+        # https://github.com/astral-sh/ruff/issues/8232
+        # https://github.com/astral-sh/ruff/issues/10882
+        args: [ --fix, --extend-select, I ]
+    -   id: ruff-format
+        name: ruff format
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+    -   id: mypy
+        name: mypy
+        additional_dependencies: [pytest, ray]

rarg_ray_patterns-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Rhodes University Centre for Radio Astronomy Techniques & Technologies (RATT)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rarg_ray_patterns-0.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: rarg-ray-patterns
+Version: 0.0.1
+Summary: Common Ray distributed computing patterns for RARG codebases
+Project-URL: Homepage, https://github.com/ratt-ru/rarg-ray-patterns
+Project-URL: Repository, https://github.com/ratt-ru/rarg-ray-patterns
+Author-email: Simon Perkins <simon.perkins@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: ray>=2.55.1
+Description-Content-Type: text/markdown
+
+# rarg-ray-patterns
+
+Common Ray distributed computing patterns for RARG codebases
+
+## Development
+This package is managed with [uv](https://docs.astral.sh/uv/).
+
+- Install: `uv sync`
+- Test: `uv run --group test pytest tests/`
+- Pre-commit hooks gate commits: `uv run --group dev pre-commit run -a`
+- Versioning is via `tbump` — never hand-edit version strings.

rarg_ray_patterns-0.0.1/README.md

@@ -0,0 +1,11 @@
+# rarg-ray-patterns
+
+Common Ray distributed computing patterns for RARG codebases
+
+## Development
+This package is managed with [uv](https://docs.astral.sh/uv/).
+
+- Install: `uv sync`
+- Test: `uv run --group test pytest tests/`
+- Pre-commit hooks gate commits: `uv run --group dev pre-commit run -a`
+- Versioning is via `tbump` — never hand-edit version strings.

rarg_ray_patterns-0.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rarg-ray-patterns"
+version = "0.0.1"
+description = "Common Ray distributed computing patterns for RARG codebases"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+authors = [{ name = "Simon Perkins", email = "simon.perkins@gmail.com" }]
+dependencies = [
+    "ray>=2.55.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ratt-ru/rarg-ray-patterns"
+Repository = "https://github.com/ratt-ru/rarg-ray-patterns"
+
+[dependency-groups]
+# ray[default] pulls in the dashboard / state-API server that the tests use to
+# query scheduled actors via ray.util.state.
+test = ["pytest", "ray[default]"]
+dev = ["pre-commit", "mypy", "ruff", "tbump"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rarg_ray_patterns"]
+
+[tool.ruff]
+line-length = 88
+indent-width = 2
+
+[tool.ruff.lint]
+extend-select = ["I"]  # import sorting
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.tbump.version]
+current = "0.0.1"
+# https://semver.org/#spec-item-9
+regex = '''(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)-?(?P<ptype>(alpha|beta|rc)\.(?P<prerelease>\d+))?'''
+
+[tool.tbump.git]
+message_template = "Bump to {new_version}"
+tag_template = "{new_version}"
+
+[[tool.tbump.file]]
+src = "pyproject.toml"
+search = 'version = "{current_version}"'
+
+[[tool.tbump.file]]
+src = "src/rarg_ray_patterns/__init__.py"
+search = '__version__ = "{current_version}"'

rarg_ray_patterns-0.0.1/src/rarg_ray_patterns/__init__.py

@@ -0,0 +1,3 @@
+"""Common Ray distributed computing patterns for RARG codebases"""
+
+__version__ = "0.0.1"

rarg_ray_patterns-0.0.1/src/rarg_ray_patterns/autoscaling.py

@@ -0,0 +1,203 @@
+import asyncio
+import time
+from typing import Any
+
+import ray
+from ray.util.scheduling_strategies import NodeAffinitySchedulingStrategy
+
+from rarg_ray_patterns.utils import wrap_future
+
+KEEPALIVE_DURATION = 60.0
+
+# Sentinel distinguishing "head node id not yet looked up" from "no head found".
+_UNSET = object()
+
+
+@ray.remote
+class MonitorActor:
+  async def heartbeat(self) -> None:
+    """Block forever; the awaiter sees RayActorError when the actor dies."""
+    await asyncio.Event().wait()
+
+
+@ray.remote
+def keep_alive(timeout: float) -> None:
+  """Sleep for timeout in order to keep the worker (and node) alive"""
+  time.sleep(timeout)
+
+
+@ray.remote(num_cpus=0, num_returns=2)
+def discover_node() -> tuple[Any, Any]:
+  """Return this node's id and a keep-alive ref pinned to the same node.
+
+  The keep-alive task takes 1 CPU on *this* node specifically (via
+  NodeAffinity), so the autoscaler will not reap the node before the caller
+  has a chance to schedule a long-lived actor on it.
+  """
+  node_id = ray.get_runtime_context().get_node_id()
+  keepalive_ref = keep_alive.options(
+    num_cpus=1,
+    scheduling_strategy=NodeAffinitySchedulingStrategy(node_id, soft=False),
+  ).remote(KEEPALIVE_DURATION)
+  return node_id, keepalive_ref
+
+
+class ActorAutoscaler:
+  def __init__(
+    self, nworkers: int = 10, batch_size: int = 2, install_on_head: bool = False
+  ):
+    self._nworkers: int = nworkers
+    self._batch_size: int = batch_size
+    self._install_on_head: bool = install_on_head
+    # Resolved lazily on first autoscale(); cached because the head node id is
+    # stable for the cluster's lifetime. _UNSET until looked up.
+    self._head_node_id: Any = _UNSET
+    self._workers: dict[str, ray.actor.ActorHandle[Any]] = {}
+    # node-id future -> (node-id ObjectRef, keepalive ObjectRef)
+    self._pending: dict[
+      asyncio.Future[Any], tuple[ray.ObjectRef[Any], ray.ObjectRef[Any]]
+    ] = {}
+    # heartbeat futures held to keep them from being GC'd
+    self._heartbeats: set[asyncio.Future[Any]] = set()
+    self._closed: bool = False
+
+  async def close(self) -> None:
+    self._closed = True
+
+    # Cancel pending discovery tasks; collect their futures so we can drain
+    # them below. Without that drain, asyncio warns "Future exception was
+    # never retrieved" when the TaskCancelledError-bearing futures are GC'd.
+    pending_futures = list(self._pending.keys())
+    for node_ref, keepalive_ref in self._pending.values():
+      ray.cancel(node_ref, force=True)
+      ray.cancel(keepalive_ref, force=True)
+    self._pending.clear()
+
+    # Kill monitor actors. Their heartbeat futures will then resolve with
+    # RayActorError; same drain rule applies.
+    heartbeats = list(self._heartbeats)
+    self._heartbeats.clear()
+    for worker in self._workers.values():
+      ray.kill(worker)
+    self._workers.clear()
+
+    if pending_futures or heartbeats:
+      await asyncio.gather(*pending_futures, *heartbeats, return_exceptions=True)
+
+  def _resolve_head_node_id(self) -> str | None:
+    """Return the head node's id (cached), or None if no head node is found.
+
+    The head node is the live node carrying Ray's auto-resource
+    ``node:__internal_head__``.
+    """
+    if self._head_node_id is _UNSET:
+      self._head_node_id = next(
+        (
+          n["NodeID"]
+          for n in ray.nodes()  # type: ignore[no-untyped-call]
+          if n.get("Alive") and "node:__internal_head__" in n.get("Resources", {})
+        ),
+        None,
+      )
+    return self._head_node_id  # type: ignore[no-any-return]
+
+  async def autoscale(self, timeout: float = 1.0) -> None:
+    # Drain completed discoveries first so capacity decisions reflect them.
+    if self._pending:
+      ready, _ = await asyncio.wait(
+        self._pending.keys(),
+        return_when="ALL_COMPLETED",
+        timeout=timeout,
+      )
+      self._handle_ready(ready)
+
+    # If we hit capacity (e.g. nworkers shrunk, or a burst overshot),
+    # cancel surplus pending work instead of letting it leak extra nodes.
+    if len(self._workers) >= self._nworkers:
+      for node_ref, keepalive_ref in self._pending.values():
+        ray.cancel(node_ref, force=True)
+        ray.cancel(keepalive_ref, force=True)
+      self._pending.clear()
+      print(f"Autoscaler at capacity: {list(self._workers)}")
+      return
+
+    shortfall = self._nworkers - len(self._workers) - len(self._pending)
+    requested = min(shortfall, self._batch_size)
+    if requested <= 0:
+      return
+
+    # Keep discovery off already-monitored nodes and, unless explicitly enabled,
+    # off the head node too.
+    excluded = set(self._workers)
+    if not self._install_on_head:
+      if (head := self._resolve_head_node_id()) is not None:
+        excluded.add(head)
+
+    options: dict[str, Any] = {"num_cpus": 0, "scheduling_strategy": "SPREAD"}
+    if excluded:
+      options["label_selector"] = {"ray.io/node-id": f"!in({','.join(excluded)})"}
+
+    print(f"Requesting {requested} nodes")
+    for _ in range(requested):
+      # num_returns=2 makes .remote() yield a 2-tuple of ObjectRefs, but the
+      # type stubs only describe the single-return case.
+      node_ref, keepalive_ref = discover_node.options(**options).remote()  # type: ignore[misc]
+      future = wrap_future(node_ref)
+      self._pending[future] = (node_ref, keepalive_ref)
+
+  def _handle_ready(self, ready: set[asyncio.Future[Any]]) -> None:
+    new_nodes = []
+    for future in ready:
+      _, keepalive_ref = self._pending.pop(future)
+
+      if future.cancelled():
+        ray.cancel(keepalive_ref, force=True)
+        continue
+
+      if exc := future.exception():
+        print(f"node discovery failed: {exc!r}")
+        ray.cancel(keepalive_ref, force=True)
+        continue
+
+      node_id = future.result()
+      if node_id in self._workers:
+        # Already monitored; release the keepalive so the node can return
+        # to its existing actor's exclusive use.
+        ray.cancel(keepalive_ref, force=True)
+        continue
+
+      if not self._install_on_head and node_id == self._resolve_head_node_id():
+        # Discovery raced ahead of head-node resolution and landed on the head
+        # node; drop it and release the keepalive.
+        ray.cancel(keepalive_ref, force=True)
+        continue
+
+      # Pin a long-lived monitor actor to this node. num_cpus=1 makes it the
+      # node's permanent CPU consumer so the autoscaler keeps the node alive.
+      monitor = MonitorActor.options(  # type: ignore[attr-defined]
+        num_cpus=0,
+        label_selector={"ray.io/node-id": node_id},
+      ).remote()
+      self._workers[node_id] = monitor
+      new_nodes.append(node_id)
+
+      # Free the CPU so the queued actor can claim it. The autoscaler treats
+      # the queued actor as resource demand and will not reap the node.
+      ray.cancel(keepalive_ref, force=True)
+
+      # Watch for actor death so we'll reprovision next iteration.
+      heartbeat = wrap_future(monitor.heartbeat.remote())
+      self._heartbeats.add(heartbeat)
+      heartbeat.add_done_callback(self._heartbeats.discard)
+      heartbeat.add_done_callback(lambda f, nid=node_id: self._on_actor_dead(nid, f))  # type: ignore[misc]
+
+    if new_nodes:
+      print(f"Procured {len(new_nodes)} nodes: {new_nodes}")
+
+  def _on_actor_dead(self, node_id: str, future: asyncio.Future[Any]) -> None:
+    # Always retrieve the exception so asyncio doesn't warn about it.
+    exc = None if future.cancelled() else future.exception()
+    if self._closed:
+      return
+    print(f"Worker on {node_id} died ({exc!r}); will reprovision")
+    self._workers.pop(node_id, None)

rarg_ray_patterns-0.0.1/src/rarg_ray_patterns/utils.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+  import ray
+
+
+def wrap_future(obj_ref: ray.ObjectRef[Any]) -> asyncio.Future[Any]:
+  """Wrap a ray ObjectReference as an asyncio Future"""
+  return asyncio.wrap_future(obj_ref.future())

rarg_ray_patterns-0.0.1/tests/conftest.py

@@ -0,0 +1,27 @@
+# Shared fixtures live here. Prefer fixtures over setup/teardown; keep tests
+# deterministic (see the shared Python conventions).
+
+import os
+import os.path
+from urllib.request import urlretrieve
+
+import pytest
+import ray
+
+RAY_GITHUB_REPO = "https://raw.githubusercontent.com/ray-project/ray"
+GITHUB_CONFIG_PATH = "python/ray/autoscaler/_private/fake_multi_node/example.yaml"
+LOCAL_CONFIG_PATH = "autoscaler/_private/fake_multi_node/example.yaml"
+
+
+@pytest.fixture(scope="session", autouse=True)
+def install_example_yaml() -> None:
+  """Install the example config needed by AutoscalingCluster.
+
+  Pinned to the installed Ray version so the YAML schema can't drift away
+  from what the local Ray expects.
+  """
+  url = f"{RAY_GITHUB_REPO}/refs/tags/ray-{ray.__version__}/{GITHUB_CONFIG_PATH}"
+  file_path = os.path.join(os.path.dirname(ray.__file__), LOCAL_CONFIG_PATH)
+  if not os.path.exists(file_path):
+    os.makedirs(os.path.dirname(file_path), exist_ok=True)
+    urlretrieve(url, file_path)

rarg_ray_patterns-0.0.1/tests/test_autoscaling.py

@@ -0,0 +1,163 @@
+import asyncio
+import copy
+import time
+import typing
+
+import pytest
+import ray
+from ray.cluster_utils import AutoscalingCluster
+from ray.util.state import list_actors
+from ray.util.state.common import ActorState
+
+from rarg_ray_patterns.autoscaling import ActorAutoscaler
+
+# Maximum number of cpu_node workers the cluster will provision. The autoscaler
+# pins one MonitorActor per node, so this also caps how many actors can be
+# scheduled regardless of how many workers are requested. Shared with the tests.
+NODE_CAP = 20
+
+# How long to wait for the cluster to provision nodes and converge. Bringing the
+# fake multi-node cluster up to full capacity (NODE_CAP node processes) is slow,
+# so give the convergence-to-capacity case generous headroom.
+CONVERGE_TIMEOUT = 240.0
+POLL_INTERVAL = 3.0
+# A second sample window used to confirm the converged count is stable and
+# doesn't overshoot the requested worker count.
+STABILITY_WINDOW = 6.0
+
+AUTOSCALING_CLUSTER_CONFIG = {
+  "head_resources": {"CPU": 0},
+  "worker_node_types": {
+    "cpu_node": {
+      "resources": {
+        "CPU": 1,
+        "object_store_memory": 100 * 1024 * 1024,
+      },
+      "node_config": {},
+      "min_workers": 0,
+      "max_workers": NODE_CAP,
+    },
+  },
+  "min_workers": 0,
+  "max_workers": NODE_CAP * 5,
+  "autoscaler_v2": True,
+}
+
+
+@ray.remote
+class Scheduler:
+  def __init__(
+    self, nworkers: int = 10, batch_size: int = 2, install_on_head: bool = False
+  ):
+    self._autoscaler = ActorAutoscaler(nworkers, batch_size, install_on_head)
+    self._event = asyncio.Event()
+
+  async def run(self) -> None:
+    try:
+      while not self._event.is_set():
+        await asyncio.sleep(1.0)
+        await self._autoscaler.autoscale()
+    finally:
+      await self._autoscaler.close()
+
+  async def stop(self) -> None:
+    self._event.set()
+
+
+def _alive_monitors() -> list[ActorState]:
+  """Return the live MonitorActor entries currently scheduled on the cluster."""
+  # list_actors is typed as returning Any; pin the element type here.
+  actors: list[ActorState] = list_actors(
+    filters=[
+      ("class_name", "=", "MonitorActor"),
+      ("state", "=", "ALIVE"),
+    ],
+    detail=True,
+  )
+  return actors
+
+
+def _head_node_id() -> str:
+  """Return the cluster's head node id (the node with node:__internal_head__)."""
+  return typing.cast(
+    str,
+    next(
+      n["NodeID"]
+      for n in ray.nodes()  # type: ignore[no-untyped-call]
+      if n.get("Alive") and "node:__internal_head__" in n.get("Resources", {})
+    ),
+  )
+
+
+# The cheap nworkers=8 cases stay below the node ceiling and exercise the
+# install_on_head flag in both states (head excluded vs. monitored). The single
+# nworkers=100 case exercises convergence to the cluster's node capacity; it is
+# slow, so we run it once with the default (head excluded) rather than for both
+# flag values, since the flag behaviour is already covered by the nworkers=8 pair.
+@pytest.mark.filterwarnings("ignore::FutureWarning")
+@pytest.mark.parametrize(
+  "nworkers, batch_size, install_on_head", [(8, 2, False), (8, 2, True), (10, 2, False)]
+)
+def test_actor_autoscaling(
+  nworkers: int,
+  batch_size: int,
+  install_on_head: bool,
+) -> None:
+  schedulable = NODE_CAP + 1 if install_on_head else NODE_CAP
+  expected = min(nworkers, schedulable)
+
+  cfg = typing.cast(dict[str, typing.Any], copy.deepcopy(AUTOSCALING_CLUSTER_CONFIG))
+  cfg["worker_node_types"]["cpu_node"]["max_workers"] = schedulable
+  cfg["max_workers"] = schedulable * 5
+  with pytest.warns(ResourceWarning, match="unclosed file"):
+    cluster = AutoscalingCluster(**cfg)
+
+  try:
+    cluster.start()
+    ray.init("auto", runtime_env={"excludes": ".*"})
+    scheduler = Scheduler.options(num_cpus=0).remote(  # type: ignore[attr-defined]
+      nworkers, batch_size, install_on_head
+    )
+    run_future = scheduler.run.remote()
+
+    # Poll until the cluster has scheduled the expected number of monitor
+    # actors, rather than waiting a fixed (and flaky) duration.
+    deadline = time.monotonic() + CONVERGE_TIMEOUT
+    monitors = _alive_monitors()
+    while len(monitors) < expected and time.monotonic() < deadline:
+      time.sleep(POLL_INTERVAL)
+      monitors = _alive_monitors()
+
+    assert len(monitors) == expected, (
+      f"expected {expected} MonitorActors scheduled, "
+      f"saw {len(monitors)} after {CONVERGE_TIMEOUT}s"
+    )
+
+    # Each actor must be pinned to a distinct node (one monitor per node).
+    node_ids = {m.node_id for m in monitors}
+    assert len(node_ids) == expected, (
+      f"expected actors on {expected} distinct nodes, saw {len(node_ids)}"
+    )
+
+    # The head node is monitored only when install_on_head is set.
+    head_node_id = _head_node_id()
+    if install_on_head:
+      assert head_node_id in node_ids, "expected a monitor on the head node"
+    else:
+      assert head_node_id not in node_ids, "head node should not be monitored"
+
+    # The converged count must be stable and must never overshoot the
+    # requested worker count.
+    time.sleep(STABILITY_WINDOW)
+    monitors = _alive_monitors()
+    assert len(monitors) == expected, (
+      f"actor count drifted to {len(monitors)} after convergence"
+    )
+    assert len(monitors) <= nworkers
+
+    ray.get(scheduler.stop.remote())
+    # Surface any error from the run loop.
+    ray.get(run_future)
+  finally:
+    ray.shutdown()
+    cluster.shutdown()  # type: ignore[no-untyped-call]

rarg_ray_patterns-0.0.1/tests/test_smoke.py

@@ -0,0 +1,5 @@
+import rarg_ray_patterns
+
+
+def test_package_exposes_version() -> None:
+  assert rarg_ray_patterns.__version__