gammonview-helper 0.1.1__tar.gz

gammonview_helper-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+# The helper's suite, on every push and pull request.
+#
+# This package runs on other people's computers, which is what the matrix is
+# shaped around: the platforms, not the Python versions. What breaks here is a
+# credential store that is not a Keychain and an `os.nice` that does not exist
+# on Windows -- neither of which a second interpreter on Linux would ever find.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A newer push to the same ref makes the older run's verdict worthless.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One red row must not hide the others: the usual reason to read this
+      # matrix is to find out *which* platform broke.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.13"]
+        include:
+          # The floor and the ceiling of the supported range, on the cheap
+          # runner. `keyring` and `httpx` are where a version difference would
+          # actually show up; the middle versions are not worth three minutes.
+          - os: ubuntu-latest
+            python: "3.10"
+          - os: ubuntu-latest
+            python: "3.14"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      # Two markers deselected, for different reasons.
+      #
+      # `slow` runs a real analysis: it needs a minute of CPU and proves the
+      # engine works, which is bgsage's suite's job rather than this one's.
+      #
+      # `contract` talks to a live relay. The server half of that protocol is
+      # in a private repository, so there is nothing a public workflow could
+      # stand up, and pointing this at beta would make every push a request to
+      # a running service. `docs/Relay.md` says when to run it by hand.
+      - name: helper suite
+        run: uv run --python ${{ matrix.python }} pytest -q -m "not slow and not contract"
+
+  build:
+    name: build (sdist + wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, and a shallow clone has
+          # none. It does not fail -- it quietly stamps 0.1.dev1+g<sha> on the
+          # artifacts, which is the kind of thing you discover on PyPI.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      - name: report the derived version
+        run: ls -l dist/
+
+      # The wheel's real test is that the console script it installs actually
+      # runs. It is the first thing a user types after `uv tool install`, and an
+      # entry point naming a module that moved fails right there -- with a
+      # traceback, on their machine, before they have any reason to trust this.
+      #
+      # `--version` rather than `status`: it exits 0 with no credentials (status
+      # exits 1, correctly, because an unlinked helper is not a working one) and
+      # it reads the version back out of the *installed metadata*, so it fails
+      # if hatch-vcs stamped nothing. Resolving the dependencies at all is the
+      # other half of the check -- this is the only place `gammonview[engine]`
+      # is installed from PyPI the way a user gets it.
+      #
+      # From outside the checkout on purpose: with the repo as cwd, `gvhelper`
+      # is importable from the source tree and the wheel is never involved.
+      - name: the wheel's entry point runs
+        working-directory: ${{ runner.temp }}
+        run: |
+          uv run --isolated --no-project --with "$GITHUB_WORKSPACE"/dist/*.whl \
+            gammonview-helper --version

gammonview_helper-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,182 @@
+# Publish to PyPI via trusted publishing (OIDC). No API token exists anywhere:
+# PyPI is configured to trust *this workflow in this repository*, and mints a
+# short-lived credential for the job at run time. Nothing to store, leak, or
+# rotate, and a stolen repo secret cannot publish because there is no secret.
+#
+# This is the reason the helper is a public repository on GitHub at all. It is
+# installed by strangers with `uv tool install gammonview-helper`, so PyPI is
+# not optional -- and the alternative to OIDC is a long-lived upload token with
+# write access to the namespace, sitting on a laptop.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/), which
+# must be done before the first run, because the project does not exist yet:
+#
+#     PyPI project name : gammonview-helper
+#     Owner             : ngvlamis
+#     Repository name   : gammonview-helper
+#     Workflow name     : publish.yml
+#     Environment name  : pypi
+#
+# That registers a "pending publisher"; the project is created by the first
+# successful upload.
+name: publish
+
+on:
+  # A tag is the release signal, matching how the version is derived: hatch-vcs
+  # reads it from git, so the tag *is* the version. Pushing v0.2.0 publishes
+  # 0.2.0 -- there is no number to bump anywhere else, and no way for the tag
+  # and the artifact to disagree.
+  #
+  # These tags are this repository's own. The helper used to share the analysis
+  # monorepo's tags, which meant a codec release renumbered a helper nobody had
+  # touched; `pyproject.toml` records why that was the wrong coupling.
+  push:
+    tags: ["v*"]
+  # Manual trigger, to retry a failed upload against a tag that already exists.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # The suite is a gate on the release, not merely a thing that also runs.
+  # Publishing is irreversible -- a version number on PyPI cannot be reused
+  # even after a yank -- and this package's failures land on other people's
+  # computers, where nobody can roll them back for them.
+  test:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv run pytest -q -m "not slow and not contract"
+
+  build:
+    name: build sdist + wheel
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, and a shallow clone has
+          # none. It does not fail -- it quietly stamps 0.1.dev1+g<sha> on the
+          # artifacts, which is the sort of thing you discover on PyPI.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      # Refuse to publish a version that git did not name. Without this, a run
+      # from an untagged commit uploads a dev version to PyPI, where it cannot
+      # be taken back.
+      - name: the artifacts carry a real release version
+        run: |
+          ls -l dist/
+          version=$(ls dist/*.whl | sed -E 's|.*/gammonview_helper-([^-]+)-py3.*|\1|')
+          echo "derived version: $version"
+          case "$version" in
+            *dev*|*+*)
+              echo "::error::refusing to publish $version -- hatch-vcs found no tag on this commit"
+              exit 1 ;;
+          esac
+
+      - name: metadata renders on PyPI
+        run: uv run --isolated --no-project --with twine python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment is the approval gate: GitHub can require a manual review
+    # before the job runs, and PyPI's trusted publisher is bound to this name,
+    # so a workflow that does not declare it cannot publish.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gammonview-helper
+    permissions:
+      # The OIDC token this mints is what PyPI trades for an upload credential.
+      # Without it the action fails with a confusing 403.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ---------------------------------------------------------------------------
+  # The same wheel, attached to the GitHub Release.
+  # ---------------------------------------------------------------------------
+  # `uv tool install <url-to-wheel>` is a complete install path that needs no
+  # index at all, which is what makes shipping ahead of PyPI possible. It is
+  # deliberately the *wheel* and not `git+https://…`: a git install makes every
+  # user's machine clone the repo and run the build backend, so it needs `git`
+  # present (a fresh Mac prompts for the Xcode tools) and it needs hatch-vcs to
+  # find a tag in whatever clone uv made -- the exact failure `fetch-depth: 0`
+  # above exists to prevent, reproduced on a stranger's laptop where nothing
+  # checks it. The artifact is pure Python, so one file covers every platform;
+  # `bgsage`'s per-platform wheels still come from PyPI either way.
+  #
+  # It is also the artifact the launcher installs (docs/DesktopHelper.md, step
+  # 7), which "asks the server which version to install rather than taking
+  # whatever is newest" -- a version string and a predictable asset name is all
+  # that takes.
+  #
+  # `needs: build`, NOT `needs: pypi`, and that ordering is the point: a PyPI
+  # upload that fails for reasons of its own must not withhold an install path
+  # that does not depend on it, and deleting the `pypi` job later must leave
+  # this one working unchanged.
+  release:
+    name: attach to the GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    # A dispatch run has no tag to attach to. The tag is the release signal
+    # everywhere else in this file; here it is also the destination.
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      # Overrides the read-only default at the top of the file. Scoped to this
+      # job so the test and build jobs stay unable to write to the repository.
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # `gh` is preinstalled on the runner. Used in preference to a third-party
+      # release action because this is a supply-chain path: the fewer things
+      # that get to touch the artifact between `uv build` and the user, the
+      # better, and that argument is the same one that put trusted publishing
+      # above an upload token.
+      #
+      # Written to be re-runnable. `workflow_dispatch` exists to retry a tag
+      # that already exists, and by then the Release usually does too.
+      - name: upload
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" dist/* \
+              --title "$TAG" \
+              --generate-notes
+          fi

