guidellm 0.4.0a21__py3-none-any.whl → 0.4.0a169__py3-none-any.whl

guidellm/mock_server/utils.py

@@ -0,0 +1,302 @@
+"""
+Mock server utilities for text generation and tokenization testing.
+
+This module provides mock tokenization and text generation utilities for testing
+guidellm's mock server functionality. It includes a mock tokenizer that simulates
+tokenization processes, functions to generate reproducible fake text with specific
+token counts, and timing generators for realistic benchmarking scenarios.
+"""
+
+from __future__ import annotations
+
+import random
+import re
+from collections.abc import Generator
+
+from faker import Faker
+from transformers.tokenization_utils import AddedToken, PreTrainedTokenizer, TextInput
+
+__all__ = [
+    "MockTokenizer",
+    "create_fake_text",
+    "create_fake_tokens_str",
+    "sample_number",
+    "times_generator",
+]
+
+
+class MockTokenizer(PreTrainedTokenizer):
+    """
+    Mock tokenizer implementation for testing text processing workflows.
+
+    Provides a simplified tokenizer that splits text using regex patterns and
+    generates deterministic token IDs based on string hashing. Used for testing
+    guidellm components without requiring actual model tokenizers.
+
+    :cvar VocabSize: Fixed vocabulary size for the mock tokenizer
+    """
+
+    VocabSize = 100000007
+
+    def __len__(self) -> int:
+        """
+        Get the vocabulary size of the tokenizer.
+
+        :return: The total number of tokens in the vocabulary
+        """
+        return self.VocabSize
+
+    def __call__(self, text: str | list[str], **kwargs) -> list[int]:  # noqa: ARG002
+        """
+        Tokenize text and return token IDs (callable interface).
+
+        :param text: Input text to tokenize
+        :return: List of token IDs
+        """
+        if isinstance(text, str):
+            tokens = self.tokenize(text)
+            return self.convert_tokens_to_ids(tokens)
+        elif isinstance(text, list):
+            # Handle batch processing
+            result = []
+            for t in text:
+                result.extend(self.__call__(t))
+            return result
+        else:
+            msg = f"text input must be of type `str` or `list[str]`, got {type(text)}"
+            raise ValueError(msg)
+
+    def tokenize(self, text: TextInput, **_kwargs) -> list[str]:  # type: ignore[override]
+        """
+        Tokenize input text into a list of token strings.
+
+        Splits text using regex to separate words, punctuation, and whitespace
+        into individual tokens for processing.
+
+        :param text: Input text to tokenize
+        :return: List of token strings from the input text
+        """
+        # Split text into tokens: words, spaces, and punctuation
+        return re.findall(r"\w+|[^\w\s]|\s+", text)
+
+    def convert_tokens_to_ids(self, tokens: str | list[str]) -> list[int]:
+        """
+        Convert token strings to numeric token IDs.
+
+        Uses deterministic hashing to generate consistent token IDs for
+        reproducible testing scenarios.
+
+        :param tokens: Single token string or list of token strings
+        :return: Single token ID or list of token IDs
+        """
+        if isinstance(tokens, str):
+            return [hash(tokens) % self.VocabSize]
+        return [hash(token) % self.VocabSize for token in tokens]
+
+    def convert_ids_to_tokens(  # type: ignore[override]
+        self, ids: list[int], _skip_special_tokens: bool = False
+    ) -> list[str]:
+        """
+        Convert numeric token IDs back to token strings.
+
+        Generates fake text tokens using Faker library seeded with token IDs
+        for deterministic and reproducible token generation.
+
+        :param ids: Single token ID or list of token IDs to convert
+        :return: Single token string or list of token strings
+        """
+        if not ids:
+            return [""]
+
+        fake = Faker()
+        fake.seed_instance(sum(ids) % self.VocabSize)
+
+        target_count = len(ids)
+        current_count = 0
+        tokens = []
+
+        while current_count < target_count:
+            text = fake.text(
+                max_nb_chars=(target_count - current_count) * 10  # oversample
+            )
+            new_tokens = self.tokenize(text)
+
+            if current_count > 0:
+                new_tokens = [".", " "] + new_tokens
+
+            new_tokens = (
+                new_tokens[: target_count - current_count]
+                if len(new_tokens) > (target_count - current_count)
+                else new_tokens
+            )
+            tokens += new_tokens
+            current_count += len(new_tokens)
+
+        return tokens
+
+    def convert_tokens_to_string(self, tokens: list[str]) -> str:
+        """
+        Convert a list of token strings back to a single text string.
+
+        :param tokens: List of token strings to concatenate
+        :return: Concatenated string from all tokens
+        """
+        return "".join(tokens)
+
+    def _add_tokens(
+        self,
+        new_tokens: list[str] | list[AddedToken],  # noqa: ARG002
+        special_tokens: bool = False,  # noqa: ARG002
+    ) -> int:
+        """
+        Add new tokens to the tokenizer vocabulary (mock implementation).
+
+        :param new_tokens: List of tokens to add to the vocabulary
+        :param special_tokens: Whether the tokens are special tokens
+        :return: Number of tokens actually added (always 0 for mock)
+        """
+        return 0
+
+    def apply_chat_template(  # type: ignore[override]
+        self,
+        conversation: list,
+        tokenize: bool = False,  # Changed default to False to match transformers
+        add_generation_prompt: bool = False,  # noqa: ARG002
+        **kwargs,  # noqa: ARG002
+    ) -> str | list[int]:
+        """
+        Apply a chat template to format conversation messages.
+
+        Mock implementation that concatenates all message content for testing.
+
+        :param conversation: List of chat messages
+        :param tokenize: Whether to return tokens or string
+        :param add_generation_prompt: Whether to add generation prompt
+        :return: Formatted text string or token IDs
+        """
+        # Simple concatenation of all message content
+        texts = []
+        for message in conversation:
+            if isinstance(message, dict) and "content" in message:
+                texts.append(message["content"])
+            elif hasattr(message, "content"):
+                texts.append(message.content)
+
+        formatted_text = " ".join(texts)
+
+        if tokenize:
+            return self.convert_tokens_to_ids(self.tokenize(formatted_text))
+        return formatted_text
+
+    def decode(  # type: ignore[override]
+        self,
+        token_ids: list[int],
+        skip_special_tokens: bool = True,
+        **kwargs,  # noqa: ARG002
+    ) -> str:
+        """
+        Decode token IDs back to text string.
+
+        :param token_ids: List of token IDs to decode
+        :param skip_special_tokens: Whether to skip special tokens
+        :return: Decoded text string
+        """
+        tokens = self.convert_ids_to_tokens(token_ids, skip_special_tokens)
+        return self.convert_tokens_to_string(tokens)
+
+
+def create_fake_text(
+    num_tokens: int,
+    processor: PreTrainedTokenizer,
+    seed: int = 42,
+    fake: Faker | None = None,
+) -> str:
+    """
+    Generate fake text using a tokenizer processor with specified token count.
+
+    Creates text by generating fake tokens and joining them into a string,
+    ensuring the result has the exact number of tokens when processed by
+    the given tokenizer.
+
+    :param num_tokens: Target number of tokens in the generated text
+    :param processor: Tokenizer to use for token generation and validation
+    :param seed: Random seed for reproducible text generation
+    :param fake: Optional Faker instance for text generation
+    :return: Generated text string with the specified token count
+    """
+    return "".join(create_fake_tokens_str(num_tokens, processor, seed, fake))
+
+
+def create_fake_tokens_str(
+    num_tokens: int,
+    processor: PreTrainedTokenizer,
+    seed: int = 42,
+    fake: Faker | None = None,
+) -> list[str]:
+    """
+    Generate fake token strings using a tokenizer processor.
+
+    Creates a list of token strings by generating fake text and tokenizing it
+    until the desired token count is reached. Uses the provided tokenizer
+    for accurate token boundary detection.
+
+    :param num_tokens: Target number of tokens to generate
+    :param processor: Tokenizer to use for token generation and validation
+    :param seed: Random seed for reproducible token generation
+    :param fake: Optional Faker instance for text generation
+    :return: List of token strings with the specified count
+    """
+    if not fake:
+        fake = Faker()
+    fake.seed_instance(seed)
+
+    tokens: list[str] = []
+
+    while len(tokens) < num_tokens:
+        text = fake.text(
+            max_nb_chars=(num_tokens - len(tokens)) * 30  # oversample
+        )
+        new_tokens = processor.tokenize(text)
+
+        if len(tokens) > 0:
+            new_tokens = [".", " "] + new_tokens
+
+        new_tokens = (
+            new_tokens[: num_tokens - len(tokens)]
+            if len(new_tokens) > (num_tokens - len(tokens))
+            else new_tokens
+        )
+        tokens += new_tokens
+
+    return tokens
+
+
+def times_generator(mean: float, standard_dev: float) -> Generator[float]:
+    """
+    Generate infinite timing values from a normal distribution.
+
+    Creates a generator that yields timing values sampled from a normal
+    distribution, useful for simulating realistic request timing patterns
+    in benchmarking scenarios.
+
+    :param mean: Mean value for the normal distribution
+    :param standard_dev: Standard deviation for the normal distribution
+    :return: Generator yielding positive timing values from the distribution
+    """
+    while True:
+        yield sample_number(mean, standard_dev)
+
+
+def sample_number(mean: float, standard_dev: float) -> float:
+    """
+    Generate a single timing value from a normal distribution.
+
+    Samples one timing value from a normal distribution with the specified
+    parameters, ensuring the result is non-negative for realistic timing
+    simulation in benchmarking scenarios.
+
+    :param mean: Mean value for the normal distribution
+    :param standard_dev: Standard deviation for the normal distribution
+    :return: Non-negative timing value from the distribution
+    """
+    return max(0.0, random.gauss(mean, standard_dev))

