Scheduler refactor [utils]: functions, mixins, statistics, text (#290)

## Summary

This PR adds new utility modules for safe math function operations,
object info extraction, and reorganizes to consolidate into the utils
package.

## Details

- **Move statistics classes from `objects` to `utils`**:
Relocates `DistributionSummary`, `Percentiles`, `RunningStats`, `StatusDistributionSummary`,
and `TimeRunningStats` from `guidellm.objects.statistics` to `guidellm.utils.statistics`
- **Add new `functions.py` module**: Implements defensive programming
utilities
including `safe_getattr`, `safe_divide`, `safe_multiply`, `safe_add`, `safe_format_timestamp`,
and `all_defined` for handling None values and edge cases
- **Add new `mixins.py` module**: Provides `InfoMixin` class for
standardized metadata extraction and object introspection across
different class hierarchies
- **Enhance `text.py` module**: Adds comprehensive
documentation, `format_value_display` function for consistent metric
formatting, and improved text processing utilities
- **Update import statements**: Modifies all affected modules
(`benchmark`, `presentation`) to import statistics classes from their
new location in `utils`
- **Remove deprecated `objects` package**: Deletes the
now-empty `objects` directory and associated test files
- **Add comprehensive test coverage**: Includes new test suites
for `functions.py`, `mixins.py`, and `statistics.py`
- **Update `__init__.py` exports**: Adds new utility functions and
classes to the main utils package exports for easy access

## Test Plan

- Run the existing test suite to ensure no regressions from the
statistics class relocation
- Execute new test files:
    - test_functions.py - Tests for safe operation utilities
    - test_mixins.py - Tests for InfoMixin functionality
- test_statistics.py - Comprehensive tests for statistical analysis
utilities
    - test_text.py - Tests for enhanced text processing functions

## Related Issues


- Resolves #

---

- [X] "I certify that all code in this PR is my own, except as noted
below."

## Use of AI

- [X] Includes AI-assisted code completion
- [X] Includes code generated by an AI application
- [ ] Includes AI-generated tests (NOTE: AI written tests should have a
docstring that includes `## WRITTEN BY AI ##`)

---------

Signed-off-by: Mark Kurtz <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Samuel Monson <[email protected]>

Author: 3 people

src/guidellm/benchmark/aggregator.py

@@ -22,10 +22,6 @@
     GenerativeTextResponseStats,
 )
 from guidellm.config import settings
-from guidellm.objects import (
-    RunningStats,
-    TimeRunningStats,
-)
 from guidellm.request import (
     GenerationRequest,
     GenerativeRequestLoaderDescription,
@@ -38,7 +34,13 @@
     SchedulerRequestResult,
     WorkerDescription,
 )
-from guidellm.utils import StandardBaseModel, StatusBreakdown, check_load_processor
+from guidellm.utils import (
+    RunningStats,
+    StandardBaseModel,
+    StatusBreakdown,
+    TimeRunningStats,
+    check_load_processor,
+)
 
 __all__ = [
     "AggregatorT",

src/guidellm/benchmark/benchmark.py

@@ -12,9 +12,6 @@
     SynchronousProfile,
     ThroughputProfile,
 )
-from guidellm.objects import (
-    StatusDistributionSummary,
-)
 from guidellm.request import (
     GenerativeRequestLoaderDescription,
     RequestLoaderDescription,
@@ -30,7 +27,11 @@
     ThroughputStrategy,
     WorkerDescription,
 )
-from guidellm.utils import StandardBaseModel, StatusBreakdown
+from guidellm.utils import (
+    StandardBaseModel,
+    StatusBreakdown,
+    StatusDistributionSummary,
+)
 
 __all__ = [
     "Benchmark",

src/guidellm/benchmark/output.py

@@ -21,14 +21,16 @@
     ThroughputProfile,
 )
 from guidellm.config import settings
-from guidellm.objects import (
-    DistributionSummary,
-    StatusDistributionSummary,
-)
 from guidellm.presentation import UIDataBuilder
 from guidellm.presentation.injector import create_report
 from guidellm.scheduler import strategy_display_str
