most-queue 2.9__py3-none-any.whl → 2.11__py3-none-any.whl

most_queue/io/serving.py

@@ -0,0 +1,258 @@
+"""Audited request-level serving measurements and joint TTFT/TPOT SLOs.
+
+Reference serializer: vLLM v0.33.0rc3, commit
+4ba787ec9959e566d3b587a796dff07673324da5, vllm/benchmarks/serve.py.
+TTFT and latency are client measurements; queue_times is CLIENT semaphore
+waiting. Server timings are separate optional measurements, never inferred.
+The SGLang array reader explicitly uses the span of streamed output events
+when full per-request latencies are absent. See docs/serving_measurements.md.
+"""
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ServingRequest:
+    """One offered request; all durations are seconds and counts are actual.
+
+    A pending request has an unknown final latency/TPOT. Failed and cancelled
+    requests remain in the offered denominator. An absent measurement is None.
+    """
+
+    input_tokens: int
+    output_tokens: int
+    status: str
+    ttft: float | None = None
+    latency: float | None = None
+    client_queue_time: float | None = None
+    server_queue_time: float | None = None
+    server_ttft: float | None = None
+
+    def __post_init__(self):
+        if self.status not in {"completed", "failed", "cancelled", "pending"}:
+            raise ValueError("unknown request status")
+        for count in (self.input_tokens, self.output_tokens):
+            if isinstance(count, bool) or not isinstance(count, (int, np.integer)) or count < 0:
+                raise ValueError("token counts must be nonnegative integers")
+        for value in (self.ttft, self.latency, self.client_queue_time, self.server_queue_time, self.server_ttft):
+            if value is not None and (not math.isfinite(value) or value < 0):
+                raise ValueError("measured durations must be finite and nonnegative, or None")
+        if self.status == "completed":
+            if min(self.input_tokens, self.output_tokens) < 1 or self.ttft is None or self.latency is None:
+                raise ValueError("completed text requests require positive lengths, TTFT and latency")
+            if self.latency < self.ttft:
+                raise ValueError("latency cannot precede the first token")
+        elif self.latency is not None:
+            raise ValueError("only completed requests have a final latency")
+
+    @property
+    def tpot(self):
+        """Per-request TPOT, excluding the first token; None for <=1 token."""
+        if self.status != "completed" or self.output_tokens <= 1:
+            return None
+        return (self.latency - self.ttft) / (self.output_tokens - 1)
+
+
+@dataclass(frozen=True)
+class ServingBenchmark:
+    """A finite offered cohort and its explicit measurement-window duration."""
+
+    requests: tuple[ServingRequest, ...]
+    duration: float
+    metadata: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.requests or not all(isinstance(row, ServingRequest) for row in self.requests):
+            raise ValueError("a benchmark requires a nonempty request cohort")
+        if not math.isfinite(self.duration) or self.duration <= 0:
+            raise ValueError("duration must be finite and positive")
+
+
+def _read_arrays(source, schema):
+    data = json.loads(Path(source).read_text(encoding="utf-8")) if isinstance(source, (str, Path)) else source
+    if not isinstance(data, dict):
+        raise ValueError("expected a single benchmark JSON object")
+    required = ["input_lens", "output_lens", "ttfts", "errors"]
+    required += ["latencies"] if schema == "vllm-bench-serve" else ["itls"]
+    if any(not isinstance(data.get(key), list) for key in required):
+        raise ValueError("detailed per-request arrays are required; aggregate percentiles are insufficient")
+    count = len(data["input_lens"])
+    if not count or any(len(data[key]) != count for key in required):
+        raise ValueError("per-request arrays must be nonempty and aligned")
+    optional = ["queue_times", "server_queue_times", "server_ttfts"]
+    for key in optional:
+        if key in data and (not isinstance(data[key], list) or len(data[key]) != count):
+            raise ValueError(f"{key} must align with the request arrays")
+    rows = []
+    for index in range(count):
+        error = data["errors"][index]
+        if not isinstance(error, str):
+            raise ValueError("each error must be a string")
+        completed = error == "" and data["output_lens"][index] > 0
+        latency = None
+        if completed:
+            if schema == "vllm-bench-serve":
+                latency = data["latencies"][index]
+            else:
+                gaps = np.asarray(data["itls"][index], dtype=float)
+                if gaps.ndim != 1 or not np.all(np.isfinite(gaps)) or np.any(gaps < 0):
+                    raise ValueError("stream gaps must be finite nonnegative vectors")
+                latency = float(data["ttfts"][index] + gaps.sum())
+        timings = {key: data[key][index] if completed and key in data else None for key in optional}
+        rows.append(
+            ServingRequest(
+                input_tokens=data["input_lens"][index],
+                output_tokens=data["output_lens"][index],
+                status="completed" if completed else "failed",
+                ttft=data["ttfts"][index] if completed else None,
+                latency=latency,
+                client_queue_time=timings["queue_times"],
+                server_queue_time=timings["server_queue_times"],
+                server_ttft=timings["server_ttfts"],
+            )
+        )
+    successes = sum(row.status == "completed" for row in rows)
+    if data.get("completed") != successes or ("failed" in data and data["failed"] != count - successes):
+        raise ValueError("aggregate completion/failure counts disagree with detailed outcomes")
+    if "num_prompts" in data and data["num_prompts"] != count:
+        raise ValueError("num_prompts disagrees with offered cohort; do not silently drop requests")
+    metadata = {
+        key: data[key]
+        for key in ["model_id", "backend", "max_concurrency", "request_rate", "dataset_name"]
+        if key in data
+    }
+    metadata.update(schema=schema, latency_basis="client_latency" if schema == "vllm-bench-serve" else "stream_span")
+    if metadata.get("request_rate") == math.inf:
+        metadata["request_rate"] = "inf"
+    return ServingBenchmark(tuple(rows), data["duration"], metadata)
+
+
+def read_vllm_benchmark(source, *, measurement_profile=None):
+    """Read vLLM detailed JSON; preserve absent server metrics as None.
+
+    The caller must retain the producer version and hardware provenance. This
+    is a schema adapter, not detection of the engine/version from latency data.
+    """
+    result = _read_arrays(source, "vllm-bench-serve")
+    result.metadata["measurement_profile"] = measurement_profile
+    return result
+
+
+def read_sglang_stream_benchmark(source, *, measurement_profile=None):
+    """Read detailed streaming arrays with TTFT + sum(ITL) as observed span.
+
+    The span ends at the last output event, not necessarily HTTP completion.
+    ITL entries can contain multiple tokens; TPOT uses actual output_tokens.
+    """
+    result = _read_arrays(source, "sglang-stream-arrays")
+    result.metadata["measurement_profile"] = measurement_profile
+    return result
+
+
+def _quantiles(values):
+    if not values:
+        return None
+    return {
+        "count": len(values),
+        "mean": float(np.mean(values)),
+        **dict(zip(["p50", "p90", "p99"], np.percentile(values, [50, 90, 99]).tolist())),
+    }
+
+
+def summarize_serving_slo(benchmark, *, ttft_limit, tpot_limit):
+    """Joint request SLO with all offered outcomes and pending-outcome bounds.
+
+    Completed one-token replies pass the TPOT condition by the vLLM goodput
+    convention but are excluded from TPOT means/quantiles. Pending requests
+    are unknown unless their already-observed TTFT violates its limit.
+    Counts/quantiles describe this cohort, without an iid confidence claim.
+    """
+    if any(not math.isfinite(value) or value < 0 for value in (ttft_limit, tpot_limit)):
+        raise ValueError("SLO limits must be finite nonnegative seconds")
+    counts = {status: 0 for status in ["completed", "failed", "cancelled", "pending"]}
+    passed, unknown, single_token = 0, 0, 0
+    ttfts, tpots = [], []
+    for row in benchmark.requests:
+        counts[row.status] += 1
+        if row.status == "completed":
+            ttfts.append(row.ttft)
+            if row.tpot is None:
+                single_token += 1
+            else:
+                tpots.append(row.tpot)
+            passed += row.ttft <= ttft_limit and (row.tpot is None or row.tpot <= tpot_limit)
+        elif row.status == "pending" and (row.ttft is None or row.ttft <= ttft_limit):
+            unknown += 1
+    offered = len(benchmark.requests)
+    return {
+        "offered": offered,
+        **counts,
+        "single_token_completed": single_token,
+        "joint_passed": passed,
+        "joint_unknown": unknown,
+        "joint_fraction_bounds": [passed / offered, (passed + unknown) / offered],
+        "observed_goodput": passed / benchmark.duration,
+        "duration": benchmark.duration,
+        "ttft_limit": ttft_limit,
+        "tpot_limit": tpot_limit,
+        "completed_ttft_seconds": _quantiles(ttfts),
+        "completed_multitoken_tpot_seconds": _quantiles(tpots),
+        "server_queue_observed": sum(row.server_queue_time is not None for row in benchmark.requests),
+        "server_ttft_observed": sum(row.server_ttft is not None for row in benchmark.requests),
+        "latency_basis": benchmark.metadata.get("latency_basis", "explicit_request_records"),
+        "uncertainty": "pending-outcome bounds; no iid confidence interval",
+    }
+
+
+def from_prefill_decode(result, arrivals, inputs, outputs, *, horizon=None):
+    """Convert token DES timestamps; optionally censor at a fixed horizon.
+
+    Future requests are outside the offered cohort. Future completions and
+    tokens are hidden rather than counted as successful outcomes at the cut.
+    No steady-state or stationarity assertion is made for the drained cohort.
+    """
+    arrivals = np.asarray(arrivals, dtype=float)
+    if arrivals.ndim != 1 or not arrivals.size or not np.all(np.isfinite(arrivals)) or np.any(np.diff(arrivals) < 0):
+        raise ValueError("arrivals must be nonempty finite chronological times")
+    if any(len(values) != len(arrivals) for values in [inputs, outputs, result.output_times, result.completion_times]):
+        raise ValueError("DES arrays must align")
+    for lengths in (inputs, outputs):
+        values = np.asarray(lengths, dtype=float)
+        if not np.all(np.isfinite(values)) or np.any(values <= 0) or np.any(values != np.floor(values)):
+            raise ValueError("DES token lengths must be positive integers")
+    for arrival, count, stamps, completion in zip(arrivals, outputs, result.output_times, result.completion_times):
+        stamps = np.asarray(stamps, dtype=float)
+        if stamps.ndim != 1 or stamps.size != count or not np.all(np.isfinite(stamps)):
+            raise ValueError("DES token timestamps must align with output lengths and be finite")
+        if (
+            np.any(np.diff(stamps) < 0)
+            or stamps[0] < arrival
+            or not math.isfinite(completion)
+            or stamps[-1] != completion
+        ):
+            raise ValueError("DES token timestamps, output lengths and completion must agree")
+    end = max(result.completion_times) if horizon is None else horizon
+    if not math.isfinite(end) or end <= arrivals[0]:
+        raise ValueError("observation horizon must follow the first arrival")
+    rows = []
+    for index, arrival in enumerate(arrivals):
+        if arrival > end:
+            break
+        tokens = result.output_times[index]
+        observed = [stamp for stamp in tokens if stamp <= end]
+        completed = result.completion_times[index] <= end
+        rows.append(
+            ServingRequest(
+                input_tokens=int(inputs[index]),
+                output_tokens=int(outputs[index]) if completed else len(observed),
+                status="completed" if completed else "pending",
+                ttft=tokens[0] - arrival if observed else None,
+                latency=result.completion_times[index] - arrival if completed else None,
+            )
+        )
+    return ServingBenchmark(tuple(rows), float(end - arrivals[0]), {"latency_basis": "token_DES"})

