localarena 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to LocalArena are documented here.
+
+The project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-07-25
+
+### Added
+
+- Dependency-free Python and JavaScript packages under the shared
+  `localarena` name.
+- Pairwise match recording with standard Elo updates.
+- Deterministic round-robin and least-played pair scheduling.
+- Rating-sorted standings with win, loss, draw, and match counts.
+- Schema-v1 JSON snapshots that replay across both runtimes.
+- JSON-safe contestant and match metadata.
+- Python and Node.js behavioral suites, package build checks, and release
+  automation for PyPI and npm.

package/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.

package/README.md

@@ -0,0 +1,211 @@
+# localarena
+
+Local-first pairwise evaluation, deterministic scheduling, and Elo ranking for
+models, agents, prompts, algorithms, or anything else you want to compare.
+
+[![PyPI](https://img.shields.io/pypi/v/localarena)](https://pypi.org/project/localarena/)
+[![npm](https://img.shields.io/npm/v/localarena)](https://www.npmjs.com/package/localarena)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+`localarena` is the small, dependency-free engine underneath a head-to-head
+arena. You generate two outputs and decide which side won; LocalArena keeps the
+match log, updates ratings, builds a fair next pairing, and gives you a portable
+leaderboard.
+
+- Same package name and concepts in Python and JavaScript
+- No network calls, telemetry, model SDK, database, or implicit file writes
+- Deterministic round-robin and least-played scheduling
+- Standard Elo updates with wins, losses, and draws
+- Versioned JSON snapshots that can move between both runtimes
+- Detached metadata so callers cannot accidentally mutate arena state
+
+## Install
+
+Python:
+
+```bash
+pip install localarena
+```
+
+JavaScript or TypeScript (Node.js 18+):
+
+```bash
+npm install localarena
+```
+
+## Quick start
+
+### Python
+
+```python
+from localarena import Arena, Result
+
+arena = Arena(["ollama/qwen3", "lm-studio/gemma"])
+
+# Generate both answers locally, ask a human or judge, then record the verdict.
+arena.record(
+    "ollama/qwen3",
+    "lm-studio/gemma",
+    Result.LEFT,
+    metadata={"prompt_id": "explain-rag"},
+)
+
+for standing in arena.standings():
+    print(standing.name, round(standing.rating, 2))
+
+print("Compare next:", arena.next_pair())
+```
+
+### JavaScript
+
+```js
+import { Arena, Result } from "localarena";
+
+const arena = new Arena(["ollama/qwen3", "lm-studio/gemma"]);
+
+arena.record("ollama/qwen3", "lm-studio/gemma", Result.LEFT, {
+  prompt_id: "explain-rag",
+});
+
+for (const standing of arena.standings()) {
+  console.log(standing.name, standing.rating.toFixed(2));
+}
+
+console.log("Compare next:", arena.nextPair());
+```
+
+The library intentionally does not decide how outputs are generated or judged.
+That keeps private prompts and responses on your machine and lets the same
+engine work with Ollama, LM Studio, vLLM, llama.cpp, local functions, human
+votes, or any provider SDK you explicitly choose.
+
+## Schedule a full arena
+
+`round_robin` / `roundRobin` returns each unordered pair once per round.
+Pair orientation flips every second round to reduce persistent left/right bias.
+
+```python
+from localarena import Arena, Result, round_robin
+
+models = ["a", "b", "c"]
+arena = Arena(models)
+
+for left, right in round_robin(models, rounds=2):
+    # Replace this deterministic example with your own comparison.
+    winner = Result.LEFT if len(left) >= len(right) else Result.RIGHT
+    arena.record(left, right, winner)
+```
+
+```js
+import { Arena, Result, roundRobin } from "localarena";
+
+const models = ["a", "b", "c"];
+const arena = new Arena(models);
+
+for (const [left, right] of roundRobin(models, 2)) {
+  const winner = left.length >= right.length ? Result.LEFT : Result.RIGHT;
+  arena.record(left, right, winner);
+}
+```
+
+## Portable snapshots
+
+Standings are derived from an append-only match history. A snapshot contains
+only the arena settings, contestant metadata, and that history:
+
+```python
+import json
+from localarena import Arena
+
+payload = json.dumps(arena.snapshot(), ensure_ascii=False, indent=2)
+restored = Arena.from_json(payload)
+```
+
+```js
+const payload = JSON.stringify(arena, null, 2);
+const restored = Arena.fromJSON(payload);
+```
+
+The schema-v1 keys are deliberately shared:
+
+```json
+{
+  "schema_version": 1,
+  "initial_rating": 1000,
+  "k_factor": 32,
+  "contestants": [
+    {"name": "a", "metadata": {}},
+    {"name": "b", "metadata": {}}
+  ],
+  "matches": [
+    {
+      "id": 1,
+      "left": "a",
+      "right": "b",
+      "result": "left",
+      "metadata": {}
+    }
+  ]
+}
+```
+
+See [the JSON Schema](schema/localarena-v1.schema.json) for the serialized
+contract. Restoring a snapshot replays the history instead of trusting stored
+ratings or counters.
+
+## Core API
+
+| Python | JavaScript | Purpose |
+| --- | --- | --- |
+| `Arena(names, initial_rating=..., k_factor=...)` | `new Arena(names, { initialRating, kFactor })` | Create an arena |
+| `add(name, metadata)` | `add(name, metadata)` | Register a contestant |
+| `rating(name)` | `rating(name)` | Read one current rating |
+| `record(left, right, result, metadata)` | `record(left, right, result, metadata)` | Record one match |
+| `standings()` / `leaderboard()` | `standings()` / `leaderboard()` | Return rating-sorted rows |
+| `next_pair()` | `nextPair()` | Choose the least-played pair |
+| `snapshot()` / `to_json()` | `snapshot()` / `JSON.stringify(arena)` | Export schema v1 |
+| `Arena.from_snapshot()` / `from_json()` | `Arena.fromSnapshot()` / `fromJSON()` | Validate and replay |
+| `expected_score(a, b)` | `expectedScore(a, b)` | Compute Elo expectation |
+| `round_robin(names, rounds)` | `roundRobin(names, rounds)` | Build all-pairs schedule |
+
+Results are `"left"`, `"right"`, or `"draw"`. Python also exports the
+`Result` string enum; JavaScript exports a frozen `Result` object.
+
+## Rating behavior
+
+LocalArena uses the conventional Elo expectation:
+
+```text
+E(left) = 1 / (1 + 10 ^ ((right_rating - left_rating) / 400))
+```
+
+A win scores `1`, a draw `0.5`, and a loss `0`. Both contestants receive equal
+and opposite rating adjustments, so total rating is conserved apart from
+normal floating-point precision.
+
+Elo is an online rating system: changing match order can change the final
+ratings. Keep and share the match log when reproducibility matters.
+
+## Development
+
+```bash
+# Python
+python3 -m pip install -e python
+python3 -m unittest discover -s python/tests
+python3 -m build python
+python3 -m twine check python/dist/*
+
+# JavaScript
+npm ci
+npm test
+npm audit --audit-level=low
+npm pack --dry-run
+```
+
+CI tests all supported runtimes. Pushing an immutable `v*` tag runs the release
+workflow, verifies that the tag, Python package, and npm package versions agree,
+then publishes the exact tested artifacts to PyPI and npm.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/javascript/src/index.d.ts

@@ -0,0 +1,90 @@
+export const SCHEMA_VERSION: 1;
+
+export const Result: Readonly<{
+  LEFT: "left";
+  RIGHT: "right";
+  DRAW: "draw";
+}>;
+
+export type ResultValue = (typeof Result)[keyof typeof Result];
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+export type Metadata = Record<string, JsonValue>;
+
+export interface Match {
+  id: number;
+  left: string;
+  right: string;
+  result: ResultValue;
+  metadata: Metadata;
+}
+
+export interface Standing {
+  rank: number;
+  name: string;
+  rating: number;
+  wins: number;
+  losses: number;
+  draws: number;
+  matches: number;
+  metadata: Metadata;
+}
+
+export interface ContestantSnapshot {
+  name: string;
+  metadata: Metadata;
+}
+
+export interface ArenaSnapshot {
+  schema_version: 1;
+  initial_rating: number;
+  k_factor: number;
+  contestants: ContestantSnapshot[];
+  matches: Match[];
+}
+
+export interface ArenaOptions {
+  initialRating?: number;
+  kFactor?: number;
+}
+
+export function expectedScore(
+  leftRating: number,
+  rightRating: number,
+): number;
+
+export function roundRobin(
+  contestants: readonly string[],
+  rounds?: number,
+): [string, string][];
+
+export class Arena {
+  constructor(contestants?: readonly string[], options?: ArenaOptions);
+
+  readonly initialRating: number;
+  readonly kFactor: number;
+  readonly contestants: string[];
+  readonly matches: Match[];
+
+  history(): Match[];
+  add(name: string, metadata?: Metadata): this;
+  rating(name: string): number;
+  record(
+    left: string,
+    right: string,
+    result: ResultValue,
+    metadata?: Metadata,
+  ): Match;
+  standings(): Standing[];
+  leaderboard(): Standing[];
+  nextPair(): [string, string] | null;
+  snapshot(): ArenaSnapshot;
+  toJSON(): ArenaSnapshot;
+
+  static fromSnapshot(snapshot: ArenaSnapshot): Arena;
+  static fromJSON(value: string): Arena;
+}

package/javascript/src/index.js

@@ -0,0 +1,522 @@
+/**
+ * LocalArena's dependency-free pairwise evaluation and Elo ranking engine.
+ *
+ * Snapshots are intentionally small and portable between the JavaScript and
+ * Python packages. Standings are always derived by replaying the match log.
+ */
+
+export const SCHEMA_VERSION = 1;
+
+export const Result = Object.freeze({
+  LEFT: "left",
+  RIGHT: "right",
+  DRAW: "draw",
+});
+
+const VALID_RESULTS = new Set(Object.values(Result));
+
+function compareCodePoints(left, right) {
+  const leftPoints = Array.from(left, (value) => value.codePointAt(0));
+  const rightPoints = Array.from(right, (value) => value.codePointAt(0));
+  const length = Math.min(leftPoints.length, rightPoints.length);
+
+  for (let index = 0; index < length; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) {
+      return leftPoints[index] - rightPoints[index];
+    }
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function assertFiniteNumber(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`${field} must be a finite number`);
+  }
+}
+
+function assertName(name, field = "name") {
+  if (typeof name !== "string") {
+    throw new TypeError(`${field} must be a string`);
+  }
+  if (name.trim().length === 0) {
+    throw new RangeError(`${field} must not be empty`);
+  }
+}
+
+function assertExactKeys(value, expected, field) {
+  const actual = Object.keys(value);
+  const missing = expected.filter((key) => !Object.hasOwn(value, key));
+  const extra = actual.filter((key) => !expected.includes(key));
+  if (missing.length === 0 && extra.length === 0) {
+    return;
+  }
+
+  const details = [];
+  if (missing.length > 0) {
+    details.push(`missing ${missing.sort().join(", ")}`);
+  }
+  if (extra.length > 0) {
+    details.push(`unexpected ${extra.sort().join(", ")}`);
+  }
+  throw new Error(`${field} has invalid fields: ${details.join("; ")}`);
+}
+
+function cloneMetadata(metadata = {}, field = "metadata") {
+  if (
+    metadata === null ||
+    typeof metadata !== "object" ||
+    Array.isArray(metadata)
+  ) {
+    throw new TypeError(`${field} must be a JSON object`);
+  }
+
+  let serialized;
+  try {
+    serialized = JSON.stringify(metadata, (_key, value) => {
+      if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new TypeError(`${field} must contain only finite numbers`);
+      }
+      if (
+        typeof value === "number" &&
+        Number.isInteger(value) &&
+        !Number.isSafeInteger(value)
+      ) {
+        throw new TypeError(
+          `${field} integers must be within JavaScript's safe range`,
+        );
+      }
+      if (
+        typeof value === "undefined" ||
+        typeof value === "function" ||
+        typeof value === "symbol" ||
+        typeof value === "bigint"
+      ) {
+        throw new TypeError(`${field} must contain only JSON values`);
+      }
+      return value;
+    });
+  } catch (error) {
+    if (error instanceof TypeError && error.message.startsWith(field)) {
+      throw error;
+    }
+    throw new TypeError(`${field} must be JSON-serializable`, {
+      cause: error,
+    });
+  }
+
+  if (serialized === undefined) {
+    throw new TypeError(`${field} must be JSON-serializable`);
+  }
+
+  const clone = JSON.parse(serialized);
+  if (clone === null || typeof clone !== "object" || Array.isArray(clone)) {
+    throw new TypeError(`${field} must be a JSON object`);
+  }
+  return clone;
+}
+
+function cloneMatch(match) {
+  return {
+    id: match.id,
+    left: match.left,
+    right: match.right,
+    result: match.result,
+    metadata: cloneMetadata(match.metadata),
+  };
+}
+
+function compareCandidateScores(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) {
+      return left[index] - right[index];
+    }
+  }
+  const leftName = compareCodePoints(left[3], right[3]);
+  if (leftName !== 0) {
+    return leftName;
+  }
+  return compareCodePoints(left[4], right[4]);
+}
+
+function pairKey(left, right) {
+  return compareCodePoints(left, right) <= 0
+    ? JSON.stringify([left, right])
+    : JSON.stringify([right, left]);
+}
+
+/**
+ * Return the expected score for the left contestant under the Elo model.
+ */
+export function expectedScore(leftRating, rightRating) {
+  assertFiniteNumber(leftRating, "leftRating");
+  assertFiniteNumber(rightRating, "rightRating");
+
+  const exponent = (rightRating - leftRating) / 400;
+  if (exponent >= 308) {
+    return 0;
+  }
+  if (exponent <= -308) {
+    return 1;
+  }
+  return 1 / (1 + 10 ** exponent);
+}
+
+/**
+ * Build a deterministic all-pairs schedule.
+ *
+ * Caller order is preserved. On every second repetition, pair orientation is
+ * flipped to reduce systematic left/right bias.
+ */
+export function roundRobin(contestants, rounds = 1) {
+  if (!Array.isArray(contestants)) {
+    throw new TypeError("contestants must be an array");
+  }
+  if (!Number.isSafeInteger(rounds) || rounds < 1) {
+    throw new RangeError("rounds must be a positive safe integer");
+  }
+
+  const names = contestants.map((name, index) => {
+    assertName(name, `contestants[${index}]`);
+    return name;
+  });
+  if (new Set(names).size !== names.length) {
+    throw new Error("contestants must contain unique names");
+  }
+  if (names.length < 2) {
+    return [];
+  }
+
+  const basePairs = [];
+  for (let left = 0; left < names.length - 1; left += 1) {
+    for (let right = left + 1; right < names.length; right += 1) {
+      basePairs.push([names[left], names[right]]);
+    }
+  }
+
+  const schedule = [];
+  for (let round = 0; round < rounds; round += 1) {
+    for (const [left, right] of basePairs) {
+      schedule.push(round % 2 === 0 ? [left, right] : [right, left]);
+    }
+  }
+  return schedule;
+}
+
+export class Arena {
+  constructor(contestants = [], options = {}) {
+    if (!Array.isArray(contestants)) {
+      throw new TypeError("contestants must be an array");
+    }
+    if (
+      options === null ||
+      typeof options !== "object" ||
+      Array.isArray(options)
+    ) {
+      throw new TypeError("options must be an object");
+    }
+
+    const initialRating = options.initialRating ?? 1000;
+    const kFactor = options.kFactor ?? 32;
+    assertFiniteNumber(initialRating, "initialRating");
+    assertFiniteNumber(kFactor, "kFactor");
+    if (kFactor <= 0) {
+      throw new RangeError("kFactor must be greater than zero");
+    }
+
+    this._initialRating = initialRating;
+    this._kFactor = kFactor;
+    this._contestants = new Map();
+    this._matches = [];
+
+    for (const name of contestants) {
+      this.add(name);
+    }
+  }
+
+  get initialRating() {
+    return this._initialRating;
+  }
+
+  get kFactor() {
+    return this._kFactor;
+  }
+
+  get contestants() {
+    return Array.from(this._contestants.keys());
+  }
+
+  get matches() {
+    return this._matches.map(cloneMatch);
+  }
+
+  history() {
+    return this.matches;
+  }
+
+  add(name, metadata = {}) {
+    assertName(name);
+    if (this._contestants.has(name)) {
+      throw new Error(`contestant already exists: ${name}`);
+    }
+
+    this._contestants.set(name, {
+      name,
+      rating: this._initialRating,
+      wins: 0,
+      losses: 0,
+      draws: 0,
+      metadata: cloneMetadata(metadata),
+    });
+    return this;
+  }
+
+  rating(name) {
+    assertName(name);
+    const contestant = this._contestants.get(name);
+    if (contestant === undefined) {
+      throw new Error(`unknown contestant: ${name}`);
+    }
+    return contestant.rating;
+  }
+
+  record(left, right, result, metadata = {}) {
+    assertName(left, "left");
+    assertName(right, "right");
+    if (left === right) {
+      throw new Error("left and right contestants must be different");
+    }
+    if (!this._contestants.has(left)) {
+      throw new Error(`unknown contestant: ${left}`);
+    }
+    if (!this._contestants.has(right)) {
+      throw new Error(`unknown contestant: ${right}`);
+    }
+    if (!VALID_RESULTS.has(result)) {
+      throw new RangeError('result must be "left", "right", or "draw"');
+    }
+
+    const safeMetadata = cloneMetadata(metadata);
+    const leftState = this._contestants.get(left);
+    const rightState = this._contestants.get(right);
+    const expectedLeft = expectedScore(leftState.rating, rightState.rating);
+    const actualLeft =
+      result === Result.LEFT ? 1 : result === Result.DRAW ? 0.5 : 0;
+    const adjustment = this._kFactor * (actualLeft - expectedLeft);
+    const nextLeftRating = leftState.rating + adjustment;
+    const nextRightRating = rightState.rating - adjustment;
+    if (!Number.isFinite(nextLeftRating) || !Number.isFinite(nextRightRating)) {
+      throw new RangeError(
+        "rating update overflowed; use smaller ratings or kFactor",
+      );
+    }
+
+    leftState.rating = nextLeftRating;
+    rightState.rating = nextRightRating;
+    if (result === Result.LEFT) {
+      leftState.wins += 1;
+      rightState.losses += 1;
+    } else if (result === Result.RIGHT) {
+      leftState.losses += 1;
+      rightState.wins += 1;
+    } else {
+      leftState.draws += 1;
+      rightState.draws += 1;
+    }
+
+    const match = {
+      id: this._matches.length + 1,
+      left,
+      right,
+      result,
+      metadata: safeMetadata,
+    };
+    this._matches.push(match);
+    return cloneMatch(match);
+  }
+
+  standings() {
+    const standings = Array.from(this._contestants.values(), (contestant) => ({
+      name: contestant.name,
+      rating: contestant.rating,
+      wins: contestant.wins,
+      losses: contestant.losses,
+      draws: contestant.draws,
+      matches: contestant.wins + contestant.losses + contestant.draws,
+      metadata: cloneMetadata(contestant.metadata),
+    })).sort((left, right) => {
+      if (left.rating !== right.rating) {
+        return right.rating - left.rating;
+      }
+      return compareCodePoints(left.name, right.name);
+    });
+    return standings.map((standing, index) => ({
+      rank: index + 1,
+      ...standing,
+    }));
+  }
+
+  leaderboard() {
+    return this.standings();
+  }
+
+  nextPair() {
+    if (this._contestants.size < 2) {
+      return null;
+    }
+
+    const names = Array.from(this._contestants.keys()).sort(compareCodePoints);
+    const totals = new Map(
+      this.standings().map((standing) => [standing.name, standing.matches]),
+    );
+    const pairCounts = new Map();
+    for (const match of this._matches) {
+      const key = pairKey(match.left, match.right);
+      pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+    }
+
+    let bestPair;
+    let bestScore;
+    for (let leftIndex = 0; leftIndex < names.length - 1; leftIndex += 1) {
+      for (
+        let rightIndex = leftIndex + 1;
+        rightIndex < names.length;
+        rightIndex += 1
+      ) {
+        const left = names[leftIndex];
+        const right = names[rightIndex];
+        const leftMatches = totals.get(left);
+        const rightMatches = totals.get(right);
+        const score = [
+          pairCounts.get(pairKey(left, right)) ?? 0,
+          leftMatches + rightMatches,
+          Math.max(leftMatches, rightMatches),
+          left,
+          right,
+        ];
+        if (
+          bestScore === undefined ||
+          compareCandidateScores(score, bestScore) < 0
+        ) {
+          bestPair = [left, right];
+          bestScore = score;
+        }
+      }
+    }
+    return bestPair;
+  }
+
+  snapshot() {
+    const contestants = Array.from(this._contestants.values())
+      .sort((left, right) => compareCodePoints(left.name, right.name))
+      .map((contestant) => ({
+        name: contestant.name,
+        metadata: cloneMetadata(contestant.metadata),
+      }));
+
+    return {
+      schema_version: SCHEMA_VERSION,
+      initial_rating: this._initialRating,
+      k_factor: this._kFactor,
+      contestants,
+      matches: this.matches,
+    };
+  }
+
+  toJSON() {
+    return this.snapshot();
+  }
+
+  static fromSnapshot(snapshot) {
+    if (
+      snapshot === null ||
+      typeof snapshot !== "object" ||
+      Array.isArray(snapshot)
+    ) {
+      throw new TypeError("snapshot must be an object");
+    }
+    if (snapshot.schema_version !== SCHEMA_VERSION) {
+      throw new Error(
+        `unsupported schema_version: ${String(snapshot.schema_version)}`,
+      );
+    }
+    if (!Array.isArray(snapshot.contestants)) {
+      throw new TypeError("snapshot.contestants must be an array");
+    }
+    if (!Array.isArray(snapshot.matches)) {
+      throw new TypeError("snapshot.matches must be an array");
+    }
+    assertExactKeys(
+      snapshot,
+      [
+        "schema_version",
+        "initial_rating",
+        "k_factor",
+        "contestants",
+        "matches",
+      ],
+      "snapshot",
+    );
+
+    const arena = new Arena([], {
+      initialRating: snapshot.initial_rating,
+      kFactor: snapshot.k_factor,
+    });
+
+    snapshot.contestants.forEach((contestant, index) => {
+      if (
+        contestant === null ||
+        typeof contestant !== "object" ||
+        Array.isArray(contestant)
+      ) {
+        throw new TypeError(`snapshot.contestants[${index}] must be an object`);
+      }
+      assertExactKeys(
+        contestant,
+        ["name", "metadata"],
+        `snapshot.contestants[${index}]`,
+      );
+      arena.add(contestant.name, contestant.metadata);
+    });
+
+    snapshot.matches.forEach((match, index) => {
+      if (
+        match === null ||
+        typeof match !== "object" ||
+        Array.isArray(match)
+      ) {
+        throw new TypeError(`snapshot.matches[${index}] must be an object`);
+      }
+      assertExactKeys(
+        match,
+        ["id", "left", "right", "result", "metadata"],
+        `snapshot.matches[${index}]`,
+      );
+      const expectedId = index + 1;
+      if (!Number.isSafeInteger(match.id) || match.id !== expectedId) {
+        throw new Error(
+          `snapshot.matches[${index}].id must be ${expectedId}`,
+        );
+      }
+      arena.record(
+        match.left,
+        match.right,
+        match.result,
+        match.metadata,
+      );
+    });
+    return arena;
+  }
+
+  static fromJSON(value) {
+    if (typeof value !== "string") {
+      throw new TypeError("value must be a JSON string");
+    }
+    let snapshot;
+    try {
+      snapshot = JSON.parse(value);
+    } catch (error) {
+      throw new SyntaxError("value must contain valid JSON", { cause: error });
+    }
+    return Arena.fromSnapshot(snapshot);
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "localarena",
+  "version": "0.1.0",
+  "description": "Local-first pairwise evaluation, deterministic scheduling, and Elo ranking.",
+  "keywords": [
+    "evaluation",
+    "elo",
+    "llm",
+    "local-first",
+    "pairwise",
+    "ranking"
+  ],
+  "homepage": "https://github.com/maziyarpanahi/localarena#readme",
+  "bugs": {
+    "url": "https://github.com/maziyarpanahi/localarena/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maziyarpanahi/localarena.git"
+  },
+  "license": "Apache-2.0",
+  "author": "Maziyar Panahi",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./javascript/src/index.js",
+  "types": "./javascript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./javascript/src/index.d.ts",
+      "import": "./javascript/src/index.js",
+      "default": "./javascript/src/index.js"
+    },
+    "./schema/localarena-v1.schema.json": "./schema/localarena-v1.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "javascript/src",
+    "schema",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check javascript/src/index.js",
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/localarena-v1.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/maziyarpanahi/localarena/blob/main/schema/localarena-v1.schema.json",
+  "title": "LocalArena snapshot v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "initial_rating",
+    "k_factor",
+    "contestants",
+    "matches"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "initial_rating": {
+      "type": "number"
+    },
+    "k_factor": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "contestants": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/contestant"
+      }
+    },
+    "matches": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/match"
+      }
+    }
+  },
+  "$defs": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "metadata": {
+      "type": "object"
+    },
+    "contestant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "metadata"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "match": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "left",
+        "right",
+        "result",
+        "metadata"
+      ],
+      "properties": {
+        "id": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "left": {
+          "$ref": "#/$defs/name"
+        },
+        "right": {
+          "$ref": "#/$defs/name"
+        },
+        "result": {
+          "enum": [
+            "left",
+            "right",
+            "draw"
+          ]
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    }
+  }
+}