gammonview 3.1.0__tar.gz → 3.2.0__tar.gz

{gammonview-3.1.0 → gammonview-3.2.0}/.github/workflows/publish.yml

@@ -7,7 +7,7 @@
 # must be done before the first run, because the project does not exist yet:
 #
 #     PyPI project name : gammonview
-#     Owner             : ngvlamis
+#     Owner             : gammonview
 #     Repository name   : gammonview-analysis
 #     Workflow name     : publish.yml
 #     Environment name  : pypi

{gammonview-3.1.0 → gammonview-3.2.0}/CHANGELOG.md

@@ -13,6 +13,31 @@ when the repository was opened; they are kept because they record why things
 are the way they are — particularly the breaking changes and the measurements
 behind several design decisions. Dates are the tag dates.
 
+## 3.2.0 — 2026-11-04
+
+**`analyze_position` takes the money rules: Jacoby and beavers** *(added)*
+
+`analyze_position(..., jacoby=None, beaver=None)` and `gvan-position
+--jacoby/--no-jacoby --beaver/--no-beaver`. Until now every money position was
+analysed under bgsage's defaults, Jacoby on and beavers allowed, with no way to
+ask otherwise. A bool chooses the rule; left unset it is the id's own. The reply
+gains `jacoby` and `beaver`, the rules actually applied, both `False` at any
+match score, where bgsage ignores them. With beavers allowed, a wrong double is
+answered with a beaver and the cube's `double_take_equity` is the beaver's
+(twice the take's), with `is_beaver` set, as it always was.
+
+**A money XGID's rules field is read as the rules** *(fixed)*
+
+At money, the XGID field that holds the Crawford flag in a match holds the
+rules instead -- "Jacoby+2xBeaver", in XG's own spec (eXtreme Gammon 2 Help,
+"XGID"), now quoted in `parse_xgid`'s docstring. It was read as Crawford in both
+cases, so a money "1" claimed a Crawford game and the Jacoby rule it stated was
+lost, and so was the beaver bit. `PositionState` gains `jacoby` and `beaver`
+(None for an OGID, which cannot say, and at a match score). Behaviour change:
+unset, both follow the XGID, so a money XGID with "0" there -- which states
+"No Jacoby, no Beaver" -- is now analysed with neither, where it was analysed
+with both. An OGID is still analysed with both.
+
 ## 3.1.0 — 2026-10-22
 
 **`engine_build` names the gammonview version that ran the analysis** *(changed)*

{gammonview-3.1.0 → gammonview-3.2.0}/CONTRIBUTING.md

@@ -6,7 +6,7 @@ you need to know before sending one.
 ## Getting set up
 
 ```bash
-git clone https://github.com/ngvlamis/gammonview-analysis
+git clone https://github.com/gammonview/gammonview-analysis
 cd gammonview-analysis
 uv sync          # gvformat + gvanalysis + bgsage + everything the tests need
 ```