most_queue/random/feature_service.py

@@ -0,0 +1,175 @@
+"""History-only conditional ECDFs with audited fallback and optional scale ratios.
+
+CRPS uses the empirical energy identity, Gneiting & Raftery (2007),
+https://doi.org/10.1198/016214506000001437. It scores a full predictive CDF,
+not a random sample from it. Feature availability must be established by callers.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+from numbers import Integral, Real
+
+import numpy as np
+
+from most_queue.random.service_calibration import ServiceCalibration
+from most_queue.random.trace_resampling import ConditionalEmpirical
+
+
+def _positive(value, name):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Real) or not np.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be positive and finite")
+    return float(value)
+
+
+def _need(value):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Integral) or value < 1:
+        raise ValueError("need must be a positive integer")
+    return int(value)
+
+
+def _context(value):
+    if value is not None and (not isinstance(value, str) or not value):
+        raise ValueError("context must be a nonempty string or None")
+    return value
+
+
+def request_bucket(request):
+    """Fixed right-closed request bins in seconds; unknown is distinct from zero."""
+    if request is None:
+        return None
+    value = _positive(request, "request")
+    return str(int(np.searchsorted([300, 1800, 7200, 28800, 86400], value)))
+
+
+@dataclass(frozen=True)
+class EmpiricalPrediction:
+    """An immutable selected ECDF, positive target scale and audited fit level."""
+
+    distribution: ServiceCalibration
+    scale: float = 1.0
+    level: str = "pooled"
+
+    def __post_init__(self):
+        _positive(self.scale, "scale")
+        # Check the support before sampling, not only the selected quantile.
+        _positive(self.scale * self.distribution.samples[-1], "scaled support")
+        _positive(self.scale * self.distribution.samples[0], "scaled support")
+
+    @property
+    def mean(self):
+        """Predictive mean in service-time units, not ratio units."""
+        return self.scale * self.distribution.mean
+
+    def quantile(self, probability):
+        """Inverse discrete ECDF; no interpolation or truncation at runtime budget."""
+        if isinstance(probability, (bool, np.bool_)) or not isinstance(probability, Real):
+            raise ValueError("probability must be a finite real in (0,1)")
+        return float(self.scale * self.distribution.quantiles("empirical", [probability])[0])
+
+    def probability_exceeding(self, threshold):
+        """Return P(S > threshold), with equality counted as within the budget."""
+        threshold = _positive(threshold, "threshold")
+        support = np.array(self.distribution.samples) * self.scale
+        return float(np.mean(support > threshold))
+
+    def crps(self, observed):
+        """Compute E|X-y| - .5 E|X-X'| exactly for a finite equal-weight ECDF.
+
+        For sorted support x_i the second term is sum((2i-n-1)x_i)/n².
+        Scaling before evaluation keeps score units in seconds for ratio fits.
+        """
+        observed = _positive(observed, "observed")
+        support = np.asarray(self.distribution.samples) * self.scale
+        n = len(support)
+        dispersion = np.dot((2 * np.arange(1, n + 1) - n - 1) / n, support) / n
+        score = float(np.mean(np.abs(support - observed)) - dispersion)
+        if not np.isfinite(score):
+            raise ValueError("CRPS overflow; rescale observations")
+        return max(0.0, score)
+
+
+@dataclass(frozen=True)
+class FeatureConditionalEmpirical:
+    """Joint context/need cells, then coarse/pooled fallback; fit uses history only.
+
+    Optional scales fit service/scale on known positive scales, multiplying by
+    the supplied target scale at prediction. Unknown target scale or absent
+    ratio history falls back to absolute service. No outcome or test S is used.
+    """
+
+    absolute: ConditionalEmpirical
+    pooled: ServiceCalibration | None
+    coarse: dict
+    joint: dict
+    exact_joint: dict
+    ratio: bool
+    audit: dict
+
+    @classmethod
+    def fit(
+        cls, needs, services, contexts, *, scales=None, exact=False, minimum=20
+    ):  # pylint: disable=too-many-arguments
+        """Fit context ECDFs with a fixed minimum count and explicit missing scales."""
+        needs, contexts = tuple(needs), tuple(contexts)
+        if len(contexts) != len(needs):
+            raise ValueError("contexts must match needs")
+        needs = tuple(_need(value) for value in needs)
+        contexts = tuple(_context(value) for value in contexts)
+        absolute = ConditionalEmpirical.fit(needs, services, minimum=minimum)
+        if not isinstance(exact, bool):
+            raise ValueError("exact must be boolean")
+        values = np.asarray(services, dtype=float)
+        ratio = scales is not None
+        scales = tuple(scales) if ratio else (1.0,) * len(needs)
+        if len(scales) != len(needs):
+            raise ValueError("scales must match needs")
+        pools = {"coarse": defaultdict(list), "joint": defaultdict(list), "exact": defaultdict(list)}
+        normalized = []
+        for need, service, context, scale in zip(needs, values, contexts, scales):
+            if scale is None:
+                continue
+            value = _positive(service / _positive(scale, "scale"), "scaled service")
+            group = int(np.searchsorted([1, 8, 32], need))
+            normalized.append(value)
+            pools["coarse"][group].append(value)
+            pools["joint"][group, context].append(value)
+            if exact:
+                pools["exact"][need, context].append(value)
+        fitted = {
+            name: {key: ServiceCalibration.fit(sample) for key, sample in cells.items() if len(sample) >= minimum}
+            for name, cells in pools.items()
+        }
+        pooled = ServiceCalibration.fit(normalized) if len(normalized) >= 2 else None
+        audit = {
+            "history_count": len(needs),
+            "scaled_count": len(normalized),
+            "missing_scale_count": sum(s is None for s in scales),
+            "minimum": int(minimum),
+            "exact": exact,
+            "ratio": ratio,
+            "fitted_cells": {name: len(cells) for name, cells in fitted.items()},
+        }
+        return cls(absolute, pooled, fitted["coarse"], fitted["joint"], fitted["exact"], ratio, audit)
+
+    def predict(self, need, context, *, scale=None):
+        """Return the complete predictive distribution and the fallback used."""
+        need, context = _need(need), _context(context)
+        if scale is not None:
+            _positive(scale, "scale")
+        if self.ratio and (scale is None or self.pooled is None):
+            distribution, level = self.absolute.distribution(need)
+            return EmpiricalPrediction(distribution, 1.0, f"absolute_{level}")
+        if not self.ratio and scale is not None:
+            raise ValueError("scale is only valid for a ratio fit")
+        factor = float(scale) if self.ratio else 1.0
+        group = int(np.searchsorted([1, 8, 32], need))
+        choices = (
+            (self.exact_joint.get((need, context)), "exact_context"),
+            (self.joint.get((group, context)), "coarse_context"),
+            (self.coarse.get(group), "coarse"),
+            (self.pooled, "pooled"),
+        )
+        for distribution, level in choices:
+            if distribution is not None:
+                return EmpiricalPrediction(distribution, factor, level)
+        raise ValueError("no predictive distribution available")

most_queue/random/marked_arrivals.py

@@ -0,0 +1,127 @@
+"""Empirical marked arrivals with zero gaps and explicit matched controls.
+
+Circular blocks use the end-to-start convention documented at
+https://bashtage.github.io/arch/bootstrap/generated/arch.bootstrap.CircularBlockBootstrap.html.
+This is a workload generator, not a stationarity assumption or population CI.
+"""
+
+from dataclasses import dataclass, replace
+from numbers import Integral, Real
+
+import numpy as np
+
+from most_queue.random.trace_resampling import circular_block_indices
+
+
+def _count(value, name, minimum=1):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Integral) or value < minimum:
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+    return int(value)
+
+
+def _real(value, name, minimum=0):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Real) or not np.isfinite(value) or value < minimum:
+        raise ValueError(f"{name} must be finite and >= {minimum}")
+    return float(value)
+
+
+@dataclass(frozen=True)
+class ArrivalMark:
+    """A preceding gap in seconds, resource demand, and a coupled feature bundle."""
+
+    gap: float
+    need: int
+    context: str | None = None
+    requested_time: float | None = None
+
+    def __post_init__(self):
+        _real(self.gap, "gap")
+        _count(self.need, "need")
+        if self.context is not None and (not isinstance(self.context, str) or not self.context):
+            raise ValueError("context must be a nonempty string or None")
+        if self.requested_time is not None:
+            _real(self.requested_time, "requested_time")
+            if self.requested_time == 0:
+                raise ValueError("requested_time must be positive or None")
+
+
+@dataclass(frozen=True)
+class MarkedArrivalBootstrap:
+    """Immutable donor tuples; callers must supply a temporally valid history."""
+
+    donors: tuple[ArrivalMark, ...]
+
+    def __post_init__(self):
+        object.__setattr__(self, "donors", tuple(self.donors))
+        if not self.donors or any(not isinstance(item, ArrivalMark) for item in self.donors):
+            raise ValueError("donors must be nonempty ArrivalMark records")
+
+    @classmethod
+    def fit(cls, arrivals, needs, contexts, requested_times=None):
+        """Form true adjacent gaps; the first row supplies only a predecessor.
+
+        Equal timestamps are retained without jitter. Filtering history before
+        calling this method changes adjacency and is the caller's responsibility.
+        """
+        arrivals, needs, contexts = tuple(arrivals), tuple(needs), tuple(contexts)
+        requests = (None,) * len(arrivals) if requested_times is None else tuple(requested_times)
+        if len(arrivals) < 2 or not len(arrivals) == len(needs) == len(contexts) == len(requests):
+            raise ValueError("history fields must match and contain at least two rows")
+        times = np.array([_real(value, "arrival") for value in arrivals])
+        gaps = np.diff(times)
+        if np.any(gaps < 0):
+            raise ValueError("arrivals must be chronological")
+        # Validate the predecessor's fields too; it is not itself a donor.
+        records = tuple(
+            ArrivalMark(float(gap), need, context, request)
+            for gap, need, context, request in zip(np.r_[0, gaps], needs, contexts, requests)
+        )
+        return cls(records[1:])
+
+    def sample(self, uniforms, *, block_length=1):
+        """Select uniform donor starts, wrap fixed blocks, and truncate to size."""
+        indices = circular_block_indices(len(self.donors), uniforms, block_length)
+        return tuple(self.donors[int(index)] for index in indices)
+
+
+def anchored_permutation(uniforms, warmup):
+    """Shuffle each cohort partition with its first row fixed, using stable keys.
+
+    Keeping rows 0 and warmup fixed preserves the first arrival and measured
+    arrival horizon when whole gap/mark/service tuples move together.
+    """
+    values = np.asarray(uniforms)
+    if values.ndim != 1 or not values.size or values.dtype.kind not in "iuf" or not np.all(np.isfinite(values)):
+        raise ValueError("uniform keys must be a nonempty finite numeric vector")
+    if np.any((values <= 0) | (values >= 1)):
+        raise ValueError("uniform keys must lie strictly inside (0,1)")
+    warmup = _count(warmup, "warmup", minimum=0)
+    if warmup >= len(values):
+        raise ValueError("warmup must leave measured jobs")
+    order = np.arange(len(values))
+    for begin, end in ((0, warmup), (warmup, len(values))):
+        if end > begin + 1:
+            order[begin + 1 : end] = begin + 1 + np.argsort(values[begin + 1 : end], kind="stable")
+    return order
+
+
+def decouple_gaps(records, order):
+    """Retain each gap while moving coupled need/context/request bundles."""
+    records, order = tuple(records), np.asarray(order)
+    if order.ndim != 1 or order.dtype.kind not in "iu" or sorted(order.tolist()) != list(range(len(records))):
+        raise ValueError("order must be a complete permutation of records")
+    if not records or any(not isinstance(item, ArrivalMark) for item in records):
+        raise ValueError("records must be nonempty ArrivalMark records")
+    return tuple(replace(records[int(index)], gap=record.gap) for record, index in zip(records, order))
+
+
+def arrival_times(records):
+    """Accumulate nonnegative gaps, anchoring the first job at zero."""
+    records = tuple(records)
+    if not records or any(not isinstance(item, ArrivalMark) for item in records):
+        raise ValueError("records must be nonempty ArrivalMark records")
+    with np.errstate(over="ignore"):
+        values = np.cumsum([record.gap for record in records]) - records[0].gap
+    if not np.all(np.isfinite(values)):
+        raise ValueError("cumulative arrival timestamps overflow")
+    return values

most_queue/random/queue_selection.py

@@ -0,0 +1,47 @@
+"""Select a service model using positive queue summaries from validation only.
+
+The mean absolute log error is an explicitly chosen downstream objective,
+not a proper distributional scoring rule. Callers own temporal separation,
+cohort comparability and aggregation over Monte Carlo replications.
+"""
+
+from collections.abc import Mapping
+
+import numpy as np
+
+
+def _metrics(values):
+    array = np.asarray(values)
+    if array.dtype.kind not in "iuf" or array.size == 0 or not np.all(np.isfinite(array)) or np.any(array <= 0):
+        raise ValueError("queue metrics must be nonempty, finite, positive real values")
+    return array.astype(float)
+
+
+def queue_log_error(predicted, observed):
+    """Mean |log(predicted)-log(observed)| with equal weights and exact shapes.
+
+    Pass MC means when comparing expected queue summaries. Zero references are
+    rejected, never stabilized with an implicit epsilon. Log differences avoid
+    overflow in a ratio of valid finite metrics.
+    """
+    predicted, observed = _metrics(predicted), _metrics(observed)
+    if predicted.shape != observed.shape:
+        raise ValueError("predicted and observed shapes must match exactly")
+    return float(np.mean(np.abs(np.log(predicted) - np.log(observed))))
+
+
+def select_queue_model(predictions, observed, *, candidate_order):
+    """Score supplied validation summaries; break exact ties in declared order.
+
+    Predictions maps every candidate name to an array with the observed shape.
+    This function neither fits a model nor reads held-out outcomes.
+    """
+    if isinstance(candidate_order, (str, bytes)):
+        raise ValueError("candidate_order must be a sequence of unique names")
+    order = tuple(candidate_order)
+    if not order or any(not isinstance(name, str) or not name for name in order) or len(set(order)) != len(order):
+        raise ValueError("candidate_order must contain unique nonempty names")
+    if not isinstance(predictions, Mapping) or set(predictions) != set(order):
+        raise ValueError("predictions must contain exactly the declared candidates")
+    losses = {name: queue_log_error(predictions[name], observed) for name in order}
+    return {"selected": min(order, key=losses.get), "losses": losses, "candidate_order": list(order)}