royaleimitate 0.2.6__tar.gz

royaleimitate-0.2.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoyaleGym contributors
+
+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.

royaleimitate-0.2.6/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: royaleimitate
+Version: 0.2.6
+Summary: RoyaleImitate: imitation learning for RoyaleLearn, as an optional add-on
+License: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: royalelearn>=0.5.4
+Requires-Dist: royalegym>=0.1.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: msgspec>=0.18
+Provides-Extra: torch
+Requires-Dist: torch>=2.4; extra == "torch"
+Requires-Dist: safetensors>=0.4; extra == "torch"
+Provides-Extra: replays
+Requires-Dist: huggingface_hub>=0.24; extra == "replays"
+Requires-Dist: pyarrow>=15; extra == "replays"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: pyarrow>=15; extra == "dev"
+Dynamic: license-file

royaleimitate-0.2.6/README.md

@@ -0,0 +1,41 @@
+<p align="center"><img src="docs/media/logo.png" width="128" alt="The RoyaleImitate logo: a purple crown shield with two white cards on it, outlined in gold"></p><h1 align="center">RoyaleImitate</h1>
+
+<p align="center"><a href="https://github.com/RoyaleGym/RoyaleImitate/actions/workflows/suite.yml"><img alt="CI" src="https://github.com/RoyaleGym/RoyaleImitate/actions/workflows/suite.yml/badge.svg"></a> <img alt="License" src="https://img.shields.io/github/license/RoyaleGym/RoyaleImitate?style=flat-square&color=555"> <img alt="Python" src="https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-3776AB?style=flat-square&logo=python&logoColor=white"> <a href="https://royalegym.github.io/RoyaleGym/"><img alt="Docs" src="https://img.shields.io/badge/docs-royalegym.github.io-8957e5?style=flat-square&logo=readthedocs&logoColor=white"></a> <a href="https://discord.gg/4D2BS5JBHP"><img alt="Discord" src="https://img.shields.io/discord/1551699576304705647?style=flat-square&logo=discord&logoColor=white&label=discord&color=5865F2"></a> <img alt="Last commit" src="https://img.shields.io/github/last-commit/RoyaleGym/RoyaleImitate?style=flat-square&color=555"></p>
+
+Start a Clash Royale bot from one you already have, and keep it close to that bot while it learns.
+It is an optional add-on to RoyaleLearn, the trainer: leave it out and nothing changes.
+
+## Install
+
+    pip install "royalegym[all]"
+
+This is the `[imitate]` part. Until it is on PyPI, see [Install](https://royalegym.github.io/RoyaleGym/install/) for the exact line.
+
+## Try it
+
+```python
+from royalegym import TowerHPReward, make_env
+from royalelearn import Learner
+from royaleimitate import save_actor
+
+def build_env():
+    return make_env(reward=TowerHPReward())
+
+teacher = Learner(build_env, save_dir="runs/teacher")
+teacher.learn(total_steps=20_000)
+digest = save_actor(teacher, "runs/teacher-actor")
+
+start = {"path": "runs/teacher-actor", "sha256": digest}
+student = Learner(build_env, save_dir="runs/student", extensions={"warm_start": {"init": start}})
+student.learn(total_steps=20_000)
+```
+
+The student starts from the teacher's weights; [examples/minimal.py](examples/minimal.py) also keeps it close.
+
+## Next
+
+- The docs: [royalegym.github.io/RoyaleGym](https://royalegym.github.io/RoyaleGym/), and the [RoyaleImitate page](https://royalegym.github.io/RoyaleGym/resources/royaleimitate/)
+- The guide: [guide](https://royalegym.github.io/RoyaleGym/repos/royaleimitate/guide/). The full contract (Advanced): [spec](https://royalegym.github.io/RoyaleGym/repos/royaleimitate/spec/)
+- Questions: [Discord](https://discord.gg/4D2BS5JBHP)
+
+MIT licensed. See [LICENSE](LICENSE).

royaleimitate-0.2.6/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "royaleimitate"
+version = "0.2.6"
+description = "RoyaleImitate: imitation learning for RoyaleLearn, as an optional add-on"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+# Neither is on PyPI: both are sibling checkouts, installed editable before this package
+# (RoyaleSim -> RoyaleGym -> RoyaleViser -> RoyaleLearn -> RoyaleImitate). pip resolves them from
+# the venv; it never fetches them.
+dependencies = [
+    "royalelearn>=0.5.4",
+    "royalegym>=0.1.0",
+    "numpy>=2.0",
+    "msgspec>=0.18",
+]
+
+[project.optional-dependencies]
+torch = [
+    "torch>=2.4",
+    "safetensors>=0.4",
+]
+# Human games from the IL_Replay dataset (``royaleimitate.from_replays``).
+replays = [
+    "huggingface_hub>=0.24",
+    "pyarrow>=15",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.16",
+    "pyarrow>=15",
+]
+
+# How RoyaleLearn finds the two config sections this package provides. The entry point's name is
+# the section's key.
+[project.entry-points."royalelearn.extensions"]
+imitation = "royaleimitate.extension:EXTENSION"
+warm_start = "royaleimitate.warm_start:EXTENSION"
+
+[project.scripts]
+royaleimitate = "royaleimitate.cli:main"
+
+# Naming the package explicitly keeps anything else in this folder out of a wheel built here.
+[tool.setuptools.packages.find]
+include = ["royaleimitate", "royaleimitate.*"]
+
+[tool.setuptools.package-data]
+royaleimitate = ["replay_cards.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+pythonpath = ["."]
+addopts = "-ra --strict-markers -m \"not slow and not engine\""
+markers = [
+    "slow: takes more than about five seconds",
+    "engine: needs a royalesim build that matches the data on disk",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["royaleimitate", "tests"]
+extend-exclude = ["datasets"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003", "SIM108"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["royaleimitate", "royalelearn", "royalegym", "royalesim"]

royaleimitate-0.2.6/royaleimitate/__init__.py

@@ -0,0 +1,55 @@
+"""Imitation learning for RoyaleLearn, as an optional add-on.
+
+Two config sections, found by RoyaleLearn through this package's entry points:
+
+- ``warm_start``: start the actor from saved weights, check them against their own probe rows,
+  and hold the actor still at first while the critic catches up;
+- ``imitation``: anchor the policy to reference policies with the reference-KL regulariser and
+  its adaptive coefficient.
+
+And the tools that make what they read: saved-policy folders (``artifacts``), field models
+(``field_model``, ``fit``), and demonstration shards (``shards``, ``split``). And ``public_log``:
+the observation's fair fields from a timed log of card plays, with no engine running.
+And ``from_replays``: human games from the public IL_Replay dataset, as demonstration shards.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.6"
+
+__all__ = ["clone", "from_replays", "record", "save_actor"]
+
+
+def save_actor(learner: object, folder: object, *, seed: int = 0) -> str:
+    """Write a trained ``royalelearn.Learner``'s actor as an actor artifact; returns its digest.
+
+    See ``royaleimitate.artifacts.save_actor``. Imported on first use, so importing this package
+    does not import torch.
+    """
+    from .artifacts import save_actor as save
+
+    return save(learner, folder, seed=seed)  # type: ignore[arg-type]
+
+
+def record(learner: object, teacher: object, out: object, **kwargs: object) -> object:
+    """A teacher's battles in ``learner``'s environment, as shard rows; see
+    ``royaleimitate.cloning.record``."""
+    from .cloning import record as run
+
+    return run(learner, teacher, out, **kwargs)  # type: ignore[arg-type]
+
+
+def clone(learner: object, demonstrations: object, out: object, **kwargs: object) -> str:
+    """``learner``'s network trained to copy ``demonstrations``, written to ``out``; see
+    ``royaleimitate.cloning.clone``."""
+    from .cloning import clone as run
+
+    return run(learner, demonstrations, out, **kwargs)  # type: ignore[arg-type]
+
+
+def from_replays(learner: object, out: object, **kwargs: object) -> object:
+    """Human games from the IL_Replay dataset, replayed in ``learner``'s environment, as shard
+    rows; see ``royaleimitate.replays.from_replays``."""
+    from .replays import from_replays as run
+
+    return run(learner, out, **kwargs)  # type: ignore[arg-type]

royaleimitate-0.2.6/royaleimitate/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m royaleimitate``: the same command as the ``royaleimitate`` script, for a shell where
+the virtual environment's scripts folder is not on PATH."""
+
+from .cli import main
+
+raise SystemExit(main())

royaleimitate-0.2.6/royaleimitate/alarms.py

@@ -0,0 +1,36 @@
+"""The regularisers' alarms (section 19.9). Both warn: a halted treatment run is censored out of
+its comparison."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from royalelearn.extensions import FamilyAlarm
+
+from .schema import IMITATION_ALARM_METRICS
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from royalelearn.extensions import Alarm
+
+__all__ = ["imitation_alarms"]
+
+
+def imitation_alarms(*, ref_kl_warn: float, lambda_saturated_patience: int) -> list[Alarm]:
+    return [
+        FamilyAlarm(
+            "imitation_ref_kl_high",
+            lambda _member, kl: kl > ref_kl_warn,
+            keys=IMITATION_ALARM_METRICS["imitation_ref_kl_high"],
+            meaning="the policy has moved far from a reference it is anchored to",
+        ),
+        FamilyAlarm(
+            "imitation_lambda_saturated",
+            lambda _member, at_max: at_max >= 1.0,
+            keys=IMITATION_ALARM_METRICS["imitation_lambda_saturated"],
+            patience=lambda_saturated_patience,
+            meaning=(
+                "lambda has sat at coef.max: the reward is pulling harder than the anchor can "
+                "hold, which is a statement about the reward"
+            ),
+        ),
+    ]

royaleimitate-0.2.6/royaleimitate/artifacts.py

@@ -0,0 +1,310 @@
+"""Actor artifacts: the folder a saved actor lives in, and how a config names it.
+
+Section 19.2 of ``docs/harness-spec.md``. An artifact is a folder, and a config names it by a
+path and a digest. The digest is over every file in the folder, not over the weights alone,
+because the other files change numbers too: a model's normalisation can live in its
+``spec.json``, and an actor's self-test is in its probe rows.
+
+An **actor artifact** is the snapshot layout of section 11.6 -- ``actor.safetensors`` beside a
+``SnapshotSpec`` -- with the weights in float32 rather than half precision, and a probe set when
+it is meant to be loaded as an init. A pool snapshot is played against and never trained from;
+an init is trained from, and a file that rounded the seeded weights could not reproduce a run
+started from them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+import msgspec
+import numpy as np
+
+from royalelearn.extensions import SPEC_NAME, WEIGHTS_NAME, PreflightError, SnapshotSpec, digest_of
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from torch import Tensor
+
+    from royalelearn.extensions import ObsBatch, RowCodec
+
+__all__ = [
+    "PROBE_CHUNK",
+    "PROBE_NAME",
+    "ActorArtifact",
+    "ProbeSet",
+    "artifact_digest",
+    "check_actor_artifact",
+    "load_actor_state",
+    "probe_log_probs",
+    "read_actor_artifact",
+    "save_actor",
+    "self_test",
+    "verify_artifact",
+    "write_actor_artifact",
+]
+
+PROBE_NAME = "probe.safetensors"
+#: The forward the probe log-probabilities are taken in, on both sides. A batch's shape can
+#: choose the kernel a convolution runs with, and a self-test that compared a 1,024-row forward
+#: against a 256-row one would be measuring that choice.
+PROBE_CHUNK = 256
+
+
+def artifact_digest(folder: str | Path) -> str:
+    """sha256 of the canonical JSON of ``{relative path: sha256 of the file}`` over the folder.
+
+    Every file, at any depth, named by its path relative to the folder with forward slashes, so
+    the digest is the same on every platform and does not depend on where the folder sits.
+    """
+    root = Path(folder)
+    if not root.is_dir():
+        raise PreflightError(f"no artifact folder at {root}")
+    listing = {
+        path.relative_to(root).as_posix(): hashlib.sha256(path.read_bytes()).hexdigest()
+        for path in sorted(root.rglob("*"))
+        if path.is_file()
+    }
+    if not listing:
+        raise PreflightError(f"the artifact folder {root} is empty")
+    return digest_of(listing)
+
+
+def verify_artifact(path: str | Path, stated: str, *, what: str) -> Path:
+    """The folder, if its digest is the one the config states; a refusal naming both if not.
+
+    Checked at every start, fresh or resumed. The identity carries the stated digest, so without
+    this the identity is only as true as the config's claim about the file.
+    """
+    folder = Path(path)
+    found = artifact_digest(folder)
+    if found != stated:
+        raise PreflightError(
+            f"{what}: the artifact at {folder} has digest {found}, and the config states "
+            f"{stated}. Either the folder changed since the config was written or the config "
+            "names the wrong one; `royaleimitate artifact-digest <folder>` prints a folder's digest"
+        )
+    return folder
+
+
+# --------------------------------------------------------------------------
+# Actor artifacts
+# --------------------------------------------------------------------------
+
+
+class ProbeSet(NamedTuple):
+    """Rows packed by the run's codec, and the masked log-probabilities recorded on them."""
+
+    rows: np.ndarray
+    log_probs: np.ndarray
+
+
+class ActorArtifact(NamedTuple):
+    folder: Path
+    spec: SnapshotSpec
+    state: dict[str, Tensor]
+    probe: ProbeSet | None
+
+
+def probe_log_probs(
+    actor: Any, codec: RowCodec, rows: np.ndarray, *, chunk: int = PROBE_CHUNK
+) -> tuple[np.ndarray, np.ndarray]:
+    """``(N, n_actions)`` float32 masked log-probabilities and the ``(N, n_actions)`` mask.
+
+    The one function both sides call: the tool that writes an artifact records what it returns,
+    and the self-test compares against what it returns now. Two implementations of "the
+    log-probabilities on these rows" would be two answers.
+    """
+    import torch
+
+    out: list[np.ndarray] = []
+    masks: list[np.ndarray] = []
+    with torch.no_grad():
+        for start in range(0, int(rows.shape[0]), chunk):
+            obs: ObsBatch = codec.decode(rows[start : start + chunk])
+            distribution = actor.distribution(obs)
+            out.append(distribution.log_probs.float().cpu().numpy())
+            masks.append(obs.mask.cpu().numpy())
+    if not out:
+        width = codec.spec.n_actions
+        return np.zeros((0, width), np.float32), np.zeros((0, width), bool)
+    return np.concatenate(out), np.concatenate(masks)
+
+
+def self_test(actor: Any, codec: RowCodec, probe: ProbeSet, *, atol: float, what: str) -> float:
+    """The probe-logit self-test of section 19.4. Returns the largest difference it found.
+
+    A compatible spec says the tensors have the right shapes; only a forward on known rows says
+    the network computes the function that was saved. Compared on the legal actions only: an
+    illegal action's log-probability is the fill value's residue and carries nothing.
+    """
+    if probe.rows.shape[0] == 0:
+        raise PreflightError(f"{what}: the artifact's probe set is empty")
+    measured, mask = probe_log_probs(actor, codec, probe.rows)
+    if measured.shape != probe.log_probs.shape:
+        raise PreflightError(
+            f"{what}: the probe records log-probabilities of shape {probe.log_probs.shape} and "
+            f"this run's actor produces {measured.shape}"
+        )
+    difference = np.where(mask, np.abs(measured - probe.log_probs), 0.0)
+    worst = float(difference.max())
+    if not worst <= atol:
+        row = int(np.unravel_index(int(difference.argmax()), difference.shape)[0])
+        raise PreflightError(
+            f"{what}: the probe-logit self-test failed. On probe row {row} a legal action's "
+            f"log-probability differs by {worst:.3g} from the one recorded when the artifact "
+            f"was written, against a tolerance of {atol:g}. The weights loaded, so the network "
+            "they were loaded into does not compute the function that was saved: a different "
+            "architecture behind the same digest, a codec that decodes the rows differently, or "
+            "a different precision or device"
+        )
+    return worst
+
+
+def write_actor_artifact(
+    folder: str | Path,
+    state: Mapping[str, Tensor],
+    spec: SnapshotSpec,
+    *,
+    probe: ProbeSet | None = None,
+) -> str:
+    """Write an actor artifact into a folder that does not exist yet. Returns its digest.
+
+    The folder must be new: an artifact half overwritten by a second writer is a folder whose
+    digest matches nothing anybody wrote down.
+    """
+    import torch
+    from safetensors.torch import save
+
+    root = Path(folder)
+    if root.exists() and any(root.iterdir()):
+        raise FileExistsError(f"{root} already holds files; an artifact is written once")
+    root.mkdir(parents=True, exist_ok=True)
+    tensors = {
+        name: tensor.detach().to(dtype=torch.float32, device="cpu").contiguous()
+        for name, tensor in state.items()
+    }
+    (root / WEIGHTS_NAME).write_bytes(save(tensors))
+    meta = dict(spec.meta)
+    meta["dtype"] = "float32"
+    (root / SPEC_NAME).write_bytes(msgspec.json.encode(msgspec.structs.replace(spec, meta=meta)))
+    if probe is not None:
+        (root / PROBE_NAME).write_bytes(
+            save(
+                {
+                    "rows": torch.from_numpy(np.ascontiguousarray(probe.rows, dtype=np.uint8)),
+                    "log_probs": torch.from_numpy(
+                        np.ascontiguousarray(probe.log_probs, dtype=np.float32)
+                    ),
+                }
+            )
+        )
+    return artifact_digest(root)
+
+
+def read_actor_artifact(folder: str | Path) -> ActorArtifact:
+    """An actor artifact's spec, its tensors on the CPU, and its probe set if it has one."""
+    from safetensors.torch import load
+
+    root = Path(folder)
+    for name in (WEIGHTS_NAME, SPEC_NAME):
+        if not (root / name).is_file():
+            raise PreflightError(f"{root} is not an actor artifact: it has no {name}")
+    spec = msgspec.json.decode((root / SPEC_NAME).read_bytes(), type=SnapshotSpec)
+    state = load((root / WEIGHTS_NAME).read_bytes())
+    probe = None
+    if (root / PROBE_NAME).is_file():
+        blob = load((root / PROBE_NAME).read_bytes())
+        probe = ProbeSet(rows=blob["rows"].numpy(), log_probs=blob["log_probs"].numpy())
+    return ActorArtifact(folder=root, spec=spec, state=dict(state), probe=probe)
+
+
+def check_actor_artifact(artifact: ActorArtifact, current: SnapshotSpec, *, what: str) -> None:
+    """``check_compatible`` plus the action layout, which an init or a reference also needs.
+
+    A pool snapshot shares the run's action space by construction; an artifact brought in from
+    outside the run is exactly the thing that might not.
+    """
+    from royalelearn.extensions import check_compatible
+
+    check_compatible(artifact.spec, current)
+    if artifact.spec.action_digest and artifact.spec.action_digest != current.action_digest:
+        raise PreflightError(
+            f"{what}: the artifact was written for action space {artifact.spec.action_digest} and "
+            f"this run's is {current.action_digest}"
+        )
+
+
+def load_actor_state(actor: Any, artifact: ActorArtifact, *, what: str) -> None:
+    """``load_state_dict(strict=True)``, with a refusal that names the keys that did not match."""
+    reference = actor.state_dict()
+    missing = sorted(set(reference) - set(artifact.state))
+    unexpected = sorted(set(artifact.state) - set(reference))
+    if missing or unexpected:
+        raise PreflightError(
+            f"{what}: the artifact's tensors do not match this run's actor. Missing: "
+            f"{missing[:8]}; unexpected: {unexpected[:8]}"
+        )
+    shapes = [
+        name
+        for name, tensor in artifact.state.items()
+        if tuple(tensor.shape) != tuple(reference[name].shape)
+    ]
+    if shapes:
+        raise PreflightError(f"{what}: tensors of the wrong shape: {shapes[:8]}")
+    actor.load_state_dict(
+        {name: tensor.to(reference[name].device) for name, tensor in artifact.state.items()},
+        strict=True,
+    )
+
+
+#: How many decisions ``save_actor`` plays to make the probe rows, two seats each.
+SAVE_PROBE_STEPS = 32
+
+
+def save_actor(learner: Any, folder: str | Path, *, seed: int = 0) -> str:
+    """Write a ``royalelearn.Learner``'s trained actor as an actor artifact. Returns its digest.
+
+    The folder is what ``warm_start.init`` and a ``snapshot`` reference read, and the digest is
+    the ``sha256`` a config names it by. The probe rows are both seats' observations from a short
+    battle of the learner's own ``build_env``, with random legal moves; the log-probabilities the
+    actor gives them are recorded beside the weights, so a run that loads the folder can check it
+    computes the same policy. Call ``learner.learn`` first.
+    """
+    run = getattr(learner, "run", None)
+    if run is None:
+        raise PreflightError("there is no trained actor to save yet: call learner.learn() first")
+    codec = run.row_codec()
+    env = learner.build_env()
+    rng = np.random.default_rng(seed)
+    observations: list[Mapping[str, Any]] = []
+    try:
+        obs, _info = env.reset(seed=seed)
+        for _ in range(SAVE_PROBE_STEPS):
+            actions = {}
+            for agent, seat in obs.items():
+                observations.append(seat)
+                legal = np.flatnonzero(np.asarray(seat["action_mask"]))
+                actions[agent] = int(rng.choice(legal))
+            obs, _rewards, terminated, truncated, _info = env.step(actions)
+            if any(terminated.values()) or any(truncated.values()):
+                obs, _info = env.reset(seed=seed + 1)
+    finally:
+        close = getattr(env, "close", None)
+        if close is not None:
+            close()
+    rows = codec.pack(observations)
+    actor = run.model.actor
+    log_probs, _mask = probe_log_probs(actor, codec, rows)
+    write_actor_artifact(
+        folder,
+        actor.state_dict(),
+        run.snapshot_template,
+        probe=ProbeSet(rows=rows, log_probs=log_probs),
+    )
+    # So that ``Learner.load_policy(folder)`` plays it, as well as a warm start loading it.
+    from royalelearn.extensions import write_policy_record
+
+    write_policy_record(folder, run.spec, learner.config.net)
+    return artifact_digest(folder)

royaleimitate-0.2.6/royaleimitate/cli.py

@@ -0,0 +1,84 @@
+"""``royaleimitate``: the commands that make what the imitation sections read.
+
+- ``artifact-digest <folder>`` prints the digest a config names an artifact folder by.
+- ``fit-field-reference`` fits the play/wait model a ``field_mlp`` reference loads.
+
+A training run itself is still ``royalelearn train``: RoyaleLearn finds this package through the
+``warm_start`` and ``imitation`` sections of the run's config.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+__all__ = ["build_parser", "main"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="royaleimitate",
+        description="Make the artifacts RoyaleLearn's imitation sections read.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    digest = commands.add_parser(
+        "artifact-digest", help="print the digest a config names an artifact folder by"
+    )
+    digest.add_argument("folder", type=Path)
+    digest.set_defaults(handler=_artifact_digest)
+
+    fit = commands.add_parser(
+        "fit-field-reference",
+        help="fit the play/wait model a field_mlp reference loads",
+    )
+    fit.add_argument("--rows", type=Path, required=True, help="an .npz of field columns")
+    fit.add_argument(
+        "--fields", required=True, help="comma-separated observation vector field names"
+    )
+    fit.add_argument("--out", type=Path, required=True, help="a new folder for the artifact")
+    fit.add_argument("--hidden", default="32,32", help="hidden layer widths, comma-separated")
+    fit.add_argument("--epochs", type=int, default=20)
+    fit.add_argument("--seed", type=int, default=20260924)
+    fit.set_defaults(handler=_fit_field_reference)
+    return parser
+
+
+def _fit_field_reference(args: argparse.Namespace) -> int:
+    """Fit the play/wait model and write it as a field-model artifact."""
+    from .fit import FitConfig, fit_field_reference
+
+    fields = [name.strip() for name in args.fields.split(",") if name.strip()]
+    hidden = [int(width) for width in args.hidden.split(",") if width.strip()]
+    fit_field_reference(
+        args.rows,
+        fields,
+        args.out,
+        config=FitConfig(hidden=hidden, epochs=args.epochs, seed=args.seed),
+    )
+    return 0
+
+
+def _artifact_digest(args: argparse.Namespace) -> int:
+    """The folder digest: over every file in the folder, by relative path."""
+    from .artifacts import artifact_digest
+
+    print(artifact_digest(args.folder))
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    from royalelearn.extensions import PreflightError
+
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.handler(args))
+    except PreflightError as exc:
+        print(f"royaleimitate: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())