[core|serve] Migrate shared utilities from `ray._private` to `ray._common`

[abrarsheikh]

We’re migrating internal utilities currently housed in ray._private to a new location: ray._common.

Purpose

The goal is to isolate reusable utilities shared across Ray Core and native libraries in a central, semantically correct location.

The new _common directory acts as a developer API:

• ✅ Safe for use across libraries within the Ray repo (Serve, Train, Data, etc.).
• ❌ Not meant for public use or for external OSS dependencies.

This migration will help reduce accidental coupling to ray._private, which is intended for Ray Core internals only.

What You Can Help With

We’ve compiled a list of functions and classes that are:

• Frequently used across libraries and tests
• Currently located in ray._private
• Good candidates to move to ray._common

Each function can be migrated independently, so feel free to pick one and open a PR!

How to Contribute

1. Choose a function or class from the list below and claim it by leaving a comment.
2. Move it to an appropriate file inside ray/_common/.
3. Update all import paths and usage sites.
4. Ensure all tests pass
5. Submit a PR titled [core] Migrate <function/class> from _private to _common

Sample PRs for referance

1. move signal and semaphore to _common/ #53457
2. [core] Mask serve directory for core tests #50609

Need Help?

If you’re unsure where a function should go or run into test failures:

• Comment below on this issue.
• Ask in Ray Slack

Let’s Go!

• Pick a function, comment here to "claim" it, and open a PR when you're ready. Thank you for helping improve Ray’s internal architecture! 💛

ray._private.worker

Function/Class	Usage Count	All Call Sites
global_worker	4	1. ray._private.worker.global_worker._filter_logs_by_job = False 2. ray._private.worker.global_worker.get_serialization_context() 3. ray._private.worker.global_worker.node.session_name 4. ray._private.worker.global_worker.node.max_bytes
_global_node	2	1. ray._private.worker._global_node.get_logs_dir_path() 2. ray._private.worker._global_node.address
blocking_get_inside_async_warned	1	1. ray._private.worker.blocking_get_inside_async_warned = True
LOCAL_MODE	1	1. from ray._private.worker import LOCAL_MODE
SCRIPT_MODE	1	1. from ray._private.worker import SCRIPT_MODE

ray.private.pydantic_compat

Function/Class	Usage Count	All Call Sites
BaseModel	5	1. from ray._private.pydantic_compat import BaseModel 2. class TypedArgs(BaseModel) 3. class ServeApplicationSchema(BaseModel) 4. class ServeDeploySchema(BaseModel) 5. class ServeInstanceDetails(BaseModel)
Field	2	1. from ray._private.pydantic_compat import Field 2. Field(default=...)
NonNegativeFloat	1	1. from ray._private.pydantic_compat import NonNegativeFloat
NonNegativeInt	2	1. from ray._private.pydantic_compat import NonNegativeInt 2. NonNegativeInt = ...
PositiveFloat	1	1. from ray._private.pydantic_compat import PositiveFloat
PositiveInt	2	1. from ray._private.pydantic_compat import PositiveInt 2. PositiveInt = ...
PrivateAttr	1	1. from ray._private.pydantic_compat import PrivateAttr
validator	2	1. from ray._private.pydantic_compat import validator 2. @validator(...)
root_validator	2	1. from ray._private.pydantic_compat import root_validator 2. @root_validator(...)
Extra	1	1. from ray._private.pydantic_compat import Extra
StrictInt	1	1. from ray._private.pydantic_compat import StrictInt
is_subclass_of_base_model	1	1. from ray._private.pydantic_compat import is_subclass_of_base_model
IS_PYDANTIC_2	1	1. from ray._private.pydantic_compat import IS_PYDANTIC_2

ray._private.test_utils

