guidellm 0.3.1__py3-none-any.whl → 0.6.0a5__py3-none-any.whl

guidellm/utils/mixins.py

@@ -0,0 +1,115 @@
+"""
+Mixin classes for common metadata extraction and object introspection.
+
+Provides reusable mixins for extracting structured metadata from objects,
+enabling consistent information exposure across different class hierarchies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["InfoMixin"]
+
+
+PYTHON_PRIMITIVES = (str, int, float, bool, list, tuple, dict)
+"""Type alias for serialized object representations"""
+
+
+class InfoMixin:
+    """
+    Mixin class providing standardized metadata extraction for introspection.
+
+    Enables consistent object metadata extraction patterns across different
+    class hierarchies for debugging, serialization, and runtime analysis.
+    Provides both instance and class-level methods for extracting structured
+    information from arbitrary objects with fallback handling for objects
+    without built-in info capabilities.
+
+    Example:
+    ::
+        from guidellm.utils.mixins import InfoMixin
+
+        class ConfiguredClass(InfoMixin):
+            def __init__(self, setting: str):
+                self.setting = setting
+
+        obj = ConfiguredClass("value")
+        # Returns {'str': 'ConfiguredClass(...)', 'type': 'ConfiguredClass', ...}
+        print(obj.info)
+    """
+
+    @classmethod
+    def extract_from_obj(cls, obj: Any) -> dict[str, Any]:
+        """
+        Extract structured metadata from any object.
+
+        Attempts to use the object's own `info` method or property if available,
+        otherwise constructs metadata from object attributes and type information.
+        Provides consistent metadata format across different object types.
+
+        :param obj: Object to extract metadata from
+        :return: Dictionary containing object metadata including type, class,
+            module, and public attributes
+        """
+        if hasattr(obj, "info"):
+            return obj.info() if callable(obj.info) else obj.info
+
+        return {
+            "str": str(obj),
+            "type": type(obj).__name__,
+            "class": obj.__class__.__name__ if hasattr(obj, "__class__") else None,
+            "module": obj.__class__.__module__ if hasattr(obj, "__class__") else None,
+            "attributes": (
+                {
+                    key: val if isinstance(val, PYTHON_PRIMITIVES) else repr(val)
+                    for key, val in obj.__dict__.items()
+                    if not key.startswith("_")
+                }
+                if hasattr(obj, "__dict__")
+                else {}
+            ),
+        }
+
+    @classmethod
+    def create_info_dict(cls, obj: Any) -> dict[str, Any]:
+        """
+        Create a structured info dictionary for the given object.
+
+        Builds standardized metadata dictionary containing object identification,
+        type information, and accessible attributes. Used internally by other
+        info extraction methods and available for direct metadata construction.
+
+        :param obj: Object to extract info from
+        :return: Dictionary containing structured metadata about the object
+        """
+        return {
+            "str": str(obj),
+            "type": type(obj).__name__,
+            "class": obj.__class__.__name__ if hasattr(obj, "__class__") else None,
+            "module": obj.__class__.__module__ if hasattr(obj, "__class__") else None,
+            "attributes": (
+                {
+                    key: val
+                    if isinstance(val, str | int | float | bool | list | dict)
+                    else repr(val)
+                    for key, val in obj.__dict__.items()
+                    if not key.startswith("_")
+                }
+                if hasattr(obj, "__dict__")
+                else {}
+            ),
+        }
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """
+        Return structured metadata about this instance.
+
+        Provides consistent access to object metadata for debugging, serialization,
+        and introspection. Uses the create_info_dict method to generate standardized
+        metadata format including class information and public attributes.
+
+        :return: Dictionary containing class name, module, and public attributes
+        """
+        return self.create_info_dict(self)

guidellm/utils/random.py

@@ -1,6 +1,5 @@
 import random
 from collections.abc import Iterator
-from typing import Optional
 
 __all__ = ["IntegerRangeSampler"]
 
@@ -9,9 +8,9 @@ class IntegerRangeSampler:
     def __init__(
         self,
         average: int,
-        variance: Optional[int],
-        min_value: Optional[int],
-        max_value: Optional[int],
+        variance: int | None,
+        min_value: int | None,
+        max_value: int | None,
         random_seed: int,
     ):
         self.average = average

guidellm/utils/registry.py

@@ -0,0 +1,220 @@
+"""
+Registry system for dynamic object registration and discovery.
+
+Provides a flexible object registration system with optional auto-discovery
+capabilities through decorators and module imports. Enables dynamic discovery
+and instantiation of implementations based on configuration parameters, supporting
+both manual registration and automatic package-based discovery for extensible
+plugin architectures.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import ClassVar, Generic, TypeVar, cast
+
+from guidellm.utils.auto_importer import AutoImporterMixin
+
+__all__ = ["RegisterT", "RegistryMixin", "RegistryObjT"]
+
+
+RegistryObjT = TypeVar("RegistryObjT")
+"""Generic type variable for objects managed by the registry system."""
+RegisterT = TypeVar(
+    "RegisterT", bound=type
+)  # Must be bound to type to ensure __name__ is available.
+"""Generic type variable for the args and return values within the registry."""
+
+
+class RegistryMixin(Generic[RegistryObjT], AutoImporterMixin):
+    """
+    Generic mixin for creating object registries with optional auto-discovery.
+
+    Enables classes to maintain separate registries of objects that can be dynamically
+    discovered and instantiated through decorators and module imports. Supports both
+    manual registration via decorators and automatic discovery through package scanning
+    for extensible plugin architectures.
+
+    Example:
+    ::
+        class BaseAlgorithm(RegistryMixin):
+            pass
+
+        @BaseAlgorithm.register()
+        class ConcreteAlgorithm(BaseAlgorithm):
+            pass
+
+        @BaseAlgorithm.register("custom_name")
+        class AnotherAlgorithm(BaseAlgorithm):
+            pass
+
+        # Get all registered implementations
+        algorithms = BaseAlgorithm.registered_objects()
+
+    Example with auto-discovery:
+    ::
+        class TokenProposal(RegistryMixin):
+            registry_auto_discovery = True
+            auto_package = "mypackage.proposals"
+
+        # Automatically imports and registers decorated objects
+        proposals = TokenProposal.registered_objects()
+
+    :cvar registry: Dictionary mapping names to registered objects
+    :cvar registry_auto_discovery: Enable automatic package-based discovery
+    :cvar registry_populated: Track whether auto-discovery has completed
+    """
+
+    registry: ClassVar[dict[str, RegistryObjT] | None] = None  # type: ignore[misc]
+    registry_auto_discovery: ClassVar[bool] = False
+    registry_populated: ClassVar[bool] = False
+
+    @classmethod
+    def register(
+        cls, name: str | list[str] | None = None
+    ) -> Callable[[RegisterT], RegisterT]:
+        """
+        Decorator for registering objects with the registry.
+
+        :param name: Optional name(s) to register the object under.
+            If None, uses the object's __name__ attribute
+        :return: Decorator function that registers the decorated object
+        :raises ValueError: If name is not a string, list of strings, or None
+        """
+
+        def _decorator(obj: RegisterT) -> RegisterT:
+            cls.register_decorator(obj, name=name)
+            return obj
+
+        return _decorator
+
+    @classmethod
+    def register_decorator(
+        cls, obj: RegisterT, name: str | list[str] | None = None
+    ) -> RegisterT:
+        """
+        Register an object directly with the registry.
+
+        :param obj: The object to register
+        :param name: Optional name(s) to register the object under.
+            If None, uses the object's __name__ attribute
+        :return: The registered object
+        :raises ValueError: If the object is already registered or name is invalid
+        """
+
+        if name is None:
+            name = obj.__name__
+        elif not isinstance(name, str | list):
+            raise ValueError(
+                "RegistryMixin.register_decorator name must be a string or "
+                f"an iterable of strings. Got {name}."
+            )
+
+        if cls.registry is None:
+            cls.registry = {}
+
+        names = [name] if isinstance(name, str) else list(name)
+
+        for register_name in names:
+            if not isinstance(register_name, str):
+                raise ValueError(
+                    "RegistryMixin.register_decorator name must be a string or "
+                    f"a list of strings. Got {register_name}."
+                )
+
+            if register_name in cls.registry:
+                raise ValueError(
+                    f"RegistryMixin.register_decorator cannot register an object "
+                    f"{obj} with the name {register_name} because it is already "
+                    "registered."
+                )
+
+            cls.registry[register_name] = cast("RegistryObjT", obj)
+
+        return obj
+
+    @classmethod
+    def auto_populate_registry(cls) -> bool:
+        """
+        Import and register all modules from the auto_package.
+
+        Automatically called by registered_objects when registry_auto_discovery is True
+        to ensure all available implementations are discovered.
+
+        :return: True if registry was populated, False if already populated
+        :raises ValueError: If called when registry_auto_discovery is False
+        """
+        if not cls.registry_auto_discovery:
+            raise ValueError(
+                "RegistryMixin.auto_populate_registry() cannot be called "
+                "because registry_auto_discovery is set to False. "
+                "Set registry_auto_discovery to True to enable auto-discovery."
+            )
+
+        if cls.registry_populated:
+            return False
+
+        cls.auto_import_package_modules()
+        cls.registry_populated = True
+
+        return True
+
+    @classmethod
+    def registered_objects(cls) -> tuple[RegistryObjT, ...]:
+        """
+        Get all registered objects from the registry.
+
+        Automatically triggers auto-discovery if registry_auto_discovery is enabled
+        to ensure all available implementations are included.
+
+        :return: Tuple of all registered objects including auto-discovered ones
+        :raises ValueError: If called before any objects have been registered
+        """
+        if cls.registry_auto_discovery:
+            cls.auto_populate_registry()
+
+        if cls.registry is None:
+            raise ValueError(
+                "RegistryMixin.registered_objects() must be called after "
+                "registering objects with RegistryMixin.register()."
+            )
+
+        return tuple(cls.registry.values())
+
+    @classmethod
+    def is_registered(cls, name: str) -> bool:
+        """
+        Check if an object is registered under the given name.
+        It matches first by exact name, then by str.lower().
+
+        :param name: The name to check for registration.
+        :return: True if the object is registered, False otherwise.
+        """
+        if cls.registry is None:
+            return False
+
+        return name in cls.registry or name.lower() in [
+            key.lower() for key in cls.registry
+        ]
+
+    @classmethod
+    def get_registered_object(cls, name: str) -> RegistryObjT | None:
+        """
+        Get a registered object by its name. It matches first by exact name,
+        then by str.lower().
+
+        :param name: The name of the registered object.
+        :return: The registered object if found, None otherwise.
+        """
+        if cls.registry is None:
+            return None
+
+        if name in cls.registry:
+            return cls.registry[name]
+
+        name_casefold = name.lower()
+        for k, v in cls.registry.items():
+            if name_casefold == k.lower():
+                return v
+
+        return None  # Not found

