localarena 0.1.0__py3-none-any.whl

localarena/__init__.py

@@ -0,0 +1,25 @@
+"""A deterministic, zero-dependency Elo arena."""
+
+from .core import (
+    SCHEMA_VERSION,
+    Arena,
+    Contestant,
+    Match,
+    Result,
+    Standing,
+    expected_score,
+    round_robin,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Arena",
+    "Contestant",
+    "Match",
+    "Result",
+    "Standing",
+    "expected_score",
+    "round_robin",
+]
+
+__version__ = "0.1.0"

localarena/core.py

@@ -0,0 +1,770 @@
+"""Core data structures and Elo logic for :mod:`localarena`."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from itertools import combinations
+from types import MappingProxyType
+from typing import Any
+
+SCHEMA_VERSION = 1
+_MAX_SAFE_INTEGER = (1 << 53) - 1
+_MAX_METADATA_DEPTH = 100
+
+
+class Result(str, Enum):
+    """The outcome of a match, expressed relative to its two sides."""
+
+    LEFT = "left"
+    RIGHT = "right"
+    DRAW = "draw"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class _FrozenDict(Mapping[str, object]):
+    """A recursively immutable mapping used by public records."""
+
+    __slots__ = ("__data",)
+
+    def __init__(self, data: Mapping[str, object]) -> None:
+        object.__setattr__(
+            self,
+            "_FrozenDict__data",
+            MappingProxyType(dict(data)),
+        )
+
+    def __getitem__(self, key: str) -> object:
+        return self.__data[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.__data)
+
+    def __len__(self) -> int:
+        return len(self.__data)
+
+    def __repr__(self) -> str:
+        return repr(self.__data)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise TypeError("metadata is immutable")
+
+    def __deepcopy__(self, memo: dict[int, object]) -> _FrozenDict:
+        return self
+
+
+def _validate_name(name: object, *, field_name: str = "name") -> str:
+    if type(name) is not str:
+        raise TypeError(f"{field_name} must be a string")
+    if not name.strip():
+        raise ValueError(f"{field_name} must not be empty or whitespace")
+    return name
+
+
+def _normalize_json(
+    value: object,
+    *,
+    path: str,
+    active: set[int],
+    depth: int,
+) -> object:
+    if depth > _MAX_METADATA_DEPTH:
+        raise ValueError(
+            f"{path} exceeds the maximum metadata depth of {_MAX_METADATA_DEPTH}"
+        )
+
+    if value is None or type(value) is bool:
+        return value
+    if isinstance(value, str):
+        return str(value)
+    if type(value) is int:
+        if abs(value) > _MAX_SAFE_INTEGER:
+            raise ValueError(
+                f"{path} must be within the interoperable JSON integer range"
+            )
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise ValueError(f"{path} must be a finite number")
+        if value.is_integer() and abs(value) > _MAX_SAFE_INTEGER:
+            raise ValueError(
+                f"{path} must be within the interoperable JSON integer range"
+            )
+        return value
+
+    if isinstance(value, Mapping):
+        identity = id(value)
+        if identity in active:
+            raise ValueError(f"{path} contains a circular reference")
+        active.add(identity)
+        try:
+            normalized: dict[str, object] = {}
+            for key, item in value.items():
+                if type(key) is not str:
+                    raise TypeError(f"{path} keys must be strings")
+                normalized[key] = _normalize_json(
+                    item,
+                    path=f"{path}.{key}",
+                    active=active,
+                    depth=depth + 1,
+                )
+            return normalized
+        finally:
+            active.remove(identity)
+
+    if isinstance(value, (list, tuple)):
+        identity = id(value)
+        if identity in active:
+            raise ValueError(f"{path} contains a circular reference")
+        active.add(identity)
+        try:
+            return [
+                _normalize_json(
+                    item,
+                    path=f"{path}[{index}]",
+                    active=active,
+                    depth=depth + 1,
+                )
+                for index, item in enumerate(value)
+            ]
+        finally:
+            active.remove(identity)
+
+    raise TypeError(f"{path} contains a non-JSON value of type {type(value).__name__}")
+
+
+def _normalize_metadata(
+    metadata: Mapping[str, object] | None,
+    *,
+    path: str = "metadata",
+) -> dict[str, object]:
+    if metadata is None:
+        return {}
+    if not isinstance(metadata, Mapping):
+        raise TypeError(f"{path} must be a mapping")
+    normalized = _normalize_json(metadata, path=path, active=set(), depth=0)
+    # A mapping input always normalizes to a plain dictionary.
+    return normalized  # type: ignore[return-value]
+
+
+def _freeze_json(value: object) -> object:
+    if isinstance(value, dict):
+        return _FrozenDict({key: _freeze_json(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze_json(item) for item in value)
+    return value
+
+
+def _freeze_metadata(metadata: Mapping[str, object] | None) -> _FrozenDict:
+    normalized = _normalize_metadata(metadata)
+    frozen = _freeze_json(normalized)
+    return frozen  # type: ignore[return-value]
+
+
+def _thaw_json(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {key: _thaw_json(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw_json(item) for item in value]
+    return value
+
+
+def _validate_finite_number(value: object, *, field_name: str) -> float:
+    if type(value) not in (int, float):
+        raise TypeError(f"{field_name} must be a number")
+    try:
+        number = float(value)
+    except OverflowError as error:
+        raise ValueError(f"{field_name} must be finite") from error
+    if not math.isfinite(number):
+        raise ValueError(f"{field_name} must be finite")
+    return number
+
+
+def _validate_configuration_number(
+    value: object,
+    *,
+    field_name: str,
+    positive: bool = False,
+) -> float:
+    number = _validate_finite_number(value, field_name=field_name)
+    if positive and number <= 0:
+        raise ValueError(f"{field_name} must be greater than zero")
+    return number
+
+
+def _portable_number(value: float) -> int | float:
+    if abs(value) <= _MAX_SAFE_INTEGER and value.is_integer():
+        return int(value)
+    return value
+
+
+def _coerce_result(result: Result | str) -> Result:
+    if isinstance(result, Result):
+        return result
+    if type(result) is not str:
+        raise TypeError("result must be a Result or string")
+    try:
+        return Result(result)
+    except ValueError as error:
+        values = ", ".join(repr(member.value) for member in Result)
+        raise ValueError(f"result must be one of {values}") from error
+
+
+@dataclass(frozen=True, slots=True)
+class Contestant:
+    """An immutable contestant descriptor."""
+
+    name: str
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", _validate_name(self.name))
+        object.__setattr__(self, "metadata", _freeze_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    """An immutable recorded match."""
+
+    id: int
+    left: str
+    right: str
+    result: Result
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if type(self.id) is not int:
+            raise TypeError("id must be an integer")
+        if self.id < 1:
+            raise ValueError("id must be greater than zero")
+        left = _validate_name(self.left, field_name="left")
+        right = _validate_name(self.right, field_name="right")
+        if left == right:
+            raise ValueError("left and right must be different contestants")
+        object.__setattr__(self, "left", left)
+        object.__setattr__(self, "right", right)
+        object.__setattr__(self, "result", _coerce_result(self.result))
+        object.__setattr__(self, "metadata", _freeze_metadata(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class Standing:
+    """An immutable leaderboard row."""
+
+    rank: int
+    name: str
+    rating: float
+    wins: int
+    losses: int
+    draws: int
+    matches: int
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if type(self.rank) is not int:
+            raise TypeError("rank must be an integer")
+        if self.rank < 1:
+            raise ValueError("rank must be greater than zero")
+        object.__setattr__(self, "name", _validate_name(self.name))
+        object.__setattr__(
+            self,
+            "rating",
+            _validate_finite_number(self.rating, field_name="rating"),
+        )
+        for field_name in ("wins", "losses", "draws", "matches"):
+            value = getattr(self, field_name)
+            if type(value) is not int:
+                raise TypeError(f"{field_name} must be an integer")
+            if value < 0:
+                raise ValueError(f"{field_name} must not be negative")
+        if self.wins + self.losses + self.draws != self.matches:
+            raise ValueError("wins, losses, and draws must sum to matches")
+        object.__setattr__(self, "metadata", _freeze_metadata(self.metadata))
+
+    @property
+    def played(self) -> int:
+        """Compatibility alias for :attr:`matches`."""
+
+        return self.matches
+
+    @property
+    def score(self) -> float:
+        """Return match points using one point per win and half per draw."""
+
+        return self.wins + (self.draws / 2)
+
+
+@dataclass(slots=True)
+class _Stats:
+    played: int = 0
+    wins: int = 0
+    draws: int = 0
+    losses: int = 0
+
+
+def expected_score(rating: float, opponent_rating: float) -> float:
+    """Return the standard Elo expected score for ``rating``.
+
+    The numerically stable form remains defined even for very large, but
+    finite, rating differences.
+    """
+
+    own = _validate_finite_number(rating, field_name="rating")
+    opponent = _validate_finite_number(
+        opponent_rating, field_name="opponent_rating"
+    )
+    exponent = (opponent - own) / 400
+    # Clamp at the IEEE-754 base-10 boundary used by the JavaScript package.
+    # This also avoids platform-specific subnormal rounding in portable runs.
+    if exponent >= 308:
+        return 0
+    if exponent <= -308:
+        return 1
+    return 1 / (1 + (10**exponent))
+
+
+def round_robin(
+    contestants: Iterable[str],
+    rounds: int = 1,
+) -> tuple[tuple[str, str], ...]:
+    """Build a deterministic round-robin schedule.
+
+    Caller order is preserved within each repetition. Every pair's orientation
+    is reversed on odd-numbered repetitions so repeated schedules balance
+    left/right placement.
+    """
+
+    if type(rounds) is not int:
+        raise TypeError("rounds must be an integer")
+    if rounds < 1:
+        raise ValueError("rounds must be at least one")
+    if rounds > _MAX_SAFE_INTEGER:
+        raise ValueError("rounds must be within the interoperable integer range")
+    if isinstance(contestants, (str, bytes, bytearray)):
+        raise TypeError("contestants must be an iterable of names")
+    try:
+        names = tuple(
+            _validate_name(name, field_name="contestant")
+            for name in contestants
+        )
+    except TypeError as error:
+        if "contestant" in str(error):
+            raise
+        raise TypeError("contestants must be an iterable of names") from error
+    if len(set(names)) != len(names):
+        raise ValueError("contestant names must be unique")
+
+    base = tuple(combinations(names, 2))
+    schedule: list[tuple[str, str]] = []
+    for repetition in range(rounds):
+        if repetition % 2:
+            schedule.extend((right, left) for left, right in base)
+        else:
+            schedule.extend(base)
+    return tuple(schedule)
+
+
+class Arena:
+    """A deterministic Elo arena with complete, replayable match history."""
+
+    def __init__(
+        self,
+        contestants: (
+            Iterable[str] | Mapping[str, Mapping[str, object] | None]
+        ),
+        *,
+        initial_rating: float = 1000,
+        k_factor: float = 32,
+    ) -> None:
+        self._initial_rating = _validate_configuration_number(
+            initial_rating,
+            field_name="initial_rating",
+        )
+        self._k_factor = _validate_configuration_number(
+            k_factor,
+            field_name="k_factor",
+            positive=True,
+        )
+        self._contestants: dict[str, Contestant] = {}
+        self._ratings: dict[str, float] = {}
+        self._stats: dict[str, _Stats] = {}
+        self._matches: list[Match] = []
+
+        if isinstance(contestants, Mapping):
+            for name, metadata in contestants.items():
+                self.add(name, metadata)
+            return
+        if isinstance(contestants, (str, bytes, bytearray)):
+            raise TypeError(
+                "contestants must be an iterable of names or a metadata mapping"
+            )
+        try:
+            for name in contestants:
+                self.add(name)
+        except TypeError as error:
+            if "name must be a string" in str(error):
+                raise
+            raise TypeError(
+                "contestants must be an iterable of names or a metadata mapping"
+            ) from error
+
+    @property
+    def initial_rating(self) -> float:
+        return self._initial_rating
+
+    @property
+    def k_factor(self) -> float:
+        return self._k_factor
+
+    @property
+    def contestants(self) -> tuple[Contestant, ...]:
+        """Return contestants in registration order."""
+
+        return tuple(self._contestants.values())
+
+    @property
+    def matches(self) -> tuple[Match, ...]:
+        """Return immutable match records in chronological order."""
+
+        return tuple(self._matches)
+
+    def __len__(self) -> int:
+        return len(self._contestants)
+
+    def add(
+        self,
+        name: str,
+        metadata: Mapping[str, object] | None = None,
+    ) -> Contestant:
+        """Register and return a contestant."""
+
+        validated_name = _validate_name(name)
+        if validated_name in self._contestants:
+            raise ValueError(f"contestant {validated_name!r} already exists")
+        contestant = Contestant(
+            validated_name,
+            metadata if metadata is not None else {},
+        )
+        self._contestants[validated_name] = contestant
+        self._ratings[validated_name] = self._initial_rating
+        self._stats[validated_name] = _Stats()
+        return contestant
+
+    def rating(self, name: str) -> float:
+        """Return the current rating for a registered contestant."""
+
+        validated_name = _validate_name(name)
+        try:
+            return self._ratings[validated_name]
+        except KeyError:
+            raise KeyError(f"unknown contestant {validated_name!r}") from None
+
+    def record(
+        self,
+        left: str,
+        right: str,
+        result: Result | str,
+        metadata: Mapping[str, object] | None = None,
+    ) -> Match:
+        """Record a match, update both ratings, and return its immutable row."""
+
+        left_name = self._registered_name(left, field_name="left")
+        right_name = self._registered_name(right, field_name="right")
+        if left_name == right_name:
+            raise ValueError("left and right must be different contestants")
+        outcome = _coerce_result(result)
+        normalized_metadata = _normalize_metadata(metadata)
+
+        left_expected = expected_score(
+            self._ratings[left_name], self._ratings[right_name]
+        )
+        if outcome is Result.LEFT:
+            left_score = 1.0
+        elif outcome is Result.RIGHT:
+            left_score = 0.0
+        else:
+            left_score = 0.5
+        adjustment = self._k_factor * (left_score - left_expected)
+
+        match = Match(
+            id=len(self._matches) + 1,
+            left=left_name,
+            right=right_name,
+            result=outcome,
+            metadata=normalized_metadata,
+        )
+
+        next_left_rating = self._ratings[left_name] + adjustment
+        next_right_rating = self._ratings[right_name] - adjustment
+        if not math.isfinite(next_left_rating) or not math.isfinite(
+            next_right_rating
+        ):
+            raise OverflowError("rating update produced a non-finite rating")
+
+        self._ratings[left_name] = next_left_rating
+        self._ratings[right_name] = next_right_rating
+        self._apply_stats(left_name, right_name, outcome)
+        self._matches.append(match)
+        return match
+
+    def history(self) -> tuple[Match, ...]:
+        """Return the same immutable chronological data as :attr:`matches`."""
+
+        return self.matches
+
+    def standings(self) -> tuple[Standing, ...]:
+        """Return leaderboard rows sorted by rating descending, then name."""
+
+        ordered_names = sorted(
+            self._contestants,
+            key=lambda name: (-self._ratings[name], name),
+        )
+        return tuple(
+            Standing(
+                rank=rank,
+                name=name,
+                rating=self._ratings[name],
+                wins=self._stats[name].wins,
+                losses=self._stats[name].losses,
+                draws=self._stats[name].draws,
+                matches=self._stats[name].played,
+                metadata=self._contestants[name].metadata,
+            )
+            for rank, name in enumerate(ordered_names, start=1)
+        )
+
+    def leaderboard(self) -> tuple[Standing, ...]:
+        """Alias for :meth:`standings`."""
+
+        return self.standings()
+
+    def next_pair(self) -> tuple[str, str] | None:
+        """Choose the least-played unordered pair deterministically."""
+
+        names = sorted(self._contestants)
+        if len(names) < 2:
+            return None
+
+        pair_matches: dict[tuple[str, str], int] = {}
+        for match in self._matches:
+            pair = tuple(sorted((match.left, match.right)))
+            pair_matches[pair] = pair_matches.get(pair, 0) + 1
+
+        def priority(pair: tuple[str, str]) -> tuple[int, int, int, str, str]:
+            left, right = pair
+            left_total = self._stats[left].played
+            right_total = self._stats[right].played
+            return (
+                pair_matches.get(pair, 0),
+                left_total + right_total,
+                max(left_total, right_total),
+                left,
+                right,
+            )
+
+        return min(combinations(names, 2), key=priority)
+
+    def snapshot(self) -> dict[str, object]:
+        """Return a detached, JSON-compatible schema-v1 snapshot."""
+
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "initial_rating": _portable_number(self._initial_rating),
+            "k_factor": _portable_number(self._k_factor),
+            "contestants": [
+                {
+                    "name": contestant.name,
+                    "metadata": _thaw_json(contestant.metadata),
+                }
+                for contestant in sorted(
+                    self._contestants.values(),
+                    key=lambda contestant: contestant.name,
+                )
+            ],
+            "matches": [
+                {
+                    "id": match.id,
+                    "left": match.left,
+                    "right": match.right,
+                    "result": match.result.value,
+                    "metadata": _thaw_json(match.metadata),
+                }
+                for match in self._matches
+            ],
+        }
+
+    def to_json(self, *, indent: int | None = None) -> str:
+        """Serialize :meth:`snapshot` to deterministic JSON."""
+
+        if indent is not None:
+            if type(indent) is not int:
+                raise TypeError("indent must be an integer or None")
+            if indent < 0:
+                raise ValueError("indent must not be negative")
+        options: dict[str, Any] = {
+            "ensure_ascii": False,
+            "allow_nan": False,
+            "indent": indent,
+        }
+        if indent is None:
+            options["separators"] = (",", ":")
+        return json.dumps(self.snapshot(), **options)
+
+    @classmethod
+    def from_snapshot(cls, snapshot: Mapping[str, object]) -> Arena:
+        """Validate schema-v1 data and reconstruct ratings by replaying history."""
+
+        root = _require_mapping(snapshot, path="snapshot")
+        _require_fields(
+            root,
+            {
+                "schema_version",
+                "initial_rating",
+                "k_factor",
+                "contestants",
+                "matches",
+            },
+            path="snapshot",
+        )
+        version = root["schema_version"]
+        if type(version) is not int:
+            raise TypeError("snapshot.schema_version must be an integer")
+        if version != SCHEMA_VERSION:
+            raise ValueError(
+                f"unsupported schema_version {version!r}; expected {SCHEMA_VERSION}"
+            )
+
+        contestants_data = root["contestants"]
+        matches_data = root["matches"]
+        if type(contestants_data) is not list:
+            raise TypeError("snapshot.contestants must be a list")
+        if type(matches_data) is not list:
+            raise TypeError("snapshot.matches must be a list")
+
+        arena = cls(
+            [],
+            initial_rating=root["initial_rating"],  # type: ignore[arg-type]
+            k_factor=root["k_factor"],  # type: ignore[arg-type]
+        )
+        for index, raw_contestant in enumerate(contestants_data):
+            path = f"snapshot.contestants[{index}]"
+            contestant = _require_mapping(raw_contestant, path=path)
+            _require_fields(contestant, {"name", "metadata"}, path=path)
+            metadata = _require_mapping(
+                contestant["metadata"], path=f"{path}.metadata"
+            )
+            arena.add(contestant["name"], metadata)  # type: ignore[arg-type]
+
+        for index, raw_match in enumerate(matches_data):
+            path = f"snapshot.matches[{index}]"
+            match = _require_mapping(raw_match, path=path)
+            _require_fields(
+                match,
+                {"id", "left", "right", "result", "metadata"},
+                path=path,
+            )
+            expected_id = index + 1
+            match_id = match["id"]
+            if type(match_id) is not int:
+                raise TypeError(f"{path}.id must be an integer")
+            if match_id != expected_id:
+                raise ValueError(
+                    f"{path}.id must be contiguous; expected {expected_id}"
+                )
+            if type(match["result"]) is not str:
+                raise TypeError(f"{path}.result must be a string")
+            metadata = _require_mapping(match["metadata"], path=f"{path}.metadata")
+            recorded = arena.record(
+                match["left"],  # type: ignore[arg-type]
+                match["right"],  # type: ignore[arg-type]
+                match["result"],
+                metadata,
+            )
+            if recorded.id != match_id:  # Defensive assertion for subclasses.
+                raise ValueError(f"{path}.id could not be reproduced")
+        return arena
+
+    @classmethod
+    def from_json(cls, payload: str | bytes | bytearray) -> Arena:
+        """Parse strict JSON and delegate to :meth:`from_snapshot`."""
+
+        if not isinstance(payload, (str, bytes, bytearray)):
+            raise TypeError("payload must be str, bytes, or bytearray")
+
+        def reject_constant(value: str) -> object:
+            raise ValueError(f"non-standard JSON constant {value!r} is not allowed")
+
+        def reject_duplicate_keys(
+            pairs: list[tuple[str, object]],
+        ) -> dict[str, object]:
+            parsed: dict[str, object] = {}
+            for key, value in pairs:
+                if key in parsed:
+                    raise ValueError(f"duplicate JSON key {key!r}")
+                parsed[key] = value
+            return parsed
+
+        try:
+            decoded = json.loads(
+                payload,
+                parse_constant=reject_constant,
+                object_pairs_hook=reject_duplicate_keys,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError) as error:
+            raise ValueError(f"invalid JSON: {error}") from error
+        return cls.from_snapshot(decoded)
+
+    def _registered_name(self, name: object, *, field_name: str) -> str:
+        validated_name = _validate_name(name, field_name=field_name)
+        if validated_name not in self._contestants:
+            raise KeyError(f"unknown contestant {validated_name!r}")
+        return validated_name
+
+    def _apply_stats(self, left: str, right: str, result: Result) -> None:
+        left_stats = self._stats[left]
+        right_stats = self._stats[right]
+        left_stats.played += 1
+        right_stats.played += 1
+        if result is Result.LEFT:
+            left_stats.wins += 1
+            right_stats.losses += 1
+        elif result is Result.RIGHT:
+            right_stats.wins += 1
+            left_stats.losses += 1
+        else:
+            left_stats.draws += 1
+            right_stats.draws += 1
+
+
+def _require_mapping(value: object, *, path: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{path} must be a mapping")
+    for key in value:
+        if type(key) is not str:
+            raise TypeError(f"{path} keys must be strings")
+    return value
+
+
+def _require_fields(
+    value: Mapping[str, object],
+    expected: set[str],
+    *,
+    path: str,
+) -> None:
+    actual = set(value)
+    missing = sorted(expected - actual)
+    extra = sorted(actual - expected)
+    if not missing and not extra:
+        return
+    details: list[str] = []
+    if missing:
+        details.append(f"missing {', '.join(missing)}")
+    if extra:
+        details.append(f"unexpected {', '.join(extra)}")
+    raise ValueError(f"{path} has invalid fields: {'; '.join(details)}")

localarena/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

localarena-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: localarena
+Version: 0.1.0
+Summary: A small, deterministic Elo arena for local model comparisons
+Project-URL: Homepage, https://github.com/maziyarpanahi/localarena
+Project-URL: Repository, https://github.com/maziyarpanahi/localarena
+Project-URL: Issues, https://github.com/maziyarpanahi/localarena/issues
+Author: Maziyar Panahi
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: arena,elo,evaluation,leaderboard,local-models
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# localarena
+
+`localarena` is a zero-dependency Elo arena for deterministic, local
+head-to-head comparisons. It keeps contestant metadata, match history, and
+ratings together in a portable versioned snapshot.
+
+```bash
+pip install localarena
+```
+
+```python
+from localarena import Arena, Result
+
+arena = Arena(
+    {
+        "model-a": {"provider": "local"},
+        "model-b": {"provider": "local"},
+    }
+)
+
+arena.record("model-a", "model-b", Result.LEFT, {"prompt_id": "demo-1"})
+
+for row in arena.standings():
+    print(row.rank, row.name, row.rating)
+
+pair = arena.next_pair()
+payload = arena.to_json()
+restored = Arena.from_json(payload)
+```
+
+## API
+
+- `Arena(contestants, initial_rating=1000, k_factor=32)` accepts an iterable
+  of unique names or a mapping of names to metadata.
+- `add(name, metadata=None)` registers another contestant.
+- `record(left, right, result, metadata=None)` records a match and applies an
+  Elo update. Results are `"left"`, `"right"`, or `"draw"`.
+- `standings()` and its alias `leaderboard()` return immutable rows ordered by
+  rating descending, then name.
+- `next_pair()` chooses the least-played unordered pair deterministically.
+- `matches` and `history()` expose immutable match records.
+- `snapshot()` / `to_json()` produce schema-v1 data with contestants sorted by
+  name;
+  `from_snapshot()` / `from_json()` validate and replay that history.
+- `expected_score()` and `round_robin()` are available as standalone helpers.
+
+Metadata must be a JSON object. Nested dictionaries, lists, tuples, strings,
+booleans, `None`, finite numbers, and interoperable safe integers are
+accepted. Public records recursively freeze metadata; snapshots return
+detached ordinary dictionaries and lists.
+
+The npm package uses the same result values and schema-v1 snapshot format, so
+match histories can move between Python and JavaScript.

localarena-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+localarena/__init__.py,sha256=h1CzcRp8p_ZAANd-C0KoAxwGr27ieys0QaN1PaaqYFk,369
+localarena/core.py,sha256=h1aYHbUtpGElTurrNT5j7sXdW4fTDKK_yP7Y1vxwRng,25693
+localarena/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+localarena-0.1.0.dist-info/METADATA,sha256=ehadseXHCsZgL7FmqKwXVh2JLskgyYxVs3lYLzUKsXo,2812
+localarena-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+localarena-0.1.0.dist-info/licenses/LICENSE,sha256=UOZ1F5fFDe3XXvG4oNnkL1-Ecun7zpHzRxjp-XsMeAo,11324
+localarena-0.1.0.dist-info/RECORD,,

localarena-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

localarena-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.