guidellm 0.4.0a18__py3-none-any.whl → 0.4.0a155__py3-none-any.whl

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])]

guidellm/utils/text.py

@@ -1,46 +1,107 @@
+"""
+Text processing utilities for content manipulation and formatting operations.
+
+Provides comprehensive text processing capabilities including cleaning, filtering,
+splitting, loading from various sources, and formatting utilities. Supports loading
+text from URLs, compressed files, package resources, and local files with automatic
+encoding detection. Includes specialized formatting for display values and text
+wrapping operations for consistent presentation across the system.
+"""
+
+from __future__ import annotations
+
 import gzip
 import re
 import textwrap
-from importlib.resources import as_file, files  # type: ignore[attr-defined]
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import ftfy
 import httpx
 from loguru import logger
 
-from guidellm import data as package_data
-from guidellm.config import settings
+from guidellm.settings import settings
+from guidellm.utils.console import Colors
 
 __all__ = [
+    "MAX_PATH_LENGTH",
     "EndlessTextCreator",
     "camelize_str",
     "clean_text",
     "filter_text",
-    "is_puncutation",
+    "format_value_display",
+    "is_punctuation",
     "load_text",
     "split_text",
     "split_text_list_by_length",
 ]
 
-MAX_PATH_LENGTH = 4096
+MAX_PATH_LENGTH: int = 4096
+
+
+def format_value_display(
+    value: float,
+    label: str,
+    units: str = "",
+    total_characters: int | None = None,
+    digits_places: int | None = None,
+    decimal_places: int | None = None,
+) -> str:
+    """
+    Format a numeric value with units and label for consistent display output.
+
+    Creates standardized display strings for metrics and measurements with
+    configurable precision, width, and color formatting. Supports both
+    fixed-width and variable-width output for tabular displays.
+
+    :param value: Numeric value to format and display
+    :param label: Descriptive label for the value
+    :param units: Units string to append after the value
+    :param total_characters: Total width for right-aligned output formatting
+    :param digits_places: Total number of digits for numeric formatting
+    :param decimal_places: Number of decimal places for numeric precision
+    :return: Formatted string with value, units, and colored label
+    """
+    if decimal_places is None and digits_places is None:
+        formatted_number = f"{value:.0f}"
+    elif digits_places is None:
+        formatted_number = f"{value:.{decimal_places}f}"
+    elif decimal_places is None:
+        formatted_number = f"{value:>{digits_places}f}"
+    else:
+        formatted_number = f"{value:>{digits_places}.{decimal_places}f}"
+
+    result = f"{formatted_number}{units} [{Colors.info}]{label}[/{Colors.info}]"
+
+    if total_characters is not None:
+        total_characters += len(Colors.info) * 2 + 5
+
+        if len(result) < total_characters:
+            result = result.rjust(total_characters)
+
+    return result
 
 
 def split_text_list_by_length(
     text_list: list[Any],
-    max_characters: Union[int, list[int]],
+    max_characters: int | list[int],
     pad_horizontal: bool = True,
     pad_vertical: bool = True,
 ) -> list[list[str]]:
     """
-    Split a list of strings into a list of strings,
-    each with a maximum length of max_characters
-
-    :param text_list: the list of strings to split
-    :param max_characters: the maximum length of each string
-    :param pad_horizontal: whether to pad the strings horizontally, defaults to True
-    :param pad_vertical: whether to pad the strings vertically, defaults to True
-    :return: a list of strings
+    Split text strings into wrapped lines with specified maximum character limits.
+
+    Processes each string in the input list by wrapping text to fit within character
+    limits, with optional padding for consistent formatting in tabular displays.
+    Supports different character limits per string and uniform padding across results.
+
+    :param text_list: List of strings to process and wrap
+    :param max_characters: Maximum characters per line, either single value or
+        per-string limits
+    :param pad_horizontal: Right-align lines within their character limits
+    :param pad_vertical: Pad shorter results to match the longest wrapped result
+    :return: List of wrapped line lists, one per input string
+    :raises ValueError: If max_characters list length doesn't match text_list length
     """
     if not isinstance(max_characters, list):
         max_characters = [max_characters] * len(text_list)