{gammonview-3.1.0 → gammonview-3.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: gammonview
-Version: 3.1.0
+Version: 3.2.0
 Summary: Backgammon match analysis — the pure-Python OGXM/GVA codec (`gvformat`) plus bgsage-powered match and position analysis (`gvanalysis`).
-Project-URL: Homepage, https://github.com/ngvlamis/gammonview-analysis
-Project-URL: Repository, https://github.com/ngvlamis/gammonview-analysis
-Project-URL: Issues, https://github.com/ngvlamis/gammonview-analysis/issues
+Project-URL: Homepage, https://github.com/gammonview/gammonview-analysis
+Project-URL: Repository, https://github.com/gammonview/gammonview-analysis
+Project-URL: Issues, https://github.com/gammonview/gammonview-analysis/issues
 Author: Nicholas Vlamis
 License-Expression: MIT
 License-File: LICENSE
@@ -28,15 +28,15 @@ Requires-Dist: pyyaml>=6.0.3; extra == 'engine'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ngvlamis/gammonview-analysis/main/assets/logo.png"
+  <img src="https://raw.githubusercontent.com/gammonview/gammonview-analysis/main/assets/logo.png"
        alt="" width="104" height="104">
 </p>
 
 <h1 align="center">GammonView</h1>
 
 <p align="center">
-  <a href="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/ci.yml"><img src="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/engine.yml"><img src="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/engine.yml/badge.svg" alt="engine"></a>
+  <a href="https://github.com/gammonview/gammonview-analysis/actions/workflows/ci.yml"><img src="https://github.com/gammonview/gammonview-analysis/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/gammonview/gammonview-analysis/actions/workflows/engine.yml"><img src="https://github.com/gammonview/gammonview-analysis/actions/workflows/engine.yml/badge.svg" alt="engine"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-green.svg" alt="Licence: MIT"></a>
 </p>
@@ -82,7 +82,7 @@ the environment — it installs both packages in editable mode, plus bgsage and
 the test dependencies:
 
 ```bash
-git clone https://github.com/ngvlamis/gammonview-analysis.git
+git clone https://github.com/gammonview/gammonview-analysis.git
 cd gammonview-analysis
 uv sync
 uv run python tests/run_all.py --fast     # ~3s, no engine needed

{gammonview-3.1.0 → gammonview-3.2.0}/README.md

@@ -1,13 +1,13 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ngvlamis/gammonview-analysis/main/assets/logo.png"
+  <img src="https://raw.githubusercontent.com/gammonview/gammonview-analysis/main/assets/logo.png"
        alt="" width="104" height="104">
 </p>
 
 <h1 align="center">GammonView</h1>
 
 <p align="center">
-  <a href="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/ci.yml"><img src="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/engine.yml"><img src="https://github.com/ngvlamis/gammonview-analysis/actions/workflows/engine.yml/badge.svg" alt="engine"></a>
+  <a href="https://github.com/gammonview/gammonview-analysis/actions/workflows/ci.yml"><img src="https://github.com/gammonview/gammonview-analysis/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/gammonview/gammonview-analysis/actions/workflows/engine.yml"><img src="https://github.com/gammonview/gammonview-analysis/actions/workflows/engine.yml/badge.svg" alt="engine"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-green.svg" alt="Licence: MIT"></a>
 </p>
@@ -53,7 +53,7 @@ the environment — it installs both packages in editable mode, plus bgsage and
 the test dependencies:
 
 ```bash
-git clone https://github.com/ngvlamis/gammonview-analysis.git
+git clone https://github.com/gammonview/gammonview-analysis.git
 cd gammonview-analysis
 uv sync
 uv run python tests/run_all.py --fast     # ~3s, no engine needed

{gammonview-3.1.0 → gammonview-3.2.0}/docs/CLI.md

@@ -174,6 +174,8 @@ position shape is matched (an XGID never matches it).
 | Flag | Effect |
 |---|---|
 | `--level LEVEL` | `1ply`, `2ply`, `3ply`, `4ply`, `truncated1/2/3`, `rollout`. Default `3ply`. |
+| `--jacoby` / `--no-jacoby` | Money games: analyse with or without the Jacoby rule (gammons count single while the cube is centred). Default: what the id says — an XGID's field 8 — and on for an OGID, which has no field for it. Ignored at a match score. |
+| `--beaver` / `--no-beaver` | Money games: allow or forbid beavers. Default as for `--jacoby`: the XGID's field 8, allowed for an OGID. Ignored at a match score. |
 | `--no-progress` | Suppress the rollout progress bar. |
 
 At a rollout level a progress bar is drawn on **stderr**, so piping the report

{gammonview-3.1.0 → gammonview-3.2.0}/gvanalysis/position.py

@@ -58,6 +58,12 @@ class PositionState:
     #: perspective either way; this is what maps a move back to the absolute
     #: point numbering the OGXM step form (and every consumer of it) uses.
     mover_is_white: bool = True
+    #: The money-game Jacoby rule, when the id says: an XGID's rules field
+    #: does at money, an OGID never does (None). Always None at a match score.
+    jacoby: bool | None = None
+    #: Whether beavers are allowed, the other half of that field; None in the
+    #: same cases.
+    beaver: bool | None = None
 
 
 #: Back-compat alias -- this was XGID-only before OGID input was added.
@@ -65,6 +71,32 @@ XGIDState = PositionState
 
 
 def parse_xgid(xgid: str) -> PositionState:
+    """Parse an XGID into the mover-perspective state bgsage analyses.
+
+    The XGID is eXtreme Gammon's, specified in its own help ("XGID", eXtreme
+    Gammon 2 Help rev. 1.01, 2011, pp. 145-146) as ten colon-separated fields:
+
+      1. Position   26 chars: the top player's bar, points 1-24 from the
+                    bottom player's side, the bottom player's bar. '-' empty,
+                    'A'-'P' 1-16 bottom-player checkers, 'a'-'p' top-player.
+      2. Cube       the cube is 2**value.
+      3. Cube pos.  1 bottom player owns it, 0 centred, -1 top player.
+      4. Turn       1 the bottom player's turn, -1 the top player's.
+      5. Dice       "00" to roll or double, "D" doubled (take or drop), "B"
+                    beavered, "R" raccooned, or the two dice ("35").
+      6. Score 1    the bottom player's.
+      7. Score 2    the top player's.
+      8. Crawford, Jacoby
+                    "Match play: 1 means the current game is Crawford, 0 means
+                    the current game is not played with the Crawford rule.
+                    Unlimited games: the value is a Jacoby+2xBeaver" --
+                    0 none, 1 Jacoby, 2 beaver, 3 both.
+      9. Match length  0 for unlimited games (money).
+     10. Max cube   2**value.
+
+    (GNU Backgammon's ``SetXGID`` reads field 8 the same way.) Field 10 is
+    optional here, as it is in ids found in the wild.
+    """
     s = xgid.strip()
     if s.upper().startswith("XGID="):
         s = s[5:]
@@ -120,7 +152,13 @@ def parse_xgid(xgid: str) -> PositionState:
     die2 = int(dice_str[1]) if len(dice_str) > 1 and dice_str[1].isdigit() else 0
 
     match_len = int(parts[8]) if parts[8].lstrip("-").isdigit() else 0
-    is_crawford = parts[7] == "1"
+    # Field 8 is two fields in one (see the docstring): the Crawford flag in a
+    # match, Jacoby + 2 x Beaver at money -- so a money "1" is the Jacoby rule,
+    # not a Crawford game money cannot have.
+    rules = int(parts[7]) if parts[7].isdigit() else 0
+    is_crawford = match_len > 0 and rules == 1
+    jacoby = bool(rules & 1) if match_len <= 0 else None
+    beaver = bool(rules & 2) if match_len <= 0 else None
 
     if match_len > 0:
         # Scores are written player 1 (White) first; `away1` is the MOVER's.
@@ -141,7 +179,7 @@ def parse_xgid(xgid: str) -> PositionState:
 
     return PositionState(
         board, die1, die2, cube_value, cube_owner, away1, away2, is_crawford,
-        mover_is_white=mover_is_white,
+        mover_is_white=mover_is_white, jacoby=jacoby, beaver=beaver,
     )
 
 
@@ -232,6 +270,8 @@ def analyze_position(
     max_alternatives: int = MAX_ALTERNATIVES,
     analyzer=None,
     on_progress: "Callable[[int, int, str], None] | None" = None,
+    jacoby: bool | None = None,
+    beaver: bool | None = None,
 ) -> dict:
     """Analyze one position and return the result as an OGXM-shaped dict.
 
@@ -253,6 +293,22 @@ def analyze_position(
     one costs ~40ms, worth reusing across requests); it must have been built at
     ``level``, which is reported back as ``eval_level``.
 
+    ``jacoby`` is the money-game rule the position is played under: gammons
+    and backgammons count single while the cube is centred. Left as ``None``
+    it is the id's own: a money XGID states it in its rules field, and an OGID,
+    which cannot, is read under the rule (bgsage's own default). A bool
+    overrides the id. It means nothing at a match score, where bgsage ignores
+    it, and the reply's ``jacoby`` reports the rule actually applied -- so it
+    is ``False`` for every match position.
+
+    ``beaver`` is the same for beavers: whether a player doubled may redouble
+    at once and keep the cube. Left as ``None`` it is the XGID's own beaver bit,
+    and allowed for an OGID (bgsage's default). Allowed, a wrong double --
+    double/take below zero -- is answered with a beaver, and the cube's
+    ``double_take_equity`` is that beaver's (twice the take's), with
+    ``is_beaver`` set. The reply's ``beaver`` is the rule applied, ``False`` at
+    a match score.
+
     ``on_progress(completed, total, phase)`` reports a rollout's progress; it is
     never called at the full-width levels, which return too fast to report.
     ``phase`` is ``"trials"`` for the planned work and ``"finalizing"`` for the
@@ -280,6 +336,13 @@ def analyze_position(
         away2=state.away2,
         is_crawford=state.is_crawford,
     )
+    money = not state.away1 and not state.away2
+    if jacoby is None:
+        jacoby = state.jacoby if state.jacoby is not None else True
+    if beaver is None:
+        beaver = state.beaver if state.beaver is not None else True
+    match_kwargs["jacoby"] = jacoby
+    match_kwargs["beaver"] = beaver
 
     started = time.perf_counter()
     result: dict = {
@@ -292,6 +355,8 @@ def analyze_position(
         "away1": state.away1,
         "away2": state.away2,
         "is_crawford": state.is_crawford,
+        "jacoby": bool(jacoby) and money,
+        "beaver": bool(beaver) and money,
         "dice": [state.die1, state.die2] if is_checker else None,
     }
 
@@ -431,6 +496,17 @@ def main() -> None:
     parser.add_argument(
         "--level", default="3ply", choices=EVAL_LEVELS,
         help="Eval level (default: 3ply)")
+    parser.add_argument(
+        "--jacoby", action=argparse.BooleanOptionalAction, default=None,
+        help="Money games: analyse with or without the Jacoby rule, gammons "
+             "counting single while the cube is centred. Default: what the id "
+             "says -- an XGID's rules field -- and on for an OGID, which cannot "
+             "say. Ignored at a match score")
+    parser.add_argument(
+        "--beaver", action=argparse.BooleanOptionalAction, default=None,
+        help="Money games: allow or forbid beavers. Default: what the id says "
+             "-- an XGID's rules field -- and allowed for an OGID. Ignored at a "
+             "match score")
     parser.add_argument(
         "--no-progress", action="store_true",
         help="Suppress the rollout progress bar (it is stderr-only and already "
@@ -439,7 +515,13 @@ def main() -> None:
 
     fmt = "OGID" if looks_like_ogid(args.position_id) else "XGID"
     state = parse_position_id(args.position_id)
-    context = "money game" if state.away1 == 0 else f"match {state.away1}-away vs {state.away2}-away"
+    jacoby = args.jacoby if args.jacoby is not None else (
+        state.jacoby if state.jacoby is not None else True)
+    beaver = args.beaver if args.beaver is not None else (
+        state.beaver if state.beaver is not None else True)
+    context = ("money game, " + ("Jacoby" if jacoby else "no Jacoby")
+               + (", beavers" if beaver else ", no beavers")
+               if state.away1 == 0 else f"match {state.away1}-away vs {state.away2}-away")
     print(f"Position ({fmt}): cube={state.cube_value} ({state.cube_owner})  {context}"
           + ("  [Crawford]" if state.is_crawford else ""))
 
@@ -468,7 +550,8 @@ def main() -> None:
 
     try:
         result = analyze_position(args.position_id, level=args.level,
-                                  on_progress=_progress)
+                                  on_progress=_progress, jacoby=jacoby,
+                                  beaver=beaver)
     finally:
         if bar is not None:
             bar.clear()

{gammonview-3.1.0 → gammonview-3.2.0}/gvformat-js/README.md

@@ -7,7 +7,7 @@ OGIDs. **No engine, no WebAssembly, no build step.** One runtime
 dependency (`pako`, for zlib).
 
 This is the browser half of
-[gammonview-analysis](https://github.com/ngvlamis/gammonview-analysis): Python
+[gammonview-analysis](https://github.com/gammonview/gammonview-analysis): Python
 writes `.gvab` server-side, this reads it client-side. It is an ESM mirror of the
 Python `gvformat` package and **the definitive copy of the JavaScript** — the
 port is maintained here, not downstream.

{gammonview-3.1.0 → gammonview-3.2.0}/gvformat-js/package.json

@@ -10,12 +10,12 @@
   "description": "OGXM binary codec — read/write .gvab match files",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ngvlamis/gammonview-analysis.git",
+    "url": "git+https://github.com/gammonview/gammonview-analysis.git",
     "directory": "gvformat-js"
   },
-  "homepage": "https://github.com/ngvlamis/gammonview-analysis/tree/main/gvformat-js",
+  "homepage": "https://github.com/gammonview/gammonview-analysis/tree/main/gvformat-js",
   "bugs": {
-    "url": "https://github.com/ngvlamis/gammonview-analysis/issues"
+    "url": "https://github.com/gammonview/gammonview-analysis/issues"
   },
   "publishConfig": {
     "access": "public"

{gammonview-3.1.0 → gammonview-3.2.0}/pyproject.toml

@@ -31,9 +31,9 @@ classifiers = [
 dependencies = []
 
 [project.urls]
-Homepage = "https://github.com/ngvlamis/gammonview-analysis"
-Repository = "https://github.com/ngvlamis/gammonview-analysis"
-Issues = "https://github.com/ngvlamis/gammonview-analysis/issues"
+Homepage = "https://github.com/gammonview/gammonview-analysis"
+Repository = "https://github.com/gammonview/gammonview-analysis"
+Issues = "https://github.com/gammonview/gammonview-analysis/issues"
 
 [project.optional-dependencies]
 # The bgsage-powered analysis layer (`gvanalysis`: game_eval, match, position

{gammonview-3.1.0 → gammonview-3.2.0}/tests/test_analyze_position.py

@@ -29,7 +29,7 @@ from pathlib import Path
 _REPO_ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(_REPO_ROOT))
 
-from gvanalysis.position import EVAL_LEVELS, analyze_position
+from gvanalysis.position import EVAL_LEVELS, analyze_position, parse_position_id
 
 _checks = 0
 _failures: list[str] = []
@@ -227,6 +227,69 @@ def main() -> int:
           == [a["notation"] for a in many["alternatives"][:5]],
           "a smaller cap truncates the same ranking, it does not reorder it")
 
+    print("11. the Jacoby rule is the caller's, and money-only")
+    # A blitz: three checkers on the bar against a closed board. Gammons are
+    # most of the wins, so with the cube centred the rule decides the cube:
+    # under Jacoby a gammon counts single and holding is worth at most a point,
+    # without it holding is worth far more than the point a pass gives.
+    blitz = "XGID=cBBBBBB-C----------cccc---:0:0:1:00:0:0:0:0:10"
+    jac = analyze_position(blitz, level="1ply", jacoby=True)
+    nojac = analyze_position(blitz, level="1ply", jacoby=False)
+    check(jac["jacoby"] is True and nojac["jacoby"] is False,
+          "the reply says which rule was applied")
+    check(jac["cube"]["no_double_equity"] <= 1.0 + 1e-9,
+          f"under Jacoby, holding is worth at most a point (got {jac['cube']['no_double_equity']})")
+    check(nojac["cube"]["no_double_equity"] > 1.2,
+          f"without it, gammons make holding worth more (got {nojac['cube']['no_double_equity']})")
+    match = analyze_position(
+        "XGID=cBBBBBB-C----------cccc---:0:0:1:00:0:0:0:7:10", level="1ply")
+    check(match["jacoby"] is False, "a match position reports no Jacoby, however asked")
+
+    print("12. a money XGID's rules field is the Jacoby rule, not Crawford")
+    # Field 8 at money is "Jacoby+2xBeaver" (XG's own spec; see parse_xgid).
+    # An OGID has no such field.
+    said_on = parse_position_id(blitz.replace(":0:0:0:0:10", ":0:0:1:0:10"))
+    said_off = parse_position_id(blitz)
+    check(said_on.jacoby is True and said_on.is_crawford is False,
+          "a money '1' is Jacoby, and no Crawford game")
+    check(parse_position_id(blitz.replace(":0:0:0:0:10", ":0:0:3:0:10")).jacoby is True,
+          "Jacoby and beavers together ('3') is still Jacoby")
+    check(said_off.jacoby is False, "a money '0' states the rule is off")
+    check(parse_position_id(OPENING_31_OGID).jacoby is None, "an OGID says nothing")
+    m = parse_position_id("XGID=-b----E-C---eE---c-e----B-:0:0:1:31:0:0:1:7:10")
+    check(m.is_crawford is True and m.jacoby is None, "at a match score '1' is still Crawford")
+    check(analyze_position(blitz.replace(":0:0:0:0:10", ":0:0:1:0:10"), level="1ply")["jacoby"] is True
+          and analyze_position(blitz, level="1ply")["jacoby"] is False,
+          "left unset, the analysis follows what the XGID says")
+    check(analyze_position(OPENING_CUBE_XGID.replace("XGID=", ""), level="1ply")["jacoby"] is False,
+          "(an XGID written with '0' there, as most are, says off)")
+
+    print("13. beavers: the caller's, or the XGID's, and money-only")
+    # The blitz from the other side: three checkers on the bar against a
+    # closed board, and it is their turn. A double here is a gift, so if the
+    # rules allow it the opponent beavers -- which doubles the take's equity.
+    victim = "XGID=cBBBBBB-C----------cccc---:0:0:-1:00:0:0:0:0:10"
+    allowed = analyze_position(victim, level="1ply", beaver=True)
+    forbidden = analyze_position(victim, level="1ply", beaver=False)
+    check(allowed["beaver"] is True and forbidden["beaver"] is False,
+          "the reply says which rule was applied")
+    check(allowed["cube"]["is_beaver"] and not forbidden["cube"]["is_beaver"],
+          "a wrong double is beavered only when beavers are allowed")
+    check(abs(allowed["cube"]["double_take_equity"]
+              - 2 * forbidden["cube"]["double_take_equity"]) < 1e-3,
+          f"and the beaver doubles the take's equity (got {allowed['cube']['double_take_equity']} "
+          f"vs {forbidden['cube']['double_take_equity']})")
+    check(parse_position_id(victim.replace(":0:0:0:0:10", ":0:0:2:0:10")).beaver is True
+          and parse_position_id(victim).beaver is False
+          and parse_position_id(OPENING_31_OGID).beaver is None,
+          "an XGID's beaver bit is read; an OGID says nothing")
+    check(analyze_position(victim.replace(":0:0:0:0:10", ":0:0:2:0:10"), level="1ply")["cube"]["is_beaver"]
+          and not analyze_position(victim, level="1ply")["cube"]["is_beaver"],
+          "left unset, the analysis follows the XGID")
+    check(analyze_position(
+        "XGID=cBBBBBB-C----------cccc---:0:0:-1:00:0:0:0:7:10", level="1ply")["beaver"] is False,
+          "a match position reports no beavers")
+
     print(f"\n{_checks - len(_failures)}/{_checks} checks passed.")
     if _failures:
         print("FAILURES:")