Function/Class	Usage Count	All Call Sites
wait_for_condition	20	1. wait_for_condition(check_replicas_on_worker_nodes) 2. wait_for_condition(lambda: len(ray._private.state.actors()) == 5) 3. wait_for_condition(check_metric_float_eq) 4. wait_for_condition(lambda: all([actor["State"] == "DEAD" for actor in ray._private.state.actors().values()])) 5. wait_for_condition(check_apps_running) 6. wait_for_condition(check_telemetry) 7. wait_for_condition(lambda: len(ray._private.state.actors()) == 6) 8. wait_for_condition(lambda: len(ray._private.state.actors()) == 3) 9. wait_for_condition(lambda: len(ray._private.state.actors()) == 2) 10. wait_for_condition(lambda: len(ray._private.state.actors()) == 1) 11. wait_for_condition(lambda: len(ray._private.state.actors()) == 0) 12. wait_for_condition(lambda: len(ray._private.state.actors()) == 4) 13. wait_for_condition(lambda: len(ray._private.state.actors()) == 7) 14. wait_for_condition(lambda: len(ray._private.state.actors()) == 8) 15. wait_for_condition(lambda: len(ray._private.state.actors()) == 9) 16. wait_for_condition(lambda: len(ray._private.state.actors()) == 10) 17. wait_for_condition(lambda: len(ray._private.state.actors()) == 11) 18. wait_for_condition(lambda: len(ray._private.state.actors()) == 12) 19. wait_for_condition(lambda: len(ray._private.state.actors()) == 13) 20. wait_for_condition(lambda: len(ray._private.state.actors()) == 14)
async_wait_for_condition	3	1. async_wait_for_condition(check_replicas_on_worker_nodes) 2. async_wait_for_condition(lambda: len(ray._private.state.actors()) == 5) 3. async_wait_for_condition(lambda: len(ray._private.state.actors()) == 3)
run_string_as_driver	3	1. run_string_as_driver(script) 2. run_string_as_driver(check_script.format(num_replicas=2)) 3. run_string_as_driver(check_controller_head_node_script)
TelemetryCallsite	1	1. from ray._private.test_utils import TelemetryCallsite
check_library_usage_telemetry	1	1. check_library_usage_telemetry(...)
Collector	1	1. from ray._private.test_utils import Collector

ray._private.state

Function/Class	Usage Count	All Call Sites
actors()	5	1. ray._private.state.actors() 2. ray._private.state.actors().values() 3. ray._private.state.actors().items() 4. ray._private.state.actors().get() 5. ray._private.state.actors().keys()

ray.private.internal_api

Function/Class	Usage Count	All Call Sites
memory_summary()	2	1. assert obj_ref_hex in ray._private.internal_api.memory_summary() 2. assert response["obj_ref_hex"] not in ray._private.internal_api.memory_summary()

ray._private.utils

Function/Class	Usage Count	All Call Sites
get_random_alphanumeric_string	1	1. from ray._private.utils import get_random_alphanumeric_string
resources_from_ray_options	1	1. from ray._private.utils import resources_from_ray_options
deprecated	1	1. from ray._private.utils import deprecated
reset_ray_address	1	1. ray._private.utils.reset_ray_address()

ray._private.signature

Function/Class	Usage Count	All Call Sites
extract_signature	1	1. from ray._private.signature import extract_signature
flatten_args	1	1. from ray._private.signature import flatten_args
recover_args	1	1. from ray._private.signature import recover_args

ray._private.ray_logging

Function/Class	Usage Count	All Call Sites
JSONFormatter	1	1. from ray._private.ray_logging.formatters import JSONFormatter
TextFormatter	1	1. from ray._private.ray_logging.formatters import TextFormatter
CoreContextFilter	1	1. from ray._private.ray_logging.filters import CoreContextFilter

ray._private.usage

Function/Class	Usage Count	All Call Sites
usage_lib	1	1. from ray._private.usage import usage_lib
get_extra_usage_tags_to_report	1	1. from ray._private.usage.usage_lib import get_extra_usage_tags_to_report

ray._private.ray_constants

Function/Class	Usage Count	All Call Sites
DEFAULT_MAX_CONCURRENCY_ASYNC	1	1. from ray._private.ray_constants import DEFAULT_MAX_CONCURRENCY_ASYNC
LOGGING_ROTATE_BACKUP_COUNT	1	1. from ray._private.ray_constants import LOGGING_ROTATE_BACKUP_COUNT
LOGGING_ROTATE_BYTES	1	1. from ray._private.ray_constants import LOGGING_ROTATE_BYTES

ray._private.resource_spec

Function/Class	Usage Count	All Call Sites
HEAD_NODE_RESOURCE_NAME	3	1. from ray._private.resource_spec import HEAD_NODE_RESOURCE_NAME 2. HEAD_NODE_RESOURCE_NAME in node.resources 3. HEAD_NODE_RESOURCE_NAME in node.resources_total

ray._private.serialization

Function/Class	Usage Count	All Call Sites
pickle_dumps	1	1. from ray._private.serialization import pickle_dumps
SerializationContext	1	1. from ray._private.serialization import SerializationContext

ray._private.ray_option_utils

Function/Class	Usage Count	All Call Sites
(module import)	1	1. from ray._private import ray_option_utils

[nehiljain]

Created a PR for tackling migration of pydantic_compat #53686.