caissify-pairings 0.1.0__py3-none-any.whl

caissify_pairings/__init__.py

@@ -0,0 +1,52 @@
+"""
+caissify-pairings — Pluggable chess tournament pairing engines.
+
+Public API:
+    generate_pairings(system, players, previous_pairings, round_number,
+                      total_rounds, **kwargs) -> List[dict]
+
+Engines:
+    "dutch"  — FIDE Dutch System (C.04.3, Feb 2026)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from typing import List, Set, Tuple
+
+from caissify_pairings.engines import available_systems, get_engine
+
+
+def generate_pairings(
+    system: str,
+    players: List[dict],
+    previous_pairings: Set[Tuple[int, int]],
+    round_number: int,
+    total_rounds: int,
+    **kwargs,
+) -> List[dict]:
+    """
+    Generate pairings using the specified pairing system.
+
+    Args:
+        system:             Engine name — "dutch", "swiss", etc.
+        players:            List of player dicts (see BasePairingEngine).
+        previous_pairings:  Set of (id_a, id_b) tuples from prior rounds.
+        round_number:       1-based round number to pair.
+        total_rounds:       Total rounds in the tournament.
+        **kwargs:           Engine-specific options (bye_value, max_byes_per_player, …).
+
+    Returns:
+        List of pairing dicts with white_id, black_id, table, and optional
+        bye/bye_type fields.
+    """
+    engine_cls = get_engine(system)
+    engine = engine_cls(
+        players=players,
+        previous_pairings=previous_pairings,
+        round_number=round_number,
+        total_rounds=total_rounds,
+        **kwargs,
+    )
+    return engine.generate_pairings()

caissify_pairings/__main__.py

@@ -0,0 +1,73 @@
+"""
+CLI entry point for caissify-pairings.
+
+Modes:
+    caissify-pairings                  — read JSON from stdin, output pairings
+    caissify-pairings --check FILE.trf — FPC: check a TRF file against engine
+    caissify-pairings-check FILE.trf   — FPC shortcut
+    caissify-pairings-rtg [options]    — RTG: generate random tournaments
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from caissify_pairings import generate_pairings
+
+
+def main() -> None:
+    # If --check flag is present, delegate to FPC
+    if len(sys.argv) >= 2 and sys.argv[1] == "--check":
+        from caissify_pairings.fpc import main as fpc_main
+        # Shift argv so fpc_main sees the file as argv[1]
+        sys.argv = [sys.argv[0]] + sys.argv[2:]
+        fpc_main()
+        return
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        print(json.dumps({"error": "Empty input. Provide JSON on stdin."}), file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(json.dumps({"error": f"Invalid JSON: {e}"}), file=sys.stderr)
+        sys.exit(1)
+
+    system = data.get("system", "dutch")
+    players = data.get("players", [])
+    round_number = data.get("round_number", 1)
+    total_rounds = data.get("total_rounds", 9)
+
+    # Convert list-of-lists to set-of-tuples for previous_pairings
+    raw_pairings = data.get("previous_pairings", [])
+    previous_pairings = {(a, b) for a, b in raw_pairings}
+
+    # Forward engine-specific options
+    kwargs = {}
+    if "bye_value" in data:
+        kwargs["bye_value"] = data["bye_value"]
+    if "max_byes_per_player" in data:
+        kwargs["max_byes_per_player"] = data["max_byes_per_player"]
+
+    try:
+        pairings = generate_pairings(
+            system=system,
+            players=players,
+            previous_pairings=previous_pairings,
+            round_number=round_number,
+            total_rounds=total_rounds,
+            **kwargs,
+        )
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+    json.dump(pairings, sys.stdout, indent=2)
+    print()  # trailing newline
+
+
+if __name__ == "__main__":
+    main()

caissify_pairings/base.py

@@ -0,0 +1,57 @@
+"""
+Abstract base class for all pairing engines.
+
+Every engine in caissify_pairings must subclass BasePairingEngine and
+implement generate_pairings().  This guarantees a uniform I/O contract
+across Dutch, Swiss, Burstein, and any future system.
+"""
+
+from __future__ import annotations
+
+import abc
+from typing import Dict, List, Set, Tuple
+
+
+class BasePairingEngine(abc.ABC):
+    """
+    Abstract base for chess tournament pairing engines.
+
+    Input contract (constructor):
+        players:            List[dict] — each dict must contain at minimum:
+                            id, name, score, rating, starting_number,
+                            color_hist, float_history, bye_count
+        previous_pairings:  Set[Tuple[int, int]] — all (id_a, id_b) pairs
+                            from earlier rounds (order-insensitive)
+        round_number:       int — 1-based round to pair
+        total_rounds:       int — total rounds in the tournament
+
+    Output contract (generate_pairings):
+        List[dict] where each dict has:
+            white_id:  int          — player ID assigned white
+            black_id:  int | None   — player ID assigned black (None = bye)
+            table:     int          — 1-based table number
+            bye:       bool         — (optional) True for bye pairings
+            bye_type:  str          — (optional) FIDE bye code, e.g. "U"
+    """
+
+    #: Override in subclass — must match the key used in the engine registry.
+    name: str = ""
+
+    def __init__(
+        self,
+        players: List[dict],
+        previous_pairings: Set[Tuple[int, int]],
+        round_number: int,
+        total_rounds: int,
+        **kwargs,
+    ):
+        self.players = players
+        self.previous_pairings = previous_pairings
+        self.round_number = round_number
+        self.total_rounds = total_rounds
+        self.options = kwargs
+
+    @abc.abstractmethod
+    def generate_pairings(self) -> List[dict]:
+        """Generate pairings for the current round.  Must be implemented."""
+        ...

caissify_pairings/engines/__init__.py

@@ -0,0 +1,43 @@
+"""
+Engine registry — maps system names to engine classes.
+
+To register a new engine, add it to ENGINES below.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Type
+
+from caissify_pairings.base import BasePairingEngine
+
+# Lazy imports to keep startup fast — engines are imported only when requested.
+_REGISTRY: Dict[str, str] = {
+    "dutch": "caissify_pairings.engines.dutch",
+}
+
+# Populated on first access
+_CACHE: Dict[str, Type[BasePairingEngine]] = {}
+
+
+def get_engine(system: str) -> Type[BasePairingEngine]:
+    """Return the engine class for the given system name."""
+    if system in _CACHE:
+        return _CACHE[system]
+
+    module_path = _REGISTRY.get(system)
+    if module_path is None:
+        available = ", ".join(sorted(_REGISTRY.keys()))
+        raise ValueError(
+            f"Unknown pairing system {system!r}. Available: {available}"
+        )
+
+    import importlib
+    mod = importlib.import_module(module_path)
+    engine_cls = mod.Engine  # Convention: each engine module exposes `Engine`
+    _CACHE[system] = engine_cls
+    return engine_cls
+
+
+def available_systems() -> list[str]:
+    """Return a sorted list of registered system names."""
+    return sorted(_REGISTRY.keys())