guidellm/preprocess/dataset.py

@@ -1,9 +1,9 @@
 import json
 import os
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from enum import Enum
 from pathlib import Path
-from typing import Any, Callable, Optional, Union
+from typing import Any
 
 import yaml
 from datasets import Dataset
@@ -11,7 +11,6 @@ from loguru import logger
 from pydantic import BaseModel, Field
 from transformers import PreTrainedTokenizerBase
 
-from guidellm.dataset import load_dataset as guidellm_load_dataset
 from guidellm.utils import IntegerRangeSampler, check_load_processor
 from guidellm.utils.hf_datasets import SUPPORTED_TYPES, save_dataset_to_file
 
@@ -32,7 +31,7 @@ def handle_ignore_strategy(
     min_prompt_tokens: int,
     tokenizer: PreTrainedTokenizerBase,
     **_kwargs,
-) -> Optional[str]:
+) -> str | None:
     """
     Ignores prompts that are shorter than the required minimum token length.
 
@@ -56,7 +55,7 @@ def handle_concatenate_strategy(
     tokenizer: PreTrainedTokenizerBase,
     concat_delimiter: str,
     **_kwargs,
-) -> Optional[str]:
+) -> str | None:
     """
     Concatenates prompts until the minimum token requirement is met.
 
@@ -117,7 +116,7 @@ def handle_error_strategy(
     min_prompt_tokens: int,
     tokenizer: PreTrainedTokenizerBase,
     **_kwargs,
-) -> Optional[str]:
+) -> str | None:
     """
     Raises an error if the prompt is too short.
 
@@ -150,24 +149,24 @@ class TokensConfig(BaseModel):
         description="The average number of tokens.",
         gt=0,
     )
-    stdev: Optional[int] = Field(
+    stdev: int | None = Field(
         description="The standard deviation of the tokens.",
         gt=0,
         default=None,
     )
-    min: Optional[int] = Field(
+    min: int | None = Field(
         description="The minimum number of tokens.",
         gt=0,
         default=None,
     )
-    max: Optional[int] = Field(
+    max: int | None = Field(
         description="The maximum number of tokens.",
         gt=0,
         default=None,
     )
 
     @staticmethod
-    def parse_str(data: Union[str, Path]) -> "TokensConfig":
+    def parse_str(data: str | Path) -> "TokensConfig":
         """
         Parses a string or path into a TokensConfig object. Supports:
         - JSON string
