gammonview 1.0.0__py3-none-any.whl

gammonview-1.0.0.dist-info/METADATA

@@ -0,0 +1,319 @@
+Metadata-Version: 2.5
+Name: gammonview
+Version: 1.0.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
+Author: Nicholas Vlamis
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD-PARTY-NOTICES.md
+Keywords: analysis,backgammon,bgsage,gvab,match-equity,ogxm,xg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: engine
+Requires-Dist: bgsage>=2.0.20260907; extra == 'engine'
+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"
+       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://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>
+
+The backgammon analysis backend behind
+**[gammonview.com](https://gammonview.com)**: read and write the site's
+`.gvab`/`.gva` match files, import `.mat`/`.xg`/`.bgf`, analyze a match or a
+single position with the [bgsage](https://pypi.org/project/bgsage/) engine, and
+compute per-decision error rate (PR), luck and cube statistics.
+
+Those files are based on **OGXM** — the chunked match format from
+[HedgeHog](https://gitlab.com/eranlambooij/hedgehog-public), not ours — extended
+to carry what bgsage's analysis produces. This repo reads OGXM; what it writes is
+that extended form. See [The format](#the-format).
+
+It ships as two importable Python packages, plus a JavaScript port of the codec
+for the browser:
+
+- **`gvformat`** — the pure-stdlib codec: read/write the `.gvab` binary, `.gva`
+  JSON conversion, `.xg`/`.bgf` import, compute-on-read stats, OGID. **Zero
+  third-party deps** — `pip install gammonview` and `import gvformat` anywhere,
+  no engine required. This is the format layer: everything else here, Python and
+  JavaScript alike, reads and writes through it.
+- **`gvanalysis`** — the [bgsage](https://pypi.org/project/bgsage/)-powered
+  analysis: `analyze_match` (a match file in, analyzed `.gvab` bytes out),
+  `analyze_file` (the same work stopping at the OGXM document), and single-position
+  analysis. Depends on `gvformat` + bgsage (the `[engine]` extra). Dependencies
+  flow one way: `gvanalysis` → `gvformat`, never back.
+- **`@gammonview/gvformat`** — the same codec in JavaScript, on npm. What reads
+  the analysis in the browser. See [In the browser](#in-the-browser).
+
+## Install
+
+To use the packages, install from PyPI — no clone needed:
+
+```bash
+pip install gammonview               # the codec alone (gvformat), no engine
+pip install "gammonview[engine]"     # adds bgsage, for gvanalysis
+```
+
+To work on them, clone the repo and let [uv](https://docs.astral.sh/uv/) build
+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
+cd gammonview-analysis
+uv sync
+uv run python tests/run_all.py --fast     # ~3s, no engine needed
+```
+
+Every command below is written `uv run …` for that checkout; from a plain
+`pip install`, drop the prefix.
+
+## Quickstart
+
+Server one-liner — analyze a dropped `.mat` and get the analyzed `.gvab` back,
+ready to store and ship to the client:
+
+```python
+from gvanalysis import analyze_match
+data = analyze_match("match.mat", preset="world_class")   # analyzed .gvab bytes
+```
+
+It runs the engine over every decision, and the bytes carry the match *and* the
+analysis. Any input the codec reads works — `.mat`, `.gva`, `.gvab` — and one
+that already carries analysis keeps it, with ours appended.
+
+It returns `.gvab` (binary), always — that is the artifact to store and ship.
+For the JSON, `read_gvab(data)` is the `.gva`; to stop a step earlier and work
+with the document itself, `analyze_file` returns it directly. (The CLI is the
+other way round: `gvan-match` writes `.gva` unless asked for `--gvab`, because
+a file you open by hand is likelier to want to be readable.)
+
+## The format
+
+The files this repo reads and writes — `.gvab` (binary) and `.gva` (JSON) — are
+based directly on **OGXM** (OpenGammon eXtensible Match), the chunked match
+format from [HedgeHog](https://gitlab.com/eranlambooij/hedgehog-public), and
+extend it with what GammonView's viewer shows and OGXM has no field for: luck,
+per-decision PR and illegal-move flags, and per-alternative eval levels — all in
+one `GVAN` chunk — plus match metadata like `event`, `site` and `cube_limit`.
+
+**We read OGXM.** `read_gvab` takes a file this repo never wrote, including one
+carrying another engine's analysis, and `gvan-match` appends its own analysis
+block rather than replacing what is already there.
+
+We make no claim in the other direction, and that is about us, not about OGXM.
+One of our choices is a genuine departure: in match play we store **normalized
+equity** in the three cube equity fields, where the base spec specifies **raw
+MWC**. We do it for quantization — these fields are an `int16` at 1e-4, which
+gives normalized equity about 20,000 usable steps at any score, while raw MWC
+has as few as **16** at a lopsided one — and we recover MWC on read from the
+shipped MET. It is the right trade for us and it is still a difference a reader
+cannot see: same fields, same layout, different numbers.
+
+So: treat these as GammonView files that an OGXM reader may well be able to make
+partial sense of, not as OGXM files with extras. The two spec documents describe
+**what this repo writes** — the base spec with every addition marked
+`[GammonView extension]` and every divergence marked, including where a base
+reader would go wrong. The upstream specs they track are in HedgeHog's `docs/`
+and remain the authority on the base format.
+
+## In the browser
+
+The codec has a JavaScript twin, published to npm as
+**[`@gammonview/gvformat`](https://www.npmjs.com/package/@gammonview/gvformat)**:
+
+```bash
+npm install @gammonview/gvformat
+```
+
+```js
+import { read_gvab, convert_mat, parse_ogid } from '@gammonview/gvformat';
+
+const match = read_gvab(bytes);           // .gvab -> .gva JSON
+const dropped = convert_mat(matText);     // .mat  -> .gva JSON, no analysis
+const pos   = parse_ogid(match.games[0].plies[0].ogid_before);
+```
+
+An ESM port of `gvformat` — the same reads, writes, source converters and OGID
+handling, with **no engine, no WebAssembly and no build step**. It is how
+gammonview.com parses a dropped `.xg`/`.bgf`/`.mat` client-side and renders the
+`.gvab` the Python side produced.
+
+The port lives in [`gvformat-js/`](gvformat-js/) and is maintained here rather
+than downstream. Python and JavaScript must agree byte-for-byte — the same
+`.gvab` in gives the same `.gva` JSON out — and the two test suites check that
+from either side.
+
+There is no JavaScript port of `gvanalysis`: analysis needs the engine, and the
+engine is Python-side only.
+
+## Command-line tools
+
+Entry points are defined in `pyproject.toml` and run with `uv run`:
+
+| CLI | What it does |
+|---|---|
+| `gvan-match` | Analyze a match (`.mat`, `.gva`/`.ogxm`, `.gvab`), compute per-move PR → `.gva`/`.gvab` |
+| `gvan-batch` | The same over many files or a directory, one output each |
+| `gvan-position` | Analyze a single position from an **XGID or OGID** |
+| `xg2gva` | Convert an eXtreme Gammon `.xg` file to `.gva` JSON (no engine) |
+| `bgf2gva` | Convert a BGBlitz `.bgf` file to `.gva` JSON (no engine) |
+
+```bash
+uv run gvan-match match.mat --preset world_class --gvab   # binary out, not .gva
+uv run gvan-match match.gvab --preset fast                # re-analyze a binary, append
+uv run gvan-match match.mat --link                        # print a shareable URL
+uv run gvan-batch matches/ --preset fast                  # a dir -> its match files
+uv run gvan-position "XGID=-b----E-C---eE---c-e----B-:0:-1:1:31:0:0:0:0"
+uv run gvan-position "11ccccchhhjjjjj:66666888dddddoo:N0N:13:B:R:0:0:0:0"
+```
+
+An OGXM input keeps any analysis it already carries — ours is appended as a new
+block rather than replacing it. `--link` encodes the whole match into a
+`gammonview.com` URL fragment, so it needs no hosted file; `--browser` opens it.
+
+### Analysis presets
+
+`--preset` selects an eXtreme Gammon–style scheme: a cheap first pass screens
+every decision, and a stronger pass runs only where it is needed. The six
+built-ins:
+
+| Preset (aliases) | 1st pass | Middle tier | 2nd pass | XG equivalent |
+|---|---|---|---|---|
+| `very_quick` (`vq`) | `2ply` | — | — | Very quick |
+| `fast` (`f`) | `2ply` | — | `3ply` | Fast |
+| `deep` (`d`) | `3ply` | — | — | Deep |
+| `balanced` (`b`) | `2ply` | `3ply` (both kinds) | `truncated2` | — (quality/speed) |
+| `world_class` (`wc`) | `4ply` | — | `truncated2` | World Class (XG Roller+) |
+| `world_class_fast` (`wcf`) | `3ply` | `truncated2` (**cube only**) | `truncated2` | World Class (3-tier) |
+
+The second pass runs on an **error**; the middle tier runs on a **borderline**
+decision the screen would otherwise have settled. `fast` is the default.
+
+#### Which one to use
+
+493 matches were analyzed by XG at World Class and by each of the three strong
+presets, then compared decision by decision:
+
+| | mean gap to XG's match PR | same checker play as XG | PR within 1 of XG | relative cost |
+|---|---|---|---|---|
+| `world_class` | 0.434 | 90.3% | 91.8%             | 45× |
+| `world_class_fast` | 0.441 | 90.0% | 90.7%             | 24× |
+| `balanced` | 0.540 | 89.2% | 86.7%             | 6× |
+
+**Mean gap** is the average distance between the two *ratings* of the same
+player-match, in either direction: rate a match with `world_class` and XG rates
+it 0.434 PR away, typically. It is not what following the preset costs you —
+priced by XG's own equities, a player who made `world_class`'s recommended
+checker play every time would post a PR of 0.333, `world_class_fast` 0.353,
+`balanced` 0.412. All three are inside what XG itself calls world-class play.
+
+Cost is mean wall clock relative to `fast` over four matches, and varies with
+the match — see [the timings](docs/CLI.md#what-they-cost).
+
+- **`world_class_fast` is the recommended analysis.** It lands 0.007 PR behind
+  the deepest preset for a little under half the time. The two sit three times
+  closer to each other (0.136) than either does to XG, because what separates
+  them from XG is the *engine*, not the search depth — 95% of
+  `world_class_fast`'s squared PR error against XG is that engine floor, which
+  no preset can spend its way past.
+- **`world_class` is for reproducing XG specifically**, not for being more
+  accurate. Its only real edge is on borderline cubes, and it gets there by
+  rolling them out *less* often than `world_class_fast` does — which is
+  XG-like, not demonstrably better. It costs roughly twice as much for that.
+- **`balanced` is the quality/speed option**, and the only one of the three with
+  real headroom: upgrading it recovers eight times as much error as upgrading
+  `world_class_fast` does.
+
+Every number above measures *similarity to XG*, which is not the same as being
+right — where the two engines differ there is no arbiter here to say which is
+correct. **[`docs/PRESET_ACCURACY.md`](docs/PRESET_ACCURACY.md)** is the full
+experiment: how the presets split on checker play versus the cube, why rolling
+out *costs* agreement with XG, and the evidence that the residual disagreement
+is systematic rather than noise.
+
+Presets live in `gvanalysis/presets.py` and are overridable via `presets.yaml`.
+See **[`docs/CLI.md`](docs/CLI.md)** for the full reference — every flag, how the
+tiers fire, parallelism, and preset overrides.
+
+## Documentation
+
+| Doc | What it covers |
+|---|---|
+| [`docs/CLI.md`](docs/CLI.md) | **Full command-line reference** — every flag, presets, parallelism |
+| [`gvformat-js/README.md`](gvformat-js/README.md) | The JavaScript package — API, layout, parity rules |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to run the tests, the conventions, what a good change looks like |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history, including the measurements behind several design decisions |
+| [`CLAUDE.md`](CLAUDE.md) | Maintainer and coding-agent notes: design rationale, measurements, and the rituals around an engine upgrade |
+| [`docs/OGXM_JSON_SPEC_GAMMONVIEW.md`](docs/OGXM_JSON_SPEC_GAMMONVIEW.md) | The JSON shape this repo writes (match → game → ply → analysis) — base spec plus every GammonView addition, marked |
+| [`docs/OGXM_FORMAT_SPEC_GAMMONVIEW.md`](docs/OGXM_FORMAT_SPEC_GAMMONVIEW.md) | The binary `.gvab` chunk layout, including the `GVAN` extension chunk |
+| [`docs/OGXM_COMPUTED_FIELDS.md`](docs/OGXM_COMPUTED_FIELDS.md) | Fields the reader computes rather than stores (PR, luck-MWC, MWC, classification) |
+| [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) | PR / luck / cube-decision methodology and filters |
+| [`docs/PRESET_ACCURACY.md`](docs/PRESET_ACCURACY.md) | What each preset costs in accuracy, measured against XG over 493 matches |
+
+## Licence
+
+[MIT](LICENSE). Every source file carries an SPDX header; `LICENSE` holds the
+full text.
+
+MIT because what this repo mainly offers is a **format**, and a format wants to
+be copied in pieces — one routine lifted into another project, or the codec
+ported to another language. It also stays compatible in both directions at once,
+which matters in this ecosystem: GNU Backgammon is GPL, eXtreme Gammon and
+BGBlitz are proprietary, and all of them are welcome to interoperate.
+[HedgeHog](https://gitlab.com/eranlambooij/hedgehog-public), whose format this
+implements, is MIT too.
+
+[bgsage](https://pypi.org/project/bgsage/), the engine behind the optional
+`[engine]` extra, is MPL-2.0, which constrains nothing here. MPL is *file-level*
+copyleft with no linking trigger: it attaches to its own files, and §3.3
+expressly permits distributing a larger work under other terms. bgsage resolves
+from PyPI at install time and is never modified or redistributed here, and
+`gvformat` does not touch the engine at all.
+
+The JavaScript mirror ([`gvformat-js/`](gvformat-js/), published as
+`@gammonview/gvformat`) is under the same licence and ships its own copy.
+
+The **GammonView logo** (`assets/logo.png`) is excluded: it identifies the site,
+so it is not part of the MIT grant. Fork the code freely; use your own mark.
+
+### Third-party material
+
+Two pieces of third-party material are incorporated, both permissively licensed.
+Their notices must be preserved — see **[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)**,
+which reproduces them in full:
+
+- **HedgeHog** (MIT, © 2026 Eran Lambooij) — OGXM is HedgeHog's format. Most of
+  `gvformat` is an independent implementation, but `binary.py` and `export.py`
+  (and their JS mirrors) are genuine ports of its C++ sources: the chunk struct
+  layouts and `parse_ply_analysis_json` from `ogxm_io.cpp`/`ogxm_json.cpp`, and
+  `_TurnState` from `ogxm_replay.cpp`'s `replay_game()`. Those four files say so
+  in their headers.
+- **Kazaross-XG2 MET** (© 2011 Neil Kazaross; transcribed for GNUbg by Michael
+  Petch) — the match-equity table embedded in `gvformat/met.py` and
+  `gvformat-js/src/met.js`. It ships with GNU Backgammon but is *not* under its
+  GPL; its own terms require only that the notice be preserved, and it is
+  reproduced at the top of both files.

gammonview-1.0.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+gvanalysis/__init__.py,sha256=S9O17fPn54wZrTT2qA_JLFUPzAywkDVNFwRNqJ8EAkU,5185
+gvanalysis/batch.py,sha256=ZqFGyimIL2Vf8lvkLnzbwHkomgqj51pTmWl_ZIaJoBg,8205
+gvanalysis/checker_eval.py,sha256=y38kmFk8MqDZj6h1Rn-m4GLhYPdQVvoY3mobldg3TSQ,17138
+gvanalysis/compare_gva.py,sha256=Os-NA_Jjy-dBU61Bl7EXVprurO2y1sw8iSyMw1nhFqo,12358
+gvanalysis/game_eval.py,sha256=AMhctfXq0gxnddSxxYUpl4K2pqqPJxUbBLyzMBf_Bcw,46745
+gvanalysis/loader.py,sha256=Uh7wklmW9hYSIFFUv98Z5zRsblaoPP566ispILB0PDE,2448
+gvanalysis/luck.py,sha256=CCafBrb58jYTap8wx2rCck47p8sCe4tOV_5A8TMQ_QQ,6260
+gvanalysis/match.py,sha256=EoC0jhCAf_hkdl8qctllJD48FKAy86JcOQhJan3OEnU,36579
+gvanalysis/ogxm_reconstructor.py,sha256=IWuP6BmwJ3gVh_5AGu5KIagg7TX1Eh5I-COFg_tMxIk,9717
+gvanalysis/position.py,sha256=_Rzrq8Hjh1hYSD6IP-msnA4oOEdmBhjHVdIb0trjQ-4,19103
+gvanalysis/presets.py,sha256=-y0DwAfdCt0z9eNwrPlXn4iIeyQtDC7inni6zBccLCA,17124
+gvanalysis/progress.py,sha256=SlNBJwFI3EyAvo1_CcwiOfpuxtA2pu7WyvTxhDL1jvk,3341
+gvanalysis/reconstruct_mat.py,sha256=IA3IaZ4EfTf0vbSksXZcx3EntIlbkvjckixQrhPrpTo,10358
+gvanalysis/share.py,sha256=60hjWWSBZWx1lduBgyx2T3_--zKTiAGXL3GdQoG55J4,1312
+gvformat/__init__.py,sha256=0b1FwWAAfzv-_Ja8iCVB88nwqx5PW6ZrqwDKj7KggEo,2186
+gvformat/basefill.py,sha256=nQp7xYC_co0iO1uPZ32lHYAmk_v9PdO-VuJvJk5YNwM,12477
+gvformat/bgf.py,sha256=TDy97AD5zzcQvTB0afVDj44MDxsl41DG5eY_M6wdocM,61346
+gvformat/binary.py,sha256=OoVVJEwTxf_JVOLv0IeHsjJUtTRhRYP2B3PKDpbgejM,40839
+gvformat/export.py,sha256=kGwi6h23lb9KQ5X3QQlnZHA8gM_sgo7Mtn6mRnP-6RI,59291
+gvformat/game_reconstructor.py,sha256=rs6qD8pJjFKVC2w3Kl14guXOcYYGn1Gp-y8pIY6ydbw,12133
+gvformat/legality.py,sha256=eRU3MyNx_J2U_seS6KB7aILebaoK_yJW35XympnscyI,9198
+gvformat/mat.py,sha256=JRtJFWsTnV3eNG6LGUWIFqTRn5cOE7pSXSaic8G-J2I,6140
+gvformat/mat_parser.py,sha256=v1QgSnBqdwWXcmWhwHrAe0xWdzGwVGMCZbWK3hC8fjM,11794
+gvformat/merge.py,sha256=B-M-MIyzsPFQyJSh56Nb3YMsbVJjnue8WLpoLtzUEoU,5800
+gvformat/met.py,sha256=QYjycKZatVWo1F3M8IxQngE8qCbcmhXy-qrrFkXn9T4,13769
+gvformat/notation.py,sha256=s69yhh-5IlXVAXK1OKMNiZDrrABPoElzAdFK_skIHGI,8294
+gvformat/ogid.py,sha256=rn5rOPxXjqa9wLu9sRcE3k7aZhkczmd9S0Niy0Vq67g,35673
+gvformat/place.py,sha256=CfoiYndZg08NGqVK2r1HuYbgBYIT2gKVSpzSFDVXasE,2185
+gvformat/reader.py,sha256=jkQolPbQp4bcltrdl0EZ7D8777kn7ygRoN6FVHgFUKQ,46464
+gvformat/share.py,sha256=ZjHmbhWRbnZhH-MDqbC8zPWXuktzmMFwhjhLbOdghn0,1944
+gvformat/stats.py,sha256=5qLR2okawClhcMZ96b06sOq8jO36YfWUTgU8iS0K9TM,19811
+gvformat/xg.py,sha256=QV2qUNWQ5PXUKo7akS40bf2nINDuywaz0S_RjmRXkms,62957
+gammonview-1.0.0.dist-info/METADATA,sha256=5zX8d1dABVXNwZB_nN44fhlpukmCIPweHSRiwVCRUoA,16692
+gammonview-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+gammonview-1.0.0.dist-info/entry_points.txt,sha256=6jzfIHRiRLHQOe6tryjxj_JOkBrlkVW7kXJnLxfxfOw,275
+gammonview-1.0.0.dist-info/licenses/LICENSE,sha256=alJKWw6YN2SqgNVH3WHiBoE610YzS716wiR8qQSIcBc,1072
+gammonview-1.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md,sha256=79PZed48nGcRAWkYUWQ2IVDgKmXCIz0eFmR-5Nya6uw,3472
+gammonview-1.0.0.dist-info/RECORD,,

gammonview-1.0.0.dist-info/WHEEL

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

gammonview-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+bgf2gva = gvformat.bgf:main
+compare-gva = gvanalysis.compare_gva:main
+gvan-batch = gvanalysis.batch:main
+gvan-match = gvanalysis.match:main
+gvan-position = gvanalysis.position:main
+reconstruct-mat = gvanalysis.reconstruct_mat:main
+xg2gva = gvformat.xg:main

gammonview-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Vlamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gammonview-1.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,80 @@
+# Third-party notices
+
+This project is MIT-licensed (see `LICENSE`). It incorporates the third-party
+material below, each under its own terms. **These notices must be preserved in
+any copy or substantial portion of this software.**
+
+---
+
+## HedgeHog — the OGXM format and reference codec
+
+OGXM is HedgeHog's format. `gvformat` is an independent implementation of it,
+but several modules are direct ports of HedgeHog's C++ sources rather than
+clean-room implementations of the published spec:
+
+| This repo | Ported from |
+|---|---|
+| `gvformat/binary.py`, `gvformat-js/src/binary.js` | `src/match/ogxm_io.cpp`, `ogxm_format.hpp`, `ogxm_json.cpp` — chunk struct layouts, `encode_ply`, fixed-point probability encoding, and `parse_ply_analysis_json` field-for-field |
+| `gvformat/export.py`, `gvformat-js/src/export.js` | `src/match/ogxm_replay.cpp` — `_TurnState` is a port of `replay_game()`; the OGID state/action string constants are taken byte-for-byte from `src/ogid.h` |
+
+Source: <https://gitlab.com/eranlambooij/hedgehog-public>
+
+```
+MIT License
+
+Copyright (c) 2026 Eran Lambooij
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## Kazaross-XG2 match-equity table
+
+The MET data shipped in `gvformat/met.py` and `gvformat-js/src/met.js` (the
+25x25 pre-Crawford table and the post-Crawford vector) is transcribed from GNU
+Backgammon's `met/Kazaross-XG2.xml`. The table is separately licensed under the
+permissive notice below — it is **not** covered by GNU Backgammon's GPL.
+
+```
+Copyright (C) 2011 Neil Kazaross
+
+Table rolled up to 9 point match by eXtreme Gammon. Then uses R/K MET
+which was rolled up to 15 and extrapolated to 25 points.
+
+Transcribed for use by GNUbg by Michael Petch <mpetch@capp-sysware.com>.
+
+This file is distributed as a part of the GNU Backgammon program.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved. This file is offered as-is, without any warranty.
+```
+
+---
+
+## Not bundled
+
+For completeness, since both are commonly assumed to be vendored here:
+
+- **bgsage** (MPL-2.0) — the analysis engine. An optional `[engine]` extra
+  resolved from PyPI at install time; no bgsage source is included in this
+  repository, and none of its files are modified.
+- **pako** (MIT) — used by the JS mirror for zlib deflate. A declared npm
+  dependency, installed by `npm install`; not vendored, and excluded from the
+  Python sdist.

gvanalysis/__init__.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2026 Nicholas Vlamis
+
+"""GammonView Analysis — bgsage-powered backgammon analysis.
+
+This is the *analysis* layer: it drives the bgsage engine to evaluate a match
+or position, and hands the result to the pure-stdlib ``gvformat`` codec for
+serialization. It depends on ``gvformat`` + ``bgsage`` (the ``[engine]`` extra);
+``gvformat`` on its own has no such dependency.
+
+Typical server use — analyze a dropped match file and get the analyzed
+``.gvab`` bytes back, in one call::
+
+    from gvanalysis import analyze_match
+    data = analyze_match("match.mat", preset="world_class")   # bytes to send to the client
+
+Or the pieces:
+
+    from gvanalysis import analyze_mat
+    from gvformat import to_ogxm_json, write_gvab, read_gvab
+    result = analyze_mat("match.mat", preset="fast")
+    data = write_gvab(to_ogxm_json(result))
+
+A single position is a different scale of problem -- fast enough to answer in
+a request, so it returns a plain OGXM-shaped dict rather than a file::
+
+    from gvanalysis import analyze_position
+    result = analyze_position("XGID=...", level="3ply")   # ~0.07s at 3ply
+
+CLIs: ``gvan-match`` / ``gvan-position`` (or ``python -m gvanalysis.match``).
+
+Note: ``analyze_mat`` / ``analyze_match`` (and the ``match`` / ``position`` /
+``game_eval`` submodules) require the bgsage engine — the ``[engine]`` extra.
+Importing ``gvanalysis`` itself, and the engine-free tool submodules
+(``reconstruct_mat``, ``compare_gva``), works without it; the engine
+requirement only surfaces — with a clear message — when you actually reach for
+the analyzer.
+
+The ``.mat`` parser/converter is *not* here: it needs no engine, so it lives in
+the codec layer beside the other source-format converters — ``gvformat``'s
+``convert_mat``/``mat_to_ogxm`` (and ``mat_parser`` / ``game_reconstructor``),
+mirroring ``convert_xg`` and ``convert_bgf``.
+"""
+
+_ENGINE_HINT = (
+    "the bgsage engine is required for this, but isn't installed. Add the "
+    "analysis extra:\n"
+    "    pip install 'gammonview[engine]'      (or, in this repo: uv sync)\n"
+    "The pure-codec layer `gvformat` needs no engine."
+)
+
+
+def _load_match():
+    """Import the engine-backed ``match`` module, or raise a clear, actionable
+    error when the bgsage engine (the ``[engine]`` extra) isn't installed."""
+    try:
+        from . import match
+    except ModuleNotFoundError as e:
+        if (e.name or "") in ("bgsage", "bgbot_cpp") or (e.name or "").startswith("bgsage."):
+            raise ModuleNotFoundError(f"gvanalysis: {_ENGINE_HINT}") from e
+        raise
+    return match
+
+
+def analyze_match(input_path, *, preset: str | None = None, quiet: bool = True, **kwargs) -> bytes:
+    """Analyze a match file and return the analyzed ``.gvab`` bytes.
+
+    Returns **bytes**, not a dict: this is the one call that hands back the
+    storable artifact. ``analyze_file`` is the same work stopping one step
+    earlier, at the OGXM document -- ``analyze_match(p)`` is exactly
+    ``write_gvab(analyze_file(p))``, and ``read_gvab`` of these bytes is that
+    document back.
+
+    One call for the common server path: a match in (``.mat``, ``.gva``/
+    ``.ogxm``, or ``.gvab`` — OGXM is the internal representation, so ``.mat``
+    is converted first), canonical ``.gvab`` bytes out, carrying the match
+    *and* the analysis this call just ran (ready to store and ship to the
+    client). An OGXM input's existing analysis blocks are preserved and ours is
+    appended. Equivalent to ``write_gvab(analyze_file(...))``. Requires the
+    ``[engine]`` extra; without it, raises a ``ModuleNotFoundError`` explaining
+    how to install.
+
+    Extra keyword arguments go to ``analyze_ogxm``; notably
+    ``on_progress=lambda done, total: ...`` reports decision-level progress, for
+    a server driving a progress bar in a client.
+    """
+    analyze_file = _load_match().analyze_file
+    from gvformat import write_gvab
+    return write_gvab(analyze_file(input_path, preset=preset, quiet=quiet, **kwargs))
+
+
+#: The former name. It read as a format conversion and named an input format
+#: this call never required, so the analysis it runs was invisible in it; kept
+#: working because callers exist.
+mat_to_gvab = analyze_match
+
+
+def __getattr__(name):
+    # PEP 562: expose the engine-backed entry points lazily so `import
+    # gvanalysis` (and the engine-free tool submodules) load without bgsage; the
+    # engine requirement only bites — with a clear message — when the analyzer
+    # is actually used.
+    if name in ("analyze_mat", "analyze_ogxm", "analyze_file"):
+        return getattr(_load_match(), name)
+    # `position` imports no engine at module scope (it reaches for bgsage only
+    # inside the call), so it needs none of _load_match's guarding — but it is
+    # still lazy, to keep `import gvanalysis` as cheap as it has always been.
+    if name == "analyze_position":
+        from . import position
+        return position.analyze_position
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "analyze_mat", "analyze_ogxm", "analyze_file",
+    "analyze_match", "mat_to_gvab",
+    "analyze_position",
+]