Merge pull request #88 from CurtisTechSolutions/feat/local-model-tournaments

feat(training): run balanced model snapshot tournaments

Author: nosam1998

examples/model-tournaments.md

@@ -0,0 +1,39 @@
+# Comparing your model snapshots
+
+```python
+from gamesforai import ChatPolicy
+from gamesforai.tournament import Agent, run_round_robin
+from gamesforai.parquet import write_parquet
+
+agents = [
+    Agent("my-checkpoint-v1", policy_factory=lambda seed, seat:
+          ChatPolicy("http://localhost:8000/v1", "my-checkpoint-v1")),
+    Agent("minimax-level-3", opponent="minimax:3"),
+]
+report = run_round_robin("connect4", agents, games_per_pair=100, seed=42)
+```
+
+For a Python model, return a callable `(observation, info) -> action_index` from
+the factory. The factory runs once per game with its seed and seat; reset recurrent
+state and policy RNG there. Keep weights frozen during evaluation and give every
+checkpoint a distinct stable agent id. Training may run between tournaments.
+
+Schedules alternate seats for every pair. Built-in random/minimax/MCTS policies
+are available without model dependencies. A pinned `position_set` can supply
+curriculum starts, and its content hash appears in the report.
+
+Every completed, non-truncated game contributes to one tournament-wide Glicko-2
+period using pre-tournament opponent ratings. Failures, truncated episodes and
+already-finished starts are counted separately and remain unrated. Reports
+contain outcomes, rating intervals, win-rate Wilson intervals, seeds and trajectory
+hashes. Intervals summarize this schedule; repeated/correlated positions can
+make them optimistic. Engine levels remain uncalibrated without measured anchors.
+
+Use `on_episode(summary, rows)` to write completed trajectories to JSONL or
+Parquet; the runner retains summaries rather than every episode's tensors.
+Sink failures abort the run. Local Python policies run in the trainer process;
+they must return promptly. The HTTP adapter has its own socket timeout.
+
+Native policy decisions and datasets repeat with fixed seeds. Full report hashes
+also require the same explicit `run_id` and `created_at` values. Remote model
+sampling and caller-owned model state are controlled by your model host/trainer.

python/gamesforai/tournament.py