@@ -215,14 +214,14 @@ class TokensConfig(BaseModel):
         return TokensConfig(**config_dict)  # type: ignore[arg-type]
 
     @staticmethod
-    def parse_config_file(data: Union[str, Path]) -> "TokensConfig":
+    def parse_config_file(data: str | Path) -> "TokensConfig":
         with Path(data).open("r") as file:
             config_dict = yaml.safe_load(file)
 
         return TokensConfig(**config_dict)
 
 
-def _validate_output_suffix(output_path: Union[str, Path]) -> None:
+def _validate_output_suffix(output_path: str | Path) -> None:
     output_path = Path(output_path)
     suffix = output_path.suffix.lower()
     if suffix not in SUPPORTED_TYPES:
@@ -233,18 +232,18 @@ def _validate_output_suffix(output_path: Union[str, Path]) -> None:
 
 
 def process_dataset(
-    data: Union[str, Path],
-    output_path: Union[str, Path],
-    processor: Union[str, Path, PreTrainedTokenizerBase],
-    prompt_tokens: Union[str, Path],
-    output_tokens: Union[str, Path],
-    processor_args: Optional[dict[str, Any]] = None,
-    data_args: Optional[dict[str, Any]] = None,
+    data: str | Path,
+    output_path: str | Path,
+    processor: str | Path | PreTrainedTokenizerBase,
+    prompt_tokens: str | Path,
+    output_tokens: str | Path,
+    processor_args: dict[str, Any] | None = None,
+    data_args: dict[str, Any] | None = None,
     short_prompt_strategy: ShortPromptStrategy = ShortPromptStrategy.IGNORE,
-    pad_char: Optional[str] = None,
-    concat_delimiter: Optional[str] = None,
+    pad_char: str | None = None,
+    concat_delimiter: str | None = None,
     push_to_hub: bool = False,
-    hub_dataset_id: Optional[str] = None,
+    hub_dataset_id: str | None = None,
     random_seed: int = 42,
 ) -> None:
     """
@@ -271,9 +270,7 @@ def process_dataset(
         f"Starting dataset conversion | Input: {data} | Output directory: {output_path}"
     )
 
-    dataset, column_mappings = guidellm_load_dataset(
-        data, data_args, processor, processor_args
-    )
+    dataset, column_mappings = None, None
     tokenizer = check_load_processor(
         processor,
         processor_args,
@@ -354,7 +351,7 @@ def process_dataset(
 
 
 def push_dataset_to_hub(
-    hub_dataset_id: Optional[str],
+    hub_dataset_id: str | None,
     processed_dataset: Dataset,
 ) -> None:
     """