guidellm/utils/singleton.py

@@ -0,0 +1,133 @@
+"""
+Singleton pattern implementations for ensuring single instance classes.
+
+Provides singleton mixins for creating classes that maintain a single instance
+throughout the application lifecycle, with support for both basic and thread-safe
+implementations. These mixins integrate with the scheduler and other system components
+to ensure consistent state management and prevent duplicate resource allocation.
+"""
+
+from __future__ import annotations
+
+import threading
+
+__all__ = ["SingletonMixin", "ThreadSafeSingletonMixin"]
+
+
+class SingletonMixin:
+    """
+    Basic singleton mixin ensuring single instance per class.
+
+    Implements the singleton pattern using class variables to control instance
+    creation. Subclasses must call super().__init__() for proper initialization
+    state management. Suitable for single-threaded environments or when external
+    synchronization is provided.
+
+    Example:
+    ::
+        class ConfigManager(SingletonMixin):
+            def __init__(self, config_path: str):
+                super().__init__()
+                if not self.initialized:
+                    self.config = load_config(config_path)
+
+        manager1 = ConfigManager("config.json")
+        manager2 = ConfigManager("config.json")
+        assert manager1 is manager2
+    """
+
+    _singleton_initialized: bool
+    _init_lock: threading.Lock
+
+    def __new__(cls, *args, **kwargs):  # noqa: ARG004
+        """
+        Create or return the singleton instance.
+
+        :param args: Positional arguments passed to the constructor
+        :param kwargs: Keyword arguments passed to the constructor
+        :return: The singleton instance of the class
+        """
+        # Use class-specific attribute name to avoid inheritance issues
+        attr_name = f"_singleton_instance_{cls.__name__}"
+
+        if not hasattr(cls, attr_name) or getattr(cls, attr_name) is None:
+            instance = super().__new__(cls)
+            setattr(cls, attr_name, instance)
+            instance._singleton_initialized = False
+        return getattr(cls, attr_name)
+
+    def __init__(self):
+        """Initialize the singleton instance exactly once."""
+        if hasattr(self, "_singleton_initialized") and self._singleton_initialized:
+            return
+        self._singleton_initialized = True
+
+    @property
+    def initialized(self):
+        """Return True if the singleton has been initialized."""
+        return getattr(self, "_singleton_initialized", False)
+
+
+class ThreadSafeSingletonMixin(SingletonMixin):
+    """
+    Thread-safe singleton mixin with locking mechanisms.
+
+    Extends SingletonMixin with thread safety using locks to prevent race
+    conditions during instance creation in multi-threaded environments. Essential
+    for scheduler components and other shared resources accessed concurrently.
+
+    Example:
+    ::
+        class SchedulerResource(ThreadSafeSingletonMixin):
+            def __init__(self):
+                super().__init__()
+                if not self.initialized:
+                    self.resource_pool = initialize_resources()
+    """
+
+    def __new__(cls, *args, **kwargs):  # noqa: ARG004
+        """
+        Create or return the singleton instance with thread safety.
+
+        :param args: Positional arguments passed to the constructor
+        :param kwargs: Keyword arguments passed to the constructor
+        :return: The singleton instance of the class
+        """
+        # Use class-specific lock and instance names to avoid inheritance issues
+        lock_attr_name = f"_singleton_lock_{cls.__name__}"
+        instance_attr_name = f"_singleton_instance_{cls.__name__}"
+
+        with getattr(cls, lock_attr_name):
+            instance_exists = (
+                hasattr(cls, instance_attr_name)
+                and getattr(cls, instance_attr_name) is not None
+            )
+            if not instance_exists:
+                instance = super(SingletonMixin, cls).__new__(cls)
+                setattr(cls, instance_attr_name, instance)
+                instance._singleton_initialized = False
+                instance._init_lock = threading.Lock()
+            return getattr(cls, instance_attr_name)
+
+    def __init_subclass__(cls, *args, **kwargs):
+        super().__init_subclass__(*args, **kwargs)
+        lock_attr_name = f"_singleton_lock_{cls.__name__}"
+        setattr(cls, lock_attr_name, threading.Lock())
+
+    def __init__(self):
+        """Initialize the singleton instance with thread-safe initialization."""
+        with self._init_lock:
+            if hasattr(self, "_singleton_initialized") and self._singleton_initialized:
+                return
+            self._singleton_initialized = True
+
+    @property
+    def thread_lock(self):
+        """Return the thread lock for this singleton instance."""
+        return getattr(self, "_init_lock", None)
+
+    @classmethod
+    def get_singleton_lock(cls):
+        """Get the class-specific singleton creation lock."""
+        lock_attr_name = f"_singleton_lock_{cls.__name__}"
+        return getattr(cls, lock_attr_name, None)