-from guidellm.utils import Colors, StandardBaseModel, split_text_list_by_length
+from guidellm.utils import (
+    Colors,
+    DistributionSummary,
+    StandardBaseModel,
+    StatusDistributionSummary,
+    split_text_list_by_length,
+)
 
 __all__ = [
     "GenerativeBenchmarksConsole",

src/guidellm/objects/__init__.py

@@ -8,7 +8,7 @@
 if TYPE_CHECKING:
     from guidellm.benchmark.benchmark import GenerativeBenchmark
 
-from guidellm.objects.statistics import DistributionSummary
+from guidellm.utils.statistics import DistributionSummary
 
 
 class Bucket(BaseModel):

src/guidellm/presentation/data_models.py

@@ -1,6 +1,14 @@
 from .auto_importer import AutoImporterMixin
 from .colors import Colors
 from .default_group import DefaultGroupHandler
+from .functions import (
+    all_defined,
+    safe_add,
+    safe_divide,
+    safe_format_timestamp,
+    safe_getattr,
+    safe_multiply,
+)
 from .hf_datasets import (
     SUPPORTED_TYPES,
     save_dataset_to_file,
@@ -18,11 +26,18 @@
 from .random import IntegerRangeSampler
 from .registry import RegistryMixin
 from .singleton import SingletonMixin, ThreadSafeSingletonMixin
+from .statistics import (
+    DistributionSummary,
+    Percentiles,
+    RunningStats,
+    StatusDistributionSummary,
+    TimeRunningStats,
+)
 from .text import (
     EndlessTextCreator,
     clean_text,
     filter_text,
-    is_puncutation,
+    is_punctuation,
     load_text,
     split_text,
     split_text_list_by_length,
@@ -33,21 +48,32 @@
     "AutoImporterMixin",
     "Colors",
     "DefaultGroupHandler",
+    "DistributionSummary",
     "EndlessTextCreator",
     "IntegerRangeSampler",
+    "Percentiles",
     "PydanticClassRegistryMixin",
     "RegistryMixin",
     "ReloadableBaseModel",
+    "RunningStats",
     "SingletonMixin",
     "StandardBaseDict",
     "StandardBaseModel",
     "StatusBreakdown",
+    "StatusDistributionSummary",
     "ThreadSafeSingletonMixin",
+    "TimeRunningStats",
+    "all_defined",
     "check_load_processor",
     "clean_text",
     "filter_text",
-    "is_puncutation",
+    "is_punctuation",
     "load_text",
+    "safe_add",
+    "safe_divide",
+    "safe_format_timestamp",
+    "safe_getattr",
+    "safe_multiply",
     "save_dataset_to_file",
     "split_text",
     "split_text_list_by_length",

src/guidellm/utils/__init__.py

@@ -0,0 +1,130 @@
+"""
+Utility functions for safe operations and value handling.
+
+Provides defensive programming utilities for common operations that may encounter
+None values, invalid inputs, or edge cases. Includes safe arithmetic operations,
+attribute access, and timestamp formatting.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+__all__ = [
+    "all_defined",
+    "safe_add",
+    "safe_divide",
+    "safe_format_timestamp",
+    "safe_getattr",
+    "safe_multiply",
+]
+
+
+def safe_getattr(obj: Any | None, attr: str, default: Any = None) -> Any:
+    """
+    Safely get an attribute from an object with None handling.
+
+    :param obj: Object to get the attribute from, or None
+    :param attr: Name of the attribute to retrieve
+    :param default: Value to return if object is None or attribute doesn't exist
+    :return: Attribute value or default if not found or object is None
+    """
+    if obj is None:
+        return default
+
+    return getattr(obj, attr, default)
+
+
+def all_defined(*values: Any | None) -> bool:
+    """
+    Check if all provided values are defined (not None).
+
+    :param values: Variable number of values to check for None
+    :return: True if all values are not None, False otherwise
+    """
+    return all(value is not None for value in values)
+
+
+def safe_divide(
+    numerator: int | float | None,
+    denominator: int | float | None,
+    num_default: float = 0.0,
+    den_default: float = 1.0,
+) -> float:
+    """
+    Safely divide two numbers with None handling and zero protection.
+
+    :param numerator: Number to divide, or None to use num_default
+    :param denominator: Number to divide by, or None to use den_default
+    :param num_default: Default value for numerator if None
+    :param den_default: Default value for denominator if None
+    :return: Division result with protection against division by zero
+    """
+    numerator = numerator if numerator is not None else num_default
+    denominator = denominator if denominator is not None else den_default
+
+    return numerator / (denominator or 1e-10)
+
+
+def safe_multiply(*values: int | float | None, default: float = 1.0) -> float:
+    """
+    Safely multiply multiple numbers with None handling.
+
+    :param values: Variable number of values to multiply, None values treated as 1.0
+    :param default: Starting value for multiplication
+    :return: Product of all non-None values multiplied by default
+    """
+    result = default
+    for val in values:
+        result *= val if val is not None else 1.0
+    return result
+
+
+def safe_add(
+    *values: int | float | None, signs: list[int] | None = None, default: float = 0.0
+) -> float:
+    """
+    Safely add multiple numbers with None handling and optional signs.
+
+    :param values: Variable number of values to add, None values use default
+    :param signs: Optional list of 1 (add) or -1 (subtract) for each value.
+        If None, all values are added. Must match length of values.
+    :param default: Value to substitute for None values
+    :return: Result of adding all values safely (default used when value is None)
+    """
+    if not values:
+        return default
+
+    values = list(values)
+
+    if signs is None:
+        signs = [1] * len(values)
+
+    if len(signs) != len(values):
+        raise ValueError("Length of signs must match length of values")
+
+    result = values[0] if values[0] is not None else default
+
+    for ind in range(1, len(values)):
+        val = values[ind] if values[ind] is not None else default
+        result += signs[ind] * val
+
+    return result
+
+
+def safe_format_timestamp(
+    timestamp: float | None, format_: str = "%H:%M:%S", default: str = "N/A"
+) -> str:
+    """
+    Safely format a timestamp with error handling and validation.
+
+    :param timestamp: Unix timestamp to format, or None
+    :param format_: Strftime format string for timestamp formatting
+    :param default: Value to return if timestamp is invalid or None
+    :return: Formatted timestamp string or default value
+    """
+    try:
+        return datetime.fromtimestamp(timestamp).strftime(format_)
+    except (ValueError, TypeError, OverflowError, OSError):
+        return default