@@ -0,0 +1,226 @@
+"""Reproducible local round robins between frozen model snapshots."""
+from __future__ import annotations
+
+import hashlib
+import itertools
+import json
+import math
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Callable
+
+import numpy as np
+
+from ._native import NativeEnv
+from .positions import PositionSet
+from .ratings import Rating
+from .trajectories import EpisodeRecorder, _time
+
+
+@dataclass(frozen=True)
+class Agent:
+    """One immutable snapshot identity and a fresh per-game policy factory.
+
+    The factory receives (seed, seat) and returns a policy(observation, info).
+    Alternatively opponent selects random or native minimax/mcts levels.
+    """
+
+    id: str
+    policy_factory: Callable | None = None
+    opponent: str | None = None
+    initial_rating: Rating | None = None
+    fixed: bool = False
+
+    def __post_init__(self):
+        if not isinstance(self.id, str) or not self.id or len(self.id.encode("utf-8")) > 256:
+            raise ValueError("agent id must be nonempty text within 256 bytes")
+        if type(self.fixed) is not bool or (self.fixed and self.initial_rating is None):
+            raise ValueError("fixed anchors require an explicit calibrated initial_rating")
+        if self.initial_rating is not None and not isinstance(self.initial_rating, Rating):
+            raise ValueError("initial_rating must be a Rating")
+        if self.initial_rating is not None and self.initial_rating.rd == 0 and not self.fixed:
+            raise ValueError("zero rating deviation requires a fixed calibrated anchor")
+        if (self.policy_factory is None) == (self.opponent is None):
+            raise ValueError("choose a policy factory or built-in opponent")
+        if self.policy_factory is not None and not callable(self.policy_factory):
+            raise ValueError("policy_factory must be callable")
+        if self.opponent is not None and (
+            not isinstance(self.opponent, str)
+            or (self.opponent != "random" and not re.fullmatch(r"(minimax|mcts):([1-9]|10)", self.opponent))
+        ):
+            raise ValueError("opponent must be random, minimax:1..10, or mcts:1..10")
+
+
+def _wilson(wins, games):
+    if games == 0:
+        return None
+    z = 1.959963984540054
+    p = wins / games
+    denominator = 1 + z * z / games
+    center = (p + z * z / (2 * games)) / denominator
+    radius = z * math.sqrt(p * (1 - p) / games + z * z / (4 * games * games)) / denominator
+    return [max(0.0, center - radius), min(1.0, center + radius)]
+
+
+def run_round_robin(
+    game, agents, *, games_per_pair=2, seed=42, config=None, position_set=None,
+    tau=0.5, run_id=None, created_at=None, on_episode=None,
+):
+    """Run balanced seats and rate completed games as one Glicko-2 period.
+
+    Truncated, failed and already-finished starts are reported but never rated.
+    Optional on_episode(match_summary, records) receives completed trajectories.
+    A sink error aborts the run so a storage failure cannot silently lose data.
+    """
+    agents = tuple(agents)
+    if not 2 <= len(agents) <= 32 or any(not isinstance(agent, Agent) for agent in agents):
+        raise ValueError("a tournament requires 2..32 Agent snapshots")
+    if len({agent.id for agent in agents}) != len(agents):
+        raise ValueError("agent snapshot ids must be unique")
+    if type(games_per_pair) is not int or not 2 <= games_per_pair <= 1000 or games_per_pair % 2:
+        raise ValueError("games_per_pair must be even, 2..1000, for balanced seats")
+    total = len(agents) * (len(agents) - 1) // 2 * games_per_pair
+    if total > 10000 or type(seed) is not int or not 0 <= seed <= 2**64 - total:
+        raise ValueError("tournament exceeds 10000 games or the 64-bit seed range")
+    if isinstance(tau, bool) or not isinstance(tau, (int, float)) or not 0.2 <= tau <= 1.2:
+        raise ValueError("tau must be 0.2..1.2")
+    prototype = NativeEnv(game, json.dumps(config or {}), seed)
+    spec = json.loads(prototype.spec_json())
+    if prototype.num_players != 2 or spec["turn_structure"] != "sequential":
+        raise ValueError("round robin currently requires a sequential two-player game")
+    for agent in agents:
+        if agent.opponent not in (None, "random") and (
+            spec["information"] != "perfect" or spec["stochastic"]
+        ):
+            raise ValueError("native search requires a deterministic perfect-information game")
+    dataset = PositionSet.load(position_set) if isinstance(position_set, str) else position_set
+    if dataset is not None:
+        if not isinstance(dataset, PositionSet):
+            raise ValueError("position_set must be a pinned name or PositionSet")
+        dataset.validate_for(prototype)
+    run_id = run_id or str(uuid.uuid4())
+    if not isinstance(run_id, str) or not run_id or len(run_id.encode("utf-8")) > 200:
+        raise ValueError("run_id must be nonempty text within 200 bytes")
+    created_at = created_at or datetime.now(timezone.utc).isoformat()
+    _time(created_at)
+    if on_episode is not None and not callable(on_episode):
+        raise ValueError("on_episode must be callable")
+    priors = {agent.id: agent.initial_rating or Rating() for agent in agents}
+    periods = {agent.id: [] for agent in agents}
+    totals = {agent.id: {"wins": 0, "draws": 0, "losses": 0, "truncated": 0, "failed": 0,
+                        "invalid_starts": 0, "seats": [0, 0]} for agent in agents}
+    matches = []
+    for left, right in itertools.combinations(agents, 2):
+        for repetition in range(games_per_pair):
+            order = (left, right) if repetition % 2 == 0 else (right, left)
+            match_seed = seed + len(matches)
+            rng = np.random.default_rng(match_seed)
+            entry = None if dataset is None else dataset.sample(rng)
+            episode = EpisodeRecorder(
+                game, [agent.id for agent in order], config=config, seed=match_seed,
+                position=None if entry is None else entry.position,
+                episode_id=f"{run_id}:{len(matches)}", created_at=created_at,
+                ratings=[priors[agent.id].rating for agent in order],
+            )
+            match = {
+                "id": f"{run_id}:{len(matches)}", "seed": str(match_seed),
+                "agents": [agent.id for agent in order], "turns": 0,
+                "status": "completed", "failure": None, "returns": None,
+                "position_id": None if entry is None else entry.id,
+            }
+            for seat, agent in enumerate(order):
+                totals[agent.id]["seats"][seat] += 1
+            policies = [None, None]
+            if any(episode.flags):
+                match["status"] = "invalid_start"
+            else:
+                for seat, agent in enumerate(order):
+                    if agent.policy_factory is not None:
+                        try:
+                            policies[seat] = agent.policy_factory(match_seed, seat)
+                            if not callable(policies[seat]):
+                                raise TypeError("factory did not return a policy")
+                        except Exception:
+                            match["status"], match["failure"] = "failed", {"agent": agent.id, "code": "policy_factory"}
+                            break
+            while match["status"] == "completed" and episode.current_players:
+                seat = episode.current_players[0]
+                agent = order[seat]
+                obs, info = episode.observation(seat)
+                try:
+                    if agent.opponent == "random":
+                        action = int(rng.choice(np.flatnonzero(info["action_mask"])))
+                    elif agent.opponent is not None:
+                        algorithm, level = agent.opponent.split(":")
+                        action = episode.builtin_action(seat, algorithm, int(level),
+                                                        int(rng.integers(0, 2**64, dtype=np.uint64)))
+                    else:
+                        action = policies[seat](obs, info)
+                except Exception:
+                    match["status"], match["failure"] = "failed", {"agent": agent.id, "code": "policy_error"}
+                    break
+                if (
+                    isinstance(action, (bool, np.bool_)) or not isinstance(action, (int, np.integer))
+                    or not 0 <= action < len(info["action_mask"]) or not info["action_mask"][action]
+                ):
+                    match["status"], match["failure"] = "failed", {"agent": agent.id, "code": "illegal_action"}
+                    break
+                try:
+                    episode.step(seat, int(action))
+                except Exception:
+                    match["status"], match["failure"] = "failed", {"agent": agent.id, "code": "episode_error"}
+                    break
+                match["turns"] += 1
+            if match["status"] == "completed":
+                match["returns"] = episode.returns
+                if episode.flags[1]:
+                    match["status"] = "truncated"
+                else:
+                    first, second = episode.returns
+                    score = 1.0 if first > second else 0.0 if first < second else 0.5
+                    for seat, value in enumerate((score, 1.0 - score)):
+                        agent, opponent = order[seat], order[1 - seat]
+                        periods[agent.id].append((priors[opponent.id], value))
+                        totals[agent.id]["wins" if value == 1 else "losses" if value == 0 else "draws"] += 1
+                rows = episode.records()
+                encoded = json.dumps(rows, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
+                match["trajectory_sha256"] = hashlib.sha256(encoded).hexdigest()
+                if on_episode is not None:
+                    on_episode(dict(match), rows)
+            for agent in order:
+                if match["status"] != "completed":
+                    field = "invalid_starts" if match["status"] == "invalid_start" else match["status"]
+                    totals[agent.id][field] += 1
+            matches.append(match)
+
+    standings = []
+    for agent in agents:
+        prior, results, stats = priors[agent.id], periods[agent.id], totals[agent.id]
+        # No eligible games is an unchanged tournament, not an implicit inactive time period.
+        if not results:
+            updated = prior
+        elif agent.fixed:
+            updated = Rating(**{**prior.to_dict(), "games_played": prior.games_played + len(results)})
+        else:
+            updated = prior.update(results, tau=tau)
+        games = len(results)
+        standings.append({
+            "agent": agent.id, **stats, "rated_games": games, "fixed": agent.fixed,
+            "initial_rating": prior.to_dict(), "rating": updated.to_dict(),
+            "rating_interval95": list(updated.interval95),
+            "win_rate": None if games == 0 else stats["wins"] / games,
+            "win_rate_wilson95": _wilson(stats["wins"], games),
+            "score": None if games == 0 else (stats["wins"] + 0.5 * stats["draws"]) / games,
+        })
+    standings.sort(key=lambda row: (-row["rating"]["rating"], row["agent"]))
+    return {
+        "format_version": 1, "run_id": run_id, "game": game,
+        "engine_version": spec["engine_version"],
+        "config": json.loads(prototype.get_state())["config"],
+        "seed": str(seed), "created_at": created_at, "games_per_pair": games_per_pair,
+        "rating_system": {"name": "glicko2", "tau": tau, "period": "whole_tournament"},
+        "position_set": None if dataset is None else {"id": dataset.identifier, "sha256": dataset.sha256},
+        "standings": standings, "matches": matches,
+    }

python/gamesforai/trajectories.py

@@ -149,6 +149,10 @@ def step(self, seat, action, *, reasoning=None, transcript=None):
         self._bytes += size
         return list(rewards), terminated, truncated
 
+    def builtin_action(self, seat, algorithm, level, seed):
+        """Choose a built-in action through the engine's observation-only planner."""
+        return self._native.builtin_action(seat, algorithm, level, seed)
+
     def records(self):
         """Finalized rows with the eventual outcome for each acting seat."""
         terminated, truncated = self.flags

python/tests/test_tournament.py

@@ -0,0 +1,95 @@
+import json
+
+import numpy as np
+import pytest
+
+from gamesforai.ratings import Rating
+from gamesforai.tournament import Agent, run_round_robin
+
+
+def run(agents=None, **kwargs):
+    return run_round_robin("tictactoe", agents or [
+        Agent("search-v1", opponent="minimax:3"),
+        Agent("random-v1", opponent="random"),
+        Agent("random-v2", opponent="random"),
+    ], seed=19, run_id="test-league", created_at="2026-01-01T00:00:00Z", **kwargs)
+
+
+def test_round_robin_balances_seats_repeats_and_exports_completed_games():
+    saved = []
+    first = run(games_per_pair=4, on_episode=lambda summary, rows: saved.append((summary, rows)))
+    second = run(games_per_pair=4)
+    assert first == second
+    assert len(first["matches"]) == len(saved) == 12
+    assert all(row["seats"] == [4, 4] and row["rated_games"] == 8 for row in first["standings"])
+    assert all(row["rating"]["games_played"] == 8 for row in first["standings"])
+    assert sum(row["wins"] for row in first["standings"]) == sum(row["losses"] for row in first["standings"])
+    for summary, rows in saved:
+        assert summary["status"] == "completed"
+        assert rows[-1]["terminated"]
+        assert all(row["episode_id"] == summary["id"] for row in rows)
+    json.dumps(first, allow_nan=False)
+
+
+def test_python_factories_reset_each_game_and_only_receive_policy_inputs():
+    calls = []
+
+    def factory(seed, seat):
+        calls.append((seed, seat))
+        rng = np.random.default_rng(seed + seat)
+
+        def choose(obs, info):
+            assert "native" not in info and "state" not in info
+            return int(rng.choice(np.flatnonzero(info["action_mask"])))
+        return choose
+
+    report = run([Agent("my-model", policy_factory=factory), Agent("random", opponent="random")], games_per_pair=4)
+    assert calls == [(19, 0), (20, 1), (21, 0), (22, 1)]
+    assert all(match["status"] == "completed" for match in report["matches"])
+
+
+def test_failures_and_truncations_are_not_wins_draws_or_rating_updates():
+    invalid = Agent("bad-policy", policy_factory=lambda seed, seat: lambda obs, info: 999)
+    report = run([invalid, Agent("random", opponent="random")])
+    assert all(match["status"] == "failed" for match in report["matches"])
+    assert all(row["rated_games"] == 0 and row["rating"] == Rating().to_dict() for row in report["standings"])
+    report = run_round_robin("chess", [Agent("one", opponent="random"), Agent("two", opponent="random")],
+                             config={"max_plies": 2})
+    assert all(match["status"] == "truncated" for match in report["matches"])
+    assert all(row["truncated"] == 2 and row["rated_games"] == 0 for row in report["standings"])
+
+
+def test_fixed_anchor_and_reported_win_rate_interval():
+    report = run([Agent("anchor", opponent="random", initial_rating=Rating(rating=1800, rd=0), fixed=True),
+                  Agent("learner", opponent="minimax:3")], games_per_pair=4)
+    anchor = next(row for row in report["standings"] if row["agent"] == "anchor")
+    assert anchor["rating"]["rating"] == 1800 and anchor["rating"]["rd"] == 0
+    assert anchor["rating"]["games_played"] == 4
+    for row in report["standings"]:
+        low, high = row["win_rate_wilson95"]
+        assert low <= row["win_rate"] <= high
+
+
+def test_policy_error_details_are_not_exported_and_sink_failures_propagate():
+    def fail(seed, seat):
+        raise RuntimeError("private-model-key")
+    report = run([Agent("failure", policy_factory=fail), Agent("random", opponent="random")])
+    assert "private-model-key" not in json.dumps(report)
+
+    def sink(summary, rows):
+        raise RuntimeError("disk full")
+    with pytest.raises(RuntimeError, match="disk full"):
+        run(on_episode=sink)
+
+
+def test_invalid_schedules_and_agent_configs_are_rejected():
+    with pytest.raises(ValueError):
+        run(games_per_pair=3)
+    with pytest.raises(ValueError):
+        run([Agent("same", opponent="random"), Agent("same", opponent="random")])
+    with pytest.raises(ValueError):
+        Agent("anchor", opponent="random", fixed=True)
+    with pytest.raises(ValueError):
+        Agent("missing")
+    with pytest.raises(ValueError):
+        run_round_robin("sudoku", [Agent("one", opponent="random"), Agent("two", opponent="random")])