Route model: first attempts are their own shadow roll; experiment plan and automated bot cycle

- game.yaml: `givens` (first or later attempt) and `distinct` levels that are not pooled; the shadow roll
  depends on the attempt first. Form submissions show the shadow on 9% of first attempts and 0.3% of later ones.
- Reporting bias: a roll whose bias cannot be measured can borrow another roll's (`borrow: {shadow: meadow}`),
  so form submissions inform the shadow again. An assumption, stated in planner/policy.yaml.
- policy.json: targets.<colour>.firstAttempt (this attempt, eventually). Black: about 1.4% on a first attempt,
  0.07% on a later one.
- solver.js: advisor options `attempt`, `fix`, sampling "uniform"; assign() and armFor() for the plan.
- planner/experiments.yaml + build_experiments.py -> data/public/experiments.json (progress and status per
  experiment, rebuilt from the bot's runs).
- python -m collection cycle: import bot runs, refit, re-plan, deliver the kit; .gitea/workflows/bot-cycle.yml.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014jqCC2LZ4x1WHQ1V57nTsv
This commit is contained in:
ekcSchiano
2026-11-12 03:31:33 +00:00
co-authored by Claude Fable 5.2
parent ee07ee143e
commit ab3664f369
25 changed files with 1938 additions and 573 deletions
+114 -7
View File
@@ -1,11 +1,15 @@
"""Hand-offs without GitHub: the zip of atlas files for the bot, and the local equivalent of the daily workflow.
python -m collection export-bot-kit -> exports/atlas-for-bot-<date>-<policy id>.zip
policy.json, solver.js and graph.js (what the bot vendors into vendor/threshing-atlas/), plus a README and
policy.json, experiments.json, solver.js and graph.js (what the bot vendors into vendor/threshing-atlas/), plus a README and
checksums. Send it to the bot's maintainer; they unzip it into vendor/threshing-atlas/.
python -m collection refresh [--bot PATH ...]
Every source (and any bot folders or zips given), then the graph, the route model, the statistics and the
build: what .github/workflows/update-sources.yml does every day.
python -m collection cycle --bot PATH [--deliver DIR] [--community] [--force]
The loop with the bot, in one command and safe to run on a timer: import the bot's new runs, refit the
route model, rebuild the experiment plan, and put the bot's files where it reads them. Does nothing but
deliver when the bot has no new runs.
"""
import hashlib
import json
@@ -14,10 +18,12 @@ import subprocess
import sys
import zipfile
from datetime import datetime, timezone
from pathlib import Path
from .common import ROOT, path
KIT = {"policy.json": "data/public/policy.json", "solver.js": "core/solver.js", "graph.js": "core/graph.js"}
KIT = {"policy.json": "data/public/policy.json", "experiments.json": "data/public/experiments.json",
"solver.js": "core/solver.js", "graph.js": "core/graph.js"}
README = """Threshing Atlas files for the DragonKind bot
============================================
@@ -25,14 +31,16 @@ README = """Threshing Atlas files for the DragonKind bot
Policy id: {policy}
Made: {made}
Unzip these three files into the bot's vendor/threshing-atlas/ folder, replacing the old ones, and keep them
Unzip these four files into the bot's vendor/threshing-atlas/ folder, replacing the old ones, and keep them
together: solver.js reads the game from this policy.json.
policy.json the route model (the game, the counts behind every roll, the best routes per colour)
solver.js the advisor: advisor(), recommendOption(), solverHistory()
graph.js trajectoryVariables(): the bot's steps -> the community form's variables
policy.json the route model (the game, the counts behind every roll, the best routes per colour)
experiments.json the experiment plan: what each attempt of each account is for (read it with assign())
solver.js the advisor: advisor(), recommendOption(), solverHistory(), assign()
graph.js trajectoryVariables(): the bot's steps -> the community form's variables
How the bot uses them: docs/BOT_INTEGRATION.md in the atlas repo. Log the policy id above as policyId on each run.
How the bot uses them: docs/BOT_INTEGRATION.md in the atlas repo. Log the policy id above as policyId on each run,
and the plan's id as planId.
Checksums (sha256):
{sums}
@@ -76,7 +84,106 @@ def refresh(update_main, bots=()):
else:
print("\n(node is not installed: data/public/graph.json is not rebuilt; everything else is)")
_step("route model (about 2 minutes)", [py, "planner/build_policy.py"])
_step("experiment plan", [py, "planner/build_experiments.py"])
_step("statistics", [py, "analysis/stats/site_stats.py"])
_step("runs, generated files and metadata", [py, "-m", "collection", "build"])
print(f"\nDone. What changed: exports/last-report.md. Send the bot its files with: {py} -m collection export-bot-kit")
return rc
# ---------------------------------------------------------------- the automated cycle with the bot
def _fingerprint():
"""What the route model and the plan are built from: the coded runs and the bot's anonymised files."""
h = hashlib.sha256()
for p in [path("data/public/runs_clean.csv"), *sorted(path("data/bot").glob("*.json*")),
path("planner/policy.yaml"), path("planner/experiments.yaml"), path("core/spec/game.yaml")]:
if p.exists():
h.update(p.name.encode())
h.update(p.read_bytes())
return h.hexdigest()
def _headline():
"""The numbers a person checks after a cycle: {label: value}."""
out = {}
try:
pol = json.loads(path("data/public/policy.json").read_text(encoding="utf-8"))
out["policy id"] = pol["id"]
t = pol["samples"]["all"]["targets"]
pct = lambda d: f"{100 * d['mean']:.2f}% ({100 * d['lo']:.2f}-{100 * d['hi']:.2f})" # noqa: E731
out["Black, first attempt"] = pct(t["Black"]["firstAttempt"]["thisAttempt"]["pX"])
out["Black, later attempt"] = pct(t["Black"]["thisAttempt"]["pX"])
out["Blue, per attempt"] = pct(t["Blue"]["thisAttempt"]["pX"])
out["runs the model learns from"] = pol["source"]["runs"]
out["bot runs"] = pol["source"]["by_source"].get("bot", 0)
except (OSError, KeyError, ValueError):
pass
try:
plan = json.loads(path("data/public/experiments.json").read_text(encoding="utf-8"))
out["plan id"] = plan["id"]
for e in plan["experiments"]:
p = e["progress"]
out[f"experiment {e['id']}"] = f"{e['status']}: {p['observed']} observed, {p['rare']} rare" + (f" [{e['note']}]" if e.get("note") else "")
except (OSError, KeyError, ValueError):
pass
return out
def deliver(dest):
"""Copy the bot's files (KIT) into a folder, each one whole (written beside it, then renamed), with a manifest
the bot can check before an attempt: atlas-kit.json = {policyId, planId, made, sha256: {file: sum}}."""
dest = Path(dest).expanduser()
dest = dest if dest.is_absolute() else path(str(dest))
dest.mkdir(parents=True, exist_ok=True)
sums = {}
for name, src in KIT.items():
data = path(src).read_bytes()
sums[name] = hashlib.sha256(data).hexdigest()
tmp = dest / (name + ".incoming")
tmp.write_bytes(data)
tmp.replace(dest / name)
head = _headline()
manifest = {"policyId": head.get("policy id"), "planId": head.get("plan id"),
"made": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "sha256": sums}
tmp = dest / "atlas-kit.json.incoming"
tmp.write_text(json.dumps(manifest, indent=1) + "\n", encoding="utf-8")
tmp.replace(dest / "atlas-kit.json") # last: a kit whose manifest matches its files is complete
return dest
def cycle(update_main, bots, deliver_to=None, community=False, force=False):
"""Import the bot's runs -> refit -> re-plan -> deliver. Returns 0 on success. Writes exports/last-cycle.md."""
py = sys.executable
path("exports").mkdir(exist_ok=True)
before, was = _fingerprint(), _headline()
rc = 0
if community:
rc |= update_main(["update", "--report", str(path("exports/last-report.md"))])
for i, b in enumerate(bots):
rc |= update_main(["update", "--source", "bot", "--file", f"bot={b}", "--report", str(path(f"exports/last-report-bot{i + 1}.md"))])
built = all(path(src).exists() for src in KIT.values())
changed = force or not built or _fingerprint() != before
if changed:
if shutil.which("node"):
_step("route graph", ["node", "analysis/network/build-graph.js"])
_step("route model (a few minutes)", [py, "planner/build_policy.py"])
_step("experiment plan", [py, "planner/build_experiments.py"])
try:
import scipy # noqa: F401
_step("statistics", [py, "analysis/stats/site_stats.py"])
except ImportError:
print("\n(scipy is not installed: data/public/stats.json is not rebuilt; the bot does not use it)")
_step("runs, generated files and metadata", [py, "-m", "collection", "build"])
else:
print("\nNo new runs: the route model and the plan are unchanged.")
now = _headline()
lines = [f"# Bot cycle, {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')} UTC", "",
"The model and the plan were rebuilt." if changed else "No new runs: nothing was rebuilt.", "",
"| | Before | Now |", "|---|---|---|"]
lines += [f"| {k} | {was.get(k, '-')} | {v} |" for k, v in now.items()]
if deliver_to:
lines += ["", f"Delivered to `{deliver(deliver_to)}`."]
path("exports/last-cycle.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
print("\n" + "\n".join(lines))
return rc
+14 -2
View File
@@ -8,7 +8,10 @@
Locally, what the daily workflow does: update every source (plus bot folders or zips someone sent), then
rebuild the graph, the route model, the statistics and the build.
python -m collection export-bot-kit
exports/atlas-for-bot-<date>-<policy id>.zip: policy.json, solver.js and graph.js for the bot.
exports/atlas-for-bot-<date>-<policy id>.zip: policy.json, experiments.json, solver.js and graph.js.
python -m collection cycle --bot PATH [--deliver DIR] [--community] [--force]
The automated loop with the bot: import its new runs, refit the route model, rebuild the experiment
plan (planner/experiments.yaml), and copy the bot's files into DIR. Safe to run on a timer.
python -m collection build [--check]
Code every public source file into data/public/runs_clean.csv (validated against data/dictionary.yaml),
and write the files generated from the specs: the "Report a run" issue form, the bot crosswalk in
@@ -104,12 +107,21 @@ def main(argv=None):
b.add_argument("--check", action="store_true")
fg = sub.add_parser("forge", help="pull requests, issues and labels on the repository's host (forge.yaml)")
fg.add_argument("args", nargs=argparse.REMAINDER)
k = sub.add_parser("export-bot-kit", help="zip policy.json, solver.js and graph.js for the bot")
k = sub.add_parser("export-bot-kit", help="zip policy.json, experiments.json, solver.js and graph.js for the bot")
k.add_argument("--out", default="exports")
r = sub.add_parser("refresh", help="update every source, then rebuild everything (the daily workflow, locally)")
r.add_argument("--bot", action="append", default=[], help="a bot folder or a .zip of its data (repeatable)")
c = sub.add_parser("cycle", help="the loop with the bot: import its runs, refit, re-plan, deliver (safe on a timer)")
c.add_argument("--bot", action="append", default=[], help="the bot's folder, or a .zip of its data (repeatable); default: $DRAGONKIND_BOT_DIR")
c.add_argument("--deliver", help="a folder to put the bot's files in (its vendor/threshing-atlas/)")
c.add_argument("--community", action="store_true", help="also check the community sources first")
c.add_argument("--force", action="store_true", help="rebuild even when there are no new runs")
a = ap.parse_args(argv)
if a.cmd == "cycle":
from .etl.handoff import cycle
bots = a.bot or ([os.environ["DRAGONKIND_BOT_DIR"]] if os.environ.get("DRAGONKIND_BOT_DIR") else [])
return cycle(main, bots, a.deliver, a.community, a.force)
if a.cmd == "forge":
from .etl import forge
return forge.main(a.args)