guidellm/utils/synchronous.py

@@ -0,0 +1,159 @@
+"""
+Async utilities for waiting on synchronization objects.
+
+This module provides async-compatible wrappers for threading and multiprocessing
+synchronization primitives (Events and Barriers). These utilities enable async code
+to wait for synchronization objects without blocking the event loop, essential for
+coordinating between async and sync code or between processes in the guidellm system.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from multiprocessing.synchronize import Barrier as ProcessingBarrier
+from multiprocessing.synchronize import Event as ProcessingEvent
+from threading import Barrier as ThreadingBarrier
+from threading import Event as ThreadingEvent
+
+__all__ = [
+    "SyncObjectTypesAlias",
+    "wait_for_sync_barrier",
+    "wait_for_sync_event",
+    "wait_for_sync_objects",
+]
+
+
+# Type alias for threading and multiprocessing synchronization object types
+SyncObjectTypesAlias = (
+    ThreadingEvent | ProcessingEvent | ThreadingBarrier | ProcessingBarrier
+)
+
+
+async def wait_for_sync_event(
+    event: ThreadingEvent | ProcessingEvent,
+    poll_interval: float,
+) -> None:
+    """
+    Asynchronously wait for a threading or multiprocessing Event to be set.
+
+    This function polls the event at regular intervals without blocking the async
+    event loop, allowing other async tasks to continue executing while waiting.
+
+    :param event: The Event object to wait for (threading or multiprocessing)
+    :param poll_interval: Time in seconds between polling checks
+    :raises asyncio.CancelledError: If the async task is cancelled
+    """
+    stop = ThreadingEvent()
+
+    def _watch():
+        try:
+            while not stop.is_set():
+                if event.wait(timeout=poll_interval):
+                    return
+        except Exception as err:  # noqa: BLE001
+            if stop.is_set():
+                return  # Ignore error if we should have stopped
+            raise err
+
+    try:
+        await asyncio.to_thread(_watch)
+    except asyncio.CancelledError:
+        stop.set()
+        raise
+
+
+async def wait_for_sync_barrier(
+    barrier: ThreadingBarrier | ProcessingBarrier,
+    poll_interval: float,
+) -> None:
+    """
+    Asynchronously wait for a threading or multiprocessing Barrier to be reached.
+
+    This function polls the barrier at regular intervals without blocking the async
+    event loop, allowing other async tasks to continue executing while waiting.
+
+    :param barrier: The Barrier object to wait for (threading or multiprocessing)
+    :param poll_interval: Time in seconds between polling checks
+    :raises asyncio.CancelledError: If the async task is cancelled
+    """
+    stop = ThreadingEvent()
+    barrier_broken = ThreadingEvent()
+
+    def _wait_indefinite():
+        try:
+            # wait forever, count on barrier broken event to exit
+            barrier.wait()
+            barrier_broken.set()
+        except Exception as err:
+            if stop.is_set():
+                return  # Ignore error if we should have stopped
+            raise err
+
+    def _watch():
+        while not barrier_broken.is_set():
+            if stop.is_set():
+                with contextlib.suppress(Exception):
+                    if not barrier.broken:
+                        barrier.abort()
+                break
+            time.sleep(poll_interval)
+
+    try:
+        await asyncio.gather(
+            asyncio.to_thread(_wait_indefinite),
+            asyncio.to_thread(_watch),
+        )
+    except asyncio.CancelledError:
+        stop.set()
+        raise
+
+
+async def wait_for_sync_objects(
+    objects: SyncObjectTypesAlias
+    | list[SyncObjectTypesAlias]
+    | dict[str, SyncObjectTypesAlias],
+    poll_interval: float = 0.1,
+) -> int | str:
+    """
+    Asynchronously wait for the first synchronization object to complete.
+
+    This function waits for the first Event to be set or Barrier to be reached
+    from a collection of synchronization objects. It returns immediately when
+    any object completes and cancels waiting on the remaining objects.
+
+    :param objects: Single sync object, list of objects, or dict mapping names
+        to objects
+    :param poll_interval: Time in seconds between polling checks for each object
+    :return: Index (for list/single) or key name (for dict) of the first
+        completed object
+    :raises asyncio.CancelledError: If the async task is canceled
+    """
+    keys: list[int | str]
+    if isinstance(objects, dict):
+        keys = list(objects.keys())
+        objects = list(objects.values())
+    elif isinstance(objects, list):
+        keys = list(range(len(objects)))
+    else:
+        keys = [0]
+        objects = [objects]
+
+    tasks = [
+        asyncio.create_task(
+            wait_for_sync_barrier(obj, poll_interval)
+            if isinstance(obj, ThreadingBarrier | ProcessingBarrier)
+            else wait_for_sync_event(obj, poll_interval)
+        )
+        for obj in objects
+    ]
+
+    done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+
+    # Cancel the remaining pending tasks
+    for pend in pending:
+        pend.cancel()
+    await asyncio.gather(*pending, return_exceptions=True)
+
+    return keys[tasks.index(list(done)[0])]