guidellm/presentation/builder.py

@@ -1,9 +1,9 @@
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from guidellm.benchmark.benchmark import GenerativeBenchmark
+    from guidellm.benchmark import GenerativeBenchmark
 
-from .data_models import BenchmarkDatum, RunInfo, WorkloadDetails
+from guidellm.presentation.data_models import BenchmarkDatum, RunInfo, WorkloadDetails
 
 
 class UIDataBuilder:

guidellm/presentation/data_models.py

@@ -1,25 +1,25 @@
 import random
 from collections import defaultdict
 from math import ceil
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, computed_field
 
 if TYPE_CHECKING:
-    from guidellm.benchmark.benchmark import GenerativeBenchmark
+    from guidellm.benchmark import GenerativeBenchmark
 
-from guidellm.objects.statistics import DistributionSummary
+from guidellm.utils import DistributionSummary
 
 
 class Bucket(BaseModel):
-    value: Union[float, int]
+    value: float | int
     count: int
 
     @staticmethod
     def from_data(
-        data: Union[list[float], list[int]],
-        bucket_width: Optional[float] = None,
-        n_buckets: Optional[int] = None,
+        data: list[float] | list[int],
+        bucket_width: float | None = None,
+        n_buckets: int | None = None,
     ) -> tuple[list["Bucket"], float]:
         if not data:
             return [], 1.0
@@ -35,7 +35,7 @@ class Bucket(BaseModel):
         else:
             n_buckets = ceil(range_v / bucket_width)
 