@@ -76,16 +137,21 @@ def split_text_list_by_length(
 
 def filter_text(
     text: str,
-    filter_start: Optional[Union[str, int]] = None,
-    filter_end: Optional[Union[str, int]] = None,
+    filter_start: str | int | None = None,
+    filter_end: str | int | None = None,
 ) -> str:
     """
-    Filter text by start and end strings or indices
+    Extract text substring using start and end markers or indices.
 
-    :param text: the text to filter
-    :param filter_start: the start string or index to filter from
-    :param filter_end: the end string or index to filter to
-    :return: the filtered text
+    Filters text content by locating string markers or using numeric indices
+    to extract specific portions. Supports flexible filtering for content
+    extraction and preprocessing operations.
+
+    :param text: Source text to filter and extract from
+    :param filter_start: Starting marker string or index position
+    :param filter_end: Ending marker string or index position
+    :return: Filtered text substring between specified boundaries
+    :raises ValueError: If filter indices are invalid or markers not found
     """
     filter_start_index = -1
     filter_end_index = -1
@@ -113,10 +179,29 @@ def filter_text(
 
 
 def clean_text(text: str) -> str:
+    """
+    Normalize text by fixing encoding issues and standardizing whitespace.
+
+    Applies Unicode normalization and whitespace standardization for consistent
+    text processing. Removes excessive whitespace and fixes common encoding problems.
+
+    :param text: Raw text string to clean and normalize
+    :return: Cleaned text with normalized encoding and whitespace
+    """
     return re.sub(r"\s+", " ", ftfy.fix_text(text)).strip()
 
 
 def split_text(text: str, split_punctuation: bool = False) -> list[str]:
+    """
+    Split text into tokens with optional punctuation separation.
+
+    Tokenizes text into words and optionally separates punctuation marks
+    for detailed text analysis and processing operations.
+
+    :param text: Text string to tokenize and split
+    :param split_punctuation: Separate punctuation marks as individual tokens
+    :return: List of text tokens
+    """
     text = clean_text(text)
 
     if split_punctuation:
@@ -125,16 +210,20 @@ def split_text(text: str, split_punctuation: bool = False) -> list[str]:
     return text.split()
 
 
-def load_text(data: Union[str, Path], encoding: Optional[str] = None) -> str:
+def load_text(data: str | Path, encoding: str | None = None) -> str:
     """
-    Load an HTML file from a path or URL
-
-    :param data: the path or URL to load the HTML file from
-    :type data: Union[str, Path]
-    :param encoding: the encoding to use when reading the file
-    :type encoding: str
-    :return: the HTML content
-    :rtype: str
+    Load text content from various sources including URLs, files, and package data.
+
+    Supports loading from HTTP/FTP URLs, local files, compressed archives, package
+    resources, and raw text strings. Automatically detects source type and applies
+    appropriate loading strategy with encoding support.
+
+    :param data: Source location or raw text - URL, file path, package resource
+        identifier, or text content
+    :param encoding: Character encoding for file reading operations
+    :return: Loaded text content as string
+    :raises FileNotFoundError: If local file path does not exist
+    :raises httpx.HTTPStatusError: If URL request fails
     """
     logger.debug("Loading text: {}", data)
 
@@ -148,15 +237,6 @@ def load_text(data: Union[str, Path], encoding: Optional[str] = None) -> str:
             response.raise_for_status()
             return response.text
 
-    # check package data
-    if isinstance(data, str) and data.startswith("data:"):
-        resource_path = files(package_data).joinpath(data[5:])
-        with (
-            as_file(resource_path) as resource_file,
-            gzip.open(resource_file, "rt", encoding=encoding) as file,
-        ):
-            return file.read()
-
     # check gzipped files
     if isinstance(data, str) and data.endswith(".gz"):
         with gzip.open(data, "rt", encoding=encoding) as file:
@@ -178,14 +258,15 @@ def load_text(data: Union[str, Path], encoding: Optional[str] = None) -> str:
     return data.read_text(encoding=encoding)
 
 
-def is_puncutation(text: str) -> bool:
+def is_punctuation(text: str) -> bool:
     """
-    Check if the text is a punctuation
+    Check if a single character is a punctuation mark.
+
+    Identifies punctuation characters by excluding alphanumeric characters
+    and whitespace from single-character strings.
 
-    :param text: the text to check
-    :type text: str
-    :return: True if the text is a punctuation, False otherwise
-    :rtype: bool
+    :param text: Single character string to test
+    :return: True if the character is punctuation, False otherwise
     """
     return len(text) == 1 and not text.isalnum() and not text.isspace()
 
@@ -197,25 +278,57 @@ def camelize_str(snake_case_string: str) -> str:
 
 
 class EndlessTextCreator:
+    """
+    Infinite text generator for load testing and content creation operations.
+
+    Provides deterministic text generation by cycling through preprocessed word
+    tokens from source content. Supports filtering and punctuation handling for
+    realistic text patterns in benchmarking scenarios.
+
+    Example:
+    ::
+        creator = EndlessTextCreator("path/to/source.txt")
+        generated = creator.create_text(start=0, length=100)
+        more_text = creator.create_text(start=50, length=200)
+    """
+
     def __init__(
         self,
-        data: Union[str, Path],
-        filter_start: Optional[Union[str, int]] = None,
-        filter_end: Optional[Union[str, int]] = None,
+        data: str | Path,
+        filter_start: str | int | None = None,
+        filter_end: str | int | None = None,
     ):
+        """
+        Initialize text creator with source content and optional filtering.
+
+        :param data: Source text location or content - file path, URL, or raw text
+        :param filter_start: Starting marker or index for content filtering
+        :param filter_end: Ending marker or index for content filtering
+        """
         self.data = data
         self.text = load_text(data)
         self.filtered_text = filter_text(self.text, filter_start, filter_end)
         self.words = split_text(self.filtered_text, split_punctuation=True)
 
     def create_text(self, start: int, length: int) -> str:
+        """
+        Generate text by cycling through word tokens from the specified position.
+
+        Creates deterministic text sequences by selecting consecutive tokens from
+        the preprocessed word list, wrapping around when reaching the end.
+        Maintains proper spacing and punctuation formatting.
+
+        :param start: Starting position in the token sequence
+        :param length: Number of tokens to include in generated text
+        :return: Generated text string with proper spacing and punctuation
+        """
         text = ""
 
         for counter in range(length):
             index = (start + counter) % len(self.words)
             add_word = self.words[index]
 
-            if counter != 0 and not is_puncutation(add_word):
+            if counter != 0 and not is_punctuation(add_word):
                 text += " "
 
             text += add_word

guidellm/utils/typing.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from types import UnionType
+from typing import Annotated, Literal, Union, get_args, get_origin
+
+# Backwards compatibility for Python <3.12
+try:
+    from typing import TypeAliasType  # type: ignore[attr-defined]
+except ImportError:
+    from typing_extensions import TypeAliasType
+
+
+__all__ = ["get_literal_vals"]
+
+
+def get_literal_vals(alias) -> frozenset[str]:
+    """Extract all literal values from a (possibly nested) type alias."""
+
+    def resolve(alias) -> Iterator[str]:
+        origin = get_origin(alias)
+
+        # Base case: Literal types
+        if origin is Literal:
+            for literal_val in get_args(alias):
+                yield str(literal_val)
+        # Unwrap Annotated type
+        elif origin is Annotated:
+            yield from resolve(get_args(alias)[0])
+        # Unwrap TypeAliasTypes
+        elif isinstance(alias, TypeAliasType):
+            yield from resolve(alias.__value__)
+        # Iterate over unions
+        elif origin in (Union, UnionType):
+            for arg in get_args(alias):
+                yield from resolve(arg)
+        # Fallback
+        else:
+            yield str(alias)
+
+    return frozenset(resolve(alias))

guidellm/version.py

@@ -1,4 +1,4 @@
-version = "0.1.0a0"
+version = "0.4.0a0"
 build_type = "nightly"
 build_iteration = "0"
 git_commit = "None"

{guidellm-0.4.0a18.dist-info → guidellm-0.4.0a155.dist-info}/METADATA

@@ -1,34 +1,57 @@
 Metadata-Version: 2.4
 Name: guidellm
-Version: 0.4.0a18
+Version: 0.4.0a155
 Summary: Guidance platform for deploying and managing large language models.
 Author: Red Hat
-License-Expression: Apache-2.0
+License: Apache-2.0
 Project-URL: homepage, https://github.com/vllm-project/guidellm
 Project-URL: source, https://github.com/vllm-project/guidellm
 Project-URL: issues, https://github.com/vllm-project/guidellm/issues
 Project-URL: docs, https://github.com/vllm-project/guidellm/tree/main/docs
 Keywords: ai,benchmarking,deep-learning,deployment,evaluation,guidance,inference,language-models,large-language-model,llm,machine-learning,model-benchmark,model-evaluation,nlp,performance,vllm
-Requires-Python: <4.0,>=3.9.0
+Requires-Python: <4.0,>=3.10.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click<8.2.0,>=8.0.0
+Requires-Dist: culsans~=0.9.0
 Requires-Dist: datasets
+Requires-Dist: eval_type_backport
+Requires-Dist: faker
 Requires-Dist: ftfy>=6.0.0
 Requires-Dist: httpx[http2]<1.0.0
 Requires-Dist: loguru
-Requires-Dist: numpy
-Requires-Dist: pillow
+Requires-Dist: msgpack
+Requires-Dist: numpy>=2.0.0
 Requires-Dist: protobuf
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich
+Requires-Dist: sanic
 Requires-Dist: transformers
+Requires-Dist: uvloop>=0.18
+Requires-Dist: torch
+Provides-Extra: all
+Requires-Dist: guidellm[audio,openai,perf,vision]; extra == "all"
 Provides-Extra: recommended
-Requires-Dist: tiktoken>=0.11.0; extra == "recommended"
-Requires-Dist: blobfile>=3.1.0; extra == "recommended"
+Requires-Dist: guidellm[openai,perf]; extra == "recommended"
+Provides-Extra: perf
+Requires-Dist: orjson; extra == "perf"
+Requires-Dist: msgpack; extra == "perf"
+Requires-Dist: msgspec; extra == "perf"
+Requires-Dist: uvloop; extra == "perf"
+Provides-Extra: openai
+Requires-Dist: tiktoken>=0.11.0; extra == "openai"
+Requires-Dist: blobfile>=3.1.0; extra == "openai"
+Provides-Extra: audio
+Requires-Dist: datasets[audio]>=4.1.0; extra == "audio"
+Requires-Dist: torch==2.9.*; extra == "audio"
+Requires-Dist: torchcodec==0.8; extra == "audio"
+Provides-Extra: vision
+Requires-Dist: datasets[vision]; extra == "vision"
+Requires-Dist: pillow; extra == "vision"
 Provides-Extra: dev
+Requires-Dist: guidellm[all]; extra == "dev"
 Requires-Dist: build>=1.0.0; extra == "dev"
 Requires-Dist: setuptools>=61.0; extra == "dev"
 Requires-Dist: setuptools-git-versioning<3,>=2.0; extra == "dev"
@@ -38,7 +61,7 @@ Requires-Dist: sphinx~=7.1.2; extra == "dev"
 Requires-Dist: tox~=4.16.0; extra == "dev"
 Requires-Dist: lorem~=0.1.1; extra == "dev"
 Requires-Dist: pytest~=8.2.2; extra == "dev"
-Requires-Dist: pytest-asyncio~=0.23.8; extra == "dev"
+Requires-Dist: pytest-asyncio~=1.1.0; extra == "dev"
 Requires-Dist: pytest-cov~=5.0.0; extra == "dev"
 Requires-Dist: pytest-mock~=3.14.0; extra == "dev"
 Requires-Dist: pytest-rerunfailures~=14.0; extra == "dev"
@@ -66,7 +89,7 @@ Dynamic: license-file
 Scale Efficiently: Evaluate and Optimize Your LLM Deployments for Real-World Inference
 </h3>
 
-[![GitHub Release](https://img.shields.io/github/release/vllm-project/guidellm.svg?label=Version)](https://github.com/vllm-project/guidellm/releases) [![Documentation](https://img.shields.io/badge/Documentation-8A2BE2?logo=read-the-docs&logoColor=%23ffffff&color=%231BC070)](https://github.com/vllm-project/guidellm/tree/main/docs) [![License](https://img.shields.io/github/license/vllm-project/guidellm.svg)](https://github.com/vllm-project/guidellm/blob/main/LICENSE) [![PyPI Release](https://img.shields.io/pypi/v/guidellm.svg?label=PyPI%20Release)](https://pypi.python.org/pypi/guidellm) [![Python Versions](https://img.shields.io/badge/Python-3.9--3.13-orange)](https://pypi.python.org/pypi/guidellm) [![Nightly Build](https://img.shields.io/github/actions/workflow/status/vllm-project/guidellm/nightly.yml?branch=main&label=Nightly%20Build)](https://github.com/vllm-project/guidellm/actions/workflows/nightly.yml)
+[![GitHub Release](https://img.shields.io/github/release/vllm-project/guidellm.svg?label=Version)](https://github.com/vllm-project/guidellm/releases) [![Documentation](https://img.shields.io/badge/Documentation-8A2BE2?logo=read-the-docs&logoColor=%23ffffff&color=%231BC070)](https://github.com/vllm-project/guidellm/tree/main/docs) [![License](https://img.shields.io/github/license/vllm-project/guidellm.svg)](https://github.com/vllm-project/guidellm/blob/main/LICENSE) [![PyPI Release](https://img.shields.io/pypi/v/guidellm.svg?label=PyPI%20Release)](https://pypi.python.org/pypi/guidellm) [![Python Versions](https://img.shields.io/badge/Python-3.10--3.13-orange)](https://pypi.python.org/pypi/guidellm) [![Nightly Build](https://img.shields.io/github/actions/workflow/status/vllm-project/guidellm/nightly.yml?branch=main&label=Nightly%20Build)](https://github.com/vllm-project/guidellm/actions/workflows/nightly.yml)
 
 ## Overview
 
@@ -93,7 +116,7 @@ Scale Efficiently: Evaluate and Optimize Your LLM Deployments for Real-World Inf
 Before installing, ensure you have the following prerequisites:
 
 - OS: Linux or MacOS
-- Python: 3.9 – 3.13
+- Python: 3.10 – 3.13
 
 The latest GuideLLM release can be installed using pip: