# Oklahoma Gin Rummy Pretrained Agent (`checkpoints/scale/gin_rummy/v1`)

Pretrained reinforcement learning checkpoint for Oklahoma Gin Rummy in
[OpenSpiel](https://github.com/google-deepmind/open_spiel), produced with
`open_spiel.python.scale` (`--config=gin_mmd_from_scratch`, step `30000`).

* **HTTPS URL:** `https://storage.googleapis.com/openspiel-data/checkpoints/scale/gin_rummy/v1`
* **GCS URI:** `gs://openspiel-data/checkpoints/scale/gin_rummy/v1`
* **Format:** `open_spiel.python.scale.ckpt.artifact` (`format="artifact"`, `schema_version=1`, step `30000`)
* **License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) ([`LICENSE`](./LICENSE))

---

## 1. Game and Rules Configuration

* **OpenSpiel game string:** `gin_rummy(oklahoma=true)`
* **Canonical `scale` `env_spec`:**
  ```json
  {
    "name": "gin_rummy",
    "kwargs": {
      "allow_upcard_throwback": true,
      "oklahoma_frac": 1.0,
      "spade_doubles": false,
      "wall_knock_pick": true
    }
  }
  ```
* **Oklahoma Gin rules:** Every deal uses Oklahoma knock thresholds (`oklahoma=true`):
  the maximum deadwood allowed to knock equals the pip value of the initial face-up
  card (an Ace upcard sets the threshold to `0`, requiring Gin). Spade-doubling is
  off (`spade_doubles=false`).
* **Equal deadwood after layoffs:** Equal deadwood after layoffs is scored as an
  **undercut** for the defender, matching current OpenSpiel `master` and the JAX
  training environment. (OpenSpiel releases up to `2.0.2` scored equal-deadwood
  hands `0-0`; `play_checkpoints` detects and reports those hands explicitly when
  replaying on older releases.)

---

## 2. Architecture and Parameters

* **Architecture:** `routed` (`gin_tfv2_d192l3` network + `gin_rummy.scripted_endgame`)
  * **Observation encoder:** `gin_card_tokens` (`799` floats structured as per-card
    and global game-state features; `241` discrete actions; **zero natural language**).
  * **Torso:** `card_tokens` transformer (`d_model=192`, `num_layers=3`,
    `num_heads=6`, `ffn_ratio=2`, row MLP enabled, `bfloat16` compute, `float32`
    parameters).
  * **Heads:** Pointer policy head (`float64` logits), 101-bin HL-Gauss categorical
    value head on `[-110.0, 110.0]`, and opponent-hand card prediction auxiliary head.
  * **Endgame routing:** The neural network plays `FIRST_UPCARD`, `DRAW`, and
    `DISCARD` decisions; `KNOCK`, `LAYOFF`, and `WALL` decisions are routed to the
    deterministic `gin_rummy.scripted_endgame` policy (`.envs.gin.endgame:in_domain`).
* **Parameter count:** **1,363,384** `float32` parameters across `67` array leaves
  (`~5.13 MB` total artifact size on disk).
* **Default decision rule:** `argmax` (`temperature=1.0`).

---

## 3. Training and Data Provenance

* **Algorithm:** Magnetic Mirror Descent (`pg.mmd`) self-play from random
  initialization (`--config=gin_mmd_from_scratch` in
  `open_spiel/python/scale/configs/gin_mmd_from_scratch.py`).
* **Schedule:** `30,000` learner updates of `1,024` parallel environments x `165`
  plies per update, playing against a scheduled snapshot pool of past learner
  checkpoints (`0.95` lagged learner snapshot refreshed every `1,000` updates,
  `0.05` uniform over the `40` newest `5,000`-step snapshots), with KL penalty
  `0.2` to a self-magnet refreshed every `500` updates, entropy bonus `0.05`,
  and linear learning-rate decay from `1e-4` to `0`.
* **Training data:** **100% synthetic self-play trajectories** generated in-memory
  by the OpenSpiel Gin Rummy environment. No human gameplay, personal data, web
  text, or third-party datasets were used.

---

## 4. Quickstart Usage

Public HTTPS URLs are fetched and cached automatically into `~/.cache` (override
with `OPEN_SPIEL_SCALE_ARTIFACT_CACHE`) using Python's standard library, with
`params_sha256` verified on load—no Google Cloud account, credentials, or `gcsfs`
needed. Both the bare folder URL (resolves to the latest step, `30000`) and the
explicit `@30000` suffix work.

### Play in the browser GUI (one command)

From an OpenSpiel checkout with `pyspiel`, `$OPEN_SPIEL_PYTHON_JAX_DEPS`, and the
built web client (`cd open_spiel/gui && npm ci && npm run build`):

```sh
CKPT=https://storage.googleapis.com/openspiel-data/checkpoints/scale/gin_rummy/v1
python3 -m open_spiel.python.gui.play --game 'gin_rummy(oklahoma=true)' \
  --bot open_spiel.python.scale.serve.remote_bot:make_bot \
  --checkpoint "$CKPT@30000"
```

### Evaluate against the scripted rule bot in the terminal

```sh
CKPT=https://storage.googleapis.com/openspiel-data/checkpoints/scale/gin_rummy/v1
python3 -m open_spiel.python.scale.examples.play_checkpoints \
  --a="$CKPT@30000" --b=arch:gin_rummy.rule_bot \
  --games=64 --out=/tmp/gin_vs_rule_bot
```

### Load directly in Python

```python
from open_spiel.python.scale.ckpt import artifact

url = "https://storage.googleapis.com/openspiel-data/checkpoints/scale/gin_rummy/v1"
art = artifact.load_artifact(url, 30000, verify=True)
```

To reproduce training from scratch:

```sh
python3 -m open_spiel.python.scale.train --config=gin_mmd_from_scratch \
  --checkpoint_dir=/tmp/gin_from_scratch
```

---

## 5. Intended Use and Limitations

* **Intended use:** Research baseline, evaluation opponent, and interactive human
  play in OpenSpiel.
* **Limitations:** Trained exclusively on Oklahoma Gin (`oklahoma=true`); standard
  10-point-knock Gin Rummy (`oklahoma=false`) is out of distribution and rejected
  by `checkpoint_bot`'s game-coverage check unless overridden. Knock, layoff, and
  wall-pick decisions are executed by `gin_rummy.scripted_endgame` code rather
  than neural weights.

---

## 6. Integrity Digests

* `30000/manifest.json` SHA-256:
  `795d901a1f770cd6cd1fc45cf84b897ffdb0183aa67d53b6d6beaafae35ac214`
* Restored parameter tree digest (`params_sha256`):
  `02714d548b571151e33b67b9e8c62812fc18a5cbaf9a47611944698970a42c07`
* Environment `rules_sha`:
  `fb4a85a33642e745a1f3b4ef741bf2a4ddf0f9dec99a99c0fc0a2a297d5d4cfd`
* Per-file SHA-256 checksums: see [`SHA256SUMS`](./SHA256SUMS).

---

## 7. License and Attribution

Copyright 2026 DeepMind Technologies Limited.

These checkpoint weights and metadata are licensed under the Creative Commons
Attribution 4.0 International Public License
([`LICENSE`](./LICENSE), <https://creativecommons.org/licenses/by/4.0/>).

Suggested attribution:

> OpenSpiel Oklahoma Gin Rummy Pretrained Agent (`checkpoints/scale/gin_rummy/v1`),
> Copyright 2026 DeepMind Technologies Limited, licensed under CC BY 4.0
> (`https://storage.googleapis.com/openspiel-data/checkpoints/scale/gin_rummy/v1`).