-        bucket_counts: defaultdict[Union[float, int], int] = defaultdict(int)
+        bucket_counts: defaultdict[float | int, int] = defaultdict(int)
         for val in data:
             idx = int((val - min_v) // bucket_width)
             if idx >= n_buckets:
@@ -67,12 +67,12 @@ class RunInfo(BaseModel):
 
     @classmethod
     def from_benchmarks(cls, benchmarks: list["GenerativeBenchmark"]):
-        model = benchmarks[0].worker.backend_model or "N/A"
+        model = benchmarks[0].benchmarker.backend.get("model", "N/A")
         timestamp = max(
             bm.run_stats.start_time for bm in benchmarks if bm.start_time is not None
         )
         return cls(
-            model=Model(name=model, size=0),
+            model=Model(name=model or "", size=0),
             task="N/A",
             timestamp=timestamp,
             dataset=Dataset(name="N/A"),
@@ -80,7 +80,7 @@ class RunInfo(BaseModel):
 
 
 class Distribution(BaseModel):
-    statistics: Optional[DistributionSummary] = None
+    statistics: DistributionSummary | None = None
     buckets: list[Bucket]
     bucket_width: float
 
@@ -108,8 +108,8 @@ class WorkloadDetails(BaseModel):
 
     @classmethod
     def from_benchmarks(cls, benchmarks: list["GenerativeBenchmark"]):
-        target = benchmarks[0].worker.backend_target
-        rate_type = benchmarks[0].args.profile.type_
+        target = benchmarks[0].benchmarker.backend.get("target", "N/A")
+        rate_type = benchmarks[0].scheduler.strategy.type_
         successful_requests = [
             req for bm in benchmarks for req in bm.requests.successful
         ]
@@ -117,21 +117,25 @@ class WorkloadDetails(BaseModel):
             range(len(successful_requests)), min(5, len(successful_requests))
         )
         sample_prompts = [
-            successful_requests[i].prompt.replace("\n", " ").replace('"', "'")
+            req.request_args.replace("\n", " ").replace('"', "'")
+            if (req := successful_requests[i]).request_args
+            else ""
             for i in sample_indices
         ]
         sample_outputs = [
-            successful_requests[i].output.replace("\n", " ").replace('"', "'")
+            req.output.replace("\n", " ").replace('"', "'")
+            if (req := successful_requests[i]).output
+            else ""
             for i in sample_indices
         ]
 
         prompt_tokens = [
-            float(req.prompt_tokens)
+            float(req.prompt_tokens) if req.prompt_tokens is not None else -1
             for bm in benchmarks
             for req in bm.requests.successful
         ]
         output_tokens = [
-            float(req.output_tokens)
+            float(req.output_tokens) if req.output_tokens is not None else -1
             for bm in benchmarks
             for req in bm.requests.successful
         ]
@@ -152,13 +156,13 @@ class WorkloadDetails(BaseModel):
             statistics=output_token_stats, buckets=output_token_buckets, bucket_width=1
         )
 
-        min_start_time = benchmarks[0].run_stats.start_time
+        min_start_time = benchmarks[0].start_time
 
         all_req_times = [
-            req.start_time - min_start_time
+            req.info.timings.request_start - min_start_time
             for bm in benchmarks
             for req in bm.requests.successful
-            if req.start_time is not None
+            if req.info.timings.request_start is not None
         ]
         number_of_buckets = len(benchmarks)
         request_over_time_buckets, bucket_width = Bucket.from_data(
@@ -190,7 +194,7 @@ class TabularDistributionSummary(DistributionSummary):
     """
 
     @computed_field
-    def percentile_rows(self) -> list[dict[str, Union[str, float]]]:
+    def percentile_rows(self) -> list[dict[str, str | float]]:
         rows = [
             {"percentile": name, "value": value}
             for name, value in self.percentiles.model_dump().items()

guidellm/presentation/injector.py

@@ -1,14 +1,13 @@
 import re
 from pathlib import Path
-from typing import Union
 
 from loguru import logger
 
-from guidellm.config import settings
+from guidellm.settings import settings
 from guidellm.utils.text import load_text
 
 
-def create_report(js_data: dict, output_path: Union[str, Path]) -> Path:
+def create_report(js_data: dict, output_path: str | Path) -> Path:
     """
     Creates a report from the dictionary and saves it to the output path.