gammonview_helper-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.pytest_cache/
+
+# Virtual environments
+.venv
+
+# Agent instruction data -- covered by a global gitignore on the author's
+# machine, which a public clone obviously cannot rely on.
+.claude/
+
+# The helper's own state, if anyone points GAMMONVIEW_CONFIG_DIR in here while
+# poking at it. It holds a worker token.
+config.json
+token

gammonview_helper-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

gammonview_helper-0.1.1/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_helper-0.1.1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: gammonview-helper
+Version: 0.1.1
+Summary: Analyze GammonView matches on your own computer.
+Project-URL: Homepage, https://gammonview.com
+Project-URL: Repository, https://github.com/ngvlamis/gammonview-helper
+Project-URL: Issues, https://github.com/ngvlamis/gammonview-helper/issues
+Author: Nicholas Vlamis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analysis,backgammon,bgsage,gammonview
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+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
+Requires-Python: >=3.10
+Requires-Dist: gammonview[engine]>=1.0.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Description-Content-Type: text/markdown
+
+# gammonview-helper
+
+Analyze your backgammon matches on your own computer, and see the results on
+[gammonview.com](https://gammonview.com).
+
+GammonView analyses matches on a shared server. That server is shared, so the
+deepest settings are not on its menu — a *World Class* run that takes a minute
+on your laptop would take an hour of a queue everybody else is waiting in. The
+helper moves that work to your machine: you keep using the website exactly as
+before, and the analysis happens at home.
+
+Nothing listens on a port. The helper dials out to gammonview.com, waits for
+work **you** queued from your own browser, runs it, and sends the result back.
+There is no inbound connection, no router setting, no firewall rule.
+
+## Install
+
+Needs [uv](https://docs.astral.sh/uv/) (or pipx, or a plain `pip install` into
+a virtualenv).
+
+```bash
+uv tool install https://github.com/ngvlamis/gammonview-helper/releases/download/v0.1.1/gammonview_helper-0.1.1-py3-none-any.whl
+```
+
+That pulls in the analysis engine and its neural networks — about 80 MB, and it
+takes a minute or two the first time.
+
+The URL names a version on purpose. Point it at a different release to install
+that one, and re-run the same line with a newer version to upgrade — there is
+no `uv tool upgrade` for a package installed from a URL, because there is no
+index for it to ask.
+
+Two other forms, for whoever prefers them:
+
+```bash
+# once this is on PyPI, the short name and `uv tool upgrade` both work
+uv tool install gammonview-helper
+
+# straight from a tag — needs `git`, and builds from source rather than
+# installing the wheel that was tested
+uv tool install git+https://github.com/ngvlamis/gammonview-helper@v0.1.1
+```
+
+## Link this computer
+
+```bash
+gammonview-helper link
+```
+
+It prints a word and opens your browser. Sign in if you are asked, and pick the
+word it printed out of the three you are shown. You will get an email saying
+the computer was linked.
+
+If the three words do not include the one on your screen, **something is
+wrong** — close the page and start again. That is the check working.
+
+## Run it
+
+```bash
+gammonview-helper run
+```
+
+Leave it running. Analyses you start on gammonview.com will now go to this
+computer, and the deeper presets appear in the menu. If the helper is not
+running, the website falls back to the shared server on its own — you never get
+an error for having closed it.
+
+You can start it before linking. An unlinked helper waits for a credential
+rather than giving up, so the usual order — install, let it start, then link in
+the browser — needs no third step telling it to look again; it picks the link
+up within a few seconds. The same is true if you unlink and re-link later.
+
+### Keeping it running (macOS)
+
+`run` stops when you close the terminal. To have it start at login and stay up:
+
+```bash
+deploy/install-login-item.sh
+```
+
+That registers a launchd agent pointing at the installed `gammonview-helper`,
+logging to `~/Library/Logs/GammonView/helper.log`. Re-run it after an upgrade —
+it boots the old job out first, so you never end up with two pollers sharing one
+worker id, and it keeps whatever site the installed agent already pointed at.
+To move a machine between sites, say so explicitly:
+
+```bash
+GAMMONVIEW_SITE=https://gammonview.com deploy/install-login-item.sh
+```
+
+It says when it moves one, because a credential is per site: the machine has to
+be linked to the new one separately.
+
+```bash
+deploy/install-login-item.sh stop     # stop it, and leave it stopped
+tail -f ~/Library/Logs/GammonView/helper.log
+```
+
+Installing always leaves the helper running, so a `stop` does not survive the
+next install. After stopping, the website keeps saying **Connected** for up to
+two minutes — a helper stops by going quiet, and the relay waits that long
+before believing a silence.
+
+The eventual installer does this for you; the script exists because the machine
+this is developed on needed it first, and `deploy/com.gammonview.helper.plist`
+records the four choices in it that are not boilerplate.
+
+## The other two commands
+
+```bash
+gammonview-helper status     # what is configured, and is the link still alive
+gammonview-helper unlink     # forget this computer's credentials
+```
+
+`unlink` is local. To remove the computer from your account, use **Unlink** in
+your account settings on the website — the helper's credentials deliberately
+cannot reach your account, so they cannot revoke themselves.
+
+## Settings
+
+Everything lives in one directory, which is the whole of the uninstall:
+
+| | |
+|---|---|
+| macOS | `~/Library/Application Support/GammonView/` |
+| Windows | `%LOCALAPPDATA%\GammonView\` |
+| Linux | `~/.config/gammonview/` |
+
+The credential is kept in your platform's credential store (Keychain, Credential
+Manager, Secret Service), not in that directory. `status` says which store it
+actually got — on a machine with no credential store it falls back to a
+`0600` file, and tells you so.
+
+`config.json` takes a few optional keys:
+
+| key | default | what it does |
+|---|---|---|
+| `jobs` | `0` — the engine decides | how many of a match's decisions run in parallel |
+| `threads` | `0` — the engine decides | engine threads inside each of those |
+| `nice` | 10 | how hard the helper tries to stay out of your way |
+
+The parallelism is sized by the engine, from measurements it keeps for the
+purpose; set either to a number if you want a hard cap, and it will be kept.
+`nice` is what makes the helper something you forget is running — it yields to
+whatever you are actually doing, and every engine worker inherits it.
+
+## Licence
+
+MIT. The engine ([bgsage](https://pypi.org/project/bgsage/)) is MPL-2.0 and is
+installed as an ordinary dependency.
+
+## Development
+
+```bash
+uv run pytest -q -m "not slow and not contract"
+```
+
+Two markers are deselected there. `slow` runs a real analysis and needs a
+minute of CPU. `contract` talks to a **live** relay and is opt-in:
+
+```bash
+GAMMONVIEW_CONTRACT_BASE=https://beta.gammonview.com uv run pytest -m contract
+```
+
+The other end of that protocol — the relay itself — is part of the
+gammonview.com service and is not open source. `docs/Relay.md` documents the
+seam from this side, says which revision this client implements, and explains
+why the contract carries a number of its own.

gammonview_helper-0.1.1/README.md

@@ -0,0 +1,168 @@
+# gammonview-helper
+
+Analyze your backgammon matches on your own computer, and see the results on
+[gammonview.com](https://gammonview.com).
+
+GammonView analyses matches on a shared server. That server is shared, so the
+deepest settings are not on its menu — a *World Class* run that takes a minute
+on your laptop would take an hour of a queue everybody else is waiting in. The
+helper moves that work to your machine: you keep using the website exactly as
+before, and the analysis happens at home.
+
+Nothing listens on a port. The helper dials out to gammonview.com, waits for
+work **you** queued from your own browser, runs it, and sends the result back.
+There is no inbound connection, no router setting, no firewall rule.
+
+## Install
+
+Needs [uv](https://docs.astral.sh/uv/) (or pipx, or a plain `pip install` into
+a virtualenv).
+
+```bash
+uv tool install https://github.com/ngvlamis/gammonview-helper/releases/download/v0.1.1/gammonview_helper-0.1.1-py3-none-any.whl
+```
+
+That pulls in the analysis engine and its neural networks — about 80 MB, and it
+takes a minute or two the first time.
+
+The URL names a version on purpose. Point it at a different release to install
+that one, and re-run the same line with a newer version to upgrade — there is
+no `uv tool upgrade` for a package installed from a URL, because there is no
+index for it to ask.
+
+Two other forms, for whoever prefers them:
+
+```bash
+# once this is on PyPI, the short name and `uv tool upgrade` both work
+uv tool install gammonview-helper
+
+# straight from a tag — needs `git`, and builds from source rather than
+# installing the wheel that was tested
+uv tool install git+https://github.com/ngvlamis/gammonview-helper@v0.1.1
+```
+
+## Link this computer
+
+```bash
+gammonview-helper link
+```
+
+It prints a word and opens your browser. Sign in if you are asked, and pick the
+word it printed out of the three you are shown. You will get an email saying
+the computer was linked.
+
+If the three words do not include the one on your screen, **something is
+wrong** — close the page and start again. That is the check working.
+
+## Run it
+
+```bash
+gammonview-helper run
+```
+
+Leave it running. Analyses you start on gammonview.com will now go to this
+computer, and the deeper presets appear in the menu. If the helper is not
+running, the website falls back to the shared server on its own — you never get
+an error for having closed it.
+
+You can start it before linking. An unlinked helper waits for a credential
+rather than giving up, so the usual order — install, let it start, then link in
+the browser — needs no third step telling it to look again; it picks the link
+up within a few seconds. The same is true if you unlink and re-link later.
+
+### Keeping it running (macOS)
+
+`run` stops when you close the terminal. To have it start at login and stay up:
+
+```bash
+deploy/install-login-item.sh
+```
+
+That registers a launchd agent pointing at the installed `gammonview-helper`,
+logging to `~/Library/Logs/GammonView/helper.log`. Re-run it after an upgrade —
+it boots the old job out first, so you never end up with two pollers sharing one
+worker id, and it keeps whatever site the installed agent already pointed at.
+To move a machine between sites, say so explicitly:
+
+```bash
+GAMMONVIEW_SITE=https://gammonview.com deploy/install-login-item.sh
+```
+
+It says when it moves one, because a credential is per site: the machine has to
+be linked to the new one separately.
+
+```bash
+deploy/install-login-item.sh stop     # stop it, and leave it stopped
+tail -f ~/Library/Logs/GammonView/helper.log
+```
+
+Installing always leaves the helper running, so a `stop` does not survive the
+next install. After stopping, the website keeps saying **Connected** for up to
+two minutes — a helper stops by going quiet, and the relay waits that long
+before believing a silence.
+
+The eventual installer does this for you; the script exists because the machine
+this is developed on needed it first, and `deploy/com.gammonview.helper.plist`
+records the four choices in it that are not boilerplate.
+
+## The other two commands
+
+```bash
+gammonview-helper status     # what is configured, and is the link still alive
+gammonview-helper unlink     # forget this computer's credentials
+```
+
+`unlink` is local. To remove the computer from your account, use **Unlink** in
+your account settings on the website — the helper's credentials deliberately
+cannot reach your account, so they cannot revoke themselves.
+
+## Settings
+
+Everything lives in one directory, which is the whole of the uninstall:
+
+| | |
+|---|---|
+| macOS | `~/Library/Application Support/GammonView/` |
+| Windows | `%LOCALAPPDATA%\GammonView\` |
+| Linux | `~/.config/gammonview/` |
+
+The credential is kept in your platform's credential store (Keychain, Credential
+Manager, Secret Service), not in that directory. `status` says which store it
+actually got — on a machine with no credential store it falls back to a
+`0600` file, and tells you so.
+
+`config.json` takes a few optional keys:
+
+| key | default | what it does |
+|---|---|---|
+| `jobs` | `0` — the engine decides | how many of a match's decisions run in parallel |
+| `threads` | `0` — the engine decides | engine threads inside each of those |
+| `nice` | 10 | how hard the helper tries to stay out of your way |
+
+The parallelism is sized by the engine, from measurements it keeps for the
+purpose; set either to a number if you want a hard cap, and it will be kept.
+`nice` is what makes the helper something you forget is running — it yields to
+whatever you are actually doing, and every engine worker inherits it.
+
+## Licence
+
+MIT. The engine ([bgsage](https://pypi.org/project/bgsage/)) is MPL-2.0 and is
+installed as an ordinary dependency.
+
+## Development
+
+```bash
+uv run pytest -q -m "not slow and not contract"
+```
+
+Two markers are deselected there. `slow` runs a real analysis and needs a
+minute of CPU. `contract` talks to a **live** relay and is opt-in:
+
+```bash
+GAMMONVIEW_CONTRACT_BASE=https://beta.gammonview.com uv run pytest -m contract
+```
+
+The other end of that protocol — the relay itself — is part of the
+gammonview.com service and is not open source. `docs/Relay.md` documents the
+seam from this side, says which revision this client implements, and explains
+why the contract carries a number of its own.